Tokens Documentation

---

tags: [tokens]

Documenting tokens

Design tokens should be self documenting through their naming schema, however it is often important to include additional details useful to customers and contributors.

Semantic tokens

Additional details can be added to a token's optional description property in `calcite-design-tokens.

name: "calcite.semantic.color.foreground.1"
description: "Usually defines the default background color of neutral components."

Component tokens

Component tokens can be documented in a component's SCSS file us JSDocs syntax. Public tokens should be documented at the top of the SCSS page in a comment block that always starts with CSS Custom Properties.

/**
 * CSS Custom Properties
 *
 * These properties can be overridden using the component's tag as selector.
 *
 */

Each token can then be added as a @prop --[token-name-for-the-web]: [description].

* @prop --calcite-component-background-color: Specifies the component's background color.

/**
 * CSS Custom Properties
 *
 * These properties can be overridden using the component's tag as selector.
 *
 * @prop --calcite-component-background-color: Specifies the component's background color.
 *
 */

Preferred Formats

Often token behavior depends on specific properties or states. Follow the formats below.

• For specific properties: When [prop]and/or[prop], [token behavior]
• For specific states (e.g., active, hover, etc.): [token behavior] when [state]
• For specific properties and specific states combined: When [prop] and/or [state], [token behavior]

Example

/* mycomponent */
/*
 * --calcite-mycomponent-color-background: Specifies the component's background color.
 * --calcite-mycomponent-button-color-background: Specifies the background color of the component's button.
 * --calcite-mycomponent-button-color-background-hover: Specifies the background color of the component's button when hovered or focused.
 * --calcite-mycomponent-button-color-background-press: Specifies the background color of the component's button when active or pressed.
 * --calcite-mycomponent-selected-icon-color: When `selected`, specifies the color of the component's icon.
 * --calcite-mycomponent-button-color-active: When `selected` or active, specifies the color of the component's button.
 */