actual-css 0.7.0 → 0.9.0

package/docs/pages/foundations/typography.md

@@ -38,7 +38,7 @@ It applies everywhere — cards, dialogs, heroes, app shells — not only in pro
 
 It does not own visual hierarchy. No global `font-size` on headings, no global `font-weight` on headings, no global margins on headings, no global `text-decoration` on links. These choices would shape app UI in ways the framework cannot predict.
 
-The mildly opinionated defaults at the baseline are few: line-height on headings (tight, so multi-line headings stay readable), `text-wrap: balance` on headings where supported, the `hr` rule, the `::selection` rule, the `code` / `kbd` / `samp` / `pre` font family, `small` font size, and a global link underline offset that prose and components reuse. Everything else stays neutral so components and `.prose` can take over without fighting the baseline.
+The mildly opinionated defaults at the baseline are few: line-height on headings (tight, so multi-line headings stay readable), `text-wrap: balance` on headings where supported, the `hr` rule, the `::selection` rule, the `code` / `kbd` / `samp` / `pre` font family, `pre` overflow containment, `small` font size, and a global link underline offset that prose and components reuse. Everything else stays neutral so components and `.prose` can take over without fighting the baseline.
 
 Global links inherit color. The visual affordance of a link is the responsibility of `.prose` (for authored content) or of a component (for nav links, button-like links, tabs, breadcrumbs, etc.). Underlining every `a` globally would collide with all of those.
 
@@ -54,10 +54,11 @@ The reason for that boundary: a dialog title, a card heading, or a sidebar secti
 
 ### Fluid module
 
-`src/css/typography/fluid.css` is a small module that is not imported by
-`actual.css`. Projects that need display, title, and lead sizes that scale
-with the viewport (landing pages, marketing pages, hero sections,
-documentation homepages) import it manually:
+`src/css/typography/fluid.css` ships with the typography family
+(`actual-css/css/typography`) and `actual-css/full`, but not with the minimal
+core. A core-only entry point that needs display, title, and lead sizes that
+scale with the viewport (landing pages, marketing pages, hero sections,
+documentation homepages) imports it explicitly:
 
 ```css
 @import "actual-css/css/typography/fluid";
@@ -116,14 +117,14 @@ baseline stays sans so app UI inherits predictably.
 
 The framework exposes a small set of weights:
 
-- `--font-weight` (400) — body default
-- `--font-weight-medium` (500) — slightly heavier than body, for nav links
-- `--font-weight-strong` (650) — emphasis, prose headings, badges, tabs, table headers
-- `--font-weight-bold` (700) — the strongest weight exposed, used by the navbar brand and the accordion summary
+- `--font-weight-normal` (400) — body default
+- `--font-weight-medium` (500) — slightly heavier than body, for nav links and accordion summaries
+- `--font-weight-semibold` (600) — emphasis, prose headings, badges, tabs, table headers
+- `--font-weight-bold` (700) — the strongest weight exposed, used by the navbar brand
 
 No `--font-weight-light`. Light weights depend on the typeface, are rarely a good default, and add surface area without a recurring need.
 
-These weights are also the values used by components. Components do not use literal `font-weight: 600` or `font-weight: 750`; they reference the tokens. Theme authors can re-map them in one place.
+These weights are also the values used by components. Components reference the tokens instead of literal weights, so theme authors can re-map the scale in one place.
 
 ## Line heights
 
@@ -159,7 +160,7 @@ Headings are split between the global baseline and `.prose`.
 
 Globally, headings get a tight line-height, a color from `--heading` (or inherited), and progressive `text-wrap: balance`. They do not get a `font-size`, a `font-weight`, or margins. The reason is that a card heading, a dialog title, or a sidebar section should not be auto-magically enlarged by selector.
 
-Inside `.prose`, headings get a `font-weight` from `--font-weight-strong`, a tighter line-height from `--prose-heading-line-height`, margin rhythm, and keep the global `text-wrap: balance`. Their color follows the contextual `--heading` alias, so prose also composes correctly with a contextual surface. The `h1` to `h4` font sizes are scoped to `.prose`, remain low-specificity, and are not exposed as a public scale.
+Inside `.prose`, headings get a `font-weight` from `--font-weight-semibold`, a tighter line-height from `--prose-heading-line-height`, margin rhythm, and keep the global `text-wrap: balance`. Their color follows the contextual `--heading` alias, so prose also composes correctly with a contextual surface. The `h1` to `h4` font sizes are scoped to `.prose`, remain low-specificity, and are not exposed as a public scale.
 
 The `hgroup` element gets only structural styling: a grid layout, a gap, and a reset of internal margins. No font-size, no color, no weight. Its visual identity is the responsibility of the headings and paragraphs it contains.
 
@@ -175,7 +176,27 @@ Three logical alignment utilities exist (`.text-start`, `.text-center`, `.text-e
 
 `small` gets a smaller font size globally (`0.875em`) because it is a semantic element, not a utility. There is no `.small` class competing with the element.
 
-`code`, `kbd`, `samp`, and `pre` get the mono font family globally. Visual treatment (background, padding, radius) is left to `.prose` or to code-block components.
+`code`, `kbd`, `samp`, and `pre` get the mono font family globally. `pre` also gets `overflow-x: auto`, because one unbreakable line widens the whole page and nothing in the markup warns you. That is containment, not decoration: background, padding, and radius are still left to `.prose` or to a code-block component.
+
+For a standalone snippet outside authored content, `.prose` is the ready-made box — opt out of the reading measure so the code can use the full width:
+
+```html
+<div class="prose" style="--prose-measure: none">
+  <pre><code>bun add actual-css</code></pre>
+</div>
+```
+
+`hr` resets the UA's `margin-inline: auto`. In document flow that changes nothing — auto inline margins on an auto-width block resolve to zero — but as a flex or grid item they replace the cross-axis stretch, which made an `<hr>` inside a `.stack` compute to zero width and disappear. `.stack` deliberately leaves the inline axis free (self-centering children keep working), so the reset belongs to the element.
+
+Its block margin is tunable with `--hr-space`. The `--space-60` default suits a rule closing a page section; a rule separating two rows inside a panel wants far less.
+
+```css
+.settings-panel hr {
+  --hr-space: var(--space-10);
+}
+```
+
+The hook applies to an `hr` in document flow. Inside `.stack` or `.prose` the parent owns the distance between siblings and overrides the element's own margin — express the rhythm there instead, with `--gap` or `--prose-flow`.
 
 ## Tables
 
@@ -198,14 +219,14 @@ To enable fluid display type on a marketing or documentation surface, import the
 
 The module does not change anything in the core: it adds three size tokens and three classes. Body text, app UI, and the default prose scale are not affected.
 
-Projects that do not need fluid display type do nothing — the module is not part of the default bundle.
+Projects on `actual-css/css/typography` or `actual-css/full` already have the module. A minimal-core project that does not need fluid display type does nothing — the module is not in the core.
 
 ## What not to reintroduce
 
 These are decisions that the framework has already made. Re-introducing them silently would regress the system.
 
 - Do not add `font-size` on global `h1` to `h6`. Headings inherit size from context (component or `.prose`).
-- Do not add `font-weight` on global `h1` to `h6`. Strong weight is scoped to `.prose` and to components that need it.
+- Do not add `font-weight` on global `h1` to `h6`. Heavier weights are scoped to `.prose` and to components that need them.
 - Do not add global `text-decoration: underline` on `a`. Links get their visual affordance from `.prose` or from their component.
 - Do not add `transition: all`. Transitions target specific properties.
 - Do not add a `--font-weight-light`. It is rarely a good default and depends on the typeface.

package/docs/pages/guides/introduction.md

@@ -78,7 +78,9 @@ 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 controls consistently.
+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 typography or icons.
 Undocumented `is-*` classes are runtime internals.
 
 ```html
@@ -139,16 +141,16 @@ internal design documents for contributors.
 
 Actual CSS is built around progressive enhancement.
 
-| Tier         | Firefox | Safari    | Chromium |
-| ------------ | ------- | --------- | -------- |
-| Degraded     | 78+     | 14+       | 88+      |
-| **Minimal**  | **98+** | **15.4+** | **99+**  |
-| Intermediate | 121+    | 16+       | 106+     |
-| Recommended  | 129+    | 17.5+     | 123+     |
+| Tier        | Firefox  | Safari  | Chromium |
+| ----------- | -------- | ------- | -------- |
+| Degraded    | 78+      | 14+     | 88+      |
+| **Minimal** | **125+** | **17+** | **116+** |
+| Recommended | 129+     | 17.5+   | 123+     |
 
 **Degraded** — semantic HTML and core CSS remain usable. JavaScript
 enhancements are outside the supported contract.
 
 **Minimal** — full Actual support, including the JavaScript runtime. The
-runtime assumes modern browser APIs and ships no legacy compatibility layers or
-polyfills.
+runtime assumes modern browser APIs — including the native manual Popover
+transport used by interactive surfaces — and ships no legacy compatibility
+layers or polyfills.

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

@@ -17,14 +17,16 @@ unsupported — it is not tested, documented as supported, or preserved when the
 runtime evolves. The runtime assumes the modern platform primitives available
 across Minimal and ships no compatibility layer or polyfill.
 
-| Tier         | Firefox | Safari    | Chromium |
-| ------------ | ------- | --------- | -------- |
-| Degraded     | 78+     | 14+       | 88+      |
-| **Minimal**  | **98+** | **15.4+** | **99+**  |
-| Intermediate | 121+    | 16+       | 106+     |
-| Recommended  | 129+    | 17.5+     | 123+     |
+| Tier        | Firefox  | Safari  | Chromium |
+| ----------- | -------- | ------- | -------- |
+| Degraded    | 78+      | 14+     | 88+      |
+| **Minimal** | **125+** | **17+** | **116+** |
+| Recommended | 129+     | 17.5+   | 123+     |
 
-The tier definitions live in the browser-support design note.
+The floor is set by the native manual Popover transport (`popover="manual"`,
+`showPopover()`, `hidePopover()`), which interactive surfaces use to promote a
+panel to the top layer without moving it in the DOM. The tier definitions live
+in the browser-support design note.
 
 ## Overview
 
@@ -109,7 +111,7 @@ The JS is designed to run on its own, without Actual's stylesheet.
   presentation class needed. Self-describing attributes (`data-mask`,
   `data-tooltip`, `data-context-menu`) stay framework-neutral by construction.
 - **`selectors.js`** lists the state classes the runtime *writes* (`is-open`,
-  `was-validated`, `is-sheet`, …). Edit this file (or alias it in a bundler) to
+  `was-validated`, …). Edit this file (or alias it in a bundler) to
   match a different CSS framework's state vocabulary. It is a read-side-only
   adapter — it does not bridge CSS class names to JS initialization.
 - **One documented exception:** validation reads `.field-error` (or its alias
@@ -157,17 +159,30 @@ const stop = autoUpdate(trigger, float, () => {
 
 Options passed to `reposition()`:
 
-| Option         | Default          | Contract                                     |
-| -------------- | ---------------- | -------------------------------------------- |
-| `placement`    | `"bottom-start"` | Preferred side and alignment                 |
-| `distance`     | `0`              | Gap from the reference element               |
-| `flip`         | `true`           | Flip when the preferred side is out of view  |
-| `shift`        | `true`           | Shift along the cross axis to stay in bounds |
-| `shiftPadding` | `4`              | Minimum space kept from the boundary         |
-| `scope`        | viewport         | Boundary element for overflow decisions      |
+| Option            | Default          | Contract                                     |
+| ----------------- | ---------------- | -------------------------------------------- |
+| `placement`       | `"bottom-start"` | Preferred side and alignment                 |
+| `distance`        | `0`              | Gap from the reference element               |
+| `flip`            | `true`           | Flip when the preferred side is out of view  |
+| `shift`           | `true`           | Shift along the cross axis to stay in bounds |
+| `shiftPadding`    | `4`              | Minimum space kept from the boundary         |
+| `scope`           | viewport         | Boundary element for overflow decisions      |
+| `coordinateSpace` | `"viewport"`     | Space the written `left`/`top` use           |
 
 `placement` takes a `-start` or `-end` alignment suffix.
 
+Measurement is always in viewport coordinates; `coordinateSpace` only changes
+what is written. `"viewport"` expects `position: fixed`; `"document"` adds the
+page scroll and expects `position: absolute` against the initial containing
+block, which the top layer supplies to an open popover. The browser then
+scrolls the element with the page rather than `autoUpdate()` correcting it a
+frame later — right for a reference that scrolls with the page, wrong for a
+fixed or sticky one. `tooltip.js` and element-anchored surfaces choose this
+coupled coordinate/position mode once per opening. A point-positioned surface
+always uses fixed viewport coordinates because `x` and `y` are client
+coordinates. Scrolling a nested container still needs the next `autoUpdate()`
+frame; document coordinates remove correction only for page scrolling.
+
 `@lekoala/floating` is the standalone positioning dependency used by the
 runtime. `autoUpdate(reference, float, callback)` batches scroll, resize, and
 element-resize callbacks per document and returns a stop handle; it observes
@@ -185,23 +200,32 @@ must be able to position a listbox under an input — that is the test.
 or account for:
 
 ```css
-.my-panel              { position: absolute; z-index: 100; }
-.my-panel[hidden]      { display: none; }
-/* surface.js sets position: fixed + inline left/top on open —
+.my-panel          { position: absolute; }
+.my-panel[popover] { inset: auto; margin: 0; }
+.my-panel[popover]:not(:popover-open) { display: none; }
+/* surface.js sets a coupled fixed/viewport or absolute/document mode —
    do not override with !important */
-/* .is-open / .is-sheet / .surface-backdrop are written by surface.js
-   — style or ignore them */
+/* no z-index: an open panel is promoted to the top layer, where
+   numbers do not apply — see Layering in foundations/tokens */
+/* .is-open is written by surface.js — style or ignore it */
 /* --surface-anchor-width is set while an open surface is positioned */
 /* data-actual-surface is written by surface.js for teardown
    — never select on it */
 ```
 
-Two non-obvious requirements:
+Three non-obvious requirements:
 
-1. `[hidden] { display: none }` must not be defeated by a higher-specificity
-   `display` rule — `surface.js` toggles `hidden`, not `display`.
-2. The open state switches to `position: fixed` with measured inline
-   coordinates.
+1. `surface.js` writes `popover="manual"` and removes `hidden`: the panel is
+   promoted to the top layer where it stands, never reparented, and the closed
+   state belongs to the platform. `.is-open` is the state the runtime writes
+   and the only one to key styles on.
+2. A panel that declares its own `display` must restore `display: none` for the
+   closed popover. An author declaration outranks the UA origin whatever the
+   specificity, so a bare `display: grid` leaves a closed panel painted at its
+   static position.
+3. The open state switches to the coupled position and coordinate mode chosen
+   from its anchor, with measured inline coordinates. The UA's own `inset` /
+   `margin` must be cleared.
 
 Lifecycle: `prepareSurface` → `openSurface` → `closeSurface` →
 `disconnectSurface`. `retainSurface(panel)` reference-counts a surface shared by
@@ -209,6 +233,11 @@ several triggers and returns a release function; `isSurfaceOpen` and
 `getSurfaceAutoClose` read current state. The separate `escape` primitive adds
 visible dismissable UI to the shared per-document Escape stack.
 
+Actual-managed surfaces are mutually exclusive within a document. Opening a
+surface closes any other open Actual surface, including one containing its
+trigger. Nested surfaces are not currently supported: a panel opened from
+inside another panel replaces it rather than stacking on it.
+
 `openSurface(menu, opts)` dispatches a cancelable `actual:surface-open` event —
 widgets can veto or decorate opens, and context menus inject their own
 `source`/`restoreFocusTo` through it.
@@ -224,14 +253,11 @@ widgets can veto or decorate opens, and context menus inject their own
 | `shift`           | `true`           | Shift to stay within the boundary           |
 | `shiftPadding`    | `4`              | Minimum space kept from the boundary        |
 | `scope`           | viewport         | Boundary element                            |
-| `mobile`          | `"auto"`         | Sheet behavior                              |
-| `breakpoint`      | `768`            | Max viewport width for an automatic sheet   |
 | `autoClose`       | `"outside"`      | Which clicks close the surface              |
 | `dismissOnScroll` | `false`          | Close on a scroll the user just started     |
 | `restoreFocusTo`  | `trigger`        | Element focused on close                    |
 
 `x`, `y` replace the anchor entirely, which is what a context menu needs.
-`mobile` takes `"auto"`, `"sheet"`, `"none"` or `"anchored"`.
 
 `autoClose` takes `"true"` to close on inside and outside clicks, `"inside"` or
 `"outside"` to limit it to one side, and `"false"` to disable automatic click
@@ -391,6 +417,63 @@ on the same root throws, and `disconnect()` releases the name so it can be
 registered again. A custom root passed as the third argument must be disposed
 by its owner; the default `document.documentElement` root is not affected.
 
+### Applying behaviors from application selectors
+
+Prefer declarative `data-enhance` in HTML. When server-rendered markup or
+application conventions make JavaScript more convenient, use
+`applyEnhancement(name, selector, root?)`:
+
+```js
+import "actual-css/js/tab";
+import "actual-css/js/flyout";
+import "actual-css/js/validation";
+import { applyEnhancement } from "actual-css/js/enhance";
+
+const bindings = {
+  tabs: ".tabs",
+  flyout: ".menu-trigger",
+  validation: "form.needs-validation",
+};
+
+for (const [name, selector] of Object.entries(bindings)) {
+  applyEnhancement(name, selector);
+}
+```
+
+Run this after the target markup exists, for example in a module script.
+Select the element that owns the behavior, not necessarily the element carrying
+the component class. For example, `flyout` applies to **triggers**, not `.flyout`
+panels. Those triggers need `aria-controls` pointing to their panels. Tooltips use
+`data-tooltip` directly and do not need a named enhancement.
+
+`selector` is a CSS selector. `root` defaults to `document.documentElement` and
+uses `querySelectorAll()` semantics: only descendants match, never the scope
+itself. Pass a container to limit the application:
+
+```js
+applyEnhancement("tabs", ".tabs", container);
+```
+
+Each registration on the scope or its ancestors refreshes the scope once.
+Shadow roots need their own registrations; document registrations do not cross
+into them.
+
+The function returns an array of matched elements, preserves existing
+tokens, and can be called repeatedly without initializing an active behavior
+twice. Invalid names or selectors throw. Without a DOM it returns an
+empty array. It does not import modules: applying a token before its module is
+registered lets that registration's initial scan discover it later.
+
+`applyEnhancement()` is a one-time convenience for adding an enhancement token
+to elements selected by the application. It does not create a persistent
+selector-to-enhancement binding. For injected markup, author `data-enhance`
+directly or call the function with a scope containing the new elements.
+Detached elements receive the token and initialize when inserted into a
+registered root. Removing the token does not disconnect an active behavior.
+
+`data-enhance` remains the portable behavior contract. Class mappings belong to
+the application; Actual does not infer behavior from presentation classes.
+
 ### Enhancement manifests
 
 The enhancement-loader lets a server (or static HTML) declare document-wide
@@ -676,7 +759,9 @@ field, and dispatches a bubbling `actual:invalid` event with
   <input class="input" name="email" type="email" required
          aria-describedby="email-error" />
   <span class="field-error" id="email-error">Enter a valid email.</span>
-  <button class="btn primary" type="submit">Submit</button>
+  <div class="form-actions">
+    <button class="btn primary" type="submit">Submit</button>
+  </div>
 </form>
 
 <div class="status-bar" data-status role="status" aria-live="polite" aria-atomic="true"></div>

package/docs/pages/guides/tailwind.md

@@ -163,7 +163,7 @@ Tailwind allows almost every utility to be changed independently at a breakpoint
 There is intentionally no equivalent Actual syntax such as:
 
 ```text
-md:cluster xl:gap-lg
+md:cluster xl:spacious
 ```
 
 First ask what the layout is supposed to do.
@@ -213,7 +213,8 @@ Actual does not prohibit media queries. It simply does not encode every media qu
 | `max-w-*` for readable text          | `.measure` where appropriate                      |
 | common visual component bundle       | Actual component                                  |
 | component colors                     | intents such as `.primary`, `.danger`, `.success` |
-| repeated layout spacing              | `--gap` / layout hooks                            |
+| `gap-*` on one container             | `gap: var(--space-*)`                             |
+| rebind rhythm for nested primitives  | `--gap` on the layout context                     |
 | small common corrections             | Actual utilities                                  |
 | breakpoint-prefixed utilities        | intrinsic layout, container query, or project CSS |
 | arbitrary values                     | custom property or project CSS                    |

package/docs/pages/layout/media.md

@@ -25,4 +25,4 @@ Add `.items-center` to align the leading element with short trailing content. Fo
 </div>
 ```
 
-The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule.
+The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule. The [Workspaces example](../examples/overview.md) shows the card pattern: `card > header` with `.media` plus `hgroup`, and row actions in the header — never a third `.media` child.

package/docs/pages/layout/overview.md

@@ -47,4 +47,14 @@ Most layout primitives read `--gap` and allow local overrides.
 
 Prefer a local custom property over adding many one-off utility classes. Use inline styles only for demos, prototypes, or truly dynamic values.
 
-There are no `.gap-sm` / `.gap-md` / `.gap-lg` density variants on the core layout primitives; set `--gap` locally when only spacing should change. The extra utilities (`src/css/utilities/extra.css`) ship those gap utilities for row/column containers.
+Set `--gap` locally to retune the primitive and its nested layouts. To change only one element's rhythm without reaching nested primitives, set the `gap` property instead.
+
+## Spacing expresses relationships
+
+**Components own their internal rhythm; layout owns the relationships between components.**
+
+Prefer a parent `gap` for relationships between peers instead of encoding sibling margins into a component. Smaller gaps imply a stronger relationship; progressively larger gaps distinguish groups and sections.
+
+Before adding a divider or other separating chrome, consider whether additional spacing already expresses the boundary clearly.
+
+Density changes the amount of space available, not the relationships that space communicates. When a composition contains local, group, and section rhythms, preserve their relative hierarchy with nested or local `--gap` values rather than relying on one inherited gap at every level. See [Stack](./stack.md) for the nesting and density mechanics.

package/docs/pages/layout/scroll-snap.md

@@ -24,10 +24,10 @@ Use `.scroll-snap` for a niche row of items that should scroll horizontally, suc
 
 The baseline is flex layout plus `overflow-x: auto`, so older browsers still get a usable horizontal scroll area. Browsers with scroll snap support add `scroll-snap-type` and item alignment.
 
-Items snap to the inline start edge by default. Use `data-snap="center"` for visual rails where centered cards are the better fit.
+Items snap to the inline start edge by default, with `proximity` snapping so a short rail never fights the pointer. Use `data-snap-align="center"` for visual rails where centered cards are the better fit, and `data-snap="mandatory"` only when every stop must land.
 
 ```html demo
-<div class="scroll-snap" data-snap="center" style="--scroll-snap-item-size: min(85%, 18rem)">
+<div class="scroll-snap" data-snap-align="center" style="--scroll-snap-item-size: min(85%, 18rem)">
   <article class="card">One</article>
   <article class="card">Two</article>
   <article class="card">Three</article>
@@ -42,7 +42,7 @@ Items snap to the inline start edge by default. Use `data-snap="center"` for vis
 - `--scroll-snap-gap` — space between items.
 - `--scroll-snap-padding` — inline scroll padding, so a snapped item does not sit
   flush against the container edge. Not declared; falls back to `--scroll-snap-gap`.
-- `--scroll-snap-align` — item snap alignment. Prefer `data-snap="center"`
+- `--scroll-snap-align` — item snap alignment. Prefer `data-snap-align="center"`
   over setting this directly.
 
 Keep scrollbars visible by default. If a product deliberately hides them, make that choice explicit with `data-scrollbar="hidden"`.

package/docs/pages/layout/stack.md

@@ -41,15 +41,17 @@ not as the wrapper that lays out independent full-width regions of a page.
 
 ## Choosing a density
 
-`--gap` is the primitive's channel, and the density variants set it at the point
-of use. Pick the one that matches how tightly the children belong together:
+`--gap` is the primitive's channel, and the density context variants set it at
+the point of use. Apply the density class on the stack itself to size one
+instance, or on an ancestor to reach nested layouts. Pick the one that matches
+how tightly the children belong together:
 
 | Markup            | Gap  | Use for                                    |
 | ----------------- | ---- | ------------------------------------------ |
 | `.stack gap-none` | 0    | Lines forming one typographic unit         |
-| `.stack sm`       | 8px  | A homogeneous series of controls           |
+| `.stack compact`  | 8px  | A homogeneous series of controls           |
 | `.stack`          | 12px | Normal flow between distinct elements      |
-| `.stack lg`       | 24px | Sections, or blocks that read as separated |
+| `.stack spacious` | 24px | Sections, or blocks that read as separated |
 
 One typographic unit means a name and a job title, or a figure and its caption.
 A homogeneous series means a radio list, a checkbox list, or a compact vertical
@@ -57,8 +59,14 @@ menu.
 
 The distinction between the first two matters. `42` above `Open issues` is
 almost a single block of text, so it takes `gap-none`. Three `.choice` labels
-stay three separate controls that happen to form one group, so they take `sm` —
-tighter than the default, but still spaced.
+stay three separate controls that happen to form one group, so they take
+`compact` — tighter than the default, but still spaced.
+
+`.compact` and `.spacious` rebind `--gap` to `--space-20` and `--space-50`.
+Because the token is inherited, the same two classes also tighten the inner gap
+of any nested stack, cluster, and grid. For a one-off gap that must *not* follow
+density, set the `gap` property directly on the instance (the next section
+explains why).
 
 A stack that mixes kinds keeps the default: five `.field` wrappers and one lone
 `.choice` is a form that contains a checkbox, not a list of options, and
@@ -84,7 +92,7 @@ depth:
 ```
 
 Both give the region the same spacing; only the second stops there. This is what
-makes a nested `.stack sm` a real density choice — 12px down to 8px — rather
+makes a nested `.stack compact` a real density choice — 12px down to 8px — rather
 than a patch cancelling a rhythm inherited from three levels up.
 
 Setting `--gap` is still the right move on the element that *consumes* it: a
@@ -92,8 +100,8 @@ one-off `--gap` on a card body or an actions row tunes that primitive and
 nothing below it, because the setter is the consumer. The leak only appears when
 a container sets the token and its children read it.
 
-`.sm` and `.lg` are the deliberate exception: they set `--gap` precisely so a
-density context reaches nested layouts.
+`.compact` and `.spacious` are the deliberate exception: they set `--gap`
+precisely so a density context reaches nested layouts.
 
 ## Grouping items tightly
 

package/docs/pages/patterns/icon-input.md

@@ -11,13 +11,15 @@ Use `.input-icon` for a search or filter input with a leading icon.
 
 It positions the wrapper's first child absolutely inside a relative container and grows the input's start padding to clear it. `pointer-events: none` on the icon keeps clicks passing through to the input underneath. It is icon-library agnostic — an `<i>` webfont icon, an inline `<svg>`, or a `<span>` all work as the wrapper's first child.
 
-The icon keeps a fixed `--input-icon-size` (1.25rem); density contexts shrink the control geometry around it, not the pictogram. Apply the density class to the wrapper and to the input so the control height follows:
+The icon follows local typography through `--input-icon-size`. Apply a size to
+the wrapper so icon, input type, and control geometry scale together. A density
+context changes only the geometry.
 
 ```html demo
 <div class="stack">
   <label class="input-icon sm">
     <i class="ti ti-search" aria-hidden="true"></i>
-    <input class="input sm" type="search" aria-label="Search">
+    <input class="input" type="search" aria-label="Search">
   </label>
 </div>
 ```

package/docs/pages/patterns/icon-slot.md

@@ -14,6 +14,8 @@ centers its glyph, and clips overflow:
 - `overflow: hidden`;
 - a child `svg` constrained to the box.
 
+Icons inherit first: an icon that supports nearby content uses `currentColor`; it takes its own color only when it conveys an independent state or intent.
+
 ## The contract
 
 ```css

package/docs/pages/patterns/intent-nesting.md

@@ -1,3 +1,3 @@
 # Intent Nesting
 
-Intent on an ancestor must not tint nested components, and a local intent inside an intent-carrying ancestor must win. Both directions are verified in `tests/css-audit.test.js` and the kitchen-sink demo template. Intent classes only expose `--intent` and `--intent-fg`; each consuming component opens a local intent boundary in a `:where()` block that resets exactly the tokens it consumes to initial. Parent intents do not leak into nested components, and a local intent class still wins because it has higher specificity than `:where()`.
+Intent on an ancestor must not tint nested components, and a local intent inside an intent-carrying ancestor must win. Both directions are verified in `tests/css-audit.test.js`, `tests/browser/intent-boundary.test.js`, `tests/browser/soft-boundary.test.js` and the kitchen-sink demo template. Intent classes expose `--intent`, `--intent-fg`, and the soft-foreground relay `--intent-soft-fg`; each consuming component opens a local intent boundary in a `:where()` block that resets exactly the tokens it consumes to initial. Parent intents do not leak into nested components, and a local intent class still wins because it has higher specificity than `:where()`.

package/docs/pages/utilities/overview.md

@@ -19,7 +19,7 @@ not about opting in. Importing `actual-css/css/utilities` — or
 | **Extra** | `actual-css/css/utilities/extra` | Explicit property/value names      |
 
 Base is the curated set, and it is where a short name is allowed: `.px`, `.py`,
-`.mbs`, `.gap-none`. Extra spells out the property and the value — `.gap-sm`,
+`.mbs`, `.gap-none`. Extra spells out the property and the value — `.row-gap-context`,
 `.overflow-x-auto`, `.justify-content-center` — and never gives a base utility
 a second spelling.
 
@@ -33,8 +33,29 @@ list the two layers as separate tables. Every other utility page is base only.
 
 > Utilities deliberately excluded to keep the surface small and intentional.
 
-- No display scale such as `.block`, `.flex`, `.grid` — use layout primitives.
+- No display scale such as `.block`, `.flex`, `.grid` — use layout primitives. The extra layer does ship explicit `.display-flex` / `.display-grid` escape hatches; see Display escape hatches below.
 - No color scales such as `.text-primary` or `.bg-success` — intent colors belong to components and state.
 - No breakpoint utility variants — use container queries or layout primitives.
 - No utility variants for hover, focus, dark mode, or arbitrary selectors — use component states.
 - No full spacing scale with every step and direction — the 17 spacing helpers across the core and extra utilities cover the most common escape hatches.
+
+## Display escape hatches
+
+A one-off display correction is the exception to the display Non-Goal. The extra
+layer spells the property and the value, so these are opt-in corrections, not the
+short atomic scale the Non-Goal bans.
+
+| Class                   | Description              |
+| ----------------------- | ------------------------ |
+| `.display-block`        | `display: block`.        |
+| `.display-inline`       | `display: inline`.       |
+| `.display-inline-block` | `display: inline-block`. |
+| `.display-flex`         | `display: flex`.         |
+| `.display-inline-flex`  | `display: inline-flex`.  |
+| `.display-grid`         | `display: grid`.         |
+| `.display-none`         | `display: none`.         |
+| `.visibility-hidden`    | `visibility: hidden`.    |
+
+Prefer `.stack`, `.cluster`, `.grid`, and the other layout primitives first.
+Reach for a display helper when existing component or third-party markup needs a
+one-line correction and no primitive expresses it.

package/docs/pages/utilities/sizing-wrapping.md

@@ -27,7 +27,7 @@ layout primitive from wrapping — for example to force a `.cluster` onto a sing
 row — set `--cluster-wrap: nowrap`.
 
 ```html demo
-<div class="cluster sm" style="--cluster-wrap: nowrap;">
+<div class="cluster compact" style="--cluster-wrap: nowrap;">
   <select class="select sm fit" aria-label="Segment">
     <option>All segments</option>
   </select>

package/docs/pages/utilities/spacing.md

@@ -18,9 +18,6 @@ Extra utilities:
 
 | Class                       | Description                                   |
 | --------------------------- | --------------------------------------------- |
-| `.gap-sm`                   | `gap: var(--space-20)` — denser row rhythm.   |
-| `.gap-md`                   | `gap: var(--space-40)` — default row rhythm.  |
-| `.gap-lg`                   | `gap: var(--space-50)` — roomier row rhythm.  |
 | `.padding-context`          | All-side padding at the current density step. |
 | `.gap-context`              | `gap: var(--gap)`.                            |
 | `.row-gap-context`          | `row-gap: var(--gap)`.                        |
@@ -32,8 +29,8 @@ Extra utilities:
 | `.margin-block-end-auto`    | Pushes content toward the block start.        |
 
 Spacing helpers follow the density context. The default step is
-`--space-40` (1rem); the `.sm` context tightens it to `--space-20` (0.5rem)
-and the `.lg` context loosens it to `--space-50` (1.5rem). All helpers read
+`--space-40` (1rem); the `.compact` context tightens it to `--space-20` (0.5rem)
+and the `.spacious` context loosens it to `--space-50` (1.5rem). All helpers read
 `--density-space` and map to logical properties (`padding-block`,
 `margin-block-end`, etc.) for writing-direction safety.
 
@@ -51,8 +48,13 @@ Override the default gap from layout primitives (`.stack`, `.cluster`, `.grid`):
 - `.gap-none` → `gap: 0`
 
 `.gap-none` sets the element's own gap directly and does not change `--gap`
-for nested layouts. For a denser or roomier rhythm, use the `.sm` / `.lg`
-density contexts or override `--gap` on the layout instance.
+for nested layouts. For a denser or roomier rhythm, use the `.compact` /
+`.spacious` density contexts, or set the `gap` property on the instance when the
+change must stop there.
+
+`--gap` defines the contextual rhythm; `.gap-context` applies that rhythm to a
+container that does not already consume `--gap`. The layout primitives
+(`.stack`, `.cluster`, `.grid`, …) read it on their own.
 
 ## Padding
 
@@ -82,5 +84,5 @@ No `mbs-none` / `mbe-none` — use `margin: 0` via `.list-reset` for lists, or a
 
 ## CSS hooks
 
-- `--density-space` — the step every padding and margin helper reads; `.sm` sets it to `--space-20`, default to `--space-40`, `.lg` to `--space-50`.
+- `--density-space` — the step every padding and margin helper reads; `.compact` sets it to `--space-20`, default to `--space-40`, `.spacious` to `--space-50`.
 - `--gap` — base gap of layout primitives; read by the optional `.gap-context`, `.row-gap-context`, and `.column-gap-context` helpers.

package/llms.txt

@@ -14,9 +14,10 @@ Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [m
 
 - `actual-css` — the minimal core: tokens, theme contract, reset, base elements, and universal variants. Components and layout primitives are NOT included.
 - `actual-css/full` — the complete framework: core plus every component, form, layout, typography, effect, and utility family.
-- `actual-css/js` — the enhancement loader only; it discovers `data-enhance` markers and loads enhancers on demand.
+- `actual-css/js` — the enhancement-loader entry only: it watches `data-enhance-modules` manifest blocks and imports the declared enhancers on demand.
 - `actual-css/js/full` — the complete runtime with all built-in enhancers pre-registered.
 - `actual-css/reserved-classes.json` — machine-readable list of the framework-owned class namespace. Use it to check whether a class belongs to Actual CSS and to validate claimed framework classes; application-specific classes are expected to exist outside this manifest.
+- `actual-css/components.json` — machine-readable component index, derived from the sources (CSS headers, selectors, package exports, `src/js`) by `scripts/build-catalog.js` and verified by `check:catalog`. Gives each component its import paths, owned classes, hooks, states, and registered enhancement tokens — enough to know what exists and where to read more, not a replacement for `docs/pages/components/*.md`.
 - Individual families and modules are importable separately (`actual-css/css/components`, `actual-css/css/layout/grid`, `actual-css/js/dialog`, …); see [README](README.md) and [Modular imports](docs/pages/guides/modular-import.md).
 
 Forms are the one family with two aggregate entrypoints: