actual-css 0.10.0 → 0.11.0

package/docs/design-notes/enhancement-contract.md

@@ -57,10 +57,11 @@ than the registration root, without crossing shadow boundaries.
 
 > `data-enhance` is a generic opt-in for when HTML does not already provide an unambiguous one.
 
-- **A token** is for a root controller — a behavior that owns a subtree and manages
-  descendants (tabs, flyout, scrollspy, validation).
-- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously the opt-in
-  and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
+- **A token** is for a named behavior whose opt-in carries no configuration,
+  whether it owns a subtree or enhances one leaf (tabs, flyout, range,
+  scrollspy, validation).
+- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously
+  the opt-in and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
   `data-context-menu`).
 - **Elements that are their own opt-in** need nothing (`<dialog>`).
 
@@ -72,6 +73,13 @@ than the registration root, without crossing shadow boundaries.
 on the same root throws; `disconnect()` releases the name; re-registration
 after disconnect is allowed; the same token on a different root is independent.
 
+Named registrations share one `[data-enhance]` discovery gate per root: however
+many behaviors are registered, the observer queries that single selector and
+each registration matches its own `[data-enhance~="name"]` against what it finds.
+`enhance()` records share the same observer and lifecycle with their arbitrary
+selectors. Behaviors on one element start in no guaranteed order and must not
+depend on each other.
+
 `enhance()` stays generic and unguarded — registering the same selector twice
 creates two independent records that both run.
 
@@ -95,8 +103,8 @@ those registrations explicitly.
 
 - Use a command for an immediate trigger-to-current-target action. Commands
   resolve the DOM at event time and do not own element lifecycle.
-- Use `registerEnhancement()` for an opted-in controller that owns listeners or
-  state for a subtree.
+- Use `registerEnhancement()` for a named, opted-in behavior that owns listeners
+  or state for a subtree or leaf.
 - Use `enhance()` for a self-describing leaf behavior that needs connection and
   cleanup lifecycle without a named token.
 - Prefer delegation when no persistent per-element state is required.
@@ -145,7 +153,8 @@ of the contract itself.
 | ------------ | ------------------------------------------------ | ------------------- |
 | `tabs`       | Tab panel switching, arrow-key navigation        | `.tabs`             |
 | `flyout`     | Trigger → panel positioning, open/close          | `.flyout`           |
+| `range`      | Fill share and named-value synchronization       | `.range`            |
 | `scrollspy`  | Scroll-driven nav highlighting                   | `.scrollspy`        |
 | `validation` | Form validation, focus management, server errors | `.needs-validation` |
 
-Four tokens. Everything else stays self-describing.
+Five tokens. Everything else stays self-describing.

package/docs/design-notes/platform-alignment.md

@@ -386,12 +386,16 @@ Prefer native controls and progressive styling.
 
 The concrete signal to watch is `appearance: base-slider` with `::slider-track`, `::slider-fill`, and `::slider-thumb`. Checked on Chrome 152: `CSS.supports('appearance', 'base-slider')` and `CSS.supports('selector(::slider-fill)')` are both false, so there is nothing to enhance against yet.
 
-Until then, `.range` intentionally omits filled tracks and tick marks. Both are reachable today only through techniques Actual should not take on:
+Until then, `.range` intentionally omits tick marks, and its filled track comes
+from the `range` enhancement (one `--range-progress` share driving a
+track gradient) rather than engine-specific pseudo-elements:
 
-- The Chromium filled-track trick needs `overflow: hidden` on the runnable track plus a large `box-shadow` on the thumb. It collides twice with `range.css`: the thumb is wider than the track and would be clipped, and the focus ring already owns the thumb's `box-shadow`.
-- CSS-only tick marks need a step count duplicated out of `min`/`max`/`step` into a custom property, so markup carries the same contract twice and the two can diverge. `datalist` cannot carry it either: its native ticks are part of the appearance that `appearance: none` removes, and no engine renders `<option label>` for a range.
+- The Chromium filled-track trick needs `overflow: hidden` on the runnable track plus a large `box-shadow` on the thumb. It collides twice with `range.css`: the thumb is wider than the track and would be clipped, and the thumb's `box-shadow` is already owned by the focus ring.
+- CSS-only tick marks need a step count duplicated out of `min`/`max`/`step` into a custom property, so markup carries the same contract twice and the two can diverge. `datalist` cannot carry it either: its native ticks are part of the appearance that `appearance: none` removes, and no engine renders `<option label>` for a range — Actual reads the datalist as data only.
 
-When the base-slider parts become interoperable, this becomes a `@supports` enhancement in the shape of `custom-select.css` — less engine-specific CSS, not more.
+When the base-slider parts become interoperable, the `--range-progress`
+calculation becomes a `@supports` enhancement in the shape of
+`custom-select.css` — less engine-specific CSS, not more.
 
 ### Navigation
 

package/docs/design-notes/rich-text.md

@@ -0,0 +1,61 @@
+# Rich text: three levels and why a package demos level 2
+
+Editing text and editing a document are different problems with different
+costs. Actual draws the line at the document boundary, in three levels:
+
+```text
+1. TEXTAREA (native)
+   text, autosize, actions row, plain-text caret helpers
+   → the composer pattern: demo/templates/composer.html
+
+2. HOSTED RICH-TEXT PACKAGE (integration)
+   bold / italic / lists / links / quote, undo, paste cleanup,
+   structured @mentions, / snippets
+   → the rich-text recipe: demo/templates/rich-text.html + @lekoala/rich-text
+
+3. STRUCTURED DOCUMENT ENGINE (integration, heavier)
+   custom document nodes, annotations, collaborative state
+   → no demo; the bridge contract from level 2 applies unchanged
+```
+
+Level 1 stays a real `<textarea>`: form value, IME, undo, mobile,
+accessibility, validation. `contenteditable="plaintext-only"` buys nothing over
+it and loses the native form control, so the framework does not use it. The
+Markdown round-trip some engines offer is still beta upstream and is not the
+storage contract.
+
+## Why a package for the level-2 demo
+
+The demo exists to prove the bridge (tokens, pressed states, focus, invalid,
+composer chrome), not the engine. Owning the toolbar, sanitizer, roving focus
+and lifecycle inside the demo meant Actual did involuntarily much of the
+editor's job. Extracting that into `@lekoala/rich-text` restored the boundary:
+
+```text
+Actual CSS         presentation, tokens, composer chrome, dialogs, validation
+@lekoala/rich-text textarea enhancement, Squire, sanitization, toolbar
+                   semantics + keyboard, links, mentions, suggestions,
+                   form/reset/readonly/disabled, lifecycle
+application        people lookup, templates, attachments, dictation, send
+```
+
+`@lekoala/rich-text` owns the editor UI semantics; Actual owns its visual
+language. Squire is an implementation detail of the integration package: it
+owns selection, editing, paste normalisation and undo/redo, while the package
+owns the product-facing contract around it (progressive enhancement of a real
+`<textarea>`, mandatory sanitization, accessible generated UI, lifecycle and
+cleanup). HTML stays the source of truth, which keeps the storage decoupled
+and the engine choice reversible.
+
+## What was deliberately not demoed
+
+- A second engine demo would prove nothing more about the bridge, and one
+  candidate changes fundamental choices between minor versions — a pinned demo
+  would rot. Spikes belong in `tmp/`, not `demo/`.
+- Plain-text caret helpers stay a textarea-level improvement at level 1.
+  Structured `@mentions` live at level 2 because they are sanitized, atomic
+  entities inserted as HTML — the demo's Snippet/Mention buttons reuse the
+  same suggestion seam as `/` and `@`, so one capability keeps two surfaces
+  without duplicating its logic.
+- Syntax highlighting inside inputs is a search-DSL concern, not a composer
+  concern; layering it onto a textarea rebuilds a fake rich editor.

package/docs/design-notes/steps.md

@@ -630,8 +630,8 @@ so an author who lowers `--step-min` below `--step-size` narrows the scroll
 budget without collapsing items behind their own markers.
 
 The cost of scrolling is that clipping happens at the padding edge, and a focus
-ring is drawn outside its element's border box — `--focus-outline` is two
-border-widths wide at `--focus-outline-offset`, so 4px past a label that sits
+ring is drawn outside its element's border box — `--focus-outline` is
+`--focus-ring-width` wide at `--focus-outline-offset`, so 4px past a label that sits
 flush with the bottom of a stacked row. A navigable row therefore reserves
 exactly that much `padding-block`, gated on `.steps-horizontal:has(a[href])`. An
 informational stepper — the common case, with no ring to protect — keeps its

package/docs/navigation.json

@@ -67,6 +67,7 @@
         "pagination",
         "progress",
         "rating",
+        "shimmer",
         "skeleton",
         "spinner",
         "steps",
@@ -80,6 +81,7 @@
         "overview",
         "controls",
         "combobox",
+        "rich-text",
         "labels",
         "floating-field",
         "states-and-sizes",

package/docs/pages/components/aura.md

@@ -84,22 +84,22 @@ The frame color comes from an intent such as `.primary`, `.success`, or
 a neutral intent produces a neutral aura. Use a chromatic intent when you want
 a visibly luminous effect.
 
-Two hooks tune how loud the effect is. `--aura-intensity` scales both halos at
-once, resting and breathing alike, so the breath stays proportional at every
-setting; `--aura-duration` sets one full rotation of the accent, or one breath
-of the glow.
+The default is a thin lit line with a faint halo. Three hooks tune how loud it
+is: `--aura-width` sets the line, `--aura-intensity` scales both halos at once,
+resting and breathing alike, and `--aura-duration` sets one full rotation of
+the accent, or one breath of the glow.
 
 ```html demo
 <div class="cluster" style="gap: 2rem">
-  <span class="aura aura-glow primary" style="--aura-intensity: 0.4">
-    <span class="card" style="inline-size: 8rem">Muted</span>
+  <span class="aura aura-glow primary" style="--aura-intensity: 0">
+    <span class="card" style="inline-size: 8rem">Line only</span>
   </span>
 
   <span class="aura aura-glow primary">
     <span class="card" style="inline-size: 8rem">Default</span>
   </span>
 
-  <span class="aura aura-glow primary" style="--aura-intensity: 2">
+  <span class="aura aura-glow primary" style="--aura-width: 3px; --aura-intensity: 1">
     <span class="card" style="inline-size: 8rem">Loud</span>
   </span>
 
@@ -113,11 +113,10 @@ Keep exactly one direct child and set `--aura-radius` when its shape differs
 from the common button, card, alert, and badge shapes detected as a visual
 enhancement.
 
-The child must be opaque. The frame paints across the whole box and relies on
-the child to cover all but its edge, so a transparent child — an `.outline`
-alert, a `.ghost` button — is filled edge to edge with the frame color instead
-of framed by it. Give such a child a surface, or move the aura to an opaque
-wrapper around it.
+A transparent or translucent child — an `.outline` alert, a `.ghost` button, a
+glass surface — shows `--surface-opaque` beneath it, the theme's opaque
+neutral, rather than the frame color. On a differently painted band, give the
+child its own surface so it matches the band.
 
 ## CSS hooks
 
@@ -125,7 +124,7 @@ wrapper around it.
 - `--aura-width` — frame thickness.
 - `--aura-blur` — near halo blur; the far halo derives its own blur and its
   spread beyond the frame from this value, so one hook scales both.
-- `--aura-intensity` — multiplies both halo opacities, resting and breathing.
+- `--aura-intensity` — multiplies both halo strengths, resting and breathing.
   It does not touch the frame itself, which stays a crisp line at any setting.
 - `--aura-radius` — child corner radius used to derive the outer radius.
 - `--aura-duration` — one rotation of the accent, or one breath of the glow.

package/docs/pages/components/badge.md

@@ -2,6 +2,12 @@
 
 > Compact label for counts, status, or category tags, with shared intents and variants.
 
+A badge is **information, never a control**: counts, status, categories. It is
+non-interactive by nature — for a selectable option use
+[`.choice-card.chip`](../forms/choice-cards.md#chips); for a value produced by
+a widget that can be removed (combobox multi-value), the widget owns the
+removable tag (see [combobox](../forms/combobox.md)).
+
 - Supports intent colors.
 - Soft by default. Use `.solid` for counters and notification badges, or `.outline` for quieter emphasis.
 - Empty badges are solid status dots: visual variants such as `.soft` and `.outline` do not change their fill.
@@ -180,6 +186,10 @@ Override the existing hooks when the three-step scale does not fit the content.
 Use `.badge soft` for tag visuals. Add a direct [`.close`](close.md) button only when the tag can actually be removed. There is no separate chip component.
 For a compact action or filter, use `.btn.sm` instead; badges describe content
 and must not be turned into toggle controls merely to obtain a compact shape.
+Never put a `.close` inside a `.choice-card.chip` label: the label is already
+an interactive target driving its checkbox/radio, and a nested button would mix
+two interactive targets. A removable tag next to a selectable chip is a sibling
+(a widget tag or a `.badge` + `.close`), never a child of the label.
 
 Inside a badge the close follows the pill's size, keeps a 24px pointer target,
 and tucks into the padding.

package/docs/pages/components/button.md

@@ -89,7 +89,7 @@ every variant keeps working — `.outline` and `.ghost` take the solid ink:
 ```css
 .btn.app-dark {
   --intent: var(--surface-solid);
-  --intent-fg: var(--surface);
+  --intent-fg: var(--surface-solid-fg);
 }
 ```
 

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/dialog.md

@@ -22,7 +22,8 @@ layout.
 
 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.
@@ -297,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

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,7 +72,8 @@ 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).

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/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

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

@@ -11,9 +11,31 @@
 | `.primary` / `.secondary` | Intent    | Accent for the selected state.                |
 
 - Use `.choice-card` on a `<label>` wrapping a native `<input type="radio">` or `<input type="checkbox">`. The input is visually hidden; in browsers without `:has()` it stays visible so selection state never disappears.
-- Selected items show a primary border, subtle background tint, and a checkmark badge at the top-right corner — round for radio, rounded square for checkbox.
-- Pair with grid or flex utilities for group layout. The badge overhangs the top-right corner, so avoid `overflow: hidden` on the direct container.
-- Supports disabled, checked, focus-visible, and invalid states.
+- The control shows before any choice: a ring (radio) or a rounded box (checkbox) on the leading edge, level with the first line. Checked, it fills with a check, and the card takes a primary border and a subtle tint.
+- Each child element of the label sits on its own row beside the indicator — a title and a `.muted` detail need no wrapper. Wrap loose text in an element.
+- Stack cards for a list of options (a person, an address, a delivery method), or pair them with grid utilities for options compared side by side.
+- Supports disabled, checked, focus-visible, and invalid states; the resting ring turns danger with the border.
+
+```html demo
+<fieldset class="field-group stack">
+  <legend class="field-label">Deliver to</legend>
+  <label class="choice-card">
+    <input type="radio" name="address" value="home" checked />
+    <strong>Home</strong>
+    <span class="muted">12 Rue des Tanneurs, 1000 Brussels</span>
+  </label>
+  <label class="choice-card">
+    <input type="radio" name="address" value="work" />
+    <strong>Work</strong>
+    <span class="muted">Avenue Louise 54, 1050 Ixelles</span>
+  </label>
+  <label class="choice-card">
+    <input type="radio" name="address" value="pickup" />
+    <strong>Pickup point</strong>
+    <span class="muted">Collect within 7 days</span>
+  </label>
+</fieldset>
+```
 
 ```html demo
 <div class="grid-3">
@@ -94,6 +116,52 @@ follows through its `em` sizing. Padding is density, so use a `.compact` or
 `.spacious` context to change it. Intent classes (`.primary`, `.secondary`) are
 supported on the `.choice-card` element.
 
+## Corner badge
+
+A tile whose content is the choice itself — a product image, a centred plan
+name — may want no indicator column, and a check badge over its corner once
+selected (radio/checkbox tile, selected tick, check in the corner). That is a
+recipe on the card's own `::before` (disc) and `::after` (check) layers,
+written in application CSS after the framework:
+
+```css
+.choice-tile {
+  --choice-card-check-size: 1.5em;
+
+  display: block;
+}
+
+.choice-tile::before,
+.choice-tile::after {
+  position: absolute;
+  inset-inline-end: -0.375em;
+  inset-block-start: -0.375em;
+  margin: 0;
+}
+
+.choice-tile::before {
+  border: 0;
+  box-shadow: 0 0 0 2px var(--surface-opaque);
+  transform: scale(0);
+}
+
+.choice-tile:has(:checked)::before {
+  transform: scale(1);
+}
+```
+
+```html
+<label class="choice-card choice-tile">
+  <input type="radio" name="cpu" value="1" checked />
+  <strong>8-core CPU</strong><br />
+  <span class="muted">32 GB RAM</span>
+</label>
+```
+
+The badge overhangs the corner, so no ancestor up to the grid may clip with
+`overflow: hidden`. The [Neon Ramen item page](../../demo/sites/neon-ramen/item.html)
+uses it for its sizes and toppings.
+
 ## Chips
 
 Add `.chip` for the compact pill form: filter chips, selectable tags, toggle
@@ -101,6 +169,9 @@ pills, multi-select facets. A radio group gives single-choice chips. A leading
 dot turns into the check in a fixed slot, so checking never moves the label.
 Use `.cluster` for a wrapping row. A chip is sized like a control: `.btn` and
 `.input` height, `--control-pad-x` inline padding, `.sm` / `.lg` scale.
+A chip is a `<label>` around its checkbox/radio — never nest a `.close` or any
+other button inside it. A removable value (combobox tag) belongs to the widget
+that produced it, or to a sibling `.badge` + `.close`, not to the chip label.
 
 ```html demo
 <fieldset class="field-group">
@@ -129,8 +200,10 @@ by widening the clip, as the `material` theme does.
 ## CSS hooks
 
 - `--choice-card-pad` — inner padding.
+- `--choice-card-gap` — space between the indicator column and the label.
 - `--choice-card-radius` — corner radius.
-- `--choice-card-check-size` — size of the check indicator.
+- `--choice-card-check-size` — size of the indicator, and the width of its
+  column.
 - `--choice-card-border` / `--choice-card-bg` — resting border and background;
   the checked state and hover rebind them, so a checked override needs
   `:has(:checked)`.

package/docs/pages/forms/combobox.md

@@ -10,7 +10,7 @@ real product needs a JavaScript combobox (searchable select, removable tags,
 autocomplete suggestions), load a dedicated component and bridge its custom
 properties onto Actual's tokens.
 
-**Related terms:** combo box, combobox, autocomplete, datalist, searchable select, enhanced select, multiple select, tags, chips, tag input, pill input.
+**Related terms:** combo box, combobox, autocomplete, datalist, select, custom select, native select, searchable select, enhanced select, multiple select, dropdown, form controls, tags, chips, tag input, pill input.
 
 ## Theme bridge
 
@@ -36,6 +36,21 @@ mix tokens.
 
 The card in the template documents the full token map of this recipe.
 
+## Bridge contract
+
+Actual owns the visual language; the widget owns the behavior. Actual provides
+surface, border, radius, inset focus outline, danger state, `.join` corners,
+and the contrast contracts those tokens carry. The widget provides search,
+keyboard navigation, multi-value state, removable tags, and option rendering.
+The bridge CSS stays in docs/demo — it is a recipe, not package API, so no
+`actual-combobox.css` ships with the framework and no widget version is pinned
+by it.
+
+Multi-value and i18n (for example a "n selected" summary string) are widget
+configuration: pass locale strings and tag rendering through the widget's own
+options, and keep skinning on the `--cb-*` tokens so light/dark mode and preset
+themes keep applying for free.
+
 ## Lightweight pass-through
 
 Most of the skin is three one-line token bridges. The visible vocabulary —