Design token usage

What are design tokens?

Design tokens are the building blocks of design - they represent decisions like color, spacing, shadow, and opacity. Design tokens encourage consistency across experiences, reinforce accessibility within components, and support rich theming and customization.

Benefits

Ensure consistency across user interfaces and applications
Assist in meeting accessibility requirements
Support shared design patterns across teams and projects
Provide more opportunities for customized theming

Types

Calcite supports the following design token types:

color

border

corner-radius

shadow

opacity

stacking

font

spacing

Calcite Components are built using combinations of each design token type to ensure styling is applied consistently.

Tiers

Calcite design tokens are grouped into tiers based on the scope of their intended use cases. These tiers reinforce the compositional nature of design decisions. Utilizing each tier is the most effective way to get the most out of Calcite design tokens.

Core tokens
Semantic tokens
Component tokens

Core tokens

Core tokens are a large collection of variables that are primarily used as values for semantic tokens. Core tokens function as a collection of predetermined raw values with no specific usage guidance.

A diagram showing the relationship between a raw HEX value and a core token consuming the HEX value as a named value.

Refer to the design tokens reference page for the list of Calcite's core tokens.

Semantic tokens

Semantic tokens pair core tokens with purpose-based naming for use in both component and non-component design decisions. By default, semantic tokens reference other variables instead of raw values.

Calcite's semantic token types include color, border, corner-radius, shadow, opacity, stacking, font, and spacing.

Semantic color

The semantic color tokens have a deeper level of categorization compared to other types. They denote each token's intended usage context that is applied throughout Calcite Components.

Color groups

background: Page backgrounds and large-scale surfaces
foreground: Surfaces of most components and containers
brand: Elements using branding colors
text: All instances of typography and icons
border: Strokes on the edges of elements and dividers
status: Non-text elements communicating a status to users
transparent: Elements using any amount of opacity
inverse: Surfaces needing color contrast opposite of foreground colors

Color sequences

Some semantic color tokens are paired with similar -hover and -press tokens that are used for interactive elements:

--calcite-color-status-danger
--calcite-color-status-danger-hover
--calcite-color-status-danger-press

Other semantic color tokens use -1, -2, and -3 to specify visual hierarchy. Elements using color tokens with a -1 typically take visual priority over elements using a -2 or -3 token:

--calcite-color-text-1
--calcite-color-text-2
--calcite-color-text-3

Refer to the design tokens reference page for the list of Calcite's semantic tokens.

Component tokens

Component tokens provide component-level overrides to semantic token patterns and allow customization of Calcite Components via CSS variables. They are scoped specifically to their respective components, enabling more specific modification. By default, component tokens reference semantic tokens.

Refer to an individual component documentation page to view available component tokens, such as Button's CSS variables.

Customization

The Calcite design tokens are structured to support building flexible customizations at any level. Making modifications through supported design tokens helps to prevent potential future breaking changes.

Semantic overrides

Semantic tokens can be customized to modify styles within Calcite Components across entire products. They can also be modified in smaller contexts to limit customizations to specific content sections if needed.

For example, this is a brand theme applied at the :root level:

Use dark colors for code blocksCopy
/* Override semantic tokens to apply a custom theme across the app */
:root {
  --calcite-color-brand: #35AC46;
  --calcite-color-brand-hover: #288835;
  --calcite-color-brand-press: #1A6324;
  --calcite-color-brand-underline: #1A6324;
}

Component overrides

The most commonly modified variables in Calcite Components are surfaced as component tokens to support component-specific customizations. They can be set at the document's :root to override all components in an application:

Use dark colors for code blocksCopy
/* Override all Button backgrounds */
calcite-button {
  --calcite-button-background-color: #8E499B;
}

Alternatively, they can be set to modify a specified component instance:

Use dark colors for code blocksCopy
/* Override specific Button backgrounds */
.example-theme-class {
  --calcite-button-background-color: #8E499B;
}

The most efficient customization strategy is utilizing the strengths of both semantic and component tokens in combination with each other.

Naming

The Calcite design token naming system is broken up into 4 categories: namespace, object, base, and modifier. They provide different levels of context for each design token's intended usage.

Namespace

Namespace terms contextualize design tokens at the highest level by defining the system and tier. In most cases, this is where design tokens are differentiated from other variables outside the Calcite system.

Namespace examples

Core tokens:

--calcite-color-high-saturation-green-h-gg-060

--calcite-size-16

--calcite-opacity-12

Semantic tokens:

--calcite-color-text-1

--calcite-spacing-md

--calcite-corner-radius-none

Component tokens:

--calcite-button-background-color

--calcite-checkbox-size

--calcite-alert-corner-radius

Object

Object terms are typically only used for component tokens. They define the component and the specific elements that the token is applied to.

Object examples

Component tokens:

--calcite-block-header-background-color

--calcite-card-group-space

--calcite-chip-corner-radius

Base

Base terms identify design token types and provide information on the expected values.

Base examples

Core tokens:

--calcite-color-neutral-blk-120

--calcite-size-12

--calcite-container-size-1440

Semantic tokens:

--calcite-color-brand-press

calcite-border-width-md

--calcite-corner-radius-md

Component tokens:

--calcite-input-border-color

--calcite-alert-corner-radius

--calcite-card-shadow

Modifier

Modifier terms are placed at the end of the token when they are needed. They specify the remainder of the details that come after the token base. Some modifier terms, like default, are left off of the final token name.

Modifier examples

Core tokens:

--calcite-color-dark-green-d-gg-430

--calcite-size-relative-50

calcite-opacity-50

Semantic tokens:

--calcite-color-status-danger-hover

--calcite-spacing-sm

--calcite-opacity-half

Component tokens:

--calcite-accordion-text-color-press

--calcite-tab-content-space-y

--calcite-tip-max-width

Structure

The majority of design tokens reference a single value and are consistent in their structure: value > core > semantic > component. Design token types following this structure include color, border, corner-radius, shadow, opacity, stacking, font, and spacing tokens.

Tokens in Figma

Semantic tokens are provided as Figma variables in the Web UI Kit. Once the UI Kit is added to a Figma file, the semantic tokens will automatically appear in the appropriate Figma menus:

Support

Visit the Community and Support page to explore more resources and about the process to submit a bug or enhancement to consider to fit use cases.