Tokens

Contract

A component sees tiers 2 and 3 — the semantics and the roles. It never sees tier 1.

.my-thing {
  /* tier 2: what the colour is for */
  color: var(--text-primary);
  /* tier 3: a padding by purpose */
  padding: var(--pad-panel);
  /* tier 4: the point of adjustment of the component itself.
     A button has five of them: --btn-bg and its neighbours */
  background: var(--btn-bg);
}

Accessibility

Anatomy

Raw steps. They do not change between themes. A ramp is continuous by definition: a step the semantics has not taken is a reserve for the application and for charts rather than rubbish.

The statuses have no step 2: their roles are fixed (1 is the background in a light theme, 3 the text in a dark one, 4 the fill in a light one, 5 the text in a light one, 6 a reserve for charts), and a free step between 1 and 3 has not been wanted once. The lightness values and the analysis of the roles are in colour.

The hue knob

Tier 2 — semantics

One declaration per token through light-dark(). A second block of tokens does not exist, so there is nothing to diverge.

Surfaces

The last three are the recess of a control: the default button, a tag, the fallback fill of a badge. Black laid over rather than a step of the ramp of its own, and that is no trifle. A step sets lightness absolutely and therefore knows one depth, while a control lies now on a page, now on a panel, now in a modal — and it has to step away from each of them by the same amount. On a raised panel --surface-sunken gave a drop of 0.087 instead of 0.033: the panel is already a step higher, and the steps added up.

The direction depends on where we are on the ramp, as with --surface-hover. In the light themes a control is recessed — a black film; in the dark ones it is raised — a white one.

That is not a refusal of the drop but the only form of it available. A film subtracts lightness, and at the bottom of the ramp there is nothing to subtract from: the page of a dark theme is rgb(12,12,12), and even a solid black gives 1.073 against it against 1.142 in the light ones. The drop that is wanted does not exist as a darkening. And the default button has its fill as its only mark: there is no border and no shadow, the drop removed both.

The invariant is therefore stated without the word "depth": the surface of a control has to differ from its ground by a discernible step.

The sign of the film changes, the order of loudness does not. The middle row serves two jobs at once: it is the hover of the default and the resting fill of the soft weight inst-btn--soft. So it has to be quieter than the default in both themes, otherwise the third step of the ladder sounds louder than the second. Loudness here is the modulus of the step against the ground rather than the alpha: in the light themes quieter means less black, in the dark ones less white.

Three cmd/contrast pairs guard this: "a button against a panel", "a button against a page" and "the ladder: soft against default".

Text

Borders

Accent

Statuses

There is no third token — a "fill" between the text and the background. There is one exception, the accent: it has a case the statuses do not, a fill under a white label.

Tone through an attribute

data-tone sets three variables, and a component reads them and knows nothing else about the tone.

Charts

The rest

The order of layers

Tier 3 — roles

The one tier density retunes, and the one reason there are no constants in the components. Declared through :where() — zero specificity, so an application overrides without a fight. The values below are for the default density, and the other two are in density.

Control heights and paddings

Paddings by purpose

--gap-section is the fourth step of the rhythm: the gap between sections, where --gap-row works inside one. The value is not appointed but derived: it is --gap-row raised by four steps of the scale. The scale is built so that +4 steps give exactly ×4 at every point — 4→16, 6→24, 8→32, 12→48, 16→64 — so the ratio holds across all fifteen combinations of scale and density with no separate fitting.

The role appeared after assembled screens were measured. Without it the tier stopped at 16px: the loudest thing available to part two blocks was of the same order as the gap inside a block — and the screen read as one continuous flow. The steps 24, 32, 48 and 64 meanwhile lay in the scale without a single role.

Glyphs and gutters

Layout

Scale

Not tied to a theme and not retuned by density. The details are in typography and rhythm and shape.

Typography

--measure is the limit on the length of a line, 68ch. The classical norm is 45–75 characters; 68 stands at the upper edge, because interface descriptions are short and wrap rarely. The unit is ch rather than pixels: otherwise the measure parts ways with the type size on each of the five steps of scale.

The role appeared after a measurement: 68ch was written as a literal in two places, while the body of a banner had no measure at all and reached 105 characters on a container of 1440px. What is truncated is the body of the banner rather than the banner: the ground of a page-level message runs the full width, the text on it does not.

Space and shape

Motion

Tier 4 — the component

It lives beside the component rather than here. There is one rule: 2–3 variables, no more, and a variant is described by them rather than by rewriting the block.

.my-btn--accent {
  --btn-fg: var(--accent-on);
  --btn-bg: var(--accent-solid);
}

The list of a particular component's variables is on its page: the button has five, the table has its own.

Variants

Rules

What to take and what not to

API

Listed by a generator reading src/tokens.css. The list is not typed by hand and therefore cannot fall behind the sources.

Related

Colour Typography Rhythm and shape Elevation and surfaces Motion Density Icons