Skip to content
helixui

Figma — Token Studio

helixui’s design tokens are W3C DTCG JSON. That’s the same format Token Studio for Figma speaks natively — so designers can pull every helixui token into their Figma file without helixui shipping a Figma plugin first.

This page walks you through the import. It takes ~10 minutes once.

Prerequisites

  • A Figma account (free is fine).
  • The Tokens Studio plugin (install).
  • A clone of the helixui repo (for the JSON), or the npm-published @helixui/tokens package extracted somewhere readable.

Step 1 — get the token JSON

The token source lives at:

packages/tokens/tokens/core.json
packages/tokens/tokens/semantic.light.json
packages/tokens/tokens/semantic.dark.json

These are W3C DTCG-format files. The build pipeline resolves the aliases between them; Tokens Studio does that too.

If you installed @helixui/tokens from npm, the same files ship inside the package:

Terminal window
ls node_modules/@helixui/tokens/tokens/

Step 2 — open Tokens Studio in Figma

  1. Open your Figma file.
  2. Run the Tokens Studio plugin (Plugins → Tokens Studio).
  3. In the plugin’s settings, choose JSON file as the source.

Step 3 — import the helixui files

Tokens Studio supports multi-file imports as sets:

Set name (in Tokens Studio)helixui file
helixui/corepackages/tokens/tokens/core.json
helixui/semantic-lightpackages/tokens/tokens/semantic.light.json
helixui/semantic-darkpackages/tokens/tokens/semantic.dark.json

Activate the order from top to bottom — Tokens Studio resolves aliases left-to-right and the semantic files reference primitives in core.

For dark mode, swap semantic-light for semantic-dark in your theme set.

Step 4 — verify

Drop a color.brand.500 swatch on the canvas. The hex should match what var(--helixui-color-brand-500) resolves to in your app. (At the time of writing: #3b82f6 — but DNA can mutate this. See DNA.)

What you get

  • Every helixui color, spacing, radius, font, shadow, motion token as Figma styles + variables.
  • Live alias resolution — change a primitive in Tokens Studio, the cascading semantic token updates everywhere.
  • Two themes pre-wired — light/dark.

What you don’t get (yet)

  • A Figma component library. That’s coming in v0.2 (tracked at [#component-figma]).
  • Round-trip — if a designer edits tokens in Figma, those edits don’t flow back to the helixui repo automatically. Use Tokens Studio’s “push to GitHub” mode if you want that workflow.
  • DNA breeding in Figma. The DNA Lab is web-only; one direction is designers pick a DNA in the lab → that DNA’s tokens are committed → Tokens Studio syncs.

A note on naming

helixui tokens use dotted DTCG paths (color.brand.500). Figma styles use slash paths (color/brand/500). Tokens Studio translates between the two on import; no manual renaming needed.

DNA workflow

If your team uses a custom DNA (not wildtype), the imported tokens should reflect that DNA, not the defaults. Two options:

  1. Run the helixui token build under your DNA, then import the resulting JSON.
  2. Use the helixui MCP server (helixui.express_dna tool) to expand a shorthand into a full DESIGN.md + tokens, then import.

The second flow is documented in Integrations → Claude Code.

Troubleshooting

Aliases don’t resolve. Check that the core set is at the top of the Tokens Studio order, above semantic.

Tokens import but don’t appear as Figma variables. In Tokens Studio, run “Export → Variables.” Tokens Studio doesn’t auto-create Figma variables; you have to ask it to once.

Light/dark not switching. Set up two Token Sets, one with semantic-light active and one with semantic-dark. Bind each set to a Figma “mode” in the variables panel.