Perspective / UX engineering
Design systems as software infrastructure: token architecture, versioning and change control

A design system should make interface decisions repeatable while allowing products to evolve. Its technical foundation is a contract between design intent, component behaviour and the platforms that render it. Typed tokens and shared components can reduce duplication, but they also create dependencies that need ownership and controlled change. For an executive sponsor, the investment question is whether this infrastructure improves delivery across real products at a sustainable operating cost. A versioned architecture makes that proposition testable rather than aspirational.
The executive view
- A portable token format supports exchange; architecture, ownership and component behaviour still need explicit decisions.
- Separate primitive values, semantic roles and component decisions, then inspect their dependency graph.
- Fund validation, release management and consumer adoption alongside the initial design-system build.
Treat the system as a product with consumers
Begin by identifying the teams and applications expected to use the system. A public website, account portal and internal operations tool may share typography and interaction conventions while differing in density, accessibility needs and release cadence. Those differences should influence the system’s boundaries.
Create a consumer map showing which packages, tokens and components each application depends on. Assign responsibility for maintaining shared decisions and for adopting releases. Without adoption ownership, a central library can improve continuously while deployed products remain on incompatible copies.
Define success through delivery evidence: the proportion of important components using maintained primitives, time required to adopt a change and the frequency of defects introduced through inconsistent implementation. These measures need an initial baseline. Avoid promising a universal productivity percentage before the organisation has established where duplication and delay actually occur.
Separate the system's users from its beneficiaries. Product designers and engineers use the library, while customers and operations staff experience the resulting services. A high component-adoption percentage is not sufficient if a shared pattern makes a consequential task harder. Pair adoption measures with user-task evidence and defect trends. Inventory forks before estimating savings: two components with the same name may encode different validation, permissions or workflow assumptions. Consolidating them requires resolving those differences, not merely moving their source into one repository. The portfolio map should expose these contracts before the team announces a universal component.
Use a portable format without confusing it with architecture
The Design Tokens Community Group published its first stable specification in October 2025. Its Format Module defines an exchange format with typed values, groups and references. It is a Community Group specification, explicitly not a W3C Standard or Recommendation.
A common format can make data exchange more predictable, but it does not decide how an organisation names tokens, assigns ownership or designs components. Those remain architectural choices. Validate the exact capabilities of the tools in use rather than assuming that support for the format means identical treatment of every feature.
In an illustrative multi-product system, keep the source representation separate from generated platform outputs. Design tools and application builds should consume controlled transformations from the same release. Generated files need traceability to their source version, so a visual discrepancy can be investigated without guessing which export produced it.
Validate round trips through the actual tools. Export a small reference fixture, resolve it through the transformation pipeline and compare generated outputs with expected values. Include aliases, composite typography, dimensions and a deliberately unsupported feature. Record whether each tool preserves metadata or silently discards it. A format that supports a feature cannot compensate for a consumer that interprets it differently. Keep transformation configuration versioned with the token source. Reproducible outputs make supplier changes and tool upgrades reviewable, reducing reliance on one person's undocumented export sequence.
Design primitive, semantic and component token layers
A primitive token stores a reusable value. A semantic token describes an intended role, such as primary text or a critical action surface. A component token can then express a decision specific to a maintained component. The layers should help explain a dependency, rather than multiply names for every value.
An illustrative model might use these relationships:
| Layer | Example role | Change implication |
|---|---|---|
| Primitive | Neutral colour step | Potential impact across many semantic roles |
| Semantic | Text on a standard surface | Contract shared by several components |
| Component | Destructive action focus ring | Narrow behaviour with a defined state |
Document where an alias is allowed and who owns its meaning. Renaming a semantic key can be a breaking change even when its current value remains identical. Conversely, a primitive value change may alter many screens without changing any key. Review both structural and perceptual consequences.
Avoid using a semantic token as a disguised colour name. A token called text.primary should express a role across supported surfaces, whereas blue.500 is a primitive choice. If primary text must change for a dark surface, the consuming component should depend on the role and receive the appropriate resolved value. Keep state contracts equally explicit: an error border and a keyboard-focus indicator may currently share a colour but serve different purposes. Aliasing them without a defensible relationship can couple future changes that should remain independent. A dependency graph should explain intent, not just reuse identical numbers.
Model themes and states as explicit dimensions
Themes should describe supported combinations, not an uncontrolled collection of overrides. Define which dimensions the system actually needs: light and dark presentation, product identity, interface density or a specific supported accessibility preference. Do not assume every dimension can combine safely with every other one.
Create a supported-configuration matrix and identify the component states that must work in each configuration. Buttons have focus, disabled and loading states; forms have validation and completion states. A theme that works for a static sample can fail when content wraps or an interaction changes its surface.
Keep variant selection deterministic. The same inputs should produce the same resolved values in a design preview and a production build. When an application requires an exception, record whether it belongs in the shared system or remains a product-specific decision. This protects the core from becoming a catalogue of unrelated local preferences.
Control the multiplication of variants. Two brands, two colour modes and two density settings already create eight combinations before language, viewport and component state are considered. Some combinations may be unsupported, but that decision must be explicit and enforced. Choose representative fixtures with long labels, empty content, validation errors and realistic data tables. Themes should not conceal information or change the meaning of status colours. Give products an escape route for a genuinely distinct requirement, with a decision record, rather than encouraging undocumented overrides that gradually become an alternative design system.
Build a validation pipeline around real failure modes
A token pipeline should reject invalid types, unresolved references and circular dependencies before generating code. Add checks for naming rules and prohibited relationships that reflect the chosen architecture. The DTCG stable-release announcement describes cross-tool interoperability as a central objective; individual organisations still need to verify their transformation chain.
Next, test representative resolved configurations. Check that required semantic roles exist and that generated outputs retain expected units and value interpretation. Evaluate relevant colour pairs and component states, while recognising that token checks alone cannot establish interface accessibility.
Use a deliberately broken fixture to demonstrate each important gate. An unresolved alias should fail for a clear reason. A missing theme value should identify the affected consumers. Validation is more useful when its failure messages explain how to restore the contract than when it merely prevents a build.
A useful contrast gate evaluates known foreground and background pairs after aliases and opacity have resolved. The WCAG contrast explanation identifies the minimum text ratios and their exceptions; it does not imply that a token file alone can demonstrate conformance. Test actual rendered components, including focus, error text, disabled behaviour and content wrapping. Keyboard interaction and accessible naming are behavioural properties that tokens cannot encode completely. Make the validation report distinguish automated assertions, human review and untested configurations so an automated green result does not acquire a broader meaning than the evidence supports.
Release changes with a visible adoption path
Publish a change record that distinguishes additions, deprecations and behavioural changes. For each significant release, show the affected tokens and components, migration steps and known constraints. Versioning needs a documented policy; a number by itself does not tell consumers whether a change is safe.
An illustrative release process can generate an impact report from the dependency graph. A change to a surface token identifies the components and products that use it, then selects the necessary reviews. Product owners can plan adoption against their own release cycles while the central team maintains a bounded support window.
Avoid combining an infrastructure migration with an unrelated visual redesign unless there is a clear benefit. Keeping the changes reviewable makes defects easier to attribute and reduces the chance that an improvement in one layer conceals a regression in another. Maintain an explicit plan for retiring older versions rather than supporting them indefinitely.
Treat a package rollback and a data migration differently. Reverting a token package may restore a prior visual state, but products may already have changed markup or removed compatibility code. Document the full adoption sequence and retain a known compatible combination of tokens, components and product integration. A canary product can expose problems before the release reaches every application. Maintain a support policy for older consumers, and require an explicit exception when a product cannot upgrade. Otherwise a nominally shared system accumulates permanent parallel versions and loses the coordination benefit used to justify its funding.
Worked example: a shared colour change across eight products
Suppose eight products each maintain a locally copied action-button style. A proposed colour adjustment appears simple, but each team must locate its implementation, assess supported states, test the change and release it. If each local assessment takes four hours, the illustrative review effort is thirty-two hours before coordination and release overhead. This is a baseline assumption, not a promised design-system saving.
A shared semantic token and maintained button component can centralise part of that work. The system team might spend eight hours validating representative themes and states, while each product spends one hour checking its integration, totalling sixteen hours. The benefit disappears if products have incompatible forks or need extensive migration first. Include that adoption cost, ongoing maintenance and any extra review required for critical journeys.
The release should produce a resolved-value diff, affected-component list, representative visual evidence and an adoption record for each product. Test a long translated label, keyboard focus, a loading state and a button on a different surface. If a product's local override bypasses the token, the impact report should identify the exception rather than falsely counting it as covered. This makes the commercial case measurable: the system reduces repeated decision and verification effort where its contracts are actually used, while preserving evidence that consequential product behaviour still works.
Review supplier portability with an actual handover exercise. Give another team the source tokens, transformation configuration, component contracts and release instructions, then ask it to reproduce a reference build without access to private authoring knowledge. Document any manual steps or tool-specific losses. The exercise tests whether the organisation owns a maintainable system or merely has exported assets from a supplier's workflow. Portability is especially relevant in tendering: an open exchange format can reduce friction, but practical independence also requires understandable source, reproducible outputs and the contractual right to maintain them.
Fund the operating discipline as well as the initial library
The cost of a design system includes review, documentation, support, adoption and compatibility work. A library created as a one-off project can become a new source of fragmentation when no team can maintain it. Size the operating model to the number and diversity of consumers.
Start with repeated, consequential interface decisions. Prove that one shared component and its token dependencies can move through authoring, validation, release and adoption. Expand when that path works and when another shared decision has a clear owner and consumer.
The executive decision is about the level of coordination the product portfolio needs. Centralisation is valuable where consistency, accessibility and change costs matter across several applications. Local flexibility remains useful where requirements diverge. A sound architecture makes those boundaries explicit and provides enough evidence to decide which changes belong in shared infrastructure.
Make contribution rules practical. A team proposing a shared component should identify at least one real use case, state its accessibility and behaviour requirements, supply representative content and name a maintainer. The system team decides whether the requirement belongs in the core, an optional package or the product. Publish the reasoning so other teams do not repeatedly reopen the same question. Capacity for support and adoption should be visible in planning. When shared maintainers are fully allocated to feature delivery elsewhere, library maintenance has not become free; it has become an unacknowledged dependency risk.
Questions this raises
Does using the DTCG format create a complete design system?
No. It provides a format for exchanging design tokens. Component behaviour, accessibility evaluation, naming, governance and adoption remain implementation and operating responsibilities.
What is the value of semantic tokens?
They express intended roles rather than only raw values, allowing components to depend on a stable meaning. The benefit depends on coherent naming, controlled references and documented change policies.
Should every product use every shared component?
No. Shared components should cover genuinely repeated requirements. Explicit product boundaries and supported variants are more maintainable than forcing unrelated workflows into one increasingly complex component.
Sources & further reading
From thinking to doing