actual-css 0.11.1 → 0.12.0

package/docs/pages/patterns/navigation-list.md

@@ -1,14 +1,15 @@
 # Navigation List
 
-Use `.nav-list` for a semantic list of navigation links.
-
-It removes native list chrome but does not force a direction. Combine it with layout primitives depending on context.
+Use `.nav-list` for a vertical list of navigation links: it removes native list
+chrome, stacks the rows and stretches each `.nav-link` across the row. For a
+horizontal row of links, use `.cluster` on the list, which removes the list
+chrome too.
 
 ```html demo
 <div class="stack">
   <h2>Navigation</h2>
   <nav aria-label="Main navigation">
-    <ul class="nav-list cluster">
+    <ul class="cluster">
       <li><a href="/docs">Docs</a></li>
       <li><a href="/components">Components</a></li>
       <li><a href="/examples">Examples</a></li>
@@ -16,7 +17,7 @@ It removes native list chrome but does not force a direction. Combine it with la
   </nav>
   <h2>Documentation</h2>
   <nav aria-label="Documentation">
-    <ul class="nav-list stack">
+    <ul class="nav-list">
       <li><a href="/docs/getting-started" aria-current="page">Getting started</a></li>
       <li><a href="/docs/tokens">Tokens</a></li>
       <li><a href="/docs/layout">Layout</a></li>
@@ -26,14 +27,6 @@ It removes native list chrome but does not force a direction. Combine it with la
 </div>
 ```
 
-Use `.nav-list` for:
-
-- header navigation
-- side navigation
-- footer navigation
-- tab-like navigation lists
-- documentation navigation
-
 Do not reset every list inside `nav`.
 
 ```css
@@ -51,7 +44,7 @@ Prefer an explicit pattern class.
 
 ```html demo
 <nav aria-label="Footer">
-  <ul class="nav-list cluster">
+  <ul class="cluster">
     <li><a href="/privacy">Privacy</a></li>
     <li><a href="/terms">Terms</a></li>
     <li><a href="/contact">Contact</a></li>
@@ -69,7 +62,7 @@ Header navigation is usually a composition of landmarks, layout primitives, and
     <a class="brand" href="/">Actual CSS</a>
 
     <nav aria-label="Main navigation">
-      <ul class="nav-list cluster">
+      <ul class="cluster">
         <li><a href="/docs">Docs</a></li>
         <li><a href="/components">Components</a></li>
         <li><a href="/examples">Examples</a></li>
@@ -85,8 +78,7 @@ In this example:
 - `.center` constrains the content.
 - `.cluster` arranges the brand and navigation.
 - `nav` provides navigation semantics.
-- `.nav-list` normalizes the navigation list.
-- the inner `.cluster` arranges navigation items horizontally.
+- the inner `.cluster` removes the list chrome and arranges the links horizontally.
 
 A project may add `.site-header` when it needs a visual shell.
 
@@ -106,7 +98,7 @@ A project may add `.site-header` when it needs a visual shell.
   <aside class="shell-sidebar-nav" aria-label="Primary">
     <a class="navbar-brand" href="#"><span class="avatar primary"><abbr>AC</abbr></span> Product</a>
     <nav aria-label="Primary">
-      <ul class="nav-list stack">
+      <ul class="nav-list">
         <li><a class="nav-link" href="#" aria-current="page">Overview</a></li>
         <li><a class="nav-link" href="#">Settings</a></li>
       </ul>
@@ -167,7 +159,7 @@ Side navigation is usually a `.nav-list` composed with `.stack`.
 ```html demo
 <aside>
   <nav aria-label="Documentation">
-    <ul class="nav-list stack">
+    <ul class="nav-list">
       <li><a href="/docs/getting-started" aria-current="page">Getting started</a></li>
       <li><a href="/docs/tokens">Tokens</a></li>
       <li><a href="/docs/layout">Layout</a></li>
@@ -182,7 +174,7 @@ A project may add `.side-nav` only when it needs specific visual behavior such a
 ```html demo
 <aside class="side-nav">
   <nav aria-label="Documentation">
-    <ul class="nav-list stack">
+    <ul class="nav-list">
       <li><a href="/docs/getting-started" aria-current="page">Getting started</a></li>
       <li><a href="/docs/tokens">Tokens</a></li>
       <li><a href="/docs/layout">Layout</a></li>
@@ -206,30 +198,8 @@ A project may add `.side-nav` only when it needs specific visual behavior such a
 }
 ```
 
-### Optional Navigation Link Styling
-
-`.nav-list` can stay purely structural. If the framework wants navigation links to have a default hit area and active state, this can be added as a lightweight visual pattern.
-
-```css
-.nav-list a {
-  display: flex;
-  align-items: center;
-  gap: var(--space-20);
-  min-block-size: 2rem;
-  padding-inline: var(--space-20);
-  border-radius: var(--radius-sm);
-  color: inherit;
-  text-decoration: none;
-}
-
-.nav-list a:hover {
-  background: var(--surface-subtle);
-}
-
-.nav-list a[aria-current="page"] {
-  background: var(--surface-subtle);
-  font-weight: 600;
-}
-```
+### Link Styling
 
-Keep this separate from layout primitives. `.cluster` and `.stack` should not style links.
+`.nav-link` gives a link its hit area, hover fill and `aria-current` state, in a
+`.cluster` row or a `.nav-list` (see [Navbar](../components/navbar.md)). Set
+`--gap` on a `.nav-list` to space its rows differently.

package/docs/pages/patterns/overview.md

@@ -22,9 +22,8 @@ Use patterns when a semantic element needs a small amount of normalization befor
 Patterns often compose with layout primitives.
 
 ```html
-<menu class="actions cluster">...</menu>
-<ul class="nav-list cluster">...</ul>
-<ul class="nav-list stack">...</ul>
+<menu class="cluster">...</menu>
+<ul class="nav-list">...</ul>
 <section class="grid">...</section>
 ```
 
@@ -51,7 +50,7 @@ Avoid putting semantic resets into layout primitives.
 If list chrome should be removed, use an explicit pattern.
 
 ```html demo
-<ul class="nav-list stack">
+<ul class="nav-list">
   <li><a href="/docs">Docs</a></li>
   <li><a href="/components">Components</a></li>
 </ul>

package/docs/pages/utilities/flex.md

@@ -6,24 +6,25 @@ Small flex helpers for grow behavior and other one-line needs.
 
 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.                        |
+| 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`.        |
+| `.items-baseline` | Aligns children on their first text baseline; 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.                |
+| Class                            | Description                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `.justify-content-start`         | `justify-content: flex-start` on the element itself.    |
+| `.justify-content-center`        | `justify-content: center` on the element itself.        |
+| `.justify-content-end`           | `justify-content: flex-end` on the element itself.      |
+| `.justify-content-space-between` | `justify-content: space-between` on the element itself. |
+| `.flex-wrap`                     | `flex-wrap: wrap` on any flex container.                |
+| `.flex-nowrap`                   | `flex-wrap: nowrap` on any flex container.              |
 
 ## Grow
 
@@ -66,14 +67,24 @@ Use `.items-start` on flex or grid layouts when children should keep their natur
 
 Use `.items-center` when a flex or grid layout should center its children on the cross axis. Use `.items-end` when children should align to the block-end edge.
 
+Use `.items-baseline` when a row mixes text sizes — a price and its period, a name and a timestamp — so the words share one line instead of their boxes sharing a center.
+
+```html demo
+<p class="cluster items-baseline">
+  <strong style="font-size: 2rem">$29</strong>
+  <span class="muted">/ month</span>
+</p>
+```
+
 These helpers work by setting a custom property that participating components read,
 so they also apply inside a component's own grid anatomy rather than only on plain
 flex containers:
 
-- `.items-start` / `.items-center` / `.items-end` set `--items-align`, read by `.alert` and `.card`.
+- `.items-start` / `.items-center` / `.items-end` / `.items-baseline` set `--items-align`, read by `.alert` and `.card`.
 - `.text-start` / `.text-center` / `.text-end` set `--text-align`, read by `.table` cells.
-- `.justify-content-*` (utilities/extra) set `--cluster-justify`, read by `.cluster`.
-- `.flex-wrap` / `.flex-nowrap` (utilities/extra) set `flex-wrap` directly on any flex container.
+
+`.justify-content-*` and `.flex-wrap` / `.flex-nowrap` (utilities/extra) set the property
+directly, so they never reach a nested `.cluster`.
 
 Set the property directly when you need a value the helpers do not ship.
 
@@ -107,6 +118,5 @@ Always mark it `aria-hidden="true"` — it is a visual separator, not content.
 
 ## CSS hooks
 
-- `--items-align` — cross-axis alignment, set by `.items-start` / `.items-center` / `.items-end`.
+- `--items-align` — cross-axis alignment, set by the `.items-*` helpers.
 - `--text-align` — text alignment, set by `.text-start` / `.text-center` / `.text-end`.
-- `--cluster-justify` — main-axis distribution, set by the optional `.justify-content-*` helpers and read by `.cluster`.

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

@@ -29,7 +29,7 @@ one line (`.badge`). To stop a layout primitive from wrapping — for example to
 force a `.cluster` onto a single row — set `--cluster-wrap: nowrap`.
 
 ```html demo
-<div class="cluster compact" style="--cluster-wrap: nowrap;">
+<div class="cluster tight" style="--cluster-wrap: nowrap;">
   <select class="select sm fit" aria-label="Segment">
     <option>All segments</option>
   </select>

package/docs/pages/utilities/spacing.md

@@ -48,9 +48,10 @@ Override the default gap from layout primitives (`.stack`, `.cluster`, `.grid`):
 - `.gap-none` → `gap: 0`
 
 `.gap-none` sets the element's own gap directly and does not change `--gap`
-for nested layouts. For a denser or roomier rhythm, use the `.compact` /
-`.spacious` density contexts, or set the `gap` property on the instance when the
-change must stop there.
+for nested layouts. For a tighter or looser rhythm alone — closer items, without
+smaller controls — use `.tight` / `.loose`; `.compact` / `.spacious` also change
+padding and control size. Set the `gap` property on the instance when the change
+must stop there.
 
 `--gap` defines the contextual rhythm; `.gap-context` applies that rhythm to a
 container that does not already consume `--gap`. The layout primitives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.2",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/lekoala/actual-css.git"
   },
-  "homepage": "https://github.com/lekoala/actual-css",
+  "homepage": "https://lekoala.github.io/actual-css/",
   "bugs": {
     "url": "https://github.com/lekoala/actual-css/issues"
   },

package/reserved-classes.json

@@ -1,6 +1,5 @@
 [
   "accordion",
-  "actions",
   "admonition",
   "alert",
   "alert-body",
@@ -56,7 +55,6 @@
   "cursor-pointer",
   "danger",
   "data-list",
-  "dialog-confirmation",
   "dialog-icon",
   "display-block",
   "display-flex",
@@ -110,6 +108,7 @@
   "intent-color",
   "is-open",
   "is-static",
+  "items-baseline",
   "items-center",
   "items-end",
   "items-start",
@@ -132,6 +131,7 @@
   "list-item-title",
   "list-item-trailing",
   "list-reset",
+  "loose",
   "margin-block-end-auto",
   "margin-block-start-auto",
   "margin-inline-auto",
@@ -159,7 +159,6 @@
   "nav-list",
   "navbar",
   "navbar-brand",
-  "navbar-nav",
   "needs-validation",
   "neutral",
   "otp",
@@ -248,6 +247,7 @@
   "text-uppercase",
   "text-wrap",
   "textarea",
+  "tight",
   "tooltip",
   "topbar",
   "touch-target",

package/skills/actual-css/references/enhancements.md

@@ -40,16 +40,19 @@ the title in the content wrapper's direct `<header>`. The close button is then
 anchored to the surface, and the header reserves room so the title cannot run
 under it. A `.close` that is a direct child of the chrome header is that same
 corner overlay, and that header reserves room for it too. Put actions in the
-wrapper's `<footer>`.
+wrapper's `<footer>` and compose its row in markup
+(`<footer class="cluster justify-content-end">`); the modal and drawer footers
+have no layout of their own.
 
 Use `.bleed` on that direct header when it needs a contrasting full-width band;
 the wrapper relays the modal padding so the band reaches the surface edges while
-its contents keep the normal inset. In `.dialog-confirmation`, keep the icon and
-the text header as the media object's two children; the component centers the
-header's first heading on the icon while following copy stays in that text
-column. For a trailing icon, use the confirmation's direct header as a
-non-wrapping split `.cluster`, with `.grow` on the text group. Do not compensate
-heading alignment with a literal margin.
+its contents keep the normal inset. A confirmation is composition, not a
+variant: a `.media` row with a leading `.dialog-icon` and the text column (its
+first heading centers on the icon, following copy stays in that column), then a
+`<footer class="bleed background-subtle cluster justify-content-space-between">` action
+band with the cancel-style action first. For a trailing icon, use the wrapper's
+direct header as a non-wrapping split `.cluster`, with `.grow` on the text
+group. Do not compensate heading alignment with a literal margin.
 
 Do not turn the dialog heading into an `.alert` to obtain icon or surface
 styling. Compose `.dialog-icon` with `.media` for a leading title icon; reserve

package/src/cli/actual-css.js

@@ -8,10 +8,11 @@ function usage() {
   return [
     "actual-css bundle INPUT --out FILE [--minify]",
     "actual-css design [--theme FILE] [--name NAME] --out DIR",
+    "actual-css contrast [--theme FILE] [--name NAME]",
     "",
     "  -o, --out FILE   write the bundle to FILE / the export to DIR (required)",
     "      --minify     collapse comments and whitespace",
-    "      --theme FILE export this [data-theme] file instead of the default theme",
+    "      --theme FILE read this [data-theme] file instead of the default theme",
     "      --name NAME  the data-theme name, when the file declares several",
     "  -h, --help       show this message",
     "      --version    print the actual-css version",
@@ -23,7 +24,13 @@ function usage() {
     "",
     "design: export a theme's tokens for Figma and Penpot, plus Button, Input, Badge,",
     "Alert and Card measured in headless Chrome and a Penpot plugin that builds them.",
-    "Needs Bun (bunx actual-css design ...).",
+    "Needs Bun (bunx --bun actual-css design ...).",
+    "",
+    "contrast: measure the pairs a theme tunes by hand in headless Chrome, in every",
+    "scheme it declares: soft ink on its resting and hovered fill, the focus line on",
+    "--surface and --surface-solid, the invalid-field focus line, and the inverse",
+    "text. Exits 1 when a pair misses its threshold. Needs Bun (bunx --bun actual-css",
+    "contrast ...).",
   ].join("\n");
 }
 
@@ -43,8 +50,8 @@ function parseArgs(argv) {
     return { version: true };
   }
 
-  if (command === "design") {
-    return parseDesignArgs(rest);
+  if (command === "design" || command === "contrast") {
+    return parseThemeArgs(command, rest);
   }
 
   if (command !== "bundle") {
@@ -101,9 +108,10 @@ function parseArgs(argv) {
   return { help: false, command: "bundle", input, out, minify };
 }
 
-function parseDesignArgs(rest) {
-  const options = { help: false, command: "design", themeFile: null, name: null, out: "" };
-  const valued = { "--theme": "themeFile", "--name": "name", "--out": "out", "-o": "out" };
+function parseThemeArgs(command, rest) {
+  const options = { help: false, command, themeFile: null, name: null, out: "" };
+  const valued = { "--theme": "themeFile", "--name": "name" };
+  if (command === "design") Object.assign(valued, { "--out": "out", "-o": "out" });
 
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
@@ -116,23 +124,40 @@ function parseDesignArgs(rest) {
     i += 1;
   }
 
-  if (!options.out) throw new Error("Missing required --out DIR option.");
+  if (command === "design" && !options.out) throw new Error("Missing required --out DIR option.");
   return options;
 }
 
-async function design({ themeFile, name, out }) {
-  // Checked before the import: under Node the module does not even parse
-  // (`await using`), and `bundle` must stay usable there.
+/* Checked before the tooling import: under Node those modules do not even
+   parse (`await using`), and `bundle` must stay usable there. The shebang is
+   Node for that reason, so plain `bunx` honors it and lands here: --bun is
+   what makes Bun run the script. */
+function requireBun(command) {
   if (typeof Bun === "undefined") {
     throw new Error(
-      "actual-css design needs Bun: it reads the theme in headless Chrome through Bun.WebView. Run it with bunx.",
+      `actual-css ${command} needs Bun: it reads the theme in headless Chrome through Bun.WebView. Run it with bunx --bun actual-css ${command} ...`,
     );
   }
+}
+
+async function design({ themeFile, name, out }) {
+  requireBun("design");
   const { exportDesign } = await import("../tooling/design-export.js");
   const written = await exportDesign({ themeFile, name, out: resolve(out) });
   console.log(`Exported ${written.length} files to ${resolve(out)}`);
 }
 
+async function contrast({ themeFile, name }) {
+  requireBun("contrast");
+  const { formatContrast, measureThemeFile } = await import("../tooling/theme-contrast.js");
+  const { text, misses } = formatContrast(await measureThemeFile({ themeFile, name }));
+  console.log(text);
+  if (misses > 0) {
+    console.error(`\n${misses} pair${misses === 1 ? "" : "s"} under threshold.`);
+    process.exitCode = 1;
+  }
+}
+
 async function bundle({ input, out, minify }) {
   const inputPath = resolve(input);
   const outputPath = resolve(out);
@@ -167,7 +192,8 @@ async function main() {
     return;
   }
 
-  await (args.command === "design" ? design(args) : bundle(args));
+  const commands = { bundle, contrast, design };
+  await commands[args.command](args);
 }
 
 main().catch((error) => {

package/src/css/components/avatar.css

@@ -198,19 +198,26 @@ a.avatar[aria-disabled="true"] {
   --avatar-stack-font-size: var(--font-size-lg);
 }
 
-@supports selector(:has(> .avatar)) {
-  .avatar-stack:has(> .avatar.sm) {
-    --avatar-stack-size: 1.75rem;
-    --avatar-stack-font-size: var(--font-size-xs);
-  }
+/* Infer the stack scale from its avatars. Progressive: without :has() the
+   explicit .avatar-stack.sm/.lg classes and the default size still size the
+   group, only the inference is lost. */
+.avatar-stack:has(> .avatar.sm) {
+  --avatar-stack-size: 1.75rem;
+  --avatar-stack-font-size: var(--font-size-xs);
+}
 
-  .avatar-stack:has(> .avatar.lg) {
-    --avatar-stack-size: 3rem;
-    --avatar-stack-font-size: var(--font-size-lg);
-  }
+.avatar-stack:has(> .avatar.lg) {
+  --avatar-stack-size: 3rem;
+  --avatar-stack-font-size: var(--font-size-lg);
 }
 
+/* Overlapping avatars hide their neighbour: a translucent fill (--surface-subtle
+   on a glass palette) would show the next avatar's edge through it, most of all
+   when hover raises one above the other. The fill is layered over the opaque
+   role; on an opaque fill the base never shows. */
 .avatar-stack > .avatar {
+  background-color: var(--surface-opaque);
+  background-image: linear-gradient(var(--avatar-bg), var(--avatar-bg));
   box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface-opaque);
 }
 

package/src/css/components/badge.css

@@ -169,10 +169,6 @@
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  :is(a.badge, button.badge):is(.solid, :empty) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
-  }
-
   :is(a.badge, button.badge):where(:not(.solid, .outline, :empty)) {
     --badge-default-hover-bg: color-mix(
       in oklab,
@@ -199,7 +195,7 @@
   :where(:disabled, [aria-disabled="true"])
 ):hover {
   /* Huge inset spread paints the overlay over the pill radius (see button.css). */
-  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+  box-shadow: inset 0 0 0 999px var(--hover-overlay-solid, var(--hover-overlay));
 }
 
 button.badge {

package/src/css/components/button.css

@@ -28,7 +28,6 @@
  * --btn-bg
  * --btn-fg
  * --btn-border
- * --btn-default-hover-bg
  * --btn-border-block-end-color
  * --btn-border-block-end-width
  * --btn-border-block
@@ -54,9 +53,8 @@
   --btn-bg: var(--ui-bg, var(--btn-default-bg, var(--intent, var(--neutral))));
   --btn-fg: var(--ui-fg, var(--btn-default-fg, var(--intent-fg, var(--neutral-fg))));
   --btn-border: var(--ui-border, var(--btn-default-border, transparent));
-  --btn-default-hover-bg: var(--btn-bg);
   --btn-radius: var(--radius);
-  --btn-hover-overlay: var(--hover-overlay, rgb(0 0 0 / 0.08));
+  --btn-hover-overlay: var(--hover-overlay-solid, var(--hover-overlay));
   --btn-border-block: calc(
     var(--border-width) +
     var(--btn-border-block-end-width, var(--border-width))
@@ -136,10 +134,6 @@
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  .btn {
-    --btn-default-hover-bg: color-mix(in oklch, var(--btn-bg) 88%, black);
-  }
-
   .btn.soft {
     --ui-hover-bg: color-mix(
       in oklab,
@@ -155,9 +149,9 @@
 }
 
 /* The .soft/.outline/.ghost hover recipe (--ui-hover-bg) is set locally above;
-   the overlay darkening for solid/soft is .btn-specific. */
+   the overlay darkening for solid is .btn-specific. */
 .btn:not(:where(:disabled, [aria-disabled="true"])):hover {
-  background: var(--ui-hover-bg, var(--btn-default-hover-bg));
+  background: var(--ui-hover-bg, var(--btn-bg));
   /* Huge inset spread paints the overlay over any border-radius without a
      pseudo-element; a plain background would replace the fill instead of
      darkening it. */

package/src/css/components/card.css

@@ -4,11 +4,11 @@
  * Docs: docs/pages/components/card.md
  *
  * Surface, border, radius, padding, density, and elevation stay local here.
- * Direct header/footer children are structural slots; a direct footer is
- * anchored to the card's bottom edge when extra block space is available (so
- * price/action rows align across equal-height cards in a grid). A bare card
- * owns its direct-child rhythm; a layout primitive on the same element takes
- * over that layout. Page layout remains the job of markup and layout
+ * Direct header/footer children are structural slots with a default split row;
+ * a direct footer is anchored to the card's bottom edge when extra block space
+ * is available (so price/action rows align across equal-height cards in a
+ * grid). A bare card owns its direct-child rhythm and its slot rows; a layout
+ * primitive on the card or on a slot takes over that layout. Page layout remains the job of markup and layout
  * primitives outside the card.
  *
  * Public hooks:
@@ -46,6 +46,9 @@
 
 .card {
   --card-pad: var(--space-40);
+  /* Local anatomy, like the padding. Never var(--gap): that token is
+     inherited, so the --gap of a parent grid became the rhythm inside every
+     card (+79px per card on a 38px grid). */
   --card-gap: var(--space-30);
   --card-radius: var(--radius-lg);
   --card-max-inline-size: none;
@@ -87,7 +90,11 @@
   margin-block: 0;
 }
 
-.card > :where(header, footer) {
+/* The slot row is a convenience default, not anatomy: like the root box it
+   lives at zero specificity, so a primitive, role or utility on the slot
+   (.cluster, .media, .form-actions, .justify-content-*) replaces it instead of
+   losing to components/ on source order. */
+:where(.card > header, .card > footer) {
   display: flex;
   flex-wrap: wrap;
   align-items: var(--items-align, center);
@@ -96,15 +103,15 @@
   min-inline-size: 0;
 }
 
+:where(.card > header) {
+  align-items: var(--items-align, flex-start);
+}
+
 .card > :where(header, footer) > * {
   min-inline-size: 0;
   margin-block: 0;
 }
 
-.card > header {
-  align-items: var(--items-align, flex-start);
-}
-
 /* A direct footer is pinned to the bottom when the card has free space.
    Specificity beats .stack > * so a .card.stack keeps this contract. */
 .card > footer {
@@ -119,6 +126,7 @@
 }
 .card.compact {
   --card-pad: var(--space-20);
+  --card-gap: var(--space-20);
 }
 
 @media print {

package/src/css/components/chat.css

@@ -94,9 +94,8 @@
 }
 
 /* Remove the reserved avatar gutter when a message has no avatar. This is a
-   cosmetic enhancement; the two-column baseline remains fully readable. */
-@supports selector(:has(*)) {
-  .chat:not(:has(> .chat-avatar)) {
-    column-gap: 0;
-  }
+   cosmetic enhancement; the two-column baseline remains fully readable, and a
+   browser without :has() drops only this rule. */
+.chat:not(:has(> .chat-avatar)) {
+  column-gap: 0;
 }