Skip to main content

Governance

Design tokens are a public contract between design, themes, and components.

Governance protects three things:

  • stable semantic names
  • clear separation between core and semantic tokens
  • safe evolution of the system over time

Core rule​

Components consume semantic tokens only for meaning-bearing families.

Infrastructure-only families (e.g., breakpoints) do not define a semantic layer — their tokens are consumed directly by layout systems and applications. See Token Model — Invariant 7 for the architectural rationale.

Core tokens of meaning-bearing families are foundation values for themes and token composition. They are not the public API for components.

When to create a token​

Create a token only when all of the following are true:

  • the need cannot be expressed by an existing semantic token
  • the need is reusable across multiple components or patterns
  • the name fits the existing taxonomy

Prefer reuse before creation.

What may change​

Add a core token​

Add a core token when the system needs a new foundation value, such as a new color, size, radius, duration, or scale step.

Rules:

  • core tokens define values, not intent
  • adding a core token must not bypass the semantic layer
  • new core tokens should extend the existing system, not create a parallel vocabulary

Change a core token​

A core value may change when a theme or foundation needs to evolve.

Rules:

  • core value changes belong to theme or foundation evolution
  • keep the token meaning the same
  • evaluate impact on all semantic mappings and supported modes
  • modes must remap semantic references, not mutate core values

Add or change a semantic token​

A semantic token may be added or remapped when the system needs a new stable design intention.

Rules:

  • semantic tokens define intent, not raw value
  • semantic names are part of the public API
  • changing a semantic mapping is allowed only when meaning stays the same
  • changing a semantic token’s meaning is not allowed

If the intention changes, create a new token and deprecate the old one.

Contract checks​

Every token change must pass validation before merge. What is checked, where each rule lives, and how severity works are defined in Validation and Build. If a rule can be validated automatically, it should be validated automatically.

Deprecation​

Do not remove tokens without deprecation first.

When a token is no longer recommended:

  1. mark it as deprecated in the token source
  2. provide the replacement
  3. allow time for migration
  4. remove it in the next major version

Every deprecation records the deprecated token name, the replacement (or an explicit statement that none exists), the version that introduced the deprecation, and the target version for removal.

Deprecation is the preferred path for contract changes.

Versioning​

Tokens follow semantic versioning.

  • PATCH: documentation fixes, metadata fixes, or internal corrections that do not change the public token contract
  • MINOR: backward-compatible additions, new tokens, new aliases, or deprecations
  • MAJOR: removals, renames, meaning changes, or any other breaking contract change

Remapping a semantic token to a different core token while meaning is preserved is MINOR or PATCH — the name and its meaning are the contract, not the resolved value. A meaning change is never a remap: it is a new token plus deprecation of the old one.

Review​

Each proposal should answer:

  • what problem exists
  • why reuse is not enough
  • what token is being added, changed, or deprecated
  • what impact exists on themes and components

Design reviews semantic fit. Engineering reviews implementation and validation. Merge only when the contract remains coherent.

Principle​

Prefer a smaller vocabulary with stronger meaning.

A token system stays scalable by making reuse easy, naming stable, and change deliberate.