Body text
Secondary ``` #### Components - Always Include: - Loading states (skeletons) - Error states (with retry option) - Empty states (with CTA) ### Step 4: Accessibility **Required:** - All interactive elements keyboard accessible - Focus states visible (`ring` class) - Labels on all form inputs - Sufficient color contrast - `prefers-reduced-motion` honored ```tsx ``` ### Step 5: File Structure ``` app/ ├── globals.css # Generated theme CSS ├── layout.tsx # Root layout with fonts ├── page.tsx # Home page ├── components/ │ └── ui/ # shadcn components ├── lib/ │ ├── utils.ts # cn() helper │ └── actions.ts # Server actions └── tailwind.config.ts # Generated config ``` ### Agent Decision Tree ``` 1. IDENTIFY APP TYPE "todo app" → productivity "landing page" → marketing "dashboard" → analytics 2. SELECT THEME productivity → focus (yellow-gray 50°) marketing → depends on industry analytics → trust (blue-gray 210°) 3. DETECT USER INTENT (from their words) "professional" → formal layout "playful" → rounded corners, friendly copy "minimal" → more whitespace, fewer elements 4. GENERATE WITH PRINCIPLES - Chromatic colors (8-20% saturation) - Consistent spacing (4px grid) - Accessible (keyboard, contrast, motion) - Honest UX (no dark patterns) 5. ALWAYS INCLUDE - Loading states - Error states - Empty states - Responsive design ``` --- ## Part 9: UX Principles (From Ancient Wisdom) ### 1. Sovereignty Over Dependency Design should empower users, not create dependency. - Clear escape routes (always show how to undo, go back, exit) - Transparent about what's happening (loading states, progress) - User controls their data (export, delete options) ### 2. Coherence Over Chaos Every element should feel like it belongs. - Consistent spacing (use 4px grid: 4, 8, 12, 16, 24, 32, 48) - Consistent typography scale (14px base, 1.25 ratio) - Consistent interaction patterns ### 3. Presence Over Distraction Help users focus on what matters. - Minimal notifications - No attention-hijacking patterns - Clear visual hierarchy - Generous whitespace ### 4. Flow Over Friction Design for natural movement. - Keyboard works everywhere - Tab order makes sense - Touch targets 44px minimum - Smooth transitions (200-400ms) ### 5. Truth Over Deception No dark patterns. - Clear pricing - Honest button labels (not "Maybe later" for "No") - Obvious unsubscribe options - No hidden fees or gotchas ### Interaction Guidelines **Keyboard Navigation:** - Every interactive element focusable - Focus visible (ring, outline) - Tab order follows visual order - Escape closes modals/dropdowns **Motion & Animation:** - Honor `prefers-reduced-motion` - Use GPU-accelerated properties only: `transform`, `opacity` - Duration: 150-400ms - Easing: `cubic-bezier(0.4, 0, 0.2, 1)` for most ```css @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } } ``` **Loading States:** - Never leave users hanging - Skeleton screens for content - Spinners for actions - Progress bars for known duration **Error States:** - Clear error messages (not "Error 500") - Suggest fixes when possible - Keep user's input after error - Position errors near the problem --- ## Part 10: Quick Reference ### Intention → Palette Mapping | Intention | Palette | Force | Hue | Best For | |-----------|---------|-------|-----|----------| | `urgency` | redGray | Thermal | 10° | Alerts, errors, critical | | `energy` | orangeGray | Thermal | 30° | CTAs, activation, enthusiasm | | `warmth` | orangeGray | Thermal | 30° | Hospitality, welcome, comfort | | `clarity` | yellowGray | Luminous | 50° | Learning, documentation, focus | | `optimism` | yellowGray | Luminous | 50° | Success states, achievements | | `growth` | greenGray | Neutral | 120° | Progress, health, nature | | `harmony` | tealGray | Neutral | 170° | Wellness, balance, equilibrium | | `trust` | blueGray | Electrical | 210° | Professional, reliable, calm | | `calm` | indigoGray | Electrical | 240° | Meditation, depth, intuition | | `spirit` | violetGray | Electrical | 270° | Creativity, luxury, transcendence | | `affection` | roseGray | Special | 340° | Care, love, nurturing | | `neutral` | achromatic | — | 0° | Minimal, universal, professional | ### Saturation Guidelines | Element Type | Saturation Range | |--------------|------------------| | Backgrounds | 8-12% | | Cards/Surfaces | 10-14% | | Text (on dark) | 0% (pure white/gray) | | Borders | 12-16% | | Interactive elements | 14-18% | | Focus states | 16-20% | ### Semantic Classes | Use | Class | |-----|-------| | Page background | `bg-background` | | Primary text | `text-foreground` | | Secondary text | `text-muted-foreground` | | Cards | `bg-card border-border` | | Inputs | `bg-input border-border` | | Primary buttons | `bg-primary text-primary-foreground` | | Borders | `border-border` | ### Standard Sizes | Element | Size | |---------|------| | Touch targets | min 44px | | Button padding | `px-4 py-2` | | Card padding | `p-6` | | Section gap | `space-y-8` | | Border radius | `rounded-lg` (8px) | ### Spacing Scale (px) `4 | 8 | 12 | 16 | 24 | 32 | 48 | 64 | 96` ### Typography Scale `12 | 14 | 16 | 18 | 20 | 24 | 30 | 36 | 48` ### Border Radius - Small (buttons, inputs): `6px` - Medium (cards): `8px` - Large (modals): `12px` - Nested: child radius < parent radius ### Shadows (Layered) ```css --shadow-sm: 0 1px 2px hsl(var(--foreground) / 0.05); --shadow-md: 0 4px 6px hsl(var(--foreground) / 0.07), 0 2px 4px hsl(var(--foreground) / 0.05); --shadow-lg: 0 10px 15px hsl(var(--foreground) / 0.1), 0 4px 6px hsl(var(--foreground) / 0.05); ``` ### Don'ts ❌ Don't use arbitrary colors (`text-blue-500`) ❌ Don't skip loading states ❌ Don't use placeholders instead of labels ❌ Don't hide navigation ❌ Don't use manipulative button labels ❌ Don't exceed 20% saturation on any color ❌ Never use saturation above 25% for any surface ❌ Never use pure black (`hsl(0, 0%, 0%)`) - use 950 shades instead ❌ Never use pure white (`hsl(0, 0%, 100%)`) - use 50 shades instead ❌ Never use brownish-green combinations (jealousy/deceit) ❌ Never use gray-green without clear separation (depression) ### Tech Stack Defaults ``` Next.js 15 (App Router) ├── TypeScript ├── Tailwind CSS 4 ├── shadcn/ui components ├── Geist font (or Inter) └── Server Actions (not API routes) ``` --- ## TypeScript Type Definitions ```typescript export type ChromaticHue = | "redGray" | "orangeGray" | "yellowGray" | "greenGray" | "tealGray" | "blueGray" | "indigoGray" | "violetGray" | "roseGray" | "achromatic" export type ChromaticShade = | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 export type Force = "thermal" | "luminous" | "neutral" | "electrical" export type DesignIntention = | "urgency" | "energy" | "warmth" // THERMAL | "clarity" | "optimism" // LUMINOUS | "growth" | "harmony" // NEUTRAL | "trust" | "calm" | "spirit" // ELECTRICAL | "affection" // SPECIAL | "neutral" // ACHROMATIC export type FormNature = | "directed" // pointed, projectile | "radiating" // star-like, outward | "protective" // enclosing, shell | "intellectual" // crystalline, sharp | "aspirational" // upward, spire | "emotional" // cloud-like, soft export type ClarityLevel = | "definite" | "clear" | "balanced" | "soft" | "ethereal" export interface ThoughtFormProperties { quality: DesignIntention // → determines color nature: FormNature // → determines shape definiteness: ClarityLevel // → determines outline } ``` --- *"Quality of thought determines colour. Nature of thought determines form. Definiteness of thought determines clearness of outline."* — Besant & Leadbeater, *Thought-Forms* (1901) *"Good design is invisible. Great design is inevitable."*