Design System CLAUDE.md + Rules Kit

What This Is

Everything you need to make Claude Code understand your design system. One download, customize, and you’re set.

What’s Inside

claude-rules-kit/
├── CLAUDE.md                              <- Root context (lean, ~100 lines)
├── .claude/
│   └── rules/
│       ├── token-naming.md                <- Only loads for token files
│       └── component-conventions.md       <- Only loads for component files
├── .design-system/
│   ├── CLAUDE.md                          <- Design system context
│   ├── token-schema.json                  <- What makes a valid token
│   ├── knowledge-graph.json               <- Component relationships
│   ├── component-intent.json              <- When to use what
│   └── naming-conventions.md              <- The naming rules
├── tokens/
│   └── CLAUDE.md                          <- Token-folder context
└── src/
    └── components/
        └── CLAUDE.md                      <- Component-folder context

Why a Kit

Setting up Claude Code for design system work requires 8+ files in the right places. Most people create a CLAUDE.md and stop there. This kit gives you the full architecture.

Without the kit: Claude guesses token names, picks wrong components, and ignores your conventions. With the kit: Claude follows your naming rules, picks components by intent, and improves with every session.

How to Use

1. Download and unzip into your project root
2. Replace all [placeholder] values with your actual system details
3. Run Claude Code. Everything loads automatically based on what you’re working on.
4. As Claude makes mistakes, add them to the ## Mistakes section in root CLAUDE.md

File: CLAUDE.md (root)

This loads on every API request. Keep it lean.

# Project: [Your Design System Name]

## Architecture
- Tokens: `tokens/` ([format: Style Dictionary / Tokens Studio / CSS])
- Components: `src/components/` ([framework: React / Vue / Svelte] + 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
<!-- Claude reads this every request. Add mistakes as they happen. -->

File: .claude/rules/token-naming.md

Only loads when Claude works with files in tokens/ or .design-system/.

---
paths:
  - "tokens/**"
  - ".design-system/**"
---

# Token Naming Rules

When creating or modifying tokens:
1. Follow the schema in .design-system/token-schema.json
2. Semantic tokens MUST alias to primitives, never raw values
3. New intents require approval (add to schema first)
4. Check existing tokens before creating new ones: duplicates are the #1 issue
5. Token names are kebab-case with dots as separators
6. No abbreviations except: bg, fg, sm, md, lg, xl
7. Run `npm run build:tokens` after any changes

File: .claude/rules/component-conventions.md

Only loads when Claude works with component files.

---
paths:
  - "src/components/**"
---

# Component Conventions

1. Check .design-system/component-intent.json before creating new components
2. Check .design-system/knowledge-graph.json for token bindings
3. Every component gets: TypeScript props interface, CSS custom properties (no hardcoded values), unit tests, Storybook story
4. Variants map 1:1 to design tokens: Button danger = color.bg.danger
5. Context-aware behavior must be documented in component-intent.json
6. All interactive components need: focus ring, keyboard nav, ARIA attributes

File: tokens/CLAUDE.md

Only loads when Claude works in the tokens folder.

# Token Files

- core.json: primitive values (colors, spacing scale)
- semantic.json: aliases to primitives by intent
- All tokens use [format] format
- Run `npm run build:tokens` after changes
- NEVER edit generated files in `dist/`
- Check for duplicates before adding new tokens

File: src/components/CLAUDE.md

Only loads when Claude works with components.

# Components

- Each component: index.tsx + styles.css + Component.test.tsx + Component.stories.tsx
- All styling via CSS custom properties mapped to tokens
- No hardcoded colors, spacing, or font sizes
- Every component must have: props interface, a11y attributes, keyboard nav
- Check .design-system/component-intent.json before creating new components
- Check .design-system/knowledge-graph.json for token bindings

File: .design-system/naming-conventions.md

# Naming Conventions

## Tokens
Pattern: `{category}.{property}.{intent}.{modifier?}`
Separator: `.` (dot)
Case: kebab-case

### Categories
color, space, size, radius, font, shadow, motion

### Properties (per category)
- color: bg, fg, border, outline, shadow
- space: gap, padding, margin, inset
- size: icon, avatar, input, touch
- radius: sm, md, lg, full
- font: size, weight, line-height, letter-spacing
- shadow: sm, md, lg, inner
- motion: duration, easing

### Allowed abbreviations
bg, fg, sm, md, lg, xl, xs, 2xl, 3xl

### Examples
- color.bg.primary (correct)
- color.background.primary (wrong: use bg)
- colorBgPrimary (wrong: use dots and kebab-case)
- red-500 (wrong: this is a primitive, not semantic)

## Components
- PascalCase for component names
- kebab-case for file names
- Variant names match intent tokens: primary, secondary, danger, ghost

## Files
- kebab-case for all file names
- Component folder: `component-name/`
- Test file: `component-name.test.tsx`
- Story file: `component-name.stories.tsx`