Skip to content
Theme and tokens

Theme and tokens

Change the system through tokens, not by adding overrides to individual components. In the full repository, edit shared/tokens/ and run the sync; in a standalone edition or starter, edit the corresponding token directory inside your own shared mirror. The generated folders guide identifies each mirror and explains why repository mirrors are not the source of truth.

Find the token layer

shared/tokens/index.css imports shared/tokens/fonts.css, shared/tokens/palette.css, shared/tokens/theme.css, shared/tokens/typography.css, shared/tokens/spacing.css, shared/tokens/effects.css, then shared/tokens/density.css. Keep that order: the palette defines primitives; the theme maps them to semantic roles; components consume roles such as --or-accent, --or-text, and --or-surface, not palette colors directly. The same structure lives under html/shared/tokens/, react/src/shared/tokens/, nextjs/src/shared/tokens/, vue/src/shared/tokens/, and nuxt/app/shared/tokens/ when those editions are standalone.

Change the accent or another role

  1. In a full repository, choose or edit a primitive in shared/tokens/palette.css, then map --or-accent, --or-accent-hover, --or-accent-soft, --or-accent-text, and --or-text-on-accent in shared/tokens/theme.css for each theme. In a standalone folder, make the equivalent edit in that edition's own shared mirror (the exact paths are listed above and in generated folders).
  2. Check the foreground/background combinations and focus indicators, rather than judging the accent alone. Normal text needs 4.5:1; large text, UI boundaries, and focus indicators need 3:1 under WCAG 2.2 AA. The repository's declared pairs live in tools/contrast-check/pairs.mjs.
  3. In a full repository, run the contrast check, then sync the changed source into the editions. In a standalone folder, verify the same ratios with your own contrast tooling; the root tools/ scripts are not part of that folder.
Full repository only
node tools/contrast-check/check.mjs
node tools/sync-shared.mjs

Choose theme, density, and layout

shared/ui/preferences.mjs lists three themes (light, dark-ink, dark-charcoal), two densities (comfortable, compact), and three layouts (sidebar, rail, topbar). shared/tokens/theme.css maps semantic roles for all three themes; the selected value is the document's data-or-theme attribute. shared/tokens/density.css changes sizes, not color, through data-or-density. data-or-layout selects the layout without changing the underlying content. Use each edition's appearance controls to inspect the result before shipping; changing shared/ui/preferences.mjs alone does not create the token mappings or UI for a new option.

Keep fonts local

The delivered faces in shared/fonts/ and shared/tokens/fonts.css are self-hosted. A full repository can regenerate them with tools/fonts/build.mjs (which fetches the faces once during development); the resulting font files are copied to editions by the sync. A standalone folder already has its mirrored fonts and does not need the root tool to render them. Do not add a runtime font-host request. See generated folders before editing generated font files.