actual-css 0.6.0 → 0.8.0

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
@@ -124,19 +126,18 @@ The JS is designed to run on its own, without Actual's stylesheet.
 ## The runtime as a primitive kit
 
 For building custom widgets (select, tags, date picker) on Actual's primitives,
-see the widget-primitives design note. Every primitive subpath is published in
-`package.json#exports`:
-
-| Subpath                  | Purpose                                                          |
-| ------------------------ | ---------------------------------------------------------------- |
-| `actual-css/js/enhance`  | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
-| `actual-css/js/escape`   | Per-document LIFO Escape dismissal stack                         |
-| `actual-css/js/events`   | The `actual:*` event name constants                              |
-| `actual-css/js/floating` | Positioning engine (`reposition`, `repositionAt`, `autoUpdate`)  |
-| `actual-css/js/focus`    | Focusable-item lookup and helpers                                |
-| `actual-css/js/keys`     | Roving-focus item navigation helpers                             |
-| `actual-css/js/menu`     | Menu keyboard/click wiring, item vocabulary                      |
-| `actual-css/js/surface`  | Surface lifecycle (`openSurface`, `closeSurface`, …)             |
+see the widget-primitives design note. Every Actual runtime primitive subpath is
+published in `package.json#exports`:
+
+| Subpath                 | Purpose                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| `actual-css/js/enhance` | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
+| `actual-css/js/escape`  | Per-document LIFO Escape dismissal stack                         |
+| `actual-css/js/events`  | The `actual:*` event name constants                              |
+| `actual-css/js/focus`   | Focusable-item lookup and helpers                                |
+| `actual-css/js/keys`    | Roving-focus item navigation helpers                             |
+| `actual-css/js/menu`    | Menu keyboard/click wiring, item vocabulary                      |
+| `actual-css/js/surface` | Surface lifecycle (`openSurface`, `closeSurface`, …)             |
 
 The exports map is explicit — it *is* the statement of what is public.
 
@@ -149,33 +150,49 @@ computes and writes inline `left`/`top`, `data-placement`,
 caller owns the floating element's presentation entirely.
 
 ```js
-import { autoUpdate, reposition, repositionAt } from "actual-css/js/floating";
+import { autoUpdate, reposition, repositionAt } from "@lekoala/floating";
 
-const stop = autoUpdate(float, () => {
+const stop = autoUpdate(trigger, float, () => {
   reposition(trigger, float, { placement: "bottom-start", distance: 4 });
 });
 ```
 
 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 main 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.
 
-`autoUpdate(element, callback)` batches scroll, resize, and element-resize
-callbacks per document and returns a stop handle; it does not keep a closed or
+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
+both the reference and floating element while the surface is open. Pass `null`
+as the reference for point-positioned surfaces. It does not keep a closed or
 hidden element positioned. `repositionAt(x, y, float, opts)` positions relative
 to a fixed point — used by context menus.
 
-A third-party widget importing only `floating` with no Actual stylesheet must be
-able to position a listbox under an input — that is the test.
+A third-party widget importing only `@lekoala/floating` with no Actual stylesheet
+must be able to position a listbox under an input — that is the test.
 
 ## Surface contract
 
@@ -183,23 +200,32 @@ 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
@@ -207,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.
@@ -222,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
@@ -389,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
@@ -674,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:

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "actual-css",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.2",
   "license": "MIT",
   "author": "Thomas <thomas@lekoala.be>",
   "repository": {
@@ -58,7 +58,6 @@
     "./js/parse-config": "./src/js/parse-config.js",
     "./js/events": "./src/js/events.js",
     "./js/filter": "./src/js/filter.js",
-    "./js/floating": "./src/js/floating.js",
     "./js/flyout": "./src/js/flyout.js",
     "./js/focus": "./src/js/focus.js",
     "./js/focus-group": "./src/js/focus-group.js",
@@ -74,7 +73,8 @@
     "./js/validation": "./src/js/validation.js",
     "./js/status": "./src/js/status.js",
     "./js/surface": "./src/js/surface.js",
-    "./reserved-classes.json": "./scripts/reserved-classes.json",
+    "./reserved-classes.json": "./reserved-classes.json",
+    "./components.json": "./components.json",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -98,7 +98,8 @@
     "src/cli",
     "src/js",
     "src/tooling",
-    "scripts/reserved-classes.json",
+    "reserved-classes.json",
+    "components.json",
     "docs",
     "CHANGELOG.md",
     "llms.txt",
@@ -120,6 +121,9 @@
     "check:compat": "bun scripts/check-compat.js",
     "check:css-api": "bun scripts/check-css-api.js",
     "check:color-space": "bun scripts/check-color-space.js",
+    "report:theme-contrast": "bun scripts/report-theme-contrast.js",
+    "report:neutral-ramp": "bun scripts/report-neutral-ramp.js",
+    "report:dead-css": "bun scripts/report-dead-css.js",
     "check:architecture": "bun scripts/check-css-architecture.js",
     "build:dist": "bun scripts/build-dist.js",
     "build:js": "bun scripts/build-js.js",
@@ -128,20 +132,27 @@
     "check:enhance": "bun run scripts/check-enhance.js",
     "generate:reserved": "bun scripts/generate-reserved-classes.js",
     "check:reserved": "bun scripts/check-reserved.js",
+    "generate:catalog": "bun scripts/build-catalog.js",
+    "check:catalog": "bun scripts/check-catalog.js",
     "check:links": "bun scripts/check-doc-links.js",
     "check:templates": "bun scripts/check-templates.js",
+    "check:markup": "bun scripts/check-markup.js",
     "shot:forced": "bun scripts/forced-colors-shot.js",
     "shot:multi": "bun scripts/multi-shot.js",
     "shot:page": "bun scripts/page-shot.js",
     "probe": "bun scripts/probe.js",
+    "serve": "bun scripts/serve.js",
     "check:sync": "bun scripts/check-sync.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",
-    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:size",
+    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run generate:catalog && bun run check:catalog && bun run check:sync && bun run check:links && bun run check:templates && bun run check:markup && bun run test && bun run build:size",
     "prepublishOnly": "bun run build:all"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5",
-    "happy-dom": "^20.11"
+    "@biomejs/biome": "^2.5.12",
+    "happy-dom": "^20.14.0"
+  },
+  "dependencies": {
+    "@lekoala/floating": "^0.2.0"
   }
 }