Design Systems in Code

A design system lives in two places: the designer's head and the engineer's code. The gap between them is where projects die. Components get built, then redesigned without telling code. Tokens change in Figma and ships still carry the old ones. Dark mode works in one place and not the other.

This module closes that gap. Not by adding layers of process (no Figma plugins, no design-to-code generators that hallucinate). By making the code speak design so clearly that when a designer glances at it, they recognize their own system. And when an engineer builds on it, they know exactly what lever to pull.

The checkpoint: one source of truth for tokens, components that have a minimal deliberate API, and a sync that works both ways without you thinking about it.

What are tokens?

Tokens are decisions written down. "This is brand blue." "This is our spacer unit." "This is the size of body text." They live in Figma as Variables, in CSS as custom properties, in TypeScript as a theme object. Same meaning, three languages.

Most teams pick one place to define them and sync the others. That's already better than none. But the real win is bidirectional sync, when a designer tweaks a color in Figma, it lands in CSS. When an engineer realizes "we need a smaller spacing unit," the token appears in Figma's token panel.

Token categories

Think of tokens in four bands:

Primitives, the raw materials. Colors (hex or oklch), font sizes, weights, spacing units. These are immutable, boring, intentional.

Semantic tokens, the rules. "This is the color of a button." "This is the text we use for labels." They reference primitives and carry intent.

Component tokens, the specifics. "This button uses this text style and this background." Used internally in component CSS, rarely leaked to consumers.

Alias tokens, shortcuts. Map semantic tokens to multiple names for different contexts. "Call it --color-text-primary when it's body text, but in a form input, call the same token --color-input-text."

The secret: semantic and alias tokens change between themes. Primitives never do. A dark theme doesn't invent new blues, it points the same --color-primary name to a different primitive blue.

Figma Variables: Where Tokens Live

In Figma, Variables are the design system's source of truth. They live in two collections: Primitives and Semantic.

Primitives collection:

• Color group: blue-50, blue-100, ... blue-950
• Space group: xs, sm, md, lg, xl
• Typography group: size-xs, size-sm, ... weight-bold

Semantic collection:

• Color group: primary, primary-hover, success, text-primary, background, etc.
• Space group: inline-xs, inline-sm, inline, inline-lg
• Type group: body, body-weight, label, label-weight

Each semantic color variable points to a primitive. In the Primitives mode, it resolves light. In the Dark mode, it resolves dark. That's it, the same variable name works everywhere.

Figma's right side: Variables panel → Select variable → Add mode. Two modes: Light, Dark. Each semantic color gets two primitives assigned.

Exporting Tokens: Figma → Code

You need a tool to walk Figma's Variables API and write CSS. Don't hand-code this. Options:

1. 1Figma's official token exporter (legacy, deprecated)
2. 2Style Dictionary, industry standard, transforms tokens to any format
3. 3Parity Check (paid, Figma plugin), syncs both directions, tells you when code drifts from design
4. 4Token Studio (Figma plugin, paid), manages tokens inside Figma, exports to JSON
5. 5Hand-roll a script, hit Figma's REST API, walk variables, emit CSS

For this module, assume you're using Style Dictionary. It reads a JSON file of tokens and emits CSS, TypeScript, Tailwind theme, etc.

Token file (JSON):

Style Dictionary config:

Run style-dictionary build. You get tokens.css with all the custom properties and tokens.ts with an object you can import.

The hardest part: maintaining sync. When a designer changes Figma variables, how does that JSON file get updated? Options:

• Export manually, designer runs Figma plugin, copies JSON, pastes into repo
• Sync script, CI job hits Figma API on a schedule, commits if changed
• Parity Check plugin, paid, does the sync for you, both directions

For a teaching module, assume manual export with a script that validates the JSON before commit. Real workflows vary wildly.

Dark mode is not a special case. It's the same tokens pointing to different primitives. The code doesn't change, the values change.

CSS Custom Properties Approach

Define all tokens on :root. In dark mode, redefine the semantic ones.

Components use the semantic names only:

The component never knows which theme is active. It always reads --color-primary. The CSS layer changes what --color-primary means.

Tailwind Approach

If you're using Tailwind, tokens become theme values:

Then in components:

Tailwind emits bg-[var(--color-primary)]. When the theme changes (via CSS custom properties), Tailwind doesn't re-run, the custom properties update and the browser repaints. It's instant.

TypeScript Theme Objects

Some teams use TypeScript theme objects in addition to or instead of CSS custom properties. Useful if your component library is pure React/TypeScript without Tailwind.

The downside: you're not leveraging CSS custom properties or Tailwind's optimization. Every theme change requires a full context update and re-render. For most apps, this is fine. For large component trees or frequent theme toggles, prefer CSS custom properties.

The Best Approach for This Module

Use CSS custom properties + Tailwind. It's the sweet spot:

• Designers recognize custom properties (they match Figma variable names)
• Tailwind gives engineers a DX win (utility classes)
• Themes update instantly (CSS layer, no JS re-render)
• Both light and dark work without special logic

A component's props are its contract. Well-designed props mean:

• A designer can use it without reading source code
• An engineer can extend it without breaking existing uses
• It scales to new variants without prop explosion

The Minimal API Principle

Every prop should earn its place. If a prop is only used once in your codebase, it shouldn't exist. If two props are always used together, merge them.

Bad:

Every prop is a escape hatch. The component has no shape, it's a factory for infinite shapes.

Good:

The component has a distinct shape. size controls both padding and font. variant controls both color and border. isLoading and disabled are clear states, not arbitrary toggles.

Variant-Based Design (CVA / Class Variance Authority)

Group related props into a variant prop using CVA (if you're using TypeScript and want type safety) or just an object of class maps.

CVA is TypeScript-first. It gives you autocomplete on variant names and type-checks that you're using valid combinations. But it's not required. You can do the same thing with a class map:

Less safe (no type checking), but less boilerplate. Choose based on team preference.

Boolean Props Are Traps

Avoid boolean props for style. They're ambiguous:

Use enums or literal unions instead:

The only boolean props that make sense are states that affect accessibility or behavior: disabled, required, checked, isSelected.

These components form the scaffold. Every design system needs them. Build them once, build them well, and everything else is a variation.

1. Button

2. Card

3. Input

4. Badge

5. Modal

Each component:

• Has a clear variant set (no prop explosion)
• Uses tokens for all spacing, color, type
• Includes subcomponents where appropriate (Card.Header, etc.)
• Works with TypeScript and Tailwind or CVA
• Is accessible (labels, ARIA, focus states)

The real constraint: when a designer changes a token in Figma, how does that update land in code? And when an engineer adds a token in code, how does it appear in Figma?

The Sync Pipeline (Code → Figma)

1. 1Engineer adds a token to the source JSON file.
2. 2npm run tokens:build runs Style Dictionary.
3. 3New CSS custom property appears in tokens.css.
4. 4New variable appears in tokens.ts.
5. 5A GitHub action or CI step hits Figma's REST API and writes the new variable to the Figma file.

Figma API call (pseudo-code):

This is overkill for a teaching module. Real sync:

• Designer exports tokens from Figma (plugin or manual)
• Engineer reviews the JSON diff
• Merge, commit, deploy
• CI builds tokens, emits CSS, deploys website

The Manual Approach (Good Enough)

For a design system that doesn't change hourly:

1. 1Create a Figma Variables export step. Designer or engineer runs a Figma plugin, downloads JSON.
2. 2Commit the JSON. Review like code.
3. 3CI builds and deploys. npm run tokens:build → CSS → site.

Figma plugins that export variables:

• Token Studio, full-featured, paid
• Figma Tokens, lightweight, free
• Parity Check, detects drift (designer: did you actually update this?)

Detecting Drift

A simple check: hash the current tokens JSON, compare to deployed CSS. If they mismatch, fail the build.

Add to CI: npm run check:tokens before deploy. If the JSON and CSS hashes don't match, deployment blocks until tokens are rebuilt.

A design system is a conversation. Code is half the conversation; documentation is the other half.

Storybook (If You're Using It)

Storybook lets designers and engineers see components in isolation, with controls to test variants.

Run npm run storybook. Open browser. Designers and engineers both see:

• Component rendered with the variant applied
• Figma links (if you've integrated Figma plugin)
• Code snippets
• Accessibility notes

Markdown Docs (Minimal)

Write one README.md per component. One page. Keep it tight.

<Button variant="primary" // 'primary' | 'secondary' | 'ghost' | 'danger' size="md" // 'sm' | 'md' | 'lg' isLoading={false} // Shows spinner, disables click disabled={false} // Disabled state onClick={handler} // Click handler />

• Buttons are not links. Use <Link> for navigation.
• Loading state sets disabled={true} internally.
• Focus ring appears on keyboard focus (Tailwind: focus:ring-2).
• Icon-only buttons require aria-label.

{ "semantic": { "color": { "primary": { "value": "{primitive.color.blue.500}", "type": "color", "deprecated": true, "replacedBy": "primary-main" }, "primary-main": { "value": "{primitive.color.blue.500}", "type": "color" } } } }

export function Select({ options, value, onChange }) { const [isOpen, setIsOpen] = useState(false);

return ( <div> <Input value={value} onClick={() => setIsOpen(!isOpen)} readOnly /> {isOpen && ( <Card className="absolute top-full mt-xs"> {options.map((opt) => ( <button key={opt.value} onClick={() => { onChange(opt.value); setIsOpen(false); }} className="px-space-md py-space-sm hover:bg-color-surface w-full text-left" > {opt.label} </button> ))} </Card> )} </div> ); }

import figma from "@figma/code-connect"; import Button from "./Button";

figma.connect(Button, "https://figma.com/design/FILE_ID?node-id=1234", { props: { variant: figma.enum("Variant"), size: figma.enum("Size"), isLoading: figma.boolean("Loading"), children: figma.string("Label"), }, example: (props) => <Button {...props}>Click</Button>, });