Design tokens explained: build a design system that scales.

Design tokens are named, platform-agnostic values for every visual decision in your product: color, spacing, typography, radius, elevation and motion. They replace hard-coded values with a shared vocabulary that designers use in Figma and developers use in code. Done well, a token layer is the difference between a design system that scales across a brand, a product and a marketing site, and one that quietly drifts apart with every release.

At RAIN Design Studio in Casablanca, a token file is one of the first artifacts we produce on any project with more than one surface. Here is how we think about it.

What are design tokens?

A design token is a key and a value, plus a little metadata. color.action.primary = #1d4ed8 is a token. So is space.4 = 16px or motion.duration.fast = 150ms.

What makes tokens useful is not the value, it is the name. A name carries intent. When a developer writes var(--color-action-primary) instead of a hex code, they are encoding a decision (“this is the primary action color”), not a coincidence (“this happens to be blue”).

Tokens typically cover:

• Color: brand, neutrals, text, surfaces, borders, states (success, warning, danger)
• Spacing and sizing: a fixed scale, usually based on 4 or 8
• Typography: font families, sizes, line heights, weights, letter spacing
• Shape: border radii and stroke widths
• Elevation: shadows and layering (z-index)
• Motion: durations and easing curves

Why hard-coded values break a growing brand

Hard-coded values work until the second product ships. Then the same “brand blue” exists as four slightly different hex codes, spacing is 15px in one component and 16px in another, and a dark-mode request turns into a multi-sprint audit.

The symptoms are familiar:

• Marketing pages and the app look like they belong to two different companies
• A rebrand means a find-and-replace across several repositories
• Designers redline the same values in every handoff
• Accessibility fixes (for example, raising text contrast) have to be made one component at a time

A design system built on tokens fixes this at the root: one change, propagated everywhere.

The three tiers of design tokens

Most mature systems organize tokens in three tiers. Each tier references the one below it.

The rule we follow: components consume semantic or component tokens, never primitives. That single rule is what lets you swap a theme, add dark mode or onboard a sub-brand without touching component code.

Component tokens are optional. Many teams stop at two tiers and only add component tokens when a component genuinely needs to diverge.

Naming tokens so they survive a rebrand

Names outlive values. A token called color.blue becomes a lie the day the brand moves to green. Good names describe role, not appearance.

A practical naming pattern is category.role.variant.state:

• color.text.default, color.text.muted, color.text.inverse
• color.surface.raised, color.surface.sunken
• color.border.focus
• space.inset.md, space.stack.lg

A few habits that help:

1. Keep names lowercase and dot-separated in the source, and let the build step convert them (to --color-text-muted in CSS, for example).
2. Avoid encoding values in names (space.16 is fine in primitives, never in semantics).
3. Document every semantic token with one sentence of intended use.

From Figma to code: one source of truth

The workflow that holds up best keeps a single source of truth and generates everything else.

1. Define in Figma variables. Primitives in one collection, semantic tokens in another, with modes for light and dark.
2. Export to JSON. The JSON file lives in the repository and is versioned like code. The W3C Design Tokens Community Group has been working on a shared, tool-neutral JSON format for exactly this purpose, which makes it easier to move tokens between design tools and build pipelines.
3. Transform at build time. A small script or a token transformer compiles the JSON into CSS custom properties, a Tailwind CSS theme, and, where needed, native formats for mobile.
4. Consume everywhere. Astro marketing pages, Vue 3 or React app components and email templates all read the same compiled output.

Tailwind CSS v4 makes this especially clean, because its theme is defined in CSS and exposed as custom properties. On RIVER ERP, our Laravel 13 and Vue 3 business platform with 154 screens, light and dark themes and a set of user-selectable accent palettes are switched with a single data attribute, and a unit test checks the theme colors against WCAG AA contrast. The same tokens serve the web, desktop and mobile builds.

Theming, dark mode and multi-brand

Because semantic tokens point to primitives, theming becomes a mapping exercise rather than a redesign:

• Dark mode: color.surface.default points to neutral.50 in light mode and neutral.950 in dark mode. Components do not change.
• Accessibility: contrast is checked at the semantic layer, once, for every mode. On the MField & Data Insight site we shipped light and dark themes designed to meet WCAG AA contrast.
• Multi-brand: a sub-brand gets its own primitive palette and semantic mapping, while sharing every component.

Governance: keeping a design system that scales

Tokens decay without ownership. Light governance is enough for most teams:

• One owner (usually the senior designer on the project) approves new semantic tokens
• Changes go through pull requests, with a visual diff where possible
• Deprecate before deleting: keep an old token as an alias for one release cycle
• Audit quarterly for unused tokens and one-off values that slipped into components

Common mistakes to avoid

• Creating hundreds of tokens up front instead of extracting them from real screens
• Letting components reference primitives directly
• Naming by color or size rather than role
• Keeping tokens only in Figma, so code drifts silently
• Treating tokens as a design-only concern; engineers must co-own the pipeline

Build your token layer with RAIN

A token layer is a modest investment that keeps a brand coherent for years. RAIN Design Studio sets up tokens, Figma libraries and coded components as part of our UI/UX design work, with one senior designer per project and every deliverable signed off by a human lead. Fixed-scope projects start at $10,000, or we can fold it into a Growth or Scale retainer. Book a free 15-minute call and tell us how many surfaces your brand needs to cover.