You are compiling the definitive CLAUDE.md design system reference file.
This file will live in the project root and serve as the single source of
truth for any AI assistant (or human developer) working on this codebase.
## Inputs
- **Token architecture:** [Phase 2 output]
- **Component documentation:** [Phase 3 output]
- **Project metadata:**
- Project name:
- Tech stack: [Next.js 14+ / React 18+ / Tailwind 3.x / etc.]
- Node version:
- Package manager: [npm / pnpm / yarn]
## CLAUDE.md Structure
Compile the final file with these sections IN THIS ORDER:
### 1. Project Identity
- Project name, description, positioning
- Tech stack summary (one table)
- Directory structure overview (src/ layout)
### 2. Quick Reference Card
A condensed cheat sheet — the most frequently needed info at a glance:
- Primary colors with hex values (max 6)
- Font stack
- Spacing scale (visual representation: 4, 8, 12, 16, 24, 32, 48, 64)
- Breakpoints
- Border radius values
- Shadow values
- Z-index map
### 3. Design Tokens — Full Reference
Organized by tier (Primitive → Semantic → Component).
Each token entry: name, value, CSS variable, Tailwind class equivalent.
Use tables for scannability.
### 4. Typography System
- Type scale table (name, size, weight, line-height, letter-spacing, usage)
- Responsive rules
- Font loading strategy
### 5. Color System
- Full palette with swatches description (name, hex, usage context)
- Semantic color mapping table
- Dark mode mapping (if applicable)
- Contrast ratio compliance notes
### 6. Layout System
- Grid specification
- Container widths
- Spacing system with visual scale
- Breakpoint behavior
### 7. Component Library
[Insert Phase 3 output for each component]
### 8. Motion & Animation
- Named presets table (name, duration, easing, usage)
- Rules: when to animate, when not to
- Performance constraints
### 9. Coding Conventions
- File naming patterns
- Import order
- Component file structure template
- CSS class ordering convention (if Tailwind)
- State management patterns used
### 10. Rules & Constraints
Hard rules that must never be broken:
- "Never use inline hex colors — always reference tokens"
- "All interactive elements must have visible focus states"
- "Minimum touch target: 44x44px"
- "All images must have alt text"
- "No z-index values outside the defined scale"
- [Add project-specific rules]
## Formatting Requirements
- Use markdown tables for all token/value mappings
- Use code blocks for all code examples
- Keep each section self-contained (readable without scrolling to other sections)
- Include a table of contents at the top with anchor links
- Maximum line length: 100 characters for readability
- Prefer explicit values over "see above" references
## Critical Rule
This file must be AUTHORITATIVE. If there's ambiguity between the
CLAUDE.md and the actual code, the CLAUDE.md should be updated to
match reality — never the other way around. This documents what IS,
not what SHOULD BE (that's a separate roadmap).
