In short
Implement design tokens as CSS custom properties (or a build step generating them from a shared JSON source), organized in the same primitive-to-semantic-to-component layers used in the design tool, so a single value change in one place propagates automatically through every consuming component.
Why implementation is where tokens either work or don't
A well-designed token system in a design tool has no effect on a shipped product until it's actually implemented in code that components reference — the design-side work and the code-side implementation are two separate efforts that need to stay connected, or the design tool's tokens become documentation nobody actually uses.
The simplest implementation: CSS custom properties
For most web projects, defining tokens as CSS custom properties is the most direct implementation:
``css :root { --color-text-primary: #151715; --color-surface-primary: #ffffff; --space-4: 1rem; --font-size-base: 1rem; } ``
Components reference these variables (color: var(--color-text-primary)) rather than hardcoded values, so a single change to the variable definition propagates everywhere it's used.
Maintaining the token layers in code
Mirror the same primitive-to-semantic-to-component layering used in the design tool: primitive scale values, semantic tokens that reference them, and component-specific tokens that reference the semantic layer. This keeps the code implementation conceptually aligned with how designers reason about the system, rather than flattening everything into one undifferentiated list of variables.
Generating code tokens from a single source of truth
For larger systems, maintaining tokens by hand in both a design tool and separately in code risks drift between the two. A build step that generates CSS variables (or equivalent for other platforms) from a single shared JSON or YAML source of truth — sometimes exported directly from the design tool — keeps both layers mechanically synchronized rather than relying on manual updates staying consistent.
Supporting multiple themes
For dark mode or other theme variations, define theme-specific semantic token values under a scoping selector or data attribute ([data-theme="dark"]), while keeping the same semantic variable names across themes — this is what makes dark mode a mapping exercise rather than a parallel implementation.
Type-safety for non-CSS platforms
For JavaScript-heavy codebases or non-web platforms, tokens are often also generated as typed constants (a TypeScript object, for instance) alongside the CSS variables, so token usage gets autocomplete and type-checking in application code, catching typos or references to non-existent tokens at build time rather than silently failing at runtime.
Keeping designers and engineers using the same names
The single most valuable property of a token implementation is that designers and engineers refer to the exact same token names when discussing a value — "use space-4" should mean the identical thing in a design file and in code. Any drift here reintroduces the ambiguity tokens are meant to eliminate.
A practical adoption path
Start by defining primitive and semantic tokens as CSS variables for your most-used values (color, spacing, type), migrate existing hardcoded values to reference them incrementally rather than in one disruptive pass, and add a generation step from a shared source once the manual approach starts showing drift between design and code.
Common questions
What's the simplest way to implement design tokens in a web project?
CSS custom properties (variables) referenced by components instead of hardcoded values — this is usually sufficient for small to medium projects without needing a generation build step.
How do I keep design-tool tokens and code tokens from drifting apart?
For larger systems, generate both from a single shared source of truth (often exported from the design tool) via a build step, rather than maintaining each manually and hoping they stay in sync.
Do I need typed token constants for a JavaScript project?
It's a valuable addition for larger codebases — typed constants give autocomplete and catch invalid token references at build time, though CSS variables alone are sufficient for smaller projects.
