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

package/skills/adia-ui-kit/references/flows-interaction.md

@@ -0,0 +1,181 @@
+# §Flows — Modals, command palette, profile card, marketing hero
+
+> **Loading note.** Reference bundle extracted from `SKILL.md` per the
+> §LoadingProtocol inversion contract (v2.20.3+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/flows-interaction.md')`
+> When wiring transient/interactive surfaces — Cmd+K palette, destructive confirmation modal, editable profile card, landing-page hero. Skip if your task doesn't involve these surfaces — the
+> seed has a stub naming each flow + the load invocation.
+
+### Command palette (Cmd+K)
+
+The signature AdiaUI quick-action surface. Modal + autofocused search +
+filterable command list. Almost always paired with admin shell.
+
+```html
+<modal-ui id="cmdk">
+  <header>
+    <input-ui placeholder="Search commands..." prefix="magnifying-glass" autofocus></input-ui>
+  </header>
+  <section>
+    <command-ui></command-ui>
+  </section>
+</modal-ui>
+```
+
+```html
+<!-- Open via Cmd+K (admin-shell wires this automatically via <admin-command>) -->
+<script type="module">
+  document.addEventListener('keydown', (e) => {
+    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+      e.preventDefault();
+      document.getElementById('cmdk').open = true;
+    }
+  });
+</script>
+```
+
+Inside `<admin-shell>`, use `<admin-command>` as the slot — Cmd+K is wired
+for you, no script needed.
+
+---
+
+
+### Destructive confirmation modal
+
+The "type the name to confirm" pattern. Always use `<modal-ui>` not
+`<drawer-ui>` for destructive actions.
+
+```html
+<modal-ui id="confirm-delete">
+  <header>
+    <span slot="icon">
+      <avatar-ui icon="warning-circle"></avatar-ui>
+    </span>
+    <span slot="heading"><text-ui strong>Are you sure?</text-ui></span>
+  </header>
+  <section>
+    <col-ui gap="3">
+      <text-ui>
+        This action cannot be undone. Type the resource name below to confirm.
+      </text-ui>
+      <field-ui label="Resource name">
+        <input-ui id="confirm-name" placeholder="my-resource-123"></input-ui>
+      </field-ui>
+    </col-ui>
+  </section>
+  <footer>
+    <row-ui gap="2" justify="end">
+      <button-ui text="Cancel" variant="ghost"
+        onclick="this.closest('modal-ui').open = false"></button-ui>
+      <button-ui id="confirm-delete-btn" text="Delete" color="danger" disabled></button-ui>
+    </row-ui>
+  </footer>
+</modal-ui>
+
+<script type="module">
+  // Enable Delete only when typed name matches
+  const resourceName = 'my-resource-123';
+  const input = document.getElementById('confirm-name');
+  const btn = document.getElementById('confirm-delete-btn');
+  input.addEventListener('input', () => {
+    btn.disabled = input.value !== resourceName;
+  });
+</script>
+```
+
+---
+
+
+### User profile card (editable)
+
+Avatar + form fields + save/cancel. Common in settings, team management.
+
+```html
+<card-ui style="max-width: 32rem">
+  <header>
+    <row-ui gap="3" align="center">
+      <avatar-ui text="Jane Doe" size="lg"></avatar-ui>
+      <col-ui gap="0">
+        <text-ui weight="semibold" size="lg">Jane Doe</text-ui>
+        <text-ui color="subtle">Product Designer</text-ui>
+      </col-ui>
+    </row-ui>
+  </header>
+  <section>
+    <col-ui gap="3">
+      <field-ui label="Email" inline>
+        <input-ui type="email" value="jane@example.com"></input-ui>
+      </field-ui>
+      <field-ui label="Role" inline>
+        <select-ui value="designer">
+          <option value="designer">Designer</option>
+          <option value="engineer">Engineer</option>
+          <option value="manager">Manager</option>
+        </select-ui>
+      </field-ui>
+      <field-ui label="Bio" inline>
+        <textarea-ui rows="2">Building design systems at AdiaUI</textarea-ui>
+      </field-ui>
+    </col-ui>
+  </section>
+  <footer>
+    <row-ui gap="2" justify="end">
+      <button-ui text="Cancel" variant="ghost" size="sm"></button-ui>
+      <button-ui text="Save" variant="primary" size="sm"></button-ui>
+    </row-ui>
+  </footer>
+</card-ui>
+```
+
+
+---
+
+
+### Marketing hero + CTA
+
+Centered headline, lede, two-button row. The canonical wrapper is
+`<simple-shell>` + `<simple-hero>` (substrate ships this exactly for
+marketing splashes). Use a bare `<section>` only when embedding inside
+another shell (e.g. an `<admin-page-body>` content region).
+
+```html
+<simple-shell>
+  <simple-hero>
+    <text-ui slot="heading" size="sm" color="accent" weight="semibold" style="letter-spacing:0.05em">ADIAUI v0.6</text-ui>
+    <h1 slot="heading">Build UIs with natural language</h1>
+    <p slot="lede">
+      Light-DOM web components + generative UI pipeline.
+      Ship faster, iterate smarter.
+    </p>
+    <div slot="actions">
+      <button-ui text="Get started" variant="primary" size="lg"></button-ui>
+      <button-ui text="See demo" size="lg" icon="play-circle"></button-ui>
+    </div>
+  </simple-hero>
+</simple-shell>
+```
+
+For an in-page hero **inside another shell**, fall back to the bare-section
+form (no double-shell nesting):
+
+```html
+<section>
+  <col-ui align="center" gap="5">
+    <col-ui align="center" gap="2">
+      <text-ui size="sm" color="accent" weight="semibold" style="letter-spacing:0.05em">ADIAUI v0.6</text-ui>
+      <h1>Build UIs with natural language</h1>
+      <text-ui size="lg" color="subtle" text-align="center">
+        Light-DOM web components + generative UI pipeline.<br>
+        Ship faster, iterate smarter.
+      </text-ui>
+    </col-ui>
+    <row-ui gap="3">
+      <button-ui text="Get started" variant="primary" size="lg"></button-ui>
+      <button-ui text="See demo" size="lg" icon="play-circle"></button-ui>
+    </row-ui>
+  </col-ui>
+</section>
+```
+
+---
+

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

@@ -0,0 +1,336 @@
+# §Flows — App-shell composition (admin, chat, editor, simple)
+
+> **Loading note.** Reference bundle extracted from `SKILL.md` per the
+> §LoadingProtocol inversion contract (v2.20.3+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/flows-shells.md')`
+> When composing the shell-tier of an application — admin-shell with sidebar+content, chat-shell with LLM streaming, editor-shell with canvas+panes, or simple-shell for marketing / error pages / single-card flows. Skip if your task doesn't involve these surfaces — the
+> seed has a stub naming each flow + the load invocation.
+
+### App shells
+
+**Admin shell — bespoke shape (recommended)**
+
+> ⚠️ **Shell CSS is REQUIRED and not auto-imported.** Before the HTML
+> below renders correctly, your entry file MUST contain the imports
+> below. Omitting the `.css` line produces an unstyled stacked-divs
+> layout with no error or warning. See §CSSPolicy + §Patterns → Admin
+> shell anatomy for the full reasoning.
+
+```js
+// In your entry file (src/main.js):
+import '@adia-ai/web-components/css';
+import '@adia-ai/web-components';
+import '@adia-ai/web-modules/shell';
+import '@adia-ai/web-modules/shell/admin-shell.css';  // REQUIRED — see §CSSPolicy
+```
+
+```html
+<admin-shell>
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header">
+      <span slot="heading">App Name</span>
+    </admin-topbar>
+    <nav-ui>
+      <a href="/dashboard">Dashboard</a>
+      <a href="/users">Users</a>
+      <a href="/settings">Settings</a>
+    </nav-ui>
+    <admin-statusbar slot="footer">
+      <avatar-ui icon="user" size="sm"></avatar-ui>
+      <span>Jane Doe</span>
+    </admin-statusbar>
+    <div data-resize></div>
+  </admin-sidebar>
+
+  <admin-content>
+    <admin-topbar slot="header">
+      <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm">
+      </button-ui>
+      <breadcrumb-ui></breadcrumb-ui>
+    </admin-topbar>
+    <admin-scroll>
+      <admin-page>
+        <admin-page-header>
+          <header-ui>
+            <span slot="heading">Page Title</span>
+            <button-ui slot="action" text="+ New" variant="primary"></button-ui>
+          </header-ui>
+        </admin-page-header>
+        <admin-page-body>
+          <!-- your router outlet here (vue-router, react-router, lit-router, etc.)
+               — see §Rendering Model → Routing ownership for the per-framework substitution -->
+        </admin-page-body>
+      </admin-page>
+    </admin-scroll>
+    <admin-statusbar slot="footer">Ready</admin-statusbar>
+  </admin-content>
+
+  <admin-command>
+    <command-ui placeholder="Search…"></command-ui>
+  </admin-command>
+</admin-shell>
+
+<script type="module">
+  document.querySelector('router-ui').routes = [
+    { path: '/dashboard', content: '/pages/dashboard.html', title: 'Dashboard' },
+    { path: '/users',     content: '/pages/users.html',     title: 'Users' },
+    { path: '/settings',  content: '/pages/settings.html',  title: 'Settings' },
+  ];
+</script>
+```
+
+#### Composition principles — what goes where in admin chrome (v0.6.13+)
+
+The ADR-0023 cluster establishes a strict separation of concerns between
+shell-tier chrome and page-tier content. Confusing the two is the most
+common cause of layout regressions during the v0.6.x cycle. The canonical
+allocation:
+
+| Slot | Container | What lives here |
+|---|---|---|
+| Shell sidebar | `<admin-sidebar slot="leading">` | Primary navigation (links/sections). The `<admin-topbar slot="header">` inside hosts the app brand. The footer chrome bar (`<admin-statusbar slot="footer">`) hosts **user-account controls only** — avatar, account menu, sign-in. App-wide preference toggles (scheme / theme) do NOT go here — see the Shell topbar row. |
+| Shell topbar | `<admin-topbar slot="header">` inside `<admin-content>` | Leading side: sidebar-toggle button + **breadcrumb** (location, not page title). Trailing `slot="action"` cluster: **persistent app-wide controls** — scheme / theme toggle, notifications, a global command trigger. NOT page actions, NOT page title, NOT global search (those are page-scoped — see the rows below). |
+| Page header | `<admin-page-header>` inside `<admin-page>` | **Page title** (`<h1>`) + page-scoped action cluster (`+ New`, `Export`, etc.) via `slot="action"`. The header band shares the body content surface (`--page-content-header-bg` → `--a-canvas-0` as of v0.6.19) so it reads as a flush extension of `<admin-page-body>`, not as separate chrome. History: v0.6.14 canvas-2 (elevated-step); v0.6.16 canvas-1 (shell-chrome-continuation); v0.6.19 canvas-0 (flush). Override `--page-content-header-bg` per-product for a raised/contrasting band. |
+| Page body | `<admin-page-body>` inside `<admin-page>` | The page's primary content. For dashboards, wrap stacked grid rows in `<col-ui gap="4">` to get correct vertical rhythm — DO NOT rely on docs-site CSS scoping; the chunk must be self-styling. |
+| Table toolbar | `<table-toolbar-ui>` adjacent to `<table-ui>` | In-page search ("Search users by email…"), filter, sort, columns dropdown. Search is scoped to the table, not global — keep it inside the page, not in the shell topbar. |
+| Statusbar | `<admin-statusbar slot="footer">` inside `<admin-content>` | App-wide status (sync state, row count, version). Optional. |
+
+**Anti-patterns that broke claims-ui-v3 during cold-start:**
+
+- ❌ Page title (`<h1>Dashboard</h1>`) placed in `<admin-topbar slot="header">` via `slot="heading"` — the topbar should carry a **breadcrumb showing location**, not the page's own title. The breadcrumb's terminal segment IS the page title (rendered by the breadcrumb's own typography).
+- ❌ `+ New Claim` button placed in the shell topbar — page-scoped actions belong in `<admin-page-header>` so they only render on the pages that need them; the shell topbar persists across all routes.
+- ❌ Global search input placed in the shell topbar — a search that's scoped to claims (not "the whole app") belongs in `<table-toolbar-ui>` inside the claims page. The shell topbar is for location + page navigation, not data filtering.
+- ❌ Dashboard tab panels using `<div data-tab-panel>` + relying on `[data-template="dashboard"]` CSS — the rule fires only on the routed dashboard template; non-routed embeds (e.g. `/site/examples/admin-dashboard` under the standalone page template) collapse to zero vertical gap. Use `<col-ui data-tab-panel="…" gap="4">` so the chunk is self-styling.
+- ❌ Scheme / theme toggle (`<toggle-scheme-ui>`) placed in the sidebar footer (`<admin-statusbar slot="footer">`) — a global app preference buried there reads as navigation and disappears when the sidebar collapses. Persistent app-wide controls belong in the shell topbar's trailing `slot="action"` cluster (top-right of the viewport).
+- ❌ `size="sm"` on a **page-header** action button — chrome icon buttons (`data-sidebar-toggle`, theme toggle) are `sm` because the topbar is compact, but page-header action buttons (`+ New`, `Export`) take the **default `md`** size. `size="sm"` there renders a visibly undersized ~14px primary CTA.
+- ❌ `<breadcrumb-ui slot="heading">` inside `<admin-topbar>` — `slot="heading"` applies `font-weight: 500; color: var(--a-fg)`, flattening the breadcrumb's own muted-ancestor / bold-terminal segment typography into one heavy label. Put `<breadcrumb-ui>` in the **default slot**; reserve `slot="heading"` for plain text labels.
+
+**Canonical page-header markup:**
+
+```html
+<admin-page>
+  <admin-page-header>
+    <header>
+      <div>
+        <h1>Page Title</h1>
+        <span slot="action">
+          <button-ui text="New" variant="primary" icon="plus"></button-ui>
+          <button-ui text="Export" icon="download"></button-ui>
+        </span>
+      </div>
+    </header>
+  </admin-page-header>
+  <admin-page-body>
+    <section>
+      <!-- Page content. For dashboards, wrap stacked grids in
+           <col-ui gap="4"> so each <grid-ui> row stacks with correct
+           vertical rhythm regardless of which template wraps the chunk. -->
+    </section>
+  </admin-page-body>
+</admin-page>
+```
+
+Either `<header>` (native HTML element) or `<header-ui>` (the AdiaUI primitive) work as the slot inside `<admin-page-header>` — CSS selectors target `:is(header, header-ui)`. Prefer native `<header>` for portable consumer chunks.
+
+> **Anti-pattern — don't repeat the icon glyph in `text=`.** `icon="plus"`
+> already renders a `+` glyph. Writing `text="+ New"` then produces a doubled
+> `+` (`[+ icon] [+ New]`). Use `text="New"` with `icon="plus"` — the icon
+> supplies the symbol. The same holds for `minus` / `x` / `check` / arrow
+> icons; `button-ui` emits a one-shot `console.warn` when it detects the
+> collision. A bare `text="+ New"` with **no** `icon` is fine — there the
+> `+` is the label itself.
+
+**Customizing the page-header band:**
+
+```css
+/* In your app's CSS, override the token at any cascade layer.
+   Default since v0.6.19 is canvas-0 (flush with body); pick any
+   higher canvas step for a raised band. */
+:root {
+  --page-content-header-bg: var(--a-canvas-1);  /* subtle elevated */
+  /* or */
+  --page-content-header-bg: var(--a-canvas-2);  /* original v0.6.14 elevated-step */
+  /* or */
+  --page-content-header-bg: var(--a-bg-elevated);  /* match cards */
+}
+```
+
+Available canvas tokens (in dark mode; ΔL increases per step):
+`--a-canvas-0` (0.15, body + **page-header default since v0.6.19**) → `--a-canvas-1` (0.19, shell-chrome) → `--a-canvas-2` (0.23) → `--a-canvas-3` (0.27) → `--a-canvas-4` (0.31).
+
+**Editor shell — canvas + dual sidebars**
+
+```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</span>
+    <button-ui slot="action" icon="gear" variant="ghost"></button-ui>
+    <button-ui slot="action" text="Share" variant="primary"></button-ui>
+  </editor-toolbar>
+
+  <editor-sidebar slot="leading" collapsible persist="structure">
+    <pane-ui side="leading" resizable min-width="200">
+      <header>Layers</header>
+      <section><!-- tree / outline --></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>
+        <tab-ui value="dom"     text="DOM"></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>
+  </editor-canvas>
+
+  <editor-sidebar slot="trailing" collapsible persist="inspector">
+    <pane-ui side="trailing" resizable min-width="200">
+      <header>Inspector</header>
+      <section><!-- properties --></section>
+    </pane-ui>
+  </editor-sidebar>
+
+  <editor-statusbar>
+    <span slot="status">Saved</span>
+    <span slot="zoom">100%</span>
+  </editor-statusbar>
+</editor-shell>
+```
+
+**Editor cluster wiring contract**
+
+- `<editor-toolbar>` slot vocabulary: `title` / `status` / `action` / `action-leading` (verified against `packages/web-modules/editor/editor-shell/css/editor-shell.bespoke.css`). Earlier kit revisions documented `icon` / `heading` / `description` (the `admin-topbar` vocabulary), but substrate CSS doesn't position those slot names on the editor cluster — they fall through to inline document-order positioning. Fixed v3.1.1.
+- `<editor-sidebar persist="…">` is the localStorage key suffix; the sidebar writes pane width under `adia-editor-sidebar-{persist}`. The deprecated `name=` alias is kept for v0.4.x back-compat; new code uses `persist=`. Omit `persist=` and width won't survive a reload.
+- `<editor-sidebar>` **WRAPS** `<pane-ui resizable>` — delegation pattern. The sidebar reflects `[collapsed]` + `[resizing]`, owns localStorage; the inner pane-ui owns the physical drag. Don't reimplement drag in the sidebar.
+- `<editor-canvas-toolbar>` is **canvas-scope** (view-mode tabs, breadcrumbs, canvas-scoped actions); `<editor-toolbar>` is **app-scope** (document-wide actions). Place `<editor-canvas-toolbar>` as the first child of `<editor-canvas>`; it's sticky to the canvas scroll surface so tabs stay visible while the canvas body scrolls. Replaces the legacy `<div data-view-strip>` pattern.
+- Host `[focus-mode]` automatically propagates to `<editor-toolbar>[full-screen]` and `<editor-canvas>[focused]` — don't toggle child attributes by hand.
+
+**Nested shells — admin wrapping editor**
+
+For editor-inside-admin pages (inline page builder, embedded canvas), place the editor shell inside `<admin-page-body>` with `flex: 1` and the `min-height: 0` chain:
+
+```html
+<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">Page Builder</span></editor-toolbar>
+    <editor-canvas><!-- canvas content --></editor-canvas>
+  </editor-shell>
+</admin-page-body>
+```
+
+> **Pitfall — nested shell height collapse.** Shells use `height: 100%`
+> internally. Every ancestor must form a flex column with `min-height: 0`.
+> Without this the inner shell silently collapses to zero height.
+
+---
+
+**Chat shell — LLM streaming with provider + thinking**
+
+```html
+<chat-shell
+    proxy-url="/api/chat"
+    provider="anthropic"
+    model="claude-sonnet-4-7"
+    system="You are a helpful assistant."
+    thinking>
+  <chat-header>
+    <span slot="name">Assistant</span>
+    <chat-status slot="status" data-state="connected">Connected</chat-status>
+  </chat-header>
+
+  <chat-thread>
+    <chat-empty>
+      <empty-state-ui icon="chat-circle"
+        heading="How can I help?" description="Ask 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>
+```
+
+**Chat cluster wiring contract**
+
+- `[proxy-url]` is the server-side endpoint that forwards to the model provider (keeps API keys server-side). For direct-provider mode set `[provider]` + provider-specific creds at the deployment layer.
+- `[submit-on-enter]` on `<chat-input-ui>` is **required** for the composer-submit chain. Without it the form-submit path never fires and the host doesn't dispatch the LLM call.
+- `<chat-composer>` forwards the inner `<chat-input-ui>` submit as `composer-submit` (de-duped); the host listens for `composer-submit` and fires the LLM call. Don't add your own submit handler on `<chat-input-ui>`.
+- Host `[streaming]` propagates automatically to `<chat-thread>[streaming]` and `<chat-composer>[disabled]`. **Don't toggle these by hand.**
+- 8 host events: `submit` (user message), `chunk` (each streaming token), `thinking` (extended-thinking content), `done` (response complete, has `{text, usage, stopReason}` detail), `error`, `abort`, `clear`, `message`.
+
+**Conversation rail (optional sidebar pattern)**
+
+```html
+<chat-shell proxy-url="/api/chat">
+  <chat-sidebar slot="leading" resizable collapsible name="conversations">
+    <pane-ui side="leading" resizable>
+      <header>Conversations</header>
+      <nav-ui variant="section">
+        <nav-item-ui text="Today's brainstorm" selected></nav-item-ui>
+        <nav-item-ui text="Spec review"></nav-item-ui>
+      </nav-ui>
+    </pane-ui>
+  </chat-sidebar>
+
+  <chat-thread>…</chat-thread>
+  <chat-composer><chat-input-ui submit-on-enter></chat-input-ui></chat-composer>
+</chat-shell>
+```
+
+`<chat-sidebar persist="…">` writes pane width under `adia-chat-sidebar-{persist}`. **Do not** put `<chat-sidebar slot="leading">` AND `<chat-sidebar slot="trailing">` simultaneously unless your conversation model genuinely needs two rails — most chat surfaces use one leading rail at most.
+
+---
+
+**Simple shell — marketing / error pages / single-card flows**
+
+```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>
+```
+
+**Simple cluster wiring contract**
+
+- 3 cluster members: `<simple-shell>` (host), `<simple-hero>` (heading + lede + actions slot), `<simple-content>` (free-form body region, max-width constrained).
+- `<simple-shell>` has two reflected boolean knobs:
+  - `[centered]` — vertically centers content in the viewport (use for 404 / 500 / maintenance / thank-you / sign-in card flows).
+  - `[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>` slots: `heading` (the `<h1>`), `lede` (a `<p>` description), `actions` (a `<div>` containing one or more buttons), default (any free-form content after the action row).
+- `<simple-content>` has one default slot — drop arbitrary content; the wrapper constrains width unless `[full-bleed]` is set on the host.
+
+**Use cases per substrate canonicals:** marketing splashes, error pages (404 / 500 / maintenance), thank-you / confirmation pages, single-card flows (sign-in, password reset). **Don't reach for simple-shell when:** the surface has a sidebar / topbar / multi-column layout — that's `admin-shell`. The simple shell exists exactly to avoid hand-rolling `<main style="display: grid; place-items: center">` for these 5 canonical cases.
+
+```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>
+```
+