actual-css 0.3.0 → 0.4.0

package/docs/pages/components/alert.md

@@ -16,18 +16,18 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.alert` | Component | Inline status surface; soft by default. |
-| `.alert-icon` | Composition | Decorative leading icon; pins to the first grid column. |
-| `.alert-dismiss` | Modifier | Compact dismiss button using the `--icon-close` mask and the `--dismiss` command. |
-| `.callout` | Variant | Neutral panel with a thick accent border on the leading edge. |
-| `.admonition` | Variant | Structured box with a tinted title bar and body on the page surface. |
-| `.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` and `.outline` 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; pins to the first grid column.                           |
+| `.alert-dismiss` | Modifier    | Compact dismiss button using the `--icon-close` mask and the `--dismiss` command. |
+| `.callout`       | Variant     | Neutral panel with a thick accent border on the leading edge.                     |
+| `.admonition`    | Variant     | Structured box with a tinted title bar and body on the page surface.              |
+| `.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` and `.outline` emphasis.                                                 |
+| `.sm` / `.lg`    | Size        | Density; inline padding stays stable.                                             |
 
 ## Basic usage
 
@@ -70,8 +70,10 @@
   <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
 
   <div class="stack">
-    <strong>Payment failed.</strong>
-    <p>Check your billing details or try another card.</p>
+    <div class="stack" style="--gap: var(--space-10)">
+      <strong>Payment failed.</strong>
+      <p>Check your billing details or try another card.</p>
+    </div>
 
     <menu class="actions cluster">
       <li><a class="btn danger sm" href="/billing">Update billing</a></li>

package/docs/pages/components/aura.md

@@ -1,6 +1,6 @@
 # Aura
 
-> **Optional** — import `actual-css/css/optional/aura` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/effects/aura` or `actual-css/css/effects`.
 
 Aura adds a decorative intent-colored border and halo around one direct child.
 It is visual emphasis only and does not change the child's semantics.

package/docs/pages/components/avatar.md

@@ -12,12 +12,12 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.avatar` | Component | Initials or image in a circular box; works on `div`, `a`, and `button`. |
-| `.avatar-stack` | Composition | Overlapping avatar group. |
-| `.badge:empty` (inside `.avatar`) | Composition | Status dot at the bottom-end corner; give it an `aria-label`. |
-| `.sm` / `.lg` | Size | Density; also rescales the whole `.avatar-stack`. |
+| Class                             | Kind        | Description                                                             |
+|-----------------------------------|-------------|-------------------------------------------------------------------------|
+| `.avatar`                         | Component   | Initials or image in a circular box; works on `div`, `a`, and `button`. |
+| `.avatar-stack`                   | Composition | Overlapping avatar group.                                               |
+| `.badge:empty` (inside `.avatar`) | Composition | Status dot at the bottom-end corner; give it an `aria-label`.           |
+| `.sm` / `.lg`                     | Size        | Density; also rescales the whole `.avatar-stack`.                       |
 
 ## Basic usage
 

package/docs/pages/components/badge.md

@@ -18,13 +18,13 @@ full-width badge is intentional.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.badge` | Component | Compact label; soft by default. |
-| `.badge:empty` | Composition | Truly-empty badge renders as a solid dot. |
-| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
-| Shared variants | Variant | `.solid` (filled) and `.outline` (bordered) emphasis. |
-| `.sm` / `.lg` | Size | Compact density. |
+| Class           | Kind        | Description                                                  |
+|-----------------|-------------|--------------------------------------------------------------|
+| `.badge`        | Component   | Compact label; soft by default.                              |
+| `.badge:empty`  | Composition | Truly-empty badge renders as a solid dot.                    |
+| Shared intents  | Intent      | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
+| Shared variants | Variant     | `.solid` (filled) and `.outline` (bordered) emphasis.        |
+| `.sm` / `.lg`   | Size        | Compact density.                                             |
 
 ## Basic usage
 

package/docs/pages/components/button.md

@@ -4,22 +4,22 @@ Actions and navigation with shared intents, variants, sizes, and loading, presse
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.btn` | Component | Base button. Solid by default; works on `<button>`, `<a href>`, and button-like `<input>`. |
-| `.primary` | Intent | Primary action. |
-| `.secondary` | Intent | Secondary action. |
-| `.success` | Intent | Positive outcome. |
-| `.warning` | Intent | Caution. |
-| `.danger` | Intent | Destructive action. |
-| `.neutral` | Intent | Neutral tone (the `.btn` default). |
-| `.soft` | Variant | Muted intent-tinted surface. |
-| `.outline` | Variant | Transparent with an intent-colored border. |
-| `.solid` | Variant | Filled intent background — the `.btn` default. |
-| `.ghost` | Variant | Borderless text button (button-only). |
-| `.link` | Variant | Underlined text button (button-only). |
-| `.sm` / `.lg` | Size | Compact or large control height. |
-| `.icon-only` | Variant | Square icon button sized to the control height. |
+| Class         | Kind      | Description                                                                                |
+|---------------|-----------|--------------------------------------------------------------------------------------------|
+| `.btn`        | Component | Base button. Solid by default; works on `<button>`, `<a href>`, and button-like `<input>`. |
+| `.primary`    | Intent    | Primary action.                                                                            |
+| `.secondary`  | Intent    | Secondary action.                                                                          |
+| `.success`    | Intent    | Positive outcome.                                                                          |
+| `.warning`    | Intent    | Caution.                                                                                   |
+| `.danger`     | Intent    | Destructive action.                                                                        |
+| `.neutral`    | Intent    | Neutral tone (the `.btn` default).                                                         |
+| `.soft`       | Variant   | Muted intent-tinted surface.                                                               |
+| `.outline`    | Variant   | Transparent with an intent-colored border.                                                 |
+| `.solid`      | Variant   | Filled intent background — the `.btn` default.                                             |
+| `.ghost`      | Variant   | Borderless text button (button-only).                                                      |
+| `.link`       | Variant   | Underlined text button (button-only).                                                      |
+| `.sm` / `.lg` | Size      | Compact or large control height.                                                           |
+| `.icon-only`  | Variant   | Square icon button sized to the control height.                                            |
 
 ## Basic usage
 
@@ -56,6 +56,11 @@ Shared intent classes set color meaning. They compose with every variant.
 `.ghost` and `.link` are button-only; `.soft`, `.outline`, and `.solid` are
 shared with other components.
 
+Transparent treatments (`.outline`, `.ghost`, `.link`) follow the surrounding
+foreground by default, including on a contrasting `.inverted` surface. A local
+intent class still wins: `.danger.outline` uses the danger color in either
+context. Filled buttons own their surface and keep their normal intent recipe.
+
 ```html demo
 <div class="cluster">
   <button class="btn outline" type="button">Outline</button>
@@ -202,4 +207,4 @@ For exclusive groups, manage a single pressed button:
 
 - `--btn-radius` — corner radius.
 - `--btn-focus-color` — focus ring base color; the ring itself is derived from it.
-- `--btn-gap` — space between an icon and the label text (default `0.375em`).
+- `--btn-gap` — space between an icon and the label text (default `0.375em`).

package/docs/pages/components/card.md

@@ -4,19 +4,21 @@ 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. |
+| 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.                                                                                                                                                                        |
 | `.inverted` | Surface modifier | Inverse surface treatment: paints `--surface-solid` and swaps the foreground to `--surface`, so it inverts in dark themes instead of always reading as dark. Apply as `class="card inverted"`, or on any block. |
-| `.compact` | Variant | Tighter padding for dense contexts. |
+| `.compact`  | Variant          | Tighter padding for dense contexts.                                                                                                                                                                             |
 
 ## Basic usage
 
 Use semantic elements inside the card. A direct `<header>` or `<footer>` is the
-card's structural slot. Cards do not own page spacing — compose them with
-layout primitives like `.grid`.
+card's structural slot. A direct `<footer>` is anchored to the bottom of the
+card when extra block space is available, so prices and actions line up across
+equal-height cards. Cards do not own page spacing — compose them with layout
+primitives like `.grid`.
 
 ```html demo
 <div style="max-inline-size: 32rem">
@@ -95,7 +97,9 @@ colored headers, or footers.
 
 ## In grids
 
-Cards display nicely in grids with equal-height behavior.
+Cards display nicely in grids with equal-height behavior. Each card in a row
+stretches to the row height, and a direct `<footer>` anchors to the bottom, so
+all footers in the row line up regardless of body length.
 
 ```html demo
 <section class="grid">
@@ -133,9 +137,21 @@ Cards display nicely in grids with equal-height behavior.
 
 ## Surfaces
 
-`.inverted` is the generic inverse surface treatment, not a card-specific class:
-it works on any block (`<header class="inverted">`, `<section class="inverted">`,
-or `class="card inverted"`) through the shared `--ui-*` contract.
+`.inverted` creates a contrasting surface context, not a complete theme island.
+On a bare block (`<header class="inverted">`, `<section class="inverted">`) it
+paints the surface directly; contextual content and transparent treatments such
+as `.btn.outline`, `.btn.ghost`, and `.btn.link` follow its foreground.
+
+Apply it directly to a component that consumes the shared `--ui-*` surface
+contract (`.card`, `.navbar`, `.alert`, `.badge`) to treat that component as the
+contrasting surface. A surface-owning component nested inside an inverted block
+keeps its own surface and establishes a new context for its descendants. Use a
+`data-theme` island when every component and form control in a subtree must use
+another theme.
+
+More specific component states or explicit surface variants still take
+precedence: `.card.inverted.subtle` keeps the `.subtle` background while the
+foreground stays inverted.
 
 `.inverted` and `.subtle` are competing surface treatments — do not combine
 them. `.subtle` paints the card's background directly while `.inverted` swaps
@@ -180,4 +196,4 @@ variants.
 
 - `--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-pad` — inner padding; also drives the negative offsets that let a `.bleed` child reach the card edge. `.compact` lowers it.

package/docs/pages/components/chat.md

@@ -1,6 +1,6 @@
 # Chat
 
-> **Optional** — import `actual-css/css/optional/chat` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/components/chat` or `actual-css/css/components`.
 
 Chat lays out message metadata, an optional avatar, and a content-sized bubble
 at either edge of a conversation.
@@ -36,13 +36,13 @@ put `role="log"` on individual messages.
 
 ## Class reference
 
-| Class | Description |
-|---|---|
-| `.chat` | Message row grid. |
-| `.chat-start` / `.chat-end` | Logical inline placement. |
-| `.chat-avatar` | Avatar grid slot; compose it with `.avatar`. |
-| `.chat-header` / `.chat-footer` | Muted message metadata. |
-| `.chat-bubble` | Content-sized message surface. |
+| Class                           | Description                                  |
+|---------------------------------|----------------------------------------------|
+| `.chat`                         | Message row grid.                            |
+| `.chat-start` / `.chat-end`     | Logical inline placement.                    |
+| `.chat-avatar`                  | Avatar grid slot; compose it with `.avatar`. |
+| `.chat-header` / `.chat-footer` | Muted message metadata.                      |
+| `.chat-bubble`                  | Content-sized message surface.               |
 
 ## CSS hooks
 

package/docs/pages/components/dialog.md

@@ -4,13 +4,13 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.modal` | Component | Centered modal surface built on the native `<dialog>` element. |
-| `.scrollable` | Variant | Keeps the header and footer visible while the dialog body scrolls. |
-| `.dialog-confirmation` | Variant | Separates a confirmation message from its full-width action band. |
-| `.dialog-icon` | Component | Circular intent-aware icon well for confirmation messages. |
-| `.dialog-close` | Component | Icon-only close button anchored to the modal's top end, out of the content flow. |
+| Class                  | Kind      | Description                                                                      |
+|------------------------|-----------|----------------------------------------------------------------------------------|
+| `.modal`               | Component | Centered modal surface built on the native `<dialog>` element.                   |
+| `.scrollable`          | Variant   | Keeps the header and footer visible while the dialog body scrolls.               |
+| `.dialog-confirmation` | Variant   | Separates a confirmation message from its full-width action band.                |
+| `.dialog-icon`         | Component | Circular intent-aware icon well for confirmation messages.                       |
+| `.dialog-close`        | Component | Icon-only close button anchored to the modal's top end, out of the content flow. |
 
 ## Usage
 

package/docs/pages/components/drawer.md

@@ -4,9 +4,9 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.drawer` | Component | Modal side-sheet built on the native `<dialog>` element. |
+| Class           | Kind      | Description                                                |
+|-----------------|-----------|------------------------------------------------------------|
+| `.drawer`       | Component | Modal side-sheet built on the native `<dialog>` element.   |
 | `.drawer-close` | Component | Icon-only close button that sits inside the drawer header. |
 
 ## Usage

package/docs/pages/components/fab.md

@@ -1,6 +1,6 @@
 # Floating action button
 
-> **Optional** — import `actual-css/css/optional/fab` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/components/fab` or `actual-css/css/components`.
 
 FAB fixes a primary action near the viewport's block-end and inline-end edges.
 The existing button component owns its size, shape, intent, and interaction.
@@ -102,12 +102,12 @@ the open state so a plus naturally becomes a close symbol.
 
 ## Class reference
 
-| Class | Description |
-|---|---|
-| `.fab` | Fixed viewport placement; use `details` for a speed dial. |
-| `.fab-actions` | Collapsible vertical action list. |
-| `.fab-action` | One horizontal label-and-button unit. |
-| `.fab-label` | Compact floating label for an action. |
+| Class          | Description                                               |
+|----------------|-----------------------------------------------------------|
+| `.fab`         | Fixed viewport placement; use `details` for a speed dial. |
+| `.fab-actions` | Collapsible vertical action list.                         |
+| `.fab-action`  | One horizontal label-and-button unit.                     |
+| `.fab-label`   | Compact floating label for an action.                     |
 
 ## CSS hooks
 

package/docs/pages/components/navbar.md

@@ -14,13 +14,13 @@ flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.navbar` | Component | Horizontal bar shell. |
-| `.navbar-brand` | Composition | Brand link at the inline start. |
-| `.navbar-nav` | Composition | Horizontal link list. |
-| `.nav-link` | Component | A link item; current page via `aria-current="page"`. |
-| `.nav-list` | Component | Shared vertical navigation list, reused by `.drawer`. |
+| Class           | Kind        | Description                                           |
+|-----------------|-------------|-------------------------------------------------------|
+| `.navbar`       | Component   | Horizontal bar shell.                                 |
+| `.navbar-brand` | Composition | Brand link at the inline start.                       |
+| `.navbar-nav`   | Composition | Horizontal link list.                                 |
+| `.nav-link`     | Component   | A link item; current page via `aria-current="page"`.  |
+| `.nav-list`     | Component   | Shared vertical navigation list, reused by `.drawer`. |
 
 ## Basic usage
 
@@ -42,7 +42,8 @@ For a vertical sidebar nav, use `.nav-list` inside the drawer or sidebar.
 There is no collapse/toggler mechanism. For a responsive navigation, keep the
 horizontal `.navbar` for the desktop bar and compose the mobile experience from
 a `.drawer` with a vertical `.nav-list`, opened by a `command="show-modal"` /
-`commandfor` trigger.
+`commandfor` trigger. Keep that trigger outside the `<nav>` subtree you hide at
+narrow widths, or hiding the nav hides the control that opens it.
 
 ```html demo
 <nav class="navbar" aria-label="Main">

package/docs/pages/components/pagination.md

@@ -9,14 +9,15 @@
 - 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.
+- Arrows, page numbers, and truncation ellipses share one geometric system: every item gets the same minimum footprint, and wider content (100, 1000, text labels) grows past it naturally.
 - Truncated ranges are plain text with `.muted` and `aria-hidden="true"`, not `.btn` — they are decorative, not actionable.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
+| Class         | Kind      | Description                    |
+|---------------|-----------|--------------------------------|
 | `.pagination` | Component | Ordered list of page controls. |
-| `.sm` / `.lg` | Size | Control density. |
+| `.sm` / `.lg` | Size      | Control density.               |
 
 ## Basic usage
 

package/docs/pages/components/skeleton.md

@@ -10,10 +10,10 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.skeleton` | Component | Animated placeholder shape. |
-| `data-shape` | Modifier | Geometry presets: `text`, `title`, `avatar`, `box`. |
+| Class        | Kind      | Description                                         |
+|--------------|-----------|-----------------------------------------------------|
+| `.skeleton`  | Component | Animated placeholder shape.                         |
+| `data-shape` | Modifier  | Geometry presets: `text`, `title`, `avatar`, `box`. |
 
 ## Basic usage
 

package/docs/pages/components/spinner.md

@@ -12,11 +12,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.spinner` | Component | Circular loading indicator using `currentColor`. |
-| `.sm` / `.lg` | Size | Smaller (`0.75em`) or larger (`2rem`) spinner. |
-| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger` color. |
+| Class          | Kind      | Description                                                        |
+|----------------|-----------|--------------------------------------------------------------------|
+| `.spinner`     | Component | Circular loading indicator using `currentColor`.                   |
+| `.sm` / `.lg`  | Size      | Smaller (`0.75em`) or larger (`2rem`) spinner.                     |
+| Shared intents | Intent    | `.primary`, `.secondary`, `.success`, `.warning`, `.danger` color. |
 
 ## Basic usage
 

package/docs/pages/components/table.md

@@ -11,10 +11,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.table-wrap` | Component | Scroll container and outer chrome (surface, border, radius). |
-| `.table` | Component | The table itself; row and cell rules. |
+| Class           | Kind      | Description                                                  |
+|-----------------|-----------|--------------------------------------------------------------|
+| `.table-wrap`   | Component | Scroll container and outer chrome (surface, border, radius). |
+| `.table`        | Component | The table itself; row and cell rules.                        |
+| `.table.compact`| Density   | Tighter cell padding; typography is unchanged.               |
 
 ## Basic usage
 
@@ -96,7 +97,31 @@ table width before the wrapper scrolls horizontally.
 </div>
 ```
 
+## Compact tables
+
+`.compact` lowers the cell padding only — density never changes typography.
+It is the same vocabulary as `.card.compact`.
+
+```html demo
+<div class="table-wrap">
+  <table class="table compact">
+    <caption>Standings by position</caption>
+    <thead>
+      <tr>
+        <th scope="col">Pos</th>
+        <th scope="col">Name</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td>1</td><td>John Nemo</td></tr>
+      <tr><td>2</td><td>Jane Doe</td></tr>
+      <tr><td>3</td><td>Ada Morgan</td></tr>
+    </tbody>
+  </table>
+</div>
+```
+
 ## CSS hooks
 
-- `--table-cell-pad` — cell padding.
+- `--table-cell-pad` — cell padding; `.compact` re-declares it tighter.
 - `--table-min` — minimum table width before `.table-wrap` scrolls horizontally.

package/docs/pages/enhancements/flyout.md

@@ -4,19 +4,19 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.flyout-trigger` | Composition | Positioning wrapper for a trigger and its panel; gives the flyout a local absolute-position fallback before JavaScript positions it. |
-| `.stretch` | Modifier | Stretches a `.flyout-trigger` to span its container, e.g. the last row of a full-width sidebar nav list. |
-| `.flyout` | Component | Floating action or nav surface, positioned by JavaScript. |
-| `.menu` | Component | Action-list primitive with strict `.menu > li > .menu-item` anatomy. |
-| `.menu-item` | Component | One action row; participates in roving focus. |
-| `.menu-item-icon` | Slot | Fixed leading column for a decorative icon. |
-| `.menu-item-text` | Slot | Flexible label column; truncates when the row is constrained. |
-| `.menu-item-end` | Slot | Trailing metadata such as a shortcut, badge, or status. |
-| `.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. |
+| Class             | Kind        | Description                                                          |
+|-------------------|-------------|----------------------------------------------------------------------|
+| `.flyout-trigger` | Composition | Positioning wrapper for a trigger and its panel.                     |
+| `.stretch`        | Modifier    | Stretches a `.flyout-trigger` to span its container.                 |
+| `.flyout`         | Component   | Floating action or nav surface, positioned by JavaScript.            |
+| `.menu`           | Component   | Action-list primitive with strict `.menu > li > .menu-item` anatomy. |
+| `.menu-item`      | Component   | One action row; participates in roving focus.                        |
+| `.menu-item-icon` | Slot        | Fixed leading column for a decorative icon.                          |
+| `.menu-item-text` | Slot        | Flexible label column; truncates when the row is constrained.        |
+| `.menu-item-end`  | Slot        | Trailing metadata such as a shortcut, badge, or status.              |
+| `.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.                                            |
 
 ## Usage
 

package/docs/pages/enhancements/overview.md

@@ -33,4 +33,4 @@ is a no-op until the module is loaded again with a DOM.
 Each interactive component has its own page documenting the exact markup its
 enhancement expects: Dialog, Drawer, Flyout, Tooltip, Tabs, Scrollspy, and
 Status Bar. The default runtime is loaded on the docs pages, so the examples
-work with the documented markup alone.
+work with the documented markup alone.

package/docs/pages/enhancements/scrollspy.md

@@ -8,11 +8,11 @@ or style `[aria-current]` yourself.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.scrollspy` | Component | Marks the nav region for the enhancer; adds no visual styles. |
-| `.nav-list` | Composition | Vertical list of navigation links. |
-| `.nav-link` | Component | Navigation link whose active state comes from `[aria-current]`. |
+| Class        | Kind        | Description                                                     |
+|--------------|-------------|-----------------------------------------------------------------|
+| `.scrollspy` | Component   | Marks the nav region for the enhancer; adds no visual styles.   |
+| `.nav-list`  | Composition | Vertical list of navigation links.                              |
+| `.nav-link`  | Component   | Navigation link whose active state comes from `[aria-current]`. |
 
 ## Usage
 
@@ -68,4 +68,4 @@ without JavaScript.
 ```
 
 Keep this as progressive enhancement. The JavaScript enhancement remains the
-portable fallback — the same markup serves both paths.
+portable fallback — the same markup serves both paths.

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

@@ -2,6 +2,10 @@
 
 > Singleton floating area for short, non-critical, transient feedback.
 
+`status-bar` is for transient feedback, not persistent application status. For
+persistent status, metrics, or operational state, compose regular content
+primitives such as cards, badges, and clusters.
+
 A status bar is a single live region, not a stacked toaster. New messages
 replace the previous one. Keep one element in the HTML, styled with
 `.status-bar` and carrying the `[data-status][role="status"]` contract that the
@@ -69,4 +73,4 @@ document.dispatchEvent(new CustomEvent("actual:status", {
 - `--status-bg` — bar background.
 - `--status-fg` — bar text color.
 
-Prefer an intent class over setting these directly.
+Prefer an intent class over setting these directly.

package/docs/pages/enhancements/tabs.md

@@ -4,11 +4,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.tabs` | Component | Tab strip; pairs with `role="tablist"`. |
-| `.tab` | Component | One tab trigger; pairs with `role="tab"`. |
-| `.primary` | Intent | Tints the selected tab's indicator and text. |
+| Class      | Kind      | Description                                  |
+|------------|-----------|----------------------------------------------|
+| `.tabs`    | Component | Tab strip; pairs with `role="tablist"`.      |
+| `.tab`     | Component | One tab trigger; pairs with `role="tab"`.    |
+| `.primary` | Intent    | Tints the selected tab's indicator and text. |
 
 ## Usage
 
@@ -77,4 +77,4 @@ JavaScript involved:
 
 ## CSS hooks
 
-- `--tab-gap` — space between an icon and the label text (default `0.375em`).
+- `--tab-gap` — space between an icon and the label text (default `0.375em`).

package/docs/pages/enhancements/tooltip.md

@@ -127,4 +127,4 @@ and solid colors both work.
 - `--tooltip-arrow-size` — arrow size.
 
 `--arrow-x` and `--arrow-y` are written by the positioner at runtime, not set by
-the author. See the JavaScript runtime documentation.
+the author. See the JavaScript runtime documentation.