Sample Design System

A playground for designers learning AI design system workflows. It is a small, real design system built on Base UI primitives, documented in Storybook and mirrored into Figma, so you can try the whole loop yourself: tokens in code, components in Storybook, the same system as Figma variables and components, and AI tools connected to both through MCP.

It is a teaching repo, not a production system. 42 components, 4 foundations pages, 4 full-screen patterns.

Start here

In plain words

A design system in code is the same idea as a Figma library. Figma has components, variables and styles. The code has the same things, written as text files a browser can show.

How a colour gets from a token to the screen (and into Figma)

1. Primitive token: tokens/tier-1-definitions/color.json defines color.brand.indigo.600 as #4F46E5. It says what the colour is.
2. Semantic token: tokens/tier-2-usage/semantic.light.json defines color.background.accent → {color.brand.indigo.600}. It says what it is for.
3. Build: npm run build:tokens (Style Dictionary) writes src/tokens/semantic.css:
   --sds-color-background-accent: var(--sds-color-brand-indigo-600);
4. Component: the primary button's stylesheet says background: var(--sds-color-background-accent);, never the hex.
5. Browser: the page looks the token up and paints #4F46E5. Flip the theme in Storybook and it reads the dark file instead.
6. Figma: the same token becomes the variable color/background/accent, an alias of color/brand/indigo/600, with the CSS name as its code syntax.

So change the token once, and every component that uses it changes, in code and, after a sync, in Figma. The JSON files are the one source: code and Figma are both generated from them.

The stack, tool by tool

A design system in code is a small chain of tools, not one. You do not need to write any of it to use the system. It helps to know what each piece is for.

How Figma and code stay in sync

Code is the source. Figma follows.

tokens/*.json ──npm run build:tokens──►  CSS variables ──►  React components ──►  Storybook
      │
      └── figma-mirror skill (Claude + Figma Console MCP) ──►  Figma variables, text styles, components
                                                                       │
                              npm run validate ◄── figma/manifest.json ┘   (fails if a name or value drifts)

• Names match on purpose. color/background/accent in Figma is --sds-color-background-accent in CSS, and a Figma layer Button · variant=primary resolves to <Button variant="primary"> through figma/manifest.json.
• Where Figma cannot express the CSS, it is written down in figma/GAPS.md instead of simplifying the CSS.
• Code Connect is not set up: it needs an Organization or Enterprise plan.

The two token tiers, in detail

Edit tokens/**/*.json, then run npm run build:tokens. The CSS is output.

Tier 1 is the raw material: --sds-color-brand-indigo-600, --sds-space-4. Nothing in a component may reference a tier-1 colour.

Tier 2 is the contract, organised into three categories — --sds-color-background-*, --sds-color-content-*, --sds-color-border-* — plus --sds-typography-heading-lg-font-size and friends. Components use only these. Theming means redefining tier 2, never touching tier 1 or components.

That separation is also what makes the Figma sync work. Tier-2 names map one-to-one to Figma variables, the light and dark files map to Figma variable modes, and the var() references map to Figma variable aliases.

Flip the theme in the Storybook toolbar to see it.

Breakpoints are emitted twice, to CSS and to TypeScript, because @media (min-width: var(--x)) is not valid CSS. Storybook viewports are generated from the TypeScript so they cannot drift from the tokens.

How I use this playground

This is the workflow I'm exploring with it, and it will keep changing while I build a course around it.

1. Work on the design branch. A branch is a parallel copy of the code. design is where prototypes live, so nothing you try there touches main (docs/branching.md).
2. See the system in Storybook. Every component, live and working, so you can see the codebase instead of reading it.
3. Keep Figma in step with the code. The Figma library is generated from this code through the Figma Console MCP (MCP is a standard plug that lets an AI tool read from another tool and work in it), following the figma-mirror skill in .claude/skills/. Variables, text styles and components use the same names and options as the code. Where Figma cannot express the CSS, it is written down in figma/GAPS.md rather than simplifying the CSS.
4. Prototype in Storybook with real components, then ask the agent to build the screen in Figma, where the library is already set up.
5. Explore in Figma. Move things by hand, put research and references next to it, and stay in the system or step out of it on purpose when the design needs something custom.
6. Bring it back to code. Ask the agent to rebuild the Figma screen from the real components. figma/manifest.json is how a Figma name like Button · variant=primary resolves back to <Button variant="primary">. The result is a real, clickable prototype in Storybook.
7. Hand off. An accepted prototype does not merge as it is. It gets built properly on a feature/* branch through a pull request, where developers run the tests and checks production code needs.

What has been tried and what has not. The Figma to Storybook direction has been done here once: the booking flow under Prototypes in Storybook started as a Figma prototype. Steps 6 and 7 have not been run inside a real product team yet, and there is no packaged skill for moving prototypes between Figma and Storybook. You ask for it in plain words.

Run it on your computer

If you have never run code before, you need exactly two things:

1. Claude Code — the desktop app.
2. Node.js — download the LTS build and run the
   installer. Node 22 or newer (this repo is developed on Node 24). To check
   whether you already have it, open Terminal and type node -v.

Then download this repository (green Code button → Download ZIP),
unzip it, open the folder in Claude Code, and say:

Show me Storybook

Claude installs the dependencies and starts it for you. To run the health
check on this system, say:

Run the design system inspection

The inspection skill already ships inside this repo — nothing to install.

Or, from the terminal

npm install
npm run storybook   # http://localhost:6001  <- the real workspace
npm run dev         # http://localhost:5173  <- scratch playground
npm run build       # tokens + typecheck + production build
npm run build:tokens # regenerate the CSS token layer from tokens/
npm run build-storybook
npm run check:contrast # colour contrast of every token pair

Open Getting started in the Storybook sidebar first.

What's where

tokens/                SOURCE OF TRUTH for design decisions (DTCG JSON)
  tier-1-definitions/  raw ramps and scales, themeless
  tier-2-usage/        roles, themed light/dark, plus composite text styles
scripts/
  build-tokens.mjs     Style Dictionary build: tokens/ -> src/tokens/
src/
  tokens/              GENERATED — do not edit
    primitives.css     from tier-1-definitions/
    semantic.css       from tier-2-usage/, light and dark blocks
    breakpoints.ts     breakpoints as values, for media queries and viewports
    base.css           imports the generated CSS, plus a minimal reset
  components/          42 components, one folder each
  foundations/         Colour, Typography, Space and shape, Motion
  patterns/            Settings page, Sign-up form, Data table, App shell
  index.ts             the public surface of the library
CLAUDE.md              the rails: ground before writing, then the rules
docs/
  architecture.md      why the repo is shaped this way
  conventions.md       how to add a component
  branching.md         the Gitflow variant, including the design branch

Going further

Adding a component

See docs/conventions.md. The short version:

1. If Base UI has a primitive, wrap it. Never rebuild focus management or ARIA.
2. Read the primitive's types and Base UI's own reference demo before writing. Not from memory.
3. Semantic tokens only. No raw hex, no primitive colours.
4. Style from Base UI's data- state attributes, not from React state.
5. A story per meaningful state, disabled included, and a clean a11y panel in both themes.

Branching

See docs/branching.md. main is the design system; changes land on it through feature/* pull requests. design exists as a long-lived branch for designers to prototype in real code, and accepted prototypes come back through a normal feature branch rather than merging design directly.

Roadmap

• Base UI + Storybook, token layer, 42 components, foundations and patterns
• On GitHub with the branch model documented
• Semantic scale tokens for space, radius and type, so density theming is possible without editing primitives
• Move tokens to a DTCG source of truth (tokens/**/*.json) with a generator emitting the CSS
• Sync tokens to Figma variables (mirrored 2026-09-10 through the Figma Console bridge)
• Code Connect mappings so Figma components point at these files
• Publish Storybook from main (GitHub Pages)
• Publish Storybook per branch, including design

Words you will hear

Not done / not checked

• Some colour pairs still fail contrast: npm run check:contrast lists them.
• Steps 6 and 7 of the workflow have not been run inside a real product team, and there is no packaged skill for moving prototypes between Figma and Storybook.
• Code Connect is not set up (Organization or Enterprise plan).
• Storybook is published from main only, not per branch.

Made by

Christine Vallaure, founder of moonlearning.io. I teach designers how Figma, code and AI fit together.

• The full course on this workflow is in the making: advanced, for designers with solid Figma skills. The newsletter is where I announce it.
• Live course on Maven: Build Scalable UI in Figma & AI: Design Systems Agents Can Actually Use. Four weeks, hybrid, all levels.
• Lightning session: Design Figma Files That Scale with AI, with materials at moonlearning.io/scaleAI.
• Self-paced Figma courses in the moonlearning store, and free sessions.
• For design teams: in-house AI workshops and consulting, through moonlearning.io.

Credits

The design system health check in .claude/skills/ds-inspection/ is the
ds-inspection skill by Brad Frost, from
https://github.com/bradfrost/skills, bundled here under the MIT licence so
that it runs with no setup. See
.claude/skills/ds-inspection/ATTRIBUTION.md.