actual-css 0.9.2 → 0.10.0

package/docs/design-notes/forced-colors.md

@@ -30,6 +30,12 @@ an essential shape, state, or affordance.
 
 ## Pattern: custom property + single override
 
+The hook-only form below is fine until an application overrides the hook: the
+override sits at the same specificity, loads after the framework, and wins the
+variable — leaving a non-system fill the browser then remaps to `Canvas`. For
+a masked marker, write the forced value on the property itself so no hook
+override can take it away (accordion) — same for range track/thumb fills.
+
 ```css
 .component {
   --cmp-marker-color: var(--text-muted);
@@ -48,6 +54,11 @@ an essential shape, state, or affordance.
   .component {
     --cmp-marker-color: CanvasText;
   }
+
+  /* Masked markers: pin the property, not just the hook. */
+  .component::marker {
+    background-color: CanvasText;
+  }
 }
 ```
 
@@ -104,7 +115,7 @@ remapping is perfect:
 
 - `.card` — `background: Canvas`, `color: CanvasText` are already the defaults
 - `.flyout` / `.menu` — `Canvas`/`CanvasText` for content, `ButtonText` for borders
-- `.accordion` / `.breadcrumb` — pure remapping gets everything right
+- `.breadcrumb` — pure remapping gets everything right
 - `.status-bar` — `CanvasText` on `Canvas` background
 
 The only forced-colors rules that should remain after a full audit are the ones

package/docs/design-notes/naming.md

@@ -47,7 +47,7 @@ never about opting in.
 - **Base** (`utilities/base.css`) is a curated set of common ergonomic
   shortcuts (`.overflow-auto`, `.gap-none`, `.text-nowrap`, `.px`, `.py`).
 - **Extra** (`utilities/extra.css`) uses explicit property/value names
-  (`.overflow-hidden`, `.padding-context`, `.white-space-normal`).
+  (`.overflow-hidden`, `.padding-context`, `.flex-nowrap`).
 
 Call them base and extra, after the files. "Optional" is the wrong word for
 either: it reads as a layer an author has to opt into, which is true of every

package/docs/design-notes/surface-reparenting.md

@@ -20,8 +20,8 @@ every scope that reached it *by inheritance*. The panel was styled by one set of
 ancestors while closed, and by a different set from the moment it became
 visible.
 
-Actual leans on inheritance deliberately: theme islands, density, `.inverted`,
-and the custom properties an application scopes to its own containers all
+Actual leans on inheritance deliberately: theme islands, density, and the
+custom properties an application scopes to its own containers all
 travel that way. So this was not one bug about themes. It was the same bug in as
 many forms as there are inherited contexts.
 
@@ -30,13 +30,12 @@ many forms as there are inherited contexts.
 Chrome, one `.flyout` per scope, values read off the panel before and after the
 click that opens it:
 
-| Scope                     | Closed                                   | Open                 |
-| ------------------------- | ---------------------------------------- | -------------------- |
-| `[data-theme="dark"]`     | `background: rgb(30, 26, 35)`            | `rgb(255, 255, 255)` |
-| `.sm`                     | `--control-size: 2rem`                   | `2.375rem`           |
-| `.inverted`               | `--ui-fg: light-dark(hsl(0 0% 100%), …)` | *(unset)*            |
-| app-scoped `--app-accent` | `rgb(1, 2, 3)`                           | *(unset)*            |
-| `.sm` inside a `<dialog>` | `--control-size: 2rem`                   | `2.375rem`           |
+| Scope                     | Closed                        | Open                 |
+| ------------------------- | ----------------------------- | -------------------- |
+| `[data-theme="dark"]`     | `background: rgb(30, 26, 35)` | `rgb(255, 255, 255)` |
+| `.sm`                     | `--control-size: 2rem`        | `2.375rem`           |
+| app-scoped `--app-accent` | `rgb(1, 2, 3)`                | *(unset)*            |
+| `.sm` inside a `<dialog>` | `--control-size: 2rem`        | `2.375rem`           |
 
 Every context broke. Three consequences were worth stating plainly:
 

package/docs/navigation.json

@@ -49,10 +49,12 @@
         "aura",
         "avatar",
         "badge",
+        "bleed",
         "breadcrumb",
         "button",
         "card",
         "chat",
+        "close",
         "dialog",
         "drawer",
         "data-list",

package/docs/pages/components/accordion.md

@@ -116,4 +116,58 @@ The end marker is a shared token-based chevron; swapping it for a local icon is
 ## CSS hooks
 
 - `--accordion-radius` — outer corner radius.
-- `--accordion-marker-color` — color of the end marker; it reinforces to the summary text color on hover, and forced-colors mode overrides it to `CanvasText`.
+- `--accordion-pad` — inset of the summary row and the panel. The panel relays it as `--surface-pad`, so a direct `.bleed` child of the panel reaches the item's sides and bottom corners (never the summary); `.flush` drops the inline half and the relay with it.
+- `--accordion-marker-color` — color of the end marker; it reinforces to the summary text color on hover. In forced-colors mode the marker is pinned to `CanvasText` on the property itself, so an application override of the hook cannot leave a `Canvas`-remapped fill.
+- `--accordion-marker-size` — edge length of the end marker.
+
+### Replacing the marker
+
+The marker is a masked box: `--accordion-marker-color` fills it and the chevron
+mask clips it to the glyph. A background, ring, or shadow set on it is clipped
+to the same silhouette, so a decorated marker — a chevron inside a pill — has
+to be a real element: hide the built-in one and put a
+`<span class="marker" aria-hidden="true"></span>` at the end of the summary. The
+pill is the span; the chevron is its pseudo-element, which reads the same color
+hook, so the hover reinforcement carries over. The forced-colors pin does not
+carry over through the hook — an application hook override at the same
+specificity loads after the framework and would win the variable — so the
+recipe repeats it on its own property:
+
+```css
+.accordion.custom-marker summary::after {
+  display: none;
+}
+
+.accordion.custom-marker .marker {
+  display: grid;
+  place-items: center;
+  margin-inline-start: auto;
+  padding: var(--space-10);
+  border-radius: 50%;
+  background: var(--surface-subtle);
+  transition: transform var(--duration);
+}
+
+.accordion.custom-marker .marker::before {
+  content: "";
+  inline-size: var(--accordion-marker-size);
+  block-size: var(--accordion-marker-size);
+  background-color: var(--accordion-marker-color);
+  -webkit-mask: var(--icon-chevron) center / contain no-repeat;
+  mask: var(--icon-chevron) center / contain no-repeat;
+}
+
+.accordion.custom-marker summary:hover .marker {
+  --accordion-marker-color: currentColor;
+}
+
+.accordion.custom-marker details[open] .marker {
+  transform: rotate(180deg);
+}
+
+@media (forced-colors: active) {
+  .accordion.custom-marker .marker::before {
+    background-color: CanvasText;
+  }
+}
+```

package/docs/pages/components/alert.md

@@ -5,7 +5,7 @@
 - Supports intent colors.
 - Supports longer text and lists.
 - Links inherit alert color by default.
-- Alerts are soft by default. Use `.surface` for neutral chrome with the intent only in the ink, `.solid` or `.outline` when the message needs stronger or quieter emphasis, and `.inverted` for an inverse surface.
+- Alerts are soft by default. Use `.surface` for neutral chrome with the intent only in the ink, `.solid` or `.outline` when the message needs stronger or quieter emphasis.
 - Use `<menu class="actions cluster">` for alert action lists.
 - Use `role="alert"` only when the alert is injected dynamically and should be announced.
 - Not a toast.
@@ -13,7 +13,7 @@
 - A title and a description are plain siblings: the alert owns the small space between its direct content blocks, so neither needs a wrapper. Nested content keeps its own rhythm — wrap several paragraphs in `.prose`, or a differently spaced group in `.stack`, when the message needs a rhythm of its own.
 - Alerts may include a decorative leading icon. Use `.alert-icon` on the icon element; the rest of the content flows into the remaining text column.
 - Use `.compact` or `.spacious` 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.
+- Use a [`.close`](close.md) button to make the alert dismissible. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions; the alert makes it compact.
 
 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
@@ -26,14 +26,13 @@ itself needs to change, not `.soft`.
 | ---------------- | ----------- | ----------------------------------------------- |
 | `.alert`         | Component   | Inline status surface; soft by default.         |
 | `.alert-icon`    | Composition | Decorative leading icon, in the first column.   |
-| `.alert-dismiss` | Modifier    | Compact dismiss button.                         |
+| `.close`         | Composition | Dismiss button, in the last column.             |
 | `.alert-title`   | Composition | Admonition title bar; hosts the dismiss button. |
 | `.alert-body`    | Composition | Admonition body on the page surface.            |
 | `.callout`       | Variant     | Leading-edge flag; owns the border geometry.    |
 | `.admonition`    | Variant     | Tinted title bar, body on the page surface.     |
 | Shared intents   | Intent      | `.primary`, `.secondary`, `.success`, …         |
 | Shared variants  | Variant     | `.solid`, `.outline`, `.surface`.               |
-| `.inverted`      | Surface     | Inverse surface, any intent.                    |
 | Density contexts | Density     | Descendant rhythm; inline padding stays stable. |
 
 ## Basic usage
@@ -101,7 +100,7 @@ intent treatment when the color itself carries the meaning.
 
 ## Trailing action
 
-The grid pins `.alert-icon` and `.alert-dismiss` to the outer columns. A
+The grid pins `.alert-icon` and `.close` to the outer columns. A
 trailing link or button is content, not anatomy, so it lives in the text column:
 wrap the row in a `.cluster` and push the two ends apart. Same recipe as any
 split / spread row — there is no `.alert-action` class.
@@ -129,10 +128,6 @@ center.
     I'm a surface alert — theme chrome, intent in the ink
   </div>
 
-  <div class="alert inverted" role="alert">
-    I'm an inverted alert <a href="#">with a link</a>
-  </div>
-
   <div class="alert danger compact" role="alert">
     I'm an error in a compact context
   </div>
@@ -153,7 +148,7 @@ center.
 
 ## Dismiss
 
-Use `.alert-dismiss` to let a user remove an inline alert. The button is transparent at rest with a muted glyph; it works with any intent because it uses `currentColor` and reduced opacity. It relies on the runtime `--dismiss` command — no custom script.
+Add a `.close` button to let a user remove an inline alert. Inside an alert it is compact and at reduced opacity, and it follows the alert's ink with any intent. The runtime `--dismiss` command removes the alert — no custom script.
 
 ```html demo
 <div class="alert warning" id="warning-alert">
@@ -162,7 +157,7 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
   <p>Something needs your attention.</p>
 
   <button
-    class="alert-dismiss"
+    class="close"
     type="button"
     commandfor="warning-alert"
     command="--dismiss"
@@ -171,14 +166,14 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
 </div>
 ```
 
-In an admonition, place `.alert-dismiss` inside `.alert-title`; it rides the inline end of the title bar:
+In an admonition, place `.close` inside `.alert-title`; it rides the inline end of the title bar:
 
 ```html
 <div class="alert admonition warning" id="notice">
   <div class="alert-title">
     <span>Warning</span>
     <button
-      class="alert-dismiss"
+      class="close"
       type="button"
       commandfor="notice"
       command="--dismiss"
@@ -261,8 +256,7 @@ An admonition is a structured box with a tinted title bar, an optional icon, and
 - `--alert-pad-block` — block padding.
 - `--alert-font-size` — base font size.
 - `--alert-icon-size` — size of a leading `.alert-icon`.
-- `--alert-dismiss-size` — inline and block size of the `.alert-dismiss` button.
-- `--alert-dismiss-icon-size` — size of the dismiss glyph.
+- `--close-size` / `--close-icon-size` — the alert declares compact values for its `.close`; set them on the alert to change them.
 - `--alert-radius` — corner radius, when the default `--radius-lg` does not fit.
 - `--alert-border-inline-start-color` / `--alert-border-inline-start-width` — extension points for a callout-style colored flag on the leading edge instead of a uniform border.
 

package/docs/pages/components/badge.md

@@ -177,21 +177,20 @@ Override the existing hooks when the three-step scale does not fit the content.
 
 ## 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.
+Use `.badge soft` for tag visuals. Add a direct [`.close`](close.md) 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.
 
-Leave the dismiss button empty: it paints its own X, so the pattern needs no
-icon font and no text glyph. Put your own icon inside it and that content is
-used instead.
+Inside a badge the close follows the pill's size, keeps a 24px pointer target,
+and tucks into the padding.
 
 ```html demo
 <span class="badge primary soft">
   Design
-  <button type="button" aria-label="Remove Design"></button>
+  <button class="close" type="button" aria-label="Remove Design"></button>
 </span>
 <span class="badge primary soft">
-  <button type="button" aria-label="Remove Design"></button>
+  <button class="close" type="button" aria-label="Remove Design"></button>
   Design
 </span>
 ```
@@ -204,4 +203,4 @@ used instead.
 - `--badge-font-size` — label font size.
 - `--badge-icon-size` — decorative child size; `1em` follows the label by default.
 - `--badge-pad-x` — inline padding. Derived from `--badge-size`, so it stays proportional to the pill; set it to opt out.
-- `--badge-dismiss-icon-size` — size of the X painted by an empty dismiss button.
+- `--close-size` / `--close-icon-size` — the badge declares them for its `.close`; set them on the badge to change them.

package/docs/pages/components/bleed.md

@@ -0,0 +1,42 @@
+# Bleed
+
+`.bleed` lets a direct child of a padded surface reach its edges. Use it for a
+full-width image, a colored header or footer, or a notice band.
+
+It works inside `.card`, `.drawer`, and an accordion panel. The accordion panel
+owns the padding, so place `.bleed` directly inside the panel, after the summary.
+A deeper descendant stays within its wrapper. A modular build imports
+`actual-css/css/components/bleed` alongside the surface component.
+
+```html demo
+<article class="card stack" style="--card-max-inline-size: 24rem">
+  <img class="bleed" src="https://picsum.photos/seed/actual-css-card/600/300" alt="" />
+  <header><h3>Full-width image</h3></header>
+  <p>The image reaches the card edges.</p>
+  <footer class="bleed" style="background: var(--surface-subtle)">
+    <button type="button" class="btn outline">View</button>
+  </footer>
+</article>
+```
+
+An `<img>`, `<picture>`, `<video>`, `<canvas>`, or `<svg>` with `.bleed` expands
+to the surface width. For a responsive image, put `.bleed` on `<picture>`; its
+image fills the picture and is clipped by it.
+
+Structural `header`, `footer`, and `figure` bands keep the surface's inner
+padding while their background reaches the edge. Other bands can read the
+relayed inset with `--bleed-pad`:
+
+```css
+.status-row {
+  padding: var(--bleed-pad);
+}
+```
+
+The participating surface relays its inset to direct children only. Read
+`--bleed-pad` on one of those children when a custom band needs matching
+padding. An author-defined surface needs its own direct-child relay to join
+this contract.
+
+See [Card](card.md), [Drawer](drawer.md), and [Accordion](accordion.md) for
+surface examples.

package/docs/pages/components/button.md

@@ -61,10 +61,37 @@ Reach for `.surface` when a secondary action must sit on an opaque, neutral
 chip: `.outline` lets whatever is behind it show through, and `.soft` is the
 intent-tinted treatment (its baseline fallback uses `--surface-subtle`).
 
+None of the three gives an opaque fill *under* an intent-colored border —
+`.surface` keeps the neutral `--border`, and `.outline` has no fill. Set
+`--ui-bg` on the element for that combination; it is the variant relay every
+component with shared variants reads, so the same declaration works on a badge:
+
+```css
+.chip-on-tint {
+  --ui-bg: var(--surface);
+}
+```
+
+The rule ties with the variant's own `--ui-bg` on specificity, so load it after
+Actual CSS or import `actual.layer.css`.
+
 Transparent treatments (`.outline`, `.ghost`, `.link`) follow the surrounding
-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.
+foreground by default, including on a band your application paints. A local
+intent class still wins: `.danger.outline` uses the danger color in any
+context, and nothing tunes that color for a surface you paint yourself. For
+intent ink on a dark band, use a `data-theme` island, whose palette is tuned
+for its surface. Filled buttons own their surface and keep their normal intent
+recipe.
+
+A dark button (inverse, contrast) is a custom intent on the button itself, so
+every variant keeps working — `.outline` and `.ghost` take the solid ink:
+
+```css
+.btn.app-dark {
+  --intent: var(--surface-solid);
+  --intent-fg: var(--surface);
+}
+```
 
 `.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
@@ -251,5 +278,4 @@ For exclusive groups, manage a single pressed button:
 ## CSS hooks
 
 - `--btn-radius` — corner radius.
-- `--btn-focus-color` — focus ring base color; the ring itself is derived from it.
 - `--btn-gap` — space between an icon and the label text (default `0.375em`).

package/docs/pages/components/card.md

@@ -1,24 +1,20 @@
 # Card
 
-Flexible content container with optional header, body, and footer regions, plus full-bleed children.
+Flexible content container with optional header, body, and footer regions.
 
 ## 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.        |
-| `.surface`  | Variant          | The page surface; intent in the text only.      |
-| `.inverted` | Surface modifier | Inverse surface treatment.                      |
-| `.compact`  | Density          | Tighter padding and compact descendant context. |
+| 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.        |
+| `.surface` | Variant   | The page surface; intent in the text only.      |
+| `.compact` | Density   | Tighter padding and compact descendant context. |
 
 `.surface` is a shared variant: it paints the page surface instead of
-`--surface-raised` and leaves the intent to the text.
-
-`.inverted` paints `--surface-solid` and swaps the foreground to `--surface`,
-so it inverts in dark themes instead of always reading as dark. Write it as
-`class="card inverted"`, or on any block.
+`--surface-raised` and leaves the intent to the text. For a dark card on a
+light page (or the reverse), put `data-theme="dark"` on the card.
 
 ## Basic usage
 
@@ -59,52 +55,8 @@ gap.
 
 ## Bleed
 
-Use `.bleed` on a direct child to escape the card padding — full-width images,
-colored headers, or footers.
-
-```html demo
-<div style="max-inline-size: 32rem">
-  <article class="card stack">
-    <img class="bleed" src="https://picsum.photos/seed/actual-css-card/600/300" alt="Coastal cliffs at dusk" />
-    <header>
-      <h3>Coastal cliffs at dusk</h3>
-    </header>
-    <section class="stack" aria-label="Summary">
-      <p>A short caption that wraps across a few lines. The image bleeds to the card edges.</p>
-    </section>
-    <footer>
-      <span class="badge primary soft">Photo</span>
-      <button type="button" class="btn outline">View</button>
-    </footer>
-  </article>
-</div>
-```
-
-```html demo
-<article class="card stack" style="--card-max-inline-size: 24rem">
-  <header class="bleed stack items-center text-center" style="background: var(--surface-subtle)">
-    <hgroup>
-      <h3>Team</h3>
-      <p class="muted">For growing products</p>
-    </hgroup>
-    <p>
-      <span style="font-size: 2rem; font-weight: var(--font-weight-semibold); line-height: 1">$24</span>
-      <span class="muted">/ user / month</span>
-    </p>
-  </header>
-
-  <ul class="stack items-center" style="list-style: none; padding: 0">
-    <li>Unlimited projects</li>
-    <li>Up to 25 seats</li>
-    <li>Shared workspaces</li>
-    <li>Priority support</li>
-  </ul>
-
-  <footer class="bleed" style="background: var(--surface-subtle); justify-content: center">
-    <a class="btn primary" href="#">Upgrade</a>
-  </footer>
-</article>
-```
+Use `.bleed` on a direct child to bring an image or band to the card edge. See
+[Bleed](bleed.md) for the shared surface contract and its modular import.
 
 ## In grids
 
@@ -148,27 +100,10 @@ all footers in the row line up regardless of body length.
 
 ## Surfaces
 
-`.inverted` creates a contrasting surface context, not a complete theme island.
-On a bare block (`<header class="inverted">`, `<section class="inverted">`) it
-paints the surface directly; contextual content and transparent treatments such
-as `.btn.outline`, `.btn.ghost`, and `.btn.link` follow its foreground.
-
-Apply it directly to a component that consumes the shared `--ui-*` surface
-contract (`.card`, `.navbar`, `.alert`, `.badge`) to treat that component as the
-contrasting surface. A surface-owning component nested inside an inverted block
-keeps its own surface and establishes a new context for its descendants. Use a
-`data-theme` island when every component and form control in a subtree must use
-another theme.
-
-More specific component states or explicit surface variants still take
-precedence: `.card.inverted.subtle` keeps the `.subtle` background while the
-foreground stays inverted.
-
-`.inverted` and `.subtle` are competing surface treatments — do not combine
-them. `.subtle` paints the card's background directly while `.inverted` swaps
-the surface tokens, so `.card.subtle.inverted` renders a subtle background with
-inverted foreground. Treat them as mutually exclusive, like two competing
-variants.
+A card is a surface-owning component: inside a painted band it keeps its own
+surface and resets the context for its content. A card with
+`data-theme="dark"` is a complete dark island — its fields, intents and states
+all follow.
 
 `.surface` is the shared variant on a card: it drops the card to the page
 surface instead of `--surface-raised`, keeps the theme border, and lets an
@@ -198,12 +133,12 @@ treatments on either side of it.
     </hgroup>
   </article>
 
-  <article class="card inverted stack">
+  <article class="card stack" data-theme="dark">
     <hgroup>
-      <h3>Inverted</h3>
-      <p>Inverse surface for emphasis. Text inherits the contrasting surface color.</p>
+      <h3>Dark island</h3>
+      <p class="muted">A complete dark theme on one card.</p>
     </hgroup>
-    <button type="button" class="btn">Action</button>
+    <button type="button" class="btn primary outline">Action</button>
   </article>
 
   <article class="card compact">
@@ -219,5 +154,5 @@ treatments on either side of it.
 
 - `--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-pad` — inner padding, relayed to direct children for `.bleed`. `.compact` lowers it.
 - `--card-gap` — space between direct children of a bare card. A composed layout primitive owns its own gap instead.

package/docs/pages/components/close.md

@@ -0,0 +1,48 @@
+# Close
+
+> Icon-only X button that closes a dialog, dismisses an alert, or removes a tag.
+
+**Related terms:** close button, dismiss button, remove button, clear, X.
+
+- Use an empty `<button class="close" aria-label="…">`: it paints its own X from `--icon-close`, so it needs no icon font and no text glyph.
+- `.close` is always the X. A button with another pictogram is a `.btn.icon-only`.
+- The class names the look, not the mechanism. Close with the container's own action: `command="request-close"` or `method="dialog"` in a dialog, `command="--dismiss"` on an alert, application logic on a tag.
+- The container sets the size and place: the top inline-end corner of a `.modal` or a `.drawer`, the last column of an `.alert`, the end of a `.badge`.
+- A modular build imports `actual-css/css/components/close` next to the component that hosts it.
+
+## Basic usage
+
+```html demo
+<div class="cluster">
+  <button class="close" type="button" aria-label="Close"></button>
+
+  <span class="badge primary soft">
+    Design
+    <button class="close" type="button" aria-label="Remove Design"></button>
+  </span>
+</div>
+```
+
+## In a dialog
+
+In a `.modal` or a `.drawer`, the close sits out of the content flow at the
+panel's top inline-end corner. Place it as a direct child of the dialog, of its
+top-level `form` or `header`, or of a `form` inside that header; a `.close`
+deeper in the content keeps its own place. See [Dialog](dialog.md) and
+[Drawer](drawer.md).
+
+```html
+<dialog class="modal" id="details">
+  <button class="close" type="button" commandfor="details" command="request-close"
+          aria-label="Close dialog"></button>
+  …
+</dialog>
+```
+
+## CSS hooks
+
+- `--close-size` — inline and block size of the button; `--control-size` unless the container sets it.
+- `--close-icon-size` — size of the X.
+
+Alerts and badges declare both hooks on themselves, so set them on the container
+or on the button.

package/docs/pages/components/data-list.md

@@ -61,6 +61,24 @@ metadata.
 </article>
 ```
 
+## Stacked
+
+`.stacked` puts each value under its term instead of beside it, for a narrow
+column or for values too long to share a row.
+
+```html demo
+<dl class="data-list stacked" style="max-inline-size: 16rem">
+  <dt>Billing contact</dt>
+  <dd>alice@example.com</dd>
+
+  <dt>Registered address</dt>
+  <dd>42 Rue des Fleurs, 1000 Brussels, Belgium</dd>
+
+  <dt>Renewal</dt>
+  <dd><time datetime="2026-09-14">14 Sep 2026</time></dd>
+</dl>
+```
+
 ## Contract
 
 `.data-list` styles one `<dt>` followed by one `<dd>` per property. A valid
@@ -69,4 +87,11 @@ markup does not belong in `.data-list` — use a plain description list instead,
 where `.prose` already covers the editorial cases.
 
 Use `.data-list` for the properties of a single object. Use a `<table>` when
-comparing the same properties across multiple objects.
+comparing the same properties across multiple objects.
+
+A per-property icon goes inside the `<dt>`, next to the term. There is no
+gutter slot spanning a term and its value: a `<dl>` admits only `<dt>` and
+`<dd>` per pair — directly or inside a `<div>` wrapper — so no third element
+can hold it. When the icon is the point and the term/value relation is not,
+the content is not a description list: reach for `.media` with an `.overline`
+label instead.