Claude Code Design System: 4 Parts for On-Brand UI

A Claude Code design system is a repository-level context stack that tells the agent what your brand looks like, how to implement it and how to check the result. A practical version uses three Markdown files plus an examples/ directory. It replaces repeated brand prompts with versioned evidence, rules and approved patterns.

The workflow came to wider attention through Charlie Hills's four-part brand system and prompt set. The useful idea is not that these filenames are magic. It is that an agent performs better when visual evidence, implementation rules and quality checks are durable project inputs rather than instructions buried in a chat.

This guide turns that idea into a workflow a product team can review, test and maintain. It targets the long-tail question how to make Claude Code follow a design system. It does not compete with our broader article on context engineering for coding agents or our production-focused AI-generated software checklist.

What are the four parts of a Claude Code design system?

Strictly speaking, this is a four-part system, not four files. The fourth part is a directory. Only CLAUDE.md has special meaning to Claude Code. Anthropic's Claude Code memory documentation says project-level CLAUDE.md files are loaded as persistent instructions and recommends keeping them specific, concise and well structured. REFERENCE.md, DESIGN.md and examples/ work because you explicitly point Claude at them.

How should the project be structured?

your-project/
├── CLAUDE.md
├── REFERENCE.md
├── DESIGN.md
├── examples/
│   ├── README.md
│   ├── dashboard-approved.png
│   ├── landing-page-approved.png
│   └── pricing-card-approved.html
├── src/
└── tests/

Add an examples/README.md with one row per artifact: owner, approval date, source, reusable elements and known exceptions. This small manifest stops an old campaign asset or experimental screen from quietly becoming a permanent product rule.

Prompt 1: turn approved work into REFERENCE.md

Choose three to five examples that already represent the brand well. Prefer your own production screens, brand deck, marketing graphics or component library. Do not copy a competitor's protected assets into the repository. Inspiration can inform a decision, but the reusable examples should be work you own or have permission to use.

Review every file in examples/. Separate what you can observe from what you must ask.

Draft REFERENCE.md with:
1. source inventory and approval status
2. colors with sampled values and observed roles
3. typography, sizes and hierarchy
4. spacing, grid and alignment patterns
5. logo placement and clear-space rules
6. recurring components and compositions
7. five patterns this brand must avoid
8. unresolved questions

Do not invent missing values. Show the draft before saving it.

The strongest output distinguishes evidence from policy. “The three approved screens use 24 px between cards” is an observation. “All card groups must use 24 px” is a rule that a human should approve. Mixing the two turns accidental legacy choices into doctrine.

Prompt 2: make CLAUDE.md route design work

Keep the pointer short. A large instruction file consumes context every session, while the detailed design material only matters during interface work.

## Interface work

Before creating or changing UI, read REFERENCE.md and DESIGN.md, then inspect the closest approved example in examples/.
Use existing components and semantic tokens before adding new ones.
If the sources conflict or do not cover a consequential choice, ask instead of guessing.
Before completion, compare the rendered result with the design rules and report every intentional exception.

This routing layer should say when to read, what has priority and how to verify. If your project already has a long CLAUDE.md, use a path-scoped rule for frontend files or a short import. Note that an import improves organization but still loads the imported text at launch, according to Anthropic's documentation.

Prompt 3: convert the reference into DESIGN.md

DESIGN.md is the build contract. The emerging Google Labs DESIGN.md format describes a self-contained file with optional machine-readable tokens in YAML frontmatter and human-readable design rationale in Markdown. You can follow that format for portability, but Claude Code does not require it.

Read REFERENCE.md and examples/README.md, then inspect every approved example.

Draft DESIGN.md as an implementation contract with:
1. semantic color tokens named by job, not hue
2. type and spacing scales with exact values
3. layout, grid and breakpoint rules
4. component anatomy, states and reuse policy
5. interaction, motion and reduced-motion behavior
6. accessibility requirements
7. responsive examples and edge cases
8. a decision log with date, owner and reason

Flag every rule that is inferred rather than approved. Ask where sources disagree. Show the file before saving it.

Role-based names survive a redesign better than visual names. color-text-primary explains intent; dark-gray only describes the current value. If tokens also need to travel into design and build tools, keep a machine-readable token source beside the narrative file.

Why do examples matter more than a longer prompt?

Rules tell an agent what is allowed. Approved examples show proportion, density, hierarchy and composition working together. Anthropic gives similar advice for its separate Claude Design product: its official design-system setup guide accepts codebases, prototypes, decks and brand assets, and recommends including real examples instead of only specifications.

Choose examples by coverage, not volume. One dense dashboard, one marketing page, one form-heavy flow and one mobile state usually teach more than fifty nearly identical hero sections. Each example should answer a question that the text alone leaves ambiguous.

Should DESIGN.md replace design tokens?

No. DESIGN.md explains design intent; a token file gives tools a strict interchange format. Use both when values must flow into code, design tools and validation. The stable Design Tokens Community Group format defines a JSON model for token names, values, types and metadata. Let that file own exact machine values, then have DESIGN.md explain when and why to apply them.

How do you stop the system from copying mistakes?

1. Label every source. Mark it approved, historical, experimental or inspiration-only.
2. Set precedence. Current tokens beat screenshots for exact values. A reviewed component beats an old marketing graphic for interaction behavior.
3. Record exceptions. If a campaign intentionally breaks the grid, say so in the manifest.
4. Require variants. Ask for three alternatives before polishing. Selection is a human design decision.
5. Promote only reviewed patterns. Add the chosen result to examples/ after approval, not after generation.

The directory should grow slowly. A library of approved patterns compounds consistency; a library of every output compounds errors.

What should the validation loop check?

Do not ask the producing agent to be the only judge. Let it run the first comparison, then use deterministic checks and a person with approval authority. The output should include changed rules, intentional exceptions and evidence from the test run.

Claude Code files vs Claude Design: which should you use?

They can complement each other. Claude Design can help teams explore and publish a shared system, while the repository keeps implementation rules, components and tests close to production code.

How should a team roll this out?

1. Select representative work. Cover product UI, marketing and at least one difficult state.
2. Draft and review the two source files. Design owns the visual truth; engineering owns implementation feasibility.
3. Wire the routing rule. Keep CLAUDE.md short and test that Claude actually loads the sources.
4. Pilot three task types. Try a new component, an existing screen change and a responsive repair.
5. Measure rework. Track review rounds, unapproved tokens, duplicate components, accessibility defects and accepted first-pass changes.
6. Assign maintenance. Name owners for tokens, components, examples and the decision log.

For a company rollout, the purchase decision is not “Which prompt pack should we buy?” It is “Who owns the design contract, how is compliance tested and which changes require approval?” Wavect's AI enablement service can help teams turn ad hoc agent use into a governed workflow with repository context, evaluations and review gates. If the generated product already needs hardening, use the prototype-to-production decision guide to scope the next step.

Research boundary

Reviewed on 2 September 2026 against the original workflow, current Claude Code memory documentation, the Google Labs DESIGN.md specification, Anthropic's Claude Design guidance and the stable Design Tokens Community Group format. Product behavior and beta availability can change. We make no quantified productivity claim because this workflow has no independent cross-team benchmark.