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 background color of the component.

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

Example

/* mycomponent */
/*
 * --calcite-mycomponent-color-background: Specifies the background color of the component.
 * --calcite-mycomponent-button-color-background: Specifies the background color of the button in the component.
 * --calcite-mycomponent-button-color-background-hover: Specifies the background color of the button in the component when hovered or focused.
 * --calcite-mycomponent-button-color-background-press: Specifies the background color of the button in the component when in an active or pressed state.
 */