Design tokens

Design tokens are the building blocks of the UAL design system. They turn design decisions into a shared language that works across disciplines, tools, and technologies.

Overview

Design tokens are named values that represent design decisions. Rather than hardcoding a hex code, a pixel value, or a font family directly into your work, you reference a token. The token carries the decision. When that decision changes, every instance updates with it.

This approach makes the design system more effective in four ways:

Consistency: everyone uses the same named values, so interfaces look and feel unified.

Speed: designers and developers speak the same language, which removes translation errors and speeds up handoffs.

Maintainability: update a value once, and every instance updates with it.

Platform-agnostic: the same set of decisions can generate code for different technologies.

Token anatomy

Every design token has three essential parts.

Type is the category the token belongs to. Examples include colour, spacing, or typography. This helps organise tokens and ensures they are used in the right context.

Name is how you reference the token. Names follow consistent patterns that tell you what the token does. This makes tokens easier to find and use correctly.

Value is what gets applied when you use the token. A value can be fixed, like a hex code or pixel number, or it can be a reference to another token, like {white}. Referencing other tokens is what allows changes to cascade through the system.

A design token broken into its three parts. The type defines its category, the name describes its role, and the value is what it resolves to.

Token structure

Design tokens are organised in layers. Each layer adds meaning, moving from raw values to names that describe purpose and context.

Primitive tokens

Primitive tokens are the raw values at the foundation. They describe what something is, not what it is for. Examples include yellow-400, spacing-md, and font-size-step-5. At this level, the name tells you the category and position, not the purpose.

Semantic tokens

Semantic tokens reference primitives and describe a role or purpose. Instead of using yellow-400, you use surface-primary.

The name tells you what the token is for, not what it looks like. In typography, a semantic token like H1-loud bundles multiple primitive properties into a composite definition that describes a specific text style.

Semantic tokens also enable theming: the same token name can point to different primitives depending on the active theme. See the Colour page for how theming works in practice.

Component-specific tokens

Component-specific tokens describe values unique to a particular component. They are self-contained, meaning changes to them do not affect anything outside that component. Component-specific tokens are mainly used for colour, where individual components need unique values for interaction states such as hover, pressed, and disabled.

The same colour value flows through the token layers.  A raw hex value becomes a primitive, which is referenced by semantic and component-specific tokens.

Not every token type uses all three layers. Colour uses the full structure. Typography expresses semantics through composite definitions. Spacing operates at the primitive level, providing a consistent scale. The layered approach is one we apply where it adds value, not a rigid framework that every token type must follow.

Token types

The UAL design system currently uses three token types: colour, spacing, and typography. These cover the essential aspects of visual design and ensure consistency across all digital products.

Each type expresses the token structure differently, as described above. See each foundation page for the full detail on how tokens work within that domain: Colour, Spacing, Typography.

As the system evolves, additional token types may be introduced.

Naming conventions

UAL design tokens follow consistent naming patterns. Each part of the name tells you something specific, making tokens easier to find, understand, and use correctly.

Primitive tokens follow the pattern [category]-[scale] e.g. yellow-400

Semantic tokens follow the pattern [category]-[role] e.g. surface-primary

Component-specific tokens follow the pattern [component]-[category]-[role]-[state] e.g. button-surface-primary-hover

Applying tokens

Connect your Figma file to the UAL Figma UI Kit. This creates a live link between your designs and the system. When tokens update, your designs update automatically.

Applying tokens in Figma by connecting to the UAL Figma UI Kit library and selecting tokens from the variables panel.

Apply tokens from the start: Use tokens instead of hardcoded values when you begin designing. This ensures consistency and saves time later.

Document new tokens: When creating new components that require a new set of component-specific tokens, document which tokens you have created and make sure they are being added to the system.

Do not override tokens locally: Resist adjusting token values for edge cases in your project. For example, do not change a font size from 17px to 14px just for your feature. If a token does not work, it needs system-level refinement.

The same colour value flows through the token layers. A raw hex value becomes a primitive, which is referenced by semantic and component-specific tokens.