The system in three layers — hard tokens at the base, components built strictly from them, and the applied patterns that compose both. Each layer cites the one below it, never the reverse.

The symbol: three isometric cubes in motion forming a triangle, one cube per product. It ships as a fixed asset, and the shell renders it inside the brand tile.

The symbol

Three isometric cubes forming a triangle, in motion.

Each cube is a product. The triangle is a system — components snapping together, breaking apart, reassembling. The motion is intrinsic, not applied: the mark is an animated SVG, one vector file describing every rotation and every transition. The logo follows the same logic as the system itself — written, not decorated.

Start with the three on top, or jump to your stack. One download per tool — a small bundle with the file, the tokens/spec it needs, and a usage README inside.

Per-runtime. Pick the row that matches your tool — the first three mirror the hero cards above.

1. 01 · COWORK / CLAUDE CODE
   ANY ANTHROPIC RUNTIME

   Install the plugin, or drop the .skill bundle in.

   In Claude Code: /plugin marketplace add angelomacaione/amaca-design, then /plugin install amaca-design@amaca; it installs the skill from amaca-plugin.zip with a SHA-256 pin. In the Claude app: Settings → Capabilities → Skills → upload amaca-frontend.skill. Invoke with amaca-frontend or just describe an Amaca task — the skill auto-triggers on context.

2. 02 · FIGMA
   — AGENT SKILL

   Install it like the Claude skill, invoke /amaca-figma.

   In any Figma file: prompt box → attachment icon → Skills → Add skill → upload amaca-figma.md. Then /amaca-figma: it fetches the live spec first, generates with Amaca Variables, and self-audits in a verify loop — or audits a selection on canvas evidence. Code-side sync (tokens pushed as Variables over the Figma MCP) stays available through the amaca-frontend skill.

3. 03 · GOOGLE STITCH
   — DESIGN.MD

   Paste the spec into the project box.

   Download DESIGN.md — the spec ships in the Google Labs design.md standard. On Stitch's Start with your project screen, paste it into the existing DESIGN.md box (or upload the file). Pick the most capable model for brand fidelity.

   Frontier-tier model required. On lighter models the spec is read as passive context, not instructions — see § 03.3 capability tiers.

4. 04 · CURSOR / VS CODE / WINDSURF · CONTINUE / AIDER
   — EDITORS & ASSISTANTS

   Drop the spec at your tool's rules path.

   Where the editor installs Agent Plugins (Cursor, GitHub Copilot, VS Code, OpenAI Codex, Kiro), install amaca-plugin.zip. Otherwise unzip amaca-ide.zip at the repo root: core + per-target rules, attached only to the files they govern:

   • Cursor.cursor/rules/amaca-core.mdc · amaca-html.mdc · amaca-react.mdc
   • Cursor · Codex (skill).agents/skills/amaca-frontend/
   • VS Code (Copilot).github/copilot-instructions.md + instructions/amaca-*.instructions.md
   • Windsurf.windsurf/rules/amaca.md
   • AiderCONVENTIONS.md
   • Continuerules in config

   The runtime reads it as instructions and grounds on the spec.

   Model-gated — fidelity tracks the model behind the editor. See § 03.3.

5. 05 · GEMINI ADVANCED
   — GEMS

   Spec as knowledge, instructions as system prompt.

   Create a new Gem. Paste AI-INSTRUCTIONS.md into Instructions: it is self-contained, with the token values inlined. Upload DESIGN.md as the Gem's knowledge file for the full component specs. Save. That Gem now speaks Amaca for any frontend task.

   Frontier-tier model required. On lighter models the spec is read as passive context, not instructions — see § 03.3 capability tiers.

6. 06 · CHATGPT
   — CUSTOM GPT

   Same pattern as Gems.

   Create a Custom GPT, or a Project. AI-INSTRUCTIONS.md as instructions, DESIGN.md as knowledge file. Same result.

   Frontier-tier model required. On lighter models the spec is read as passive context, not instructions — see § 03.3 capability tiers.

7. 07 · ONE-OFF
   ANY LLM CHAT

   Attach and prefix.

   Attach AI-INSTRUCTIONS.md to the chat: about seventy lines, every token value inlined, where DESIGN.md runs to thousands. Prefix your prompt with "Use this as the canonical reference for tokens, components, and voice — generate strictly compliant frontend code." Lighter than the skill but works when nothing else does.

   Frontier-tier model required. On lighter models the spec is read as passive context, not instructions — see § 03.3 capability tiers.

8. 08 · REPLIT / LOVABLE / V0 / BOLT / BASE44
   — APP BUILDERS

   Feed the tokens, not the skill.

   Prompt-to-app builders impose their own stack (usually React + Tailwind + shadcn) and treat a pasted spec as soft context. Give them AI-INSTRUCTIONS.md as project knowledge and, where they take files, theme.css (the Tailwind @theme) as the project foundation — those travel; the enforcement workflow does not. Replit is closest (its Agent reads project files — drop a rules file). Base44 is the tightest (locked stack). Compliance is model- and platform-gated: a frontier model + tokens-as-foundation gets most of the way — verify with the § 03.3 scan.

9. 09 · NPM · CDN
   — THE WHOLE SYSTEM

   Install the package, versioned.

   npm install amaca-design, then import amaca-design/tokens.css before amaca-design/components.css. With no install, link the same two files from jsDelivr: cdn.jsdelivr.net/npm/amaca-design@5/tokens.css. The package also carries theme.css (the Tailwind v4 @theme), tokens.dtcg.json and DESIGN.md. Satoshi loads from www.amaca.design; its files are not in the package.

10. 10 · SHADCN
    — ONE COMPONENT

    Add one component, with its tokens.

    npx shadcn add https://www.amaca.design/r/button.json writes the component's CSS and an example into your project, with the tokens and the components it uses. No React and no components.json needed. Every item carries its contract in meta.amaca: usage, parts and their tokens, rules, variants. The index is /r/registry.json.

The DESIGN.md the skill bundles, and the raw download serves, is organized in the Google design.md grammar:

The skill encodes a 7-step workflow and 14 verification checks. How rigorously a model runs them depends on its reasoning, how faithfully it follows instructions and how it reads files, more than on its name: model families change every few months, so this page names tiers, not models. Judge the output, not the label.

Tailwind v4 @theme is native: tokens become first-class utilities (bg-primary-500, rounded-md) straight from tokens.css — no Google spec, no build hack. React is first-class in amaca-frontend v1.1.

Two SemVer streams, one rule each.

The magenta range. Use for primary actions, links, data emphasis, and gradients. Never for body text.

The working surface. Twelve-step scale from page bedrock to bone. Body text lives at 100; metadata at 300; edges at 700.

High-voltage cyan. Use for focus accents, highlighted states, and secondary emphasis — never as a second primary.

Deep petrol teal. Used for default badges, quiet tags, and neutral chips that shouldn’t read as brand but still need color.

Reserved for feedback only — success, warning, danger, info. Never use as decoration.

A colour with an alpha is a token colour times a tint: color-mix(in srgb, var(--hue) calc(var(--tint-*) * 100%), transparent). Seven steps, shown on --primary-500; an opacity is 0, 1 or a token. A value between two steps snaps to the nearest, the smaller at equal distance.

One row per color token: value, sanctioned use, and the misuse to refuse. The 85/10/5 law decides the proportions; this matrix decides the placements.

The display end of the scale, display to h6, one Swatch type tile each (§ 3.36): the sample in its class at full size, cropped at the end of the line, then size / leading / tracking and weight. Negative tracking is part of the voice at this size, not a tweak.

The text scale, lede to micro: the steps running copy actually uses, one Swatch type tile each. Each tile declares its size and leading — reference the token, never the number.

The Satoshi weights the system ships. One typeface carries every register — the mono voice is Satoshi too, tracked and upper-cased, never a second family.

Numbered rules for combining the scale: tracking bounds, weight pairings, the register mixes that hold. Pair inside them.

The spacing scale: a 4px grid from --s-0 to --s-32, with --s-0-5 (2px) under the first step, one Swatch space tile each (§ 3.36): the bar at 1:1 on the 4px grid. Every gap, inset, and rhythm in the system is one of these steps.

Where to reach on the scale for the common cases — icon gaps, button padding, card rhythm, section breath. The fastest route from a layout decision to its token.

The radius scale, --r-none to --r-full, one Swatch radius tile each (§ 3.36): the shape at the token’s radius, 1:1. Sub-4px hairlines are a ratified closed list (§ Shapes in the contract), not scale members.

Level 0 to 4, the menu shadow, the two brand glows and the three focus rings, one Swatch shadow tile each (§ 3.36): a surface on a section ground, where cards and popovers sit. Elevation on this ground is tonal — an inset highlight over a soft drop — never a hard outline; the rings exist only for focus and are never used as depth.

The motion vocabulary at a glance: five easings and where each belongs, one Swatch motion tile each (§ 3.36). Time runs across, position up; the ball on the right rides the curve at the dot’s height. Decel, accel and ease in-out run on the same --d-base so the curves can be compared; spring rides --d-slow, the overshoot needs the room, and soft rides it too, as a page’s entrance does. Each tile plays three times and rests on the end. The pairing rules and the durations each job usually rides are in § 09.3.

Click Replay to re-trigger animations.

Six duration tokens, each named for a job. Stat count-up is a RIGID rule: numeric stats and KPIs compose from zero to their target riding --d-draw · --ease-decel and land exactly on the final value; under reduced motion they jump straight to it.

The trigger decides the pairing: user-triggered states ride --d-quick · --ease-standard; system-triggered transitions — content entering, leaving, or moving without a direct pointer cause — ride --d-base · --ease-decel. Spatial vs Effects is a RIGID rule: every animated property has a type, and the type gates the easing. Spatial properties — transform, position, size, shape — may use any easing, including --ease-spring. Effect properties — color, background, opacity, shadow — use no-overshoot curves only; --ease-spring on an effect property is off-system, and greppable per line.

Every component that moves documents its motion in one fixed schema — same four columns everywhere, no prose specs. The Motion column accepts token pairs only; the Property column declares the type (spatial / effect) so the rule above is checkable on the row itself; the Reduced motion column uses a closed vocabulary — instant · fade-only · none — recording only how the component lands when the global kill-switch (§ 24.3) fires. Seeded with the site-canonical patterns; every new component ships its rows here — and in DESIGN.md § Motion — in the same release. Continuous loops are a ratified class: they run while the component is mounted, on per-component literal clocks — the --d-* scale describes perceived transitions, not idle rhythm. Mechanical loops ride linear (or steps), never an easing curve; every loop is ratified by its own loop row above, and a loop literal without a row is drift — the raw-duration grep exception covers exactly this list, nothing else.

Every icon as a Swatch icon tile (§ 3.36): the drawing 4× on its 16 grid with the 14 live area dashed, then at 16 and 24. The drawing is copied into the markup as it is; a drawing that is not here is not in the system. Component spec: § 3.1 in the contract.

Actions

Arrows and chevrons

Navigation and panels

Status and content

People and chat

Shapes

Various

Four steps from the size tokens. The stroke is 1.5 on the 16 grid, so it grows with the size: 1.3px at 14, 1.5 at 16, 1.9 at 20, 2.3 at 24.

The icon takes the colour of its container. The only role is muted, --obsidian-300, for decorative icons inside a field.

Beside a label, alone in a button that carries the name, and trailing. In a button the icon is 14.

One rule: copy it from the album.

The page grid — twelve columns compressing to eight, then four. Columns are page anatomy; the component grid presets in § 15.3 handle everything inside a section.

The four breakpoints with their columns and gutters. Layout changes at these widths and nowhere else.

The compositions the system ships — sidebar and content, hero three-up, editorial split — and how each reflows down the breakpoints.

Four surfaces the browser paints are styled: the scrollbars, the selection, the caret. They are not components, and everything else the browser paints stays native. Scroll the box both ways and select its text.

One shell, one active section; the grid lays out and does nothing else.

The primary button, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<button class="btn btn-primary">Primary action</button>

.btn{
  display:inline-flex;
  align-items:center;
  justify-content:center;
  gap:var(--s-2);
  font-family:var(--font-sans);
  font-size:var(--t-body);
  font-weight:500;
  letter-spacing:var(--tr-snug);
  line-height:1;
  min-height:var(--s-10);
  padding:0 var(--s-6);
  border-radius:var(--r-full);
  transition:all var(--d-quick) var(--ease-standard);
  border:var(--bw-1) solid transparent;
  white-space:nowrap;
}
.btn:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.btn-primary{
  background:var(--primary-500);
  color:var(--obsidian-050);
  border-color:var(--primary-500);
  box-shadow:var(--sh-2);
  transition:all var(--d-quick) var(--ease-standard), transform var(--d-quick) var(--ease-spring);
}
.btn-primary:hover{
  background:var(--primary-500);
  color:var(--obsidian-050);
  border-color:var(--primary-500);
  box-shadow:var(--sh-glow), var(--sh-3);
}
.btn-primary:active:not(:disabled){
  background:var(--primary-600);
  border-color:var(--primary-600);
  box-shadow:var(--sh-1);
  transform:scale(.97);
}
@media (prefers-reduced-motion: reduce){
  .btn-primary:active:not(:disabled){
    transform:none;
  }
}
.btn:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}

What the contract holds the button to, word for word from its section of DESIGN.md.

• One .btn-primary per screen. Everything else recedes.
• Touch. On a coarse pointer every .btn grows to at least 44px tall and every .btn-icon 44px wide — the § 6 floor. .btn-lg already clears it; dense desktop keeps 32.
• Focus: dual-ring (white outline + --ring-halo). Never remove outline without re-implementing focus visibility.
• States: § 3.0.1. default · hover · active · focus-visible · disabled · loading, values in the state index. loading is .is-loading on the button: the label turns transparent but keeps the width, and the loader sits at the centre — its composition is § 3.19's. disabled is the native attribute — <button disabled> — which the CSS reads as :disabled; no class produces it.
• Pressed (active). A coloured fill darkens toward --obsidian-950: the primary lands on --primary-600 (the palette's pressed step, 4.09 : 1 for its label), the danger fill on 85% --danger. A neutral fill goes one step past its hover; the outline takes the link's pressed magenta; the floating button keeps its translucent fill and darkens its edge. Only the primary moves: it gives to scale(.97) on --d-quick · --ease-spring (L8), and under reduced motion it does not move. Never a lighter fill on press (§ 6.3).
• Primary label is near-white (--obsidian-050) on --primary-500 — a ratified exception to the § 6 floor (§ 6.3, ≈ 2.8 : 1), kept on perceptual grounds. Scoped to .btn-primary; rest and hover are bounded to --primary-500 (no lighten); pressed darkens to --primary-600. The only other light label on magenta is .badge-solid (§ 6.3); never elsewhere.
• Label weight is Medium 500 — ratified 2026-06-12 after a 400 / 500 / 700 comparison. Under APCA stroke weight is a contrast input and 700 scores strongest, but at 15px the bold label shifts the button's voice; 500 keeps the register, and the legibility budget is carried by the § 6.3 pairing. Don't bold the primary label for emphasis; don't drop below 500.

The button variants, one job each. One primary per screen; everything else supports it.

A button that stays on screen while the content under it scrolls: Back in a long page, such as a case study. The fill is translucent and blurred, so the text reads through it, and it takes no height of its own. Scroll inside the frame.

Three sizes — 32, 40, 48 — and the default is the middle one. Size signals density, not importance: the variant does that.

Icon-and-label compositions, leading and trailing, and the icon-only square for toolbars where the meaning is universal. The icon-only button is named by its aria-label; the icon itself is hidden from assistive tech.

One primary per screen; the variant says how much it matters.

The link in running text, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<p>Every value is <a class="link" href="#">derived from a token</a> in the file.</p>

.link{
  color:var(--primary-400);
  text-decoration:underline;
  text-decoration-thickness:var(--bw-1);
  text-underline-offset:var(--s-1);
  border-radius:var(--r-sm);
  cursor:pointer;
  transition:color var(--d-quick) var(--ease-standard),text-decoration-thickness var(--d-quick) var(--ease-standard);
}
.link:hover{
  color:var(--primary-300);
  text-decoration-thickness:var(--bw-2);
}
.link:active{
  color:var(--primary-500);
}
.link:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
.link[aria-disabled="true"]{
  color:var(--obsidian-400);
  text-decoration-thickness:var(--bw-1);
  cursor:not-allowed;
}

What the contract holds the link to, word for word from its section of DESIGN.md.

• Choosing the variant is a rule, not a taste (RIGID). If a sentence or a paragraph holds the link, it is .link. .link-quiet is legal only when nothing around the link is running text. When in doubt, .link: an underline that is not needed costs nothing, a missing one is a WCAG failure. A .link-quiet inside a <p>, an <li> of prose or any element that carries running text is a defect, and check 60 fails it.
• Colour --primary-400, underlined at rest. The colour alone is 2.1:1 against the body text, under the 3:1 a link needs to stand out without a cue (§ 6 floor #1, WCAG 1.4.1), so the underline is not optional and not hover-only. --info is not a link colour: it belongs to status (§ 3.16).
• Underline --bw-1, offset --s-1, so it clears the descenders. It thickens to --bw-2 on hover while the colour moves to --primary-300; pressed lands on --primary-500. --primary-600 is reserved for the filled button.
• No visited state. In an application the colour of a link carries no history, and a second colour would need its own contrast pair.
• Focus: the pressable ring — outline --focus-width --obsidian-100, offset --focus-offset, --ring-halo, radius --r-sm.
• The label names the destination. "The spec", never "click here" and never a bare URL; a link that opens a file or another site says so in the label.
• Disabled is an anchor without href carrying aria-disabled="true": --obsidian-400, cursor: not-allowed. A disabled link is rare; if the destination is not available, prefer plain text.
• Not a button. A link that triggers an action on the page is a defect: it is announced as navigation and cannot be pressed with Space. Use § 3.6.
• States: § 3.0.1 — default · hover · focus-visible · active · disabled. Motion: the colour and the thickness on --d-quick · --ease-standard, in the § 8.3 index.

Underline 1px at rest, 2px on hover with the lighter colour; pressed lands on --primary-500. Component spec: § 3.7 in the contract.

No underline at rest; it appears on hover and focus. Only for a standalone link, where the position and the label already say it is a link. Inside a sentence the colour is 2.1:1 against the text, and WCAG 1.4.1 fails.

Default, hover, focus-visible, active and disabled. There is no visited state: in an application the colour of a link carries no history.

One rule: a link goes somewhere, a button does something.

The checkbox, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<label class="check"><input type="checkbox" checked> Published</label>

.check{
  display:inline-flex;
  align-items:center;
  gap:var(--s-2);
  cursor:pointer;
  font-size:var(--t-small);
  color:var(--obsidian-100);
}
.check input{
  appearance:none;
  width:var(--s-4);
  height:var(--s-4);
  border:var(--bw-1) solid var(--border-input);
  border-radius:var(--r-xs);
  background:var(--surface-field);
  display:grid;
  place-items:center;
  transition:border-color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.check input:checked{
  background:var(--primary-500);
  border-color:var(--primary-500);
}
.check input:checked::after{
  content:"";
  width:10px;
  height:6px;
  border:var(--bw-2) solid var(--obsidian-950);
  border-top:0;
  border-right:0;
  transform:rotate(-45deg) translate(1px,-1px);
}
.check input:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
.check input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.check:has(input:disabled){
  color:var(--obsidian-400);
  cursor:not-allowed;
}

What the contract holds the checkbox to, word for word from its section of DESIGN.md.

• Checkbox and radio are told apart by shape — square with a tick, circle with a dot. Never a tick in a circle, never a dot in a square.
• The switch is the only one of the three that commits on change. If the change needs a Save button, it is a checkbox.
• The whole <label> is the hit target; on mobile it must reach 44×44 (§ 6 floor #7) — pad the label, don't grow the box.
• The focus ring lives on the input, not the label, so the halo traces the control.
• A radio group has exactly one checked member at all times. A group with none is a defect, not a state.
• State matrix: § 3.0.1. Motion: § 06.4.

A square with a tick: many of many. The value applies when the form is submitted. Shape carries the meaning before colour does. What separates the three choice controls is when they commit.

Shape first: a square with a tick.

The radio, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<label class="radio"><input type="radio" name="kit-radio" checked> Everyone</label>

.radio{
  display:inline-flex;
  align-items:center;
  gap:var(--s-2);
  cursor:pointer;
  font-size:var(--t-small);
  color:var(--obsidian-100);
}
.radio input{
  appearance:none;
  width:var(--s-4);
  height:var(--s-4);
  border:var(--bw-1) solid var(--border-input);
  border-radius:var(--r-full);
  background:var(--surface-field);
  display:grid;
  place-items:center;
  transition:border-color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.radio input:checked{
  border-color:var(--primary-500);
}
.radio input:checked::after{
  content:"";
  width:8px;
  height:8px;
  border-radius:var(--r-full);
  background:var(--primary-500);
}
.radio input:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
.radio input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.radio:has(input:disabled){
  color:var(--obsidian-400);
  cursor:not-allowed;
}

What the contract holds the radio to, word for word from its section of DESIGN.md.

• Checkbox and radio are told apart by shape — square with a tick, circle with a dot. Never a tick in a circle, never a dot in a square.
• The switch is the only one of the three that commits on change. If the change needs a Save button, it is a checkbox.
• The whole <label> is the hit target; on mobile it must reach 44×44 (§ 6 floor #7) — pad the label, don't grow the box.
• The focus ring lives on the input, not the label, so the halo traces the control.
• A radio group has exactly one checked member at all times. A group with none is a defect, not a state.
• State matrix: § 3.0.1. Motion: § 06.4.

A circle with a dot: one of many, always in a named group with a default. Like the checkbox, it applies on submit.

One of many, and always one checked.

The switch, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<label class="switch"><input type="checkbox" role="switch" checked> Show dates</label>

.switch{
  display:inline-flex;
  align-items:center;
  gap:var(--s-2);
  cursor:pointer;
  font-size:var(--t-small);
  color:var(--obsidian-100);
}
.switch input{
  appearance:none;
  width:var(--s-8);
  height:calc(var(--s-4) + var(--s-0-5));
  background:var(--obsidian-700);
  border-radius:var(--r-full);
  position:relative;
  transition:background var(--d-quick) var(--ease-standard);
}
.switch input::after{
  content:"";
  position:absolute;
  top:var(--s-0-5);
  left:var(--s-0-5);
  width:14px;
  height:14px;
  background:var(--obsidian-200);
  border-radius:var(--r-full);
  transition:left var(--d-base) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.switch input:checked{
  background:var(--primary-500);
}
.switch input:checked::after{
  left:var(--s-4);
  background:var(--obsidian-950);
}
.switch input:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
.switch input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.switch:has(input:disabled){
  color:var(--obsidian-400);
  cursor:not-allowed;
}

What the contract holds the switch to, word for word from its section of DESIGN.md.

• Checkbox and radio are told apart by shape — square with a tick, circle with a dot. Never a tick in a circle, never a dot in a square.
• The switch is the only one of the three that commits on change. If the change needs a Save button, it is a checkbox.
• The whole <label> is the hit target; on mobile it must reach 44×44 (§ 6 floor #7) — pad the label, don't grow the box.
• The focus ring lives on the input, not the label, so the halo traces the control.
• A radio group has exactly one checked member at all times. A group with none is a defect, not a state.
• State matrix: § 3.0.1. Motion: § 06.4.

A track with a knob: the only choice control that applies immediately, on change.

The fill carries the state, never a stroke.

The slider, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="slider"><div class="slider-head"><label class="label" for="kit-slider">Volume</label><output class="slider-value" for="kit-slider">40</output></div><input class="slider-input" id="kit-slider" type="range" min="0" max="100" value="40" style="--p:40%"><div class="slider-scale"><span>0</span><span>100</span></div></div>

.label{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--obsidian-300);
}
.slider{
  display:flex;
  flex-direction:column;
  gap:var(--s-2);
}
.slider-head{
  display:flex;
  align-items:baseline;
  justify-content:space-between;
  gap:var(--s-3);
}
.slider-value{
  color:var(--obsidian-100);
  font-size:var(--t-small);
  font-variant-numeric:tabular-nums;
}
.slider-scale{
  display:flex;
  justify-content:space-between;
  color:var(--obsidian-300);
  font-size:var(--t-caption);
  font-variant-numeric:tabular-nums;
}
.slider-input{
  -webkit-appearance:none;
  appearance:none;
  display:block;
  width:100%;
  height:var(--s-8);
  margin:0;
  padding:0;
  background:transparent;
  cursor:pointer;
  outline:none;
}
.slider-input::-webkit-slider-runnable-track{
  height:var(--s-1);
  border-radius:var(--r-full);
  background:linear-gradient(to right,var(--primary-500) var(--p,0%),var(--obsidian-600) var(--p,0%));
}
.slider-input::-moz-range-track{
  height:var(--s-1);
  border-radius:var(--r-full);
  background:linear-gradient(to right,var(--primary-500) var(--p,0%),var(--obsidian-600) var(--p,0%));
}
.slider-input::-webkit-slider-thumb{
  -webkit-appearance:none;
  appearance:none;
  box-sizing:border-box;
  width:var(--s-5);
  height:var(--s-5);
  margin-top:calc((var(--s-1) - var(--s-5)) / 2);
  border:var(--bw-2) solid var(--obsidian-950);
  border-radius:var(--r-full);
  background:var(--obsidian-100);
  box-shadow:var(--sh-1);
  transition:box-shadow var(--d-quick) var(--ease-standard);
}
.slider-input::-moz-range-thumb{
  box-sizing:border-box;
  width:var(--s-5);
  height:var(--s-5);
  border:var(--bw-2) solid var(--obsidian-950);
  border-radius:var(--r-full);
  background:var(--obsidian-100);
  box-shadow:var(--sh-1);
  transition:box-shadow var(--d-quick) var(--ease-standard);
}
.slider-input:hover::-webkit-slider-thumb{
  box-shadow:var(--ring-field);
}
.slider-input:hover::-moz-range-thumb{
  box-shadow:var(--ring-field);
}
.slider-input:focus-visible::-webkit-slider-thumb{
  box-shadow:var(--ring-halo);
}
.slider-input:focus-visible::-moz-range-thumb{
  box-shadow:var(--ring-halo);
}
.slider-input:active{
  cursor:grabbing;
}
.slider-input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
@media (prefers-reduced-motion:reduce){
  .slider-input::-webkit-slider-thumb, .slider-input::-moz-range-thumb{
    transition:none;
  }
}
.slider{
  width:min(100%, calc(var(--s-32) * 2));
}

What the contract holds the slider to, word for word from its section of DESIGN.md.

• Count the steps, not the values. The unit is the step: (max − min) ÷ step is the number of positions. Fewer than about ten → Radio or Select. More than a few hundred, or a value the reader has to hit exactly → a number typed in a Text input. 0 to 100 in steps of 5 is 20 positions.
• Native underneath. Arrow keys move one step, Page Up and Page Down a larger one, Home and End go to the ends. The value goes with the form under the input's name.
• A range starts on a selection, not on the whole scale. Each thumb is its own input with its own aria-label ("Minimum price", "Maximum price"), and the pair is a role="group" named by the visible label. The lower thumb cannot pass the upper one; they can meet.
• The value is always shown. In .slider-value, beside the label; the minimum and the maximum sit in .slider-scale. A slider with no visible value is a guess.
• The fill is the script's. --p on the input (single), --lo and --hi on the pair (range), as percentages of the scale. Without the script the control still works and the fill is absent.
• No error state. The value is always inside the scale. A slider that cannot be changed is disabled.
• Targets (WCAG 2.5.8). The thumb is 20px and the whole 32px row takes the pointer, so a click on the track moves the nearest thumb.
• Motion. The ring on the thumb changes on --d-quick · --ease-standard, none under reduced motion (§ 06.4).

A label, the value beside it, the scale under the track. The fill runs from the start to the handle. Arrow keys move one step, Page Up and Page Down ten, Home and End go to the ends. The last one is disabled.

Two handles on one track, each its own range input with its own name. The lower cannot pass the upper; they can meet. A range starts on a selection inside the scale, not on the whole of it.

Count the steps, not the values.

The text input, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<label class="field"><span class="label">Email</span><input class="input" type="email" placeholder="you@studio"><span class="help">We never share it.</span></label>

.field{
  display:flex;
  flex-direction:column;
  gap:var(--s-1);
}
.label{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--obsidian-300);
}
.input{
  background:var(--surface-field);
  border:var(--bw-1) solid var(--border-input);
  border-radius:var(--r-md);
  color:var(--obsidian-100);
  min-height:var(--s-10);
  padding:var(--s-2) var(--s-3);
  font-family:var(--font-sans);
  font-size:var(--t-small);
  outline:none;
  transition:all var(--d-quick) var(--ease-standard);
  width:100%;
}
.input:hover:not(:focus):not(:disabled):not([readonly]):not([aria-invalid="true"]){
  border-color:var(--obsidian-300);
}
.input:focus{
  border-color:var(--primary-500);
  box-shadow:var(--ring-field);
}
.input[aria-invalid="true"]{
  border-color:var(--danger);
}
.input[aria-invalid="true"]:focus{
  border-color:var(--danger);
  box-shadow:var(--ring-field-danger);
}
.input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.input[readonly]{
  background:var(--obsidian-900);
  color:var(--obsidian-300);
}
.input::placeholder{
  color:var(--obsidian-300);
}
.input[type="search"]::-webkit-search-cancel-button, .input[type="search"]::-webkit-search-decoration{
  -webkit-appearance:none;
  appearance:none;
}
.help{
  font-size:var(--t-caption);
  color:var(--obsidian-300);
}

What the contract holds the text input to, word for word from its section of DESIGN.md.

• Labels are mono-uppercase, --t-micro, --obsidian-300 — the neutral mono register (§ Typography); they took it first, for legibility over dark fields, and v5.2.0 gave it to every neutral label. Always persistent — placeholder is not a label.
• Height --s-10, declared. min-height: var(--s-10), block padding --s-2, type --t-small: a single-line field is 40px, the height of the default button beside it (§ 3.6). The height is the token, not a sum of paddings.
• Helper text is .help; the error variant is .help.error.
• Error is marked with aria-invalid="true" — the border and the helper text both follow from it. Colour alone never says "error" (§ 6 floor #1).
• States: § 3.0.1. default · hover · focus-visible · error · disabled · readonly, values in the state index (hover is the field's outline, one step lighter, and the .input-action's; error is not a search state). No state is described in prose here.
• Icon left. A .icon as a direct child of .input-wrap: decorative (aria-hidden), --icon-sm, --obsidian-300, no click. The field pads --s-8 on the left to clear it.
• Action right. .input-action: a <button type="button"> last in the .input-wrap, 32px square, --r-sm, --icon-sm, --obsidian-300 and --obsidian-100 on hover. The field pads --s-10 on the right. It carries an aria-label: it has no text. The date picker and the time picker use this same part (§ 3.13).
• Clear. An .input-action with data-input-clear and the x of § 3.1. It is visible only while the field has a value (:placeholder-shown, so the field needs a placeholder) and hidden when the field is disabled or readonly. Clicking it empties the field, fires input and gives the focus back to the field.
• Search. The field sits in <form role="search"> with type="search", so Enter submits natively. The browser's own clear button is removed: there is one. A search has no error state: no results is a result and is shown where the results go, never on the field.

Text, search and textarea, each with a persistent label and the helper text below. States live in the contract’s state matrix; error is aria-invalid, never color alone.

The icon on the left says what the field is for; the clear button on the right appears once there is something to clear. Enter submits the form. Type in the first one to try it. A search has no error state: no results is a result, shown where the results go.

A label that stays; an error said in words.

The select, its menu laid open apart from the field, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="field"><span class="label" id="kit-select-label">Status</span><div class="select-wrap"><button type="button" class="select select-trigger" aria-haspopup="listbox" aria-expanded="false" aria-labelledby="kit-select-label"><span class="select-value">Published</span></button><ul class="select-menu" role="listbox" aria-labelledby="kit-select-label" hidden><li class="select-option" role="option" aria-selected="false"><span class="select-option-label">Draft</span><svg class="icon select-check" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 8.5l3 3 7-7.5"/></svg></li><li class="select-option" role="option" aria-selected="false"><span class="select-option-label">Pending</span><svg class="icon select-check" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 8.5l3 3 7-7.5"/></svg></li><li class="select-option" role="option" aria-selected="true"><span class="select-option-label">Published</span><svg class="icon select-check" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 8.5l3 3 7-7.5"/></svg></li><li class="select-option" role="option" aria-selected="false"><span class="select-option-label">Archived</span><svg class="icon select-check" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 8.5l3 3 7-7.5"/></svg></li></ul></div></div>

.field{
  display:flex;
  flex-direction:column;
  gap:var(--s-1);
}
.label{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--obsidian-300);
}
.select{
  background:var(--surface-field);
  border:var(--bw-1) solid var(--border-input);
  border-radius:var(--r-md);
  color:var(--obsidian-100);
  min-height:var(--s-10);
  padding:var(--s-2) var(--s-3);
  font-family:var(--font-sans);
  font-size:var(--t-small);
  outline:none;
  transition:all var(--d-quick) var(--ease-standard);
  width:100%;
}
.select{
  appearance:none;
  -webkit-appearance:none;
  -moz-appearance:none;
  padding-right:var(--s-8);
  background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%238A94A3' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M3 6l5 5 5-5'/%3E%3C/svg%3E");
  background-repeat:no-repeat;
  background-position:right var(--s-3) center;
  background-size:var(--icon-xs) var(--icon-xs);
}
.select-wrap{
  position:relative;
  width:100%;
}
.select-trigger{
  display:flex;
  align-items:center;
  justify-content:flex-start;
  text-align:left;
  cursor:pointer;
  width:100%;
}
.select-trigger[aria-expanded="true"]{
  border-color:var(--primary-500);
  box-shadow:var(--ring-field);
}
.select-value{
  flex:1;
  color:var(--obsidian-100);
}
.select-menu{
  position:absolute;
  top:calc(100% + var(--s-1));
  left:0;
  right:0;
  margin:0;
  padding:var(--s-1);
  list-style:none;
  background:var(--obsidian-850);
  border:var(--bw-1) solid var(--obsidian-700);
  border-radius:var(--r-md);
  box-shadow:var(--sh-menu);
  z-index:var(--z-menu);
  max-height:240px;
  overflow:auto;
}
.select-menu[hidden]{
  display:none;
}
.select-option{
  display:flex;
  align-items:center;
  gap:var(--s-2);
  min-width:0;
  padding:var(--s-2);
  border-radius:calc(var(--r-md) - var(--r-xs));
  font-family:var(--font-sans);
  font-size:var(--t-small);
  color:var(--obsidian-100);
  cursor:pointer;
  transition:background var(--d-quick) var(--ease-standard);
}
.select-option:hover, .select-option:focus-visible{
  background:var(--obsidian-800);
  outline:none;
}
.select-option[aria-selected="true"]{
  color:var(--primary-400);
}
.select-option-label{
  flex:1;
  min-width:0;
  overflow:hidden;
  text-overflow:ellipsis;
  white-space:nowrap;
}
.select-check{
  width:var(--icon-xs);
  height:var(--icon-xs);
  visibility:hidden;
}
.select-option > .select-check{
  color:inherit;
}
.select-option[aria-selected="true"] .select-check{
  visibility:visible;
}
.select-option[aria-disabled="true"]{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.select-option[aria-disabled="true"]:hover{
  background:transparent;
}
@supports (appearance: base-select){
  select.select, select.select::picker(select){
    appearance:base-select;
  }
  select.select{
    line-height:normal;
  }
  select.select::picker-icon{
    display:none;
  }
  select.select::picker(select){
    position-try-order:normal;
    position-try-fallbacks:flip-block;
    margin-block:var(--s-1);
    padding:var(--s-1);
    max-height:240px;
    overflow:auto;
    background:var(--obsidian-850);
    border:var(--bw-1) solid var(--obsidian-700);
    border-radius:var(--r-md);
    box-shadow:var(--sh-menu);
  }
  select.select option{
    padding:var(--s-2);
    border-radius:calc(var(--r-md) - var(--r-xs));
    font-family:var(--font-sans);
    font-size:var(--t-small);
    color:var(--obsidian-100);
    cursor:pointer;
    transition:background var(--d-quick) var(--ease-standard);
  }
  select.select option::checkmark{
    display:none;
  }
  select.select option:hover, select.select option:focus-visible{
    background:var(--obsidian-800);
    outline:none;
  }
  select.select option:checked{
    color:var(--primary-400);
  }
}
.select:hover:not(:focus):not(:disabled):not([aria-invalid="true"]){
  border-color:var(--obsidian-300);
}
.select:focus{
  border-color:var(--primary-500);
  box-shadow:var(--ring-field);
}
.select[aria-invalid="true"]{
  border-color:var(--danger);
}
.select[aria-invalid="true"]:focus{
  border-color:var(--danger);
  box-shadow:var(--ring-field-danger);
}
.select:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.select-trigger:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
@media (prefers-reduced-motion: reduce){
  .select-menu{
    transition:none !important;
  }
}

What the contract holds the select to, word for word from its section of DESIGN.md.

• aria-expanded on .select-trigger toggles "true"/"false"; open state activates the magenta border + glow (same focus treatment as .input:focus).
• Keyboard focus on the trigger is the pressable ring, not the field glow: the .input .textarea .select | focus-visible row of the state index does not apply to .select-trigger, which has its own row — a trigger is pressed, not typed into. The magenta border stays, from .select:focus.
• .select-menu placement is viewport-aware: open below the trigger by default; flip above only when the menu's height does not fit below and above offers more room; max-height = min(240px, room on the chosen side), with internal scroll beyond it — measure the menu's natural height with getBoundingClientRect() rounded up (not scrollHeight, which rounds and skips the border), and scroll only when the menu is really shortened; clamp horizontally to the viewport. The menu never covers adjacent content (e.g. a chat composer the control sits above). Use position:fixed measured from the trigger's rect (.select-menu.is-fixed) when the control may sit near a viewport edge or above important content. A transformed ancestor becomes the containing block of a fixed element, so measure where (0,0) lands and subtract it; position:absolute; top:calc(100% + 4px); left:0; right:0 is acceptable only when there is always room below. Background --obsidian-850 (or --obsidian-900 for an elevated overlay); hidden attribute used to dismiss (do not toggle display directly).
• The panel never transitions. Its box is measured and written by script at open; under reduced motion the global 0.01ms rule gives every property a transition, and a script that reads the start of one places the panel off screen. .select-menu carries transition:none inside the reduced-motion override (v5.0.0).
• .select-option[aria-selected="true"] is rendered in --primary-400, with a check after the label (.select-check, the album's check, 14px) in the colour of the text. The check's room is reserved on every row, so labels never move when the choice changes. Hover/focus background is --obsidian-800.
• Only one menu open at a time — opening one closes any other open .select-menu.
• Enter/Space/↓ on trigger opens.
• ↓/↑ navigate options; Home/End jump to the first and last; no wrap from the last to the first. First open lands on the currently selected option (aria-selected="true"), or the first if none.
• A printable character jumps to the next option that starts with the letters typed (typeahead, 500ms).
• Enter/Space on focused option commits + closes; trigger receives focus back.
• Esc closes without committing; trigger receives focus back.
• Tab from open menu closes and proceeds.
• Click outside the wrapper closes the menu.
• A fixed-position (viewport-aware) menu also closes on resize, and on a page scroll that moves the trigger. Its anchored coordinates would otherwise drift from the trigger. Scrolling inside the menu never closes it.
• Window blur does not auto-close (browser-quirk; leave the menu, let the next click handle it).

The native <select> for short lists, the custom listbox when options need a look of their own. The chosen option keeps the magenta text and gains a check after its label; a disabled option stays visible and the arrow keys skip it. Both open below the trigger and flip only when there is no room.

A number set without typing it. The field is the same; the panel holds one Slider, with one handle or two, and the field shows the value while it moves. Esc puts back the value the panel opened with.

Actions behind a labelled button or a kebab. The same panel and row, with an icon in front and a shortcut after; the destructive action comes last, after a divider. A kebab at the end of a row opens inward.

A long list splits into named groups: a heading in the grammar of the label, a full-bleed divider between groups. Typing a letter jumps to the next option that starts with it.

A choice stays, an action runs, a number slides. The panel finds its own room.

The time input, its wheel laid open apart from the field, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="field"><label class="label" for="kit-time">Time</label><div class="tp-wrap"><div class="input-wrap"><input class="input" id="kit-time" type="text" value="18:00"><button type="button" class="input-action" aria-label="Open time picker"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="8" cy="8" r="6.25"/><path d="M8 4.75V8l2.25 1.5"/></svg></button></div><div class="tp-popover" hidden><div class="tp-wheels"><div class="tp-wheel"><div class="tp-wheel-list"><div class="tp-wheel-item">16</div><div class="tp-wheel-item">17</div><div class="tp-wheel-item is-active">18</div><div class="tp-wheel-item">19</div><div class="tp-wheel-item">20</div></div></div><span class="tp-sep">:</span><div class="tp-wheel"><div class="tp-wheel-list"><div class="tp-wheel-item">50</div><div class="tp-wheel-item">55</div><div class="tp-wheel-item is-active">00</div><div class="tp-wheel-item">05</div><div class="tp-wheel-item">10</div></div></div></div></div></div></div>

.field{
  display:flex;
  flex-direction:column;
  gap:var(--s-1);
}
.label{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--obsidian-300);
}
.input{
  background:var(--surface-field);
  border:var(--bw-1) solid var(--border-input);
  border-radius:var(--r-md);
  color:var(--obsidian-100);
  min-height:var(--s-10);
  padding:var(--s-2) var(--s-3);
  font-family:var(--font-sans);
  font-size:var(--t-small);
  outline:none;
  transition:all var(--d-quick) var(--ease-standard);
  width:100%;
}
.input:hover:not(:focus):not(:disabled):not([readonly]):not([aria-invalid="true"]){
  border-color:var(--obsidian-300);
}
.input:focus{
  border-color:var(--primary-500);
  box-shadow:var(--ring-field);
}
.input[aria-invalid="true"]{
  border-color:var(--danger);
}
.input[aria-invalid="true"]:focus{
  border-color:var(--danger);
  box-shadow:var(--ring-field-danger);
}
.input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.input[readonly]{
  background:var(--obsidian-900);
  color:var(--obsidian-300);
}
.input::placeholder{
  color:var(--obsidian-300);
}
.input-wrap{
  position:relative;
  width:100%;
}
.input-wrap:has(> .input-action) .input{
  padding-right:var(--s-10);
}
.input[type="search"]::-webkit-search-cancel-button, .input[type="search"]::-webkit-search-decoration{
  -webkit-appearance:none;
  appearance:none;
}
.input-action{
  position:absolute;
  right:var(--s-1);
  top:50%;
  transform:translateY(-50%);
  display:grid;
  place-items:center;
  width:var(--s-8);
  height:var(--s-8);
  border:0;
  background:transparent;
  cursor:pointer;
  color:var(--obsidian-300);
  border-radius:var(--r-sm);
  transition:color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.input-action:hover{
  color:var(--obsidian-100);
  background:var(--obsidian-800);
}
.input-action:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--s-px);
  box-shadow:var(--ring-halo);
  color:var(--obsidian-100);
}
.input:placeholder-shown ~ .input-action[data-input-clear], .input[readonly] ~ .input-action[data-input-clear], .input:disabled ~ .input-action{
  visibility:hidden;
}
.tp-wrap{
  position:relative;
}
.tp-popover{
  position:absolute;
  top:calc(100% + var(--s-1));
  left:0;
  width:200px;
  background:var(--obsidian-900);
  border:var(--bw-1) solid var(--obsidian-700);
  border-radius:var(--r-lg);
  box-shadow:var(--sh-3);
  padding:var(--s-3);
  z-index:var(--z-popover);
  font-family:var(--font-sans);
  opacity:0;
  transform:translateY(-4px);
  pointer-events:none;
  transition:opacity var(--d-quick) var(--ease-accel), transform var(--d-quick) var(--ease-accel);
}
.tp-popover.is-open{
  opacity:1;
  transform:translateY(0);
  pointer-events:auto;
  transition:opacity var(--d-quick) var(--ease-decel), transform var(--d-quick) var(--ease-decel);
}
.tp-popover[hidden]{
  display:none;
}
.tp-wheels{
  position:relative;
  display:grid;
  grid-template-columns:1fr auto 1fr;
  align-items:center;
  height:calc(28px * 7);
  --tp-item-h:28px;
  --tp-visible:7;
  --tp-center:3;
}
.tp-sep{
  font-family:var(--font-sans);
  font-size:var(--t-lead);
  font-weight:600;
  color:var(--obsidian-300);
  padding:0 var(--s-1);
}
.tp-wheels::before{
  content:"";
  position:absolute;
  left:0;
  right:0;
  top:calc(var(--tp-item-h) * var(--tp-center));
  height:var(--tp-item-h);
  background:color-mix(in srgb, var(--primary-500) calc(var(--tint-fill) * 100%), transparent);
  border-top:var(--bw-1) solid color-mix(in srgb, var(--primary-500) calc(var(--tint-glow) * 100%), transparent);
  border-bottom:var(--bw-1) solid color-mix(in srgb, var(--primary-500) calc(var(--tint-glow) * 100%), transparent);
  pointer-events:none;
  border-radius:var(--r-sm);
}
.tp-wheels::after{
  content:"";
  position:absolute;
  inset:0;
  background:linear-gradient(180deg, var(--obsidian-900) 0%, color-mix(in srgb, var(--obsidian-900) calc(var(--tint-strong) * 100%), transparent) 14%, transparent 36%, transparent 64%, color-mix(in srgb, var(--obsidian-900) calc(var(--tint-strong) * 100%), transparent) 86%, var(--obsidian-900) 100%);
  pointer-events:none;
  border-radius:var(--r-sm);
}
.tp-wheel{
  height:100%;
  overflow-y:scroll;
  scroll-snap-type:y mandatory;
  scrollbar-width:none;
  -ms-overflow-style:none;
  scroll-behavior:smooth;
}
.tp-wheel::-webkit-scrollbar{
  display:none;
}
.tp-wheel-list{
  padding:calc(var(--tp-item-h) * var(--tp-center)) 0;
}
.tp-wheel-item{
  height:var(--tp-item-h);
  display:grid;
  place-items:center;
  font-family:var(--font-sans);
  font-size:var(--t-small);
  font-variant-numeric:tabular-nums;
  color:var(--obsidian-300);
  scroll-snap-align:center;
  scroll-snap-stop:always;
  cursor:pointer;
  transition:color var(--d-quick) var(--ease-standard), font-weight var(--d-quick) var(--ease-standard);
}
.tp-wheel-item.is-active{
  color:var(--obsidian-100);
  font-weight:600;
}
.tp-wheel:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:calc(-1 * var(--s-0-5));
  box-shadow:var(--ring-halo);
  border-radius:var(--r-sm);
}
@media (prefers-reduced-motion: reduce){
  .tp-popover, .tp-wheel-item{
    transition:none;
  }
  .tp-wheel{
    scroll-behavior:auto;
  }
  .input-action{
    transition:none;
  }
}
.tp-wheel-item:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
.tp-popover{
  display:block;
}
.tp-popover{
  position:static;
  margin-top:var(--s-6);
  max-height:none;
  opacity:1;
  transform:none;
  pointer-events:auto;
}

What the contract holds the time input to, word for word from its section of DESIGN.md.

• maxlength="5" and inputmode="numeric" are required.
• Optional by default; a context can make it required.
• No type="time": the native picker does not follow the system.
• Focus and error follow § 3.10.

HH:MM, 24h. Auto-formats as you type — the colon is inserted after the second digit, and each position is bounded so an invalid time is impossible to enter. No type="time": the native picker doesn't respect the system.

Typed, and formatted as it is typed.

The date picker, its calendar laid open apart from the field, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="field"><label class="label" for="kit-date">Date</label><div class="dp-wrap"><div class="input-wrap"><input class="input" id="kit-date" type="text" value="18/08/2026"><button type="button" class="input-action" aria-label="Open calendar"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><rect x="2" y="3" width="12" height="11" rx="1.75"/><path d="M2 6.5h12M5 1.75v2.75M11 1.75v2.75"/></svg></button></div><div class="dp-popover" role="dialog" aria-label="August 2026" hidden><div class="dp-header"><button class="dp-nav" type="button" aria-label="Previous month"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M10 3L5 8l5 5"/></svg></button><button class="dp-title" type="button">August 2026</button><button class="dp-nav" type="button" aria-label="Next month"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M6 3l5 5-5 5"/></svg></button></div><div class="dp-dow"><span>M</span><span>T</span><span>W</span><span>T</span><span>F</span><span>S</span><span>S</span></div><div class="dp-grid"><button class="dp-day" type="button">1</button><button class="dp-day" type="button">2</button><button class="dp-day" type="button">3</button><button class="dp-day" type="button">4</button><button class="dp-day" type="button">5</button><button class="dp-day" type="button">6</button><button class="dp-day" type="button">7</button><button class="dp-day" type="button">8</button><button class="dp-day" type="button">9</button><button class="dp-day" type="button">10</button><button class="dp-day" type="button">11</button><button class="dp-day is-today" type="button">12</button><button class="dp-day" type="button">13</button><button class="dp-day" type="button">14</button><button class="dp-day" type="button">15</button><button class="dp-day" type="button">16</button><button class="dp-day" type="button">17</button><button class="dp-day" type="button" aria-selected="true">18</button><button class="dp-day" type="button">19</button><button class="dp-day" type="button">20</button><button class="dp-day" type="button">21</button><button class="dp-day" type="button">22</button><button class="dp-day" type="button">23</button><button class="dp-day" type="button">24</button><button class="dp-day" type="button">25</button><button class="dp-day" type="button">26</button><button class="dp-day" type="button">27</button><button class="dp-day" type="button">28</button></div></div></div></div>

.field{
  display:flex;
  flex-direction:column;
  gap:var(--s-1);
}
.label{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--obsidian-300);
}
.input{
  background:var(--surface-field);
  border:var(--bw-1) solid var(--border-input);
  border-radius:var(--r-md);
  color:var(--obsidian-100);
  min-height:var(--s-10);
  padding:var(--s-2) var(--s-3);
  font-family:var(--font-sans);
  font-size:var(--t-small);
  outline:none;
  transition:all var(--d-quick) var(--ease-standard);
  width:100%;
}
.input:hover:not(:focus):not(:disabled):not([readonly]):not([aria-invalid="true"]){
  border-color:var(--obsidian-300);
}
.input:focus{
  border-color:var(--primary-500);
  box-shadow:var(--ring-field);
}
.input[aria-invalid="true"]{
  border-color:var(--danger);
}
.input[aria-invalid="true"]:focus{
  border-color:var(--danger);
  box-shadow:var(--ring-field-danger);
}
.input:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
}
.input[readonly]{
  background:var(--obsidian-900);
  color:var(--obsidian-300);
}
.input::placeholder{
  color:var(--obsidian-300);
}
.input-wrap{
  position:relative;
  width:100%;
}
.input-wrap:has(> .input-action) .input{
  padding-right:var(--s-10);
}
.input[type="search"]::-webkit-search-cancel-button, .input[type="search"]::-webkit-search-decoration{
  -webkit-appearance:none;
  appearance:none;
}
.input-action{
  position:absolute;
  right:var(--s-1);
  top:50%;
  transform:translateY(-50%);
  display:grid;
  place-items:center;
  width:var(--s-8);
  height:var(--s-8);
  border:0;
  background:transparent;
  cursor:pointer;
  color:var(--obsidian-300);
  border-radius:var(--r-sm);
  transition:color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.input-action:hover{
  color:var(--obsidian-100);
  background:var(--obsidian-800);
}
.input-action:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--s-px);
  box-shadow:var(--ring-halo);
  color:var(--obsidian-100);
}
.input:placeholder-shown ~ .input-action[data-input-clear], .input[readonly] ~ .input-action[data-input-clear], .input:disabled ~ .input-action{
  visibility:hidden;
}
.dp-wrap{
  position:relative;
}
.dp-popover{
  position:absolute;
  top:calc(100% + var(--s-1));
  left:0;
  width:280px;
  background:var(--obsidian-900);
  border:var(--bw-1) solid var(--obsidian-700);
  border-radius:var(--r-lg);
  box-shadow:var(--sh-3);
  padding:var(--s-3);
  z-index:var(--z-popover);
  font-family:var(--font-sans);
  opacity:0;
  transform:translateY(-4px);
  pointer-events:none;
  transition:opacity var(--d-quick) var(--ease-accel), transform var(--d-quick) var(--ease-accel);
}
.dp-popover[hidden]{
  display:none;
}
.dp-header{
  display:flex;
  align-items:center;
  justify-content:space-between;
  padding:var(--s-1) var(--s-1) var(--s-2);
}
.dp-title{
  flex:1;
  display:flex;
  align-items:center;
  justify-content:center;
  gap:var(--s-1);
  background:transparent;
  border:0;
  cursor:pointer;
  font-family:var(--font-sans);
  font-size:var(--t-small);
  font-weight:600;
  color:var(--obsidian-100);
  letter-spacing:var(--tr-snug);
  padding:var(--s-1) var(--s-2);
  border-radius:var(--r-sm);
  transition:background var(--d-quick) var(--ease-standard);
}
.dp-title:hover{
  background:var(--obsidian-800);
}
.dp-title:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--s-px);
  box-shadow:var(--ring-halo);
}
.dp-title svg{
  width:var(--icon-xs);
  height:var(--icon-xs);
  color:var(--obsidian-400);
  transition:transform var(--d-quick) var(--ease-standard);
}
.dp-popover[data-mode="years"] .dp-title svg{
  transform:rotate(180deg);
}
.dp-nav{
  display:grid;
  place-items:center;
  width:28px;
  height:28px;
  border:0;
  background:transparent;
  cursor:pointer;
  color:var(--obsidian-300);
  border-radius:var(--r-sm);
  transition:color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.dp-nav:hover:not(:disabled){
  color:var(--obsidian-100);
  background:var(--obsidian-800);
}
.dp-nav:disabled{
  color:var(--obsidian-500);
  cursor:not-allowed;
}
.dp-nav:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--s-px);
  box-shadow:var(--ring-halo);
}
.dp-nav svg{
  width:var(--icon-xs);
  height:var(--icon-xs);
}
.dp-dow{
  display:grid;
  grid-template-columns:repeat(7,1fr);
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  color:var(--obsidian-500);
  text-align:center;
  padding:var(--s-1) 0;
  margin-bottom:var(--s-0-5);
}
.dp-dow span{
  padding:var(--s-1) 0;
}
.dp-grid{
  display:grid;
  grid-template-columns:repeat(7,1fr);
  gap:var(--s-0-5);
}
.dp-day{
  display:grid;
  place-items:center;
  height:var(--s-8);
  border:0;
  background:transparent;
  cursor:pointer;
  font-family:var(--font-sans);
  font-size:var(--t-small);
  font-variant-numeric:tabular-nums;
  color:var(--obsidian-100);
  border-radius:var(--r-sm);
  transition:background var(--d-quick) var(--ease-standard), color var(--d-quick) var(--ease-standard);
}
.dp-day:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:calc(-1 * var(--s-0-5));
  box-shadow:var(--ring-halo);
}
.dp-day:disabled{
  color:var(--obsidian-600);
  cursor:not-allowed;
  background:transparent;
}
@media (prefers-reduced-motion: reduce){
  .dp-popover, .dp-day, .dp-nav, .dp-title, .input-action{
    transition:none;
  }
}
.dp-popover)[hidden]{
  display:block;
}
.dp-popover){
  position:static;
  margin-top:var(--s-6);
  max-height:none;
  opacity:1;
  transform:none;
  pointer-events:auto;
}

What the contract holds the date picker to, word for word from its section of DESIGN.md.

• The trigger is a real <input> plus a labelled <button> — never a bare div. The popover is role="dialog" with an accessible name.
• .is-today and .is-selected are visually distinct on purpose: today is a ring, selection is a fill. When a range end lands on today, the ring is dropped (the fill already says it).
• Range corners are geometric, not decorative: square in the middle, rounded at the ends, fully rounded when start and end are the same day.
• Disabled days are <button disabled>, not styled-out divs — keyboard users must be able to tell.
• State matrix: § 3.0.1. Motion: § 06.4.

DD/MM/YYYY, single date. Typed input is digit-by-digit masked (slashes auto-insert) and the trailing icon opens a calendar popover that stays in sync. No native type="date" — the browser picker doesn't respect the system. Optional min/max attributes constrain both the typed value and the picker.

Two coupled inputs sharing one popover. Two months side-by-side on desktop, stacked on mobile. Click 1 sets the start, click 2 sets the end — clicking before start swaps. Footer presets cover the analytics defaults; the helper line auto-counts inclusive days.

A real input and a labelled button; today a ring, the selection a fill.

The badge, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<span class="badge badge-brand"><span class="dot"></span>Published</span>

.badge{
  --tint-hue:var(--tertiary-500);
  display:inline-flex;
  align-items:center;
  gap:var(--s-1);
  font-family:var(--font-sans);
  font-size:var(--t-small);
  letter-spacing:var(--tr-snug);
  padding:var(--s-2) var(--s-4);
  border-radius:var(--r-md);
  border:var(--bw-1) solid color-mix(in srgb, var(--tint-hue) calc(var(--tint-edge-deep) * 100%), transparent);
  color:var(--tertiary-300);
  background:color-mix(in srgb, var(--tint-hue) calc(var(--tint-fill-deep) * 100%), transparent);
  font-weight:500;
  white-space:nowrap;
  flex:none;
}
.badge .dot{
  width:var(--s-1);
  height:var(--s-1);
  border-radius:var(--r-full);
  background:currentColor;
}
.badge-brand{
  border-color:color-mix(in srgb, var(--tint-hue) calc(var(--tint-edge) * 100%), transparent);
  background:color-mix(in srgb, var(--tint-hue) calc(var(--tint-fill) * 100%), transparent);
}
.badge-brand{
  --tint-hue:var(--primary-500);
  color:var(--primary-400);
}

What the contract holds the badge to, word for word from its section of DESIGN.md.

• The badge's own register. --t-small, weight 500, --tr-snug; padding --s-2 --s-4, gap --s-1; corner --r-md. Line height and case come from the context. It is taller than the Chip on purpose: the badge reports, the chip is handled.
• A tint is a hue at two strengths, a fill and an edge, text on the full token. The variants use the Chip's pair, --tint-fill / --tint-edge. The default's deep hue, --tertiary-500, uses the heavier --tint-fill-deep / --tint-edge-deep. Never a hand-written rgba.
• One line, always. A badge never wraps (white-space: nowrap) and never shrinks in a flex row (flex: none): when room runs out, the text beside it wraps instead.
• The dot (.dot, --s-1 square, --r-full, currentColor) leads every status badge. The solid badge carries none.
• The solid badge takes the light label, --obsidian-050 on --primary-500: the second ratified exception of § 6.3, bounded like the first.
• States: § 3.0.1. default only: a badge is static — no hover, no focus. If it needs one, it is a button or a chip.

The badge variants: semantic color plus the dot. Shape and label carry the state; the tint reinforces it.

Badges in running context — rows, cards, headers — where they annotate a noun rather than announce a state.

A badge is a label read at a glance; it holds its line.

The chip, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<span class="chip chip-brand"><span class="chip-dot"></span> Design systems</span>

.chip{
  display:inline-flex;
  align-items:center;
  gap:var(--s-1);
  position:relative;
  font-family:var(--font-sans);
  font-size:var(--t-small);
  font-weight:500;
  letter-spacing:var(--tr-snug);
  line-height:var(--lh-snug);
  white-space:nowrap;
  padding:var(--s-1) var(--s-3);
  border-radius:var(--r-full);
  border:var(--bw-1) solid var(--obsidian-700);
  background:var(--obsidian-800);
  color:var(--obsidian-100);
  transition:border-color var(--d-quick) var(--ease-standard), color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
button.chip::before, a.chip::before{
  content:"";
  position:absolute;
  top:50%;
  left:50%;
  width:max(100%,var(--target-touch));
  height:var(--target-touch);
  transform:translate(-50%,-50%);
}
.chip .chip-dot{
  width:var(--s-1);
  height:var(--s-1);
  border-radius:var(--r-full);
  background:currentColor;
  flex:none;
}
.chip-brand{
  border-color:color-mix(in srgb, var(--tint-hue) calc(var(--tint-edge) * 100%), transparent);
  background:color-mix(in srgb, var(--tint-hue) calc(var(--tint-fill) * 100%), transparent);
}
.chip-brand{
  --tint-hue:var(--primary-500);
  color:var(--primary-400);
}
button.chip, a.chip{
  cursor:pointer;
  text-decoration:none;
}
button.chip:hover, a.chip:hover{
  border-color:var(--obsidian-600);
}
button.chip:active, a.chip:active{
  background:var(--obsidian-700);
}
button.chip[aria-pressed="true"]{
  border-color:var(--primary-500);
  color:var(--primary-400);
}
button.chip:disabled{
  opacity:var(--opacity-disabled);
  cursor:not-allowed;
  color:var(--obsidian-400);
}
@media (prefers-reduced-motion: reduce){
  .chip{
    transition:none;
  }
}
.chip:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}

What the contract holds the chip to, word for word from its section of DESIGN.md.

• The variant is a tint, at the Badge's two strengths. Background at --tint-fill (0.08), border at --tint-edge (0.3) — tokens since v4.3.0 — text on the full token — the same pair § 3.14 already uses, so the two small labelled objects of the system read as one family. The neutral chip is the exception and the majority case: --obsidian-800 on --obsidian-700, the card surfaces. A filled chip — solid magenta behind white — is off-system: one filled accent per viewport is the whole 85 / 10 / 5 budget, and a filter row would spend it six times over.
• A chip may be static. A chip that is neither pressable nor dismissible is legal and is the common case — a tag, a category, a value shown but not editable here. What makes it a chip rather than a § 3.14 Badge is who owns the value: a chip carries something a person entered or chose, a badge reports state the system computed. The affordance follows from the context, not from the definition.
• --r-full, always. A chip with a rectangular radius is a badge wearing a chip's label. The radius is how the two are told apart at a glance, so it is not a variant.
• The label rides --t-small. --t-micro is the dense step, legal inside a table cell or a toolbar and nowhere else. No other step is on-scale for a chip.
• A chip carries at most one affordance, never two (RIGID). Pressable or dismissible, not both. Both roles want the 44×44 target and two of them do not fit inside one 28px object without one swallowing the other. A filter chip is a <button> and the whole object is the target; a tag that leads to the list of its tag is an <a>, pressable the same way, with no aria-pressed and no disabled state; a dismissible chip is static and the dismiss button is the only target. A chip that is both is off-system — that pattern is a list row, not a chip. Carbon reaches the same rule from the other side: "avoid using tags with multiple functions to prevent confusion and reduce accidental clicks". It is a decision, not a law — Calcite and Fluent ship the combination deliberately.
• The touch target grows, the chip does not. At --t-small the rendered box is shorter than the 44×44 floor (§ 6), so the hit area is extended with a transparent inset pseudo-element. Growing the chip to reach 44px instead makes the densest component in the system the tallest one.
• A filter chip declares aria-pressed, and a group of them is a role="group" with an accessible name. Selection lands on the border and the text (--primary-500 · --primary-400), never on a magenta fill: a filter row is exactly the place where one filled accent becomes six.
• The dismiss names its value. aria-label="Remove Motion", never a bare × and never "Remove". Removing a chip changes a collection the reader can't otherwise see change, so the field's own live region announces it — not a toast (§ 3.17 is for things that happened somewhere else).
• Never colour alone (§ 6 floor #1). The label carries the meaning; the variant is emphasis on top of it. There is no icon-only chip — a chip without a label is a dot.
• Chips wrap, they never scroll and never truncate. A collection long enough to need either collapses behind a trailing +N chip, which is itself a .chip and a button. A horizontally scrolling chip row hides values from a keyboard and from a screen reader alike.

A compact label for one value that belongs to something else — a tag on a post, a facet on a result set, a recipient already entered. Where a badge reports what the system computed, a chip carries what a person chose. Six variants on the badge's tint, an optional dot; most chips are neutral and static.

Pressable chips narrow a set. Each is a button that holds its state in aria-pressed, and the row is a named group. Selection lands on the border and the label, so a row of six selections still spends no fill.

Values entered into a field. The chip itself stays static; the dismiss is the only target and its label names the value it removes. The field announces the removal in its own live region, and a long collection collapses behind a trailing count.

The chip is the one object here the reader owns: they put the value there, so they can take it back.

The alert, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="alert alert-success" role="status"><svg class="icon alert-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 8.5l3 3 7-7.5"/></svg><div class="alert-title">Draft published</div><div class="alert-body">The changes are live for every reader.</div></div>

.alert{
  display:grid;
  grid-template-columns:auto minmax(0,1fr);
  column-gap:var(--s-3);
  row-gap:var(--s-1);
  align-items:center;
  padding:var(--s-3) var(--s-4);
  background:var(--obsidian-850);
  border:var(--bw-1) solid var(--obsidian-800);
  border-left:var(--bw-2) solid var(--primary-500);
  border-radius:var(--r-md);
  font-size:var(--t-small);
  color:var(--obsidian-200);
}
.alert-icon{
  grid-column:1;
  grid-row:1;
  width:16px;
  height:16px;
  color:var(--primary-400);
}
.alert-title{
  grid-column:2;
  grid-row:1;
  font-weight:600;
  color:var(--obsidian-100);
  min-width:0;
}
.alert-body{
  grid-column:2;
  grid-row:1;
  min-width:0;
  overflow-wrap:anywhere;
}
.alert:has(.alert-title) .alert-body{
  grid-column:1 / -1;
  grid-row:2;
}
.alert-success{
  border-left-color:var(--success);
}
.alert-success .alert-icon{
  color:var(--success);
}

What the contract holds the alert to, word for word from its section of DESIGN.md.

• The fill never changes. Every variant sits on --obsidian-850; semantics ride the 2px left rule and the icon. A tinted alert surface would spend the 5% semantic budget on furniture (§ Law, L1).
• The icon is mandatory and aria-hidden — it is the shape half of "colour never alone" (§ 6 floor #1). The text carries the meaning.
• role="status" for informative, role="alert" for danger. Nothing else.
• An alert is not dismissible, at all. Not on a timer (§ 6 floor #6) and not by the reader either: it clears when the condition clears. A close button would let someone hide a state that is still true. If the reader must be able to make it go away, the message is transient and belongs in § 3.17 Toast — that is the whole difference between the two components.
• Entrance is the system's canonical reveal — [data-alert-fade] + .is-in, opacity plus 12px from below on --d-slow · --ease-decel, the same ride as [data-fade]. Staggered when several land together. Under reduced motion they are simply there.

Inline, in flow, addressed to the whole surface. The fill never changes — semantics ride the 2px left rule and the icon, so the accent budget stays spent on actions, not on furniture. An alert is never dismissible — not on a timer, and not by the reader either.

Click Replay to re-trigger animations.

An alert states a condition; it clears when the condition clears.

The toast, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="toast toast-success is-in" role="status"><svg class="icon toast-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 8.5l3 3 7-7.5"/></svg><div class="toast-title">Draft published</div><button class="toast-dismiss" type="button" aria-label="Dismiss"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3.5 3.5l9 9M12.5 3.5l-9 9"/></svg></button><div class="toast-body">Live on the blog. <button class="toast-action" type="button">Undo</button></div></div>

.toast{
  pointer-events:auto;
  display:grid;
  grid-template-columns:auto minmax(0,1fr) auto;
  column-gap:var(--s-3);
  row-gap:var(--s-1);
  align-items:center;
  padding:var(--s-4);
  background:var(--obsidian-850);
  border:var(--bw-1) solid var(--obsidian-700);
  border-left:var(--bw-2) solid var(--primary-500);
  border-radius:var(--r-md);
  box-shadow:var(--sh-3);
  font-size:var(--t-small);
  color:var(--obsidian-200);
  opacity:0;
  transform:translateX(24px);
  transition:opacity var(--d-base) var(--ease-decel), transform var(--d-base) var(--ease-decel);
}
.toast.is-in{
  opacity:1;
  transform:translateX(0);
}
.toast-icon{
  grid-column:1;
  grid-row:1;
  width:var(--icon-sm);
  height:var(--icon-sm);
  color:var(--primary-400);
}
.toast-title{
  grid-column:2;
  grid-row:1;
  font-weight:600;
  color:var(--obsidian-100);
  min-width:0;
}
.toast-body{
  grid-column:2;
  grid-row:1;
  min-width:0;
  overflow-wrap:anywhere;
}
.toast:has(.toast-title) .toast-body{
  grid-column:1 / -1;
  grid-row:2;
}
.toast-action{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--primary-400);
  background:transparent;
  border:0;
  cursor:pointer;
  padding:var(--s-1) 0;
  margin-top:var(--s-2);
  transition:color var(--d-quick) var(--ease-standard);
}
.toast-action:hover{
  color:var(--primary-300);
}
.toast-action:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--focus-offset);
  box-shadow:var(--ring-halo);
}
.toast-dismiss{
  grid-column:3;
  grid-row:1;
  display:grid;
  place-items:center;
  width:20px;
  height:20px;
  color:var(--obsidian-400);
  border-radius:var(--r-sm);
  background:transparent;
  border:0;
  cursor:pointer;
  transition:color var(--d-quick) var(--ease-standard), background var(--d-quick) var(--ease-standard);
}
.toast-dismiss:hover{
  color:var(--obsidian-100);
  background:var(--obsidian-800);
}
.toast-dismiss:focus-visible{
  outline:var(--focus-width) solid var(--obsidian-100);
  outline-offset:var(--s-px);
  box-shadow:var(--ring-halo);
}
.toast-dismiss svg{
  width:var(--icon-xs);
  height:var(--icon-xs);
}
.toast-success{
  border-left-color:var(--success);
}
.toast-success .toast-icon{
  color:var(--success);
}
.toast{
  width:min(100%, calc(var(--s-32) * 2.5));
}

What the contract holds the toast to, word for word from its section of DESIGN.md.

• Auto-dismiss is opt-in and bounded (§ 6 floor #6). data-autohide is permitted only when the toast carries no action and is not .toast-danger; anything with an Undo or an error stays until dismissed. Hover and focus pause any countdown.
• The region is aria-live="polite"; a .toast-danger carries role="alert" on the toast itself.
• Newest enters at the bottom of the stack. Three visible at most — a fourth means the surface should be showing an § 3.16 Alert instead.
• A toast is never the only place a result appears. If losing it loses the information, it wasn't a toast.
• Same grid as § 3.16: icon and title on the first row, body returning to the icon's left edge below.
• A toast enters and leaves on the same side it lives on — 24px from the right, opacity with it. Coming in from below would read as the page growing; coming in from the edge reads as something arriving from outside the page, which is what it is. Exit retraces the entry exactly: same axis, same distance, opposite direction.
• The stack closes the gap, it never snaps. Dismissal is two moves on two curves, and they are not the same move. The toast fades and slides out on --d-quick · --ease-accel — that is the exit. Its box then collapses on --d-base · --ease-decel — and that is not an exit at all: it is the repositioning of the toasts below, which are not leaving, they are settling into a new place. Accel on the collapse would tell the survivors they are being dismissed too. Same roll-off shape as the chat message (§ 3.35). Removing the node outright drops everything below it by a full toast height in one frame — that reads as a glitch, not a dismissal.
• The two rides differ in speed, not in path. In: .is-in, --d-base · --ease-decel — the system announcing itself. Out: .is-out, --d-quick · --ease-accel — the reader dismissed it, get out of the way. Remove the node after the exit resolves; under reduced motion it goes at once.
• The toast keeps its close button. It is the dismissible half of the pair: § 3.16 Alert has none by contract.
• Motion: § 06.4.

What an alert becomes when the message is about an action that just happened somewhere else. Transient, stacked bottom-right, three visible at most. Auto-dismiss is opt-in and bounded: only for a toast with no action that is not an error, and hover or focus pauses the countdown.

Click Replay to re-trigger animations.

Four types, one rule on the left and one icon: the default for a neutral event, success, warning and danger. The fill never changes.

A toast reports an event, and something durable keeps the record.

The progress bar, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="progress"><span class="progress-label" id="kit-progress">Upload</span><div class="progress-track" role="progressbar" aria-labelledby="kit-progress" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100"><div class="progress-fill" style="--value:60%"></div></div><span class="progress-value">60%</span></div>

.progress{
  display:flex;
  align-items:center;
  gap:var(--s-4);
}
.progress-label{
  font-family:var(--font-mono);
  font-size:var(--t-micro);
  letter-spacing:var(--tr-mono);
  text-transform:uppercase;
  color:var(--obsidian-300);
}
.progress-track{
  flex:1;
  height:var(--s-2);
  border-radius:var(--r-full);
  background:var(--obsidian-700);
}
.progress-fill{
  height:100%;
  width:var(--value, 0%);
  border-radius:inherit;
  background:var(--grad-progress);
  box-shadow:var(--sh-glow-soft);
  transform-origin:left;
  transition:width var(--d-scene) var(--ease-decel);
}
.progress-value{
  font-size:var(--t-small);
  color:var(--obsidian-100);
  font-variant-numeric:tabular-nums;
}
.progress[data-reveal] .progress-fill{
  transform:scaleX(0);
}
@media (prefers-reduced-motion: reduce){
  .progress-fill{
    transition:none;
  }
  .progress[data-reveal] .progress-fill{
    transform:none;
    transition:none;
  }
}
.progress{
  width:min(100%, calc(var(--s-32) * 2));
}

What the contract holds the progress bar to, word for word from its section of DESIGN.md.

• Two heights. 8px by default; .progress-sm, 4px, where the bar sits inside a row or a card. Nothing between: 6px is not on the scale.
• Named and valued. The track carries role="progressbar", aria-valuenow, aria-valuemin, aria-valuemax and a name; the value is also written as text.
• Known end only. An unknown wait is a Loader; a bar that moves without a value is not a Progress.
• Motion. On view the fill draws from zero on --d-scene · --ease-decel from 700ms and lands exactly on its value; a new value moves the fill on the same curve. Reduced motion: the fill is at its value.

The linear meter: draws from zero to its value on view and lands exactly. The value is stated in text beside the bar. Two heights: 8px by default, 4px with .progress-sm where the bar sits inside a row or a card.

Click Replay to re-trigger animations.

A known amount of work, with its value written.

The loader, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

AnatomyCode

1Size--loader-lg

2Marklogo-loader-fast.svgthe Amaca logo, drawn and animated in the file

3Motion--d-quick --ease-standard

What the contract holds the loader to, word for word from its section of DESIGN.md.

• Show the loader within 100ms of the action that triggered the wait. Late loaders read as glitches, not feedback.
• A 200ms wait deserves no loader at all — show the result.
• One full-page loader per route at a time. After 800ms hand off to a Skeleton.
• Don't stack a section loader inside a card that already sits inside a full-page loader.
• Resolve to the success state when a wait completes green. Let the loader keep spinning after the wait is over and you've shipped a bug surface, not a state.
• Never use the loader as a decorative animation. The mark is in motion because something is loading.

Measurements

Tokenized spacing between logo and label, padding on overlay variants, alpha on the backdrop. Each measurement maps to a system token — no raw px in component code.

Generating tokens…

01

Logo box (MD)

--loader-md (48)

02

Gap between logo and label

--s-3 (12)

03

Label · body 15, tracking snug

--obsidian-200

04

Overlay backdrop alpha

0.72 · blur 2px

05

Success check · scale-in spring

--ease-spring

06

Reduced-motion ring · stroke

--primary-500 · 1.4s

07

ARIA · live announcement

role=status

Five shapes for five waits. The standalone is the floor; everything else composes from it. Success swaps the mark for a check on --ease-spring when the wait resolves green.

Standalone

Generating tokens…

With label

Submit

Inside button

Skeleton handoff

Success state

Four sizes, four tokens. The SVG scales linearly — the file is vector. Hit-area follows the box exactly; no extra padding.

--loader-xs 16 PX

--loader-sm 24 PX

--loader-md 48 PX

--loader-lg 96 PX

Four real-world placements. Click any Trigger to start the wait, watch the loader hold the surface, then resolve.

17.3 / 01 Inside primary button · submitting

A submit handler is in flight. The button stays the same size; the label crossfades to the loader so layout never shifts.

Submit form

Trigger

17.3 / 02 Inline · async validation

EMAIL

Checking availability…

Trigger

17.3 / 03 Full-page · app boot

Loading workspace…

Trigger

17.3 / 04 Chat composer · bot generating (cross-component)

Amaca is generating a response…

Send another message…

Trigger

A loader has a job. If it isn't communicating a real wait, it's decoration — and decoration on a brand mark dilutes the mark.

The skeleton, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<div class="skeleton-circle" aria-hidden="true"></div><div class="skeleton-stack"><div class="skeleton-line" style="width:70%" aria-hidden="true"></div><div class="skeleton-line" style="width:45%" aria-hidden="true"></div></div>

.skeleton-stack{
  display:grid;
  gap:var(--s-3);
  width:100%;
}
.skeleton-line, .skeleton-circle{
  position:relative;
  overflow:hidden;
  background:var(--obsidian-700);
}
.skeleton-line{
  height:var(--s-3);
  border-radius:var(--r-sm);
}
.skeleton-circle{
  --size:var(--s-8);
  flex:none;
  width:var(--size);
  height:var(--size);
  border-radius:var(--r-full);
}
.skeleton-line::after, .skeleton-circle::after{
  content:"";
  position:absolute;
  inset:0;
  background:linear-gradient( 90deg, transparent 0, color-mix(in srgb, var(--primary-500) calc(var(--tint-fill) * 100%), transparent) 50%, transparent 100% );
  animation:skeleton-shimmer 1600ms linear infinite;
}
@media (prefers-reduced-motion: reduce){
  .skeleton-line::after, .skeleton-circle::after{
    animation:none;
    opacity:0;
  }
}

What the contract holds the skeleton to, word for word from its section of DESIGN.md.

• The same size as the content. The shapes take the height and the width of what will arrive, so the swap moves nothing. If the size is not known, the shape is not known: use a Loader.
• Visible inside a card. The fill is --obsidian-700. --obsidian-800 is the colour of the card and the shapes would disappear.
• Quiet. The shimmer is a magenta tint at --tint-fill over 1600 ms, linear, in a loop. No high-contrast sweep.
• Not the only signal. The region carries aria-busy="true" and a name (aria-label). When the content lands, aria-busy goes away and a live region (role="status") says so.
• Silent shapes. Every shape is aria-hidden="true". A skeleton is never focusable and never a link.
• Reduced motion. The shimmer is off and the fill stays still (§ 06.4).

A line for text, a circle for a person, a block for an image. The fill is --obsidian-700, so it stays visible inside a card; the shimmer is a quiet magenta tint and stops under reduced motion.

The region is aria-busy while the shapes are there, the shapes are aria-hidden, and a live region says when the content arrives. The two states have the same height.

A skeleton promises a shape; keep the promise.

The modal, open in place without its backdrop, part by part, with the tokens that draw each part. Switch to Code for its HTML and the rules of components.css that draw it, ready to copy or download.

<dialog class="modal" aria-labelledby="kit-modal-title"><div class="modal-head"><h2 class="modal-title" id="kit-modal-title">Publish the project?</h2><button class="btn btn-ghost btn-sm btn-icon" type="button" aria-label="Close"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3.5 3.5l9 9M12.5 3.5l-9 9"/></svg></button></div><p class="modal-body">The project and its 14 versions go live for every reader.</p><div class="modal-foot"><button class="btn btn-secondary btn-sm" type="button">Cancel</button><button class="btn btn-primary btn-sm" type="button">Publish</button></div></dialog>

.modal{
  width:calc(100% - var(--s-8));
  max-width:var(--w-modal);
  max-height:calc(100vh - var(--s-8));
  overflow:auto;
  margin:auto;
  padding:var(--s-6);
  background:var(--obsidian-800);
  color:var(--obsidian-100);
  border:var(--bw-1) solid var(--obsidian-700);
  border-radius:var(--r-lg);
  box-shadow:var(--sh-4);
  font-family:var(--font-sans);
  opacity:0;
  transform:translateY(var(--s-2));
  transition:opacity var(--d-quick) var(--ease-accel),transform var(--d-quick) var(--ease-accel), overlay var(--d-quick) var(--ease-accel) allow-discrete,display var(--d-quick) var(--ease-accel) allow-discrete;
}
.modal[open]{
  opacity:1;
  transform:none;
  transition:opacity var(--d-quick) var(--ease-decel),transform var(--d-base) var(--ease-decel), overlay var(--d-quick) var(--ease-decel) allow-discrete,display var(--d-quick) var(--ease-decel) allow-discrete;
}
.modal::backdrop{
  background:transparent;
  transition:background var(--d-quick) var(--ease-accel),overlay var(--d-quick) var(--ease-accel) allow-discrete,display var(--d-quick) var(--ease-accel) allow-discrete;
}
.modal[open]::backdrop{
  background:var(--scrim);
  backdrop-filter:blur(var(--blur-veil));
  transition:background var(--d-quick) var(--ease-decel),overlay var(--d-quick) var(--ease-decel) allow-discrete,display var(--d-quick) var(--ease-decel) allow-discrete;
}
.modal-head{
  display:flex;
  align-items:center;
  justify-content:space-between;
  gap:var(--s-4);
  margin-bottom:var(--s-4);
}
.modal-title{
  margin:0;
  font-size:var(--t-h6);
  font-weight:700;
  line-height:var(--lh-snug);
}
.modal-body{
  margin:0;
  color:var(--obsidian-200);
  font-size:var(--t-body);
}
.modal-foot{
  display:flex;
  justify-content:flex-end;
  flex-wrap:wrap;
  gap:var(--s-2);
  margin-top:var(--s-6);
}
@media (prefers-reduced-motion:reduce){
  .modal, .modal[open]{
    transition:none;
    transform:none;
  }
  .modal::backdrop, .modal[open]::backdrop{
    transition:none;
  }
}
.modal{
  width:min(100%, calc(var(--s-32) * 2.5));
}

What the contract holds the modal to, word for word from its section of DESIGN.md.

• The panel is the card's surface, not a new one. Same fill, border and radius; what lifts it off the page is --sh-4 and the --scrim behind it. A modal with a radius of its own is a second card shape.
• --scrim is a veil. The page stays visible, dimmed and softened by --blur-veil (the Veil material). The Lightbox takes the Bar material, darker and more blurred, because it is a viewer.
• Open it with showModal(). The browser then traps focus, makes the rest of the page inert, and closes on Esc; none of that is rebuilt. It rides --z-overlay, and the page behind does not scroll.
• The title is the name. aria-labelledby points at .modal-title. A confirmation that needs the answer to proceed uses role="alertdialog" and aria-describedby on the body.
• Focus goes to a control, never to the panel. The first control, or for a destructive confirmation the least destructive one (Cancel). On close it returns to the control that opened the modal.
• Closing (RIGID). Esc always closes. A click on the scrim closes too, except in a role="alertdialog" and whenever the modal holds data not yet saved. The close button is always present, so the way out never depends on a gesture.
• Actions: one primary, at the end. A destructive action is .btn-danger and is never the default focus. A modal has at most two actions and no third "learn more" link; that goes in the body.
• Never stack. A modal opened from a modal is a flow that wants a page.
• Small screens: at ≤480px the panel keeps --s-4 of margin on each side, the actions stack at full width, and the body scrolls inside the panel. A panel anchored to the bottom is a different component and is not this one.
• Motion. In: the panel fades in and rises --s-2; out: the same, faster. Reduced motion: instant. Rows in the § 06.4 index.
• No state matrix beyond default. The panel is never focused or pressed itself (§ 3.0.1); the controls inside carry their own states.