actual-css 0.5.0 → 0.7.0

package/docs/pages/enhancements/flyout.md

@@ -6,16 +6,18 @@
 
 ## Class reference
 
-| 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.              |
+| Class             | Kind        | Description                                 |
+| ----------------- | ----------- | ------------------------------------------- |
+| `.flyout-trigger` | Composition | Positioning wrapper for trigger and panel.  |
+| `.stretch`        | Modifier    | Spans a `.flyout-trigger` to its container. |
+| `.flyout`         | Component   | Floating surface, positioned by JavaScript. |
+| `.menu`           | Component   | Action-list primitive.                      |
+| `.menu-item`      | Component   | One action row; joins roving focus.         |
+| `.menu-item-icon` | Slot        | Fixed leading column for an icon.           |
+| `.menu-item-text` | Slot        | Flexible label column; truncates.           |
+| `.menu-item-end`  | Slot        | Trailing shortcut, badge or status.         |
+
+`.menu` has a strict `.menu > li > .menu-item` anatomy.
 | `.menu-label`     | Variant     | Muted section heading inside a menu; not interactive.                |
 | `.menu-separator` | Variant     | Divider between menu groups (`<hr role="separator">`).               |
 | `.sm` / `.lg`     | Variant     | Compact or large density.                                            |
@@ -72,8 +74,98 @@ placement strings supported by the floating runtime, such as `bottom-start`,
 
 Use `data-flyout-distance` for the trigger gap in pixels. The default is `4`.
 
-Use `data-flyout-auto-close` when the default click dismissal behavior is not
-right. Escape still follows the shared surface lifecycle.
+### Native popover lifecycle
+
+The `.flyout` presentation also composes with an element carrying `popover`.
+Actual neutralizes the native popover geometry that conflicts with anchored
+positioning and recognizes `:popover-open` as the visible state. The browser or
+another library may therefore own opening, dismissal, and focus without
+requiring `.is-open` or `[hidden]`.
+
+Actual CSS does not position that independently managed popover. Its positioner
+must write fixed viewport coordinates (and may write `--available-height` and
+`--surface-anchor-width`); the built-in `surface.js` runtime remains the full
+fallback when Actual owns the lifecycle too. A bare `[popover]` without
+`.flyout` or `.tooltip` keeps its platform appearance.
+
+Native Popover is optional and is not part of Actual's Minimal contract:
+browsers within the Minimal range may not support it. Actual gates its own
+geometry reset behind `@supports selector(:popover-open)`, so an engine without
+Popover no longer gets a mispositioned panel — but that engine also never hides
+or promotes a `popover` element, so nothing dismisses the panel either.
+
+When the lifecycle must work across the full Minimal range, use `surface.js`.
+Otherwise using the native lifecycle is an application support decision. The
+two are alternatives, not layers.
+
+#### Choose one lifecycle owner
+
+The Actual runtime path, where `surface.js` owns opening, dismissal, focus and
+placement:
+
+```html
+<div class="flyout-trigger">
+  <button data-enhance="flyout" aria-controls="actions" aria-expanded="false">
+    Actions
+  </button>
+
+  <ul id="actions" class="flyout menu" hidden>
+    <li><button class="menu-item" type="button">Rename</button></li>
+  </ul>
+</div>
+```
+
+The native path, where the browser owns the lifecycle and the top layer:
+
+```html
+<button popovertarget="actions">Actions</button>
+
+<ul id="actions" class="flyout menu" popover>
+  <li><button class="menu-item" type="button">Rename</button></li>
+</ul>
+```
+
+Do not combine them. `surface.js` opens a panel by clearing `[hidden]` and
+adding `.is-open`; it never calls `showPopover()`, so a `popover` element handed
+to the runtime has two owners and stays closed. The runtime logs a warning if it
+is asked to retain one.
+
+**The native path still needs a positioner.** `popovertarget` gives the panel an
+implicit anchor reference to its invoker, but it does not place it: Actual's
+geometry reset clears the UA's centering, so an unpositioned native flyout is
+laid out at its static position rather than under its trigger. Supply
+coordinates the same way `surface.js` does:
+
+```js
+import { autoUpdate, reposition } from "@lekoala/floating";
+
+const trigger = document.querySelector("[popovertarget='actions']");
+const panel = document.getElementById("actions");
+
+// One tracker at a time. autoUpdate returns its own cleanup; releasing it
+// before every state change keeps repeated opens from stacking trackers, and
+// stops the scroll/resize work as soon as the panel closes.
+let stop;
+
+panel.addEventListener("toggle", (event) => {
+  stop?.();
+  stop = undefined;
+  if (event.newState !== "open") return;
+
+  stop = autoUpdate(trigger, panel, () => {
+    reposition(trigger, panel, { placement: "bottom-start", distance: 4 });
+  });
+});
+```
+
+CSS Anchor Positioning will eventually cover the simple anchored case from the
+stylesheet alone, using that implicit anchor reference. It is still only
+partially supported and is not the documented recipe yet.
+
+**When `surface.js` owns the lifecycle**, use `data-flyout-auto-close` if the
+default click dismissal behavior is not right. Escape still follows the shared
+surface lifecycle. These options do not reach a natively managed
+`popover="auto"`, whose dismissal belongs to the browser.
 
 - `true` is the default. Clicks inside or outside close the flyout.
 - `inside` closes on inside clicks only.

package/docs/pages/enhancements/overview.md

@@ -15,7 +15,7 @@ class API, shared tokens, and progressive enhancement.
 
 ## Modules
 
-The full runtime is `actual-css/js`. Each enhancer is also importable on its own
+The full runtime is `actual-css/js/full`. Each enhancer is also importable on its own
 for projects that use custom components or want a smaller behavior surface:
 
 ```js
@@ -32,5 +32,5 @@ 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
+Status Bar. The full runtime is loaded on the docs pages, so the examples
 work with the documented markup alone.

package/docs/pages/enhancements/scrollspy.md

@@ -9,7 +9,7 @@ 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]`. |

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

@@ -15,6 +15,7 @@ runtime targets, empty by default.
 - Use it for transient status (`Saved.`, `Reconnected.`, `Copied.`). Critical, persistent, or actionable information belongs in `.alert`, inline messages, or dialogs.
 - Intents: `danger`, `success`, `warning`, `neutral`. The default (no intent) is a neutral dark pill.
 - On mobile, the runtime keeps the bar above the software keyboard by tracking `visualViewport` while a message is showing.
+- A message originating inside an open modal dialog temporarily moves the singleton bar into that dialog. This keeps it in the active top-layer and accessibility subtree; the bar returns to its original DOM position after its exit.
 
 Clearing is deferred, not immediate: the bar closes first and only empties its
 text and intent once the exit transition has finished, so it leaves at the size
@@ -77,6 +78,25 @@ document.dispatchEvent(new CustomEvent("actual:status", {
 }));
 ```
 
+Dispatch from the control or region that produced the feedback when it lives
+inside a dialog; bubbling lets the runtime infer the active surface:
+
+```js
+saveButton.dispatchEvent(new CustomEvent("actual:status", {
+  bubbles: true,
+  detail: { message: "Saved.", intent: "success" },
+}));
+```
+
+Code importing `status()` directly passes the same origin as `source`:
+
+```js
+status("Saved.", { intent: "success", source: saveButton });
+```
+
+Validation and declarative status commands propagate their source
+automatically.
+
 ## CSS hooks
 
 - `--status-bg` — bar background.

package/docs/pages/enhancements/tabs.md

@@ -5,7 +5,7 @@
 ## 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. |

package/docs/pages/enhancements/tooltip.md

@@ -17,6 +17,18 @@ with the `hidden` attribute.
 - The arrow inherits the tooltip background — custom gradients carry through automatically.
 - Avoid relying on the native `title` attribute as the primary implementation.
 
+A `.tooltip[popover]` may use a native or third-party-owned popover lifecycle.
+Actual removes the native inset, margin, and overflow that conflict with
+positioning and with the projecting arrow, while leaving bare `[popover]`
+elements untouched. The lifecycle owner must still write the fixed viewport
+coordinates and arrow position; Actual only supplies the presentation.
+
+That reset is gated on `@supports selector(:popover-open)`. Native Popover is
+optional and is not part of Actual's Minimal contract: browsers within the
+Minimal range may not support it, and there the attribute carries no behavior,
+so nothing shows or hides the tip. Use `data-tooltip` and the built-in runtime
+when the lifecycle must work across the full Minimal range.
+
 ```html demo
 <button class="btn ghost"
         type="button"

package/docs/pages/examples/overview.md

@@ -22,6 +22,8 @@ and `actual.full.js` from `dist/`, plus the theme palettes bundle from
 - [Layout reference](../../demo/templates/layouts.html) - canonical compositions built only with the layout primitives
 - [Grid density](../../demo/templates/grid.html) - the grid contracts on resizable stages, with the pitfalls called out
 - [Density](../../demo/templates/density.html) - compact control density
+- [Data grid](../../demo/templates/data-grid.html) - an external data grid component themed with Actual tokens (sort, filter, search, selection)
+- [Combobox](../../demo/templates/combobox.html) - an external combobox themed with Actual tokens (search, tags, autocomplete)
 
 ## Sites
 

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

@@ -4,10 +4,10 @@
 
 ## Class reference
 
-| Class                     | Kind      | Description                                                   |
-|---------------------------|-----------|---------------------------------------------------------------|
-| `.choice-card`            | Component | Card-style `<label>` wrapping a native radio or checkbox.     |
-| `.primary` / `.secondary` | Intent    | Intent accent for the selected state (supported on the card). |
+| Class                     | Kind      | Description                                   |
+| ------------------------- | --------- | --------------------------------------------- |
+| `.choice-card`            | Component | Card-style `<label>` around a native control. |
+| `.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.

package/docs/pages/forms/combobox.md

@@ -0,0 +1,87 @@
+# Combobox
+
+> A searchable or multi-value combobox is not shipped by the framework — the native `<select>` and `<datalist>` stay the baseline. Theme an external combobox with Actual tokens instead.
+
+The `.select` class keeps the native baseline with a CSS chevron, and the optional
+`custom-select` module adds the `appearance: base-select` native picker where the
+browser supports it. Beyond those, apply the framework's judgment from the
+[data grid template](../../demo/templates/data-grid.html) to the problem: when a
+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.
+
+## Theme bridge
+
+The [combobox template](../../demo/templates/combobox.html) themes
+[`@lekoala/combobox`](https://github.com/lekoala/combobox) entirely with Actual
+tokens: the control mirrors `.input`, chips re-derive the `.badge` soft recipe,
+and the picker popover follows `--surface-raised` and `--shadow-popout`. No
+adapter, no compatibility layer — a handful of `--cb-*` assignments and shared
+mix tokens.
+
+```html
+<label class="field actual-combobox">
+  <span class="field-label">Skills</span>
+  <combo-box placeholder="Search or add a skill…">
+    <select class="select" name="skills[]" multiple>
+      <option value="design" selected>Design</option>
+      <option value="css" selected>CSS</option>
+      <option value="javascript" selected>JavaScript</option>
+    </select>
+  </combo-box>
+</label>
+```
+
+The card in the template documents the full token map of this recipe.
+
+## Lightweight pass-through
+
+Most of the skin is three one-line token bridges. The visible vocabulary —
+surface, border, radius, focus ring, danger, hover overlay and the `--soft-*`
+mix — stays the Actual one, so light/dark mode, the preset themes and their
+contrast contracts apply to the combobox for free:
+
+```css
+.actual-combobox {
+  --cb-bg: var(--surface);
+  --cb-color: var(--text);
+  --cb-border-color: var(--border);
+  --cb-border-radius: var(--radius);
+  --cb-focus-color: var(--focus);
+  --cb-muted-color: var(--text-muted);
+  --cb-error-color: var(--danger);
+  --cb-chip-bg: transparent;
+  --cb-control-height: var(--control-size);
+  --cb-option-min-height: var(--control-size);
+}
+
+.actual-combobox .cb-control:focus-within,
+.actual-combobox .cb-text-control:focus {
+  outline: 2px solid transparent;
+  box-shadow: var(--focus-ring-shadow);
+}
+
+.actual-combobox .cb-chip-remove:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow: 0 0 0 2px var(--focus-ring);
+}
+
+.actual-combobox .cb-chip {
+  border: var(--border-width) solid
+    color-mix(in oklab, var(--surface) var(--soft-border-mix), var(--primary));
+  border-radius: var(--radius-full);
+  background: color-mix(in oklab, var(--surface) var(--soft-bg-mix), var(--primary));
+  color: color-mix(in oklab, var(--primary) var(--soft-fg-mix), var(--text));
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-strong);
+}
+```
+
+The composite focus ring follows any internal focus, not just the search
+input: focus a chip or its remove × and the control shows the same field ring,
+with the local `:focus-visible` indicator on the chip or its × on top.
+
+The same approach works for any widget that exposes a custom-property skin —
+keep the widget's behavior, restyle its tokens through the shared vocabulary.

package/docs/pages/forms/floating-field.md

@@ -7,9 +7,11 @@ the label rests inside the control and floats to the top when the control is
 focused or filled. It composes the existing `.field` layout and the text
 controls (`.input`, `.textarea`, `.select`) with zero JavaScript.
 
-The cell holds the control and its label only. Help and error messages stay in
-the surrounding `.field`, otherwise the resting label centers on the whole
-field instead of the control.
+The cell holds exactly one control and its label, with the control before the
+label. Label placement is linked through the general sibling combinator, so an
+injected node between the two (a password manager, an extension wrapper) is
+tolerated. Help and error messages stay in the surrounding `.field`, otherwise
+the resting label centers on the whole field instead of the control.
 
 ```html demo
 <div class="field">

package/docs/pages/forms/joined-controls.md

@@ -6,10 +6,10 @@
 
 ## Class reference
 
-| Class         | Kind        | Description                                                                     |
-|---------------|-------------|---------------------------------------------------------------------------------|
-| `.join`       | Composition | Visually joins adjacent controls into a single unit.                            |
-| `.join-addon` | Composition | Static prefix/suffix content such as currency symbols, units, or protocol text. |
+| Class         | Kind        | Description                                 |
+| ------------- | ----------- | ------------------------------------------- |
+| `.join`       | Composition | Joins adjacent controls into a single unit. |
+| `.join-addon` | Composition | Static prefix or suffix content.            |
 
 Add `.join` to the wrapper that groups the controls. Use `.join-addon` for static prefix/suffix content such as currency symbols, units, or protocol text. Action buttons inside the group should use `.btn`. The wrapper should still carry `role="group"` with a label for accessibility.
 

package/docs/pages/forms/labels.md

@@ -4,11 +4,14 @@
 
 ## Class reference
 
-| Class            | Kind        | Description                                                                                  |
-|------------------|-------------|----------------------------------------------------------------------------------------------|
-| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`.                                            |
-| `.field-label`   | Composition | Label text, element-agnostic — works on `<span>`, a detached `<label for>`, or a `<legend>`. |
-| `.required-mark` | Composition | Visual required marker (`aria-hidden`) added inside a label.                                 |
+| Class            | Kind        | Description                                       |
+| ---------------- | ----------- | ------------------------------------------------- |
+| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`. |
+| `.field-label`   | Composition | Label text, element-agnostic.                     |
+| `.required-mark` | Composition | Visual required marker (`aria-hidden`).           |
+
+`.field-label` works on a `<span>`, on a detached `<label for>`, or on a
+`<legend>`. `.required-mark` goes inside a label.
 
 Use a **wrapped label** for simple hand-authored forms. The whole label area becomes the click target, there is no `id` noise, and the markup is harder to break.
 

package/docs/pages/forms/overview.md

@@ -9,27 +9,34 @@
 - Proper focus style that preserves keyboard navigation.
 - `.field-group` and `.choice` provide layout without depending on parent scope.
 - Customizable select is progressive enhancement only — the native select remains the baseline.
+- Searchable selects, tags and autocomplete are a JavaScript widget concern; theme an external combobox with Actual tokens — see the [combobox template](../../demo/templates/combobox.html).
 
 ## Class reference
 
-| Class           | Kind        | Description                                                                   |
-|-----------------|-------------|-------------------------------------------------------------------------------|
-| `.input`        | Component   | Text input; shares the text-control recipe with `.textarea` and `.select`.    |
-| `.textarea`     | Component   | Multi-line text control.                                                      |
-| `.select`       | Component   | Dropdown — native baseline with a CSS chevron and an opt-in enhanced picker.  |
-| `.check`        | Component   | Styled checkbox.                                                              |
-| `.radio`        | Component   | Styled radio button.                                                          |
-| `.switch`       | Component   | Toggle switch on a checkbox input with `role="switch"`.                       |
-| `.range`        | Component   | Native range slider with a theme-aware accent color.                          |
-| `.file`         | Component   | Native file input with a themed picker button.                                |
-| `.color`        | Component   | Native color picker in a control-sized box.                                   |
-| `.field`        | Composition | Field wrapper that works on `<label>` and `<div>`.                            |
-| `.field-label`  | Composition | Label text; element-agnostic — `<span>`, detached `<label>`, or `<legend>`.   |
-| `.field-help`   | Composition | Supporting helper text under a control.                                       |
-| `.field-error`  | Composition | Inline error message shown while the field is invalid.                        |
-| `.field-group`  | Composition | Grouped `<fieldset>` container with a tunable legend gutter.                  |
-| `.choice`       | Composition | Choice-label layout wrapping a `.check`, `.radio`, or `.switch`.              |
-| `.form-actions` | Composition | Class-only flex row that closes a form; works inside or outside the `<form>`. |
+| Class           | Kind        | Description                                   |
+| --------------- | ----------- | --------------------------------------------- |
+| `.input`        | Component   | Text input.                                   |
+| `.textarea`     | Component   | Multi-line text control.                      |
+| `.select`       | Component   | Dropdown, native baseline with a CSS chevron. |
+| `.check`        | Component   | Styled checkbox.                              |
+| `.radio`        | Component   | Styled radio button.                          |
+| `.switch`       | Component   | Toggle switch on a `role="switch"` checkbox.  |
+| `.range`        | Component   | Native range slider, theme-aware accent.      |
+| `.file`         | Component   | Native file input, themed picker button.      |
+| `.color`        | Component   | Native color picker in a control-sized box.   |
+| `.field`        | Composition | Field wrapper, on `<label>` or `<div>`.       |
+| `.field-label`  | Composition | Label text, element-agnostic.                 |
+| `.field-help`   | Composition | Supporting helper text under a control.       |
+| `.field-error`  | Composition | Inline error message, shown while invalid.    |
+| `.field-group`  | Composition | `<fieldset>` with a tunable legend gutter.    |
+| `.choice`       | Composition | Choice-label layout around an inline control. |
+| `.form-actions` | Composition | Class-only flex row that closes a form.       |
+
+`.input` shares the text-control recipe with `.textarea` and `.select`, and
+`.select` also has an opt-in enhanced picker. `.field-label` works on a
+`<span>`, a detached `<label>` or a `<legend>`. `.choice` wraps a `.check`,
+`.radio` or `.switch`, and `.form-actions` works inside or outside the
+`<form>`.
 
 ## Example form
 

package/docs/pages/forms/password.md

@@ -1,8 +1,9 @@
 # Password Toggle
 
 > A password field reveals its value through a linked button. The markup is a
-> plain command invoker; the behavior ships with the JS runtime
-> (`actual-css/js` or `actual-css/js/password`).
+> plain command invoker; the behavior ships with the full JS runtime
+> (`actual-css/js/full`) and can also be imported independently
+> (`actual-css/js/password`).
 
 Point a `button` at the input with `commandfor` and
 `command="--password-toggle"`. Use `.join` when the button should sit attached

package/docs/pages/forms/range.md

@@ -1,8 +1,11 @@
 # Range
 
-> Native range inputs with theme-aware accent color.
+> Native range input with a lightweight theme-aware custom skin.
 
-Core: native range, enhanced by `accent-color`. Optional richer skin may come later.
+`.range` keeps the native range control and its interaction semantics, while
+customizing the track, thumb, focus state, intents, and disabled state. The
+focus ring targets the thumb — the surface the user actually manipulates —
+rather than the CSS box.
 
 **Related terms:** slider, range input, scrubber.
 
@@ -13,7 +16,15 @@ Core: native range, enhanced by `accent-color`. Optional richer skin may come la
 </label>
 ```
 
+Actual deliberately does not emulate filled tracks, tick marks, value labels,
+or multi-thumb ranges. Those still require engine-specific pseudo-elements or a
+value duplicated out of the HTML into CSS. Prefer the platform as richer range
+styling becomes interoperable — see
+[Enhanced range controls](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/platform-alignment.md).
+
 ## CSS hooks
 
 - `--range-thumb-size` — thumb diameter.
 - `--range-track-height` — track thickness.
+- `--range-thumb-bg` — thumb color. Defaults to the local intent, then `--primary`.
+- `--range-track-bg` — track color.

package/docs/pages/forms/states-and-sizes.md

@@ -4,10 +4,12 @@
 
 ## Class reference
 
-| Class | Kind     | Description                                                                              |
-|-------|----------|------------------------------------------------------------------------------------------|
-| `.sm` | Modifier | Compact control height and spacing rhythm; sets `--control-size` to `--control-size-sm`. |
-| `.lg` | Modifier | Large control height and spacing rhythm; sets `--control-size` to `--control-size-lg`.   |
+| Class | Kind     | Description                                |
+| ----- | -------- | ------------------------------------------ |
+| `.sm` | Modifier | Compact control height and spacing rhythm. |
+| `.lg` | Modifier | Large control height and spacing rhythm.   |
+
+Each sets `--control-size` to `--control-size-sm` or `--control-size-lg`.
 
 Use `readonly` for text-like values that can still be focused, selected, and submitted. Use `disabled` for unavailable controls that should not receive focus or submit a value.
 

package/docs/pages/forms/validation.md

@@ -6,14 +6,18 @@
 
 ## Class reference
 
-| Class               | Kind        | Description                                                                     |
-|---------------------|-------------|---------------------------------------------------------------------------------|
-| `.field-error`      | Composition | Canonical inline error message; shown while the field is invalid.               |
-| `.field-help`       | Composition | Canonical helper text; carries supporting copy before and after validation.     |
-| `.field.danger`     | Modifier    | Manual invalid marking on the field wrapper.                                    |
-| `.needs-validation` | Modifier    | Opt-in class for the validation enhancer and `:user-invalid` styling.           |
-| `.was-validated`    | Modifier    | Added to the form by the enhancer after the first submit attempt.               |
-| `.status-bar`       | Component   | Optional status element that shows `data-validation-message` on invalid submit. |
+| Class               | Kind        | Description                                  |
+| ------------------- | ----------- | -------------------------------------------- |
+| `.field-error`      | Composition | Canonical inline error message.              |
+| `.field-help`       | Composition | Canonical helper text.                       |
+| `.field.danger`     | Modifier    | Manual invalid marking on the wrapper.       |
+| `.needs-validation` | Modifier    | Opt-in for the enhancer and `:user-invalid`. |
+| `.was-validated`    | Modifier    | Set by the enhancer after a submit attempt.  |
+| `.status-bar`       | Component   | Optional form-level status element.          |
+
+`.field-error` shows while the field is invalid; `.field-help` carries
+supporting copy before and after validation. `.status-bar` shows
+`data-validation-message` on an invalid submit.
 
 - `.field-error` is the canonical error message. It is wired to `aria-invalid="true"` via the input, so the visual border and the assistive-tech announcement move together.
 - `.field-help` is the canonical helper text. It carries supporting copy before and after validation.
@@ -49,7 +53,7 @@
 
 Native validation first; the enhancer only adds state and focus behavior.
 
-Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the default runtime (`actual-css/js`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
+Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the full runtime (`actual-css/js/full`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
 
 Opt in with the `.needs-validation` class. Importing the module registers the behavior; there is no init call.
 

package/docs/pages/foundations/philosophy.md

@@ -75,6 +75,19 @@ As inherited contexts, one class tightens or loosens the whole subtree:
 </div>
 ```
 
+Application chrome can use the same scope; no separate `.compact` mode is
+needed:
+
+```html demo
+<header class="navbar sm">
+  <a class="navbar-brand" href="/">Workspace</a>
+  <nav class="cluster" aria-label="Workspace actions">
+    <button class="btn ghost">Search</button>
+    <button class="btn primary">Create</button>
+  </nav>
+</header>
+```
+
 The same class on a component is local density, not a second meaning:
 
 ```html demo
@@ -86,7 +99,8 @@ This is not "`.sm` sometimes means density and sometimes size": `.sm` always
 establishes the same density tokens — only the scope changes. The density
 tokens are `--gap`, `--density-space`, `--control-size`, and
 `--density-compact-size`. Components consume the dimensions that make sense
-for them and opt out of the rest.
+for them and opt out of the rest. The absolute `--space-*` scale is not rebound
+by density scopes.
 
 Components with bespoke sizing (`.avatar`, `.spinner`) define local `.sm`/`.lg`
 instead of consuming the shared tokens.

package/docs/pages/foundations/theming.md

@@ -70,6 +70,14 @@ Native controls that no component class restyles — a bare checkbox, radio, ran
 
 → Forms · Overview · Foundations · Tokens (theme contract)
 
+### Store a theme name without applying it
+
+`data-theme` is an active theme boundary on every element that carries it, not
+a generic storage attribute. Use a different name such as `data-theme-value`,
+or a form control's `value`, when the element should only hold a theme name.
+Apply `data-theme` deliberately when that element and its subtree should paint
+with the selected palette — a theme swatch is a useful example.
+
 ### Loading / busy overlay on a container
 
 Use `aria-busy="true"` with a direct last-child `.spinner`; tint the overlay with `--busy-overlay-bg`.

package/docs/pages/foundations/tokens.md

@@ -247,6 +247,7 @@ Icons used by CSS-only controls are public tokens because users may need to repl
   --icon-chevron: url("data:image/svg+xml,...");
   --icon-check: url("data:image/svg+xml,...");
   --icon-close: url("data:image/svg+xml,...");
+  --icon-plus: url("data:image/svg+xml,...");
 }
 ```
 
@@ -275,12 +276,14 @@ Under `forced-colors: active`, `--backdrop-fill` maps to `Canvas`.
 
 A small z-index scale orders non-dialog overlays. Native `<dialog>` elements (modal, drawer) render on the platform top-layer, which has no numeric z-index and always paints above the page — they never compete with this scale.
 
-| Token         | Value | Used by                                                                           |
-|---------------|-------|-----------------------------------------------------------------------------------|
-| `--z-sticky`  | 10    | Sticky page chrome (`form-actions.sticky`, `topbar`).                             |
-| `--z-menu`    | 20    | Floating menus (`flyout`); `.surface-backdrop` sits at `calc(var(--z-menu) - 1)`. |
-| `--z-tooltip` | 50    | Tooltips.                                                                         |
-| `--z-status`  | 60    | `status-bar`.                                                                     |
+| Token         | Value | Used by                         |
+| ------------- | ----- | ------------------------------- |
+| `--z-sticky`  | 10    | `form-actions.sticky`, `topbar` |
+| `--z-menu`    | 20    | Floating menus (`flyout`)       |
+| `--z-tooltip` | 50    | Tooltips                        |
+| `--z-status`  | 60    | `status-bar`                    |
+
+`.surface-backdrop` sits just under the menus, at `calc(var(--z-menu) - 1)`.
 
 Stacking-context traps: a flyout or tooltip that is a DOM descendant of a dialog, or of a container with `transform`, `filter`, `contain`, `isolation`, or `will-change`, is confined to that ancestor's stacking context. Its z-index token only orders it against siblings within that context. When a dialog's top-layer clips a descendant flyout, move the flyout markup outside the dialog or use a portal/popover to escape the stacking context.
 

package/docs/pages/foundations/typography.md

@@ -66,7 +66,7 @@ documentation homepages) import it manually:
 The module exposes three size tokens and three composed classes. It is deliberately not the foundation: body text, app UI, and the default prose scale stay static.
 
 | Token             | Class           | Purpose                               |
-|-------------------|-----------------|---------------------------------------|
+| ----------------- | --------------- | ------------------------------------- |
 | `--fluid-display` | `.text-display` | Hero / display sizes.                 |
 | `--fluid-title`   | `.text-title`   | Section titles.                       |
 | `--fluid-lead`    | `.text-lead`    | Intro paragraphs on display surfaces. |