@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/references/patterns-shells.md

@@ -0,0 +1,1097 @@
+# Shell Patterns
+
+Application-level layout shells. Use when composing a *whole product
+surface* — not a single card or form, but the wrapper that holds an
+entire admin app, code editor, or section-with-rail page. These
+patterns are the highest-leverage compose-time primitives in the
+library: they wire sidebar toggles, resize handles, command palettes,
+and responsive breakpoints so authors don't reinvent any of it.
+
+## When to reach for a shell
+
+| Surface | Shell |
+|---|---|
+| Admin product (sidebar nav + main content + optional command palette) | `<admin-shell>` + `<nav-ui>` |
+| Code / design-tool editor (topbar + resizable panes + footer status) | `<editor-shell>` + `<pane-ui>` children |
+| Embedded app — a primary surface + provider-supplied side panels (50/50 ≥760px; cover-sheet below) | `<embed-shell>` + `[app]` / `[panel="…"]` children · ADR-0024 attr contract (`[opens]`/`[close]`) · *draft* |
+| Long-form page with sub-rail (docs site, settings hub) | bare card layout + `<nav-ui variant="section">` rail |
+| LLM-streaming chat surface (history, input, response rendering) | `<chat-shell>` + `<chat-thread>` + `<chat-composer>` |
+| Marketing / landing / 404 / 500 / thank-you / single-card sign-in | `<simple-shell>` + `<simple-hero>` (+ optional `<simple-content>`) |
+| Single dashboard / form / single chat thread | no shell — card composition direct |
+
+If the page has more than one navigation surface (sidebar AND tabs AND
+breadcrumbs), it almost always belongs in a shell. If it's one card
+deep, it doesn't.
+
+## Admin shell (admin product layout)
+
+Behavior-only wrapper. Author provides the structural DOM — the shell wires sidebar toggles, resize handles, a `Cmd+K` command palette, and a `ResizeObserver` that drives responsive breakpoints. Tokens come from the same component layer; no shell-specific CSS to author.
+
+Per ADR-0023 (shipped v0.3.6, all consumers migrated) and ADR-0024 (legacy shapes retired v0.4.0), the **canonical authoring shape** uses bespoke cluster-namespaced children. **The single source of truth is `chat-ui:site/index.html`** — the canonical 13-part anatomy below was extracted directly from it. Do NOT use the substrate's `admin-shell.examples.html` demo as a reference (it carried pre-ADR-0023 shapes through v0.5.x; same drift class as the `editor-shell.examples.html` issue tracked in `.agents/team/tickets/drafts/FB-editor-shell-demo-slot-vocab.md`).
+
+```html
+<admin-shell mode="rounded borderless">
+
+  <!-- ═══ LEFT SIDEBAR ═══ -->
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header">
+      <!-- Brand chrome — CANONICAL for SINGLE-PRODUCT apps (no workspace switching).
+           This is the default for ~most admin apps. The icon + label collapse together
+           as one slottable unit inside the collapsible sidebar.
+           For MULTI-TENANT (user belongs to >1 workspace), swap with:
+             <select-ui id="workspace-select" avatar="/icons/brand.svg" value="default" variant="ghost" style="flex:1"></select-ui>
+           See §Brand chrome below for all 3 patterns (static / switcher / nav-home) + decision table.
+           Do NOT use bare <span slot="icon"> + <span slot="heading"> here — that's the
+           re-implement-bare anti-pattern explicitly forbidden by admin-entity-item.yaml. -->
+      <admin-entity-item slot="heading">
+        <icon-ui slot="icon" name="lightning"></icon-ui>
+        <span slot="label">App Name</span>
+      </admin-entity-item>
+    </admin-topbar>
+
+    <section-ui>
+      <nav-ui id="nav">
+        <nav-item-ui data-command-trigger icon="magnifying-glass" text="Search" value="search">
+          <kbd slot="trailing">⌘K</kbd>
+        </nav-item-ui>
+        <hr data-nav-divider />
+        <nav-item-ui icon="gauge" text="Dashboard" value="/"></nav-item-ui>
+        <nav-item-ui icon="users" text="Members" value="/members"></nav-item-ui>
+      </nav-ui>
+    </section-ui>
+
+    <admin-statusbar slot="footer">
+      <!-- User identity — two canonical shapes by intent:
+           • INTERACTIVE user menu (sign-out, profile, settings actions) → <select-ui avatar>
+           • STATIC user identity (just display who's signed in)         → <admin-entity-item>
+           Both share the same geometry. Pick by whether clicking the row opens a menu.
+           Below: interactive multi-tenant canonical. For static, mirror the header
+           Pattern A shape with <icon-ui slot="icon"> or <avatar-ui slot="icon"> + slot="label". -->
+      <select-ui id="user-select" avatar="https://example.com/user.jpg" value="me" variant="ghost" style="flex:1"></select-ui>
+    </admin-statusbar>
+
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <!-- ═══ MAIN ═══ -->
+  <admin-content>
+
+    <admin-topbar>
+      <button-ui data-sidebar-toggle="leading" icon="sidebar" title="Toggle navigation sidebar" variant="ghost" size="sm"></button-ui>
+      <breadcrumb-ui id="breadcrumb">
+        <a href="/">App</a>
+        <span>Dashboard</span>
+      </breadcrumb-ui>
+      <span data-spacer></span>
+      <div data-actions>
+        <!-- Theme switcher — canonical: popover-ui + theme-panel; theme-picker-ui does NOT exist -->
+        <popover-ui id="theme-popover" placement="bottom-end">
+          <button-ui icon="palette" title="Choose theme" variant="ghost" size="sm" slot="trigger"></button-ui>
+          <theme-panel slot="content" persist parametric presets scheme-toggle></theme-panel>
+        </popover-ui>
+        <button-ui data-sidebar-toggle-trailing icon="note" variant="ghost" size="sm" aria-label="Side panel"></button-ui>
+      </div>
+    </admin-topbar>
+
+    <admin-scroll>
+      <!-- Page content — usually <admin-page> or <router-ui> -->
+      <admin-page>
+        <admin-page-header>
+          <header>                            <!-- REQUIRED inner column-owner -->
+            <div>                             <!-- title row: h1 left, actions right -->
+              <h1>Dashboard</h1>
+              <div data-actions>
+                <button-ui text="New" variant="primary" icon="plus"></button-ui>
+              </div>
+            </div>
+            <p>Operator-facing claims review.</p>   <!-- optional description -->
+          </header>
+        </admin-page-header>
+        <admin-page-body>
+          <section>                           <!-- REQUIRED inner column-owner -->
+            <!-- Cards / grids / charts / tables — multiple <card-ui> siblings
+                 get gap: var(--page-section-gap) ≈ a-space-8 automatically -->
+          </section>
+        </admin-page-body>
+      </admin-page>
+    </admin-scroll>
+
+    <admin-statusbar>
+      <span>App</span>
+      <span data-spacer></span>
+      <span id="version-label">v1.0.0</span>
+    </admin-statusbar>
+
+  </admin-content>
+
+  <!-- ═══ RIGHT SIDEBAR (optional) ═══ -->
+  <admin-sidebar slot="trailing" resizable collapsible id="side-rail" hidden>
+    <admin-topbar slot="header">
+      <span slot="heading">Activity</span>
+      <button-ui slot="action" data-sidebar-toggle-trailing icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>
+    </admin-topbar>
+    <section-ui>
+      <!-- ai chat companion, changelog feed, inspector, etc. -->
+    </section-ui>
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <!-- ═══ COMMAND PALETTE ═══ -->
+  <admin-command>
+    <command-ui id="cmd" placeholder="Search..."></command-ui>
+  </admin-command>
+
+</admin-shell>
+```
+
+**Slot vocabulary (where `slot=` is REQUIRED vs FORBIDDEN).** The same tag (`<admin-topbar>`, `<admin-statusbar>`) appears in TWO positions with DIFFERENT slot rules — getting this wrong silently breaks layout:
+
+| Element | Position | `slot=` attribute |
+|---|---|---|
+| `<admin-sidebar>` | Direct child of `<admin-shell>` | **REQUIRED**: `slot="leading"` or `slot="trailing"` |
+| `<admin-content>` | Direct child of `<admin-shell>` | **No slot** (default position) |
+| `<admin-command>` | Direct child of `<admin-shell>` | **No slot** |
+| `<admin-topbar>` | Inside `<admin-sidebar>` (sidebar header) | **REQUIRED**: `slot="header"` |
+| `<admin-topbar>` | Inside `<admin-content>` (content-area top chrome) | **No slot** — positioned as first child via CSS, not via slot vocab |
+| `<admin-statusbar>` | Inside `<admin-sidebar>` (sidebar footer) | **REQUIRED**: `slot="footer"` |
+| `<admin-statusbar>` | Inside `<admin-content>` (content-area bottom chrome) | **No slot** — positioned as last child via CSS |
+| `<admin-page>` | Inside `<admin-scroll>` inside `<admin-content>` | **No slot** |
+| `<admin-page-header>` / `<admin-page-body>` | Direct child of `<admin-page>` | **No slot** |
+
+> ⚠️ **Common slot anti-pattern**: putting `slot="header"` on the **content-area** `<admin-topbar>` (inside `<admin-content>`). `slot="header"` only positions inside `<admin-sidebar>`. The content-area topbar is positioned by being the FIRST CHILD of `<admin-content>`, not by a slot attribute. Adding `slot="header"` is silently ignored at the CSS level but signals the wrong mental model — verify against the canonical above.
+
+**The 13 canonical parts (post-ADR-0023):**
+
+| Tag | Role | Attributes that matter |
+|---|---|---|
+| `<admin-shell>` | Outer host; reflects `[mode]` to children | `mode="rounded borderless"` is the canonical visual |
+| `<admin-sidebar slot="leading">` | Primary nav rail | **MUST have `resizable collapsible`** — pure `collapsible` loses the resize affordance; persists width per `[id]` to localStorage |
+| `<admin-topbar slot="header">` inside sidebar | Sidebar's own top region — brand chrome (single-product `<admin-entity-item>` OR multi-tenant `<select-ui workspace-switcher>`) | Inner identity unit goes in `slot="heading"`; auxiliary buttons in `slot="action"`. See §Brand chrome below for the 3 canonical patterns + decision table. Do NOT use bare `<span slot="icon">` + `<span slot="heading">` (anti-pattern; admin-entity-item.yaml forbids it). |
+| `<section-ui>` inside sidebar | The middle / scrollable section between the sidebar's header and footer | — |
+| `<nav-ui>` inside section-ui | Primary nav items (`<nav-item-ui>`, `<nav-group-ui>`) | — |
+| `<admin-statusbar slot="footer">` inside sidebar | Sidebar's footer region — user-menu (`<select-ui avatar>`) lives here | — |
+| `<div data-resize>` inside sidebar | The resize-handle anchor element (REQUIRED for `resizable` to work) | — |
+| `<admin-content>` (no slot — sibling of sidebars) | The center work region | — |
+| `<admin-topbar>` inside admin-content (no slot — first child) | Content-area top: sidebar-toggle, breadcrumb, action cluster | `<button-ui data-sidebar-toggle="leading">` for the hamburger; `<span data-spacer>` for the auto-margin push; `<div data-actions>` for the trailing cluster |
+| `<admin-scroll>` inside admin-content | The scroll viewport — owns scroll mechanics + sticky-bottom for `<admin-statusbar>` | — |
+| `<admin-page>` inside admin-scroll | Per-page anatomy wrapper (alternative: `<router-ui>` for dynamic-route apps) | Children: `<admin-page-header>` + `<admin-page-body>` |
+| `<admin-statusbar>` inside admin-content (no slot — last child) | Content-area footer: status indicator, page metadata, version label | — |
+| `<admin-sidebar slot="trailing">` | OPTIONAL: secondary rail for activity feed, AI companion, inspector | `hidden` by default; toggled via `[data-sidebar-toggle-trailing]` |
+| `<admin-command>` | Cmd+K command palette host | Wraps `<command-ui>`; carries the global keyboard listener |
+
+**Wrapper-vs-column rule (the silent-degrade trap).** `<admin-page-header>` and `<admin-page-body>` are bespoke **wrappers** — they own full-width chrome (sticky position, border, background, scroll sizing). The **inner column-owner** (`<header>` / `<section>`) owns the centered reading column (max-width, padding, flex rhythm). Skipping the inner wrapper drops padding/max-width silently — the chrome still renders, but content flushes to the viewport edge.
+
+| Wrapper | Required inner | What you lose if omitted |
+|---|---|---|
+| `<admin-page-header>` | `<header>` or `<header-ui>` | `padding-inline: var(--page-content-inset)` ≈ 40px, `max-width: var(--page-content-max-width)`, column flex layout |
+| `<admin-page-body>` | `<section>` or `<section-ui>` | `padding: var(--page-content-inset)` ≈ 40px on all edges, `max-width`, `gap: var(--page-section-gap)` ≈ a-space-8 between sibling cards |
+
+**Full-bleed escape hatch.** Use a direct-child element OTHER than `<header>` / `<section>` to opt out of the centered column intentionally — for `<iframe>` embeds, `<editor-shell>` nesting, or split-pane layouts. The wrapper's flex sizing still applies; only the column inset is dropped.
+
+| Use case | Direct child of `<admin-page-body>` |
+|---|---|
+| Standard page content (cards, grids, charts, tables) | `<section>` — required for padding + section-gap |
+| Iframe page (embedded doc, third-party widget) | `<iframe>` direct child — fills body, no padding |
+| Editor-inside-admin (nested shell) | `<editor-shell>` direct child — opts out of column (see §Editor-inside-admin) |
+| Split-pane layout | `<pane-ui>` siblings — owns its own chrome |
+
+For full-bleed-with-padding (e.g. gallery surface), set `[data-content-full]` on the inner `<section>` — max-width relaxes to 100%, padding is preserved.
+
+**No console warning fires** when the inner wrapper is omitted. Verify by reading `getComputedStyle(adminPageBody).padding` — should be `var(--page-content-inset)`, NOT `0px`. If `0px`, the inner `<section>` is missing.
+
+**Key affordances:**
+- `[data-sidebar-toggle="leading|trailing"]` — buttons that toggle the matching `<admin-sidebar>` rail. Place inside `<admin-topbar>` or anywhere in the shell.
+- `[data-resize]` — anchor element inside `<admin-sidebar>` that grabs for width-drag. Required for `resizable` to work.
+- `[data-spacer]` — empty `<span>` inside `<admin-topbar>` that pushes subsequent siblings to the trailing edge via auto-margin.
+- `[data-actions]` — wrapping `<div data-actions>` for the trailing action cluster in `<admin-topbar>` **AND** for the action cluster inside `<admin-page-header>` `<header>` title row. Must be `<div>` with the `data-actions` attribute — bare `<span>` (or `<div>` without the attribute) doesn't match the CSS rule and the buttons fall into the title column instead of right-aligning. Anti-pattern: `<span><button-ui>New</button-ui></span>` next to `<h1>`.
+
+**Responsive — `@bp` annotations are mandatory on layout primitives.** The shell itself handles sidebar collapse via the ResizeObserver, but **page content inside `<admin-page-body>` will overflow on narrow viewports unless you write `@bp`-annotated layouts.** This is the #1 missed kit guidance — full `@bp` reference in [`patterns-layout.md`](patterns-layout.md) §Responsive Layout. Quick reference:
+
+```html
+<!-- 5-up KPI grid on desktop, 2-up tablet, 1-up phone -->
+<grid-ui columns="1 2@sm 3@md 5@lg" gap="3 4@md">
+  <stat-ui label="Total" value="766" trend="up"></stat-ui>
+  …
+</grid-ui>
+
+<!-- Side-by-side charts that stack on phone -->
+<grid-ui columns="1 2@md" gap="4">
+  <card-ui>…</card-ui>  <!-- volume chart -->
+  <card-ui>…</card-ui>  <!-- donut chart -->
+</grid-ui>
+```
+
+Breakpoints: `xs/sm/md/lg/xl` = 0/480/768/1024/1280 px. Never write `@media (max-width: …)` or inline `grid-template-columns` — both are anti-patterns the kit explicitly rejects.
+
+**Legacy shapes RETIRED in v0.4.0** (ADR-0024). If you find ANY of these patterns in agent-generated DOM, the agent followed a stale recipe (chat-ui's `admin-shell.examples.html` carried these through v0.5.x; the actual canonical is `chat-ui:site/index.html`):
+
+| Legacy shape (pre-v0.4.0) | Canonical replacement (post-v0.4.0) |
+|---|---|
+| `<header slot="header">` direct child of admin-shell | `<admin-topbar slot="header">` inside `<admin-sidebar>` |
+| `<nav-ui slot="leading">` direct child of admin-shell | `<admin-sidebar slot="leading">` wrapping `<nav-ui>` |
+| `<main>` direct child of admin-shell | `<admin-content>` |
+| `<header-ui>` inside main | `<admin-topbar>` (no slot) inside admin-content |
+| `<section-ui>` directly inside main (as the page body) | `<admin-scroll>` > `<admin-page>` > `{<admin-page-header>, <admin-page-body>}` |
+| `<dialog data-command>` | `<admin-command>` |
+| `<aside data-sidebar="leading">` | `<admin-sidebar slot="leading" resizable collapsible>` |
+
+**The "halfway-modernized" anti-pattern.** A common failure mode: consumer adopts `<admin-shell>` + `<admin-sidebar>` + `<admin-content>` (the visible parts) but skips `<admin-scroll>` + `<admin-statusbar>` + `<admin-command>` (the invisible parts) and puts `<admin-topbar>` at the wrong level (sibling of `<admin-content>` instead of its first child). Symptoms: page scrolls the entire viewport instead of just the content region; no Cmd+K palette; missing status row at the bottom. Verify against the 13-part table above before shipping.
+
+### Brand chrome in `<admin-topbar slot="header">` (sidebar header)
+
+The canonical anatomy above shows the **single-product** brand shape (`<admin-entity-item>`) as the default — that's the majority case. For multi-tenant apps (user belongs to >1 workspace), swap to `<select-ui variant="ghost">`. Three canonical patterns total, picked by intent:
+
+`<admin-entity-item>` is the canonical identity-row primitive (shipped `@adia-ai/web-modules@0.7.13`, FB-38). It owns the icon + label + badge geometry as one slottable unit that collapses correctly inside a collapsible sidebar AND aligns 1px-perfect with `<nav-item-ui>` icons in the section below.
+
+> **For any non-interactive brand chrome (single product, no switcher), prefer `<admin-entity-item>` over bare `[slot="icon"]` + `[slot="heading"]`.** The primitive owns icon-label-badge geometry, the sidebar-collapse boundary, and `<nav-item-ui>` alignment. Per its own a2ui rule: *"admin-entity-item is the canonical icon + label + badge identity row for shell surfaces. Do NOT re-implement it with a bare `<span>` or an ad-hoc flex `<div>` — those have no shared collapse boundary."*
+
+#### Pattern A — `<admin-entity-item>` (canonical static brand)
+
+```html
+<admin-sidebar slot="leading" resizable collapsible>
+  <admin-topbar slot="header">
+    <admin-entity-item slot="heading">
+      <icon-ui slot="icon" name="lightning"></icon-ui>
+      <span slot="label">Claims Portal</span>
+      <!-- Optional: <badge-ui slot="badge" text="Staging" size="sm" variant="warning"></badge-ui> -->
+    </admin-entity-item>
+  </admin-topbar>
+  …
+</admin-sidebar>
+```
+
+Use when: one workspace, brand is the app's identity, no navigation home action.
+
+**Why `<admin-entity-item>` over bare `[slot="icon"]` + `[slot="heading"]`:**
+
+- **Aligns with `<nav-item-ui>` icons** — admin-entity-item's trigger-row geometry mirrors `<select-ui>` and sits at 12px (matches `<section-ui>` 4px + `<nav-item-ui>` 8px). Bare slot vocabulary lands at the topbar's `--page-sidebar-px` (4px) — **8px short** of nav alignment.
+- **Collapses as one slottable unit** in collapsible sidebars (icon survives, label + badge hide together via the primitive's own CSS). Bare `[slot]` siblings have no shared collapse boundary and depend on separate cleanup rules that can drift across kit CSS evolution.
+- **Has an explicit `[slot="badge"]`** for environment / role chips (staging, beta, production, internal).
+- **Matches the user-identity footer** primitive — consistent identity-row geometry top AND bottom of the sidebar (see `<admin-statusbar slot="footer">` recipe in `patterns-recipes.md`).
+
+#### Pattern B — `<select-ui variant="ghost">` interactive workspace switcher
+
+```html
+<admin-topbar slot="header">
+  <select-ui id="workspace-select" avatar="/icons/brand.svg" value="acme" variant="ghost" style="flex:1">
+    <option value="acme">Acme Co.</option>
+    <option value="bravo">Bravo Industries</option>
+  </select-ui>
+</admin-topbar>
+```
+
+Use when: the user belongs to >1 workspace and can switch between them. **Do not use `<select-ui disabled>` to fake a static brand** — that re-implements `<admin-entity-item>` with a chevron artifact and `pointer-events: none`. For static (non-interactive) brand chrome, use Pattern A (`<admin-entity-item>`).
+
+#### Pattern C — brand-anchored navigation home link
+
+```html
+<admin-topbar slot="header">
+  <a href="/" data-brand-home>
+    <admin-entity-item>
+      <icon-ui slot="icon" name="lightning"></icon-ui>
+      <span slot="label">Claims Portal</span>
+    </admin-entity-item>
+  </a>
+</admin-topbar>
+```
+
+Use when: clicking the brand should route to `/` (home) — common in SPA admin apps where the brand doubles as a navigation anchor. Wrap `<admin-entity-item>` in an `<a>` rather than wrapping bare slots — preserves the identity-row collapse boundary.
+
+#### Brand-chrome decision table
+
+| Tier | Brand chrome | When |
+|---|---|---|
+| **Single-product, static** | **(A) `<admin-entity-item slot="heading">`** (canonical in anatomy above — line ~36) | **One workspace, brand is identity** |
+| Multi-product workspace | (B) `<select-ui variant="ghost">` workspace switcher | User belongs to >1 workspace |
+| Single-product, nav-home | (C) `<a href="/">` wrapping `<admin-entity-item>` | Brand should route to `/` on click |
+
+> ⚠️ **Bare `<span slot="heading">Name</span>` (no icon, no anchor) is structurally valid but visually undersized AND misaligned with `<nav-item-ui>` icons (8px off).** Always use one of Pattern A/B/C above. Verified by `getBoundingClientRect`: bare-slot brand icon at x=4px vs admin-entity-item brand icon at x=12px (matches nav-icon at x=12px).
+
+### Routing inside admin-shell
+
+Three supported patterns for navigating between views inside the same admin-shell. Pick by app shape.
+
+#### Pattern A — `<router-ui>` (dynamic routes)
+
+The canonical pattern from `chat-ui:site/index.html`. Place `<router-ui>` where `<admin-page>` would otherwise go. The router stamps the matched route's `<template>` (keyed by path); each template contains a full `<admin-page>` with the inner `<header>`/`<section>` column-owners.
+
+```html
+<admin-scroll>
+  <router-ui id="router"></router-ui>
+</admin-scroll>
+
+<template id="route-dashboard">
+  <admin-page>
+    <admin-page-header><header><h1>Dashboard</h1></header></admin-page-header>
+    <admin-page-body><section><!-- cards / grids --></section></admin-page-body>
+  </admin-page>
+</template>
+
+<template id="route-claims">
+  <admin-page>
+    <admin-page-header><header><h1>Claims</h1></header></admin-page-header>
+    <admin-page-body><section><!-- cards / grids --></section></admin-page-body>
+  </admin-page>
+</template>
+```
+
+Use when: dynamic routes, deep linking, browser back/forward navigation.
+
+#### Pattern B — separate `<admin-page>` per view, toggle via `[hidden]`
+
+```html
+<admin-scroll>
+  <admin-page id="view-dashboard">
+    <admin-page-header><header><h1>Dashboard</h1></header></admin-page-header>
+    <admin-page-body><section><!-- … --></section></admin-page-body>
+  </admin-page>
+  <admin-page id="view-claims" hidden>
+    <admin-page-header><header><h1>Claims</h1></header></admin-page-header>
+    <admin-page-body><section><!-- … --></section></admin-page-body>
+  </admin-page>
+</admin-scroll>
+```
+
+Each view is a complete `<admin-page>` direct child of `<admin-scroll>`. The `admin-page > admin-page-header` selector matches; sticky chrome works. Use when: 2-3 views, no deep linking, you want zero router setup.
+
+#### Pattern C — anti-pattern: DON'T wrap in `<div>` for view toggle
+
+```html
+<!-- ✗ WRONG — wrapping breaks the direct-child selectors -->
+<admin-scroll>
+  <admin-page>
+    <div id="view-dashboard">
+      <admin-page-header>…</admin-page-header>
+      <admin-page-body>…</admin-page-body>
+    </div>
+  </admin-page>
+</admin-scroll>
+```
+
+Symptoms: `<admin-page-header>` loses sticky/border/background (no `admin-page > admin-page-header` match); `<admin-page-body>` falls back to `display: inline` (HTMLUnknownElement default) and its `<section>` child renders inline-flowing. Catastrophic — and **silent**, no console warning.
+
+Always nest the routing-control element OUTSIDE the per-view `<admin-page>` (Pattern B) or use `<router-ui>` (Pattern A).
+
+**Don't reach for admin-shell when:** the page is a one-card login/signup, a marketing landing, or a doc page. Use `<simple-shell>` for those (see below). Admin-shell is for sidebar-IA product surfaces — settings, dashboards, lists, detail-with-aside.
+
+## Editor shell (design-tool / code-editor layout)
+
+Behavior-only editor shell for structural design-tool layouts. Author
+provides toolbar + canvas + panes; the shell coordinates the bespoke
+children + persists pane sizes.
+
+Per ADR-0023
+(shipped v0.3.6, all consumers migrated), the **canonical authoring
+shape** uses cluster-namespaced bespoke children. Note: `<editor-sidebar>`
+WRAPS `<pane-ui resizable>` rather than reimplementing drag — see
+Pitfall #11 in the `bespoke-shell-children` skill.
+
+```html
+<editor-shell>
+  <editor-toolbar>
+    <span slot="action-leading"><icon-ui name="layers"></icon-ui></span>
+    <span slot="title">Untitled.fig</span>
+    <span slot="status">1920 × 1080 · Saved</span>
+    <span slot="action">
+      <button-ui text="Share" variant="ghost"></button-ui>
+      <button-ui text="Run" variant="primary"></button-ui>
+    </span>
+  </editor-toolbar>
+
+  <editor-sidebar slot="leading" collapsible persist="structure">
+    <pane-ui side="leading" resizable min-width="200">
+      <header>Layers</header>
+      <section><!-- tree / outline / explorer --></section>
+    </pane-ui>
+  </editor-sidebar>
+
+  <editor-canvas>
+    <editor-canvas-toolbar>
+      <tabs-ui value="preview" variant="underline">
+        <tab-ui value="preview" text="Preview"></tab-ui>
+        <tab-ui value="schema"  text="Schema"></tab-ui>
+      </tabs-ui>
+    </editor-canvas-toolbar>
+    <editor-canvas-empty>
+      <empty-state-ui icon="square" heading="New document"
+        description="Drop content to begin."></empty-state-ui>
+    </editor-canvas-empty>
+    <!-- host-rendered canvas content (artboards, doc body) appears here -->
+  </editor-canvas>
+
+  <editor-sidebar slot="trailing" collapsible persist="inspector">
+    <pane-ui side="trailing" resizable min-width="200">
+      <header>Inspector</header>
+      <section><!-- properties / outputs / chat --></section>
+    </pane-ui>
+  </editor-sidebar>
+
+  <editor-statusbar>
+    <span slot="status">Saved</span>
+    <span slot="zoom">100%</span>
+  </editor-statusbar>
+</editor-shell>
+```
+
+**Slot vocabulary (substrate-grounded).** `editor-toolbar`, `editor-canvas-toolbar`, and `editor-statusbar` position children via CSS rules matching `[slot=…]` on the direct child (Light-DOM contract — there's no shadow projection). The CSS only positions the slot names below; other slot names render as inline children at the document-order position and may look "fine" but don't follow the canonical layout. Verified against `packages/web-modules/editor/editor-shell/css/editor-shell.bespoke.css`:
+
+| Host | Positioned slots | Note |
+|---|---|---|
+| `<editor-toolbar>` | `title`, `status`, `action`, `action-leading` | First `[slot=action]` pushes to the trailing edge via auto-margin; subsequent `[slot=action]` siblings hug it. `[full-screen]` reflected (set by parent shell when `[focus-mode]`). |
+| `<editor-canvas-toolbar>` | `default`, `title`, `action`, `action-leading` | `default` slot is the common case for the view-mode `<tabs-ui>`. |
+| `<editor-statusbar>` | `status`, `cursor`, `zoom`, `action` | All four are inline siblings — separator-free, evenly spaced. |
+| `<editor-sidebar>` | only `slot="leading"` / `slot="trailing"` on the host as discriminator | Sidebar's own children are NOT slot-positioned; you place a `<pane-ui resizable>` inside and the pane owns chrome. |
+
+**Common drift trap (FB-trace D1, fixed v3.1.1):** earlier kit revisions used `slot="icon|heading|description"` on `<editor-toolbar>` (mirroring the `admin-topbar` vocabulary). Substrate CSS does NOT position those slot names on the editor cluster. Use `action-leading` for the leading icon, `title` for the document name, `status` for the secondary metadata cluster. The substrate's `editor-shell.examples.html` demo carried the same drift through v0.6.32; tracked in `.agents/team/tickets/drafts/FB-editor-shell-demo-slot-vocab.md`.
+
+- `<editor-shell>` — host; reflects `[focus-mode]`; propagates to children's `[full-screen]` / `[focused]`
+- `<editor-toolbar>` — app-scope top chrome with `title` / `status` / `action` / `action-leading` slot vocabulary; `[full-screen]` reflected; `[data-toolbar-action="<name>"]` buttons bubble `toolbar-action` events
+- `<editor-canvas>` — central content surface; `[empty]` + `[focused]` reflected; public API `.focus()` / `.blur()` / `.resetView()` / `.zoom`
+- `<editor-canvas-toolbar>` — sticky chrome bar at the TOP of `<editor-canvas>`; holds view-mode `<tabs-ui>` (preview / schema / DOM), breadcrumbs, or canvas-scoped actions. **Canvas-scope** (distinct from app-scope `<editor-toolbar>`); replaces the legacy `<div data-view-strip>` pattern. Slots: `default` / `title` / `action` / `action-leading`
+- `<editor-canvas-empty>` — first-child empty-state slot inside `<editor-canvas>`; visibility driven by parent `[empty]` (CSS-only — no JS toggling)
+- `<editor-sidebar slot="leading|trailing" collapsible persist="…">` — **WRAPS `<pane-ui resizable>` (delegation pattern)**; `[collapsed]` + `[resizing]` reflected; localStorage prefix `adia-editor-sidebar-{persist}`. The `[persist]` attribute is the storage-key suffix (preferred over deprecated `[name]` alias kept for v0.4.x back-compat).
+- `<editor-statusbar>` — bottom chrome bar with `status` / `cursor` / `zoom` / `action` slots
+
+**Legacy shapes retired in v0.4.0** (ADR-0024). Pre-v0.4.0 the shell read `<header>` / `<div data-canvas>` / `<pane-ui data-left|data-right>` / `<footer>` via priority chain; those paths were removed in v0.4.0. Consumers MUST use the bespoke vocabulary.
+
+**Don't reach for editor-shell when:** the surface is a typical product page with sidebar + content + optional aside (use `admin-shell` instead). Editor-shell is for *editing* surfaces — code, canvases, designs — where pane resizing is a primary affordance.
+
+## Standalone pane-ui (split-pane layout without a shell)
+
+`<pane-ui>` is a [category: layout] primitive that works **standalone**, not just inside `<editor-sidebar>`. The substrate's `pane.yaml` SoT explicitly documents the standalone split-pane shape: two `<pane-ui side="leading|trailing">` siblings in a flex row produce a shared resize seam between them. Reach for this when you need a resizable split without the full editor cluster's toolbar + statusbar chrome — markdown-editor + preview, settings list + detail, JSON input + rendered output, side-by-side diff.
+
+```html
+<!-- Standalone two-pane split: editor + preview -->
+<div style="display: flex; height: 100%;">
+  <pane-ui side="leading" resizable min-width="320">
+    <header>Source</header>
+    <section>
+      <textarea-ui placeholder="Type markdown…" rows="20"></textarea-ui>
+    </section>
+  </pane-ui>
+  <pane-ui side="trailing" resizable min-width="320">
+    <header>Preview</header>
+    <section>
+      <article><!-- rendered preview --></article>
+    </section>
+  </pane-ui>
+</div>
+```
+
+**Pane-ui contract (from `packages/web-components/components/pane/pane.yaml`):**
+
+| Prop | Type | Default | Note |
+|---|---|---|---|
+| `resizable` | boolean | `false` | Adds the drag grabber. Without it, pane-ui is a static container. |
+| `side` | enum `'' \| 'leading' \| 'trailing'` | `''` | Reflected. Unset → standalone-pane chrome (four-sided border, right-edge grabber). Set → "horizontal-sibling" chrome (border + grabber move to the inner edge so adjacent panes share a single seam). `trailing` also flips the drag direction so the pane grows leftward. |
+| `collapsed` | boolean | `false` | Toggle to hide pane body; auto-created header arrow flips. |
+| `min-width` | number | `200` | px floor for the resize drag. |
+| `max-width` | number | `9999` | px ceiling for the resize drag. |
+
+**Conventional inner shape** (matches `<editor-sidebar>` children, but you author it yourself when standalone):
+
+```html
+<pane-ui side="leading" resizable>
+  <header>Layers</header>                  <!-- auto-styled, with the toggle arrow on the right -->
+  <section>…</section>                     <!-- primary content; gets the scroll surface -->
+  <footer slot="footer">…</footer>         <!-- optional, e.g. count summary -->
+</pane-ui>
+```
+
+**Events:** `toggle` bubbles when `[collapsed]` flips (button press, keyboard, or programmatic `.toggle()`). Listen on the pane or any ancestor.
+
+**When NOT to use standalone pane-ui:**
+- The surface is an editor with a canvas + dual rails — use `<editor-shell>` instead; it carries the chrome (toolbar + statusbar) and the focus-mode propagation.
+- The surface is an admin page where the sidebar is fixed-width (not user-resizable) — use `<admin-sidebar>` inside `<admin-shell>`; that delegation is already documented.
+- You need keyboard shortcut wiring for sidebar collapse — wrap in the bespoke sidebar (`<editor-sidebar>` or `<admin-sidebar>`) which owns the `[data-sidebar-toggle]` keyboard plumbing.
+
+**Anti-patterns:**
+- **Don't nest a third pane-ui as a sibling of leading+trailing.** Pane-ui's `[side]` enum has only `leading` and `trailing`; three siblings break the resize-seam math. For three-pane layouts (file tree + editor + inspector), use `<editor-shell>` with both sidebars.
+- **Don't hand-roll the resize handle.** Pane-ui owns drag entirely; styling the grabber requires editing the substrate (not consumer code).
+
+## Editor-inside-admin (nested-shell composition)
+
+Editor-shell and admin-shell are normally **sibling shells, not nested** — an admin product page typically links OUT to an editor flow (a separate route). The nested case **is supported** for editor-inside-admin-page-body pages — inline page builders, embedded canvases, or any "edit-this-thing" surface that stays inside the admin chrome rather than navigating away.
+
+The nested case requires the `min-height: 0` flex-chain discipline; without it, the inner shell collapses to zero height because flex children default to `min-height: auto` (which equals content height, which is unknown for the canvas).
+
+```html
+<admin-shell>
+  <admin-sidebar slot="leading">…</admin-sidebar>
+
+  <admin-content>
+    <admin-topbar slot="header">
+      <breadcrumb-ui>
+        <a href="/">Dashboard</a>
+        <span>Page Builder</span>
+      </breadcrumb-ui>
+    </admin-topbar>
+
+    <admin-scroll>
+      <admin-page>
+        <admin-page-header>
+          <h1>Inline Page Builder</h1>
+        </admin-page-header>
+
+        <admin-page-body style="flex: 1; display: flex; flex-direction: column; min-height: 0;">
+          <editor-shell style="flex: 1; min-height: 0;">
+            <editor-toolbar>
+              <span slot="title">Untitled draft</span>
+              <span slot="status">Saved · 30s ago</span>
+              <button-ui slot="action" text="Publish" variant="primary"></button-ui>
+            </editor-toolbar>
+
+            <editor-sidebar slot="leading" collapsible persist="builder-structure">
+              <pane-ui side="leading" resizable min-width="200">
+                <header>Blocks</header>
+                <section><!-- block palette --></section>
+              </pane-ui>
+            </editor-sidebar>
+
+            <editor-canvas>
+              <editor-canvas-toolbar>
+                <tabs-ui value="design" variant="underline">
+                  <tab-ui value="design" text="Design"></tab-ui>
+                  <tab-ui value="preview" text="Preview"></tab-ui>
+                </tabs-ui>
+              </editor-canvas-toolbar>
+              <!-- live page rendering goes here -->
+            </editor-canvas>
+
+            <editor-sidebar slot="trailing" collapsible persist="builder-inspector">
+              <pane-ui side="trailing" resizable min-width="200">
+                <header>Properties</header>
+                <section><!-- inspector form --></section>
+              </pane-ui>
+            </editor-sidebar>
+
+            <editor-statusbar>
+              <span slot="status">12 blocks</span>
+              <span slot="zoom">100%</span>
+            </editor-statusbar>
+          </editor-shell>
+        </admin-page-body>
+      </admin-page>
+    </admin-scroll>
+  </admin-content>
+</admin-shell>
+```
+
+**The flex-chain rule (substrate-grounded):**
+- Every ancestor of `<editor-shell>` from `<admin-page-body>` upward must carry `flex: 1; min-height: 0`.
+- `<admin-page-body>` itself needs `display: flex; flex-direction: column` so its single editor-shell child sizes correctly.
+- `<editor-shell>` itself needs `flex: 1; min-height: 0` to fill the body.
+
+**Skipping any of those four properties = inner shell collapses to zero height** (the most common nested-shell bug). The substrate's `editor-shell.yaml` `a2ui.rules` calls this out explicitly:
+
+> For editor-inside-admin nested-shell pages, place the editor-shell inside `<admin-page-body>` with `flex: 1; min-height: 0` on every ancestor in the flex chain. Without `min-height: 0` the inner shell collapses to zero height.
+
+**Persist scoping.** When nesting, use distinct `persist=` suffixes for the editor's sidebars to avoid localStorage collisions with the outer admin shell. The example above uses `persist="builder-structure"` + `persist="builder-inspector"` — distinct from any unscoped `persist="structure"` / `persist="inspector"` you'd use in a standalone editor route.
+
+**When NOT to nest:**
+- The editor is the entire surface (no admin chrome around it) — keep it as a sibling route. Most editor flows are this shape.
+- The "edit" interaction is small enough to fit in a `<dialog-ui>` or `<drawer-ui>` — don't reach for a full nested shell for an inline form-field edit.
+
+## Editor canvas API + state (focus-mode keyboard, zoom controller, [empty] auto-management)
+
+`<editor-shell>` and `<editor-canvas>` expose a small JS API for host wiring of keyboard shortcuts and zoom controllers. Three things you author yourself when building an editor; the substrate does the rest.
+
+### 1. Focus-mode keyboard shortcut (host wires; shell propagates)
+
+`<editor-shell>` carries `.toggleFocusMode()` which flips `[focus-mode]` and auto-propagates: `<editor-toolbar>[full-screen]`, `<editor-canvas>[focused]` (plus calls `<editor-canvas>.focus()` programmatically), and fires `editor-mode-change` with `detail.focusMode`. The shell does NOT bind a keyboard shortcut itself — the host owns the chord.
+
+```html
+<editor-shell id="editor">
+  <editor-toolbar>
+    <span slot="title">Untitled.fig</span>
+    <!-- A toolbar button with [data-toolbar-action] bubbles a `toolbar-action` event
+         on the shell — wire it OR a global keyboard shortcut OR both. -->
+    <button-ui slot="action" data-toolbar-action="toggle-focus"
+               icon="arrows-out" variant="ghost"
+               aria-label="Toggle focus mode"></button-ui>
+  </editor-toolbar>
+  <editor-canvas><!-- canvas content --></editor-canvas>
+</editor-shell>
+
+<script type="module">
+  const editor = document.getElementById('editor');
+
+  // (a) Toolbar-action route — listen to the bubbled custom event
+  editor.addEventListener('toolbar-action', (e) => {
+    if (e.detail?.action === 'toggle-focus') editor.toggleFocusMode();
+  });
+
+  // (b) Global keyboard route — Cmd+. (or Ctrl+. on non-mac) — your call
+  document.addEventListener('keydown', (e) => {
+    const isMac = navigator.platform.includes('Mac');
+    const mod = isMac ? e.metaKey : e.ctrlKey;
+    if (mod && e.key === '.') {
+      e.preventDefault();
+      editor.toggleFocusMode();
+    }
+  });
+
+  // (c) React to the propagation — render a focus-mode-aware UI elsewhere
+  editor.addEventListener('editor-mode-change', (e) => {
+    document.body.classList.toggle('editor-focused', e.detail.focusMode);
+  });
+</script>
+```
+
+**The propagation cascade (substrate-managed; do NOT toggle manually):**
+- `editor-shell` sets `[focus-mode]` on itself → reflected attribute
+- Auto-sets `editor-toolbar[full-screen]` (toolbar can `display: none` under that selector)
+- Auto-sets `editor-canvas[focused]` AND calls `editor-canvas.focus()`
+- Fires `editor-mode-change` `{detail: {focusMode: true|false}}` for host listeners
+
+**Don't toggle `[focus-mode]`, `[full-screen]`, or `[focused]` yourself.** Use `editorShell.toggleFocusMode()` (or set `.focusMode = true/false` directly) and let the shell propagate. Toggling child attributes by hand breaks the focus call into the canvas and the toolbar/canvas state can desync.
+
+### 2. Zoom controller — programmatic + UI integration
+
+`<editor-canvas>` exposes `.zoom` as a getter/setter (default `1.0`) plus `.resetView()` which restores `1.0`. Setting `.zoom` writes `--editor-canvas-zoom` as a CSS custom property on the canvas — the host's canvas content layer can read it for scale transforms:
+
+```html
+<editor-shell>
+  <editor-toolbar>
+    <span slot="title">Document</span>
+    <span slot="status" id="zoom-readout">100%</span>
+    <button-ui slot="action" data-toolbar-action="zoom-out"
+               icon="minus" variant="ghost" aria-label="Zoom out"></button-ui>
+    <button-ui slot="action" data-toolbar-action="zoom-reset"
+               icon="dot" variant="ghost" aria-label="Reset zoom"></button-ui>
+    <button-ui slot="action" data-toolbar-action="zoom-in"
+               icon="plus" variant="ghost" aria-label="Zoom in"></button-ui>
+  </editor-toolbar>
+
+  <editor-canvas id="canvas">
+    <div class="artboard">
+      <!-- Host content scales via --editor-canvas-zoom: -->
+      <!-- .artboard { transform: scale(var(--editor-canvas-zoom, 1)); transform-origin: 0 0 } -->
+    </div>
+  </editor-canvas>
+
+  <editor-statusbar>
+    <span slot="zoom" id="status-zoom">100%</span>
+  </editor-statusbar>
+</editor-shell>
+
+<script type="module">
+  const editor = document.querySelector('editor-shell');
+  const canvas = document.getElementById('canvas');
+  const zoomReadout = document.getElementById('zoom-readout');
+  const statusZoom = document.getElementById('status-zoom');
+
+  const ZOOM_STEPS = [0.25, 0.5, 0.75, 1.0, 1.5, 2.0, 3.0, 4.0];
+  const updateReadouts = () => {
+    const pct = Math.round(canvas.zoom * 100) + '%';
+    zoomReadout.textContent = pct;
+    statusZoom.textContent = pct;
+  };
+
+  editor.addEventListener('toolbar-action', (e) => {
+    const idx = ZOOM_STEPS.findIndex(z => Math.abs(z - canvas.zoom) < 0.01);
+    if (e.detail?.action === 'zoom-in') {
+      canvas.zoom = ZOOM_STEPS[Math.min(idx + 1, ZOOM_STEPS.length - 1)] ?? canvas.zoom;
+    } else if (e.detail?.action === 'zoom-out') {
+      canvas.zoom = ZOOM_STEPS[Math.max(idx - 1, 0)] ?? canvas.zoom;
+    } else if (e.detail?.action === 'zoom-reset') {
+      canvas.resetView();   // resets to 1.0
+    }
+    updateReadouts();
+  });
+
+  // Keyboard: Cmd+= / Cmd+- / Cmd+0 — host owns the chord
+  document.addEventListener('keydown', (e) => {
+    const mod = e.metaKey || e.ctrlKey;
+    if (!mod) return;
+    if (e.key === '=' || e.key === '+') { canvas.zoom = Math.min(canvas.zoom * 1.25, 4); updateReadouts(); e.preventDefault(); }
+    if (e.key === '-')                   { canvas.zoom = Math.max(canvas.zoom / 1.25, 0.25); updateReadouts(); e.preventDefault(); }
+    if (e.key === '0')                   { canvas.resetView(); updateReadouts(); e.preventDefault(); }
+  });
+</script>
+```
+
+**Public API surface on `<editor-canvas>` (from `packages/web-modules/editor/editor-canvas/editor-canvas.js`):**
+
+| API | Type | Note |
+|---|---|---|
+| `.zoom` | number, getter/setter | Default `1.0`. Setting writes `--editor-canvas-zoom` CSS custom property on the host. Host content reads via `transform: scale(var(--editor-canvas-zoom, 1))`. |
+| `.resetView()` | method | Sets `.zoom = 1.0`. Forward-compatible — may also reset scroll position in future revs; don't replicate "set zoom to 1" inline. |
+| `.focus()` | method | Claims focus; reflects `[focused]`. Called automatically by `editor-shell.toggleFocusMode()` when entering focus mode. |
+| `.blur()` | method | Releases focus; clears `[focused]`. |
+| `[empty]` | reflected boolean | **Auto-managed via MutationObserver** — see §3 below. Don't toggle. |
+| `[focused]` | reflected boolean | Auto-set by `.focus()` / `.blur()`. Don't toggle. |
+
+### 3. `[empty]` is auto-managed — don't toggle it yourself
+
+`<editor-canvas>` auto-manages its `[empty]` reflected attribute via a MutationObserver on `childList`: `[empty]` is `true` when there are zero non-`<editor-canvas-empty>` children, `false` otherwise. The `<editor-canvas-empty>` child's visibility is then driven by the parent `[empty]` selector in CSS — entirely declarative, no JS toggling.
+
+```html
+<!-- Right — the canvas auto-detects empty/non-empty -->
+<editor-canvas>
+  <editor-canvas-empty>
+    <empty-state-ui icon="square" heading="New document"
+      description="Drop content to begin."></empty-state-ui>
+  </editor-canvas-empty>
+  <!-- When you append a content child (artboard, doc body, etc.), [empty]
+       flips to false automatically; editor-canvas-empty hides via CSS. -->
+</editor-canvas>
+
+<script type="module">
+  // The right way to "show content":
+  const canvas = document.querySelector('editor-canvas');
+  const artboard = document.createElement('div');
+  artboard.className = 'artboard';
+  canvas.appendChild(artboard);
+  // → [empty] becomes false automatically; empty-state hides.
+
+  // The right way to "clear content":
+  canvas.querySelectorAll(':scope > :not(editor-canvas-empty)').forEach(el => el.remove());
+  // → [empty] becomes true automatically; empty-state shows.
+</script>
+```
+
+**Anti-patterns:**
+
+- ❌ `canvas.toggleAttribute('empty', isEmpty)` — manual toggle. The MutationObserver will fight you on the next childList mutation and reset to whatever it detects.
+- ❌ `canvas.empty = isEmpty` — same problem; the substrate's MutationObserver overrides on next mutation.
+- ❌ Wrapping content in `<editor-canvas-empty>` to "show it conditionally" — `<editor-canvas-empty>` is the empty-state slot; canvas content goes alongside it, not inside it.
+- ❌ Toggling `<editor-canvas-empty>` visibility with `hidden` / `display: none` inline — the canvas's CSS already does that via `:host([empty]) ::slotted(editor-canvas-empty) { display: block }` (light-DOM equivalent: `editor-canvas[empty] > editor-canvas-empty { display: block }`).
+
+**The implication for canvas content loading:** if your editor renders content asynchronously (fetch a document → mount it into the canvas), the empty state shows during the fetch and hides once the first content child mounts. Free behavior — no loading state wiring needed for the empty-state surface.
+
+If you need a *distinct* loading state (vs. empty state — e.g. "loading…" with spinner instead of "drop content to begin"), nest a `<empty-state-ui>` with loading content as a sibling of `<editor-canvas-empty>`, gated by your own attribute:
+
+```html
+<editor-canvas>
+  <editor-canvas-empty>
+    <empty-state-ui icon="square" heading="New document"></empty-state-ui>
+  </editor-canvas-empty>
+  <div data-loading hidden>
+    <empty-state-ui icon="spinner" heading="Loading…"></empty-state-ui>
+  </div>
+  <!-- toggle [data-loading] yourself; [empty] auto-toggles based on child count -->
+</editor-canvas>
+```
+
+## Chat shell (LLM streaming)
+
+Behavior-only LLM-chat surface. Wires message history, streaming
+adapter selection, and the input bar — given `proxy-url=` (or direct
+provider creds) the shell handles the full request/response cycle and
+streams tokens through `<chat-thread>` without any author JS.
+
+Per ADR-0023
+(shipped v0.3.5, all consumers migrated), the **canonical authoring
+shape** uses cluster-namespaced bespoke children.
+
+```html
+<chat-shell
+    proxy-url="/api/chat"
+    provider="anthropic"
+    model="claude-sonnet-4-7"
+    system="You are a helpful assistant.">
+  <chat-header>
+    <span slot="name">Chat with Claude</span>
+    <chat-status slot="status" data-state="connected">Connected</chat-status>
+  </chat-header>
+
+  <chat-thread>
+    <chat-empty>
+      <empty-state-ui icon="chat-circle"
+        heading="Hello!" description="Ask me anything.">
+      </empty-state-ui>
+    </chat-empty>
+  </chat-thread>
+
+  <chat-composer>
+    <chat-input-ui placeholder="Message…" submit-on-enter></chat-input-ui>
+  </chat-composer>
+</chat-shell>
+```
+
+**The 7-element chat cluster (per ADR-0023):**
+- `<chat-shell>` — host orchestrator; reflects `[streaming]` / `[provider]` / `[model]` / `[system]` / `[proxy-url]` / `[thinking]`. Fires 8 events: `submit` (user message), `chunk` (streaming token), `thinking` (extended-thinking content), `done` (response complete), `error`, `abort`, `clear`, `message`.
+- `<chat-header>` — top chrome stub; slot vocabulary `name` / `status` / `action` / `action-leading`. CSS-only.
+- `<chat-thread streaming? empty?>` — scrollable message surface; scroll-to-bottom on new message with user-scroll-up suspension; `[streaming]` + `[empty]` reflected from host.
+- `<chat-empty>` — first-child empty-state slot inside `<chat-thread>`; CSS-only visibility driven by parent `[empty]`.
+- `<chat-composer disabled?>` — wraps `<chat-input-ui submit-on-enter>` (the `submit-on-enter` attribute is **required** for the composer-submit chain to fire on Enter); forwards inner submit as `composer-submit` event (prevents double-fire from the form-tier `submit`); reflects `[disabled]` from host `[streaming]`.
+- `<chat-sidebar slot="leading|trailing" resizable collapsible persist="…">` — conversation rail; mirrors `<admin-sidebar>` API; `[collapsed]` + `[resizing]` reflected; localStorage prefix `adia-chat-sidebar-{persist}`. **Stable in v0.6.x** (no longer "planned").
+- `<chat-status [data-state="streaming|connected|disconnected|…"]>` — inline status indicator; `[data-state]` drives token-coloring (CSS-only).
+
+**Automatic state propagation — don't toggle child attributes manually.** When `<chat-shell>` reflects `[streaming]`, the shell automatically propagates `[streaming]` to `<chat-thread>` and `[disabled]` to `<chat-composer>`. Authors who toggle these by hand race the shell's own writes and produce flicker.
+
+**Pick provider config explicitly.** The host attributes `[provider]` (anthropic / openai / google / stub), `[model]`, `[system]`, `[proxy-url]` (server-side proxy for keys), and `[thinking]` (Anthropic extended-thinking) are the supported surface; everything else routes through events.
+
+**Legacy shapes retired in v0.4.0** (ADR-0024). Pre-v0.4.0 the shell read `<section data-chat-messages>`, `<chat-input-ui data-chat-input>`, and `<empty-state-ui data-chat-empty>` via priority chain; those paths were removed in v0.4.0. Consumers MUST use the bespoke vocabulary.
+
+**Don't reach for chat-shell when:** the surface is a non-LLM messaging UI (use `<chat-thread>` + `<chat-composer>` directly without the shell — they work standalone and you wire your own submit handler). chat-shell's value is the LLM streaming + proxy-url + thinking-mode wiring.
+
+## Simple shell (marketing / error / single-card)
+
+Behavior-light single-surface shell — the canonical wrapper for any
+page that **isn't** an admin dashboard, editor canvas, or LLM chat.
+Use cases per substrate canonicals: marketing splashes, error pages
+(404 / 500 / maintenance), thank-you / confirmation pages, single-card
+flows (sign-in, password reset).
+
+```html
+<simple-shell centered>
+  <simple-hero>
+    <h1 slot="heading">404 — page not found</h1>
+    <p slot="lede">The page you're looking for doesn't exist (or moved).</p>
+    <div slot="actions">
+      <button-ui text="Back to home" variant="primary"></button-ui>
+      <button-ui text="Contact support" variant="ghost"></button-ui>
+    </div>
+  </simple-hero>
+</simple-shell>
+```
+
+**The 3-element simple cluster (per ADR-0023):**
+- `<simple-shell>` — host with two reflected boolean knobs:
+  - `[centered]` — vertically centers content in the viewport (use for 404 / 500 / maintenance / thank-you / sign-in card flows). Replaces the hand-rolled `<main style="display: grid; place-items: center">` pattern.
+  - `[full-bleed]` — drops the max-width constraint on `<simple-content>` children (use for marketing splashes where the hero should span edge-to-edge).
+- `<simple-hero>` — hero region. Slots: `heading` (the `<h1>`), `lede` (a `<p>` description), `actions` (a `<div>` containing one or more `<button-ui>`), default (free-form content after the action row).
+- `<simple-content>` — free-form body region; single default slot; width constrained unless host `[full-bleed]` is set.
+
+```html
+<!-- Marketing splash with two regions -->
+<simple-shell>
+  <simple-hero>
+    <h1 slot="heading">Build UI that ships itself</h1>
+    <p slot="lede">A2UI + AdiaUI — generative UI as a first-class substrate.</p>
+    <div slot="actions">
+      <button-ui text="Get started" variant="primary"></button-ui>
+      <button-ui text="View docs" variant="ghost"></button-ui>
+    </div>
+  </simple-hero>
+  <simple-content>
+    <!-- features grid, testimonials, etc. -->
+  </simple-content>
+</simple-shell>
+```
+
+**Don't reach for simple-shell when:** the surface has a sidebar / topbar / multi-column chrome — that's `<admin-shell>`. Don't author hand-rolled `<main style="display: grid; place-items: center"><card-ui>…</card-ui></main>` either: that re-implements `[centered]` and bypasses the canonical slot vocabulary.
+
+## Nav family — one consolidated set of primitives
+
+Per ADR-0015 § Nav consolidation, the prior 6-element family
+(`<app-nav-ui>` / `<app-nav-group-ui>` / `<app-nav-item-ui>` /
+`<section-nav-ui>` / `<section-nav-group-ui>` / `<section-nav-item-ui>`)
+collapsed into 3 primitives in `@adia-ai/web-components`:
+
+| Primitive | Role | Variants |
+|---|---|---|
+| `<nav-ui>` | Navigation rail | `[variant="primary"]` (default; app sidebar; ResizeObserver collapse to icon-only below 96px). `[variant="section"]` (subnav rail; quieter chrome; optional `[heading]` kicker). |
+| `<nav-group-ui>` | Labeled group of nav items | Inherits parent's variant via CSS cascade. Primary: collapsible header with caret. Section: static kicker label, children always visible. |
+| `<nav-item-ui>` | Single navigation link | Inherits parent's variant via CSS cascade. Primary: icon slot reserved (left indent). Section: empty icon hidden (flat), no leading selected indicator. |
+| `<tabs-ui>` (+ `<tab-ui>`) | In-page section switcher | Lives inside `<card-ui>` header or as a child of `<main>`. NOT for cross-page navigation. |
+
+### Decision rules
+
+1. If the user can navigate AWAY from this page → `<nav-ui>` (sidebar or sub-rail).
+2. If the user is switching VIEWS within the same logical page → `<tabs-ui>`.
+3. App-style sidebar with collapse-to-icons → `<nav-ui>` (default `variant="primary"`).
+4. Sub-rail beside an article (docs, settings hub) → `<nav-ui variant="section">`.
+5. Standalone group/item with section styling outside a section rail → set `[variant="section"]` on the child directly (escape hatch from the cascade).
+
+### Section-variant cascade pattern
+
+`[variant="section"]` on the parent `<nav-ui>` cascades to direct
+descendants via CSS rules using `:not([variant])`. The children's JS
+state (their own `variant` prop) isn't mutated — the cascade is purely
+visual. Explicit `[variant]` on a child always wins.
+
+```html
+<!-- Cascade — children inherit section styling -->
+<nav-ui variant="section" heading="On this page">
+  <nav-group-ui text="Sign in">
+    <nav-item-ui text="Email"   value="/auth/sign-in/email"></nav-item-ui>
+    <nav-item-ui text="Magic"   value="/auth/sign-in/magic"></nav-item-ui>
+  </nav-group-ui>
+  <nav-group-ui text="Sign up">
+    <nav-item-ui text="Profile" value="/auth/sign-up/profile"></nav-item-ui>
+  </nav-group-ui>
+</nav-ui>
+
+<!-- Per-element — same shape, but explicit. Use when no parent rail. -->
+<nav-group-ui variant="section" text="Sign in">
+  <nav-item-ui variant="section" text="Email" value="/email"></nav-item-ui>
+</nav-group-ui>
+
+<!-- Override — primary item inside a section rail -->
+<nav-ui variant="section">
+  <nav-group-ui text="Account">
+    <nav-item-ui text="Profile" value="/profile"></nav-item-ui>
+    <nav-item-ui variant="primary" icon="warning"
+      text="Verify email" value="/verify"></nav-item-ui>
+  </nav-group-ui>
+</nav-ui>
+```
+
+## Table family — table-ui + table-toolbar-ui pairing
+
+A real data table is two components composed:
+
+```html
+<table-toolbar-ui for="members" text="Active members" count="24" no-search>
+  <button-ui slot="actions" text="Invite" variant="primary" icon="plus"></button-ui>
+</table-toolbar-ui>
+
+<table-ui id="members" data-stream-src="/api/members">
+  <!-- columns + rows wired via data-stream attribute -->
+</table-ui>
+```
+
+**Why two components:** the toolbar carries the page-level affordances (title, count badge, filter / sort / columns popovers, debounced search input, bulk-action bar in selection mode); the table carries the rows. Pairing them via `[for]` lets each evolve independently — the toolbar doesn't need to know table internals; the table doesn't need to host its own header.
+
+**Affordances on `<table-toolbar-ui>`:**
+- `[slot="title"]` + `[slot="count"]` — left-cluster identification
+- `[slot="action"]` — right-cluster primary actions (Invite, Export, +New)
+- `[no-search]` / `[no-filter]` / `[no-sort]` / `[no-columns]` — opt out of any of the four built-in affordances. **Default: all four enabled.** (Inverted from a previous default-true API; if you see `[searchable]` / `[filterable]` in old examples that's the deprecated form.)
+- `[variant="card"]` — wraps the toolbar in a card-style chrome for use outside `<card-ui>` parent
+
+**Don't pair table-toolbar with:** `<card-ui>`'s own `<header>`. Pick one — either the toolbar above the table or a card header. Stacking both produces a doubled chrome row.
+
+## Composition recipes
+
+### Admin product page (the common shape)
+
+```html
+<admin-shell mode="rounded borderless">
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header">
+      <!-- Single-product brand chrome (canonical). For multi-tenant, swap to
+           <select-ui workspace-switcher> — see §Brand chrome above. -->
+      <admin-entity-item slot="heading">
+        <icon-ui slot="icon" name="lightning"></icon-ui>
+        <span slot="label">App Name</span>
+      </admin-entity-item>
+    </admin-topbar>
+    <section-ui>
+      <nav-ui>
+        <nav-item-ui icon="users" text="Members" value="/members"></nav-item-ui>
+      </nav-ui>
+    </section-ui>
+    <admin-statusbar slot="footer">
+      <!-- Interactive user menu (multi-tenant). For static user identity, swap to
+           <admin-entity-item> with avatar-ui or icon-ui in slot="icon". -->
+      <select-ui id="user" avatar="…" value="me" variant="ghost" style="flex:1"></select-ui>
+    </admin-statusbar>
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <admin-content>
+    <admin-topbar>
+      <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"></button-ui>
+      <breadcrumb-ui><a href="/">App</a><span>Members</span></breadcrumb-ui>
+      <span data-spacer></span>
+      <div data-actions>
+        <popover-ui placement="bottom-end">
+          <button-ui icon="palette" variant="ghost" size="sm" slot="trigger"></button-ui>
+          <theme-panel slot="content" persist parametric presets scheme-toggle></theme-panel>
+        </popover-ui>
+      </div>
+    </admin-topbar>
+
+    <admin-scroll>
+      <admin-page>
+        <admin-page-header>
+          <header>                          <!-- REQUIRED inner column-owner -->
+            <h1>Members</h1>
+          </header>
+        </admin-page-header>
+        <admin-page-body>
+          <section>                         <!-- REQUIRED inner column-owner -->
+            <card-ui>
+              <header><span slot="heading">Active members</span></header>
+              <section bleed>               <!-- card-ui's own section slot — different element -->
+                <table-toolbar-ui for="members"></table-toolbar-ui>
+                <table-ui id="members">…</table-ui>
+              </section>
+            </card-ui>
+          </section>
+        </admin-page-body>
+      </admin-page>
+    </admin-scroll>
+
+    <admin-statusbar>
+      <span>App</span>
+      <span data-spacer></span>
+      <span>v1.0.0</span>
+    </admin-statusbar>
+  </admin-content>
+
+  <admin-command><command-ui placeholder="Search..."></command-ui></admin-command>
+</admin-shell>
+```
+
+- Admin-shell wraps everything; primary nav lives inside `<admin-sidebar slot="leading">`, NOT as a sibling.
+- Content region is `<admin-content>` containing `<admin-topbar>` + `<admin-scroll>` + `<admin-statusbar>`. The `<admin-scroll>` wraps `<admin-page>` which contains `<admin-page-header>` and `<admin-page-body>`.
+- **The inner `<header>` inside `<admin-page-header>` and the inner `<section>` inside `<admin-page-body>` are REQUIRED column-owners.** They own padding + max-width + section-gap; omitting them drops 40px of inset silently. See §Wrapper-vs-column rule.
+- The two `<section>` elements in this recipe are distinct: the outer is the page-body's centered column; the inner (with `bleed`) is the card's content slot. Both required.
+- Page content is a card per section; toolbar + table inside the card's `<section bleed>` (so the table runs edge-to-edge).
+- `<admin-command>` for the `Cmd+K` palette is always present (even if you don't expose it from the UI yet — wire it up later).
+- Full 13-part anatomy reference: see [§Admin shell](#admin-shell-admin-product-layout) above.
+
+### Docs page (article + sub-rail)
+
+```html
+<main data-docs prose>
+  <nav-ui variant="section">
+    <nav-group-ui text="Components">
+      <nav-item-ui text="Button" value="/components/button"></nav-item-ui>
+      …
+    </nav-group-ui>
+  </nav-ui>
+
+  <article>
+    <h1>Button</h1>
+    <p>…</p>
+  </article>
+</main>
+```
+
+- No admin-shell — this is a doc, not a product surface
+- `<nav-ui variant="section">` is the sub-rail; sits as sibling to `<article>`
+- Children inherit section-variant styling automatically (kicker headers, flat items)
+
+### Editor flow (panes + canvas)
+
+```html
+<editor-shell>
+  <editor-toolbar>…</editor-toolbar>
+  <editor-sidebar slot="leading" collapsible>
+    <pane-ui side="leading" resizable>…</pane-ui>
+  </editor-sidebar>
+  <editor-canvas>
+    <code-ui language="js" editable>…</code-ui>
+  </editor-canvas>
+  <editor-sidebar slot="trailing" collapsible>
+    <pane-ui side="trailing" resizable>…</pane-ui>
+  </editor-sidebar>
+  <editor-statusbar>…</editor-statusbar>
+</editor-shell>
+```
+
+- The center `<editor-canvas>` carries the work surface; `<editor-sidebar>` wraps each `<pane-ui>` on either side
+- Pane sizes persist via `<editor-sidebar>`'s localStorage prefix `adia-editor-sidebar-{name}` (cluster-distinct from admin / chat)
+
+## Anti-patterns
+
+- **Hand-rolling the sidebar toggle** instead of using `[data-sidebar-toggle]`. The shell wires the localStorage persistence + the resize-observer breakpoint logic; rolling your own re-derives both.
+- **Putting `<header>` inside `<main>` of `admin-shell`.** The shell already provides `[slot="header"]`; a second header in main is redundant chrome.
+- **Stacking `<card-ui>` header AND `<table-toolbar-ui>`.** Pick one. Both produce a chrome row above the data; both at once is doubled.
+- **Using `<nav-ui>` (primary) for in-page section switching.** That's `<tabs-ui>`'s job. Nav is for navigating between distinct routes/pages.
+- **Using the OLD `<app-nav-ui>` / `<section-nav-ui>` tags or any of their group/item variants.** The 6-element family was consolidated into 3 primitives in 0.0.33 per ADR-0015 § Nav consolidation. Section-rail migration: `<section-nav-ui …>` → `<nav-ui variant="section" …>`.
+- **Reaching for the `[collapsible]` attribute on `<nav-group-ui>` inside a section rail.** Section-variant groups render as static kicker labels by default; the cascade overrides the `[collapsible="true"]` default. If you really need an interactive collapse inside a section rail, set `[variant=""]` on the group to opt out of the cascade and re-enable primary-style collapse.
+- **Putting `<editor-shell>` outside `<admin-page-body>` when nesting under `<admin-shell>`.** Editor-shell and admin-shell are normally siblings (separate routes / surfaces), but the nested case **is** supported for editor-inside-admin pages (inline page builder, embedded canvas): wrap the editor-shell in `<admin-page-body style="flex: 1; display: flex; flex-direction: column; min-height: 0">` and set `style="flex: 1; min-height: 0"` on the editor-shell itself. Without `min-height: 0` on every ancestor in the flex chain, the inner shell collapses to zero height. Bare `<editor-shell>` directly inside `<admin-shell>` chrome (no `<admin-page-body>` wrapper) is unsupported.
+- **Manually styling pane resize handles** in editor-shell. `<pane-ui resizable>` owns drag; `<editor-sidebar>` wraps it and reflects `[collapsed]` / `[resizing]`. Just place the panes.
+
+## Cross-references
+
+- Layout primitives go inside shells: `patterns-layout.md`
+- Forms inside `admin-shell` main content: `patterns-forms.md`
+- Tables inside cards inside `admin-shell`: `patterns-data.md`
+- Wiring pages through A2UI: `patterns-wiring.md` (all shells participate via `<a2ui-root>` if generated)