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. DENSITY IS AN ATTRIBUTE, NOT A LOOSE NUMBER This file used to say «because the multiplier is inherited, you can make one region denser without touching anything else: .sidebar { --space-scale: 0.85 }». That never worked. The steps below are declared on :root, so their var(--space-scale) is substituted there and every descendant inherits a resolved length; a --space-scale written further down has nothing left to multiply. Measured 17 August 2026: --space-4 came out 16px at scale 1, at 0.5 and at 2 alike. It is the same trap _contract.css records for scoped skins, and the same answer — the tokens have to be re-declared where the override is made. <aside data-density="compact">…</aside> [data-density] re-declares the whole scale, so the multiplier resolves on that element and the region below it is denser. A closed set rather than a free number, for the reason Cloudscape gives: density is a system-level decision, and a scale anyone can write anywhere compounds — 0,85 inside 0,85 is 0,72, and nobody chose that.

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. SPRINGS, AND WHY THEY ARE NOT BÉZIERS Apple's interfaces settle rather than ease. A bézier is a shape somebody drew; a spring is what the shape becomes once you have said how quickly the thing should respond and how much friction it has. The difference is not subtle at the end of the movement, which is where a bézier arrives dead and a spring arrives alive, and it is the reason a cubic-bezier(0.34, 1.56, …) — which is what this file used to ship — reads as a cartoon bounce rather than as weight. linear() is what makes the real thing expressible. Each curve below is SwiftUI's own spring, sampled: omega = 2π / response zeta = dampingFraction x(t) = 1 − e^(−ζωt)·(cos(ω_d t) + (ζω/ω_d)·sin(ω_d t)) integrated at 27 stops and cut where the curve comes within a thousandth of rest and stays there — which is also where the matching --duration-* comes from. The names are SwiftUI's, so .smooth, .snappy and .bouncy mean here what they mean there. WHICH ONE TO REACH FOR --ease-quick a press, a hover, a checkbox. 300ms response, barely overshoots. The one most interactions want. --ease-snappy a sheet, a popover, a drawer arriving. The default. --ease-smooth anything leaving. It is the only one that does not overshoot, and an exit that overshoots pushes the element back on screen for a frame before it goes. --ease-bouncy a toggle, a like, something that should feel pleased with itself. Deliberately the loudest thing here; used sparingly, per the HIG's "don't add motion for the sake of motion". tests/e2e/motion.spec.ts pins the three things about these that are invisible on screen: that every curve starts at 0 and ends at exactly 1, that the calm one does not overshoot and the bouncy one does, and that the reduced-motion preference reaches the easings and not only the durations.

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

Materials

A material is a surface that lets what is behind it show through. Apple's platforms use them to say *this is a control layer, and the content is underneath* — a toolbar, a sidebar, a sheet, a menu. The Human Interface Guidelines put it in one sentence: «By allowing color to pass through from background to foreground, a material establishes visual hierarchy to help people more easily retain a sense of place.» That is the whole reason a translucent bar is worth the trouble. It is not a decorative frosted-glass effect: it is the only cheap way for a fixed bar to tell you there is content scrolling under it rather than behind a wall. FOUR THICKNESSES, AND THE TRADE THEY MAKE The HIG names the trade explicitly, and it is the reason there is more than one: «Thicker materials, which are more opaque, can provide better contrast for text and other elements with fine features. Thinner materials, which are more translucent, can help people retain their context.» --material-ultra-thin the most context, the least contrast. Over media. --material-thin a bar over a page that is mostly text. --material-regular the default. Menus, popovers, sheets, navbars. --material-thick where a lot of small text sits on it. Sidebars. DERIVED, NOT DECLARED — AND WHY THAT IS NOT A BREACH OF RULE 5 «No runtime colour derivation» is about a theme's colours: a skin states what its blue is rather than asking the library to lighten one. The alpha here is not a colour, it is the material's thickness, which is structural and the same in every skin — so each material is the skin's own raised surface with a structural alpha over it, exactly the way elevation.css already builds every shadow from --color-shadow and a structural opacity. A skin that changes --color-surface-raised gets four correct materials for free, and one that wants different ones restates these four names. THE DEGRADATION LIVES HERE, NOT IN THE COMPONENTS This is the part worth copying. A component opts in with two lines: .navbar { --navbar-bg: var(--material-regular); backdrop-filter: var(--material-filter); } and never writes an @supports, a prefers-reduced-transparency or a [data-legacy] of its own. Four conditions turn every material back into a plain opaque surface, and they are decided once, here: 1. No backdrop-filter. A translucent bar with nothing blurring behind it is not a weaker version of the effect, it is unreadable text over whatever scrolled under it. So the base rule is opaque and the translucency arrives only inside @supports. This is the dual-branch rule from CLAUDE.md, and it is the case it was written for. 2. prefers-reduced-transparency: reduce. Settings ▸ Accessibility ▸ Display ▸ Reduce Transparency. A reader who has asked for this has asked for exactly this, and the platform honours it by making every material opaque rather than by making it slightly less see-through. 3. prefers-contrast: more. The HIG notes that materials change appearance under increased contrast; the honest answer for a library that cannot measure the content behind the glass is to stop guessing. 4. [data-legacy]. The library-wide opt out. tests/e2e/materials.spec.ts pins all four, on real components, because every one of them is a state no screenshot is taken in. SATURATION IS NOT A FLOURISH saturate(180%) next to the blur is what keeps colour alive through the material. Blur averages the pixels behind it, and averaging colours pulls them towards grey; without the boost a blue image under a white material reads as a grey smudge, which is the opposite of «allowing color to pass through». Apple's own materials do the same thing, which is why a photo under a toolbar still looks like a photo.

Source: src/css/tokens/materials.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 used to say they were deliberately not a container component, on the grounds that 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. Measured on 17 August 2026: eight consumers out of eight had written those two declarations, every one of them as .wrap, and each had grown a third the argument did not account for — padding-inline, the gutter. The class is utilities/center.css; the custom property the argument feared is what makes it worth having. 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