How to Make Claude Code Follow Your Design System

Claude Code needs a source it can inspect

When Claude Code chooses a different blue or spacing value in a later session, the problem is rarely a lack of model capability. The project has asked the model to interpret a design decision again. A sentence such as “our brand color is dark blue” still leaves many valid values. Even an exact hex in prose is separate from the theme that production code uses.

The stable answer is to express the decision in code, give it a semantic name, and tell Claude where to find it. The same principle applies to components. If the repository contains a production Button with approved variants and states, Claude should import it instead of recreating its appearance.

Use CLAUDE.md as an index

Claude Code loads CLAUDE.md as project context. The file can also import other documents, and .claude/rules/ can scope guidance to particular paths. This makes it useful as an index to the design system.

Keep the instruction concrete and short. It should identify the design document, token source, component directory, and validation command. The detailed system stays in the files that people and code already maintain.

## Product UI
Before changing UI, read @DESIGN.md.
Use tokens from @src/styles/tokens.css.
Reuse @src/components/ui before creating a new primitive.
Run the component and accessibility checks after the change.

Specific instructions work better than broad adjectives because they are verifiable. “Use the existing Dialog component and its destructive variant” can be checked in a diff. “Keep the interface elegant” cannot.

Components carry more information than a style guide

A component is not only its appearance. It also contains semantics, keyboard behavior, focus handling, responsive behavior, loading, disabled, and error states. This is why component reuse is the strongest constraint available to a coding agent.

A DESIGN.md file should explain the relationships that code alone does not make obvious: which component is canonical, when a variant is allowed, how settings pages are composed, and which patterns should not be added to navigation. This product layer is what separates a reusable system from a collection of styled primitives.

Skills can add general craft guidance, but they do not know the decisions inside your product. A public UI skill may improve spacing or accessibility. It cannot know that your customers already use one settings flow and that a second flow would damage product coherence.

Claude Design can consume the system, but the source still matters

Claude Design can extract reusable colors, typography, components, and layout patterns from codebases and other design material. Anthropic recommends reviewing the generated system and testing it against realistic projects before publishing it to a team.

That review is important. If the source contains duplicate cards, incomplete states, or an outdated visual direction, extraction can preserve those problems. The tool can organize what it receives, but it cannot know which historical variation should define the next version of the product.

For a small, consistent application, connect the clean source and test it with a real flow. For a product that has already drifted, begin with a SaaS UX audit, make the canonical decisions, and then expose the result to Claude Code or Claude Design. The comparable setup for another coding tool is described in the Cursor guide.