Updated 3 November 2026

Make Claude Code follow your design system

To make Claude Code follow your design system, give it a project skill at .claude/skills/<name>/SKILL.md that lists your tokens and hard rules, with a description saying when to use it, and keep the full reference in a DESIGN.md at the repo root. Claude Code uses a skill's description to decide when to load it, so UI work picks up your colours, type and spacing without you repeating them. Then check what it writes: an MCP server lets it query tokens and lint snippets before it finishes, and a CI lint catches anything that slips through.

What Claude Code reads

Claude Code has two places that matter for UI consistency:

• Skills in .claude/skills/<skill-name>/SKILL.md. The description in the front matter tells Claude when to apply the skill, and you can also run it by hand with /<skill-name> (skills docs).
• CLAUDE.md at ./CLAUDE.md or ./.claude/CLAUDE.md, loaded at the start of every session (memory docs).

A skill suits a design system because it loads when the task matches its description, while CLAUDE.md loads every time. Use CLAUDE.md for a pointer and the skill for the tokens.

The manual way

1. Write DESIGN.md

DESIGN.md is Google's open format for a design system: YAML front matter with the token values, then prose sections on how to apply them. See What is DESIGN.md? for the structure. It is the source of truth; the skill is a working summary of it.

2. Create the skill

Make a folder named after the skill and put SKILL.md inside it:

.claude/skills/acme-design-system/SKILL.md

Keep the description specific and front-loaded with when to use it. Claude Code truncates the combined description and when_to_use text at 1,536 characters in the skill listing, so put the use case first. A short example:

---
name: acme-design-system
description: "Use when building, editing or reviewing any UI for Acme: pages, components, styles, Tailwind classes or CSS. Applies the Acme design tokens (colours, typography, spacing, radii, shadows, motion) and component specs so generated UI matches the existing product."
---

# Acme design system

If the project has a `DESIGN.md`, it is the full reference; this skill is the working summary.

## Tokens

### Colors
- `background` #ffffff
- `text` #1f2933
- `primary` #2f5bea
- `on-primary` #ffffff

### Spacing (4px grid)
`xs` 4px · `sm` 8px · `md` 16px · `lg` 24px

## Constraints

- MUST use only the colours above. No new hex, rgb or hsl values, and no Tailwind palette defaults (`blue-500`, `gray-100`).
- MUST keep every margin, padding and gap a multiple of 4px, preferring the spacing tokens.
- MUST NOT hard-code a value when a token exists; reference the CSS variable or theme key.
- If a requirement cannot be met with existing tokens, ask before adding a token.

## Output rules

1. Map tokens to the project's existing token layer (CSS variables, Tailwind theme, CSS-in-JS theme). Create one only if none exists.
2. Build from the component specs above; add hover, focus, active and disabled states using existing tokens.
3. End your reply with a short **Tokens used** list and a **Deviations** list (empty if none).

The "Tokens used / Deviations" note gives you something quick to review on every UI change.

3. Point CLAUDE.md at it

Add a short section so every session knows where the design system lives:

## UI
- `DESIGN.md` is the source of truth for all UI. Read it before writing or changing UI.
- Use the acme-design-system skill for pages, components and styles.

You could import the whole file with @DESIGN.md, but imported files load with CLAUDE.md in every session, and the docs suggest keeping each CLAUDE.md under 200 lines. A pointer plus the skill keeps the context small.

The fast way with Designrail

Designrail reads the rendered styles of a live site and writes these files for you from one token set.

From the extension (Chrome or Edge): open the Designrail side panel on the site you want to match; it scans the page. Choose Add to project… and pick your repository folder. On the free plan this writes DESIGN.md and .claude/skills/<name>-design-system/SKILL.md; the Cursor rule, Copilot instructions, AGENTS.md section and token files are part of Pro.

From the CLI: run this in your repository:

pnpm dlx designrail scan https://www.example.com --site --install

--site crawls up to 10 same-origin pages plus a 390px mobile pass. --install writes the full project layout:

The skill name is the site name in lowercase with -design-system appended, so Acme becomes acme-design-system. Without --install, only DESIGN.md and SKILL.md are written to --out. Full options are in the CLI docs.

Codex and AGENTS.md

Codex reads AGENTS.md: it starts at the project root, walks down to your working directory, and joins the files it finds, with closer files appearing later. It stops adding files at project_doc_max_bytes, 32 KiB by default (Codex AGENTS.md docs).

So --install writes only a short section into AGENTS.md, between <!-- designrail:start --> and <!-- designrail:end --> markers, and leaves the rest of the file alone:

<!-- designrail:start -->
## Design system

UI in this repo follows the **Acme** design system. `DESIGN.md` at the repo root is the source of truth: read it before writing or changing any UI.

- Colours: only the tokens in `DESIGN.md` (primary `#2f5bea`). No new hex, rgb or hsl values, no framework palette defaults.
- Spacing: multiples of 4px from the spacing scale.
- If a token is missing, ask before adding one. End UI changes with a short "Tokens used / Deviations" note.
<!-- designrail:end -->

Codex also supports skills in the same SKILL.md format (name and description are required), but it looks for them in .agents/skills, not .claude/skills (Codex skills docs). To use the skill in Codex as well, copy the generated folder there.

Keeping it in sync

MCP server. designrail mcp serves your DESIGN.md to Claude Code over MCP. Register it once:

claude mcp add design-system -- pnpm dlx designrail mcp

It exposes four tools and one resource:

• get_tokens: tokens from DESIGN.md, optionally one category (colors, typography, spacing, rounded, components).
• get_component: one component spec, such as button-primary, with its hover, focus and disabled states.
• check_snippet: lints code for raw colours, default Tailwind palette classes, off-grid spacing and unknown fonts.
• check_url: renders a page such as http://localhost:3000 and scores it against DESIGN.md.
• design://DESIGN.md: the whole file as a resource.

The server rereads ./DESIGN.md on every call (--design <path> to change it), so edits apply without a restart. See the MCP docs.

CI. designrail lint-code src --max-warnings 0 fails when source contains raw colour literals, palette classes such as bg-blue-500, off-grid arbitrary values such as p-[13px], or unknown fonts. The GitHub Action runs the same lint on every pull request, annotates the diff, and can score a preview URL. Its sync mode rescans your live site on a schedule and opens a pull request when the design changes, so DESIGN.md and the skill do not go stale. Add designrail-ignore to a line to skip it.

Troubleshooting

The skill never loads. Check the folder layout: the file must be .claude/skills/<name>/SKILL.md, and the front matter is read only when --- is the file's first line. If .claude/skills/ did not exist when the session started, run /reload-skills. Edits to an existing skill are picked up within the session.

It loads for some tasks but not others. Claude decides from the description. Name the kinds of work in it ("pages, components, styles, Tailwind classes or CSS"), or invoke it directly with /acme-design-system.

The AGENTS.md section has no effect in Claude Code. By default Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you have a CLAUDE.md, add @AGENTS.md to it. Run /context to see which files loaded.

It still invents hex values. Instructions are context, not enforcement. Register the MCP server and ask Claude to run check_snippet before finishing, and keep lint-code in CI as the backstop.

FAQ

Should the design system go in CLAUDE.md or a skill?

Put the tokens in a skill and a one-line pointer in CLAUDE.md. CLAUDE.md loads in every session, while a skill loads when the task matches its description.

Does Claude Code read DESIGN.md on its own?

No, it is not one of the files Claude Code loads automatically. Point to it from CLAUDE.md, the skill or the AGENTS.md section, or expose it through the MCP server's design://DESIGN.md resource.

Does the same SKILL.md work in Codex?

The format is the same, but Codex looks for skills in .agents/skills, so copy the folder there. Codex already gets the design rules from the AGENTS.md section.

Will a rescan overwrite my AGENTS.md?

No. Only the block between the Designrail markers is replaced; the rest of the file stays as you wrote it. DESIGN.md, the skill and the token files are overwritten.

I use Cursor or Copilot as well. Do I need separate files?

Yes, each tool reads its own location, and --install writes all of them from one scan. See Make Cursor follow your design system, or compare the options.