@adia-ai/adia-ui-forge 0.8.62 → 0.8.63

package/skills/primitive-authoring/references/code-style.md

@@ -1,31 +1,31 @@
-# AdiaUI code style — best practices
+# AdiaUI code style, best practices
 
 ## First principles (SKILL.md's own summary, expanded)
 
 1. **Invariants are enforced by the next author, not the linter.** A component
    that violates the contract silently teaches the next agent the violation is
    acceptable. Write as if your component is the reference the next one is
-   patterned after — because it will be.
+   patterned after, because it will be.
 2. **Default behavior is the absent attribute.** `<component-ui>` with no
    attributes does the expected default thing; every Boolean prop defaults to
-   `false`. If the expected default is "on," the prop name is wrong — flip it
+   `false`. If the expected default is "on," the prop name is wrong, flip it
    (`closable` → `permanent`, `animate` → `static`).
 3. **Variants change tokens; modes change layout.** A variant body contains
-   only `--component-*: var(...)` lines — no `padding`, `display`, `position`,
+   only `--component-*: var(...)` lines, no `padding`, `display`, `position`,
    `width`, `height`, `gap`, `flex`, `grid`, `overflow`, `border-radius`.
    Layout-changing attributes are modes and require a Sanctioned Mode
    Attributes entry in the contract doc.
 4. **Symmetric lifecycle or it's a leak.** Every listener added in
    `connected()` is removed in `disconnected()`; every timer cleared, observer
    disconnected, cached ref nulled. Handlers are stable `#field` arrows so
-   `removeEventListener` can match — inline arrows bit three components in one
+   `removeEventListener` can match, inline arrows bit three components in one
    audit cycle.
 5. **Component tokens consume L3, not L2.** Alias from the role×state matrix
-   (`--a-primary-bg-hover`), never the family base (`--a-primary`) — bypassing
+   (`--a-primary-bg-hover`), never the family base (`--a-primary`), bypassing
    L3 strands the component outside theme / dark-mode / contrast cascades
    silently.
 
-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.
+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 (the `lookup_component` MCP tool, or the adia-factory plugin's composition skill), pick the existing primitive, wire through tokens.
 
@@ -47,7 +47,7 @@ Every interactive surface, form control, layout container, and content block shi
 <input type="email" />
 ```
 
-The catalog has 125 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.
+The catalog has 125 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.
 
 ### Tag naming across tiers (`-ui` or bare)
 
@@ -58,18 +58,17 @@ suffix and was renamed to `form-popover-ui` one release later):
 | Tier | Convention | Examples |
 | --- | --- | --- |
 | Primitives (`packages/web-components`) | **always `-ui`** | `button-ui`, `select-ui`, `nav-item-ui` |
-| Standalone feature composites (`packages/web-modules`) — drop-in anywhere, consumer-facing | **always `-ui`** | `confirm-dialog-ui`, `plan-picker-ui`, `date-range-selector-ui`, `form-popover-ui` |
-| Shell/bespoke-cluster children + runtime roots | **bare** — the cluster prefix is the namespace | `admin-topbar`, `chat-composer`, `editor-canvas`, `simple-shell`, `a2ui-root`, `gen-root` |
+| Standalone feature composites (`packages/web-modules`), drop-in anywhere, consumer-facing | **always `-ui`** | `confirm-dialog-ui`, `plan-picker-ui`, `date-range-selector-ui`, `form-popover-ui` |
+| Shell/bespoke-cluster children + runtime roots | **bare**: the cluster prefix is the namespace | `admin-topbar`, `chat-composer`, `editor-canvas`, `simple-shell`, `a2ui-root`, `gen-root` |
 
-`theme-panel` (bare, standalone) predates this rule and is grandfathered —
-do not copy it as precedent for a new standalone composite. The DIRECTORY
+`theme-panel` (bare, standalone) predates this rule and is grandfathered, do not copy it as precedent for a new standalone composite. The DIRECTORY
 name never carries the suffix in either tier (`plan-picker/` →
 `<plan-picker-ui>`), and the a2ui `component:` name is unaffected
 (`FormPopover`).
 
 ## Layout primitives
 
-Use `<col-ui>`, `<row-ui>`, `<grid-ui>`, `<stack-ui>` for layout — never a bare `<div>`. The primitives carry the project's spacing scale (`gap`, padding tokens) and respond to density / theme providers; a plain `<div>` strands content outside that system.
+Use `<col-ui>`, `<row-ui>`, `<grid-ui>`, `<stack-ui>` for layout, never a bare `<div>`. The primitives carry the project's spacing scale (`gap`, padding tokens) and respond to density / theme providers; a plain `<div>` strands content outside that system.
 
 Pick the primitive by the axis the content flows along:
 
@@ -85,14 +84,14 @@ Pick the primitive by the axis the content flows along:
   <input-ui label="Password" type="password"></input-ui>
 </col-ui>
 
-<!-- wrong — manual spacing fights the density provider -->
+<!-- wrong, manual spacing fights the density provider -->
 <div style="display: flex; flex-direction: column; gap: 8px;">
   <input-ui label="Email" type="email"></input-ui>
   <input-ui label="Password" type="password"></input-ui>
 </div>
 ```
 
-The validator (`check_anti_patterns` → `noBareDivs`) catches this on rendered HTML. If a `<section>` has multiple direct children, wrap them in one layout primitive — `cardContentModel` flags the alternative.
+The validator (`check_anti_patterns` → `noBareDivs`) catches this on rendered HTML. If a `<section>` has multiple direct children, wrap them in one layout primitive, `cardContentModel` flags the alternative.
 
 ### `@bp` responsive prop annotations
 
@@ -127,11 +126,11 @@ The card content model is mandatory for anything resembling a block. Header carr
 
 Headings live in `<header>`, never in `<section>`. Sections contain exactly one layout primitive. Multiple direct children in `<section>` fail `cardContentModel` validation.
 
-`<card-ui>` and `<drawer-ui>` body content must wrap in `<section>` — direct `<col-ui>` / `<row-ui>` / `<stack-ui>` / `<div>` / `<text-ui>` / `<h*>` bypass the canonical body slot, lose `--card-inset` margin, and corrupt gen-UI corpus. Use `<section bleed>` to preserve existing padding when needed. Gated by `npm run audit:card-structure` + `audit:drawer-structure`.
+`<card-ui>` and `<drawer-ui>` body content must wrap in `<section>`, direct `<col-ui>` / `<row-ui>` / `<stack-ui>` / `<div>` / `<text-ui>` / `<h*>` bypass the canonical body slot, lose `--card-inset` margin, and corrupt gen-UI corpus. Use `<section bleed>` to preserve existing padding when needed. Gated by `npm run audit:card-structure` + `audit:drawer-structure`.
 
 ## `<field-ui>` for form composition
 
-Wrap form controls in `<field-ui>`. Don't pass `[label]` as an attribute on new form controls — it's the legacy form, kept for back-compat but not extended.
+Wrap form controls in `<field-ui>`. Don't pass `[label]` as an attribute on new form controls, it's the legacy form, kept for back-compat but not extended.
 
 ```html
 <!-- right -->
@@ -143,9 +142,9 @@ Wrap form controls in `<field-ui>`. Don't pass `[label]` as an attribute on new
 <input-ui label="Email" type="email" required></input-ui>
 ```
 
-`<field-ui>` owns the real `<label for="…">` and binds to the slotted control's `id` for proper click-to-focus — a pattern the embedded attribute can't provide. It also carries `[slot="trailing"]` / `[slot="action"]` for composition (clear button, helper actions) and an `inline` mode for stacked vs single-row layout.
+`<field-ui>` owns the real `<label for="…">` and binds to the slotted control's `id` for proper click-to-focus, a pattern the embedded attribute can't provide. It also carries `[slot="trailing"]` / `[slot="action"]` for composition (clear button, helper actions) and an `inline` mode for stacked vs single-row layout.
 
-For a single `check-ui` (which is its own labeled affordance), just use `<check-ui name label>` directly — wrapping it in `<field-ui inline>` produces ghost rows.
+For a single `check-ui` (which is its own labeled affordance), just use `<check-ui name label>` directly, wrapping it in `<field-ui inline>` produces ghost rows.
 
 ## Generated UIs through `<a2ui-root>`
 
@@ -155,7 +154,7 @@ Static markup written by hand uses the components directly. UIs generated from i
 <a2ui-root data-stream-src="/api/genui-stream"></a2ui-root>
 ```
 
-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`.
+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 sibling **a2ui-maintenance** skill for the operator playbook.
 
@@ -190,41 +189,41 @@ Detailed pattern in [css-patterns.md](css-patterns.md).
 
 ## Tokens, never raw colors
 
-Every color comes through a token. Zero `#hex` / `rgb()` / `rgba()` / `oklch()` in component CSS — the only places raw colors live are `packages/web-components/styles/colors/semantics.css` and `packages/web-components/styles/tokens.css`.
+Every color comes through a token. Zero `#hex` / `rgb()` / `rgba()` / `oklch()` in component CSS: the only places raw colors live are `packages/web-components/styles/colors/semantics.css` and `packages/web-components/styles/tokens.css`.
 
 Component CSS aliases from L3 (the role × state matrix), not L2 (the family base). The L3 matrix is where state wiring lives; bypassing it strands the component outside the theme system and breaks dark mode / high-contrast modes silently.
 
 ```css
-/* right — L3 alias keeps the state cascade working */
+/* right, L3 alias keeps the state cascade working */
 :scope[variant="primary"]:hover {
   --button-bg: var(--a-primary-bg-hover);
   --button-fg: var(--a-primary-fg-hover);
 }
 
-/* wrong — L2 stops the cascade */
+/* wrong, L2 stops the cascade */
 :scope[variant="primary"]:hover {
   --button-bg: var(--a-primary);   /* loses theme + contrast wiring */
 }
 ```
 
-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.)
+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).
 
 ## Variants change tokens, modes change layout
 
-A **variant** is cosmetic — color, border, shadow depth. A **mode** restructures the box — direction, grid template, display type.
+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 `.claude/docs/specs/component-token-contract.md` `Modes` section.
 
 ```css
-/* right — variant overrides tokens only */
+/* right, variant overrides tokens only */
 :scope[variant="outlined"] {
   --button-bg:     transparent;
   --button-border: var(--a-border);
 }
 
-/* wrong — variant changes layout; this should be a mode */
+/* wrong, variant changes layout; this should be a mode */
 :scope[variant="outlined"] {
   padding: var(--a-space-3) var(--a-space-4);
   display: flex;
@@ -233,7 +232,7 @@ Variant bodies may only contain `--component-*: var(...)` lines. They must NEVER
 
 ## Boolean attributes default to `false`
 
-Every Boolean prop on a component must default to `false`. If the expected default behavior is "on," the prop name is wrong — flip it.
+Every Boolean prop on a component must default to `false`. If the expected default behavior is "on," the prop name is wrong, flip it.
 
 | Right (default off, opt in)       | Wrong (default on, opt out)    |
 | --------------------------------- | ------------------------------ |
@@ -242,24 +241,23 @@ Every Boolean prop on a component must default to `false`. If the expected defau
 | `<cursor-ui no-cursor>`           | `<cursor-ui cursor>`           |
 | `<carousel-ui no-pause-on-hover>` | `<carousel-ui pause-on-hover>` |
 
-Default behavior is the absent attribute. Attributes exist to opt OUT or carry a value — never to opt INTO the expected default.
+Default behavior is the absent attribute. Attributes exist to opt OUT or carry a value, never to opt INTO the expected default.
 
 State-bearing Booleans must `reflect: true` so CSS can match `:scope[disabled]`, `:scope[selected]`, etc. Without reflection, hover / active / selected styles break silently.
 
 [verified 2026-08-19] **The literal string `"false"` is not "presence = true"
 here.** ADR-0075 special-cases `parseAttr` for `Boolean`-typed props so the
-literal attribute string `"false"` parses to JS `false`, not `true` —
-deviating from strict HTML semantics on purpose, to match this repo's own
+literal attribute string `"false"` parses to JS `false`, not `true`, deviating from strict HTML semantics on purpose, to match this repo's own
 A2UI transpiler (which already special-cased it defensively) and the
 authoring intuition both human and generated markup default to. Writing
 `show-label="false"` on a `default: true` Boolean prop does what it looks
 like it does. (`default: true` is itself the rare, ratified exception to
-this section's "every Boolean defaults to `false`" rule — ADR-0063's
-stamped-attribute mechanism, gh#961 — not a license to skip the flip rule
+this section's "every Boolean defaults to `false`" rule, ADR-0063's
+stamped-attribute mechanism, gh#961, not a license to skip the flip rule
 above for a new prop.) See [api-contract.md](api-contract.md)'s field-rules
 section for the full rule and shipped blast radius (`core/element.js:93-94`).
 
-Native DOM accessors (`textContent`, `innerHTML`) get clobbered if declared in `static properties` — `installProps` overrides the native setter and `el.textContent = ''` becomes a signal write, not a child-wipe. Don't declare those names in `static properties`.
+Native DOM accessors (`textContent`, `innerHTML`) get clobbered if declared in `static properties`, `installProps` overrides the native setter and `el.textContent = ''` becomes a signal write, not a child-wipe. Don't declare those names in `static properties`.
 
 ## Symmetric lifecycle
 
@@ -280,15 +278,15 @@ class UIBadge extends UIElement {
 }
 ```
 
-Inline arrows passed to `addEventListener` look fine and leak quietly — `removeEventListener` no-ops because the new arrow has different identity. Three components in one audit cycle bit on this exact bug.
+Inline arrows passed to `addEventListener` look fine and leak quietly, `removeEventListener` no-ops because the new arrow has different identity. Three components in one audit cycle bit on this exact bug.
 
-If the class extends `UIFormElement`, `connected()` and `disconnected()` MUST call `super.*` — `ElementInternals` registration depends on it. And declare `disconnected()` exactly once per class; the second silently overrides the first.
+If the class extends `UIFormElement`, `connected()` and `disconnected()` MUST call `super.*`, `ElementInternals` registration depends on it. And declare `disconnected()` exactly once per class; the second silently overrides the first.
 
 Full lifecycle patterns in [lifecycle-patterns.md](lifecycle-patterns.md).
 
 ## Reactivity through signals + effects
 
-New runtime data flows use the project's `signal()` / `effect()` primitives — never parallel `CustomEvent`-only paths. The convention keeps reactivity coherent: a single read-write surface, observable by any number of consumers, integrated with the framework's effect graph.
+New runtime data flows use the project's `signal()` / `effect()` primitives, never parallel `CustomEvent`-only paths. The convention keeps reactivity coherent: a single read-write surface, observable by any number of consumers, integrated with the framework's effect graph.
 
 ```js
 import { signal, effect } from '@adia-ai/web-components/core/reactivity';
@@ -302,7 +300,7 @@ effect(() => {
 count.value = 1;  // effect re-runs
 ```
 
-`CustomEvent` is fine for one-shot lifecycle notifications (a button click, a form submit). It's wrong for ongoing state that other components want to read — that wants a signal.
+`CustomEvent` is fine for one-shot lifecycle notifications (a button click, a form submit). It's wrong for ongoing state that other components want to read, that wants a signal.
 
 Custom setter `untracked()` discipline: reactive-property reads inside `set options/data/columns/...` setters that read `this.value` (via installProps getter) subscribe the caller's effect. Next `el.value = X` re-triggers it → drain loop. Wrap setter body in `untracked()`.
 
@@ -316,7 +314,7 @@ Universal data ingestion across the library is the `data-stream-*` attribute tra
 <a2ui-root data-stream-src="/api/genui"></a2ui-root>
 ```
 
-The trait dedupes connections — two components pointing at the same URL share one transport — and propagates updates through the signal graph automatically.
+The trait dedupes connections, two components pointing at the same URL share one transport, and propagates updates through the signal graph automatically.
 
 ## Modern browser baseline
 
@@ -324,7 +322,7 @@ The project targets Chromium 125+, Safari 18.0+, Firefox 129+ (raised from 17.4
 
 Don't propose polyfilling native APIs already at the baseline. The runtime expects native `:has()`, `@scope`, `@property`, OKLCH, `light-dark()`, `popover`, `dialog.showModal()`, `ResizeObserver`, `color-mix()`. Authoring against an older implicit floor is the source of most "but it works in Chrome" surprises.
 
-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:
+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-primary-muted) 40%, transparent);
@@ -354,7 +352,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 consumer-side migration, use `app-migration` (adia-factory plugin) — it reads the MIGRATION GUIDE and runs the mechanical sweeps.
+For a wholesale consumer-side migration, use `app-migration` (adia-factory plugin), it reads the MIGRATION GUIDE and runs the mechanical sweeps.
 
 ## Validate, always
 
@@ -366,17 +364,17 @@ 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 sibling **package-release** skill.
+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 **package-release** skill.
 
 ## Cross-references
 
-- [authoring-cycle.md](authoring-cycle.md) — the full 5-step authoring procedure
-- [api-contract.md](api-contract.md) — prop naming, type choices, reflection policy
-- [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
-- [module-promotion.md](module-promotion.md) — promote inline → module
-- [anti-patterns.md](anti-patterns.md) — failure-mode catalogue with file:line refs
-- **a2ui-maintenance** (sibling skill) — generator / corpus / MCP pipeline
-- **demo-audit** (sibling skill) — cross-surface visual / static QA
-- the **adia-factory** plugin — composition playbook for consumers building apps on the framework
+- [authoring-cycle.md](authoring-cycle.md), the full 5-step authoring procedure
+- [api-contract.md](api-contract.md), prop naming, type choices, reflection policy
+- [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
+- [module-promotion.md](module-promotion.md), promote inline → module
+- [anti-patterns.md](anti-patterns.md), failure-mode catalogue with file:line refs
+- **a2ui-maintenance** (sibling skill), generator / corpus / MCP pipeline
+- **demo-audit** (sibling skill), cross-surface visual / static QA
+- the **adia-factory** plugin, composition playbook for consumers building apps on the framework

package/skills/primitive-authoring/references/common-gotchas.md

@@ -1,4 +1,4 @@
-# Common gotchas — authoring traps
+# Common gotchas, authoring traps
 
 Seven concrete failure modes: five from a billing-overview rebuild + multi-demo grandfather-elimination cycle (CSS/composition-layering traps, §§1–5, composite authoring specifically), 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), plus one from minting `anchor-bar-ui` (generated-artifact regeneration ordering, §7, any change that mints/renames a component and touches a demo using it in the same pass). Each is the kind of bug that:
 
@@ -20,7 +20,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 
 ---
 
-## 1. Component used without reading its CSS — and especially without reading its composition grammar
+## 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).
 
@@ -39,7 +39,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 **Example**: 4 billing composites all had:
 
 ```css
-/* WRONG — clobbers empty-state-ui's flex column */
+/* WRONG, clobbers empty-state-ui's flex column */
 :scope > [data-empty] { display: none; }
 :scope[empty] > [data-empty] { display: block; }
 ```
@@ -48,10 +48,10 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 
 **Detector**: None today. Caught by user visual review.
 
-**Fix** — invert visibility toggle so no display value is set when shown:
+**Fix**, invert visibility toggle so no display value is set when shown:
 
 ```css
-/* RIGHT — child's :scope display remains intact */
+/* RIGHT, child's :scope display remains intact */
 :scope:not([empty]) > [data-empty] { display: none; }
 ```
 
@@ -59,7 +59,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 
 ## 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.
+**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.
 
@@ -74,7 +74,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 
 ## 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.
+**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.
 
@@ -86,27 +86,27 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 
 ## 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.
+**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.
+**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
+## 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.
+**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").
+**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.
+**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.
+**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):
+**Illustrative** (simplified from the real fix, see `provider.js:230,245,250,286` for the actual code):
 
 ```javascript
 async #loadContent(route) {
@@ -119,21 +119,21 @@ async #loadContent(route) {
 }
 ```
 
-**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.
+**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.
 
 ---
 
-## 7. Minting a wrapper-shaped component before its registry.js entry lands — the transpiler silently deletes the node, not just mis-types it
+## 7. Minting a wrapper-shaped component before its registry.js entry lands, the transpiler silently deletes the node, not just mis-types it
 
-**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Transpile a demo using a component minted in the SAME change, before its `registry.js` line lands (e.g. the chunk harvester, `node scripts/build/harvest-chunks.mjs`, or any other engine-transpiler consumer), and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh` reports clean.
+**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map, inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved, `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either, `reverseRegistry` is a one-time init snapshot, not live. Transpile a demo using a component minted in the SAME change, before its `registry.js` line lands (e.g. the chunk harvester, `node scripts/build/harvest-chunks.mjs`, or any other engine-transpiler consumer), and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183), same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after, "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all, not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh` reports clean.
 
-**Example (historical — the illustrating consumer has since retired):** minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row (site-a2ui itself retired 2026-08-31, ADR-0072 Decision 2 / gh#2410 — the underlying registry-gating hazard below is unchanged, only that particular consumer is gone) before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): the converted artifact contained zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. The site-a2ui freshness gate of the day reported clean regardless, for the exact reason the Detector below still explains.
+**Example (historical, the illustrating consumer has since retired):** minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row (site-a2ui itself retired 2026-08-31, ADR-0072 Decision 2 / gh#2410, the underlying registry-gating hazard below is unchanged, only that particular consumer is gone) before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): the converted artifact contained zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere, not retyped-and-visible, genuinely absent, while its single child (the toolbar content) survived, reparented one level up. The site-a2ui freshness gate of the day reported clean regardless, for the exact reason the Detector below still explains.
 
-**Detector**: none generic — a same-source freshness check can't catch this (the artifact IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual consuming surface and confirming the new tag's node count is nonzero, or re-running the transpile after `registry.js` is updated and diffing the output for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here — it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
+**Detector**: none generic, a same-source freshness check can't catch this (the artifact IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual consuming surface and confirming the new tag's node count is nonzero, or re-running the transpile after `registry.js` is updated and diffing the output for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here, it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
 
-**Fix**: the `registry.js` entry is what gates resolution — land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before transpiling anything that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run the transpile on the merged tree and confirm the tag actually appears in the output — never trust a freshness gate's green alone for a surface touching a component minted in the same change.
+**Fix**: the `registry.js` entry is what gates resolution, land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before transpiling anything that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run the transpile on the merged tree and confirm the tag actually appears in the output, never trust a freshness gate's green alone for a surface touching a component minted in the same change.
 
-**Generalizes to**: any hand-maintained resolution map (not build-generated) that a later regeneration step reads through — regenerating before the map is updated produces an internally-consistent-but-wrong artifact that passes a same-source freshness check; if the misresolved shape also happens to trip a downstream simplification/collapse rule, the failure escalates from "renders wrong" to "renders nothing," with no visual tell at all.
+**Generalizes to**: any hand-maintained resolution map (not build-generated) that a later regeneration step reads through, regenerating before the map is updated produces an internally-consistent-but-wrong artifact that passes a same-source freshness check; if the misresolved shape also happens to trip a downstream simplification/collapse rule, the failure escalates from "renders wrong" to "renders nothing," with no visual tell at all.
 
 ---
 
@@ -141,4 +141,4 @@ async #loadContent(route) {
 
 **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. #7 is a third axis (a hand-maintained resolution map read by a downstream regeneration step, not CSS or async ordering) — its own Detector/Fix above; no audit catches it, only a browser probe of the specific route touched.
+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. #7 is a third axis (a hand-maintained resolution map read by a downstream regeneration step, not CSS or async ordering), its own Detector/Fix above; no audit catches it, only a browser probe of the specific route touched.