Skip to content

Color

The color system is structured across three layers of abstraction: primitive, semantic and component tokens. This layered approach allows color decisions to scale across brands, themes and components while keeping usage consistent and predictable.

Design explains the layers and what each semantic group is for; Tokens lists every one of them per brand and scheme; Scheme covers the mechanism that flips a whole subtree between the neutral and contrast palettes; Accessibility states which colors may be paired with which. Component tokens are defined and documented within each individual component, where their context and usage are more explicit.

DesignTokensSchemeAccessibility

Primitive tokens name the raw values, semantic tokens name the intent. Design and build against the semantic layer — it is the contract that survives a brand or theme change; the primitives underneath it do not.

Every token this tab describes is listed, per brand and per scheme, on the Tokens tab.

Primitive

Section titled “Primitive”

Core tokens define the raw color values of the system.

They represent the foundational palette and do not carry any usage meaning on their own.

Core tokens should never be used directly in layouts or components.

They exist to:

  • Centralise color values
  • Enable theming and brand customisation
  • Serve as the source of truth for semantic and component tokens

Semantic Tokens

Section titled “Semantic Tokens”

Semantic tokens map core colors to intent and purpose. They describe why a color exists, not what it looks like.

Semantic tokens are the primary interface between design and development and should be used in all layouts and components unless a component-specific token is required.

Semantic color tokens are organised into functional groups based on usage and context. The groups below are ordered the way they layer — a page background carries a component surface, which carries a filled element on top of it.

Background

Surface

Background

Section titled “Background”

Background semantic tokens define colors used for page-level surfaces only. They establish the overall visual context of a page and should not be used for component backgrounds.

Variants (default, subtle, muted) represent different levels of visual weight to create hierarchy between page sections.

Surface

Section titled “Surface”

Surface tokens define solid background colors for component-level surfaces such as cards, panels, drawers or modals.

Surface-dim tokens are opacity-based variants of surface colors, used to introduce layering, depth or soft separation while preserving the underlying color context.

Fill

Section titled “Fill”

Fill tokens are used for filled UI elements such as buttons, chips, badges and decorative component areas.

They are grouped by intent:

  • Neutral and contrast
  • Brand (primary, secondary, model-specific)
  • Feedback (success, error, warning, info)

Variants (emphasis, default, subtle, muted) control visual hierarchy.

Fill-dim tokens apply opacity to fill colors and should be used whenever reduced emphasis or transparency is required, instead of applying custom opacity values.

Foreground

Section titled “Foreground”

Foreground tokens define colors for text and icons.

They are separated by:

  • Background context (neutral, contrast)
  • Brand usage (primary on-neutral, primary on-contrast)
  • Feedback intent (success, error, warning, info)

Hierarchy variants help maintain readability and accessibility across different surfaces. Which foreground family goes with which surface is the pairing contract — get that wrong and the token values are irrelevant.

Border

Section titled “Border”

Border tokens define outlines and separators for components.

They follow the same semantic structure as fill and foreground, enabling consistent expression of hierarchy, brand emphasis and feedback.

Border-dim tokens provide opacity-based borders to soften visual separation without removing structural boundaries.

Gradient

Section titled “Gradient”

Lexus specs its copper accent as a gradient rather than a flat colour, for both fills and strokes. Design tokens can only carry flat values, so the stops are hand-authored in the styleguide and applied by the gradient utilities — which is also where the @supports fallback and the opt-out hooks are documented. The stops themselves are specced here.

Each pairing is one gradient in two geometries: linear, left to right when rested, sliding to radial, inside to outside on hover.

Layer Scheme From To
Background Neutral copper/400 copper/600
Background Contrast copper/200 copper/500
Border Neutral copper/400 copper/700
Border Contrast copper/200 copper/500

Every other brand has no bespoke stops. Rather than fall back to a flat swatch, the utilities derive a two-stop gradient from the brand’s secondary accent — Toyota red, for instance — so a gradient element stays on-brand everywhere.

Usage

Section titled “Usage”
  • Never use core tokens directly in UI.
  • Use semantic tokens based on intent, not appearance.
  • Use background tokens only for page-level surfaces.
  • Use dim variants instead of custom opacity values.
  • Do not repurpose feedback tokens for non-feedback use cases.
  • Component tokens should only be defined when semantic tokens are not expressive enough.