Token Usage Guidelines

Do’s

• Always use tokens according to their semantic meaning, not their raw value.
• Define new tokens when needed instead of overwriting existing ones with a different meaning.

Don’ts

• Do not change the meaning or core definition of tokens. → Example: outline is reserved for functional boundaries, not for decorative lines.
• Do not use hardcoded raw values (colors, spacing, sizes, etc.) instead of tokens.

---

Additional Notes
All tokens in the system are semantically defined – their meaning is stable and must not be changed. “Repurposed” tokens cause misunderstandings within the team, broken consistency, weakened accessibility.

---

Typography

Typography tokens define the semantic role of text styles in the application, beyond their visual size or weight. They describe how strongly a text element should stand out in the visual hierarchy — from highly emphasized titles down to subtle supporting text.

By default, the title-* tokens are mapped to native HTML heading elements (h1–h6) to provide a consistent baseline. However, typography tokens (title, headline, body) are not identical to HTML headings — the mapping is an implementation detail, while the tokens themselves remain design-semantic typography roles.

Do’s

• Apply headlines primarily in content-heavy views.
• Use body for standard text and body-subtle for secondary information.

Don’ts

• Do not omit token role levels when the content structure requires them.
• Do not overuse title-large.
• Do not apply branding typography for regular content.

---

Additional Notes
Typography tokens are not inherently tied to HTML headings (<h1>, <h2>, …). Their default mapping ensures consistency, but the tokens themselves remain design-semantic typography roles.

Semantics and visual hierarchy usually align, but they do not always need to be identical. Deviations should be rare and intentional to avoid confusion and accessibility issues. If layout or branding requires different emphasis (e.g., section title appearing larger than a pane title), do it intentionally and keep token roles intact.

---

Token	Purpose	Recommended Usage
title-large	Maximum emphasis	Strongest visual title style for short, prominent text (e.g., primary pane titles).
title-medium	High emphasis	Secondary title style for shorter text elements, providing strong but less dominant emphasis.
title-small	Medium emphasis	Tertiary title style for concise supporting text, often in nested or smaller structures.
title-smallest (custom)	Compact emphasis	Very compact title style for short labels or titles in limited space.
headline-large	Strong emphasis (Content)	Marks entry points in content-heavy contexts (e.g., articles, pages). Still short-form text.
headline-medium	Medium emphasis (Content)	Structures content with concise section headers (e.g., chapters, larger sections).
headline-small	Lower emphasis (Content)	Subsections in text-heavy layouts. Short supporting headers below larger structures.
body	Default body text	Long-form text for reading: descriptions, paragraphs, labels, and general content.
body-subtle	Reduced emphasis	Lower-priority body text such as hints, meta-information, or supplementary labels.
app-name (custom)	Branding emphasis	Reserved for brand-related naming (e.g., app name in top bar).
(Label Tokens – planned)	Functional emphasis	Reserved for short, functional texts such as button labels, form field labels, or UI tags. Not covered by current tokens.

Titles

Title · Large

Maximum emphasis

The quick brown fox jumps over

Title · Medium

High emphasis

The quick brown fox jumps over

Title · Small

Medium emphasis

The quick brown fox jumps over

Title · Smallest (custom)

Compact emphasis

The quick brown fox jumps over

Headlines

Headline · Large

Strong emphasis (Content)

The quick brown fox jumps over

Headline · Medium

Medium emphasis (Content)

The quick brown fox jumps over

Headline · Small

Lower emphasis (Content)

The quick brown fox jumps over

Body

Body

Default body text

The quick brown fox jumps over

Body · Subtle

Reduced emphasis

The quick brown fox jumps over

Branding

App Name (custom)

Branding emphasis

The quick brown fox jumps over

Interaction & Status (Color)

These tokens combine branding, key interactions, and status communication. They differ from surfaces in that they are not intended for neutral surfaces, but rather for signaling and action orientation.

Do’s

• Use primary for central interactions and success, danger, and warning for clear status communication.
• Always ensure sufficient contrast with the respective on-* colors.
• Apply container variants (*-container) for subtle surfaces.
• Use brand sparingly and deliberately for identity.

Don’ts

• Do not mix branding and functional colors within the same element.
• Do not use on-brand for content that requires high readability.
• Do not apply colors inconsistently for the same state.

---

Additional Notes

• All colors are semantically defined – what matters is their meaning, not the raw color value.
• Accessibility is mandatory: on-* colors ensure contrast and legibility.
• The brand / on-brand tokens form an exception: they are not required to meet accessibility standards. They have to be used with care.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
brand		Pure brand color	Derived directly from the branding. Typically reserved for logos or identity elements.
on-brand	Aa	Content on brand surfaces	For text and icons displayed on brand-colored surfaces.
primary		Central system color	Used for interactive accents, central surfaces, borders, and text.
on-primary	Aa	Content on primary surfaces	Text/icons on primary-colored surfaces with sufficient contrast.
primary-container		Subdued primary surface	Background for interactive components with primary context.
on-primary-container	Aa	Content on primary containers	Text/icons on primary-container surfaces with good readability.
success		Positive/confirmation color	Signals success or positive feedback.
on-success	Aa	Content on success surfaces	Text/icons on success surfaces with clear contrast.
success-container		Subdued success surface	Softer positive background.
on-success-container	Aa	Content on success containers	Text/icons on subdued success backgrounds.
danger		Error/destructive color	Marks errors or destructive actions.
on-danger	Aa	Content on danger surfaces	Text/icons on danger backgrounds with contrast.
danger-container		Subdued danger surface	Subtle error emphasis.
on-danger-container	Aa	Content on danger containers	Readable text/icons on subdued error contexts.
warning		Warning/notice color	Marks warnings or notices.
on-warning	Aa	Content on warning surfaces	Text/icons on warning surfaces.
warning-container		Subdued warning surface	Softer warning background.
on-warning-container	Aa	Content on warning containers	Readable text/icons on subdued warning.

Surfaces (Color)

Surface tokens define the neutral base layers of the application — the visual foundation for all structural and interactive elements. They serve as calm, unobtrusive backgrounds for main content areas and help to organize hierarchy through subtle tonal steps.

While Interaction & Status Colors convey meaning, surface colors stay intentionally neutral, ensuring that content and actions remain in focus.

Surfaces form the background for semantic layout areas such as panes, bars, and other containers as well.

Do’s

• Apply surface-app as the application background only.
• Use surface as the standard base layer for panes and main content regions.
• Use on-surface-subtle for secondary information (labels, meta info, hints).
• Use container levels to create depth and establish visual hierarchy.

Don’ts

• Do not apply high container levels to low-importance content.
• Avoid mixing multiple surface variants in a small area.
• Don’t use surface colors to express meaning or status.

---

Additional Notes

• surface-app is the outermost structural frame of the interface.
• surface defines the standard base layer for content regions that sit on top of surface-app.
• Surface containers (e.g., surface-container-low, surface-container-high) help to differentiate visual depth and build hierarchy across layout layers.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
surface		Neutral base surface	Default background for content and containers. Acts as a stable foundation for the UI, visually restrained to keep focus on content and interactions.
surface-container-lowest		Container level – lowest	Very close to surface, with minimal elevation. Suitable for large background areas that should feel calm and neutral.
surface-container-low		Container level – low	Slightly differentiated from surface. Provides subtle separation of areas without dominating the overall layout.
surface-container		Container level – medium	Default layer for most UI elements. Offers balanced elevation for content containers and interactive surfaces.
surface-container-high		Container level – high	Noticeably elevated above surface. Used to highlight important areas and bring them visually to the foreground.
surface-container-highest		Container level – highest	Foreground-near layer with maximum visual dominance. Supports UI elements requiring top-level attention, such as active states or modal contexts.
surface-app		Application background	Base surface of the application. All other surfaces (panes, containers, bars) are layered on top. Neutral in appearance to avoid competing with content.
on-surface	Aa	Content color on surfaces	Default color for text, icons, and symbols on all surface and surface-container layers. Ensures readability and sufficient contrast.
on-surface-type-subtle	Aa	Subtle content color	Less dominant variant of on-surface. Suitable for secondary content such as labels, hints, or meta-information. Provides reduced weight while remaining accessible.
text-color (alias)	Aa	Alias to on-surface	Standard color for text and icons, functionally identical to on-surface.
text-color-subtle (alias)	Aa	Alias to on-surface-subtle	Matches the subtle content color. Used for secondary or supporting content.
text-color-primary (alias)		Alias to primary	Matches the primary color. Highlights text or icons with primary importance.

Inverse Surfaces (Color)

Inverse surface tokens provide high-contrast background layers that invert the usual surface logic. They are used in situations where elements must stand out strongly from the standard UI, such as toolbars, overlays, or floating panels.

Unlike neutral surfaces, inverse surfaces are designed to create strong visual separation while still maintaining accessibility and readability.

Do’s

• Use inverse-surface for clear visual inversion (e.g., toolbars, overlays).
• Always apply on-inverse-surface to ensure text and icon readability.
• Use semi-transparent variants (e.g., inverse-surface-90) for floating contexts where background visibility is needed.

Don’ts

• Do not use inverse surfaces as default backgrounds.
• Do not mix neutral and inverse surfaces in the same area without clear separation.

---

Additional Notes

• Inverse surfaces follow the Material Design pattern for high-contrast backgrounds.
• Ideal for toolbars, overlays, or floating components that must remain visually distinct.
• Transparency adds depth and layering while preserving contrast.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
inverse-surface		High-contrast inverse surface	Solid background surface designed to contrast strongly with standard surfaces. Used for components or areas that require visual inversion, such as toolbars or high-contrast overlays.
inverse-surface-90		Semi-transparent inverse surface	A translucent variant of inverse-surface (90%). Allows subtle background visibility while maintaining strong contrast. Useful for overlays or floating elements.
on-inverse-surface	Aa	Content color on inverse surfaces	Default text and icon color used on inverse-surface and inverse-surface-90. Ensures readability and sufficient contrast against darkened or inverted backgrounds.

Pane Surfaces (Color)

These tokens define the surface and behavior of application work areas. They segment the viewport into functional zones and provide a stable surface for content.

While Surfaces establish the general neutral layers of the system, Panes are more specific: they represent interactive and structural containers that can be static, floating, or transparent.

Do’s

• Use pane-surface as the base surface for work areas.
• Apply pane-surface-floating for overlapping or temporary tools that need to sit above the standard layout.
• Use pane-surface-blank intentionally for transparent panes that reveal underlying structure or grids.

Don’ts

• Do not place content in panes without ensuring sufficient contrast.
• Do not overuse floating panes — they should remain exceptions for tools or dialogs.

---

Additional Notes

• Panes are the primary organizational unit of the application’s layout.
• Standard panes use the surface token to stay visually consistent.
• Floating panes follow a similar logic to dialogs but allow greater flexibility within a workspace.
• Drag handles improve usability by supporting docking and rearrangement, enabling adaptable work environments.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
pane-surface		Standard pane surface	Base surface for app panes. Panes divide the viewport into work areas and provide a neutral background for content.
on-pane-surface	Aa	Content color on pane surfaces	Default color for text, icons, and controls displayed on pane surfaces. Ensures contrast and readability.
pane-surface-blank		Transparent pane surface	Pane without a background color. Reveals underlying layers. Suitable for structural grids.
pane-surface-floating		Floating pane	Pane not part of the regular layout, layered above all other surfaces. Used temporarily or permanently, e.g., for tools or dialog areas.
pane-surface-floating-inverse		Inverse floating pane	Derived from inverse-surface-90. Ensures maximum contrast to stand out clearly from regular content surfaces.
on-pane-surface-floating-inverse	Aa	Content color on inverse floating panes	Default color for text, icons, and controls displayed on pane-surface-floating-inverse. Ensures readability even under extreme contrast.
pane-drag-handle		Drag handle for pane control	Visible anchor point for moving, docking, or rearranging panes. Supports flexible workspaces within the app layout.

Bars Surfaces (Color)

Bar-surface tokens define the surface treatment of linear UI elements such as navigation bars, toolbars, or status bars. While pane-surfaces structure larger work areas, bar-surfaces are functional control surfaces that provide space for navigation and actions. They integrate into the surrounding layout while ensuring clarity and contrast for interactive elements.

Do’s

• Use bar-surface for toolbars and navigation bars.
• Apply bar-surface-blank when bars should seamlessly blend with the underlying pane surface.
• Ensure clear readability with on-bar-surface for text and icons.

Don’ts

• Do not use bar-surfaces as content containers.

---

Additional Notes

• Bar-surfaces are always part of the UI control layer, not the content layer.
• Transparent variants (bar-surface-blank) support immersive layouts where controls should not distract from content.
• Consistent use of bar-surface tokens ensures that controls are visually distinct yet harmonized with pane- and neutral surfaces.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
bar-surface		Bar surface	Background surface for linear control bars. Can appear within a pane (e.g., toolbars) or across the viewport (e.g., top bar, navigation bar).
on-bar-surface	Aa	Content color on bars	Default color for text, icons, and controls on bars. Ensures clear visibility of interactive elements.
bar-surface-blank		Transparent bar surface	Variant without its own background color. Keeps underlying pane content visible, allowing bars to integrate subtly into immersive layouts.

Outlines (Color)

Outline tokens define the lines and borders that provide structure, separation, and emphasis within the UI. Unlike surfaces, which build visual layers, outlines are linear elements that frame or divide areas. They ensure clarity, guide focus, and support accessibility by differentiating interactive from non-interactive zones.

Do’s

• Use outline for functional separations that require sufficient contrast (e.g., form fields, input borders).
• Apply outline-variant for subtle structural divisions such as container boundaries or large grids.
• Use outline-variant-emphasized when a stronger but not full outline is needed to create balance.

Don’ts

• Do not replace functional status communication (e.g., error, success) with outlines alone.
• Do not overload layouts with multiple outline styles in close proximity.

---

Additional Notes

• outline ensures accessibility and clear separation, especially in inputs and focus states.
• Variants (outline-variant, outline-variant-emphasized) can be used decoratively or structurally, depending on the visual weight required.
• outline is reserved for system use: it should not be reassigned or used for purely decorative purposes.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
outline-width		Outline line width	Standard width for borders, outlines, and dividers. Ensures visual consistency and clear separations across the UI.
outline		Neutral outline color	Color value for visible yet restrained borders. Provides functional separation without competing with primary or brand colors.
outline-variant		Subtle outline color	Less dominant than outline. Suitable for large structures, grids, or container divisions.
outline-variant-emphasized		Medium outline color	Color value between outline and outline-variant. Used when outline is too strong and outline-variant too weak. Allows for moderate emphasis.

Corner (Dimension)

Corner tokens define the rounding of component edges. They establish a consistent visual language for how surfaces, panes, and interactive elements appear in terms of softness or sharpness.

Do’s

• Use the defined corner range to keep rounding consistent across the system.
• Apply larger corners (l–full) for high-level surfaces (e.g., modals).
• Apply smaller corners (s–xs) for functional elements (e.g., inputs, buttons).
• Use corner-m as the default for most components.

Don’ts

• Do not use arbitrary corner values outside the defined token range.
• Do not apply excessive rounding inconsistently across similar components.

---

Additional Notes

• corner (alias for corner-m) is the system reference value.
• Extreme values (corner-full, corner-xl) should be used intentionally, not by default.
• Consistent corner usage helps maintain recognizability and brand character across applications.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
corner-full		Fully rounded corners	Part of the defined corner range. Use intentionally for extreme rounding (e.g., pills, circular shapes).
corner-xl		Extra-large rounding	Part of the defined corner range. Suitable for high-level surfaces like dialogs or modals.
corner-l		Large rounding	Part of the defined corner range. Often used for prominent containers or cards.
corner-m		Medium rounding	System reference within the corner range. Default for most components.
corner (alias)		Alias to corner-m	Default corner value, refers to the medium reference.
corner-s		Small rounding	Part of the defined corner range. Suitable for functional elements like inputs or buttons.
corner-xs		Extra-small rounding	Part of the defined corner range. Best for subtle rounding in compact UI elements.

Sizing (Dimension)

Sizing tokens define the scalable size range for components and UI elements. They provide a consistent system from very small to very large, ensuring balance and predictability across the design.

Do’s

• Use the defined sizing range.
• Consciously select sizes from the range, even if this results in gaps.

Don’ts

• Do not use arbitrary values outside the token range.

---

Additional Notes

• Jumps within the range are allowed to create clear differentiation.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
sizing-3xs		Smallest size level	Part of the defined sizing range.
sizing-2xs		Very small size level	Part of the defined sizing range.
sizing-xs		Extra-small size level	Part of the defined sizing range.
sizing-s		Small size level	Part of the defined sizing range.
sizing-m (reference)		Medium size level	Central reference point of the sizing range.
sizing-l		Large size level	Part of the defined sizing range.
sizing-xl		Extra-large size level	Part of the defined sizing range.
sizing-2xl		Very large size level	Part of the defined sizing range.
sizing-3xl		Above-average large size	Part of the defined sizing range.
sizing-4xl		Strongly enlarged size level	Part of the defined sizing range.
sizing-5xl		Extreme size level	Part of the defined sizing range.
sizing-6xl		Over-proportional size level	Part of the defined sizing range.
sizing-7xl		Maximum size level	Top-defined size level of the sizing range.

Spacing (Dimension)

Spacing tokens define the consistent distance system for arranging elements. They structure relationships between components and create rhythm, readability, and clarity in the UI.

Unlike sizing, which controls component dimensions, spacing defines the white space around and between elements.

Do’s

• Use the defined spacing range.
• Apply spacing consistently to establish a recognizable layout pattern.
• Use larger spacings intentionally to highlight visual weight and hierarchy.
• Leverage white space to clarify relationships: proximity signals belonging, larger distances create separation.

Don’ts

• Do not use hardcoded pixel values instead of tokens.
• Avoid too many small spacings.
• Do not apply spacing randomly or inconsistently — it weakens perception of proximity and grouping.
• Do not “optimize away” white space — missing gaps make layouts noisy and harder to read.
• Do not separate semantically related elements with oversized spacing.

---

Additional Notes

• Spacing is key for rhythm, readability, and information architecture.
• Consistent spacing makes layouts calmer and more coherent.
• Spacing derives from semantic proximity and visual hierarchy — not from rigid, uniform values.
• Rule of thumb: equal relationships → equal spacing; different relationship strength → graded spacing.
• Consistency does not mean uniformity — it means a recognizable pattern that supports hierarchy and semantic grouping.

---

Token Name	Preview	Purpose (Intent)	Recommended Usage
spacing-0		Zero spacing	Used intentionally where no spacing is required.
spacing-4xs		Smallest spacing	Part of the defined spacing range.
spacing-3xs		Very small spacing	Part of the defined spacing range.
spacing-2xs		Extra-small spacing	Part of the defined spacing range.
spacing-xs		Small spacing	Part of the defined spacing range.
spacing-s		Small to medium spacing	Part of the defined spacing range.
spacing-m (reference)		Medium spacing (reference)	Central reference point of the spacing range.
spacing-l		Slightly larger spacing	Part of the defined spacing range.
spacing-xl		Large spacing	Part of the defined spacing range.
spacing-2xl		Very large spacing	Part of the defined spacing range.
spacing-3xl		Extra-large spacing	Part of the defined spacing range.
spacing-4xl		Maximum defined spacing	Top-defined level of the spacing range.

Transient Elements & States

Transient Elements & States tokens define the temporary UI elements and state indicators that support interaction.

Token Name	Preview	Purpose (Intent)	Recommended Usage
scrim		Darkened background surface	Semi-transparent overlay that darkens the background when modal dialogs, overlays, or popups are open. Helps direct focus to the foreground and reduces distractions.
scrim-opacity		Scrim transparency level	Defines how much of the background remains visible. Higher opacity increases separation, lower opacity creates a subtler effect.
disabled-opacity		Disabled state transparency	Reduces visibility of non-interactive content. Clearly signals inactive state without breaking the layout structure.
scrollbar-outer-size		Scrollbar track width	Sets the outer dimension of the scrollbar. Ensures sufficiently large interaction targets without covering content excessively.
scrollbar-inner-size		Scroll thumb width	Defines the actual draggable area of the scrollbar. Should be clearly visible and easy to use.
scrollbar-thumb-color		Default scroll thumb color	Color value for the thumb in its resting state. Neutral design for visibility without distraction.
scrollbar-thumb-color-hover		Hover scroll thumb color	Stronger color for the thumb in hover state. Improves discoverability and indicates readiness for interaction.
scrollbar-track-color		Scroll track background color	Color value for the track the thumb moves along. Designed subtly to keep focus on content and thumb.
focus-indicator-size		Focus band width	Defines the width of the inner and outer lines forming the focus indicator. Ensures consistent rendering across the system.
focus-indicator-inner		Inner focus band	Color value for the line directly adjacent to the component. Provides clear visual separation from the surrounding area.
focus-indicator-outer		Outer focus band	Color value for the outer focus line. Adds extra contrast to the environment and strengthens focus visibility.