Tokens

Every token is a custom property of :root named --phil-*, in one of three files: css/tokens/dimensions.css, css/tokens/palette.css and css/tokens/colors.css, each in its own layer. The CSS is the source; dist/tokens.json gives the same tokens to design tools, in the format of the Design Tokens Community Group — see The tokens as JSON.

The scales

Each scale is computed from one unit and a global multiplier, so a site changes a whole scale at once.

The other dimensions: --phil-leading-tight and --phil-leading-md, --phil-measure (65ch) and --phil-measure-narrow (36ch), the font stacks --phil-font-sans, --phil-font-serif and --phil-font-mono — the system's own, nothing downloaded —, --phil-focus-width and --phil-focus-offset, the durations --phil-duration-sm, -md, -lg and -loop, and the easings --phil-ease-out and --phil-ease-in-out.

The palette

Seven hues — neutral, brand, red, green, amber, blue, violet — of eleven tones each, numbered by their OKLCH lightness: --phil-brand-40 is oklch(0.40 …). The neutrals add 99, the near-white of the page.

Because the number is the lightness, the difference of two numbers gives the contrast, whatever the hues:

Each chroma is the hue's own, held within the sRGB gamut at every lightness, so a tone looks the same on every screen.

The colour roles

Components read roles, never the palette. Each role is light-dark(<light tone>, <dark tone>).

The grid

Six roles — brand, neutral, danger (red), success (green), warning (amber), info (blue) — each have six colours: a fill, a border and the colour on that fill, each quiet (a tint) or loud (solid).

.isNotice {
    color: var(--phil-color-info-on-quiet);
    background: var(--phil-color-info-fill-quiet);
    border: 1px solid var(--phil-color-info-border-loud);
}

The tokens as JSON

dist/tokens.json holds the tokens in the format of the W3C Design Tokens Community Group (2025.10), which design tools read and write. It is generated from the CSS, which stays the source, by the same command as the single file:

php bin/build.php    # from the package, after a change under css/

The tests compare it with an export of the sources and fail while it is stale, so the continuous integration catches a CSS change without its JSON. The npm package exports it as @phil/ux-css/tokens.json.

Each token carries, under the extension ca.ph-il.phil-ux, its custom property and its CSS as written, so that a tool writing CSS back keeps the formulas:

"sm": {
    "$type": "dimension",
    "$value": {"value": 0.75, "unit": "rem"},
    "$extensions": {
        "ca.ph-il.phil-ux": {"property": "--phil-space-sm", "css": "calc(var(--phil-space-unit) * 0.75)"}
    }
}

A value the format has no type for is left out, and named in the extension of the file: --phil-measure and --phil-measure-narrow, in ch, and --phil-mix-hover and --phil-mix-active, in percent. calc() is computed only where it is plain arithmetic of one unit — +, -, *, /, parentheses and var() —, within bounds on its length, its pieces and the depth of var(); Token\DesignTokens does the export and Token\Calc the arithmetic, for a site that exports its own overrides:

use Phil\UxCss\Token\DesignTokens;
use Phil\UxCss\Token\TokenSheet;

$sources = [...DesignTokens::sources('vendor/phil/ux-css/css'), 'assets/theme.css'];
$json = DesignTokens::fromSheet(TokenSheet::fromFiles(...$sources))->toJson();