Radius, border & shadow

Twenty-four tokens covering corner radius, border width, the focus ring composite, and a six-step elevation set built from two derived tints. Every value here is a literal in tokens.css and nowhere else.

Radius

Eight steps. --radius-none is a real token rather than a bare 0, and --radius-full is a large pixel value rather than 50% — a percentage radius on a non-square box gives you an ellipse, which is almost never what a pill button wanted.

The boxes below are identical in every respect except the corner.

Border width

Four widths, in px rather than rem. A border is a hairline, not type: scaling it with the root font size makes a 1px rule land on a fractional device pixel and go grey.

There is no --border-width-3. The numbers are the pixel values, not scale positions, so the gap is information rather than an omission. --border-width-0 exists for the same reason --space-0 does: so that removing a border is still written as a token.

Border colour is not border width

The focus ring

Three tokens compose one ring. base.css applies them as an outline, not a box-shadow and not a border, so the ring never changes layout and never gets clipped by a parent's overflow.

:focus-visible {
  outline: var(--focus-ring-width) solid var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

The colour is aliased twice on purpose: --focus-ring-color → --color-focus → --color-brand. Retune --hue-brand and the focus ring follows without anyone touching this file. The middle link exists so a product that needs a focus colour distinct from its brand — a high-contrast kiosk build, for instance — has one place to break the chain, rather than having to override every ring at every call site.

Shadow

Six elevations plus --shadow-inset, built from exactly two tint tokens.

Two tints, derived not authored

Every elevation is two layered shadows: a tight, low-offset penumbra that reads as contact, and a broader, softer umbra that reads as distance. That is why --shadow-md looks like an object above a surface rather than a grey smudge behind it — one shadow alone cannot do both jobs at once.

Neither tint is hand-authored. Both are color-mix() results: a step from the neutral ramp mixed against transparent to get the alpha, wrapped in light-dark() so the dark theme can be much denser than the light one. The mix result is still a <color>, which is all light-dark() will accept.

--shadow-penumbra: light-dark(
  color-mix(in oklab, var(--color-neutral-900) 6%, transparent),
  color-mix(in oklab, var(--color-black) 30%, transparent)
);

This is the point of the whole arrangement. These two were previously the only hand-authored colours in tokens.css, which meant retuning --hue-neutral moved every grey in the system while the shadows stayed on the old hue. Deriving them from the ramp keeps a shadow the same colour family as the greys it is a shadow of, automatically.

The elevation set

Light and dark, side by side

Shadows read completely differently across themes, and this is the section that needs the two-panel treatment more than any other on the site. In light mode the elevation ladder is obvious. In dark mode it is nearly invisible: a dark shadow on a dark surface has almost nothing to contrast against, so the steps collapse into each other.

Those two panels are one page in one theme. The resolved values printed under each name are read per panel at runtime, which is why the offsets match and the tints do not.

Pair a raised surface with a shadow

The semantic surface roles are deliberately asymmetric, and the shadow tokens are the other half of that decision. See the elevation-asymmetry note on theming & dark mode for the full reasoning.

.card {
  background-color: var(--color-surface-raised);
  box-shadow: var(--shadow-md);
  border-radius: var(--radius-lg);
}