@adia-ai/adia-ui-forge 0.1.2 → 0.8.0

package/skills/{adia-ui-authoring → adia-author}/references/anti-patterns.md

@@ -196,7 +196,7 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 /* WRONG — button.css */
 @scope (button-ui) {
   :where(:scope) {
-    --btn-bg: var(--a-accent-bg);  /* ← stem mismatch */
+    --btn-bg: var(--a-primary-bg);  /* ← stem mismatch */
   }
 }
 ```
@@ -206,7 +206,7 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 ```css
 @scope (button-ui) {
   :where(:scope) {
-    --button-bg: var(--a-accent-bg);
+    --button-bg: var(--a-primary-bg);
   }
 }
 ```
@@ -229,7 +229,7 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 
 **What went wrong:** `variant="button"` changes the layout (square buttons with specific dimensions) — that's a mode, not a variant.
 
-**Fix:** add `pagination-ui[variant="button"]` to the Sanctioned Mode Attributes table in `docs/specs/component-token-contract.md`. Document the layout change as intentional.
+**Fix:** add `pagination-ui[variant="button"]` to the Sanctioned Mode Attributes table in `.claude/docs/specs/component-token-contract.md`. Document the layout change as intentional.
 
 Alternative: refactor to make the attribute cosmetic — if possible.
 
@@ -239,7 +239,7 @@ Alternative: refactor to make the attribute cosmetic — if possible.
 /* WRONG — missing the :where(:scope) token block */
 @scope (button-ui) {
   :scope {
-    --button-bg: var(--a-accent-bg);
+    --button-bg: var(--a-primary-bg);
     background: var(--button-bg);
     display: inline-flex;
   }
@@ -597,6 +597,35 @@ disconnected() {
 
 ---
 
+## Rapid-fire anti-patterns (mined from incident history)
+
+One line each; every entry is a shipped bug or a CRITICAL gate. Same axes as above, too small for a full entry.
+
+### API / silent-failure class
+
+- **Components silently accept ANY made-up attribute and no-op** (`text-ui muted`, `card-ui hover-elevate`, `description-list-ui variant="columns"`) — check the component's yaml for the real prop list before authoring any attribute.
+- **`empty-state-ui` takes `[heading]`, not `[title]`** — `title=` becomes the invisible native tooltip and the message never renders (the AP-04 collision in the wild).
+- **A hardcoded `open` on a `showModal` overlay (`modal-ui` / `drawer-ui`) bricks the whole page** — no console error; only a live click / `elementFromPoint` probe catches it.
+- **Set `select-ui.options = [...]` for dynamic options, never `appendChild(<option>)`** — the listbox popover is stamped around the INITIAL `<option>` children at connect; later-appended options land outside it as visible flow content.
+- **`<thead>/<tbody>/<tr>/<th>/<td>` are foster-parented OUT of the DOM inside any non-`<table>` ancestor, including custom elements** — gone before JS runs; never author them inside a custom element.
+
+### UIElement / reactivity class
+
+- **Declaring `textContent` / `innerHTML` / `className` / `id` in `static properties` breaks the native accessor** — `installProps` swaps it for a signal, so `el.textContent = ''` becomes a signal write, not a child-wipe.
+- **`customElements.whenDefined(tag)` never rejects; an unimported tag never resolves** — a `Promise.all([...]).then(bootstrap)` gate hangs forever with no console error (chrome renders via tag-keyed CSS; the page is just "empty").
+- **A MutationObserver that watches its own host AND mutates it in the callback hangs** — drain with `this.#observer.takeRecords()` after every absorb pass.
+- **A document-listening trait must NOT re-emit the same-named event on its host with `bubbles: true`** — the bubble re-reaches document and re-fires the handler (infinite loop); use distinct incoming vs outgoing names.
+- **Parent `render()` that filters children by an attribute the child sets in its OWN `connected()` races the upgrade** — match by tag name too.
+- **Sync icon-registry checks (`isIconName` / `hasIcon`) at connect race the async manifest on static (non-Vite) deploys** — pair with `whenIconRegistryReady` deferred re-stamping.
+
+### Registration / packaging class
+
+- **Composites render internal `*-ui` tags the author never wrote** (`chat-input-ui` stamps `textarea-ui` + `select-ui`) — a consumer importing only the composite must also import those primitives (or the cluster barrel `packages/web-modules/<cluster>/index.js`) or they stay unregistered and collapse to 0px.
+- **A NEW yaml prop with `reflect: true` is not load-bearing alone** — the class's `static properties` block is hand-authored, not codegen'd from yaml; add both.
+- **Every `[slot="X"]` a component's CSS positions MUST be declared in the yaml `slots:` block** (including auto-stamped internal slots) — the slot-vocab-vs-CSS audit in `npm run check` fails CRITICAL otherwise.
+- **A new primitive's CSS must be registered in `packages/web-components/styles/components.css`** (the hand-maintained CSS aggregator) — separate from the `components/index.js` JS barrel; miss it and the element registers but renders unstyled.
+- **A primitive that programmatically creates a form-bearing primitive needs a `COMPOSITION_PAIR` entry in `scripts/release/check-composes-passthrough.mjs`** or the passthrough gate flags it.
+
 ## Meta-pattern: the "just this once" trap
 
 All of these bugs started as "just this once" exceptions — a component author thought "I'll fix it later," or "this component is special," or "the linter isn't catching it so it's fine." Each "just this once" became a template for the next author.

package/skills/{adia-ui-authoring → adia-author}/references/authoring-cycle.md

@@ -1,8 +1,6 @@
-# Authoring cycle — modes 1 & 2 (NEW or MODIFY primitive)
+# Authoring cycle — author a NEW primitive or MODIFY an existing one
 
-The 5-step procedure run AFTER [primitive-audit.md](primitive-audit.md) clears (mode 1) or jumping straight to Step 2 (mode 2: modify existing).
-
-Absorbed from the legacy author skill's Workflow section.
+The 5-step procedure run AFTER [primitive-audit.md](primitive-audit.md) clears (new primitive) — or jumping straight to Step 2 when modifying an existing one.
 
 ---
 
@@ -10,7 +8,7 @@ Absorbed from the legacy author skill's Workflow section.
 
 Before writing or editing, load these four files. They are the ground truth:
 
-- `docs/specs/component-token-contract.md` — the authoritative invariants. Skim the whole thing if you haven't read it this session; focus on "Variants vs Modes" and "Sanctioned Mode Attributes" if you're adding a new layout-affecting attribute.
+- `.claude/docs/specs/component-token-contract.md` — the authoritative invariants. Skim the whole thing if you haven't read it this session; focus on "Variants vs Modes" and "Sanctioned Mode Attributes" if you're adding a new layout-affecting attribute.
 - `packages/web-components/core/element.js` — `AdiaElement` base class. The `static properties` schema, `connected()`/`disconnected()`/`render()` lifecycle, and attribute-mapping conventions are all defined here.
 - `packages/web-components/core/form.js` — `AdiaFormElement`. Only needed if the new component participates in forms (inputs, selects, checkboxes, etc.).
 - At least one good-citizen reference that matches the shape of what you're building. Pick from: `button-ui`, `card-ui`, `input-ui`, `textarea-ui`, `check-ui`. Read both the `.js` and the `.css`.
@@ -19,7 +17,7 @@ Before writing or editing, load these four files. They are the ground truth:
 
 Before typing, answer:
 
-1. **Is this cosmetic or structural?** If the change affects `display`, `flex-direction`, `grid-template`, `padding`, layout geometry — it's a mode, not a variant. Modes require an entry in the Sanctioned Mode Attributes table (`docs/specs/component-token-contract.md` `Modes` section). Do not introduce undocumented layout-changing variants.
+1. **Is this cosmetic or structural?** If the change affects `display`, `flex-direction`, `grid-template`, `padding`, layout geometry — it's a mode, not a variant. Modes require an entry in the Sanctioned Mode Attributes table (`.claude/docs/specs/component-token-contract.md` `Modes` section). Do not introduce undocumented layout-changing variants.
 
 2. **Does the new prop fit the Boolean-default-false rule?** If the default behavior is "on," negate the prop name before writing (`closable` is wrong if closable is the default; `permanent` is right).
 
@@ -43,7 +41,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 5. **Reserved-name anti-patterns.** Avoid: `title` (collides with HTML tooltip attribute), `active` on parent components (use `value` for a selection or `step` for an index — per-item `active` on children is fine), `error` in variant names (use `danger`; reserve `error` for validation state), `disabled` on non-form-participating components (use `readonly`), `multiple` with exclusion semantics (use a negated positive like `single`).
 
-6. **Element tag ends in `-ui`; JS class is `Adia<Component>`.** `<foo-ui>` ↔ `class AdiaFoo extends AdiaElement`. Three-way consistency: filename, class name, custom-element tag. The sanctioned `-n` carve-out is `cot-ui` (the chain-of-thought streaming component); `nav-ui` was deprecated in favor of the `-ui` replacements. New `-n` tags require a contract-doc update — see `docs/specs/component-token-contract.md`.
+6. **Element tag ends in `-ui`; JS class is `Adia<Component>`.** `<foo-ui>` ↔ `class AdiaFoo extends AdiaElement`. Three-way consistency: filename, class name, custom-element tag. The sanctioned `-n` carve-out is `cot-ui` (the chain-of-thought streaming component); `nav-ui` was deprecated in favor of the `-ui` replacements. New `-n` tags require a contract-doc update — see `.claude/docs/specs/component-token-contract.md`.
 
 ### CSS
 
@@ -80,7 +78,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 5. **Component tokens follow `--<tag-stem>-<prop>`.** `--button-bg`, not `--btn-bg`. Files hosting multiple `@scope` blocks (e.g. `layout.css` with `col-ui`, `row-ui`, `stack-ui`) use each scope's own stem (`--col-gap`, `--row-gap`, `--stack-gap`).
 
-6. **Consume L3, not L2.** In a variant/state body, alias from the role×state matrix, not the family base. Right: `--button-fg-hover: var(--a-accent-fg-hover)`. Wrong: `--button-fg: var(--a-accent)`.
+6. **Consume L3, not L2.** In a variant/state body, alias from the role×state matrix, not the family base. Right: `--button-fg-hover: var(--a-primary-fg-hover)`. Wrong: `--button-fg: var(--a-primary)`.
 
 7. **No BEM, no `::part()`, no `::slotted()`.** AdiaUI is light-DOM; the shadow-DOM escape hatches don't apply. Slots are styled through slotted attribute selectors (`:scope > [slot="foo"]`), not `::slotted()`.
 
@@ -196,16 +194,16 @@ npm run verify:palette      # CVD thresholds across theme × scheme
 node -c path/to/new/file.js # JS syntax check
 ```
 
-The full release-side gate roster lives in the **adia-ui-release** skill's gate catalog. Invoke `adia-ui-release` mode "Just verify" for the comprehensive sweep after any structural change.
+The full release-side gate roster lives in the sibling **adia-release** skill; run its pre-flight sweep after any structural change.
 
 If a gate fails, fix before declaring done.
 
 ## Cross-references
 
-- [primitive-audit.md](primitive-audit.md) — mode 1 §0 gate (run BEFORE this)
+- [primitive-audit.md](primitive-audit.md) — the §0 gate (run BEFORE this)
 - [api-contract.md](api-contract.md) — deep dive on prop naming, type choices, reflection policy
 - [css-patterns.md](css-patterns.md) — exhaustive CSS architecture (@scope, variants, modes)
 - [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listener patterns
 - [anti-patterns.md](anti-patterns.md) — full failure-mode catalogue, file:line refs
 - [worked-example.md](worked-example.md) — badge-ui + counter-ui walkthroughs
-- [token-contract.md](token-contract.md) — mode 5 audit (post-implementation token check)
+- [token-contract.md](token-contract.md) — token audit (post-implementation check)

package/skills/adia-author/references/canonical-pattern-index.md

@@ -0,0 +1,243 @@
+# Canonical Pattern Index — survey targets for Mode 8 (composite-demo-protocol.md)
+
+**Auto-generated** by this skill's `scripts/build-canonical-pattern-index.mjs`. Do not edit by hand — re-run the build script (from the monorepo root) after adding new canonicals to `apps/`, `catalog/`, or `playgrounds/`.
+
+**Total canonical `.contents.html` files**: 111
+
+## How to use this index
+
+1. From Phase 1 of [composite-demo-protocol.md](composite-demo-protocol.md), name the UI type.
+2. Find the matching section below.
+3. Read every `.contents.html` listed (or the closest 2-3 if the section has many).
+4. Extract primitive composition per Phase 3 of the protocol.
+5. Cite the path in your demo's `<!-- Pattern source: ... -->` comment.
+
+---
+
+## billing (5)
+
+> Billing dashboards (current plan, invoices, payment methods, usage). Lift card-ui + section + col-ui + field-ui chain from billing.contents.html.
+
+- `apps/saas/app/billing/billing.contents.html` — 482 lines (from SaaS app dashboards)
+- `apps/user-flow/app/registration/billing/billing.contents.html` — 94 lines (from User-flow templates)
+- `catalog/ui-patterns/app/invoice-line-items/invoice-line-items.contents.html` — 91 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/newsletter-subscription/newsletter-subscription.contents.html` — 36 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/payment-method-form/payment-method-form.contents.html` — 65 lines (from UI-pattern atomics (catalog))
+
+## dashboard (1)
+
+> Admin dashboards (KPI grids, overview cards). Lift grid-ui responsive columns from admin-dashboard.contents.html.
+
+- `apps/saas/app/admin-dashboard/admin-dashboard.contents.html` — 1566 lines (from SaaS app dashboards)
+
+## settings (5)
+
+> Settings pages (preferences, security, appearance). Lift card-ui per setting group + col-ui spacing.
+
+- `apps/saas/app/settings-page/settings-page.contents.html` — 267 lines (from SaaS app dashboards)
+- `apps/user-flow/app/onboarding/notification-prefs/notification-prefs.contents.html` — 65 lines (from User-flow templates)
+- `catalog/ui-patterns/app/settings-appearance/settings-appearance.contents.html` — 13 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/settings-notifications/settings-notifications.contents.html` — 45 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/settings-page/settings-page.contents.html` — 30 lines (from Page-shell templates (catalog))
+
+## auth-flow (10)
+
+> Authentication flows (sign-in, MFA, OAuth, password reset). Lift single-column form layout from sign-in.contents.html siblings.
+
+- `apps/user-flow/app/auth/email-change/verify/verify.contents.html` — 38 lines (from User-flow templates)
+- `apps/user-flow/app/auth/forgot-password/forgot-password.contents.html` — 32 lines (from User-flow templates)
+- `apps/user-flow/app/auth/oauth/callback/callback.contents.html` — 39 lines (from User-flow templates)
+- `apps/user-flow/app/auth/reset-password/reset-password.contents.html` — 61 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/mfa/mfa.contents.html` — 40 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/otp/verify/verify.contents.html` — 38 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/password/password.contents.html` — 52 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/sign-in.contents.html` — 50 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-up/mfa-setup/mfa-setup.contents.html` — 64 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-up/verify/verify.contents.html` — 38 lines (from User-flow templates)
+
+## onboarding-wizard (3)
+
+> Onboarding multi-step wizards. Lift step-progress + section + cta-row pattern.
+
+- `apps/user-flow/app/onboarding/first-action/first-action.contents.html` — 77 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/welcome/welcome.contents.html` — 68 lines (from User-flow templates)
+- `catalog/ui-patterns/app/onboarding-checklist/onboarding-checklist.contents.html` — 46 lines (from UI-pattern atomics (catalog))
+
+## registration-wizard (5)
+
+> Registration multi-step flows. Lift wizard step + form composition.
+
+- `apps/saas/app/profile-security/profile-security.contents.html` — 524 lines (from SaaS app dashboards)
+- `apps/user-flow/app/auth/sign-up/profile/profile.contents.html` — 51 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-up/sign-up.contents.html` — 45 lines (from User-flow templates)
+- `apps/user-flow/app/registration/profile/profile.contents.html` — 51 lines (from User-flow templates)
+- `catalog/ui-patterns/app/user-profile-card/user-profile-card.contents.html` — 34 lines (from UI-pattern atomics (catalog))
+
+## list-with-detail (3)
+
+> List + detail compositions (entity rows + drawer/modal detail). Lift entity-item + drawer pattern.
+
+- `apps/saas/app/members/members.contents.html` — 447 lines (from SaaS app dashboards)
+- `apps/user-flow/app/registration/team-size/team-size.contents.html` — 73 lines (from User-flow templates)
+- `catalog/ui-patterns/app/users-table-badge/users-table-badge.contents.html` — 42 lines (from UI-pattern atomics (catalog))
+
+## integrations-list (3)
+
+> Searchable integration/connector grids. Lift grid-ui + card-ui + empty-state-inside-card pattern.
+
+- `apps/saas/app/integrations/integrations.contents.html` — 856 lines (from SaaS app dashboards)
+- `apps/user-flow/app/registration/integrations/integrations.contents.html` — 109 lines (from User-flow templates)
+- `catalog/ui-patterns/app/api-key-table/api-key-table.contents.html` — 22 lines (from UI-pattern atomics (catalog))
+
+## agent-activity (3)
+
+> Agent activity / reasoning feeds. Lift activity-feed scroll + collapsed-reasoning pattern.
+
+- `catalog/ui-patterns/app/agent-activity-feed/agent-activity-feed.contents.html` — 17 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/agent-reasoning-collapsed/agent-reasoning-collapsed.contents.html` — 13 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/agent-canvas/agent-canvas.contents.html` — 56 lines (from Page-shell templates (catalog))
+
+## chat (3)
+
+> Chat surfaces (thread, composer, sidebar). Lift chat-streaming-surface composition.
+
+- `apps/genui/app/factory-chat/factory-chat.contents.html` — 48 lines (from GenUI app routes)
+- `catalog/ui-patterns/app/chat-streaming-surface/chat-streaming-surface.contents.html` — 16 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/chat-page/chat-page.contents.html` — 67 lines (from Page-shell templates (catalog))
+
+## editor (6)
+
+> Editor panes (code, preview, toolbar). Lift editor-shell composition.
+
+- `apps/genui/app/a2ui-editor/a2ui-editor.contents.html` — 261 lines (from GenUI app routes)
+- `apps/genui/app/render-preview/render-preview.contents.html` — 74 lines (from GenUI app routes)
+- `catalog/ui-patterns/app/editor-code-pane/editor-code-pane.contents.html` — 16 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/editor-preview-pane/editor-preview-pane.contents.html` — 13 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/doc-editor/doc-editor.contents.html` — 65 lines (from Page-shell templates (catalog))
+- `catalog/page-shells/app/editor-page/editor-page.contents.html` — 25 lines (from Page-shell templates (catalog))
+
+## kanban (2)
+
+> Kanban / column-based boards. Lift kanban-board-3col pattern.
+
+- `catalog/ui-patterns/app/kanban-board-3col/kanban-board-3col.contents.html` — 145 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/kanban-page/kanban-page.contents.html` — 121 lines (from Page-shell templates (catalog))
+
+## data-table (5)
+
+> Data tables with badges/inline actions. Lift users-table-badge composition.
+
+- `apps/user-flow/app/onboarding/import-data/import-data.contents.html` — 70 lines (from User-flow templates)
+- `catalog/ui-patterns/app/card-grid-images/card-grid-images.contents.html` — 91 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/feature-grid-icons/feature-grid-icons.contents.html` — 60 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/permission-matrix-table/permission-matrix-table.contents.html` — 58 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/sortable-search-table/sortable-search-table.contents.html` — 23 lines (from UI-pattern atomics (catalog))
+
+## command (1)
+
+> Command palette / global search. Lift command-palette overlay pattern.
+
+- `catalog/ui-patterns/app/command-palette/command-palette.contents.html` — 46 lines (from UI-pattern atomics (catalog))
+
+## overlay (2)
+
+> Modals, drawers, popovers. Lift destructive-confirm-modal pattern for confirmations.
+
+- `apps/user-flow/app/registration/confirmation/confirmation.contents.html` — 79 lines (from User-flow templates)
+- `catalog/ui-patterns/app/destructive-confirm-modal/destructive-confirm-modal.contents.html` — 28 lines (from UI-pattern atomics (catalog))
+
+## multi-step-funnel (1)
+
+> Multi-step conversion funnels. Lift conversion-funnel-6step composition.
+
+- `catalog/ui-patterns/app/conversion-funnel-6step/conversion-funnel-6step.contents.html` — 26 lines (from UI-pattern atomics (catalog))
+
+## feed (2)
+
+> Activity / event feeds. Lift activity-feed composition.
+
+- `apps/genui/app/gen-ui-feed/gen-ui-feed.contents.html` — 392 lines (from GenUI app routes)
+- `catalog/ui-patterns/app/order-tracking-timeline/order-tracking-timeline.contents.html` — 45 lines (from UI-pattern atomics (catalog))
+
+## marketing (2)
+
+> Marketing pages, hero CTAs. Lift marketing-hero-cta composition.
+
+- `catalog/ui-patterns/app/marketing-hero-cta/marketing-hero-cta.contents.html` — 17 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/marketing-page/marketing-page.contents.html` — 55 lines (from Page-shell templates (catalog))
+
+## error-page (6)
+
+> Error states (404, 500, forbidden, expired). Lift centered single-card error pattern.
+
+- `apps/user-flow/app/auth/account-deleted/account-deleted.contents.html` — 40 lines (from User-flow templates)
+- `apps/user-flow/app/auth/account-locked/account-locked.contents.html` — 40 lines (from User-flow templates)
+- `apps/user-flow/app/auth/forbidden/forbidden.contents.html` — 38 lines (from User-flow templates)
+- `apps/user-flow/app/auth/link-expired/link-expired.contents.html` — 41 lines (from User-flow templates)
+- `apps/user-flow/app/auth/session-expired/session-expired.contents.html` — 37 lines (from User-flow templates)
+- `catalog/page-shells/app/error-page/error-page.contents.html` — 20 lines (from Page-shell templates (catalog))
+
+## demo-playground (3)
+
+> Internal demo + playground surfaces. Use these as reference for composition style; not always production-grade.
+
+- `apps/genui/app/a2ui/a2ui.contents.html` — 48 lines (from GenUI app routes)
+- `apps/genui/app/css-channel-demo/css-channel-demo.contents.html` — 70 lines (from GenUI app routes)
+- `apps/genui/app/streams-bridge/streams-bridge.contents.html` — 80 lines (from GenUI app routes)
+
+## other (40)
+
+> Misc canonicals. Inspect contents.html to determine UI type.
+
+- `apps/genui/app/gen-ui/gen-ui.contents.html` — 47 lines (from GenUI app routes)
+- `apps/user-flow/app/auth/accept-invite/accept-invite.contents.html` — 52 lines (from User-flow templates)
+- `apps/user-flow/app/auth/forgot-password/sent/sent.contents.html` — 33 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/magic-link/sent/sent.contents.html` — 35 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/mfa/recovery/recovery.contents.html` — 46 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-out/sign-out.contents.html` — 33 lines (from User-flow templates)
+- `apps/user-flow/app/auth/sign-up/sso-only/sso-only.contents.html` — 41 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/browser-extension/browser-extension.contents.html` — 69 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/complete/complete.contents.html` — 82 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/connect-source/connect-source.contents.html` — 82 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/mobile-app/mobile-app.contents.html` — 67 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/mode/mode.contents.html` — 50 lines (from User-flow templates)
+- `apps/user-flow/app/onboarding/review/review.contents.html` — 301 lines (from User-flow templates)
+- `apps/user-flow/app/registration/address/address.contents.html` — 253 lines (from User-flow templates)
+- `apps/user-flow/app/registration/brand-scrape/brand-scrape.contents.html` — 156 lines (from User-flow templates)
+- `apps/user-flow/app/registration/departments/departments.contents.html` — 91 lines (from User-flow templates)
+- `apps/user-flow/app/registration/done/done.contents.html` — 281 lines (from User-flow templates)
+- `apps/user-flow/app/registration/import/import.contents.html` — 79 lines (from User-flow templates)
+- `apps/user-flow/app/registration/invite/invite.contents.html` — 99 lines (from User-flow templates)
+- `apps/user-flow/app/registration/legal/legal.contents.html` — 102 lines (from User-flow templates)
+- `apps/user-flow/app/registration/org-review/org-review.contents.html` — 247 lines (from User-flow templates)
+- `apps/user-flow/app/registration/personal/personal.contents.html` — 146 lines (from User-flow templates)
+- `apps/user-flow/app/registration/plan/plan.contents.html` — 128 lines (from User-flow templates)
+- `apps/user-flow/app/registration/support/support.contents.html` — 146 lines (from User-flow templates)
+- `apps/user-flow/app/registration/use-case/use-case.contents.html` — 77 lines (from User-flow templates)
+- `apps/user-flow/app/registration/workspace/workspace.contents.html` — 45 lines (from User-flow templates)
+- `catalog/ui-patterns/app/email-inbox-list/email-inbox-list.contents.html` — 135 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/import-mapping/import-mapping.contents.html` — 217 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/loading-skeleton-placeholder/loading-skeleton-placeholder.contents.html` — 62 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/product-card-buy/product-card-buy.contents.html` — 39 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/social-media-post-card/social-media-post-card.contents.html` — 31 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/survey-rating-form/survey-rating-form.contents.html` — 31 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/testimonials-avatar-cards/testimonials-avatar-cards.contents.html` — 56 lines (from UI-pattern atomics (catalog))
+- `catalog/ui-patterns/app/tooltip-hover/tooltip-hover.contents.html` — 12 lines (from UI-pattern atomics (catalog))
+- `catalog/page-shells/app/form-page/form-page.contents.html` — 26 lines (from Page-shell templates (catalog))
+- `catalog/page-shells/app/gallery-page/gallery-page.contents.html` — 79 lines (from Page-shell templates (catalog))
+- `playgrounds/admin-shell/app/admin-shell.contents.html` — 99 lines (from Playgrounds)
+- `playgrounds/chat/app/chat.contents.html` — 49 lines (from Playgrounds)
+- `playgrounds/composed-flow/app/composed-flow.contents.html` — 294 lines (from Playgrounds)
+- `playgrounds/table-toolbar/app/table-toolbar.contents.html` — 31 lines (from Playgrounds)
+
+---
+
+## Maintenance
+
+Re-build this index:
+
+```bash
+node <this-skill>/scripts/build-canonical-pattern-index.mjs   # from the monorepo root
+```
+
+If a heuristic misclassifies a path (the file lands in `other` or the wrong UI type), update the `inferUiType()` regex in `scripts/build-canonical-pattern-index.mjs`.

package/skills/{adia-ui-authoring → adia-author}/references/code-style.md

@@ -2,9 +2,7 @@
 
 Modern AdiaUI is small, declarative, and token-driven. Most of the "bugs" agents write are bugs _against the conventions_ — bare `<div>`s where `col-ui` belongs, raw `<input>` where `input-ui` belongs, hex colors where tokens belong. The conventions are not stylistic preferences; each one corresponds to a working feature (theme switching, density modes, form association, focus rings) that breaks silently when the convention is violated.
 
-When in doubt: look up the catalog (use the `lookup_component` MCP tool, or the consumer-side composition skill in the adia-ui-factory plugin), pick the existing primitive, wire through tokens.
-
-Absorbed from the legacy code-bestpractices skill (now a redirect; this file replaces the daily-driver content).
+When in doubt: look up the catalog (the `lookup_component` MCP tool, or the adia-factory plugin's composition skill), pick the existing primitive, wire through tokens.
 
 ---
 
@@ -24,7 +22,7 @@ Every interactive surface, form control, layout container, and content block shi
 <input type="email" />
 ```
 
-The catalog has 90+ `*-ui` elements. Before composing, confirm via `get_component_map` (the a2ui MCP) that the one you want exists — and what its real prop names are.
+The catalog has 127 component directories under `packages/web-components/components/`. Before composing, confirm via `get_component_map` (the a2ui MCP) that the one you want exists — and what its real prop names are.
 
 ## Layout primitives
 
@@ -116,7 +114,7 @@ Static markup written by hand uses the components directly. UIs generated from i
 
 The runtime handles `createSurface` / `updateComponents` / `wireComponents` messages and binds `FormController` / `DataStreamController` controllers automatically. Don't roll your own message handler — the wiring lives in `@adia-ai/a2ui-runtime`.
 
-For multi-turn refinement, pass back `state_id` from prior responses so the engine can chain through `parent_state_id`. See the **adia-ui-a2ui** skill for the operator playbook.
+For multi-turn refinement, pass back `state_id` from prior responses so the engine can chain through `parent_state_id`. See the sibling **adia-a2ui** skill for the operator playbook.
 
 ## Two-block `@scope` CSS
 
@@ -137,8 +135,8 @@ Component CSS uses a mandatory two-block `@scope` structure. Tokens go in `:wher
   }
 
   :scope[variant="accent"] {
-    --badge-bg: var(--a-accent-bg);   /* token override only */
-    --badge-fg: var(--a-accent-fg);
+    --badge-bg: var(--a-primary-bg);   /* token override only */
+    --badge-fg: var(--a-primary-fg);
   }
 }
 ```
@@ -156,17 +154,17 @@ Component CSS aliases from L3 (the role × state matrix), not L2 (the family bas
 ```css
 /* right — L3 alias keeps the state cascade working */
 :scope[variant="accent"]:hover {
-  --button-bg: var(--a-accent-bg-hover);
-  --button-fg: var(--a-accent-fg-hover);
+  --button-bg: var(--a-primary-bg-hover);
+  --button-fg: var(--a-primary-fg-hover);
 }
 
 /* wrong — L2 stops the cascade */
 :scope[variant="accent"]:hover {
-  --button-bg: var(--a-accent);   /* loses theme + contrast wiring */
+  --button-bg: var(--a-primary);   /* loses theme + contrast wiring */
 }
 ```
 
-For text on filled accent discs (radio dots, step numerals), use `--a-chrome-light`, not `--a-accent-fg` — `accent-fg` resolves near-black in the current OKLCH derivation and disappears on saturated accent backgrounds.
+For text on filled primary discs (radio dots, step numerals), use `--a-chrome-light` — theme-stable against any fill. (`--a-primary-fg` also works post-Material-adoption — it resolves to the palette's fixed-light on-color — but `--a-chrome-light` stays correct on arbitrary/brand fills too.)
 
 Audit procedure + chrome palette in [token-contract.md](token-contract.md).
 
@@ -174,7 +172,7 @@ Audit procedure + chrome palette in [token-contract.md](token-contract.md).
 
 A **variant** is cosmetic — color, border, shadow depth. A **mode** restructures the box — direction, grid template, display type.
 
-Variant bodies may only contain `--component-*: var(...)` lines. They must NEVER touch `padding`, `display`, `position`, `width`, `height`, `gap`, `flex`, `grid`, `overflow`, `border-radius`. Layout-changing attributes are modes, and modes require an entry in the Sanctioned Mode Attributes table at `docs/specs/component-token-contract.md` `Modes` section.
+Variant bodies may only contain `--component-*: var(...)` lines. They must NEVER touch `padding`, `display`, `position`, `width`, `height`, `gap`, `flex`, `grid`, `overflow`, `border-radius`. Layout-changing attributes are modes, and modes require an entry in the Sanctioned Mode Attributes table at `.claude/docs/specs/component-token-contract.md` `Modes` section.
 
 ```css
 /* right — variant overrides tokens only */
@@ -273,7 +271,7 @@ Don't propose polyfilling native APIs already at the baseline. The runtime expec
 When transparency-mixing colors, use `oklab` not `oklch` for the interpolation space — Safari < 18 had an OKLCH-with-transparent red-shift bug, and `oklab` is perceptually equivalent here:
 
 ```css
---code-active-line-bg: color-mix(in oklab, var(--a-accent-muted) 40%, transparent);
+--code-active-line-bg: color-mix(in oklab, var(--a-primary-muted) 40%, transparent);
 ```
 
 ## Legacy avoidance
@@ -283,7 +281,7 @@ The library was renamed from `@agent-ui-kit/*` to `@adia-ai/*`; tokens went from
 ```js
 // right
 import { AdiaElement } from '@adia-ai/web-components';
-:where(:scope) { --button-bg: var(--a-accent-bg); }
+:where(:scope) { --button-bg: var(--a-primary-bg); }
 
 // wrong
 import { NanoElement } from '@agent-ui-kit/web-components';
@@ -300,7 +298,7 @@ Other deprecated forms swept in an early cut:
 - `'chat-submit'` event → `'submit'`
 - `<field-ui error="…">` → message moves to the slotted control
 
-For a wholesale migration, use the dedicated migration skill — it reads the MIGRATION GUIDE and runs the mechanical sweeps.
+For a wholesale consumer-side migration, use `adia-migrate` (adia-factory plugin) — it reads the MIGRATION GUIDE and runs the mechanical sweeps.
 
 ## Validate, always
 
@@ -312,7 +310,7 @@ For consumer markup (HTML pages, exemplars, training data), the checks are manua
 - Run the project's lint if applicable: `npx eslint <path>`.
 - Smoke the rendered output via `npm run dev` and load the touched page.
 
-For component source under `packages/web-components/components/**`, the gate is heavier — see [authoring-cycle.md](authoring-cycle.md) Step 5 + the full release-side gate roster in the **adia-ui-release** skill's gate catalog.
+For component source under `packages/web-components/components/**`, the gate is heavier — see [authoring-cycle.md](authoring-cycle.md) Step 5 + the full release-side gate roster in the sibling **adia-release** skill.
 
 ## Cross-references
 
@@ -321,9 +319,9 @@ For component source under `packages/web-components/components/**`, the gate is
 - [css-patterns.md](css-patterns.md) — full @scope + variant/mode CSS architecture
 - [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listeners
 - [token-contract.md](token-contract.md) — token audit procedure
-- [llm-bridge.md](llm-bridge.md) — mode 6 (extend @adia-ai/llm)
-- [module-promotion.md](module-promotion.md) — mode 4 (promote inline → module)
+- [llm-bridge.md](llm-bridge.md) — extend @adia-ai/llm
+- [module-promotion.md](module-promotion.md) — promote inline → module
 - [anti-patterns.md](anti-patterns.md) — failure-mode catalogue with file:line refs
-- **adia-ui-a2ui** (sibling skill) — generator / corpus / MCP pipeline
-- **adia-ui-dogfood** (sibling skill) — cross-surface visual / static QA
-- the **adia-ui-factory** plugin — composition playbook for consumers building apps on the framework
+- **adia-a2ui** (sibling skill) — generator / corpus / MCP pipeline
+- **adia-dogfood** (sibling skill) — cross-surface visual / static QA
+- the **adia-factory** plugin — composition playbook for consumers building apps on the framework