actual-css 0.7.0 → 0.9.0

package/docs/pages/components/alert.md

@@ -5,13 +5,14 @@
 - Supports intent colors.
 - Supports longer text and lists.
 - Links inherit alert color by default.
-- Alerts are soft by default. Use `.solid` or `.outline` when the message needs stronger or quieter emphasis.
+- Alerts are soft by default. Use `.surface` for neutral chrome with the intent only in the ink, `.solid` or `.outline` when the message needs stronger or quieter emphasis, and `.inverted` for an inverse surface.
 - Use `<menu class="actions cluster">` for alert action lists.
 - Use `role="alert"` only when the alert is injected dynamically and should be announced.
 - Not a toast.
 - Could have simple or complex html content.
+- A title and a description are plain siblings: the alert owns the small space between its direct content blocks, so neither needs a wrapper. Nested content keeps its own rhythm — wrap several paragraphs in `.prose`, or a differently spaced group in `.stack`, when the message needs a rhythm of its own.
 - Alerts may include a decorative leading icon. Use `.alert-icon` on the icon element; the rest of the content flows into the remaining text column.
-- Use `.sm` or `.lg` for density changes. The inline padding stays stable.
+- Use `.compact` or `.spacious` for density changes. The inline padding stays stable.
 - Use `.alert-dismiss` for a compact dismiss button. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions. It uses the shared `--icon-close` mask and the `--dismiss` runtime command — no icon font or custom JS.
 
 Because alerts are soft by default, adding `.soft` to an intent (`.alert.soft.primary`,
@@ -21,26 +22,33 @@ itself needs to change, not `.soft`.
 
 ## Class reference
 
-| Class            | Kind        | Description                                   |
-| ---------------- | ----------- | --------------------------------------------- |
-| `.alert`         | Component   | Inline status surface; soft by default.       |
-| `.alert-icon`    | Composition | Decorative leading icon, in the first column. |
-| `.alert-dismiss` | Modifier    | Compact dismiss button.                       |
-| `.callout`       | Variant     | Neutral panel, thick accent leading edge.     |
-| `.admonition`    | Variant     | Tinted title bar, body on the page surface.   |
-
-`.alert-dismiss` draws itself with the `--icon-close` mask and acts through the
-`--dismiss` command.
-| `.alert-title`   | Composition | Admonition title bar; hosts the dismiss button.                                   |
-| `.alert-body`    | Composition | Admonition body resting on the page surface.                                      |
-| Shared intents   | Intent      | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`.                      |
-| Shared variants  | Variant     | `.solid`, `.outline`, and `.surface` emphasis.                                    |
-| `.sm` / `.lg`    | Size        | Density; inline padding stays stable.                                             |
+| Class            | Kind        | Description                                     |
+| ---------------- | ----------- | ----------------------------------------------- |
+| `.alert`         | Component   | Inline status surface; soft by default.         |
+| `.alert-icon`    | Composition | Decorative leading icon, in the first column.   |
+| `.alert-dismiss` | Modifier    | Compact dismiss button.                         |
+| `.alert-title`   | Composition | Admonition title bar; hosts the dismiss button. |
+| `.alert-body`    | Composition | Admonition body on the page surface.            |
+| `.callout`       | Variant     | Leading-edge flag; owns the border geometry.    |
+| `.admonition`    | Variant     | Tinted title bar, body on the page surface.     |
+| Shared intents   | Intent      | `.primary`, `.secondary`, `.success`, …         |
+| Shared variants  | Variant     | `.solid`, `.outline`, `.surface`.               |
+| `.inverted`      | Surface     | Inverse surface, any intent.                    |
+| Density contexts | Density     | Descendant rhythm; inline padding stays stable. |
 
 ## Basic usage
 
+`.surface` comes first on purpose: it keeps the theme's own chrome and puts the
+intent in the ink alone, which is what most informational messages want. Add an
+intent treatment when the color itself carries the meaning.
+
 ```html demo
 <div class="stack">
+  <div class="alert surface">
+    <i class="ti ti-info-circle alert-icon" aria-hidden="true"></i>
+    <div><strong>New message.</strong> 12 unread. <a href="#">Open inbox</a>.</div>
+  </div>
+
   <div class="alert success">
     <i class="ti ti-circle-check alert-icon" aria-hidden="true"></i>
     <div>Your changes have been saved. <a href="#">View activity</a>.</div>
@@ -91,16 +99,46 @@ itself needs to change, not `.soft`.
 </div>
 ```
 
+## Trailing action
+
+The grid pins `.alert-icon` and `.alert-dismiss` to the outer columns. A
+trailing link or button is content, not anatomy, so it lives in the text column:
+wrap the row in a `.cluster` and push the two ends apart. Same recipe as any
+split / spread row — there is no `.alert-action` class.
+
+The alert aligns its columns to the block start, so a multi-line message keeps
+its icon on the first line. A trailing control makes that row taller than a line
+of text: add `.items-center` to put the icon, the text and the button on one
+center.
+
+```html demo
+<div class="alert surface items-center">
+  <i class="ti ti-info-circle alert-icon" aria-hidden="true"></i>
+  <div class="cluster justify-content-space-between">
+    <strong>New message!</strong>
+    <a class="btn sm outline" href="#">Open</a>
+  </div>
+</div>
+```
+
 ## Variants
 
 ```html demo
 <div class="stack">
-  <div class="alert danger sm" role="alert">
-    I'm a small error
+  <div class="alert surface" role="alert">
+    I'm a surface alert — theme chrome, intent in the ink
+  </div>
+
+  <div class="alert inverted" role="alert">
+    I'm an inverted alert <a href="#">with a link</a>
+  </div>
+
+  <div class="alert danger compact" role="alert">
+    I'm an error in a compact context
   </div>
 
-  <div class="alert danger lg" role="alert">
-    I'm a large error
+  <div class="alert danger spacious" role="alert">
+    I'm an error in a spacious context
   </div>
 
   <div class="alert danger outline" role="alert">
@@ -120,11 +158,8 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
 ```html demo
 <div class="alert warning" id="warning-alert">
   <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
-
-  <div class="stack" style="--gap: var(--space-10)">
-    <strong>Warning</strong>
-    <p>Something needs your attention.</p>
-  </div>
+  <strong>Warning</strong>
+  <p>Something needs your attention.</p>
 
   <button
     class="alert-dismiss"
@@ -156,22 +191,42 @@ In an admonition, place `.alert-dismiss` inside `.alert-title`; it rides the inl
 
 ## Callout
 
-Use `.callout` for a neutral panel with a thick accent border on the leading edge. Intent classes tint the border color.
+`.callout` is a **leading-edge flag treatment**: it owns the border geometry and
+nothing else, so the surface and the ink keep coming from the alert's own intent
+and treatment. Bare is the soft panel, `.surface` the page surface, `.solid` a
+filled one — and `.outline` has no fill and no other side, since the flag *is*
+the border.
 
 ```html demo
 <div class="stack">
   <div class="alert callout">
     <strong>Note</strong>
-    <p>This is a callout — a neutral panel with a thick accent border on the leading edge.</p>
+    <p>A neutral panel with a thick accent flag on the leading edge.</p>
   </div>
 
   <div class="alert warning callout" role="alert">
     <strong>Heads up</strong>
-    <p>The border color follows the intent. No other borders are drawn.</p>
+    <p>The intent tints the panel and the flag together.</p>
+  </div>
+
+  <div class="alert success callout surface">
+    <strong>On the page surface</strong>
+    <p>The flag keeps the intent, the panel drops the tint.</p>
   </div>
 </div>
 ```
 
+Tune the flag with `--alert-border-inline-start-width` and
+`--alert-border-inline-start-color`; `--alert-radius: 0` turns it into a
+full-bleed notice.
+
+```html demo
+<div class="alert danger callout" style="--alert-radius: 0">
+  <i class="ti ti-user-x alert-icon" aria-hidden="true"></i>
+  <div>Your request to join the team is denied.</div>
+</div>
+```
+
 ## Admonition
 
 An admonition is a structured box with a tinted title bar, an optional icon, and body content on the page surface — like the `!!! note` callouts in mkdocs. Use `.alert-title` for the header and `.alert-body` for the content. Intent classes tint the title bar background and the border.
@@ -202,7 +257,7 @@ An admonition is a structured box with a tinted title bar, an optional icon, and
 
 ## CSS hooks
 
-- `--alert-pad-inline` — inline padding. Stays stable across `.sm`/`.lg`.
+- `--alert-pad-inline` — inline padding. Stays stable across density contexts.
 - `--alert-pad-block` — block padding.
 - `--alert-font-size` — base font size.
 - `--alert-icon-size` — size of a leading `.alert-icon`.

package/docs/pages/components/app-navigation.md

@@ -5,6 +5,12 @@
 Use one `.app-nav` landmark for the application's primary destinations. Links
 remain links, and `aria-current="page"` is the only current-page state.
 
+Reach for `.app-nav` only as part of a persistent application shell: it exists
+as a direct child of `.app-layout`, which turns the landmark from a bottom bar
+into side navigation. A site or webapp header with normal scrolling stays
+`.navbar` — `.app-nav` is not a stacked-icon variant of the horizontal bar. See
+[Navbar](navbar.md).
+
 **Related terms:** tab bar, bottom navigation, bottom nav, navigation rail, side navigation.
 
 ```html demo

package/docs/pages/components/avatar.md

@@ -12,12 +12,12 @@
 
 ## Class reference
 
-| Class           | Kind        | Description                             |
-| --------------- | ----------- | --------------------------------------- |
-| `.avatar`       | Component   | Initials or image in a circular box.    |
-| `.avatar-stack` | Composition | Overlapping avatar group.               |
-| `.badge:empty`  | Composition | Status dot, at the bottom-end corner.   |
-| `.sm` / `.lg`   | Size        | Density; also rescales `.avatar-stack`. |
+| Class           | Kind        | Description                                  |
+| --------------- | ----------- | -------------------------------------------- |
+| `.avatar`       | Component   | Initials or image in a circular box.         |
+| `.avatar-stack` | Composition | Overlapping avatar group.                    |
+| `.badge:empty`  | Composition | Status dot, at the bottom-end corner.        |
+| `.sm` / `.lg`   | Size        | Optical size; also rescales `.avatar-stack`. |
 
 `.avatar` works on `div`, `a` and `button`. The status dot is an empty
 `.badge` inside an `.avatar`, and needs an `aria-label` of its own.

package/docs/pages/components/badge.md

@@ -4,17 +4,18 @@
 
 - Supports intent colors.
 - Soft by default. Use `.solid` for counters and notification badges, or `.outline` for quieter emphasis.
-- Dots stay solid regardless of variant.
-- Use `.sm` or `.lg` for compact density changes.
+- Empty badges are solid status dots: visual variants such as `.soft` and `.outline` do not change their fill.
+- Use `.sm` or `.lg` to scale the badge locally.
+- Use `.compact` or `.spacious` on a context to change geometry without changing the label or icon size.
 - Can be used inline in headings.
 - Can be used as a count badge.
 - Can be used as a stable dot badge when empty and given an accessible name.
 - Empty badges render as dots. The element must be truly empty: no text and no whitespace.
 
 A badge is **content-sized**: it never stretches to fill its container, even as a
-direct child of `.stack` (where flex children otherwise stretch). Use
-`inline-size: 100%` — or the optional `.inline-size-full` utility — when a
-full-width badge is intentional.
+direct child of `.stack` (where flex children otherwise stretch), and a flex
+parent never compresses it (`flex: none`). Use `inline-size: 100%` — or the
+optional `.inline-size-full` utility — when a full-width badge is intentional.
 
 **Related terms:** chip, tag, pill, removable tag.
 
@@ -24,9 +25,10 @@ full-width badge is intentional.
 | --------------- | ----------- | ----------------------------------------- |
 | `.badge`        | Component   | Compact label; soft by default.           |
 | `.badge:empty`  | Composition | Truly-empty badge renders as a solid dot. |
+| `.dot`          | Composition | Status dot inside a badge.                |
 | Shared intents  | Intent      | `.primary`, `.secondary`, `.success`, …   |
 | Shared variants | Variant     | `.solid`, `.outline`, `.surface`.         |
-| `.sm` / `.lg`   | Size        | Compact density.                          |
+| `.sm` / `.lg`   | Size        | Smaller or larger optical scale.          |
 
 The shared intents are `.primary`, `.secondary`, `.success`, `.warning` and
 `.danger`. The variants set emphasis: `.solid` is filled, `.outline` bordered,
@@ -42,6 +44,9 @@ The shared intents are `.primary`, `.secondary`, `.success`, `.warning` and
 <span class="badge danger">Danger</span>
 <span class="badge success outline">Outline success</span>
 <span class="badge warning soft">Soft warning</span>
+<span class="badge primary solid">Solid primary</span>
+<span class="badge success solid">Solid success</span>
+<span class="badge danger solid">Solid danger</span>
 ```
 
 ## In a title
@@ -73,6 +78,29 @@ The shared intents are `.primary`, `.secondary`, `.success`, `.warning` and
 An autonomous dot conveys state without visible text, so give it an accessible
 name.
 
+For a dot beside a label, put the shared `.dot` utility inside the badge. It
+paints with `currentColor`, so it follows the badge ink instead of needing the
+intent class repeated on it.
+
+```html demo
+<span class="badge warning">
+  <span class="dot" aria-hidden="true"></span>
+  In progress
+</span>
+<span class="badge danger">
+  <span class="dot" aria-hidden="true"></span>
+  Blocked
+</span>
+<span class="badge success">
+  <span class="dot" aria-hidden="true"></span>
+  Completed
+</span>
+```
+
+Custom status or category dots define a custom intent (`--intent` /
+`--intent-fg`); `--ui-*` controls treatment, while empty dots intentionally
+remain solid.
+
 ## Color marker
 
 Use an empty badge as a compact intent-colored marker in legends and status
@@ -87,9 +115,64 @@ Regular
 ## Size variants
 
 ```html demo
-<span class="badge success sm">Small Success</span>
-<span class="badge success">Regular Success</span>
-<span class="badge success lg">Large Success</span>
+<span class="badge success sm">Small</span>
+<span class="badge success">Default</span>
+<span class="badge success lg">Large</span>
+```
+
+## Density
+
+Density changes the pill geometry without scaling its label or icon.
+
+```html demo
+<span class="compact"><span class="badge success">Compact</span></span>
+<span><span class="badge success">Default</span></span>
+<span class="spacious"><span class="badge success">Spacious</span></span>
+```
+
+## With an icon
+
+Decorative SVG, image, or `[aria-hidden="true"]` children follow
+`--badge-icon-size`.
+
+```html demo
+<span class="badge success">
+  <i class="ti ti-rosette-discount-check" aria-hidden="true"></i>
+  Verified
+</span>
+<span class="badge warning">
+  <i class="ti ti-clock" aria-hidden="true"></i>
+  Pending
+</span>
+<span class="badge danger solid">
+  <i class="ti ti-alert-circle" aria-hidden="true"></i>
+  Failed
+</span>
+```
+
+## Loading status
+
+A decorative spinner follows the badge color and optical size.
+
+```html demo
+<span class="badge danger sm">
+  <span class="spinner" aria-hidden="true"></span>
+  Deleting
+</span>
+<span class="badge sm">
+  Generating
+  <span class="spinner" aria-hidden="true"></span>
+</span>
+```
+
+## Custom sizing
+
+Override the existing hooks when the three-step scale does not fit the content.
+
+```html demo
+<span class="badge primary" style="--badge-size: 2rem; --badge-font-size: var(--font-size-md);">
+  Prominent
+</span>
 ```
 
 ## Removable tag pattern
@@ -98,17 +181,17 @@ Use `.badge soft` for tag visuals. Add a direct dismiss button only when the tag
 For a compact action or filter, use `.btn.sm` instead; badges describe content
 and must not be turned into toggle controls merely to obtain a compact shape.
 
+Leave the dismiss button empty: it paints its own X, so the pattern needs no
+icon font and no text glyph. Put your own icon inside it and that content is
+used instead.
+
 ```html demo
 <span class="badge primary soft">
   Design
-  <button type="button" aria-label="Remove Design">
-    <i class="ti ti-x" aria-hidden="true"></i>
-  </button>
+  <button type="button" aria-label="Remove Design"></button>
 </span>
 <span class="badge primary soft">
-  <button type="button" aria-label="Remove Design">
-    <i class="ti ti-x" aria-hidden="true"></i>
-  </button>
+  <button type="button" aria-label="Remove Design"></button>
   Design
 </span>
 ```
@@ -119,4 +202,6 @@ and must not be turned into toggle controls merely to obtain a compact shape.
 - `--badge-size` — minimum block size; also the square size of an `:empty` dot badge.
 - `--badge-dot-size` — size of an `:empty` dot badge.
 - `--badge-font-size` — label font size.
-- `--badge-pad-x` — inline padding.
+- `--badge-icon-size` — decorative child size; `1em` follows the label by default.
+- `--badge-pad-x` — inline padding. Derived from `--badge-size`, so it stays proportional to the pill; set it to opt out.
+- `--badge-dismiss-icon-size` — size of the X painted by an empty dismiss button.

package/docs/pages/components/button.md

@@ -110,21 +110,29 @@ Always name it with an `aria-label` since there is no visible text.
 
 ### Button groups
 
-Join adjacent buttons with `.join`. The joined group is not a new component —
-the buttons keep their own variants.
+Join adjacent buttons with `.join`. The joined group is not a new component:
+each button keeps its own classes, and `.join` only reshapes the outer corners
+and collapses the shared edges.
 
 ```html demo
-<div class="join" role="group" aria-label="Text alignment">
-  <button class="btn" type="button">Left</button>
-  <button class="btn outline" type="button">Center</button>
-  <button class="btn soft" type="button">Right</button>
+<div class="join" role="group" aria-label="Row actions">
+  <button class="btn outline" type="button">Edit</button>
+  <button class="btn outline" type="button">Duplicate</button>
+  <button class="btn outline" type="button">Archive</button>
 </div>
 ```
 
+Keep one variant family inside a group. Because each button keeps its own
+classes, nothing stops `.btn`, `.btn outline` and `.btn soft` from sitting side
+by side — but three fills and three border treatments in one shape read as
+unrelated controls that happen to touch, not as one unit. Change the variant
+only to carry meaning: [Toggle](#toggle) marks the active segment with a solid
+button among outlines, which is the pattern a segmented control wants.
+
 ## Sizes
 
-Prefer `.sm` and `.lg` over setting sizes directly. Density variants never
-change typography.
+Prefer `.sm` and `.lg` over setting sizes directly. They scale control geometry
+and typography together; `.compact` and `.spacious` only change density.
 
 ```html demo
 <div class="cluster">

package/docs/pages/components/card.md

@@ -4,14 +4,14 @@ Flexible content container with optional header, body, and footer regions, plus
 
 ## Class reference
 
-| Class       | Kind             | Description                                 |
-| ----------- | ---------------- | ------------------------------------------- |
-| `.card`     | Component        | Neutral raised surface for grouped content. |
-| `.raised`   | Variant          | Elevated surface with a soft shadow.        |
-| `.subtle`   | Variant          | Lower contrast against the page surface.    |
-| `.surface`  | Variant          | The page surface; intent in the text only.  |
-| `.inverted` | Surface modifier | Inverse surface treatment.                  |
-| `.compact`  | Variant          | Tighter padding for dense contexts.         |
+| Class       | Kind             | Description                                     |
+| ----------- | ---------------- | ----------------------------------------------- |
+| `.card`     | Component        | Neutral raised surface for grouped content.     |
+| `.raised`   | Variant          | Elevated surface with a soft shadow.            |
+| `.subtle`   | Variant          | Lower contrast against the page surface.        |
+| `.surface`  | Variant          | The page surface; intent in the text only.      |
+| `.inverted` | Surface modifier | Inverse surface treatment.                      |
+| `.compact`  | Density          | Tighter padding and compact descendant context. |
 
 `.surface` is a shared variant: it paints the page surface instead of
 `--surface-raised` and leaves the intent to the text.
@@ -88,7 +88,7 @@ colored headers, or footers.
       <p class="muted">For growing products</p>
     </hgroup>
     <p>
-      <span style="font-size: 2rem; font-weight: var(--font-weight-strong); line-height: 1">$24</span>
+      <span style="font-size: 2rem; font-weight: var(--font-weight-semibold); line-height: 1">$24</span>
       <span class="muted">/ user / month</span>
     </p>
   </header>
@@ -220,4 +220,4 @@ treatments on either side of it.
 - `--card-radius` — corner radius.
 - `--card-max-inline-size` — maximum width.
 - `--card-pad` — inner padding; also drives the negative offsets that let a `.bleed` child reach the card edge. `.compact` lowers it.
-- `--card-gap` — space between direct children of a bare card. A composed layout primitive owns its own gap instead. `.compact` does not change this hook.
+- `--card-gap` — space between direct children of a bare card. A composed layout primitive owns its own gap instead.

package/docs/pages/components/dialog.md

@@ -167,7 +167,13 @@ Use `modal scrollable` when the header and footer should stay visible while the
 dialog body scrolls. Modal dialogs lock page scroll while a modal is open: the
 runtime writes `html.has-modal-open`, and the stylesheet applies `overflow:
 hidden` (and reserves the scrollbar gutter with `scrollbar-gutter: stable` when
-one was present).
+one was present). The height cap follows the small viewport, so the panel keeps
+a stable size while mobile browser chrome expands or collapses.
+
+The scrolling body is a scroll container, and browsers make one
+keyboard-focusable so it can be scrolled without a pointer — it takes a focus
+ring like any other focusable element, and it can claim initial focus when
+nothing focusable precedes it. Mark the control you want focused `autofocus`.
 
 ```html demo
 <button class="btn"
@@ -213,8 +219,15 @@ one was present).
 
 ## Overlays inside modals
 
-Flyouts and tooltips opened from inside a modal dialog are mounted inside the
-dialog so they stay in the same top-layer context.
+Flyouts and tooltips opened from inside a modal dialog stay exactly where they
+are authored. The runtime promotes them to the top layer instead of moving
+them, which is what keeps them inside every scope that reaches them by
+inheritance.
+
+Author them inside the dialog. Promotion paints an element above a modal, but
+it does not lift it out of the modal's inertness — that is computed on the DOM,
+not on paint order — so an overlay authored outside the dialog would be
+promoted above it and still unclickable.
 
 ```html demo
 <button class="btn"
@@ -295,7 +308,7 @@ Available options:
 ## Browser support
 
 Actual relies on the native `<dialog>` API in its supported JavaScript range
-(Safari 15.4+, Firefox 98+, Chromium 99+). No dialog polyfill or fallback shim
+(Safari 17+, Firefox 125+, Chromium 116+). No dialog polyfill or fallback shim
 is shipped.
 
 ## Animation
@@ -306,7 +319,7 @@ remain in the top layer while `display` and `overlay` transition out. Browsers
 without that support keep native close behavior.
 
 The open dialog root intentionally ends at `transform: none`; fixed flyouts and
-tooltips mounted inside a modal dialog rely on viewport coordinates.
+tooltips authored inside a modal dialog rely on viewport coordinates.
 
 ### View transition
 
@@ -362,7 +375,9 @@ Keep the button a direct child of `dialog.modal` so the scrolling content
 
 ## CSS hooks
 
-- `--modal-size` — maximum dialog width.
+- `--modal-size` — maximum dialog width. Fallback-only, so a class on the
+  dialog or an inherited value both reach it. A dialog is shrink-to-fit: a
+  composition that must fill this width sets `inline-size` as well.
 - `--dialog-viewport-gap` — distance kept between the dialog and the viewport edges.
 - `--dialog-icon-size` — diameter of the `.dialog-icon` circle.
 - `--dialog-icon-glyph-size` — size of the glyph centered inside `.dialog-icon`.

package/docs/pages/components/drawer.md

@@ -21,8 +21,21 @@
 - Use `closedby="none"` when the drawer must not be dismissed by the user at all
   (e.g. a form with unsaved changes): no backdrop close and no Escape close.
 - Use `[data-side="end"]` for a right-side drawer.
+- Put the body between a `header` and a `footer`: the panel is a three-row grid
+  whose middle region scrolls, so the footer stays reachable however long the
+  content gets.
 - Permanent desktop sidebars belong in layout, not here.
 
+The panel is `--viewport-block` tall, so it follows the space a mobile browser
+actually leaves on screen as its URL bar collapses. A shell that fakes a
+viewport (an embedded preview) overrides that token rather than the drawer.
+
+The body region is a scroll container, and browsers make one keyboard-focusable
+so it can be scrolled without a pointer — it takes a focus ring like any other
+focusable element. `showModal()` focuses the first focusable thing in the
+drawer, so put the close button in the `header` (as both examples do) or mark
+your intended target `autofocus`; otherwise the body claims initial focus.
+
 ```html demo
 <button class="btn ghost"
         type="button"

package/docs/pages/components/fab.md

@@ -96,7 +96,7 @@ does not close automatically after an action, on outside click, or on Escape;
 add application behavior only when the product requires those policies.
 
 Each `.fab-action` keeps its `.fab-label` and secondary button on one compact
-line. The example uses the button's existing `.lg` density for 44px secondary
+line. The example uses the button's existing `.lg` size for 44px secondary
 actions and its `--btn-min-size` hook for a dominant 56px trigger. Size still
 belongs to Button rather than introducing FAB-specific size modifiers.
 Unlike the plain FAB, the speed dial trigger takes no icon: FAB owns it as a
@@ -120,5 +120,6 @@ two states stay visually identical in size and stroke.
 - `--fab-gap` — gap between actions and between the trigger and action list.
 - `--fab-icon-size` — size of the speed dial toggle's open and close markers.
 
-FAB is hidden in print and uses `--z-menu`, leaving tooltips and status UI above
-it. Dialogs remain in the browser's top layer.
+FAB uses `--z-menu`, leaving `status-bar` above it on the scale. Open flyouts
+and tooltips are promoted to the top layer and paint above it whatever their
+number. Dialogs remain in the browser's top layer.

package/docs/pages/components/list.md

@@ -29,9 +29,15 @@ list markers when order or bullets carry meaning.
 ```
 
 Leading and trailing content are unconstrained: avatars, native choices,
-badges, text, switches, and buttons retain their own component sizing. The
-middle region has no minimum content floor, so supporting text and long tokens
-wrap instead of widening the page.
+badges, text, switches, and buttons retain their own component sizing.
+`.list-item-content` has no minimum content floor, so supporting text and long
+tokens wrap instead of widening the page.
+
+Both outer regions are optional, and an absent one costs neither space nor a
+gap: `.list-item-content` always takes the row's free space and
+`.list-item-trailing` always sits on the end edge, whether the row has a
+leading region or not. A settings row — a label, a description, and one
+control on the end edge — is the two-region form.
 
 Regions align to the row's first line: the leading check or avatar, the title,
 and the trailing metadata or control sit on one horizontal line while
@@ -42,6 +48,30 @@ A pure traversal affordance such as a trailing caret can opt out of the
 first-line rule on its own item with `align-self: center`, keeping metadata
 rows unaffected.
 
+```html demo
+<ul class="list">
+  <li class="list-item">
+    <label class="list-item-content" for="row-memory">
+      <span class="list-item-title">Memory</span>
+      <span class="list-item-text">Remember details across conversations.</span>
+    </label>
+    <span class="list-item-trailing">
+      <input class="switch" type="checkbox" role="switch" id="row-memory" checked>
+    </span>
+  </li>
+  <li class="list-item">
+    <label class="list-item-content list-item-title" for="row-theme">Theme</label>
+    <span class="list-item-trailing">
+      <select class="select sm fit" id="row-theme">
+        <option>System</option>
+        <option>Light</option>
+        <option>Dark</option>
+      </select>
+    </span>
+  </li>
+</ul>
+```
+
 For a navigable row, keep the list semantics and put `.list-item` on the link:
 
 ```html demo
@@ -62,10 +92,18 @@ For a navigable row, keep the list semantics and put `.list-item` on the link:
 Do not attach click JavaScript to the entire row. Use a link for navigation and
 a button or native control for actions.
 
+In a master/detail navigation, mark the current row with `aria-current` on its
+link, using the value that matches the semantics (`page`, `location`, …).
+Presence is the contract: set the attribute on the current row and remove it
+elsewhere, never `aria-current="false"`. The [Workspaces example](../examples/overview.md)
+shows a current row with trailing actions and a flyout. Navigable rows usually
+want a non-zero `--list-item-pad-inline`: without that gutter, the current
+indicator touches the leading region and the trailing touches the row edge.
+
 ### Hooks
 
 - `--list-item-min-size` controls the row's minimum touch height.
 - `--list-item-pad-block` and `--list-item-pad-inline` control row padding.
-- `--list-item-gap` controls spacing between the three regions.
+- `--list-item-gap` controls spacing between the regions a row actually has.
 - `--list-divider` controls the leading and inter-row dividers. The final row
   deliberately has no trailing divider.