Maintaining a Design System with Claude Code

A design system does not break, it drifts. The Figma variables, the token file, the component code, and the documentation describe the same system on four different dates, and by the time someone notices, nobody can say which one is right. Claude Code is well suited to this because drift is a comparison problem, and comparison across four surfaces is tedious for a person and cheap for an agent.

This is the maintenance half of design work. Getting a frame into code is covered in Figma to code with Claude Code; the wider picture is in the pillar, Claude for design work. Definitions live in the glossary under design tokens.

The four surfaces that disagree

None of those four events is a mistake in isolation. The cost is the gap between them, and the gap is invisible until you read all four at once.

A repo layout an agent can navigate

Put the surfaces in one repository, and name things so a file's job is obvious from its path:

design-system/
├── tokens/
│   ├── figma-variables.json     # raw export, never hand-edited
│   └── tokens.css               # generated from the export
├── components/
│   └── Button/
│       ├── Button.tsx
│       ├── Button.spec.md       # the human-readable contract
│       └── Button.test.tsx
├── docs/
│   └── patterns/
└── .claude/
    └── rules/
        └── components.md

Two things matter here. The token file is generated, so a diff on it is meaningful rather than a mix of intent and typos. And each component folder carries its own spec beside the code, so documentation drift shows up in the same pull request as the change that caused it.

Rules the system enforces on itself

CLAUDE.md at the repo root is read at the start of every session, so it is where the non-negotiables go:

## Design system rules
 
- Tokens are generated. Re-run the export to change `tokens/figma-variables.json`;
  never hand-edit `tokens/tokens.css`.
- Components may only use token classes. A raw hex, rgb, or px value under
  `components/**` is a bug, not a style choice.
- Every component folder has a `.spec.md` listing variants, states, props,
  accessibility notes, and the Figma node URL it implements.
- New variants are added to the spec first, the component second.
- Deprecations are additive: keep the old export, mark it deprecated, and add a
  migration line to the spec.

Keep that file short. Anthropic's guidance is to target under 200 lines per CLAUDE.md, because long files consume context and reduce how reliably instructions are followed; CLAUDE.md best practices goes further. Longer, file-specific material belongs in .claude/rules/, where a paths field scopes it to matching files:

---
paths:
  - "components/**/*.tsx"
---
 
# Component authoring
 
- Props are typed, no `any`. One component per file, named export.
- Every interactive element has a visible focus style and an accessible name.
- Loading, empty, disabled, and error states are implemented, not left to callers.

That rule only enters context when Claude opens a component file, so the rest of your sessions are not paying for it.

The weekly drift report

Give the audit to a subagent so the file reading it does stays out of your main session and comes back as a report. The design-systems-librarian agent is built for this: it reads the token file, the components, and the specs, and returns a list rather than a set of edits.

A useful report answers five questions:

1. Which token classes are defined but referenced nowhere?
2. Which components contain a raw color, spacing, or radius value?
3. Which components have variants or states the spec does not mention, or a spec entry the code does not implement?
4. Which two components are close enough to be duplicates?
5. Which specs point at a Figma node URL that no longer resolves?

Run it on a schedule and open the findings as issues. Resist the temptation to let an agent fix drift unattended: an unused token is unused until a marketing page imports it, and a prop rename is safe until something outside the repo consumes it. The exception is the token file itself, which is regenerated rather than edited.

Regenerating tokens instead of maintaining them

The Figma MCP server exposes get_variable_defs, which returns the variables and styles behind a selection: colors, spacing, typography. Export that to tokens/figma-variables.json, then run the design-tokens command to regenerate tokens.css from it and print a diff of what changed. Setup for the server is in Figma to code with Claude Code, and its tools are listed on the Figma MCP tool page.

Two more tools matter once the system is real. get_code_connect_map resolves Figma node IDs to the code components they represent, and add_code_connect_map records new mappings, which is what stops an agent from re-implementing a button that already exists. Figma also ships a create_design_system_rules prompt that generates a rules file for aligning generated code with your system; treat its output as a first draft of the rules above rather than a finished policy.

Documentation that survives the next change

Specs rot because writing them is nobody's favorite hour. Hand the first draft to the component-spec-writer skill: it reads the component and produces a spec with variants, states, props, accessibility notes, and usage guidance in a fixed shape, which you then correct. A wrong draft you edit in five minutes beats a blank file that stays blank for a quarter.

Then make the spec load-bearing. If the rule is that new variants go into the spec first, the spec stops being a description of the past and becomes the thing the next change is written against.

The review checklist

Before a component change merges, run through this. Claude can check every item except the last two.

• Every color, spacing, and radius value resolves to a token; nothing raw.
• Variants and states in the code match the spec, in both directions.
• Loading, empty, disabled, and error states exist and are reachable.
• Focus is visible, targets are large enough, and contrast holds in both themes. The accessibility-auditor agent covers this properly against WCAG.
• The spec's Figma node URL still resolves to the frame the code implements.
• No near-duplicate of an existing component was introduced.
• A human looked at the rendered component, not just the diff.

If your team also wants critique, handoff specs, and UX copy inside the same setup, Anthropic's plugin covers that side and is walked through in Anthropic's design plugin. For the terminal groundwork behind all of it, start at Claude Code for designers.