actual-css 0.4.2 → 0.6.0

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

@@ -3,7 +3,7 @@
 > The optional JavaScript runtime that progressively enhances Actual's semantic markup — self-registering side-effect modules, the `enhance()` DOM lifecycle, stateless command routing, and the floating and surface contracts for custom widgets.
 
 Actual's JavaScript modules are optional. Importing `actual-css/js/full`
-registers the complete default runtime — every built-in enhancer, including
+registers the full runtime — every built-in enhancer, including
 validation and status. Importing `actual-css/js` registers only the enhancement
 manifest loader; importing a specific module registers only that behavior. The
 runtime does not require `DOMContentLoaded` or manual init calls, and it never
@@ -18,7 +18,7 @@ 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+     |
@@ -56,7 +56,7 @@ Modules are safe to import during SSR — registration is a no-op when there is
 DOM. The runtime remains active until the page unloads; there is no teardown
 handle, and cleanup happens per element when an element leaves the DOM.
 
-## The default runtime
+## The full runtime
 
 Loading `dist/actual.full.js` as a plain `<script>` (no `type="module"`, no
 bundler, no `import`) gets the full runtime. Static HTML that needs to trigger
@@ -74,22 +74,25 @@ example:
 </script>
 ```
 
-| Module                             | Behavior                                                                      |
-|------------------------------------|-------------------------------------------------------------------------------|
-| `actual-css/js/flyout`             | Trigger → panel surface: positioning, open/close, sheet mode (token `flyout`) |
-| `actual-css/js/context-menu`       | Context menus on `data-context-menu`                                          |
-| `actual-css/js/focus-group`        | Reusable roving-focus controller; no automatic discovery                      |
-| `actual-css/js/dialog`             | Native `<dialog>` behavior, focus management, dismissal                       |
-| `actual-css/js/dismiss`            | The generic `--dismiss` command                                               |
-| `actual-css/js/tab`                | Tab panels and arrow-key navigation (token `tabs`)                            |
-| `actual-css/js/tooltip`            | Tooltips on `data-tooltip`                                                    |
-| `actual-css/js/scrollspy`          | Scroll-driven nav highlighting (token `scrollspy`)                            |
-| `actual-css/js/filter`             | Input value filtering on `data-filter`                                        |
-| `actual-css/js/mask`               | Input masks on `data-mask`                                                    |
-| `actual-css/js/password`           | Password reveal toggle                                                        |
-| `actual-css/js/validation`         | Form validation (token `validation`)                                          |
-| `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`                        |
-| `actual-css/js/enhancement-loader` | Declared enhancement manifests (`data-enhance-modules`, `Enhance-Modules`)    |
+| Module                             | Behavior                                                    |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `actual-css/js/flyout`             | Trigger → panel positioning and open/close (token `flyout`) |
+| `actual-css/js/context-menu`       | Context menus on `data-context-menu`                        |
+| `actual-css/js/focus-group`        | Reusable roving-focus controller; no automatic discovery    |
+| `actual-css/js/dialog`             | Native `<dialog>` behavior, focus management, dismissal     |
+| `actual-css/js/dismiss`            | The generic `--dismiss` command                             |
+| `actual-css/js/tab`                | Tab panels and arrow-key navigation (token `tabs`)          |
+| `actual-css/js/tooltip`            | Tooltips on `data-tooltip`                                  |
+| `actual-css/js/scrollspy`          | Scroll-driven nav highlighting (token `scrollspy`)          |
+| `actual-css/js/filter`             | Input value filtering on `data-filter`                      |
+| `actual-css/js/mask`               | Input masks on `data-mask`                                  |
+| `actual-css/js/password`           | Password reveal toggle                                      |
+| `actual-css/js/validation`         | Form validation (token `validation`)                        |
+| `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`      |
+| `actual-css/js/enhancement-loader` | Declared enhancement manifests                              |
+
+The enhancement loader reads its manifests from `data-enhance-modules` or the
+`Enhance-Modules` header.
 
 Use `actual-css/js/full` for demos, playgrounds, and smoke tests where one import
 enables every built-in behavior. Production apps can import individual modules
@@ -125,7 +128,7 @@ 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                              |
@@ -155,14 +158,16 @@ const stop = autoUpdate(float, () => {
 
 Options passed to `reposition()`:
 
-| Option         | Default          | Contract                                                         |
-|----------------|------------------|------------------------------------------------------------------|
-| `placement`    | `"bottom-start"` | Preferred side and alignment (`-start` / `-end`)                 |
-| `distance`     | `0`              | Gap between the reference and the floating element               |
-| `flip`         | `true`           | Flip to the opposite side when the preferred side is out of view |
-| `shift`        | `true`           | Shift along the main axis to stay within the boundary            |
-| `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 main axis to stay in bounds |
+| `shiftPadding` | `4`              | Minimum space kept from the boundary        |
+| `scope`        | viewport         | Boundary element for overflow decisions     |
+
+`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
@@ -206,22 +211,33 @@ visible dismissable UI to the shared per-document Escape stack.
 widgets can veto or decorate opens, and context menus inject their own
 `source`/`restoreFocusTo` through it.
 
-| Option            | Default               | Contract                                                                                                                                                          |
-|-------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `trigger`         | —                     | Anchoring element; also the focus-restore target by default                                                                                                       |
-| `source`          | —                     | Alternate anchor when there is no trigger                                                                                                                         |
-| `x`, `y`          | —                     | Position at a fixed viewport point instead of an anchor (context menus)                                                                                           |
-| `placement`       | `"bottom-start"`      | Preferred placement                                                                                                                                               |
-| `distance`        | `4`                   | Gap between anchor and surface                                                                                                                                    |
-| `flip`            | `true`                | Flip when the preferred side is out of view                                                                                                                       |
-| `shift`           | `true`                | Shift to stay within the boundary                                                                                                                                 |
-| `shiftPadding`    | `4`                   | Minimum space kept from the boundary                                                                                                                              |
-| `scope`           | viewport              | Boundary element                                                                                                                                                  |
-| `mobile`          | `"auto"`              | `"auto"`, `"sheet"`, `"none"`, or `"anchored"` sheet behavior                                                                                                     |
-| `breakpoint`      | `768`                 | Max viewport width for an automatic sheet                                                                                                                         |
-| `autoClose`       | `"outside"`           | `"true"` closes for inside and outside clicks; `"inside"` and `"outside"` limit the side; `"false"` disables automatic click closing. Invalid values use `"true"` |
-| `dismissOnScroll` | `false`               | Close when scrolling outside the surface follows a new user input; opening/focus scroll is ignored                                                                |
-| `restoreFocusTo`  | `trigger` or `source` | Element focused on close                                                                                                                                          |
+| Option            | Default          | Contract                                    |
+| ----------------- | ---------------- | ------------------------------------------- |
+| `trigger`         | —                | Anchoring element, and focus-restore target |
+| `source`          | —                | Alternate anchor when there is no trigger   |
+| `x`, `y`          | —                | Position at a fixed viewport point          |
+| `placement`       | `"bottom-start"` | Preferred placement                         |
+| `distance`        | `4`              | Gap between anchor and surface              |
+| `flip`            | `true`           | Flip when the preferred side is hidden      |
+| `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
+closing; an invalid value reads as `"true"`.
+
+`dismissOnScroll` only fires when the scroll follows a new user input — the
+scroll that opening or focusing causes is ignored. `restoreFocusTo` falls back
+to `source` when there is no `trigger`.
 
 The click policy belongs to the surface rather than to a particular menu
 anatomy. The generic primitive defaults to outside-click dismissal; flyout and
@@ -242,14 +258,18 @@ The runtime dispatches a small set of public `actual:*` events. All are
 listenable on the document; cancelable events veto the associated action when
 `preventDefault()` is called.
 
-| Event                  | Dispatch                                   | Contract                                                                                       |
-|------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------|
-| `actual:surface-open`  | `openSurface()`, before a surface opens    | Cancelable. `detail: { surface, options }`                                                     |
-| `actual:context-menu`  | context-menu, before its menu opens        | Cancelable. `detail: { menu, context, origin, trigger }`                                       |
-| `actual:status`        | status module, or any code                 | Show or clear the status bar. `detail: { message, intent, duration }`; omit `message` to clear |
-| `actual:invalid`       | validation, after a submit was blocked     | `detail: { form, firstInvalid, message }`                                                      |
-| `actual:dialog-cancel` | dialog, before native cancel close         | Cancelable. `detail: { dialog, sourceEvent }`                                                  |
-| `actual:dismiss`       | `--dismiss` command, after hiding a target | `detail: { trigger }`                                                                          |
+| Event                  | Dispatch                       | `detail`                             |
+| ---------------------- | ------------------------------ | ------------------------------------ |
+| `actual:surface-open`  | before a surface opens         | `{ surface, options }`               |
+| `actual:context-menu`  | before a context menu opens    | `{ menu, context, origin, trigger }` |
+| `actual:status`        | status module, or any code     | `{ message, intent, duration }`      |
+| `actual:invalid`       | after a submit was blocked     | `{ form, firstInvalid, message }`    |
+| `actual:dialog-cancel` | before a native cancel close   | `{ dialog, sourceEvent }`            |
+| `actual:dismiss`       | after `--dismiss` hid a target | `{ trigger }`                        |
+
+`actual:surface-open`, `actual:context-menu` and `actual:dialog-cancel` are
+cancelable. `actual:status` both shows and clears the status bar — omit
+`message` to clear it.
 
 ## Extending the runtime
 
@@ -388,7 +408,8 @@ import { loadEnhancement, loadEnhancements, loadResponse } from "actual-css/js/e
 
 await loadEnhancements(); // every manifest block in the document
 await loadEnhancement("autosubmit", "/js/autosubmit.js");
-await loadResponse(fetch("/...").then((r) => r)); // Enhance-Modules header
+const response = await fetch("/...");
+await loadResponse(response); // Enhance-Modules header
 ```
 
 The `Enhance-Modules` HTTP header carries the same JSON object. Loaded modules
@@ -638,7 +659,7 @@ enhance({
 
 ## Form validation
 
-`actual-css/js/validation` is part of the default runtime and also importable on
+`actual-css/js/validation` is part of the full runtime and also importable on
 its own — it is an enhancer, not a validation framework. Forms opt in with the
 `data-enhance="validation"` token (`.needs-validation` is a presentation class
 for CSS-only `:user-invalid` feedback and does not by itself register the

package/docs/pages/guides/tailwind.md

@@ -205,7 +205,7 @@ Actual does not prohibit media queries. It simply does not encode every media qu
 ## Utility translation guide
 
 | Tailwind usage                       | Actual approach                                   |
-|--------------------------------------|---------------------------------------------------|
+| ------------------------------------ | ------------------------------------------------- |
 | `flex flex-col gap-*`                | `.stack`                                          |
 | `flex flex-wrap items-center gap-*`  | `.cluster`                                        |
 | `grid grid-cols-*`                   | `.grid`, `.grid-2`, `.grid-3`, etc.               |
@@ -407,7 +407,7 @@ Do not remove Tailwind from the build until migrated screens no longer depend on
 ## Where migration is genuinely harder
 
 | Existing Tailwind usage                            | Migration cost |
-|----------------------------------------------------|----------------|
+| -------------------------------------------------- | -------------- |
 | buttons, badges, alerts, forms                     | low            |
 | repeated card/panel patterns                       | low            |
 | basic flex/grid composition                        | low to medium  |

package/docs/pages/layout/app-shell.md

@@ -1,11 +1,11 @@
 # App Shell
 
-Full-height, single-column document flow. Despite its historical name, this is
-the general shell for ordinary pages as well as simple applications.
+Full-height, single-column document flow. Use it as the outer shell for ordinary pages,
+simple applications, and other layouts that need a header / main / footer structure spanning the viewport.
 
 Header and footer are document landmarks, not required layout classes.
-Use semantic elements by default. `.app-shell` already supplies the outer
-column, so do not add a `.stack` solely to arrange the page landmarks.
+Use semantic elements by default. .app-shell already supplies the outer column,
+so do not add a .stack solely to arrange the page landmarks.
 
 ```html demo
 <body class="app-shell">

package/docs/pages/layout/choosing.md

@@ -5,10 +5,14 @@ number of children visible in one mockup.
 
 ## Page and application shells
 
-| Situation | Recipe |
-|---|---|
-| Public, marketing, editorial, or normally scrolling page | Semantic landmarks; optionally `.app-shell`, with `.navbar` for site navigation |
-| Persistent topbar + independently scrolling main + bottom-to-side primary navigation | `.app-layout` with its exact direct-child contract |
+| Situation                              | Recipe                                      |
+| -------------------------------------- | ------------------------------------------- |
+| A normally scrolling page              | Semantic landmarks, optionally `.app-shell` |
+| Topbar + scrolling main + adaptive nav | `.app-layout`                               |
+
+The first covers public, marketing and editorial pages; add `.navbar` for site
+navigation. The second is `.app-layout` with its exact direct-child contract,
+where the primary navigation moves from bottom to side.
 
 Do not choose `.app-layout` from the word "app" or from the presence of a
 header. Its viewport-sized grid, hidden shell overflow, internal main scroll,
@@ -19,11 +23,11 @@ below.
 ## Content relationships
 
 | Situation                                                    | Primitive         |
-|--------------------------------------------------------------|-------------------|
+| ------------------------------------------------------------ | ----------------- |
 | Vertical flow                                                | `.stack`          |
 | Inline actions, tags, or navigation that may wrap            | `.cluster`        |
 | Responsive collection; an incomplete final row is acceptable | `.grid`           |
-| Known structural density, at most N columns                 | `.grid-N`         |
+| Known structural density, at most N columns                  | `.grid-N`         |
 | Peer regions that must switch together                       | `.switcher`       |
 | Main content followed by a secondary region                  | `.sidebar-layout` |
 | Fixed media followed by flexible content                     | `.media`          |

package/docs/pages/layout/grid.md

@@ -12,7 +12,7 @@ column count.
 `.grid` fits as many columns as the available inline space permits. Incomplete
 final rows are part of the contract.
 
-```html demo
+```html demo resize
 <section class="grid">
   <article class="card"><h3>Starter</h3><p>For small projects.</p></article>
   <article class="card"><h3>Team</h3><p>For shared products.</p></article>
@@ -34,7 +34,7 @@ Tune the item minimum with `--grid-min`.
 own: it never exceeds N columns, never overflows, and every item keeps the same
 width.
 
-```html demo bare
+```html demo resize
 <div class="grid-4">
   <div class="card">Exercitation</div>
   <div class="card">Amet mollit</div>
@@ -47,7 +47,7 @@ width.
 density is `.grid-N`'s. Choose the preset that suits your item size:
 
 | Item                              | Preset               |
-|-----------------------------------|----------------------|
+| --------------------------------- | -------------------- |
 | large card                        | `.grid-2`            |
 | card with a heading and a summary | `.grid-3`, `.grid-4` |
 | compact tile, stat, avatar        | `.grid-6`            |
@@ -56,9 +56,9 @@ density is `.grid-N`'s. Choose the preset that suits your item size:
 
 Left alone, a preset collapses one column at a time, so a six-item `.grid-6`
 can pass through five columns — five items and a lone sixth. The example above
-is that bare version. Placed inside a container named **`actual-grid`** — the
+is that bare version. Placed inside a container named **`actual-container`** — the
 `.container-query` helper, or a region of your own that declares
-`container: actual-grid / inline-size` — it only ever enters a **divisor of N**:
+`container: actual-container / inline-size` — it only ever enters a **divisor of N**:
 
 ```text
 .grid-2   2 → 1
@@ -69,7 +69,7 @@ is that bare version. Placed inside a container named **`actual-grid`** — the
 
 Every state splits the collection evenly, and all items keep the same width.
 
-```html demo
+```html demo resize
 <div class="container-query">
   <div class="grid-6">
     <div class="card">1</div>
@@ -89,7 +89,7 @@ not the grid's own width. Padding and borders on the container come off before
 the query resolves.
 
 | Container content box | `.grid-2` | `.grid-3` | `.grid-4` | `.grid-6` |
-|-----------------------|-----------|-----------|-----------|-----------|
+| --------------------- | --------- | --------- | --------- | --------- |
 | under `28rem`         | 1         | 1         | 1         | 1         |
 | `28rem` to `48rem`    | 2         | 1         | 2         | 2         |
 | `48rem` to `64rem`    | 2         | 3         | 2         | 3         |
@@ -113,9 +113,10 @@ change cannot drop the region a state.
 
 Balanced subdivision is precision, never a prerequisite for responsive
 behavior — forgetting the container costs you the exact chain, nothing else.
-The grid responds only to a container named `actual-grid`, never to an
-incidental query container, so a region that sets `container-type: inline-size`
-for its own reasons leaves the grid untouched. The container has to be an
+`actual-container` is the framework's shared name for size-aware components,
+so one region can serve a grid and a step flow at once. The grid responds only
+to that name, never to an incidental query container, so a region that sets
+`container-type: inline-size` for its own reasons leaves the grid untouched. The container has to be an
 ancestor: an element cannot query its own size without taking inline-size
 containment, which would collapse the grid inside a `.cluster`, a float, or any
 shrink-to-fit box. Put it on a normal block-level wrapper for the same reason.

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

@@ -6,6 +6,8 @@ Horizontal rails that stay useful without JavaScript and snap in modern browsers
 
 Use `.scroll-snap` for a niche row of items that should scroll horizontally, such as card rails, media strips, overflow tabs, or a simple touch-friendly carousel baseline. Scrolling only appears when the items are wider than the container; set `--scroll-snap-item-size` for card rails.
 
+**Related terms:** carousel, card carousel, horizontal scroller, media rail, scrolling rail.
+
 ```html demo
 <section class="stack" aria-labelledby="featured-title">
   <h2 id="featured-title">Featured articles</h2>

package/docs/pages/layout/sidebar-layout.md

@@ -5,6 +5,8 @@ switches intrinsically according to its own available width: the regions sit
 side by side when the main minimum, preferred aside width, and gap fit; they
 otherwise stack. No `.container-query` ancestor is required.
 
+**Related terms:** master-detail, split view.
+
 ```html demo
 <div class="sidebar-layout">
   <article class="stack">

package/docs/pages/layout/stack.md

@@ -44,12 +44,16 @@ not as the wrapper that lays out independent full-width regions of a page.
 `--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:
 
-| Markup | Gap | Use for |
-|--------------------|------|--------------------------------------------------------|
-| `.stack gap-none` | 0 | Lines that form one typographic unit — a name and a job title, a figure and its caption. |
-| `.stack sm` | 8px | A homogeneous series of distinct controls — a radio list, a checkbox list, a compact vertical menu. |
-| `.stack` | 12px | Normal flow between distinct elements. |
-| `.stack lg` | 24px | Sections, or blocks that should read as separated. |
+| Markup            | Gap  | Use for                                    |
+| ----------------- | ---- | ------------------------------------------ |
+| `.stack gap-none` | 0    | Lines forming one typographic unit         |
+| `.stack sm`       | 8px  | A homogeneous series of controls           |
+| `.stack`          | 12px | Normal flow between distinct elements      |
+| `.stack lg`       | 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
+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

package/docs/pages/layout/topbar.md

@@ -21,3 +21,5 @@ Use `.topbar` for the structural shell of an app-shell header: sticky positionin
 ```
 
 This is for the app-shell topbar specifically — a structural need that recurs unchanged across app UIs regardless of brand. It is not for marketing or editorial site headers, which are one-off visual identity per page.
+
+**Related terms:** sticky header, app bar, application header.

package/docs/pages/patterns/structured-lists.md

@@ -3,13 +3,13 @@
 Choose list markup from the content semantics, then add only the layout or
 component contract the collection needs.
 
-| Need | Use |
-| --- | --- |
-| Bullets or order carry meaning | Native `<ul>` or `<ol>` |
-| One leading element and one flexible content region | [`.media`](../layout/media.md) |
-| Repeated application rows with leading, content, and trailing regions | [`.list`](../components/list.md) |
-| A list of navigation links | [`.nav-list`](./navigation-list.md) |
-| A richer collection with its own item structure | Native list plus layout primitives and components |
+| Need                                            | Use                                 |
+| ----------------------------------------------- | ----------------------------------- |
+| Bullets or order carry meaning                  | Native `<ul>` or `<ol>`             |
+| Leading element plus flexible content           | [`.media`](../layout/media.md)      |
+| Repeated rows: leading, content, trailing       | [`.list`](../components/list.md)    |
+| A list of navigation links                      | [`.nav-list`](./navigation-list.md) |
+| A richer collection with its own item structure | Native list plus primitives         |
 
 `.media` and `.list` are not interchangeable. `.media` is geometry for one
 two-part composition and requires exactly two direct children. `.list` owns the

package/docs/pages/utilities/accessibility.md

@@ -5,7 +5,7 @@ Text hidden visually but still available to assistive technology.
 ## Class reference
 
 | Class      | Kind    | Description                                                     |
-|------------|---------|-----------------------------------------------------------------|
+| ---------- | ------- | --------------------------------------------------------------- |
 | `.sr-only` | Utility | Visually hides text while keeping it in the accessibility tree. |
 
 ## Screen reader only
@@ -32,3 +32,21 @@ Use `.sr-only` for text that should be available to assistive technology but vis
   border: 0;
 }
 ```
+
+## Touch targets
+
+`.touch-target` adds 8px of invisible hit area around a small control on coarse
+primary pointers, without growing the visual. Apply it opt-in to targets that
+are genuinely small — icon buttons, close buttons, compact actions.
+
+```html demo
+<button class="btn icon-only touch-target" type="button" aria-label="Close">
+  <i class="ti ti-x" aria-hidden="true"></i>
+</button>
+```
+
+**Related terms:** touch target, hit area, tap target, target size.
+
+On fine pointers the class is fully neutral. On coarse pointers it establishes
+a relative positioning context — do not apply it to controls whose positioning
+is structural (`fixed`, `absolute`, `sticky`).

package/docs/pages/utilities/flex.md

@@ -4,19 +4,26 @@ Small flex helpers for grow behavior and other one-line needs.
 
 ## Class reference
 
-| Class                            | Kind    | Description                                                               |
-|----------------------------------|---------|---------------------------------------------------------------------------|
-| `.grow`                          | Utility | Makes an item take available flex space without overflowing.              |
-| `.items-start`                   | Utility | Aligns children to the block-start edge; sets `--items-align`.            |
-| `.items-center`                  | Utility | Centers children on the cross axis; sets `--items-align`.                 |
-| `.items-end`                     | Utility | Aligns children to the block-end edge; sets `--items-align`.              |
-| `.dot`                           | Utility | Inline separator dot for metadata rows.                                   |
-| `.justify-content-start`         | Utility | `justify-content: flex-start` and `--cluster-justify`. Optional layer.    |
-| `.justify-content-center`        | Utility | `justify-content: center` and `--cluster-justify`. Optional layer.        |
-| `.justify-content-end`           | Utility | `justify-content: flex-end` and `--cluster-justify`. Optional layer.      |
-| `.justify-content-space-between` | Utility | `justify-content: space-between` and `--cluster-justify`. Optional layer. |
-| `.flex-wrap`                     | Utility | `flex-wrap: wrap` on any flex container. Optional layer.                  |
-| `.flex-nowrap`                   | Utility | `flex-wrap: nowrap` on any flex container. Optional layer.                |
+Base utilities:
+
+| Class           | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `.grow`         | Makes an item take available flex space without overflowing.   |
+| `.items-start`  | Aligns children to the block-start edge; sets `--items-align`. |
+| `.items-center` | Centers children on the cross axis; sets `--items-align`.      |
+| `.items-end`    | Aligns children to the block-end edge; sets `--items-align`.   |
+| `.dot`          | Inline separator dot for metadata rows.                        |
+
+Extra utilities:
+
+| Class                            | Description                                               |
+| -------------------------------- | --------------------------------------------------------- |
+| `.justify-content-start`         | `justify-content: flex-start` and `--cluster-justify`.    |
+| `.justify-content-center`        | `justify-content: center` and `--cluster-justify`.        |
+| `.justify-content-end`           | `justify-content: flex-end` and `--cluster-justify`.      |
+| `.justify-content-space-between` | `justify-content: space-between` and `--cluster-justify`. |
+| `.flex-wrap`                     | `flex-wrap: wrap` on any flex container.                  |
+| `.flex-nowrap`                   | `flex-wrap: nowrap` on any flex container.                |
 
 ## Grow
 

package/docs/pages/utilities/links.md

@@ -5,7 +5,7 @@ Link styling for chrome that is conceptually a link but should not look like pro
 ## Class reference
 
 | Class         | Kind    | Description                                               |
-|---------------|---------|-----------------------------------------------------------|
+| ------------- | ------- | --------------------------------------------------------- |
 | `.link-plain` | Utility | Removes the underline and inherits the surrounding color. |
 | `.link-muted` | Utility | Muted link that shifts to the full text color on hover.   |
 

package/docs/pages/utilities/list.md

@@ -5,7 +5,7 @@ Utilities for list chrome reset, readable measure, and editorial kicker labels.
 ## Class reference
 
 | Class         | Kind      | Description                                                   |
-|---------------|-----------|---------------------------------------------------------------|
+| ------------- | --------- | ------------------------------------------------------------- |
 | `.list-reset` | Utility   | Removes native list margin, padding, and markers.             |
 | `.measure`    | Utility   | Caps a block at a readable width via `--measure`.             |
 | `.overline`   | Component | Small editorial kicker label: muted, uppercase, letterspaced. |

package/docs/pages/utilities/overflow.md

@@ -4,13 +4,20 @@ Explicit overflow handling for content that may exceed its container.
 
 ## Class reference
 
-| Class              | Kind    | Description                                                           |
-|--------------------|---------|-----------------------------------------------------------------------|
-| `.overflow-auto`   | Utility | Enables scrolling when content exceeds the container.                 |
-| `.overflow-hidden` | Utility | Clips overflowing content. Optional layer.                            |
-| `.overflow-clip`   | Utility | Clips overflowing content without a scroll container. Optional layer. |
-| `.overflow-x-auto` | Utility | Horizontal scrolling only. Optional layer.                            |
-| `.overflow-y-auto` | Utility | Vertical scrolling only. Optional layer.                              |
+Base utilities:
+
+| Class            | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `.overflow-auto` | Enables scrolling when content exceeds the container. |
+
+Extra utilities:
+
+| Class              | Description                                           |
+| ------------------ | ----------------------------------------------------- |
+| `.overflow-hidden` | Clips overflowing content.                            |
+| `.overflow-clip`   | Clips overflowing content without a scroll container. |
+| `.overflow-x-auto` | Horizontal scrolling only.                            |
+| `.overflow-y-auto` | Vertical scrolling only.                              |
 
 Use `.overflow-auto` when content may overflow its container, especially tables and code-like regions.
 

package/docs/pages/utilities/overview.md

@@ -7,6 +7,28 @@ Utilities are a small escape hatch for common single-purpose needs. They should
 - Keep utility names stable, boring, and few.
 - Utilities should use logical properties where relevant.
 
+## Two layers
+
+Utilities ship in two modules, and the split is about **naming and curation**,
+not about opting in. Importing `actual-css/css/utilities` — or
+`actual.full.css` — gives you both.
+
+| Module    | Import                           | Naming                             |
+| --------- | -------------------------------- | ---------------------------------- |
+| **Base**  | `actual-css/css/utilities/base`  | Compact names, frequent operations |
+| **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`,
+`.overflow-x-auto`, `.justify-content-center` — and never gives a base utility
+a second spelling.
+
+Reach for base first. Extra exists so an explicit one-off does not have to
+become a new short name, which is the pressure that grows a utility surface.
+
+Extra utilities are concentrated in flex, overflow and spacing; those pages
+list the two layers as separate tables. Every other utility page is base only.
+
 ## Non-Goals
 
 > Utilities deliberately excluded to keep the surface small and intentional.

package/docs/pages/utilities/shape.md

@@ -5,7 +5,7 @@ Rare shape utilities for cases that must be perfectly round or square.
 ## Class reference
 
 | Class     | Kind    | Description                                         |
-|-----------|---------|-----------------------------------------------------|
+| --------- | ------- | --------------------------------------------------- |
 | `.circle` | Utility | Forces a perfectly round shape via `--radius-full`. |
 
 Shape utilities should be rare because shape is mostly theme-level.

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

@@ -4,13 +4,13 @@ Small layout corrections for controls, labels, and compact rails.
 
 ## Class reference
 
-| Class                     | Kind    | Description                                                               |
-|---------------------------|---------|---------------------------------------------------------------------------|
-| `.fit`                    | Utility | Shrinks a control or element to its content width.                        |
-| `.text-nowrap`            | Utility | Keeps text on one line.                                                   |
-| `.truncate`               | Utility | Ellipsizes overflowing single-line text.                                  |
-| `.scroller`               | Utility | Theme-aware scrollbar density and colour for scroll containers. Optional layer. |
-| `.scroller.stable-gutter` | Variant | Reserves scrollbar gutter space so layout does not shift. Optional layer. |
+| Class                     | Kind    | Description                               |
+| ------------------------- | ------- | ----------------------------------------- |
+| `.fit`                    | Utility | Shrinks an element to its content width.  |
+| `.text-nowrap`            | Utility | Keeps text on one line.                   |
+| `.truncate`               | Utility | Ellipsizes overflowing single-line text.  |
+| `.scroller`               | Layout  | Theme-aware scrollbar density and colour. |
+| `.scroller.stable-gutter` | Variant | Reserves inline-axis scrollbar gutter.    |
 
 Use `.fit` when a control or element should shrink to its content instead of filling the available inline space.
 
@@ -78,7 +78,9 @@ above the capability floor. An engine that knows neither ignores both
 declarations and draws its native scrollbar — the intended fallback, not a
 broken state.
 
-`scroller` is not imported by `actual.css`. Import it explicitly when a project wants Actual CSS scrollbar chrome instead of the native OS default:
+`.scroller` is a layout primitive, so it comes with `actual.full.css` and with
+`actual-css/css/layout` like `.stack` or `.cluster`. A project importing module
+by module reaches it directly:
 
 ```css
 @import "actual-css/css/layout/scroller";