CLAUDE.md: Teaching Claude Your Design System

What you will need

Claude Code

CLI or IDE extension. The /init command in this lesson is part of standard Claude Code.

Read more

A design system repo

Your own project, a client project, or a copy of one you maintain. The exercise will not feel real on a toy repo.

30 minutes

10 minutes to bootstrap with /init. 15 minutes to add the design-system-specific layer. 5 minutes for the before/after test.

What CLAUDE.md is, in one sentence

CLAUDE.md is a markdown file at the root of your project that Claude reads before every task, and it is the single biggest variable controlling whether Claude’s output looks like your design system or like the internet’s average.

That is the whole concept. The rest of this lesson is what to put in it, what to leave out, and how to keep it small.

The four jobs of a good CLAUDE.md

A useful CLAUDE.md does exactly four things. Anything else is bloat.

1. Compress your design system into a readable summary

Not the full system. The summary. A new contractor (or a new agent) reading the first 60 lines should be able to tell you:

• What this project is
• What the design system is built on (Style Dictionary, Tokens Studio, Tailwind, etc.)
• The token naming pattern
• How many components there are, organized into how many categories
• Where things live (folder structure)

2. State your preferences in plain English

The decisions that are not implied by the code. The “we always do this” rules.

• Naming conventions (“kebab-case for token names, PascalCase for components”)
• File organization rules (“never put a component in src/utils/”)
• Voice and tone (“docs are written in second person, no marketing language”)

3. Declare your capabilities

What Claude is allowed to do, what it must ask before doing, and what is off-limits.

• “You may run npm test and npm run build without asking.”
• “You may not run any command that touches package.json without confirmation.”
• “You may not delete files in legacy/ ever.”

4. Keep a failure log

The mistakes Claude has made before, written down so it does not make them again.

• “When asked to add a token, never invent a new category. Use one of: color, spacing, radius, shadow, motion.”
• “When refactoring components, never rename props that appear in public/ exports.”
• “When generating docs, never use the word ‘seamless’.”

That is it. Four jobs. Everything else is fluff.

Where tools.md fits

CLAUDE.md should not become a dumping ground for every package, command, and deployment detail in the project. Keep those facts in tools.md.

Use the split like this:

• CLAUDE.md: project rules, design-system standards, permissions, failure log
• tools.md: framework, package manager, UI library, test commands, build commands, deployment target

Then add this bridge line to CLAUDE.md:

Before changing tooling, dependencies, tests, package scripts, or deployment
configuration, read ./tools.md and follow it as the source of truth.

If you do not have tools.md yet, use the Tools.md Generator or follow the full split in CLAUDE.md + tools.md: The Two Files Every AI Project Needs.

Step 1: Bootstrap with /init (3 minutes)

Open Claude Code in your project root. Run:

/init

Claude reads your repo and generates a baseline CLAUDE.md. It will catch the obvious stuff: language, framework, basic folder structure, lint and test commands.

Save what /init generated. Open it in your editor. You are about to add the layer that actually matters.

Step 2: Add the design system layer (15 minutes)

Add the four sections below to the file. Adapt them to your project. The labels stay the same so future-you (and future agents) can find what they need.

Template

## Design system summary

- **Project**: [your project name]
- **Built on**: [Style Dictionary / Tokens Studio / Tailwind / vanilla CSS / your stack]
- **Framework**: [React / Vue / Svelte / vanilla]
- **Component count**: [number] components across [number] categories
  ([list categories: layout, form, feedback, navigation, data, etc.])
- **Token count**: [number] semantic tokens, [number] primitive tokens
- **Source of truth**: [Figma library / GitHub / both]

## File structure

- `tokens/`, token JSON files (primitive in `core/`, semantic in `semantic/`)
- `src/components/`, one folder per component, each with `index.tsx`,
  `[Name].stories.tsx`, and `README.md`
- `src/styles/`, generated CSS variables only. Never edit by hand.
- `docs/`, written documentation. MDX. Reads like a guide, not an API dump.
- `legacy/`, read-only. Never modify or delete.

## Token naming convention

Pattern: `{category}.{role}.{variant?}.{state?}`

Examples:
- `color.background.surface.default`
- `color.background.surface.hover`
- `spacing.md`
- `radius.sm`

Bad (will be rejected): `bg-1`, `theme-color-7`, `primaryBtnBg`

## Top 10 components

The components that account for ~80% of usage. When asked to refactor or
generate UI, prefer these unless explicitly told otherwise:

1. Button. Primary, secondary, tertiary.
2. Input. Text, email, password, number.
3. Card. Surface for grouped content.
4. Modal. For blocking decisions only.
5. Toast. For non-blocking feedback.
6. Nav. Top-level navigation.
7. Table. Data with sorting and pagination.
8. Form. Wraps Input + validation.
9. Tabs. Content switcher.
10. Empty. Empty-state surface for lists and tables.

## Preferences

- Always use kebab-case for tokens. PascalCase for components. camelCase for props.
- Never use marketing words in product UI ("seamless", "unlock", "empower").
- Always reach for an existing component before creating a new one.
  When in doubt, ask before creating.
- Always co-locate stories and README with the component file.
- Before adding to an existing screen, observe its visual vocabulary first.
  Read the surrounding components and "think out loud" about what you see:
  copy tone, color palette, spacing density, hover and focus states, animation
  timings, shadow and card patterns. Match it. Do not invent a new style
  unless the user explicitly asks for one.

## Capabilities

You may, without asking:
- Run `npm test`, `npm run lint`, `npm run build`, `npm run docs:generate`
- Read any file in `src/`, `tokens/`, `docs/`
- Open small PRs in `tokens/` and `docs/`

You must ask before:
- Modifying anything in `src/components/` (touches public exports)
- Editing `package.json`, lockfiles, or any CI configuration
- Adding a new dependency

You must never:
- Delete or modify anything in `legacy/`
- Rename existing tokens (deprecate them instead)
- Skip the verification step before opening a PR

## Failure log

Past mistakes, recorded so they do not happen again. Add to this list whenever
Claude makes a real-world mistake on this project.

- (2026-04-12) Invented a `color.danger.subtle` token that did not exist.
  Always check `tokens/semantic/color.json` before referencing a color token.
- (2026-04-15) Renamed `Button` prop `variant` to `kind`. Broke 14 consumers.
  Never rename existing public props on components in `src/components/`.
- (2026-04-17) Used the word "seamless" in a generated doc. Banned word.

Save the file. You now have a design-system-aware CLAUDE.md.

Step 3: Run the before/after test (5 minutes)

Pick a prompt you would actually run on this project. Something specific. For example:

Add a destructive confirmation modal to the user-settings delete-account flow. Use our existing components and tokens.

Run it before, then after

1. Temporarily rename your CLAUDE.md to CLAUDE.md.bak.
2. Open a fresh Claude Code session. Paste the prompt. Save the output.
3. Restore the file: rename CLAUDE.md.bak back to CLAUDE.md.
4. Open another fresh session. Paste the same prompt. Save the output.

Compare the two outputs side by side.

That gap is the entire return on this lesson. Every prompt for the rest of the project’s life runs at the second level instead of the first.

Step 4: Establish the local feedback loop

CLAUDE.md is not a file you write once. It is a file you grow.

The local loop:

1. PLAN.     Describe the task to Claude
2. BUILD.    Claude executes, you review
3. COMPILE.  Note what went wrong (or surprisingly right)
4. UPDATE.   Add a line to the failure log or a new preference

Three habits that keep this loop going:

• End every working session with one minute of CLAUDE.md edits. What did Claude get wrong today? Add it to the failure log.
• Use /insights (covered in Lesson 7.8: Context Management) to surface patterns from your conversation history.
• Cap the file at ~200 lines. When it grows past that, split rules into .claude/rules/ files that load only on the relevant paths. See What Is an Agentic Design System?, Trait 3 for the path-scoped pattern.

If something stops working, check the CLAUDE.md section of Common failure modes.

Checklist: you are done when

What this unlocks

Once CLAUDE.md exists and is real, three things change:

1. Every other Module 7 lesson works as designed. Skills, sub-agents, parallelization, auto research. All of them depend on Claude knowing what your project actually is.
2. You stop re-explaining the same things every session. The repeated 1,100-token explanation goes away. Your context is freed up for the actual task.
3. Your team gets the same Claude you do. A teammate cloning your repo gets the same CLAUDE.md and the same baseline behavior. Quality stops being personal.

This is the smallest possible move with the biggest possible compounding effect. Every lesson after this one is downstream of how good your CLAUDE.md is.