actual-css 0.4.2 → 0.6.0

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

@@ -4,21 +4,38 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 
 ## Primitives
 
-| 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` |
-| Menu-item vocabulary, usable-item filtering | `menu` | `actual-css/js/menu` |
-| Focusable lookup, visibility | `focus` | `actual-css/js/focus` |
-| One remembered tab stop with directional navigation | `focus-group` (`connectFocusGroup`) | `actual-css/js/focus-group` |
-| Caret-safe value rewriting | `input` (`onTextInput`, `setCaret`, `dispatchInput`) | `actual-css/js/input` |
-| Character policies | `filter` | `actual-css/js/filter` |
-| Event namespace | `events` (`EVENTS`, `ACTUAL_EVENT_PREFIX`) | `actual-css/js/events` |
-| Declarative triggers | `command` (`registerCommands`) | `actual-css/js/command` |
-| State classes the runtime writes | `selectors` (`CLASSES`) | `actual-css/js/selectors` |
+| Need                               | Primitive     | Import                      |
+| ---------------------------------- | ------------- | --------------------------- |
+| Discovery, lifecycle, cleanup      | `enhance`     | `actual-css/js/enhance`     |
+| Per-document LIFO Escape dismissal | `escape`      | `actual-css/js/escape`      |
+| Positioning, flip and shift        | `floating`    | `actual-css/js/floating`    |
+| Open/close, sheet, backdrop, focus | `surface`     | `actual-css/js/surface`     |
+| Directional item lookup            | `keys`        | `actual-css/js/keys`        |
+| Menu-item vocabulary               | `menu`        | `actual-css/js/menu`        |
+| Focusable lookup, visibility       | `focus`       | `actual-css/js/focus`       |
+| One remembered tab stop            | `focus-group` | `actual-css/js/focus-group` |
+| Caret-safe value rewriting         | `input`       | `actual-css/js/input`       |
+| Character policies                 | `filter`      | `actual-css/js/filter`      |
+| Event namespace                    | `events`      | `actual-css/js/events`      |
+| Declarative triggers               | `command`     | `actual-css/js/command`     |
+| State classes the runtime writes   | `selectors`   | `actual-css/js/selectors`   |
+
+The named exports each module carries:
+
+- `enhance` — `enhance`, `registerEnhancement`
+- `escape` — `registerEscapeDismissal`
+- `floating` — `track`, `reposition`, `repositionAt`, plus
+  `--available-height` and `data-placement`
+- `keys` — `itemForKey`, `firstItem`, `lastItem`, `nextItem`, with edge,
+  wrapping and RTL handling
+- `focus-group` — `connectFocusGroup`
+- `input` — `onTextInput`, `setCaret`, `dispatchInput`
+- `events` — `EVENTS`, `ACTUAL_EVENT_PREFIX`
+- `command` — `registerCommands`
+- `selectors` — `CLASSES`
+
+`surface` also owns outside-click and Escape dismissal, and focus restore.
+`menu` filters to usable items.
 
 ## Focus group
 

package/docs/navigation.json

@@ -55,6 +55,7 @@
         "chat",
         "dialog",
         "drawer",
+        "data-list",
         "fab",
         "indicator",
         "key",
@@ -76,6 +77,7 @@
       "pages": [
         "overview",
         "controls",
+        "combobox",
         "labels",
         "floating-field",
         "states-and-sizes",

package/docs/pages/components/alert.md

@@ -21,17 +21,20 @@ 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.              |
+| Class            | Kind        | Description                                   |
+| ---------------- | ----------- | --------------------------------------------- |
+| `.alert`         | Component   | Inline status surface; soft by default.       |
+| `.alert-icon`    | Composition | Decorative leading icon, in the first column. |
+| `.alert-dismiss` | Modifier    | Compact dismiss button.                       |
+| `.callout`       | Variant     | Neutral panel, thick accent leading edge.     |
+| `.admonition`    | Variant     | Tinted title bar, body on the page surface.   |
+
+`.alert-dismiss` draws itself with the `--icon-close` mask and acts through the
+`--dismiss` command.
 | `.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.                                                 |
+| Shared variants  | Variant     | `.solid`, `.outline`, and `.surface` emphasis.                                    |
 | `.sm` / `.lg`    | Size        | Density; inline padding stays stable.                                             |
 
 ## Basic usage
@@ -117,10 +120,12 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
 ```html demo
 <div class="alert warning" id="warning-alert">
   <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
-  <div>
+
+  <div class="stack" style="--gap: var(--space-10)">
     <strong>Warning</strong>
     <p>Something needs your attention.</p>
   </div>
+
   <button
     class="alert-dismiss"
     type="button"

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

@@ -5,6 +5,8 @@
 Use one `.app-nav` landmark for the application's primary destinations. Links
 remain links, and `aria-current="page"` is the only current-page state.
 
+**Related terms:** tab bar, bottom navigation, bottom nav, navigation rail, side navigation.
+
 ```html demo
 <nav class="app-nav" aria-label="Primary">
   <a href="#today" aria-current="page">

package/docs/pages/components/aura.md

@@ -5,6 +5,32 @@
 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.
 
+```html demo
+<div class="cluster" style="gap: 2.5rem">
+  <span class="aura primary">
+    <article class="card" style="inline-size: 13rem">
+      <p><strong>Rotating arc</strong></p>
+      <p class="muted">One lit segment travels around the frame.</p>
+    </article>
+  </span>
+
+  <span class="aura aura-glow primary">
+    <article class="card" style="inline-size: 13rem">
+      <p><strong>Breathing glow</strong></p>
+      <p class="muted">The whole perimeter lights and breathes.</p>
+    </article>
+  </span>
+</div>
+```
+
+`.aura` sends a short accent of light travelling around the frame, over a
+permanent halo that keeps the object present between two passes. Add
+`.aura-glow` to light the whole perimeter evenly instead, as a halo that
+breathes slowly.
+
+Aura reads best when it has enough perimeter to travel around, and is naturally
+more pronounced on dark surfaces. It still composes on small shapes:
+
 ```html demo
 <div class="cluster">
   <span class="aura primary">
@@ -14,22 +40,92 @@ It is visual emphasis only and does not change the child's semantics.
   <span class="aura aura-glow secondary">
     <span class="badge">New</span>
   </span>
+
+  <span class="aura aura-glow success">
+    <span class="badge success soft">Live</span>
+  </span>
+
+  <span class="aura danger">
+    <span class="badge danger solid" aria-label="12 unread notifications">12</span>
+  </span>
+</div>
+```
+
+Note the intent on the wrapper, not on the child: `.aura` is an intent
+boundary, so the badge or alert inside keeps its own color and the frame keeps
+the one you gave the wrapper. Matching them reads as one object; deliberately
+mismatching them reads as two.
+
+```html demo
+<div class="stack" style="max-inline-size: 28rem">
+  <span class="aura warning">
+    <div class="alert warning" role="alert">
+      <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
+      <div>Your trial ends in three days.</div>
+    </div>
+  </span>
+
+  <span class="aura aura-glow danger">
+    <div class="alert danger" role="alert">
+      <i class="ti ti-credit-card-off alert-icon" aria-hidden="true"></i>
+      <div>Two payment methods failed. <a href="#">Review them</a>.</div>
+    </div>
+  </span>
 </div>
 ```
 
-The animated conic frame runs only when the user has not requested reduced
-motion. Add `.aura-glow` for a static, solid frame. The component uses an
-intent such as `.primary`, `.success`, or `.danger`; it does not introduce
-separate aura color variants.
+Motion changes how the light lives, never whether the effect is there: when the
+user has requested reduced motion, the travelling accent becomes two opposite
+lit corners — a deliberate composition rather than a rotation frozen at an
+arbitrary angle — and the glow stays a full, still halo.
+
+The frame color comes from an intent such as `.primary`, `.success`, or
+`.danger`; there are no separate aura color variants. The intent is sovereign:
+a neutral intent produces a neutral aura. Use a chromatic intent when you want
+a visibly luminous effect.
+
+Two hooks tune how loud the effect is. `--aura-intensity` scales both halos at
+once, resting and breathing alike, so the breath stays proportional at every
+setting; `--aura-duration` sets one full rotation of the accent, or one breath
+of the glow.
+
+```html demo
+<div class="cluster" style="gap: 2rem">
+  <span class="aura aura-glow primary" style="--aura-intensity: 0.4">
+    <span class="card" style="inline-size: 8rem">Muted</span>
+  </span>
+
+  <span class="aura aura-glow primary">
+    <span class="card" style="inline-size: 8rem">Default</span>
+  </span>
+
+  <span class="aura aura-glow primary" style="--aura-intensity: 2">
+    <span class="card" style="inline-size: 8rem">Loud</span>
+  </span>
+
+  <span class="aura primary" style="--aura-duration: 2s">
+    <span class="card" style="inline-size: 8rem">Fast accent</span>
+  </span>
+</div>
+```
 
 Keep exactly one direct child and set `--aura-radius` when its shape differs
 from the common button, card, alert, and badge shapes detected as a visual
 enhancement.
 
+The child must be opaque. The frame paints across the whole box and relies on
+the child to cover all but its edge, so a transparent child — an `.outline`
+alert, a `.ghost` button — is filled edge to edge with the frame color instead
+of framed by it. Give such a child a surface, or move the aura to an opaque
+wrapper around it.
+
 ## CSS hooks
 
 - `--aura-color` — frame and halo color; follows the local intent.
 - `--aura-width` — frame thickness.
-- `--aura-blur` — halo blur radius.
+- `--aura-blur` — near halo blur; the far halo derives its own blur and its
+  spread beyond the frame from this value, so one hook scales both.
+- `--aura-intensity` — multiplies both halo opacities, resting and breathing.
+  It does not touch the frame itself, which stays a crisp line at any setting.
 - `--aura-radius` — child corner radius used to derive the outer radius.
-- `--aura-duration` — rotation duration when motion is allowed.
+- `--aura-duration` — one rotation of the accent, or one breath of the glow.

package/docs/pages/components/avatar.md

@@ -12,12 +12,15 @@
 
 ## 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.    |
+| `.avatar-stack` | Composition | Overlapping avatar group.               |
+| `.badge:empty`  | Composition | Status dot, at the bottom-end corner.   |
+| `.sm` / `.lg`   | Size        | Density; also rescales `.avatar-stack`. |
+
+`.avatar` works on `div`, `a` and `button`. The status dot is an empty
+`.badge` inside an `.avatar`, and needs an `aria-label` of its own.
 
 ## Basic usage
 

package/docs/pages/components/badge.md

@@ -16,15 +16,21 @@ direct child of `.stack` (where flex children otherwise stretch). Use
 `inline-size: 100%` — or the optional `.inline-size-full` utility — when a
 full-width badge is intentional.
 
+**Related terms:** chip, tag, pill, removable tag.
+
 ## 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`, …   |
+| Shared variants | Variant     | `.solid`, `.outline`, `.surface`.         |
+| `.sm` / `.lg`   | Size        | Compact density.                          |
+
+The shared intents are `.primary`, `.secondary`, `.success`, `.warning` and
+`.danger`. The variants set emphasis: `.solid` is filled, `.outline` bordered,
+`.surface` untinted.
 
 ## Basic usage
 
@@ -58,13 +64,25 @@ full-width badge is intentional.
 </button>
 ```
 
-## Empty badge dot
+## Status dot
 
 ```html demo
 <span class="badge success" aria-label="Online"></span>
 ```
 
-The dot conveys no text, so an `aria-label` is required for it to mean anything.
+An autonomous dot conveys state without visible text, so give it an accessible
+name.
+
+## Color marker
+
+Use an empty badge as a compact intent-colored marker in legends and status
+labels. When adjacent text carries the same information, keep the marker
+decorative.
+
+```html demo
+<span class="badge primary" aria-hidden="true"></span>
+Regular
+```
 
 ## Size variants
 

package/docs/pages/components/button.md

@@ -4,22 +4,23 @@ 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.                     |
+| `.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.     |
+| `.surface`    | Variant   | Page surface, neutral border, intent on the label. |
+| `.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
 
@@ -53,8 +54,12 @@ Shared intent classes set color meaning. They compose with every variant.
 
 ## Variants
 
-`.ghost` and `.link` are button-only; `.soft`, `.outline`, and `.solid` are
-shared with other components.
+`.ghost` and `.link` are button-only; `.soft`, `.outline`, `.solid`, and
+`.surface` are shared with other components.
+
+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`).
 
 Transparent treatments (`.outline`, `.ghost`, `.link`) follow the surrounding
 foreground by default, including on a contrasting `.inverted` surface. A local
@@ -79,6 +84,8 @@ container. For a plain text link, use a bare `<a>` with no class.
   <button class="btn danger outline" type="button">Danger outline</button>
   <button class="btn soft" type="button">Soft</button>
   <button class="btn danger soft" type="button">Danger soft</button>
+  <button class="btn surface" type="button">Surface</button>
+  <button class="btn danger surface" type="button">Danger surface</button>
   <button class="btn ghost" type="button">Ghost</button>
   <button class="btn link" type="button">Button as link</button>
 </div>

package/docs/pages/components/card.md

@@ -4,13 +4,21 @@ 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.                                                                                                                                                                        |
-| `.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.                                                                                                                                                                             |
+| 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`  | Variant          | Tighter padding for dense contexts.         |
+
+`.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.
 
 ## Basic usage
 
@@ -162,6 +170,11 @@ the surface tokens, so `.card.subtle.inverted` renders a subtle background with
 inverted foreground. Treat them as mutually exclusive, like two competing
 variants.
 
+`.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
+intent class color the text only. `.raised` and `.subtle` are the card-local
+treatments on either side of it.
+
 ```html demo
 <section class="grid">
   <article class="card raised">
@@ -178,6 +191,13 @@ variants.
     </hgroup>
   </article>
 
+  <article class="card surface">
+    <hgroup>
+      <h3>Surface</h3>
+      <p class="muted">The page surface with the theme border.</p>
+    </hgroup>
+  </article>
+
   <article class="card inverted stack">
     <hgroup>
       <h3>Inverted</h3>

package/docs/pages/components/chat.md

@@ -37,7 +37,7 @@ 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`. |

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

@@ -0,0 +1,72 @@
+# Data list
+
+> A compact key/value layout for object properties.
+
+Use `.data-list` to present the properties of a single object as simple
+term–value pairs on a `<dl>`. It expects alternating `<dt>` and `<dd>` children
+— one term, one value per property. Use a plain description list for
+relationships that involve multiple terms or descriptions, and a `<table>` to
+compare the same property across several objects.
+
+```html demo
+<dl class="data-list">
+  <dt>Name</dt>
+  <dd>Alice Martin</dd>
+
+  <dt>Email</dt>
+  <dd>alice@example.com</dd>
+
+  <dt>Role</dt>
+  <dd>Administrator</dd>
+</dl>
+```
+
+## Rich values
+
+Values accept inline content such as badges, links, dates, or a `.cluster` of
+related items. Terms and values remain baseline-aligned.
+
+```html demo
+<dl class="data-list">
+  <dt>Status</dt>
+  <dd><span class="badge success">Active</span></dd>
+
+  <dt>Plan</dt>
+  <dd>Professional</dd>
+
+  <dt>Renewal</dt>
+  <dd><time datetime="2026-09-14">14 Sep 2026</time></dd>
+</dl>
+```
+
+## In a card
+
+`.data-list` composes with `.card` and other layout primitives for business
+metadata.
+
+```html demo
+<article class="card stack">
+  <h3>Storage details</h3>
+
+  <dl class="data-list">
+    <dt>Used</dt>
+    <dd>6.7 GB</dd>
+
+    <dt>Available</dt>
+    <dd>1.3 GB</dd>
+
+    <dt>Files</dt>
+    <dd>12,492</dd>
+  </dl>
+</article>
+```
+
+## Contract
+
+`.data-list` styles one `<dt>` followed by one `<dd>` per property. A valid
+`<dl>` may group several terms with one description or the reverse, but that
+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.

package/docs/pages/components/dialog.md

@@ -2,15 +2,20 @@
 
 > Centered modal overlay for focused tasks, confirmations, or forms, built on the native `<dialog>` element.
 
+**Related terms:** modal, alert dialog, confirmation dialog.
+
 ## 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 surface on the native `<dialog>`.     |
+| `.scrollable`          | Variant   | Header and footer stay while the body scrolls. |
+| `.dialog-confirmation` | Variant   | Message above a full-width action band.        |
+| `.dialog-icon`         | Component | Circular intent-aware icon well.               |
+| `.dialog-close`        | Component | Icon-only close button, at the top end.        |
+
+`.dialog-close` sits outside the content flow, so it does not take part in the
+dialog's own layout.
 
 ## Usage
 

package/docs/pages/components/drawer.md

@@ -2,10 +2,12 @@
 
 > Modal side-sheet that overlays the page for navigation or filters.
 
+**Related terms:** off-canvas, side panel, side sheet, navigation drawer.
+
 ## Class reference
 
 | 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. |