Design Token

Origin & evolution

Design tokens were named at Salesforce in 2014. Jina Anne and Jon Levine were building the Lightning Design System🧰Design SystemDesign SystemThe root design system entityView reference → and hit a structural problem: a single design decision, made once, was being recreated by hand across iOS, Android, and web, in different languages, drifting out of sync each time. They gave the abstraction a name, the design token, a stored variable that holds a decision and distributes it everywhere. Jina Anne has been firm that a token is a methodology, not just a variable; reducing it to a CSS custom property misses the point in the same way that calling responsive design "just media queries" does.

The idea spread through tooling and shared vocabulary. In 2017 Nathan Curtis published Tokens in Design Systems, which gave the community a way to talk about token tiers and naming. Around the same time Danny Banks open-sourced Style Dictionary, a build step that takes one set of tokens and transforms it into whatever format a platform needs, Swift, XML, CSS, JSON. That broke the manual-copy problem the Salesforce team had started from.

Standardisation followed. The Design Tokens Community Group, a W3C group of designers, developers, and tool makers, set out to define a vendor-neutral file format so tokens could move between Figma, Style Dictionary, and any other tool. Its Format Module reached its first stable version in October 2025, settling on a JSON shape with typed values and composite tokens. The live debate now is layering: how many tiers (primitive📋PrimitiveFoundationsA canonical reusable building block defined by a specificationView reference →, semantic, component) a system needs before the indirection costs more than it saves.

How it works in practice

A fintech team ships a web app, an iOS app, and a marketing site. Their brand blue is defined once as a primitive token, colour.blue.500 mapping to #1d4ed8. A semantic token, colour.action.primary, points at it, and the primary button's background binds to the semantic token, never the raw hex. When the brand refreshes and blue shifts two shades darker, one primitive value changes. Style Dictionary regenerates the platform files, and every primary button across three codebases updates in the next build. No engineer searches for hex strings. The semantic layer also lets dark mode swap colour.action.primary to a brighter blue for contrast without redefining the button at all.

Design token vs. its neighbours

• Design component🧱Design ComponentDesign SystemA reusable UI componentView reference → is the assembled, reusable unit (a button, a card) that has structure and behaviour. A token is a single value the component consumes. One button reads a dozen tokens; one token feeds hundreds of components. The graph models this as design_component_styled_by_design_tokenDesign Componentstyled byDesign Tokenhierarchy.
• Brand colour🌈Brand ColourBrand IdentityA brand colour definitionView reference → is the brand-level intention ("our blue"), a marketing and identity decision. A token is the technical implementation of that intention, the addressable variable engineering binds to. The edge design_token_reflects_brand_colourDesign TokenreflectsBrand Colourcross-domain keeps the intention and its implementation linked but distinct.
• Style guide documents decisions for humans to read. A token encodes the same decision for machines to consume at build time. A style guide tells a designer the heading is 32px; a token makes that 32px the literal source the heading renders from.

In the graph

In the Unified Product Graph, a design token sits in the Experience, Design & Brand region's design-system domain, owned by its parent system through design_system_defines_design_tokenDesign SystemdefinesDesign Tokenhierarchy. It connects downward to the components that consume it (design_component_styled_by_design_tokenDesign Componentstyled byDesign Tokenhierarchy) and sideways to the brand intention it encodes (design_token_reflects_brand_colourDesign TokenreflectsBrand Colourcross-domain), and it can be exposed as a service via design_token_tokenised_as_serviceDesign Tokentokenised asServicecross-domain when a platform publishes its tokens for other products to consume. That structure makes the token's reach queryable: change one value and the graph shows every component, surface, and downstream product the change touches, which is the audit the manual-copy era could never produce.

The alias tier got its own edge at 0.39.0. A token system of any size runs in tiers, primitives that hold raw values, semantic tokens that alias them, components that consume the semantic layer, and the graph could hold the ends but not the middle, so the chain from colour.action.primary back to colour.blue.500 lived in descriptions. design_token_derives_from_design_token records it. The classification is causal rather than semantic, which is the substantive part: the alias's value is computed from the primitive's, so the dependency⛓️DependencyTeam & OrganisationA cross-team or system dependencyView reference → is real, directional, and breaks downward. Two questions that used to need a script become traversals, which primitives a given component ultimately depends on, and which primitives nothing derives from and can be retired.

The edge is authorable across product graphs, which matters because the primitive tier is routinely published as its own package with its own graph while the semantic tier ships alongside the component library. That reach is granted by name rather than inherited: design_token🪙Design TokenDesign SystemA design token (colour, spacing, typography) is not a portfolio🧸PortfolioPortfolioA grouping of products by strategic axisView reference →-shared type, so the edge is admitted individually into the curated cross-product set, on the same footing as surface_governed_by_design_guidelineSurfacegoverned byDesign Guidelinecross-domain.

The category property changed in the same release🚢ReleaseProduct SpecificationA shipped version of the productView reference →. It previously offered five values, color, spacing, typography, radius, motion, which is a design system's own vocabulary rather than the DTCG format's, and a measured estate of 163 primitives had shadow, dimension and opacity tokens with nowhere to land. 0.39.0 extends the enum with the DTCG $type vocabulary, dimension, fontFamily, fontWeight, duration, cubicBezier, number, shadow, gradient, border, transition, strokeStyle, opacity, and keeps all five original values. Both spellings are accepted, so a DTCG export maps across without translation and a system that speaks UPG's original five never has to retranslate at the boundary.

The mapping is not one-to-one, and the places it is not are the ones worth knowing. A radius token is a DTCG dimension. A motion token is usually a duration or a cubicBezier. A typography token is a composite over fontFamily, fontWeight and a dimension. Only color and spacing are spelled the same in both vocabularies. Choosing one spelling per system and holding to it matters more than choosing the right one, because a set that mixes them cannot be grouped by category in a single query. From 0.39.0 validate_graph reports a property_enum_drift class, so a value outside the enum is visible rather than merely undocumented.