Finishes and themes

data-finish on any element

Every colour in the kit is a token, and the tokens are defined per finish. Set data-finish="graphite" on any element and everything inside it recomputes: a graphite call-to-action band on an aluminium page, a dark console in a light site.

<section data-finish="graphite">
  <h2 class="tui-h2">Set it up in the time it takes to read this.</h2>
  <a class="tui-key tui-key--primary" href="/docs/start-free">Start free</a>
</section>

Following the system

The head script sets the page finish before the first paint: the stored choice if there is one, otherwise graphite for a dark system and aluminium for a light one. setFinish() puts a finish and its tone on the page and stores the choice:

import { setFinish } from '/kit/kit.mjs';
for (const r of document.querySelectorAll('input[name="finish"]')) {
  r.checked = r.value === document.documentElement.dataset.finish;
  r.addEventListener('change', () => setFinish(r.value));
}

Families and tones

Every finish belongs to a family of two, a light finish and a dark one: Machined, aluminium and graphite; Wood, oak and walnut; Materials, porcelain and black; Light, daylight and night; Printed, paper and phosphor; Screens, e-paper and amoled. Machined is kit.css itself; each other family is one stylesheet, linked after it:

<link rel="stylesheet" href="/kit/themes/wood.css">
<link rel="stylesheet" href="/kit/themes/materials.css">
<link rel="stylesheet" href="/kit/themes/light.css">
<link rel="stylesheet" href="/kit/themes/printed.css">
<link rel="stylesheet" href="/kit/themes/screens.css">

With the finish goes data-tone="light" or "dark", which the head script and setFinish() set. Where you mean a dark page rather than one material, read the tone. setFamily('materials') keeps the visitor's tone, and setTone('dark') flips within the family, as the finish key on this site does.

The finish tokens

These change with the finish. Read them in your own CSS; never write a literal colour instead.

Constant across finishes: the lamps (--tui-green, --tui-amber, --tui-red), grid, radii and --tui-ease; and, in Machined and Materials, the displays (--tui-lcd, --tui-lcd-ink, --tui-vfd-bg, --tui-vfd) and type. Daylight shows an LCD in the sun it reads best in, and night backlights it amber, since a reflective LCD is blank in the dark. Paper and phosphor print an LCD as a tint and a lit window solid, and set labels, keys and the figures in displays in Departure Mono (--tui-mono), a pixel face at 11px that kit/themes/printed.css loads. E-paper and AMOLED set every word in it (--tui-sans too) on its 11px grid, with their own type scale (--tui-t-*) and smaller corners (--tui-r-*); kit/themes/screens.css loads it for them. The light stacks (--tui-raised, --tui-inset, --tui-pressed) are drawn from the finish tokens and change with the volume; porcelain and black draw their own recess, daylight and night draw the light itself (the sun’s short, hard shadow; no shadow at all and every edge lit from inside), paper and phosphor draw every edge as a line of ink, and e-paper and AMOLED draw it as a rim of whole pixels, with a hard pixel shadow on e-paper and dithering for a key that is down. --tui-hl is the catch light on an edge and --tui-sheen the broad light on a cap: unset, the sheen is the catch light, and black sets it apart so a bright chamfer can sit on a satin cap.

What there is no token for

An accent colour of its own. The kit ships without one and its restraint is the product; --tui-brand is a layer for whoever ships it, left unset here (see Tune it to your brand). You can also change the finishes’ values (a warmer desk, a colder aluminium) by overriding the finish tokens on [data-finish="aluminium"] (a recess takes its colour from --tui-tactile-well or --tui-quiet-well, one for each volume); the verify tool will still refuse purple and orange literals.