actual-css 0.9.2 → 0.11.0

package/dist/actual.full.css

@@ -130,11 +130,15 @@ select {
   --ease-enter: cubic-bezier(0.2, 0, 0, 1);
   --ease-exit: cubic-bezier(0.4, 0, 1, 1);
 
-  /* Focus ring — shared by every interactive component's :focus-visible */
+  /* Generic focus fallback — an adaptive currentColor line for elements
+     without a component ring (links, summary, plain items). Components draw
+     the themed ring instead: --focus-ring-width solid --focus. See focus.css
+     for the two contracts. Both share --focus-ring-width: they differ in
+     color only. */
   --focus-outline-color: currentColor;
-  --focus-outline: calc(var(--border-width) * 2) solid var(--focus-outline-color);
+  --focus-outline: var(--focus-ring-width) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
-  --focus-ring-width: 3px;
+  --focus-ring-width: 2px;
 
   /* Status dot positioning — used by .avatar > .badge:empty. The offset is
      the circle-aware inset (1 - 1/√2) / 2 ≈ 14.65%; the ring surrounds the
@@ -195,8 +199,8 @@ select {
   --state-selected-fg: var(--primary-fg);
   --state-disabled: var(--text-subtle);
 
-  /* Status dot ring — follows the island's surface. */
-  --indicator-ring: var(--surface);
+  /* Status dot ring — cuts the dot out of what it overlaps. */
+  --indicator-ring: var(--surface-opaque);
 }
 
 :root {
@@ -291,6 +295,8 @@ select {
  * Shadow color, Focus ring derivation.
  * Derived: "Theme-derived aliases", Tone subsystem, Backdrop fill — reference
  * other tokens; hard-coded overrides on a custom theme will break the intent.
+ * Exception: --surface-opaque and --surface-solid-fg are public; a theme with
+ * translucent surfaces overrides them with opaque values.
  * Internal: --hgroup-gap.
  */
 :root {
@@ -356,10 +362,10 @@ select {
 
   /* Lines and focus */
   --border: hsl(260 15% 88%);
-  --focus: var(--neutral);
-  /* Pre-color-mix fallback only — superseded below by a derivation from
-     --focus so overriding --neutral/--focus never leaves a stale ring. */
-  --focus-ring: hsl(258 7% 43% / 0.3);
+  /* A primary-hued mid-tone on purpose, one value for both schemes: focus
+     lines must hold 3:1 against --surface and --surface-solid alike (page,
+     fields, a solid band), which rules out the primary itself. */
+  --focus: hsl(268 30% 55%);
   --hover-overlay: hsl(260 20% 10% / 0.04);
 
   /* Radius scale — themes may override the whole scale (e.g. [data-theme="square"]) */
@@ -382,7 +388,12 @@ select {
   --heading: var(--text);
   --selection-bg: var(--primary);
   --selection-fg: var(--primary-fg);
-  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
+  /* Surface roles that must stay opaque when a theme paints translucent
+     surfaces; both equal --surface on an opaque palette. --surface-opaque
+     hides or separates what is painted beneath a ring, separator or marker —
+     never a fill. --surface-solid-fg is the ink on --surface-solid. */
+  --surface-opaque: var(--surface);
+  --surface-solid-fg: var(--surface);
 }
 
 /* Soft foreground hooks — the soft ink is the intent rebated toward the local
@@ -391,18 +402,17 @@ select {
    default theme: a custom property bakes its var() references where it is
    declared, so these resolve against root/light/dark tokens on every boundary.
    Presets and custom islands keep their --soft-fg-mix / raw-intent ink unless
-   they declare hooks themselves — :where() keeps this reset from outranking a
-   theme's own declaration (e.g. brutalist's 45% soft-fg-mix). */
-:where([data-theme]:not([data-theme="light"]):not([data-theme="dark"])) {
-  --primary-soft-fg: initial;
-  --secondary-soft-fg: initial;
-  --success-soft-fg: initial;
-  --warning-soft-fg: initial;
-  --danger-soft-fg: initial;
-  --neutral-soft-fg: initial;
-}
-
-:root,
+   they declare hooks themselves.
+
+   Why :where(:root) and why the reset comes second: both rules match when a
+   custom theme sits on <html> itself. A bare :root is (0,1,0) and would
+   outrank the zero-specificity reset, so the same theme resolved a calibrated
+   Ink & Terra ink on <html data-theme="brand"> and the raw --soft-fg-mix ink
+   on <div data-theme="brand"> — one attribute, two soft palettes. Levelling
+   both rules to zero specificity makes source order the tiebreaker, so the
+   reset must stay below. Zero specificity is also what lets a theme declare
+   its own hooks (e.g. brutalist's 45% soft-fg-mix) and win at (0,1,0). */
+:where(:root),
 [data-theme="light"],
 [data-theme="dark"] {
   --secondary-soft-fg: color-mix(in oklab, var(--text) 10%, var(--secondary) 90%);
@@ -412,6 +422,15 @@ select {
   --neutral-soft-fg: color-mix(in oklab, var(--text) 20%, var(--neutral) 80%);
 }
 
+:where([data-theme]:not([data-theme="light"]):not([data-theme="dark"])) {
+  --primary-soft-fg: initial;
+  --secondary-soft-fg: initial;
+  --success-soft-fg: initial;
+  --warning-soft-fg: initial;
+  --danger-soft-fg: initial;
+  --neutral-soft-fg: initial;
+}
+
 /* Native platform controls (checkbox, radio, range, progress) that are not
    restyled by a component class still follow the theme accent. Declared on
    every island: accent-color inherits as a computed value, so islands must
@@ -433,20 +452,6 @@ select {
   --tone-fg: var(--text);
 }
 
-/* Focus ring derivation — color-mix tier. Runs whether or not light-dark()
-   is also supported, so it covers the color-mix-without-light-dark browser
-   tier on its own; the light-dark block below refines it further with the
-   light/dark alpha split once both features are available. Declared on every
-   [data-theme] island (not just the built-in light/dark pair) so custom
-   islands recolor the ring for free; a preset that re-declares --focus-ring
-   later in source order intentionally pins its own ring instead. */
-@supports (color: color-mix(in oklch, red, white)) {
-  :root,
-  [data-theme] {
-    --focus-ring: color-mix(in oklch, var(--focus) 30%, transparent);
-  }
-}
-
 /* Auto dark mode via light-dark(). Resolves based on the element's color-scheme:
     :root (light dark) follows the OS, [data-theme="light"] forces light,
     [data-theme="dark"] forces dark by overriding color-scheme.
@@ -483,22 +488,11 @@ select {
     --text-subtle: light-dark(hsl(258 7% 57%), hsl(258 7% 54%));
 
     --border: light-dark(hsl(260 15% 88%), hsl(262 12% 24%));
-    --focus-ring: light-dark(hsl(258 7% 43% / 0.3), hsl(258 10% 72% / 0.28));
     --hover-overlay: light-dark(hsl(260 20% 10% / 0.04), hsl(0 0% 100% / 0.06));
     --shadow-color: light-dark(hsl(260 25% 10%), hsl(262 40% 2%));
   }
 }
 
-@supports (color: color-mix(in oklch, red, white)) and (color: light-dark(red, blue)) {
-  :root,
-  [data-theme] {
-    --focus-ring: light-dark(
-      color-mix(in oklch, var(--focus) 30%, transparent),
-      color-mix(in oklch, var(--focus) 28%, transparent)
-    );
-  }
-}
-
 @media (prefers-contrast: more) {
   :root,
   /* The repeated attribute intentionally outranks single-attribute preset
@@ -506,7 +500,7 @@ select {
   [data-theme][data-theme] {
     --border-width: 2px;
     --focus-outline-offset: 3px;
-    --focus-ring-width: 4px;
+    --focus-ring-width: 3px;
     --text-muted: var(--text);
     --text-subtle: var(--text);
   }
@@ -662,13 +656,9 @@ small {
  * Cross-cutting variant token mapping.
  *
  * Variant scope: .solid/.soft/.outline/.surface set --ui-* for components that
- * opt into shared variants. .inverted is a surface modifier, not a variant: it paints
- * the element directly (background/color/border-color) so it works on any bare
- * block, and remaps the shared --ui-* tokens so participating components
- * (.card, .navbar, .alert, .badge) invert through their own rules. Loaded
- * before components, so a component with its own explicit surface (e.g.
- * .accordion) naturally keeps that surface — .inverted never forces a
- * non-participant.
+ * opt into shared variants. A subtree that needs another palette or scheme is
+ * a data-theme island, never a variant: only an island recomputes every token
+ * (fields, states, intents), where a remap of a few --ui-* tokens cannot.
  * Component-specific defaults (.btn solid-by-default, .badge
  * soft-by-default, .alert soft-by-default) live with their components:
  *   components/button.css — .btn default solid + .btn.ghost + .btn.link
@@ -724,28 +714,6 @@ small {
   --ui-border: var(--border);
 }
 
-/* Inverse surface treatment. Paints the element directly (so it works on any
-   bare block) and remaps the shared --ui-* tokens so opt-in components
-   (.card, .navbar) invert through their own rules. Because this loads before
-   component base surfaces, components with their own explicit surface
-   (e.g. .accordion) keep it — participation is opt-in, never forced. --heading
-   is set so global headings (var(--heading, inherit)) do not inherit an outside
-   heading color onto the dark surface; surface-owning descendants derive
-   their contextual aliases from their own local surface. */
-.inverted {
-  --ui-bg: var(--surface-solid);
-  --ui-fg: var(--surface);
-  --ui-border: transparent;
-  --ui-hover-bg: var(--surface-solid);
-
-  --heading: var(--surface);
-  --busy-overlay-bg: var(--surface-solid);
-
-  background: var(--ui-bg);
-  color: var(--ui-fg);
-  border-color: var(--ui-border);
-}
-
 .compact {
   --gap: var(--space-20);
   --density-space: var(--space-20);
@@ -763,7 +731,8 @@ small {
 /* Shared control scale. Wrappers are listed when their descendants form one
    component (field, choice-card, floating-field, input-icon, join, pagination,
    tabs, flyout). A local size declaration beats inherited density because it
-   is declared on the sized component itself. */
+   is declared on the sized component itself. Guarded by check:sync
+   (size-scale-participants): .sm and .lg must list the same components. */
 :where(
   .btn,
   .input,
@@ -829,10 +798,6 @@ small {
     );
     /* @sync soft-recipe */
   }
-
-  .inverted {
-    --ui-hover-bg: color-mix(in oklch, var(--surface-solid) 88%, black);
-  }
 }
 
 /* Interactive hover recipes live in the components that consume them:
@@ -843,9 +808,25 @@ small {
    pointer/mouse focus and interactive components layer their ring on top.
 
    Invariant: an interactive component must never rely on box-shadow alone
-   for its keyboard focus indicator. Components that remove the native
-   outline on :focus-visible replace it with a transparent outline — invisible
-   normally, forced to the system focus color under forced-colors. */
+   for its keyboard focus indicator; forced colors keep outlines and drop
+   shadows.
+
+   Two contracts share the job, both --focus-ring-width wide. Text-like
+   elements, whose ink is the thing being focused (links, summary, .nav-link,
+   .menu-item, breadcrumb links, .navbar-brand), declare no outline and take
+   the generic fallback below: a currentColor line that follows whatever the
+   application painted. Boxed components, with a fill or border of their own,
+   draw the themed ring instead — a solid line in --focus: inset on fields
+   (inside their border box), offset by --focus-outline-offset on discrete
+   actions. The color never derives from an intent or a local
+   surface — the theme guarantees --focus at 3:1 against both --surface and
+   --surface-solid, so one token reads on the page, on a solid band and on
+   any nested surface.
+
+   Documented exception: an invalid field focuses in --form-invalid-border
+   (danger), so the error stays visible at the point of correction. The border
+   carries the same hook; report:theme-contrast measures that line at 3:1
+   against the field's background alongside --focus. */
 :focus {
   outline: var(--focus-outline);
   outline-offset: var(--focus-outline-offset);
@@ -1390,7 +1371,7 @@ small {
  *
  * Docs: docs/pages/layout/app-layout.md
  *
- * Public hook:
+ * Public hooks:
  * --app-nav-side-size
  */
 .app-layout {
@@ -1719,12 +1700,12 @@ small {
  * Docs: docs/pages/layout/column-layout.md
  *
  * Neither space-driven like .grid nor count-driven like .grid-N: this is a
- * coordinate system. The author places regions with .column-span-N /
- * .column-start-N and owns narrow-container recomposition. There is
- * deliberately no automatic collapse — no threshold, no hidden
- * .container-query behavior, no breakpoint variants. A single framework
- * threshold cannot be right for arbitrary per-region compositions, and a
- * hidden default would have to be undone rather than extended.
+ * coordinate system. Each direct child places itself with two numbers,
+ * --column-start and --column-span, and the author owns narrow-container
+ * recomposition. There is deliberately no automatic collapse — no threshold,
+ * no hidden .container-query behavior, no breakpoint variants. A single
+ * framework threshold cannot be right for arbitrary per-region compositions,
+ * and a hidden default would have to be undone rather than extended.
  *
  * See docs/design-notes/column-layout.md.
  *
@@ -1736,11 +1717,12 @@ small {
  *   media + flexible content        -> .media
  *   exact custom track templates    -> --grid-columns on .grid
  *
- * Child contract: each direct child is placed on the canvas via its own
- * .column-span-N / .column-start-N.
- *
  * Unlike .grid-N, the track template does not read --gap, so the gap
  * utilities are exact here at every width.
+ *
+ * Public hooks:
+ * --column-start (the start line, 1-12; unset = auto-placed)
+ * --column-span (the width in canvas units, 1-12; unset = to the canvas end)
  */
 .column-layout {
   display: grid;
@@ -1748,116 +1730,30 @@ small {
   grid-template-columns: repeat(12, minmax(0, 1fr));
 }
 
-/* Three zero-specificity tiers, applied in this order and only ever separated
- * by source order. ORDER IS LOAD-BEARING:
+/* One rule covers the four placements:
+ *   neither          auto-placed, spanning the whole canvas
+ *   span only        auto-placed over N units, so 8 + 4 flows onto one row
+ *   start only       from line S to the canvas end (span 13 - S)
+ *   start and span   explicit; keep S + N - 1 <= 12
  *
- *   1. the child reset       auto-placed, spanning the whole canvas
- *   2. .column-start-*       a definite start line, running to the canvas end
- *   3. .column-span-*        the end only, so it refines either of the above
+ * The start stays `auto` unless set: a definite start on every child would
+ * take all of them out of auto-placement, and an 8 + 4 pair would stack.
  *
- * Moving tier 3 above tier 2 makes every start+span pair run to column 12;
- * moving either above tier 1 makes every placement full-span. Both failures
- * are silent. tests/css-audit.test.js locks the order and
- * tests/browser/column-layout.test.js locks the resulting geometry.
- *
- * Zero specificity is the point: an application's own container-query rules
- * override placement additively, with a single-class selector and without
- * having to undo framework specificity first.
- */
-
-/* Tier 1. A child with no placement class stays a readable full-width region
- * instead of collapsing to one twelfth. Expressed as a span, not as
- * `1 / -1`: a definite start line would give every child a definite column
- * position and disable auto-placement, so `.column-span-8` next to
- * `.column-span-4` would stack instead of composing 8 + 4.
+ * The reset makes the two hooks inputs of this grid item rather than an
+ * inherited context: a nested .column-layout keeps the coordinates it was
+ * given for its own placement, and its children start from nothing. Zero
+ * specificity, so any author rule on the child wins.
  *
  * min-inline-size: 0 keeps the item box inside its track so the canvas never
  * grows past its container. It does not stop content from painting outside a
  * narrow track — that distinction is the primitive's contract, not a bug. */
 :where(.column-layout) > * {
-  grid-column-end: span 12;
-  min-inline-size: 0;
-}
-
-/* Tier 2. A definite start line, running to the end of the canvas unless a
- * .column-span-* refines the end. `column-start-9` alone is therefore the
- * last four columns rather than an implicit 21-line overflow. */
-:where(.column-start-1) {
-  grid-column: 1 / -1;
-}
-:where(.column-start-2) {
-  grid-column: 2 / -1;
-}
-:where(.column-start-3) {
-  grid-column: 3 / -1;
-}
-:where(.column-start-4) {
-  grid-column: 4 / -1;
-}
-:where(.column-start-5) {
-  grid-column: 5 / -1;
-}
-:where(.column-start-6) {
-  grid-column: 6 / -1;
-}
-:where(.column-start-7) {
-  grid-column: 7 / -1;
-}
-:where(.column-start-8) {
-  grid-column: 8 / -1;
-}
-:where(.column-start-9) {
-  grid-column: 9 / -1;
-}
-:where(.column-start-10) {
-  grid-column: 10 / -1;
-}
-:where(.column-start-11) {
-  grid-column: 11 / -1;
-}
-:where(.column-start-12) {
-  grid-column: 12 / -1;
-}
+  --column-start: initial;
+  --column-span: initial;
 
-/* Tier 3. The end only. Combined with a start, keep the placement inside the
- * canvas: S + N - 1 <= 12. Exceeding it adds an auto-sized implicit column,
- * which reshapes every 1fr track — the whole canvas loses its alignment, not
- * just the offending region. */
-:where(.column-span-1) {
-  grid-column-end: span 1;
-}
-:where(.column-span-2) {
-  grid-column-end: span 2;
-}
-:where(.column-span-3) {
-  grid-column-end: span 3;
-}
-:where(.column-span-4) {
-  grid-column-end: span 4;
-}
-:where(.column-span-5) {
-  grid-column-end: span 5;
-}
-:where(.column-span-6) {
-  grid-column-end: span 6;
-}
-:where(.column-span-7) {
-  grid-column-end: span 7;
-}
-:where(.column-span-8) {
-  grid-column-end: span 8;
-}
-:where(.column-span-9) {
-  grid-column-end: span 9;
-}
-:where(.column-span-10) {
-  grid-column-end: span 10;
-}
-:where(.column-span-11) {
-  grid-column-end: span 11;
-}
-:where(.column-span-12) {
-  grid-column-end: span 12;
+  grid-column-start: var(--column-start, auto);
+  grid-column-end: span var(--column-span, calc(13 - var(--column-start, 1)));
+  min-inline-size: 0;
 }
 
 /*
@@ -2138,6 +2034,8 @@ small {
  * --control-cursor
  * --control-border-block-end-color
  * --control-border-block-end-width
+ * --control-hover-border (input and textarea)
+ * --control-hover-bg (select)
  */
 .input,
 .textarea,
@@ -2165,8 +2063,8 @@ small {
   cursor: var(--control-cursor);
   /* No outline: none here — the core :focus fallback must survive for browsers
      without :focus-visible. Pointer focus is hidden by core's
-     :focus:not(:focus-visible); keyboard focus swaps in the transparent
-     outline + ring below. */
+     :focus:not(:focus-visible); keyboard focus draws the inset outline below
+     (invalid fields take --form-invalid-border, the documented exception). */
   transition:
     border-color var(--duration),
     box-shadow var(--duration),
@@ -2182,19 +2080,24 @@ small {
 
 .input:hover:not(:disabled),
 .textarea:hover:not(:disabled) {
-  --control-border: var(--text-subtle);
+  --control-border: var(--control-hover-border, var(--text-subtle));
 }
 
 .select:hover:not(:disabled) {
-  --control-bg: var(--surface-subtle);
-}
-
-.input:focus-visible,
-.textarea:focus-visible,
-.select:focus-visible {
-  --control-border: var(--focus);
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+  --control-bg: var(--control-hover-bg, var(--surface-subtle));
+}
+
+/* Field focus is an inset outline: offset = -width keeps every pixel inside
+   the control's border box (any smaller offset bleeds outward), so it covers
+   the border, never touches a .join neighbour or a scrollport edge, and needs
+   no group treatment. Width follows --focus-ring-width, including its
+   prefers-contrast step. Border = shape and validation, outline = focus. */
+.input:focus-visible:not(:disabled),
+.textarea:focus-visible:not(:disabled),
+.select:focus-visible:not(:disabled) {
+  outline: var(--focus-ring-width) solid var(--form-invalid-border, var(--focus));
+  outline-offset: calc(var(--focus-ring-width) * -1);
+  box-shadow: none;
 }
 
 .input[readonly],
@@ -2447,9 +2350,8 @@ small {
 
 .check:focus-visible,
 .radio:focus-visible {
-  --choice-border: var(--focus);
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
 }
 
 .check:disabled,
@@ -2571,8 +2473,8 @@ small {
 }
 
 .file:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
 }
 
 /* Native color picker — keep the browser's dialog and selected-color UI. The
@@ -2608,8 +2510,8 @@ small {
 }
 
 .color:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
 }
 
 @media (forced-colors: active) {
@@ -2973,9 +2875,8 @@ small {
 }
 
 .switch:focus-visible {
-  --switch-border: var(--focus);
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
 }
 
 .switch:disabled {
@@ -3011,6 +2912,10 @@ small {
  * --range-track-height
  * --range-thumb-bg
  * --range-track-bg
+ * --range-fill-bg
+ *
+ * Runtime-written (by actual-css/js/range, never set by hand):
+ * --range-progress
  */
 
 /* Intent boundary — inherited intents do not tint this component.
@@ -3020,10 +2925,17 @@ small {
 }
 
 .range {
-  --range-thumb-size: 1.25rem;
-  --range-track-height: 0.25rem;
+  --range-thumb-size: 1.125rem;
+  --range-track-height: 0.625rem;
   --range-thumb-bg: var(--intent, var(--primary));
   --range-track-bg: var(--border);
+  --range-fill-bg: var(--intent, var(--primary));
+  /* Fill share, written by actual-css/js/range. 0% with no runtime means a
+     plain track — the control stays fully usable without JavaScript. */
+  --range-progress: 0%;
+  /* Logical fill direction: the gradient below cannot use flow-relative
+     keywords, so RTL flips the angle through this hook instead. */
+  --range-fill-from: to right;
 
   appearance: none;
   -webkit-appearance: none;
@@ -3033,16 +2945,29 @@ small {
   cursor: pointer;
 }
 
+:where([dir="rtl"]) .range,
+.range:dir(rtl) {
+  --range-fill-from: to left;
+}
+
 .range::-webkit-slider-runnable-track {
   block-size: var(--range-track-height);
   border-radius: var(--radius-full);
-  background: var(--range-track-bg);
+  background: linear-gradient(
+    var(--range-fill-from),
+    var(--range-fill-bg) var(--range-progress),
+    var(--range-track-bg) var(--range-progress)
+  );
 }
 
 .range::-moz-range-track {
   block-size: var(--range-track-height);
   border-radius: var(--radius-full);
-  background: var(--range-track-bg);
+  background: linear-gradient(
+    var(--range-fill-from),
+    var(--range-fill-bg) var(--range-progress),
+    var(--range-track-bg) var(--range-progress)
+  );
 }
 
 .range::-webkit-slider-thumb {
@@ -3055,6 +2980,10 @@ small {
   background: var(--range-thumb-bg);
   margin-block-start: calc((var(--range-track-height) - var(--range-thumb-size)) / 2);
   cursor: inherit;
+  /* Permanent surface separator: the fill defaults to the thumb color, so
+     without this the thumb would melt into the filled part of the track.
+     Focus-visible keeps this ring and adds the --focus ring outside it. */
+  box-shadow: 0 0 0 2px var(--surface-opaque);
   transition: box-shadow var(--duration);
 }
 
@@ -3065,6 +2994,7 @@ small {
   border: 0;
   background: var(--range-thumb-bg);
   cursor: inherit;
+  box-shadow: 0 0 0 2px var(--surface-opaque);
   transition: box-shadow var(--duration);
 }
 
@@ -3073,20 +3003,23 @@ small {
 }
 
 /*
- * The 1px surface-coloured separator keeps the ring visually distinct from
- * the small, coloured thumb — unlike a full-size input where the same gap
- * would read as an unwanted void.
+ * A thumb pseudo-element takes no reliable outline, so its ring is a solid
+ * --focus shadow (the transparent outline above covers forced colors). The
+ * surface-coloured separator keeps the ring visually distinct from the
+ * coloured thumb — unlike a full-size input where the same gap would
+ * read as an unwanted void. It doubles as the resting separator between
+ * the thumb and the same-coloured fill.
  */
 .range:focus-visible::-webkit-slider-thumb {
   box-shadow:
-    0 0 0 1px var(--surface),
-    0 0 0 calc(1px + var(--focus-ring-width)) var(--focus-ring);
+    0 0 0 2px var(--surface-opaque),
+    0 0 0 calc(2px + var(--focus-ring-width)) var(--focus);
 }
 
 .range:focus-visible::-moz-range-thumb {
   box-shadow:
-    0 0 0 1px var(--surface),
-    0 0 0 calc(1px + var(--focus-ring-width)) var(--focus-ring);
+    0 0 0 2px var(--surface-opaque),
+    0 0 0 calc(2px + var(--focus-ring-width)) var(--focus);
 }
 
 .range:disabled {
@@ -3094,22 +3027,48 @@ small {
   cursor: not-allowed;
   opacity: var(--disabled-opacity);
 }
-
 /* Forced colors: the track must stay a visible line against the page (Canvas
    would merge with it) and the thumb needs a real boundary to remain
-   distinguishable from the track. Disabled keeps GrayText via :disabled.
-   Focus stays on the transparent outline of :focus-visible. */
+   distinguishable from the track. The fill keeps its two-tone split with
+   system colors so the value stays readable. Disabled keeps GrayText via
+   :disabled. Focus stays on the transparent outline of :focus-visible. Track
+   and thumb fills are written on the properties, not only the hooks: an
+   application hook override at the same specificity loads after this file
+   and would win the variable, leaving a Canvas-remapped fill.
+   The split lives in a background-image, which forced-color-adjust: auto
+   drops — so the tracks opt out locally. The colors stay system keywords,
+   keeping native contrast adaptation; only the host keeps adjusting. */
 @media (forced-colors: active) {
   .range {
     --range-track-bg: CanvasText;
     --range-thumb-bg: ButtonFace;
+    --range-fill-bg: Highlight;
+  }
+
+  .range::-webkit-slider-runnable-track {
+    forced-color-adjust: none;
+    background: linear-gradient(
+      var(--range-fill-from),
+      Highlight var(--range-progress),
+      CanvasText var(--range-progress)
+    );
   }
 
+  .range::-moz-range-track {
+    forced-color-adjust: none;
+    background: linear-gradient(
+      var(--range-fill-from),
+      Highlight var(--range-progress),
+      CanvasText var(--range-progress)
+    );
+  }
   .range::-webkit-slider-thumb {
+    background: ButtonFace;
     border: var(--border-width) solid ButtonText;
   }
 
   .range::-moz-range-thumb {
+    background: ButtonFace;
     border: var(--border-width) solid ButtonText;
   }
 }
@@ -3121,20 +3080,29 @@ small {
  *
  * Each .choice-card is a <label> wrapping a native radio or checkbox. When
  * :has() is supported the input is visually hidden and the card mirrors its
- * state: checked border and tint, checkmark badge (round for radio, rounded
- * square for checkbox), focus ring, disabled dimming. Without :has() the
- * native input stays visible so selection state never disappears.
+ * state: an indicator on the leading edge (a ring for radio, a box for
+ * checkbox) that fills with a check, checked border and tint, focus ring,
+ * disabled dimming. Without :has() the native input stays visible in the
+ * indicator's slot, so selection state never disappears.
+ *
+ * The card is a two-column grid: the indicator in the first column, level
+ * with the first row, and each child element of the label on its own row in
+ * the second. Wrap loose text in an element. A corner badge for tiles is a
+ * documented recipe on these same layers, not a variant.
  *
- * The badge overhangs the top-right corner by 0.375em; ancestors with
- * overflow: hidden will clip it. Pair with grid or flex utilities for group
- * layout.
+ * .chip is the compact pill form (filter chips, selectable tags): control
+ * height, and a leading dot that turns into the check in a fixed slot, so
+ * checking never moves the label.
  *
  * Public hooks:
  * --choice-card-pad
+ * --choice-card-gap
  * --choice-card-radius
  * --choice-card-border
  * --choice-card-bg
  * --choice-card-check-size
+ * --choice-chip-dot (read-only, on .chip ::before: the check-slot centre as a
+ *   circle() position, for a theme that grows the dot into a fill)
  */
 :where(.choice-card) {
   --intent: initial;
@@ -3143,19 +3111,25 @@ small {
 
 .choice-card {
   --choice-card-pad: var(--density-space, var(--space-40));
+  --choice-card-gap: var(--space-30);
   --choice-card-radius: var(--radius);
   --choice-card-border: var(--border);
   --choice-card-bg: var(--surface);
-  --choice-card-check-size: 1.5em;
+  --choice-card-check-size: 1.25em;
 
   position: relative;
-  display: block;
+  display: grid;
+  grid-template-columns: var(--choice-card-check-size) minmax(0, 1fr);
+  /* why: a card stretched by a taller grid neighbour keeps its rows at the
+     top instead of spreading them. */
+  align-content: start;
+  column-gap: var(--choice-card-gap);
   padding: var(--choice-card-pad);
   border: var(--border-width) solid var(--form-invalid-border, var(--choice-card-border));
   border-radius: var(--choice-card-radius);
   background: var(--choice-card-bg);
   color: var(--text);
-  /* Consumed so .sm/.lg reach the card; the badge's em sizing follows. */
+  /* Consumed so .sm/.lg reach the card; the indicator's em sizing follows. */
   font-size: var(--control-font-size);
   cursor: pointer;
   transition:
@@ -3164,6 +3138,18 @@ small {
     box-shadow var(--duration);
 }
 
+.choice-card > * {
+  grid-column: 2;
+}
+
+/* The input owns the indicator's cell: visible there without :has(), hidden
+   in it with :has(). */
+.choice-card > :is(input[type="radio"], input[type="checkbox"]) {
+  grid-area: 1 / 1;
+  place-self: center;
+  margin: 0;
+}
+
 /* The native input is visually hidden but stays focusable and participates in
    form submission and keyboard navigation (sr-only pattern). Guarded: without
    :has() the card cannot mirror the input's state, so the visible native
@@ -3184,8 +3170,8 @@ small {
 
 /* Focus ring on the label follows the hidden input's focus. */
 .choice-card:has(:focus-visible) {
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
 }
 
 .choice-card:has(:disabled) {
@@ -3209,32 +3195,41 @@ small {
   }
 }
 
-/* Checkmark badge — always rendered at scale(0) and scaled in on check, so
-   the entrance can transition (a pseudo created on :checked could not). */
+/* Indicator: ::before is the ring or box, ::after the check. Both share the
+   input's cell, centred on the first line — not the first row, which a long
+   label wraps — and stay hidden until :has() can mirror the input. The em
+   margin is the lh-less fallback at the default 1.5 line-height. */
 .choice-card::before,
 .choice-card::after {
   content: "";
-  position: absolute;
-  inset-inline-end: -0.375em;
-  inset-block-start: -0.375em;
+  grid-area: 1 / 1;
+  align-self: start;
+  margin-block-start: calc((1.5em - var(--choice-card-check-size)) / 2);
+  margin-block-start: calc((1lh - var(--choice-card-check-size)) / 2);
   inline-size: var(--choice-card-check-size);
   block-size: var(--choice-card-check-size);
   transform: scale(0);
-  transition: transform var(--duration);
+  transition:
+    transform var(--duration),
+    background-color var(--duration),
+    border-color var(--duration);
 }
 
-/* Badge disc — circle for radio, rounded square for checkbox */
+/* A border, not an inset shadow: forced colors drop shadows, and the resting
+   ring is the only sign of an unchecked option. The invalid border reaches it
+   through the same hook as the card's. */
 .choice-card::before {
-  background: var(--intent, var(--state-selected));
-  box-shadow: 0 0 0 2px var(--surface);
+  border: max(var(--border-width), 1.5px) solid var(--form-invalid-border, var(--text-muted));
   z-index: 1;
 }
 
-.choice-card:has(input[type="radio"])::before {
+/* :where() keeps the shape at single-class weight, so .chip can reshape the
+   layer without out-arguing the input-type test. */
+.choice-card:where(:has(input[type="radio"]))::before {
   border-radius: var(--radius-full);
 }
 
-.choice-card:has(input[type="checkbox"])::before {
+.choice-card:where(:has(input[type="checkbox"]))::before {
   border-radius: var(--radius-sm);
 }
 
@@ -3246,18 +3241,86 @@ small {
   z-index: 2;
 }
 
-.choice-card:has(:checked)::before,
+/* Guarded with the input's hiding above: a resting ring beside a visible
+   native input would draw the indicator twice. */
+@supports selector(:has(*)) {
+  .choice-card::before {
+    transform: none;
+  }
+}
+
+.choice-card:has(:checked)::before {
+  border-color: var(--intent, var(--state-selected));
+  background: var(--intent, var(--state-selected));
+}
+
 .choice-card:has(:checked)::after {
   transform: scale(1);
 }
 
+/* Chip — the rules above stay in force; this section only relocates the
+   indicator. Must follow them: several ties are won by source order. */
+.choice-card.chip {
+  --choice-card-pad: 0 var(--control-pad-x);
+  --choice-card-radius: var(--radius-full);
+  --choice-card-check-size: 1em;
+
+  display: inline-flex;
+  align-items: center;
+  min-block-size: var(--control-size);
+  line-height: 1.2;
+  /* The dot layer sits under the label at z-index -1. */
+  isolation: isolate;
+}
+
+/* ::before is a full-bleed layer clipped to a dot centred on the check slot,
+   so a theme can grow the same clip into a selected fill. The chip itself
+   must not clip (its focus ring is an outline), hence the inherited radius. */
+.choice-card.chip::before {
+  --choice-chip-dot: calc(var(--control-pad-x) + var(--choice-card-check-size) / 2) 50%;
+
+  position: absolute;
+  inset: 0;
+  /* why: an absolute box honours self-alignment — the card's start would
+     shrink this layer to 0 height and the dot with it. */
+  align-self: auto;
+  margin: 0;
+  inline-size: auto;
+  block-size: auto;
+  border: 0;
+  border-radius: inherit;
+  background: var(--text-subtle);
+  transform: none;
+  clip-path: circle(0.1875em at var(--choice-chip-dot));
+  z-index: -1;
+  transition: clip-path var(--duration);
+}
+
+.choice-card.chip:has(:checked)::before {
+  clip-path: circle(0 at var(--choice-chip-dot));
+}
+
+/* The check keeps the card's scale-in, in flow ahead of the label. */
+.choice-card.chip::after {
+  order: -1;
+  flex: none;
+  align-self: center;
+  margin-block: 0;
+  margin-inline: 0 0.375em;
+  background: var(--intent, var(--state-selected));
+  -webkit-mask-size: contain;
+  mask-size: contain;
+}
+
 /* The native input is hidden and the checked marker is custom-drawn: without
    this repair, forced colors pushes disc and check to the same system color
    and the state disappears. Highlight/Canvas/HighlightText are preserved as-is,
    so no forced-color-adjust is needed. The pseudo is not focusable — the
-   outline is a separator against the card, not a focus channel. */
+   outline separates the disc from whatever it overlaps (the card's border,
+   for a corner-badge recipe), not a focus channel. */
 @media (forced-colors: active) {
   .choice-card:has(:checked)::before {
+    border-color: Highlight;
     background: Highlight;
     outline: 2px solid Canvas;
   }
@@ -3265,6 +3328,20 @@ small {
   .choice-card:has(:checked)::after {
     background: HighlightText;
   }
+
+  /* A chip has no disc behind its check: the check carries the state alone,
+     and dropping the checked layer also drops any theme fill. */
+  .choice-card.chip::before {
+    background: CanvasText;
+  }
+
+  .choice-card.chip:has(:checked)::before {
+    content: none;
+  }
+
+  .choice-card.chip:has(:checked)::after {
+    background: CanvasText;
+  }
 }
 
 /*
@@ -3278,7 +3355,6 @@ small {
  * Arbitrary menu and popover behavior belongs elsewhere.
  *
  * Internal:
- * --control-border
  * --control-bg
  */
 /* This enhancement is excluded from forced-colors, where the native/shared
@@ -3303,11 +3379,12 @@ small {
         box-shadow: var(--shadow-popout);
       }
 
+      /* Same inset outline as a focused field (control.css). */
       &:open {
-        --control-border: var(--border);
         --control-bg: var(--surface-raised);
-        outline: none;
-        box-shadow: var(--focus-ring-shadow);
+        outline: var(--focus-ring-width) solid var(--form-invalid-border, var(--focus));
+        outline-offset: calc(var(--focus-ring-width) * -1);
+        box-shadow: none;
       }
 
       &::picker-icon {
@@ -3539,7 +3616,7 @@ small {
   padding-block: 0;
   padding-inline: calc((var(--otp-cell-size) - 1ch) / 2) 0;
   border: 0;
-  outline: 2px solid transparent;
+  outline: none;
   box-shadow: none;
   background: transparent;
   color: var(--text);
@@ -3564,6 +3641,14 @@ small {
    character after it: the state rules select the cells as following siblings
    (input:focus ~ span, input:disabled ~ span, …), so that order is part of the
    contract. */
+/* The documented markup puts .input on the native input, so the field ring
+   (.input:focus-visible:not(:disabled), control.css) would outrank the reset
+   above and draw that group ring; this selector must stay one step above it.
+   No transparent outline either: forced colors would paint it as a ring. */
+.otp > input:focus-visible:not(:disabled) {
+  outline: none;
+}
+
 .otp > input:focus ~ span {
   --otp-cell-border: var(--focus);
   --otp-cell-border-width: calc(var(--border-width) * 2);
@@ -3636,7 +3721,6 @@ small {
  * --btn-min-size
  * --btn-pad-x
  * --btn-radius
- * --btn-focus-color
  * --btn-gap
  * --btn-hover-overlay
  * --btn-default-bg
@@ -3649,7 +3733,6 @@ small {
  * --btn-fg
  * --btn-border
  * --btn-default-hover-bg
- * --btn-focus-ring-color
  * --btn-border-block-end-color
  * --btn-border-block-end-width
  * --spinner-width
@@ -3676,7 +3759,6 @@ small {
   --btn-border: var(--ui-border, var(--btn-default-border, transparent));
   --btn-default-hover-bg: var(--btn-bg);
   --btn-radius: var(--radius);
-  --btn-focus-color: var(--intent, var(--focus));
   --btn-hover-overlay: var(--hover-overlay, rgb(0 0 0 / 0.08));
 
   /* Positioning context for indicators, overlays, and grouped states. */
@@ -3718,12 +3800,6 @@ small {
   padding: 0;
 }
 
-@supports (color: color-mix(in oklch, red, white)) {
-  .btn {
-    --btn-focus-ring-color: color-mix(in oklch, var(--btn-focus-color) 28%, transparent);
-  }
-}
-
 /* .solid/.soft/.outline are shared via variants.css. The baseline --btn-*
    fallbacks make .btn solid by default; .ghost/.link are .btn-only variants. */
 .btn.ghost {
@@ -3811,15 +3887,13 @@ small {
   text-decoration-thickness: 0.12em;
 }
 
+/* why: the ring must contrast with the surface around the button, not with
+   the button, so it is --focus for every intent and variant — the theme
+   guarantees --focus against --surface and --surface-solid, which covers
+   the page, a solid band and nested surfaces without tracking any context. */
 .btn:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: 0 0 0 var(--focus-ring-width) var(--btn-focus-ring-color, var(--focus-ring));
-}
-
-.btn.link:focus-visible {
-  outline: var(--focus-outline);
-  outline-offset: 0.2em;
-  box-shadow: none;
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
 }
 
 .btn:disabled {
@@ -3865,6 +3939,98 @@ a.btn[aria-disabled="true"] {
   }
 }
 
+/*
+ * Close button — the shared X that removes or closes the thing it sits in.
+ *
+ * Docs: docs/pages/components/close.md
+ *
+ * .close is always the X, painted from the --icon-close mask: an empty
+ * <button class="close" aria-label="…"> needs no icon font and no text glyph.
+ * The mechanism stays with the container (command="request-close",
+ * method="dialog", command="--dismiss", application logic); the class only
+ * names the visual action.
+ *
+ * The containers that host one (alert, badge) tune it from their own files by
+ * declaring the size hooks and their geometry; this file owns the control
+ * and the dialog-surface corner, shared by .modal and .drawer.
+ *
+ * Public hooks:
+ * --close-size
+ * --close-icon-size
+ */
+.close {
+  display: inline-grid;
+  place-items: center;
+  flex: none;
+  inline-size: var(--close-size, var(--control-size));
+  block-size: var(--close-size, var(--control-size));
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+
+.close::before {
+  content: "";
+  inline-size: var(--close-icon-size, 1rem);
+  block-size: var(--close-icon-size, 1rem);
+  background: currentColor;
+  -webkit-mask: var(--icon-close) center / contain no-repeat;
+  mask: var(--icon-close) center / contain no-repeat;
+}
+
+/* An inset overlay, not a background: it tints whatever fill the context gave
+   the control (the dialog corner's --surface-subtle) instead of replacing it. */
+@media (hover: hover) {
+  .close:hover {
+    box-shadow: inset 0 0 0 999px var(--hover-overlay);
+  }
+}
+
+.close:active {
+  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+}
+
+.close:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: var(--focus-outline-offset);
+}
+
+/* Dialog corner — out of the content flow, anchored to the positioned dialog
+   surface rather than to the header or a scroll container inside it. Matched
+   on the documented positions (the dialog, its form, its header, or a form
+   inside that header) so a .close inside content — an alert in the body —
+   keeps its own place. */
+:where(dialog):is(.modal, .drawer) > .close,
+:where(dialog):is(.modal, .drawer) > :is(form, header) > .close,
+:where(dialog):is(.modal, .drawer) > :is(form, header) > :is(form, header) > .close {
+  position: absolute;
+  z-index: 1;
+  inset-block-start: var(--space-20);
+  inset-inline-end: var(--space-20);
+  background: var(--surface-subtle);
+  color: var(--text-muted);
+}
+
+@media (hover: hover) {
+  :where(dialog):is(.modal, .drawer) > .close:hover,
+  :where(dialog):is(.modal, .drawer) > :is(form, header) > .close:hover,
+  :where(dialog):is(.modal, .drawer) > :is(form, header) > :is(form, header) > .close:hover {
+    color: var(--text);
+  }
+}
+
+@media (forced-colors: active) {
+  /* The X is a currentColor mask fill: without this the system remaps the
+    background to Canvas and the glyph disappears. Kept on the pseudo so the
+    host keeps its native color and focus adaptation. */
+  .close::before {
+    forced-color-adjust: none;
+  }
+}
+
 /*
  * Badges for compact labels, counts, and state hints.
  *
@@ -3881,7 +4047,6 @@ a.btn[aria-disabled="true"] {
  * --badge-icon-size
  * --badge-dot-size
  * --badge-radius
- * --badge-dismiss-icon-size
  *
  * Internal:
  * --badge-default-bg
@@ -3912,7 +4077,10 @@ a.btn[aria-disabled="true"] {
   --badge-font-size: var(--font-size-sm);
   --badge-icon-size: 1em;
   --badge-dot-size: 0.5rem;
-  --badge-dismiss-icon-size: 0.875em;
+  /* Declared on the badge, not the button, so an author can still set them
+     on either. Same element as --badge-size, so .sm/.lg carry through. */
+  --close-size: max(var(--badge-size), 24px);
+  --close-icon-size: 0.875em;
   --badge-default-bg: var(--surface-subtle);
   --badge-default-fg: var(--intent, var(--text));
   --badge-default-border: var(--border);
@@ -3962,8 +4130,8 @@ a.btn[aria-disabled="true"] {
   --badge-dot-size: 0.625rem;
 }
 
-/* Decorative children follow the badge's optical size. Text and interactive
-   dismiss buttons retain their own boxes. */
+/* Decorative children follow the badge's optical size. Text and the .close
+   button retain their own boxes. */
 .badge > :where(svg, img, [aria-hidden="true"]:not(.dot)) {
   flex: none;
   /* The shared rule maps --badge-icon-size onto font-size. One em is therefore
@@ -4016,45 +4184,15 @@ a.btn[aria-disabled="true"] {
   background-color: currentColor;
 }
 
-.badge > button {
-  display: inline-grid;
-  place-items: center;
-  flex: 0 0 auto;
-  /* WCAG 2.5.8 floors pointer targets at 24 CSS px. Density and local size may
-     keep the badge visually compact through the negative margins, but never
-     shrink its action target below that literal floor. */
-  min-inline-size: max(var(--badge-size), 24px);
-  min-block-size: max(var(--badge-size), 24px);
+/* Removable tag — a .close (components/close.css) inside the pill. WCAG 2.5.8
+   floors pointer targets at 24 CSS px: density and local size may keep the
+   badge visually compact through the negative margins, but never shrink the
+   target below that literal floor. */
+.badge > .close {
   margin-block: -0.25rem;
   margin-inline-start: -0.15em;
   margin-inline-end: -0.45em;
-  padding: 0.25rem;
-  border: 0;
   border-radius: var(--radius-full);
-  background: transparent;
-  color: inherit;
-  font: inherit;
-  line-height: 1;
-  cursor: pointer;
-}
-
-/* Dismiss mark — an empty dismiss button paints its own X from the shared
-   --icon-close mask, so no icon font or text glyph is required in the markup
-   (same contract as .alert-dismiss and .dialog-close). A mask box is a block
-   box, so place-items centers the ink itself; a text glyph would only center
-   its line box and land the ink low, because a lowercase x has no descender
-   and only x-height of ascent. A button with its own content keeps it. */
-.badge > button:empty::before {
-  content: "";
-  inline-size: var(--badge-dismiss-icon-size);
-  block-size: var(--badge-dismiss-icon-size);
-  background: currentColor;
-  -webkit-mask: var(--icon-close) center / contain no-repeat;
-  mask: var(--icon-close) center / contain no-repeat;
-}
-
-.badge > button:not(:disabled):hover {
-  background: var(--hover-overlay);
 }
 
 /* Hover recipes — sets --ui-hover-bg consumed by the hover rule below.
@@ -4145,7 +4283,6 @@ a.badge[aria-disabled="true"] {
  * --alert-font-size
  * --alert-radius
  * --alert-icon-size
- * --alert-dismiss-size
  * --alert-border-inline-start-color
  * --alert-border-inline-start-width
  *
@@ -4156,7 +4293,6 @@ a.badge[aria-disabled="true"] {
  * --alert-bg
  * --alert-fg
  * --alert-border
- * --alert-dismiss-icon-size
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
@@ -4205,13 +4341,13 @@ a.badge[aria-disabled="true"] {
    The slots are excluded because they are anatomy, not content: an
    admonition's title bar has to stay flush against its body. The list follows
    the anatomy, so it grows with it. */
-.alert > :not(:where(.alert-icon, .alert-dismiss, .alert-title, .alert-body)) {
+.alert > :not(:where(.alert-icon, .close, .alert-title, .alert-body)) {
   margin-block: 0;
 }
 
 .alert
-  > :not(:where(.alert-icon, .alert-dismiss, .alert-title, .alert-body))
-  + :not(:where(.alert-icon, .alert-dismiss, .alert-title, .alert-body)) {
+  > :not(:where(.alert-icon, .close, .alert-title, .alert-body))
+  + :not(:where(.alert-icon, .close, .alert-title, .alert-body)) {
   margin-block-start: var(--space-10);
 }
 
@@ -4249,42 +4385,24 @@ a.badge[aria-disabled="true"] {
   vertical-align: -0.125em;
 }
 
-/* Dismiss — compact close button for inline alerts. Transparent at rest with
-   a reduced opacity glyph so it stays secondary inside an already-colored
-   alert; hover reinforces it via the shared overlay. Uses the shared
-   --icon-close mask, so no icon font or text glyph is required in the markup.
-   Standard alerts place it as a direct trailing child; admonitions place it
-   inside .alert-title (see below). */
-.alert-dismiss {
-  --alert-dismiss-size: 1.75rem;
-  --alert-dismiss-icon-size: 0.875rem;
-
-  display: inline-grid;
-  place-items: center;
-  inline-size: var(--alert-dismiss-size);
-  block-size: var(--alert-dismiss-size);
-  flex: none;
-  padding: 0;
-  border: 0;
-  border-radius: var(--radius);
-  background: transparent;
-  color: currentColor;
-  opacity: 0.65;
-  cursor: pointer;
+/* Close (components/close.css) — compact, and at reduced opacity so it stays
+   secondary inside an already-colored alert. Standard alerts place it as a
+   direct trailing child; admonitions place it inside .alert-title (see
+   below). The sizes are declared on the alert so an author can still set
+   them on the alert or on the button. */
+.alert {
+  --close-size: 1.75rem;
+  --close-icon-size: 0.875rem;
 }
 
-.alert-dismiss::before {
-  content: "";
-  inline-size: var(--alert-dismiss-icon-size);
-  block-size: var(--alert-dismiss-icon-size);
-  background: currentColor;
-  -webkit-mask: var(--icon-close) center / contain no-repeat;
-  mask: var(--icon-close) center / contain no-repeat;
+.alert > .close,
+.alert > .alert-title > .close {
+  opacity: 0.65;
 }
 
 @media (hover: hover) {
-  .alert-dismiss:hover {
-    background: var(--hover-overlay);
+  .alert > .close:hover,
+  .alert > .alert-title > .close:hover {
     opacity: 1;
   }
 }
@@ -4293,7 +4411,7 @@ a.badge[aria-disabled="true"] {
    both. Icon and dismiss are pinned to the outer columns; anything else (the
    message content) flows into the remaining text column. */
 @supports selector(.alert:has(> *)) {
-  .alert:has(> .alert-icon, > .alert-dismiss) {
+  .alert:has(> .alert-icon, > .close) {
     display: grid;
     grid-template-columns: minmax(0, 1fr);
     align-items: var(--items-align, start);
@@ -4312,19 +4430,19 @@ a.badge[aria-disabled="true"] {
     margin-block-start: 0.125em;
   }
 
-  .alert:has(> .alert-icon) > :not(.alert-icon, .alert-dismiss) {
+  .alert:has(> .alert-icon) > :not(.alert-icon, .close) {
     grid-column: 2;
   }
 
-  .alert:has(> .alert-dismiss) {
+  .alert:has(> .close) {
     grid-template-columns: minmax(0, 1fr) auto;
   }
 
-  .alert:has(> .alert-icon):has(> .alert-dismiss) {
+  .alert:has(> .alert-icon):has(> .close) {
     grid-template-columns: auto minmax(0, 1fr) auto;
   }
 
-  .alert:has(> .alert-dismiss) > .alert-dismiss {
+  .alert:has(> .close) > .close {
     grid-column: -2 / -1;
     grid-row: 1;
   }
@@ -4372,8 +4490,8 @@ a.badge[aria-disabled="true"] {
   border-start-end-radius: calc(var(--alert-radius, var(--radius-lg)) - var(--border-width));
 }
 
-/* Dismiss inside an admonition title bar rides the inline end. */
-.alert.admonition > .alert-title > .alert-dismiss {
+/* Close inside an admonition title bar rides the inline end. */
+.alert.admonition > .alert-title > .close {
   margin-inline-start: auto;
 }
 
@@ -4466,7 +4584,9 @@ a.badge[aria-disabled="true"] {
  *
  * Child contract:
  * Direct .bleed children escape --card-pad (negative inset, wider media);
- * edge children inherit the card corners. .bleed must be a direct child.
+ * edge children inherit the card corners. .bleed must be a direct child, and
+ * its rules live in components/bleed.css — the card relays --card-pad to the
+ * shared --surface-pad that they read.
  *
  * Internal:
  * --card-bg
@@ -4497,6 +4617,10 @@ a.badge[aria-disabled="true"] {
   --card-bg: var(--ui-bg, var(--surface-raised));
   --card-fg: var(--ui-fg, var(--text));
 
+  /* The inset a direct .bleed child cancels (components/bleed.css). Relayed
+     from --card-pad so .compact and an author override both reach it. */
+  --surface-pad: var(--card-pad);
+
   /* Keep contextual descendants tied to the surface this card actually owns. */
   --heading: var(--card-fg);
   --busy-overlay-bg: var(--card-bg);
@@ -4562,45 +4686,6 @@ a.badge[aria-disabled="true"] {
   --card-pad: var(--space-20);
 }
 
-/* Full-bleed children */
-.card > .bleed {
-  margin-inline: calc(var(--card-pad) * -1);
-  max-inline-size: none;
-}
-
-.card > .bleed:first-child {
-  margin-block-start: calc(var(--card-pad) * -1);
-  border-start-start-radius: inherit;
-  border-start-end-radius: inherit;
-}
-
-.card > .bleed:last-child {
-  margin-block-end: calc(var(--card-pad) * -1);
-  border-end-start-radius: inherit;
-  border-end-end-radius: inherit;
-}
-
-/* Media bleed */
-.card > :where(img, picture, video, canvas, svg).bleed {
-  display: block;
-  inline-size: calc(100% + var(--card-pad) * 2);
-  max-inline-size: none;
-}
-
-.card > picture.bleed {
-  overflow: hidden;
-}
-
-.card > picture.bleed > img {
-  display: block;
-  inline-size: 100%;
-  block-size: auto;
-}
-
-/* Padded structural bleed */
-.card > :where(header, footer, figure).bleed {
-  padding: var(--card-pad);
-}
 @media print {
   .card {
     border: var(--border-width) solid CanvasText;
@@ -4622,8 +4707,9 @@ a.badge[aria-disabled="true"] {
  * --dialog-icon-size
  * --dialog-icon-glyph-size
  *
+ * The corner close control is .close (components/close.css).
+ *
  * Internal:
- * --dialog-close-icon-size
  * --dialog-focus-bleed
  * --dialog-viewport-block
  * --dialog-viewport-gap-default
@@ -4709,11 +4795,16 @@ a.badge[aria-disabled="true"] {
 
 :where(dialog).modal.scrollable > form > :not(:is(header, footer)),
 :where(dialog).modal.scrollable > .stack > :not(:is(header, footer)) {
-  --dialog-focus-bleed: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+  --dialog-focus-bleed: calc(
+    var(--focus-outline-offset) +
+    max(var(--focus-ring-width), var(--border-width) * 2)
+  );
 
   min-block-size: 0;
   /* Keep focus paint inside the clip without moving the body off the fixed
-     header and footer edges. */
+     header and footer edges. The reserve covers the thicker of the two
+     outside indicators: the :focus baseline (2 × border) and the component
+     line (--focus-ring-width, 3px in bootstrap-v6). */
   margin-inline: calc(var(--dialog-focus-bleed) * -1);
   padding-inline: var(--dialog-focus-bleed);
   overflow: auto;
@@ -4736,7 +4827,7 @@ a.badge[aria-disabled="true"] {
    The form/.stack anatomy is structural, so it stays in :where() and never
    lends .stack's specificity to a bare <form>. */
 :where(dialog).modal > :where(form, .stack) > header {
-  padding-inline-end: calc(var(--control-size) + var(--space-30));
+  padding-inline-end: calc(var(--close-size, var(--control-size)) + var(--space-30));
 }
 
 :where(dialog).modal > :where(form, .stack) > footer {
@@ -4900,59 +4991,6 @@ html.has-modal-open.had-scrollbar {
   }
 }
 
-/* Close control. A close button is an action attached to a surface, so it
-   never participates in the content flow — absolute at the panel's top
-   inline-end, inside the surface. The glyph comes from --icon-close, masked to
-   currentColor, so no icon font or text glyph is required in the markup. */
-.dialog-close {
-  --dialog-close-icon-size: 1rem;
-
-  display: inline-grid;
-  place-items: center;
-  padding: 0;
-  border: 0;
-  border-radius: var(--radius);
-  color: var(--text-muted);
-  cursor: pointer;
-
-  /* Out of flow, anchored to the positioned dialog surface, not the header or
-     any scroll container inside it. */
-  position: absolute;
-  z-index: 1;
-  inset-block-start: var(--space-20);
-  inset-inline-end: var(--space-20);
-
-  inline-size: var(--control-size);
-  block-size: var(--control-size);
-
-  background: var(--surface-subtle);
-}
-
-.dialog-close::before {
-  content: "";
-  inline-size: var(--dialog-close-icon-size);
-  block-size: var(--dialog-close-icon-size);
-  background: currentColor;
-  -webkit-mask: var(--icon-close) center / contain no-repeat;
-  mask: var(--icon-close) center / contain no-repeat;
-}
-
-@media (hover: hover) {
-  .dialog-close:hover {
-    box-shadow: inset 0 0 0 999px var(--hover-overlay);
-    color: var(--text);
-  }
-}
-
-.dialog-close:active {
-  box-shadow: inset 0 0 0 999px var(--hover-overlay);
-}
-
-.dialog-close:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
-}
-
 /*
  * Drawer — modal side-sheet built on the native dialog element.
  *
@@ -4972,6 +5010,8 @@ html.has-modal-open.had-scrollbar {
  * --drawer-size
  * --drawer-pad
  *
+ * The corner close control is .close (components/close.css).
+ *
  * Internal:
  * --drawer-closed-translate (side/RTL positioning state)
  * --drawer-focus-bleed
@@ -4981,6 +5021,8 @@ html.has-modal-open.had-scrollbar {
 :where(dialog).drawer {
   --drawer-size: 20rem;
   --drawer-pad: var(--space-40);
+  /* The inset a direct .bleed child cancels (components/bleed.css). */
+  --surface-pad: var(--drawer-pad);
   --drawer-closed-translate: -100%;
   /* Exit is shorter than entry so the panel clears quickly; the scrim reads
      the same variable through inheritance and never lags the panel. */
@@ -5080,15 +5122,20 @@ html.has-modal-open.had-scrollbar {
 /* The body region absorbs the panel's height and scrolls. A drawer is a
    full-height shell by definition, so it always scrolls its body — unlike the
    modal, which sizes to its content and opts in with .scrollable. Header and
-   footer keep their own tracks; .drawer-close is named because a generic
+   footer keep their own tracks; .close is named because a generic
    exclusion list is easier to trust than its `position: absolute`. */
-:where(dialog).drawer > :not(:is(header, footer, form, .drawer-close)),
-:where(dialog).drawer > form > :not(:is(header, footer, .drawer-close)) {
-  --drawer-focus-bleed: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+:where(dialog).drawer > :not(:is(header, footer, form, .close)),
+:where(dialog).drawer > form > :not(:is(header, footer, .close)) {
+  --drawer-focus-bleed: calc(
+    var(--focus-outline-offset) +
+    max(var(--focus-ring-width), var(--border-width) * 2)
+  );
 
   min-block-size: 0;
   /* Keep focus paint inside the clip without moving the body off the fixed
-     header and footer edges. */
+     header and footer edges. The reserve covers the thicker of the two
+     outside indicators: the :focus baseline (2 × border) and the component
+     line (--focus-ring-width, 3px in bootstrap-v6). */
   margin-inline: calc(var(--drawer-focus-bleed) * -1);
   padding-inline: var(--drawer-focus-bleed);
   overflow: auto;
@@ -5160,57 +5207,87 @@ html.has-modal-open.had-scrollbar {
    control. */
 :where(dialog).drawer > header,
 :where(dialog).drawer > form > header {
-  padding-inline-end: calc(var(--control-size) + var(--space-30));
+  padding-inline-end: calc(var(--close-size, var(--control-size)) + var(--space-30));
 }
 
-/* Close control, owned here so a drawer-only build does not depend on
-   modal.css. Mirrors the modal's .dialog-close placement: absolute at the
-   panel's top inline-end, out of the content flow. */
-.drawer-close {
-  --drawer-close-icon-size: 1rem;
+/*
+ * Full-bleed children — the shared escape hatch for a padded surface.
+ *
+ * Docs: docs/pages/components/bleed.md
+ *
+ * A surface that insets its direct children relays that inset to them as
+ * --surface-pad; a direct .bleed child cancels it and reaches the surface
+ * edge. Card and drawer pad at the container level, so they own the token
+ * there; the accordion pads its summary and its panel instead, so the panel
+ * owns it and the item does not.
+ *
+ * Why the token is handed to the children rather than declared on the surface:
+ * custom properties inherit, so a surface-level declaration would also reach a
+ * grandchild, which sits at its wrapper's edge rather than the surface's and
+ * would pull a negative margin out of the wrong box. Relaying it one level and
+ * clearing it below keeps the child combinator's guarantee while leaving the
+ * .bleed rules themselves free of the surface list.
+ *
+ * Why the clearing rule comes first: both rules are zero-specificity, so
+ * source order decides where they overlap, and they overlap on exactly one
+ * element — a direct child of a surface nested inside another surface. That
+ * child must keep the inner surface's inset, so the relay has to win.
+ *
+ * Public hooks:
+ * --bleed-pad (read-only: the inset relayed to a surface's direct children;
+ *   pad a band that is not a header/footer/figure with it)
+ *
+ * Framework plumbing:
+ * --surface-pad (declared by the surface)
+ */
+:where(.card, .drawer, .accordion details > summary + *) > * * {
+  --bleed-pad: initial;
+}
 
-  display: inline-grid;
-  place-items: center;
-  padding: 0;
-  border: 0;
-  border-radius: var(--radius);
-  color: var(--text-muted);
-  cursor: pointer;
+:where(.card, .drawer, .accordion details > summary + *) > * {
+  --bleed-pad: var(--surface-pad);
+}
 
-  position: absolute;
-  z-index: 1;
-  inset-block-start: var(--space-20);
-  inset-inline-end: var(--space-20);
+/* Inert without a surface: the fallback resolves the negative margin to zero
+   rather than dropping the declaration and inheriting a stray inset. */
+.bleed {
+  margin-inline: calc(var(--bleed-pad, 0px) * -1);
+  max-inline-size: none;
+}
 
-  inline-size: var(--control-size);
-  block-size: var(--control-size);
+.bleed:first-child {
+  margin-block-start: calc(var(--bleed-pad, 0px) * -1);
+  border-start-start-radius: inherit;
+  border-start-end-radius: inherit;
+}
 
-  background: var(--surface-subtle);
+.bleed:last-child {
+  margin-block-end: calc(var(--bleed-pad, 0px) * -1);
+  border-end-start-radius: inherit;
+  border-end-end-radius: inherit;
 }
 
-.drawer-close::before {
-  content: "";
-  inline-size: var(--drawer-close-icon-size);
-  block-size: var(--drawer-close-icon-size);
-  background: currentColor;
-  -webkit-mask: var(--icon-close) center / contain no-repeat;
-  mask: var(--icon-close) center / contain no-repeat;
+/* Media bleed */
+:where(img, picture, video, canvas, svg).bleed {
+  display: block;
+  inline-size: calc(100% + var(--bleed-pad, 0px) * 2);
+  max-inline-size: none;
 }
 
-@media (hover: hover) {
-  .drawer-close:hover {
-    box-shadow: inset 0 0 0 999px var(--hover-overlay);
-    color: var(--text);
-  }
+picture.bleed {
+  overflow: hidden;
 }
 
-.drawer-close:active {
-  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+picture.bleed > img {
+  display: block;
+  inline-size: 100%;
+  block-size: auto;
 }
 
-.drawer-close:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+/* Padded structural bleed — the band keeps the surface's own rhythm while its
+   background reaches the edge. */
+:where(header, footer, figure).bleed {
+  padding: var(--bleed-pad, 0px);
 }
 
 
@@ -5231,6 +5308,7 @@ html.has-modal-open.had-scrollbar {
  * Public hooks:
  * --flyout-inline-size
  * --flyout-max-inline-size
+ * --flyout-pad
  *
  * Internal:
  * --menu-item-size (derived from --control-size for menu rows)
@@ -5283,10 +5361,13 @@ html.has-modal-open.had-scrollbar {
   );
   overflow: auto;
   margin: 0;
-  padding: var(--space-10);
+  /* Tight by default for action menus, whose items carry their own padding.
+     Rich panels (forms, pickers) opt into dialog air per instance. */
+  padding: var(--flyout-pad, var(--space-10));
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
   background: var(--surface-raised);
+  color: var(--text);
   box-shadow: var(--shadow-popout);
   list-style: none;
   opacity: 1;
@@ -5519,6 +5600,18 @@ html.has-modal-open.had-scrollbar {
   border-block-start: var(--border-width) solid var(--border);
 }
 
+@media (forced-colors: active) {
+  /* The check mark is a currentColor mask fill and the mixed/radio marks are
+    currentColor gradients: without this the system remaps them to Canvas or
+    drops the image and the state disappears. Kept on the pseudo so the host
+    keeps its native color and focus adaptation. */
+  .menu-item[role="menuitemcheckbox"][aria-checked="true"]::before,
+  .menu-item[role="menuitemcheckbox"][aria-checked="mixed"]::before,
+  .menu-item[role="menuitemradio"]::before {
+    forced-color-adjust: none;
+  }
+}
+
 /*
  * Tooltip — supplemental label overlaid near a trigger.
  *
@@ -5543,7 +5636,7 @@ html.has-modal-open.had-scrollbar {
  */
 .tooltip {
   --tooltip-bg: var(--surface-solid);
-  --tooltip-fg: var(--surface);
+  --tooltip-fg: var(--surface-solid-fg);
   --tooltip-arrow-size: 5px;
 
   position: fixed;
@@ -5680,11 +5773,15 @@ html.has-modal-open.had-scrollbar {
  *
  * Public hooks:
  * --accordion-radius
+ * --accordion-pad
  * --accordion-marker-color
+ * --accordion-marker-size
  */
 .accordion {
   --accordion-radius: var(--radius);
+  --accordion-pad: var(--space-40);
   --accordion-marker-color: var(--text-muted);
+  --accordion-marker-size: 1rem;
 
   border: var(--border-width) solid var(--border);
   border-radius: var(--accordion-radius);
@@ -5701,7 +5798,7 @@ html.has-modal-open.had-scrollbar {
   gap: var(--space-30);
   cursor: pointer;
   list-style: none;
-  padding: var(--space-40);
+  padding: var(--accordion-pad);
   color: var(--text);
   font-weight: var(--font-weight-medium);
 }
@@ -5717,12 +5814,17 @@ html.has-modal-open.had-scrollbar {
   display: none;
 }
 
+/* The marker is the chevron itself: the box is filled with
+   --accordion-marker-color and then clipped to the glyph by the mask. Anything
+   painted on this pseudo-element — a background, a ring, a shadow — is clipped
+   with it, so a decorated marker (a chevron in a pill) needs a real element;
+   see the accordion docs for the opt-out. */
 .accordion summary::after {
   content: "";
   flex: 0 0 auto;
   margin-inline-start: auto;
-  inline-size: 1rem;
-  block-size: 1rem;
+  inline-size: var(--accordion-marker-size);
+  block-size: var(--accordion-marker-size);
   background-color: var(--accordion-marker-color);
   -webkit-mask: var(--icon-chevron) center / contain no-repeat;
   mask: var(--icon-chevron) center / contain no-repeat;
@@ -5733,9 +5835,14 @@ html.has-modal-open.had-scrollbar {
   transform: rotate(180deg);
 }
 
+/* The panel, not the item, owns the inset here — .separated paints a card on
+   <details> but leaves it unpadded — so the panel is what a .bleed child
+   escapes (components/bleed.css). */
 .accordion details > summary + * {
-  padding-block: 0 var(--space-40);
-  padding-inline: var(--space-40);
+  --surface-pad: var(--accordion-pad);
+
+  padding-block: 0 var(--accordion-pad);
+  padding-inline: var(--accordion-pad);
   color: var(--text-muted);
   margin-block: 0;
 }
@@ -5744,6 +5851,9 @@ html.has-modal-open.had-scrollbar {
   padding-block-start: var(--space-10);
 }
 
+/* Also cancels the lift of a first .bleed child (bleed.css, lower
+   specificity): the panel's top edge is the summary, not the item edge, so a
+   bleed reaches only the sides and the bottom. */
 .accordion details > summary + * > :first-child {
   margin-block-start: 0;
 }
@@ -5768,6 +5878,12 @@ html.has-modal-open.had-scrollbar {
   padding-inline: 0;
 }
 
+/* Flush already sits at the embedding surface's edge, so there is no inline
+   inset left for a .bleed child to cancel. */
+.accordion.flush details > summary + * {
+  --surface-pad: 0px;
+}
+
 /* Separated — each item owns a full card. The item's own border beats the
    shared details + details separator on specificity alone, so nothing needs
    undoing for the second item onwards. */
@@ -5784,9 +5900,23 @@ html.has-modal-open.had-scrollbar {
   background: var(--surface-raised);
 }
 
+/* A last .bleed child inherits its bottom corners from the panel, but the
+   rounded box is the item (.separated) or the group (last item) — relay the
+   radius to the panel. Explicit rather than inherit: in browsers with
+   ::details-content the panel's flat-tree parent is that slot, not
+   <details>. */
+.accordion.separated > details > summary + *,
+.accordion:not(.flush) > details:last-child > summary + * {
+  border-end-start-radius: var(--accordion-radius);
+  border-end-end-radius: var(--accordion-radius);
+}
+
 @media (forced-colors: active) {
-  .accordion {
-    --accordion-marker-color: CanvasText;
+  /* Written on the property, not the hook: an application hook override at
+    the same specificity loads after this file and would win the variable,
+    leaving a Canvas-remapped fill. The property keeps CanvasText. */
+  .accordion summary::after {
+    background-color: CanvasText;
   }
 }
 
@@ -6152,8 +6282,8 @@ html.has-modal-open.had-scrollbar {
 }
 
 .status-bar {
-  --status-bg: var(--intent, var(--text));
-  --status-fg: var(--intent-fg, var(--surface));
+  --status-bg: var(--intent, var(--surface-solid));
+  --status-fg: var(--intent-fg, var(--surface-solid-fg));
 
   position: fixed;
   /* Fixed positioning tracks the layout viewport, which the mobile software
@@ -6423,7 +6553,7 @@ a.avatar[aria-disabled="true"] {
 }
 
 .avatar-stack > .avatar {
-  box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface);
+  box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface-opaque);
 }
 
 .avatar-stack > .avatar + .avatar {
@@ -6781,6 +6911,16 @@ a.avatar[aria-disabled="true"] {
   transform: none;
 }
 
+@media (forced-colors: active) {
+  /* Both toggle markers are currentColor mask fills: without this the system
+    remaps the backgrounds to Canvas and the glyphs disappear. Kept on the
+    pseudos so the host keeps its native color and focus adaptation. */
+  .fab > summary::before,
+  .fab > summary::after {
+    forced-color-adjust: none;
+  }
+}
+
 /*
  * Rating — integer star rating drawn on native radio inputs.
  *
@@ -6839,7 +6979,7 @@ a.avatar[aria-disabled="true"] {
 }
 
 .rating > input[type="radio"]:focus-visible {
-  outline: var(--focus-outline);
+  outline: var(--focus-ring-width) solid var(--focus);
   outline-offset: var(--focus-outline-offset);
   background: var(--rating-color);
 }
@@ -6945,7 +7085,7 @@ a.avatar[aria-disabled="true"] {
   --step-size: 1.75rem;
   --step-inline-gap: var(--space-20);
   --step-line-size: var(--border-width);
-  --step-marker-bg: var(--surface);
+  --step-marker-bg: var(--surface-opaque);
   --step-marker-border: var(--border);
   --step-marker-fg: var(--text-muted);
   --step-marker-radius: var(--radius-full);
@@ -7025,7 +7165,7 @@ a.avatar[aria-disabled="true"] {
    connector leaving current goes back to neutral. Declared after
    .step-complete at equal specificity: current wins on every channel. */
 .steps > [aria-current="step"] {
-  --step-marker-bg: var(--surface);
+  --step-marker-bg: var(--surface-opaque);
   --step-marker-border: var(--state-selected);
   --step-marker-fg: var(--state-selected);
   --step-line: var(--border);
@@ -7064,7 +7204,7 @@ a.avatar[aria-disabled="true"] {
    focus ring's own width and offset. Only this composition scrolls, and only a
    link has a ring to protect. */
 .steps-horizontal:has(a[href]) {
-  padding-block: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+  padding-block: calc(var(--focus-outline-offset) + var(--focus-ring-width));
 }
 
 /* One explicit row, the marker's: a `.step-label` is auto-placed into an
@@ -7305,6 +7445,15 @@ a.avatar[aria-disabled="true"] {
   color: var(--text);
 }
 
+/* Same contextual hover as .nav-link (navbar.css): a tint of the tile's ink
+   reads on any --ui-* bar; the baseline keeps a legible light chip. */
+@supports (color: color-mix(in oklch, red, white)) {
+  .app-nav > a:hover {
+    background: color-mix(in oklch, currentColor 10%, transparent);
+    color: var(--ui-fg, var(--text));
+  }
+}
+
 /* Current tile is already a full selected surface. Selection never changes
    text metrics: the shared medium weight is kept, no permanent indicator is
    added here. */
@@ -7392,11 +7541,16 @@ a.avatar[aria-disabled="true"] {
   display: inline-flex;
   align-items: center;
   min-block-size: var(--control-size-sm);
+  padding-block: 0;
   padding-inline: var(--space-20);
+  border: 0;
   border-radius: var(--radius);
+  background: transparent;
   color: var(--ui-fg, var(--text-muted));
+  font: inherit;
   font-weight: var(--font-weight-medium);
   text-decoration: none;
+  cursor: pointer;
 }
 
 /* nav-link serves two contracts: plain page navigation (aria-current="page")
@@ -7421,6 +7575,28 @@ a.avatar[aria-disabled="true"] {
   color: var(--state-selected);
 }
 
+/* On a bar with its own --ui-bg/--ui-fg the fill is a tint of the link's own
+   ink, the .btn.ghost hover recipe, so it reads on light and dark bars alike
+   instead of snapping back to --surface-subtle. Not --ui-hover-bg: that is the
+   bar's own hover and can equal its fill. The ink follows --ui-fg too — the
+   selected accent has no contrast pair with an arbitrary bar. The baseline
+   above keeps the light chip where color-mix is missing, with ink that is
+   legible on it. */
+@supports (color: color-mix(in oklch, red, white)) {
+  .nav-link:is(:hover, [aria-current]) {
+    background: color-mix(in oklch, currentColor 10%, transparent);
+  }
+
+  .nav-link:hover {
+    color: var(--ui-fg, var(--text));
+  }
+
+  .nav-link[aria-current],
+  .nav-link[aria-current]:hover {
+    color: var(--ui-fg, var(--state-selected));
+  }
+}
+
 /* Nav list — a vertical navigation list. Used by .drawer for stacked links.
    Links fill each row so the whole line is an interactive target; the
    horizontal .navbar-nav links keep their intrinsic size. */
@@ -7512,8 +7688,9 @@ a.avatar[aria-disabled="true"] {
  *
  * Docs: docs/pages/components/pagination.md
  *
- * Render .btn elements inside a .pagination list. The active page is marked
- * with aria-current="page"; .btn owns the active state styling.
+ * Render .btn.ghost elements inside a .pagination list. The active page is
+ * marked with aria-current="page"; .btn owns the active state styling, so the
+ * current page is the only filled item.
  *
  * Truncated ranges are plain text (`.muted`, `aria-hidden="true"`), not .btn
  * — they are decorative, not actionable. They still get the same box sizing
@@ -7631,10 +7808,10 @@ a.avatar[aria-disabled="true"] {
 }
 
 /* The ring is square on the edge the tab is attached to, so it reads as part
-   of the strip rather than a floating chip. */
+   of the strip rather than a floating chip. Color and width follow the
+   component ring contract (focus.css); only the geometry is tab-specific. */
 .tab:focus-visible {
-  outline: var(--focus-outline);
-  outline-color: var(--focus);
+  outline: var(--focus-ring-width) solid var(--focus);
   outline-offset: -2px;
   border-radius: var(--radius-sm) var(--radius-sm) 0 0;
 }
@@ -7716,6 +7893,9 @@ a.avatar[aria-disabled="true"] {
  * A plain <dl> handles richer relationships (several terms or descriptions)
  * and stays untouched by this component.
  *
+ * Variants:
+ * .stacked — value under its term rather than beside it.
+ *
  * Why margin resets: neutralizes .prose list margins if .data-list appears
  * inside an authored rich-text scope; the grid owns row/column rhythm.
  */
@@ -7737,6 +7917,21 @@ a.avatar[aria-disabled="true"] {
   margin: 0;
 }
 
+/* Stacked — the value sits under its term instead of beside it, for narrow
+   columns and for values too long to sit in a second column.
+   Why the pair separation rides on the term's margin: the children alternate
+   dt/dd with no element around a pair, so the grid has no row boundary to give
+   a larger gap to. The tight gap is the row gap; the term reopens the space. */
+.data-list.stacked {
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--space-10);
+}
+
+.data-list.stacked > dt + dt,
+.data-list.stacked > dd + dt {
+  margin-block-start: var(--space-30);
+}
+
 /*
  * Application list — repeated rows with optional leading and trailing regions.
  * Content determines the number of lines; the component only owns the row
@@ -7869,6 +8064,12 @@ a.list-item[aria-current]::before {
  * .table-wrap provides the scroll container and outer chrome; .table owns row
  * and cell rules. Tokens are sourced from the shared scale.
  *
+ * Responsive strategy is horizontal overflow: the wrap scrolls, the table
+ * keeps its columns. Restructuring rows into cards would destroy the
+ * column scanability tables exist for, and needs data-label duplication
+ * because CSS cannot join a cell to its header — that representation choice
+ * belongs to the application, not the framework.
+ *
  * Public hooks:
  * --table-min
  * --table-cell-pad
@@ -7989,7 +8190,7 @@ a.list-item[aria-current]::before {
 }
 
 .meter:not(meter) > * + * {
-  border-inline-start: var(--border-width) solid var(--surface);
+  border-inline-start: var(--border-width) solid var(--surface-opaque);
 }
 
 .meter::-webkit-meter-bar {
@@ -8090,6 +8291,11 @@ a.list-item[aria-current]::before {
   min-block-size: var(--control-size);
   padding-inline: var(--space-30);
   border: var(--border-width) solid var(--control-border);
+  /* An addon is a field segment: it honours the same lower-edge extension
+     points as text controls (control.css), so a theme's underline or accent
+     edge reaches it instead of stopping at the field. */
+  border-block-end-color: var(--control-border-block-end-color, var(--control-border));
+  border-block-end-width: var(--control-border-block-end-width, var(--border-width));
   border-radius: var(--radius);
   background: var(--control-bg);
   color: var(--control-fg);
@@ -8137,38 +8343,49 @@ a.list-item[aria-current]::before {
   z-index: 1;
 }
 
-/* Keep an active focus ring above an adjacent hovered control. This matters
-   on platforms where clicking a button does not move focus from the input. */
-.join > :is(:focus, :focus-within) {
-  z-index: 4;
-}
-
 /* An input's border must read as the "primary" edge against an attached
    action (e.g. a password-reveal button) at all times, not only while
    hovered or focused — otherwise the shared edge flips ownership as the
-   user's pointer moves, which reads as a rendering glitch. */
-.join > :is(.input, .textarea, .select) {
+   user's pointer moves, which reads as a rendering glitch. The :has()
+   variant covers a control nested one wrapper level deep (e.g. a combobox
+   element): the wrapper is the flex item, so it carries the z-index — a
+   z-index on the inner control would be a no-op on a static grandchild. */
+.join > :is(.input, .textarea, .select),
+.join > :has(> :is(.input, .textarea, .select)) {
   z-index: 3;
 }
 
-/* An input/select with an attached action reads as one composite field. Move
-   its outer focus treatment to the join; button-only groups keep per-button
-   focus, and unsupported :has() browsers retain the control's normal ring. */
-.join:has(> :is(.input, .textarea, .select):focus-visible) {
-  border-radius: var(--join-radius);
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+/* Keep an active focus line above every neighbour, including an adjacent
+   field and a hovered control (some platforms keep focus on the input while
+   a button is clicked). It must follow the primary-edge rule above: both are
+   (0,2,0), and when it came first a focused field stayed at 3 and the next
+   field, painted later, covered the 1px shared edge of its line. */
+.join > :is(:focus, :focus-within) {
+  z-index: 4;
 }
 
-.join:has(> :is(.input, .textarea, .select)) > :is(.input, .textarea, .select):focus-visible {
-  outline: none;
-  box-shadow: none;
+/* One wrapper level (e.g. a combobox element around the native control) is
+   supported generically — no widget is named here. The wrapper is the flex
+   item that receives the corner longhands above; the inner control inherits
+   them. The wrapper is also what align-items stretches: block-size: 100%
+   resolves against that stretched size, so the field fills it. :hover and
+   :focus-within already propagate to the wrapper, so the z-index rules above
+   need no duplication. */
+.join > * > :is(.input, .textarea, .select) {
+  block-size: 100%;
+  border-radius: inherit;
 }
 
+/* Text controls paint their own inset focus outline (control.css), so a
+   .join never moves the ring to the group: button-only groups and wrapped
+   inputs alike keep per-control focus, with no :has() group treatment. */
+
 /* A default outline action belongs to the composite field border. An explicit
    intent still provides its own outline color — --intent is guaranteed-invalid
-   for a neutral button (the :where(.btn) boundary), so the fallback applies. */
-.join:has(> :is(.input, .textarea, .select)) > .btn.outline {
+   for a neutral button (the :where(.btn) boundary), so the fallback applies.
+   The second :has() covers a control nested one wrapper level deep. */
+.join:has(> :is(.input, .textarea, .select)) > .btn.outline,
+.join:has(> * > :is(.input, .textarea, .select)) > .btn.outline {
   --btn-border-color: var(--intent, var(--border));
 }
 
@@ -8210,36 +8427,55 @@ a.list-item[aria-current]::before {
 
 .aura {
   --aura-color: var(--intent, var(--primary));
-  --aura-width: 2px;
+  --aura-width: 1px;
   --aura-blur: 0.25rem;
-  --aura-intensity: 1;
+  --aura-intensity: 0.4;
   --aura-radius: var(--radius-lg);
   --aura-duration: 6s;
 
   position: relative;
   isolation: isolate;
   display: inline-grid;
-  padding: var(--aura-width);
   border-radius: calc(var(--aura-radius) + var(--aura-width));
-  border: var(--border-width) solid transparent;
+
+  /* The frame is the border itself, so --aura-width is the painted thickness.
+     A transparent border stays for forced colors, where it becomes the visible
+     boundary; a padding frame inside it would paint both, doubling the line. */
+  border: var(--aura-width) solid transparent;
   background: var(--aura-color);
 
   /* A short feathered accent rather than a long wedge with a hard edge, which
      reads as one lit side. Nothing tints the frame outside it: a constant tint
-     across 2px draws an outline, the opposite of the effect. */
+     across the frame draws an outline, the opposite of the effect. `border-box`
+     sizes the gradient to the border box: the default padding-box origin would
+     tile a neighbouring copy of the gradient into the border, which is now the
+     whole frame. */
   background: conic-gradient(
-    from var(--aura-angle),
-    transparent 0 78%,
-    var(--aura-color) 93%,
-    transparent
-  );
-}
-
-/* Near halo — inherits the frame gradient, so it tracks the lit accent. */
+      from var(--aura-angle),
+      transparent 0 78%,
+      var(--aura-color) 93%,
+      transparent
+    )
+    border-box;
+
+  /* Far halo — flat and static. At this blur the rotating detail is no longer
+     legible, so there is nothing to gain from animating a second wide blurred
+     layer. This is the layer that stays lit at all times, so it — not the
+     frame — is what keeps the object present between two passes of the
+     accent. An outer shadow never paints under the box, so it stays out of a
+     translucent child. min() because a color-mix() share above 100% is
+     invalid, where the opacity it replaces clamped. */
+  box-shadow: 0 0 calc(var(--aura-blur) * 8) var(--aura-blur)
+    color-mix(in oklab, var(--aura-color) min(100%, calc(15% * var(--aura-intensity))), transparent);
+}
+
+/* Near halo — inherits the frame gradient, so it tracks the lit accent. An
+   absolute inset starts at the padding edge, inside the border that is the
+   frame, so the negative inset puts the halo back on the frame. */
 .aura::before {
   position: absolute;
   z-index: -1;
-  inset: 0;
+  inset: calc(-1 * var(--aura-width));
   border-radius: inherit;
   background: inherit;
   filter: blur(var(--aura-blur));
@@ -8248,29 +8484,22 @@ a.list-item[aria-current]::before {
   content: "";
 }
 
-/* Far halo — flat and static. At this blur the rotating detail is no longer
-   legible, so there is nothing to gain from animating a second wide blurred
-   layer. It outgrows the frame, otherwise the child covers it and the whole
-   effect reads as a drop shadow. This is the layer that stays lit at all
-   times, so it — not the frame — is what keeps the object present between two
-   passes of the accent. */
+/* Occlusion — the frame and the near halo paint across the whole box, and only
+   their edge is meant to show. This mask sits above both, under the child, so
+   a transparent or translucent child (an .outline alert, a glass surface) is
+   framed rather than filled with the frame color. It follows the child's
+   shape through --aura-radius. */
 .aura::after {
   position: absolute;
   z-index: -1;
-  inset: calc(-1 * var(--aura-blur));
-  border-radius: calc(var(--aura-radius) + var(--aura-width) + var(--aura-blur));
-  background: var(--aura-color);
-  filter: blur(calc(var(--aura-blur) * 4));
-  opacity: calc(0.15 * var(--aura-intensity));
+  inset: 0;
+  border-radius: var(--aura-radius);
+  background: var(--surface-opaque);
   pointer-events: none;
   content: "";
 }
 
-/* Lifts the child above both halos. It also has to be opaque: the frame paints
-   across the whole box and only its edge is meant to show, so a transparent
-   child (an .outline alert, a .ghost button) is filled with the frame color
-   rather than framed by it. Documented as a constraint, not worked around —
-   masking a ring would cost more than the case is worth. */
+/* Lifts the child above the halo and the mask. */
 .aura > * {
   position: relative;
 }
@@ -8293,7 +8522,7 @@ a.list-item[aria-current]::before {
     animation: aura-breathe-near var(--aura-duration) ease-in-out infinite;
   }
 
-  .aura-glow::after {
+  .aura-glow {
     animation: aura-breathe-far var(--aura-duration) ease-in-out infinite;
   }
 }
@@ -8305,8 +8534,8 @@ a.list-item[aria-current]::before {
 @media (prefers-reduced-motion: reduce) {
   .aura:not(.aura-glow) {
     background:
-      radial-gradient(4rem 4rem at 0% 0%, var(--aura-color), transparent 70%),
-      radial-gradient(4rem 4rem at 100% 100%, var(--aura-color), transparent 70%);
+      radial-gradient(4rem 4rem at 0% 0%, var(--aura-color), transparent 70%) border-box,
+      radial-gradient(4rem 4rem at 100% 100%, var(--aura-color), transparent 70%) border-box;
   }
 }
 
@@ -8327,10 +8556,16 @@ a.list-item[aria-current]::before {
   }
 }
 
+/* The far halo is the element's own shadow: opening its spread and share
+   breathes it without scaling the child. */
 @keyframes aura-breathe-far {
   50% {
-    opacity: calc(0.28 * var(--aura-intensity));
-    transform: scale(1.07);
+    box-shadow: 0 0 calc(var(--aura-blur) * 10) calc(var(--aura-blur) * 2)
+      color-mix(
+        in oklab,
+        var(--aura-color) min(100%, calc(28% * var(--aura-intensity))),
+        transparent
+      );
   }
 }
 
@@ -8350,6 +8585,64 @@ a.list-item[aria-current]::before {
   --aura-radius: var(--radius-full);
 }
 
+/*
+ * Highlight sweeping across a text label — an activity in progress.
+ *
+ * Docs: docs/pages/components/shimmer.md
+ *
+ * Presentation only: it carries no state and selects no ARIA attribute, so the
+ * label stays whatever the author makes it (a role="status" message, a list
+ * item, a heading).
+ *
+ * Public hooks:
+ * --shimmer-color
+ * --shimmer-highlight
+ */
+.shimmer {
+  --shimmer-color: var(--text-muted);
+  --shimmer-highlight: var(--text);
+
+  color: var(--shimmer-color);
+}
+
+/* The sweep paints the glyphs through a clipped background, which needs the
+   glyph fill transparent. Without background-clip: text that would erase the
+   label, so the transparency lives under the same query as the clip. It is
+   the fill, not `color`: a label class that sets its own color (.muted, a
+   caption style) would otherwise win the cascade and paint opaque glyphs over
+   the sweep. Reduced motion keeps the plain label — a frozen band would read
+   as a random tint. */
+@supports (background-clip: text) {
+  @media (prefers-reduced-motion: no-preference) {
+    .shimmer {
+      -webkit-text-fill-color: transparent;
+      background:
+        linear-gradient(
+          90deg,
+          var(--shimmer-color) 40%,
+          var(--shimmer-highlight) 50%,
+          var(--shimmer-color) 60%
+        )
+        0 0 / 300% 100%;
+      background-clip: text;
+      animation: actual-shimmer var(--duration-shimmer) linear infinite;
+    }
+  }
+}
+
+/* The band occupies the middle third of a background three times the label's
+   width, so each pass leaves the end of the label before the next one enters
+   at the start. */
+@keyframes actual-shimmer {
+  from {
+    background-position: 100% 0;
+  }
+
+  to {
+    background-position: 0% 0;
+  }
+}
+
 /* Utilities — small, single-purpose escape hatches. */
 /*
  * Small, single-purpose utilities for common escape hatches.
@@ -8537,9 +8830,9 @@ a.list-item[aria-current]::before {
 }
 
 /*
- * Optional utility helpers.
- *
- * These classes are intentionally not part of the core API.
+ * Extra utility helpers — explicit property/value names beside the curated
+ * shortcuts of base.css. Both are imported by utilities/index.css and are
+ * equally public (docs/design-notes/naming.md § Utilities).
  * They are escape hatches for layout nudges, not a full atomic scale.
  *
  * Core principle:
@@ -8715,8 +9008,9 @@ a.list-item[aria-current]::before {
   overflow-y: auto;
 }
 
-/* Text */
-.white-space-normal {
+/* Text. .text-wrap is the counterpart of base's .text-nowrap: it restores
+   wrapping inside a component that sets nowrap (.badge). */
+.text-wrap {
   white-space: normal;
 }
 
@@ -8789,7 +9083,7 @@ a.list-item[aria-current]::before {
 /* Surface. These are semantic surfaces, not arbitrary paint: each owns its
    matching ink and rebinds --heading to that ink, so it stays readable when it
    recreates a light surface inside a context that installed a dark one
-   (.inverted). Intent ink is not inherited through a surface utility; use
+   (e.g. a --surface-solid band). Intent ink is not inherited through a surface utility; use
    .intent-color for that. */
 .background-surface {
   --heading: currentColor;