npm - @adia-ai/adia-ui-factory - Versions diffs - 0.2.2 → 0.2.3 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

package/.claude-plugin/plugin.json +12 -3
package/CHANGELOG.md +8 -0
package/README.md +24 -1
package/bin/adia-scaffold +93 -13
package/package.json +2 -2
package/references/shell-embed.md +10 -0
package/references/spa-architecture.md +7 -0
package/skills/adia-ui-kit/CHANGELOG.md +41 -0
package/skills/adia-ui-kit/SKILL.md +442 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/Guidelines.md +87 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/components.md +142 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/styles.md +118 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/tokens.md +120 -0
package/skills/adia-ui-kit/assets/team-scaffold/archive-README.md +30 -0
package/skills/adia-ui-kit/assets/team-scaffold/drafts-README.md +57 -0
package/skills/adia-ui-kit/assets/team-scaffold/inbox-README.md +76 -0
package/skills/adia-ui-kit/assets/team-scaffold/outbox-README.md +46 -0
package/skills/adia-ui-kit/assets/team-scaffold/team-root.README.md +51 -0
package/skills/adia-ui-kit/assets/team-scaffold/tickets-README.md +208 -0
package/skills/adia-ui-kit/assets/team-scaffold/tickets-REGISTRY.md +81 -0
package/skills/adia-ui-kit/assets/templates/AGENTS.template.md +128 -0
package/skills/adia-ui-kit/assets/templates/CLAUDE.template.md +1 -0
package/skills/adia-ui-kit/assets/templates/FEEDBACK-OMISSIONS-DEFENSE.template.md +150 -0
package/skills/adia-ui-kit/assets/templates/FEEDBACK.template.md +213 -0
package/skills/adia-ui-kit/assets/templates/RESPONSE.template.md +114 -0
package/skills/adia-ui-kit/assets/templates/figma-make-guidelines.md +90 -0
package/skills/adia-ui-kit/evals/adversarial-content-trust.json +83 -0
package/skills/adia-ui-kit/evals/evals.json +55 -0
package/skills/adia-ui-kit/evals/routing-corpus.json +121 -0
package/skills/adia-ui-kit/evals/teach-routing-cases.json +92 -0
package/skills/adia-ui-kit/references/capabilities.md +245 -0
package/skills/adia-ui-kit/references/catalog-lookup.md +186 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v1.md +8 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v2.md +3585 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v3.md +1899 -0
package/skills/adia-ui-kit/references/common-gotchas-consumer.md +522 -0
package/skills/adia-ui-kit/references/component-literacy.md +291 -0
package/skills/adia-ui-kit/references/composition.md +245 -0
package/skills/adia-ui-kit/references/correction-loop.md +462 -0
package/skills/adia-ui-kit/references/css-policy.md +343 -0
package/skills/adia-ui-kit/references/decision-model.md +158 -0
package/skills/adia-ui-kit/references/diagnostic-output.md +57 -0
package/skills/adia-ui-kit/references/docs-catalog.md +239 -0
package/skills/adia-ui-kit/references/exclusions.md +225 -0
package/skills/adia-ui-kit/references/feedback-authoring.md +466 -0
package/skills/adia-ui-kit/references/figma-make.md +244 -0
package/skills/adia-ui-kit/references/flows-auth.md +307 -0
package/skills/adia-ui-kit/references/flows-content.md +206 -0
package/skills/adia-ui-kit/references/flows-data.md +348 -0
package/skills/adia-ui-kit/references/flows-interaction.md +181 -0
package/skills/adia-ui-kit/references/flows-shells.md +336 -0
package/skills/adia-ui-kit/references/gap-detection.md +266 -0
package/skills/adia-ui-kit/references/harness.md +284 -0
package/skills/adia-ui-kit/references/loading-protocol.md +406 -0
package/skills/adia-ui-kit/references/local-link.md +198 -0
package/skills/adia-ui-kit/references/mcp.md +401 -0
package/skills/adia-ui-kit/references/migration.md +116 -0
package/skills/adia-ui-kit/references/mission.md +194 -0
package/skills/adia-ui-kit/references/mode-routing.md +298 -0
package/skills/adia-ui-kit/references/patterns-agent.md +223 -0
package/skills/adia-ui-kit/references/patterns-data.md +1066 -0
package/skills/adia-ui-kit/references/patterns-forms.md +223 -0
package/skills/adia-ui-kit/references/patterns-layout.md +326 -0
package/skills/adia-ui-kit/references/patterns-recipes.md +1416 -0
package/skills/adia-ui-kit/references/patterns-shells.md +1097 -0
package/skills/adia-ui-kit/references/patterns-traits.md +259 -0
package/skills/adia-ui-kit/references/patterns-wiring.md +339 -0
package/skills/adia-ui-kit/references/pev-rationale.md +137 -0
package/skills/adia-ui-kit/references/reasoning-gate.md +146 -0
package/skills/adia-ui-kit/references/reasoning-methodologies.md +112 -0
package/skills/adia-ui-kit/references/recon.md +192 -0
package/skills/adia-ui-kit/references/rendering-model.md +431 -0
package/skills/adia-ui-kit/references/response-authoring.md +398 -0
package/skills/adia-ui-kit/references/session-log-schema.md +203 -0
package/skills/adia-ui-kit/references/session-log-template.md +118 -0
package/skills/adia-ui-kit/references/setup.md +652 -0
package/skills/adia-ui-kit/references/skill-hygiene.md +135 -0
package/skills/adia-ui-kit/references/spec-to-ui-reasoning.md +394 -0
package/skills/adia-ui-kit/references/state.md +229 -0
package/skills/adia-ui-kit/references/teach-protocol.md +421 -0
package/skills/adia-ui-kit/references/theme.md +142 -0
package/skills/adia-ui-kit/references/version-check.md +69 -0
package/skills/adia-ui-kit/scripts/audit-decision-trace.mjs +198 -0
package/skills/adia-ui-kit/scripts/audit-kit-roster.mjs +366 -0
package/skills/adia-ui-kit/scripts/changelog-archive.mjs +126 -0
package/skills/adia-ui-kit/scripts/check-adia-versions.py +404 -0
package/skills/adia-ui-kit/scripts/run-skill-evals.mjs +358 -0
package/skills/adia-ui-kit/scripts/validate-session-log.mjs +242 -0
package/skills/adia-ui-kit/skill.json +102 -0
package/skills/adia-ui-migration/CHANGELOG.md +47 -0
package/skills/adia-ui-migration/SKILL.md +381 -0
package/skills/adia-ui-migration/skill.json +29 -0
package/skills/adia-ui-spa/SKILL.md +1 -1
package/skills/adia-ui-verify/SKILL.md +2 -2

package/skills/adia-ui-kit/references/figma-make.md ADDED Viewed

@@ -0,0 +1,244 @@
+---
+name: figma-make
+load-when: The user wants to use AdiaUI inside Figma Make (or any prompt-to-app / web-container codegen tool) and needs the CDN load options — every CSS + JS bundle URL, the recommended one-import default, and the React/JSX usage caveats
+---
+# §FigmaMake — Using AdiaUI in Figma Make via CDN
+> **Loading note.** Reference bundle per the §LoadingProtocol inversion
+> contract. Load via
+> `skill_view(name='adia-ui-kit', file_path='references/figma-make.md')`
+> when the user is building in Figma Make (or a similar prompt-to-app /
+> sandboxed web-container tool — Bolt, Lovable, v0, StackBlitz) and asks
+> how to pull AdiaUI in over a CDN. For a raw Vite + npm project use
+> `references/setup.md` instead; for the framework-agnostic CDN policy
+> rationale use `references/css-policy.md` §CDN.
+## Why this works at all
+AdiaUI primitives are **framework-agnostic Light-DOM custom elements**.
+They register themselves with `customElements.define` and style
+themselves with CSS `@scope` — there is no React/Vue/Svelte binding to
+install, no build step required, no JSX wrapper. Anything that can put
+a `<link>` and a `<script type="module">` in the document — which Figma
+Make's generated app can — can render `<button-ui>`, `<card-ui>`,
+`<admin-shell>`, etc.
+That means you do **not** `npm install` anything in Make. You load two
+or three CDN URLs and start writing tags.
+## The 90-second default (recommended for Make)
+One CSS link + one JS module = every primitive **and** every shell, with
+the icon manifest baked in. Paste into the document `<head>` (see
+"Where to paste in Figma Make" below):
+```html
+<!-- AdiaUI — kitchen-sink: all 100+ primitives + 4 shells + a2ui-runtime -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.css">
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/everything.min.js"></script>
+```
+`everything.min.js` registers all primitives + all 4 shells + the
+a2ui-runtime + the icon manifest in one file — nothing else to load for
+the JS side. Add only the **shell CSS for the shell tier you actually
+render** (the kitchen-sink JS covers every shell, but each shell's CSS
+is a separate file — see the table). If you're not using a shell at all,
+drop the second `<link>` and keep just `web-components.min.css`.
+## All CDN options
+Base URL: `https://cdn.jsdelivr.net/npm/` (unpkg works too — swap the
+host). Use the `@0.6` **minor range** — jsdelivr auto-resolves the
+latest `0.6.x` patch, tracks fixes, and won't jump to a breaking `0.7`.
+### CSS bundles
+| What | URL (after the base) | Size | Load when |
+|---|---|---|---|
+| **All primitives + tokens + themes** | `@adia-ai/web-components@0.7/dist/web-components.min.css` | ~590 KB | **Always** — this is the base stylesheet |
+| Admin shell | `@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.css` | ~18 KB | Rendering `<admin-shell>` |
+| Chat shell | `@adia-ai/web-modules@0.7/dist/chat/chat-shell.min.css` | ~10 KB | Rendering `<chat-shell>` |
+| Editor shell | `@adia-ai/web-modules@0.7/dist/editor/editor-shell.min.css` | ~6 KB | Rendering `<editor-shell>` |
+| Simple shell | `@adia-ai/web-modules@0.7/dist/simple/simple-shell.min.css` | ~0.4 KB | Rendering `<simple-shell>` |
+Add **one** base stylesheet always; add a shell stylesheet only for the
+shell you render. Each shell's CSS bundles every sub-component style it
+needs (`admin-shell.min.css` covers `admin-sidebar` / `admin-topbar` /
+`admin-page` / … — you don't load those separately).
+### JS bundles — pick exactly ONE registration path
+| What | URL (after the base) | Size | Load when |
+|---|---|---|---|
+| **Everything (kitchen-sink)** | `@adia-ai/web-modules@0.7/dist/everything.min.js` | ~1.3 MB | **Default for Make** — all primitives + 4 shells + a2ui-runtime + icons baked in |
+| Primitives only | `@adia-ai/web-components@0.7/dist/web-components.min.js` | ~1.2 MB | No shells at all — **must co-load** `icons-manifest.js` (next row) |
+| Icon manifest (standalone) | `@adia-ai/web-components@0.7/dist/icons-manifest.js` | ~250 KB | Only with the primitives-only path above (it's already inside `everything.min.js`) |
+| Admin shell only | `@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.js` | ~15 KB | `web-components.min.js` + this one shell (advanced) |
+| Chat shell only | `@adia-ai/web-modules@0.7/dist/chat/chat-shell.min.js` | ~230 KB | `web-components.min.js` + chat only |
+| Editor shell only | `@adia-ai/web-modules@0.7/dist/editor/editor-shell.min.js` | ~6 KB | `web-components.min.js` + editor only |
+| Simple shell only | `@adia-ai/web-modules@0.7/dist/simple/simple-shell.min.js` | ~6 KB | `web-components.min.js` + simple only |
+> **Pick ONE JS path.** Loading `everything.min.js` *and* a separate
+> `web-components.min.js` makes `customElements.define` throw
+> "name already defined" on the dup-registered tag — the page half-boots
+> then errors. For Make, just use `everything.min.js`.
+> **Icons need the manifest.** Icons (`<button-ui icon="gear">`,
+> `<icon-ui name="house">`) lazy-load from `@phosphor-icons/core` gated
+> by `icons-manifest.js`. It's **baked into `everything.min.js`**, so the
+> default path needs nothing extra. Only the primitives-only
+> `web-components.min.js` path must co-load the standalone manifest URL,
+> or every icon renders blank.
+## The Guidelines field (primary path — steer the generator)
+Figma Make has a **Provide guidelines** field ("Give instructions to
+Make so it knows how to use your context"). This is the canonical place
+to make Make build with AdiaUI: paste a guidelines block that (a) tells
+Make to load the CDN bundles, (b) tells it to prefer AdiaUI tags over
+hand-built UI, and (c) gives the component vocabulary + usage rules.
+A ready-to-paste guidelines artifact lives at
+`assets/templates/figma-make-guidelines.md` — hand it to the user
+verbatim (or tailor it: trim the vocabulary to the surfaces they're
+building, pin the version). It encodes the setup block, the `<name>-ui`
+naming rule, the grouped tag vocabulary, the 9 usage rules (the
+common-mistake list — `text=` labels, `<section>` card bodies,
+presence-based booleans, `class` not `className`, `nav-ui` not
+`menu-ui`, `stack-ui` is z-axis, theme-via-tokens-not-Tailwind), and a
+worked `<admin-shell>` example. Keep it current with the substrate — the
+usage rules mirror the kit's `common-gotchas-consumer.md` + the memory
+pitfalls; re-derive if a primitive's contract changes.
+### Two artifacts — pick by how the user runs Make
+- **Single paste-in block** → `assets/templates/figma-make-guidelines.md`.
+  For the quick path: the user pastes one block into the **Provide
+  guidelines** field. Everything in one file.
+- **Structured kit folder** → `assets/figma-make/guidelines/` (four
+  files: `Guidelines.md` read-first, `components.md`, `styles.md`,
+  `tokens.md`). This matches Figma's documented Make-kit
+  `guidelines/` layout ("multiple short files beat one large file";
+  Make discovers the folder automatically). Hand the user the whole
+  folder when they maintain a Make kit, or when they asked for the
+  `Guidelines.md` / `components.md` / `styles.md` / `tokens.md` split
+  by name. `Guidelines.md` carries the CDN-rollup setup block + the
+  read-first critical rules; the other three are the deep references.
+Both encode the **same facts** (CDN rollup CSS lead, `<name>-ui` naming,
+the usage-rule list, `theme` palette + `data-scheme` mode as two
+SEPARATE attributes, `--a-*` tokens incl. `--a-primary` + `--a-chrome-light`
+for primary fills). Keep them in sync if you edit one.
+## Where the loads actually land
+Guidelines steer Make to *emit* the setup; this is where it ends up.
+Figma Make generates a real web app you can edit, so the load lines go
+wherever the document `<head>` is assembled. Two routes, in order of
+preference:
+1. **Document head (best).** If Make exposes an `index.html` or a
+   "custom `<head>` / external resources" affordance, paste the three
+   lines from "The 90-second default" there verbatim. This is the
+   most robust — the elements upgrade before your app's first render.
+2. **App entry (React fallback).** If Make only gives you a React entry
+   (`App.tsx` / `main.tsx`) and no head access, inject at module load.
+   Put this at the **top** of the entry file, outside the component:
+   ```jsx
+   // AdiaUI CDN bootstrap — runs once, before first render.
+   const ADIA = "https://cdn.jsdelivr.net/npm/@adia-ai";
+   for (const href of [
+     `${ADIA}/web-components@0.6/dist/web-components.min.css`,
+     `${ADIA}/web-modules@0.6/dist/shell/admin-shell.min.css`,
+   ]) {
+     if (!document.querySelector(`link[href="${href}"]`)) {
+       const l = document.createElement("link");
+       l.rel = "stylesheet";
+       l.href = href;
+       document.head.appendChild(l);
+     }
+   }
+   import(/* @vite-ignore */ `${ADIA}/web-modules@0.6/dist/everything.min.js`);
+   ```
+   `import()` (dynamic) is used so the bundler doesn't try to resolve the
+   URL at build time. The CSS goes in via `<link>` because bundlers can't
+   `import` a remote `.css`.
+## Using the tags in JSX (React)
+Custom elements are just lowercase-hyphenated tags — write them directly
+in JSX. AdiaUI is **attribute-driven**, which is exactly what React emits
+for unknown props, so the common cases just work:
+```jsx
+<card-ui>
+  <header><h3>Plan</h3></header>
+  <section>
+    <text-ui>Pro — $29/mo</text-ui>
+    <button-ui variant="primary" text="Upgrade"></button-ui>
+  </section>
+</card-ui>
+```
+Caveats for the React context specifically:
+- **Use `class`, not `className`, inside AdiaUI subtrees** when you hand-
+  write attributes — these are real DOM elements, not React host
+  components. (React still accepts `className` on its own `<div>`s.)
+- **Booleans are presence-based.** `<switch-ui checked>` not
+  `checked={true}` — render the attribute only when true:
+  `{isOn && <switch-ui checked></switch-ui>}` or
+  `<switch-ui {...(isOn ? {checked: ""} : {})}></switch-ui>`.
+- **Content via `text=` where the yaml says so.** `<button-ui>` renders
+  its label from `text="…"` (a CSS `::after`), not from JSX children —
+  same for `badge-ui`. `card-ui` / `kbd-ui` use the default slot
+  (children). When in doubt, the per-component contract is in the kit
+  catalog (`§1 Catalog Lookup`).
+- **Events** are native `CustomEvent`s. In React 19 `onClick`-style
+  props bind to custom-element events; on older React add a `ref` +
+  `el.addEventListener('change', …)`. Most AdiaUI form elements also
+  emit standard `input`/`change` so the native path is usually enough.
+## Version-pin policy
+- **`@0.6`** (default) — latest `0.6.x` patch, auto-tracked. Best for
+  Make demos and prototypes.
+- **`@0.6.45`** (exact) — pin for a reproducible artifact you'll hand
+  off. Bump it deliberately.
+- **Avoid `@latest`** — it crosses MINOR/MAJOR boundaries and can pull a
+  breaking change into a working prototype without warning.
+All 9 `@adia-ai/*` packages move in lockstep, so the version you choose
+must match across **both** `web-components` and `web-modules` URLs.
+## Quick verification
+After the loads are in, drop one of each tier and reload:
+```html
+<button-ui variant="primary" text="It works"></button-ui>
+<card-ui><section><text-ui>Styled + registered.</text-ui></section></card-ui>
+```
+- Button shows a filled primary style + label → **CSS + JS both live.**
+- Unstyled / no label → CSS link missing or wrong order.
+- Tag stays an empty inline element → JS bundle didn't load (check the
+  Network tab for the `everything.min.js` request).
+- Icons blank → you're on the primitives-only path without the
+  `icons-manifest.js` co-load (switch to `everything.min.js`).
+## Cross-references
+- `references/setup.md` §Step 0.5 — the same CDN facts for the raw-Vite
+  cold-start path (plus the npm-install route Make doesn't need).
+- `references/css-policy.md` — why the CSS is a separate explicit load
+  (the Light-DOM cascade-control reason it isn't bundled into the JS).
+- Live CDN guide: [ui-kit.exe.xyz/site/getting-started/cdn-usage](https://ui-kit.exe.xyz/site/getting-started/cdn-usage).
+- The package READMEs (`@adia-ai/web-components`, `@adia-ai/web-modules`
+  on npm) carry the canonical CDN block — kept on the `@0.6` range by the
+  `check:cdn-pins` release gate.

package/skills/adia-ui-kit/references/flows-auth.md ADDED Viewed

@@ -0,0 +1,307 @@
+# §Flows — Auth, registration, onboarding wizards
+> **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-auth.md')`
+> When implementing sign-in / sign-up / forgot-password / multi-step registration / first-run onboarding flows. Skip if your task doesn't involve these surfaces — the
+> seed has a stub naming each flow + the load invocation.
+### Auth flows
+All auth surfaces center a `<card-ui style="max-width: 32rem">`.
+No app shell needed for standalone auth pages.
+**Sign-in: email entry (step 1 of 2)**
+```html
+<main style="min-height: 100vh; display: grid; place-items: center;">
+  <card-ui style="max-width: 32rem; width: 100%">
+    <header>
+      <col-ui align="center" gap="1">
+        <img src="/logo.svg" alt="Logo" style="height: 4rem" />
+        <h1>Sign in</h1>
+        <text-ui color="subtle">Continue with email or a connected account.</text-ui>
+      </col-ui>
+    </header>
+    <section>
+      <col-ui gap="4">
+        <form size="lg" action="/auth/password" method="get">
+          <col-ui gap="4">
+            <input-ui label="Email" type="email" name="email"
+              autocomplete="email" placeholder="you@example.com" required></input-ui>
+            <button-ui text="Continue with Email" variant="primary" type="submit"></button-ui>
+          </col-ui>
+        </form>
+        <divider-ui label="or"></divider-ui>
+        <col-ui gap="2">
+          <button-ui text="Continue with Google" icon="google-logo" variant="outline"></button-ui>
+          <button-ui text="Continue with GitHub" icon="github-logo" variant="outline"></button-ui>
+          <button-ui text="Continue with SSO"    icon="buildings"   variant="outline"></button-ui>
+        </col-ui>
+        <text-ui text-align="center" color="subtle" size="sm">
+          No account? <a href="/auth/sign-up">Sign up</a>
+        </text-ui>
+      </col-ui>
+    </section>
+  </card-ui>
+</main>
+```
+**Sign-in: password (step 2 of 2)**
+```html
+<card-ui style="max-width: 32rem; width: 100%">
+  <header>
+    <col-ui align="center" gap="1">
+      <h1>Enter your password</h1>
+      <text-ui color="subtle">Signing in as <strong>you@example.com</strong></text-ui>
+    </col-ui>
+  </header>
+  <section>
+    <col-ui gap="6">
+      <form size="lg">
+        <col-ui gap="4">
+          <input-ui label="Password" type="password" name="password"
+            autocomplete="current-password" placeholder="••••••••" required></input-ui>
+          <row-ui justify="space-between" align="center">
+            <check-ui name="remember" label="Remember me"></check-ui>
+            <a href="/auth/forgot-password">Forgot password?</a>
+          </row-ui>
+          <button-ui text="Sign in" variant="primary" type="submit"></button-ui>
+        </col-ui>
+      </form>
+      <divider-ui label="or use a one-time code"></divider-ui>
+      <col-ui gap="2">
+        <button-ui text="Email me a magic link"  icon="envelope-simple"   variant="outline"></button-ui>
+        <button-ui text="Send me a 6-digit code" icon="number-square-six" variant="outline"></button-ui>
+      </col-ui>
+      <text-ui text-align="center" color="subtle">
+        <a href="/auth/sign-in">← Use a different email</a>
+      </text-ui>
+    </col-ui>
+  </section>
+</card-ui>
+```
+**Email OTP / magic-link verify**
+```html
+<card-ui style="max-width: 32rem; width: 100%">
+  <header>
+    <col-ui align="center" gap="1">
+      <h1>Verify your email</h1>
+      <text-ui color="subtle">We sent a 6-digit code to <strong>you@example.com</strong>.</text-ui>
+    </col-ui>
+  </header>
+  <section>
+    <col-ui gap="6">
+      <col-ui align="center">
+        <otp-input-ui length="6" autocomplete="one-time-code"></otp-input-ui>
+      </col-ui>
+      <alert-ui variant="warning" icon="warning">
+        <span slot="content">Already have an account?
+          <a href="/auth/sign-in">Try signing in instead</a>.</span>
+      </alert-ui>
+      <text-ui text-align="center" color="subtle">
+        Didn't get a code? <a href="#">Resend</a>
+      </text-ui>
+    </col-ui>
+  </section>
+</card-ui>
+```
+**Forgot password + reset**
+```html
+<!-- Step 1: request link -->
+<card-ui style="max-width: 32rem; width: 100%">
+  <header><col-ui align="center" gap="1">
+    <h1>Forgot your password?</h1>
+    <text-ui color="subtle">We'll send a reset link to your email.</text-ui>
+  </col-ui></header>
+  <section>
+    <form size="lg" action="/auth/forgot/sent" method="get">
+      <col-ui gap="4">
+        <input-ui label="Email" type="email" name="email"
+          autocomplete="email" placeholder="you@example.com" required></input-ui>
+        <button-ui text="Send reset link" variant="primary" type="submit"></button-ui>
+      </col-ui>
+    </form>
+  </section>
+</card-ui>
+<!-- Step 2: set new password (from email link) -->
+<card-ui style="max-width: 32rem; width: 100%">
+  <header><col-ui align="center" gap="1"><h1>Set a new password</h1></col-ui></header>
+  <section>
+    <form size="lg">
+      <col-ui gap="4">
+        <field-ui label="New password" hint="At least 12 characters">
+          <input-ui type="password" name="password" autocomplete="new-password" minlength="12" required></input-ui>
+        </field-ui>
+        <input-ui label="Confirm password" type="password" name="confirm"
+          autocomplete="new-password" required></input-ui>
+        <button-ui text="Set password" variant="primary" type="submit"></button-ui>
+      </col-ui>
+    </form>
+  </section>
+</card-ui>
+```
+---
+### Registration flow (multi-step wizard)
+Two-column: story pane (left) + form (right). `<step-progress-ui>` in the footer.
+**Shell — wraps every step:**
+```html
+<main data-reg>
+  <aside data-reg-story>
+    <a href="/"><img src="/logo.svg" alt="" /><strong>Your App</strong></a>
+    <div data-reg-story-content>
+      <h2>Step headline.</h2>
+      <p>Why this step matters to the user.</p>
+      <text-ui color="subtle" size="sm">Step 1 of 4 · Workspace setup</text-ui>
+    </div>
+  </aside>
+  <form data-reg-input action="/registration/next" method="get">
+    <header data-reg-heading>
+      <h1>Step title</h1>
+      <text-ui color="subtle">Optional sub-copy.</text-ui>
+    </header>
+    <section data-reg-form>
+      <!-- step-specific fields -->
+    </section>
+    <footer>
+      <step-progress-ui value="1" total="4" caption="Step 1 of 4"></step-progress-ui>
+      <div data-reg-actions>
+        <a href="/registration/prev">← Back</a>
+        <button-ui text="Continue" variant="primary" type="submit"></button-ui>
+      </div>
+    </footer>
+  </form>
+</main>
+```
+**Step: name entity (workspace / org / project)**
+```html
+<section data-reg-form>
+  <field-ui inline label="Workspace name" hint="Letters, numbers, and spaces.">
+    <input-ui name="workspace" autocomplete="organization"
+      placeholder="Acme Inc." required></input-ui>
+  </field-ui>
+</section>
+```
+**Step: personal profile**
+```html
+<section data-reg-form>
+  <field-ui inline label="Full name">
+    <input-ui name="name" autocomplete="name" placeholder="Jane Doe" required></input-ui>
+  </field-ui>
+  <field-ui inline label="Title">
+    <input-ui name="title" placeholder="e.g. Senior Designer"
+      autocomplete="organization-title"></input-ui>
+  </field-ui>
+  <field-ui inline label="Department">
+    <select-ui name="department">
+      <option value="">Pick one…</option>
+      <option value="engineering">Engineering</option>
+      <option value="product">Product</option>
+      <option value="design">Design</option>
+    </select-ui>
+  </field-ui>
+</section>
+```
+**Step: invite team**
+```html
+<section data-reg-form>
+  <field-ui label="Email addresses">
+    <textarea-ui name="invites" rows="3"
+      placeholder="alex@acme.com, sarah@acme.com (comma or newline)"></textarea-ui>
+  </field-ui>
+  <field-ui inline label="Default role">
+    <select-ui name="role" value="member">
+      <option value="admin">Admin</option>
+      <option value="member">Member</option>
+      <option value="viewer">Viewer · read-only</option>
+    </select-ui>
+  </field-ui>
+  <field-ui inline label="Send welcome email">
+    <switch-ui name="welcome-email" checked></switch-ui>
+  </field-ui>
+</section>
+```
+---
+### Onboarding flow (post-registration wizard)
+Same two-column shell as registration (`data-onb`).
+Uses `<option-card-ui>` for persona selection.
+**Shell — wraps every step:**
+```html
+<main data-onb>
+  <aside data-onb-story>
+    <a href="/"><img src="/logo.svg" alt="" /><strong>Your App</strong></a>
+    <div data-onb-story-content>
+      <h2>Step headline.</h2>
+      <p>Why this step matters.</p>
+      <text-ui color="subtle" size="sm">Step 2 of 5 · Setup</text-ui>
+    </div>
+  </aside>
+  <form data-onb-input action="/onboarding/next" method="get">
+    <header data-onb-heading>
+      <h1>Step question</h1>
+      <text-ui color="subtle">Pick the closest match.</text-ui>
+    </header>
+    <div data-onb-form>
+      <!-- step content -->
+    </div>
+    <footer>
+      <step-progress-ui value="2" total="5" caption="Step 2 of 5"></step-progress-ui>
+      <div data-onb-actions>
+        <a href="/onboarding/prev">← Back</a>
+        <button-ui text="Continue" variant="primary" type="submit"></button-ui>
+      </div>
+    </footer>
+  </form>
+</main>
+```
+**Step: persona / role picker**
+```html
+<div data-onb-form>
+  <div role="radiogroup" aria-label="Primary role"
+    style="display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--a-space-3)">
+    <option-card-ui name="role" value="developer" required
+      heading="Developer" description="Wire APIs, ship features, monitor releases.">
+    </option-card-ui>
+    <option-card-ui name="role" value="designer"
+      heading="Designer" description="Compose patterns, review, hand off.">
+    </option-card-ui>
+    <option-card-ui name="role" value="analyst"
+      heading="Analyst" description="Query, chart, share insight, set alerts.">
+    </option-card-ui>
+    <option-card-ui name="role" value="admin"
+      heading="Admin" description="Configure, govern, manage access and billing.">
+    </option-card-ui>
+  </div>
+</div>
+```
+---