@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

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

package/skills/adia-author/references/common-gotchas.md

@@ -0,0 +1,129 @@
+# Common gotchas — authoring traps
+
+Six concrete failure modes: five from a billing-overview rebuild + multi-demo grandfather-elimination cycle (CSS/composition-layering traps, §§1–5, composite authoring specifically), plus one from the site-a2ui migration's router-race root cause (async-lifecycle sequencing, §6, any primitive or module with a multi-await lifecycle method). Each is the kind of bug that:
+
+- Renders visually broken without console errors
+- Passes existing audits silently
+- Is fixed in one place but recurs in others until pattern-corrected
+
+Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async lifecycle method (fetch, dynamic `import()`, any multi-`await` sequence) to any primitive or module: read §6. Each entry includes the pattern, the detector (if any), and the fix.
+
+## Contents
+
+1. [Component used without reading its CSS](#1-component-used-without-reading-its-css--and-especially-without-reading-its-composition-grammar)
+2. [Parent CSS overriding child component's intrinsic display](#2-parent-css-overriding-child-components-intrinsic-display)
+3. [Mixed sizes across form/control groups](#3-mixed-sizes-across-formcontrol-groups)
+4. [minmax(min, 1fr) inside repeat() fighting container queries](#4-minmaxmin-1fr-inside-repeat-fighting-container-queries)
+5. [Nested `<!-- ... -->` inside design-plan canonical-sketch fenced blocks](#5-nested----inside-design-plan-canonical-sketch-fenced-blocks)
+6. [Async load/render function completing out of order](#6-async-loadrender-function-completing-out-of-order--a-guard-at-the-checkpoint-isnt-enough)
+
+---
+
+## 1. Component used without reading its CSS — and especially without reading its composition grammar
+
+**Pattern**: Stamping `<X-ui>` and relying on attributes/slots without opening `X-ui.css`. The primitive's `@scope` rules ARE part of its API contract, not implementation details. Particularly load-bearing: composition grammars (which children the primitive expects + how it lays them out).
+
+**Example**: `payment-method-list-ui` stamped three sibling `<div data-brand>/<div data-meta>/<div data-actions>` inside `<card-ui>` and re-implemented the 3-column grid via custom `@scope` rules. Bypassed card-ui's canonical `<header>` + `[slot=icon|heading|description|action]` grammar entirely. Result: visual debt downstream (50% icon-to-frame ratio, off-rhythm tag placement, fragile chrome).
+
+**Detector**: the component-literacy step in [composite-demo-protocol.md](composite-demo-protocol.md) (Phase 2) has you read each used primitive's `.css` before locking the choice. `audit:card-structure` catches the specific card-ui bypass; analogous strict audits don't exist yet for avatar-ui / drawer-ui / aside-ui.
+
+**Fix**: Read the primitive's `.css` end-to-end. Identify its expected child structure (slot grammar). USE it; never invent a parallel layer.
+
+---
+
+## 2. Parent CSS overriding child component's intrinsic display
+
+**Pattern**: A parent composite hides/shows an embedded child via `display: none` ↔ `display: block` toggling. The `display: block` override beats the child's `:scope { display: flex }` from its own `@scope` (specificity 0,2,0 vs 0,1,0). Child's intrinsic layout silently collapses.
+
+**Example**: 4 billing composites all had:
+
+```css
+/* WRONG — clobbers empty-state-ui's flex column */
+:scope > [data-empty] { display: none; }
+:scope[empty] > [data-empty] { display: block; }
+```
+
+`empty-state-ui` declares its own `:scope { display: flex; flex-direction: column; align-items: center }`. The parent's `display: block` removed that, making icon + heading + description flow inline: **`⊡ No payment methodsAdd a method to get started.`**
+
+**Detector**: None today. Caught by user visual review.
+
+**Fix** — invert visibility toggle so no display value is set when shown:
+
+```css
+/* RIGHT — child's :scope display remains intact */
+:scope:not([empty]) > [data-empty] { display: none; }
+```
+
+---
+
+## 3. Mixed sizes across form/control groups
+
+**Pattern**: A composite stamps multiple form/control primitives in the same visual row (toolbar, button cluster, filter strip) without coordinating `size` attributes. Defaults differ — buttons might default `sm`, inputs default to a larger size, search-ui doesn't forward `size` to its inner input.
+
+**Example**: an invoice-history toolbar had buttons at `size='sm'` (24px), filter chips at `size='sm'` (24px), search input at default (~36px). Same row, mismatched baseline.
+
+**Detector**: None today. Caught by user visual review.
+
+**Fix**:
+
+- When stamping a control group, set the SAME `size` attribute on every control explicitly.
+- Wrapper primitives (search-ui wraps input-ui; select-ui wraps native select) MUST forward `[size]` to their inner control. If a wrapper doesn't forward, file a fix in the wrapper rather than working around it in the consumer.
+
+---
+
+## 4. minmax(min, 1fr) inside repeat() fighting container queries
+
+**Pattern**: A grid uses `repeat(N, minmax(<min>, 1fr))` with a hardcoded minimum, BUT the container also has `@container` queries that collapse columns at breakpoints. The minmax fights the breakpoints — when the container narrows, columns hit the floor and overflow before the breakpoint reduces column count.
+
+**Example**: a dashboard-layout KPI grid was `repeat(4, minmax(16em, 1fr))` plus `@container ≤48em → 2 cols` and `≤32em → 1 col`. Redundant + conflicted. Removed the minmax; container queries own the responsive collapse cleanly.
+
+**Detector**: None today.
+
+**Fix**: When a grid has container-query breakpoints, use plain `repeat(N, 1fr)`. The breakpoints handle responsive behavior; minmax is for grids WITHOUT container queries.
+
+---
+
+## 5. Nested `<!-- ... -->` inside design-plan canonical-sketch fenced blocks
+
+**Pattern**: The `<!-- design-plan: ... -->` block contains a fenced ` ```canonical-sketch ... ``` ` body. Authors sometimes paste HTML examples with inner `<!-- ... -->` comments into the sketch. HTML comments DON'T NEST — the inner `-->` closes the OUTER `<!-- design-plan: -->`. Trailing ` ``` --> ` then leaks as visible text on the page.
+
+**Example**: a billing-overview.examples.html had two inner comments inside its canonical-sketch (annotations + a drawer composition example). Stray ` ``` --> ` rendered above the page header.
+
+**Detector**: ✓ caught by `npm run audit:demo-pattern-source` — emits `phase_3_sketch contains an inner <!-- ... --> comment` finding.
+
+**Fix**: Remove inner HTML comments from the canonical-sketch. Use plain text annotations or remove the doc-noise entirely.
+
+---
+
+## 6. Async load/render function completing out of order — a guard AT the checkpoint isn't enough
+
+**Pattern**: A lifecycle method does asynchronous work (fetch, dynamic `import()`, any `await`) BEFORE reaching a sequence/resolver checkpoint that's guarded against stale calls. The guard only checks identity/sequence AT that one checkpoint — it doesn't protect the awaits that come after it. A call that started earlier but is slow can resume, pass every checkpoint it reaches (each one, in isolation, looks current), and finish writing state AFTER a faster, later call already completed — clobbering the newer result with stale content. The bug is invisible per-checkpoint because each individual guard check "passes"; the invariant that breaks is the ORDER completions land in, not any single check's correctness.
+
+**Example**: `router-ui`'s `#loadContent` (`packages/web-components/core/provider.js`) fetched content, then ran it through the template resolver, which itself carried the only staleness guard (checked at resolver entry). A navigation to `/site/components/button` that fetched slowly could resume after a faster later navigation to `/site/dashboard` had already rendered — the resolver's own guard had nothing to check against by the time the stale call reached it, since the fetch (before the resolver) was itself unguarded. Reproduced deterministically with a 2-second-delayed fetch: the DOM showed the Dashboard's content under `data-route-path="button"`. Three separate flake classes across the site-a2ui migration all traced back to this one mechanism (`site-a2ui/FINDINGS.md`, "Router race fully root-caused: late-resuming #loadContent steals the sequence").
+
+**Detector**: None generic — a per-page timing repro (delay the async step past the next call's completion, then assert final state matches the LAST call issued, not the first-guarded one) is how this was actually caught; no static check flags it.
+
+**Fix**: Claim a monotonic sequence token as the FIRST line of the function, before any `await` — not at the first checkpoint reached. Re-check the token after EVERY subsequent `await` (not just once), and return early — without writing any state or emitting any event — the moment it no longer matches. A checkpoint guard placed only where you happen to already have a natural pause point (a resolver, a render call) is not equivalent to this; it only catches staleness FOR CALLS THAT REACH THAT SPECIFIC POINT before the pause, which a slow-but-eventually-arriving call always will.
+
+**Illustrative** (simplified from the real fix — see `provider.js:230,245,250,286` for the actual code):
+
+```javascript
+async #loadContent(route) {
+  const nav = ++this.#navSeq;              // claimed before any await
+  const content = await fetchContent(route);
+  if (nav !== this.#navSeq) return;        // re-checked after EVERY await
+  const resolved = await this.#templateResolver.resolve(content);
+  if (nav !== this.#navSeq) return;
+  // ...write state / emit route-loaded only here
+}
+```
+
+**Generalizes to**: any lifecycle method with more than one `await` where a caller can re-invoke it before the previous call finishes (route changes, search-as-you-type, tab switches, any "latest wins" async UI update) — not just routing.
+
+---
+
+## Meta-pattern across gotchas 1–5
+
+**Composites and primitives have layered contracts. The parent's CSS shouldn't reach into the child's layout territory. The child's CSS shouldn't fight its parent's container queries. The audit should detect the rendering hazard, not just the parsing structure.**
+
+The structural defense for #1 (composition-grammar bypass) is `npm run audit:card-structure[:strict]` / `npm run audit:avatar-structure` / `npm run audit:alert-structure` (HTML + JS `createElement` scan) plus `npm run audit:sketch-grammar` at Phase 3. The component-literacy read is a hint, not a gate — the mechanical defenses above are the proximate fix. See [composite-demo-protocol.md](composite-demo-protocol.md) Phase 2. Gotchas #2–4 are caught only by visual review until corresponding audits are added. #6 is a distinct axis (async-lifecycle correctness, not CSS layering) — see its own Detector/Fix above.