Writing the CLAUDE.md for a design systemWriting the CLAUDE.md for a design system

A coding agent will build you a perfectly good dialog from scratch, which is a problem, because you already have one, with focus handling and motion tokens and a dark-mode treatment that took months to get right, and the agent has no way of knowing that unless something tells it. Putting that something in every prompt is a losing game. The durable fix is a short instructions file at the root of the repository (a CLAUDE.md for Claude Code, and the idea carries to any agent) that says what the system is, in what order to reach for its parts, and what never to do.

Where the rule came from

Agents on this site were using the wrong icons and tokens, several at once: icon styles that did not match, colors off the palette, and spacing and type that did not follow the scale. I saw it on the rendered page, where the pages looked slightly generic and slightly off, and I did not see it in a diff, which is why restating the system in prompts could not catch it. This site's rule went in on 2026-06-26, in a commit that added a hard "reuse the existing design system, don't hand-roll UI or pull in outside libraries" directive so it wouldn't have to be restated per prompt. The commit split the work in two. CLAUDE.md carries the directive, because it is always loaded as project instructions, and docs/design.md carries the supporting detail in its composition rules and its Do's and Don'ts list. CLAUDE.md then pulls in the design doc, the writing style guide and the backlog by @ reference, so the short file points at the long ones.

The directive is short enough to be read in full every session, the detail runs as long as it needs to, and a rule written in both places drifts apart, so each fact has one home and the other file points at it.

The order of preference

The center of the file is an ordered list, condensed here:

1. src/components/ui/: the atomic design system (Button, Input, Dialog, Tabs, and ~40 more). Reach here first.
2. src/blocks/: generic, props-driven section templates for larger layout patterns.
3. Radix primitives for any interactive overlay or disclosure behavior. Never re-implement this by hand.
4. src/icons/: the only place icons come from.

An ordered list works better than a blanket ban because it answers the question an agent is really asking, which is what to do when the thing it needs isn't in the first place it looked. Each tier hands it a next step. The file then closes the loop: build a new component only when nothing in the system fits, match the existing patterns (CSS Modules, the size and variant conventions, the icon registry), and add the new piece to the system so a one-off never ends up inside a page. It also points the agent at a live inventory page, /visual-language, to check before deciding something doesn't exist, because a component the agent cannot see is a component it will hand-roll.

What the detail file holds

The design doc is where the rules get precise. Components are styled with CSS Modules and no Tailwind. Portals mount to the app shell's portal roots and never to document.body. Radix internals never get !important overrides. No one hand-rolls an inline <svg> for an icon shape the icon library already provides, and the icon gets added to the registry instead.

Each of those names the specific behavior to stop and the specific place to go next, and that is the standard for any rule you add. "Follow the design system" gives an agent nothing to act on. "Icons come from src/icons and nowhere else" gives it a destination and gives you a search that can verify the result. I wrote about the token side of the same problem in token architecture decisions, and the workflow around it in how I use Claude to ship design system work faster.

Where instructions stop

The icon rule has no lint check behind it yet. eslint.config.js has no no-restricted-imports rule for @phosphor-icons/react, and the code review plan from 2026-10-21 queues one as issue #145, with src/icons/** as the only exception. Until that lands, an agent that ignores the rule gets caught by a reviewer, which is the expensive way to catch it.

Figma's post on design systems, AI and MCP describes automated rules generation that scans a codebase for token definitions, components and naming conventions, and warns that output defaults to React and Tailwind unless the agent is configured for your stack. That warning is one more reason the file names your stack, your directories and your forbidden imports in words an agent can match.

How to test yours

Ask your agent for something ordinary, such as a settings panel with a toggle, a confirmation dialog and a form, once with no instructions file and once with it, and compare the two results on the rendered page as well as in the diff. Count the hand-rolled elements, the invented colors and the imports from the wrong place, and look at the icons, the spacing and the type, since those are the failures that read fine in code and wrong on screen. Every failure that survives in the second run is the next rule to write, and it should be specific enough that a search can tell you whether it was followed.