# Design tokens

Named values for color, shadow, curve and layout that resolve per theme, offered as a CSS file, a JSON file and a print file.

* Kind: foundation
* Page: https://design.werklist.com/foundations/tokens
* Version: 2.1.2

## When to use it

* Style through var(--token), so the value follows the theme.
* Link werklist-tokens.css in a web page and write data-theme on the root element, light included.
* Read werklist-tokens.json in a design tool or a script: $value is the light value, and $extensions["com.werklist.mode"] holds the dark value as well.
* Use werklist-tokens.print.css for anything printed: light values only, no glass, no shadow.

## When not to use it

* Copying a value from the JSON file into code: it keeps one value when the theme changes.
* Naming a new token for how it looks, such as --light-grey: the name stops being true in the dark theme.
* Editing your copy of a token file: take the files as they are published, so every screen reads the same values.
* Using a token that belongs to one part of the product, such as --chat-bubble-own, anywhere else.

## Rules

* In the CSS file, dark values stand on :root and light values on html[data-theme="light"]. Without data-theme the file gives the dark values. WerkOS always writes the attribute and opens in light.
* A token that is the same in both themes, such as --brand-true, is declared once, on :root.
* The tokens a screen is built from are named for their job, not their look: --surface-control, not --light-grey.
* Page: background takes var(--bg).
* Panel: background takes var(--surface-1).
* Band: background takes var(--surface-2).
* Nested box: background takes var(--surface-strong).
* Control fill: background takes var(--surface-control).
* Scrim: background takes var(--overlay).
* Body text: color takes var(--text).
* Supporting text: color takes var(--text-muted).
* Labels: color takes var(--text-label).
* Blue text: color takes var(--brand-ink).
* Edge of a control: border-color takes var(--border).
* Row rule: border-color takes var(--border-rule).
* Marks: background takes var(--brand-blue).
* Button fill: background takes var(--brand-true).
* Text on the button fill: color takes var(--on-brand).
* Status fills: background takes var(--success), var(--warning) or var(--error).
* Status inks: color takes var(--success-ink), var(--warning-ink) or var(--error-ink).

## Tokens

* --bg
* --surface-1
* --text
* --brand-true
* --brand-ink