Using tokens in design

Design tokens in Figma are stored as variables — the same source of truth that drives the CSS custom properties in code. Using variables in Figma instead of raw hex codes or hardcoded values ensures that what you design maps directly to what gets built.

Finding tokens in Figma

Tokens are organized into the same collections you see in this documentation:

• Primitives — raw color swatches, type scale, base spacing values
• Mode — semantic light/dark tokens (fg, bg, border)
• Brand — brand palette values
• Layout — padding, gap, and screen size tokens
• Component — component-scoped tokens (button, border, spacing)
• Platform — desktop and native platform values

To apply a variable to a fill, stroke, or text property in Figma, click the swatch or value field and select from the variable picker. Variables are grouped by collection and category.

Naming alignment

Token names in Figma variables match token names in code exactly. For example:

Figma variable	CSS variable
light/fg/primary	--light-fg-primary
color/action/primary	--token-color-action-primary
padding/md	--padding-md

This alignment means a developer reading the Figma file can find the same token name in the codebase without any translation.

Modes and theming

The Mode collection contains light and dark variants. In Figma, you can switch a frame or component between light and dark mode using the variable mode toggle. This lets you preview both themes without duplicating your designs.

When handing off to development, the semantic token name (e.g. light/fg/primary) is what matters — not the underlying primitive color it resolves to.

Keeping tokens in sync

Tokens flow from Figma → JSON → CSS in the following steps:

1. A designer updates or adds a variable in Figma.
2. The Figma token export is run and the resulting files are committed to the repo under src/data/tokens/.
3. The npm run convert-tokens script converts those exports to the JSON format the docs and CSS use.
4. src/css/design-tokens.css is regenerated, publishing the updated CSS variables to the live site.

If you notice a mismatch between a Figma variable value and what appears in code, the most likely cause is that the export hasn't been re-run since the Figma change.

Best practices

• Always apply variables to fills, strokes, text, and effects rather than raw values — this ensures your work responds correctly to theme switches.
• Use semantic tokens (Mode collection) for UI decisions like "this is a primary foreground color." Use primitive tokens only when building the token system itself.
• If a variable you need doesn't exist, raise it with the design system team rather than using a raw value — adding the token once benefits the whole system.