actual-css 0.6.0 → 0.8.0

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.

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/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`,
@@ -74,8 +73,101 @@ placement strings supported by the floating runtime, such as `bottom-start`,
 
 Use `data-flyout-distance` for the trigger gap in pixels. The default is `4`.
 
-Use `data-flyout-auto-close` when the default click dismissal behavior is not
-right. Escape still follows the shared surface lifecycle.
+### Native popover lifecycle
+
+The `.flyout` presentation also composes with an element carrying `popover`.
+Actual neutralizes the native popover geometry that conflicts with anchored
+positioning and recognizes `:popover-open` as the visible state. The browser or
+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 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.
+
+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.
+
+`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
+
+The Actual runtime path, where `surface.js` owns opening, dismissal, focus and
+placement:
+
+```html
+<div class="flyout-trigger">
+  <button data-enhance="flyout" aria-controls="actions" aria-expanded="false">
+    Actions
+  </button>
+
+  <ul id="actions" class="flyout menu" hidden>
+    <li><button class="menu-item" type="button">Rename</button></li>
+  </ul>
+</div>
+```
+
+The native path, where the browser owns the lifecycle and the top layer:
+
+```html
+<button popovertarget="actions">Actions</button>
+
+<ul id="actions" class="flyout menu" popover>
+  <li><button class="menu-item" type="button">Rename</button></li>
+</ul>
+```
+
+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
+geometry reset clears the UA's centering, so an unpositioned native flyout is
+laid out at its static position rather than under its trigger. Supply
+coordinates the same way `surface.js` does:
+
+```js
+import { autoUpdate, reposition } from "@lekoala/floating";
+
+const trigger = document.querySelector("[popovertarget='actions']");
+const panel = document.getElementById("actions");
+
+// One tracker at a time. autoUpdate returns its own cleanup; releasing it
+// before every state change keeps repeated opens from stacking trackers, and
+// stops the scroll/resize work as soon as the panel closes.
+let stop;
+
+panel.addEventListener("toggle", (event) => {
+  stop?.();
+  stop = undefined;
+  if (event.newState !== "open") return;
+
+  stop = autoUpdate(trigger, panel, () => {
+    reposition(trigger, panel, { placement: "bottom-start", distance: 4 });
+  });
+});
+```
+
+CSS Anchor Positioning will eventually cover the simple anchored case from the
+stylesheet alone, using that implicit anchor reference. It is still only
+partially supported and is not the documented recipe yet.
+
+**When `surface.js` owns the lifecycle**, use `data-flyout-auto-close` if the
+default click dismissal behavior is not right. Escape still follows the shared
+surface lifecycle. These options do not reach a natively managed
+`popover="auto"`, whose dismissal belongs to the browser.
 
 - `true` is the default. Clicks inside or outside close the flyout.
 - `inside` closes on inside clicks only.
@@ -108,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
@@ -131,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>
@@ -149,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
@@ -214,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>
@@ -247,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">
@@ -266,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">
@@ -367,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>

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,6 +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. 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
@@ -77,6 +78,25 @@ document.dispatchEvent(new CustomEvent("actual:status", {
 }));
 ```
 
+Dispatch from the control or region that produced the feedback when it lives
+inside a dialog; bubbling lets the runtime infer the active surface:
+
+```js
+saveButton.dispatchEvent(new CustomEvent("actual:status", {
+  bubbles: true,
+  detail: { message: "Saved.", intent: "success" },
+}));
+```
+
+Code importing `status()` directly passes the same origin as `source`:
+
+```js
+status("Saved.", { intent: "success", source: saveButton });
+```
+
+Validation and declarative status commands propagate their source
+automatically.
+
 ## CSS hooks
 
 - `--status-bg` — bar background.

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.
@@ -17,6 +20,32 @@ with the `hidden` attribute.
 - The arrow inherits the tooltip background — custom gradients carry through automatically.
 - Avoid relying on the native `title` attribute as the primary implementation.
 
+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 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"
         type="button"
@@ -86,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>