Give Claude Code your design system as a skill, not a paragraph in a prompt

Most teams already have a design system. It lives in a Figma file, a style guide and one senior designer's head, and none of those are places Claude reads. So every generated screen starts from the generic default and someone spends an afternoon pulling it back on brand. The system needs to be where the model looks.

The shape: four files in one folder

your-design-skill/
  SKILL.md                 the hard rules, and the description that loads it
  references/tokens.css    every value, named
  references/components.md recipes for the pieces every screen uses
  README.md                install, requirements, what to try

Keeping tokens and recipes in references/ matters. The rules in SKILL.md are read whenever the skill is active; the references are opened only when Claude needs them, so a long token file does not cost context on every turn.

SKILL.md: ten rules, not a style guide

Resist pasting the whole brand book. What Claude needs is the short list of decisions it would otherwise get wrong, stated so they can be checked. Good rules are specific and falsifiable:

• The accent appears at most twice per screen, and only on actions.
• Every number is monospace with tabular figures.
• Borders are hairlines; no shadow except to show one surface above another.
• Headlines use the display face at weight 400; nothing under 32px uses it.
• Green and red appear only on figures that moved, never on buttons.

Add a short section called what this look is not. It is the cheapest way to stop a request drifting into the generic default, because it names the default and rules it out.

tokens.css: names that carry meaning

Write the palette as named values, and name them by job rather than by colour where you can. A token called --accent tells Claude where it goes; a token called --lime-400 only tells it what it looks like. The best token files have both: a raw ramp at the top, and semantic tokens that components are required to use.

:root {
  --lime-400: #d2f205;   /* raw ramp */
  --ink-900: #0e0f0d;
  --accent-fill: var(--lime-400);   /* what components use */
  --accent-fill-ink: var(--ink-900);
}

components.md: recipes for the five pieces that matter

You do not need a full component library. Write down the pieces nearly every screen uses, in working code, with the values filled in: the primary and secondary button, the card, the header, the hero and how a number is shown. If a piece has a trap, such as a stacking context that breaks a glow, say so next to the recipe.

The description decides whether any of it is used

A skill Claude never loads does nothing, and loading is decided by one line: the description in the frontmatter. Name the requests people actually make and the look itself. The same rule as any other skill applies, covered in why a skill does not fire.

description: Builds or restyles UI in an editorial style: paper and coal surfaces,
  a serif display face, mono numbers, one flat lime accent. Use when asked for a
  page that looks credible rather than techy, a leaderboard, or less generic UI.

Or start from one that already exists

If you would rather begin from a finished system than write one, each of ours is exactly this structure, written from a live site you can open and compare: Glass Instrument UI, macOS Native Dark UI and Editorial Ledger UI. Pair any of them with a usability pass, as described in using ui-ux-pro-max with a design skill.