WHAT THIS CHANGES
Three shifts to carry into the next design review.
- 01PRIMITIVE
Store the possible values.
- 02SEMANTIC
Name the product decision.
- 03CONTRACT
Let components consume intent.
A token called blue-500 is a spreadsheet cell with better marketing.
Most teams start token work by renaming hex codes. The result is a tidy palette that still leaks raw implementation into every component. When the brand changes, dark mode arrives, or a high-contrast theme is required, blue-500 has no idea what job it was doing.
A useful token preserves intent. ‘Action primary background’ can become a different colour across brands and modes while keeping the same product meaning. The abstraction is not the value. The abstraction is the decision the value currently expresses.
Use three layers, and do not let components skip one.
The cleanest architecture I know has three layers: primitives, semantic decisions, and component contracts. Primitives hold possible values. Semantic tokens assign meaning. Component tokens express the local contract only when a component genuinely needs a narrower decision.
The rule that matters is consumption. Product components should not reach directly into primitives. A button consumes an action role, not a shade. A status message consumes a feedback role, not ‘red’. This one constraint makes theming, accessibility, and future migration dramatically cheaper.
- 01PRIMITIVE
A possible value—never a component dependency.
- 02SEMANTIC
The durable product decision.
- 03COMPONENT
A narrow local contract only when needed.
Modes should resolve decisions, not duplicate files.
Light, dark, brand, density, platform, and high-contrast variants are contexts. Treating each as a separate token file creates copies that drift. A resolver should take one semantic decision and return the correct value for the active contexts.
The stable Design Tokens specification published in 2025 gives the industry a vendor-neutral format for expressing and resolving this kind of information across tools. That matters. But interoperability does not rescue weak semantics. A perfectly portable token called grey-600 is still the wrong abstraction.
- 01EXPLICIT AXES
Model mode, brand, density, and platform as contexts.
- 02ALIASES
Let one decision inherit from another.
- 03COMBINATIONS
Test intersecting contexts, not isolated modes.
- 04PAIRED ROLES
Evaluate foreground and background contrast together.
Components need behaviour contracts, not anatomy diagrams.
A component page showing a button’s padding, radius, and variants documents its body but not its judgment. The valuable knowledge is when to use it, when not to use it, how it behaves with long content, what happens while waiting, and how failure recovers.
Document the states teams usually improvise: loading, empty, error, partial permission, destructive confirmation, keyboard focus, and reduced motion. Include content limits and examples of misuse. A design system earns trust by helping teams make decisions, not by displaying pristine inventory.
- 01CONTENT
Long, empty, and constrained.
- 02SYSTEM
Loading, error, and partial permission.
- 03CONTROL
Keyboard focus and destructive confirmation.
- 04MOTION
Reduced choreography without lost orientation.
Treat token changes like API changes.
Changing a widely used token can alter thousands of surfaces at once. Yet many teams manage it like a Figma tidy-up. Mature systems need ownership, versioning, deprecation, migration notes, and visual regression across every supported mode and state.
Also track escape hatches. Overrides are not automatically bad; they are evidence. A repeated override says the system is missing a legitimate decision. A one-off override may be product specificity. Review them monthly, promote the patterns that repeat, and delete the ones that no longer earn their complexity.
- 01OWNER
One accountable owner per semantic family.
- 02VERSION
Publish the reason for breaking change.
- 03MIGRATION
Ship the path before removing the old name.
- 04REGRESSION
Verify every supported mode and state.
AI makes implicit design systems visibly inadequate.
Human designers fill gaps using history, taste, and hallway context. AI does not. If your system only stores components and values, generated work will be consistently plausible and subtly wrong. It needs the reasoning: product principles, constraints, examples, failure patterns, and quality thresholds.
This is the new test of a design system. Can a capable newcomer—or an agent—make a strong product decision without asking the original author what they meant? If not, the missing asset is not another component. It is explicit judgment.
- 01PrinciplesWhat good means here.
- 02ConstraintsWhat must remain true.
- 03ExamplesPatterns and anti-patterns.
- 04ThresholdsWhen the work is ready.
EXPLICIT JUDGMENT MAKES QUALITY REPEATABLE
THE ONE-LINE TESTThe purpose of a token is not to store a value. It is to preserve a decision when the value changes.
SOURCES / FURTHER READING