@adia-ai/adia-ui-forge 0.1.2

package/skills/adia-ui-authoring/references/api-contract.md

@@ -0,0 +1,205 @@
+# API Contract — Props, Attributes, Reflection
+
+Deep dive on declaring component APIs in AdiaUI. Read this when adding a new prop whose shape doesn't match any obvious pattern in the good-citizen references.
+
+## The `static properties` block
+
+Every `AdiaElement` subclass declares its public API as a `static properties` object. Keys are camelCase JS names; values describe type, default, reflection, and attribute mapping.
+
+```javascript
+static properties = {
+  disabled:  { type: Boolean, default: false,  reflect: true },
+  placeholder: { type: String,  default: '',     reflect: true },
+  value:     { type: String,  default: '' },
+  maxLength: { type: Number,  default: null,   reflect: true, attribute: 'max-length' },
+};
+```
+
+**Field rules:**
+
+- `type` — one of `String`, `Number`, `Boolean`, `Object`, `Array`. The runtime uses this to coerce attribute strings into typed values.
+- `default` — the value the prop takes when no attribute is present AND no JS value has been assigned. For `Boolean` props, default is ALWAYS `false` (see rule 1). For numeric props, default is `0`, a real value, or `null` for indeterminate — NEVER a sentinel like `-1`.
+- `reflect` — when `true`, JS property changes write back to the HTML attribute so CSS can match it. Required for every state-bearing Boolean. Usually safe to omit for large value props (long strings, big objects).
+- `attribute` — explicit kebab-case mapping when the JS name doesn't auto-convert cleanly. `camelCase` → `camel-case` automatic; override via `attribute: 'max-length'` when you want non-default behavior.
+
+## The `attr:` silent-typo trap
+
+A real bug caught in iteration 4:
+
+```javascript
+// BROKEN — silent
+allowHalf: { type: Boolean, default: false, reflect: true, attr: 'allow-half' },
+
+// FIXED
+allowHalf: { type: Boolean, default: false, reflect: true, attribute: 'allow-half' },
+```
+
+`attr:` is not a recognized key. The mapper ignores it. The default auto-conversion (`allowHalf` → `allow-half`) happens to produce the same result, so the bug hides — until someone changes the prop name and notices the attribute never wired.
+
+Use `attribute:` verbatim. If you think you're writing `attr:`, stop and correct it before saving.
+
+## Boolean prop naming — the flip rule
+
+AdiaUI conventions require `default: false` on all Booleans. The naming follows:
+
+| Intended default behavior | Wrong name (default:true) | Right name (default:false) |
+| --- | --- | --- |
+| Modal can be dismissed | `closable` | `permanent` |
+| Skeleton animates | `animate` | `static` |
+| Stream shows blinking cursor | `cursor` | `hideCursor` |
+| Chart shows average line | `average` | `hideAverage` |
+| Toggle group allows multi-select | `multiple` | `single` |
+| Swiper pauses on hover | `pause-on-hover` | `noPauseOnHover` |
+
+**Naming patterns:**
+
+- `permanent` / `static` / `readonly` — describes the non-default state positively.
+- `no*` / `hide*` / `disable*` — prefixes for "opt-out of a default."
+
+**Don't write:**
+
+- `enabled` (invert to `disabled`), `visible` (invert to `hidden`) — these clash with standard HTML attribute vocabulary.
+- Double-negatives like `unhide` or `dontSkip`.
+
+## Numeric props — `null` over sentinels
+
+Indeterminate, unknown, or "not yet set" numeric state uses `null`, not `-1` or `Infinity`:
+
+```javascript
+// BROKEN — `-1` is a magic sentinel
+value: { type: Number, default: -1, reflect: true }
+// Consumer: if (this.value !== -1) { ... }
+
+// FIXED
+value: { type: Number, default: null, reflect: true }
+// Consumer: if (this.value != null) { ... }
+```
+
+The `progress-ui` component carried `-1` for "indeterminate" for a long time. Branching on a specific number is fragile — someone assigns `-1` meaningfully later and the indeterminate check breaks silently. `null` is unambiguous.
+
+**Back-compat coercion is allowed:**
+
+```javascript
+set value(v) {
+  if (v === -1) v = null; // legacy input coercion, remove in a future cycle
+  this._value = v;
+}
+```
+
+## Reserved-name anti-patterns
+
+These prop names collide with HTML semantics, framework-wide conventions, or create ambiguity in audit. Pick alternatives:
+
+### `title`
+
+HTML's global `title` attribute is the browser tooltip. Using `title` on a custom element makes any custom-element heading a tooltip by default, which is almost never intended. Use `heading`.
+
+### `active` on a parent component
+
+Children can have per-item `active` (a Boolean describing that item's state). Parents use `value` (for a selection) or `step` (for an index into a series).
+
+- `<timeline-item-ui active>` — OK, per-item Boolean state.
+- `<timeline-ui step="3">` — correct: parent holds the index.
+- `<timeline-ui active="3">` — wrong: `active` shouldn't carry a non-boolean payload.
+
+### `error` as a variant
+
+Reserve `error` for validation state (`[error]` on form inputs matches ARIA patterns). For visual emphasis meaning "destructive/negative," use `danger`, matching the semantic family (`--a-danger-*` tokens).
+
+```html
+<!-- wrong -->
+<tag-ui variant="error">Failed</tag-ui>
+
+<!-- right -->
+<tag-ui variant="danger">Failed</tag-ui>
+
+<!-- separate use -->
+<input-ui error>Please enter a valid email</input-ui>
+```
+
+### `disabled` on a non-form component
+
+`disabled` has form-participating semantics — it removes the element from the tab order, blocks submission, etc. On a non-form component (a diagram, a toolbar, a noodle editor), use `readonly`:
+
+- `<input-ui disabled>` — correct: input is form-participating.
+- `<noodles-ui readonly>` — correct: diagram is read-only, not form-disabled.
+
+### `multiple` with exclusion semantics
+
+`<select multiple>` in HTML means "allow multiple selections." A prop named `multiple` means "multi-select is the default." If you want single-select as the default behavior:
+
+```html
+<!-- wrong: implies multiple was default, which violates Boolean-false rule -->
+<toggle-group-ui multiple>...</toggle-group-ui>
+
+<!-- right: single-select is the opt-out, matches Boolean-false -->
+<toggle-group-ui single>...</toggle-group-ui>
+```
+
+## Three-way name consistency
+
+The component has three names that must agree:
+
+- **File path:** `packages/web-components/components/foo/foo.js`
+- **Class name:** `class AdiaFoo extends AdiaElement`
+- **Custom element tag:** `customElements.define('foo-ui', AdiaFoo)`
+
+A fourth consistency requirement: the CSS file at `packages/web-components/components/foo/foo.css` uses `@scope (foo-ui)`.
+
+## Extending `AdiaFormElement`
+
+Form-participating components extend `AdiaFormElement` (which extends `AdiaElement`) and get `ElementInternals` wiring, form-reset handling, and `.form` / `.labels` / `.validity` accessors for free.
+
+```javascript
+import { AdiaFormElement } from '../../core/form.js';
+
+class AdiaInput extends AdiaFormElement {
+  static properties = {
+    ...AdiaFormElement.properties, // inherit name, value, disabled, required, etc.
+    placeholder: { type: String, default: '', reflect: true },
+  };
+
+  connected() {
+    super.connected(); // MUST call — registers ElementInternals
+    // ...
+  }
+
+  disconnected() {
+    super.disconnected(); // MUST call
+    // ...
+  }
+
+  // Override `value` getter/setter if the form-submitted value differs
+  // from the stored one
+  get value() { return this._value ?? ''; }
+  set value(v) { this._value = v; this.syncValue(String(v)); }
+}
+```
+
+Key details:
+
+- **Always `super.connected()` and `super.disconnected()`** — without them, form-association doesn't register.
+- **`this.syncValue(str)`** — call this whenever the value changes to update the form-submitted string. Accepts a string.
+- **Inheriting properties** — spread `AdiaFormElement.properties` into your own `static properties` so you don't re-declare `name`, `disabled`, `required`.
+
+## Event conventions
+
+- Bubble custom events: `new CustomEvent('foo', { bubbles: true, detail: {...} })`.
+- Reuse standard events where possible: `input`, `change`, `submit`, `focus`.
+- Custom event names are kebab-case: `cot-toggle`, `noodle-connected`.
+- When dispatching state changes, fire `input` during interaction and `change` on commit. Matches native form semantics.
+
+## When to add the `render()` method
+
+`render()` runs when reflected attributes change. Use it to update internal DOM that depends on props:
+
+```javascript
+render() {
+  if (this.#textareaEl) {
+    this.#textareaEl.disabled = this.disabled;
+    this.#textareaEl.placeholder = this.placeholder;
+  }
+}
+```
+
+Rule of thumb: if CSS can do the work via an attribute selector (`:scope[disabled] { ... }`), prefer CSS. Reserve `render()` for propagating state into child inputs, recalculating positions, or reflecting data changes that attribute selectors can't express.

package/skills/adia-ui-authoring/references/authoring-cycle.md

@@ -0,0 +1,211 @@
+# Authoring cycle — modes 1 & 2 (NEW or MODIFY primitive)
+
+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.
+
+---
+
+## Step 1 — Read the contract and the reference components
+
+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.
+- `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`.
+
+## Step 2 — Classify the work before you write
+
+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.
+
+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).
+
+3. **Does the component hold state that CSS needs to read?** If yes, every state-bearing Boolean declares `{ type: Boolean, default: false, reflect: true }`.
+
+4. **Does the component add listeners, timers, or observers?** If yes, plan the `disconnected()` method at the same time as `connected()` — do not defer. The symmetric pair is one unit of work, never two.
+
+## Step 3 — Apply the non-negotiable rules
+
+These rules are the distilled lessons from a 5-iteration audit. Each one corresponds to a real bug that was fixed in the codebase. Full rationale and the bug histories are in [anti-patterns.md](anti-patterns.md).
+
+### API / Attributes
+
+1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `hideCursor`, `average` → `hideAverage`, `pause-on-hover` → `noPauseOnHover`.
+
+2. **No magic-value sentinels in numeric props.** Indeterminate = `null`, not `-1`. Consumers branch on `value == null`, which is explicit.
+
+3. **Use `attribute:` not `attr:`.** `attr:` is a silent typo — the mapper ignores it and the kebab-case HTML attribute never wires. This cost a real bug in `rating-ui`.
+
+4. **State-bearing Booleans reflect.** `{ type: Boolean, default: false, reflect: true }`. Without `reflect`, CSS can't match `:scope[disabled]`, hover/active/selected states break silently.
+
+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`.
+
+### CSS
+
+1. **Two-block `@scope` structure** is mandatory:
+
+   ```css
+   @scope (component-ui) {
+     :where(:scope) {
+       /* ── Tokens ── */
+       --component-bg: var(--a-bg);
+       --component-fg: var(--a-fg);
+       /* ...all component tokens here, zero-specificity */
+     }
+
+     :scope {
+       /* ── Base styles — consume only component tokens ── */
+       background: var(--component-bg);
+       color: var(--component-fg);
+     }
+
+     /* ── Variants / states third — override TOKENS only ── */
+     :scope[variant="outlined"] {
+       --component-bg: transparent;
+       --component-border: var(--a-border);
+     }
+   }
+   ```
+
+2. **Variants override tokens only.** A variant body may only contain `--component-*: var(...)` lines. Never `padding`, `display`, `position`, `width`, `height`, `margin`, `gap`, `flex`, `grid`, `overflow`, `border-radius`. Layout changes are modes, see rule 3 in Step 2.
+
+3. **Zero raw colors in component CSS.** No `#hex`, `rgb()`, `rgba()`, `oklch()` outside `packages/web-components/styles/colors/semantics.css` and `packages/web-components/styles/tokens.css`. Every color goes through a token.
+
+4. **Raw px ≥ 3 is forbidden.** Use `var(--a-space-*)`. Stroke/border widths (1–2px) and documented component-intrinsic constants are carve-outs, and each carve-out needs a one-line code comment explaining why the literal.
+
+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)`.
+
+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()`.
+
+### JS Lifecycle
+
+1. **Every `addEventListener` in `connected()` has a matching `removeEventListener` in `disconnected()`.** Handler must be a stable `#field` arrow (`#onClick = (e) => { ... }`), never an inline arrow passed to `addEventListener`. Inline arrows can't be removed — `removeEventListener` needs reference equality.
+
+2. **`AdiaFormElement` subclasses call `super.connected()` and `super.disconnected()`.** `ElementInternals` registration depends on it. Omitting `super` strands the form-association.
+
+3. **Timers and observers are torn down.** `clearInterval`, `clearTimeout`, `ResizeObserver.disconnect()`, `MutationObserver.disconnect()`, `IntersectionObserver.disconnect()` all in `disconnected()`.
+
+4. **Null cached DOM refs in `disconnected()`.** `this.#fooEl = null` after removing its listeners. Prevents stale-tree GC pinning when the component is re-attached.
+
+5. **Never declare `disconnected()` twice in one class.** The second silently overrides the first — this exact bug lost `ResizeObserver` cleanup in `chart.js` for several commits. If you find yourself needing a "second disconnected," merge it into the existing one.
+
+6. **Popover/tooltip overlays created in `connected()` are removed in `disconnected()`.** Anything appended to `document.body` or `<body>` via the Popover API needs explicit cleanup; they don't GC with the host.
+
+7. **Inline arrows on dynamically created ephemeral DOM are tolerated only when the container is guaranteed fully-detached before re-render.** If a row is built fresh per render and the parent's `innerHTML` replacement detaches the old subtree, GC collects the listeners with their nodes. If the container persists, use stable handlers or event delegation on the parent.
+
+### Field composition
+
+1. **Do not add a `label` attribute to a new form-associated control.** `<field-ui label="…">` is the canonical labeled-field wrapper. It owns the real `<label for="…">` and binds to the slotted control's id for proper click-to-focus — a pattern the embedded per-control `label` attribute can't provide (no `[for]`, just a shadow slot). Existing controls (input-ui, select-ui, textarea-ui, switch-ui, check-ui, radio-ui, slider-ui, calendar-picker-ui, upload-ui, range-ui) still accept the legacy `label` attr but log a one-shot console.warn; **no new control should declare one**. Wrap instead:
+
+   ```html
+   <!-- right -->
+   <field-ui label="Email">
+     <input-ui type="email" value="…"></input-ui>
+   </field-ui>
+
+   <!-- wrong (deprecated) -->
+   <input-ui label="Email" type="email" value="…"></input-ui>
+   ```
+
+   `field-ui` also carries `[slot="trailing"]` and `[slot="action"]` composition slots + an `inline` mode attribute (stacked vs. single-row). See the Field component at `packages/web-components/components/field/`.
+
+### Nested-control composition
+
+1. **Composite hosts own the focus ring; nested form controls suppress theirs.** When a composite wraps a form control as an internal implementation detail (textarea-ui inside chat-input-ui is the canonical example), the composite IS the primary surface from a user's perspective. Focus should wrap the whole composite, not just the inner control. Pattern:
+
+   ```css
+   @scope (my-composite-ui) {
+     /* 1. Composite paints the ring via :focus-within —
+        wraps both the control and any siblings inside the shell. */
+     :scope:focus-within {
+       box-shadow: var(--my-composite-focus-ring);
+     }
+     :scope[aria-invalid="true"]:focus-within,
+     :scope[error]:focus-within {
+       box-shadow: var(--my-composite-focus-ring-invalid);
+     }
+
+     /* 2. Suppress the inner control's own focus affordance.
+        The @scope block's containment IS the signal — no data
+        attribute or explicit opt-in needed; selectors targeting
+        inner elements only apply when they're inside this host. */
+     textarea-ui [slot="text"]:focus {
+       box-shadow: none;
+     }
+   }
+   ```
+
+   Tokens follow the L3 pattern from rule 12:
+
+   ```css
+   --my-composite-focus-ring:         var(--a-focus-ring);
+   --my-composite-focus-ring-invalid: var(--a-focus-ring-invalid);
+   ```
+
+   **When to use this (not field-ui):**
+   - **field-ui** is a _wrapper composite_ — it adds chrome (label / hint / error / required) around a control, but the control is still the primary focus target. Control owns the ring.
+   - **chat-input-ui** (and future equivalents) are _shell composites_ — the composite IS the control; the inner textarea is an implementation detail. Host owns the ring.
+
+   A user's mental model is the discriminator: do they think of the composite as a single control, or as a labeled/wrapped version of an inner control? The former is a shell; the latter is a wrapper.
+
+## Step 4 — Run the 30-second self-check
+
+Before declaring the work done, run through this checklist. If anything fails, fix before committing.
+
+### Attributes
+
+- [ ] No Boolean prop has `default: true`.
+- [ ] No numeric prop uses `-1` or other sentinels (indeterminate = `null`).
+- [ ] Every `static properties` entry uses `attribute:` (not `attr:`).
+- [ ] Every state-bearing Boolean has `reflect: true`.
+- [ ] No reserved-name anti-patterns (`title`, parent-level `active`, `error` variant, `disabled` on non-form, exclusion-`multiple`).
+- [ ] Element tag ends in `-ui`; class is `Adia<Component>`.
+
+### CSS
+
+- [ ] File opens with `@scope (component-ui) {` and has both `:where(:scope)` (tokens) and `:scope` (base styles) blocks.
+- [ ] Variants in the file contain ONLY `--component-*: var(...)` lines.
+- [ ] Zero `#hex` / `rgb()` / `rgba()` / `oklch()` in the file.
+- [ ] Zero raw `px` values ≥ 3 (or each has a one-line justification comment).
+- [ ] Component tokens prefixed with the scope's tag-stem.
+- [ ] Variant/state bodies alias from L3 (`--a-<family>-<role>-<state>`), not L2 (`--a-<family>`).
+
+### Lifecycle
+
+- [ ] Every `addEventListener` in `connected()` has a paired `removeEventListener` in `disconnected()`.
+- [ ] All handlers passed to `addEventListener` are stable `#field` arrows (or bound method refs), not inline arrows.
+- [ ] If the class extends `AdiaFormElement`, both `connected()` and `disconnected()` call `super`.
+- [ ] Every timer/observer created in `connected()` is disposed in `disconnected()`.
+- [ ] Cached DOM refs (`this.#fooEl`) are nulled in `disconnected()`.
+- [ ] Class declares `disconnected()` exactly once.
+
+## Step 5 — Run the project's verification gates
+
+Before committing, run the project's verify scripts. These catch the drift-shaped bugs the checklist can miss:
+
+```bash
+npm run verify:components   # component schema integrity (catalog)
+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.
+
+If a gate fails, fix before declaring done.
+
+## Cross-references
+
+- [primitive-audit.md](primitive-audit.md) — mode 1 §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)

package/skills/adia-ui-authoring/references/canonical-pattern-index.md

@@ -0,0 +1,179 @@
+# Canonical Pattern Index — survey targets for Mode 8 (composite-demo-protocol.md)
+
+**Auto-generated** by `scripts/build-canonical-pattern-index.mjs`. Do not edit by hand — re-run the build script after adding new canonicals to `apps/`, `catalog/`, or `playgrounds/`.
+
+This file is the checked-in snapshot the build script produces; the entries below are **representative** of a typical monorepo state (file lists + line counts will differ on your tree — re-run the build to refresh). The durable content is the **UI-type taxonomy** (the section headers + the lift-guidance under each): that taxonomy is the Phase 2 survey-target schema, and `ui_type` in Phase 1 must resolve to one of these section slugs.
+
+## 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
+
+> 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` (from SaaS app dashboards)
+- `apps/user-flow/app/registration/billing/billing.contents.html` (from User-flow templates)
+
+## dashboard
+
+> 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` (from SaaS app dashboards)
+
+## settings
+
+> Settings pages (preferences, security, appearance). Lift card-ui per setting group + col-ui spacing.
+
+- `apps/saas/app/settings-page/settings-page.contents.html` (from SaaS app dashboards)
+- `apps/user-flow/app/onboarding/notification-prefs/notification-prefs.contents.html` (from User-flow templates)
+- `catalog/ui-patterns/app/settings-appearance/settings-appearance.contents.html` (from UI-pattern atomics)
+- `catalog/ui-patterns/app/settings-notifications/settings-notifications.contents.html` (from UI-pattern atomics)
+- `catalog/page-shells/app/settings-page/settings-page.contents.html` (from Page-shell templates)
+
+## auth-flow
+
+> Authentication flows (sign-in, MFA, OAuth, password reset). Lift single-column form layout from sign-in.contents.html siblings.
+
+- `apps/user-flow/app/auth/forgot-password/forgot-password.contents.html` (from User-flow templates)
+- `apps/user-flow/app/auth/reset-password/reset-password.contents.html` (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/mfa/mfa.contents.html` (from User-flow templates)
+- `apps/user-flow/app/auth/sign-in/sign-in.contents.html` (from User-flow templates)
+- `apps/user-flow/app/auth/sign-up/mfa-setup/mfa-setup.contents.html` (from User-flow templates)
+
+## onboarding-wizard
+
+> Onboarding multi-step wizards. Lift step-progress + section + cta-row pattern.
+
+- `apps/user-flow/app/onboarding/first-action/first-action.contents.html` (from User-flow templates)
+- `apps/user-flow/app/onboarding/welcome/welcome.contents.html` (from User-flow templates)
+
+## registration-wizard
+
+> Registration multi-step flows. Lift wizard step + form composition.
+
+- `apps/saas/app/profile-security/profile-security.contents.html` (from SaaS app dashboards)
+- `apps/user-flow/app/auth/sign-up/profile/profile.contents.html` (from User-flow templates)
+- `catalog/ui-patterns/app/user-profile-card/user-profile-card.contents.html` (from UI-pattern atomics)
+
+## list-with-detail
+
+> List + detail compositions (entity rows + drawer/modal detail). Lift entity-item + drawer pattern.
+
+- `apps/saas/app/members/members.contents.html` (from SaaS app dashboards)
+- `catalog/ui-patterns/app/users-table-badge/users-table-badge.contents.html` (from UI-pattern atomics)
+
+## integrations-list
+
+> Searchable integration/connector grids. Lift grid-ui + card-ui + empty-state-inside-card pattern.
+
+- `apps/saas/app/integrations/integrations.contents.html` (from SaaS app dashboards)
+- `apps/user-flow/app/registration/integrations/integrations.contents.html` (from User-flow templates)
+
+## agent-activity
+
+> Agent activity / reasoning feeds. Lift activity-feed scroll + collapsed-reasoning pattern.
+
+- `catalog/ui-patterns/app/agent-activity-feed/agent-activity-feed.contents.html` (from UI-pattern atomics)
+- `catalog/ui-patterns/app/agent-reasoning-collapsed/agent-reasoning-collapsed.contents.html` (from UI-pattern atomics)
+- `catalog/page-shells/app/agent-canvas/agent-canvas.contents.html` (from Page-shell templates)
+
+## chat
+
+> Chat surfaces (thread, composer, sidebar). Lift chat-streaming-surface composition.
+
+- `apps/genui/app/factory-chat/factory-chat.contents.html` (from GenUI app routes)
+- `catalog/ui-patterns/app/chat-streaming-surface/chat-streaming-surface.contents.html` (from UI-pattern atomics)
+- `catalog/page-shells/app/chat-page/chat-page.contents.html` (from Page-shell templates)
+
+## editor
+
+> Editor panes (code, preview, toolbar). Lift editor-shell composition.
+
+- `apps/genui/app/a2ui-editor/a2ui-editor.contents.html` (from GenUI app routes)
+- `catalog/ui-patterns/app/editor-code-pane/editor-code-pane.contents.html` (from UI-pattern atomics)
+- `catalog/page-shells/app/editor-page/editor-page.contents.html` (from Page-shell templates)
+
+## kanban
+
+> Kanban / column-based boards. Lift kanban-board-3col pattern.
+
+- `catalog/ui-patterns/app/kanban-board-3col/kanban-board-3col.contents.html` (from UI-pattern atomics)
+- `catalog/page-shells/app/kanban-page/kanban-page.contents.html` (from Page-shell templates)
+
+## data-table
+
+> Data tables with badges/inline actions. Lift users-table-badge composition.
+
+- `apps/user-flow/app/onboarding/import-data/import-data.contents.html` (from User-flow templates)
+
+## command
+
+> Command palette / global search. Lift command-palette overlay pattern.
+
+- `catalog/ui-patterns/app/command-palette/command-palette.contents.html` (from UI-pattern atomics)
+
+## overlay
+
+> Modals, drawers, popovers. Lift destructive-confirm-modal pattern for confirmations.
+
+- `apps/user-flow/app/registration/confirmation/confirmation.contents.html` (from User-flow templates)
+- `catalog/ui-patterns/app/destructive-confirm-modal/destructive-confirm-modal.contents.html` (from UI-pattern atomics)
+
+## multi-step-funnel
+
+> Multi-step conversion funnels. Lift conversion-funnel-6step composition.
+
+- `catalog/ui-patterns/app/conversion-funnel-6step/conversion-funnel-6step.contents.html` (from UI-pattern atomics)
+
+## feed
+
+> Activity / event feeds. Lift activity-feed composition.
+
+- `apps/genui/app/gen-ui-feed/gen-ui-feed.contents.html` (from GenUI app routes)
+
+## marketing
+
+> Marketing pages, hero CTAs. Lift marketing-hero-cta composition.
+
+- `catalog/ui-patterns/app/marketing-hero-cta/marketing-hero-cta.contents.html` (from UI-pattern atomics)
+- `catalog/page-shells/app/marketing-page/marketing-page.contents.html` (from Page-shell templates)
+
+## error-page
+
+> Error states (404, 500, forbidden, expired). Lift centered single-card error pattern.
+
+- `apps/user-flow/app/auth/account-locked/account-locked.contents.html` (from User-flow templates)
+- `apps/user-flow/app/auth/session-expired/session-expired.contents.html` (from User-flow templates)
+- `catalog/page-shells/app/error-page/error-page.contents.html` (from Page-shell templates)
+
+## demo-playground
+
+> Internal demo + playground surfaces. Use these as reference for composition style; not always production-grade.
+
+- `apps/genui/app/a2ui/a2ui.contents.html` (from GenUI app routes)
+- `apps/genui/app/css-channel-demo/css-channel-demo.contents.html` (from GenUI app routes)
+
+## other
+
+> Misc canonicals. Inspect contents.html to determine UI type.
+
+- Any `.contents.html` whose slug fragment matches none of the heuristics above lands here. Inspect each to determine its UI type, or extend the `inferUiType()` regex (see Maintenance).
+
+---
+
+## Maintenance
+
+Re-build this index:
+
+```bash
+node scripts/build-canonical-pattern-index.mjs
+```
+
+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`.