actual-css 0.9.1 → 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/components/table.md

@@ -16,7 +16,7 @@
 | ---------------- | --------- | ------------------------------------------------------------ |
 | `.table-wrap`    | Component | Scroll container and outer chrome (surface, border, radius). |
 | `.table`         | Component | The table itself; row and cell rules.                        |
-| `.table.compact` | Density   | Tighter cell padding; typography is unchanged.               |
+| `.table.compact` | Density   | Tighter cell padding; font size and icons unchanged.         |
 
 ## Basic usage
 
@@ -101,7 +101,8 @@ table width before the wrapper scrolls horizontally.
 ## Compact tables
 
 `.compact` lowers cell padding and establishes compact density for controls or
-spacing helpers inside cells. Typography and icons stay unchanged. It is the
+spacing helpers inside cells. Font size and icons stay unchanged; the framework's
+denser font width may apply when the typeface supports it. It is the
 same vocabulary as `.card.compact`.
 
 ```html demo

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

@@ -30,6 +30,7 @@ Whole pages, composed the way a real product would.
 - [Settings modal](../../demo/templates/settings-modal.html) - two-pane preferences dialog, with the local CSS it needs audited rule by rule
 - [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
 
 ### Layout references
 
@@ -46,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/input-policy.md

@@ -2,6 +2,8 @@
 
 > Native input intent first. Actual's runtime filters values only when explicitly asked, and fixed-shape masks stay opt-in through `data-mask`.
 
+**Related terms:** telephone, phone, tel-prefix.
+
 `inputmode` changes the virtual keyboard but does not constrain the value. Actual
 does not filter plain `inputmode` fields by default because numeric entry often
 needs temporary, signed, grouped, or locale-specific values while the user types.
@@ -89,3 +91,60 @@ Use `data-mask` when the input has a fixed shape. Tokens are `9` for a digit,
 
 Masks enforce shape, not domain validity. Use application validation when a date
 must reject impossible values such as `2026-13-40`.
+
+### Telephone input
+
+Do not mask telephone numbers by default. Phone formatting varies by country,
+device, copied source, and user convention. Preserve the entered value, apply
+only coarse client-side policy, and normalize or validate the actual number on
+the server.
+
+`tel-prefix` is that coarse policy: a local number passes, and an explicit
+international number must match one of the allowed prefixes. It analyzes a copy
+of the value and never rewrites it.
+
+```html demo
+<form class="needs-validation stack" data-enhance="validation" novalidate>
+  <label class="field">
+    <span class="field-label">Phone</span>
+    <input
+      class="input"
+      type="tel"
+      name="phone"
+      inputmode="tel"
+      autocomplete="tel"
+      data-validation-rules="tel-prefix +32"
+      aria-describedby="phone-help phone-error"
+    />
+    <span class="field-help" id="phone-help">
+      Local number or +32 international number.
+    </span>
+    <span class="field-error" id="phone-error">
+      Use a local number or an allowed international prefix.
+    </span>
+  </label>
+
+  <div class="form-actions">
+    <button class="btn primary" type="submit">Submit</button>
+    <button class="btn neutral outline" type="reset">Reset</button>
+  </div>
+</form>
+```
+
+| Input                | `tel-prefix +32` |
+| -------------------- | ---------------- |
+| `0470 12 34 56`      | passes           |
+| `02/123.45.67`       | passes           |
+| `+32 470 12 34 56`   | passes           |
+| `0032 470 12 34 56`  | passes           |
+| `(+32) 470 12 34 56` | passes           |
+| `0033 6 12 34 56 78` | fails            |
+| `+33 6 12 34 56 78`  | fails            |
+
+A local number passes in any usual notation, but its digits are required: once
+the separators are ignored, letters and stray symbols fail, so a pasted word is
+never read as a local number. An explicit international number is normalized
+for comparison — `0032…`, `(+32)…`, and `+32 (0)…` all read as `+32` — and a
+foreign prefix fails. With no prefix, only local input passes. This is an origin
+policy, not phone validation: region detection, number semantics, and E.164
+normalization stay on the server. See [validation](validation.md).

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/forms/validation.md

@@ -2,7 +2,7 @@
 
 > Inline error feedback that respects assistive technology and form state.
 
-**Related terms:** inline validation, field error.
+**Related terms:** inline validation, field error, telephone input.
 
 ## Class reference
 
@@ -162,10 +162,46 @@ Custom rules live in `data-validation-rules` as a comma-separated list; each rul
 - `number` — Value is empty or a valid `Number`.
 - `digits` — Value is empty or ASCII digits only.
 - `alnum` — Value is empty or letters and digits only.
+- `starts-with <token>…` — Value must begin with one of the literal tokens (`starts-with INV- CR-`). The value is trimmed before comparison; the match is case-sensitive.
+- `ends-with <token>…` — Value must end with one of the literal tokens (`ends-with .pdf .csv`). Trimmed, case-sensitive.
 - `date` — Value is a valid date in `yyyy-mm-dd`, `dd/mm/yyyy`, `mm/dd/yyyy`, `dd.mm.yyyy`, `mm.dd.yyyy`, `dd-mm-yyyy`, or `mm-dd-yyyy` shape; rejects non-existent dates like `2026-02-29`. ISO remains the recommended wire format because servers can parse it without guessing.
+- `tel-prefix <prefix>…` — A local number (its digits, with the usual separators `space ( ) . / -` ignored) passes; an explicit international number is normalized (`00` to `+`) and must match one of the literal prefixes (`tel-prefix +32`, `tel-prefix +32 +33 +352`). A value that is not dialing digits fails. With no prefix, only local input passes. The entered value is never modified.
+
+`starts-with` and `ends-with` options are literal tokens: no quoting, no escaping, and a token cannot contain whitespace. Without a token they fail rather than passing silently. `tel-prefix` without a prefix is instead a deliberate local-only policy.
 
 Add your own with `FormValidator.registerRule(name, (value, el, ...opts) => boolean)`. The built-in rules treat empty values as valid so optional fields stay optional; custom rules should do the same when that behavior is wanted.
 
+```html demo
+<form class="needs-validation stack" data-enhance="validation" novalidate>
+  <label class="field">
+    <span class="field-label">Invoice reference</span>
+    <input class="input" name="reference"
+           data-validation-rules="starts-with INV- CR-"
+           aria-describedby="reference-help reference-error"
+           required />
+    <span class="field-help" id="reference-help">Start with INV- or CR-.</span>
+    <span class="field-error" id="reference-error">Use an INV- or CR- reference.</span>
+  </label>
+
+  <label class="field">
+    <span class="field-label">Attachment filename</span>
+    <input class="input" name="attachment"
+           data-validation-rules="ends-with .pdf .csv"
+           aria-describedby="attachment-help attachment-error"
+           required />
+    <span class="field-help" id="attachment-help">A .pdf or .csv filename.</span>
+    <span class="field-error" id="attachment-error">Choose a .pdf or .csv file.</span>
+  </label>
+
+  <div class="form-actions">
+    <button class="btn primary" type="submit">Submit</button>
+    <button class="btn neutral outline" type="reset">Reset</button>
+  </div>
+</form>
+```
+
+More specific telephone policies — determining the actual region, validating number semantics, or producing E.164 — belong in application or server code, registered through `FormValidator.registerRule()`.
+
 The `date` rule pairs naturally with `data-mask` — the mask structures input, the rule validates meaning. Same rule, different formats:
 
 ```html demo

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.