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.

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. Roles multiply from it so nested corners stay concentric, and --corner-shape reshapes every corner where the browser supports it.

--control-h is the medium control height; the other sizes derive from it. 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 shorten them 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, and highlighted menu items paint it on their own edge, and everything else gets a ring at --focus-ring-offset. It must clear 3:1 against every surface it lands on.