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

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

@@ -0,0 +1,1416 @@
+# §Patterns — Concrete answers to prompt-shaped pattern asks
+
+> **Loading note.** Reference bundle extracted from `SKILL.md` per the
+> §LoadingProtocol inversion contract (v2.20.4+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/patterns-recipes.md')`
+> when an active task asks for a concrete recipe matching one of the
+> headings below (admin shell anatomy, REST→component data binding,
+> chart data wiring, segmented-control children rule, entity-list →
+> drawer pattern, status → badge mapping, design-board → token mapping,
+> v0.6.18 loading state, imperative toasts via feed-ui). Skip
+> otherwise.
+>
+> **Transitional bundle.** These 10 recipes were authored inline in
+> SKILL.md §Patterns and extracted as a single bundle in v2.20.4 to
+> get them out of the seed. Future polish cut (v2.21+) may redistribute
+> them into the topic-bundled patterns-{shells,data,forms,layout,wiring}.md
+> files where they would live more naturally:
+>   - Admin shell anatomy + composition tiers → `patterns-shells.md`
+>   - REST data binding + imperative toasts → `patterns-wiring.md`
+>   - Chart wiring + entity list/drawer + status badge + loading state → `patterns-data.md`
+>   - Segmented control rule → `patterns-forms.md`
+>   - Design board → token mapping → standalone or `patterns-layout.md`
+
+Concrete answers to patterns that appear in prompts like
+"Admin UI that loads X from endpoint Y following design board Z."
+
+> **For the visual reference** of any pattern below, browse
+> `https://ui-kit.exe.xyz/site/pages/patterns/`. For markup not covered
+> here, check `.claude/docs/guides/71-recipes.md` (in-repo) or fetch the relevant
+> page-shell template from `https://ui-kit.exe.xyz/site/modules/`.
+
+## Admin shell anatomy
+
+> ⚠️ **Shell CSS is REQUIRED and not auto-imported.** Before any
+> `<admin-shell>` markup renders, your entry file MUST contain:
+>
+> ```ts
+> import '@adia-ai/web-modules/shell/admin-shell.css';
+> ```
+>
+> `admin-shell.js` does NOT self-import its layout CSS — every layout
+> rule (the fixed-viewport flex grid, sidebar widths, topbar/statusbar
+> heights, scroll geometry, bespoke-tag selectors) lives in
+> `admin-shell.css`. **This is policy, not a bug** — see §CSSPolicy
+> above for the full reasoning (light-DOM cascade control, tree-shake
+> honesty, theme layering). Omitting the import produces an **unstyled
+> stacked divs layout with no error or warning** — the sidebar renders
+> above the content instead of beside it. Same caveat for `chat-shell`,
+> `editor-shell`, `simple-shell` — import the matching CSS for the shell
+> tag you use (`shell/admin-shell.css`, `chat/chat-shell.css`,
+> `editor/editor-shell.css`, `simple/simple-shell.css`).
+
+> ℹ️ **There is only ONE CSS file per shell — `admin-shell.css`.** (FB-06)
+> The `./shell/*.css` exports wildcard makes `@adia-ai/web-modules/shell/
+> admin-topbar.css` / `admin-sidebar.css` / `admin-content.css` /
+> `admin-page.css` / `admin-scroll.css` *look* like they should resolve,
+> but **none of those files exist on disk**. Vite 8 (rolldown) fails to
+> resolve them at build time with a terse error. Every sub-component
+> style (topbar layout, sidebar grid, content scroll geometry, page
+> sticky-header band, bespoke-tag selectors) is bundled into
+> `admin-shell.css`. Import it once and you're done. Same convention for
+> the other shells: one CSS file per shell tag, all sub-component styles
+> bundled. The `admin-command.css` import is the ONE exception — it
+> ships separately because the command palette is opt-in and most apps
+> don't use it.
+
+```html
+<admin-shell>
+  <!-- v0.6.13+: bare <admin-shell> auto-promotes to mode="rounded borderless"
+       on connectedCallback. Any explicit mode="..." attribute is respected
+       verbatim (including mode="" for the flat legacy chrome). The empty
+       string is the only opt-out; omitting the attribute entirely uses the
+       modern soft-chrome default. -->
+  <!-- Sidebar: navigation lives here -->
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header">
+      <span slot="heading">Claims Portal</span>
+    </admin-topbar>
+    <nav-ui>
+      <a href="/claims">Claims</a>
+      <a href="/policies">Policies</a>
+      <a href="/adjusters">Adjusters</a>
+    </nav-ui>
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <!-- Main content area -->
+  <admin-content>
+    <admin-topbar>
+      <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"></button-ui>
+      <breadcrumb-ui></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>
+      <!-- SPA route content lives here — the framework's route element
+           (e.g. <vue-router-view />, <Outlet />, <slot />, <lit-route-outlet>)
+           goes inside <admin-scroll>. In SSR contexts (Next.js / Nuxt /
+           SvelteKit / Astro / Rails+Turbo / Django+HTMX / Phoenix), the
+           framework's route children fill <admin-scroll> directly — there
+           is no separate route-outlet element. See §Rendering Model →
+           Routing ownership for the per-framework substitution table.
+           There is exactly ONE route owner per app — running two at once
+           causes click-double-handling and URL/content desync. -->
+      <!-- your router outlet here -->
+    </admin-scroll>
+    <admin-statusbar>
+      <span>App</span>
+      <span data-spacer></span>
+      <span>v1.0.0</span>
+    </admin-statusbar>
+  </admin-content>
+
+  <!-- Cmd+K command palette -->
+  <admin-command>
+    <command-ui placeholder="Search claims…"></command-ui>
+  </admin-command>
+</admin-shell>
+```
+
+Route setup requires a **one-time script block** — this is the sole
+legitimate exception to "no `<script>`". The script only wires routing
+metadata; it emits no layout or components:
+
+> ⚠️ **SPA-only.** Skip this script entirely in SSR. Next.js / Nuxt /
+> SvelteKit / Astro / Rails+Turbo / Django+HTMX / Phoenix all own
+> routing themselves (filesystem routes + framework `<Link>` /
+> `link_to` / `<.link>` primitives). See §Rendering Model → Routing
+> ownership for the per-framework path. Adding this script in SSR
+> creates two competing route owners.
+
+> ✅ **Router provider — auto-registered from the barrel at v0.6.40+.**
+> `import '@adia-ai/web-components'` side-effect-imports
+> `core/provider.js` (which registers `<router-ui>`). The router
+> "just works" after the standard cold-start import.
+>
+> ⚠️ **Subpath-imported consumers must register the provider
+> explicitly.** Apps with bundle-size SLOs that skip the main
+> barrel — `import '@adia-ai/web-components/components/button'` etc.
+> — must add `import '@adia-ai/web-components/core/provider';`
+> alongside their primitive imports. Omitting it makes
+> `<router-ui>` render as `HTMLUnknownElement`,
+> `router.routes = [...]` silently no-op (no error, no warning),
+> and the route content area stay empty. Same failure mode applies
+> in any consumer setup that side-effect-imports per-primitive
+> instead of the full barrel.
+>
+> ```ts
+> // Bundle-size-conscious cold-start:
+> import '@adia-ai/web-components/components/button';
+> import '@adia-ai/web-components/components/table';
+> // ...
+> import '@adia-ai/web-components/core/provider';  // <-- router
+> ```
+>
+> Source: `core/provider.js` `customElements.define('router-ui', UIRouter)`;
+> barrel-side-effect-import added 2026-05-25 (FB-72 substrate fix).
+
+```html
+<script type="module">
+  // The ONLY script block allowed — route wiring, not layout
+  const router = document.querySelector('router-ui');
+  router.routes = [
+    { path: '/claims',         content: '/pages/claims-list.html',   title: 'Claims' },
+    { path: '/claims/:id',     content: '/pages/claim-detail.html',  title: 'Claim Detail' },
+    { path: '/policies',       content: '/pages/policies.html',      title: 'Policies' },
+  ];
+</script>
+```
+
+Each page file is a standalone HTML fragment (no `<html>` wrapper).
+`<router-ui>` fetches and injects the fragment on navigation.
+
+## App-shell composition tiers — Advanced / Simple / Minimal (branched checklist)
+
+The admin-shell anatomy above is the **canonical structure**, but real
+apps differ in how many of the shell's optional surfaces they actually
+populate. Pick a tier explicitly **at the §0 Reasoning Gate** — don't
+defer it until mid-composition. The default for any new product surface
+is **Advanced**; drop down only when there's a specific reason.
+
+Use the matching tier as the starting checklist; then trim
+component-by-component as your audit justifies it. Live references:
+[admin-shell.examples.html](https://ui-kit.exe.xyz/site/components/admin-shell)
+ships a side-by-side gallery of all three tiers.
+
+#### Decision rule
+
+```
+Does the product span more than one platform / sub-product?    → Advanced
+Does the app need an authenticated user identity?              → Advanced
+Does the surface need contextual help / changelog visibility?  → Advanced
+   ↓ NONE of the above:
+Does the app need authentication + a meaningful nav tree?      → Simple
+   ↓ otherwise:
+Single page or two-route demo, no auth, flat nav               → Minimal
+```
+
+When in doubt, **start Advanced and trim**. Adding `<context-switcher>`
+or a trailing sidebar to a Minimal scaffold mid-build is a multi-slot
+refactor; removing them from an Advanced scaffold is delete-only.
+
+#### Tier checklists
+
+| Surface | Advanced (default) | Simple | Minimal |
+|---|---|---|---|
+| **Leading sidebar** (`<admin-sidebar slot="leading">`) | ✓ resizable + collapsible | ✓ collapsible | ✓ (no resize) |
+| ↳ Context switcher (top, `<select-ui avatar="…" value="…" variant="ghost">` for workspace/product jump) | ✓ | — (static brand `<span slot="heading">`) | — (static brand) |
+| ↳ `<nav-ui>` with `<nav-item-ui>` + `<nav-group-ui>` + dividers | ✓ grouped + nested + badges + dividers | ✓ groups, no badges | ✓ flat nav-item-ui only |
+| ↳ User menu (sidebar footer `<admin-statusbar slot="footer">` + `<select-ui avatar="…" value="…" variant="ghost">`) | ✓ avatar + account + sign-out | ✓ sign-in entry only | — |
+| **Topbar** (`<admin-topbar slot="header">` inside `<admin-content>`) <sup>*</sup> | ✓ | ✓ | ✓ |
+| ↳ Leading: sidebar toggle button + `<breadcrumb-ui>` (hydrated) | ✓ | ✓ | ✓ |
+| ↳ Trailing `slot="action"`: theme toggle + sidebar toggle for trailing sidebar | ✓ | ✓ (theme only) | — |
+| **Scroll region** (`<admin-scroll>`) | ✓ | ✓ | ✓ |
+| ↳ `<router-ui>` (SPA) or framework children (SSR, see §Rendering Model → Routing ownership) | ✓ | ✓ | ✓ |
+| ↳ `<admin-page>` wrapping route content | ✓ | ✓ | ✓ |
+| ↳ `<admin-page-header>` with `<header>` + `<tabs-ui>` for page-scoped tabs | ✓ | ✓ (no tabs unless the page needs them) | — (h1 only) |
+| ↳ `<admin-page-body>` for page content | ✓ | ✓ | ✓ |
+| **Content statusbar** (`<admin-statusbar slot="footer">` inside `<admin-content>`) | ✓ pkg + skill versions (overrideable) | — | — |
+| **Trailing sidebar** (`<admin-sidebar slot="trailing">`) | ✓ changelog / contextual help | — | — |
+| **Command palette** (`<admin-command>`) | ✓ Cmd+K `<command-ui>` | optional | — |
+
+#### Advanced — full markup (start here for any new product surface)
+
+> **SoT alignment.** This markup mirrors `site/index.html` (the live
+> docs-site shell at `ui-kit.exe.xyz`) and `admin-shell.examples.html`'s
+> sidebar-variant gallery (the canonical demo). Where the two diverge,
+> the gallery is the new-code canonical form; `site/index.html` ships
+> a few legacy patterns (`[data-actions]` instead of `slot="action"`,
+> `data-sidebar-toggle-trailing` boolean instead of
+> `data-sidebar-toggle="trailing"` value) that admin-topbar.yaml flags
+> as "for one release, prefer slots." This skill teaches the
+> new-canonical forms; if you're working in the chat-ui repo itself,
+> the docs site's bespoke wiring may differ.
+>
+> <sup>*</sup> **`<admin-topbar slot="header">` vs no-slot.** Both forms work and render identically. `<admin-content>` is light-DOM per ADR-0033 (no shadow root), so `slot="header"` is inert and CSS positions `<admin-topbar>` by tag + DOM order regardless. This skill and `site/index.html` use `slot="header"` for parity with substrate demos; `loading-protocol.md`'s 13-part list uses the no-slot form. Both are correct; do not "fix" one to the other.
+
+```html
+<admin-shell mode="rounded borderless">
+
+  <!-- ═══ Leading sidebar ═══
+       name="…" attribute is OPTIONAL — defaults to the slot value
+       ("leading" / "trailing") for localStorage namespacing. Only set
+       it when running multiple sidebars with the same slot. -->
+  <admin-sidebar slot="leading" resizable collapsible>
+
+    <!-- Top: context switcher (jump between products / platforms /
+         workspaces). Canonical pattern: <select-ui avatar="…" value="…"
+         variant="ghost"> — used by the live docs site at
+         ui-kit.exe.xyz/site/examples/admin-dashboard (chat-ui:site/index.html
+         line 47). The `avatar` attribute renders the leading image; the
+         `value` attribute selects the current option from .options=[…].
+         No <span slot="trigger"> hand-roll needed — the primitive
+         self-stamps the trigger row (avatar + label + caret-up-down).
+
+         Legacy form (admin-shell.examples.html v0.5.x): <menu-ui> with
+         a button-trigger holding brand logo + label + caret. Still
+         works but is NOT the canonical pattern as of v0.6.30 — the
+         site shell migrated to select-ui because it handles
+         workspace/user dropdown cases more cleanly (auto avatar
+         stamping, value+options data binding, narrower API surface).
+         menu-ui remains correct for richer non-dropdown trigger menus
+         (multi-level command menus, etc.) but NOT for the
+         context-switcher slot. -->
+    <admin-topbar slot="header">
+      <select-ui id="workspace-select"
+                 avatar="/icons/brand.svg"
+                 value="studio"
+                 variant="ghost"
+                 style="flex:1">
+        <!-- Options hydrated via .options = [{ value, label, icon? }, …]
+             in the page's main.ts. The primitive stamps the listbox +
+             trigger row automatically. -->
+      </select-ui>
+    </admin-topbar>
+
+    <!-- Middle: nav with groups + dividers + badges.
+         Canonical wrapper: <section-ui> (the AdiaUI primitive). Used by
+         the live docs site at chat-ui:site/index.html line 50. The
+         section-ui wrap is what admin-sidebar's light-DOM CSS targets
+         for inner scroll + padding rules; native <section> works in
+         simple cases but loses the scroll-area treatment that
+         section-ui provides.
+
+         Legacy form: native <section>. The admin-shell.examples.html
+         "Advanced" gallery uses native <section> from before
+         section-ui shipped. Treat it as a deprecated alternate; prefer
+         <section-ui>. -->
+    <section-ui>
+      <nav-ui>
+        <nav-item-ui icon="house" text="Dashboard" value="dashboard" selected></nav-item-ui>
+        <nav-item-ui icon="tray"  text="Inbox"     value="inbox" badge="12"></nav-item-ui>
+
+        <hr data-nav-divider>
+
+        <nav-group-ui icon="chart-line" text="Analytics" open>
+          <nav-item-ui text="Overview"  value="an-overview"></nav-item-ui>
+          <nav-item-ui text="Funnels"   value="an-funnels"></nav-item-ui>
+          <nav-item-ui text="Retention" value="an-retention"></nav-item-ui>
+        </nav-group-ui>
+
+        <nav-group-ui icon="folders" text="Content">
+          <nav-item-ui text="Pages"  value="content-pages"></nav-item-ui>
+          <nav-item-ui text="Media"  value="content-media" badge="3"></nav-item-ui>
+          <nav-item-ui text="Drafts" value="content-drafts"></nav-item-ui>
+        </nav-group-ui>
+
+        <hr data-nav-divider>
+
+        <nav-group-ui icon="gear" text="Settings">
+          <nav-item-ui text="General" value="settings-general"></nav-item-ui>
+          <nav-item-ui text="Members" value="settings-members"></nav-item-ui>
+          <nav-item-ui text="Billing" value="settings-billing"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    </section-ui>
+
+    <!-- Bottom: user menu (avatar + account menu).
+         Inside an <admin-sidebar slot="leading"> the <admin-statusbar
+         slot="footer"> is the USER MENU band. Same primitive used at
+         <admin-content slot="footer"> = VERSION-STRIP band (see below).
+
+         Canonical pattern: <select-ui avatar="…" value="…" variant="ghost">
+         — used by the live docs site (chat-ui:site/index.html line 62).
+         Same primitive as the context-switcher above; the `avatar`
+         attribute auto-stamps the leading image (use a URL like
+         `https://i.pravatar.cc/32?u=username` or your own /icons/ path).
+
+         Legacy form (admin-shell.examples.html v0.5.x): <menu-ui> with
+         a button-trigger holding <avatar-ui> + name. Still works but is
+         NOT the canonical pattern as of v0.6.30; the docs site
+         migrated to select-ui for the same reasons as the
+         context-switcher above (auto avatar stamping, narrower API
+         surface, value+options data binding). -->
+    <admin-statusbar slot="footer">
+      <select-ui id="user-select"
+                 avatar="https://i.pravatar.cc/32?u=maya"
+                 value="maya"
+                 variant="ghost"
+                 style="flex:1">
+        <!-- Options: { value: 'maya', label: 'Maya Chen', icon: 'user' }, etc.
+             For account actions (Profile / Settings / Sign out), add
+             them as option items; select-ui emits change events on
+             selection that the page can route to the right action. -->
+      </select-ui>
+    </admin-statusbar>
+
+    <!-- Legacy menu-ui form (kept for reference; do not use for new
+         shells — site/index.html is canonical):
+
+         <admin-statusbar slot="footer">
+           <menu-ui placement="top-start">
+             <button type="button" slot="trigger" class="user-switcher">
+               <avatar-ui text="Maya Chen" size="sm"></avatar-ui>
+               <span class="user-label">Maya Chen</span>
+               <icon-ui name="caret-up-down" size="14"></icon-ui>
+             </button>
+             <menu-item-ui icon="user"     text="Profile"          value="profile"></menu-item-ui>
+             <menu-item-ui icon="gear"     text="Account settings" value="account"></menu-item-ui>
+             <menu-item-ui icon="moon"     text="Appearance"       value="appearance"></menu-item-ui>
+             <menu-divider-ui></menu-divider-ui>
+             <menu-item-ui icon="sign-out" text="Sign out"         value="signout"></menu-item-ui>
+           </menu-ui>
+         </admin-statusbar>
+    -->
+
+    <!-- Read-only identity primitive — admin-entity-item.
+         The canonical shell-tier identity-row primitive (shipped
+         @adia-ai/web-modules@0.7.13, FEEDBACK-38). Use it on EITHER
+         end of <admin-sidebar>:
+           - <admin-topbar slot="header"> for brand chrome (single-
+             product, no switcher) — see patterns-shells.md §Brand
+             chrome Pattern A
+           - <admin-statusbar slot="footer"> for user identity (non-
+             interactive, no menu)
+
+         Geometry mirrors <select-ui>'s trigger row (icon ≡ leading,
+         label ≡ display, badge ≡ caret) so it aligns 1px-perfect with
+         <nav-item-ui> icons in the section between header and footer.
+         The wrapper collapses as one slottable unit inside a
+         collapsible sidebar: icon survives, label + badge hide. Without
+         admin-entity-item, bare [slot="icon"] + [slot="heading"]
+         siblings have no shared collapse boundary and land at the
+         topbar's --page-sidebar-px (4px) — 8px short of nav alignment.
+
+         Brand chrome (header):
+         <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>
+
+         User identity (footer):
+         <admin-statusbar slot="footer">
+           <admin-entity-item slot="heading">
+             <icon-ui slot="icon" name="user-circle"></icon-ui>
+             <span slot="label">Kim Granlund</span>
+             <badge-ui slot="badge" text="Operator" size="sm" variant="muted"></badge-ui>
+           </admin-entity-item>
+         </admin-statusbar>
+
+         For an INTERACTIVE workspace switcher OR user menu, keep the
+         <select-ui>/<menu-ui> trigger patterns above. admin-entity-item
+         is read-only display; select-ui/menu-ui are interactive. -->
+
+
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <!-- ═══ Main content area ═══ -->
+  <admin-content>
+
+    <admin-topbar slot="header">
+      <!-- Leading: sidebar toggle + hydrated breadcrumb.
+           data-sidebar-toggle="leading|trailing" is the canonical
+           value-bearing attribute (per admin-shell.js wiring); the
+           sidebar matches by its `name` attribute (default = slot value). -->
+      <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"></button-ui>
+      <breadcrumb-ui>
+        <a href="/">Studio</a>
+        <a href="/analytics">Analytics</a>
+        <span aria-current="page">Overview</span>
+      </breadcrumb-ui>
+
+      <!-- Trailing: persistent app-wide controls.
+           slot="action" is the new-code canonical anchor (v0.6.13+).
+           The legacy <div data-actions> hook still works (admin-topbar.yaml
+           "coexists for one release") and is what the docs-site shell
+           ships today; new code should prefer slot="action".
+
+           For richer theme control than scheme toggle (light/dark/system),
+           swap <toggle-scheme-ui> for <popover-ui> + <theme-panel> — the
+           docs site uses the panel form. -->
+      <toggle-scheme-ui slot="action" scheme="auto"></toggle-scheme-ui>
+      <button-ui slot="action" data-sidebar-toggle="trailing" icon="sidebar-simple-reverse" variant="ghost" size="sm"></button-ui>
+    </admin-topbar>
+
+    <admin-scroll>
+      <!-- SPA: the router outlet stays EMPTY in the shell — admin-page +
+           admin-page-header + admin-page-body live in the ROUTE FRAGMENT
+           (a separate .html file loaded by the router). The shell defines
+           layout; routes define page content. See the "Route fragment"
+           snippet below. SSR: omit the outlet entirely — see §Rendering
+           Model → Routing ownership. -->
+      <!-- your router outlet here -->
+    </admin-scroll>
+
+    <!-- Content statusbar: status / version-strip. The same <admin-statusbar>
+         primitive that hosted the user menu in the sidebar is the
+         version-strip band when used at admin-content slot="footer".
+         Use <span data-spacer> to push trailing content to the end.
+         The version label is meant to be overridden per-product (sync
+         indicator, last-saved timestamp, row count, etc.). -->
+    <admin-statusbar slot="footer">
+      <span>Adia Studio</span>
+      <span data-spacer></span>
+      <span id="version-label">v0.6.19</span>
+    </admin-statusbar>
+
+  </admin-content>
+
+  <!-- ═══ Trailing sidebar — changelog / contextual help ═══
+       Starts hidden — click the trailing-sidebar toggle in the topbar
+       to reveal. resizable + collapsible matches the leading sidebar
+       so users get consistent affordances. -->
+  <admin-sidebar slot="trailing" resizable collapsible hidden>
+    <admin-topbar slot="header">
+      <span slot="heading">What's new</span>
+      <!-- Close button — slot="action" cluster (canonical) -->
+      <button-ui slot="action" data-sidebar-toggle="trailing" icon="x" variant="ghost" size="sm" aria-label="Close changelog"></button-ui>
+    </admin-topbar>
+    <section-ui>
+      <text-ui variant="kicker">v0.6.18 · 2026-05-21</text-ui>
+      <text-ui variant="heading">Loading state is first-class</text-ui>
+      <text-ui>
+        <code>&lt;stat-ui loading&gt;</code> + <code>&lt;table-ui loading&gt;</code> now
+        render skeleton placeholders while data fetches. Pair with
+        <code>data-stream-*</code> for declarative loading.
+      </text-ui>
+    </section-ui>
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <!-- ═══ Cmd+K command palette ═══ -->
+  <admin-command>
+    <command-ui placeholder="Search anything…"></command-ui>
+  </admin-command>
+
+</admin-shell>
+```
+
+**Route fragment** (`pages/overview.html`) — the content the router
+fetches and injects into `<router-ui>` on navigation. Each route is a
+standalone HTML fragment with no `<html>` / `<body>` wrapper:
+
+```html
+<admin-page>
+  <admin-page-header>
+    <header>
+      <div>
+        <h1>Overview</h1>
+        <div data-actions>
+          <button-ui text="Export" icon="download"></button-ui>
+          <button-ui text="New"    variant="primary" icon="plus"></button-ui>
+        </div>
+      </div>
+    </header>
+    <tabs-ui value="summary">
+      <tab-ui value="summary">Summary</tab-ui>
+      <tab-ui value="trends">Trends</tab-ui>
+      <tab-ui value="cohorts">Cohorts</tab-ui>
+    </tabs-ui>
+  </admin-page-header>
+  <admin-page-body>
+    <section>
+      <!-- Page content — KPI cards, tables, charts wired via data-stream-* -->
+    </section>
+  </admin-page-body>
+</admin-page>
+```
+
+> ⚠️ **`<admin-page-body>` needs an inner column-owner** —
+> `<section>` (or `<header-ui>` / `<section-ui>` / `<iframe>` /
+> `<editor-shell>` / `<pane-ui>`). The wrapper element is a
+> flex/grid container that doesn't own the `--card-inset` padding;
+> a bare `<col-ui>` / `<grid-ui>` / `<card-ui>` directly inside
+> renders edge-to-edge with zero gutter. The inner `<section>` carries
+> the inset. Same shape for `<admin-page-header>` and its inner
+> `<header>` — both wrap a content-owner. See
+> `patterns-shells.md` §Wrapper-vs-column callout + the matching
+> §5 entry in `common-gotchas-consumer.md`. Mechanically
+> enforced via `npm run audit:admin-page-structure --strict`.
+
+Route wiring (the one-time script block from "Admin shell anatomy"
+above) connects each route path to its fragment URL.
+
+**SSR variant** — in Next.js / Nuxt / SvelteKit / Astro the route
+fragment is whatever the framework injects as `{children}` /
+`<slot />` / `<Astro.children />`; the empty `<router-ui>` slot in
+`<admin-scroll>` is replaced by that injection point. See
+§Rendering Model → Routing ownership for the full per-framework table.
+
+#### Simple — Advanced minus context-switcher, trailing sidebar, content statusbar
+
+Use when there's **one product**, optional auth, and no need for
+persistent contextual chrome. Delta from Advanced (5 deletions):
+
+```diff
+  <admin-sidebar slot="leading" resizable collapsible name="primary">
+    <admin-topbar slot="header">
+-     <select-ui avatar="…" value="…" variant="ghost"></select-ui>   <!-- context-switcher -->
++     <span slot="heading">My App</span>                              <!-- static brand -->
+    </admin-topbar>
+    <section-ui><nav-ui>…</nav-ui></section-ui>
+    <admin-statusbar slot="footer">
+      <!-- Either: <select-ui avatar="…"> for full account, OR a single Sign-in entry: -->
+-     <select-ui avatar="…" value="…" variant="ghost"></select-ui>   <!-- full user menu -->
++     <button-ui text="Sign in" variant="ghost" icon="sign-in"></button-ui>
+    </admin-statusbar>
+  </admin-sidebar>
+
+  <admin-content>
+    <admin-topbar slot="header">…</admin-topbar>
+    <admin-scroll>
+      <router-ui><admin-page>…</admin-page></router-ui>
+    </admin-scroll>
+-   <admin-statusbar slot="footer">…version-strip…</admin-statusbar>
+  </admin-content>
+
+- <admin-sidebar slot="trailing" collapsible name="changelog">…</admin-sidebar>
+  <admin-command>…</admin-command>
+</admin-shell>
+```
+
+Keep the topbar trailing `slot="action"` cluster (theme toggle is still
+useful even without a trailing sidebar). Drop the trailing-sidebar
+toggle button since the trailing sidebar is gone.
+
+#### Minimal — Advanced minus auth, statusbar (both), trailing sidebar, command palette, tabs
+
+Use for single-page demos, two-route prototypes, or embedded surfaces
+where the parent already owns chrome. Delta from Advanced:
+
+```diff
+  <admin-shell>
+    <admin-sidebar slot="leading" collapsible name="primary">  <!-- no resizable -->
+      <admin-topbar slot="header">
+-       <select-ui avatar="…" value="…" variant="ghost"></select-ui>   <!-- context-switcher -->
++       <span slot="heading">My App</span>
+      </admin-topbar>
+      <section-ui>
+        <nav-ui>
+-         <nav-item-ui …badge="12"></nav-item-ui>
+-         <nav-group-ui …>…</nav-group-ui>             <!-- no groups -->
++         <nav-item-ui icon="house"   text="Home"     value="home" selected></nav-item-ui>
++         <nav-item-ui icon="folder"  text="Items"    value="items"></nav-item-ui>
++         <nav-item-ui icon="gear"    text="Settings" value="settings"></nav-item-ui>
+        </nav-ui>
+      </section-ui>
+-     <admin-statusbar slot="footer">…</admin-statusbar>   <!-- no user menu -->
+    </admin-sidebar>
+
+    <admin-content>
+      <admin-topbar slot="header">
+        <button-ui data-sidebar-toggle="leading" icon="sidebar" …></button-ui>
+        <breadcrumb-ui>…</breadcrumb-ui>
+-       <toggle-scheme-ui slot="action" …></toggle-scheme-ui>
+-       <button-ui slot="action" data-sidebar-toggle="trailing" …></button-ui>
+      </admin-topbar>
+      <admin-scroll>
+        <router-ui>
+          <admin-page>
+            <admin-page-header>
+              <header><h1>Home</h1></header>
+-             <tabs-ui>…</tabs-ui>                       <!-- no tabs -->
+            </admin-page-header>
+            <admin-page-body>…</admin-page-body>
+          </admin-page>
+        </router-ui>
+      </admin-scroll>
+-     <admin-statusbar slot="footer">…version-strip…</admin-statusbar>
+    </admin-content>
+
+-   <admin-sidebar slot="trailing" …>…</admin-sidebar>
+-   <admin-command>…</admin-command>
+  </admin-shell>
+```
+
+#### Authoring discipline
+
+- **Default to Advanced.** It's delete-only to step down. Stepping up is
+  a multi-slot refactor.
+- **Audit against SoT BEFORE authoring.** The canonical references are
+  `site/index.html` (the live docs-site shell), `apps/saas/app/
+  admin-dashboard/admin-dashboard.contents.html` (a real product
+  surface), and `packages/web-modules/shell/admin-shell/admin-shell.examples.html`'s
+  sidebar-variant gallery. When yaml + SoT disagree (e.g. `slot="action"`
+  vs `[data-actions]`), yaml is the new-code canonical — but check
+  whether the SoT lags before deciding which to ship in a chunk that
+  must work against the deployed system. **A 30-second `cat site/index.html`
+  prevents the divergence class.**
+- **Each removal must be justified at the §0 Reasoning Gate.** "There's
+  no second product" → context-switcher out. "No authenticated identity"
+  → user-menu out. "No persistent chrome need" → trailing sidebar out.
+- **`name="…"` on sidebars is OPTIONAL.** It defaults to the slot value
+  (`"leading"` / `"trailing"`) for `localStorage` namespacing. Only set
+  it when running multiple sidebars with the same slot (e.g. two
+  trailing sidebars on different routes).
+- **`data-sidebar-toggle="<name>"` is value-bearing.** Buttons target
+  the sidebar by its `name` attribute (default = slot value). The
+  docs-site shell ships a bespoke boolean form
+  `data-sidebar-toggle-trailing` — that's the docs site's own wiring,
+  NOT the canonical contract documented in `admin-shell.js`.
+- **`<admin-statusbar>` is dual-use.** Inside `<admin-sidebar slot="leading">
+  slot="footer">` it's the **user menu band**. Inside `<admin-content>
+  slot="footer">` it's the **content version-strip / status band**.
+  Same primitive, different host = different role.
+- **`<admin-page-header>` always wraps a `<header>`** (native HTML). Inside it,
+  put `<h1>` + the action cluster in a title-row `<div>`
+  (`<div><h1/><div data-actions>…</div></div>`) — `[data-actions]` is what the
+  substrate right-aligns; a bare `<span slot="action">` is NOT styled for
+  `admin-page-header` and stacks under the `<h1>`. Tabs go AFTER the `<header>`
+  but still inside `<admin-page-header>`.
+- **`<router-ui>` stays EMPTY in the shell.** `<admin-page>` +
+  `<admin-page-header>` + `<admin-page-body>` live in the **route
+  fragment** — a separate `.html` file loaded by the router on
+  navigation. The shell defines layout; routes define page content.
+  Putting `<admin-page>` inline inside `<router-ui>` makes the page
+  static across all routes (the router can't replace it).
+- **The version-strip in the content statusbar is meant to be
+  overridden.** Most products replace it with their own status content
+  (sync indicator, row count, last-saved timestamp). Keep the
+  `<span data-spacer></span>` between leading + trailing spans to
+  preserve the push-to-end layout.
+
+## Data binding: REST endpoint → component
+
+Use `data-stream-*` attributes for declarative HTTP binding.
+**No `fetch()` calls in script blocks.** No manual DOM updates.
+
+```html
+<!-- GET /api/claims every 10s → table rows -->
+<table-ui
+  data-stream-src="/api/claims"
+  data-stream-interval="10000"
+  data-stream-path="items">
+</table-ui>
+
+<!-- GET /api/stats (one-shot) → KPI card -->
+<stat-ui
+  label="Open Claims"
+  data-stream-src="/api/stats"
+  data-stream-target="value"
+  data-stream-path="open_count">
+</stat-ui>
+
+<!-- SSE stream → live updates -->
+<table-ui
+  data-stream-src="/api/claims/live"
+  data-stream-mode="sse"
+  data-stream-event="claim-updated">
+</table-ui>
+```
+
+| Attribute | Purpose | Example |
+|---|---|---|
+| `data-stream-src` | Endpoint URL | `/api/claims` |
+| `data-stream-interval` | Poll interval (ms) | `10000` |
+| `data-stream-mode` | `fetch` (default) or `sse` | `sse` |
+| `data-stream-path` | JSON path into response | `items`, `data.claims` |
+| `data-stream-target` | Which property to set | `value`, `rows`, `textContent` |
+| `data-stream-method` | HTTP method | `POST` |
+| `data-stream-headers` | JSON headers string | `{"Authorization":"Bearer …"}` |
+| `data-stream-id` | Share one transport across elements | `claims-feed` |
+
+**Shared transport:** two elements with the same `data-stream-id` share
+one HTTP connection:
+
+```html
+<stat-ui data-stream-id="claims-feed" data-stream-src="/api/claims" data-stream-path="total" data-stream-target="value" label="Total"></stat-ui>
+<table-ui data-stream-id="claims-feed" data-stream-path="items"></table-ui>
+```
+
+## Chart data wiring
+
+`chart-ui` takes its data as a **JS property** — an array of plain objects —
+plus `x=` / `y=` attributes naming which object key maps to each axis. It is
+**not** the Chart.js `{ labels, datasets }` envelope; passing that (or any
+non-array) renders a blank chart (a one-shot `console.warn` flags it).
+
+```js
+const chart = document.querySelector('chart-ui');
+chart.data = [
+  { month: 'Jan', revenue: 3200, expenses: 2100 },
+  { month: 'Feb', revenue: 4100, expenses: 2400 },
+];
+```
+
+```html
+<!-- x= / y= name the object keys. Multi-series: comma-separate y. -->
+<chart-ui type="bar"  x="month" y="revenue"></chart-ui>
+<chart-ui type="line" x="month" y="revenue,expenses"></chart-ui>
+
+<!-- Sparkline / pie / donut: y only, no x -->
+<chart-ui type="sparkline" y="revenue"></chart-ui>
+```
+
+`x` and `y` are documented props in `chart.yaml`; `.data` is a JS property
+(also settable as a `data="[…]"` JSON-string attribute). The Chart.js
+`{ labels, datasets }` shape is a different library's API — never chart-ui's.
+
+## Segmented control — children must be `<segment-ui>`
+
+`segmented-ui`'s children must be `<segment-ui>` custom elements. A bare
+`<segment>` tag renders its text but receives **no** sliding indicator, no
+`role="radio"` / `aria-checked`, and no reliable `change` state — silently
+(a one-shot `console.warn` flags a non-`segment-ui` child).
+
+```html
+<!-- CORRECT -->
+<segmented-ui value="30d">
+  <segment-ui value="30d" text="30d"></segment-ui>
+  <segment-ui value="7d"  text="7d"></segment-ui>
+  <segment-ui value="1d"  text="1d"></segment-ui>
+</segmented-ui>
+
+<!-- WRONG — bare <segment> breaks the indicator + a11y -->
+<segmented-ui value="30d">
+  <segment value="30d">30d</segment>
+</segmented-ui>
+```
+
+Importing `@adia-ai/web-components/components/segmented` pulls in
+`<segment-ui>` transitively — no separate `components/segment` import needed.
+
+## Entity list → detail drawer pattern
+
+The canonical pattern for "list of claims → click row → detail panel":
+
+```html
+<!-- List view -->
+<table-ui id="claims-table" data-stream-src="/api/claims" data-stream-path="items">
+</table-ui>
+
+<!-- Detail drawer: header + body + dual-cluster footer -->
+<drawer-ui id="claim-drawer" side="right" size="lg">
+
+  <header slot="header">
+    <col-ui gap="1">
+      <h3 id="drawer-title">Claim Detail</h3>
+      <badge-ui id="drawer-status-badge" size="sm" hidden></badge-ui>
+    </col-ui>
+    <span slot="action">
+      <button-ui id="drawer-close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>
+    </span>
+  </header>
+
+  <section slot="body" id="claim-detail-body">
+    <!-- populated by row-select event.
+         NOTE: drawer-ui's body slot is the content surface.
+         Wrap stacked content in <col-ui gap="N"> if you need vertical rhythm;
+         drawer body has no default flex layout (only padding inset). -->
+  </section>
+
+  <footer slot="footer">
+    <!-- Dual-cluster footer: destructive on the left, commit on the right -->
+    <span slot="action-leading">
+      <button-ui id="drawer-delete" text="Delete" icon="trash" variant="danger" hidden></button-ui>
+    </span>
+    <span slot="action">
+      <button-ui id="drawer-cancel" text="Cancel" variant="ghost"></button-ui>
+      <button-ui id="drawer-save"   text="Save"   variant="primary" disabled></button-ui>
+    </span>
+  </footer>
+
+</drawer-ui>
+
+<script type="module">
+  // Row-select wiring — the only permitted script
+  document.getElementById('claims-table').addEventListener('select', e => {
+    const drawer = document.getElementById('claim-drawer');
+    const body = document.getElementById('claim-detail-body');
+    // Populate detail from event.detail.row
+    body.querySelector('[data-field="id"]').textContent = e.detail.row.id;
+    drawer.open = true;
+  });
+</script>
+```
+
+> **Button density inside the drawer.** Header close button: `size="sm"`
+> (icon-only, tucked in the corner — matches topbar chrome convention).
+> Footer commit/cancel/delete buttons: **default size (no `size=` attribute)**
+> — these are terminal commit/cancel/delete affordances on the user's
+> decision moment; sub-sizing them with `size="sm"` makes them feel
+> optional on the ~80px footer band. See §Button density by surface below.
+
+> **Dual-cluster footer layout.** `slot="action-leading"` (destructive,
+> left edge) + `slot="action"` (commit/cancel, trailing edge) is the
+> canonical Delete/Cancel/Save layout. Do NOT wrap the buttons in a `<div>`
+> — drawer-ui's footer CSS positions each `[slot=…]` cluster directly;
+> wrapping bypasses the slot grid (same anti-pattern as card-ui header).
+
+> **Drawer slot vocabulary.** `<drawer-ui>` internally creates the
+> `<dialog>` host; **content MUST be slotted** via `slot="header"` /
+> `slot="body"` / `slot="footer"` (the three positioned slots). Direct
+> children with no `slot=` attribute do not project — the drawer renders
+> empty. The earlier `<card-ui>` wrapper shape (recipe pre-2026-05-25)
+> still works but offloads chrome ownership to the card; for terminal
+> commit/cancel flows, native drawer slots give cleaner footer layout.
+
+### Button density by surface
+
+The footer-vs-chrome size convention matters across the kit. Default
+size = "the action is the surface's primary purpose"; `size="sm"` =
+"the action is one of many chrome affordances in a dense band":
+
+| Surface | `size=` | Why |
+|---|---|---|
+| admin-topbar / chat-header / editor-toolbar | `"sm"` | Chrome density; many buttons in a narrow band |
+| card-ui header action cluster | `"sm"` | Matches kebab-menu / icon-button neighbor density |
+| table-toolbar-ui actions | `"sm"` | Same chrome-band density |
+| drawer-ui **header** close button | `"sm"` | Icon-only corner-tucked affordance |
+| **drawer-ui footer** commit/cancel/delete | **default** | Terminal-action; needs visual weight on the decision moment |
+| modal-ui footer commit/cancel | default | Same logic as drawer footer |
+| admin-page-header action cluster | default | Page-level CTAs feel primary, not chrome |
+| inline-form commit/cancel | default | Same |
+
+When in doubt: `size="sm"` for chrome-band buttons (topbar, card-header,
+toolbar); default size for content-band terminal-action buttons (drawer
+footer, modal footer, page-header CTAs, form commits).
+
+**drawer-ui vs modal-ui decision:**
+- `drawer-ui` — detail panels, contextual editing, side-by-side review
+- `modal-ui` — confirmation dialogs, destructive actions, focused forms
+
+## Entity status → badge variant mapping
+
+| Domain status | `badge-ui` variant |
+|---|---|
+| Open / Active / New | `info` |
+| In Review / Processing | `warning` |
+| Approved / Resolved / Complete | `success` |
+| Rejected / Failed / Overdue | `danger` |
+| Closed / Archived / Inactive | `neutral` |
+
+## Card-ui header — slotted children, NOT `<div>` wrapper
+
+`<card-ui>` exposes a `<header>` slot that uses CSS Grid activated by
+`:has(> [slot])`. h1-h6 elements auto-place into the heading column
+without an explicit slot; elements with `slot="action"` go into the
+trailing auto-width action column. The `1fr auto` grid only activates
+when at least one **direct child** of `<header>` carries a `slot=`
+attribute.
+
+> ⚠️ **Anti-pattern: wrapping heading + action in a `<div>` bypasses
+> the grid entirely.** The grid activator (`:has(> [slot])`) doesn't
+> match because the `<header>`'s direct child is the `<div>`, which
+> has no `slot=`. Both elements fall into the unslotted full-width
+> fallback row — the action badge appears below the title instead of
+> right-aligned.
+
+**Wrong** (action appears below title — grid never activates):
+
+```html
+<card-ui>
+  <header>
+    <div>                                       <!-- ✗ bare div bypasses grid -->
+      <h3>Title</h3>
+      <tag-ui>Badge</tag-ui>
+    </div>
+  </header>
+</card-ui>
+```
+
+**Correct** (h3 auto-placed in 1fr heading column, tag-ui in trailing auto column):
+
+```html
+<card-ui>
+  <header>
+    <h3>Title</h3>                              <!-- auto-placed: 1fr heading column -->
+    <tag-ui slot="action" size="sm">Badge</tag-ui>  <!-- slot=action: trailing auto column -->
+  </header>
+</card-ui>
+```
+
+**Available header slots**:
+
+| Slot | Position | Notes |
+|------|----------|-------|
+| `icon` (leading) | left of heading | optional |
+| `heading` (1fr) | main column | `<h1>`–`<h6>` auto-place without explicit `slot=` |
+| `description` (row 2) | spans full width | for sub-text below heading |
+| `action` (trailing auto) | right edge | badges, buttons, kebab menus |
+
+**CSS mechanism** (from `card.css`, for reference):
+- `header:has(> [slot]) { display: grid; gap: … }` — grid only activates with slotted child
+- `header :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 1; grid-row: 1 }`
+- `header:not(:has(> [slot="icon"])):has(> [slot="action"]) { grid-template-columns: 1fr auto }`
+
+**Detection** (manual): visually, the badge appears below or beside-the-wrong-edge of the title. No console error — it's a silent layout regression.
+
+**Source**: 2026-05-23 docs-overhaul session generated this pattern repeatedly; the failure required visual debugging to identify. Documented to prevent recurrence in agent-generated card markup.
+
+### Card-ui header — inline title + controls without `slot=action`
+
+The CSS grid only activates when at least one direct child carries `slot=`. Two unslotted siblings (e.g., `<text-ui>` + `<button-ui>`) fall into the unslotted fallback row, which is `display: block` — they stack vertically instead of sharing one row.
+
+**Wrong** (controls stack BELOW the title):
+
+```html
+<card-ui>
+  <header>
+    <text-ui weight="600">Recent activity</text-ui>   <!-- no slot — fallback row -->
+    <button-ui size="sm" text="View all"></button-ui> <!-- no slot — next fallback row -->
+  </header>
+</card-ui>
+```
+
+**Right A** (slot-grid path — canonical for hand-authored HTML):
+
+```html
+<card-ui>
+  <header>
+    <h3>Recent activity</h3>                          <!-- auto-placed: 1fr -->
+    <button-ui slot="action" size="sm" text="View all"></button-ui> <!-- trailing -->
+  </header>
+</card-ui>
+```
+
+**Right B** (`<row-ui>` fallback — for contexts that strip `slot=`):
+
+```html
+<card-ui>
+  <header>
+    <row-ui justify="space-between" align="center">
+      <h3>Recent activity</h3>
+      <button-ui size="sm" text="View all"></button-ui>
+    </row-ui>
+  </header>
+</card-ui>
+```
+
+**When to use each**:
+- Right A is preferred — minimal markup, uses the primitive's intended grammar
+- Right B is required when authoring corpus HTML for the A2UI gen-UI pipeline. The transpiler strips `slot=` attributes from many native-element children (`<span slot="action">`, `<text-ui slot="description">`). The `<row-ui>` form survives transpilation intact.
+
+## Card-ui vs `<card-ui raw>` — surface-vs-chrome decision
+
+`<card-ui>` defaults to a **chromed surface** (background + border + shadow). `<card-ui raw>` strips that chrome — content structure (`<header>`/`<section>`/`<footer>` grammar) still applies, but the parent owns the visible surface.
+
+| Use | When |
+|---|---|
+| `<card-ui>` (default) | Standalone content surface on a page background — dashboards, settings cards, summary tiles, list containers, form containers. The card IS the visible boundary. |
+| `<card-ui raw>` | Layout wrapper where the parent already owns the surface — auth screens centred on the viewport, embedded inside another chromed container, transparent column collectors. The card carries the slot grammar but not the chrome. |
+
+**Two recurring anti-patterns**:
+
+1. **Defaulting to `raw` when a chromed surface is intended.** Card content (icon + heading + body + footer) floats against the page background with no visible boundary. Looks "minimal" but is the symptom of "missed default" — the agent reached for `raw` to skip thinking about surface.
+
+2. **Non-raw card without an explicit `<header>`.** The card has chrome but no title — the first visible content element (a `<field-ui label="…">`, a `<list-item-ui>`'s primary text, the first paragraph) becomes the de-facto heading visually. Reads as "two-title card" when label text and content text both compete for top-of-card primacy. Always include `<header>` with an explicit title on non-raw cards.
+
+```html
+<!-- WRONG — chrome present, no header → field-ui label reads as "Section heading" -->
+<card-ui>
+  <section>
+    <field-ui label="Email addresses">…</field-ui>
+  </section>
+</card-ui>
+
+<!-- RIGHT — explicit header owns the title; field-ui label is field-scoped -->
+<card-ui>
+  <header><h3>Invite teammates</h3></header>
+  <section>
+    <field-ui label="Email addresses">…</field-ui>
+  </section>
+</card-ui>
+```
+
+**Source**: 2026-05-26 gen-review cycle 17 surfaced this across 8 demos (invite-members, contact-form, billing-overview, role-management, status-dashboard, audit-log, integrations-grid, webhook-config). Non-raw card without `<header>` was indistinguishable from a `<card-ui raw>` field group at first glance.
+
+## Design board → AdiaUI token mapping
+
+When the user provides a Figma board or screenshot:
+
+1. **Extract intent, not values.** Read the board for visual hierarchy,
+   component patterns, and UX intent — not pixel measurements.
+2. **Map design components to AdiaUI primitives.** A Figma "Status Chip"
+   → `<badge-ui>`. A Figma "Data Row" → `<table-ui>` row. A Figma
+   "Side Panel" → `<drawer-ui>`.
+3. **Map colors to semantic tokens** — never copy hex values:
+   - Primary brand color → `var(--a-primary-bg)` / `var(--a-primary-fg)`
+   - Danger/error red → `var(--a-danger-strong)`
+   - Neutral gray → `var(--a-chrome-*)`
+   - Surface background → `var(--a-bg)` / `var(--a-bg-muted)` / `var(--a-bg-strong)`
+4. **Flag mismatches.** If the board shows a component AdiaUI doesn't have
+   (e.g. a custom Gantt chart, a specialized calendar heatmap), flag it
+   explicitly in the GenUI Plan `deviations:` field — do not silently
+   approximate it with the wrong primitive.
+5. **Do not override tokens.** No inline `style="color: #3b82f6"`.
+   If the design calls for a color not in the token system, that is a
+   design system gap to surface to the user, not a one-off override.
+
+## Loading state (v0.6.18 — `stat-ui` + `table-ui`)
+
+Pre-v0.6.18, consumers hand-rolled skeleton CSS to bridge the gap between
+mount and first data render. v0.6.18 adds `loading` as a first-class
+prop on the two highest-leverage data-display primitives:
+
+```html
+<!-- KPI cards: loading skeleton until value/change arrive -->
+<stat-ui label="Total Revenue" loading></stat-ui>
+
+<!-- When data arrives, flip loading off and set the value+change -->
+<script>
+  const card = document.querySelector('stat-ui');
+  fetchKPI().then(({value, change, trend}) => {
+    card.removeAttribute('loading');
+    card.setAttribute('value', value);
+    card.setAttribute('change', change);
+    card.setAttribute('trend', trend);
+  });
+</script>
+```
+
+```html
+<!-- Tables: skeleton rows preserve header + columns -->
+<table-ui id="recent" paginate="10" loading></table-ui>
+
+<script>
+  const t = document.getElementById('recent');
+  t.columns = [{key:'name',label:'Name'}, /* … */];
+  fetchRows().then(rows => {
+    t.data = rows;
+    t.removeAttribute('loading');
+  });
+</script>
+```
+
+**What v0.6.18 ships:**
+
+- `<stat-ui loading>` — renders `<skeleton-ui>` shimmer in the value + change
+  slots. Label + icon are preserved (static metadata). Host gets `aria-busy="true"`.
+- `<table-ui loading>` — renders N ghost skeleton rows (N = `paginate` capped at 8,
+  else 5). Header + columns stay intact so layout is preserved. Host gets
+  `aria-busy="true"`. Pre-v0.6.18 the impl was a `<progress-ui>` spinner overlay
+  even though the yaml description always said "skeleton rows" — that drift is
+  now fixed.
+
+**`chart-ui` does NOT have a `loading` prop** — by design. `chart-ui` is a
+renderer over already-shaped data; loading-state belongs in the container
+wrapping it. Canonical pattern:
+
+```html
+<card-ui>
+  <section>
+    <!-- Wrap chart-ui with a sibling skeleton-ui while data fetches -->
+    <skeleton-ui height="180px" width="100%" id="chart-skeleton"></skeleton-ui>
+    <chart-ui hidden id="my-chart"></chart-ui>
+  </section>
+</card-ui>
+```
+
+This split (own-state for data-prop primitives, compose-state for renderers)
+is intentional. See `components/chart/chart.examples.html` for the canonical
+demo, and `outbox/FEEDBACK-12--...--followup.md` for the design discussion.
+
+## Button `text=` + `icon=` symbol doubling (FEEDBACK-15 trap)
+
+`<button-ui>` renders `icon=` as a prepended `<icon-ui>` child AND
+renders `text=` as the visible label. When `text=` begins with the
+same symbol the icon already provides — `+` / `-` / `×` / `✓` / `→` /
+`←` — the glyph renders **twice**. Substrate console-warns via
+`ICON_TEXT_PREFIXES` in `node_modules/@adia-ai/web-components/components/button/class.js:23-30`,
+but the warn is per-element WeakSet-guarded and easy to miss in a
+noisy dev console.
+
+```html
+<!-- Right -->
+<button-ui text="New Claim" icon="plus" variant="primary"></button-ui>
+
+<!-- Wrong — doubled "+"; substrate console-warns (FEEDBACK-15) -->
+<button-ui text="+ New Claim" icon="plus" variant="primary"></button-ui>
+```
+
+**Discipline: `icon=` provides the glyph; `text=` is the semantic
+label only.** Strip the symbol from `text=` whenever the icon
+provides it. Covered collision pairs (substrate `ICON_TEXT_PREFIXES`):
+
+| `icon=` | symbols stripped from `text=` |
+|---|---|
+| `plus` | `+`, `＋` |
+| `minus` | `-`, `−`, `–` |
+| `x` | `×`, `x `, `X ` |
+| `check` | `✓`, `✔` |
+| `arrow-right` | `→`, `>` |
+| `arrow-left` | `←`, `<` |
+
+The list is high-frequency, not exhaustive. If you find a doubled
+glyph that isn't covered (e.g. `dots-three` + `…`), the discipline
+still applies — substrate just won't warn yet.
+
+## Imperative toasts via `feed-ui` (FB-11 P2)
+
+`<feed-ui position="bottom-right">` is the toast container. To post a toast
+imperatively, either:
+
+**Option A — global CustomEvent (works everywhere, no import needed):**
+
+```js
+window.dispatchEvent(new CustomEvent('feed', {
+  detail: { kind: 'success', title: 'Saved', message: 'Changes synced.' }
+}));
+```
+
+This is the canonical, lowest-friction API. `feed.js` (loaded via the
+barrel import `@adia-ai/web-components`) installs a global listener on
+`window` that routes `'feed'` CustomEvents to `UIFeed.post()`. No
+import needed — just dispatch the event from any module / framework /
+inline script.
+
+**Option B — explicit class import:**
+
+```ts
+import { UIFeed } from '@adia-ai/web-components/components/feed/class';
+UIFeed.post({ kind: 'success', title: 'Saved', message: 'Changes synced.' });
+```
+
+The canonical import path is the `/class` shorthand (resolves via the
+`./components/*/class` exports pattern). Do NOT try
+`@adia-ai/web-components/components/feed/feed.js` — Node's exports
+wildcards can't substitute across multiple path segments, so it resolves
+to a phantom nested path and fails. (Verified end-to-end in FB-11.)
+
+**Post-options shape (same for both APIs):**
+
+```ts
+{
+  kind:    'success' | 'info' | 'warning' | 'danger',
+  title:   string,
+  message: string,
+  timeout: number,  // ms, 0 = sticky
+}
+```
+
+## Editor inspector pane (right-side property form inside `<editor-sidebar slot="trailing">`)
+
+The canonical right-pane idiom inside `<editor-shell>` is a property
+inspector. It's not a separate component — it's a composition of
+primitives the editor cluster expects in the trailing sidebar.
+
+```html
+<editor-sidebar slot="trailing" collapsible persist="inspector">
+  <pane-ui side="trailing" resizable min-width="200">
+    <header>
+      <span>Inspector</span>
+      <span slot="action">
+        <button-ui id="wrap-btn" icon="brackets-square" variant="ghost" size="sm" title="Wrap selection"></button-ui>
+        <button-ui id="duplicate-btn" icon="copy" variant="ghost" size="sm" title="Duplicate"></button-ui>
+      </span>
+    </header>
+    <section>
+      <fields-ui>
+        <field-ui label="Name">
+          <input-ui name="name" value="..."></input-ui>
+        </field-ui>
+        <field-ui label="Variant">
+          <select-ui name="variant" data-options='[{"value":"primary","label":"Primary"}]'></select-ui>
+        </field-ui>
+        <field-ui label="Size">
+          <segmented-ui>
+            <segment-ui value="sm" text="Sm"></segment-ui>
+            <segment-ui value="md" text="Md"></segment-ui>
+            <segment-ui value="lg" text="Lg"></segment-ui>
+          </segmented-ui>
+        </field-ui>
+      </fields-ui>
+    </section>
+  </pane-ui>
+</editor-sidebar>
+```
+
+**Why this shape:**
+- `<pane-ui side="trailing" resizable>` carries the inner-edge resize seam (per `pane.yaml` a2ui.rules — `[side]` flips grabber + chrome to the inner edge).
+- `<header>` slot is what `<pane-ui>` projects as the pane title; `[slot="action"]` button cluster pushes to the trailing edge.
+- `<section>` carries the form rows. Use `<fields-ui>` + `<field-ui label="…">` for the typed-row scaffolding — `<field-ui>` is the canonical label+control wrapper, not a raw `<label>`.
+- Persistence via `persist="inspector"` puts pane width under `adia-editor-sidebar-inspector` localStorage key (cluster-distinct from admin and chat sidebars).
+
+**Pitfalls:**
+- Don't substitute raw `<div>` for `<fields-ui>` — the typography + spacing tokens hang on the bespoke wrapper. Reference: `apps/genui/a2ui-editor/` for the production canonical.
+- Don't put header `[slot="action"]` buttons *outside* the `<header>` element. The pane projects them via the header projection.
+- A non-resizable inspector (fixed-width detail rail) drops `resizable` from `<pane-ui>` but keeps `persist=` for future toggleability.
+
+## Editor sub-views inside `<editor-canvas>` (Preview / Schema / DOM toggle)
+
+When an editor has multiple representations of the same document
+(preview pane vs schema text vs DOM text), the canonical shape is a
+`<tabs-ui>` inside `<editor-canvas-toolbar>` driving multiple
+`<div data-view="…">` panels inside the canvas body.
+
+```html
+<editor-canvas>
+  <editor-canvas-toolbar>
+    <tabs-ui id="view-tabs" value="preview" variant="underline">
+      <tab-ui value="preview" text="Preview" icon="eye"></tab-ui>
+      <tab-ui value="schema"  text="Schema"  icon="brackets-curly"></tab-ui>
+      <tab-ui value="dom"     text="DOM"     icon="code"></tab-ui>
+    </tabs-ui>
+  </editor-canvas-toolbar>
+
+  <div data-view-body>
+    <div data-view="preview">
+      <!-- live rendered tree -->
+    </div>
+    <div data-view="schema" hidden>
+      <code-ui id="schema-code" language="json" editable bare></code-ui>
+    </div>
+    <div data-view="dom" hidden>
+      <!-- nested canvas-toolbar for HTML/CSS/JS sub-tabs -->
+      <editor-canvas-toolbar>
+        <tabs-ui id="dom-tabs" value="html" variant="underline">
+          <tab-ui value="html" text="HTML"></tab-ui>
+          <tab-ui value="css"  text="CSS"></tab-ui>
+          <tab-ui value="js"   text="JS"></tab-ui>
+        </tabs-ui>
+      </editor-canvas-toolbar>
+      <div data-dom-body>
+        <div data-dom-view="html"><code-ui language="html" bare></code-ui></div>
+        <div data-dom-view="css" hidden><code-ui language="css" bare></code-ui></div>
+        <div data-dom-view="js"  hidden><code-ui language="javascript" bare></code-ui></div>
+      </div>
+    </div>
+  </div>
+</editor-canvas>
+```
+
+**Why this shape:**
+- `<editor-canvas-toolbar>` is canvas-scope chrome (sticky at the top of the canvas body, per the yaml SoT). Distinct from the app-scope `<editor-toolbar>` at the top of `<editor-shell>`.
+- `<tabs-ui>` is the in-page section switcher (per the nav-decision rule — "switching views within the same logical page" not "navigating away").
+- The wiring is dead-simple: a `[value]` listener on `<tabs-ui>` flips the `[hidden]` attribute on the matching `<div data-view="…">`. The shell doesn't need to know about the sub-views.
+- Nested toolbars work: a sub-view can contain its own `<editor-canvas-toolbar>` for sub-sub-tabs. The DOM nesting is enough — the CSS doesn't constrain depth.
+
+**Pitfalls:**
+- Don't use `<editor-toolbar>` for view-mode tabs. `<editor-toolbar>` is app-scope (top of the shell, document-wide actions); `<editor-canvas-toolbar>` is canvas-scope (top of the canvas, view-mode affordances). The yaml SoT spells this out in `editor-canvas-toolbar.yaml`'s `a2ui.rules`.
+- Don't toggle `[hidden]` on `<tab-ui>` — toggle it on the `<div data-view="…">` panels. The tabs-ui keeps its own selected-state via `[value]`.
+- Programmatic writes to a focused `<code-ui editable bare>` are no-ops by design (render-guard prevents clobbering in-flight typing). If you `.text = X` while user is typing in Schema view, the write silently won't apply. Intentional — don't "fix" it.
+
+Production canonical: `apps/genui/a2ui-editor/` uses this exact shape with three top-level views + nested DOM sub-tabs.
+
+---
+
+## Meta / Introspection surfaces
+
+**Pattern class:** Internal tooling, review galleries, audit dashboards, dogfood harnesses — any page whose purpose is *inspecting the system itself* rather than *using it*.
+
+**Structural rules that consumer patterns don't cover:**
+
+### 1. No nested card chrome
+
+The most common mistake: wrapping a prompt block in a card, then wrapping the output inside another card. Every level of card chrome implies "this is a standalone surfaced thing" — but in an inspection surface, the hierarchy is already established by document headings.
+
+❌ Wrong:
+```html
+<card-ui>          <!-- prompt "card" -->
+  <header>...</header>
+  <section>
+    <card-ui>      <!-- output card inside -->
+      <header>...</header>
+      <section><canvas-ui></canvas-ui></section>
+    </card-ui>
+  </section>
+</card-ui>
+```
+
+✅ Right — flat document rhythm:
+```html
+<section class="prompt-row">     <!-- role: document section, not card -->
+  <h3>Login Form</h3>
+  <code class="prompt-text">"login form with email and password"</code>
+  <!-- flat tab bar, no wrapper chrome -->
+  <div role="tablist">...</div>
+  <div class="output-area">      <!-- single inset, not a card -->
+    <canvas-ui></canvas-ui>
+  </div>
+</section>
+```
+
+### 2. Headings as section breaks, not card headers
+
+Use `h2` / `h3` for group and prompt labels. A card header is for interactive chrome that needs the card's slot vocabulary (icon, action, description). A static label needs none of that — it's just a heading.
+
+```html
+<!-- group -->
+<h2>Auth <badge-ui text="6" variant="muted" size="sm"></badge-ui></h2>
+
+<!-- individual item -->
+<h3>Login Form</h3>
+```
+
+### 3. Code for literal values
+
+Prompt strings, output IDs, version tags, selectors — any value the user will read verbatim or copy:
+
+```html
+<!-- prompt text -->
+<code class="prompt-text">"login form with email and password"</code>
+
+<!-- copyable ID chip -->
+<code class="output-id">auth-login-form-Z-v2</code>
+```
+
+Font: `var(--a-font-family-code, ui-monospace, monospace)`. Not `--a-font-family` (proportional).
+
+### 4. Tab bars flush to content, no padding wrapper
+
+Engine or view-mode tabs sit directly above their output, separated only by a 1px border. They don't need a padded container.
+
+```css
+.gallery-tabs {
+  display: flex;
+  border-bottom: 1px solid var(--a-border-subtle);
+  /* No padding, no background card, no border-radius */
+}
+.gallery-tab[aria-selected="true"] {
+  border-bottom: 2px solid var(--a-accent-strong);
+  color: var(--a-accent-strong);
+}
+```
+
+### 5. Inset-not-card for output areas
+
+The rendered output area gets visual containment via `background: var(--a-bg-subtle)` + `border: 1px solid var(--a-border-subtle)` + `border-radius`. That's enough — no `<card-ui>` wrapper needed.
+
+```css
+.output-area {
+  background: var(--a-bg-subtle);
+  border: 1px solid var(--a-border-subtle);
+  border-radius: var(--a-radius-md);
+  padding: var(--a-space-4);
+  min-height: 200px;
+  max-height: 600px;
+  overflow-y: auto;
+}
+```
+
+### 6. Two-column inspection layout
+
+Left: sticky anchor-link rail to jump between groups (not a `<toc-ui>` — that auto-scans headings; here we want explicit curated links).  
+Right: scrollable content with generous padding.
+
+```html
+<div style="display:grid;grid-template-columns:220px 1fr;min-height:100dvh;">
+  <nav style="position:sticky;top:0;height:100dvh;overflow-y:auto;border-right:1px solid var(--a-border-subtle);padding:var(--a-space-4);">
+    <!-- explicit group links, not toc-ui -->
+    <a href="#group-auth" class="rail-link">Auth <small>(6)</small></a>
+    ...
+  </nav>
+  <main style="padding:var(--a-space-6);">
+    <!-- groups -->
+  </main>
+</div>
+```
+
+**When to use this pattern:**
+- Gen UI output gallery
+- Eval result browsers
+- Audit log / drift report pages
+- Any internal tooling surface where the content IS the system's output
+
+**What separates this from `patterns-shells.md`:** Shell patterns are for product pages users navigate to complete tasks. Meta surfaces are for operators inspecting or debugging the system — document-like, dense, information-first, no decorative chrome.