Design tokens 101: turn your brand kit into code that scales
Why every modern brand needs design tokens, how to structure them, and how to sync values between Figma, Tailwind, and your codebase without endless drift.
A design token is a named variable for a brand decision — 'color.primary.500 = #3b82f6' instead of a raw hex value scattered across a hundred Figma files and CSS modules. Tokens turn a brand kit from a PDF into a single source of truth that designers and engineers both consume.
Without tokens, every brand refresh becomes a manual search-and-replace across files nobody fully owns. With tokens, one change in the source file propagates to Figma, Tailwind, iOS, Android, and email templates within minutes. This is the difference between brands that scale and brands that fragment.
This guide covers the W3C Design Tokens format, a sensible naming convention, and a workflow using Figma Variables + Style Dictionary + Tailwind v4 that works for teams of any size.
- A finalized brand kit (colors, type scale, spacing, radii)
- Figma (Pro or higher for Variables)
- A codebase using CSS variables or Tailwind v4
What problem do tokens actually solve?
Without tokens, brand values are duplicated everywhere: Figma fill styles, Tailwind config, iOS Color assets, Android XML, email HTML, marketing site CSS, and the dashboard's styled-components. A 'small' brand color update touches 7+ files and inevitably misses one.
Tokens centralize these values in a single machine-readable file (typically JSON) that gets compiled into platform-specific outputs. Designers edit the source in Figma Variables; a small build step exports the JSON; tools like Style Dictionary or Tokens Studio compile it into CSS variables, Tailwind config, Swift, Kotlin, and anywhere else you need them.
Naming conventions that survive contact with reality
Use a 3-tier structure: category.concept.variant. For example, color.primary.500, color.text.muted, space.4, radius.sm. The first tier groups (color, space, radius, font), the second identifies the purpose, the third the specific value.
Separate primitive tokens from semantic tokens. Primitives are raw values (color.blue.500 = #3b82f6). Semantics map primitives to roles (color.action.primary = {color.blue.500}). UI code uses semantics; primitives can change without rewriting components. This is the secret to painless rebrands.
Add a third layer — component tokens — for complex systems: button.primary.background = {color.action.primary}. This sounds excessive until your dark mode launch, when you'll thank yourself.
The toolchain in 2026
Figma Variables (built-in since 2024) is the standard source for design teams. Tokens Studio (Figma plugin) is the power-user alternative with multi-mode support and Git sync.
Style Dictionary (Amazon, open source) is the most popular compiler — JSON in, CSS/Swift/Kotlin/JS out. It's a build script you run in CI on every token change.
Tailwind v4 reads CSS variables natively via the @theme directive, which means your tokens become Tailwind utility classes (bg-primary-500, text-muted) without a separate config file. This is the cleanest setup for modern web teams.
Step by step
- 01
List every brand value worth tokenizing
Colors (primitive + semantic), spacing scale, border radii, type scale, line heights, shadows, and motion durations. Skip one-offs that only appear in a single component.
- 02
Define primitives first
Build the raw scale: color.blue.50 through color.blue.950, space.0 through space.32, radius.none through radius.full. No semantics yet — just the raw materials.
- 03
Layer semantic tokens on top
Map roles to primitives: color.background.default = {color.neutral.0}, color.text.primary = {color.neutral.900}, color.border.subtle = {color.neutral.200}. Components only ever reference semantic tokens.
- 04
Set up Figma Variables to match
In Figma, create variable collections that mirror your token files. Use modes for light/dark and (optionally) for brand variants. Now designers pick from semantic tokens too, not raw colors.
Tip — Name Figma variables identically to your code tokens (color/text/primary). Future-you doing a token audit will be grateful. - 05
Export to a JSON file as the source of truth
Use the Figma API or Tokens Studio plugin to export variables to a tokens.json file committed to your repo. This file is what humans edit (via Figma) and what build tools consume.
- 06
Compile to platform outputs
Run Style Dictionary in CI to compile tokens.json into: CSS variables for the web (loaded via Tailwind v4's @theme), Swift extensions for iOS, Kotlin objects for Android, and JSON for email templates. One source, many outputs.
- 07
Document token usage in your brand guidelines
Replace 'use #3b82f6 for primary actions' with 'use color.action.primary'. Now your guidelines reference the same names as your code, and there's no translation layer to drift.
Watch out — If guidelines still reference raw hex values after you ship tokens, drift will return within 6 months.
Key takeaways
- Tokens turn brand values into a single source of truth across design and code.
- Use a primitives → semantics → components layering for painless rebrands and dark mode.
- Figma Variables + Style Dictionary + Tailwind v4 is the cleanest 2026 toolchain.
- Reference tokens in your brand guidelines so design, code, and docs stay in sync.
Frequently asked questions
+Do tokens make sense for a small brand?
Even a one-person brand benefits from semantic tokens because dark mode and rebrands become trivial. Skip the compiler step at first — just use CSS variables — and add Style Dictionary when you ship a second platform.
+Figma Variables or Tokens Studio?
Variables is built-in, free, and sufficient for 90% of teams. Tokens Studio adds Git sync, multi-mode math, and JSON import/export — worth it for design systems teams shipping to 3+ platforms.
We design logos, brand kits, type systems and color palettes end-to-end.
Book a branding call