actual-css 0.7.0 → 0.9.0

package/docs/pages/components/navbar.md

@@ -7,6 +7,9 @@
 - `.navbar-nav` is the horizontal link list; its items are `.nav-link`.
 - `.nav-list` is the shared vertical navigation list, reused by `.drawer` for stacked links.
 - Mark the current page with `aria-current="page"` on the active `.nav-link`.
+- Presence is the contract: set `aria-current` on the current link and remove
+  it elsewhere, never `aria-current="false"`. Scrollspy follows the same rule
+  with `aria-current="location"`.
 
 For a public or normally scrolling page, `.navbar` belongs inside the semantic
 site header. Do not use `.topbar` or `.app-layout` unless the page actually has
@@ -16,6 +19,13 @@ the specialized persistent application-shell behavior those APIs describe.
 flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
 `.nav-list` (vertical) — pick one per container.
 
+`.navbar` stays the horizontal bar for a site or webapp header with a brand and
+normal document scrolling. `.app-nav` is not merely a stacked-icon flavour of it:
+reach for that component only when the destinations are part of a persistent
+application shell — bottom navigation or labelled side navigation via
+`.app-layout`. The choice follows the shell contract, not a preference for
+icons. See [App Navigation](app-navigation.md).
+
 ## Class reference
 
 | Class           | Kind        | Description                                           |
@@ -41,7 +51,9 @@ flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
 
 For a vertical sidebar nav, use `.nav-list` inside the drawer or sidebar.
 Links inside `.nav-list` stretch to the available inline size, providing a
-full-row hit target for vertical navigation.
+full-row hit target for vertical navigation. The [Workspaces example](../examples/overview.md)
+shows the sectioned-sidebar composition: grouped `.nav-list` blocks with
+section titles, a pinned account footer, and the native current state.
 
 ## Responsive: navbar + drawer
 
@@ -51,6 +63,10 @@ a `.drawer` with a vertical `.nav-list`, opened by a `command="show-modal"` /
 `commandfor` trigger. Keep that trigger outside the `<nav>` subtree you hide at
 narrow widths, or hiding the nav hides the control that opens it.
 
+When the compact layout drops labels, keep that text in the DOM and hide it
+visually instead of replacing it with `aria-label` strings: one source for the
+accessible name.
+
 ```html demo
 <nav class="navbar" aria-label="Main">
   <a class="navbar-brand" href="/">Actual CSS</a>

package/docs/pages/components/pagination.md

@@ -5,7 +5,7 @@
 - Use a semantic `<nav>` landmark.
 - Put `.pagination` on the ordered list.
 - Use `aria-current="page"` for the current page.
-- Put `.sm` or `.lg` on `.pagination` to change the density of its controls.
+- Put `.sm` or `.lg` on `.pagination` to scale its controls.
 - Numeric links may use `aria-label="Page N"` for clearer screen reader output.
 - Prefer text labels for Previous and Next. Icon-only controls need an accessible name.
 - Page links can compose with `.btn` for button-like hit targets.
@@ -17,7 +17,7 @@
 | Class         | Kind      | Description                    |
 | ------------- | --------- | ------------------------------ |
 | `.pagination` | Component | Ordered list of page controls. |
-| `.sm` / `.lg` | Size      | Control density.               |
+| `.sm` / `.lg` | Size      | Control geometry and type.     |
 
 ## Basic usage
 

package/docs/pages/components/skeleton.md

@@ -37,4 +37,6 @@
 - `--skeleton-highlight` — sweeping highlight color.
 - `--skeleton-radius` — corner radius; `data-shape` presets override it.
 - `--skeleton-size` — block size; `data-shape` presets override it.
-- `--skeleton-width` — inline size; `data-shape` presets override it.
+- `--skeleton-width` — maximum inline size. A placeholder fills its container
+  and stops here, so it never gives an ancestor a width floor. `data-shape`
+  presets set it; `avatar` ignores it and stays square.

package/docs/pages/components/steps.md

@@ -65,6 +65,25 @@ smaller than body text, and neutral in weight. Only the current step's label is
 emphasised — it is where you are now. A completed step needs no bold text; its
 filled marker already says as much.
 
+## Theming the states
+
+The complete and current states consume the shared
+`--state-selected` / `--state-selected-fg` tokens, which default to
+`--primary` / `--primary-fg`. A `--primary` recolor therefore flows through
+without any stepper-specific rule. To theme only this sequence with a local
+accent, override the tokens on the component:
+
+```css
+.checkout-steps {
+  --state-selected: var(--success);
+  --state-selected-fg: var(--success-fg);
+}
+```
+
+`--state-selected` drives the completed fill, connector and the current ring;
+`--state-selected-fg` corrects the number inside a completed marker when the
+accent needs a lighter ink.
+
 ## Horizontal steps
 
 `.steps-horizontal` is designed for **2 to 5 stages**.

package/docs/pages/components/table.md

@@ -100,8 +100,9 @@ table width before the wrapper scrolls horizontally.
 
 ## Compact tables
 
-`.compact` lowers the cell padding only — density never changes typography.
-It is the same vocabulary as `.card.compact`.
+`.compact` lowers cell padding and establishes compact density for controls or
+spacing helpers inside cells. Typography and icons stay unchanged. It is the
+same vocabulary as `.card.compact`.
 
 ```html demo
 <div class="table-wrap">

package/docs/pages/enhancements/flyout.md

@@ -19,8 +19,8 @@
 
 `.menu` has a strict `.menu > li > .menu-item` anatomy.
 | `.menu-label`     | Variant     | Muted section heading inside a menu; not interactive.                |
-| `.menu-separator` | Variant     | Divider between menu groups (`<hr role="separator">`).               |
-| `.sm` / `.lg`     | Variant     | Compact or large density.                                            |
+| `.menu-separator` | Variant     | Divider between menu groups (`<hr>`).                               |
+| `.sm` / `.lg`     | Size        | Smaller or larger menu rows and type.                                |
 
 ## Usage
 
@@ -28,7 +28,12 @@ Flyout and context menu share one action-surface runtime:
 
 - Flyout = a visible trigger opens a surface.
 - Context menu = right click or a keyboard context action opens that same surface.
-- Sheet = mobile presentation mode of that same surface.
+- Flyouts and context menus remain anchored, non-modal popovers at every viewport size.
+
+One surface is open at a time. Opening any of them closes the others, so a
+trigger placed inside an open panel replaces that panel instead of opening a
+second level. Submenus and other nested panels are outside the current
+contract.
 
 ### Trigger wiring
 
@@ -44,7 +49,8 @@ contract:
   context for the no-JS fallback: without it the panel lays out against the
   nearest positioned ancestor (or the page edge) instead of under the trigger.
 - Start the panel with `hidden` so it does not flash open before the runtime
-  hides and positions it.
+  takes it over. The runtime then removes the attribute: a closed panel is
+  hidden by the popover transport, and `[hidden]` would outrank it.
 
 ```html
 <div class="flyout-trigger">
@@ -57,16 +63,9 @@ contract:
 </div>
 ```
 
-Use `data-flyout-mobile` on the flyout to control mobile behavior:
-
-- `auto` is the default. It keeps the surface anchored on desktop and switches to a bottom sheet on coarse pointers below the breakpoint.
-- `sheet` always uses the sheet presentation.
-- `anchored` always uses floating positioning.
-- `none` disables the mobile transformation.
-
-`data-flyout-breakpoint` only matters for `auto`. Prefer the built-in tokens
-(`sm`, `md`, `lg`) and use raw pixel values only as an escape hatch, for example
-`data-flyout-breakpoint="640"`.
+For a modal bottom sheet or action sheet, use `dialog.drawer`; use
+`dialog.modal` for a centered modal. Those components own modal focus,
+dismissal, scroll locking, and backdrop behavior explicitly.
 
 Use `data-flyout-placement` for the preferred anchored placement. It accepts the
 placement strings supported by the floating runtime, such as `bottom-start`,
@@ -83,20 +82,21 @@ another library may therefore own opening, dismissal, and focus without
 requiring `.is-open` or `[hidden]`.
 
 Actual CSS does not position that independently managed popover. Its positioner
-must write fixed viewport coordinates (and may write `--available-height` and
-`--surface-anchor-width`); the built-in `surface.js` runtime remains the full
+must couple fixed positioning with viewport coordinates or absolute positioning
+with document coordinates (and may write `--available-height` and
+`--surface-anchor-width`). The built-in `surface.js` runtime remains the full
 fallback when Actual owns the lifecycle too. A bare `[popover]` without
 `.flyout` or `.tooltip` keeps its platform appearance.
 
-Native Popover is optional and is not part of Actual's Minimal contract:
-browsers within the Minimal range may not support it. Actual gates its own
-geometry reset behind `@supports selector(:popover-open)`, so an engine without
-Popover no longer gets a mispositioned panel — but that engine also never hides
-or promotes a `popover` element, so nothing dismisses the panel either.
+The Popover lifecycle is guaranteed across Minimal, so choosing it is a
+behavior decision rather than a support one: native light dismiss closes on
+outside clicks only, which cannot express `data-flyout-auto-close`. The two
+lifecycles are alternatives, not layers.
 
-When the lifecycle must work across the full Minimal range, use `surface.js`.
-Otherwise using the native lifecycle is an application support decision. The
-two are alternatives, not layers.
+`surface.js` itself uses `popover="manual"` as its transport — the panel is
+promoted to the top layer where it stands, so a scoped theme, density, or
+custom property still reaches it. That transport supplies no behavior, so the
+runtime keeps owning dismissal, Escape ordering, focus and placement.
 
 #### Choose one lifecycle owner
 
@@ -125,10 +125,12 @@ The native path, where the browser owns the lifecycle and the top layer:
 </ul>
 ```
 
-Do not combine them. `surface.js` opens a panel by clearing `[hidden]` and
-adding `.is-open`; it never calls `showPopover()`, so a `popover` element handed
-to the runtime has two owners and stays closed. The runtime logs a warning if it
-is asked to retain one.
+Do not combine them. `surface.js` writes `popover="manual"` on every panel it
+manages and drives `showPopover()` / `hidePopover()` itself, so a
+`popover="auto"` panel handed to the runtime has its mode overwritten — the
+runtime keeps one lifecycle owner rather than letting native light dismiss
+compete with `data-flyout-auto-close`. Keep `popovertarget` for panels the
+runtime does not enhance.
 
 **The native path still needs a positioner.** `popovertarget` gives the panel an
 implicit anchor reference to its invoker, but it does not place it: Actual's
@@ -198,9 +200,9 @@ A list of *actions* the user can take: sign out, copy, delete.
 - Flyout triggers are opt-in: add `data-enhance="flyout"` to the trigger.
 - Wrap the trigger and flyout in `.flyout-trigger` when the flyout should have a local absolute-position fallback before JavaScript positions it. Add `.stretch` when the trigger must span its container, such as the last row of a full-width sidebar nav list.
 - Use `<menu class="flyout menu">` with strict anatomy: `.menu > li > .menu-item`. Items must carry the `.menu-item` class to participate in directional keyboard navigation. ArrowUp/Down and Home/End move focus without rewriting their normal tab stops.
-- Use `.menu-label` on a `li` for a muted section heading inside a menu (e.g. a group title before its items). It is non-interactive and does not participate in roving focus. Use `.menu-separator` (`<hr role="separator">`) between groups.
+- Use `.menu-label` on a `li` for a muted section heading inside a menu (e.g. a group title before its items). It is non-interactive and does not participate in roving focus. Use `.menu-separator` (a plain `<hr>`) between groups.
 - Items are regular `<button>` or `<a>` elements.
-- Use `.sm` or `.lg` for density changes.
+- Use `.sm` or `.lg` to scale one flyout; use a density context for surrounding UI.
 - Add `role="menu"` / `role="menuitem"` only when you intentionally need the ARIA menu pattern described below.
 
 ```html demo
@@ -221,7 +223,7 @@ A list of *actions* the user can take: sign out, copy, delete.
         hidden>
     <li><button class="menu-item" type="button">Profile</button></li>
     <li><button class="menu-item" type="button">Settings</button></li>
-    <hr class="menu-separator" role="separator">
+    <hr class="menu-separator">
     <li><button class="menu-item danger" type="button">Sign out</button></li>
   </menu>
 </div>
@@ -239,6 +241,36 @@ tab stop instead.
 The runtime owns only focus movement and `tabindex`. The application still owns
 command state and updates attributes such as `aria-checked`.
 
+### Linting `role="menu"`
+
+Biome's `a11y/noNoninteractiveElementToInteractiveRole` reports
+`<menu role="menu">`, and the fix it offers — remove the role — dismantles the
+pattern. It is a port of
+`jsx-a11y/no-noninteractive-element-to-interactive-role` that lost the source
+rule's default allowlist, and that allowlist exists to permit exactly this
+markup: the source documents `<ul role="menu">` as *valid*, matching the
+WAI-ARIA APG menu button pattern. Every ARIA composite built on a list is
+affected, not only menus — `listbox`, `tablist`, `menubar`, `tree`, `grid`.
+
+Until it is fixed upstream, turn the rule off:
+
+```json
+{
+  "linter": {
+    "rules": {
+      "a11y": { "noNoninteractiveElementToInteractiveRole": "off" }
+    }
+  }
+}
+```
+
+One line, and no `biome-ignore` comment above every menu in your markup. The
+rest of the `a11y` group stays on and is worth keeping — with just this rule
+off, the menu anatomy above lints clean.
+
+[Accessibility decisions](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/accessibility-decisions.md)
+records which patterns Biome rejects, and which of its findings were right.
+
 ### Rich items and selection state
 
 Wrap rich item content in the three optional slots when a menu needs aligned
@@ -304,7 +336,6 @@ can be multi-column with `<section>` / `<ul>` groups.
       <div class="flyout"
            id="products-panel"
            aria-label="Products"
-           data-flyout-mobile="auto"
            hidden>
         <section aria-labelledby="products-design">
           <h3 id="products-design">Design</h3>
@@ -337,8 +368,8 @@ can be multi-column with `<section>` / `<ul>` groups.
 ## Mega menu
 
 Use `class="flyout grid-3"` when a nav panel needs multiple link groups. Keep
-links regular anchors and let the panel collapse to a one-column sheet on mobile
-with `data-flyout-mobile="auto"`.
+links as regular anchors. The panel remains an anchored popover on mobile; use
+a separate `dialog.drawer` when the content needs a modal mobile presentation.
 
 ```html demo
 <nav aria-label="Product navigation">
@@ -356,7 +387,6 @@ with `data-flyout-mobile="auto"`.
       <div class="flyout grid-3"
            id="product-mega-menu"
            aria-label="Platform"
-           data-flyout-mobile="auto"
            style="--flyout-inline-size: 42rem; --flyout-max-inline-size: 42rem"
            hidden>
         <section aria-labelledby="mega-design">
@@ -457,7 +487,7 @@ delay; a number sets the delay in milliseconds.
         hidden>
     <li><button class="menu-item" type="button">Open</button></li>
     <li><button class="menu-item" type="button">Rename</button></li>
-    <hr class="menu-separator" role="separator">
+    <hr class="menu-separator">
     <li><button class="menu-item danger" type="button">Delete</button></li>
   </menu>
 </div>
@@ -476,8 +506,22 @@ delay; a number sets the delay in milliseconds.
 
 ## CSS hooks
 
-- `--flyout-inline-size` — panel width.
-- `--flyout-max-inline-size` — panel width cap.
+- `--flyout-inline-size` — preferred width. Takes intrinsic values such as
+  `max-content`, its default.
+- `--flyout-max-inline-size` — width cap, a `<length-percentage>` the runtime
+  also clamps to the viewport. Defaults to `20rem`, independently of the
+  preferred width — the same way `width: 42rem; max-width: 20rem` renders at
+  20rem. A panel wider than the cap therefore sets both:
+
+  ```css
+  .mega-panel {
+    --flyout-inline-size: 42rem;
+    --flyout-max-inline-size: 42rem;
+  }
+  ```
+
+  The repetition is the point: the two hooks are different contracts, and only
+  the cap may enter the runtime's `min()`.
 - `--menu-item-size` — minimum row height of `.menu-item`.
 - `--menu-item-icon-size` — shared leading-column width for icons and checked-state indicators.
 

package/docs/pages/enhancements/overview.md

@@ -13,6 +13,31 @@ class API, shared tokens, and progressive enhancement.
 - Use shared button classes and variants for triggers.
 - Do not add toasts. Use alerts, status regions, dialogs, or inline validation instead.
 
+## Popover ownership
+
+Actual drives the top layer itself. On every surface and tooltip its runtime
+manages, `surface.js` and `tooltip.js` own the `popover` attribute and both
+`showPopover()` and `hidePopover()`.
+
+On a managed element, an application must not:
+
+- set or change `popover`. The runtime writes `manual` over any other value, because `popover="auto"` hands the browser a dismissal policy of its own that competes with `data-flyout-auto-close`.
+- call `showPopover()`, `hidePopover()`, or `togglePopover()`.
+- cancel its `beforetoggle`. Preventing an open leaves Actual's state saying open while the element is not in the top layer, and nothing repairs that — Actual owns the lifecycle rather than mediating it.
+
+To stop a surface from opening, cancel Actual's own `actual:surface-open`
+instead. It is dispatched before anything is promoted, so cancelling it leaves
+no state behind.
+
+**What counts as managed is the runtime's decision, not the attribute's.** A
+panel is managed when a `data-enhance="flyout"` trigger points at it through
+`aria-controls`, or when a `data-context-menu` target names it; a tooltip is
+managed when a `data-tooltip` trigger points at it. A `.flyout[popover]` or
+`.tooltip[popover]` that no such trigger reaches is never touched — Actual
+supplies its presentation and the application owns its lifecycle. That is the
+supported way to drive either class with `popovertarget` or a third-party
+lifecycle. Do not do both to the same element.
+
 ## Modules
 
 The full runtime is `actual-css/js/full`. Each enhancer is also importable on its own

package/docs/pages/enhancements/status-bar.md

@@ -15,7 +15,7 @@ runtime targets, empty by default.
 - Use it for transient status (`Saved.`, `Reconnected.`, `Copied.`). Critical, persistent, or actionable information belongs in `.alert`, inline messages, or dialogs.
 - Intents: `danger`, `success`, `warning`, `neutral`. The default (no intent) is a neutral dark pill.
 - On mobile, the runtime keeps the bar above the software keyboard by tracking `visualViewport` while a message is showing.
-- A message originating inside an open modal dialog temporarily moves the singleton bar into that dialog. This keeps it in the active top-layer and accessibility subtree; the bar returns to its original DOM position after its exit.
+- A message originating inside an open modal dialog temporarily moves the singleton bar into that dialog. A modal inerts the rest of the document, and being painted above it would not undo that — inertness is computed on the DOM — so the bar has to be in the dialog's subtree to be announced and seen. The bar returns to its original DOM position after its exit.
 
 Clearing is deferred, not immediate: the bar closes first and only empties its
 text and intent once the exit transition has finished, so it leaves at the size

package/docs/pages/enhancements/tabs.md

@@ -14,51 +14,59 @@
 
 - Use real tab semantics when panels switch in place.
 - Use normal links and `aria-current="page"` for page navigation that only looks like tabs.
+- On that link variant, `aria-current="page"` on the current link gets the same
+  color and underline treatment as `aria-selected="true"` on a widget tab;
+  `primary` tints it.
+- Tab selection never changes text metrics: the active tab keeps the shared
+  weight and is marked by color and the indicator line.
 - JavaScript owns roving `tabindex`, `aria-selected`, `hidden`, and keyboard behavior.
 - Left/Right select tabs and wrap at the ends. Home/End jump to first/last. Down moves focus into the selected panel.
 - A tab list needs both `.tabs` and `role="tablist"`; `.tab` styles each trigger.
 - A `.tab` with an icon uses `--tab-gap` (default `0.375em`) for the space between icon and label.
+- A tab that is `hidden`, `disabled`, `aria-disabled`, or has no panel is skipped
+  by the arrow keys. An application filtering a tab strip only has to set
+  `hidden`; deciding what to show when the selected tab is filtered out is the
+  application's call.
 
 ```html demo
 <div class="tabs" data-enhance="tabs" role="tablist" aria-label="Settings">
-    <button class="tab primary"
-            type="button"
-            role="tab"
-            aria-selected="true"
-            aria-controls="panel-general"
-            id="tab-general">
-      General
-    </button>
-    <button class="tab"
-            type="button"
-            role="tab"
-            aria-selected="false"
-            aria-controls="panel-security"
-            id="tab-security"
-            tabindex="-1">
-      Security
-    </button>
-    <button class="tab"
-            type="button"
-            role="tab"
-            aria-selected="false"
-            aria-controls="panel-billing"
-            id="tab-billing"
-            tabindex="-1">
-      Billing
-    </button>
-  </div>
-
-  <section role="tabpanel" id="panel-general" aria-labelledby="tab-general" tabindex="-1" class="py">
-    General content
-  </section>
-  <section role="tabpanel" id="panel-security" aria-labelledby="tab-security" tabindex="-1" hidden class="py">
-    Security content
-  </section>
-  <section role="tabpanel" id="panel-billing" aria-labelledby="tab-billing" tabindex="-1" hidden class="py">
-    Billing content
-  </section>
+  <button class="tab primary"
+          type="button"
+          role="tab"
+          aria-selected="true"
+          aria-controls="panel-general"
+          id="tab-general">
+    General
+  </button>
+  <button class="tab"
+          type="button"
+          role="tab"
+          aria-selected="false"
+          aria-controls="panel-security"
+          id="tab-security"
+          tabindex="-1">
+    Security
+  </button>
+  <button class="tab"
+          type="button"
+          role="tab"
+          aria-selected="false"
+          aria-controls="panel-billing"
+          id="tab-billing"
+          tabindex="-1">
+    Billing
+  </button>
 </div>
+
+<section role="tabpanel" id="panel-general" aria-labelledby="tab-general" tabindex="-1" class="py">
+  General content
+</section>
+<section role="tabpanel" id="panel-security" aria-labelledby="tab-security" tabindex="-1" hidden class="py">
+  Security content
+</section>
+<section role="tabpanel" id="panel-billing" aria-labelledby="tab-billing" tabindex="-1" hidden class="py">
+  Billing content
+</section>
 ```
 
 For navigation that only looks like tabs, keep it a plain link list — no

package/docs/pages/enhancements/tooltip.md

@@ -5,11 +5,14 @@
 Tooltips are supplemental: `data-tooltip` on the trigger wires a `.tooltip`
 element (`role="tooltip"`) that appears near the trigger. Position, placement,
 and arrow position are written by JavaScript; the element is shown and hidden
-with the `hidden` attribute.
+by promoting it to the top layer with `popover="manual"`.
 
 - Use `data-tooltip` on the trigger. With text (`data-tooltip="Help"`), the tooltip element is generated. Empty (`data-tooltip`) marks an explicit tooltip connected via `aria-describedby`.
 - Tooltips are supplemental. Do not put required information or interactive controls inside them.
-- Show on hover and focus. Hide on Escape, blur, pointer leave, or scroll when appropriate.
+- Show on hover and focus. Hide on Escape, blur, or pointer leave.
+- A trigger scrolled out of view takes its tooltip down and brings it back when it returns; only a dismissal ends the tooltip.
+- Escape outlasts the hover and focus that justified the tooltip (WCAG 2.1 SC 1.4.13); showing it again takes a fresh hover or focus, not a second click on a trigger that already has focus.
+- Author an explicit tooltip with `hidden`. The runtime removes it when it takes the lifecycle over; until then it is what keeps the tooltip off screen.
 - JavaScript can generate tooltip elements from `data-tooltip`.
 - Add `data-tooltip-click` to toggle it on click instead of hover/focus.
 - Add `data-tooltip-visible` to show it immediately and keep it visible while its trigger is in view.
@@ -20,14 +23,28 @@ with the `hidden` attribute.
 A `.tooltip[popover]` may use a native or third-party-owned popover lifecycle.
 Actual removes the native inset, margin, and overflow that conflict with
 positioning and with the projecting arrow, while leaving bare `[popover]`
-elements untouched. The lifecycle owner must still write the fixed viewport
-coordinates and arrow position; Actual only supplies the presentation.
-
-That reset is gated on `@supports selector(:popover-open)`. Native Popover is
-optional and is not part of Actual's Minimal contract: browsers within the
-Minimal range may not support it, and there the attribute carries no behavior,
-so nothing shows or hides the tip. Use `data-tooltip` and the built-in runtime
-when the lifecycle must work across the full Minimal range.
+elements untouched. The lifecycle owner still writes `position`, the
+coordinates, and the arrow position; Actual only supplies the presentation.
+
+Do not combine them. `tooltip.js` writes `popover="manual"` on every tooltip it
+manages and calls `showPopover()` / `hidePopover()` itself, so a tooltip handed
+to the runtime has its mode overwritten. The runtime only ever reaches a
+tooltip that a `data-tooltip` trigger points at, so a `.tooltip[popover]` with
+no such trigger stays yours to drive. Use `data-tooltip` and the built-in
+runtime when Actual should own showing and hiding.
+
+**Where the element lives is part of the contract.** An explicit tooltip stays
+exactly where you wrote it, so it keeps every scope that reaches it by
+inheritance — a theme island, a density scope, `.inverted`, your own scoped
+custom properties. It also means placement is yours to get right: a tooltip
+used from inside a modal dialog must be authored inside that dialog, because
+the top layer does not lift an element out of a modal's inertness.
+
+A generated tooltip (`data-tooltip="Help"`) is Actual's to place, and it goes
+at document level rather than beside the trigger, so it cannot disturb the
+trigger's structural position — a generated sibling would take
+`.join > :last-child` from a trigger that ends a group. It therefore makes no
+inheritance promise. Use the explicit form when the local CSS context matters.
 
 ```html demo
 <button class="btn ghost"
@@ -98,6 +115,15 @@ viewport-aware maximum width.
 Set `data-tooltip-placement` to control where the tooltip appears relative to
 its trigger. The arrow follows the placement automatically.
 
+The runtime also picks the coordinate space, and writes `position` to match. A
+tooltip whose trigger scrolls with the page is placed in document coordinates
+and `position: absolute`, so the browser scrolls it with the page instead of
+the positioner correcting it a frame later — the lag visible while scrolling on
+a touch device. A trigger that is viewport-anchored — inside a fixed or sticky
+ancestor, an open popover, or a modal dialog — keeps `position: fixed`. Do not
+override `position` on a tooltip the runtime manages. See
+[Tooltip coordinate space](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/tooltip-coordinate-space.md).
+
 ```html demo
 <p>
   <button class="btn outline" type="button" data-tooltip="Above the button" data-tooltip-placement="top">Top</button>

package/docs/pages/examples/overview.md

@@ -9,19 +9,52 @@ and `actual.full.js` from `dist/`, plus the theme palettes bundle from
 
 ## Templates
 
-`demo/templates/` are standalone pages covering common page shapes.
+`demo/templates/` are standalone pages. The first three explain the system; the
+rest show it composed, isolated, or under stress.
+
+### Start here
+
+- [Visual guide](../../demo/templates/visual-guide.html) - seventeen illustrated figures on the spacing scale, the layout primitives, and density versus local size
+- [Color guide](../../demo/templates/color-guide.html) - theming principles measured live on `ocean` and `sunset`, in light and dark, as `data-theme` islands
+- [Kitchen sink](../../demo/templates/kitchen-sink.html) - one-screen test bed for themes, scopes, variants and interactions
+
+### Page shapes
+
+Whole pages, composed the way a real product would.
 
-- [Kitchen sink](../../demo/templates/kitchen-sink.html) - every component and variant on one page
-- [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
-- [Surface contracts](../../demo/templates/surfaces.html) - .inverted, cascade precedence, and the intent boundary
 - [Dashboard](../../demo/templates/dashboard.html) - data-heavy overview page
 - [App](../../demo/templates/app.html) - application shell with sidebar
+- [Workspaces](../../demo/templates/workspaces.html) - sectioned sidebar, master/detail list with native current state, and workspace cards
 - [Marketing](../../demo/templates/marketing.html) - landing page with typography and fluid type
 - [Blog](../../demo/templates/blog.html) - article page with prose
-- [Blocks](../../demo/templates/blocks.html) - layout building blocks
+- [Settings modal](../../demo/templates/settings-modal.html) - two-pane preferences dialog, with the local CSS it needs audited rule by rule
+- [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and a local segmented tab treatment
+- [Card compositions](../../demo/templates/card-compositions.html) - editorial, team, sign-in and horizontal cards composed from existing primitives
+
+### Layout references
+
+One mechanism at a time, with its contract and its pitfalls.
+
 - [Layout reference](../../demo/templates/layouts.html) - canonical compositions built only with the layout primitives
+- [Blocks](../../demo/templates/blocks.html) - layout building blocks
 - [Grid density](../../demo/templates/grid.html) - the grid contracts on resizable stages, with the pitfalls called out
+- [Column layout](../../demo/templates/column-layout.html) - the twelve-column canvas: spans, starts, and the narrow-container recomposition the framework leaves to the application
 - [Density](../../demo/templates/density.html) - compact control density
+
+### System benches
+
+Contracts you cannot read off a static screenshot: state, motion, focus, and
+extension points.
+
+- [Surface contracts](../../demo/templates/surfaces.html) - `.inverted`, cascade precedence, and the intent boundary
+- [Presence motion](../../demo/templates/motion.html) - status bar, tooltip, flyout, modal and drawer replayed side by side, with easing swaps and a reduced-motion simulation
+- [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
+- [Adaptive filter surface](../../demo/templates/adaptive-surface.html) - app-level flyout/drawer composition with one synchronized filter state
+- [Select intents](../../demo/templates/select-intents.html) - extending the enhancer with a project's own `data-enhance` behavior, injected markup included, with no framework change
+- [Popover transport probe](../../demo/templates/popover-transport.html) - self-scoring bench for the native popover transport go/no-go
+
+### Third-party components on Actual tokens
+
 - [Data grid](../../demo/templates/data-grid.html) - an external data grid component themed with Actual tokens (sort, filter, search, selection)
 - [Combobox](../../demo/templates/combobox.html) - an external combobox themed with Actual tokens (search, tags, autocomplete)
 

package/docs/pages/forms/choice-cards.md

@@ -88,7 +88,10 @@ Validation follows the shared pattern: `aria-invalid="true"` on the input (set m
 </fieldset>
 ```
 
-Sizes follow the shared `.sm` and `.lg` modifiers. Intent classes (`.primary`, `.secondary`) are supported on the `.choice-card` element.
+Sizes follow the shared `.sm` and `.lg` typography scale; the check indicator
+follows through its `em` sizing. Padding is density, so use a `.compact` or
+`.spacious` context to change it. Intent classes (`.primary`, `.secondary`) are
+supported on the `.choice-card` element.
 
 ## CSS hooks
 
@@ -100,8 +103,10 @@ Plain `.check` / `.radio` controls expose two hooks:
 
 - `--choice-control-size` — the control's own size, in `em` off the surrounding
   type. The switch track derives from it too, so a checkbox and a switch on the
-  same line stay proportionate. `.sm` / `.lg` do not touch it.
-- `--choice-control-offset` — top offset that aligns the control with the first
-  line of a multi-line label. Left unset, each control derives its own offset
-  from its height and the line box, which keeps a checkbox and a taller switch
-  level with each other. Setting one constant applies it to both.
+  same line stay proportionate. A `.choice.sm` or `.choice.lg` scales it through
+  the surrounding typography.
+- `--choice-control-nudge` — block correction added to the derived first-line
+  offset, for every control in the row. Left unset, each control centres itself
+  on the first line's cap height, measured from its own block size — so a
+  checkbox and a taller switch stay level with each other, and with the text,
+  whatever the font, line-height or control size.