actual-css 0.5.0 → 0.6.0

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/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/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

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";

package/docs/pages/utilities/spacing.md

@@ -4,25 +4,32 @@ Semantic step helpers for gap, padding, and margin — the most common inline-st
 
 ## Class reference
 
-| Class                       | Kind    | Description                                                   |
-|-----------------------------|---------|---------------------------------------------------------------|
-| `.gap-none`                 | Utility | `gap: 0` on the element itself.                               |
-| `.py`                       | Utility | Block (vertical) padding at the current density step.         |
-| `.px`                       | Utility | Inline (horizontal) padding at the current density step.      |
-| `.mbs`                      | Utility | Block-start margin at the current density step.               |
-| `.mbe`                      | Utility | Block-end margin at the current density step.                 |
-| `.gap-sm`                   | Utility | `gap: var(--space-20)` — denser row rhythm. Optional layer.   |
-| `.gap-md`                   | Utility | `gap: var(--space-40)` — default row rhythm. Optional layer.  |
-| `.gap-lg`                   | Utility | `gap: var(--space-50)` — roomier row rhythm. Optional layer.  |
-| `.padding-context`          | Utility | All-side padding at the current density step. Optional layer. |
-| `.gap-context`              | Utility | `gap: var(--gap)`. Optional layer.                            |
-| `.row-gap-context`          | Utility | `row-gap: var(--gap)`. Optional layer.                        |
-| `.column-gap-context`       | Utility | `column-gap: var(--gap)`. Optional layer.                     |
-| `.margin-inline-auto`       | Utility | Horizontally centers a block. Optional layer.                 |
-| `.margin-inline-start-auto` | Utility | Pushes a block toward the inline end. Optional layer.         |
-| `.margin-inline-end-auto`   | Utility | Pushes a block toward the inline start. Optional layer.       |
-| `.margin-block-start-auto`  | Utility | Pushes content toward the block end. Optional layer.          |
-| `.margin-block-end-auto`    | Utility | Pushes content toward the block start. Optional layer.        |
+Base utilities:
+
+| Class       | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| `.gap-none` | `gap: 0` on the element itself.                          |
+| `.py`       | Block (vertical) padding at the current density step.    |
+| `.px`       | Inline (horizontal) padding at the current density step. |
+| `.mbs`      | Block-start margin at the current density step.          |
+| `.mbe`      | Block-end margin at the current density step.            |
+
+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)`.                        |
+| `.column-gap-context`       | `column-gap: var(--gap)`.                     |
+| `.margin-inline-auto`       | Horizontally centers a block.                 |
+| `.margin-inline-start-auto` | Pushes a block toward the inline end.         |
+| `.margin-inline-end-auto`   | Pushes a block toward the inline start.       |
+| `.margin-block-start-auto`  | Pushes content toward the block end.          |
+| `.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)

package/docs/pages/utilities/text.md

@@ -5,7 +5,7 @@ Lightweight helpers for muted or secondary text without a full color scale.
 ## Class reference
 
 | Class           | Kind    | Description                                              |
-|-----------------|---------|----------------------------------------------------------|
+| --------------- | ------- | -------------------------------------------------------- |
 | `.muted`        | Utility | Secondary text color.                                    |
 | `.text-start`   | Utility | Logical start-aligned text; sets `--text-align`.         |
 | `.text-center`  | Utility | Centered text; sets `--text-align`.                      |

package/llms.txt

@@ -16,19 +16,37 @@ Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [m
 - `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/full` — the complete runtime with all built-in enhancers pre-registered.
-- `actual-css/reserved-classes.json` — machine-readable list of every class name the framework can generate. Use it to validate class usage in HTML (an "unknown class" checker) instead of guessing names from other frameworks.
+- `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.
 - 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:
+`actual-css/css/forms` is the native-control baseline; use
+`actual-css/css/forms/all` for the complete forms family.
+
 The composition guides in [README](README.md) and [Progressive Enhancements](docs/pages/enhancements/overview.md)
 show supported CSS modules and individual enhancer imports without duplicating
 the full export list here.
 
 Presentation (`class`) and behavior (`data-enhance`) are separate layers.
-Behaviour primitives (`enhance`, `floating`, `surface`, `keys`, `menu`, `focus`,
-`events`) are independently importable for building custom widgets.
-See [enhancement contract](docs/design-notes/enhancement-contract.md) and
+Behaviour primitives are independently importable for building custom widgets,
+including `enhance`, `surface`, `floating`, `focus-group`, `keys`, `input`,
+`command`, `menu`, `focus`, `escape`, and `events`. See
+[enhancement contract](docs/design-notes/enhancement-contract.md) and
 [widget primitives](docs/design-notes/widget-primitives.md).
 
+## Choosing a page shell
+
+Before choosing a content layout, choose the page shell:
+
+- Normal scrolling page, marketing/editorial site, or ordinary application page
+  → semantic landmarks; optionally `.app-shell` and `.navbar`.
+- Persistent topbar + independently scrolling main + adaptive bottom/side
+  primary navigation → `.app-layout`.
+
+Do not choose `.app-layout` merely because the product is an application. Its
+viewport-sized shell, internal scrolling, and adaptive navigation are one
+combined contract. See [layout choices](docs/pages/layout/choosing.md).
+
 ## Choosing a layout primitive
 
 Pick from the relationship between children, not the number of children in one mockup:
@@ -41,6 +59,11 @@ Pick from the relationship between children, not the number of children in one m
 - Explicit region placement on a shared 12-column canvas → `.column-layout`
 - Vertical flow → `.stack`; wrapping inline items → `.cluster`
 
+`.container-query` establishes the framework's shared
+`actual-container / inline-size` container for components that explicitly
+respond to allocated space; it is not a general prerequisite for responsive
+layouts.
+
 Use `--grid-columns` on `.grid` for exact track templates that do not match a
 built-in layout contract: arbitrary structural counts (seven calendar days),
 asymmetric fractional tracks, or mixed intrinsic/flexible tracks. See

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -115,6 +115,7 @@
     "build:docs": "bun run build:themes && bun scripts/build-docs.js",
     "watch:docs": "bun run build:themes && bun scripts/build-docs.js --watch",
     "check:docs": "bun scripts/check-docs.js",
+    "format:docs": "bun scripts/format-doc-tables.js",
     "check:doc-classes": "bun scripts/check-doc-classes.js",
     "check:compat": "bun scripts/check-compat.js",
     "check:css-api": "bun scripts/check-css-api.js",
@@ -136,7 +137,7 @@
     "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 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 check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:size",
     "prepublishOnly": "bun run build:all"
   },
   "devDependencies": {

package/scripts/reserved-classes.json

@@ -75,7 +75,6 @@
   "column-start-8",
   "column-start-9",
   "compact",
-  "complete",
   "container-query",
   "cursor-pointer",
   "danger",
@@ -243,7 +242,11 @@
   "stack",
   "start",
   "status-bar",
+  "step-complete",
+  "step-label",
   "steps",
+  "steps-horizontal",
+  "steps-vertical",
   "sticky",
   "stretch",
   "subtle",

package/src/css/components/fab.css

@@ -1,14 +1,17 @@
 /*
  * Fixed floating action placement and a native-details speed dial.
- * Button owns the action's size, shape, and intent; FAB only owns placement.
+ * Button owns the trigger's size, shape, and intent; FAB owns placement and
+ * the speed dial's structural open/close markers (--icon-plus / --icon-close).
  *
  * Public hooks:
  * --fab-offset
  * --fab-gap
+ * --fab-icon-size
  */
 .fab {
   --fab-offset: var(--space-40);
   --fab-gap: var(--space-20);
+  --fab-icon-size: 1.5rem;
 
   position: fixed;
   z-index: var(--z-menu);
@@ -17,6 +20,9 @@
 }
 
 .fab > summary {
+  /* Centers the toggle markers: the summary is the markers' positioned
+     context, not just the app-button class. */
+  position: relative;
   list-style: none;
   cursor: pointer;
 }
@@ -25,11 +31,35 @@
   display: none;
 }
 
-/* A lone decorative plus can communicate the open/close state without
-   requiring a second icon or JavaScript-managed content. */
-.fab > summary > [aria-hidden="true"]:only-child {
-  display: inline-block;
-  transition: transform var(--duration);
+/* The speed dial trigger is an icon-only toggle. FAB owns both structural
+   markers: masked pseudo-elements swap the shared plus (closed) and close
+   (open) glyphs at the same size, so the two states never drift apart. */
+.fab > summary::before,
+.fab > summary::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  inline-size: var(--fab-icon-size);
+  block-size: var(--fab-icon-size);
+  background: currentColor;
+  opacity: 0;
+  transform: scale(0.8);
+  transition:
+    opacity var(--duration),
+    transform var(--duration);
+}
+
+.fab > summary::before {
+  -webkit-mask: var(--icon-plus) center / contain no-repeat;
+  mask: var(--icon-plus) center / contain no-repeat;
+  opacity: 1;
+  transform: none;
+}
+
+.fab > summary::after {
+  -webkit-mask: var(--icon-close) center / contain no-repeat;
+  mask: var(--icon-close) center / contain no-repeat;
 }
 
 .fab-actions {
@@ -87,8 +117,14 @@
   transition-delay: 0s;
 }
 
-.fab[open] > summary > [aria-hidden="true"]:only-child {
-  transform: rotate(45deg);
+.fab[open] > summary::before {
+  opacity: 0;
+  transform: scale(0.8);
+}
+
+.fab[open] > summary::after {
+  opacity: 1;
+  transform: none;
 }
 
 @media print {

package/src/css/components/list.css

@@ -33,7 +33,9 @@
 .list > li > .list-item {
   display: grid;
   grid-template-columns: auto minmax(0, 1fr) auto;
-  align-items: center;
+  /* Regions align to the first line, so leading, title, and trailing controls
+     share one horizontal line while supporting text wraps beneath. */
+  align-items: start;
   gap: var(--list-item-gap);
   min-block-size: var(--list-item-min-size);
   padding-block: var(--list-item-pad-block);