​

Brand tokens

​

Package layout

packages/brand-tokens/
  package.json    private, version 0.0.0, exports the three subpaths below
  tokens.css      --wai-* primitives + product tokens for dark, light, high-contrast
  fonts.css       @font-face rules with relative url() to ./fonts/*.woff2
  fonts/          Inter 400/500/600, Space Grotesk 500/600, JetBrains Mono 400/500 (woff2)
  OFL.txt         licence for the bundled fonts (OFL-1.1)

​

The theme contract

• A theme mode is not the attribute value. The web client stores a mode (auto | dark | light | high-contrast) but writes only the resolved theme (dark | light | high-contrast) to document.documentElement’s data-theme. auto never appears on the attribute; it resolves through prefers-color-scheme and prefers-contrast: more. The Control UI resolves only dark | light, so it never reaches the high-contrast block.
• color-scheme comes from the token blocks. Each block sets color-scheme so native scroll bars and form controls follow the chosen theme rather than the operating system. Do not override it with a hard-coded value in an app stylesheet, and give any new theme block its own value. The Control UI also sets style.colorScheme inline to the same resolved value.
• Dark is the fallback. With no data-theme attribute the :root block applies, so a page that has not resolved a theme yet renders dark rather than unstyled.

​

Token groups

​

The accent-foreground token

/* Do this: pair a fill with its foreground token */
.cl-badge {
  background: var(--accent);
  color: var(--accent-foreground);
}

/* Not this: a hard-coded white that fails contrast in high-contrast */
.cl-badge {
  background: var(--accent);
  color: #fff;
}

​

How the apps consume it

import "brand-tokens/fonts.css";
import "brand-tokens/tokens.css";
import "./app/app.css";
import "./ui/client.css";

/* Do this */
src: url("./fonts/inter-400.woff2") format("woff2");

/* Not this: resolves against the host root and 404s under any base path */
src: url("/fonts/inter-400.woff2") format("woff2");

​

Add a token safely

1. Add the property to the :root block. If its value differs by theme, add it to the light and high-contrast blocks too; a token missing from a block silently inherits the dark value.
2. Use only six-digit hex for colours the contrast test reads (#rrggbb).
3. Keep the block formatting: the test finds blocks by the literal text <selector> { and reads one --name: value; declaration per line up to the first \n}.
4. If the token is a text or border colour that sits on another token, add an assertion to test/brand-tokens-contrast.test.ts for the pair.
5. Run the guards below, then pnpm --dir ui test and pnpm test:web.

​

Add or change a font safely

1. Confirm the licence allows redistribution and record it beside OFL.txt.
2. Add the woff2 (latin subset) under packages/brand-tokens/fonts/.
3. Declare it in fonts.css with a relative url() and font-display: swap. The package files list already covers the fonts directory.
4. Update the tokens that name the family (--font-body, --font-display, --mono).
5. Update the brand e2e (test/user-client-web-brand.e2e.test.ts): the font test counts the declared faces and requires each to load with a 200 response. If the weight has no always-rendered use, also add it to REQUIRED_WARM_FONTS in apps/web/src/providers/font-warm.ts, because browsers load @font-face lazily.

​

Guard tests

​

Related

• Web client components - how apps/web builds on these tokens
• Web client hosting - what operators and users see
• Control UI - the other consumer