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.

Global & Semantic tokens

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

name: "calcite.global.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.
 */