Colour

Contract

A component reaches for the semantics, and for nothing else. A ramp is the raw material the semantics is made of, and it has no business in markup.

.my-thing {
  color: var(--text-primary);
  background: var(--surface-raised);
  border: var(--hairline) solid var(--border);
}

Accessibility

Anatomy

The neutral — 15 steps

<div class="ramp">
  <span class="ramp-step" style="--c: var(--n-0)"></span>
  <span class="ramp-step" style="--c: var(--n-1)"></span>
  <span class="ramp-step" style="--c: var(--n-2)"></span>
  <span class="ramp-step" style="--c: var(--n-3)"></span>
  <span class="ramp-step" style="--c: var(--n-4)"></span>
  <span class="ramp-step" style="--c: var(--n-5)"></span>
  <span class="ramp-step" style="--c: var(--n-6)"></span>
  <span class="ramp-step" style="--c: var(--n-7)"></span>
  <span class="ramp-step" style="--c: var(--n-8)"></span>
  <span class="ramp-step" style="--c: var(--n-9)"></span>
  <span class="ramp-step" style="--c: var(--n-10)"></span>
  <span class="ramp-step" style="--c: var(--n-11)"></span>
  <span class="ramp-step" style="--c: var(--n-12)"></span>
  <span class="ramp-step" style="--c: var(--n-13)"></span>
  <span class="ramp-step" style="--c: var(--n-14)"></span>
</div>
<div class="ramp ramp-scale">
  <span>0</span><span>1</span><span>2</span><span>3</span><span>4</span>
  <span>5</span><span>6</span><span>7</span><span>8</span><span>9</span>
  <span>10</span><span>11</span><span>12</span><span>13</span><span>14</span>
</div>

Switch the theme of the table: the ramp will not change. It is raw and knows nothing of themes — what changes is only which of its steps the semantics takes.

One knob sets the direction of the cast: --hue-neutral: 75 is warm, 250 cool. A chroma of 0.002–0.006: below the threshold of conscious notice, and that is its job. The fifteenth step exists because the dark end needs four discernible surfaces in a row, and on fourteen only three fitted.

The steps with no semantics are a reserve for the application and for charts.

The accent — one hue

<div class="ramp">
  <span class="ramp-step" style="--c: var(--a-1)"></span>
  <span class="ramp-step" style="--c: var(--a-2)"></span>
  <span class="ramp-step" style="--c: var(--a-3)"></span>
  <span class="ramp-step" style="--c: var(--a-4)"></span>
  <span class="ramp-step" style="--c: var(--a-5)"></span>
  <span class="ramp-step" style="--c: var(--a-6)"></span>
</div>
<div class="ramp ramp-scale">
  <span>1</span><span>2</span><span>3</span><span>4</span><span>5</span><span>6</span>
</div>

A second accent hue is not started. That is not a feature request but a signal that the meaning ought to be carried by something else.

The hue is 215°. The lightness of --accent-solid is bounded from above by the white label, and the bound DEPENDS ON HUE: 0.545 at 215°, 0.568 at 250°, 0.576 at 275°, 0.580 at 45°. There can be no single number here — "lighter than 0.56 and the label loses 4.5:1" is the measurement of one blue. Each set holds its own bound, and the gate checks it.

The focus ring stands on steps 6 and 2 rather than 4 and 3, and that is not a third blue by oversight: the ring outlines a fill, and in the light themes step 4 is EXACTLY --accent-solid. The ring around a solid button was the colour of the button, contrast 1.00.

Statuses — three reserved hues

<div class="ramp">
  <span class="ramp-step" style="--c: var(--ok-1)"></span>
  <span class="ramp-step" style="--c: var(--ok-2)"></span>
  <span class="ramp-step" style="--c: var(--ok-3)"></span>
  <span class="ramp-step" style="--c: var(--ok-4)"></span>
  <span class="ramp-step" style="--c: var(--ok-5)"></span>
  <span class="ramp-step" style="--c: var(--ok-6)"></span>
</div>
<div class="ramp">
  <span class="ramp-step" style="--c: var(--warn-1)"></span>
  <span class="ramp-step" style="--c: var(--warn-3)"></span>
  <span class="ramp-step" style="--c: var(--warn-4)"></span>
  <span class="ramp-step" style="--c: var(--warn-5)"></span>
  <span class="ramp-step" style="--c: var(--warn-6)"></span>
</div>
<div class="ramp">
  <span class="ramp-step" style="--c: var(--err-1)"></span>
  <span class="ramp-step" style="--c: var(--err-3)"></span>
  <span class="ramp-step" style="--c: var(--err-4)"></span>
  <span class="ramp-step" style="--c: var(--err-5)"></span>
  <span class="ramp-step" style="--c: var(--err-6)"></span>
</div>
<div class="ramp ramp-scale">
  <span>1</span><span>3</span><span>4</span><span>5</span><span>6</span>
</div>

There is no step 2 in the status rows — no role has wanted it.

ok is 150°, warn 85°, err 25°. They are never used as decoration or as "a fourth series on a chart".

Step 5 exists precisely because step 4 does not pass the threshold on itself. While it was not there, a yellow badge lived on a contrast of 3.02.

Scale

One declaration per token through light-dark(). A second theme as a separate block does not exist — so there is nothing to diverge.

Surfaces

<div class="swatches">
  <div class="sw"><div class="sw-chip" style="--c: var(--surface-sunken)"></div><div class="sw-cap">--surface-sunken</div></div>
  <div class="sw"><div class="sw-chip" style="--c: var(--surface-page)"></div><div class="sw-cap">--surface-page</div></div>
  <div class="sw"><div class="sw-chip" style="--c: var(--surface-raised)"></div><div class="sw-cap">--surface-raised</div></div>
  <div class="sw"><div class="sw-chip" style="--c: var(--surface-overlay)"></div><div class="sw-cap">--surface-overlay</div></div>
  <div class="sw"><div class="sw-chip" style="--c: var(--surface-field)"></div><div class="sw-cap">--surface-field</div></div>
</div>

Switch the theme of the table — here is where everything changes. The ramp has stayed as it was, and the semantics has taken other steps of it: in a dark theme the step between neighbouring surfaces is wider, because a dark theme is not an inversion but written by hand.

They read as a stack. Depth is carried by the order of lightness and never by a shadow.

Text

Borders

Load-bearing and decorative are different tokens, because the requirements on them differ.

Tones

A tone that carries meaning has three tokens: text, mark and background.

Text and mark parted for the same reason as with the accent. Step 5 is calculated for reading, and while the tone stood in the label of a badge there was no difference. Across a full-width fill — a history bar, the arc of a ring, the ribbon of a meter — it reads darker and duller than the accent mark beside it, and the palette falls into two registers. A mark makes do with 3:1, and on step 4 every minimal mark of the library stands in one.

There is no third one — a "fill" between the text and the background. It lived on step 4 and did not pass where a track ended up under it: a yellow meter fill gave 2.49 against a norm of 3.0.

The accent has a case the statuses do not — a fill under a white label (--accent-solid and --accent-on).

Tone as an attribute

data-tone is set once on a group; the elements inside read --tone-ink, --tone-mark and --tone-bg and know nothing else about the tone.

The vocabulary is closed. A sixth value is not started.

Variants

A theme is three independent knobs: the hue of the neutral, the strength of the cast and the depth of the dark surfaces. A seventh theme costs one line.

The light ones differ by the cast, the dark ones by depth, and that is not carelessness. On a light background the eye catches temperature: warm paper and cool paper read as different. On a dark one the temperature is barely visible, while how far the panel parts from the page shows at once. The knobs differ because different things are noticed in light and in dark.

--tint is a multiplier rather than an absolute quantity: the steps of the ramp keep their own shares of the cast (weaker at the light end, stronger at the dark one), and at zero the whole row becomes grey at once. The neutral theme is not a third hue but the absence of one: any --hue-neutral at zero chroma gives one and the same grey.

<html data-theme="dark">   <!-- forced -->
<html>                     <!-- by the system setting -->

The light depth is not adjustable. At the top of the ramp the steps run close together, and a "less light" light theme is just a grey background.

The ceiling of depth

There are two dark themes, and there will be no third one upwards. Above the "grey" one the ramp stops being dark: at --n-10 even --text-muted gives 3.29 against a norm of 4.5, and a translucent tone fill, through which the panel shows, drops the label of a badge earlier still. That is exactly why dark-soft overrides the status labels along with the four surfaces — they move to step 2 of the ramp.

The categorical palette

<div class="ramp">
  <span class="ramp-step" style="--c: var(--chart-1)"></span>
  <span class="ramp-step" style="--c: var(--chart-2)"></span>
  <span class="ramp-step" style="--c: var(--chart-3)"></span>
  <span class="ramp-step" style="--c: var(--chart-4)"></span>
  <span class="ramp-step" style="--c: var(--chart-5)"></span>
  <span class="ramp-step" style="--c: var(--chart-6)"></span>
</div>
<div class="ramp ramp-scale">
  <span>1</span><span>2</span><span>3</span><span>4</span><span>5</span><span>6</span>
</div>

The lightness within the row differs. That keeps the series discernible under colour blindness and in black-and-white print, where hue disappears altogether. Squint — the order by lightness still reads.

Here colour encodes a series rather than a state — the one such place in the library. Hence the separate rules.

• The order is part of the contract. Series no. 1 is always --chart-1, otherwise one and the same measure changes colour from screen to screen.
• At least 25° from every status hue (25, 85, 150): a categorical colour must not read as "it failed". Against the accent there is no angular guarantee — it is a knob with four positions (215, 250, 275, 45), and clay stands 10° from series no. 4. In place of a guarantee, a division of territory: the accent does not step inside a chart, a categorical colour does not step outside.
• The lightness within the palette differs deliberately — the series stay discernible under colour blindness and in black-and-white print, where hue disappears altogether.
• Six is the ceiling. A seventh series means this is not a chart but a table.
• Forbidden outside a chart and its legend. There is no categorical colour in the role of a status, of a button fill or of a row highlight.

The rest

Rules

What to take and what not to

API

Related

Tokens Elevation and surfaces Badge Chart legend Metric