use-wc 1.0.0-pre.65 → 1.0.0-pre.66

package/dist/design-system.css

@@ -1790,45 +1790,19 @@
   }
 }
 
-/* Card — `use-card` is a theme-only tag, styled like `use-field`/`use-selector` with no
-   registration behind it: an author can still add `role`/ARIA directly on `<use-card>` for real
-   semantics, the same as any other element, just not for free the way `<article>`/`<section>`
-   give an implicit landmark. It supplies the surface chrome (background/border/radius/shadow);
-   `shell.css` (declared later, so it wins on `display`) makes it a flex column, and
-   `surface.css` styles its header/footer/figure regions. `.outlined` drops the shadow and keeps
-   the border, for a flatter, less "floating" card. */
-@layer use-theme.card {
-  use-card {
-    display: block;
-    overflow: hidden;
-    background: var(--usewc-color-surface-background);
-    border: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-border);
-    border-radius: var(--usewc-effect-surface-border-radius);
-    box-shadow: var(--usewc-effect-surface-shadow);
-    color: var(--usewc-color-document-text);
-
-    use-theme-escape & {
-      all: revert-layer;
-    }
-  }
-
-  use-card.outlined {
-    box-shadow: none;
-
-    use-theme-escape & {
-      all: revert-layer;
-    }
-  }
-}
-
 /* Dialog — a native `<dialog>` already provides the overlay mechanics (top-layer promotion,
    `::backdrop`, focus trapping, Esc-to-close) for free once shown with `.showModal()`. Themed by
    default, like the rest of this family's native elements — `:not(.appearance-native)` is the
    escape hatch, not an opt-in class. The default look centers (the UA default for `<dialog>`, so
    no extra positioning is needed) and constrains its size; `.drawer` is the one variant that
    needs an opt-in class, since it pins to a block-size-100dvh edge panel instead — the positioning
-   itself, not just the chrome, changes. That's what makes `use-shell-fill` (see `shell.css`)
-   matter for a drawer specifically — the body scrolls while header/footer stay put. */
+   itself, not just the chrome, changes.
+
+   Chrome only — a `<dialog>` gets no layout from this family. Nest a `use-layout` variant
+   inside it (`layout.css`) to arrange a header / body / footer, which leaves the element's
+   UA-controlled `display` alone and lets one dialog host any variant. That nested layout is
+   what makes a drawer work: its `use-layout[fill]` body scrolls while header and footer stay
+   put over the full 100dvh. */
 @layer use-theme.dialog {
   dialog:not(.appearance-native) {
     padding: 0;
@@ -1838,8 +1812,8 @@
     background: var(--usewc-color-surface-background);
     box-shadow: var(--usewc-effect-surface-shadow);
     color: var(--usewc-color-document-text);
-    inline-size: min(32rem, 100% - var(--usewc-space-surface-padding) * 2);
-    max-block-size: min(80dvh, 100% - var(--usewc-space-surface-padding) * 2);
+    inline-size: min(32rem, 100% - var(--usewc-layout-surface-padding) * 2);
+    max-block-size: min(80dvh, 100% - var(--usewc-layout-surface-padding) * 2);
 
     use-theme-escape & {
       all: revert-layer;
@@ -1886,7 +1860,8 @@
    is already a specific enough signal on its own). Anchor positioning (`anchor-name`/
    `position-anchor`) is left to the author, the same way plain `[popover]` elements work
    otherwise — this only replaces the UA default chrome with the shared `surface` tokens,
-   matching `dialog`/`use-card`.
+   matching `dialog` / `use-layout.card`. Chrome only, like `dialog`: nest a `use-layout`
+   variant inside to arrange a header / body / footer (`layout.css`).
 
    The `::backdrop` is deliberately left at its transparent UA default: a `[popover]` at
    `popover="auto"` is non-modal — the page stays interactive and an outside click dismisses it
@@ -1907,8 +1882,46 @@
     background: var(--usewc-color-surface-background);
     box-shadow: var(--usewc-effect-surface-shadow);
     color: var(--usewc-color-document-text);
-    max-inline-size: min(24rem, 100% - var(--usewc-space-surface-padding) * 2);
-    max-block-size: min(80dvh, 100% - var(--usewc-space-surface-padding) * 2);
+    max-inline-size: min(24rem, 100% - var(--usewc-layout-surface-padding) * 2);
+    max-block-size: min(80dvh, 100% - var(--usewc-layout-surface-padding) * 2);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+}
+
+/* Anchored surface positioning — a modal `<dialog>` or `[popover]` positioned against an
+   invoker (wrapped in `use-anchored`) keeps a small gap from it and stays willing to flip to
+   the other side on scroll. An anchored surface carries no region layout of its own — nest a
+   `use-layout` variant inside it, the same as any other `dialog`/`[popover]` (`layout.css`). */
+@layer use-theme.anchored {
+  /* An anchored surface keeps a small gap from its anchor, the same convention `use-menu`
+     follows in `menu.css`. Scoped to `use-anchored`'s direct child — the one reliable "this is
+     anchored" signal — so a standalone `[popover]` or modal `<dialog>` elsewhere keeps its UA
+     centering. `margin-block` (both edges) so the gap survives a `position-try` flip to the
+     other side. The open-state check mirrors the positioning util: `:popover-open` for a
+     popover, `[open]` for a `<dialog>`.
+
+     The `max-block-size` override is what lets it flip on scroll instead of shrinking.
+     `popover.css` / `dialog.css` cap the surface at `min(80dvh, 100% - <pad>)`, where `100%`
+     is the free space on the anchor's *current* side — so as the anchor nears a viewport edge
+     that cap shrinks with it, the surface never overflows, and `position-try` never sees the
+     overflow it needs to flip (or to flip back). Reworking the cap to
+     `min(80dvh, max(45dvh, 100% - <pad>))` keeps the surface willing to be at least 45dvh: a
+     side smaller than that overflows and triggers a flip, and since sibling sides sum to nearly
+     the full viewport a 45dvh surface always fits the other one, so the flip lands on-screen.
+     Where a side has more than 45dvh the `100%` term still tracks it, up to 80dvh. Left at the
+     default `position-try-order` (not `most-block-size`) so the surface stays on the block-end
+     (below) side whenever the content fits there, only flipping above when it doesn't — rather
+     than jumping to whichever side merely has more room. `overflow` (otherwise `hidden`)
+     scrolls the content once the cap bites; a surface with a `[fill]` region already scrolls
+     that region (`layout.css`), so the surface itself never overflows there and this `overflow`
+     is inert. */
+  use-anchored > :is(dialog, [popover]):not(use-menu, .appearance-native):is([open], :popover-open) {
+    margin-block: var(--usewc-layout-surface-anchor-offset);
+    max-block-size: min(80dvh, max(45dvh, 100% - var(--usewc-layout-surface-padding) * 2));
+    overflow: auto;
 
     use-theme-escape & {
       all: revert-layer;
@@ -1916,104 +1929,351 @@
   }
 }
 
-/* Shell — `use-shell` is a theme-only tag (no registration, styled by tag name like
-   `use-field`/`use-selector`/`use-card`) providing a generic flex-column-with-one-growing-region
-   mechanic, usable anywhere in an app that wants it — not specific to card/dialog/popover
-   surfaces. Every direct child defaults to `flex: 0 0 auto` (fixed, doesn't grow or shrink) and
-   `min-block-size: 0`; `use-shell-fill` is the one region that grows to fill the remaining
-   space and scrolls its own overflow, wherever it appears.
-
-   The three surface hosts (`dialog`, `use-card`, `[popover]`) participate in the same mechanic
-   directly — no `use-shell` wrapper needed inside them — since they're already the flex
-   container an author nests header/use-shell-fill/footer straight into. This layer is declared
-   after `card.css`/`dialog.css`/`popover.css`, so its `display: flex` wins over their own
-   `display: block` for `use-card` (dialog/popover don't set `display` themselves, so there's
-   nothing to override there).
-
-   `dialog` and `[popover]` are scoped to `:modal`/`:popover-open` here, unlike the chrome rules
-   in `dialog.css`/`popover.css` — a closed `<dialog>`/`[popover]` is `display: none` by the UA
-   stylesheet, and normal-importance author CSS always beats normal-importance UA CSS regardless
-   of layers, so an unconditional `display: flex` here would un-hide a closed one. Chrome
-   properties (background/border/shadow/sizing) don't have this problem — they're inert on a
-   `display: none` element either way — only `display` itself does. */
-@layer use-theme.shell {
-  use-shell,
-  dialog:modal:not(.appearance-native),
-  use-card,
-  [popover]:popover-open:not(use-menu, .appearance-native) {
+/* Flex layout — `use-layout` is a theme-only tag (no custom element registration, styled by
+   tag name like `use-field`/`use-selector`), providing a configurable flex container:
+   direction, alignment, justification, a named gap scale, wrapping, and inline vs block
+   display, all driven by attributes. It defaults to a column, since stacking is the common
+   case for the page/panel structure it's used for; set `direction="row"` for a row.
+
+   When a direct child `use-layout` carries `fill`, that child grows to consume the remaining
+   space and the other children are pinned so they can't shrink; with no such child,
+   `use-layout` is a bare flex container that leaves its children alone. `fill` is read *only*
+   on a `use-layout`, and only as a direct child, so an `<svg fill="…">` or an author's own
+   `fill` attribute anywhere in the tree is untouched — no exclusion list needed.
+
+   Four variant classes name what the container *is*, and its semantic `<figure>` / `<header>` /
+   `<main>` / `<footer>` regions are arranged to match:
+
+     use-layout.page      an app frame      — ruled topbar and footer, roomy
+     use-layout.prose     a document        — stacked title/byline header, measure-capped, loose
+     use-layout.message   a chat or comment — an avatar rail with the regions beside it, compact
+     use-layout.card      a panel           — avatar + hgroup + actions, end-aligned ruled
+                                              footer, compact, plus the chrome at end of file
+
+   All four regions are optional and any combination lays out correctly: `header` + `footer` is a
+   confirm dialog, `header` + `main` a bare card, `main` alone a grouped chat message. Source
+   order is canonical — figure, header, main, footer — and a variant may re-position regions
+   visually but never asks an author to reorder markup.
+
+   Rather than four arrangements, a variant class sets *only* a density scale on itself
+   (`--usewc-layout-region-padding`, `-gap`, `-avatar-size`, `--usewc-layout-header-rule`,
+   `-footer-rule`, `--usewc-layout-footer-justify`, `--usewc-layout-measure`) and one generic set
+   of region rules reads them. Just three arrangements can't be said in a property — prose's
+   column header, message's rail, message's inline hgroup — and those follow as structural
+   overrides. The mechanic isn't repeated per variant either: a `use-layout.page` is a
+   `use-layout`, so the base pin/grow rules above already cover it.
+
+   Every selector stays compound (`use-layout.page`, never a bare `.page`) so none of these
+   common words can collide with an author's own class of the same name.
+
+   `dialog` and `[popover]` deliberately carry no layout here — they are chrome only
+   (`dialog.css`, `popover.css`). Nest a `use-layout` inside one to lay it out, which keeps the
+   overlay element's UA-controlled `display` alone and lets a dialog host any variant rather
+   than being hard-wired to the card's arrangement.
+
+   Every rule carries the `use-theme-escape` revert so an escaped subtree drops back to
+   unstyled markup, the same as the rest of this family. */
+@layer use-theme.layout {
+  use-layout {
     display: flex;
     flex-direction: column;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[inline] {
+    display: inline-flex;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[direction="row"] {
+    flex-direction: row;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[wrap] {
+    flex-wrap: wrap;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[align="start"] {
+    align-items: start;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[align="center"] {
+    align-items: center;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[align="end"] {
+    align-items: end;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[align="stretch"] {
+    align-items: stretch;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[justify="start"] {
+    justify-content: start;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[justify="center"] {
+    justify-content: center;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[justify="end"] {
+    justify-content: end;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[justify="space-between"] {
+    justify-content: space-between;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[justify="space-around"] {
+    justify-content: space-around;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[gap="xsmall"] {
+    gap: var(--usewc-layout-flex-gap-xsmall);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[gap="small"] {
+    gap: var(--usewc-layout-flex-gap-small);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[gap="medium"] {
+    gap: var(--usewc-layout-flex-gap-medium);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[gap="large"] {
+    gap: var(--usewc-layout-flex-gap-large);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[gap="xlarge"] {
+    gap: var(--usewc-layout-flex-gap-xlarge);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[gap="super"] {
+    gap: var(--usewc-layout-flex-gap-super);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout[fill],
+  use-layout > use-layout[fill] {
+    flex: 1 1 auto;
     min-block-size: 0;
+    min-inline-size: 0;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  use-shell > :not(use-shell-fill),
-  dialog:modal:not(.appearance-native) > :not(use-shell-fill),
-  use-card > :not(use-shell-fill),
-  [popover]:popover-open:not(use-menu, .appearance-native) > :not(use-shell-fill) {
+  use-layout:has(> use-layout[fill]) > :not(use-layout[fill]) {
     flex: 0 0 auto;
     min-block-size: 0;
+    min-inline-size: 0;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  use-shell-fill {
-    display: block;
-    flex: 1 1 auto;
+  /* ── Variant density ────────────────────────────────────────────────────────────────────────
+     A variant class sets its own scale and nothing else; the generic region rules below read
+     these properties. Keeping the arrangement in one ruleset rather than four means a future
+     region variant (a tabbed header, a search header, a toolbar) can be written as a plain
+     `header.tabbed` and win on specificity, instead of having to out-specify a
+     `use-layout.card > header`. That's also why every generic rule scopes its container list in
+     `:where()` — it contributes no specificity, so those rules sit at the weight of a bare
+     `header` and are trivially overridden. Between themselves the generic and structural rules
+     order by source position, later winning. */
+  use-layout.page {
+    --usewc-layout-region-padding: var(--usewc-layout-page-padding);
+    --usewc-layout-region-padding-block: var(--usewc-layout-page-padding-block);
+    --usewc-layout-region-gap: var(--usewc-layout-page-gap);
+    --usewc-layout-region-avatar-size: var(--usewc-layout-page-avatar-size);
+    --usewc-layout-header-rule: var(--usewc-color-region-border);
+    --usewc-layout-footer-rule: var(--usewc-color-region-border);
+    --usewc-layout-footer-justify: space-between;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout.prose {
+    --usewc-layout-region-padding: var(--usewc-layout-prose-padding);
+    --usewc-layout-region-gap: var(--usewc-layout-prose-gap);
+    --usewc-layout-region-avatar-size: var(--usewc-layout-prose-avatar-size);
+    --usewc-layout-measure: var(--usewc-layout-prose-measure);
+    --usewc-layout-footer-rule: var(--usewc-color-region-border);
+    --usewc-layout-footer-justify: flex-start;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout.message {
+    --usewc-layout-region-padding: var(--usewc-layout-message-padding);
+    --usewc-layout-region-gap: var(--usewc-layout-message-gap);
+    --usewc-layout-region-avatar-size: var(--usewc-layout-message-rail);
+    --usewc-layout-footer-justify: flex-start;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout.card {
+    --usewc-layout-region-padding: var(--usewc-layout-card-padding);
+    --usewc-layout-region-gap: var(--usewc-layout-card-gap);
+    --usewc-layout-region-avatar-size: var(--usewc-layout-card-avatar-size);
+    --usewc-layout-footer-rule: var(--usewc-color-region-border);
+    --usewc-layout-footer-justify: flex-end;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* ── Generic regions ────────────────────────────────────────────────────────────────────────
+     One ruleset for all four variants, reading the properties above. A rule colour left unset
+     falls back to `transparent`, so a variant opts into a hairline by naming one rather than by
+     having a rule of its own. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) {
     min-block-size: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > use-layout[fill] {
     overflow: auto;
+    padding: var(--usewc-layout-region-padding);
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
-}
 
-/* Surface regions — header/poster/footer styling shared by the three surface hosts (`dialog`,
-   `use-card`, `[popover]`), scoped to them specifically rather than to bare `use-shell`: this is
-   a surface-family visual convention (the anchored-gap offset, avatar sizing, trailing-action
-   pinning, a footer rule), not something every generic `use-shell` consumer should inherit.
-   Everything here rides on top of `shell.css`'s flex mechanic — this only adds padding, gaps,
-   and per-region treatment. */
-@layer use-theme.surface {
-  /* An anchored surface keeps a small gap from its anchor, the same convention `use-menu`
-     follows in `menu.css`. Scoped to `use-anchored`'s direct child — the one reliable "this is
-     anchored" signal — so a standalone `[popover]` or modal `<dialog>` elsewhere keeps its UA
-     centering. `margin-block` (both edges) so the gap survives a `position-try` flip to the
-     other side. The open-state check mirrors the positioning util: `:popover-open` for a
-     popover, `[open]` for a `<dialog>`.
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > main {
+    padding: var(--usewc-layout-region-padding);
+    max-inline-size: var(--usewc-layout-measure, none);
 
-     The `max-block-size` override is what lets it flip on scroll instead of shrinking.
-     `popover.css` / `dialog.css` cap the surface at `min(80dvh, 100% - <pad>)`, where `100%`
-     is the free space on the anchor's *current* side — so as the anchor nears a viewport edge
-     that cap shrinks with it, the surface never overflows, and `position-try` never sees the
-     overflow it needs to flip (or to flip back). Reworking the cap to
-     `min(80dvh, max(45dvh, 100% - <pad>))` keeps the surface willing to be at least 45dvh: a
-     side smaller than that overflows and triggers a flip, and since sibling sides sum to nearly
-     the full viewport a 45dvh surface always fits the other one, so the flip lands on-screen.
-     Where a side has more than 45dvh the `100%` term still tracks it, up to 80dvh. Left at the
-     default `position-try-order` (not `most-block-size`) so the surface stays on the block-end
-     (below) side whenever the content fits there, only flipping above when it doesn't — rather
-     than jumping to whichever side merely has more room. `overflow` (otherwise `hidden`)
-     scrolls the content once the cap bites; a `use-shell-fill` layout already scrolls its own
-     fill region (`shell.css`), so the surface itself never overflows there and this `overflow`
-     is inert. */
-  use-anchored > :is(dialog, [popover]):not(use-menu, .appearance-native):is([open], :popover-open) {
-    margin-block: var(--usewc-layout-surface-anchor-offset);
-    max-block-size: min(80dvh, max(45dvh, 100% - var(--usewc-space-surface-padding) * 2));
-    overflow: auto;
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* The region owns its outer spacing, so the first and last things in it shed the block margins
+     they'd otherwise stack on top of the padding — a leading `<p>`, `<ul>`, `<ol>` or heading
+     would otherwise push itself away from an edge that's already spaced. Matched by position
+     rather than by tag so it holds for whatever flow content lands there. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
+    > :is(main, use-layout[fill])
+    > :first-child {
+    margin-block-start: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
+    > :is(main, use-layout[fill])
+    > :last-child {
+    margin-block-end: 0;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > figure {
+  /* A header already supplies the block-start padding, so the body region drops its own and the
+     two read as one padded column rather than a double gap under the header. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
+    > header
+    + :is(main, use-layout[fill]) {
+    padding-block-start: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > figure {
     margin: 0;
 
     use-theme-escape & {
@@ -2021,7 +2281,7 @@
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > figure > img {
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > figure > img {
     display: block;
     inline-size: 100%;
     block-size: auto;
@@ -2032,22 +2292,40 @@
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header {
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: var(--usewc-layout-region-gap);
+    padding-block: var(--usewc-layout-region-padding-block, var(--usewc-layout-region-padding));
+    padding-inline: var(--usewc-layout-region-padding);
+    border-block-end: var(--usewc-layout-surface-border) solid var(--usewc-layout-header-rule, transparent);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > footer {
     display: flex;
     align-items: center;
-    gap: var(--usewc-space-surface-gap);
-    padding: var(--usewc-space-surface-padding);
+    justify-content: var(--usewc-layout-footer-justify, flex-end);
+    gap: var(--usewc-layout-region-gap);
+    padding-block: var(--usewc-layout-region-padding-block, var(--usewc-layout-region-padding));
+    padding-inline: var(--usewc-layout-region-padding);
+    border-block-start: var(--usewc-layout-surface-border) solid var(--usewc-layout-footer-rule, transparent);
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header > img.avatar {
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > :is(img.avatar, figure) {
     flex: none;
-    inline-size: var(--usewc-layout-surface-avatar-size);
-    block-size: var(--usewc-layout-surface-avatar-size);
+    inline-size: var(--usewc-layout-region-avatar-size);
+    block-size: var(--usewc-layout-region-avatar-size);
     border-radius: var(--usewc-effect-surface-avatar-border-radius);
+    overflow: hidden;
     object-fit: cover;
 
     use-theme-escape & {
@@ -2055,8 +2333,14 @@
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header > hgroup {
-    flex: 1;
+  /* An `hgroup` is a title stack wherever it turns up in a region — often wrapped in a
+     `<section>` in a topbar — so it's matched by descent rather than as a direct child. Only the
+     one sitting directly in a header grows, since that's what pushes trailing actions to the
+     far end. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) hgroup {
+    display: flex;
+    flex-direction: column;
+    gap: var(--usewc-layout-region-title-gap);
     min-inline-size: 0;
 
     use-theme-escape & {
@@ -2064,48 +2348,194 @@
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native))
-    > header
-    > *:last-child:not(:first-child) {
-    margin-inline-start: auto;
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > header > hgroup {
+    flex: 1;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > use-shell-fill {
-    padding: var(--usewc-space-surface-padding);
+  /* A header and footer are flex containers and an `hgroup` is a flex column, so `gap` is the
+     spacing — a default block margin stacks on top of it and blows the region apart. Headings are
+     matched at any depth, since a topbar routinely nests them a `<section>` and an `<hgroup>`
+     down; `<p>` and friends only need it where they sit directly in the flex flow. Body copy in
+     `<main>` keeps its margins, which is the whole point of a paragraph there. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) > *,
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) hgroup > *,
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
+    > :is(header, footer)
+    :is(h1, h2, h3, h4, h5, h6) {
+    margin-block: 0;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > header + use-shell-fill {
-    padding-block-start: 0;
+  /* A `<section>` inside a header or footer is one cluster of related controls. Two or more of
+     them means the region has distinct ends, so it splits them apart regardless of the variant's
+     default justification. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(header, footer) > section {
+    display: flex;
+    align-items: center;
+    gap: var(--usewc-layout-region-gap);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
+    > :is(header, footer):has(> section ~ section) {
+    justify-content: space-between;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* ── Structural overrides ───────────────────────────────────────────────────────────────────
+     The three arrangements a density property can't express. Same `:where()` weight as the
+     generic rules, winning on source order. */
+
+  /* Prose stacks its header instead of spreading it across a row: an eyebrow, then a title free
+     to wrap, then a byline. It shares `main`'s measure so the two align down the left edge,
+     while a `<figure>` above stays full-bleed to the container. A growing `hgroup` would stretch
+     vertically in a column, so it sizes to content here. */
+  :where(use-layout.prose) > header {
+    flex-direction: column;
+    align-items: start;
+    max-inline-size: var(--usewc-layout-measure);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.prose) > header > hgroup {
+    flex: 0 1 auto;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* A message is the one variant that isn't a column: a fixed avatar rail, then header, body and
+     reactions stacked beside it. It's a grid rather than nested flex so the rail keeps its width
+     when a grouped message omits its header and leaves the rail empty — bodies stay aligned down
+     the feed either way. The container owns the padding, so the regions drop theirs. */
+  use-layout.message {
+    display: grid;
+    grid-template-columns: var(--usewc-layout-message-rail) 1fr;
+    gap: var(--usewc-layout-region-gap);
+    padding: var(--usewc-layout-region-padding);
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native)) > footer {
+  /* The rail is a fixed square that centres whatever it's given — a photo, an `<svg>` glyph, a
+     date badge, a `<div>` of initials — rather than assuming an `<img>`. A photo fills it and
+     crops; anything else keeps its own size and sits in the middle. */
+  :where(use-layout.message) > figure {
     display: flex;
+    grid-column: 1;
+    grid-row: 1 / -1;
     align-items: center;
-    gap: var(--usewc-space-surface-gap);
-    padding: var(--usewc-space-surface-padding);
-    border-block-start: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-footer-border);
+    justify-content: center;
+    inline-size: var(--usewc-layout-message-rail);
+    block-size: var(--usewc-layout-message-rail);
+    overflow: hidden;
+    border-radius: var(--usewc-effect-surface-avatar-border-radius);
+    font-size: calc(var(--usewc-layout-message-rail) * 0.4);
+    line-height: 1;
 
     use-theme-escape & {
       all: revert-layer;
     }
   }
 
-  :is(dialog:not(.appearance-native), use-card, [popover]:not(use-menu, .appearance-native))
-    > footer
-    > *:last-child:not(:first-child) {
-    margin-inline-start: auto;
+  :where(use-layout.message) > figure > img {
+    block-size: 100%;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* A `<figure>` inside the body is an attachment, not the rail — it keeps the flow but sheds the
+     UA margin so the region's own spacing is the only spacing. */
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card) > :is(main, use-layout[fill]) figure {
+    margin-inline: 0;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.page, use-layout.prose, use-layout.message, use-layout.card)
+    > :is(main, use-layout[fill])
+    figure
+    > img {
+    display: block;
+    inline-size: 100%;
+    block-size: auto;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  :where(use-layout.message) > :is(header, main, footer) {
+    grid-column: 2;
+    padding: 0;
+    max-inline-size: none;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* Name and timestamp sit on one line here rather than stacking, and the line never wraps —
+     trailing actions stay put as the name grows. */
+  :where(use-layout.message) > header > hgroup {
+    flex-direction: row;
+    align-items: baseline;
+    gap: var(--usewc-layout-region-gap);
+    white-space: nowrap;
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  /* Card chrome — the one bit of floating surface treatment that isn't layout, and the only
+     thing separating `.card` from the other three variants: they arrange regions, this also
+     paints a raised panel. `.outlined` keeps the border but drops the shadow, for a flatter
+     card.
+
+     A card nested directly in a `dialog` or `[popover]` skips the chrome: the overlay already
+     paints a surface, and stacking a second border and shadow inside it reads as a panel within
+     a panel. That makes `.card` the variant to reach for inside an overlay — a modal wants
+     exactly the card's arrangement (avatar header, actions collected at the inline-end edge),
+     just not a second background. */
+  use-layout.card:not(:is(dialog, [popover]) > *) {
+    overflow: hidden;
+    background: var(--usewc-color-surface-background);
+    border: var(--usewc-layout-surface-border) solid var(--usewc-color-surface-border);
+    border-radius: var(--usewc-effect-surface-border-radius);
+    box-shadow: var(--usewc-effect-surface-shadow);
+    color: var(--usewc-color-document-text);
+
+    use-theme-escape & {
+      all: revert-layer;
+    }
+  }
+
+  use-layout.card.outlined:not(:is(dialog, [popover]) > *) {
+    box-shadow: none;
 
     use-theme-escape & {
       all: revert-layer;

package/dist/tokens.css

@@ -639,10 +639,48 @@
   --usewc-color-code-border: var(--usewc-color-transparent);
   --usewc-font-code-size: var(--usewc-font-size-14);
 
-  /* Surface — shared by every surface host (dialog, use-card, [popover]): the visible chrome
-     (background/border/radius/shadow), the backdrop behind a modal `<dialog>` (non-modal
-     `[popover]` keeps its transparent UA backdrop), the gap an anchored surface keeps from its
-     anchor, and the internal header/poster/footer region layout they all apply the same way. */
+  /* Flex layout — `use-layout`'s named gap scale (see `theme/layout.css`). */
+  --usewc-layout-flex-gap-xsmall: var(--usewc-space-2);
+  --usewc-layout-flex-gap-small: var(--usewc-space-4);
+  --usewc-layout-flex-gap-medium: var(--usewc-space-8);
+  --usewc-layout-flex-gap-large: var(--usewc-space-16);
+  --usewc-layout-flex-gap-xlarge: var(--usewc-space-24);
+  --usewc-layout-flex-gap-super: var(--usewc-space-32);
+
+  /* Layout regions — the density scale each `use-layout` variant sets on itself, which the one
+     generic set of header / main / footer rules in `theme/layout.css` then reads. The four
+     variants are deliberately far apart: a document and a card in a feed can't share one
+     padding step and still read as themselves, so each gets its own rather than overriding a
+     shared base. The hairline colour is shared, since a rule is a rule wherever it lands. */
+  --usewc-color-region-border: var(--usewc-color-surface-border);
+  --usewc-layout-region-title-gap: var(--usewc-space-2);
+
+  --usewc-layout-prose-padding: var(--usewc-space-32);
+  --usewc-layout-prose-gap: var(--usewc-space-16);
+  --usewc-layout-prose-measure: 68ch;
+  --usewc-layout-prose-avatar-size: var(--usewc-space-24);
+
+  --usewc-layout-page-padding: var(--usewc-space-20);
+  --usewc-layout-page-padding-block: var(--usewc-space-12);
+  --usewc-layout-page-gap: var(--usewc-space-12);
+  --usewc-layout-page-avatar-size: var(--usewc-space-32);
+
+  --usewc-layout-card-padding: var(--usewc-space-12);
+  --usewc-layout-card-gap: var(--usewc-space-8);
+  --usewc-layout-card-avatar-size: var(--usewc-space-24);
+
+  /* The message rail width and its avatar are one value on purpose: a grouped message omits its
+     header and leaves the rail empty, and the bodies only stay aligned down a feed if the empty
+     rail is exactly as wide as the avatar it replaces. */
+  --usewc-layout-message-padding: var(--usewc-space-12);
+  --usewc-layout-message-gap: var(--usewc-space-12);
+  --usewc-layout-message-rail: var(--usewc-space-32);
+
+  /* Surface — the visible chrome for a surface host (background/border/radius/shadow), the
+     backdrop behind a modal `<dialog>` (non-modal `[popover]` keeps its transparent UA
+     backdrop), and the gap an anchored surface keeps from its anchor. `-padding` is the inset a
+     `dialog`/`[popover]` keeps from the viewport edge when sizing itself, not region padding —
+     the regions inside one come from whichever `use-layout` variant is nested there. */
   --usewc-color-surface-background: var(--usewc-color-canvas-background);
   --usewc-color-surface-border: var(--usewc-color-button-base-border-static);
   --usewc-color-surface-backdrop: oklch(0% 0 0 / 0.4);
@@ -651,11 +689,8 @@
   --usewc-effect-surface-border-radius: var(--usewc-effect-border-radius-8);
   --usewc-effect-surface-shadow: var(--usewc-effect-shadow-raised);
   --usewc-effect-surface-transition-duration: 200ms;
-  --usewc-space-surface-padding: var(--usewc-space-16);
-  --usewc-space-surface-gap: var(--usewc-space-12);
-  --usewc-layout-surface-avatar-size: var(--usewc-space-32);
+  --usewc-layout-surface-padding: var(--usewc-space-16);
   --usewc-effect-surface-avatar-border-radius: var(--usewc-effect-border-radius-full);
-  --usewc-color-surface-footer-border: var(--usewc-color-surface-border);
 }
 
 @media (prefers-color-scheme: dark) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-wc",
-  "version": "1.0.0-pre.65",
+  "version": "1.0.0-pre.66",
   "private": false,
   "homepage": "https://usewc.com",
   "bugs": "https://github.com/dang-rabbits/use-wc/issues",