actual-css 0.9.2 → 0.11.0

package/docs/pages/foundations/theming.md

@@ -96,27 +96,119 @@ Set `--avatar-size` / `--avatar-radius`; tune overlap with `--avatar-stack-overl
 
 → Components · Avatar
 
-### Make an inverted / contrasting surface
-
-Apply `.inverted` to create one contrasting surface context. It paints a bare
-block (`<header class="inverted">`, `<section class="inverted">`) with
-`--surface-solid` and `--surface`; contextual content and transparent treatments
-follow that foreground. Apply it directly to a component that consumes the
-shared `--ui-*` contract when that component itself is the contrasting surface.
-
-Surface-owning descendants keep their own component surface and establish a new
-foreground context. Use `data-theme="dark"`, `data-theme="light"`, or a named
-theme instead when an entire subtree — including forms, states, and nested
-surfaces — must use another palette. More specific component states or explicit
-surface variants (`.card.subtle`) still take precedence.
-
-→ Components · Card · Foundations · Tokens (theme contract)
+### Make a dark (or light) section / inverted, inverse, contrasting band
+
+Put `data-theme="dark"` (or `"light"`) on the section, footer, navbar or card.
+The island recomputes every token — surfaces, text, fields, validation,
+intents, focus and native controls — so a form or a `.primary.outline` inside
+it reads correctly. In a branded application, `[data-theme="light"]` and
+`[data-theme="dark"]` are the scheme roles of your brand: redefine them after
+Actual CSS and the island follows your palette.
+
+```html
+<footer data-theme="dark">…</footer>
+<article class="card" data-theme="dark">…</article>
+```
+
+The island recomputes tokens but paints nothing. A `.card` paints its own
+surface; any other element needs `background: var(--surface)` and
+`color: var(--text)`, or its ink lands on the page theme's background. A
+`<legend>` straddles its fieldset's border, outside the fieldset's surface, so
+put the island on a wrapper, not on the `<fieldset>`.
+
+Actual has no class that inverts only part of a subtree. When all you need is
+a painted band with neutral content and filled buttons, write it in
+application CSS and keep forms and intent ink out of it:
+
+```css
+.site-band {
+  --heading: var(--surface-solid-fg);
+  background: var(--surface-solid);
+  color: var(--surface-solid-fg);
+}
+```
+
+Transparent treatments (`.btn.outline`, `.ghost`, `.link`) and headings follow
+that ink; fields, their labels and help text, and intent colors keep the page
+palette, which nothing tunes for `--surface-solid`. Focus lines stay readable
+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
+`--primary`. Every neutral of the default theme — surfaces, text, border,
+`--neutral`, `--hover-overlay`, `--shadow-color` — is tinted toward the default
+primary and never derived from `--primary` at runtime, so a partial override
+leaves the default identity in the greys. `report:theme-contrast` checks
+contrast, not a leftover tint.
+
+Soft ink is the other half. The default palette ships calibrated
+`--*-soft-fg` hooks; any other theme falls back to the `--soft-fg-mix`
+derivation, which is a single global percentage and therefore guarantees
+nothing about your intents. Verify with `bun run report:theme-contrast`, then
+lower `--soft-fg-mix` or declare the per-role hooks for the intents that miss.
+
+→ Foundations · Tokens (theme contract)
 
 ### Use or adapt a preset palette
 
 `src/css/themes/` holds example palettes (`ocean`, `spruce`, `neon`, `brutalist`, …) as
 reference material to copy into your own `[data-theme]` island — they are demo
 assets, not package entrypoints. Each sets the intent/surface/text tokens and
-lets the core derive everything else. In browsers with `color-mix()` support,
-`--focus-ring` follows each island's `--focus` automatically; re-declare it only
-for a deliberate visual override or a matching legacy fallback.
+lets the core derive everything else.
+
+The `bootstrap-v6` example follows Bootstrap 6's blue palette, stronger subtle
+surfaces, filled badges, and steady select hover; its focus is the core solid
+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. 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.

package/docs/pages/foundations/tokens.md

@@ -17,6 +17,24 @@ Component custom properties fall into three header categories in the source: **P
 
 As a convention, component-prefixed properties owned by the component's base rule are usually author hooks. Properties owned by states/variants, derived from other hooks, or written by JavaScript are not. This convention is indicative, not algorithmic: runtime-written, derived, and state-relay properties stay internal even when their form resembles a hook.
 
+### Where a token is declared
+
+A hook is only defined inside the scope that declares it. Reading one outside that scope is not an error a browser reports: `var()` resolves to nothing, the whole declaration becomes invalid at computed-value time, and the property falls back to its initial value — `padding: var(--card-pad)` outside a card computes to `0`, silently.
+
+| Scope     | Declared on                 | Examples                               |
+| --------- | --------------------------- | -------------------------------------- |
+| Global    | `:root`, every theme island | `--space-40`, `--radius`, `--primary`  |
+| Component | the component's base rule   | `--card-pad`, `--drawer-size`          |
+| Relay     | a variant, state, or script | `--ui-bg`, `--intent`, `--surface-pad` |
+
+Global tokens are the ones to reach for in application CSS. Write a relay only to override what a variant sets on one element (Button · Variants); read one only where its owner documents it (`--bleed-pad`). When you do want a component token outside its component — matching a bare block to the card rhythm, say — give `var()` the default explicitly, so the declaration survives where the hook is absent:
+
+```css
+.panel {
+  padding: var(--card-pad, var(--space-40));
+}
+```
+
 ### Color
 
 Intent tokens are used by `.primary`, `.secondary`, `.success`, `.warning`, `.danger`, and `.neutral`. They are curated color/foreground pairs. Actual CSS does not compute foregrounds automatically in the core theme contract.
@@ -58,21 +76,27 @@ Surface tokens describe the canvas and elevation model. Components should prefer
 }
 ```
 
-The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the dark inverse surface, used for accent areas).
+The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the inverse surface, used for accent areas).
+
+Surfaces are painted material and may be translucent. Two roles must stay opaque, so they have their own tokens, both defaulting to `--surface`:
+
+- `--surface-solid-fg` — the ink on `--surface-solid`: tooltips, the status bar, an inverse band.
+- `--surface-opaque` — an opaque neutral used where a component must hide or separate what is painted beneath it: the status-dot and avatar-stack rings, range-thumb and meter separators, step markers, the mask under an `.aura` child. It is not a surface fill; paint panels with `--surface-*`.
+
+A theme with translucent surfaces overrides both with opaque values.
 
 Use `*-fg` pairs only for solid backgrounds where the component controls both foreground and background. Do not require a foreground token for every surface token.
 
-Focus styling is outline-first. `--focus` names the theme's focus color, and a ring is derived from it with `color-mix()`. A global focus baseline applies `--focus-outline` and `--focus-outline-offset`: older browsers show it on `:focus`, while modern browsers limit it to `:focus-visible`. Components add `--focus-ring-shadow` only where a softer halo helps; `--focus-ring-width` sets its thickness. Under `forced-colors: active`, the outline maps to `Highlight` and the shadow is disabled.
+Focus styling is outline-first. A global focus baseline applies `--focus-outline` and `--focus-outline-offset`: older browsers show it on `:focus`, while modern browsers limit it to `:focus-visible`. The baseline is a `currentColor` line, so text-like elements (links, `summary`, nav and menu items) follow whatever surface the application painted. Boxed components draw a solid `--focus-ring-width` line in `--focus`: inside the border box on text fields (`.input`, `.textarea`, `.select`), outside at `--focus-outline-offset` on actions (`.btn`, `.close`, choices, switches). The color never follows an intent or a local surface, so `--focus` must hold 3:1 against both `--surface` and `--surface-solid` — the page, fields and a solid band all rely on it. Both lines are `--focus-ring-width` wide. Under `forced-colors: active`, outlines map to the system focus color.
 
 ```css
 :root {
-  --focus: var(--neutral);
+  --focus: hsl(268 30% 55%);
 
   --focus-outline-color: currentColor;
-  --focus-outline: calc(var(--border-width) * 2) solid var(--focus-outline-color);
+  --focus-outline: var(--focus-ring-width) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
-  --focus-ring-width: 3px;
-  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
+  --focus-ring-width: 2px;
 }
 ```
 
@@ -364,7 +388,7 @@ A few cross-component helpers:
 ```css
 :root {
   --indicator-offset: 14.65%;      /* circle-aware inset */
-  --indicator-ring: var(--surface);
+  --indicator-ring: var(--surface-opaque);
   --backdrop-color: rgb(0 0 0);
   --backdrop-opacity: 0.45;
   --backdrop-fill: rgb(0 0 0 / var(--backdrop-opacity));
@@ -445,9 +469,7 @@ Text controls (`.input`/`.textarea`/`.select`) expose the same lower-edge extens
 
 Alerts expose the same idea on the leading edge instead of the lower one: `--alert-border-inline-start-color` and `--alert-border-inline-start-width` are unset by default and fall back to the regular `--ui-border`, so a theme can turn an alert into a callout with a colored flag on the inline-start side, matching the classic notice pattern, without a per-variant override.
 
-A theme is not limited to the tokens above; it can restate any component-local token under a state selector to change the interaction recipe itself, not just the palette. The `edge` theme does this for focus: the base input recipe (forms/control.css) flips `--control-border` to `--focus` on top of the shared outline + ring, which would stack with a lower-edge accent. Edge instead restores `--control-border` under `:focus-visible` and thickens the accent edge so the edge, not a second ring, carries the focus.
-
-Buttons don't consume `--focus-outline` — button.css computes its own ring inline so the color can follow `--btn-focus-color` (intent-aware, unlike the plain `--focus`). It reuses the shared `--focus-ring-width` for the ring thickness and derives the color through `--btn-focus-ring-color` (a `color-mix()` of `--btn-focus-color` when supported, falling back to the shared `--focus-ring`).
+A theme is not limited to the tokens above; it can restate any component-local token or rule under a state selector to change the interaction recipe itself, not just the palette. The `gradient` theme does this for field focus: it restores a `--focus` border plus an outer translucent halo in place of the core inset outline.
 
 Rules:
 
@@ -464,9 +486,13 @@ Rules:
 
 Themes override tokens, not selectors. The themes in `src/css/themes/` are repository-only demo examples, not included in the default stylesheet or the npm package; they exist to show valid ways to use this contract, such as `ocean`, `square`, `cyberpunk`, and `brutalist`.
 
-A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, and hover overlay. In browsers with `color-mix()` support, the core derives `--focus-ring` from the island's `--focus`; override the ring only for a deliberate visual treatment or when a matching pre-`color-mix()` fallback is required.
+A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, hover overlay, and shadow color. Pick `--focus` as a mid-tone that holds 3:1 against both `--surface` and `--surface-solid` in every scheme the theme declares; a pastel dark-scheme primary usually fails on the light solid surface. `bun run report:theme-contrast` measures both pairs.
+
+When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. A theme that declares no hook falls back to the `--soft-fg-mix` derivation: one global percentage applied to every role, so it carries no contrast guarantee for a palette it was not tuned against. `bun run report:theme-contrast` prints the resting and hovered soft pair for every intent of every island, which is how a theme finds the roles that need a hook or a lower `--soft-fg-mix`.
+
+The default palette's hooks apply to `:root` and to the `light`/`dark` boundaries only. Any other `data-theme` value resets them to the derivation, whether the attribute sits on `<html>` or on a nested island.
 
-When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. The generic soft fallback (`--soft-fg-mix` derivation, above) may already be sufficient.
+Contrast is measured between opaque colors. A translucent `--surface` has no ratio until it is composited over its backdrop, so `report:theme-contrast` refuses such a theme, and `.soft` mixes over it come out more opaque and more saturated than the surface. A translucent theme owns both: it measures against its real backdrop and replaces any recipe that does not hold there.
 
 Shape, shadow, motion, typography, and soft-variant mix tokens are optional knobs. Override them only when the theme actually changes that part of the system.
 
@@ -474,6 +500,7 @@ A full theme can override:
 
 - intent colors and foreground pairs
 - surface, text, border, focus, and overlay colors
+- `--surface-opaque` and `--surface-solid-fg`, when surfaces are translucent
 - radius tokens
 - optional shadow, motion, typography, and soft-variant mix tokens
 
@@ -507,6 +534,7 @@ A minimal recolor theme (illustrative, not a shipped theme):
   --border: hsl(260 24% 84%);
   --focus: var(--primary);
   --hover-overlay: hsl(260 30% 10% / 0.04);
+  --shadow-color: hsl(260 30% 10%);
   --soft-bg-mix: 84%;
   --soft-border-mix: 58%;
 
@@ -516,7 +544,7 @@ A minimal recolor theme (illustrative, not a shipped theme):
 }
 ```
 
-Several tokens are theme-derived aliases that reference other tokens — `--state-selected`/`--state-selected-fg`/`--state-disabled`, `--indicator-ring`, `--shadow`/`--shadow-popout`, `--heading`, `--selection-bg`/`--selection-fg`, and `--focus-ring-shadow`. They are declared on `:root, [data-theme]` so they recompute on every theme boundary: a custom property resolves its `var()` references at computed-value time on the element that declares it, so an alias declared only on `:root` would be inherited as an already-resolved value and would not follow a `[data-theme]` island's overridden tokens. A theme that wants a distinct alias (e.g. a `--selection-bg` of its own) overrides it explicitly afterwards, which wins by cascade order.
+Several tokens are theme-derived aliases that reference other tokens — `--state-selected`/`--state-selected-fg`/`--state-disabled`, `--indicator-ring`, `--shadow`/`--shadow-popout`, `--heading`, `--selection-bg`/`--selection-fg`, and `--surface-opaque`/`--surface-solid-fg`. They are declared on `:root, [data-theme]` so they recompute on every theme boundary: a custom property resolves its `var()` references at computed-value time on the element that declares it, so an alias declared only on `:root` would be inherited as an already-resolved value and would not follow a `[data-theme]` island's overridden tokens. A theme that wants a distinct alias (e.g. a `--selection-bg` of its own) overrides it explicitly afterwards, which wins by cascade order.
 
 Without `data-theme`, the default theme advertises `color-scheme: light dark` and follows the user's OS preference in browsers that support `light-dark()`. Dark themes should set `color-scheme: dark`. Light themes should set `color-scheme: light`. Browsers without `light-dark()` receive the light fallback.
 

package/docs/pages/guides/bootstrap.md

@@ -18,7 +18,8 @@ For an incremental migration, use one of these approaches:
 
 * migrate isolated pages or application areas;
 * control precedence with cascade layers or import order;
-* use a project-side prefix transform for Actual while both frameworks coexist.
+* use a project-side prefix transform for Actual while both frameworks coexist,
+  renaming the runtime's state classes in `actual-css/js/selectors` as well.
 
 The layered import is the cleanest way to keep both stylesheets during the
 migration:

package/docs/pages/guides/introduction.md

@@ -30,37 +30,29 @@ ARIA and native HTML, and per-widget configuration uses self-describing
 npm install actual-css
 ```
 
-Import the full framework in your CSS:
+Import what you use. The simplest start is the package's full entry, copied
+into your project and pruned — see
+[Start from the full entry](modular-import.md#start-from-the-full-entry):
 
 ```css
-@import "actual-css/full";
-```
-
-`actual-css/full` ships every functional family. The bare `actual-css` entrypoint
-is the minimal core (reset, tokens, theme, base, intents, variants, focus,
-print).
-
-Or compose only the pieces you use:
-
-```css
-@import "actual-css/css";
+@import "actual-css/css";                   /* core */
 @import "actual-css/css/layout";
+@import "actual-css/css/forms/all";
 @import "actual-css/css/components/button";
 @import "actual-css/css/components/card";
-@import "actual-css/css/forms";
-@import "actual-css/css/components/flyout";
 @import "actual-css/css/utilities";
 ```
 
-`actual-css/css` is the minimal core. Family manifests (`css/layout`,
-`css/forms`, `css/components`, `css/typography`, `css/effects`,
-`css/utilities`) and their modules map one-to-one to `src/css/`. See the
-[modular import guide](modular-import.md) for the full map.
+`actual-css/css` is the core (reset, tokens, theme, base, intents, variants,
+focus, print). Each family and module is its own import; the
+[modular import guide](modular-import.md) has the full map.
 
-You can also use the compiled full bundle directly:
+For zero-config use — prototypes, CDN, or when bundle size is not worth
+optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resolve
+to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.11/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map
@@ -76,9 +68,9 @@ Actual CSS uses a small unprefixed class grammar:
 
 Intents are `.primary`, `.secondary`, `.success`, `.warning`, and `.danger`, and
 work across components. Variants such as `.solid`, `.soft`, `.outline`, and `.surface` are
-shared by buttons, badges, alerts, and cards; `.inverted` is a shared surface
-modifier that paints any block with the inverse surface. `.ghost` and `.link`
-are button-only. Size variants `.sm` and `.lg` scale typography and
+shared by buttons, badges, alerts, and cards; a subtree that needs another
+palette is a `data-theme` island, not a class. `.ghost` and `.link` are
+button-only. Size variants `.sm` and `.lg` scale typography and
 participating component geometry consistently. Density contexts `.compact` and
 `.spacious` change geometry and spacing without changing font size or icons;
 `.compact` may slightly narrow typefaces that support a width axis.

package/docs/pages/guides/modular-import.md

@@ -1,19 +1,26 @@
 # Modular imports
 
-Actual CSS ships one minimal core (`actual-css`) and one all-in entrypoint (`actual-css/full`). Projects can also compose the framework from family manifests or individual modules.
+Actual CSS has two kinds of entrypoint. Without `/css`, you get a compiled artifact ready to serve. With `/css`, you compose the sources.
 
 ## Entrypoints
 
-```css
-@import "actual-css";        /* minimal core */
-@import "actual-css/full";   /* complete framework */
+```text
+Composable source CSS (recommended)
+  actual-css/css             core
+  actual-css/css/<family>    one family, e.g. css/layout, css/forms/all
+  actual-css/css/<family>/*  one module, e.g. css/components/button
+  actual-css/css/full        every family, as source
+
+Zero-config distribution
+  actual-css                 complete compiled framework
+  actual-css/full            the same bundle, named explicitly
 ```
 
-`actual-css` contains the shared baseline: reset, tokens, theme, document defaults, intents, universal variants, focus, and print.
+`actual-css/css` contains the shared baseline: reset, tokens, theme, document defaults, intents, universal variants, focus, and print.
 
 It contains no typography, layout, forms, components, effects, or utilities.
 
-`actual-css/full` starts from the core and adds every family in cascade order:
+The full framework starts from the core and adds every family in cascade order:
 
 ```text
 core → typography → layout → forms → components → effects → utilities
@@ -27,6 +34,46 @@ Components may enhance or replace that treatment in interactive states, but thei
 
 When an interactive state replaces the outline, it must preserve a visible focus indicator in forced-colors, either with an outline-based fallback or by keeping the replacement out of forced-colors.
 
+## Start from the full entry
+
+Deleting is easier than adding, and it keeps the cascade order right. Copy the
+package's full entry into your project, rewrite its relative imports to
+package paths, then delete what you do not need:
+
+- CSS: `src/css/actual.full.css`. Prefix each import with `actual-css/css/`
+  and drop `.css` and `/index`; `./actual.css` is `actual-css/css`. To go below
+  family level, replace a family line with the imports of its `index.css`,
+  rewritten the same way.
+- JS: `src/js/full.js`. Prefix each import with `actual-css/js/` and drop
+  `.js`; `./index.js` is `actual-css/js`.
+
+```css
+/* app/index.css — actual.full.css, rewritten, components expanded and pruned */
+@import "actual-css/css";
+@import "actual-css/css/typography";
+@import "actual-css/css/layout";
+@import "actual-css/css/forms/all";
+@import "actual-css/css/components/button";
+@import "actual-css/css/components/close";
+@import "actual-css/css/components/card";
+@import "actual-css/css/components/modal";
+@import "actual-css/css/utilities";
+```
+
+```js
+// app/index.js — full.js, rewritten and pruned
+import "actual-css/js/flyout";
+import "actual-css/js/dialog";
+import "actual-css/js/dismiss";
+import "actual-css/js/tooltip";
+import "actual-css/js";
+```
+
+JS modules import what they depend on. CSS modules do not, and three are
+shared: keep `components/close` with modal, drawer, alert, or a removable
+badge; `components/bleed` with a `.bleed` child of card, drawer, or accordion;
+`components/spinner` with `components/busy`.
+
 ## Family manifests
 
 Each family is one import. The contents are enumerations rather than table
@@ -47,7 +94,7 @@ cells, so they read as a list:
 - **Components** — `actual-css/css/components`
   buttons, surfaces, overlays, feedback, navigation, data and composed controls
 - **Effects** — `actual-css/css/effects`
-  aura
+  aura, shimmer
 - **Utilities** — `actual-css/css/utilities`
   base and extra utilities
 

package/docs/pages/guides/progressive-enhancement.md

@@ -49,7 +49,10 @@ never tracked.
 
 `enhance()` observes DOM insertions and removals, not attribute changes. If an
 already-connected element receives a behavior attribute later, call the returned
-`refresh(node)` handle. Behavior attributes are setup-time contracts: removing
+`refresh(node)` handle of your own `enhance()`, or `applyEnhancement()` for a
+`data-enhance` token. The built-in `data-*` behaviors (`data-mask`,
+`data-filter`, …) expose no handle: insert the element with the attribute
+already set. Behavior attributes are setup-time contracts: removing
 one does not disconnect an active behavior. If an application needs a live
 enable/disable switch, keep that state inside its enhancer and clean it up when
 the element leaves the DOM.
@@ -89,6 +92,7 @@ example:
 | `actual-css/js/filter`             | Input value filtering on `data-filter`                      |
 | `actual-css/js/mask`               | Input masks on `data-mask`                                  |
 | `actual-css/js/password`           | Password reveal toggle                                      |
+| `actual-css/js/range`              | Range fill and named values (token `range`)                 |
 | `actual-css/js/validation`         | Form validation (token `validation`)                        |
 | `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`      |
 | `actual-css/js/enhancement-loader` | Declared enhancement manifests                              |
@@ -105,11 +109,12 @@ needed.
 
 The JS is designed to run on its own, without Actual's stylesheet.
 
-- **`data-enhance` tokens** register root-controller behaviors. The runtime
-  discovers components through `data-enhance="tabs"`, `data-enhance="flyout"`,
-  `data-enhance="scrollspy"`, and `data-enhance="validation"` — no Actual
-  presentation class needed. Self-describing attributes (`data-mask`,
-  `data-tooltip`, `data-context-menu`) stay framework-neutral by construction.
+- **`data-enhance` tokens** register named behaviors. The runtime discovers
+  components through `data-enhance="tabs"`, `data-enhance="flyout"`,
+  `data-enhance="range"`, `data-enhance="scrollspy"`, and
+  `data-enhance="validation"` — no Actual presentation class needed.
+  Self-describing attributes (`data-mask`, `data-tooltip`,
+  `data-context-menu`) stay framework-neutral by construction.
 - **`selectors.js`** lists the state classes the runtime *writes* (`is-open`,
   `was-validated`, …). Edit this file (or alias it in a bundler) to
   match a different CSS framework's state vocabulary. It is a read-side-only
@@ -229,8 +234,8 @@ Three non-obvious requirements:
 
 Lifecycle: `prepareSurface` → `openSurface` → `closeSurface` →
 `disconnectSurface`. `retainSurface(panel)` reference-counts a surface shared by
-several triggers and returns a release function; `isSurfaceOpen` and
-`getSurfaceAutoClose` read current state. The separate `escape` primitive adds
+several triggers and returns a release function; `isSurfaceOpen` reads the
+current state. The separate `escape` primitive adds
 visible dismissable UI to the shared per-document Escape stack.
 
 Actual-managed surfaces are mutually exclusive within a document. Opening a
@@ -323,7 +328,6 @@ import { registerCommands } from "actual-css/js/command";
 
 registerCommands("--toggle-hidden", {
   handle(event, trigger, target) {
-    event.preventDefault();
     target.hidden = !target.hidden;
     trigger.setAttribute("aria-expanded", String(!target.hidden));
   },
@@ -332,10 +336,10 @@ registerCommands("--toggle-hidden", {
 
 The default resolver `targetFor(trigger)` looks up `commandfor` by ID in the
 trigger's document or shadow root. Supply `resolve(trigger)` to validate or
-replace that lookup. An optional idempotent `prepare(trigger, target, command)`
-callback runs directly before `handle`; built-in behaviors use it for
-target-derived semantics. `commandSelector(commands)` builds the matching button
-selector. The returned handle has an idempotent `disconnect()` method for
+replace that lookup. Once a target resolves, the router cancels the click before
+`handle` runs, so the native `command` event is never dispatched for a routed
+command. Names must be a native keyword or start with `--`; anything else
+throws. `commandSelector(commands)` builds the matching button selector. The returned handle has an idempotent `disconnect()` method for
 applications that unload the module owning the command.
 
 ### Dismiss command
@@ -411,10 +415,8 @@ registerEnhancement("autosubmit", (form) => {
 <form data-enhance="validation autosubmit">
 ```
 
-`enhancementSelector(name)` returns the matching `[data-enhance~="name"]`
-selector (names must match `[a-z][a-z0-9-]*`), and `hasEnhancement(el, name)`
-tests it. No core module list is modified — the regression test in
-`tests/enhance.test.js` proves the shape.
+Names must match `[a-z][a-z0-9-]*`. To find opted-in elements from your own
+script, query `[data-enhance~="name"]`; styles keep using presentation classes.
 
 A name is owned once per root: a second `registerEnhancement("autosubmit", …)`
 on the same root throws, and `disconnect()` releases the name so it can be

package/docs/pages/guides/tailwind.md

@@ -17,25 +17,39 @@ If you finish the migration with a new `.mt-4`, `.flex`, `.bg-primary`, and `md:
 
 Tailwind and Actual can temporarily coexist, but some short class names overlap.
 
-Examples include layout and flex-related names such as `.grid`, `.grow`, and `.items-center`.
+The most dangerous is `.outline`: it is an Actual button variant (`.btn.outline`), and Tailwind's `outline` utility draws a real outline on it. Layer order does not save this one — the migration setup above puts Tailwind utilities over Actual on purpose.
 
-For a staged migration, use cascade layers, controlled import order, or a project-side Actual prefix transform where necessary.
+Other overlapping names: `.table`, `.sticky`, `.truncate`, `.prose`, `.sr-only`, plus layout names such as `.grid`, `.grow`, and `.items-center`.
+
+For a staged migration, use cascade layers, controlled import order, or a project-side Actual prefix transform where necessary. The transform lives in the consumer's own pipeline (a build-time rename on the Actual import), not in the Actual CLI, which only bundles. The JavaScript runtime writes state classes (`is-open`, `danger`, …): rename them in `actual-css/js/selectors` too, or flyouts and dialogs never open.
 
 The layered import is the cleanest way to keep both stylesheets during the
 migration:
 
 ```css
+/* Tailwind v4 emits its own layers (theme, base, components, utilities),
+   so declare the order explicitly: Actual sits above Tailwind components
+   but below Tailwind utilities during the migration. */
+@layer theme, base, components, actual, utilities;
+
 @import "tailwind.css";        /* your compiled Tailwind output */
-@layer actual;
 @import "actual-css/full" layer(actual);
+
 /* Unlayered project overrides stay on top */
 @import "app.css";
 ```
 
-The full import places every Actual rule in a single `actual` layer, so
-unlayered Tailwind output and project CSS keep precedence while the migration
-runs. See [Cascade layer strategy](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/cascade-layer.md) for the
-limitations of the approach.
+The full import places every Actual rule in a single `actual` layer. The
+explicit `@layer` order is what keeps Tailwind utilities above Actual while
+the migration runs — not the unlayered status of either output. See
+[Cascade layer strategy](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/cascade-layer.md)
+for the limitations of the approach.
+
+Layers do not scope custom properties: both frameworks define
+`--font-sans`, `--font-mono`, `--font-weight-*`, and `--radius-sm` /
+`--radius-lg`. With `actual` after `theme`, `font-sans` takes Actual's font
+stack and `rounded-lg` resolves to Actual's `--radius-lg`. Expect these
+token collisions on migrated screens until Tailwind is removed.
 
 Do not assume that loading both complete stylesheets is automatically safe.