actual-css 0.9.2 → 0.11.0

package/docs/pages/components/card.md

@@ -1,24 +1,20 @@
 # Card
 
-Flexible content container with optional header, body, and footer regions, plus full-bleed children.
+Flexible content container with optional header, body, and footer regions.
 
 ## Class reference
 
-| Class       | Kind             | Description                                     |
-| ----------- | ---------------- | ----------------------------------------------- |
-| `.card`     | Component        | Neutral raised surface for grouped content.     |
-| `.raised`   | Variant          | Elevated surface with a soft shadow.            |
-| `.subtle`   | Variant          | Lower contrast against the page surface.        |
-| `.surface`  | Variant          | The page surface; intent in the text only.      |
-| `.inverted` | Surface modifier | Inverse surface treatment.                      |
-| `.compact`  | Density          | Tighter padding and compact descendant context. |
+| Class      | Kind      | Description                                     |
+| ---------- | --------- | ----------------------------------------------- |
+| `.card`    | Component | Neutral raised surface for grouped content.     |
+| `.raised`  | Variant   | Elevated surface with a soft shadow.            |
+| `.subtle`  | Variant   | Lower contrast against the page surface.        |
+| `.surface` | Variant   | The page surface; intent in the text only.      |
+| `.compact` | Density   | Tighter padding and compact descendant context. |
 
 `.surface` is a shared variant: it paints the page surface instead of
-`--surface-raised` and leaves the intent to the text.
-
-`.inverted` paints `--surface-solid` and swaps the foreground to `--surface`,
-so it inverts in dark themes instead of always reading as dark. Write it as
-`class="card inverted"`, or on any block.
+`--surface-raised` and leaves the intent to the text. For a dark card on a
+light page (or the reverse), put `data-theme="dark"` on the card.
 
 ## Basic usage
 
@@ -59,52 +55,8 @@ gap.
 
 ## Bleed
 
-Use `.bleed` on a direct child to escape the card padding — full-width images,
-colored headers, or footers.
-
-```html demo
-<div style="max-inline-size: 32rem">
-  <article class="card stack">
-    <img class="bleed" src="https://picsum.photos/seed/actual-css-card/600/300" alt="Coastal cliffs at dusk" />
-    <header>
-      <h3>Coastal cliffs at dusk</h3>
-    </header>
-    <section class="stack" aria-label="Summary">
-      <p>A short caption that wraps across a few lines. The image bleeds to the card edges.</p>
-    </section>
-    <footer>
-      <span class="badge primary soft">Photo</span>
-      <button type="button" class="btn outline">View</button>
-    </footer>
-  </article>
-</div>
-```
-
-```html demo
-<article class="card stack" style="--card-max-inline-size: 24rem">
-  <header class="bleed stack items-center text-center" style="background: var(--surface-subtle)">
-    <hgroup>
-      <h3>Team</h3>
-      <p class="muted">For growing products</p>
-    </hgroup>
-    <p>
-      <span style="font-size: 2rem; font-weight: var(--font-weight-semibold); line-height: 1">$24</span>
-      <span class="muted">/ user / month</span>
-    </p>
-  </header>
-
-  <ul class="stack items-center" style="list-style: none; padding: 0">
-    <li>Unlimited projects</li>
-    <li>Up to 25 seats</li>
-    <li>Shared workspaces</li>
-    <li>Priority support</li>
-  </ul>
-
-  <footer class="bleed" style="background: var(--surface-subtle); justify-content: center">
-    <a class="btn primary" href="#">Upgrade</a>
-  </footer>
-</article>
-```
+Use `.bleed` on a direct child to bring an image or band to the card edge. See
+[Bleed](bleed.md) for the shared surface contract and its modular import.
 
 ## In grids
 
@@ -148,27 +100,10 @@ all footers in the row line up regardless of body length.
 
 ## Surfaces
 
-`.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
-the surface tokens, so `.card.subtle.inverted` renders a subtle background with
-inverted foreground. Treat them as mutually exclusive, like two competing
-variants.
+A card is a surface-owning component: inside a painted band it keeps its own
+surface and resets the context for its content. A card with
+`data-theme="dark"` is a complete dark island — its fields, intents and states
+all follow.
 
 `.surface` is the shared variant on a card: it drops the card to the page
 surface instead of `--surface-raised`, keeps the theme border, and lets an
@@ -198,12 +133,12 @@ treatments on either side of it.
     </hgroup>
   </article>
 
-  <article class="card inverted stack">
+  <article class="card stack" data-theme="dark">
     <hgroup>
-      <h3>Inverted</h3>
-      <p>Inverse surface for emphasis. Text inherits the contrasting surface color.</p>
+      <h3>Dark island</h3>
+      <p class="muted">A complete dark theme on one card.</p>
     </hgroup>
-    <button type="button" class="btn">Action</button>
+    <button type="button" class="btn primary outline">Action</button>
   </article>
 
   <article class="card compact">
@@ -219,5 +154,5 @@ treatments on either side of it.
 
 - `--card-radius` — corner radius.
 - `--card-max-inline-size` — maximum width.
-- `--card-pad` — inner padding; also drives the negative offsets that let a `.bleed` child reach the card edge. `.compact` lowers it.
+- `--card-pad` — inner padding, relayed to direct children for `.bleed`. `.compact` lowers it.
 - `--card-gap` — space between direct children of a bare card. A composed layout primitive owns its own gap instead.

package/docs/pages/components/chat.md

@@ -34,6 +34,11 @@ For a live conversation, put an appropriate live-region or `role="log"` on the
 conversation container according to the product's announcement needs. Do not
 put `role="log"` on individual messages.
 
+For the message input itself, keep a native `<textarea>` inside a surface with
+an actions row — see the [composer template](../../demo/templates/composer.html).
+Formatting needs a hosted editor instead — see the
+[rich-text template](../../demo/templates/rich-text.html).
+
 ## Class reference
 
 | Class                           | Description                                  |

package/docs/pages/components/close.md

@@ -0,0 +1,48 @@
+# Close
+
+> Icon-only X button that closes a dialog, dismisses an alert, or removes a tag.
+
+**Related terms:** close button, dismiss button, remove button, clear, X.
+
+- Use an empty `<button class="close" aria-label="…">`: it paints its own X from `--icon-close`, so it needs no icon font and no text glyph.
+- `.close` is always the X. A button with another pictogram is a `.btn.icon-only`.
+- The class names the look, not the mechanism. Close with the container's own action: `command="request-close"` or `method="dialog"` in a dialog, `command="--dismiss"` on an alert, application logic on a tag.
+- The container sets the size and place: the top inline-end corner of a `.modal` or a `.drawer`, the last column of an `.alert`, the end of a `.badge`.
+- A modular build imports `actual-css/css/components/close` next to the component that hosts it.
+
+## Basic usage
+
+```html demo
+<div class="cluster">
+  <button class="close" type="button" aria-label="Close"></button>
+
+  <span class="badge primary soft">
+    Design
+    <button class="close" type="button" aria-label="Remove Design"></button>
+  </span>
+</div>
+```
+
+## In a dialog
+
+In a `.modal` or a `.drawer`, the close sits out of the content flow at the
+panel's top inline-end corner. Place it as a direct child of the dialog, of its
+top-level `form` or `header`, or of a `form` inside that header; a `.close`
+deeper in the content keeps its own place. See [Dialog](dialog.md) and
+[Drawer](drawer.md).
+
+```html
+<dialog class="modal" id="details">
+  <button class="close" type="button" commandfor="details" command="request-close"
+          aria-label="Close dialog"></button>
+  …
+</dialog>
+```
+
+## CSS hooks
+
+- `--close-size` — inline and block size of the button; `--control-size` unless the container sets it.
+- `--close-icon-size` — size of the X.
+
+Alerts and badges declare both hooks on themselves, so set them on the container
+or on the button.

package/docs/pages/components/data-list.md

@@ -61,6 +61,24 @@ metadata.
 </article>
 ```
 
+## Stacked
+
+`.stacked` puts each value under its term instead of beside it, for a narrow
+column or for values too long to share a row.
+
+```html demo
+<dl class="data-list stacked" style="max-inline-size: 16rem">
+  <dt>Billing contact</dt>
+  <dd>alice@example.com</dd>
+
+  <dt>Registered address</dt>
+  <dd>42 Rue des Fleurs, 1000 Brussels, Belgium</dd>
+
+  <dt>Renewal</dt>
+  <dd><time datetime="2026-09-14">14 Sep 2026</time></dd>
+</dl>
+```
+
 ## Contract
 
 `.data-list` styles one `<dt>` followed by one `<dd>` per property. A valid
@@ -69,4 +87,11 @@ markup does not belong in `.data-list` — use a plain description list instead,
 where `.prose` already covers the editorial cases.
 
 Use `.data-list` for the properties of a single object. Use a `<table>` when
-comparing the same properties across multiple objects.
+comparing the same properties across multiple objects.
+
+A per-property icon goes inside the `<dt>`, next to the term. There is no
+gutter slot spanning a term and its value: a `<dl>` admits only `<dt>` and
+`<dd>` per pair — directly or inside a `<div>` wrapper — so no third element
+can hold it. When the icon is the point and the term/value relation is not,
+the content is not a description list: reach for `.media` with an `.overline`
+label instead.

package/docs/pages/components/dialog.md

@@ -6,22 +6,24 @@
 
 ## Class reference
 
-| Class                  | Kind      | Description                                    |
-| ---------------------- | --------- | ---------------------------------------------- |
-| `.modal`               | Component | Centered surface on the native `<dialog>`.     |
-| `.scrollable`          | Variant   | Header and footer stay while the body scrolls. |
-| `.dialog-confirmation` | Variant   | Message above a full-width action band.        |
-| `.dialog-icon`         | Component | Circular intent-aware icon well.               |
-| `.dialog-close`        | Component | Icon-only close button, at the top end.        |
-
-`.dialog-close` sits outside the content flow, so it does not take part in the
-dialog's own layout.
+| Class                  | Kind        | Description                                    |
+| ---------------------- | ----------- | ---------------------------------------------- |
+| `.modal`               | Component   | Centered surface on the native `<dialog>`.     |
+| `.scrollable`          | Variant     | Header and footer stay while the body scrolls. |
+| `.dialog-confirmation` | Variant     | Message above a full-width action band.        |
+| `.dialog-icon`         | Component   | Circular intent-aware icon well.               |
+| `.close`               | Composition | Icon-only close button, at the top end.        |
+
+A [`.close`](close.md) placed as a direct child of the dialog or of its form
+sits outside the content flow, so it does not take part in the dialog's own
+layout.
 
 ## Usage
 
 Modals use the platform-native `<dialog class="modal">` element with `commandfor` and `command` buttons.
 
-Use `command="show-modal"` to open a modal dialog.
+Use `command="show-modal"` to open a modal dialog, or `command="--show"` to open
+it non-modally.
 
 Add `aria-haspopup="dialog"` and `aria-controls="<id>"` to opening buttons so
 their semantics are present before either native or framework JavaScript runs.
@@ -138,7 +140,7 @@ has no action button; the header close button dismisses the dialog.
         id="details-dialog"
         closedby="any"
         data-dialog-dismissible>
-  <button class="dialog-close"
+  <button class="close"
           type="button"
           commandfor="details-dialog"
           command="request-close"
@@ -243,7 +245,7 @@ promoted above it and still unclickable.
         id="overlay-dialog"
         closedby="any"
         data-dialog-dismissible>
-  <button class="dialog-close"
+  <button class="close"
           type="button"
           commandfor="overlay-dialog"
           command="request-close"
@@ -296,7 +298,9 @@ Available options:
   light dismiss and closes the dialog (or rewrites `closedby="any"` to
   `closedby="closerequest"` so the native dialog does not double-handle).
   It never affects Escape or explicit close requests.
-* `data-dialog-modal="false"` opens with `show()` instead of `showModal()`.
+* `data-dialog-modal="false"` makes direct `openDialog()` calls use `show()`
+  instead of `showModal()`. The `show-modal` and `--show` commands override
+  this default.
 * `data-dialog-view-transition` enables a view transition that morphs the dialog to/from its trigger. Only active when the browser supports `document.startViewTransition` and the user allows motion.
 * `closedby` keeps its native meaning: `"any"` closes on backdrop click and
   Escape, `"closerequest"` closes on Escape only, `"none"` disables both. The
@@ -381,7 +385,6 @@ Keep the button a direct child of `dialog.modal` so the scrolling content
 - `--dialog-viewport-gap` — distance kept between the dialog and the viewport edges.
 - `--dialog-icon-size` — diameter of the `.dialog-icon` circle.
 - `--dialog-icon-glyph-size` — size of the glyph centered inside `.dialog-icon`.
-- `--control-size` — inline and block size of the `.dialog-close` button. The
-  header reserves `calc(var(--control-size) + var(--space-30))` on its inline
-  end so the title never runs under the close.
-- `--dialog-close-icon-size` — size of the close glyph.
+- `--close-size` / `--close-icon-size` — size of the corner `.close` and of its
+  X. The header reserves the close size plus `--space-30` on its inline end so
+  the title never runs under it.

package/docs/pages/components/drawer.md

@@ -6,10 +6,10 @@
 
 ## Class reference
 
-| 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. |
+| Class     | Kind        | Description                                              |
+| --------- | ----------- | -------------------------------------------------------- |
+| `.drawer` | Component   | Modal side-sheet built on the native `<dialog>` element. |
+| `.close`  | Composition | Icon-only close button, at the top end.                  |
 
 ## Usage
 
@@ -56,7 +56,7 @@ your intended target `autofocus`; otherwise the body claims initial focus.
     <strong>Menu</strong>
 
     <form method="dialog">
-      <button class="drawer-close" type="submit" aria-label="Close navigation"></button>
+      <button class="close" type="submit" aria-label="Close navigation"></button>
     </form>
   </header>
 
@@ -96,7 +96,7 @@ actions and the close button can close the drawer.
   <form method="dialog">
     <header>
       <strong>Settings</strong>
-      <button class="drawer-close" type="submit" aria-label="Close settings"></button>
+      <button class="close" type="submit" aria-label="Close settings"></button>
     </header>
 
     <div class="stack">
@@ -123,6 +123,6 @@ useful for drawers that should not be dismissed accidentally.
 
 - `--drawer-size` — panel width.
 - `--drawer-pad` — panel padding.
-- `--control-size` — size of the `.drawer-close` button. The drawer header
-  reserves `calc(var(--control-size) + var(--space-30))` on its inline end so
-  the title never runs under the close.
+- `--close-size` / `--close-icon-size` — size of the corner [`.close`](close.md)
+  and of its X. The header reserves the close size plus `--space-30` on its
+  inline end so the title never runs under it.

package/docs/pages/components/navbar.md

@@ -51,7 +51,7 @@ icons. See [App Navigation](app-navigation.md).
 
 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. The [Workspaces example](../examples/overview.md)
+full-row hit target for vertical navigation. The [Workspaces example](../examples/overview.md#page-shapes)
 shows the sectioned-sidebar composition: grouped `.nav-list` blocks with
 section titles, a pinned account footer, and the native current state.
 
@@ -94,15 +94,15 @@ accessible name.
   <header>
     <strong>Menu</strong>
     <form method="dialog">
-      <button class="drawer-close" type="submit" aria-label="Close navigation"></button>
+      <button class="close" type="submit" aria-label="Close navigation"></button>
     </form>
   </header>
 
   <nav>
     <ul class="nav-list stack">
-      <li><a href="#" aria-current="page">Home</a></li>
-      <li><a href="#">Docs</a></li>
-      <li><a href="#">Components</a></li>
+      <li><a class="nav-link" href="#" aria-current="page">Home</a></li>
+      <li><a class="nav-link" href="#">Docs</a></li>
+      <li><a class="nav-link" href="#">Components</a></li>
     </ul>
   </nav>
 </dialog>

package/docs/pages/components/pagination.md

@@ -7,8 +7,8 @@
 - Use `aria-current="page"` for the current page.
 - 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.
+- Prefer text labels for Previous and Next; a chevron icon may accompany them. Icon-only controls need an accessible name.
+- Compose page links with `.btn.ghost`; `aria-current="page"` fills the current one, so it is the only boxed item.
 - 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.
 
@@ -24,12 +24,12 @@
 ```html demo
 <nav aria-label="Pagination">
   <ol class="pagination sm">
-    <li><a href="?page=2" class="btn outline" rel="prev">Previous</a></li>
-    <li><a href="?page=1" class="btn outline" aria-label="Page 1">1</a></li>
-    <li><a href="?page=2" class="btn outline" aria-label="Page 2">2</a></li>
-    <li><a href="?page=3" class="btn" aria-current="page" aria-label="Page 3">3</a></li>
-    <li><a href="?page=4" class="btn outline" aria-label="Page 4">4</a></li>
-    <li><a href="?page=5" class="btn outline" rel="next">Next</a></li>
+    <li><a href="?page=2" class="btn ghost" rel="prev"><i class="ti ti-chevron-left" aria-hidden="true"></i> Previous</a></li>
+    <li><a href="?page=1" class="btn ghost" aria-label="Page 1">1</a></li>
+    <li><a href="?page=2" class="btn ghost" aria-label="Page 2">2</a></li>
+    <li><a href="?page=3" class="btn ghost" aria-current="page" aria-label="Page 3">3</a></li>
+    <li><a href="?page=4" class="btn ghost" aria-label="Page 4">4</a></li>
+    <li><a href="?page=5" class="btn ghost" rel="next">Next <i class="ti ti-chevron-right" aria-hidden="true"></i></a></li>
   </ol>
 </nav>
 ```
@@ -42,15 +42,15 @@ buttons — they are decorative, not actionable.
 ```html demo
 <nav aria-label="Pagination">
   <ol class="pagination sm">
-    <li><a href="?page=1" class="btn outline" rel="prev">Previous</a></li>
-    <li><a href="?page=1" class="btn outline" aria-label="Page 1">1</a></li>
+    <li><a href="?page=7" class="btn ghost" rel="prev"><i class="ti ti-chevron-left" aria-hidden="true"></i> Previous</a></li>
+    <li><a href="?page=1" class="btn ghost" aria-label="Page 1">1</a></li>
     <li><span class="muted" aria-hidden="true">…</span></li>
-    <li><a href="?page=7" class="btn outline" aria-label="Page 7">7</a></li>
-    <li><a href="?page=8" class="btn" aria-current="page" aria-label="Page 8">8</a></li>
-    <li><a href="?page=9" class="btn outline" aria-label="Page 9">9</a></li>
+    <li><a href="?page=7" class="btn ghost" aria-label="Page 7">7</a></li>
+    <li><a href="?page=8" class="btn ghost" aria-current="page" aria-label="Page 8">8</a></li>
+    <li><a href="?page=9" class="btn ghost" aria-label="Page 9">9</a></li>
     <li><span class="muted" aria-hidden="true">…</span></li>
-    <li><a href="?page=20" class="btn outline" aria-label="Page 20">20</a></li>
-    <li><a href="?page=9" class="btn outline" rel="next">Next</a></li>
+    <li><a href="?page=20" class="btn ghost" aria-label="Page 20">20</a></li>
+    <li><a href="?page=9" class="btn ghost" rel="next">Next <i class="ti ti-chevron-right" aria-hidden="true"></i></a></li>
   </ol>
 </nav>
 ```

package/docs/pages/components/shimmer.md

@@ -0,0 +1,57 @@
+# Shimmer
+
+> **Module** — import `actual-css/css/effects/shimmer` or `actual-css/css/effects`.
+
+Shimmer sweeps a highlight across a text label to show an activity in
+progress: an agent working, a chatbot composing, a job processing.
+
+```html demo
+<div class="stack">
+  <span class="shimmer" role="status">Working…</span>
+  <p class="cluster">
+    <span class="spinner" aria-hidden="true"></span>
+    <span class="shimmer" role="status">Generating the report…</span>
+  </p>
+</div>
+```
+
+**Related terms:** shimmering text, loading text, thinking indicator, pending
+label, typing indicator.
+
+Shimmer is presentation only and selects no ARIA attribute. Put
+`role="status"` on a message that should be announced, and `aria-busy="true"`
+on the region whose content is being updated — not on the message because it
+looks busy. Assistive technology may hold back changes inside a busy region
+until it is released.
+
+The label rests on `--shimmer-color` and the band passes in
+`--shimmer-highlight`; one pass takes `--duration-shimmer`, the pace shared
+with `.skeleton` and indeterminate `.progress`. With reduced motion, or in a
+browser without `background-clip: text`, the label is plain
+`--shimmer-color` text. Recolor a label through these hooks: its own `color`
+shows only where the sweep does not run.
+
+## Choosing a waiting signal
+
+| Primitive                  | Signals                                      |
+| -------------------------- | -------------------------------------------- |
+| [`.spinner`](spinner.md)   | An operation takes time                      |
+| [`.skeleton`](skeleton.md) | Content is not available yet                 |
+| `.shimmer`                 | This label describes an activity in progress |
+| [`.aura`](aura.md)         | This object is emphasized                    |
+
+They compose rather than imply one another: `aria-busy` never adds an aura or
+a shimmer. A card being processed can carry several, each for its own reason:
+
+```html demo
+<span class="aura primary">
+  <article class="card stack" style="inline-size: 18rem">
+    <p><strong>Quarterly import</strong></p>
+    <p class="shimmer" role="status">Processing 1,204 rows…</p>
+    <div class="stack" aria-busy="true">
+      <div class="skeleton" data-shape="text" aria-hidden="true"></div>
+      <div class="skeleton" data-shape="text" aria-hidden="true"></div>
+    </div>
+  </article>
+</span>
+```

package/docs/pages/components/skeleton.md

@@ -8,7 +8,8 @@
 - Use layout utilities for placeholder arrangement.
 - Only relevant for simple placeholders - use more structural solutions like phantom-ui for complex cases.
 
-**Related terms:** skeleton screen, shimmer, loading placeholder.
+**Related terms:** skeleton screen, shimmer, loading placeholder. For a text
+label showing an activity in progress, see [Shimmer](shimmer.md).
 
 ## Class reference
 

package/docs/pages/components/spinner.md

@@ -12,11 +12,15 @@
 
 ## 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`. |
+| `[aria-busy="true"]` | State     | Loading region; see Busy state below.            |
+| `.sm` / `.lg`        | Size      | Smaller (`0.75em`) or larger (`2rem`) spinner.   |
+| Shared intents       | Intent    | `.primary`, `.secondary`, `.success`, …          |
+
+The shared intents are `.primary`, `.secondary`, `.success`, `.warning` and
+`.danger`.
 
 ## Basic usage
 
@@ -68,13 +72,14 @@ Size follows the font (`1em`); use `.sm` / `.lg` rather than sizing it directly.
 
 ## Busy state
 
-A container-wide loading state that keeps the underlying content in place. It is
+The spinner is the indicator; `aria-busy` is the state. A container-wide
+loading state keeps the underlying content in place. It is
 driven by `aria-busy="true"` plus a direct last-child `.spinner` — there is no
 separate `.busy` class. The spinner is shown as a centered overlay over a faded
 surface; buttons keep their spinners inline instead (see Button).
 
 - Set `aria-busy="true"` on the container and add `<span class="spinner" aria-hidden="true"></span>` as its last direct child.
-- The overlay uses `--busy-overlay-bg`; an inverted surface (`.inverted`) already composes with it.
+- The overlay uses `--busy-overlay-bg`; a card derives it from its own surface.
 - Decorative spinners stay `aria-hidden="true"`; announce progress on the region with `role="status"` and a label when needed.
 
 ```html demo
@@ -89,5 +94,5 @@ surface; buttons keep their spinners inline instead (see Button).
 
 - `--spinner-track` — the ring color.
 - `--spinner-value` — the moving gap; swap the two for an inverted spinner.
-- `--busy-overlay-bg` — background of the busy overlay. An inverted surface
-  (`.inverted`) overrides it to blend with its own surface.
+- `--busy-overlay-bg` — background of the busy overlay. Set it on a surface you
+  paint yourself so the overlay blends with that surface.

package/docs/pages/components/table.md

@@ -124,6 +124,19 @@ same vocabulary as `.card.compact`.
 </div>
 ```
 
+## When a table stops reading as a table
+
+Responsive strategy is horizontal overflow: the wrap scrolls, the table keeps
+its columns and its column scanability. No `data-label` restructuring, no
+second representation of the data.
+
+For datasets that no longer read well as a table on narrow screens, compose a
+different view instead of restructuring the table: a `.list` / `.media` row
+with badges and actions for a CRUD collection, [`.data-list`](data-list.md)
+for one object's properties, or a dedicated data grid for interactive tables
+(sorting, filtering, selection). Two views for two contexts is a feature, not
+a duplication.
+
 ## CSS hooks
 
 - `--table-cell-pad` — cell padding; `.compact` re-declares it tighter.

package/docs/pages/enhancements/flyout.md

@@ -522,6 +522,8 @@ delay; a number sets the delay in milliseconds.
 
   The repetition is the point: the two hooks are different contracts, and only
   the cap may enter the runtime's `min()`.
+- `--flyout-pad` — panel padding. Defaults to `var(--space-10)`, tight for
+  action menus; rich panels opt into dialog air per instance.
 - `--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

@@ -53,6 +53,11 @@ Enhancer modules self-register when imported. They do not require init calls and
 are safe to import during server-side rendering: outside a browser, registration
 is a no-op until the module is loaded again with a DOM.
 
+Load the full bundle **or** the source modules, never both: each evaluation
+owns its registry and document handlers, so a dist bundle mixed with
+`actual-css/js/*` source subpaths (or two dist bundles) registers every
+behavior twice and a flyout opens then immediately closes.
+
 ## Component pages
 
 Each interactive component has its own page documenting the exact markup its

package/docs/pages/enhancements/tabs.md

@@ -22,6 +22,10 @@
 - 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.
+- Naming follows the container/item convention (like `menu` / `menu-item`):
+  `.tabs` is the strip, `.tab` is one trigger. The JS module
+  (`actual-css/js/tab`) is named for the file; the behavior token
+  (`data-enhance="tabs"`) is named for what it wires.
 - 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