Design tokens FAQ: 8 questions, short answers

Design tokens are names for design decisions, such as the secondary text colour or a card's corner radius, shared by Figma and code. This page answers the eight questions I get asked most, from how tokens differ from CSS variables to when you need dedicated tooling. Every answer uses this site's real tokens.

If the three layers (raw, alias, semantic) are new to you, start with what are design tokens, which walks through each layer with code.

Are design tokens just renamed CSS variables?

Not quite. A CSS variable is the storage mechanism. A token is the convention about which layer a value belongs to and who is allowed to reference it.

All three lines below are CSS variables on this site. Only the last one is used in components:

--gray-700: #595959;                    /* raw */
--neutral-700: var(--gray-700);          /* alias */
--muted-foreground: var(--neutral-700);  /* semantic */

Two projects can both use CSS variables. The one with a layering convention has a token system. The other has a list of constants.

Do you need Style Dictionary or Tokens Studio?

Not at the scale of one site or a small product. All three layers can live in one disciplined CSS file, which is how app/globals.css works here.

Dedicated tooling pays off when tokens must sync from one source to several platforms. Style Dictionary reads token files and outputs CSS, Swift, Kotlin and more. Its docs say it has had first-class support for the W3C Design Tokens Community Group format since version 4, with full support for the newest 2025.10 spec still in progress for version 5.

Does changing a raw token update components immediately?

Yes, and that is the point of having layers. Change --brand-500 once and every element using bg-primary updates, with no component edits.

The condition is that components never reference the raw layer. This site leaves the raw layer out of the Tailwind theme on purpose, so a bg-gray-600 class does not exist. To use grey you go through bg-muted or text-muted-foreground.

Should you name tokens by colour or by role?

It depends on the layer. Raw tokens are named by colour and step: --gray-700, --brand-500. Semantic tokens are named by role: --background, --muted-foreground, --destructive.

A colour name at the semantic layer goes stale at the first colour change. A token called --pink-button after a rebrand to blue is a small lie living in your codebase. This site uses shadcn's semantic names plus three of its own: subtle-foreground, primary-text and footer.

How do you handle dark mode with tokens?

The tidiest approach I know is numbering the neutral ramp by distance from the background, as Radix does. neutral-50 is always the background and neutral-950 is always the strongest text. Dark mode then only overrides raw values inside .dark, and the alias and semantic layers stay untouched.

In Figma, the equivalent is a collection with Light and Dark modes, where each variable holds one value per mode. The finer points are in the dark mode FAQ and the Radix colour scale.

Is there a standard token file format?

Yes. The W3C Design Tokens Community Group published the Design Tokens Format Module 2025.10 on 28 October 2025. Files use the .tokens or .tokens.json extension. Each token has a $value, usually a $type, and references other tokens with curly braces:

{
  "primary": {
    "$type": "color",
    "$value": "{brand.500}"
  }
}

You only need this format when a tool will read it. If your tokens serve a single website, a CSS file does the job.

How do you keep Figma and code tokens in sync?

Three habits do most of the work:

1. Use the same name in both places. A Figma variable called muted-foreground maps to the CSS variable --muted-foreground.
2. Fill in Code syntax for each variable. Figma lets you record a code name for Web, Android and iOS. For Web, include the var() wrapper so Dev Mode shows the variable name instead of a hex value.
3. Let an AI agent read both sides. I use Figma MCP so Claude Code can read variables from the Figma file and check them against globals.css. The setup is in Figma MCP with Claude Code.

The reason each token exists lives in neither Figma nor CSS. I keep it in DESIGN.md, covered in what is DESIGN.md.

How many tokens does a system need?

Fewer than you expect. This site has exactly three surface values (#ffffff background, #f8f8f8 grey band, #efefef hairline) and four text tiers. The project rules say it plainly: if a design needs a fourth surface value, the layout is wrong.

Token counts grow fastest when every new screen is allowed to request a new colour. Before adding a token, check whether an existing one can do the job. If it can, use it. If it cannot, ask whether the layout should change first.

Sources

• Design Tokens Format Module 2025.10, W3C Design Tokens Community Group. Accessed 2026-10-04.
• Figma: Overview of variables, collections, and modes. Accessed 2026-10-04.
• Figma Plugin API: setVariableCodeSyntax.
• Tailwind CSS: Theme variables. Accessed 2026-10-04.
• Style Dictionary: DTCG support. Accessed 2026-10-04.

I'm Hai Le, a UI/UX designer who builds design systems and wrote the code for this site. To see tokens applied in a real product, read the Joyme case study, or find out more about me.