actual-css 0.2.0 → 0.3.0

package/dist/actual.css

@@ -24,16 +24,6 @@ select {
   display: none !important;
 }
 
-/* Legacy dialog fallback only. Modern dialogs keep the browser's native closed
-   state so display/overlay transitions are not flattened by the reset.
-   The presentation for the dialog-fallback.js shim lives in the separate
-   dialog-fallback.css, so it can be dropped from custom bundles. */
-@supports not (selector(dialog:modal)) {
-  dialog:not([open]) {
-    display: none;
-  }
-}
-
 :where(img, svg, video) {
   max-inline-size: 100%;
   block-size: auto;
@@ -55,64 +45,24 @@ select {
   }
 }
 
-/*
- * Legacy dialog fallback — presentation for the dialog-fallback.js shim
- * (browsers without native <dialog>: Safari <= 15.3, Firefox <= 97).
- *
- * Isolated in its own file so a custom bundle can opt out by dropping this
- * import; the JS side is disabled with data-dialog-fallback="false" on the
- * root element or on a dialog. Must load before component styles so ties
- * such as dialog.modal's padding resolve in the component's favor.
- *
- * The whole file is inert on modern browsers: rules key on the
- * .dialog-fallback marker written by the shim, so browsers that support
- * <dialog> but not :modal are never affected either.
- */
-@supports not (selector(dialog:modal)) {
-  /* Browsers without native <dialog> ship no UA dialog styles at all;
-     approximate them. :where() keeps specificity at dialog[open] level so
-     component styles such as dialog.modal still override the emulation. */
-  dialog[open]:where(.dialog-fallback) {
-    position: absolute;
-    inset-inline: 0;
-    width: -moz-fit-content;
-    width: fit-content;
-    max-inline-size: calc(100% - 2rem);
-    margin: auto;
-    padding: var(--space-4, 1em);
-    border: var(--border-width, 1px) solid var(--border, currentColor);
-    background: var(--surface-raised, #fff);
-    color: var(--text, inherit);
-  }
-
-  /* Open modally: fixed near the top (no fit-content in the block axis on
-     these browsers, so no vertical centering) and above menus, below
-     tooltips. Legacy-only layer, hence no z-index token. The spread shadow is
-     the visible backdrop: the dialog is its own stacking context, where a
-     negative z-index child paints above the element's background, so the
-     dimming cannot live on the ::before. */
-  dialog[open].is-fallback-modal {
-    position: fixed;
-    inset-block: 8vh auto;
-    max-block-size: 84vh;
-    overflow: auto;
-    z-index: 40;
-    box-shadow: 0 0 0 100vmax var(--backdrop-fill, rgb(0 0 0 / 35%));
-  }
-
-  /* Transparent stand-in for ::backdrop, hit-testing only. Clicks on it hit
-     the dialog element outside its own box, which dialog.js already treats as
-     a backdrop click, and it blocks pointer interaction with the page behind
-     the modal. */
-  dialog[open].is-fallback-modal::before {
-    content: "";
-    position: fixed;
-    inset: 0;
-    z-index: -1;
-  }
-}
-
 :root {
+  /*
+   * Global framework tokens.
+   *
+   * Public: properties in the named groups below are public API (typography,
+   * spacing, shape, motion, focus, controls, viewport, z-index, icons) unless
+   * a group is explicitly marked Internal or Derived.
+   *
+   * Derived: "Theme-derived aliases" and "State tokens" reference intent and
+   * surface tokens and follow the theme; do not hard-code values into them.
+   * Internal: indicator offsets, --bar-height, --disabled-opacity and the
+   * like are consumed by components, not authored.
+   *
+   * Component-local hooks and internal state relays live with their
+   * components. See docs/pages/foundations/tokens.md for the public/internal
+   * token contract.
+   */
+
   /* Typography */
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
@@ -130,20 +80,22 @@ select {
   --font-size-md: 1rem;
   --font-size-lg: 1.125rem;
 
-  /* Spacing */
+  /* Spacing — official steps are named in tens so the scale stays open for
+     application themes to intercalate intermediate values (--space-15,
+     --space-45…) without colliding with future framework steps. */
   --gap: 0.75rem;
-  --variant-space: var(--space-4);
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-3: 0.75rem;
-  --space-4: 1rem;
-  --space-5: 1.5rem;
-  --space-6: 2rem;
+  --density-space: var(--space-40);
+  --density-compact-size: 1.5rem;
+  --space-10: 0.25rem;
+  --space-20: 0.5rem;
+  --space-30: 0.75rem;
+  --space-40: 1rem;
+  --space-50: 1.5rem;
+  --space-60: 2rem;
 
   /* Shape */
   --border-width: 1px;
   --radius-full: 9999px;
-  --shadow-xs: 0 1px 2px rgb(0 0 0 / 0.04);
   --shadow: 0 1px 3px rgb(0 0 0 / 0.05), 0 4px 12px rgb(0 0 0 / 0.04);
   --shadow-popout: 0 0.25rem 0.75rem rgb(0 0 0 / 0.15);
 
@@ -167,7 +119,6 @@ select {
      the circle-aware inset (1 - 1/√2) / 2 ≈ 14.65%; the ring surrounds the
      dot with the parent surface color. */
   --indicator-offset: 14.65%;
-  --indicator-ring: var(--surface);
 
   /* Shared backdrop — consumed by modal, drawer, and mobile flyout sheets. */
   --backdrop-color: rgb(0 0 0);
@@ -178,7 +129,8 @@ select {
   --bar-height: 0.65rem;
 
   /* Controls — inputs and buttons share --control-size so heights always match.
-     .sm/.lg (variants.css) switch --control-size and --control-font-size. */
+     .sm/.lg (variants.css) switch --control-size; --control-font-size stays
+     at its baseline because density does not change typography. */
   --control-size-sm: 2rem;
   --control-size-md: 2.375rem;
   --control-size-lg: 2.75rem;
@@ -186,19 +138,38 @@ select {
   --control-pad-x: 1em;
   --control-font-size: var(--font-size-md);
   --disabled-opacity: 0.65;
+}
 
+/* Theme-derived aliases. These reference intent/surface tokens, so they must
+   be re-declared on every theme boundary: a custom property resolves its
+   var() references at computed-value time on the element that declares it,
+   so an alias declared only on :root is inherited as an already-resolved
+   value and would not follow a [data-theme] island's overridden tokens.
+   Themes that want a distinct alias override it explicitly afterwards. */
+:root,
+[data-theme] {
+  /* State tokens — semantic colors for selected/pressed/current and disabled.
+     Components consume these instead of hard-wiring --primary/--text-subtle
+     so forced-colors can override them in one place. */
+  --state-selected: var(--primary);
+  --state-selected-fg: var(--primary-fg);
+  --state-disabled: var(--text-subtle);
+
+  /* Status dot ring — follows the island's surface. */
+  --indicator-ring: var(--surface);
+}
+
+:root {
   /* Variant tuning — themes may adjust generated soft surfaces without
      replacing the component rules. */
   --soft-bg-mix: 88%;
   --soft-border-mix: 65%;
   --soft-hover-alpha: 12%;
 
-  /* Shared icons */
-  --icon-chevron-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
-  --icon-check-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='20 6 9 17 4 12'/%3E%3C/svg%3E");
-  /* Native select uses background-image, which cannot inherit currentColor.
-     The stroke matches the default theme's text-subtle (hue 258 neutral). */
-  --icon-chevron-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%238a8594' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
+  /* Shared icon assets. Override these URLs when a strict CSP disallows data:. */
+  --icon-chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%238a8594' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
+  --icon-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='20 6 9 17 4 12'/%3E%3C/svg%3E");
+  --icon-close: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cline x1='6' y1='6' x2='18' y2='18'/%3E%3Cline x1='18' y1='6' x2='6' y2='18'/%3E%3C/svg%3E");
 
   /* Viewport size tokens — fallback vh/vw with dvh/vi enhancement.
      Consumed by full-viewport components (app-shell, drawer, modal, flyout).
@@ -207,13 +178,24 @@ select {
   --viewport-block: 100vh;
   --viewport-inline: 100vw;
 
-  /* Layering */
+  /* Z-index scale — used ONLY by non-dialog overlays (see the layering
+     note below for the full model). Actual CSS reserves multiples of 10 for
+     framework layers; applications may use intermediate values for local
+     layering. */
   --z-sticky: 10;
   --z-menu: 20;
   --z-tooltip: 50;
   --z-status: 60;
 }
 
+@media (forced-colors: active) {
+  :root {
+    --state-selected: Highlight;
+    --state-selected-fg: HighlightText;
+    --state-disabled: GrayText;
+  }
+}
+
 @supports (block-size: 100dvh) {
   :root {
     --viewport-block: 100dvh;
@@ -227,12 +209,17 @@ select {
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  :root {
-    --shadow-xs: 0 1px 2px color-mix(in oklch, var(--shadow-color) 4%, transparent);
+  :root,
+  [data-theme] {
+    /* Shadows derive from --shadow-color (theme.css) — re-declared on every
+       theme boundary so islands follow their own shadow-color. */
     --shadow:
       0 1px 3px color-mix(in oklch, var(--shadow-color) 5%, transparent),
       0 4px 12px color-mix(in oklch, var(--shadow-color) 4%, transparent);
     --shadow-popout: 0 0.25rem 0.75rem color-mix(in oklch, var(--shadow-color) 15%, transparent);
+  }
+
+  :root {
     --backdrop-fill: color-mix(
       in oklch,
       var(--backdrop-color) calc(var(--backdrop-opacity) * 100%),
@@ -241,6 +228,17 @@ select {
   }
 }
 
+/*
+ * Theme tokens — the palette, surfaces, text, borders, radius and shadow
+ * color. Named themes (themes/*.css) override this file; authors can set the
+ * same tokens on :root or on [data-theme="…"] islands.
+ *
+ * Public: Intent colors, Surfaces, Text, Lines and focus, Radius scale,
+ * 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.
+ * Internal: --hgroup-gap.
+ */
 :root {
   color-scheme: light dark;
 }
@@ -308,7 +306,6 @@ select {
   /* 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);
-  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
   --hover-overlay: hsl(260 20% 10% / 0.04);
 
   /* Radius scale — themes may override the whole scale (e.g. [data-theme="square"]) */
@@ -319,13 +316,19 @@ select {
   /* Shadow color — consumed by --shadow / --shadow-popout in tokens.css */
   --shadow-color: hsl(260 25% 10%);
 
-  /* Heading and selection — derived from theme color tokens */
+  /* hgroup internal gap */
+  --hgroup-gap: 0.25em;
+}
+
+/* Theme-derived aliases — re-declared on every theme boundary (see tokens.css
+   for the custom-property resolution rationale): islands recompute these from
+   their own tokens instead of inheriting :root's resolved values. */
+:root,
+[data-theme] {
   --heading: var(--text);
   --selection-bg: var(--primary);
   --selection-fg: var(--primary-fg);
-
-  /* hgroup internal gap */
-  --hgroup-gap: 0.25em;
+  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
 }
 
 /* Tone subsystem — fixed-backdrop foreground for components placed over media
@@ -447,10 +450,8 @@ a {
   text-underline-offset: 0.18em;
 }
 
-@media (hover: hover) {
-  a:hover {
-    text-decoration-thickness: 0.12em;
-  }
+a:hover {
+  text-decoration-thickness: 0.12em;
 }
 
 /* Global heading chrome: color (--heading or inherit), a tight line-height,
@@ -476,7 +477,7 @@ hgroup > * {
 hr {
   border: 0;
   border-block-start: var(--border-width) solid var(--border);
-  margin-block: var(--space-6);
+  margin-block: var(--space-60);
 }
 
 code,
@@ -499,8 +500,8 @@ small {
  * Intent classes do not style elements directly.
  * They only expose --intent and --intent-fg.
  * Components and variants decide how to consume them. Each component that
- * consumes --intent or --ui-* must open a local intent boundary in a :where()
- * block that resets --intent / --intent-fg / --ui-* to initial. Parent intents
+ * consumes --intent or --ui-* opens a local intent boundary in a :where()
+ * block that resets exactly the tokens it consumes to initial. Parent intents
  * do not leak into nested components. Local intent classes (.primary, .danger,
  * etc.) still apply because they have higher specificity than :where().
  */
@@ -529,6 +530,28 @@ small {
   --intent-fg: var(--neutral-fg);
 }
 
+/*
+ * Core layout primitives: stack, cluster, center, frame, app-shell, media,
+ * sidebar-layout. Each primitive owns a single, readable behavior; they are
+ * meant to compose in markup.
+ *
+ * Public hooks:
+ * --cluster-align
+ * --cluster-justify
+ * --cluster-wrap
+ * --center-size
+ * --center-pad
+ * --frame-ratio
+ * --sidebar-layout-size
+ *
+ * Child contracts:
+ * .stack owns vertical rhythm: direct-child margins are reset, spacing comes
+ *   from --gap.
+ * .cluster owns inline rhythm: direct-child margins are reset, spacing comes
+ *   from --gap.
+ * .frame sizes direct media children (img/video/iframe/canvas/svg) to fill the
+ *   frame.
+ */
 .container-query {
   container-type: inline-size;
 }
@@ -545,12 +568,16 @@ small {
 
 .cluster {
   display: flex;
-  flex-wrap: wrap;
+  flex-wrap: var(--cluster-wrap, wrap);
   align-items: var(--cluster-align, center);
   justify-content: var(--cluster-justify, flex-start);
   gap: var(--gap);
 }
 
+.cluster > * {
+  margin: 0;
+}
+
 .center {
   box-sizing: content-box;
   max-inline-size: var(--center-size, 72rem);
@@ -594,6 +621,8 @@ small {
   grid-template-columns: minmax(0, 1fr);
 }
 
+/* Container queries are the preferred path; without them the @supports not
+   block below restores the same columns at the same viewport breakpoint. */
 @container (width >= 64rem) {
   .container-query .sidebar-layout {
     grid-template-columns: minmax(0, 1fr) var(--sidebar-layout-size, 18rem);
@@ -610,29 +639,27 @@ small {
   }
 }
 
+/*
+ * Responsive equal-width grids, with fixed-column presets below.
+ *
+ * Public hooks:
+ * --grid-min
+ * --grid-columns
+ */
 .grid {
   display: grid;
   gap: var(--gap);
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr));
-}
-
-/* Query-container wrapper that opts .grid-2/3/4/6 into responsive
- * collapse. Wrap a .grid-2/3/4/6 inside .container-query to make the
- * column count collapse on narrow wrappers. Without this wrapper,
- * .grid-2/3/4/6 stay at their full column count. */
-/* Fixed-column grids at their full count by default.
- *   .grid-2: 2 cols
- *   .grid-3: 3 cols
- *   .grid-4: 4 cols
- *   .grid-6: 6 cols
- * When placed inside .container-query, the column count collapses
- * on narrow wrappers. The intermediate 2-col step applies to
- * .grid-3/.grid-4; .grid-6 starts at 2 columns because it is meant
- * for compact items that do not need a full single-column stack.
- *   .grid-2: 1 col -> 2 cols
- *   .grid-3: 1 col -> 2 cols -> 3 cols
- *   .grid-4: 1 col -> 2 cols -> 4 cols
- *   .grid-6: 2 cols -> 3 cols -> 6 cols */
+  grid-template-columns: var(
+      --grid-columns,
+      repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr))
+    );
+}
+
+/* Fixed-column grids at their full count by default: .grid-2/3/4/6 stay at
+   2/3/4/6 columns unless wrapped in .container-query, which collapses the
+   column count on narrow wrappers (a 2-col intermediate step for
+   .grid-3/.grid-4; .grid-6 starts at 2 columns because it is meant for
+   compact items that do not need a full single-column stack). */
 .grid-2,
 .grid-3,
 .grid-4,
@@ -654,6 +681,9 @@ small {
   grid-template-columns: repeat(6, minmax(0, 1fr));
 }
 
+/* Container queries are the preferred responsive path; browsers without them
+   ignore these rules and get the equivalent @media rules from the
+   @supports not (container-type) block below — same columns, same breakpoints. */
 @container (width < 28rem) {
   .container-query .grid-2,
   .container-query .grid-3,
@@ -710,15 +740,20 @@ small {
  * Cross-cutting variant token mapping.
  *
  * Variant scope: .solid/.soft/.outline set --ui-* for components that opt into
- * shared variants. Component-specific defaults (.btn solid-by-default, .badge
- * solid-by-default, .alert soft-by-default) live with their components:
+ * shared variants. .inverted is a surface modifier, not a variant: it also
+ * paints the element directly (background/color/border-color) so it works on
+ * any block, competing with component surface treatments (.card.subtle).
+ * 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
- *   components/badge.css   — .badge default solid
- *   components/alert.css   — .alert default + .alert.solid/.alert.outline
+ *   components/badge.css   — .badge default soft
+ *   components/alert.css   — .alert default soft (consumes --ui-* directly)
  *
- * .sm/.lg set shared size tokens. Controls consume --control-*; non-control
- * components may consume --variant-* when the variant should affect their
- * local density. Compact components may consume --variant-compact-*.
+ * .sm/.lg set shared density tokens: spacing rhythm and geometry only.
+ * Density never changes typography — controls keep their font-size and
+ * content components keep theirs. Controls consume --control-size; non-control
+ * components may consume --density-* when the density context should affect
+ * their local rhythm. Compact components may consume --density-compact-size.
  * Components with bespoke sizing (spinner, avatar) define local .sm/.lg;
  * applying .sm/.lg to card, dialog, accordion, navbar, table is
  * a no-op.
@@ -744,27 +779,34 @@ small {
   --ui-border: var(--intent, var(--border));
 }
 
+/* Inverse surface treatment. Components (e.g. .card) compose through --ui-*;
+   the direct background/color/border-color also make .inverted useful on a
+   generic element. --heading is set so global headings (var(--heading, inherit))
+   do not inherit an outside heading color onto the dark surface. */
+.inverted {
+  --ui-bg: var(--surface-solid);
+  --ui-fg: var(--surface);
+  --ui-border: transparent;
+
+  --heading: var(--surface);
+  --busy-overlay-bg: var(--surface-solid);
+
+  background: var(--ui-bg);
+  color: var(--ui-fg);
+  border-color: var(--ui-border);
+}
+
 .sm {
-  --gap: var(--space-2);
-  --variant-space: var(--space-2);
+  --gap: var(--space-20);
+  --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
-  --control-font-size: var(--font-size-sm);
-  --variant-font-size: var(--font-size-sm);
-  --variant-icon-size: 1rem;
-  --variant-pad-block: var(--space-3);
-  --variant-compact-size: 1.25rem;
-  --variant-compact-font-size: 0.75rem;
+  --density-compact-size: 1.25rem;
 }
 .lg {
-  --gap: var(--space-5);
-  --variant-space: var(--space-5);
+  --gap: var(--space-50);
+  --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
-  --control-font-size: var(--font-size-lg);
-  --variant-font-size: var(--font-size-lg);
-  --variant-icon-size: 1.5rem;
-  --variant-pad-block: var(--space-5);
-  --variant-compact-size: 1.875rem;
-  --variant-compact-font-size: var(--font-size-sm);
+  --density-compact-size: 1.875rem;
 }
 
 /* Modern color enhancement. Baseline variant values above remain usable
@@ -782,54 +824,25 @@ small {
   }
 }
 
-/* Interactive hover recipe shared by .btn and .badge. Declared outside :hover
-   on purpose: --ui-hover-bg is only consumed inside their @media (hover: hover)
-   rules, so these values are inert until hovered. :is() carries real
-   specificity so the components' :where() intent boundaries
-   (--ui-hover-bg: initial) cannot override the recipe. The solid/soft overlay
-   darkening lives in the consuming components. */
-:is(.btn, a.badge, button.badge):is(.outline, .ghost) {
-  --ui-hover-bg: var(--surface-subtle);
-}
-
-@supports (color: color-mix(in oklch, red, white)) {
-  /* Solid has no literal class requirement: bare .btn/.badge default to solid,
-     so this must match anything that isn't one of the other variants rather
-     than an explicit .solid class. Stacks with the box-shadow overlay the
-     consuming components apply on top for extra depth. */
-  :is(.btn, a.badge, button.badge):not(:where(.soft, .outline, .ghost, .link)) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
-  }
-
-  /* Same recipe as the resting .soft bg with the surface share reduced by
-     --soft-hover-alpha: stays opaque, so it reads on any backdrop instead of
-     letting the container show through on hover. */
-  :is(.btn, a.badge, button.badge):is(.soft) {
-    --ui-hover-bg: color-mix(
-      in oklch,
-      var(--surface) calc(var(--soft-bg-mix) - var(--soft-hover-alpha)),
-      var(--intent, var(--neutral))
-    );
-  }
-
-  /* Mixed against the opaque --surface-subtle rather than transparent: a
-     transparent-based tint reads clean on light surfaces but goes muddy and
-     low-contrast on dark ones, since the same low alpha lands very
-     differently over a light vs. a near-black backdrop. */
-  :is(.btn, a.badge, button.badge):is(.outline) {
-    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
-  }
-
-  :is(.btn, a.badge, button.badge):is(.ghost) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--text)) 8%, transparent);
-  }
-}
+/* Interactive hover recipes live in the components that consume them:
+     components/button.css and components/badge.css. */
 
 /*
  * Prose is the opt-in rich text scope for authored content.
  *
  * Global element styles stay mild so app UI is not shaped accidentally. Page
  * layout, forms, cards, navigation, and app tables remain outside this scope.
+ *
+ * Public hooks:
+ * --prose-size
+ * --prose-line-height
+ * --prose-measure
+ * --prose-flow
+ * --prose-heading-line-height
+ * --prose-h1
+ * --prose-h2
+ * --prose-h3
+ * --prose-h4
  */
 
 .prose {
@@ -893,15 +906,13 @@ small {
   text-underline-offset: 0.18em;
 }
 
-@media (hover: hover) {
-  .prose a:hover {
-    text-decoration-thickness: 0.12em;
-  }
+.prose a:hover {
+  text-decoration-thickness: 0.12em;
+}
 
-  @supports (color: color-mix(in oklch, red, white)) {
-    .prose a:hover {
-      color: color-mix(in oklch, var(--primary), var(--text) 15%);
-    }
+@supports (color: color-mix(in oklch, red, white)) {
+  .prose a:hover {
+    color: color-mix(in oklch, var(--primary), var(--text) 15%);
   }
 }
 
@@ -921,6 +932,7 @@ small {
   font-size: 0.875em;
 }
 
+/* Visual twin of .key (components/key.css) — keep the two recipes in sync. */
 .prose kbd {
   display: inline-flex;
   align-items: center;
@@ -1025,19 +1037,35 @@ small {
  * Disabled state uses the native disabled attribute for buttons and inputs.
  * Anchors have no native disabled state, so a.btn uses aria-disabled="true"
  * for disabled styling and activation guards.
+ *
+ * Public hooks:
+ * --btn-font-size
+ * --btn-min-size
+ * --btn-pad-x
+ * --btn-radius
+ * --btn-focus-color
+ * --btn-gap
+ * --btn-hover-overlay
+ *
+ * Internal:
+ * --btn-bg
+ * --btn-fg
+ * --btn-border
+ * --btn-focus-ring-color
+ * --btn-border-block-end-color
+ * --btn-border-block-end-width
+ * --spinner-width
  */
 
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.btn) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
   --ui-bg: initial;
   --ui-fg: initial;
   --ui-border: initial;
   --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .btn {
@@ -1049,17 +1077,17 @@ small {
   --btn-border: var(--ui-border, var(--btn-default-border, transparent));
   --btn-radius: var(--radius);
   --btn-focus-color: var(--intent, var(--focus));
-  --btn-hover-bg: var(--ui-hover-bg, var(--btn-bg));
   --btn-hover-overlay: var(--hover-overlay, rgb(0 0 0 / 0.08));
 
+  /* Positioning context for indicators, overlays, and grouped states. */
   position: relative;
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: 0.375em;
+  gap: var(--btn-gap, 0.375em);
   min-block-size: var(--btn-min-size);
-  padding-block: var(--space-2);
-  padding-block: max(var(--space-1), calc((var(--btn-min-size) - 1lh) / 2));
+  padding-block: var(--space-20);
+  padding-block: max(var(--space-10), calc((var(--btn-min-size) - 1lh) / 2));
   padding-inline: var(--btn-pad-x);
   border: var(--border-width) solid var(--btn-border-color, var(--btn-border));
   border-block-end-color: var(
@@ -1084,6 +1112,11 @@ small {
     transform var(--duration);
 }
 
+.btn.icon-only {
+  inline-size: var(--btn-min-size);
+  padding-inline: 0;
+}
+
 @supports (color: color-mix(in oklch, red, white)) {
   .btn {
     --btn-focus-ring-color: color-mix(in oklch, var(--btn-focus-color) 28%, transparent);
@@ -1108,13 +1141,40 @@ small {
   --btn-hover-overlay: transparent;
 }
 
-/* The .soft/.outline/.ghost hover recipe (--ui-hover-bg) is shared with
-   .badge in variants.css; the overlay darkening for solid/soft is .btn-specific. */
-@media (hover: hover) {
-  .btn:not(:where(:disabled, [aria-disabled="true"])):hover {
-    background: var(--btn-hover-bg);
-    box-shadow: inset 0 0 0 999px var(--btn-hover-overlay);
+/* Shared hover recipe — sets --ui-hover-bg consumed by the hover rule below.
+   Declared outside :hover: the variables resolve only when the hover rule
+   reads them, so the values are inert until interaction. */
+.btn:is(.outline, .ghost) {
+  --ui-hover-bg: var(--surface-subtle);
+}
+
+@supports (color: color-mix(in oklch, red, white)) {
+  .btn:not(:where(.soft, .outline, .ghost, .link)) {
+    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
+  }
+
+  .btn.soft {
+    --ui-hover-bg: color-mix(
+      in oklch,
+      var(--surface) calc(var(--soft-bg-mix) - var(--soft-hover-alpha)),
+      var(--intent, var(--neutral))
+    );
+  }
+
+  .btn.outline {
+    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
   }
+
+  .btn.ghost {
+    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--text)) 8%, transparent);
+  }
+}
+
+/* The .soft/.outline/.ghost hover recipe (--ui-hover-bg) is set locally above;
+   the overlay darkening for solid/soft is .btn-specific. */
+.btn:not(:where(:disabled, [aria-disabled="true"])):hover {
+  background: var(--ui-hover-bg, var(--btn-bg));
+  box-shadow: inset 0 0 0 999px var(--btn-hover-overlay);
 }
 
 .btn:not(:where(:disabled, [aria-disabled="true"])):active {
@@ -1139,16 +1199,14 @@ small {
 /* .btn.circle needs no local rule: the .circle utility (utilities.css) loads
    after components and overrides border-radius at equal specificity. */
 
-@media (hover: hover) {
-  .btn.link:not(:where(:disabled, [aria-disabled="true"])):hover {
-    background: transparent;
-    color: var(--intent, var(--text));
-    text-decoration-thickness: 0.12em;
-  }
+.btn.link:not(:where(:disabled, [aria-disabled="true"])):hover {
+  background: transparent;
+  color: var(--intent, var(--text));
+  text-decoration-thickness: 0.12em;
 }
 
 .btn:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: 0 0 0 var(--focus-ring-width) var(--btn-focus-ring-color, var(--focus-ring));
 }
 
@@ -1182,13 +1240,15 @@ a.btn[aria-disabled="true"] {
   --spinner-width: 0.15em;
 }
 
-/* Toggle */
-/* State must outrank the shared .outline/.ghost hover recipes: a pressed
-   button keeps its intent background and foreground while hovered. */
-.btn:is([aria-pressed="true"], [aria-current]:not([aria-current="false"])):not(.link) {
-  --btn-bg: var(--intent, var(--primary));
-  --btn-fg: var(--intent-fg, var(--primary-fg));
-  --btn-border: var(--intent, var(--primary));
+/* Toggle and current state.
+   State must outrank the shared .outline/.ghost hover recipes: a pressed or
+   current button keeps its intent background and foreground while hovered.
+   aria-current="page" is the pagination current-page marker; aria-pressed
+   covers toggle buttons. */
+.btn:is([aria-pressed="true"], [aria-current="page"]):not(.link) {
+  --btn-bg: var(--intent, var(--state-selected));
+  --btn-fg: var(--intent-fg, var(--state-selected-fg));
+  --btn-border: var(--intent, var(--state-selected));
   --ui-hover-bg: var(--btn-bg);
 }
 
@@ -1206,18 +1266,16 @@ a.btn[aria-disabled="true"] {
     color: LinkText;
   }
 
-  .btn:is([aria-pressed="true"], [aria-current]:not([aria-current="false"])):not(.link) {
+  .btn:is([aria-pressed="true"], [aria-current="page"]):not(.link) {
     border-color: Highlight;
     background: Highlight;
     color: HighlightText;
     forced-color-adjust: none;
   }
 
-  @media (hover: hover) {
-    .btn:hover:not(:where(:disabled, [aria-disabled="true"], .link)) {
-      outline: var(--border-width) solid ButtonText;
-      outline-offset: 2px;
-    }
+  .btn:hover:not(:where(:disabled, [aria-disabled="true"], .link)) {
+    outline: var(--border-width) solid ButtonText;
+    outline-offset: 2px;
   }
 
   .btn:disabled,
@@ -1235,34 +1293,46 @@ a.btn[aria-disabled="true"] {
  * Soft by default. .solid for counters and notification badges. The dot
  * (.badge:empty) stays solid regardless — a soft dot is pointless.
  * Shared .outline variant stays available.
+ *
+ * Public hooks:
+ * --badge-size
+ * --badge-pad-x
+ * --badge-font-size
+ * --badge-dot-size
+ * --badge-radius
+ *
+ * Internal:
+ * --badge-bg
+ * --badge-fg
+ * --badge-border
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.badge) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
   --ui-bg: initial;
   --ui-fg: initial;
   --ui-border: initial;
   --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .badge {
-  --badge-size: var(--variant-compact-size, 1.5rem);
+  --badge-size: var(--density-compact-size);
   --badge-pad-x: 0.55em;
-  --badge-font-size: var(--variant-compact-font-size, 0.8125rem);
+  --badge-font-size: 0.8125rem;
   --badge-dot-size: 0.5rem;
-  --badge-bg: var(--ui-bg, transparent);
+  --badge-bg: var(--ui-bg, var(--surface-subtle));
   --badge-fg: var(--ui-fg, var(--intent, var(--text)));
-  --badge-border: var(--ui-border, var(--intent, var(--border)));
-  --badge-radius: 999px;
+  --badge-border: var(--ui-border, var(--border));
+  --badge-radius: var(--radius-full);
 
   display: inline-flex;
   align-items: center;
   justify-content: center;
   gap: 0.35em;
+  inline-size: fit-content;
+  max-inline-size: 100%;
   min-block-size: var(--badge-size);
   padding-inline: var(--badge-pad-x);
   border: var(--border-width) solid var(--badge-border);
@@ -1331,27 +1401,44 @@ a.btn[aria-disabled="true"] {
   cursor: pointer;
 }
 
-@media (hover: hover) {
-  .badge > button:not(:disabled):hover {
-    background: var(--hover-overlay);
-  }
+.badge > button:not(:disabled):hover {
+  background: var(--hover-overlay);
 }
 
-/* .solid/.soft/.outline are shared via variants.css, including the
-   .soft/.outline hover recipe (--ui-hover-bg). */
-@media (hover: hover) {
-  :where(a.badge, button.badge):not(:where(:disabled, [aria-disabled="true"])):hover {
-    background: var(--ui-hover-bg, var(--badge-bg));
+/* Hover recipes — sets --ui-hover-bg consumed by the hover rule below.
+   Declared outside :hover like button.css for the same reason. */
+:is(a.badge, button.badge).outline {
+  --ui-hover-bg: var(--surface-subtle);
+}
+
+@supports (color: color-mix(in oklch, red, white)) {
+  :is(a.badge, button.badge):is(.solid, :empty) {
+    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
   }
 
-  :where(a.badge, button.badge):not(:where(:disabled, [aria-disabled="true"], .outline)):hover {
-    box-shadow: inset 0 0 0 999px var(--hover-overlay);
+  :is(a.badge, button.badge):where(:not(.solid, .outline, :empty)) {
+    --ui-hover-bg: color-mix(
+      in oklch,
+      var(--surface) calc(var(--soft-bg-mix) - var(--soft-hover-alpha)),
+      var(--intent, var(--neutral))
+    );
+  }
+
+  :is(a.badge, button.badge).outline {
+    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
   }
 }
 
+:where(a.badge, button.badge):not(:where(:disabled, [aria-disabled="true"])):hover {
+  background: var(--ui-hover-bg, var(--badge-bg));
+}
+
+:where(a.badge, button.badge):not(:where(:disabled, [aria-disabled="true"], .outline)):hover {
+  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+}
+
 button.badge {
   cursor: pointer;
-  font: inherit;
 }
 
 button.badge:disabled,
@@ -1365,27 +1452,18 @@ a.badge[aria-disabled="true"] {
 }
 
 @media (forced-colors: active) {
-  .badge {
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-    box-shadow: none;
-  }
-
   .badge:empty {
     background: ButtonText;
   }
 
-  @media (hover: hover) {
-    :where(a.badge, button.badge):hover:not(:where(:disabled, [aria-disabled="true"])) {
-      outline: var(--border-width) solid ButtonText;
-      outline-offset: 2px;
-    }
+  :where(a.badge, button.badge):hover:not(:where(:disabled, [aria-disabled="true"])) {
+    outline: var(--border-width) solid ButtonText;
+    outline-offset: 2px;
+  }
 
-    .badge > button:not(:disabled):hover {
-      outline: var(--border-width) solid currentColor;
-      outline-offset: 1px;
-    }
+  .badge > button:not(:disabled):hover {
+    outline: var(--border-width) solid currentColor;
+    outline-offset: 1px;
   }
 
   button.badge:disabled,
@@ -1405,42 +1483,48 @@ a.badge[aria-disabled="true"] {
  * --alert-border-inline-start-color/-width are unset extension points, mirroring
  * --btn-border-block-end-* (button.css), for themes that give alerts a
  * callout-style colored flag on the leading edge instead of a uniform border.
+ *
+ * Public hooks:
+ * --alert-pad-block
+ * --alert-pad-inline
+ * --alert-font-size
+ * --alert-radius
+ * --alert-icon-size
+ * --alert-dismiss-size
+ *
+ * Internal:
+ * --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. */
 :where(.alert) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
   --ui-bg: initial;
   --ui-fg: initial;
   --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .alert {
-  --alert-pad-block: var(--variant-pad-block, var(--space-3));
-  --alert-pad-inline: var(--space-4);
-  --alert-font-size: var(--variant-font-size, var(--font-size-md));
-  --alert-icon-size: var(--variant-icon-size, 1.25rem);
-  --alert-bg: var(--surface-subtle);
-  --alert-border: var(--border);
-  --ui-bg: var(--alert-bg);
-  --ui-border: var(--alert-border);
-  --ui-fg: var(--intent, var(--text));
+  --alert-pad-block: var(--space-30);
+  --alert-pad-inline: var(--space-40);
+  --alert-font-size: var(--font-size-md);
+  --alert-icon-size: 1.25rem;
+  --alert-bg: var(--ui-bg, var(--surface-subtle));
+  --alert-fg: var(--ui-fg, var(--intent, var(--text)));
+  --alert-border: var(--ui-border, var(--border));
 
   padding-block: var(--alert-pad-block);
   padding-inline: var(--alert-pad-inline);
-  background: var(--ui-bg, transparent);
-  color: var(--ui-fg, var(--text));
-  border: var(--border-width) solid var(--ui-border, var(--border));
-  border-inline-start-color: var(
-    --alert-border-inline-start-color,
-    var(--ui-border, var(--border))
-  );
+  background: var(--alert-bg);
+  color: var(--alert-fg);
+  border: var(--border-width) solid var(--alert-border);
+  border-inline-start-color: var(--alert-border-inline-start-color, var(--alert-border));
   border-inline-start-width: var(--alert-border-inline-start-width, var(--border-width));
-  border-radius: var(--radius-lg);
+  border-radius: var(--alert-radius, var(--radius-lg));
   font-size: var(--alert-font-size);
 }
 
@@ -1456,19 +1540,8 @@ a.badge[aria-disabled="true"] {
   margin-block-end: 0;
 }
 
-/* Alerts are soft by default. Use .solid or .outline for stronger emphasis. */
-.alert.solid {
-  --ui-bg: var(--intent, var(--neutral));
-  --ui-fg: var(--intent-fg, var(--neutral-fg));
-  --ui-border: transparent;
-}
-
-.alert.outline {
-  --ui-bg: transparent;
-  --ui-fg: var(--intent, var(--text));
-  --ui-border: var(--intent, var(--border));
-}
-
+/* Alerts are soft by default. .solid and .outline need no local rules — the
+   shared variant plumbing in variants.css sets --ui-* that alert consumes. */
 @supports (color: color-mix(in oklch, red, white)) {
   .alert:where(:not(.solid, .outline, .callout)) {
     /* @sync soft-recipe */
@@ -1482,8 +1555,8 @@ a.badge[aria-disabled="true"] {
   }
 }
 
-/* Decorative leading icon */
-.alert > :first-child[aria-hidden="true"] {
+/* Decorative leading icon — use .alert-icon on the icon element. */
+.alert > .alert-icon {
   display: inline-block;
   flex: none;
   inline-size: var(--alert-icon-size);
@@ -1493,33 +1566,84 @@ 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;
+}
+
+.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;
+}
+
+@media (hover: hover) {
+  .alert-dismiss:hover {
+    background: var(--hover-overlay);
+    opacity: 1;
+  }
+}
+
+/* Grid anatomy — activated by a leading icon, a trailing dismiss button, or
+   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(> :first-child[aria-hidden="true"]) {
+  .alert:has(> .alert-icon, > .alert-dismiss) {
     display: grid;
-    grid-template-columns: auto minmax(0, 1fr);
+    grid-template-columns: minmax(0, 1fr);
     align-items: var(--items-align, start);
-    column-gap: var(--space-3);
+    column-gap: var(--space-30);
+  }
+
+  .alert:has(> .alert-icon) {
+    grid-template-columns: auto minmax(0, 1fr);
   }
 
-  .alert:has(> :first-child[aria-hidden="true"]) > :first-child {
+  .alert:has(> .alert-icon) > .alert-icon {
     grid-column: 1;
     grid-row: 1 / -1;
     display: inline-grid;
     place-items: center;
-    inline-size: var(--alert-icon-size);
-    block-size: var(--alert-icon-size);
     margin-block-start: 0.125em;
-    font-size: var(--alert-icon-size);
-    line-height: 1;
   }
 
-  .alert:has(> :first-child[aria-hidden="true"]) > :first-child:is(svg, i) {
-    inline-size: var(--alert-icon-size);
-    block-size: var(--alert-icon-size);
+  .alert:has(> .alert-icon) > :not(.alert-icon, .alert-dismiss) {
+    grid-column: 2;
   }
 
-  .alert:has(> :first-child[aria-hidden="true"]) > :not(:first-child) {
-    grid-column: 2;
+  .alert:has(> .alert-dismiss) {
+    grid-template-columns: minmax(0, 1fr) auto;
+  }
+
+  .alert:has(> .alert-icon):has(> .alert-dismiss) {
+    grid-template-columns: auto minmax(0, 1fr) auto;
+  }
+
+  .alert:has(> .alert-dismiss) > .alert-dismiss {
+    grid-column: -2 / -1;
+    grid-row: 1;
   }
 }
 
@@ -1534,100 +1658,84 @@ a.badge[aria-disabled="true"] {
    Canvas backplate (unreadable) — so .solid intentionally falls back to the
    default look. */
 
-/* Callout — neutral surface with an inset accent band on the leading edge.
-   The ::before pseudo is absolutely positioned and inset to respect the
-   outer border-radius, so it never needs its own radius. */
+/* Callout — neutral surface with a thick accent border on the leading edge.
+   The thickness follows the shared --alert-border-inline-start-width hook. */
 .alert.callout {
   --alert-bg: var(--surface-subtle);
-  --ui-bg: var(--alert-bg);
-  --ui-fg: var(--text);
-  --ui-border: var(--border);
-  position: relative;
-  padding-inline-start: calc(var(--alert-pad-inline) + var(--space-3));
-}
-
-.alert.callout::before {
-  content: "";
-  position: absolute;
-  inset-block: var(--space-2);
-  inset-inline-start: var(--space-2);
-  inline-size: 0.25rem;
-  border-radius: var(--radius-full);
-  background: var(--intent, var(--neutral));
+  --alert-fg: var(--text);
+  border: 0;
+  border-inline-start: var(--alert-border-inline-start-width, 4px) solid
+    var(--alert-border-inline-start-color, var(--intent, var(--neutral)));
 }
 
-/* Admonition — structured title/body anatomy with a tinted title band.
-   The root is layout-neutralized: no padding, no gap, no icon grid. */
+/* Admonition — structured static box with a tinted title bar and a body
+   that rests on the page surface. Not collapsible — use .accordion inside
+   the body if the content needs to be expandable. */
 .alert.admonition {
   padding: 0;
-  gap: 0;
   display: block;
   overflow: clip;
+  border-color: var(--intent, var(--border));
 }
 
-.alert-title {
+.alert.admonition > .alert-title {
+  display: flex;
+  align-items: center;
+  gap: var(--space-20);
   padding-block: var(--alert-pad-block);
   padding-inline: var(--alert-pad-inline);
+  border-start-start-radius: calc(var(--alert-radius, var(--radius-lg)) - var(--border-width));
+  border-start-end-radius: calc(var(--alert-radius, var(--radius-lg)) - var(--border-width));
+}
 
-  @supports (color: color-mix(in oklch, red, white)) {
+/* Dismiss inside an admonition title bar rides the inline end. */
+.alert.admonition > .alert-title > .alert-dismiss {
+  margin-inline-start: auto;
+}
+
+@supports (color: color-mix(in oklch, red, white)) {
+  .alert.admonition > .alert-title {
     background: color-mix(
       in oklch,
       var(--surface) var(--soft-bg-mix),
       var(--intent, var(--neutral))
     );
   }
+}
 
-  @supports not (color: color-mix(in oklch, red, white)) {
+@supports not (color: color-mix(in oklch, red, white)) {
+  .alert.admonition > .alert-title {
     background: var(--intent, var(--neutral));
+    color: var(--intent-fg, var(--neutral-fg));
   }
-
-  border-start-start-radius: calc(var(--radius-lg) - var(--border-width));
-  border-start-end-radius: calc(var(--radius-lg) - var(--border-width));
 }
 
-.alert-title:where(summary) {
-  cursor: pointer;
-  user-select: none;
-  list-style: none;
-}
-
-.alert-title:where(summary)::-webkit-details-marker {
-  display: none;
-}
-
-.alert-title[aria-hidden] {
-  display: inline-flex;
-  gap: var(--space-2);
-  align-items: center;
-}
-
-.alert-body {
+.alert.admonition > .alert-body {
   padding-block: var(--alert-pad-block);
   padding-inline: var(--alert-pad-inline);
+  background: var(--surface);
   color: var(--text);
 }
 
-.alert-body > :first-child {
+.alert.admonition > .alert-body > :first-child {
   margin-block-start: 0;
 }
 
-.alert-body > :last-child {
+.alert.admonition > .alert-body > :last-child {
   margin-block-end: 0;
 }
 
-details.alert.admonition[open] .alert-title {
-  border-end-start-radius: 0;
-  border-end-end-radius: 0;
-}
-
 /*
  * Actions — a horizontal action-button cluster.
  *
  * Composes with .btn (or any inline element) and feeds layout via the shared
  * --gap token.
+ *
+ * Internal:
+ * --gap (local value for the shared gap token)
  */
 .actions {
-  --gap: var(--space-2);
+  --gap: var(--space-20);
 
   display: flex;
   flex-wrap: wrap;
@@ -1650,28 +1758,36 @@ details.alert.admonition[open] .alert-title {
  * Surface, border, radius, padding, density, and elevation stay local here.
  * Direct header/footer children are structural slots. Page layout remains the
  * job of markup and layout primitives outside the card.
+ *
+ * Public hooks:
+ * --card-pad
+ * --card-radius
+ * --card-max-inline-size
+ *
+ * Child contract:
+ * Direct .bleed children escape --card-pad (negative inset, wider media);
+ * edge children inherit the card corners. .bleed must be a direct child.
+ *
+ * Internal:
+ * --heading
+ * --busy-overlay-bg
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.card) {
-  /* @sync intent-boundary */
-  --intent: initial;
-  --intent-fg: initial;
   --ui-bg: initial;
   --ui-fg: initial;
   --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .card {
-  --card-pad: var(--space-4);
+  --card-pad: var(--space-40);
   --card-radius: var(--radius-lg);
   --card-max-inline-size: none;
 
   max-inline-size: var(--card-max-inline-size);
   padding: var(--card-pad);
-  background: var(--ui-bg, var(--surface));
+  background: var(--ui-bg, var(--surface-raised));
   color: var(--ui-fg, var(--text));
   border: var(--border-width) solid var(--ui-border, var(--border));
   border-radius: var(--card-radius);
@@ -1686,7 +1802,7 @@ details.alert.admonition[open] .alert-title {
   flex-wrap: wrap;
   align-items: var(--items-align, center);
   justify-content: space-between;
-  gap: var(--space-3);
+  gap: var(--space-30);
   min-inline-size: 0;
 }
 
@@ -1713,16 +1829,8 @@ details.alert.admonition[open] .alert-title {
 .card.subtle {
   background: var(--surface-subtle);
 }
-.card.inverted {
-  background: var(--surface-solid);
-  color: var(--surface);
-  border-color: transparent;
-  --heading: var(--surface);
-  --busy-overlay-bg: var(--surface-solid);
-}
-
 .card.compact {
-  --card-pad: var(--space-2);
+  --card-pad: var(--space-20);
 }
 
 /* Full-bleed children */
@@ -1765,26 +1873,6 @@ details.alert.admonition[open] .alert-title {
   padding: var(--card-pad);
 }
 
-@media (forced-colors: active) {
-  .card {
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-  }
-
-  .card.raised {
-    box-shadow: none;
-  }
-
-  .card.inverted {
-    --heading: CanvasText;
-
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-  }
-}
-
 /*
  * Surface — shared modal scrim and backdrop for flyout and drawer.
  *
@@ -1806,7 +1894,7 @@ details.alert.admonition[open] .alert-title {
   z-index: calc(var(--z-menu) - 1);
   background: var(--backdrop-fill);
   opacity: 1;
-  transition: opacity var(--duration) var(--ease, ease);
+  transition: opacity var(--duration) var(--ease);
 }
 
 .surface-backdrop[hidden] {
@@ -1823,28 +1911,40 @@ details.alert.admonition[open] .alert-title {
 @supports (transition-behavior: allow-discrete) {
   .surface-backdrop {
     transition:
-      opacity var(--duration) var(--ease, ease),
+      opacity var(--duration) var(--ease),
       display var(--duration) allow-discrete;
   }
 }
 
-@media (forced-colors: active) {
-  .surface-backdrop {
-    background: Canvas;
-  }
-}
-
 /*
  * Modal shell styling for native dialog elements.
  *
  * Spacing, radius, transitions, and focus treatment come from shared tokens.
  * Opening behavior and intent-specific decisions stay outside this component.
+ *
+ * Public hooks:
+ * --modal-size
+ * --dialog-viewport-gap
+ * --dialog-icon-size
+ * --dialog-icon-glyph-size
+ *
+ * Internal:
+ * --dialog-close-icon-size
+ * --dialog-viewport-gap-2x
  */
 dialog.modal {
   --modal-size: 32rem;
+  --dialog-viewport-gap: var(--space-40);
+  /* calc() multiplication is not in the supported browser range, so the
+     doubled gap is spelled out with an additive calc. */
+  --dialog-viewport-gap-2x: calc(var(--dialog-viewport-gap) + var(--dialog-viewport-gap));
 
-  max-inline-size: min(100% - 2rem, var(--modal-size));
-  max-block-size: calc(var(--viewport-block) - 2rem);
+  /* Keep the surface anchored to the viewport in the top layer. This also
+     provides the containing block for the absolutely positioned close button. */
+  position: fixed;
+
+  max-inline-size: min(calc(100% - var(--dialog-viewport-gap-2x)), var(--modal-size));
+  max-block-size: calc(var(--viewport-block) - var(--dialog-viewport-gap-2x));
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius-lg);
   background: var(--surface-raised);
@@ -1868,11 +1968,18 @@ dialog.modal {
 dialog.modal > form,
 dialog.modal > .stack {
   display: grid;
-  gap: var(--space-4);
-  max-block-size: calc(var(--viewport-block) - 2rem);
+  gap: var(--space-40);
+  max-block-size: calc(var(--viewport-block) - var(--dialog-viewport-gap-2x));
   overflow: auto;
   overscroll-behavior: contain;
-  padding: var(--space-4);
+  padding: var(--space-40);
+}
+
+/* Keep the dialog off the viewport edges on small screens. */
+@media (max-width: 30rem) {
+  dialog.modal {
+    --dialog-viewport-gap: var(--space-30);
+  }
 }
 
 dialog.modal.scrollable > form,
@@ -1898,6 +2005,13 @@ dialog.modal footer > :last-child {
   margin-block-end: 0;
 }
 
+/* The close button is anchored to the dialog at top inline-end, out of the
+   content flow; headers reserve inline room so titles never run under it. */
+dialog.modal > form > header,
+dialog.modal > .stack > header {
+  padding-inline-end: calc(var(--control-size) + var(--space-30));
+}
+
 dialog.modal footer {
   display: flex;
   flex-wrap: wrap;
@@ -1905,6 +2019,65 @@ dialog.modal footer {
   gap: var(--gap);
 }
 
+/* Confirmation layout — a focused message followed by a visually distinct
+   action band. The media primitive owns icon/content alignment; this variant
+   only removes the standard form inset so both regions can own their padding. */
+dialog.modal.dialog-confirmation > form {
+  gap: 0;
+  padding: 0;
+}
+
+dialog.modal.dialog-confirmation > form > .media {
+  gap: var(--space-40);
+  padding: var(--space-50);
+}
+
+dialog.modal.dialog-confirmation > form > footer {
+  padding: var(--space-40) var(--space-50);
+  border-end-start-radius: calc(var(--radius-lg) - var(--border-width));
+  border-end-end-radius: calc(var(--radius-lg) - var(--border-width));
+  background: var(--surface-subtle);
+}
+
+/* Intent boundary — inherited intents do not tint the icon well. A local
+   intent plus .soft opts into the shared soft-variant recipe. */
+:where(.dialog-icon) {
+  --intent: initial;
+  --intent-fg: initial;
+  --ui-bg: initial;
+  --ui-fg: initial;
+}
+
+.dialog-icon {
+  --dialog-icon-size: 3rem;
+  --dialog-icon-glyph-size: 1.5rem;
+
+  display: inline-grid;
+  place-items: center;
+  inline-size: var(--dialog-icon-size);
+  block-size: var(--dialog-icon-size);
+  flex: none;
+  border-radius: var(--radius-full);
+  background: var(--ui-bg, var(--surface-subtle));
+  color: var(--ui-fg, var(--intent, var(--text-muted)));
+}
+
+.dialog-icon > * {
+  display: inline-grid;
+  place-items: center;
+  inline-size: var(--dialog-icon-glyph-size);
+  block-size: var(--dialog-icon-glyph-size);
+  font-size: var(--dialog-icon-glyph-size);
+  line-height: 1;
+}
+
+@media (max-width: 30rem) {
+  dialog.modal.dialog-confirmation > form > .media,
+  dialog.modal.dialog-confirmation > form > footer {
+    padding: var(--space-40);
+  }
+}
+
 dialog.modal[open] {
   opacity: 1;
   transform: none;
@@ -1960,7 +2133,7 @@ html.has-modal-open.had-scrollbar {
 
 @media (prefers-reduced-motion: no-preference) {
   dialog.modal.is-static {
-    animation: actual-modal-static 180ms var(--ease);
+    animation: actual-dialog-static var(--duration-slow) var(--ease);
   }
 
   ::view-transition-group(actual-dialog) {
@@ -1969,7 +2142,7 @@ html.has-modal-open.had-scrollbar {
   }
 }
 
-@keyframes actual-modal-static {
+@keyframes actual-dialog-static {
   0%,
   100% {
     transform: none;
@@ -1995,6 +2168,70 @@ html.has-modal-open.had-scrollbar {
   dialog.modal::backdrop {
     background: Canvas;
   }
+
+  .dialog-icon {
+    border: var(--border-width) solid CanvasText;
+  }
+}
+
+/* Close controls. A close button is an action attached to a surface, so it
+   never participates in the content flow. The modal and the drawer share the
+   same simple placement — absolute at the panel's top inline-end, inside the
+   surface — so both close buttons look and behave identically. The glyph comes
+   from --icon-close, masked to currentColor, so no icon font or text glyph is
+   required in the markup. */
+.dialog-close,
+.drawer-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,
+.drawer-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,
+  .drawer-close:hover {
+    box-shadow: inset 0 0 0 999px var(--hover-overlay);
+    color: var(--text);
+  }
+}
+
+.dialog-close:active,
+.drawer-close:active {
+  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+}
+
+.dialog-close:focus-visible,
+.drawer-close:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow: var(--focus-ring-shadow);
 }
 
 /*
@@ -2005,16 +2242,30 @@ html.has-modal-open.had-scrollbar {
  * discrete display/overlay transitions. The drawer is a layout shell only —
  * navigation content inside uses .nav-link and .accordion, which carry their
  * own link/summary styling.
+ *
+ * Public hooks:
+ * --drawer-size
+ * --drawer-pad
+ *
+ * Internal:
+ * --drawer-closed-translate (side/RTL positioning state)
  */
 dialog.drawer {
   --drawer-size: 20rem;
-  --drawer-pad: var(--space-4);
+  --drawer-pad: var(--space-40);
   --drawer-closed-translate: -100%;
 
+  /* Keep the surface anchored to the viewport in the top layer. This also
+     provides the containing block for the absolutely positioned close button.
+     A percentage height resolves against the fixed containing viewport, while
+     dynamic viewport units can be stale in embedded previews. */
+  position: fixed;
+  inset-block-start: 0;
+
   inline-size: min(calc(var(--viewport-inline) * 0.9), var(--drawer-size));
-  block-size: var(--viewport-block);
+  block-size: 100%;
   max-inline-size: none;
-  max-block-size: var(--viewport-block);
+  max-block-size: 100%;
   margin: 0;
   padding: var(--drawer-pad);
   border: 0;
@@ -2033,7 +2284,7 @@ dialog.drawer {
 dialog.drawer[open] {
   display: grid;
   grid-template-rows: auto minmax(0, 1fr) auto;
-  gap: var(--space-4);
+  gap: var(--space-40);
   opacity: 1;
   transform: translateX(0);
 }
@@ -2104,20 +2355,23 @@ dialog.drawer nav {
 }
 
 @media (forced-colors: active) {
-  dialog.drawer {
-    border-inline-end-color: ButtonText;
+  dialog.drawer::backdrop {
     background: Canvas;
-    color: CanvasText;
-    box-shadow: none;
   }
+}
 
-  dialog.drawer[data-side="end"] {
-    border-inline-start-color: ButtonText;
+@media (prefers-reduced-motion: no-preference) {
+  dialog.drawer.is-static {
+    animation: actual-dialog-static var(--duration-slow) var(--ease);
   }
+}
 
-  dialog.drawer::backdrop {
-    background: Canvas;
-  }
+/* The close button shares the modal's interior placement (modal.css): absolute
+   at the panel's top inline-end, out of the content flow. The header reserves
+   inline room so the title never runs under it. */
+dialog.drawer > header,
+dialog.drawer > form > header {
+  padding-inline-end: calc(var(--control-size) + var(--space-30));
 }
 
 
@@ -2133,7 +2387,16 @@ dialog.drawer nav {
  * .is-sheet marks "auto" resolved to bottom-sheet presentation on coarse
  * pointers. Authors opt into mobile behavior with
  * [data-flyout-mobile="sheet|auto|none|anchored"].
- * --flyout-trigger-width is set by surface.js while an open flyout is positioned.
+ * --surface-anchor-width is set by surface.js while an open flyout is positioned.
+ *
+ * Public hooks:
+ * --flyout-inline-size
+ * --flyout-max-inline-size
+ *
+ * Internal:
+ * --menu-item-size (derived from --control-size for menu rows)
+ * --available-height (measured by floating.js)
+ * --surface-anchor-width (measured by surface.js)
  */
 
 .flyout-trigger {
@@ -2156,28 +2419,32 @@ dialog.drawer nav {
 }
 
 .flyout {
+  --menu-item-size: var(--control-size);
   z-index: var(--z-menu);
   /* No-JS fallback: below the trigger inside the relative .flyout-trigger.
      surface.js switches an open flyout to position: fixed with measured
      coordinates; this only covers a flyout revealed without the runtime. */
   position: absolute;
-  inset-block-start: calc(100% + var(--space-1));
+  inset-block-start: calc(100% + var(--space-10));
   inset-inline-start: 0;
   display: grid;
-  gap: var(--space-1);
+  gap: var(--space-10);
   inline-size: var(--flyout-inline-size, max-content);
   min-inline-size: min(
-    var(--flyout-trigger-width, 0px),
-    min(var(--flyout-max-inline-size, 20rem), calc(var(--viewport-inline) - var(--space-6)))
+    var(--surface-anchor-width, 0px),
+    min(var(--flyout-max-inline-size, 20rem), calc(var(--viewport-inline) - var(--space-60)))
   );
   max-inline-size: min(
     var(--flyout-max-inline-size, 20rem),
-    calc(var(--viewport-inline) - var(--space-6))
+    calc(var(--viewport-inline) - var(--space-60))
+  );
+  max-block-size: min(
+    24rem,
+    var(--available-height, calc(var(--viewport-block) - var(--space-60)))
   );
-  max-block-size: min(24rem, var(--available-height, calc(var(--viewport-block) - var(--space-6))));
   overflow: auto;
   margin: 0;
-  padding: var(--space-1);
+  padding: var(--space-10);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
   background: var(--surface-raised);
@@ -2186,9 +2453,9 @@ dialog.drawer nav {
   opacity: 1;
   scale: 1;
   transition:
-    opacity var(--duration-fast, var(--duration)) var(--ease, ease),
-    scale var(--duration-fast, var(--duration)) var(--ease, ease),
-    translate var(--duration-fast, var(--duration)) var(--ease, ease);
+    opacity var(--duration-fast) var(--ease),
+    scale var(--duration-fast) var(--ease),
+    translate var(--duration-fast) var(--ease);
 }
 
 .flyout.is-open:not(.is-sheet) {
@@ -2205,6 +2472,7 @@ dialog.drawer nav {
 /* Bottom-sheet presentation. surface.js toggles .is-sheet when the flyout is
    opened on coarse pointer / narrow viewports. */
 .flyout.is-sheet {
+  --menu-item-size: var(--control-size-lg);
   position: fixed;
   inset-inline: 0;
   inset-block-start: auto;
@@ -2215,8 +2483,8 @@ dialog.drawer nav {
   max-block-size: min(calc(var(--viewport-block) * 0.75), 32rem);
   overflow: auto;
   grid-template-columns: 1fr;
-  padding: max(var(--space-3), env(safe-area-inset-top)) var(--space-3)
-    max(var(--space-3), env(safe-area-inset-bottom));
+  padding: max(var(--space-30), env(safe-area-inset-top)) var(--space-30)
+    max(var(--space-30), env(safe-area-inset-bottom));
   border-end-start-radius: 0;
   border-end-end-radius: 0;
 }
@@ -2229,23 +2497,23 @@ dialog.drawer nav {
 
 .flyout.is-sheet[hidden] {
   scale: 1;
-  translate: 0 var(--space-3);
+  translate: 0 var(--space-30);
 }
 
 @starting-style {
   .flyout.is-sheet.is-open {
     scale: 1;
-    translate: 0 var(--space-3);
+    translate: 0 var(--space-30);
   }
 }
 
 @supports (transition-behavior: allow-discrete) {
   .flyout {
     transition:
-      opacity var(--duration-fast, var(--duration)) var(--ease, ease),
-      scale var(--duration-fast, var(--duration)) var(--ease, ease),
-      translate var(--duration-fast, var(--duration)) var(--ease, ease),
-      display var(--duration-fast, var(--duration)) allow-discrete;
+      opacity var(--duration-fast) var(--ease),
+      scale var(--duration-fast) var(--ease),
+      translate var(--duration-fast) var(--ease),
+      display var(--duration-fast) allow-discrete;
   }
 }
 
@@ -2255,7 +2523,7 @@ dialog.drawer nav {
 
 .flyout > :where(section, footer) {
   min-inline-size: 0;
-  padding: var(--space-2);
+  padding: var(--space-20);
 }
 
 .flyout > section > :where(h1, h2, h3, h4, h5, h6) {
@@ -2267,8 +2535,8 @@ dialog.drawer nav {
 
 .flyout > section > ul {
   display: grid;
-  gap: var(--space-1);
-  margin: var(--space-1) 0 0;
+  gap: var(--space-10);
+  margin: var(--space-10) 0 0;
   padding: 0;
   list-style: none;
 }
@@ -2277,91 +2545,133 @@ dialog.drawer nav {
   margin: 0;
 }
 
-/* Item contract: a button, link, or menuitem placed directly in the flyout
-   or directly in any of its <li> (bare list, or grouped section > ul > li).
-   menu.js mirrors this contract in MENU_ITEM_SELECTOR — keep them in sync.
-   :where(li) keeps specificity at a single class (0,1,0) so consumer
-   overrides behave the same as a plain .flyout > rule. */
-:is(.flyout, .flyout :where(li)) > :where(button, a, [role="menuitem"]) {
+/* Vertical dividers — .menu-separator (menu.css) is the canonical way to
+   separate menu items. Flyout panels that are not menus use auto grid gap
+   declared on .flyout itself. */
+
+/*
+ * Menu — action list primitive consumed by flyout and context-menu.
+ *
+ * Strict anatomy: .menu > li > .menu-item. Separators and section labels
+ * sit directly under .menu as siblings of <li>.
+ *
+ * Public hooks:
+ * --menu-item-icon-size
+ */
+
+.menu {
+  display: grid;
+  gap: var(--space-10);
+  margin: 0;
+  padding: var(--space-10);
+  list-style: none;
+}
+
+.menu > li {
+  margin: 0;
+}
+
+.menu-item {
+  --menu-item-icon-size: 1.25em;
+
   display: flex;
   align-items: center;
-  justify-content: flex-start;
-  gap: var(--space-2);
+  gap: var(--space-20);
   inline-size: 100%;
-  min-block-size: var(--control-size);
-  padding-inline: var(--space-2);
+  min-block-size: var(--menu-item-size, var(--control-size));
+  padding-inline: var(--space-20);
   border: 0;
   border-radius: var(--radius-sm);
-  background: none;
+  background: transparent;
   color: var(--text);
   font: inherit;
-  font-weight: var(--font-weight);
-  text-decoration: none;
   text-align: start;
+  text-decoration: none;
   white-space: nowrap;
   cursor: pointer;
 }
 
-:is(.flyout.is-sheet, .flyout.is-sheet :where(li)) > :where(button, a, [role="menuitem"]) {
-  min-block-size: var(--control-size-lg);
+.menu-item-icon {
+  display: grid;
+  flex: 0 0 var(--menu-item-icon-size);
+  inline-size: var(--menu-item-icon-size);
+  place-items: center;
+}
+
+.menu-item-text {
+  flex: 1;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
-:is(.flyout, .flyout :where(li)) > :where(button, a, [role="menuitem"]):focus-visible {
+.menu-item-end {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-10);
+  margin-inline-start: auto;
+  color: var(--text-muted);
+}
+
+/* Checkable menu items are one command with one accessible state. Their
+   indicator is generated so authors do not add a second interactive input. */
+.menu-item:is([role="menuitemcheckbox"], [role="menuitemradio"])::before {
+  display: grid;
+  flex: 0 0 var(--menu-item-icon-size);
+  inline-size: var(--menu-item-icon-size);
+  place-items: center;
+}
+
+.menu-item[role="menuitemcheckbox"]::before {
+  content: "";
+}
+
+.menu-item[role="menuitemcheckbox"][aria-checked="true"]::before {
+  content: "✓";
+}
+
+.menu-item[role="menuitemcheckbox"][aria-checked="mixed"]::before {
+  content: "−";
+}
+
+.menu-item[role="menuitemradio"]::before {
+  content: "○";
+}
+
+.menu-item[role="menuitemradio"][aria-checked="true"]::before {
+  content: "●";
+}
+
+.menu-item:focus-visible {
   background: var(--surface-subtle);
-  outline: var(--focus-outline);
-  outline-offset: var(--focus-outline-offset);
 }
 
-:is(.flyout, .flyout :where(li))
-  > :where(button, a, [role="menuitem"]):is(:disabled, [aria-disabled="true"]) {
-  cursor: not-allowed;
-  opacity: var(--disabled-opacity);
+.menu-item:hover:not(:where(:disabled, [aria-disabled="true"])) {
+  background: var(--surface-subtle);
 }
 
-:is(.flyout, .flyout :where(li)) > :where(a, [role="menuitem"])[aria-disabled="true"] {
-  pointer-events: none;
+.menu-item:is(:disabled, [aria-disabled="true"]) {
+  cursor: not-allowed;
+  opacity: var(--disabled-opacity);
 }
 
-@media (hover: hover) {
-  :is(.flyout, .flyout :where(li))
-    > :where(button, a, [role="menuitem"]):hover:not(
-      :where(:focus-visible, :disabled, [aria-disabled="true"])
-    ) {
-    background: var(--surface-subtle);
-    outline: none;
-  }
+.menu-label {
+  padding: var(--space-20);
+  color: var(--text-muted);
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-strong);
 }
 
-.flyout > hr,
-.flyout > li > hr {
-  inline-size: 100%;
+.menu-separator {
   margin: 0;
-  margin-block: var(--space-1);
   border: 0;
   border-block-start: var(--border-width) solid var(--border);
 }
 
 @media (forced-colors: active) {
-  .flyout {
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-    box-shadow: none;
-  }
-
-  :is(.flyout, .flyout :where(li)) > :where(button, a, [role="menuitem"]):focus-visible {
-    background: Canvas;
-    color: CanvasText;
-  }
-
-  @media (hover: hover) {
-    :is(.flyout, .flyout :where(li))
-      > :where(button, a, [role="menuitem"]):hover:not(:where(:disabled, [aria-disabled="true"])) {
-      outline: var(--border-width) solid ButtonText;
-      outline-offset: -1px;
-      background: Canvas;
-      color: CanvasText;
-    }
+  .menu-item:focus-visible {
+    outline: var(--border-width) solid ButtonText;
+    outline-offset: -1px;
   }
 }
 
@@ -2371,6 +2681,15 @@ dialog.drawer nav {
  * Position, placement, and arrow position are managed by JavaScript
  * via position: fixed, left, top, data-placement, and --arrow-x.
  * Visibility is managed with hidden; CSS owns entry and exit animation.
+ *
+ * Public hooks:
+ * --tooltip-bg
+ * --tooltip-fg
+ * --tooltip-arrow-size
+ *
+ * Internal:
+ * --arrow-x (arrow position, written by floating.js)
+ * --arrow-y (arrow position, written by floating.js)
  */
 .tooltip {
   --tooltip-bg: var(--surface-solid);
@@ -2392,8 +2711,8 @@ dialog.drawer nav {
   opacity: 1;
   scale: 1;
   transition:
-    opacity var(--duration-fast, var(--duration)) var(--ease, ease),
-    scale var(--duration-fast, var(--duration)) var(--ease, ease);
+    opacity var(--duration-fast) var(--ease),
+    scale var(--duration-fast) var(--ease);
 }
 
 .tooltip[hidden] {
@@ -2412,9 +2731,9 @@ dialog.drawer nav {
 @supports (transition-behavior: allow-discrete) {
   .tooltip {
     transition:
-      opacity var(--duration-fast, var(--duration)) var(--ease, ease),
-      scale var(--duration-fast, var(--duration)) var(--ease, ease),
-      display var(--duration-fast, var(--duration)) allow-discrete;
+      opacity var(--duration-fast) var(--ease),
+      scale var(--duration-fast) var(--ease),
+      display var(--duration-fast) allow-discrete;
   }
 }
 
@@ -2464,8 +2783,6 @@ dialog.drawer nav {
   .tooltip {
     --tooltip-bg: Canvas;
     --tooltip-fg: CanvasText;
-
-    border: var(--border-width) solid ButtonText;
   }
 
   .tooltip::before {
@@ -2481,9 +2798,14 @@ dialog.drawer nav {
  * Keeps the clickable summary affordance aligned and usable without JavaScript
  * or demo styles. Decorative palettes and custom markers belong outside the
  * base component.
+ *
+ * Public hooks:
+ * --accordion-radius
+ * --accordion-marker-color
  */
 .accordion {
   --accordion-radius: var(--radius);
+  --accordion-marker-color: var(--text-muted);
 
   border: var(--border-width) solid var(--border);
   border-radius: var(--accordion-radius);
@@ -2497,14 +2819,18 @@ dialog.drawer nav {
 .accordion summary {
   display: flex;
   align-items: center;
-  gap: var(--space-3);
+  gap: var(--space-30);
   cursor: pointer;
   list-style: none;
-  padding: var(--space-4);
+  padding: var(--space-40);
   color: var(--text);
   font-weight: var(--font-weight-bold);
 }
 
+.accordion summary:hover {
+  color: var(--primary);
+}
+
 .accordion summary::-webkit-details-marker {
   display: none;
 }
@@ -2515,15 +2841,9 @@ dialog.drawer nav {
   margin-inline-start: auto;
   inline-size: 1rem;
   block-size: 1rem;
-  background-color: var(--text-muted);
-  -webkit-mask-image: var(--icon-chevron-mask);
-  mask-image: var(--icon-chevron-mask);
-  -webkit-mask-repeat: no-repeat;
-  mask-repeat: no-repeat;
-  -webkit-mask-size: contain;
-  mask-size: contain;
-  -webkit-mask-position: center;
-  mask-position: center;
+  background-color: var(--accordion-marker-color);
+  -webkit-mask: var(--icon-chevron) center / contain no-repeat;
+  mask: var(--icon-chevron) center / contain no-repeat;
   transition: transform var(--duration);
 }
 
@@ -2532,14 +2852,14 @@ dialog.drawer nav {
 }
 
 .accordion details > summary + * {
-  padding-block: 0 var(--space-4);
-  padding-inline: var(--space-4);
+  padding-block: 0 var(--space-40);
+  padding-inline: var(--space-40);
   color: var(--text-muted);
   margin-block: 0;
 }
 
 .accordion details[open] > summary + * {
-  padding-block-start: var(--space-1);
+  padding-block-start: var(--space-10);
 }
 
 .accordion details > summary + * > :first-child {
@@ -2549,27 +2869,12 @@ dialog.drawer nav {
 .accordion details > summary + ul,
 .accordion details > summary + ol {
   margin: 0;
-  padding-inline-start: 2rem;
-}
-
-@media (forced-colors: active) {
-  .accordion {
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-  }
-
-  .accordion > details + details {
-    border-block-start-color: ButtonText;
-  }
-
-  .accordion summary {
-    color: CanvasText;
-  }
+  padding-inline-start: 2rem;
+}
 
-  .accordion summary::after {
-    background-color: ButtonText;
-    forced-color-adjust: none;
+@media (forced-colors: active) {
+  .accordion {
+    --accordion-marker-color: CanvasText;
   }
 }
 
@@ -2580,18 +2885,17 @@ dialog.drawer nav {
  *
  * Uses currentColor so it adapts to buttons, alerts, badges, and text. The
  * [aria-busy] overlay composition lives in components/busy.css.
+ *
+ * Public hooks:
+ * --spinner-size
+ * --spinner-width
+ * --spinner-track
+ * --spinner-value
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.spinner) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .spinner {
@@ -2641,6 +2945,13 @@ dialog.drawer nav {
  *
  * Shows approximate loading structure without implying real content hierarchy.
  * Geometry, animation, and color stay theme-aware.
+ *
+ * Public hooks:
+ * --skeleton-size
+ * --skeleton-width
+ * --skeleton-radius
+ * --skeleton-track
+ * --skeleton-highlight
  */
 .skeleton {
   --skeleton-size: 1rem;
@@ -2710,6 +3021,12 @@ dialog.drawer nav {
  * A non-button element with aria-busy="true" and a direct last-child .spinner
  * shows that spinner as a centered overlay over a faded surface. Buttons keep
  * their spinners inline (e.g. .btn[aria-busy] > .spinner stays inline-flex).
+ *
+ * Public hooks:
+ * --busy-overlay-bg
+ *
+ * Internal:
+ * --spinner-size (overlay copy of the shared spinner hook)
  */
 [aria-busy] > .spinner:last-child {
   display: none;
@@ -2755,26 +3072,21 @@ dialog.drawer nav {
  *
  * Consumes the shared --intent/--primary for the value bar and --bar-height
  * for thickness. Indeterminate state animates a shimmer using --duration-shimmer.
+ *
+ * Public hooks:
+ * --progress-track
+ * --progress-value
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.progress) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .progress {
   --progress-track: var(--surface-subtle);
   --progress-value: var(--intent, var(--primary));
-}
 
-.progress {
   appearance: none;
   -webkit-appearance: none;
   display: block;
@@ -2853,27 +3165,14 @@ dialog.drawer nav {
 }
 
 @media (forced-colors: active) {
-  .progress {
-    border: var(--border-width) solid ButtonText;
-    background: Canvas;
-  }
-
-  .progress::-webkit-progress-bar {
-    background: Canvas;
-  }
-
-  .progress::-webkit-progress-value {
+  .progress::-webkit-progress-value,
+  .progress:indeterminate::-webkit-progress-value {
     background: Highlight;
-    forced-color-adjust: none;
   }
 
-  .progress::-moz-progress-bar {
+  .progress::-moz-progress-bar,
+  .progress:indeterminate::-moz-progress-bar {
     background: Highlight;
-    forced-color-adjust: none;
-  }
-
-  .progress:indeterminate {
-    background: Canvas;
   }
 }
 
@@ -2892,19 +3191,17 @@ dialog.drawer nav {
  * CSS API:            .status-bar
  * JS target contract:  [data-status][role="status"]
  * Normally combined, but they describe separate concerns.
+ *
+ * Internal:
+ * --status-bg
+ * --status-fg
  */
 
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.status-bar) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .status-bar {
@@ -2912,22 +3209,22 @@ dialog.drawer nav {
   --status-fg: var(--intent-fg, var(--surface));
 
   position: fixed;
-  inset-block-end: var(--space-4);
-  inset-inline: var(--space-4);
-  z-index: var(--z-status, 60);
+  inset-block-end: var(--space-40);
+  inset-inline: var(--space-40);
+  z-index: var(--z-status);
 
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: var(--space-2);
+  gap: var(--space-20);
 
   inline-size: fit-content;
-  max-inline-size: min(calc(100vw - var(--space-6)), 32rem);
+  max-inline-size: min(calc(var(--viewport-inline) - var(--space-60)), 32rem);
   margin-inline: auto;
   overflow-wrap: anywhere;
 
-  padding-block: var(--space-2);
-  padding-inline: var(--space-3);
+  padding-block: var(--space-20);
+  padding-inline: var(--space-30);
 
   border-radius: var(--radius-full);
   background: var(--status-bg);
@@ -2940,25 +3237,18 @@ dialog.drawer nav {
   pointer-events: none;
 
   transition:
-    opacity var(--duration-slow) var(--ease, ease),
-    scale var(--duration-slow) var(--ease, ease),
-    translate var(--duration-slow) var(--ease, ease);
+    opacity var(--duration-slow) var(--ease),
+    scale var(--duration-slow) var(--ease),
+    translate var(--duration-slow) var(--ease);
 }
 
 .status-bar:empty {
   opacity: 0;
   scale: 0.96;
-  translate: 0 var(--space-2);
+  translate: 0 var(--space-20);
   pointer-events: none;
 }
 
-@media (forced-colors: active) {
-  .status-bar {
-    border: var(--border-width) solid ButtonText;
-    box-shadow: none;
-  }
-}
-
 
 /* Display */
 /*
@@ -2967,18 +3257,26 @@ dialog.drawer nav {
  * The visual box stays the same across semantic elements. Grouping and status
  * dots (an empty .badge child) compose around the avatar without changing its
  * meaning.
+ *
+ * Public hooks:
+ * --avatar-size
+ * --avatar-radius
+ * --avatar-font-size
+ * --avatar-stack-size
+ * --avatar-stack-font-size
+ * --avatar-stack-overlap
+ * --avatar-stack-ring
+ *
+ * Internal:
+ * --avatar-bg
+ * --avatar-fg
+ * --avatar-status-translate-x
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.avatar) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .avatar {
@@ -3070,10 +3368,8 @@ button.avatar {
   transition: opacity var(--duration);
 }
 
-@media (hover: hover) {
-  :where(a.avatar, button.avatar):not(:where(:disabled, [aria-disabled="true"])):hover::after {
-    opacity: 1;
-  }
+:where(a.avatar, button.avatar):not(:where(:disabled, [aria-disabled="true"])):hover::after {
+  opacity: 1;
 }
 
 :where(a.avatar, button.avatar):not(:where(:disabled, [aria-disabled="true"])):active {
@@ -3166,6 +3462,8 @@ a.avatar[aria-disabled="true"] {
  *
  * Use .key outside prose. Plain kbd inside .prose gets the same visual
  * treatment from prose.css so authored content stays convenient.
+ *
+ * Visual twin of .prose kbd (prose.css) — keep the two recipes in sync.
  */
 .key {
   display: inline-flex;
@@ -3197,14 +3495,7 @@ a.avatar[aria-disabled="true"] {
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.overline) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .overline {
@@ -3245,6 +3536,9 @@ a.avatar[aria-disabled="true"] {
  * .navbar is a horizontal bar; .navbar-brand is the brand link; .navbar-nav is
  * the inline link list using .nav-link items. .nav-list is the vertical nav
  * list shared with .drawer, fed by the shared --gap token.
+ *
+ * Internal:
+ * --gap (local value for the shared gap token)
  */
 .navbar {
   display: flex;
@@ -3252,8 +3546,8 @@ a.avatar[aria-disabled="true"] {
   align-items: center;
   justify-content: space-between;
   gap: var(--gap);
-  padding-block: var(--space-3);
-  padding-inline: var(--space-4);
+  padding-block: var(--space-30);
+  padding-inline: var(--space-40);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius-lg);
   background: var(--surface-raised);
@@ -3263,7 +3557,7 @@ a.avatar[aria-disabled="true"] {
 .navbar-brand {
   display: inline-flex;
   align-items: center;
-  gap: var(--space-2);
+  gap: var(--space-20);
   color: var(--text);
   font-weight: var(--font-weight-bold);
   text-decoration: none;
@@ -3277,7 +3571,7 @@ a.avatar[aria-disabled="true"] {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--space-1);
+  gap: var(--space-10);
   margin: 0;
   padding: 0;
   list-style: none;
@@ -3287,7 +3581,7 @@ a.avatar[aria-disabled="true"] {
   display: inline-flex;
   align-items: center;
   min-block-size: var(--control-size-sm);
-  padding-inline: var(--space-2);
+  padding-inline: var(--space-20);
   border-radius: var(--radius);
   color: var(--text-muted);
   font-weight: var(--font-weight-medium);
@@ -3299,21 +3593,19 @@ a.avatar[aria-disabled="true"] {
   color: var(--text);
 }
 
-@media (hover: hover) {
-  .nav-link:hover {
-    background: var(--surface-subtle);
-    color: var(--text);
-  }
+.nav-link:hover {
+  background: var(--surface-subtle);
+  color: var(--text);
 }
 
 /* Nav list — a vertical navigation list. Used by .drawer for stacked links. */
 .nav-list {
   display: grid;
+  --gap: var(--space-20);
   gap: var(--gap);
   margin: 0;
   padding: 0;
   list-style: none;
-  --gap: var(--space-2);
 }
 
 .nav-list > li {
@@ -3328,13 +3620,11 @@ a.avatar[aria-disabled="true"] {
     forced-color-adjust: none;
   }
 
-  @media (hover: hover) {
-    .nav-link:hover:not(:where([aria-current]:not([aria-current="false"]))) {
-      outline: var(--border-width) solid ButtonText;
-      outline-offset: 2px;
-      background: Canvas;
-      color: CanvasText;
-    }
+  .nav-link:hover:not(:where([aria-current]:not([aria-current="false"]))) {
+    outline: var(--border-width) solid ButtonText;
+    outline-offset: 2px;
+    background: Canvas;
+    color: CanvasText;
   }
 }
 
@@ -3348,7 +3638,7 @@ a.avatar[aria-disabled="true"] {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--space-1);
+  gap: var(--space-10);
   margin: 0;
   padding: 0;
   color: var(--text-subtle);
@@ -3359,7 +3649,7 @@ a.avatar[aria-disabled="true"] {
 .breadcrumb li {
   display: inline-flex;
   align-items: center;
-  gap: var(--space-1);
+  gap: var(--space-10);
 }
 
 .breadcrumb li + li::before {
@@ -3372,25 +3662,17 @@ a.avatar[aria-disabled="true"] {
   text-decoration: none;
 }
 
-@media (hover: hover) {
-  .breadcrumb
-    li:not(:where([aria-current]:not([aria-current="false"])))
-    > a:hover:not(:where([aria-current]:not([aria-current="false"]))) {
-    color: var(--text);
-    text-decoration: underline;
-  }
+.breadcrumb a:not([aria-current]):hover,
+.breadcrumb a[aria-current="false"]:hover {
+  color: var(--text);
+  text-decoration: underline;
 }
 
 .breadcrumb a:focus-visible {
   border-radius: var(--radius-sm);
 }
 
-.breadcrumb a:where([aria-current]:not([aria-current="false"])) {
-  color: var(--text);
-  font-weight: var(--font-weight-medium);
-}
-
-.breadcrumb li:where([aria-current]:not([aria-current="false"])) > :where(a, span) {
+.breadcrumb :where(a, span):where([aria-current]:not([aria-current="false"])) {
   color: var(--text);
   font-weight: var(--font-weight-medium);
 }
@@ -3409,7 +3691,7 @@ a.avatar[aria-disabled="true"] {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: var(--space-1);
+  gap: var(--space-10);
   margin: 0;
   padding: 0;
   list-style: none;
@@ -3432,24 +3714,20 @@ a.avatar[aria-disabled="true"] {
  * JavaScript owns roving tabindex, aria-selected, panel visibility,
  * and arrow-key navigation. CSS owns the tab strip appearance and
  * active indicator.
+ *
+ * Public hooks:
+ * --tab-gap
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.tab) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .tabs {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--space-1);
+  gap: var(--space-10);
   margin: 0;
   padding: 0;
   border-block-end: var(--border-width) solid var(--border);
@@ -3467,8 +3745,9 @@ a.avatar[aria-disabled="true"] {
 .tab {
   display: inline-flex;
   align-items: center;
+  gap: var(--tab-gap, 0.375em);
   min-block-size: var(--control-size);
-  padding-inline: var(--space-3);
+  padding-inline: var(--space-30);
   border: 0;
   border-block-end: 2px solid transparent;
   border-radius: 0;
@@ -3484,7 +3763,7 @@ a.avatar[aria-disabled="true"] {
   justify-content: flex-start;
   border-block-end: 0;
   border-inline-end: 2px solid transparent;
-  padding-inline-end: var(--space-4);
+  padding-inline-end: var(--space-40);
 }
 
 .tab:is(:disabled, [aria-disabled="true"]) {
@@ -3492,10 +3771,8 @@ a.avatar[aria-disabled="true"] {
   opacity: var(--disabled-opacity);
 }
 
-@media (hover: hover) {
-  .tab:hover:not(:where(:disabled, [aria-disabled="true"])) {
-    color: var(--text);
-  }
+.tab:hover:not(:where(:disabled, [aria-disabled="true"])) {
+  color: var(--text);
 }
 
 .tab:focus-visible {
@@ -3505,52 +3782,28 @@ a.avatar[aria-disabled="true"] {
   border-radius: var(--radius-sm) var(--radius-sm) 0 0;
 }
 
-.tab[aria-selected="true"],
-.tab[aria-current]:not([aria-current="false"]),
-.tab[aria-pressed="true"] {
-  border-block-end-color: var(--intent, var(--primary));
-  color: var(--intent, var(--primary));
+.tab[aria-selected="true"] {
+  border-block-end-color: var(--intent, var(--state-selected));
+  color: var(--intent, var(--state-selected));
 }
 
-.tabs[aria-orientation="vertical"] .tab[aria-selected="true"],
-.tabs[aria-orientation="vertical"] .tab[aria-current]:not([aria-current="false"]),
-.tabs[aria-orientation="vertical"] .tab[aria-pressed="true"] {
+.tabs[aria-orientation="vertical"] .tab[aria-selected="true"] {
   border-block-end-color: transparent;
-  border-inline-end-color: var(--intent, var(--primary));
+  border-inline-end-color: var(--intent, var(--state-selected));
 }
 
 @media (forced-colors: active) {
-  .tabs {
-    border-block-end-color: ButtonText;
-  }
-
-  .tabs[aria-orientation="vertical"] {
-    border-block-end-color: transparent;
-    border-inline-end-color: ButtonText;
-  }
-
-  .tab {
-    color: ButtonText;
-  }
-
-  @media (hover: hover) {
-    .tab:hover:not(:where(:disabled, [aria-disabled="true"])) {
-      color: ButtonText;
-      text-decoration: underline;
-      text-underline-offset: 0.18em;
-    }
+  .tab:hover:not(:where(:disabled, [aria-disabled="true"])) {
+    text-decoration: underline;
+    text-underline-offset: 0.18em;
   }
 
-  .tab[aria-selected="true"],
-  .tab[aria-current]:not([aria-current="false"]),
-  .tab[aria-pressed="true"] {
+  .tab[aria-selected="true"] {
     border-block-end-color: Highlight;
     color: Highlight;
   }
 
-  .tabs[aria-orientation="vertical"] .tab[aria-selected="true"],
-  .tabs[aria-orientation="vertical"] .tab[aria-current]:not([aria-current="false"]),
-  .tabs[aria-orientation="vertical"] .tab[aria-pressed="true"] {
+  .tabs[aria-orientation="vertical"] .tab[aria-selected="true"] {
     border-block-end-color: transparent;
     border-inline-end-color: Highlight;
   }
@@ -3591,6 +3844,10 @@ a.avatar[aria-disabled="true"] {
  *
  * .table-wrap provides the scroll container and outer chrome; .table owns row
  * and cell rules. Tokens are sourced from the shared scale.
+ *
+ * Public hooks:
+ * --table-min
+ * --table-cell-pad
  */
 .table-wrap {
   inline-size: 100%;
@@ -3604,7 +3861,7 @@ a.avatar[aria-disabled="true"] {
 
 .table {
   --table-min: 100%;
-  --table-cell-pad: var(--space-3);
+  --table-cell-pad: var(--space-30);
 
   inline-size: max(var(--table-min), 100%);
   border-collapse: collapse;
@@ -3640,10 +3897,8 @@ a.avatar[aria-disabled="true"] {
   background: var(--surface-subtle);
 }
 
-@media (hover: hover) {
-  .table tbody tr:hover {
-    background-color: var(--hover-overlay);
-  }
+.table tbody tr:hover {
+  background-color: var(--hover-overlay);
 }
 
 .table > tr:last-child > *,
@@ -3657,18 +3912,6 @@ a.avatar[aria-disabled="true"] {
  * Maps the three standard meter zones (optimum / suboptimum / even-less-good)
  * to the shared success / warning / danger intent colors.
  */
-/* Intent boundary — inherited intents do not tint this component.
-   Local intent classes still win because :where() has zero specificity. */
-:where(.meter) {
-  /* @sync intent-boundary */
-  --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
-}
 
 .meter {
   appearance: none;
@@ -3714,29 +3957,18 @@ a.avatar[aria-disabled="true"] {
 }
 
 @media (forced-colors: active) {
-  .meter {
-    border: var(--border-width) solid ButtonText;
-    background: Canvas;
-  }
-
-  .meter::-webkit-meter-bar {
-    border: 0;
-    background: Canvas;
-  }
-
   .meter::-webkit-meter-optimum-value,
   .meter::-webkit-meter-suboptimum-value,
   .meter::-webkit-meter-even-less-good-value,
   .meter::-moz-meter-bar {
     background: Highlight;
-    forced-color-adjust: none;
   }
 }
 
-/* Forms — import order matters: switch.css must follow choice.css so its
-   :not([role="switch"]) exclusion in choice.css still applies.
-   validation.css is part of the default forms bundle, but custom builds may
-   omit it when validation styling is app-owned. */
+/* Forms — import order matters: switch.css follows choice.css so its rules
+   land after the shared choice recipe. validation.css is part of the default
+   forms bundle, but custom builds may omit it when validation styling is
+   app-owned. */
 /*
  * Form layout and supporting text.
  *
@@ -3745,23 +3977,26 @@ a.avatar[aria-disabled="true"] {
  *
  * Public API: .field, .field-label, .field-help, .field-error, .field-group,
  * .required-mark.
+ *
+ * Public hooks:
+ * --fieldset-legend-padding-inline
  */
 .field {
   display: grid;
-  gap: var(--space-1);
+  gap: var(--space-10);
   color: var(--text);
 }
 
 .field-group {
   min-inline-size: 0;
   margin: 0;
-  padding: var(--space-3);
+  padding: var(--space-30);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
 }
 
 .field-group + .field-group {
-  margin-block-start: var(--space-4);
+  margin-block-start: var(--space-40);
 }
 
 .field-label,
@@ -3772,7 +4007,7 @@ a.avatar[aria-disabled="true"] {
 
 .field-group > legend {
   padding-block: 0;
-  padding-inline: var(--fieldset-legend-padding-inline, var(--space-1));
+  padding-inline: var(--fieldset-legend-padding-inline, var(--space-10));
   font-size: var(--font-size-xs);
 }
 
@@ -3811,6 +4046,12 @@ a.avatar[aria-disabled="true"] {
  * --control-border-block-end-color/-width are unset extension points, mirroring
  * --btn-border-block-end-* (button.css), for themes that give text controls an
  * underline-style lower edge instead of a uniform border.
+ *
+ * Public hooks:
+ * --control-border
+ * --control-bg
+ * --control-fg
+ * --control-cursor
  */
 .input,
 .textarea,
@@ -3818,14 +4059,12 @@ a.avatar[aria-disabled="true"] {
   --control-border: var(--border);
   --control-bg: var(--surface);
   --control-fg: var(--text);
-  --control-ring: none;
   --control-cursor: auto;
-  --control-opacity: 1;
 
   appearance: none;
   inline-size: 100%;
   min-block-size: var(--control-size);
-  padding-inline: var(--space-3);
+  padding-inline: var(--space-30);
   border: var(--border-width) solid var(--form-invalid-border, var(--control-border));
   border-block-end-color: var(
     --form-invalid-border,
@@ -3836,9 +4075,7 @@ a.avatar[aria-disabled="true"] {
   background: var(--control-bg);
   color: var(--control-fg);
   font-size: var(--control-font-size);
-  box-shadow: var(--control-ring);
   cursor: var(--control-cursor);
-  opacity: var(--control-opacity);
   outline: none;
   transition:
     border-color var(--duration),
@@ -3849,26 +4086,24 @@ a.avatar[aria-disabled="true"] {
 
 .textarea {
   min-block-size: 6rem;
-  padding-block: var(--space-2);
+  padding-block: var(--space-20);
   resize: vertical;
 }
 
-@media (hover: hover) {
-  .input:hover:not(:disabled),
-  .textarea:hover:not(:disabled) {
-    --control-border: var(--text-subtle);
-  }
+.input:hover:not(:disabled),
+.textarea:hover:not(:disabled) {
+  --control-border: var(--text-subtle);
+}
 
-  .select:hover:not(:disabled) {
-    --control-bg: var(--surface-subtle);
-  }
+.select:hover:not(:disabled) {
+  --control-bg: var(--surface-subtle);
 }
 
 .input:focus-visible,
 .textarea:focus-visible,
 .select:focus-visible {
   --control-border: var(--focus);
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
@@ -3882,10 +4117,9 @@ a.avatar[aria-disabled="true"] {
 .textarea:disabled,
 .select:disabled {
   --control-bg: var(--surface-subtle);
-  --control-fg: var(--text-subtle);
+  --control-fg: var(--state-disabled);
   --control-border: var(--border);
   --control-cursor: not-allowed;
-  --control-opacity: 1;
 }
 
 .input::placeholder,
@@ -3894,40 +4128,58 @@ a.avatar[aria-disabled="true"] {
 }
 
 /*
- * Input Icon — leading decorative icon inside a relative wrapper.
+ * Input Icon — decorative icon inside a relative wrapper, leading or trailing.
  *
- * Icon-library agnostic: selects the wrapper's first child rather than a
- * specific tag, so it works with an <i> webfont icon, an inline <svg>, or a
- * <span>. Sizes with --variant-icon-size (variants.css) so .sm/.lg pick up
- * the same icon scale used elsewhere (alert.css); the input's start padding
- * grows to match so text never runs under the icon.
+ * Icon-library agnostic: detects position by DOM order. First child that is
+ * not .input = leading icon; icon after .input = trailing. The icon keeps a
+ * fixed size; density contexts shrink the control geometry around it, not
+ * the pictogram.
+ *
+ * Public hooks:
+ * --input-icon-size
  */
 .input-icon {
-  --input-icon-size: var(--variant-icon-size, 1.25rem);
+  --input-icon-size: 1.25rem;
 
   display: block;
   position: relative;
 }
 
-.input-icon > :first-child {
+/* Icon — shared by leading and trailing */
+.input-icon > :where(:not(.input)) {
   position: absolute;
   inset-block-start: 50%;
-  inset-inline-start: var(--space-3);
   transform: translateY(-50%);
   font-size: var(--input-icon-size);
   color: var(--text-muted);
   pointer-events: none;
 }
 
+/* Leading: icon is the first child */
+.input-icon > :first-child:where(:not(.input)) {
+  inset-inline-start: var(--space-30);
+}
+
+/* Trailing: input is the first child, icon follows */
+.input-icon > .input:first-child ~ :where(:not(.input)) {
+  inset-inline-end: var(--space-30);
+}
+
 /* font-size only sizes text-metric icons (webfont <i>, <span>). An inline
    <svg> with just a viewBox ignores it, so give it explicit dimensions. */
-.input-icon > svg:first-child {
+.input-icon > svg:where(:not(.input)) {
   inline-size: var(--input-icon-size);
   block-size: var(--input-icon-size);
 }
 
-.input-icon > .input {
-  padding-inline-start: calc(var(--space-3) * 2 + var(--input-icon-size));
+/* Leading: input gets start padding to clear the icon */
+.input-icon > :first-child:where(:not(.input)) ~ .input {
+  padding-inline-start: calc(var(--space-30) * 2 + var(--input-icon-size));
+}
+
+/* Trailing: input is first child and has a sibling → end padding */
+.input-icon > .input:first-child:where(:not(:last-child)) {
+  padding-inline-end: calc(var(--space-30) * 2 + var(--input-icon-size));
 }
 
 /*
@@ -3940,23 +4192,23 @@ a.avatar[aria-disabled="true"] {
  *
  * Switches (input[role="switch"]) are excluded so switch.css owns their
  * geometry and states. switch.css is imported after this file.
+ *
+ * Public hooks:
+ * --choice-control-offset
+ * --choice-border
+ * --choice-bg
+ * --choice-mark
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.choice, .check, .radio) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
-/* A classed .choice is the component surface. Let its nested input consume a
+/* A classed .choice is the component surface. Let its direct input consume a
    local intent without reopening inherited page-level intents. */
-:where(.choice) :where(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
+:where(.choice) > :where(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
   --intent: inherit;
   --intent-fg: inherit;
 }
@@ -3966,7 +4218,7 @@ a.avatar[aria-disabled="true"] {
 
   display: inline-flex;
   align-items: flex-start;
-  gap: var(--space-2);
+  gap: var(--space-20);
   color: var(--text);
   font-size: var(--control-font-size);
   cursor: pointer;
@@ -3989,8 +4241,11 @@ a.avatar[aria-disabled="true"] {
   display: block;
 }
 
-.choice:has(:disabled) {
-  color: var(--text-subtle);
+/* Progressive enhancement: dim the whole row when one of its controls is
+   disabled. Without :has() the native disabled control keeps its own state
+   styling — the row-level dim is lost but the field stays clearly disabled. */
+.choice:has(> :disabled) {
+  color: var(--state-disabled);
   cursor: not-allowed;
 }
 
@@ -4007,8 +4262,7 @@ a.avatar[aria-disabled="true"] {
   place-content: center;
   inline-size: 1.125em;
   block-size: 1.125em;
-  margin-inline: 0;
-  margin-block-end: 0;
+  margin: 0;
   border: var(--border-width) solid var(--form-invalid-border, var(--choice-border));
   background: var(--choice-bg);
   color: var(--choice-mark);
@@ -4049,7 +4303,7 @@ a.avatar[aria-disabled="true"] {
   background: currentColor;
 }
 
-.check:checked,
+.check:is(:checked, :indeterminate),
 .radio:checked {
   --choice-border: var(--intent, var(--primary));
   --choice-bg: var(--intent, var(--primary));
@@ -4060,12 +4314,6 @@ a.avatar[aria-disabled="true"] {
   transform: translateY(-0.06em) rotate(-45deg) scale(1);
 }
 
-.check:indeterminate {
-  --choice-border: var(--intent, var(--primary));
-  --choice-bg: var(--intent, var(--primary));
-  --choice-mark: var(--intent-fg, var(--primary-fg));
-}
-
 .check:indeterminate::before {
   border-inline-start: 0;
   inline-size: 0.6em;
@@ -4078,17 +4326,15 @@ a.avatar[aria-disabled="true"] {
   transform: scale(1);
 }
 
-@media (hover: hover) {
-  .check:hover:not(:checked, :indeterminate, :disabled),
-  .radio:hover:not(:checked, :indeterminate, :disabled) {
-    --choice-border: var(--text-subtle);
-  }
+.check:hover:not(:checked, :indeterminate, :disabled),
+.radio:hover:not(:checked, :indeterminate, :disabled) {
+  --choice-border: var(--text-subtle);
 }
 
 .check:focus-visible,
 .radio:focus-visible {
   --choice-border: var(--focus);
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
@@ -4096,7 +4342,7 @@ a.avatar[aria-disabled="true"] {
 .radio:disabled {
   --choice-bg: var(--surface-subtle);
   --choice-border: var(--border);
-  --choice-mark: var(--text-subtle);
+  --choice-mark: var(--state-disabled);
   cursor: not-allowed;
   opacity: 1;
 }
@@ -4138,20 +4384,21 @@ a.avatar[aria-disabled="true"] {
  * 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.
+ *
+ * Public hooks:
+ * --choice-card-pad
+ * --choice-card-radius
+ * --choice-card-border
+ * --choice-card-bg
+ * --choice-card-check-size
  */
 :where(.choice-card) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .choice-card {
-  --choice-card-pad: var(--variant-space, var(--space-4));
+  --choice-card-pad: var(--density-space, var(--space-40));
   --choice-card-radius: var(--radius);
   --choice-card-border: var(--border);
   --choice-card-bg: var(--surface);
@@ -4191,7 +4438,7 @@ a.avatar[aria-disabled="true"] {
 
 /* Focus ring on the label follows the hidden input's focus. */
 .choice-card:has(:focus-visible) {
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
@@ -4200,10 +4447,8 @@ a.avatar[aria-disabled="true"] {
   cursor: not-allowed;
 }
 
-@media (hover: hover) {
-  .choice-card:hover:not(:has(:disabled)) {
-    --choice-card-border: var(--text-subtle);
-  }
+.choice-card:hover:not(:has(:disabled)) {
+  --choice-card-border: var(--text-subtle);
 }
 
 /* Checked border — shared by radio and checkbox */
@@ -4250,8 +4495,8 @@ a.avatar[aria-disabled="true"] {
 /* Check mark */
 .choice-card::after {
   background: var(--intent-fg, var(--primary-fg));
-  -webkit-mask: var(--icon-check-mask) center / 60% no-repeat;
-  mask: var(--icon-check-mask) center / 60% no-repeat;
+  -webkit-mask: var(--icon-check) center / 60% no-repeat;
+  mask: var(--icon-check) center / 60% no-repeat;
   z-index: 2;
 }
 
@@ -4294,19 +4539,19 @@ a.avatar[aria-disabled="true"] {
  * custom-select.css can be opted out independently. Add .native to a specific
  * select to opt out of the enhancement.
  */
-.select:is(:not([multiple], [size]), :not([multiple])[size="1"]) {
+.select:not([multiple], [size]:not([size="1"])) {
   appearance: none;
-  padding-inline-end: calc(var(--space-3) + var(--space-6));
-  background-image: var(--icon-chevron-image);
-  background-position: center right var(--space-3);
+  padding-inline-end: calc(var(--space-30) + var(--space-60));
+  background-image: var(--icon-chevron);
+  background-position: center right var(--space-30);
   background-size: 1rem auto;
   background-repeat: no-repeat;
 }
 
 /* The chevron sits on the inline-end side; flip it in RTL so it follows
    the padding-inline-end space reserved for it. */
-.select:is(:not([multiple], [size]), :not([multiple])[size="1"]):dir(rtl) {
-  background-position: center left var(--space-3);
+.select:not([multiple], [size]:not([size="1"])):dir(rtl) {
+  background-position: center left var(--space-30);
 }
 
 /* Both forced-colors and prefers-contrast hand the arrow back to the
@@ -4314,10 +4559,10 @@ a.avatar[aria-disabled="true"] {
    simpler than maintaining contrast variants, and native rendering already
    matches whatever contrast mode the user picked. */
 @media (forced-colors: active), (prefers-contrast: more) {
-  .select:is(:not([multiple], [size]), :not([multiple])[size="1"]) {
+  .select:not([multiple], [size]:not([size="1"])) {
     appearance: auto;
     background-image: none;
-    padding-inline-end: var(--space-3);
+    padding-inline-end: var(--space-30);
   }
 }
 
@@ -4330,6 +4575,10 @@ a.avatar[aria-disabled="true"] {
  *
  * No layout or interaction contract may depend on appearance: base-select.
  * Arbitrary menu and popover behavior belongs elsewhere.
+ *
+ * Internal:
+ * --control-border
+ * --control-bg
  */
 @media (forced-colors: none) and (prefers-contrast: no-preference) and (hover: hover) and (
     pointer: fine
@@ -4342,7 +4591,7 @@ a.avatar[aria-disabled="true"] {
       &::picker(select) {
         appearance: base-select;
         max-height: min(24rem, calc(var(--viewport-block) * 0.7));
-        margin-block: var(--space-2);
+        margin-block: var(--space-20);
         padding: 0;
         border: var(--border-width) solid var(--border);
         border-radius: var(--radius);
@@ -4364,8 +4613,8 @@ a.avatar[aria-disabled="true"] {
 
       & option {
         position: relative;
-        padding-block: var(--space-2);
-        padding-inline: var(--space-3);
+        padding-block: var(--space-20);
+        padding-inline: var(--space-30);
         white-space: normal;
         transition-property: color, background-color;
         transition-duration: var(--duration);
@@ -4393,14 +4642,8 @@ a.avatar[aria-disabled="true"] {
           inline-size: 1rem;
           block-size: 1rem;
           background-color: currentColor;
-          -webkit-mask-image: var(--icon-check-mask);
-          mask-image: var(--icon-check-mask);
-          -webkit-mask-repeat: no-repeat;
-          mask-repeat: no-repeat;
-          -webkit-mask-size: contain;
-          mask-size: contain;
-          -webkit-mask-position: center;
-          mask-position: center;
+          -webkit-mask: var(--icon-check) center / contain no-repeat;
+          mask: var(--icon-check) center / contain no-repeat;
         }
       }
 
@@ -4416,9 +4659,9 @@ a.avatar[aria-disabled="true"] {
 }
 
 /*
- * Native-only control polish: file input that mostly defeats custom styling,
- * so the framework stays out of the way and just keeps it readable and
- * theme-aware.
+ * Native-only control polish: the file input and color picker mostly defeat
+ * custom styling, so the framework stays out of the way and just keeps them
+ * readable and theme-aware.
  *
  * Range has its own custom-styled file (range.css) so the focus ring can
  * target the thumb pseudo-element rather than the rectangular CSS box.
@@ -4428,9 +4671,9 @@ a.avatar[aria-disabled="true"] {
 }
 
 .file::file-selector-button {
-  margin-inline-end: var(--space-3);
-  padding-block: var(--space-1);
-  padding-inline: var(--space-2);
+  margin-inline-end: var(--space-30);
+  padding-block: var(--space-10);
+  padding-inline: var(--space-20);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius-sm);
   background: var(--surface-subtle);
@@ -4449,17 +4692,56 @@ a.avatar[aria-disabled="true"] {
   cursor: not-allowed;
 }
 
-@media (hover: hover) {
-  .file:not(:disabled)::file-selector-button:hover {
-    background: var(--border);
-  }
+.file:not(:disabled)::file-selector-button:hover {
+  background: var(--border);
 }
 
 .file:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
+  box-shadow: var(--focus-ring-shadow);
+}
+
+/* Native color picker — keep the browser's dialog and selected-color UI. */
+.color {
+  inline-size: var(--control-size);
+  block-size: var(--control-size);
+  padding: var(--space-10);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  cursor: pointer;
+}
+
+.color::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.color::-webkit-color-swatch {
+  border: 0;
+}
+
+.color::-moz-color-swatch {
+  border: 0;
+}
+
+.color:disabled {
+  cursor: not-allowed;
+  opacity: var(--disabled-opacity);
+}
+
+.color:focus-visible {
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
+@media (forced-colors: active) {
+  .color {
+    border-color: ButtonText;
+    background: ButtonFace;
+    forced-color-adjust: none;
+  }
+}
+
 /*
  * Range slider — custom-styled so the focus ring always targets the
  * user-manipulated surface (the thumb) rather than the CSS box.
@@ -4467,19 +4749,18 @@ a.avatar[aria-disabled="true"] {
  * appearance: none gives us full control over track and thumb; without it,
  * pseudo-element rules for ::-webkit-slider-thumb and ::-moz-range-thumb
  * are not reliably applied across browsers.
+ *
+ * Public hooks:
+ * --range-thumb-size
+ * --range-track-height
+ * --range-thumb-bg
+ * --range-track-bg
  */
 
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.range) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .range {
@@ -4530,7 +4811,7 @@ a.avatar[aria-disabled="true"] {
 }
 
 .range:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
 }
 
 /*
@@ -4551,28 +4832,41 @@ a.avatar[aria-disabled="true"] {
 }
 
 .range:disabled {
-  --range-thumb-bg: var(--text-subtle);
+  --range-thumb-bg: var(--state-disabled);
   cursor: not-allowed;
   opacity: var(--disabled-opacity);
 }
 
+/* Forced colors: map the custom thumb/track to system colors. The focus
+   indicator stays visible through the transparent outline on :focus-visible. */
+@media (forced-colors: active) {
+  .range {
+    --range-thumb-bg: ButtonText;
+    --range-track-bg: Canvas;
+  }
+}
+
 /*
  * Switch controls for checkbox inputs with switch semantics.
  *
  * The switch remains an input control, not a decorative toggle. Checked, hover,
  * focus-visible, and disabled states stay clear.
+ *
+ * Public hooks:
+ * --switch-bg
+ * --switch-border
+ * --switch-knob
+ * --switch-width
+ * --switch-block-size
+ * --switch-knob-margin
+ * --switch-knob-size
+ * --switch-travel
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.switch) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .switch {
@@ -4620,10 +4914,8 @@ a.avatar[aria-disabled="true"] {
     box-shadow var(--duration);
 }
 
-@media (hover: hover) {
-  .switch:hover:not(:disabled) {
-    --switch-border: var(--intent, var(--primary));
-  }
+.switch:hover:not(:disabled) {
+  --switch-border: var(--intent, var(--primary));
 }
 
 .switch:checked {
@@ -4644,14 +4936,14 @@ a.avatar[aria-disabled="true"] {
 
 .switch:focus-visible {
   --switch-border: var(--focus);
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
 .switch:disabled {
   --switch-bg: var(--surface-subtle);
   --switch-border: var(--border);
-  --switch-knob: var(--text-subtle);
+  --switch-knob: var(--state-disabled);
   opacity: 1;
   cursor: not-allowed;
 }
@@ -4688,6 +4980,17 @@ a.avatar[aria-disabled="true"] {
  *
  * Imported by default through forms/index.css. Custom builds may omit this
  * file when an app wants to own validation styling completely.
+ *
+ * State coverage (which states each component ships) is audited in
+ * tests/validation.test.js and summarized in docs/pages/forms/validation.md —
+ * not kept as a source comment that can drift from the implementation.
+ *
+ * Public hooks:
+ * --form-invalid-border
+ *
+ * Internal:
+ * --choice-bg
+ * --switch-bg
  */
 
 .field.danger {
@@ -4710,17 +5013,33 @@ a.avatar[aria-disabled="true"] {
   --form-invalid-border: var(--danger);
 }
 
-/* Override checked/indeterminate background so both border and fill signal
-   danger instead of showing a red border around a primary-colored control. */
-.check[aria-invalid="true"]:is(:checked, :indeterminate),
-.radio[aria-invalid="true"]:checked {
+/* Override checked/indeterminate fill so both border and fill signal danger
+   instead of a red border around a primary-colored control. All three
+   invalid routes must converge: aria-invalid, was-validated :invalid, and
+   :user-invalid. */
+.check:is(:checked, :indeterminate)[aria-invalid="true"],
+.needs-validation.was-validated .check:is(:checked, :indeterminate):invalid,
+.radio:checked[aria-invalid="true"],
+.needs-validation.was-validated .radio:checked:invalid {
   --choice-bg: var(--danger);
 }
 
-.switch[aria-invalid="true"]:checked {
+.switch:checked[aria-invalid="true"],
+.needs-validation.was-validated .switch:checked:invalid {
   --switch-bg: var(--danger);
 }
 
+@supports selector(:user-invalid) {
+  .needs-validation .check:is(:checked, :indeterminate):user-invalid,
+  .needs-validation .radio:checked:user-invalid {
+    --choice-bg: var(--danger);
+  }
+
+  .needs-validation .switch:checked:user-invalid {
+    --switch-bg: var(--danger);
+  }
+}
+
 /* Choice cards hide their native input, so invalid state must surface on the
    card itself. Sets the same --form-invalid-border hook the card's border
    consumes. */
@@ -4753,13 +5072,24 @@ a.avatar[aria-disabled="true"] {
  * A flex cluster of buttons/actions that closes a form. The sticky variant
  * docks to the viewport bottom with a translucent blur where supported; at
  * rest it stays visually neutral so it does not double as a separator.
+ *
+ * Public hooks:
+ * --form-actions-align
+ * --form-actions-justify
+ * --form-actions-margin-block-start
+ *
+ * Internal:
+ * --form-actions-sticky-block-offset (owned by .form-actions.sticky)
+ * --form-actions-sticky-inline-offset (owned by .form-actions.sticky)
+ * --form-actions-sticky-padding (owned by .form-actions.sticky)
  */
 .form-actions {
   display: flex;
   flex-wrap: wrap;
   gap: var(--gap);
-  align-items: center;
-  margin-block-start: var(--form-actions-margin-block-start, var(--space-5));
+  align-items: var(--form-actions-align, center);
+  justify-content: var(--form-actions-justify, flex-start);
+  margin-block-start: var(--form-actions-margin-block-start, var(--space-50));
 }
 
 /* Opt-in sticky variant. When the bar is not stuck (at rest) the translucent
@@ -4773,7 +5103,7 @@ a.avatar[aria-disabled="true"] {
   isolation: isolate;
 
   margin-inline: calc(var(--form-actions-sticky-inline-offset, 0px) * -1);
-  padding: var(--form-actions-sticky-padding, var(--space-3));
+  padding: var(--form-actions-sticky-padding, var(--space-30));
 
   border-block-start: var(--border-width) solid var(--border);
   background: var(--surface);
@@ -4823,7 +5153,7 @@ a.avatar[aria-disabled="true"] {
   min-inline-size: 0;
 }
 
-.nowrap {
+.text-nowrap {
   white-space: nowrap;
 }
 
@@ -4918,15 +5248,13 @@ a.avatar[aria-disabled="true"] {
   text-decoration: none;
 }
 
-@media (hover: hover) {
-  .link-muted:hover {
-    color: var(--text);
-  }
+.link-muted:hover {
+  color: var(--text);
 }
 
 /* Spacing step helpers — semantic scale (sm / default / lg).
    Names map to logical properties for writing-direction safety. The default
-   step uses --space-4, which matches the framework's built-in padding on
+   step uses --space-40, which matches the framework's built-in padding on
    cards, dialogs, and form-actions. */
 
 /* Gap */
@@ -4936,22 +5264,22 @@ a.avatar[aria-disabled="true"] {
 
 /* Padding — block (vertical) */
 .py {
-  padding-block: var(--variant-space);
+  padding-block: var(--density-space);
 }
 
 /* Padding — inline (horizontal) */
 .px {
-  padding-inline: var(--variant-space);
+  padding-inline: var(--density-space);
 }
 
 /* Margin — block-start */
 .mbs {
-  margin-block-start: var(--variant-space);
+  margin-block-start: var(--density-space);
 }
 
 /* Margin — block-end */
 .mbe {
-  margin-block-end: var(--variant-space);
+  margin-block-end: var(--density-space);
 }
 
 /* Joined controls are a component, but must load after the controls it groups. */
@@ -4964,6 +5292,18 @@ a.avatar[aria-disabled="true"] {
  * Cascade note: .join writes border-radius longhands on its direct children.
  * Keep this file loaded after control/component styles so those corners win at
  * equal specificity.
+ *
+ * Public hooks:
+ * --join-radius
+ *
+ * Internal:
+ * --join-ss
+ * --join-se
+ * --join-es
+ * --join-ee
+ * --control-border
+ * --control-bg
+ * --control-fg
  */
 .join {
   --join-radius: var(--radius);
@@ -4991,7 +5331,7 @@ a.avatar[aria-disabled="true"] {
   display: inline-flex;
   justify-content: center;
   min-block-size: var(--control-size);
-  padding-inline: var(--space-3);
+  padding-inline: var(--space-30);
   border: var(--border-width) solid var(--control-border);
   border-radius: var(--radius);
   background: var(--control-bg);
@@ -5052,7 +5392,7 @@ a.avatar[aria-disabled="true"] {
    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: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
@@ -5061,9 +5401,14 @@ a.avatar[aria-disabled="true"] {
   box-shadow: none;
 }
 
-/* Focus baseline — loaded after components so its legacy fallback also covers
-   controls that reset their native outline. Modern browsers hide it for focus
-   that is not keyboard-relevant; components layer local state on top. */
+/* Focus baseline — a visible outline is the guaranteed focus affordance. The
+   :focus outline covers legacy browsers; modern browsers hide it for
+   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. */
 :focus {
   outline: var(--focus-outline);
   outline-offset: var(--focus-outline-offset);
@@ -5073,42 +5418,13 @@ a.avatar[aria-disabled="true"] {
   :focus:not(:focus-visible) {
     outline: none;
   }
-}
-
-/*
- * Forced-colors focus — centralised so individual components do not need
- * their own fallback.  The double :focus keeps specificity high enough
- * (0,0,2,0) to beat a single :focus-visible; against a class selector like
- * .input:focus-visible it ties, but this file loads last so it wins on
- * source order.
- *
- * .choice-card and .join receive focus indirectly (:has on a wrapper that
- * never matches :focus), so they are listed explicitly.
- *
- * .range is excluded from the rectangular fallback: its focus is drawn on
- * the thumb pseudo-element, which is the manipulated surface.
- *
- * box-shadow: none is redundant when forced-color-adjust is auto, but safe
- * when a component uses forced-color-adjust: none (e.g. checked switches /
- * checkboxes).
- */
-@media (forced-colors: active) {
-  :focus:focus-visible:not(.range),
-  .choice-card:has(:focus-visible),
-  .join:has(> :is(.input, .textarea, .select):focus-visible) {
-    outline: var(--focus-outline);
-    outline-offset: var(--focus-outline-offset);
-    box-shadow: none;
-  }
-
-  .range:focus-visible::-webkit-slider-thumb {
-    outline: var(--focus-outline);
-    outline-offset: var(--focus-outline-offset);
-  }
 
-  .range:focus-visible::-moz-range-thumb {
-    outline: var(--focus-outline);
-    outline-offset: var(--focus-outline-offset);
+  /* Pointer focus must still signal in high-contrast mode, where the shared
+     box-shadow rings are disabled (--focus-ring-shadow: none). */
+  @media (forced-colors: active) {
+    :focus:not(:focus-visible) {
+      outline: var(--focus-outline);
+    }
   }
 }
 
@@ -5159,3 +5475,16 @@ a.avatar[aria-disabled="true"] {
     break-after: avoid;
   }
 }
+
+
+/*
+ * NOTE: The 'optional/' directory contains layout and utility extensions
+ * (such as optional grids, split, visual effects, and extra utility classes
+ * like .gap-sm, .flex-nowrap, .shadow-sm, etc.). These are intentionally not
+ * bundled here. Two entry points ship them:
+ *
+ *   actual-css/css/optional/index   optional layer only
+ *   actual-css/css/actual.full      core + optional
+ *
+ * Import one of these paths in your project when you need them.
+ */