actual-css 0.9.2 → 0.10.0

package/docs/pages/components/dialog.md

@@ -6,16 +6,17 @@
 
 ## Class reference
 
-| Class                  | Kind      | Description                                    |
-| ---------------------- | --------- | ---------------------------------------------- |
-| `.modal`               | Component | Centered surface on the native `<dialog>`.     |
-| `.scrollable`          | Variant   | Header and footer stay while the body scrolls. |
-| `.dialog-confirmation` | Variant   | Message above a full-width action band.        |
-| `.dialog-icon`         | Component | Circular intent-aware icon well.               |
-| `.dialog-close`        | Component | Icon-only close button, at the top end.        |
-
-`.dialog-close` sits outside the content flow, so it does not take part in the
-dialog's own layout.
+| Class                  | Kind        | Description                                    |
+| ---------------------- | ----------- | ---------------------------------------------- |
+| `.modal`               | Component   | Centered surface on the native `<dialog>`.     |
+| `.scrollable`          | Variant     | Header and footer stay while the body scrolls. |
+| `.dialog-confirmation` | Variant     | Message above a full-width action band.        |
+| `.dialog-icon`         | Component   | Circular intent-aware icon well.               |
+| `.close`               | Composition | Icon-only close button, at the top end.        |
+
+A [`.close`](close.md) placed as a direct child of the dialog or of its form
+sits outside the content flow, so it does not take part in the dialog's own
+layout.
 
 ## Usage
 
@@ -138,7 +139,7 @@ has no action button; the header close button dismisses the dialog.
         id="details-dialog"
         closedby="any"
         data-dialog-dismissible>
-  <button class="dialog-close"
+  <button class="close"
           type="button"
           commandfor="details-dialog"
           command="request-close"
@@ -243,7 +244,7 @@ promoted above it and still unclickable.
         id="overlay-dialog"
         closedby="any"
         data-dialog-dismissible>
-  <button class="dialog-close"
+  <button class="close"
           type="button"
           commandfor="overlay-dialog"
           command="request-close"
@@ -381,7 +382,6 @@ Keep the button a direct child of `dialog.modal` so the scrolling content
 - `--dialog-viewport-gap` — distance kept between the dialog and the viewport edges.
 - `--dialog-icon-size` — diameter of the `.dialog-icon` circle.
 - `--dialog-icon-glyph-size` — size of the glyph centered inside `.dialog-icon`.
-- `--control-size` — inline and block size of the `.dialog-close` button. The
-  header reserves `calc(var(--control-size) + var(--space-30))` on its inline
-  end so the title never runs under the close.
-- `--dialog-close-icon-size` — size of the close glyph.
+- `--close-size` / `--close-icon-size` — size of the corner `.close` and of its
+  X. The header reserves the close size plus `--space-30` on its inline end so
+  the title never runs under it.

package/docs/pages/components/drawer.md

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

package/docs/pages/components/navbar.md

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

package/docs/pages/components/spinner.md

@@ -74,7 +74,7 @@ separate `.busy` class. The spinner is shown as a centered overlay over a faded
 surface; buttons keep their spinners inline instead (see Button).
 
 - Set `aria-busy="true"` on the container and add `<span class="spinner" aria-hidden="true"></span>` as its last direct child.
-- The overlay uses `--busy-overlay-bg`; an inverted surface (`.inverted`) already composes with it.
+- The overlay uses `--busy-overlay-bg`; a card derives it from its own surface.
 - Decorative spinners stay `aria-hidden="true"`; announce progress on the region with `role="status"` and a label when needed.
 
 ```html demo
@@ -89,5 +89,5 @@ surface; buttons keep their spinners inline instead (see Button).
 
 - `--spinner-track` — the ring color.
 - `--spinner-value` — the moving gap; swap the two for an inverted spinner.
-- `--busy-overlay-bg` — background of the busy overlay. An inverted surface
-  (`.inverted`) overrides it to blend with its own surface.
+- `--busy-overlay-bg` — background of the busy overlay. Set it on a surface you
+  paint yourself so the overlay blends with that surface.

package/docs/pages/enhancements/overview.md

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

package/docs/pages/enhancements/tooltip.md

@@ -8,6 +8,8 @@ and arrow position are written by JavaScript; the element is shown and hidden
 by promoting it to the top layer with `popover="manual"`.
 
 - Use `data-tooltip` on the trigger. With text (`data-tooltip="Help"`), the tooltip element is generated. Empty (`data-tooltip`) marks an explicit tooltip connected via `aria-describedby`.
+- Generated text is a snapshot at show time: changing `data-tooltip` never rewrites a tooltip that is already shown, and an always-visible generated tooltip keeps its initial text. For content that must update dynamically, use an explicit tooltip. See the [tooltips bench](../examples/overview.md) (`demo/templates/tooltips.html`) for all six cases side by side.
+- Generated text is always plain text (`textContent` only), so a shorthand value is safe for untrusted strings once they are in the DOM. An explicit tooltip is author-owned DOM: its sanitization belongs to whoever produces it. Escape the attribute server-side — a DOM already compromised at render cannot be repaired at read time. There is no `data-tooltip-html`, by design.
 - Tooltips are supplemental. Do not put required information or interactive controls inside them.
 - Show on hover and focus. Hide on Escape, blur, or pointer leave.
 - A trigger scrolled out of view takes its tooltip down and brings it back when it returns; only a dismissal ends the tooltip.
@@ -35,7 +37,7 @@ runtime when Actual should own showing and hiding.
 
 **Where the element lives is part of the contract.** An explicit tooltip stays
 exactly where you wrote it, so it keeps every scope that reaches it by
-inheritance — a theme island, a density scope, `.inverted`, your own scoped
+inheritance — a theme island, a density scope, your own scoped
 custom properties. It also means placement is yours to get right: a tooltip
 used from inside a modal dialog must be authored inside that dialog, because
 the top layer does not lift an element out of a modal's inertness.

package/docs/pages/examples/overview.md

@@ -47,12 +47,13 @@ One mechanism at a time, with its contract and its pitfalls.
 Contracts you cannot read off a static screenshot: state, motion, focus, and
 extension points.
 
-- [Surface contracts](../../demo/templates/surfaces.html) - `.inverted`, cascade precedence, and the intent boundary
+- [Contrast contexts](../../demo/templates/contrast-contexts.html) - the page, `data-theme` islands, a card island, a named theme and an application-painted band side by side, with every intent variant, a full form (combobox and date picker included) and focus line measured live, plus joined fields that need no focus adaptation
 - [Presence motion](../../demo/templates/motion.html) - status bar, tooltip, flyout, modal and drawer replayed side by side, with easing swaps and a reduced-motion simulation
 - [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
 - [Adaptive filter surface](../../demo/templates/adaptive-surface.html) - app-level flyout/drawer composition with one synchronized filter state
 - [Select intents](../../demo/templates/select-intents.html) - extending the enhancer with a project's own `data-enhance` behavior, injected markup included, with no framework change
 - [Popover transport probe](../../demo/templates/popover-transport.html) - self-scoring bench for the native popover transport go/no-go
+- [Tooltips](../../demo/templates/tooltips.html) - generated text is a snapshot at show time: what updates, what stays, and the explicit-tip way for dynamic content
 
 ### Third-party components on Actual tokens
 

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

@@ -7,6 +7,7 @@
 | Class                     | Kind      | Description                                   |
 | ------------------------- | --------- | --------------------------------------------- |
 | `.choice-card`            | Component | Card-style `<label>` around a native control. |
+| `.chip`                   | Modifier  | Compact pill form: filter chips, tags.        |
 | `.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.
@@ -93,11 +94,49 @@ 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.
 
+## Chips
+
+Add `.chip` for the compact pill form: filter chips, selectable tags, toggle
+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.
+
+```html demo
+<fieldset class="field-group">
+  <legend class="field-label">Fruit</legend>
+  <div class="cluster">
+    <label class="choice-card chip">
+      <input type="checkbox" name="fruit" value="pear" checked />
+      Pear
+    </label>
+    <label class="choice-card chip">
+      <input type="checkbox" name="fruit" value="apple" />
+      Apple
+    </label>
+    <label class="choice-card chip">
+      <input type="checkbox" name="fruit" value="plum" disabled />
+      Plum
+    </label>
+  </div>
+</fieldset>
+```
+
+The dot is `::before`: a full-chip layer clipped to a `circle()` centred on
+the check slot (`--choice-chip-dot`). A theme can grow it into a selected fill
+by widening the clip, as the `material` theme does.
+
 ## CSS hooks
 
 - `--choice-card-pad` — inner padding.
 - `--choice-card-radius` — corner radius.
 - `--choice-card-check-size` — size of the check indicator.
+- `--choice-card-border` / `--choice-card-bg` — resting border and background;
+  the checked state and hover rebind them, so a checked override needs
+  `:has(:checked)`.
+- `--choice-chip-dot` — read-only: the chip's check-slot centre as a `circle()`
+  position. It is declared on the chip's `::before`, so read it in a
+  `.choice-card.chip…::before` rule.
 
 Plain `.check` / `.radio` controls expose two hooks:
 

package/docs/pages/forms/combobox.md

@@ -47,7 +47,7 @@ contrast contracts apply to the combobox for free:
 .actual-combobox {
   --cb-bg: var(--surface);
   --cb-color: var(--text);
-  --cb-border-color: var(--border);
+  --cb-border-color: var(--form-invalid-border, var(--border));
   --cb-border-radius: var(--radius);
   --cb-focus-color: var(--focus);
   --cb-muted-color: var(--text-muted);
@@ -57,15 +57,23 @@ contrast contracts apply to the combobox for free:
   --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 :is(.cb-text-control:focus-visible, .cb-control:has(.cb-input:focus-visible)) {
+  border-color: var(--form-invalid-border, var(--cb-border-color));
+  outline: var(--focus-ring-width) solid var(--form-invalid-border, var(--focus));
+  outline-offset: calc(var(--focus-ring-width) * -1);
+  box-shadow: none;
 }
 
-.actual-combobox .cb-chip-remove:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: 0 0 0 2px var(--focus-ring);
+.actual-combobox :is(.cb-text-control[aria-invalid="true"], .cb-control:has([aria-invalid="true"])) {
+  --form-invalid-border: var(--danger);
+}
+
+:where(.actual-combobox) combo-box {
+  border-radius: var(--cb-border-radius);
+}
+
+.actual-combobox :is(.cb-control, .cb-text-control) {
+  border-radius: inherit;
 }
 
 .actual-combobox .cb-chip {
@@ -79,9 +87,13 @@ contrast contracts apply to the combobox for free:
 }
 ```
 
-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.
+While the search input is focused, the control takes the same inset outline as
+`.input` in place of the library's accent border and outer halo; a focused chip
+or remove × keeps the library's own inner ring. Being inset, the outline needs
+no adaptation inside `.join`: `combo-box` owns the radius at zero specificity,
+so the join gives it the group corners and the visible control inherits them. The invalid rule sets `--form-invalid-border`,
+the hook `.field.danger` and `aria-invalid` already use, so border and outline
+turn danger together.
 
 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/joined-controls.md

@@ -29,11 +29,8 @@ When composing source files manually, import `components/join.css` after the con
 </div>
 ```
 
-`.join` handles border-radius and border collapsing between adjacent children. It works with any direct child — `.input`, `.btn`, `.select`, or `.join-addon`.
-When an `.input`, `.textarea`, or `.select` receives keyboard-relevant focus,
-the focus ring surrounds the complete joined field. Attached buttons keep their
-own focus indicator when reached directly, so the actionable segment remains
-identifiable.
+`.join` handles border-radius and border collapsing between adjacent children. It works with any direct child — `.input`, `.btn`, `.select`, or `.join-addon` — plus one wrapper level (e.g. a combobox element around the native control): the wrapper receives the group corners and the inner control inherits them via `border-radius: inherit`.
+When an `.input`, `.textarea`, or `.select` receives keyboard focus, it keeps its own inset focus outline; the group never moves the ring onto itself, so the focused segment remains identifiable.
 
 ## Linting `role="group"`
 

package/docs/pages/forms/overview.md

@@ -165,6 +165,12 @@ A full form using the control classes, field wrappers, and form actions:
 </form>
 ```
 
+## Hooks
+
+Set `--control-hover-border` to tune the hover border of `.input` and `.textarea`.
+Set `--control-hover-bg` to keep a `.select` background steady on hover, or give
+it a stronger fill.
+
 ## Notes
 
 - `required` is enough on native inputs. `aria-required="true"` is redundant and not used in these examples.

package/docs/pages/foundations/theming.md

@@ -96,27 +96,73 @@ 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);
+  background: var(--surface-solid);
+  color: var(--surface);
+}
+```
+
+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
+
+### 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.

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.
@@ -62,17 +80,16 @@ The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surf
 
 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`. 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. 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-offset: 2px;
-  --focus-ring-width: 3px;
-  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
+  --focus-ring-width: 2px;
 }
 ```
 
@@ -445,9 +462,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 +479,11 @@ 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`.
 
-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.
+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.
 
 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.
 
@@ -507,6 +524,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 +534,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`, and `--selection-bg`/`--selection-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/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.10/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.