Design tokens connect visual decisions in Figma to CSS and other generated outputs. UI Foundations organises them into layers so patterns can adapt to different brands and schemes without changing their markup.
Token layers
One decision, a clear role.
Each layer adds context or intent. Patterns use semantic roles to stay adaptable across brands and schemes.
- 01CoreReusable raw values
- 02AppearanceBrand · Scheme · Scale
- 03SemanticsAction / Surface / Hover
- 04PatternsButton hover background
Token layers
The system separates four responsibilities so a token name can explain what it means without also encoding a specific brand or theme.
| Responsibility | What it controls | Example |
|---|---|---|
| Core | Reusable primitives such as palette steps, spacing, radii, and type values | --size-spacing-200 |
| Appearance / Brand | Brand-specific visual identity | Brand A, Brand B, Brand C |
| Appearance / Scheme | Light/dark realization | Light, Dark |
| Appearance / Scale | Fluid or scalar endpoints | Min, Max |
| Semantics | Stable UI purpose, independent of brand and scheme | Color/Action/Surface/Hover |
| Patterns | Where a semantic role is used in a UI pattern | Button/…/Background/Hover |
A useful mental model is: Core provides values, Appearance resolves context, Semantics names intent, and Patterns apply that intent.
Surface, Content, and Foreground
- Surface is a filled region.
- Content is text or an icon placed on that Surface.
- Foreground is standalone action/status text, icon, stroke, or outline on a surrounding surface.
Surface and Content are paired per interaction state so accessibility can be verified for the actual state rather than inferred from a default color.
Naming convention
New semantic color roles use Color/<Purpose>/<Role>/<State> (or
Color/<Role>/<State> for the default canvas pair).
Pattern names follow <Family>/<Variant?>/<Part?>/<Property>/<State?>.
Interaction state is always the final segment. UIF keeps Active as the
existing Runtime name for the pressed interaction; do not introduce
Pressed as a second vocabulary.
Applying tokens
Use the CSS custom properties listed in the token reference. Prefer semantic roles for application UI and pattern tokens for a specific control.
See Theming for brand, scheme, and scoped overrides.
Rules
- Use semantic roles for patterns so their intent stays consistent across brands and schemes.
- Brand, Scheme, and Scale belong to Appearance, not to semantic token names.
- Never hardcode color values in pattern CSS.
- Use
var(--...)for token-driven visual properties.
Reference
- All Tokens — complete tabular index of all generated tokens