Design tokens are named values that represent reusable design decisions such as color, typography, spacing, motion, or elevation. Build a layered model from base values to semantic roles and component decisions, with platform transforms and governance. Tokens improve consistency and change management, but they do not guarantee usability, accessibility, or correct implementation.
Who this is for: Design-system designers and engineers aligning reusable visual and interaction decisions across products and platforms.
- Use semantic names that express purpose and preserve room for themes and platform differences.
- Define aliases, modes, component mappings, output formats, and deprecation behavior as one maintained system.
- Review token changes through affected components and workflows, including criterion-level accessibility checks.
Model layers and meaning
Inventory repeated design decisions and the contexts they serve before naming tokens. Base tokens may hold raw values, semantic tokens express roles such as surface-default, and component tokens capture a justified local decision. Not every measurement needs a token; indiscriminate abstraction makes the system harder to understand.
Name by purpose rather than appearance. A token called blue-500 cannot explain whether it represents a link, selection, or decorative accent. Semantic aliases allow themes and brands to change underlying values while components retain intent. Document when direct base-token use is permitted and why.
Define the technical contract
Choose a source format, identifier convention, value types, units, descriptions, modes, alias rules, and platform transformations. Decide how Figma variables and styles map to code without assuming both tools support identical concepts. Preserve stable identifiers where renaming could break consumers.
Specify outputs for web, native platforms, documentation, and tests. Color may need different serialization; typography may combine several properties; motion and shadows may not translate directly. Validate generated artifacts and prohibit silent fallbacks that make a missing token look like a valid design decision.
Connect tokens to components
Map semantic roles to component states such as default, hover, focus, selected, disabled, error, and high-contrast behavior. Test realistic combinations rather than reviewing a token table alone. A contrast-safe text pair can still be used incorrectly on another surface, and a spacing token cannot prove touch or target usability.
Use component tokens when shared semantic roles cannot express a stable need without repeated exceptions. Keep the chain inspectable so teams can trace a rendered value back to its purpose. Avoid deeply nested aliases that make impact analysis and debugging inaccessible to ordinary contributors.
Govern change and deprecation
Assign owners, proposal criteria, naming review, versioning, release notes, and consumer communication. Before changing a token, identify every affected theme, component, platform, and product. Visual regression and accessibility checks can reveal consequences, but human review still needs to assess meaning and workflow context.
Deprecate with a replacement, migration guide, deadline, and detection method. Do not reuse an old name for a different purpose because cached files and downstream packages may retain it. Track adoption and remove obsolete outputs only after supported consumers migrate. Record exceptions instead of creating private shadow tokens.
Refactor hypothetical status colors
Hypothetical products use raw green values directly for success text, icons, banners, and charts.
- Inventory each hypothetical use and separate status meaning from decorative or chart-series color.
- Create semantic foreground, surface, border, and icon roles with explicit theme aliases and intended contexts.
- Map component states, check actual color pairs under applicable WCAG criteria, and add non-color status cues.
- Deprecate direct raw-value use with replacement guidance, consumer detection, release notes, and implementation review.
Token definition record
Use one governed record for each reusable design decision.
- Identifier, layer, semantic purpose, description, value type, unit, base value, alias, and modes.
- Allowed contexts, prohibited contexts, components, states, themes, brands, and platform differences.
- Figma mapping, code output, transformation, package version, documentation, and validation tests.
- Accessibility considerations, actual pair checks, non-color cues, workflow review, and known limitations.
- Owner, proposal, approval, impact analysis, release, deprecation, replacement, migration, and removal.
Common mistakes
- Naming every token after its current visual value and losing the purpose needed for themes and change.
- Publishing Figma variables without a defined mapping, version, or validation path to product code.
- Treating token use as proof that every component is usable or conforms to accessibility requirements.
Try one
Should every spacing value in a product be replaced by a token? Explain a maintainable rule.
A strong answer tokens repeated decisions that carry shared meaning or need coordinated change, while allowing a documented local value when abstraction adds no useful contract. It considers component APIs, layout context, platform units, and migration cost. The goal is traceable consistency, not eliminating every literal number regardless of purpose or future maintenance.
Sources
- Figma variables guideOfficial Figma guidance on variables, collections, modes, and aliases.
- Figma styles guideOfficial Figma guidance on reusable color, text, effect, and layout-grid styles.