Foundations

Every skin carries twelve-step ramps for neutral, primary, and seven hues. Each step has one job, and the same job in light and dark: 1–2 backgrounds, 3–5 component fills, 6–8 borders, 9–10 solid fills, 11–12 text. A ramp derives from its --scale-{name}-seed, so one declaration retints the whole family.

Components paint roles, never a ramp step: surfaces, text, lines, and the badge families each alias a step. A skin re-values a seed or a role and every component follows. Contrast between each pairing is audited on Theme accessibility.

Two font roles, body and display, default to one sans stack. The type scale is a fixed ladder of rungs; headings carry their own line-height, weight, and tracking so a skin can re-voice them without touching components.

Canvas is the paper, background and card sit on it, and popovers float above everything. Floating surfaces and the modal overlay take their translucency and blur from the surface knobs.

Stacking follows one ladder of tiers, so layers from different components never compete: --z-raised (10), --z-sticky (20), --z-nav (30), --z-overlay (70), --z-modal (one above the overlay), --z-popup (80), --z-toast (90), and --z-tooltip (95). A part that only needs to sit above or below a sibling inside its own component uses a local z-1 or -z-1 instead of a tier.

Every shadow is one recipe scaled by a tier multiplier, then by the global size, opacity, and vertical bias knobs. Flatten a skin with --shadow-size: 0; deepen one tier by raising its multiplier.

One --radius knob drives the whole scale: each role is a multiple of it. Nested corners stay concentric through the additive tokens — --radius-popover, --radius-composer, and --nest-radius add the inset to the inner corner — and --corner-shape reshapes every corner where the browser supports it.

--control-h is the medium control height, 2.25rem by default. The extra-small, small, and large sizes are 0.78, 0.89, and 1.11 times that height, snapped to 2px, so one declaration rescales every control and the heights follow the user's font size. --spacing is the density unit: gaps and padding are multiples of it, including --popover-padding and --composer-padding. Padding knobs set the density of rounded surfaces such as bubbles and the composer.

Three tempos and two curves cover every transition. Reduced-motion settings collapse them to zero globally, so components never check the preference themselves.

The focus indicator is its own role: color, width, style, and offset. It appears on :focus-visible only, so a pointer press on a button, tab, or checkbox draws nothing, while a text field shows it on click because typing goes there next. Each control draws one indicator: fields, the composer, the message being edited, and highlighted menu items paint it on their own edge, and everything else gets a ring at --focus-ring-offset. A container that owns the ring for its parts declares data-focus-ring="within"; a field whose surface already shows where focus is, like the command palette search, declares data-focus-ring="none" and relies on the caret. It must clear 3:1 against every surface it lands on.