tokens getting started

---

tags: [tokens]

Getting Started with Tokens

Using tokens in Calcite Components

In the following section you will see the words CSS variables and Calcite tokens used somewhat interchangeably. That is because within Calcite Components, Calcite Design Tokens are applied as CSS variables. Tokens are also available as SCSS and JavaScript variables but should be used sparingly and only in edge-cases where other tokens are not available or do not semantically apply. If you import Core tokens directly, log it and bring it up with the Calcite team.

Apply global tokens directly when only the global theming API should apply.

background-color: var(--calcite-color-foreground-1);

Custom theming

Or to allow more customization provide a public component token using the CSS variable fallback pattern. If you are providing a component token, be sure to document it.

background-color: var(--calcite-component-background-color, var(--calcite-color-foreground-1));

Internal variables

If multiple modifiers on the host should share a value or you a variable will improve readability and developer experience but it is not a property or element we want to encourage theming of, use an -internal- variable. This follows the best practice "only set a CSS style property once.Unless you are setting the value of an -internal- variable, all default values should reference global tokens. If you come across a static value which does not align to our design patterns make sure to double check with design that the value is necessary to meet an edge-case.

div {
    background-color: var(--calcite-component-background-color, var(--calcite-internal-component-background-color));
}

:host[modifier1] {
    --calcite-internal-component-background-color: var(--calcite-color-foreground-1);
}

:host[modifier2] {
    --calcite-internal-component-background-color: var(--calcite-color-foreground-3);
}

Best practices

1. Consider the theming experience for our customers
   1. Follow a CSS variable fallback pattern
   2. Do not set the Calcite Component Token CSS variables within the web-component code
2. only set CSS style properties once
3. Limit public tokens
4. document component tokens
5. old variables should be tagged with [Deprecated] and the new preferred token indicated in the documentation

Calcite Component Token Example

This shows examples of documenting tokens, deprecating old tokens, and applying tokens as CSS variables using a fallback pattern. For a more robust example, refer to PR 10058.

/*
 * CSS Custom Properties
 *
 * These properties can be overridden using the component's tag as selector.
 *
 * @prop --calcite-button-background-color: Specifies the component's background color.
 * @prop --calcite-el-color-background: [Deprecated] Specifies the component's background color. Use `--calcite-button-background-color` instead.
 */

/* button.scss */
button, a {
    background-color: var(--calcite-button-background-color, var(--calcite-el-color-background, var(--calcite-internal-button-background-color)));

    &:hover,
    &:focus {
        --calcite-internal-button-background-color: var(--calcite-button-background-color-hover, var(--calcite-internal-button-background-color));
    }

    &:active, {
        --calcite-internal-button-background-color: var(--calcite-button-background-color-active, var(--calcite-internal-button-background-color));
    }
}

:host {
    button, a {
        --calcite-internal-button-background-color: var(--calcite-color-foreground-1);
    }
}

:host([kind="brand"]) {
    button, a {
        --calcite-internal-button-background-color: var(--calcite-color-brand);

        &:hover,
        &:focus {
            --calcite-internal-button-background-color: var(--calcite-color-brand-hover);
        }

        &:active {
            --calcite-internal-button-background-color: var(--calcite-color-brand-press);
        }
    }

Calcite Component Token E2E Test Example

Test component tokens using the themed common test helper. Read more about testing here.

describe("theme", () => {
    themed('calcite-button', {
       "--calcite-button-background-color": {
            shadowSelector: 'button',
            targetProp: "backgroundColor",
        },
        "--calcite-button-background-color-hover": {
            shadowSelector: 'button',
            targetProp: "backgroundColor",
            state: 'hover'
        }
        "--calcite-button-background-color-active": {
            shadowSelector: 'button',
            targetProp: "backgroundColor",
            state: { press: { attribute: "class", value: CSS.button } },
        }
    }
}

Calcite Component Token Demo Example

<demo-theme tokens="--calcite-button-background-color, --calcite-button-background-color-hover, --calcite-button-background-color-active"><calcite-button kind="inverse" scale="l"> Button </calcite-button></demo-theme>

Importing tokens in other contexts

Core & Global tokens

If you are working outside the calcite-design-system, Core and Global Tokens are provided via a node module.

npm install @esri/calcite-design-tokens;

And you can use them in a project.

@import "@esri/calcite-design-tokens/css/global";

:root {   --my-custom-token: var(--calcite-color-brand); }

import * as tokens from "@esri/calcite-design-tokens/js/global";

const myColor = tokens.color.brand;

Component tokens

Component tokens are available through Calcite Components.

Learn more about the supported platforms here.