actual-css 0.3.1 → 0.4.1

package/docs/design-notes/naming.md

@@ -37,3 +37,18 @@ Actual CSS is intended for new projects. Existing projects with class collisions
 - Shared runtime primitives may have public JavaScript APIs without becoming author-facing CSS or HTML vocabulary. Do not introduce `.surface` or `data-surface-*`; components keep their feature-specific author APIs (`data-flyout-*`, `data-context-menu-*`, CSS `.flyout`, `.menu`, …).
 - `data-enhance` is the one un-namespaced attribute — it carries *opt-in* for any feature, not *configuration* for one feature. Feature-namespaced attributes carry configuration.
 - Custom events use the `actual:*` namespace.
+
+## Utilities
+
+Utilities ship in two layers that follow the same class grammar.
+
+- **Base utilities** are a curated set of common ergonomic shortcuts
+  (`.overflow-auto`, `.gap-none`, `.text-nowrap`, `.px`, `.py`).
+- **Optional utilities** use explicit property/value names
+  (`.overflow-hidden`, `.gap-sm`, `.white-space-normal`).
+
+Base utilities may use compact names for a small set of frequent operations
+(`.px`, `.py`, `.mbs`, `.mbe`). Extra utilities use explicit property/value
+names and must not duplicate an operation already provided by base. The two
+sets may cover the same CSS property, but must not expose competing names for
+the same declaration.

package/docs/design-notes/references.md

@@ -221,7 +221,7 @@ Prior Actual CSS libraries:
 - https://smolcss.dev/#smol-container
 - https://every-layout.dev/layouts/center/
 
-### Layout: List
+### Component: List
 
 - https://daisyui.com/components/list/
 - https://html.spec.whatwg.org/multipage/grouping-content.html#the-li-element

package/docs/design-notes/widget-primitives.md

@@ -7,6 +7,7 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 | Need | Primitive | Import |
 |------|-----------|--------|
 | Opt-in discovery + lifecycle + cleanup | `enhance`, `registerEnhancement` | `actual-css/js/enhance` |
+| Per-document LIFO Escape dismissal | `escape` (`registerEscapeDismissal`) | `actual-css/js/escape` |
 | Positioning, flip/shift, `--available-height`, `data-placement` | `floating` (`track`, `reposition`, `repositionAt`) | `actual-css/js/floating` |
 | Open/close, sheet on mobile, backdrop, outside-click, Escape, focus restore | `surface` | `actual-css/js/surface` |
 | Directional item lookup, edges, wrapping, RTL | `keys` (`itemForKey`, `firstItem`, `lastItem`, `nextItem`) | `actual-css/js/keys` |

package/docs/navigation.json

@@ -5,7 +5,8 @@
       "slug": "guides",
       "pages": [
         "introduction",
-        "optional-components",
+        "integrating-actual-css",
+        "modular-import",
         "progressive-enhancement",
         "bootstrap",
         "tailwind"
@@ -21,18 +22,21 @@
       "slug": "layout",
       "pages": [
         "overview",
+        "choosing",
         "stack",
         "cluster",
         "grid",
+        "column-layout",
         "center",
         "sidebar-layout",
         "media",
         "switcher",
         "topbar",
         "scroll-snap",
+        "scroll-target",
         "frame",
         "app-shell",
-        "list"
+        "app-layout"
       ]
     },
     {
@@ -41,6 +45,7 @@
       "pages": [
         "accordion",
         "alert",
+        "app-navigation",
         "aura",
         "avatar",
         "badge",
@@ -51,13 +56,17 @@
         "dialog",
         "drawer",
         "fab",
+        "indicator",
         "key",
+        "list",
         "meter",
         "navbar",
         "pagination",
         "progress",
+        "rating",
         "skeleton",
         "spinner",
+        "steps",
         "table"
       ]
     },
@@ -91,6 +100,7 @@
         "actions",
         "navigation-list",
         "icon-input",
+        "icon-slot",
         "structured-lists",
         "hierarchical-nav",
         "code-block",

package/docs/pages/components/alert.md

@@ -14,20 +14,25 @@
 - Use `.sm` or `.lg` for density changes. The inline padding stays stable.
 - Use `.alert-dismiss` for a compact dismiss button. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions. It uses the shared `--icon-close` mask and the `--dismiss` runtime command — no icon font or custom JS.
 
+Because alerts are soft by default, adding `.soft` to an intent (`.alert.soft.primary`,
+`.alert.soft.danger`, …) is a no-op: it already resolves to a soft version of that
+intent. Reach for `.solid` (stronger) or `.outline` (quieter) when the emphasis
+itself needs to change, not `.soft`.
+
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.alert` | Component | Inline status surface; soft by default. |
-| `.alert-icon` | Composition | Decorative leading icon; pins to the first grid column. |
-| `.alert-dismiss` | Modifier | Compact dismiss button using the `--icon-close` mask and the `--dismiss` command. |
-| `.callout` | Variant | Neutral panel with a thick accent border on the leading edge. |
-| `.admonition` | Variant | Structured box with a tinted title bar and body on the page surface. |
-| `.alert-title` | Composition | Admonition title bar; hosts the dismiss button. |
-| `.alert-body` | Composition | Admonition body resting on the page surface. |
-| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
-| Shared variants | Variant | `.solid` and `.outline` emphasis. |
-| `.sm` / `.lg` | Size | Density; inline padding stays stable. |
+| Class            | Kind        | Description                                                                       |
+|------------------|-------------|-----------------------------------------------------------------------------------|
+| `.alert`         | Component   | Inline status surface; soft by default.                                           |
+| `.alert-icon`    | Composition | Decorative leading icon; pins to the first grid column.                           |
+| `.alert-dismiss` | Modifier    | Compact dismiss button using the `--icon-close` mask and the `--dismiss` command. |
+| `.callout`       | Variant     | Neutral panel with a thick accent border on the leading edge.                     |
+| `.admonition`    | Variant     | Structured box with a tinted title bar and body on the page surface.              |
+| `.alert-title`   | Composition | Admonition title bar; hosts the dismiss button.                                   |
+| `.alert-body`    | Composition | Admonition body resting on the page surface.                                      |
+| Shared intents   | Intent      | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`.                      |
+| Shared variants  | Variant     | `.solid` and `.outline` emphasis.                                                 |
+| `.sm` / `.lg`    | Size        | Density; inline padding stays stable.                                             |
 
 ## Basic usage
 
@@ -70,8 +75,10 @@
   <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
 
   <div class="stack">
-    <strong>Payment failed.</strong>
-    <p>Check your billing details or try another card.</p>
+    <div class="stack" style="--gap: var(--space-10)">
+      <strong>Payment failed.</strong>
+      <p>Check your billing details or try another card.</p>
+    </div>
 
     <menu class="actions cluster">
       <li><a class="btn danger sm" href="/billing">Update billing</a></li>

package/docs/pages/components/app-navigation.md

@@ -0,0 +1,34 @@
+# App Navigation
+
+> Primary application destinations in a persistent bottom bar or labelled side navigation.
+
+Use one `.app-nav` landmark for the application's primary destinations. Links
+remain links, and `aria-current="page"` is the only current-page state.
+
+```html demo
+<nav class="app-nav" aria-label="Primary">
+  <a href="#today" aria-current="page">
+    <span aria-hidden="true">☀</span>
+    <span>Today</span>
+  </a>
+  <a href="#tasks">
+    <span aria-hidden="true">✓</span>
+    <span>Tasks</span>
+  </a>
+  <a href="#settings">
+    <span aria-hidden="true">⚙</span>
+    <span>Settings</span>
+  </a>
+</nav>
+```
+
+On its own, `.app-nav` is a sticky bottom bar. Compose it as a direct child of
+`.app-layout` to let the layout turn the same landmark into side navigation when space
+permits. The component contains no JavaScript and does not manage routing.
+The icon slot accepts SVGs, images, and decorative elements such as icon-font
+`i` elements marked with `aria-hidden="true"`.
+
+### Hooks
+
+- `--app-nav-size` controls the minimum bottom-bar size.
+- `--app-nav-gap` controls spacing between destinations.

package/docs/pages/components/aura.md

@@ -1,6 +1,6 @@
 # Aura
 
-> **Optional** — import `actual-css/css/optional/aura` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/effects/aura` or `actual-css/css/effects`.
 
 Aura adds a decorative intent-colored border and halo around one direct child.
 It is visual emphasis only and does not change the child's semantics.

package/docs/pages/components/avatar.md

@@ -12,12 +12,12 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.avatar` | Component | Initials or image in a circular box; works on `div`, `a`, and `button`. |
-| `.avatar-stack` | Composition | Overlapping avatar group. |
-| `.badge:empty` (inside `.avatar`) | Composition | Status dot at the bottom-end corner; give it an `aria-label`. |
-| `.sm` / `.lg` | Size | Density; also rescales the whole `.avatar-stack`. |
+| Class                             | Kind        | Description                                                             |
+|-----------------------------------|-------------|-------------------------------------------------------------------------|
+| `.avatar`                         | Component   | Initials or image in a circular box; works on `div`, `a`, and `button`. |
+| `.avatar-stack`                   | Composition | Overlapping avatar group.                                               |
+| `.badge:empty` (inside `.avatar`) | Composition | Status dot at the bottom-end corner; give it an `aria-label`.           |
+| `.sm` / `.lg`                     | Size        | Density; also rescales the whole `.avatar-stack`.                       |
 
 ## Basic usage
 
@@ -41,6 +41,16 @@
 The avatar keeps the same visual box across semantics — as a link or button it
 gains hover and pressed feedback.
 
+For an accessible initials label, prefer `<abbr title="Full name">` so the
+expansion is available to assistive tech; the UA dotted underline it would draw
+is suppressed inside the avatar.
+
+```html demo
+<div class="avatar" role="img">
+  <abbr title="Ada Meridian">AM</abbr>
+</div>
+```
+
 ```html demo
 <a href="#" class="avatar">
   <img src="https://mockmind-api.uifaces.co/content/human/219.jpg" alt="Jane Doe" />

package/docs/pages/components/badge.md

@@ -18,13 +18,13 @@ full-width badge is intentional.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.badge` | Component | Compact label; soft by default. |
-| `.badge:empty` | Composition | Truly-empty badge renders as a solid dot. |
-| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
-| Shared variants | Variant | `.solid` (filled) and `.outline` (bordered) emphasis. |
-| `.sm` / `.lg` | Size | Compact density. |
+| Class           | Kind        | Description                                                  |
+|-----------------|-------------|--------------------------------------------------------------|
+| `.badge`        | Component   | Compact label; soft by default.                              |
+| `.badge:empty`  | Composition | Truly-empty badge renders as a solid dot.                    |
+| Shared intents  | Intent      | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
+| Shared variants | Variant     | `.solid` (filled) and `.outline` (bordered) emphasis.        |
+| `.sm` / `.lg`   | Size        | Compact density.                                             |
 
 ## Basic usage
 
@@ -77,6 +77,8 @@ The dot conveys no text, so an `aria-label` is required for it to mean anything.
 ## Removable tag pattern
 
 Use `.badge soft` for tag visuals. Add a direct dismiss button only when the tag can actually be removed. There is no separate chip component.
+For a compact action or filter, use `.btn.sm` instead; badges describe content
+and must not be turned into toggle controls merely to obtain a compact shape.
 
 ```html demo
 <span class="badge primary soft">

package/docs/pages/components/button.md

@@ -4,22 +4,22 @@ Actions and navigation with shared intents, variants, sizes, and loading, presse
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.btn` | Component | Base button. Solid by default; works on `<button>`, `<a href>`, and button-like `<input>`. |
-| `.primary` | Intent | Primary action. |
-| `.secondary` | Intent | Secondary action. |
-| `.success` | Intent | Positive outcome. |
-| `.warning` | Intent | Caution. |
-| `.danger` | Intent | Destructive action. |
-| `.neutral` | Intent | Neutral tone (the `.btn` default). |
-| `.soft` | Variant | Muted intent-tinted surface. |
-| `.outline` | Variant | Transparent with an intent-colored border. |
-| `.solid` | Variant | Filled intent background — the `.btn` default. |
-| `.ghost` | Variant | Borderless text button (button-only). |
-| `.link` | Variant | Underlined text button (button-only). |
-| `.sm` / `.lg` | Size | Compact or large control height. |
-| `.icon-only` | Variant | Square icon button sized to the control height. |
+| Class         | Kind      | Description                                                                                |
+|---------------|-----------|--------------------------------------------------------------------------------------------|
+| `.btn`        | Component | Base button. Solid by default; works on `<button>`, `<a href>`, and button-like `<input>`. |
+| `.primary`    | Intent    | Primary action.                                                                            |
+| `.secondary`  | Intent    | Secondary action.                                                                          |
+| `.success`    | Intent    | Positive outcome.                                                                          |
+| `.warning`    | Intent    | Caution.                                                                                   |
+| `.danger`     | Intent    | Destructive action.                                                                        |
+| `.neutral`    | Intent    | Neutral tone (the `.btn` default).                                                         |
+| `.soft`       | Variant   | Muted intent-tinted surface.                                                               |
+| `.outline`    | Variant   | Transparent with an intent-colored border.                                                 |
+| `.solid`      | Variant   | Filled intent background — the `.btn` default.                                             |
+| `.ghost`      | Variant   | Borderless text button (button-only).                                                      |
+| `.link`       | Variant   | Underlined text button (button-only).                                                      |
+| `.sm` / `.lg` | Size      | Compact or large control height.                                                           |
+| `.icon-only`  | Variant   | Square icon button sized to the control height.                                            |
 
 ## Basic usage
 
@@ -61,6 +61,18 @@ foreground by default, including on a contrasting `.inverted` surface. A local
 intent class still wins: `.danger.outline` uses the danger color in either
 context. Filled buttons own their surface and keep their normal intent recipe.
 
+`.btn.link` is a link-style action: it keeps button behavior and states, but
+remains intrinsically sized like text instead of stretching with its layout
+container. For a plain text link, use a bare `<a>` with no class.
+
+```html demo
+<div class="cluster">
+  <a href="#">Normal link</a>
+  <a class="btn link" href="#">Button-like link</a>
+  <button class="btn link" type="button">Button with link appearance</button>
+</div>
+```
+
 ```html demo
 <div class="cluster">
   <button class="btn outline" type="button">Outline</button>
@@ -117,6 +129,24 @@ change typography.
 
 ## States
 
+### Compact filters and actions
+
+A compact filter is still a button, not a separate chip semantic. Compose the
+small size with `aria-pressed`; application code owns the state change.
+
+```html demo
+<div class="cluster" aria-label="Task filters">
+  <button class="btn sm" type="button" aria-pressed="true">All</button>
+  <button class="btn sm outline" type="button" aria-pressed="false">Open</button>
+  <button class="btn sm outline" type="button" aria-pressed="false">Done</button>
+</div>
+```
+
+Use `.badge` for a passive category or count and the removable-tag composition
+when a displayed value needs its own remove action. Actual intentionally has no
+generic `.chip` component: action, selection, and information retain their HTML
+semantics.
+
 ### Disabled
 
 Disable a `<button>` or `<input>` with the native `disabled` attribute. Anchors

package/docs/pages/components/card.md

@@ -4,19 +4,24 @@ Flexible content container with optional header, body, and footer regions, plus
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.card` | Component | Neutral raised surface for grouped content. |
-| `.raised` | Variant | Elevated surface with a soft shadow. |
-| `.subtle` | Variant | Lower contrast against the page surface. |
+| Class       | Kind             | Description                                                                                                                                                                                                     |
+|-------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.card`     | Component        | Neutral raised surface for grouped content.                                                                                                                                                                     |
+| `.raised`   | Variant          | Elevated surface with a soft shadow.                                                                                                                                                                            |
+| `.subtle`   | Variant          | Lower contrast against the page surface.                                                                                                                                                                        |
 | `.inverted` | Surface modifier | Inverse surface treatment: paints `--surface-solid` and swaps the foreground to `--surface`, so it inverts in dark themes instead of always reading as dark. Apply as `class="card inverted"`, or on any block. |
-| `.compact` | Variant | Tighter padding for dense contexts. |
+| `.compact`  | Variant          | Tighter padding for dense contexts.                                                                                                                                                                             |
 
 ## Basic usage
 
 Use semantic elements inside the card. A direct `<header>` or `<footer>` is the
-card's structural slot. Cards do not own page spacing — compose them with
-layout primitives like `.grid`.
+card's structural slot. A direct `<footer>` is anchored to the bottom of the
+card when extra block space is available, so prices and actions line up across
+equal-height cards. Cards do not own page spacing — compose them with layout
+primitives like `.grid`. A bare card owns the rhythm between its direct
+children through `--card-gap`; applying a layout primitive such as `.stack` or
+`.media` to the same element gives that primitive control of the layout and
+gap.
 
 ```html demo
 <div style="max-inline-size: 32rem">
@@ -95,7 +100,9 @@ colored headers, or footers.
 
 ## In grids
 
-Cards display nicely in grids with equal-height behavior.
+Cards display nicely in grids with equal-height behavior. Each card in a row
+stretches to the row height, and a direct `<footer>` anchors to the bottom, so
+all footers in the row line up regardless of body length.
 
 ```html demo
 <section class="grid">
@@ -193,3 +200,4 @@ variants.
 - `--card-radius` — corner radius.
 - `--card-max-inline-size` — maximum width.
 - `--card-pad` — inner padding; also drives the negative offsets that let a `.bleed` child reach the card edge. `.compact` lowers it.
+- `--card-gap` — space between direct children of a bare card. A composed layout primitive owns its own gap instead. `.compact` does not change this hook.

package/docs/pages/components/chat.md

@@ -1,6 +1,6 @@
 # Chat
 
-> **Optional** — import `actual-css/css/optional/chat` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/components/chat` or `actual-css/css/components`.
 
 Chat lays out message metadata, an optional avatar, and a content-sized bubble
 at either edge of a conversation.
@@ -36,13 +36,13 @@ put `role="log"` on individual messages.
 
 ## Class reference
 
-| Class | Description |
-|---|---|
-| `.chat` | Message row grid. |
-| `.chat-start` / `.chat-end` | Logical inline placement. |
-| `.chat-avatar` | Avatar grid slot; compose it with `.avatar`. |
-| `.chat-header` / `.chat-footer` | Muted message metadata. |
-| `.chat-bubble` | Content-sized message surface. |
+| Class                           | Description                                  |
+|---------------------------------|----------------------------------------------|
+| `.chat`                         | Message row grid.                            |
+| `.chat-start` / `.chat-end`     | Logical inline placement.                    |
+| `.chat-avatar`                  | Avatar grid slot; compose it with `.avatar`. |
+| `.chat-header` / `.chat-footer` | Muted message metadata.                      |
+| `.chat-bubble`                  | Content-sized message surface.               |
 
 ## CSS hooks
 

package/docs/pages/components/dialog.md

@@ -4,13 +4,13 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.modal` | Component | Centered modal surface built on the native `<dialog>` element. |
-| `.scrollable` | Variant | Keeps the header and footer visible while the dialog body scrolls. |
-| `.dialog-confirmation` | Variant | Separates a confirmation message from its full-width action band. |
-| `.dialog-icon` | Component | Circular intent-aware icon well for confirmation messages. |
-| `.dialog-close` | Component | Icon-only close button anchored to the modal's top end, out of the content flow. |
+| Class                  | Kind      | Description                                                                      |
+|------------------------|-----------|----------------------------------------------------------------------------------|
+| `.modal`               | Component | Centered modal surface built on the native `<dialog>` element.                   |
+| `.scrollable`          | Variant   | Keeps the header and footer visible while the dialog body scrolls.               |
+| `.dialog-confirmation` | Variant   | Separates a confirmation message from its full-width action band.                |
+| `.dialog-icon`         | Component | Circular intent-aware icon well for confirmation messages.                       |
+| `.dialog-close`        | Component | Icon-only close button anchored to the modal's top end, out of the content flow. |
 
 ## Usage
 

package/docs/pages/components/drawer.md

@@ -4,9 +4,9 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.drawer` | Component | Modal side-sheet built on the native `<dialog>` element. |
+| Class           | Kind      | Description                                                |
+|-----------------|-----------|------------------------------------------------------------|
+| `.drawer`       | Component | Modal side-sheet built on the native `<dialog>` element.   |
 | `.drawer-close` | Component | Icon-only close button that sits inside the drawer header. |
 
 ## Usage

package/docs/pages/components/fab.md

@@ -1,9 +1,11 @@
 # Floating action button
 
-> **Optional** — import `actual-css/css/optional/fab` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/components/fab` or `actual-css/css/components`.
 
 FAB fixes a primary action near the viewport's block-end and inline-end edges.
 The existing button component owns its size, shape, intent, and interaction.
+As a direct child of `.app-layout`, it instead overlays the main grid area so
+the layout keeps it clear of adaptive application navigation and safe areas.
 
 ```html
 <div class="fab">
@@ -102,12 +104,12 @@ the open state so a plus naturally becomes a close symbol.
 
 ## Class reference
 
-| Class | Description |
-|---|---|
-| `.fab` | Fixed viewport placement; use `details` for a speed dial. |
-| `.fab-actions` | Collapsible vertical action list. |
-| `.fab-action` | One horizontal label-and-button unit. |
-| `.fab-label` | Compact floating label for an action. |
+| Class          | Description                                               |
+|----------------|-----------------------------------------------------------|
+| `.fab`         | Fixed viewport placement; use `details` for a speed dial. |
+| `.fab-actions` | Collapsible vertical action list.                         |
+| `.fab-action`  | One horizontal label-and-button unit.                     |
+| `.fab-label`   | Compact floating label for an action.                     |
 
 ## CSS hooks
 

package/docs/pages/components/indicator.md

@@ -0,0 +1,52 @@
+# Indicator
+
+> Attach any component to one of a container's four corners.
+
+`.indicator` creates the positioning context and `.indicator-item` positions
+its child at the top-end corner. The primitive does not add a background,
+size, border, or contrast ring: compose it with `.badge` or another component
+that owns its appearance.
+
+## Class reference
+
+| Class             | Kind      | Description                                      |
+|-------------------|-----------|--------------------------------------------------|
+| `.indicator`      | Component | Positioning context for an overlaid child.       |
+| `.indicator-item` | Part      | Item attached to the top-end corner by default.  |
+| `.start`          | Placement | Moves the item to the inline-start corner.       |
+| `.bottom`         | Placement | Moves the item to the bottom corner.             |
+
+Combine `.bottom.start` for bottom-start. Logical inline placement follows the
+document direction automatically.
+
+```html demo
+<div class="cluster" style="padding: var(--space-40);">
+  <button class="btn indicator" type="button">
+    Inbox
+    <span class="indicator-item badge danger solid">3</span>
+  </button>
+
+  <article class="card indicator" style="max-inline-size: 18rem;">
+    <span class="indicator-item start badge success">New</span>
+    <h2>Quarterly report</h2>
+    <p>The latest figures are ready to review.</p>
+  </article>
+</div>
+```
+
+## Four corners
+
+```html demo
+<div class="indicator card" style="inline-size: 12rem; min-block-size: 7rem; margin: var(--space-40);">
+  <span class="indicator-item badge solid" aria-label="Top end">TE</span>
+  <span class="indicator-item start badge solid" aria-label="Top start">TS</span>
+  <span class="indicator-item bottom badge solid" aria-label="Bottom end">BE</span>
+  <span class="indicator-item bottom start badge solid" aria-label="Bottom start">BS</span>
+  <p class="muted">Four logical corners</p>
+</div>
+```
+
+The item extends beyond the container edge. An ancestor with clipped overflow
+can cut it off; leave overflow visible or provide enough inset space in that
+composition. Avatar status dots keep their dedicated circle-aware placement
+and contrast ring; continue to use `.avatar > .badge:empty` for that pattern.

package/docs/pages/components/list.md

@@ -0,0 +1,62 @@
+# List
+
+> Repeated application rows with optional leading and trailing regions.
+
+Use `.list` when a collection repeatedly needs leading content, flexible text,
+and trailing metadata or controls. Use `.media` for a single two-part
+media/content relationship, `.nav-list` for navigation structure, and native
+list markers when order or bullets carry meaning.
+
+```html demo
+<ul class="list">
+  <li class="list-item">
+    <span class="avatar sm"><abbr>AM</abbr></span>
+    <span class="list-item-content">
+      <strong class="list-item-title">Ada Morgan</strong>
+      <span class="list-item-text">Design systems · Brussels</span>
+    </span>
+    <span class="badge success">Online</span>
+  </li>
+  <li class="list-item">
+    <input class="check" type="checkbox" aria-label="Select quarterly review">
+    <span class="list-item-content">
+      <strong class="list-item-title">Quarterly review</strong>
+      <span class="list-item-text">Due tomorrow</span>
+    </span>
+    <time class="list-item-trailing" datetime="09:30">09:30</time>
+  </li>
+</ul>
+```
+
+Leading and trailing content are unconstrained: avatars, native choices,
+badges, text, switches, and buttons retain their own component sizing. The
+middle region has no minimum content floor, so supporting text and long tokens
+wrap instead of widening the page.
+
+For a navigable row, keep the list semantics and put `.list-item` on the link:
+
+```html demo
+<ul class="list">
+  <li>
+    <a class="list-item" href="#profile">
+      <span aria-hidden="true">👤</span>
+      <span class="list-item-content">
+        <strong class="list-item-title">Profile</strong>
+        <span class="list-item-text">Name, photo, and contact details</span>
+      </span>
+      <span class="list-item-trailing" aria-hidden="true">›</span>
+    </a>
+  </li>
+</ul>
+```
+
+Do not attach click JavaScript to the entire row. Use a link for navigation and
+a button or native control for actions.
+
+### Hooks
+
+- `--list-item-min-size` controls the row's minimum touch height.
+- `--list-item-pad-block` and `--list-item-pad-inline` control row padding.
+- `--list-item-gap` controls spacing between the three regions.
+- `--list-divider` controls the leading and inter-row dividers. The final row
+  deliberately has no trailing divider.