actual-css 0.11.1 → 0.13.0

package/docs/pages/forms/sticky-actions.md

@@ -1,6 +1,6 @@
 # Sticky Actions
 
-> Use `.form-actions sticky` when long forms need reachable submit actions while scrolling.
+> Use `.cluster.form-actions.sticky` when long forms need reachable submit actions while scrolling.
 
 ## Inside the form
 
@@ -8,8 +8,8 @@ The `<form>` is the bounding parent. The sticky stays pinned to the viewport bot
 
 Scroll the page to see the actions stay reachable.
 
-```html demo
-<form novalidate>
+```html demo sticky
+<form class="stack" novalidate>
   <div class="stack">
     <label class="field">
       <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
@@ -57,7 +57,7 @@ Scroll the page to see the actions stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack compact">
+      <div class="stack tight">
         <label class="choice">
           <input class="radio" type="radio" name="theme" value="light" checked />
           <span>Light</span>
@@ -79,7 +79,7 @@ Scroll the page to see the actions stay reachable.
     </label>
   </div>
 
-  <div class="form-actions sticky">
+  <div class="cluster form-actions sticky">
     <button type="button" class="btn outline">Cancel</button>
     <button type="submit" class="btn primary">Save changes</button>
   </div>
@@ -92,84 +92,86 @@ For a sticky page footer, dialog footer, or card footer, detach the actions and
 
 Scroll the page to see the detached footer stay reachable.
 
-```html demo
-<form id="account-form" novalidate>
-  <div class="stack">
-    <label class="field">
-      <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
-      <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Email <span class="required-mark" aria-hidden="true">*</span></span>
-      <input class="input" type="email" autocomplete="email" required />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Phone</span>
-      <input class="input" type="tel" autocomplete="tel" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Bio</span>
-      <textarea class="textarea" rows="4" placeholder="Tell us about yourself…"></textarea>
-    </label>
-
-    <label class="field">
-      <span class="field-label">Website</span>
-      <input class="input" type="url" autocomplete="url" placeholder="https://example.com" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Language</span>
-      <select class="select">
-        <option>English</option>
-        <option>Français</option>
-        <option>Deutsch</option>
-      </select>
-    </label>
-
-    <label class="field">
-      <span class="field-label">Experience level</span>
-      <input class="range" type="range" min="0" max="10" value="5" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Profile picture</span>
-      <input class="file" type="file" accept="image/*" />
-    </label>
-
-    <fieldset class="field-group">
-      <legend class="field-label">Theme</legend>
-      <div class="stack compact">
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="light" checked />
-          <span>Light</span>
-        </label>
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="dark" />
-          <span>Dark</span>
-        </label>
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="auto" />
-          <span>System</span>
-        </label>
-      </div>
-    </fieldset>
-
-    <label class="choice">
-      <input class="check" type="checkbox" />
-      <span>Email notifications</span>
-    </label>
-  </div>
-</form>
-
-<footer class="form-actions sticky">
-  <button type="button" class="btn outline">Cancel</button>
-  <button type="submit" class="btn primary" form="account-form">
-    Save changes
-  </button>
-</footer>
+```html demo sticky
+<div class="stack">
+  <form id="account-form" novalidate>
+    <div class="stack">
+      <label class="field">
+        <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
+        <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Email <span class="required-mark" aria-hidden="true">*</span></span>
+        <input class="input" type="email" autocomplete="email" required />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Phone</span>
+        <input class="input" type="tel" autocomplete="tel" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Bio</span>
+        <textarea class="textarea" rows="4" placeholder="Tell us about yourself…"></textarea>
+      </label>
+
+      <label class="field">
+        <span class="field-label">Website</span>
+        <input class="input" type="url" autocomplete="url" placeholder="https://example.com" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Language</span>
+        <select class="select">
+          <option>English</option>
+          <option>Français</option>
+          <option>Deutsch</option>
+        </select>
+      </label>
+
+      <label class="field">
+        <span class="field-label">Experience level</span>
+        <input class="range" type="range" min="0" max="10" value="5" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Profile picture</span>
+        <input class="file" type="file" accept="image/*" />
+      </label>
+
+      <fieldset class="field-group">
+        <legend class="field-label">Theme</legend>
+        <div class="stack tight">
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="light" checked />
+            <span>Light</span>
+          </label>
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="dark" />
+            <span>Dark</span>
+          </label>
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="auto" />
+            <span>System</span>
+          </label>
+        </div>
+      </fieldset>
+
+      <label class="choice">
+        <input class="check" type="checkbox" />
+        <span>Email notifications</span>
+      </label>
+    </div>
+  </form>
+
+  <footer class="cluster form-actions sticky">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary" form="account-form">
+      Save changes
+    </button>
+  </footer>
+</div>
 ```
 
 ## CSS hooks

package/docs/pages/forms/validation.md

@@ -62,7 +62,7 @@ there is no init call. To opt in forms you cannot mark up, call
 `actual-css/js/enhance`.
 
 ```html demo
-<form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
+<form class="stack needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
   <div class="stack">
     <label class="field">
       <span class="field-label">Password</span>
@@ -81,7 +81,7 @@ there is no init call. To opt in forms you cannot mark up, call
     </label>
   </div>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>
@@ -139,7 +139,7 @@ The status bar (`actual-css/js/status`) auto-wires to that event: import it and
         Switch this on to submit.
       </span>
     </div>
-    <div class="form-actions">
+    <div class="cluster form-actions">
       <button class="btn primary" type="submit">Submit</button>
       <button class="btn neutral outline" type="reset">Reset</button>
     </div>
@@ -197,7 +197,7 @@ Add your own with `FormValidator.registerRule(name, (value, el, ...opts) => bool
     <span class="field-error" id="attachment-error">Choose a .pdf or .csv file.</span>
   </label>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>
@@ -246,7 +246,7 @@ The `date` rule pairs naturally with `data-mask` — the mask structures input,
     </span>
   </label>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>

package/docs/pages/foundations/philosophy.md

@@ -1,6 +1,102 @@
 # Philosophy
 
-How components, intents, variants, and density compose — and what each layer is responsible for.
+Actual CSS is a composition-first component framework: let HTML and the
+cascade do the work, compose layout separately from components, and add an
+abstraction only for a real, repeated need. The outlook is close to
+[CUBE CSS](https://cube.fyi/), without adopting its methodology or naming.
+
+**Related terms:** principles, architecture, CUBE, BEM, naming, methodology, guidelines.
+
+## Layers
+
+| Layer     | In Actual                         | Owns                                |
+| --------- | --------------------------------- | ----------------------------------- |
+| Baseline  | reset, tokens, themes, base       | HTML defaults, cascade, inheritance |
+| Layout    | `.stack`, `.cluster`, `.grid`, …  | space between children              |
+| Utility   | `.list-reset`, `.measure`, …      | one reusable adjustment             |
+| Component | `.card`, `.btn`, form controls, … | intrinsic anatomy and appearance    |
+| State     | native attributes, ARIA, `data-*` | what the element is doing           |
+
+## Principles
+
+**Components own their inside; compositions own the space between them.** A
+card sets its padding, surface and slots. Where it sits, and how far it is from
+the next card, belongs to the layout around it:
+
+```html
+<section class="stack">
+  <article class="card">…</article>
+  <article class="card">…</article>
+</section>
+```
+
+A rule such as `.card + .card { margin-block-start: 2rem }` moves page layout
+into the component; put a composition around the cards instead.
+
+**A composition on a component takes over its default layout.** A component's
+own layout sits at zero specificity, so `<article class="card media">` lays out
+as a `.media` without an override, whatever the import order.
+
+**State uses the most semantic attribute; classes choose presentation.**
+
+| Kind             | Mechanism      | Examples                                     |
+| ---------------- | -------------- | -------------------------------------------- |
+| Native state     | HTML attribute | `disabled`, `open`, `checked`                |
+| Accessible state | ARIA           | `aria-current`, `aria-expanded`, `aria-busy` |
+| Runtime state    | `data-*`       | no native or ARIA equivalent                 |
+| Presentation     | class          | `.soft`, `.outline`, `.sm`, `.compact`       |
+
+Write `<a class="nav-link" aria-current="page">`, not `.nav-link.active`. The
+few `.is-*` classes (`.is-open`, `.is-static`) are runtime internals: neither
+set nor select them. `data-enhance` activates behavior and is never a styling
+hook.
+
+**A utility does one thing.** A class that sets a surface, a border, padding and
+type together is a component: give it a name in application CSS.
+
+**Configure before overriding.** Documented public hooks (`--grid-min`,
+`--card-pad`, `--cluster-justify`) are the API. Other custom properties are
+internal and may change.
+
+## Before adding CSS
+
+Go down the layers and stop at the first that answers the need:
+
+1. Does HTML already express it, or the browser already do it?
+2. Is it a relationship between children? Use a composition.
+3. Is it one small adjustment? Use a utility.
+4. Is it the anatomy of a component? Use the component and its hooks.
+5. Is it a state of that component? Use the attribute that names the state.
+
+What remains is product-specific: write it as application CSS, as described in
+[Building with Actual CSS](../guides/integrating-actual-css.md).
+
+## Class grammar
+
+A component takes optional intent, variant and size classes:
+`<button class="btn primary soft sm">`. The sections below describe each axis.
+
+### Flat names, not BEM
+
+A modifier is a separate class that combines with others (`.btn.primary.soft`,
+not `.btn--primary`), and a part gets a prefixed class (`.alert-icon`,
+`.list-item-title`) only when its element does not already say what it is.
+There is no `__` or `--` in Actual's names, because:
+
+- **Modifiers are shared axes.** `.primary`, `.soft` and `.sm` mean the same
+  thing on every component that supports them, so one class serves `.btn`,
+  `.badge` and `.alert`. BEM names a modifier per block, which multiplies the
+  vocabulary and keeps a custom intent such as `.tertiary` from working
+  everywhere at once.
+- **State is not a modifier.** `disabled`, `aria-current` and `open` already
+  name the state; a `--disabled` or `--active` class would duplicate them and
+  drift out of sync.
+- **Elements come from HTML.** A card's `header` and `footer`, an avatar's
+  `<img>` need no `__element` class; a prefixed class is kept for the parts
+  HTML cannot name.
+
+Application CSS can use any convention, BEM included, alongside Actual's
+classes: `<article class="card pricing-plan pricing-plan--featured">`.
 
 ## Components
 
@@ -80,8 +176,9 @@ how `.field sm`, `.input-icon sm`, `.join sm`, and `.flyout sm` size the
 controls inside them, while a bare `.sm` on a plain element does nothing.
 
 `.compact` and `.spacious` establish inherited density tokens. Density arranges
-how tightly UI sits — spacing and component geometry — while typography and
-icon size stay unchanged. Participation is opt-in, and a component only joins
+how tightly UI sits — spacing and component geometry — while font size and
+icon size stay unchanged. `.tight` and `.loose` change the rhythm (`--gap`)
+alone. Participation is opt-in, and a component only joins
 where density has an effect independent from its optical size: if the result is
 merely that the component looks smaller or larger, that is size, not density.
 
@@ -126,7 +223,8 @@ affect the same dimension:
 </div>
 ```
 
-The density tokens are `--gap`, `--density-space`, and `--control-size`.
+The density tokens are `--gap`, `--density-space`, `--control-size`, and
+`--control-pad-x`.
 Components consume the dimensions that make sense for them and opt out of the
 rest. The absolute `--space-*` scale is not rebound by density scopes.
 Components with bespoke geometry (`.badge`, `.avatar`,

package/docs/pages/foundations/theming.md

@@ -184,16 +184,27 @@ 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
+leaves the default identity in the greys. `actual-css 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.
+nothing about your intents. Measure it, then lower `--soft-fg-mix` or declare
+the per-role hooks for the intents that miss:
 
-→ Foundations · Tokens (theme contract)
+```sh
+bunx --bun actual-css contrast --theme src/theme.css
+```
+
+It reads the theme in headless Chrome, in every scheme it declares, and exits 1
+when a soft, focus, invalid-focus or inverse pair misses its threshold, so it
+can gate a CI job.
+
+Starting from a color scale (Tailwind `--color-zinc-*`, a brand ramp): map one
+step per role rather than importing the scale.
+
+→ Foundations · Tokens (theme contract) · Guides · Tailwind (Map the palette to theme roles)
 
 ### Use or adapt a preset palette
 

package/docs/pages/foundations/tokens.md

@@ -35,6 +35,28 @@ Global tokens are the ones to reach for in application CSS. Write a relay only t
 }
 ```
 
+### Which hooks inherit
+
+A hook either describes one element's own layout, or a policy its context
+hands down. Instance geometry stops at every new instance; policy inherits.
+
+| Kind              | Examples                                  | Inherits |
+| ----------------- | ----------------------------------------- | -------- |
+| Palette, theme    | `--text`, `--primary`                     | yes      |
+| Rhythm, density   | `--gap`, `--control-size`                 | yes      |
+| Page policy       | `--center-size`, `--measure`              | yes      |
+| Role policy       | `--form-actions-justify`, `--frame-ratio` | yes      |
+| Instance geometry | `--cluster-justify`, `--grid-columns`     | no       |
+
+Set instance geometry on the element itself (a class or inline style), and
+select nested instances to change them (`.toolbar > .cluster`). Set a policy
+once on the region or on `:root` that owns it. A new hook follows the same
+test: "how this element lays out" stops at the element, "what this context
+hands down" inherits. The stop needs the instance to read its own hook:
+`.switcher` and `.sidebar-layout` hooks are read by their children, and a
+nested instance that is itself such a child still needs its parent's value,
+so those keep inheriting.
+
 ### 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.
@@ -85,21 +107,34 @@ Surfaces are painted material and may be translucent. Two roles must stay opaque
 
 A theme with translucent surfaces overrides both with opaque values.
 
+`--border` separates surfaces: cards, tables, dividers, panels. `--border-control`
+is the resting edge that tells a control apart from the surface — fields,
+checkboxes and radios, switches, OTP cells, choice cards, join addons, the color
+and file inputs. It defaults to `--border`; set it alone to make controls
+stand out (input border, field outline, form control contrast) without
+darkening every separator. Hover, checked, invalid and disabled states keep
+their own colors.
+
 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. 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.
+Focus styling is outline-first. A global focus baseline draws a `--focus-ring-width` line in `--focus-outline-color`, offset by `--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: hsl(268 30% 55%);
 
   --focus-outline-color: currentColor;
-  --focus-outline: var(--focus-ring-width) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
   --focus-ring-width: 2px;
 }
 ```
 
+The line is composed on the focused element, so a theme island or a region
+that sets `--focus-ring-width` widens links and buttons alike. Set
+`--focus-outline` to replace the whole generic line (`4px dashed currentColor`);
+it has no default value. Application CSS that draws the generic line itself
+writes `var(--focus-ring-width) solid var(--focus-outline-color)`.
+
 ### Palette coherence
 
 A coherent palette treats surfaces, text, borders, intents, and shadows as related roles rather than isolated colors.
@@ -167,8 +202,8 @@ to keep that pair ≥ 4.5:1 in both color schemes, enforced by
 presets and custom `[data-theme]` islands keep the `--soft-fg-mix` derivation
 unless they declare the hooks themselves (the framework resets them outside
 the default boundary). A theme that overrides the soft palette is responsible
-for preserving sufficient text contrast; `bun run report:theme-contrast`
-reports every preset's resting and hovered pairs without failing the build.
+for preserving sufficient text contrast; `bunx --bun actual-css contrast --theme FILE`
+measures its resting and hovered pairs.
 
 A theme whose primary should read more muted than its statuses sets only
 `--primary-soft-fg`, and every soft `.primary` foreground follows it. Without a
@@ -236,7 +271,6 @@ Typography tokens cover the document baseline and common component needs.
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   --font-width: 100%;
-  --font-width-dense: 95%;
 
   --line-height: 1.5;
   --font-weight-normal: 400;
@@ -265,18 +299,45 @@ Local `.sm`/`.lg` sizes map `--control-size`, `--control-font-size`, and
   --control-size-md: 2.375rem;  /* 38px → default */
   --control-size-lg: 2.75rem;   /* 44px → .lg */
   --control-size: var(--control-size-md);
-  --control-pad-x: var(--font-size-md);
+  --control-pad-x-sm: var(--font-size-xs); /* .sm, .compact */
+  --control-pad-x-md: var(--font-size-md); /* default */
+  --control-pad-x-lg: var(--font-size-lg); /* .lg, .spacious */
+  --control-pad-x: var(--control-pad-x-md);
   --control-font-size: var(--font-size-md);
   --disabled-opacity: 0.65;
 }
 ```
 
-`--control-pad-x` is a resolved geometry length, stated in the typographic
-tokens rather than an `em`. Every part of one control must see the same
-horizontal distance; an `em` would change value on a descendant with its own
-font size, which is exactly what `--input-icon-size` does to the icon glyph. It
-mirrors `--control-font-size` and is rebound beside it at the `.sm`/`.lg`
-boundaries.
+A theme sets the steps (`--control-size-*`, `--control-pad-x-*`); `.sm`/`.lg`
+and `.compact`/`.spacious` select one. `--control-size` and `--control-pad-x`
+are the selected values: override them on one instance, never in a theme,
+where every size and density boundary would overwrite them.
+
+A `data-theme` island inherits the selected values, so an override set above it
+crosses it. A theme that changes the steps and is used as a nested island must
+re-select them in its own block, from the step weights that size and density
+classes set, so the island keeps the density around it:
+
+```css
+[data-theme="brand"] {
+  --control-pad-x-sm: 0.5rem;
+  --control-pad-x-md: 0.75rem;
+  --control-pad-x-lg: 1rem;
+  --control-pad-x: calc(
+    (var(--control-pad-x-sm) * var(--control-step-sm)) +
+    (var(--control-pad-x-md) * var(--control-step-md)) +
+    (var(--control-pad-x-lg) * var(--control-step-lg))
+  );
+}
+```
+
+Re-select only the token whose steps the theme changes: the same rule for
+`--control-size` would stop an inherited `--control-size` at the island.
+
+`--control-pad-x` is a length, not an `em`: every part of one control must see
+the same horizontal distance, and an `em` would change value on a descendant
+with its own font size, which is exactly what `--input-icon-size` does to the
+icon glyph.
 
 - `.lg` — 44px control height
 - default — 38px control height
@@ -290,42 +351,33 @@ Disabled controls and disabled-prone components read `--disabled-opacity` for th
 
 ### Density
 
-Density contexts swap shared spacing and geometry, plus a slight typographic
-width bonus:
+Density contexts swap shared rhythm and geometry, and never typography:
 
 ```css
-:root {
-  --font-width: 100%;
-  --font-width-dense: 95%;
-}
-
 .compact {
   --gap: var(--space-20);
   --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
-  font-stretch: var(--font-width-dense);
+  --control-pad-x: var(--control-pad-x-sm);
 }
 
 .spacious {
   --gap: var(--space-50);
   --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
-  font-stretch: var(--font-width);
+  --control-pad-x: var(--control-pad-x-lg);
 }
 ```
 
-Density never changes font size or icon size — it may only use the denser font
-width. `font-stretch` uses a variable `wdth` axis when available, or
-participates in normal width-face matching for families that expose multiple
-widths. Layout must never depend on the narrowing being available. Compact
-density may slightly narrow variable typefaces when they support a width axis.
-This is a density enhancement, not an overflow strategy: never condense a
-component just because its label overflows at some viewport — that hides a
-composition problem. A theme whose typeface has no useful width axis opts out
-with `--font-width-dense: 100%`.
+- **Size** (`.sm`, `.lg`) — typography + geometry, on one component.
+- **Density** (`.compact`, `.spacious`) — rhythm + geometry, on a region.
+- **Rhythm** (`.tight`, `.loose`) — `--gap` only, on a region.
+
+Font size, icon size and font width stay put under density. A condensed table
+or panel is a typographic choice: set `font-stretch` on it in the application.
 
 Participation is opt-in and selective: controls consume `--control-size`
-for geometry; spacing helpers and rhythms consume `--density-space` and `--gap`;
+and `--control-pad-x` for geometry; spacing helpers and rhythms consume `--density-space` and `--gap`;
 components whose size is intrinsic (badge, avatar, spinner, rating, key, prose,
 inline choice/switch) keep their own scales. A local component size overrides
 inherited density for the dimensions they share.
@@ -359,7 +411,7 @@ Motion durations keep transitions consistent and easy to disable.
 }
 ```
 
-Ordinary interaction/state transitions have **no easing token**: they use the CSS default `ease` directly, and the dialog shake feedback plus the `actual-dialog` View Transition keep that default deliberately. The presence pair exists only for one-shot open/close where open and closed states own separate transition declarations (`.status-bar`/`.is-open`, `dialog.modal[open]`, `dialog.drawer[open]`): `--ease-enter` decelerates the appearance, `--ease-exit` accelerates the departure. The pair follows Material's standard rhythm; the emphasized-decelerate entrance is deliberately not offered because it only pays off at 250–400ms durations, beyond this vocabulary. Backdrops keep `ease` — a scrim only fades, it does not travel — but track their surface's duration. Toggles that share one transition list at `--duration-fast` (flyout, tooltip) also stay on `ease`: at 100ms the curve barely resolves and entry/exit cannot split on a single rule. These absences are deliberate, not gaps; a theme with a different motion character overrides `--ease-enter` / `--ease-exit`.
+Ordinary interaction/state transitions have **no easing token**: they use the CSS default `ease` directly, and the dialog shake feedback plus the `actual-dialog` View Transition keep that default deliberately. The presence pair exists only for one-shot open/close where open and closed states own separate easing values (`.status-bar`/`.is-open`, `dialog.modal[open]`, `dialog.drawer[open]`): `--ease-enter` decelerates the appearance, `--ease-exit` accelerates the departure. The pair follows Material's standard rhythm; the emphasized-decelerate entrance is deliberately not offered because it only pays off at 250–400ms durations, beyond this vocabulary. Backdrops keep `ease` — a scrim only fades, it does not travel — but track their surface's duration. Toggles that share one transition list at `--duration-fast` (flyout, tooltip) also stay on `ease`: at 100ms the curve barely resolves and entry/exit cannot split on a single rule. These absences are deliberate, not gaps; a theme with a different motion character overrides `--ease-enter` / `--ease-exit`.
 
 `reset.css` clamps raw animation and transition durations to `0.01ms`, resets their delays, and restores `html` scroll behavior under `prefers-reduced-motion: reduce`. Decorative loops effectively complete immediately without blanket-disabling animation support.
 
@@ -486,13 +538,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, 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.
+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. `bunx --bun actual-css contrast --theme FILE` measures both pairs, and exits 1 when a pair misses. The file may declare a `[data-theme]` island or set the tokens on `:root`; the tool reads each scheme through `color-scheme`, so write dark values with `light-dark()` — a `prefers-color-scheme` media block is not measured.
 
-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`. 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. `actual-css contrast` prints the resting and hovered soft pair for every intent in every scheme the theme declares, 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.
 
-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.
+Contrast is measured between opaque colors. A translucent `--surface` has no ratio until it is composited over its backdrop, so `actual-css contrast` reports its pairs as n/a, 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.
 
@@ -501,6 +553,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
+- `--border-control`, when controls need a stronger edge than separators
 - radius tokens
 - optional shadow, motion, typography, and soft-variant mix tokens
 
@@ -532,7 +585,7 @@ A minimal recolor theme (illustrative, not a shipped theme):
   --text-muted: hsl(260 10% 42%);
   --text-subtle: hsl(260 8% 56%);
   --border: hsl(260 24% 84%);
-  --focus: var(--primary);
+  --focus: hsl(260 60% 62%);
   --hover-overlay: hsl(260 30% 10% / 0.04);
   --shadow-color: hsl(260 30% 10%);
   --soft-bg-mix: 84%;