CLAUDE.md Assembly

Improved Prompt:

You are responsible for creating the definitive CLAUDE.md design system reference document for the [Project Name] AI assistant codebase. This markdown file will reside in the project root directory and serve as the single, authoritative source of truth for all AI assistant developers and human contributors working on the codebase.

Input Sources

• Architectural Tokens: The Phase 2 output containing the finalized token architecture for the project.
• Component Documentation: The Phase 3 output providing detailed documentation for each UI component in the system.
• Project Metadata:
  • Project Name: [Project Name]
  • Tech Stack: [Next.js 14+ / React 18+ / Tailwind 3.x / etc.]
  • Node Version: [Node Version]
  • Package Manager: [npm / pnpm / yarn]

CLAUDE.md Document Structure

Compile the final CLAUDE.md file with the following sections in this precise order. Each section should be self-contained, readable independently, and link to relevant sections using automatic markdown anchor links.

1. Project Identity (100-200 words)

• Project Name, Description, and Positioning: A clear, concise description of the project's purpose, audience, and unique value proposition.
• Tech Stack Summary: A table listing the primary technologies used in the project, their versions, and their roles in the architecture.
• Directory Structure Overview: A visual representation or brief description of the project's folder structure, highlighting the src directory and major subdirectories.

2. Quick Reference Card

A two-column table (50% width each) containing the most frequently needed information at a glance:

Category	Value
Primary Colors (Hex)	- Brand: #123456 - Accent: #7890ab - Text: #cdef01 - Neutral: #90a1b2
Font Stack	- Primary: Inter, system-serif - Secondary: Source Sans Pro, system-serif
Spacing Scale (px)	4, 8, 12, 16, 24, 32, 48, 64
Breakpoints (px)	- Small: 640 - Medium: 768 - Large: 1024 - X-Large: 1280
Border Radius	- Small: 2px - Medium: 4px - Large: 8px
Shadow Values	- Small: 0 1px 2px rgba(0,0,0,.1) - Medium: 0 2px 4px rgba(0,0,0,.2)
Z-Index Map	- Lowest: 10 - Below: 20 - Base: 30 - Above: 40 - Highest: 50

3. Design Tokens — Full Reference

Organized by token tier (Primitive → Semantic → Component), each entry in a markdown table:

Tier	Name	Value	CSS Variable	Tailwind Equivalent
Primitive	$color-brand	#123456	--color-brand	text-brand-500
Semantic	$spacing-xxs	4px	--spacing-xxs	--
Component	$btn-border-radius	8px	--btn-border-radius	border-rounded-8xl

4. Typography System

• Type Scale Table: A table listing font sizes, weights, line heights, letter spacing, and usage contexts for each font size variation.
• Responsive Rules: A description or pseudocode specifying how the font size scales across different viewport sizes.
• Font Loading Strategy: An explanation of the font loading technique (e.g., async, preload, etc.) and any optimization strategies.

5. Color System

• Full Palette: A table listing all color names, hex values, color swatches, and usage contexts.
• Semantic Color Mapping: A table mapping semantic colors (e.g., success, warning) to their corresponding hex values.
• Dark Mode Mapping: If applicable, a table mapping light mode colors to their dark mode equivalents.
• Contrast Ratio Compliance Notes: Detailed notes on contrast ratio calculations and any exceptions or adjustments made to meet accessibility guidelines.

6. Layout System

• Grid Specification: A description of the grid system used (e.g., Flexbox, CSS Grid, etc.) and any specific configuration details.
• Container Widths: A table or list of container widths for different screen sizes.
• Spacing System: A visual representation or table of the spacing system and its usage.
• Breakpoint Behavior: A description of how the layout adjusts at different breakpoints.

7. Component Library

Insert the Phase 3 output for each component, formatted as follows:

Button

• Props: variant, size, color, disabled, etc.
• Usage:
  • Primary: [use for main actions]
  • Secondary: [for less important actions]
• CSS Class: btn (with variants and sizes appended, e.g., btn-primary-lg)
• Code Example:
  javascriptCopy

  <Button variant="primary" size="lg" onClick={handleClick}>
    Save
  </Button>

8. Motion & Animation

• Named Presets Table: A table listing animation names, durations, easing functions, and usage contexts.
• Rules: Detailed guidelines on when to animate, when not to, and any performance constraints.
• Preset Examples: Code examples or visual representations of the defined animations.

9. Coding Conventions

• File Naming Patterns: The exact naming conventions for components, modules, and other files.
• Import Order: The preferred order for importing dependencies.
• Component File Structure: A template for the structure of each component file.
• CSS Class Ordering: If using Tailwind, the preferred order for applying utility classes.
• State Management Patterns: An explanation of the state management techniques used (e.g., React Context, Redux, etc.).

10. Rules & Constraints

Hard Rules (Never to be Broken): A numbered list of rules that must be followed without exception, such as:

1. Color Consistency: "Never use inline hex colors — always reference tokens."
2. Accessibility: "All interactive elements must have visible focus states."
3. Touch Target: "Minimum touch target size: 44x44px."
4. Image Accessibility: "All images must have alt text."

11. Contributors Guidelines (Optional)

Brief instructions for new contributors, including how to make pull requests, the code review process, and any other relevant guidelines.

Formatting and Style Guide

• Tables: Use markdown tables for all token/value mappings, component props, and other data-driven content.
• Code Blocks: Enclose all code examples in markdown code blocks with proper syntax highlighting.
• Line Length: Keep each line of text and each line of code under 100 characters for optimal readability.
• Consistency: Maintain a consistent style throughout the document, following the project's code style guide.

Primary Rule: Authority of the Document

This document must be the absolute, authoritative reference for the design system. If any ambiguity arises between CLAUDE.md and the actual code, CLAUDE.md should always be updated to match the reality of the codebase. This document describes what IS, not what SHOULD BE (which is documented in a separate roadmap or design documentation).

By following this improved prompt, you will create a comprehensive, readable, and authoritative CLAUDE.md document that serves as the single source of truth for the project. The clear structure, detailed instructions, and emphasis on authority ensure that the output will be a valuable resource for the development team.