actual-css 0.10.0 → 0.11.1

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/examples/overview.md

@@ -28,6 +28,7 @@ Whole pages, composed the way a real product would.
 - [Marketing](../../demo/templates/marketing.html) - landing page with typography and fluid type
 - [Blog](../../demo/templates/blog.html) - article page with prose
 - [Settings modal](../../demo/templates/settings-modal.html) - two-pane preferences dialog, with the local CSS it needs audited rule by rule
+- [Modal patterns](../../demo/templates/modal-patterns.html) - eight application modals, each the modal surface plus the smallest application CSS it needs
 - [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and a local segmented tab treatment
 - [Card compositions](../../demo/templates/card-compositions.html) - editorial, team, sign-in and horizontal cards composed from existing primitives
 - [Register form](../../demo/templates/register-form.html) - registration page with choice cards, masks, the password toggle, `tel-prefix` validation, an OTP verification dialog, and status feedback

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 —

package/docs/pages/forms/overview.md

@@ -10,6 +10,9 @@
 - `.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).
+- Formatted text (bold, lists, links) is a hosted-editor concern; the native textarea stays the baseline and an external engine is themed the same way — see the [rich-text template](../../demo/templates/rich-text.html) and the [composer template](../../demo/templates/composer.html) for the plain-text case.
+
+**Related terms:** form controls, select, custom select, dropdown, input, textarea, checkbox, radio.
 
 ## Class reference
 
@@ -181,7 +184,7 @@ it a stronger fill.
 - Use native `<optgroup>` and `disabled` options in `.select` controls when applicable; the customizable picker preserves both as a progressive enhancement.
 - `.choice` is the choice-label API. Use `.check` or `.radio` on the nested control. The control goes first, the label group second, so multi-line labels align the control with the first line.
 - For a switch, use `class="switch"` and `role="switch"`.
-- Core range controls stay native and are enhanced by `accent-color`. An optional richer range skin may come later if real projects need it.
+- `.range` skins the native range control (`appearance: none` track, thumb, and focus ring). Add `data-enhance="range"` for the fill share, named `datalist` values, and output sync.
 - `.form-actions` carries a default top margin. Override it with `--form-actions-margin-block-start`, `--form-actions-align`, or `--form-actions-justify`. It is class-only and may live inside or outside `<form>`. See Detached Actions below.
 - `.join` visually joins adjacent controls into a single unit. Use `.join-addon` for static prefix/suffix content. The container still carries `role="group"` for accessibility.
 

package/docs/pages/forms/range.md

@@ -12,14 +12,117 @@ rather than the CSS box.
 ```html demo
 <label class="field">
   <span class="field-label">Volume</span>
-  <input class="range" type="range" min="0" max="100" value="50" />
+  <input class="range" data-enhance="range" type="range" min="0" max="100" value="50" />
 </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
+## Fill
+
+`data-enhance="range"` opts into the `actual-css/js/range` behavior. It writes
+`--range-progress`, the fill share the track gradient reads, and keeps it in
+sync on input and after a form reset, including inputs associated through
+`form="…"`. Without it the variable stays at its `0%` default and the track
+renders plain — the control stays fully usable without JavaScript. The fill
+follows the writing direction, and a bare `input[type="range"]` without the
+`.range` class can opt in the same way.
+
+## Named values
+
+A `datalist` is the source of truth for discrete named steps: positions plus
+names. Browsers render its ticks and labels inconsistently, so Actual never
+depends on their presentation — the enhancement only reads `option` values and
+their `label`. A matching label sets `aria-valuetext` on the input and mirrors
+into each `<output for="…">`. The output is the visible value, not the input's
+name — give the input its own accessible name, since `for` only declares the
+output's operands.
+
+```html demo
+<div class="field">
+  <output class="field-label" for="effort">High</output>
+  <input
+    class="range"
+    data-enhance="range"
+    id="effort"
+    type="range"
+    min="0"
+    max="3"
+    step="1"
+    value="2"
+    list="effort-levels"
+    aria-label="Effort"
+  />
+  <datalist id="effort-levels">
+    <option value="0" label="Minimal"></option>
+    <option value="1" label="Standard"></option>
+    <option value="2" label="High"></option>
+    <option value="3" label="Maximum"></option>
+  </datalist>
+</div>
+```
+
+`aria-valuetext` is the announced value when a number really means a text; keep
+it even if the visible `output` changes shape. An `output` is a live region,
+so verify with a screen reader that the two do not double-announce.
+
+## In a flyout
+
+The range stays an `input`, the flyout stays a flyout — together they read as
+a richer picker with no new component. `data-flyout-auto-close="outside"` keeps
+dragging the slider from closing the panel.
+
+```html demo
+<div class="flyout-trigger">
+  <button
+    class="btn outline"
+    type="button"
+    data-enhance="flyout"
+    aria-expanded="false"
+    aria-controls="effort-picker"
+  >
+    Reasoning effort
+  </button>
+
+  <div
+    class="flyout"
+    id="effort-picker"
+    data-flyout-auto-close="outside"
+    style="--flyout-inline-size: 16rem; --flyout-pad: var(--space-40)"
+    hidden
+  >
+    <div class="field">
+      <output class="field-label text-center" for="effort-flyout">High</output>
+
+      <input
+        class="range"
+        data-enhance="range"
+        id="effort-flyout"
+        type="range"
+        min="0"
+        max="3"
+        step="1"
+        value="2"
+        list="effort-flyout-levels"
+        aria-label="Reasoning effort"
+      >
+
+      <datalist id="effort-flyout-levels">
+        <option value="0" label="Minimal"></option>
+        <option value="1" label="Standard"></option>
+        <option value="2" label="High"></option>
+        <option value="3" label="Maximum"></option>
+      </datalist>
+    </div>
+
+    <div class="cluster" style="--cluster-justify: center">
+      <button class="btn primary sm" type="button" data-flyout-close>Done</button>
+    </div>
+  </div>
+</div>
+```
+
+Actual deliberately does not emulate tick marks or multi-thumb ranges. Ticks
+still need engine-specific pseudo-elements; the fill above is designed for
+deletion once `::slider-fill` is interoperable — see
 [Enhanced range controls](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/platform-alignment.md).
 
 ## CSS hooks
@@ -28,3 +131,5 @@ styling becomes interoperable — see
 - `--range-track-height` — track thickness.
 - `--range-thumb-bg` — thumb color. Defaults to the local intent, then `--primary`.
 - `--range-track-bg` — track color.
+- `--range-fill-bg` — filled portion color. Defaults to the local intent, then `--primary`.
+- `--range-progress` — fill share. Written by `actual-css/js/range`, never set by hand.

package/docs/pages/forms/rich-text.md

@@ -0,0 +1,110 @@
+# Rich text
+
+> A rich-text editor is not shipped by the framework — the native `<textarea>` stays the baseline. Enhance it with a dedicated engine, themed with Actual tokens.
+
+Use a `<textarea>` while editing text, and a hosted editing engine as soon as
+editing means a document (formatting, lists, links, mentions). The
+[rich-text template](../../demo/templates/rich-text.html) enhances a textarea
+with [@lekoala/rich-text](https://github.com/lekoala/rich-text) (Squire
+underneath): the package generates the toolbar with its roving tabindex,
+states, commands and lifecycle, while Actual maps its visual language onto the
+package's `--rt-*` tokens. No adapter, no compatibility layer.
+
+**Related terms:** rich text, richtext, WYSIWYG, HTML editor, formatted text, Squire, ProseMirror, Tiptap, text formatting, bold italic, mentions, slash commands.
+
+## Theme bridge
+
+The template loads the package JS and CSS from a CDN (`@0.2` caret range) and
+declares one editor per field — Actual never builds toolbar buttons or calls
+into the editing engine:
+
+```html
+<div class="field actual-rich-text">
+  <label class="field-label" for="note">Team note</label>
+  <rich-text id="note-editor">
+    <textarea class="textarea" id="note" name="note" required placeholder="Write a note…"></textarea>
+  </rich-text>
+  <span class="field-help">Bold, italic, lists, quotes and links.</span>
+</div>
+```
+
+```js
+editor.options = {
+  buttons, // Tabler icons as Nodes, never HTML strings
+  requestLink, // an Actual <dialog> replacing window.prompt()
+  suggestions, // static @people and /snippets providers
+};
+```
+
+The bridge maps tokens; it does not restyle the editor's internals:
+
+```css
+.actual-rich-text .rt-shell {
+  --rt-bg: var(--surface);
+  --rt-fg: var(--text);
+  --rt-border: var(--form-invalid-border, var(--control-border, var(--border)));
+  --rt-divider: var(--border);
+  --rt-focus: var(--form-invalid-border, var(--focus));
+  --rt-toolbar-bg: var(--surface-subtle);
+  --rt-button-pressed-bg: var(--state-selected);
+  --rt-link: var(--primary);
+  --rt-suggestion-bg: var(--surface-raised);
+  --rt-suggestion-shadow: var(--shadow-popout);
+}
+```
+
+The card in the template documents the full token map of this recipe. The
+suggestion popover is a child of `.rt-shell`, so it inherits the tokens like
+the rest of the editor. `--rt-border` paints only the field frame, so the
+invalid and hover hooks never reach the toolbar separators or the quote bar,
+which follow `--rt-divider`.
+
+## Bridge contract
+
+`@lekoala/rich-text` owns the editor UI semantics — progressive enhancement,
+sanitization, toolbar behaviour and keyboard, links, `@mentions`, `/`
+suggestions, form/reset/readonly/disabled integration, selection and undo
+lifecycle. Actual owns presentation and composer chrome — tokens, visual
+states, dialogs, attachments, send, `Ctrl/Cmd+Enter`.
+
+Formatting buttons stay local to the editor instance. The stateless `command`
+router never drives bold/italic: those depend on selection, schema and history,
+which only the engine knows. Reserve `command` for the chrome around the
+editor (attach, template, dictate, send).
+
+A rich composer reuses `.composer` and `.composer-actions` for the outer
+surface; the bridge only lifts the editor and toolbar into the composer grid
+with `display: contents` and grid areas. `composer.css` itself never knows
+about `.rt-*`. The plain-text [composer template](../../demo/templates/composer.html)
+stays the canonical pattern when editing means text, not a document.
+
+People lookup and templates are application concerns: the demo wires static
+arrays into the package's suggestion seam, and the composer buttons type
+`@`/`/` so the providers do the rest. Attachments stay composer-owned —
+logged, never serialized into the HTML.
+
+## Storage and sanitization
+
+The form submits limited HTML, not engine state: portable, readable,
+editor-independent, reversible. Sanitization is mandatory inside the package
+and not configurable; the client-side sanitizer is a UI boundary, not the
+persistence security boundary — sanitize again on the server before storing or
+rendering untrusted content. An editor holding only the empty block serializes
+to `""`, so native `required` keeps working.
+
+If the product later needs truly structural content (custom document nodes,
+annotations, collaboration), a schema-based engine becomes interesting — see
+the [rich-text design note](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/rich-text.md).
+
+## Baseline traps
+
+The textarea is the value owner and the no-JS fallback, holding raw HTML. Two
+details keep it honest:
+
+- Without the integration script the page remains a plain textarea — the link
+  dialog wiring and the suggestion providers only exist once the package
+  loads, and the composer falls back to plain-text send.
+- `required` cannot sit usefully on a hidden textarea: mirror validity with
+  `aria-invalid` on submit (the package emits `richtext:invalid` and focuses
+  the editor when it is the form's first invalid control), and let the bridge
+  re-own the danger hook from there.

package/docs/pages/forms/validation.md

@@ -55,7 +55,11 @@ 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 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.
+Opt in with `data-enhance="validation"` on the form; `.needs-validation` alone
+only enables the CSS feedback. Importing the module registers the behavior;
+there is no init call. To opt in forms you cannot mark up, call
+`applyEnhancement("validation", "form.needs-validation")` from
+`actual-css/js/enhance`.
 
 ```html demo
 <form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">

package/docs/pages/foundations/theming.md

@@ -122,9 +122,9 @@ application CSS and keep forms and intent ink out of it:
 
 ```css
 .site-band {
-  --heading: var(--surface);
+  --heading: var(--surface-solid-fg);
   background: var(--surface-solid);
-  color: var(--surface);
+  color: var(--surface-solid-fg);
 }
 ```
 
@@ -135,6 +135,49 @@ there: the theme contract keeps `--focus` at 3:1 on `--surface-solid`.
 
 → Foundations · Tokens (theme contract) · Examples · Contrast contexts
 
+### Scope a theme to one section / microtheme / theme island
+
+Any `data-theme` value is an island, not only `light` and `dark`:
+`<aside data-theme="promo">` paints its subtree with that theme, nested inside
+the page theme, without changing the markup. The same painting rule applies as
+for a dark section. A theme can change radius, typography, shadow and motion as
+well as color.
+
+→ Foundations · Tokens (theme contract)
+
+### Dark mode toggle / theme switcher / remember the user's choice
+
+Actual CSS ships the mechanism, not the control. Without `data-theme` the page
+follows the OS; `data-theme="light"` or `"dark"` on `<html>` forces a scheme,
+and removing the attribute returns to the OS. The switcher UI and where the
+choice is stored belong to the application; a page with no setting already
+follows the OS. Apply a stored choice from an inline script in `<head>` so the
+first paint does not flash the OS scheme. The demo's theme picker is an
+inspection tool, not a component to copy.
+
+### Force light or dark on a theme that has both / theme and color scheme
+
+With a single brand theme, `data-theme="light"` and `"dark"` already are that
+choice once you redefine them as your brand's two schemes (see the dark section
+above).
+
+A named theme that pairs both schemes through `light-dark()` follows the OS. To
+pin one scheme, set `color-scheme` on the element that carries `data-theme`,
+inline or in a rule more specific than the theme's own. `color-scheme` is the
+scheme axis and `data-theme` the design axis, so there is no separate
+`data-color-scheme` attribute.
+
+```html
+<html data-theme="ocean" style="color-scheme: dark">
+```
+
+On an ancestor it has no effect: the theme declares its own `color-scheme` on
+its boundary. Leave single-scheme themes (`color-scheme: dark` only) alone —
+their tokens have one value, so forcing the other scheme only flips native
+controls and scrollbars.
+
+→ Foundations · Tokens (theme contract)
+
 ### Replace the palette with my own brand
 
 Override the whole minimal recolor set (Tokens · Theme contract), not just
@@ -165,4 +208,7 @@ line. Use `.badge.soft` for a subtle badge. It is a visual theme, not a
 Bootstrap compatibility layer. The `gradient` example keeps a Bootstrap 4 style
 outer halo on focused fields, for comparison. The `material` example restyles
 fields as filled underlines with pill buttons — tokens plus three small rules,
-and `.join` still needs no adaptation.
+and `.join` still needs no adaptation. The `glass` example paints translucent
+surfaces over its own backdrop: it sets `--surface-opaque` and
+`--surface-solid-fg` to opaque values, raises `--soft-bg-mix` so soft fills stay
+light over glass, and adds the blur and an opaque busy veil as small rules.