All foundations
THE FOUNDATION

Design tokens

The anatomy of every design decision.

Version 1

About design tokens

Design tokens are the named decisions behind every interface. They connect approved values, semantic themes, and component recipes into a language people and agents can share.

The decisions inside a component

A button combines several approved decisions. Color communicates intent, shape identifies the control, and typography keeps the action readable.

Create project
Sizeux.prototype.global.typography.size.16
Backgroundux.prototype.theme.color.background.primary
Foregroundux.prototype.theme.color.foreground.on_primary
Shapeux.prototype.theme.border.radius.small
Weightux.prototype.global.typography.weight.600
Line height150% · documented, variable pending
One component, six connected decisionsAn original illustration of the six token callouts in the V1 source. Typography property names are aligned with the captured token collection.

A global value, given a name

Global tokens are the approved vocabulary of the system. A semantic theme alias can reference a global value; a dedicated abstraction such as Typography can consume primitives deliberately.

#165896ux.prototype.global.color.blue.60
From raw value to named primitiveA descriptive name connects an approved color value to its palette and ramp level.

Design decisions, made visible

Tokens give repeatable decisions a name: color, spacing, typography, borders, and elevation. A global value records the approved vocabulary. A theme alias gives that value a purpose. Components consume that purpose so their appearance can adapt without rewriting their behavior.

From value to experience
GLOBAL VALUEux.prototype.global.color.blue.60#165896
SEMANTIC ROLEux.prototype.theme.color.background.primaryPrimary action
COMPONENTCreate projectBackground + foreground + shape
An original token relationship illustration based on the foundation’s global → theme → component examples.

How to read global tokens

Global tokens hold static, approved values. Theme tokens normally consume them; a dedicated abstraction such as Typography can also consume primitives deliberately. Domains include color, typography, space, border, screen, and the documented shadow and opacity conventions.

Global token anatomy
ux.prototype1. NamespaceYour design system’s name.
global2. HierarchyAn approved primitive value.
color3. DomainThe design decision being described.
blue.604. Property / modifierThe attribute, role, level, or intent.
Names carry meaning from left to right. The selected workspace supplies the namespace; aliases retain the same hierarchy.

How to read theme tokens

Theme tokens describe use, including background, foreground, outline, intent, size, and elevation. The same name can point to different global values in light and dark themes. Changing a system’s name changes its token namespace and exported alias paths together.

Theme token anatomy
ux.prototype1. NamespaceYour design system’s name.
theme2. HierarchyA purpose that adapts with the theme.
color3. DomainThe design decision being described.
background.primary4. Property / modifierThe attribute, role, level, or intent.
Names carry meaning from left to right. The selected workspace supplies the namespace; aliases retain the same hierarchy.
ux.prototype.theme.color.background.primary
→ {ux.prototype.global.color.blue.60}

CSS
--ux-prototype-theme-color-background-primary:
  var(--ux-prototype-global-color-blue-60);

A component is a collection of decisions

Anatomy of a review dialog
OVERLAY SURFACE

Review your theme

Check the proposed changes before publishing.

CancelConfirm
  • Surfaceux.prototype.theme.color.background.overlay
  • Shapeux.prototype.theme.border.radius.large
  • Contentux.prototype.theme.color.foreground.neutral_high
  • Actionux.prototype.theme.color.background.primary
  • Titleux.prototype.theme.color.foreground.neutral_high
  • Dividerux.prototype.theme.color.outline.neutral_low
  • Supporting copyux.prototype.theme.color.foreground.neutral_medium
  • Secondary actionux.prototype.theme.color.foreground.neutral_high
  • Action labelux.prototype.theme.color.foreground.on_primary
  • ElevationHigh / down style observed: 0 16px 32px rgb(0 0 0 / .10). Token-table reconciliation remains pending.
A new schematic inspired by the source’s Save files example. This specimen explains token relationships and is not an interactive dialog.

Apply the complete recipe. A background token alone cannot define a dialog: include readable foregrounds, boundaries, shape, elevation, spacing, focus behavior, and accessible semantics.

A dependable agent contract

An agent should discover the selected system, resolve aliases for the target theme, select documented components, and return a reviewable proposal. Unknown tokens, circular aliases, unresolved shadow recipes, and unverified combinations must be reported rather than silently substituted. Namespace changes must preserve the semantic hierarchy and source provenance.