Design tokens

Introduction

Design tokens are reusable, named CSS variables that represent design attributes like colors. They help keep your component styles consistent and easy to manage.

The Component SDK exposes a set of design tokens via CSS custom properties prefixed with --uic-, as well as an accessor method getDesignToken on the Component Context API.

Overview

The following table lists the supported design tokens:

Token Name	CSS Variable	Description
`color-scheme`	`--uic-color-scheme`	Color scheme for the component, e.g. `light` or `dark`.
`background`	`--uic-background`	Background color for the component, which may vary based on where the component is rendered.
`on-background`	`--uic-on-background`	Readable color on top of the background color.
`primary`	`--uic-primary`	Primary brand color, which is derived from the key color and adjusted for contrast based on the active color scheme.
`on-primary`	`--uic-on-primary`	Readable color on top of the primary color.
`secondary`	`--uic-secondary`	Secondary brand color.
`on-secondary`	`--uic-on-secondary`	Readable color on top of the secondary color.
`error`	`--uic-error`	Error color.
`on-error`	`--uic-on-error`	Readable color on top of the error color.
`success`	`--uic-success`	Success/confirmation color.
`on-success`	`--uic-on-success`	Readable color on top of the success color.

Design Tokens in JavaScript

Use the Component Context API to retrieve token values programmatically.

context.getDesignToken(name: string): string returns the evaluated value of a design token (e.g., a hex color like "#ff0000").
context.getDesignToken.var(name: string): string returns the CSS variable string (e.g., "var(--uic-primary)"), useful for setting styles in markup or inline styles.

Example

Get the primary color value as a value:

const primaryColor = context.getDesignToken('primary'); // → "#ff0000"

Or as a CSS variable string for an attribute binding:

<svg width="100" height="100" viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" fill={context.getDesignToken.var('primary')} />
</svg>

Detecting a dark color scheme:

if (context.getDesignToken('color-scheme') === 'dark') {
  console.log("Dark theme detected!");
}