FloatPrompt

This is a good use case for creating a @floatprompt to store your app details for context etc You can also continually update the floatprompt file as well as you find new states and data structure.

Below is an example of a floatprompt I'm using to develop the new Shift Nudge site. This was created after a back and forth conversation with Claude about my goals, intentions, best practices, etc. then saying... "ok, create a floatprompt capturing all of this information we've discussed" I didn't write any of this JSON or any of the floatprompt document below. It's all written by AI through conversational emergence. It simply follows the floatprompt format I gave it as instructions for what to provide back to me. Now when I work in Cursor (or anywhere else with AI), I'll have the model follow these principles instead of making random decisions and generating random code. These .txt files are portable across any AI model and can evolve with your project. The beauty of FloatPrompt, is it's a simple little format and a self-referencing file so you can use it to generate literally anything. I've generated hundreds of these and am now using them for all sorts of things. --- { "meta": { "title": "Shift Nudge Development Guide", "id": "shiftnudge-dev-guide-v1", "format": "floatprompt", "file": "txt", "process": "AI-generated from human conversation" }, "human": { "author": "@mds", "intent": "Establish development ethos and best practices for scalable, maintainable codebase", "context": "Building shiftnudge.com with React, Framer Motion, Headless UI, Tailwind using Cursor AI", "style": "Systematic, principle-driven, anti-fragile architecture" }, "ai": { "model": "Claude Sonnet 4" }, "requirements": { "core_philosophy": { "system_first_custom_second": "Always check if the design system can handle it before creating custom solutions", "composition_over_configuration": "Build complex components by combining simple ones rather than adding more props/config", "progressive_enhancement": "Start with the simplest solution that works, then add complexity only when needed", "deletion_principle": "The best code is code you don't have to write. Can this be solved by removing complexity instead of adding it?" }, "anti_patterns": { "avoid_important_declarations": "!important usually indicates architectural issues", "avoid_hardcoded_values": "No magic numbers or colors scattered throughout components", "avoid_oneoff_solutions": "If you need it twice, systematize it", "avoid_inline_styles": "Use design tokens and component variants instead" }, "decision_frameworks": { "three_question_rule": "Before writing custom code: 1) Does our system handle this? 2) Should our system handle this? 3) What's the most reusable approach?", "future_self_test": "Will someone (including AI) understand this code in 6 months without context?", "consistency_check": "Is this consistent with our existing patterns?" }, "component_architecture": { "atomic_design": "Use atoms, molecules, organisms hierarchy", "compound_components": "For complex UI patterns with multiple interdependent parts", "headless_patterns": "Separate logic from presentation for maximum reusability", "variant_system": "Use class-variance-authority for type-safe component variations" }, "file_organization": { "path_as_documentation": "File structure should tell the story of your architecture", "locality_of_behavior": "Related things live near each other (components, styles, tests, stories)", "import_hierarchy": "Clear rules about what can import what (atoms don't import molecules, etc.)" }, "performance_accessibility": { "accessible_by_default": "Every component should handle basic a11y without extra configuration", "performance_budget": "Bundle size and runtime performance considerations baked into component decisions", "mobile_first_always": "Responsive design isn't an afterthought" }, "state_data_management": { "state_shape_consistency": "Predictable data structures across components", "single_source_truth": "Avoid duplicating state or configuration", "immutable_updates": "Prevent side effects and unexpected mutations" }, "documentation_tooling": { "self_documenting_code": "Good TypeScript interfaces serve as documentation", "example_driven_development": "Every component should have clear usage examples", "fail_fast_principle": "TypeScript errors, linting, and validation catch issues early" }, "testing_philosophy": { "test_behavior_not_implementation": "Focus on user outcomes, not internal mechanics", "visual_regression_protection": "Systematic approach to preventing UI regressions" }, "ai_development_guidelines": { "context_window_management": "Structure code so AI can understand the full system within token limits", "incremental_complexity": "Build features step-by-step so AI can follow the logic progression", "template_over_generation": "Prefer extending existing patterns rather than generating from scratch", "validation_first": "Always validate generated code against existing patterns before implementation", "explain_then_code": "AI should explain the approach before implementing", "small_commits": "Generate code in small, testable chunks", "human_checkpoint": "AI should pause and ask for human review at architectural decision points", "system_boundary_respect": "AI shouldn't modify core system components without explicit permission", "documentation_updates": "AI should update relevant docs when adding new patterns" }, "common_ai_pitfalls": { "avoid_over_engineering": "AI tendency to add unnecessary complexity - start simple", "avoid_pattern_mixing": "Don't combine different architectural approaches inconsistently", "remember_edge_cases": "Always consider error states, loading states, empty states", "accessibility_first": "Don't forget ARIA labels, keyboard navigation, screen reader support", "performance_awareness": "Consider bundle size, re-renders, memory leaks in every implementation" } } } # ShiftNudge Development Requirements Document (DRD) A comprehensive guide for maintaining scalable, systematic, and maintainable code architecture when building shiftnudge.com. This document serves as the source of truth for development decisions and should be referenced by both human developers and AI assistants. ## Quick Start Before implementing any feature: 1. Check if our design system already handles this use case 2. Ask the three questions: Does our system handle this? Should it? What's the most reusable approach? 3. Choose composition over configuration 4. Start simple, add complexity only when needed ## Goals - **Systematic Architecture**: Build solutions that scale and compose elegantly - **Future-Proof Codebase**: Code that remains maintainable as the project grows - **AI-Human Collaboration**: Clear principles that both humans and AI can follow consistently - **Brand Quality**: Unique ShiftNudge brand expression through systematic design implementation - **Developer Experience**: Architecture that makes building features fast and enjoyable ## Context **When to use this guide:** - Before implementing any new component or feature - When reviewing code (human or AI-generated) - When refactoring existing code - When onboarding new team members or AI assistants - When making architectural decisions **Technology Stack:** - React with TypeScript - Tailwind CSS for styling - Framer Motion for animations - Headless UI for accessible primitives - class-variance-authority for component variants - Cursor for AI-assisted development ## Output **Following this guide results in:** - Predictable, reusable component architecture - Consistent design system implementation - Reduced technical debt and maintenance burden - Faster feature development through composition - Better collaboration between humans and AI - Scalable codebase that grows elegantly **Code Quality Indicators:** - No `!important` declarations needed - No hardcoded values (colors, spacing, etc.) - High component reusability - Clear file organization and naming - Self-documenting TypeScript interfaces - Consistent patterns across the codebase ## AI Development Guidelines **Context Window Management:** - Structure code so AI can understand the full system within token limits - Break large components into smaller, comprehensible pieces - Use clear, descriptive naming that tells the story **Development Patterns:** - **Template Over Generation**: Prefer extending existing patterns rather than generating from scratch - **Validation First**: Always validate generated code against existing patterns before implementation - **Explain Then Code**: AI should explain the approach before implementing - **Small Commits**: Generate code in small, testable chunks - **Incremental Complexity**: Build features step-by-step so AI can follow logic progression **Collaboration Protocols:** - **Human Checkpoint**: AI should pause and ask for human review at architectural decision points - **System Boundary Respect**: AI shouldn't modify core system components without explicit permission - **Documentation Updates**: AI should update relevant docs when adding new patterns **Common AI Pitfalls to Avoid:** - **Over-engineering**: AI tendency to add unnecessary complexity - start simple - **Pattern Mixing**: Don't combine different architectural approaches inconsistently - **Missing Edge Cases**: Always consider error states, loading states, empty states - **Accessibility Oversights**: Don't forget ARIA labels, keyboard navigation, screen reader support - **Performance Blind Spots**: Consider bundle size, re-renders, memory leaks in every implementation ## Warnings **Common Pitfalls:** - Don't over-engineer early - start simple and systematize when patterns emerge - Don't create abstractions for single use cases - Don't bypass the design system without good reason - Don't optimize prematurely - measure first - Don't forget accessibility in pursuit of aesthetics - Don't ignore performance implications of animations and effects **When to Break the Rules:** - Prototyping and experimentation phases - One-off marketing pages with unique requirements - Performance-critical sections requiring optimization - Third-party integrations with specific constraints Created by @mds and Claude Sonnet 4

hello world floatprompt.com