actual-css 0.9.0 → 0.9.2

package/dist/actual.full.css

@@ -71,6 +71,8 @@ select {
   /* Typography */
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --font-width: 100%;
+  --font-width-dense: 95%;
   --line-height: 1.5;
   --line-height-tight: 1.25;
   --line-height-relaxed: 1.75;
@@ -519,12 +521,14 @@ select {
  * Public hooks:
  * --link
  * --hr-space
+ * --font-width / --font-width-dense (see variants.css for the dense application)
  */
 
 body {
   background: var(--surface);
   color: var(--text);
   font-family: var(--font-sans);
+  font-stretch: var(--font-width);
   line-height: var(--line-height);
 }
 
@@ -672,9 +676,16 @@ small {
  *   components/alert.css   — .alert default soft behind explicit --ui-*
  *
  * .compact/.spacious set inherited density tokens: spacing rhythm and geometry
- * only. Density never changes typography or icon size. Controls consume
- * --control-size; non-control components may consume --density-* when the
- * context should affect their local rhythm.
+ * only, plus a slight typographic width bonus. Density never changes font size
+ * or icon size. Controls consume --control-size; non-control components may
+ * consume --density-* when the context should affect their local rhythm.
+ * .compact applies --font-width-dense through font-stretch (a variable wdth
+ * axis when available, otherwise normal width-face matching); layout must
+ * never depend on the narrowing being available. .spacious restores
+ * --font-width, so a spacious island inside a compact context returns to the
+ * normal width exactly as it restores its own gap, spacing, and control size.
+ * Themes whose typeface has no useful width axis opt out with
+ * --font-width-dense: 100%.
  *
  * .sm/.lg are local size roles, not shared measurements. Shared control
  * participants below map both typography and geometry; components with
@@ -739,18 +750,20 @@ small {
   --gap: var(--space-20);
   --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
+  font-stretch: var(--font-width-dense);
 }
 
 .spacious {
   --gap: var(--space-50);
   --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
+  font-stretch: var(--font-width);
 }
 
 /* Shared control scale. Wrappers are listed when their descendants form one
-   component (field, input-icon, join, pagination, tabs, flyout). A local size
-   declaration beats inherited density because it is declared on the sized
-   component itself. */
+   component (field, choice-card, floating-field, input-icon, join, pagination,
+   tabs, flyout). A local size declaration beats inherited density because it
+   is declared on the sized component itself. */
 :where(
   .btn,
   .input,
@@ -760,7 +773,9 @@ small {
   .file,
   .field,
   .choice,
+  .choice-card,
   .input-icon,
+  .floating-field,
   .otp,
   .join,
   .pagination,
@@ -782,7 +797,9 @@ small {
   .file,
   .field,
   .choice,
+  .choice-card,
   .input-icon,
+  .floating-field,
   .otp,
   .join,
   .pagination,
@@ -842,6 +859,9 @@ small {
 
 @media print {
   :root,
+  /* The doubled attribute intentionally outranks single-attribute preset
+     islands (data-theme="dark", paired themes) loaded after the core. */
+  [data-theme][data-theme],
   body {
     /* Save some ink in dark mode */
     color-scheme: light;
@@ -863,6 +883,8 @@ small {
 /*
  * Prose is the opt-in rich text scope for authored content.
  *
+ * Docs: docs/pages/foundations/typography.md
+ *
  * Global element styles stay mild so app UI is not shaped accidentally. Page
  * layout, forms, cards, navigation, and app tables remain outside this scope.
  *
@@ -1079,7 +1101,8 @@ small {
 
 /* Lead paragraph: a slightly larger, more relaxed reading-introduction text.
    Non-fluid and always available — use .text-lead from the optional fluid
-   module for marketing/display surfaces. */
+   module for marketing/display surfaces.
+   Docs: docs/pages/foundations/typography.md */
 .lead {
   font-size: 1.125em;
   line-height: var(--line-height-relaxed);
@@ -1088,6 +1111,8 @@ small {
 /*
  * Overline — editorial small-cap label for section openers.
  *
+ * Docs: docs/pages/foundations/typography.md
+ *
  * Base form is unstyled chrome that takes its surrounding color. Add .pill for
  * the bordered rounded shape, and combine with an intent class (.primary,
  * .success, etc.) to tint the text, border, and background.
@@ -1137,6 +1162,8 @@ small {
 /*
  * Optional fluid typography module.
  *
+ * Docs: docs/pages/foundations/typography.md
+ *
  * Part of the typography family (typography/index.css) and the full bundle; it
  * is not in the minimal core, so a core-only import adds it explicitly when
  * display, title, and lead sizes must scale with the viewport. Typical use
@@ -1267,7 +1294,8 @@ small {
    region re-spaces every nested stack, cluster and grid at any depth. Setting
    the token stays correct on the element that consumes it, and
    .compact/.spacious set it deliberately so a density context reaches nested layouts. See
-   docs/pages/layout/stack.md. */
+   docs/pages/layout/stack.md.
+   Docs: docs/pages/layout/stack.md */
 .stack {
   display: flex;
   flex-direction: column;
@@ -1281,6 +1309,8 @@ small {
 /*
  * Inline group that wraps when space runs out.
  *
+ * Docs: docs/pages/layout/cluster.md
+ *
  * Public hooks:
  * --cluster-align
  * --cluster-justify
@@ -1304,6 +1334,8 @@ small {
 /*
  * Centered content column with a maximum measure.
  *
+ * Docs: docs/pages/layout/center.md
+ *
  * Public hooks:
  * --center-size
  * --center-pad
@@ -1319,6 +1351,8 @@ small {
 /*
  * Media frame with a fixed ratio.
  *
+ * Docs: docs/pages/layout/frame.md
+ *
  * Public hooks:
  * --frame-ratio
  *
@@ -1336,7 +1370,11 @@ small {
   object-fit: cover;
 }
 
-/* Full-height single-column document shell. */
+/*
+ * Full-height single-column document shell.
+ *
+ * Docs: docs/pages/layout/app-shell.md
+ */
 .app-shell {
   min-block-size: var(--viewport-block);
   display: flex;
@@ -1350,6 +1388,8 @@ small {
  * chrome available without fixed offsets. This is not a generic page wrapper
  * or a public-site layout; all three direct regions are part of the contract.
  *
+ * Docs: docs/pages/layout/app-layout.md
+ *
  * Public hook:
  * --app-nav-side-size
  */
@@ -1449,7 +1489,8 @@ small {
 /* Media object: fixed-width leading element (avatar, icon, image) + flexible
    trailing content. Replaces the repeated "auto minmax(0, 1fr)" pattern in
    author cards, comments, meta rows, and similar compositions.
-   Child contract: exactly two direct children (leading media + content). */
+   Child contract: exactly two direct children (leading media + content).
+   Docs: docs/pages/layout/media.md */
 .media {
   display: grid;
   grid-template-columns: auto minmax(0, 1fr);
@@ -1460,6 +1501,8 @@ small {
 /*
  * Peer regions that switch as a group.
  *
+ * Docs: docs/pages/layout/switcher.md
+ *
  * All children sit side by side when they all fit; otherwise every child
  * stacks. Unlike .grid, this recipe cannot create a partial row such as two
  * items plus one orphan.
@@ -1485,6 +1528,8 @@ small {
 /*
  * Main content + secondary region.
  *
+ * Docs: docs/pages/layout/sidebar-layout.md
+ *
  * The children wrap according to the space allocated to this layout, without
  * an ancestor opt-in or viewport threshold. The large growth ratio lets the
  * main region reclaim the full row when the aside wraps instead of remaining
@@ -1539,6 +1584,8 @@ small {
 /*
  * Responsive equal-width grids.
  *
+ * Docs: docs/pages/layout/grid.md
+ *
  * .grid is space-driven: it fits as many tracks as --grid-min allows.
  * .grid-N is count-driven: it declares a structural density of N and collapses
  * through natural divisors of N.
@@ -1669,6 +1716,8 @@ small {
 /*
  * Explicit 12-column composition canvas.
  *
+ * Docs: docs/pages/layout/column-layout.md
+ *
  * Neither space-driven like .grid nor count-driven like .grid-N: this is a
  * coordinate system. The author places regions with .column-span-N /
  * .column-start-N and owns narrow-container recomposition. There is
@@ -1856,6 +1905,8 @@ small {
  * Scroll snap — optional horizontal rails for niche card strips and simple
  * touch-friendly overflow areas.
  *
+ * Docs: docs/pages/layout/scroll-snap.md
+ *
  * This is not a full carousel. For previous/next controls, pagination,
  * active state, drag behavior, looping, or robust desktop mouse interaction,
  * use a dedicated carousel library.
@@ -1920,6 +1971,8 @@ small {
  * header (.topbar) or underlaps it; scroll-margin reserves space on the
  * target itself so the browser stops early.
  *
+ * Docs: docs/pages/layout/scroll-target.md
+ *
  * Apply to the elements that are link targets: <section id="...">, headings,
  * etc. The scrollspy enhancer only reads ids — this offset is what actually
  * shapes where the page lands, and the two are independent.
@@ -1937,6 +1990,8 @@ small {
  * background only — row content (search, breadcrumb, actions) stays local
  * to the page.
  *
+ * Docs: docs/pages/layout/topbar.md
+ *
  * Not for marketing/editorial site headers — those are one-off visual
  * identity per page; see docs/pages/patterns/overview.md's Header Navigation
  * section. This is for the structural app-shell topbar, which recurs unchanged
@@ -1990,6 +2045,8 @@ small {
 /*
  * Form layout and supporting text.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Individual controls keep their own files; .choice label layout lives in
  * choice.css; .form-actions lives in form-actions.css.
  *
@@ -2005,6 +2062,12 @@ small {
  */
 .field {
   display: grid;
+
+  /* why: a field stretched by a taller row sibling — the classic case is a
+     neighbour revealing its .field-error — would otherwise hand the extra
+     block size to its auto rows and inflate the control. Rows keep their
+     natural height; the slack stays at the end. */
+  align-content: start;
   gap: var(--space-10);
   color: var(--text);
   font-size: var(--control-font-size);
@@ -2052,6 +2115,8 @@ small {
 /*
  * Text controls — input, textarea, select.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Neutral geometry and interaction states shared across all text-like
  * controls. select shares this base recipe; its chevron/appearance layer
  * lives in select.css. checkbox, radio, range, switch, and file have their
@@ -2405,6 +2470,8 @@ small {
  * Select — chevron and appearance layer on top of the shared text-control
  * recipe.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Base geometry and interaction states come from control.css (select shares
  * the --control-* tokens). This file only removes the native arrow and draws
  * the CSS chevron, so the picker (appearance: base-select) enhancement in
@@ -2463,6 +2530,8 @@ small {
  * custom styling, so the framework stays out of the way and just keeps them
  * readable and theme-aware.
  *
+ * Docs: docs/pages/forms/controls.md
+ *
  * 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.
  */
@@ -2563,6 +2632,8 @@ small {
 /*
  * Form validation states.
  *
+ * Docs: docs/pages/forms/validation.md
+ *
  * Imported by default through forms/index.css. Custom builds may omit this
  * file when an app wants to own validation styling completely.
  *
@@ -2654,6 +2725,8 @@ small {
 /*
  * Form actions — bottom form bar with sticky variant.
  *
+ * Docs: docs/pages/forms/form-actions.md
+ *
  * 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.
@@ -2710,6 +2783,8 @@ small {
 /*
  * Input Icon — decorative icon inside a relative wrapper, leading or trailing.
  *
+ * Docs: docs/pages/patterns/icon-input.md
+ *
  * Icon-library agnostic: detects position by DOM order. First child that is
  * not .input = leading icon; icon after .input = trailing. The icon follows
  * local typography; density contexts shrink the control geometry around it
@@ -2771,6 +2846,8 @@ small {
 /*
  * Switch controls for checkbox inputs with switch semantics.
  *
+ * Docs: docs/pages/forms/switch.md
+ *
  * The switch remains an input control, not a decorative toggle. Checked, hover,
  * focus-visible, and disabled states stay clear.
  *
@@ -2923,6 +3000,8 @@ small {
  * Range slider — custom-styled so the focus ring always targets the
  * user-manipulated surface (the thumb) rather than the CSS box.
  *
+ * Docs: docs/pages/forms/range.md
+ *
  * 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.
@@ -3038,6 +3117,8 @@ small {
 /*
  * Choice cards — card-style radio and checkbox labels.
  *
+ * Docs: docs/pages/forms/choice-cards.md
+ *
  * Each .choice-card is a <label> wrapping a native radio or checkbox. When
  * :has() is supported the input is visually hidden and the card mirrors its
  * state: checked border and tint, checkmark badge (round for radio, rounded
@@ -3074,6 +3155,8 @@ small {
   border-radius: var(--choice-card-radius);
   background: var(--choice-card-bg);
   color: var(--text);
+  /* Consumed so .sm/.lg reach the card; the badge's em sizing follows. */
+  font-size: var(--control-font-size);
   cursor: pointer;
   transition:
     border-color var(--duration),
@@ -3282,6 +3365,8 @@ small {
  * Floating labels — optional composition over the text controls
  * (.input, .textarea, .select) and .field-label.
  *
+ * Docs: docs/pages/forms/floating-field.md
+ *
  * The cell owns a control plus its label; the label overlays the control and
  * floats to the top when the control is focused or non-empty. Help and error
  * messages stay in the surrounding .field, not inside the cell, so the
@@ -3323,7 +3408,9 @@ small {
 
 .floating-field > .field-label {
   position: absolute;
-  inset-inline-start: calc(var(--space-30) + var(--border-width));
+  /* Same start edge as the control's text: --control-pad-x owns that shared
+     geometry, so .sm/.lg keep label and value aligned. */
+  inset-inline-start: calc(var(--control-pad-x) + var(--border-width));
   color: var(--text-muted);
   font-size: var(--control-font-size);
   font-weight: var(--font-weight-normal);
@@ -3389,6 +3476,8 @@ small {
 /*
  * One-time code input with visual cells and one native input.
  *
+ * Docs: docs/pages/forms/otp.md
+ *
  * Add one direct span per accepted character. The cells determine the
  * component width; the overlaid input remains the only interactive control.
  *
@@ -3517,12 +3606,22 @@ small {
   .needs-validation.was-validated .otp > input:invalid ~ span {
     --otp-cell-border: Mark;
   }
+
+  /* biome-ignore lint/style/noDescendingSpecificity: the :user-invalid route
+     mirrors the non-forced-colors block above and must come last — the three
+     invalid markers write the same value, so source order is inert. An engine
+     without the pseudo drops this rule alone. */
+  .needs-validation .otp > input:user-invalid ~ span {
+    --otp-cell-border: Mark;
+  }
 }
 
 /* Controls */
 /*
  * Buttons for actions and button-like links.
  *
+ * Docs: docs/pages/components/button.md
+ *
  * .btn is primarily for actionable elements: <button>, <a href>,
  * input[type="button"|"submit"|"reset"].
  *
@@ -3769,6 +3868,8 @@ a.btn[aria-disabled="true"] {
 /*
  * Badges for compact labels, counts, and state hints.
  *
+ * Docs: docs/pages/components/badge.md
+ *
  * 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.
@@ -4029,6 +4130,8 @@ a.badge[aria-disabled="true"] {
 /*
  * Alerts for inline feedback and status messages.
  *
+ * Docs: docs/pages/components/alert.md
+ *
  * Keeps alert defaults local while consuming the shared --ui-* variant
  * plumbing for emphasis.
  *
@@ -4315,6 +4418,8 @@ a.badge[aria-disabled="true"] {
 /*
  * Actions — a horizontal action-button cluster.
  *
+ * Docs: docs/pages/patterns/actions.md
+ *
  * Composes with .btn (or any inline element) and feeds layout via the shared
  * --gap token.
  *
@@ -4343,6 +4448,8 @@ a.badge[aria-disabled="true"] {
 /*
  * Cards provide a neutral raised surface for grouped content.
  *
+ * Docs: docs/pages/components/card.md
+ *
  * Surface, border, radius, padding, density, and elevation stay local here.
  * Direct header/footer children are structural slots; a direct footer is
  * anchored to the card's bottom edge when extra block space is available (so
@@ -4504,6 +4611,8 @@ a.badge[aria-disabled="true"] {
 /*
  * Modal shell styling for native dialog elements.
  *
+ * Docs: docs/pages/components/dialog.md
+ *
  * Spacing, radius, transitions, and focus treatment come from shared tokens.
  * Opening behavior and intent-specific decisions stay outside this component.
  *
@@ -4515,16 +4624,15 @@ a.badge[aria-disabled="true"] {
  *
  * Internal:
  * --dialog-close-icon-size
+ * --dialog-focus-bleed
  * --dialog-viewport-block
  * --dialog-viewport-gap-default
  * --dialog-viewport-gap-2x
  */
-dialog.modal {
-  /* --dialog-viewport-gap stays fallback-only for the same reason as
-     --modal-size below: declaring the public hook here would give it
-     type+class specificity that a single author class cannot outrank. The
-     responsive default lives in an internal token instead, so a media query
-     can still move it without closing the hook.
+:where(dialog).modal {
+  /* --dialog-viewport-gap stays fallback-only so the responsive default can
+     live in an internal token: a media query moves it without closing the
+     public hook.
 
      calc() multiplication is not in the supported browser range, so the
      doubled gap is spelled out with an additive calc. */
@@ -4538,10 +4646,8 @@ dialog.modal {
      provides the containing block for the absolutely positioned close button. */
   position: fixed;
 
-  /* --modal-size stays fallback-only: declaring it on dialog.modal gives it
-     type+class specificity, which a single author class cannot outrank, so the
-     public hook would silently keep this default. Same reason choice.css never
-     declares --choice-control-nudge. */
+  /* The root is :where(dialog).modal (0-1-0), so a single author class can
+     outrank these defaults — no fallback-only indirection needed here. */
   max-inline-size: min(calc(100% - var(--dialog-viewport-gap-2x)), var(--modal-size, 32rem));
 
   /* Stable viewport cap for the panel: dvh tracks the dynamic browser toolbar
@@ -4571,8 +4677,8 @@ dialog.modal {
     transform var(--duration) var(--ease-exit);
 }
 
-dialog.modal > form,
-dialog.modal > .stack {
+:where(dialog).modal > form,
+:where(dialog).modal > .stack {
   display: grid;
   gap: var(--space-40);
   max-block-size: calc(var(--dialog-viewport-block) - var(--dialog-viewport-gap-2x));
@@ -4582,7 +4688,7 @@ dialog.modal > .stack {
 }
 
 @supports (block-size: 100svh) {
-  dialog.modal {
+  :where(dialog).modal {
     --dialog-viewport-block: 100svh;
   }
 }
@@ -4590,42 +4696,50 @@ dialog.modal > .stack {
 /* Keep the dialog off the viewport edges on small screens. Moves the internal
    default, not the public hook, so an author override still wins here too. */
 @media (max-width: 30rem) {
-  dialog.modal {
+  :where(dialog).modal {
     --dialog-viewport-gap-default: var(--space-30);
   }
 }
 
-dialog.modal.scrollable > form,
-dialog.modal.scrollable > .stack {
+:where(dialog).modal.scrollable > form,
+:where(dialog).modal.scrollable > .stack {
   grid-template-rows: auto minmax(0, 1fr) auto;
   overflow: hidden;
 }
 
-dialog.modal.scrollable > form > :not(:is(header, footer)),
-dialog.modal.scrollable > .stack > :not(:is(header, footer)) {
+:where(dialog).modal.scrollable > form > :not(:is(header, footer)),
+:where(dialog).modal.scrollable > .stack > :not(:is(header, footer)) {
+  --dialog-focus-bleed: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+
   min-block-size: 0;
+  /* Keep focus paint inside the clip without moving the body off the fixed
+     header and footer edges. */
+  margin-inline: calc(var(--dialog-focus-bleed) * -1);
+  padding-inline: var(--dialog-focus-bleed);
   overflow: auto;
   overscroll-behavior: contain;
 }
 
-dialog.modal header > :first-child,
-dialog.modal footer > :first-child {
+/* Anatomy is bounded to the structural slots (direct children of the
+   form/.stack body): a header or footer deeper in the content keeps its own
+   rhythm and is not restyled as the modal's chrome. */
+:where(dialog).modal > :where(form, .stack) > :is(header, footer) > :first-child {
   margin-block-start: 0;
 }
 
-dialog.modal header > :last-child,
-dialog.modal footer > :last-child {
+:where(dialog).modal > :where(form, .stack) > :is(header, 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 {
+   content flow; headers reserve inline room so titles never run under it.
+   The form/.stack anatomy is structural, so it stays in :where() and never
+   lends .stack's specificity to a bare <form>. */
+:where(dialog).modal > :where(form, .stack) > header {
   padding-inline-end: calc(var(--control-size) + var(--space-30));
 }
 
-dialog.modal footer {
+:where(dialog).modal > :where(form, .stack) > footer {
   display: flex;
   flex-wrap: wrap;
   justify-content: flex-end;
@@ -4635,17 +4749,17 @@ dialog.modal footer {
 /* 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 {
+:where(dialog).modal.dialog-confirmation > form {
   gap: 0;
   padding: 0;
 }
 
-dialog.modal.dialog-confirmation > form > .media {
+:where(dialog).modal.dialog-confirmation > form > .media {
   gap: var(--space-40);
   padding: var(--space-50);
 }
 
-dialog.modal.dialog-confirmation > form > footer {
+:where(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));
@@ -4686,13 +4800,13 @@ dialog.modal.dialog-confirmation > form > footer {
 }
 
 @media (max-width: 30rem) {
-  dialog.modal.dialog-confirmation > form > .media,
-  dialog.modal.dialog-confirmation > form > footer {
+  :where(dialog).modal.dialog-confirmation > form > .media,
+  :where(dialog).modal.dialog-confirmation > form > footer {
     padding: var(--space-40);
   }
 }
 
-dialog.modal[open] {
+:where(dialog).modal[open] {
   opacity: 1;
   transform: none;
   transition:
@@ -4701,13 +4815,13 @@ dialog.modal[open] {
 }
 
 @starting-style {
-  dialog.modal[open] {
+  :where(dialog).modal[open] {
     opacity: 0;
     transform: translateY(0.35rem);
   }
 }
 
-dialog.modal::backdrop {
+:where(dialog).modal::backdrop {
   background: var(--backdrop-fill);
   opacity: 0;
   /* Scrim curve stays neutral `ease`; only the panel carries the character
@@ -4716,7 +4830,7 @@ dialog.modal::backdrop {
 }
 
 @supports (transition-behavior: allow-discrete) {
-  dialog.modal {
+  :where(dialog).modal {
     transition:
       opacity var(--duration) var(--ease-exit),
       transform var(--duration) var(--ease-exit),
@@ -4724,7 +4838,7 @@ dialog.modal::backdrop {
       display var(--duration) allow-discrete;
   }
 
-  dialog.modal[open] {
+  :where(dialog).modal[open] {
     transition:
       opacity var(--duration) var(--ease-enter),
       transform var(--duration) var(--ease-enter),
@@ -4732,7 +4846,7 @@ dialog.modal::backdrop {
       display var(--duration) allow-discrete;
   }
 
-  dialog.modal::backdrop {
+  :where(dialog).modal::backdrop {
     transition:
       opacity var(--duration) ease,
       overlay var(--duration) allow-discrete,
@@ -4740,7 +4854,7 @@ dialog.modal::backdrop {
   }
 }
 
-dialog.modal[open]::backdrop {
+:where(dialog).modal[open]::backdrop {
   opacity: 1;
 }
 
@@ -4753,7 +4867,7 @@ html.has-modal-open.had-scrollbar {
 }
 
 @starting-style {
-  dialog.modal[open]::backdrop {
+  :where(dialog).modal[open]::backdrop {
     opacity: 0;
   }
 }
@@ -4761,7 +4875,7 @@ html.has-modal-open.had-scrollbar {
 @media (prefers-reduced-motion: no-preference) {
   /* Wrong-close feedback and view-transition transport are motion quirks, not
      presence enter/exit, so they stay on the plain CSS default easing. */
-  dialog.modal.is-static {
+  :where(dialog).modal.is-static {
     animation: actual-dialog-static var(--duration-slow) ease;
   }
 
@@ -4842,6 +4956,12 @@ html.has-modal-open.had-scrollbar {
 /*
  * Drawer — modal side-sheet built on the native dialog element.
  *
+ * Docs: docs/pages/components/drawer.md
+ *
+ * Open with a native command button:
+ * command="show-modal" commandfor="<drawer-id>".
+ * For stacked navigation, compose with .nav-list from navbar.css.
+ *
  * Top-layer rendering, ::backdrop, Escape, and modal focus come from the
  * native dialog. CSS owns progressive enter/exit motion where browsers support
  * discrete display/overlay transitions. The drawer is a layout shell only —
@@ -4854,10 +4974,11 @@ html.has-modal-open.had-scrollbar {
  *
  * Internal:
  * --drawer-closed-translate (side/RTL positioning state)
+ * --drawer-focus-bleed
  * --drawer-motion-duration (shared by panel and ::backdrop so exit duration
  *   changes in one place; entry state redefines it longer)
  */
-dialog.drawer {
+:where(dialog).drawer {
   --drawer-size: 20rem;
   --drawer-pad: var(--space-40);
   --drawer-closed-translate: -100%;
@@ -4900,7 +5021,7 @@ dialog.drawer {
     transform var(--drawer-motion-duration) var(--ease-exit);
 }
 
-dialog.drawer[open] {
+:where(dialog).drawer[open] {
   --drawer-motion-duration: var(--duration-slow);
   display: grid;
   grid-template-rows: auto minmax(0, 1fr) auto;
@@ -4915,7 +5036,7 @@ dialog.drawer[open] {
 /* A form is the drawer's content wrapper when actions need method="dialog".
    Span the drawer tracks so the form can keep the header at the top, let the
    body absorb the available height, and keep the footer at the bottom. */
-dialog.drawer > form {
+:where(dialog).drawer > form {
   display: grid;
   grid-row: 1 / -1;
   grid-template-rows: auto minmax(0, 1fr) auto;
@@ -4924,7 +5045,7 @@ dialog.drawer > form {
 }
 
 /* The shared backdrop token keeps drawer and modal scrims consistent. */
-dialog.drawer::backdrop {
+:where(dialog).drawer::backdrop {
   background: var(--backdrop-fill);
   opacity: 0;
   /* Scrim curve stays neutral `ease`; only the panel's character curves
@@ -4932,7 +5053,7 @@ dialog.drawer::backdrop {
   transition: opacity var(--drawer-motion-duration) ease;
 }
 
-dialog.drawer[data-side="end"] {
+:where(dialog).drawer[data-side="end"] {
   --drawer-closed-translate: 100%;
 
   margin-inline-start: auto;
@@ -4941,17 +5062,17 @@ dialog.drawer[data-side="end"] {
   border-inline-start: var(--border-width) solid var(--border);
 }
 
-dialog.drawer[open]::backdrop {
+:where(dialog).drawer[open]::backdrop {
   opacity: 1;
 }
 
 @starting-style {
-  dialog.drawer[open] {
+  :where(dialog).drawer[open] {
     opacity: 0;
     transform: translateX(var(--drawer-closed-translate));
   }
 
-  dialog.drawer[open]::backdrop {
+  :where(dialog).drawer[open]::backdrop {
     opacity: 0;
   }
 }
@@ -4961,15 +5082,21 @@ dialog.drawer[open]::backdrop {
    modal, which sizes to its content and opts in with .scrollable. Header and
    footer keep their own tracks; .drawer-close is named because a generic
    exclusion list is easier to trust than its `position: absolute`. */
-dialog.drawer > :not(:is(header, footer, form, .drawer-close)),
-dialog.drawer > form > :not(:is(header, footer, .drawer-close)) {
+:where(dialog).drawer > :not(:is(header, footer, form, .drawer-close)),
+:where(dialog).drawer > form > :not(:is(header, footer, .drawer-close)) {
+  --drawer-focus-bleed: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+
   min-block-size: 0;
+  /* Keep focus paint inside the clip without moving the body off the fixed
+     header and footer edges. */
+  margin-inline: calc(var(--drawer-focus-bleed) * -1);
+  padding-inline: var(--drawer-focus-bleed);
   overflow: auto;
   overscroll-behavior: contain;
 }
 
 @supports (transition-behavior: allow-discrete) {
-  dialog.drawer {
+  :where(dialog).drawer {
     transition:
       opacity var(--drawer-motion-duration) var(--ease-exit),
       transform var(--drawer-motion-duration) var(--ease-exit),
@@ -4977,7 +5104,7 @@ dialog.drawer > form > :not(:is(header, footer, .drawer-close)) {
       display var(--drawer-motion-duration) allow-discrete;
   }
 
-  dialog.drawer[open] {
+  :where(dialog).drawer[open] {
     transition:
       opacity var(--drawer-motion-duration) var(--ease-enter),
       transform var(--drawer-motion-duration) var(--ease-enter),
@@ -4985,7 +5112,7 @@ dialog.drawer > form > :not(:is(header, footer, .drawer-close)) {
       display var(--drawer-motion-duration) allow-discrete;
   }
 
-  dialog.drawer::backdrop {
+  :where(dialog).drawer::backdrop {
     transition:
       opacity var(--drawer-motion-duration) ease,
       overlay var(--drawer-motion-duration) allow-discrete,
@@ -4999,40 +5126,40 @@ dialog.drawer > form > :not(:is(header, footer, .drawer-close)) {
    directionality and handles nested direction changes; the explicit ltr rules
    neutralize an outer RTL fallback selector. Each specificity group keeps the
    fallback before the :dir() rules. */
-[dir="rtl"] dialog.drawer {
+[dir="rtl"] :where(dialog).drawer {
   --drawer-closed-translate: 100%;
 }
 
-dialog.drawer:dir(ltr) {
+:where(dialog).drawer:dir(ltr) {
   --drawer-closed-translate: -100%;
 }
 
-dialog.drawer:dir(rtl) {
+:where(dialog).drawer:dir(rtl) {
   --drawer-closed-translate: 100%;
 }
 
-[dir="rtl"] dialog.drawer[data-side="end"] {
+[dir="rtl"] :where(dialog).drawer[data-side="end"] {
   --drawer-closed-translate: -100%;
 }
 
-dialog.drawer[data-side="end"]:dir(ltr) {
+:where(dialog).drawer[data-side="end"]:dir(ltr) {
   --drawer-closed-translate: 100%;
 }
 
-dialog.drawer[data-side="end"]:dir(rtl) {
+:where(dialog).drawer[data-side="end"]:dir(rtl) {
   --drawer-closed-translate: -100%;
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  dialog.drawer.is-static {
+  :where(dialog).drawer.is-static {
     animation: actual-dialog-static var(--duration-slow) ease;
   }
 }
 
 /* The header reserves inline room so the title never runs under the close
    control. */
-dialog.drawer > header,
-dialog.drawer > form > header {
+:where(dialog).drawer > header,
+:where(dialog).drawer > form > header {
   padding-inline-end: calc(var(--control-size) + var(--space-30));
 }
 
@@ -5091,6 +5218,8 @@ dialog.drawer > form > header {
 /*
  * Flyout — floating panel for actions and links.
  *
+ * Docs: docs/pages/enhancements/flyout.md
+ *
  * JavaScript promotes the panel to the top layer and chooses viewport or
  * document coordinates from its anchor. It also owns state (.is-open), focus,
  * and keyboard behavior. CSS owns the surfaced panel appearance, item styles,
@@ -5393,6 +5522,8 @@ dialog.drawer > form > header {
 /*
  * Tooltip — supplemental label overlaid near a trigger.
  *
+ * Docs: docs/pages/enhancements/tooltip.md
+ *
  * Position, placement, and arrow position are managed by JavaScript via left,
  * top, data-placement, and --arrow-x. The runtime also owns `position`: it
  * writes `absolute` for a tip whose trigger scrolls with the page, so the
@@ -5535,6 +5666,8 @@ dialog.drawer > form > header {
 /*
  * Accordion disclosures built on native details and summary.
  *
+ * Docs: docs/pages/components/accordion.md
+ *
  * Keeps the clickable summary affordance aligned and usable without JavaScript
  * or demo styles. Decorative palettes and custom markers belong outside the
  * base component.
@@ -5662,6 +5795,8 @@ dialog.drawer > form > header {
 /*
  * Spinner — compact loading feedback.
  *
+ * Docs: docs/pages/components/spinner.md
+ *
  * Uses currentColor so it adapts to buttons, alerts, badges, and text. The
  * [aria-busy] overlay composition lives in components/busy.css.
  *
@@ -5727,6 +5862,8 @@ dialog.drawer > form > header {
 /*
  * Skeleton placeholders for loading states.
  *
+ * Docs: docs/pages/components/skeleton.md
+ *
  * Shows approximate loading structure without implying real content hierarchy.
  * Geometry, animation, and color stay theme-aware.
  *
@@ -5813,6 +5950,8 @@ dialog.drawer > form > header {
 /*
  * Busy overlay — non-button loading state.
  *
+ * Docs: docs/pages/components/spinner.md
+ *
  * 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).
@@ -5865,6 +6004,8 @@ dialog.drawer > form > header {
 /*
  * Progress — native progress bar with theme-aware track and value.
  *
+ * Docs: docs/pages/components/progress.md
+ *
  * Consumes the shared --intent/--primary for the value bar and --bar-height
  * for thickness. Indeterminate state animates a shimmer using --duration-shimmer.
  *
@@ -5979,6 +6120,8 @@ dialog.drawer > form > header {
 /*
  * Status bar — singleton floating status area.
  *
+ * Docs: docs/pages/enhancements/status-bar.md
+ *
  * One element in the HTML, empty by default. .is-open is the visual state, set
  * by status.js like any other surface: it lands after the message is written
  * and lifts before the bar is cleared, so the bar leaves in the exact state it
@@ -6070,6 +6213,8 @@ dialog.drawer > form > header {
 /*
  * Avatars for initials, images, links, and buttons.
  *
+ * Docs: docs/pages/components/avatar.md
+ *
  * 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.
@@ -6292,6 +6437,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Indicator — generic corner positioning for overlaid component content.
  *
+ * Docs: docs/pages/components/indicator.md
+ *
  * The container only establishes the containing block. The item owns no
  * paint, size, or ring so badges and other components keep their own visual
  * contract.
@@ -6361,6 +6508,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Key — keyboard keys and shortcut tokens for UI chrome.
  *
+ * Docs: docs/pages/components/key.md
+ *
  * Use .key outside prose. Plain kbd inside .prose gets the same visual
  * treatment from prose.css so authored content stays convenient.
  *
@@ -6401,6 +6550,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Message rows composed from an optional avatar, metadata, and bubble.
  *
+ * Docs: docs/pages/components/chat.md
+ *
  * Public hooks:
  * --chat-gap
  * --chat-max-size
@@ -6504,6 +6655,8 @@ a.avatar[aria-disabled="true"] {
  * Button owns the trigger's size, shape, and intent; FAB owns placement and
  * the speed dial's structural open/close markers (--icon-plus / --icon-close).
  *
+ * Docs: docs/pages/components/fab.md
+ *
  * Public hooks:
  * --fab-offset
  * --fab-gap
@@ -6631,6 +6784,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Rating — integer star rating drawn on native radio inputs.
  *
+ * Docs: docs/pages/components/rating.md
+ *
  * The checked radio remains the functional baseline. :has() progressively
  * fills preceding stars without reversing DOM or keyboard order. Forced
  * colors restores the platform radio presentation.
@@ -6733,6 +6888,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Steps — semantic ordered-list progression for a multi-step process.
  *
+ * Docs: docs/pages/components/steps.md
+ *
  * One primitive, two explicit compositions. Both classes are required:
  *
  *   <ol class="steps steps-horizontal">  horizontal, 2 to 5 stages
@@ -7081,6 +7238,8 @@ a.avatar[aria-disabled="true"] {
  * and item states; app-layout owns whether that surface is a bottom bar or
  * labelled side navigation.
  *
+ * Docs: docs/pages/components/app-navigation.md
+ *
  * Public hooks:
  * --app-nav-size
  * --app-nav-gap
@@ -7166,6 +7325,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Navbar — top-level navigation bar.
  *
+ * Docs: docs/pages/components/navbar.md
+ *
  * .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.
@@ -7298,6 +7459,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Breadcrumb — current-location trail from the site root.
  *
+ * Docs: docs/pages/components/breadcrumb.md
+ *
  * Inline list separated by "/". Mark the current page with `aria-current="page"`
  * either on the item or on the current link.
  */
@@ -7347,6 +7510,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Pagination — page navigation for paginated lists.
  *
+ * Docs: docs/pages/components/pagination.md
+ *
  * Render .btn elements inside a .pagination list. The active page is marked
  * with aria-current="page"; .btn owns the active state styling.
  *
@@ -7391,6 +7556,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Tabs — in-place panel switcher with real tab semantics.
  *
+ * Docs: docs/pages/enhancements/tabs.md
+ *
  * JavaScript owns roving tabindex, aria-selected, panel visibility,
  * and arrow-key navigation. CSS owns the tab strip appearance and
  * active indicator.
@@ -7512,6 +7679,8 @@ a.avatar[aria-disabled="true"] {
  * Scrollspy — behavior hook for navigation that marks the active section
  * while the page scrolls.
  *
+ * Docs: docs/pages/enhancements/scrollspy.md
+ *
  * Does not add visual styles by itself. scrollspy.js watches
  * <nav class="scrollspy">
  * containing <a href="#section"> links and toggles aria-current="location" on
@@ -7541,6 +7710,8 @@ a.avatar[aria-disabled="true"] {
 /*
  * Data list — term/value pairs for the properties of a single object.
  *
+ * Docs: docs/pages/components/data-list.md
+ *
  * Expects alternating <dt>/<dd> children: one term, one value per property.
  * A plain <dl> handles richer relationships (several terms or descriptions)
  * and stays untouched by this component.
@@ -7571,6 +7742,8 @@ a.avatar[aria-disabled="true"] {
  * Content determines the number of lines; the component only owns the row
  * geometry, dividers, and supporting-text treatment.
  *
+ * Docs: docs/pages/components/list.md
+ *
  * Public hooks:
  * --list-item-min-size
  * --list-item-pad-block
@@ -7691,6 +7864,8 @@ a.list-item[aria-current]::before {
 /*
  * Table — structured tabular data.
  *
+ * Docs: docs/pages/components/table.md
+ *
  * .table-wrap provides the scroll container and outer chrome; .table owns row
  * and cell rules. Tokens are sourced from the shared scale.
  *
@@ -7772,6 +7947,8 @@ a.list-item[aria-current]::before {
 /*
  * Meter — native and segmented gauges for known-range values.
  *
+ * Docs: docs/pages/components/meter.md
+ *
  * Maps the three standard meter zones (optimum / suboptimum / even-less-good)
  * to the shared success / warning / danger intent colors.
  *
@@ -7864,6 +8041,8 @@ a.list-item[aria-current]::before {
 /*
  * Join — visually groups adjacent controls into a single unit.
  *
+ * Docs: docs/pages/forms/joined-controls.md
+ *
  * This is a cross-cutting control primitive, not a forms-only component:
  * it applies equally to inputs, selects, buttons, and button-like links.
  *
@@ -7997,6 +8176,8 @@ a.list-item[aria-current]::before {
 /*
  * Decorative intent-colored frame for one direct child.
  *
+ * Docs: docs/pages/components/aura.md
+ *
  * The effect is built from three layers with distinct roles: a frame carrying
  * a short accent of light, a small halo that belongs to the frame and keeps
  * that light attached to the edge, and a wide static halo that belongs to the
@@ -8315,7 +8496,12 @@ a.list-item[aria-current]::before {
   text-decoration: none;
 }
 
-.link-muted:hover,
+/* :focus-visible stays in its own rule: in a mixed selector list an engine
+   without it would drop the whole rule, taking the :hover styling with it. */
+.link-muted:hover {
+  color: var(--text);
+}
+
 .link-muted:focus-visible {
   color: var(--text);
 }