Colour and surface

Background

The three neutral backgrounds are a depth order, not a palette: .bg-sunken is behind the page, --bg is the page, and .bg-surface is a card lifted off it. In dark mode the order inverts in lightness and stays the same in meaning, which is the point of naming them by role.

.bg-brand and .bg-soft also set a foreground colour, because a background without a matching text colour is how you get grey-on-brand that nobody can read. .bg-soft is the tinted-but-quiet one — the fill behind a selected row or an informational callout.

Text colour

Three neutrals and four status colours. The neutrals are a hierarchy — --text for the content, .text-muted for a caption or a label, .text-faint for metadata that should be findable and not read — and the gap between them is deliberately large enough to see and small enough to keep the faint one above the contrast floor.

The status four are the 700 step of each hue rather than the 500, so they carry enough contrast on a light surface to be used as text rather than only as a fill. .text-inherit is the escape hatch: it puts a link or an icon back to whatever colour its parent is, which is what you want for a link inside a coloured alert.

Colour is never the only signal in Deck. .alert-bad has an icon, .badge-good has a word, and a chart series has a shape as well as a hue — because roughly one man in twelve cannot separate the good and bad ends of a red-green pair. If you use .text-bad to mean "this failed", something else on the row has to say so too.

Border

One hairline, in --line, which is a low-contrast neutral that reads as a division rather than as a drawn box. .border-t and .border-b set the block edges and .bis and .bie the inline ones — the inline pair is named logically because those are the two that flip.

Radius

Five steps and two logical halves. The steps are in px rather than rem on purpose: a corner radius is a physical property of the shape and should not grow when someone raises their base font size, or a 4px chip corner becomes a 5px one for no reason anybody asked for.

.r-start and .r-end round one inline side, which is how a segmented control or a button group gets rounded ends and square joins that survive a direction flip.

<div class="cluster cluster-tight">
  <span class="badge r-xs">r-xs</span>
  <span class="badge r-sm">r-sm</span>
  <span class="badge r-md">r-md</span>
  <span class="badge r-lg">r-lg</span>
  <span class="badge r-full">r-full</span>
</div>

Shadow

Four elevations and a reset. The shadow colour is a token, --shadow-color, rather than a flat black at low alpha — a black shadow over a tinted surface goes muddy, and tinting the shadow toward the surface keeps it reading as depth.

Elevation should track how far something is from the page, so a card is .shadow-1, a popover is .shadow-2, and .shadow-4 is for something being dragged. Using a large shadow on a resting element spends the whole range at once and leaves nothing to say "this is lifted".

Tone

Three classes driven by a style query rather than by their own name. Set --tone to critical, caution or clear on an element carrying .cq-tone, and every .tone-surface, .tone-text and .tone-icon inside it takes the matching colour — with no class changes on the children at all.

<article class="card cq-tone" style="--tone: caution">
  <div class="card-body tone-surface">
    <h3 class="tone-text">Payment overdue</h3>
  </div>
</article>

That matters when the tone comes from data. A server rendering a row does not have to map a status onto three class names; it writes one custom property and the stylesheet does the rest. Style queries are supported in current Chrome and Safari; where they are not, the fallback is simply the untinted appearance, which is why the rows below show a condition rather than a plain declaration.

When not to use these

• Not to build a component that already exists. .bg-surface .border .r-md .shadow-1 is a .card. The card also handles its header, its media slot and its print appearance.
• Not with a literal colour beside them. Mixing .text-muted with an inline #666 gives you an element that half-follows the theme, which is more confusing than one that does not follow it at all.
• Not as the only signal for a state. Pair a status colour with an icon or a word.
• Not .r-full on a rectangle. It is 999px, so on a wide element the ends go to semicircles. It is for a pill or a circle.