A token is a Typed OM value whose toString() is var(--name). It fits anywhere a value of its type fits: color(blue), border("1px solid", blue). In math and in other CSS functions it is a part of a call: calc(t.space.md, "*", 2), var(t.space.sm, "4px") (see "Functions").
import * as import csscss from "cssints" with { type: "cssints" };
const const blue: Token<"color", true, string>blue = import csscss.const token: {
readonly number: TokenFn<"number">;
readonly color: TokenFn<"color">;
readonly length: TokenFn<"length">;
readonly percentage: TokenFn<"percentage">;
readonly integer: TokenFn<"integer">;
readonly angle: TokenFn<"angle">;
readonly time: TokenFn<"time">;
readonly resolution: TokenFn<"resolution">;
readonly url: TokenFn<"url">;
readonly image: TokenFn<"image">;
readonly shadow: TokenFn<"shadow">;
readonly lengthPercentage: TokenFn<"lengthPercentage">;
readonly customIdent: TokenFn<...>;
readonly transformList: TokenFn<...>;
readonly easingFunction: TokenFn<...>;
} & {
...;
}
color: <"blue", "color-primary">(initial: "blue", name?: "color-primary" | undefined) => Token<"color", true, string>color("blue", "color-primary"); // --color-primary, can be set
const const gap: Token<"length", true, string>gap = import csscss.const token: {
readonly number: TokenFn<"number">;
readonly color: TokenFn<"color">;
readonly length: TokenFn<"length">;
readonly percentage: TokenFn<"percentage">;
readonly integer: TokenFn<"integer">;
readonly angle: TokenFn<"angle">;
readonly time: TokenFn<"time">;
readonly resolution: TokenFn<"resolution">;
readonly url: TokenFn<"url">;
readonly image: TokenFn<"image">;
readonly shadow: TokenFn<"shadow">;
readonly lengthPercentage: TokenFn<"lengthPercentage">;
readonly customIdent: TokenFn<...>;
readonly transformList: TokenFn<...>;
readonly easingFunction: TokenFn<...>;
} & {
...;
}
length: <"16px", {
readonly var: "gap";
readonly inherit: false;
}>(initial: "16px", name?: {
readonly var: "gap";
readonly inherit: false;
} | undefined) => Token<"length", true, string>
var: "gap"var: "gap", inherit: falseinherit: false });
const const muted: Token<"color", false, string>muted = import csscss.const token: {
readonly number: TokenFn<"number">;
readonly color: TokenFn<"color">;
readonly length: TokenFn<"length">;
readonly percentage: TokenFn<"percentage">;
readonly integer: TokenFn<"integer">;
readonly angle: TokenFn<"angle">;
readonly time: TokenFn<"time">;
readonly resolution: TokenFn<"resolution">;
readonly url: TokenFn<"url">;
readonly image: TokenFn<"image">;
readonly shadow: TokenFn<"shadow">;
readonly lengthPercentage: TokenFn<"lengthPercentage">;
readonly customIdent: TokenFn<...>;
readonly transformList: TokenFn<...>;
readonly easingFunction: TokenFn<...>;
} & {
...;
}
color: <"#6b7280", undefined>(initial: "#6b7280", name?: undefined) => Token<"color", false, string>color("#6b7280"); // --_<hash>, private
export const const A: () => anyA = () => <IntrinsicElements[string]: anydiv className?: string | undefinedclassName={import csscss.const cn: (...styles: css.Style[]) => css.Stylecn(import csscss.const color: <readonly [Token<"color", true, string>]>(parts_0: Token<"color", true, string>) => css.Style`<color>`. Chrome 1, Edge 12, Firefox 1, Safari 1, iOS 1, Android 18. [MDN](https://developer.mozilla.org/docs/Web/CSS/color)color(const blue: Token<"color", true, string>blue), import csscss.const gap: <readonly [Token<"length", true, string>]>(parts_0: Token<"length", true, string>) => css.Style`<'row-gap'> <'column-gap'>?`. Chrome 57, Edge 16, Firefox 52, Safari 10.1, iOS 10.3, Android 57. [MDN](https://developer.mozilla.org/docs/Web/CSS/gap)gap(const gap: Token<"length", true, string>gap), import csscss.const color: <readonly [Token<"color", false, string>]>(parts_0: Token<"color", false, string>) => css.Style`<color>`. Chrome 1, Edge 12, Firefox 1, Safari 1, iOS 1, Android 18. [MDN](https://developer.mozilla.org/docs/Web/CSS/color)color(const muted: Token<"color", false, string>muted))} />;
export const const B: () => anyB = () => <IntrinsicElements[string]: anydiv style?: Record<string, string> | undefinedstyle={import csscss.const style: (...styles: (css.Style | StyleObject)[]) => StyleObjectcss values (declarations, no conditions) and `token.set()` results, as an inline `style` object.style(import csscss.const color: <readonly [Token<"color", true, string>]>(parts_0: Token<"color", true, string>) => css.Style`<color>`. Chrome 1, Edge 12, Firefox 1, Safari 1, iOS 1, Android 18. [MDN](https://developer.mozilla.org/docs/Web/CSS/color)color(const blue: Token<"color", true, string>blue), import csscss.const token: {
readonly number: TokenFn<"number">;
readonly color: TokenFn<"color">;
readonly length: TokenFn<"length">;
readonly percentage: TokenFn<"percentage">;
readonly integer: TokenFn<"integer">;
readonly angle: TokenFn<"angle">;
readonly time: TokenFn<"time">;
readonly resolution: TokenFn<"resolution">;
readonly url: TokenFn<"url">;
readonly image: TokenFn<"image">;
readonly shadow: TokenFn<"shadow">;
readonly lengthPercentage: TokenFn<"lengthPercentage">;
readonly customIdent: TokenFn<...>;
readonly transformList: TokenFn<...>;
readonly easingFunction: TokenFn<...>;
} & {
...;
}
set: <"color", "red">(token: Token<"color", true, string>, value: "red") => StyleObjectset(const blue: Token<"color", true, string>blue, "red"))} />; // { "--color-primary": "red", color: "var(--color-primary)" }
import csscss.const token: {
readonly number: TokenFn<"number">;
readonly color: TokenFn<"color">;
readonly length: TokenFn<"length">;
readonly percentage: TokenFn<"percentage">;
readonly integer: TokenFn<"integer">;
readonly angle: TokenFn<"angle">;
readonly time: TokenFn<"time">;
readonly resolution: TokenFn<"resolution">;
readonly url: TokenFn<"url">;
readonly image: TokenFn<"image">;
readonly shadow: TokenFn<"shadow">;
readonly lengthPercentage: TokenFn<"lengthPercentage">;
readonly customIdent: TokenFn<...>;
readonly transformList: TokenFn<...>;
readonly easingFunction: TokenFn<...>;
} & {
...;
}
set: <"color", "red">(token: Token<"color", true, string>, value: "red") => StyleObjectset(muted, "red"); // error: private tokens cannot be settoken.<type> exists for the types that @property syntax allows: color, length, percentage, lengthPercentage, number, integer, angle, time, customIdent, resolution, url, image, transformList, and two that it does not: easingFunction (<easing-function>) and shadow (a list of box shadows, <shadow>#). Those two have syntax: "*": the browser takes any value and does not check or animate it, and the initial value is still checked by the grammar; the alternative, no @property rule, would lose inherits and the default outside :root. A token fits only the typed parts of its type, with two exceptions: an integer also fits <number>, and a url also fits <image> (a url() is an image). A url token in a <url>-only position (markerStart) is fine, an image token there is an error. A relative url() in a <url> token resolves against the page, not the stylesheet. The initial value is checked against that type's grammar, in types and at build time. A browser drops an @property rule whose initial value depends on a font size (1rem, 1em, 1ch), so such a value is the initial value in px at a 16px font (1rem is 16px; 1ex and 1ch are 8px, 1lh is 19.2px, the fallbacks of CSS) and the value itself goes on :root (:where(*) when the token does not inherit): @property --gap{…initial-value:16px} and :root{--gap:1rem}, so the token follows the user's font size. On :root an em is the root's font size, as rem; a token that does not inherit takes the em of each element.{ var, inherit }) gives --name, and the token can be set. Without a name the variable is --_<hash> of the file and site, and the token is private. inherits defaults to true.@property per token at the top of the global sheet, after the layer statement and outside the layers, once however many modules use it. Two tokens with one name are a build error at the second.@property --color-primary {
syntax: "<color>";
inherits: true;
initial-value: blue;
}style() and token.set() are build-time and take static values; the result is a style object, custom properties first. A dynamic value is set with a plain style={{ "--color-primary": value }}; a typed runtime setter is not part of 0.1.color: unexpected "1px" in "1px", expected <color> ("var(--gap)" is checked as "1px": a token stands for a value of its type).env() or if() in a string part (margin("env(safe-area-inset-top)", "auto")) stands for any run of values, commas included, in any property, and the rest of the value is still checked: margin("env(x)", "red") is an error. Only the call's shape is checked (the conditions of an if()). A raw var(--name) is for a token, and a token is already its var(): a string that writes the var() of a declared token is a build warning that names the token to pass (padding: "var(--space-sm)" is the token space.sm: pass the token itself, and css.var(token, fallback) for a fallback). Any other custom property is left alone (a library's like --shiki-light, a plugin's own after namespacing like --motion-o, one an inline style or a script sets), and the scope's own --_x of a scope() kernel stays a string.docs/research/design-tokens.md.