Theming

Make a brand

Four inputs: an accent, an ink, a paper and a body font. The brand builder does this in the browser; make-brand does it on the command line and writes packages/tokens/brands/<name>.json.

node packages/tokens/scripts/make-brand.mjs --name acme --label "Acme Roofing" \
  --accent "#0f766e" --ink "#111827" --paper "#fbfaf7" \
  --font-body "'Hanken Grotesk Variable', Arial, sans-serif" \
  --font-display "'Fraunces Variable', Georgia, serif"
# or: --input brief.json (same keys), --dry-run, --report report.json, --appearance solid|depth

It exits with an error and writes nothing when a required pair fails AA. --force writes the file for review, but the build still refuses it. After adding a brand, add its ./brands/<name>.css entry to the package exports and rebuild.

Brands and modes

Two attributes, on <html> or on any element: data-brand picks the palette and data-theme picks light or dark. Nesting works both ways.

<html data-brand="harbour" data-theme="light">
  <section data-theme="dark">Still Harbour, now in its dark palette.</section>
</html>

The depth button tokens

The depth button is a tonal gradient that models light on a physical button. All of it comes from tokens, so it follows every brand.

.button {
  background-image: var(--brand-action-depth-fill);
  box-shadow: var(--brand-shadow-action-depth);
  color: var(--brand-action-depth-text);
}
.button:hover { box-shadow: var(--brand-shadow-action-depth-hover); }

Offer level tokens

Five levels, sky, blue, navy, pearl and obsidian, for ranking offers and plans. Print the level name next to the colour so colour is never the only cue.

• Skylevel-sky-*
• Bluelevel-blue-*
• Navylevel-navy-*
• Pearllevel-pearl-*
• Obsidianlevel-obsidian-*

The gradient rule

Gradients are welcome when they model light on an object: one hue, lighter at the top, a thin sheen and a same-hue shadow, on buttons, level tiles and at most one brand-colour section. The build refuses any brand whose depth, level or WhatsApp stops span more than 40 degrees of hue, and the UI lint flags multi-hue gradients and gradient text in your code.

pnpm exec brand-ui-lint                  # check against the baseline
pnpm exec brand-ui-lint --update-baseline

Colour roles for this site's brand

Every role exists in every brand and mode and compiles to --brand-<role>. These are the values for the docs brand.