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

package/skills/primitive-authoring/references/module-promotion.md

@@ -1,8 +1,8 @@
 # Promote inline → module
 
-Use when you find the same UI block (markup + controller JS) authored in two or more consumers — typically the docs shell (`site/`) and a playground (`playgrounds/<name>/`) — and need to lift it into a single reusable element under `packages/web-modules/<cluster>/<name>/`.
+Use when you find the same UI block (markup + controller JS) authored in two or more consumers, typically the docs shell (`site/`) and a playground (`playgrounds/<name>/`), and need to lift it into a single reusable element under `packages/web-modules/<cluster>/<name>/`.
 
-This reference codifies the **5-phase arc** proven on `<theme-panel>`. Phases are independent commits — trivially revertible.
+This reference codifies the **5-phase arc** proven on `<theme-panel>`. Phases are independent commits, trivially revertible.
 
 > See [shell-patterns.md](shell-patterns.md) for the **different** activity of decomposing a single shell into a family of bespoke child elements per ADR-0023. This reference is for the _cross-cluster_ case where a single control surface (theme panel, command palette, future notification center, future user-menu) needs to live as one element used by many shells.
 
@@ -12,45 +12,45 @@ This reference codifies the **5-phase arc** proven on `<theme-panel>`. Phases ar
 
 - A consumer-authored inline block appears (with non-trivial drift) in 2+ surfaces, AND
 - The block has a stable, semi-public API surface (4–10 props at most), AND
-- The bug-surface from drift is real (e.g. behavior B is wrong relative to behavior A — playground "always shows 1,1" vs docs "reads computed").
+- The bug-surface from drift is real (e.g. behavior B is wrong relative to behavior A, playground "always shows 1,1" vs docs "reads computed").
 
 ## When NOT to use
 
-- The duplication is ≤ 10 lines and has zero behavior drift — leave it inline.
-- The element is genuinely shell-internal (admin-only, chat-only) — use [shell-patterns.md](shell-patterns.md) instead.
-- The block is a CSS-only template — promote to `catalog/ui-patterns/` not `packages/web-modules/`.
-- The block is a primitive (composes < 3 other primitives, no state) — promote to `packages/web-components/components/` instead.
+- The duplication is ≤ 10 lines and has zero behavior drift, leave it inline.
+- The element is genuinely shell-internal (admin-only, chat-only), use [shell-patterns.md](shell-patterns.md) instead.
+- The block is a CSS-only template, promote to `catalog/ui-patterns/` not `packages/web-modules/`.
+- The block is a primitive (composes < 3 other primitives, no state), promote to `packages/web-components/components/` instead.
 
 ## The 5-phase arc
 
 Each phase = one commit. Each independently revertible. Verification gate runs at the end of every phase before the commit.
 
-### Phase 1 — Author the element
+### Phase 1, Author the element
 
-1. `mkdir -p packages/web-modules/<cluster>/<name>` (new cluster, or under an existing one — see "Cluster placement" below).
+1. `mkdir -p packages/web-modules/<cluster>/<name>` (new cluster, or under an existing one, see "Cluster placement" below).
 2. Author **7 files** mirroring `web-modules/shell/admin-sidebar/`:
 
    ```text
-   <name>.yaml             # source of truth — schema + a2ui rules + keywords
+   <name>.yaml             # source of truth, schema + a2ui rules + keywords
    <name>.js               # UIElement subclass; light-DOM; imperative DOM stamping
    <name>.css              # two-block @scope pattern per component-token-contract.md
    <name>.html             # standalone demo (loads <name>.examples.html via fetch)
    <name>.examples.html    # the matrix consumed by the live demo
-   <name>.test.js          # vitest happy-dom — minimum 15 specs
-   <name>.a2ui.json        # GENERATED — never hand-edit
+   <name>.test.js          # vitest happy-dom, minimum 15 specs
+   <name>.a2ui.json        # GENERATED, never hand-edit
    ```
 
 3. Wire the **4 package.json + barrel touchpoints**:
-   - `packages/web-modules/<cluster>/index.js` — `export { Name } from './<name>/<name>.js';`
-   - `packages/web-modules/index.js` — add `export * from './<cluster>/index.js';`
-   - `packages/web-modules/package.json` `exports` — add `"./<cluster>": "./<cluster>/index.js"` + `"./<cluster>/*": "./<cluster>/*/*.js"`
-   - `packages/web-modules/package.json` `files` — add `"<cluster>/"`
-   - `packages/web-modules/package.json` `sideEffects` — add `"./<cluster>/**/*.js"`
-4. Regenerate catalog: `node scripts/build/components.mjs` — produces `<name>.a2ui.json` + updates the aggregate corpus catalog.
+   - `packages/web-modules/<cluster>/index.js`, `export { Name } from './<name>/<name>.js';`
+   - `packages/web-modules/index.js`, add `export * from './<cluster>/index.js';`
+   - `packages/web-modules/package.json` `exports`, add `"./<cluster>": "./<cluster>/index.js"` + `"./<cluster>/*": "./<cluster>/*/*.js"`
+   - `packages/web-modules/package.json` `files`, add `"<cluster>/"`
+   - `packages/web-modules/package.json` `sideEffects`, add `"./<cluster>/**/*.js"`
+4. Regenerate catalog: `node scripts/build/components.mjs`, produces `<name>.a2ui.json` + updates the aggregate corpus catalog.
 5. **Gate** before commit:
 
    ```bash
-   node scripts/build/components.mjs --verify     # "clean — N files up-to-date"
+   node scripts/build/components.mjs --verify     # "clean, N files up-to-date"
    npm run verify:traits                          # 100%
    npm run smoke:engines                          # green
    npm run smoke:register-engine                  # 11/11
@@ -58,9 +58,9 @@ Each phase = one commit. Each independently revertible. Verification gate runs a
    npx vitest run packages/web-modules/<cluster>/<name>/<name>.test.js
    ```
 
-### Phase 2 — Migrate primary consumer (typically `site/`)
+### Phase 2, Migrate primary consumer (typically `site/`)
 
-The "full-fat" consumer — the one with persistence, prefers-color-scheme listeners, etc. This is your reference behavior; replicate its full surface in the module.
+The "full-fat" consumer, the one with persistence, prefers-color-scheme listeners, etc. This is your reference behavior; replicate its full surface in the module.
 
 1. Replace inline markup with single-tag composition:
 
@@ -80,7 +80,7 @@ The "full-fat" consumer — the one with persistence, prefers-color-scheme liste
    # Expect zero hits.
    ```
 
-4. **LS-key migration shim** — if the module uses a different storage namespace than the legacy controller, ship a one-shot read-old / write-new / drop-old block at the top of the consumer's boot script. Tested recipe:
+4. **LS-key migration shim**, if the module uses a different storage namespace than the legacy controller, ship a one-shot read-old / write-new / drop-old block at the top of the consumer's boot script. Tested recipe:
 
    ```js
    // ── One-shot LS migration (YYYY-MM-DD) ──
@@ -108,20 +108,20 @@ The "full-fat" consumer — the one with persistence, prefers-color-scheme liste
 
 5. **Gate**: `node --check` the consumer JS, grep for stale `#`-ids, manual visual QA at `npm run dev` if the user agrees to a foreground dev session.
 
-### Phase 3 — Migrate secondary consumer (typically a playground)
+### Phase 3, Migrate secondary consumer (typically a playground)
 
 The "stripped" consumer. Same structural change minus persistence.
 
-1. Same markup substitution — **omit `[persist]`** so the playground stays ephemeral and doesn't leak state into the primary consumer on the same origin.
+1. Same markup substitution, **omit `[persist]`** so the playground stays ephemeral and doesn't leak state into the primary consumer on the same origin.
 2. Delete the controller blocks. Drop any `const html = document.documentElement;` that is now unused. Keep primitive imports needed by the module's stamped children (text-ui, divider-ui, slider-ui, field-ui, button-ui, etc.).
 3. Update the playground's `spec/SPEC.md` ASCII diagram to show the new tag.
 4. **Gate**: same as Phase 2.
 
-### Phase 4 — Migrate the chunk corpus
+### Phase 4, Migrate the chunk corpus
 
 The harvested training-corpus chunk (`packages/gen-ui/a2ui/corpus/chunks/<name>.json`) embeds the consumer's HTML as an escaped string. Update it so the LLM sees the new authoring shape.
 
-1. **Preferred** — re-run the harvester:
+1. **Preferred**, re-run the harvester:
 
    ```bash
    npm run harvest:chunks
@@ -129,7 +129,7 @@ The harvested training-corpus chunk (`packages/gen-ui/a2ui/corpus/chunks/<name>.
 
    Confirm `SOURCES` in `scripts/build/harvest-chunks.mjs` includes the consumer's directory (post-ADR-0026 it should include `site/pages`, `apps`, `playgrounds`, `catalog`).
 
-2. **Fallback** — if the harvester source list excludes your consumer, edit the chunk JSON directly via a Python regex script. The pattern that worked for theme-panel:
+2. **Fallback**, if the harvester source list excludes your consumer, edit the chunk JSON directly via a Python regex script. The pattern that worked for theme-panel:
 
    ```python
    pat = re.compile(
@@ -147,25 +147,25 @@ The harvested training-corpus chunk (`packages/gen-ui/a2ui/corpus/chunks/<name>.
    grep -l 'id="<old-id>"' packages/gen-ui/a2ui/corpus/chunks/*.json
    ```
 
-4. **Gotcha — hand-edit + later re-harvest** — if you used the fallback (step 2) AND a peer later adds your consumer's directory to harvester SOURCES, the next `harvest:chunks` run will overwrite your hand-edit with the live consumer HTML. Usually that's _good_ (the re-harvest captures the live state, including any post-edit consumer updates), but diff before assuming. Concrete example: theme-panel's `playground-app-shell.json` was hand-edited, then re-harvested after `playgrounds/` was added to SOURCES — the re-harvest captured the `<aside-ui>` → `<admin-sidebar>` bespoke conversion that the hand-edit missed.
+4. **Gotcha, hand-edit + later re-harvest**, if you used the fallback (step 2) AND a peer later adds your consumer's directory to harvester SOURCES, the next `harvest:chunks` run will overwrite your hand-edit with the live consumer HTML. Usually that's _good_ (the re-harvest captures the live state, including any post-edit consumer updates), but diff before assuming. Concrete example: theme-panel's `playground-app-shell.json` was hand-edited, then re-harvested after `playgrounds/` was added to SOURCES, the re-harvest captured the `<aside-ui>` → `<admin-sidebar>` bespoke conversion that the hand-edit missed.
 5. **Gate**:
 
    ```bash
-   npm run test:a2ui                              # 22 pass — chunk loads
+   npm run test:a2ui                              # 22 pass, chunk loads
    npm run smoke:chunks                           # tolerate pre-existing failures
    # Optional (real-LLM, ~$2 per full eval):
    npm run eval:diff -- --engine zettel           # cov ≥ 40, avg ≥ 85
    ```
 
-### Phase 5 — Release
+### Phase 5, Release
 
 Either ship as a standalone lockstep cut (per the sibling **package-release** skill), OR ride a bundled cut that the user is already coordinating. Either way:
 
-1. **CHANGELOGs** — `packages/web-modules/CHANGELOG.md` `[Unreleased]` (or the dated bump block if you're cutting now) + root `CHANGELOG.md`.
-2. **README** — `packages/web-modules/README.md`: cluster table row, Layout tree entry, Quick start `import` line.
-3. **Spec status** — `.claude/docs/specs/<name>-module.md` Status field flips `Draft — proposed` → `Active — shipped vN.M.P`, plus the phase-table tick.
-4. **Specs INDEX** — `.claude/docs/specs/INDEX.md` row status column.
-5. **PR description** — the arc's rationale, commit list, and verification table live in the PR description (history lives in git + PRs).
+1. **CHANGELOGs**, `packages/web-modules/CHANGELOG.md` `[Unreleased]` (or the dated bump block if you're cutting now) + root `CHANGELOG.md`.
+2. **README**, `packages/web-modules/README.md`: cluster table row, Layout tree entry, Quick start `import` line.
+3. **Spec status**, `.claude/docs/specs/<name>-module.md` Status field flips `Draft, proposed` → `Active, shipped vN.M.P`, plus the phase-table tick.
+4. **Specs INDEX**, `.claude/docs/specs/INDEX.md` row status column.
+5. **PR description**, the arc's rationale, commit list, and verification table live in the PR description (history lives in git + PRs).
 
 ## Cluster placement decision (OD-001)
 
@@ -173,16 +173,16 @@ Either ship as a standalone lockstep cut (per the sibling **package-release** sk
 | --- | --- |
 | **A. New cluster** | The element is its own product axis; ≥ 2 credible siblings are foreseeable (e.g. `theme/` cluster: theme-panel today, theme-toggle + theme-preview tomorrow). Cost: 4 single-line edits (cluster `index.js`, root barrel, 3 `package.json` entries). |
 | **B. Existing cluster** | The element fits a current family with no expansion plans. Pick the **most cross-cutting** cluster (`simple/`, `runtime/`) before a shell-specific one (`shell/`, `chat/`, `editor/`). |
-| **C. Inside a shell cluster** | Almost never — fails if the element is consumed by _other_ shells. Use only when the element is structurally shell-bound. |
+| **C. Inside a shell cluster** | Almost never, fails if the element is consumed by _other_ shells. Use only when the element is structurally shell-bound. |
 | **D. Promote to primitive** | Only if it composes < 3 other primitives. Most controls fail this test. |
 
-**ADR prose drift — don't trust an ADR's "Today's work" narrative for live paths.** ADR-0012 is the source for the primitives-vs-modules-vs-themes decision above, but its own "Today's work"/outcome-notes prose has drifted out from under its ratified Decision: that prose describes `packages/web-components/patterns/` as the shell/chat/editor/runtime source-clustering directory, but present-day `patterns/` holds 45+ usage-example dirs instead — source moved on to `packages/web-modules/{chat,editor,runtime,shell}/` per the later ADR-0015. The same drift claims `@adia-ai/web-themes` as a sibling workspace package; it never shipped that way — themes live under `packages/web-modules/theme/` as a subpath instead. An ADR's ratified **Decision** stays append-only-safe; its **"Today's work" / outcome-notes prose is not** — later reorganizations can strand it, and a reader following the literal directory claims today would git-mv into the wrong (docs-example) directory. Before executing a cluster-placement call cited from an ADR, verify the directory it names still matches the live tree (see "Path-rebase awareness" below) rather than trusting the ADR's narrative section verbatim.
+**ADR prose drift, don't trust an ADR's "Today's work" narrative for live paths.** ADR-0012 is the source for the primitives-vs-modules-vs-themes decision above, but its own "Today's work"/outcome-notes prose has drifted out from under its ratified Decision: that prose describes `packages/web-components/patterns/` as the shell/chat/editor/runtime source-clustering directory, but present-day `patterns/` holds 45+ usage-example dirs instead, source moved on to `packages/web-modules/{chat,editor,runtime,shell}/` per the later ADR-0015. The same drift claims `@adia-ai/web-themes` as a sibling workspace package; it never shipped that way, themes live under `packages/web-modules/theme/` as a subpath instead. An ADR's ratified **Decision** stays append-only-safe; its **"Today's work" / outcome-notes prose is not**, later reorganizations can strand it, and a reader following the literal directory claims today would git-mv into the wrong (docs-example) directory. Before executing a cluster-placement call cited from an ADR, verify the directory it names still matches the live tree (see "Path-rebase awareness" below) rather than trusting the ADR's narrative section verbatim.
 
-**A second, distinct ADR-0012 correction — the nav family's tier, and 4 retired element names (ADR-0087, partial supersession).** ADR-0012's "Today's work" cluster table and "What lives where today" table classified 6 nav elements (`<app-nav-ui>`, `<app-nav-group-ui>`, `<app-nav-item-ui>`, `<section-nav-ui>`, `<section-nav-group-ui>`, `<section-nav-item-ui>`) as modules-tier, living in `web-modules/shell/`. ADR-0015 corrected this same-day as "a misclassification ADR-0012 inherited from the patterns/ era": the nav family is primitives-tier, consolidated to 3 elements (`<nav-ui>`, `<nav-group-ui>`, `<nav-item-ui>`) in `web-components/components/`. Using ADR-0012's tables to classify a new nav-family element via the OD-001 decision table above would land it in modules-tier — wrong; nav elements are primitives per ADR-0015. ADR-0012's tables also named 4 element names since retired per ADR-0015's rename map: `<adia-chat-ui>` → `<chat-shell>`, `<adia-editor-ui>` → `<editor-shell>`, `<app-shell-ui>` → `<admin-shell>`, `<gen-ui>` → `<gen-root>`. ADR-0087 records this partial supersession formally (`supersedes: adr-0012`, scoped to these two tables only — the three-tier package model, the lateral-dependency rule, and the cluster boundaries all stand unchanged). Live authority: ADR-0015 itself, not ADR-0012's tables.
+**A second, distinct ADR-0012 correction, the nav family's tier, and 4 retired element names (ADR-0087, partial supersession).** ADR-0012's "Today's work" cluster table and "What lives where today" table classified 6 nav elements (`<app-nav-ui>`, `<app-nav-group-ui>`, `<app-nav-item-ui>`, `<section-nav-ui>`, `<section-nav-group-ui>`, `<section-nav-item-ui>`) as modules-tier, living in `web-modules/shell/`. ADR-0015 corrected this same-day as "a misclassification ADR-0012 inherited from the patterns/ era": the nav family is primitives-tier, consolidated to 3 elements (`<nav-ui>`, `<nav-group-ui>`, `<nav-item-ui>`) in `web-components/components/`. Using ADR-0012's tables to classify a new nav-family element via the OD-001 decision table above would land it in modules-tier, wrong; nav elements are primitives per ADR-0015. ADR-0012's tables also named 4 element names since retired per ADR-0015's rename map: `<adia-chat-ui>` → `<chat-shell>`, `<adia-editor-ui>` → `<editor-shell>`, `<app-shell-ui>` → `<admin-shell>`, `<gen-ui>` → `<gen-root>`. ADR-0087 records this partial supersession formally (`supersedes: adr-0012`, scoped to these two tables only, the three-tier package model, the lateral-dependency rule, and the cluster boundaries all stand unchanged). Live authority: ADR-0015 itself, not ADR-0012's tables.
 
 ## Two rules from observed bugs
 
-### OD-002 — Absorb the standalone-button-next-door
+### OD-002, Absorb the standalone-button-next-door
 
 When the original duplicated markup has a sibling button that conceptually belongs with the panel (e.g. `<button-ui #theme-toggle>` flipping `color-scheme` next to the `<popover-ui>` that contains the theme panel), **absorb it into the module behind a boolean attribute**, don't leave it next door. Two duplications collapse into zero.
 
@@ -195,7 +195,7 @@ Module shape:
 
 The sibling button retires from consumer markup. Programmatic alternative stays available via `.apply({scheme})`.
 
-### OD-003 — Read computed values back into controls
+### OD-003, Read computed values back into controls
 
 When the module owns sliders that mirror CSS custom-property values that a _theme_ (or other parent) sets, the user mental model is "the slider shows the current value, regardless of how it got there." So on theme-change:
 
@@ -211,15 +211,15 @@ requestAnimationFrame(() => {
 });
 ```
 
-The `requestAnimationFrame` matters — CSS application is async with attribute write; reading on the next frame guarantees the computed value reflects the new theme block.
+The `requestAnimationFrame` matters, CSS application is async with attribute write; reading on the next frame guarantees the computed value reflects the new theme block.
 
 The bug this fixes: a stripped-down playground variant that resets sliders to `1, 1` on theme click. Sliders then lie about the current value (`1.5` is the actual radius for `[theme="ocean"]`).
 
 ## Catalog-regeneration caution
 
-`node scripts/build/components.mjs` reads ALL yamls in `packages/web-components/components/` AND `packages/web-modules/`, so a regenerated aggregate corpus catalog absorbs any uncommitted yaml changes elsewhere in the tree. **Don't stage the aggregate catalog** if it would bundle unrelated in-flight work; the per-component `<name>.a2ui.json` sidecar inside `packages/web-modules/<cluster>/<name>/` is sufficient on its own — that's what the per-component verify gate compares against.
+`node scripts/build/components.mjs` reads ALL yamls in `packages/web-components/components/` AND `packages/web-modules/`, so a regenerated aggregate corpus catalog absorbs any uncommitted yaml changes elsewhere in the tree. **Don't stage the aggregate catalog** if it would bundle unrelated in-flight work; the per-component `<name>.a2ui.json` sidecar inside `packages/web-modules/<cluster>/<name>/` is sufficient on its own, that's what the per-component verify gate compares against.
 
-A later `harvest:chunks` run over your consumer's directory supersedes any Phase-4 hand-edit with the live consumer HTML — usually strictly better (it captures shape updates the hand-edit missed); diff before assuming.
+A later `harvest:chunks` run over your consumer's directory supersedes any Phase-4 hand-edit with the live consumer HTML, usually strictly better (it captures shape updates the hand-edit missed); diff before assuming.
 
 ## Path-rebase awareness
 
@@ -244,7 +244,7 @@ apps/playgrounds/catalog layout.
 
 ## Pitfalls
 
-1. **Skipping the `<name>.test.js` file.** Mandatory — peer references ([shell-patterns.md](shell-patterns.md)) demand a behavior test. Minimum coverage: stamp + connect, attribute reflection, primary user action, programmatic API, persistence on/off, disconnect cleanup. Target ≥ 15 specs; theme-panel ships 23.
+1. **Skipping the `<name>.test.js` file.** Mandatory, peer references ([shell-patterns.md](shell-patterns.md)) demand a behavior test. Minimum coverage: stamp + connect, attribute reflection, primary user action, programmatic API, persistence on/off, disconnect cleanup. Target ≥ 15 specs; theme-panel ships 23.
 2. **Forgetting one of the 4 `package.json` touchpoints.** Add to `exports` only, leave `files` out → `npm publish` ships a broken package (the directory isn't in the tarball). Add to `files` only, leave `sideEffects` out → bundlers tree-shake the `customElements.define()` call and the element silently never registers in production builds. All four are required.
 3. **`[persist]` on by default.** Embedded demos silently mutate the docs shell's stored preferences (same origin). Default to ephemeral; flip `[persist]` on per-consumer.
 4. **Editing the aggregate catalog by hand.** It's generated. Edit the `<name>.yaml` SoT and run `npm run build:components`.
@@ -266,10 +266,10 @@ apps/playgrounds/catalog layout.
 
 ## Cross-references
 
-- [shell-patterns.md](shell-patterns.md) — bespoke shell-tier decomposition (ADR-0023; the _different_ activity)
-- [authoring-cycle.md](authoring-cycle.md) — the standard 5-step authoring cycle
-- [api-contract.md](api-contract.md) — prop naming, reflection, the legacy forms
-- **package-release** (sibling skill) — lockstep release cycle (Phase 5)
-- **a2ui-maintenance** (sibling skill) — chunk corpus harvest + smoke gates (Phase 4)
-- Spec: `.claude/docs/specs/package-architecture.md` — three-tier package layout
-- ADR-0012 / ADR-0023 — decision labels: primitives-vs-modules-vs-themes and the bespoke shell pattern (history lives in git + PR descriptions)
+- [shell-patterns.md](shell-patterns.md), bespoke shell-tier decomposition (ADR-0023; the _different_ activity)
+- [authoring-cycle.md](authoring-cycle.md), the standard 5-step authoring cycle
+- [api-contract.md](api-contract.md), prop naming, reflection, the legacy forms
+- **package-release** (sibling skill), lockstep release cycle (Phase 5)
+- **a2ui-maintenance** (sibling skill), chunk corpus harvest + smoke gates (Phase 4)
+- Spec: `.claude/docs/specs/package-architecture.md`, three-tier package layout
+- ADR-0012 / ADR-0023, decision labels: primitives-vs-modules-vs-themes and the bespoke shell pattern (history lives in git + PR descriptions)

package/skills/primitive-authoring/references/primitive-audit.md

@@ -1,12 +1,12 @@
-# Primitive Audit — the §0 gate before any NEW primitive
+# Primitive Audit, the §0 gate before any NEW primitive
 
-**This is mandatory before _every_ new component or interactive surface in `packages/web-components/components/`.** Skipping it produces work that re-derives existing wiring, hits first-paint timing races (e.g. `input-ui[prefix]` falls back to literal text before the icon registry loads — `search-ui` was built precisely to hide that), creates asymmetry across the library, and burns user trust.
+**This is mandatory before _every_ new component or interactive surface in `packages/web-components/components/`.** Skipping it produces work that re-derives existing wiring, hits first-paint timing races (e.g. `input-ui[prefix]` falls back to literal text before the icon registry loads, `search-ui` was built precisely to hide that), creates asymmetry across the library, and burns user trust.
 
 The audit takes 30 seconds. Do it.
 
 ---
 
-## Step 0 — list the affordances
+## Step 0, list the affordances
 
 Take your spec / screenshot / user request and list each interactive affordance independently. For a "table header bar" like a table-toolbar, that's:
 
@@ -18,7 +18,7 @@ Take your spec / screenshot / user request and list each interactive affordance
 
 Each line is a separate audit target.
 
-## Step 1 — inventory the library
+## Step 1, inventory the library
 
 ```bash
 ls packages/web-components/components/
@@ -26,7 +26,7 @@ ls packages/web-components/components/
 
 Skim the names. Most affordances have a dedicated component already.
 
-## Step 2 — for each affordance, grep yamls
+## Step 2, for each affordance, grep yamls
 
 ```bash
 # Example: looking for an existing search-input primitive
@@ -41,9 +41,9 @@ grep -lE "menu|popover|dropdown" packages/web-components/components/*/*.yaml
 
 Read every match's yaml top section (description + props + slots + events). Five minutes of reading saves an hour of re-implementation.
 
-## Step 3 — known-primitive map
+## Step 3, known-primitive map
 
-Treat this as the default lookup table. **If your affordance maps to a row here, use that primitive — do not roll your own.**
+Treat this as the default lookup table. **If your affordance maps to a row here, use that primitive, do not roll your own.**
 
 | Affordance | Primitive (NOT your own from scratch) |
 | --- | --- |
@@ -60,7 +60,7 @@ Treat this as the default lookup table. **If your affordance maps to a row here,
 | Inline code / shortcut hint | `kbd-ui` (NOT raw `<code>` / `<kbd>`) |
 | Inline metric (label + value + change + trend) | `stat-ui` |
 | Block of code with syntax highlighting | `code-ui` |
-| Table data-cell formatting (badge, link, progress, date, etc.) | `cell-types.js` registry — register a new type, don't render in column.render |
+| Table data-cell formatting (badge, link, progress, date, etc.) | `cell-types.js` registry, register a new type, don't render in column.render |
 | Filter / sort / columns / search bar above a table | `table-toolbar-ui[for]` |
 | Tabs + panels | `tabs-ui` + `tab-ui` |
 | Modal / drawer / toast | `modal-ui` / `drawer-ui` / `toast-ui` |
@@ -68,13 +68,13 @@ Treat this as the default lookup table. **If your affordance maps to a row here,
 | Avatar / avatar group | `avatar-ui` / `avatar-group-ui` |
 | Color / calendar / OTP picker | `color-area-ui` / `calendar-picker-ui` / `otp-input-ui` |
 | Stepper / timeline / progress / progress-row | `stepper-ui` / `timeline-ui` / `progress-ui` / `progress-row-ui` |
-| Card with header / section / footer | `card-ui` (+ slot children) — don't roll a "panel" |
+| Card with header / section / footer | `card-ui` (+ slot children), don't roll a "panel" |
 | Description-list (key/value) | `description-list-ui` |
 | Tree / list / action-list | `tree-ui` / `list-ui` / `action-list-ui` |
 
 If your affordance isn't in this table, run Step 2 again with better grep keywords. Only after those return nothing should you consider authoring something new.
 
-## Step 4 — when authoring IS warranted
+## Step 4, when authoring IS warranted
 
 If an affordance genuinely has no primitive (e.g. you're building the _first_ version of a new pattern), follow `chart-legend-ui` as the canonical "companion-bound-by-`[for]`" template:
 
@@ -82,15 +82,15 @@ If an affordance genuinely has no primitive (e.g. you're building the _first_ ve
 - Resolve via `getRootNode().getElementById()`, fall back to first sibling of the right tag
 - Listen to peer events for state sync
 - Dispatch state changes back via `peer.<setter>` or `peer.<method>()`
-- NEVER duplicate state in the companion — peer remains source of truth
+- NEVER duplicate state in the companion, peer remains source of truth
 
-## Step 5 — tone & token audit (mode 5 of this skill)
+## Step 5, tone & token audit (mode 5 of this skill)
 
 After the primitive audit passes, run the token audit at [token-contract.md](token-contract.md) to confirm:
 
 - Two-block `@scope` pattern (tokens on `:where(:scope)`, styles on `:scope`)
 - Zero raw colors (`grep -E '#[0-9a-fA-F]|rgb\(|hsl\(|oklch\(' <component>.css`)
-- Match the canonical surface tokens of similar primitives — for any popover that visually competes with `select-ui [slot="listbox"]`, copy its surface tokens exactly: `--a-canvas-bright`, `--a-ui-border`, `--a-radius`, `--a-bg-hover`, `--a-fg-hover`, `--a-fg-subtle`. Don't pick `--a-canvas` for floating menus — it's the L2 mid-tone surface, identical luminance in both schemes.
+- Match the canonical surface tokens of similar primitives, for any popover that visually competes with `select-ui [slot="listbox"]`, copy its surface tokens exactly: `--a-canvas-bright`, `--a-ui-border`, `--a-radius`, `--a-bg-hover`, `--a-fg-hover`, `--a-fg-subtle`. Don't pick `--a-canvas` for floating menus, it's the L2 mid-tone surface, identical luminance in both schemes.
 
 ## Past failure (do not repeat)
 
@@ -98,7 +98,7 @@ A `table-toolbar-ui` initial implementation rolled its own from scratch:
 
 - Hand-stamped `<input-ui prefix="magnifying-glass">` for search → "magnifying-glass" rendered as **literal text** because the icon registry hadn't resolved at first paint. `search-ui` already wraps input-ui with the right prefix + suffix + debounced `search` event.
 - Hand-stamped `<label>` + `<span>` + `<input-ui>` for filter rows → `field-ui inline` is the canonical label+control pair, mints `id` + `[for]` automatically.
-- Wrote `<text-ui display>` (invalid bare attr — `display` is an enum value of `variant`, requires `<text-ui variant="display">`).
+- Wrote `<text-ui display>` (invalid bare attr, `display` is an enum value of `variant`, requires `<text-ui variant="display">`).
 - Wrote popover surface as `--a-canvas` (washed-out mid-gray) instead of reading `select-ui`'s listbox tokens (`--a-canvas-bright`).
 
 Caught only after user feedback. The audit takes 30 seconds. Do it.
@@ -117,5 +117,5 @@ Ask: "is there a higher-level primitive that wraps this?" 80% of the time yes. E
 
 ## Cross-references
 
-- [authoring-cycle.md](authoring-cycle.md) — the full 5-step authoring procedure (run AFTER this audit clears)
-- [anti-patterns.md](anti-patterns.md) — failure-mode catalogue (look up the rule a found primitive enforces)
+- [authoring-cycle.md](authoring-cycle.md), the full 5-step authoring procedure (run AFTER this audit clears)
+- [anti-patterns.md](anti-patterns.md), failure-mode catalogue (look up the rule a found primitive enforces)