Interface Lab
Login
Back to knowledge
Design Systems Page Patterns

Design System Token Settings

Token settings pages must show semantics, aliases, modes, affected components, version diffs, and release risk together, not only color and number inputs.

tokenssettingsdesign-systemversioninggovernance

Design Principle

Design tokens are design decisions that move across design tools, code platforms, and component libraries. A settings page does not only edit values; it explains how a value is referenced, how it changes by mode, and which components and versions it affects.

Large Theory

A token settings page sits at a high-risk point in design-system governance: one color, spacing, or type change can affect hundreds of components, brand themes, dark mode, mobile layout, and accessibility contrast. A healthy token UI separates primitive, alias, semantic, component token, mode, and platform output so users understand dependencies before editing and publishing.

Small Points

  1. Token values need role names and source: color.brand.primary, color.action.background.default, and button.primary.background are different layers and should not be flattened into one table.
  2. Variable modes must be visible: light/dark, brand, density, locale, platform, and responsive mode can give one token different values.
  3. Impact scope appears before saving: affected components, states, pages, themes, generated CSS/JSON/iOS/Android output, and screenshot previews.
  4. Version governance includes draft, review, approved, released, deprecated, and rollback. Each release needs changelog, owner, and reason.
  5. Contrast, non-text contrast, focus ring, status colors, and chart colors need automated checks; a valid hex value is not enough.
  6. Token editors expose alias graphs and cycle/missing-reference errors so component tokens do not point to missing or overly specific values.

Design Judgment

A token settings page is production-ready only when designers, engineers, and reviewers can answer what the token means, which modes change it, which components are affected, whether contrast breaks, and how to roll back before saving.

Implementation Notes

Create a token change model: tokenId, tokenType, tier(primitive/alias/semantic/component), mode, currentValue, proposedValue, references, affectedComponents, contrastChecks, platformOutputs, owner, status, version, changeReason, and rollbackTarget. The UI can filter by collection/tier/mode on the left, edit value and semantic notes in the middle, and show component previews, diff, contrast results, and release checklist on the right. Generate a review packet before submit and block direct publishing for high-risk tokens.

Counterexamples/Risks

Only providing a color picker; hiding dark-mode values in another file; changing primary without knowing which buttons, links, and charts change; saving without version; semantic tokens using brand colors directly so states cannot scale; deleting a token and letting components silently fall back to black.

Case Study

Style Dictionary describes design tokens as platform-agnostic design decisions and can export them to iOS, Android, CSS, JS, HTML, and other targets. The DTCG format specification aims to let tools exchange token files. Figma variables documentation explains that variables and modes let one design system support contexts such as light and dark themes. The reusable lesson is that token settings pages must serve design semantics, mode editing, and cross-platform output together rather than merely editing CSS variable text.

Source Links

Style Dictionary Design Tokens: https://styledictionary.com/info/tokens/ Style Dictionary DTCG: https://styledictionary.com/info/dtcg/ DTCG Format Module: https://www.designtokens.org/TR/2025.10/format/ Figma Variables Guide: https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma Figma Variable Modes: https://help.figma.com/hc/en-us/articles/15343816063383-Modes-for-variables

Agent Directive

Before generating token settings pages, output token tier, mode, alias graph, affected components, contrast checks, platform outputs, version diff, and rollback; do not generate only color/number inputs.