Tokens

Typography

Four families. Which is used where is a component decision.

Surfaces and content

Borders

Brand roles

Each with a hover, an active and a foreground.

Status roles

A solid colour, a foreground for it, and a tinted surface.

Utility

Shape

Spacing scale

Structural, not thematic: the rhythm stays the same across themes. What a theme (or a section, or a single component) may change is `--space-scale`, which multiplies the whole scale at once. That multiplier is what "density" means here — compact and comfortable are not separate features, they are `--space-scale: 0.8` and `--space-scale: 1`. Because the multiplier is inherited, you can make one region denser without touching anything else: .sidebar { --space-scale: 0.85; }

Source: src/css/tokens/spacing.css

Typographic scale

Structural: the sizes and rhythm live here and do not change per theme. The font *families* do change per theme, and are defined in themes/ instead — see themes/_contract.css for the four families every theme must provide. Sizes are fluid. Each step interpolates between a minimum and a maximum across the viewport using `vi` (the inline-axis viewport unit), so they keep working in vertical writing modes. There are no breakpoints to maintain. The clamp() minimum is always in rem so browser zoom and user font-size settings keep working — never lock a font size to a viewport unit alone.

Source: src/css/tokens/typography.css

Motion

Structural. Durations collapse to near-zero under `prefers-reduced-motion`, which is handled here once rather than in every component: as long as a component animates using these tokens, it respects the preference for free. Near-zero rather than zero, because a 0s transition never fires `transitionend`, and some components rely on that event to clean up.

Source: src/css/tokens/motion.css

Elevation

The *geometry* of each step lives here and is structural. The *colour* comes from `--color-shadow`, which every theme defines — so a dark theme gets shadows that read correctly without needing a different elevation mechanism. This deliberately keeps one mechanism across all themes. Swapping shadows for glowing borders in dark mode is a real technique, but it makes every component's elevation conditional on the theme, and that cost is not worth paying for a library that must support an unbounded number of themes. Opacity is baked into each step rather than exposed, because a shadow's alpha is not something anyone tunes independently of its blur.

Source: src/css/tokens/elevation.css

Shape roles

The radius *scale* (--radius-sm … --radius-full) is thematic and lives in themes/. These three are the semantic roles built on top of it: what a selector, a field and a box are shaped like. They are derived, so restating them in every skin would be three lines of copied boilerplate that never vary — a skin should only have to state what it actually changes. A skin may still override any of them (a brutalist skin with square boxes and pill-shaped fields is a legitimate thing to want). `:where()` keeps the specificity at zero so overriding takes nothing more than restating it. WHY THE SELECTOR IS `:where(:root, [data-skin])` AND NOT JUST `:root` Custom properties are substituted at computed-value time on the element that declares them, and the *result* is what descendants inherit. If these were declared only on `:root`, `var(--radius-md)` would resolve once against the root's scale, and a scoped skin — `<div data-skin="sepia">` inside a default page — would inherit the root's radii instead of sepia's. Re-declaring on every skinned element makes each one resolve against its own scale.

Source: src/css/tokens/shape.css

Container widths, and the floor under anything you tap

`--measure` and friends in typography.css answer "how wide should a line of text be", in `ch`, and they are about reading comfort. These answer "how wide is a content column", in `rem`, and they are about page structure. Both are design-system decisions rather than per-page ones, which is why they are tokens — unlike a gap, which is genuinely local and stays inline. They are deliberately *not* a container component. Using one is `max-inline-size: var(--container); margin-inline: auto;` — two declarations, where a class would have to expose a custom property to be reusable and you would end up writing both anyway. ON BREAKPOINTS There is no `--breakpoint-*` token, because CSS cannot use `var()` inside a media query — `@media (min-width: var(--bp-md))` does not work, and shipping a token nobody can use in the one place they want it is worse than shipping none. Prefer container queries, which need no breakpoint at all. Where a viewport media query is unavoidable, the convention is 40rem / 60rem / 80rem, written literally. TARGET SIZE — THE NUMBERS, BECAUSE THE ADVICE YOU HAVE READ IS THREE DIFFERENT NUMBERS They are not in conflict; they are different requirements, and a library has to say which one it meets: 24×24 WCAG 2.2 SC 2.5.8 Target Size (Minimum) — **level AA**, with a spacing exception: a 24px circle centred on the target may not overlap another target's circle. 44×44 WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — level **AAA**. Also Apple's HIG figure, in points. 48×48 Material, in dp. So 44 is the touch convention and the AAA bar, not the AA requirement, and a 40px control is conformant at AA. It is still the wrong default for a phone, which is what these two tokens are for. WHY THE FLOOR MOVES WITH THE POINTER A 44px row of controls is right under a thumb and wasteful under a cursor — that is the whole reason design systems sit at 36–40 and then get this review. The platform already models the difference, so nothing here has to guess: the fine-pointer values below are exactly what this library shipped before, and the coarse ones are 44. `any-pointer`, not `pointer`. A laptop with a touchscreen reports `pointer: fine` — its *primary* input is the trackpad — while `any-pointer: coarse` matches, and erring towards the larger target is the safe direction of that error. Measured in Chromium, Firefox and WebkKit: all three match `any-pointer: coarse` under touch emulation. WHAT THE `-sm` VARIANTS COST, STATED RATHER THAN IMPLIED They do not read these tokens. `.btn-sm` is 32px, `.nav-sm` and `.segmented-sm` are 28px, and that is a deliberate density decision for pointer-first interfaces — a toolbar, a data table's row actions, a settings strip on a desktop. All of them clear the AA floor of 24; none of them reaches 44. **If the control is a touch target, do not use the `-sm` variant**, or raise the component's own `--*-min-size` back to `var(--target-size)` yourself. Nothing can detect which case you are in.

Source: src/css/tokens/sizing.css