Design System as a Claude Code Skill

Claude does not know your design system, so it guesses. You correct the guess on every screen.

It picks a colour nobody approved. It hand draws a button that already exists. It writes an Arabic screen by mirroring the English one at the end. The system is in your head and in a Figma file, and neither of those is something Claude can read.

This kit is that system written as a folder Claude loads before it draws, audits or fixes anything. Drop it in, replace the example brand with yours, and the guessing stops.

Where you are now

1. Loose values. A hex and a pixel number typed on each screen. Nothing names them, so nothing can check them.
2. Styles in the Figma file. Named in one place only. The code retypes the same values by hand.
3. Primitive tokens. A scale exists and the steps have names. No rule says which step belongs where.
4. Semantic roles. Tokens named by the job they do, with modes for light and dark, density, and breakpoint.
5. Contracts and rules. Every component has a written spec, and a validator fails the values that break it.
6. A system an agent reads. The folder is the source. Claude loads it first, cites it, and proposes instead of inventing.

This kit hands you levels four, five and six already built, across eight foundations: colour, typography, spacing, radius, border, elevation, layout, motion. Each one runs three layers, scale then primitives then semantic roles. You replace the primitives with your brand and the whole system follows.

Before

• You tell Claude which colour, every time.
• The same button is redrawn on three screens.
• The Figma file and the code drift, and nobody knows which one is right.
• “Is this on brand” gets answered from memory.
• Arabic is the English layout, flipped at the end.
• A decision made in March gets argued again in September.

After

• Claude resolves the colour to a semantic token path, or it reports that no token exists.
• Every element maps to a contract in components/. No contract means a proposal, not a free hand.
• figma-variables.js pushes the same tokens.json into the file as eight variable collections with their modes.
• An audit finding cites a token path, a contract field or a rule line, or it does not count.
• rtl.md runs on every placement, and the tokens carry the Arabic type size.
• decisions/ holds the record and HISTORY.md routes to it in one hop.

What lands in the download

One folder, 79 files. Sixty of them plus 19 PDF guides.

• SKILL.md · MD · The router. One load path per task, the intake rule, and four rules that never bend.
• tokens.json · JSON · 637 tokens in W3C DTCG shape. Scale, primitives and semantic roles, with modes for light and dark, compact, default and comfortable density, and four breakpoints.
• foundations/ · 33 MD · Eight foundations. Each one has its rules file plus ACCESSIBILITY.md (the WCAG criteria and the one test), DEV_HANDOFF.md (the CSS variables and the mode switch) and KNOWLEDGE_BASE.md (one file to paste into any chat or NotebookLM).
• components/ · 6 YAML · Button, TextField, CodeField, Badge, Banner, EmptyState, plus the schema they are checked against. Tokens, geometry, props, states, copy rules, accessibility, do and do not.
• references/ · 8 MD · The design, audit, fix and component methods. Plus rtl.md, content-system.md, figma-sync.md and design-system.md.
• GOVERNANCE.md, HISTORY.md, decisions/ · MD · The lifecycle ladder, the three part promotion gate, the two tier SemVer policy, and one record per decision with a template.
• scripts/ · 3 PY + 1 JS · build_tokens.py generates tokens.json from the scales. validate.py rejects a hex, a scale step or a primitive on a component. tokens_to_css.py emits the CSS variables. figma-variables.js builds the eight Figma collections through the Claude Figma connector and updates them by name on a re run.
• docs/ · 19 PDF · 312 pages. The Kit guide (18 pages), the Foundations guide (19) and the Prompts library (27 pages, 17 prompts across six stages), then a usage guide (20 pages) and a prompt library (11 pages) for each of the eight foundations.

How it starts

The first message asks two things and writes nothing until both are answered. Are you connecting Claude to a design system that already exists, or starting one from this kit. And what backup do you want in place before the first change, a named version in Figma or a branch in the repo.

Who it is for

Product designers, design system leads and founders working in Claude Code with Figma, Cursor, or any editor that reads skills. The foundation names follow the designsystems.surf templates, so if you own those Figma files the tokens map one to one. Arabic first teams get the RTL rules and the Arabic type layer, which the templates do not carry. The example brand is Bunn, a coffee delivery app, used across every guide so you can see a finished system before you replace it.

Licence. One person, unlimited projects and clients. The design system you build with it is yours. Updates ship to the same download.