CLAUDE.md for Design Systems

What This Is

A ready-to-customize CLAUDE.md file that makes Claude Code understand your design system from the first prompt. Without it, Claude guesses token names, invents components, and ignores your conventions.

This template encodes:

• Token naming conventions with valid/invalid examples
• Component inventory summary
• File structure and key paths
• Hard rules (what Claude must never do)
• A failure log that improves over time

How to Use

1. Download the .md file
2. Place it in the root of your design system project
3. Replace the placeholder values with your actual conventions
4. Run Claude Code in that directory. It loads automatically.
5. As Claude makes mistakes, add them to the ## Mistakes section

What’s Inside

• Architecture section with token and component locations
• Conventions with naming patterns and examples
• Key file references using @import syntax for lazy loading
• Don’t rules to prevent common AI mistakes
• Mistakes log that self-improves over sessions

Who This Is For

• Designers setting up Claude Code for design system work
• Teams standardizing how AI interacts with their component library
• Anyone tired of Claude generating color.backgroundPrimary instead of color.bg.primary

The Template

# Project: [Your Design System Name]

## Architecture
- Tokens: `tokens/` (Style Dictionary format)
- Components: `src/components/` (React + CSS custom properties)
- [X] components, [X] semantic tokens, [X] themes

## Conventions
- Token naming: `{category}.{property}.{intent}.{modifier?}`
- Valid: color.bg.primary, color.fg.danger, space.gap.md
- Invalid: red-500, bg-primary, colorBgPrimary
- kebab-case everywhere. Never rename existing variables.
- Components use CSS custom properties, not hardcoded values.

## Key files
- @.design-system/token-schema.json
- @.design-system/naming-conventions.md

## Don't
- Don't use raw hex colors. Always reference a token.
- Don't create new tokens without checking for existing ones first.
- Don't rename existing tokens (breaking change).
- Don't generate camelCase token names.
- Don't hardcode spacing values. Use the spacing scale.

## Mistakes
<!-- Add AI mistakes here as they happen. Claude reads this on every request. -->