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

package/skills/primitive-authoring/references/anti-patterns.md

@@ -15,7 +15,7 @@ Organized by axis.
 closable: { type: Boolean, default: true, reflect: true }
 ```
 
-**What went wrong:** the component did something by default, and the prop named the default behavior. Users couldn't opt out by just setting the attribute — they had to pass `closable="false"` which doesn't even work for Boolean attributes (presence = true; absent = false is the HTML model).
+**What went wrong:** the component did something by default, and the prop named the default behavior. Users couldn't opt out by just setting the attribute, they had to pass `closable="false"` which doesn't even work for Boolean attributes (presence = true; absent = false is the HTML model).
 
 **Fix:** flip the name. Default `true` behavior = name the prop for the opt-out.
 
@@ -28,7 +28,7 @@ closable: { type: Boolean, default: true, reflect: true }
 | `toggle-group-ui[multiple]` | `toggle-group-ui[single]` |
 | `swiper-ui[pause-on-hover]` | `swiper-ui[noPauseOnHover]` |
 
-**Recognition:** if you find yourself writing `default: true` in a `static properties` block, stop — the name is wrong.
+**Recognition:** if you find yourself writing `default: true` in a `static properties` block, stop: the name is wrong.
 
 ### AP-02 · Magic-value sentinel instead of `null`
 
@@ -50,11 +50,11 @@ value: { type: Number, default: null, reflect: true }
 ### AP-03 · `attr:` silent typo
 
 ```javascript
-// WRONG — silently ignored
+// WRONG, silently ignored
 allowHalf: { type: Boolean, default: false, reflect: true, attr: 'allow-half' }
 ```
 
-**What went wrong:** the mapper looks for `attribute:`, not `attr:`. The typo is silently dropped. The kebab-case HTML attribute _happens_ to auto- convert to `allow-half` so the bug hides — until someone renames `allowHalf` and the attribute never wires.
+**What went wrong:** the mapper looks for `attribute:`, not `attr:`. The typo is silently dropped. The kebab-case HTML attribute _happens_ to auto- convert to `allow-half` so the bug hides, until someone renames `allowHalf` and the attribute never wires.
 
 **Fix:** `attribute:` always.
 
@@ -83,7 +83,7 @@ allowHalf: { type: Boolean, default: false, reflect: true, attr: 'allow-half' }
 
 - Parent holds a current index → `step` (e.g. `timeline-ui[step="3"]`)
 - Parent holds a selection → `value` (e.g. `inspector-ui[value="item-42"]`)
-- Child Boolean state stays as `active` — that's fine.
+- Child Boolean state stays as `active`, that's fine.
 
 ### AP-06 · `error` as a variant
 
@@ -103,7 +103,7 @@ allowHalf: { type: Boolean, default: false, reflect: true, attr: 'allow-half' }
 
 **What went wrong:** `disabled` has specific form semantics (removed from tab order, blocks submission). On a non-form component, the implicit meaning is "read-only interaction."
 
-**Fix:** `readonly` — matches the actual intent.
+**Fix:** `readonly`, matches the actual intent.
 
 ### AP-08 · `multiple` with exclusion semantics
 
@@ -123,7 +123,7 @@ allowHalf: { type: Boolean, default: false, reflect: true, attr: 'allow-half' }
 ### AP-09 · Native `<input>` / `<select>` / `<textarea>` stamped inside a primitive
 
 ```javascript
-// WRONG — command.class.js before gh#1302 (a9d282461^); select.class.js's
+// WRONG, command.class.js before gh#1302 (a9d282461^); select.class.js's
 // searchable branch and drilldown.class.js carried the same shape
 this.innerHTML = `
   <header>
@@ -132,20 +132,20 @@ this.innerHTML = `
   </header>…`;
 ```
 
-**What went wrong:** AdiaUI interactive primitives own their affordance — the host IS the interactive surface: `contenteditable="plaintext-only"` (or a custom non-editable surface), form participation via `UIFormElement` + `ElementInternals`, explicit ARIA on the host, a JS keyboard model per the WAI-ARIA APG, and `--a-*`-token chrome (ADR-0025, 2026-05-11). A native form control under the hood leaks browser chrome the token contract cannot uniformly restyle, imports per-browser keyboard quirks, and splits the value contract. Three primitives stamped a raw `<input>` anyway with no recorded exception — a search field is exactly the case the rule exists for (ADR-0055, gh#1302).
+**What went wrong:** AdiaUI interactive primitives own their affordance: the host IS the interactive surface: `contenteditable="plaintext-only"` (or a custom non-editable surface), form participation via `UIFormElement` + `ElementInternals`, explicit ARIA on the host, a JS keyboard model per the WAI-ARIA APG, and `--a-*`-token chrome (ADR-0025, 2026-05-11). A native form control under the hood leaks browser chrome the token contract cannot uniformly restyle, imports per-browser keyboard quirks, and splits the value contract. Three primitives stamped a raw `<input>` anyway with no recorded exception, a search field is exactly the case the rule exists for (ADR-0055, gh#1302).
 
-**Fix:** compose an in-house surface already in the tree — pick per component:
+**Fix:** compose an in-house surface already in the tree, pick per component:
 
-- the `combobox-ui` shape — `contenteditable="plaintext-only"` + `role="combobox"` + list filtering (`combobox.class.js:22-23`); now used by `command-ui`'s palette field (`command.class.js:108`) and `select-ui`'s searchable trigger (`select.class.js:442`);
-- composition of `<input-ui>` — the `search-ui` precedent (`search.class.js:19,44`); now used by `drilldown-ui`'s filter field (`drilldown.class.js:184-201`).
+- the `combobox-ui` shape, `contenteditable="plaintext-only"` + `role="combobox"` + list filtering (`combobox.class.js:22-23`); now used by `command-ui`'s palette field (`command.class.js:108`) and `select-ui`'s searchable trigger (`select.class.js:442`);
+- composition of `<input-ui>`, the `search-ui` precedent (`search.class.js:19,44`); now used by `drilldown-ui`'s filter field (`drilldown.class.js:184-201`).
 
-Behavior parity is part of done: focus order, IME/paste, `inputmode`, and APG-combobox ARIA, verified by a browser probe on the surface — not by tests alone.
+Behavior parity is part of done: focus order, IME/paste, `inputmode`, and APG-combobox ARIA, verified by a browser probe on the surface, not by tests alone.
 
-**The exception list is singular and closed:** `<input-ui type="password">` wraps a native `<input type="password">` (`input.class.js:116,213`) because `-webkit-text-security: disc` masking only paints on a real input — a mechanical justification, not an aesthetic one. Nothing else qualifies by convenience; a new exception is its own ADR, not a comment in the class. **Out of scope:** disclosure widgets (`<details>/<summary>`, e.g. `agent-trace.js:170`'s row expand) — the rule covers surfaces that gather user input, participate in `<form>`, or carry a value; a `<details>` toggle does none of these. Widening the rule to all native interactive chrome would be a new decision with its own blast radius.
+**The exception list is singular and closed:** `<input-ui type="password">` wraps a native `<input type="password">` (`input.class.js:116,213`) because `-webkit-text-security: disc` masking only paints on a real input, a mechanical justification, not an aesthetic one. Nothing else qualifies by convenience; a new exception is its own ADR, not a comment in the class. **Out of scope:** disclosure widgets (`<details>/<summary>`, e.g. `agent-trace.js:170`'s row expand), the rule covers surfaces that gather user input, participate in `<form>`, or carry a value; a `<details>` toggle does none of these. Widening the rule to all native interactive chrome would be a new decision with its own blast radius.
 
-**Gate:** `npm run audit:stamped-native-buttons` (`scripts/dev/audit-stamped-native-buttons.mjs`; runs in PR CI via `.github/workflows/ci.yml`, NOT in the `npm run check` aggregate) scans `packages/web-components/components/**` + `packages/web-modules/**` `.js` for all four control classes ADR-0055 §Consequences named — `<button` / `createElement('button')` (gh#276, `SANCTIONED_BUTTON` map), `<input` (ADR-0055 / gh#1302, `SANCTIONED_INPUT`), and since gh#1495 `<select` (`SANCTIONED_SELECT`) and `<textarea` (`SANCTIONED_TEXTAREA`) — and fails any hit outside the matching map. The two stamps that widening surfaced are both dispositioned in the maps: `table.class.js` (`createElement('select')` — the numeric-filter operator picker, a value-gathering surface squarely inside the rule, PENDING the same gh#276 filter-popover migration blocker as this file's button/input entries) and `color-picker.class.js` (`createElement('textarea')` — DECIDED gh#1495, keep: an off-screen `execCommand('copy')` clipboard-transport shim, appended and removed within one call, is out of ADR-0025's scope by ADR-0055 §Decision 4's own test — it gathers no user input, joins no `<form>`, carries no user-facing value; the primary path is `navigator.clipboard.writeText` and the shim only runs where the Clipboard API is absent). Entries carry per-file reasons: password is the ADR-0025 exception; `type="file"` pickers (chat-input, upload) and the otp-input / table stamps are listed PENDING their own decision — sanctioned-with-reason is not the same as ratified. A sanctioned entry whose stamp disappears is reported stale so the list only shrinks, and the script's `selftest` proves each element class's positive + negative controls on scratch fixtures (also run in PR CI).
+**Gate:** `npm run audit:stamped-native-buttons` (`scripts/dev/audit-stamped-native-buttons.mjs`; runs in PR CI via `.github/workflows/ci.yml`, NOT in the `npm run check` aggregate) scans `packages/web-components/components/**` + `packages/web-modules/**` `.js` for all four control classes ADR-0055 §Consequences named, `<button` / `createElement('button')` (gh#276, `SANCTIONED_BUTTON` map), `<input` (ADR-0055 / gh#1302, `SANCTIONED_INPUT`), and since gh#1495 `<select` (`SANCTIONED_SELECT`) and `<textarea` (`SANCTIONED_TEXTAREA`), and fails any hit outside the matching map. The two stamps that widening surfaced are both dispositioned in the maps: `table.class.js` (`createElement('select')`, the numeric-filter operator picker, a value-gathering surface squarely inside the rule, PENDING the same gh#276 filter-popover migration blocker as this file's button/input entries) and `color-picker.class.js` (`createElement('textarea')`, DECIDED gh#1495, keep: an off-screen `execCommand('copy')` clipboard-transport shim, appended and removed within one call, is out of ADR-0025's scope by ADR-0055 §Decision 4's own test, it gathers no user input, joins no `<form>`, carries no user-facing value; the primary path is `navigator.clipboard.writeText` and the shim only runs where the Clipboard API is absent). Entries carry per-file reasons: password is the ADR-0025 exception; `type="file"` pickers (chat-input, upload) and the otp-input / table stamps are listed PENDING their own decision, sanctioned-with-reason is not the same as ratified. A sanctioned entry whose stamp disappears is reported stale so the list only shrinks, and the script's `selftest` proves each element class's positive + negative controls on scratch fixtures (also run in PR CI).
 
-Source: ADR-0025 (the rule) · ADR-0055 (conformance amendment, ratified 2026-08-15, gh#1302 — appends to ADR-0025's record; the ADR-0025 text itself is not edited).
+Source: ADR-0025 (the rule) · ADR-0055 (conformance amendment, ratified 2026-08-15, gh#1302, appends to ADR-0025's record; the ADR-0025 text itself is not edited).
 
 ---
 
@@ -154,14 +154,14 @@ Source: ADR-0025 (the rule) · ADR-0055 (conformance amendment, ratified 2026-08
 ### AP-T1 · Variant body consumes L2 directly
 
 ```css
-/* WRONG — button.css */
+/* WRONG, button.css */
 :scope[variant="danger"]:not([disabled]):hover {
   --button-fg: var(--a-danger);      /* L2 */
   --button-border: var(--a-danger);  /* L2 */
 }
 ```
 
-**What went wrong:** the variant bypassed the L3 state matrix. When a user enables high-contrast mode, the contrast-mode overrides on `--a-danger-fg-hover` don't reach this component — it's reading the flat L2 token instead of the stateful L3 one.
+**What went wrong:** the variant bypassed the L3 state matrix. When a user enables high-contrast mode, the contrast-mode overrides on `--a-danger-fg-hover` don't reach this component, it's reading the flat L2 token instead of the stateful L3 one.
 
 **Fix:** alias from the L3 matrix:
 
@@ -198,7 +198,7 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 ### AP-T3 · Raw px ≥ 3 without justification
 
 ```css
-/* WRONG — 12px is neither a stroke nor intrinsic */
+/* WRONG, 12px is neither a stroke nor intrinsic */
 :scope { padding: 12px; }
 ```
 
@@ -220,7 +220,7 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 ### AP-T4 · Component token name mismatches scope
 
 ```css
-/* WRONG — button.css */
+/* WRONG, button.css */
 @scope (button-ui) {
   :where(:scope) {
     --btn-bg: var(--a-primary-bg);  /* ← stem mismatch */
@@ -245,7 +245,7 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 ### AP-S1 · Variant body sets layout properties
 
 ```css
-/* WRONG — pagination.css (pre-fix) */
+/* WRONG, pagination.css (pre-fix) */
 :scope[variant="button"] [slot="nav"] button {
   width: var(--pagination-button-size);
   height: var(--pagination-button-size);
@@ -254,16 +254,16 @@ Or, if the component already defines state-aware tokens in `:where(:scope)`, reu
 }
 ```
 
-**What went wrong:** `variant="button"` changes the layout (square buttons with specific dimensions) — that's a mode, not a variant.
+**What went wrong:** `variant="button"` changes the layout (square buttons with specific dimensions), that's a mode, not a variant.
 
 **Fix:** add `pagination-ui[variant="button"]` to the Sanctioned Mode Attributes table in `.claude/docs/specs/component-token-contract.md`. Document the layout change as intentional.
 
-Alternative: refactor to make the attribute cosmetic — if possible.
+Alternative: refactor to make the attribute cosmetic, if possible.
 
 ### AP-S2 · Single-block `:scope` (tokens and styles interleaved)
 
 ```css
-/* WRONG — missing the :where(:scope) token block */
+/* WRONG, missing the :where(:scope) token block */
 @scope (button-ui) {
   :scope {
     --button-bg: var(--a-primary-bg);
@@ -280,7 +280,7 @@ Alternative: refactor to make the attribute cosmetic — if possible.
 ### AP-S3 · `::slotted()` in light-DOM component
 
 ```css
-/* WRONG — shadow DOM syntax */
+/* WRONG, shadow DOM syntax */
 ::slotted([slot="icon"]) { margin-inline-end: var(--gap); }
 ```
 
@@ -297,7 +297,7 @@ Ever. If you need it, specificity is wrong somewhere. Fix the layering.
 ### AP-S5 · Inline `grid-template-columns` for asymmetric splits
 
 ```html
-<!-- WRONG — escape hatch that bypasses the grid-ui vocabulary -->
+<!-- WRONG, escape hatch that bypasses the grid-ui vocabulary -->
 <grid-ui gap="4" style="grid-template-columns: 2fr 1fr">
   <card-ui>Chart</card-ui>
   <card-ui>Sidebar</card-ui>
@@ -309,61 +309,61 @@ Ever. If you need it, specificity is wrong somewhere. Fix the layering.
 **Fix:** use `grid-ui[columns="N"]` plus `[span="M"]` on the children. The component ships column variants 1-6, auto-fill, auto-fit, and a per-child `span="2|3|4|5|6|full"` attribute. Compose a 2:1 split as `columns="3"` + the wide child gets `span="2"`; compose a 3:2 split as `columns="5"` + `span="3"` + `span="2"`.
 
 ```html
-<!-- RIGHT — 2:1 via columns=3 and a span=2 child -->
+<!-- RIGHT, 2:1 via columns=3 and a span=2 child -->
 <grid-ui columns="3" gap="4">
   <card-ui span="2">Chart</card-ui>
   <card-ui>Sidebar</card-ui>
 </grid-ui>
 
-<!-- RIGHT — 3:2 via columns=5 and span=3 + span=2 -->
+<!-- RIGHT, 3:2 via columns=5 and span=3 + span=2 -->
 <grid-ui columns="5" gap="4">
   <card-ui span="3">Overview</card-ui>
   <card-ui span="2">Recent Sales</card-ui>
 </grid-ui>
 ```
 
-**Recognition:** `style="grid-template-columns: …"` anywhere in a page is a signal that either (a) the author doesn't know the `span` attribute exists, or (b) the ratio truly can't be expressed in columns 1-6. The second case is rare — most asymmetric splits approximate cleanly to `3:1`, `2:1`, `3:2`, or `4:1`. If the ratio genuinely can't be expressed, it probably should become a separate layout primitive with a named attribute rather than live as an inline style.
+**Recognition:** `style="grid-template-columns: …"` anywhere in a page is a signal that either (a) the author doesn't know the `span` attribute exists, or (b) the ratio truly can't be expressed in columns 1-6. The second case is rare, most asymmetric splits approximate cleanly to `3:1`, `2:1`, `3:2`, or `4:1`. If the ratio genuinely can't be expressed, it probably should become a separate layout primitive with a named attribute rather than live as an inline style.
 
-**Real fix:** admin-dashboard had `style="grid-template-columns: 7fr 5fr"` and `"2fr 1fr"`, analytics-dashboard had one `"2fr 1fr"`. Replaced with `columns="5" span="3"+"2"` and `columns="3" span="2"+default` respectively; the 7:5 ratio shifted to 3:2 (60:40 vs 58:42) — imperceptible visually, a win structurally.
+**Real fix:** admin-dashboard had `style="grid-template-columns: 7fr 5fr"` and `"2fr 1fr"`, analytics-dashboard had one `"2fr 1fr"`. Replaced with `columns="5" span="3"+"2"` and `columns="3" span="2"+default` respectively; the 7:5 ratio shifted to 3:2 (60:40 vs 58:42), imperceptible visually, a win structurally.
 
 ### AP-S6 · `:scope >` child combinator on a conditionally-rendered part
 
 ```css
-/* WRONG — [data-part="empty"] is rendered behind a `${isEmpty ? … : null}` branch */
+/* WRONG, [data-part="empty"] is rendered behind a `${isEmpty ? … : null}` branch */
 :scope > [data-part="empty"] { display: grid; place-items: center; }
 ```
 
-**What went wrong:** the template engine wraps every conditional render branch — `${cond ? … : null}` (also `?` / `.map()`) — in a `<span style="display:contents">`. That span is a real DOM child, so the conditionally-rendered element is a _grandchild_ of `:scope`, not a direct child. `display:contents` removes the span from layout but NOT from selector matching, so `:scope > [data-part="empty"]` matches nothing and the rule silently no-ops — no error, passes `components --verify`, looks fine in happy-dom. Only a live render shows the un-styled block.
+**What went wrong:** the template engine wraps every conditional render branch, `${cond ? … : null}` (also `?` / `.map()`), in a `<span style="display:contents">`. That span is a real DOM child, so the conditionally-rendered element is a _grandchild_ of `:scope`, not a direct child. `display:contents` removes the span from layout but NOT from selector matching, so `:scope > [data-part="empty"]` matches nothing and the rule silently no-ops, no error, passes `components --verify`, looks fine in happy-dom. Only a live render shows the un-styled block.
 
 **Fix:** use a **descendant** combinator for any conditionally-rendered part; keep `:scope >` only for parts that render unconditionally (those stay direct children).
 
 ```css
-/* RIGHT — descendant combinator survives the display:contents wrapper */
+/* RIGHT, descendant combinator survives the display:contents wrapper */
 :scope [data-part="empty"] { display: grid; place-items: center; }
-:scope > [data-part="header"] { … }   /* static part — child combinator OK */
+:scope > [data-part="header"] { … }   /* static part, child combinator OK */
 ```
 
-**Recognition:** a `[data-part]` rule that "doesn't apply" though the markup looks right, on a part rendered inside a `${cond ? … : null}` / `?` / `.map()` branch. Inspect the live DOM — a `<span style="display:contents">` wrapping the part confirms it. **Recurring class:** integrations-page empty-state, onboarding-checklist complete-CTA, and earlier sightings (bug-51, bug-53). Positive-guidance version: [css-patterns.md](css-patterns.md) §"Conditional-render parts defeat `:scope >`".
+**Recognition:** a `[data-part]` rule that "doesn't apply" though the markup looks right, on a part rendered inside a `${cond ? … : null}` / `?` / `.map()` branch. Inspect the live DOM, a `<span style="display:contents">` wrapping the part confirms it. **Recurring class:** integrations-page empty-state, onboarding-checklist complete-CTA, and earlier sightings (bug-51, bug-53). Positive-guidance version: [css-patterns.md](css-patterns.md) §"Conditional-render parts defeat `:scope >`".
 
 **Real fix:** integrations-page.css + onboarding-checklist.css had `:scope > [data-part]` on conditionally-rendered parts (empty-state / complete CTA); the layout grid and the separating margin silently dropped. Converted those rules to descendant combinators.
 
 ### AP-S7 · `align-self: stretch` to vertically center a fixed-height flex child
 
 ```css
-/* WRONG — stretch can't size a child that carries a definite height */
+/* WRONG, stretch can't size a child that carries a definite height */
 [slot="field"] > [slot="trailing"] { align-self: stretch; }   /* a 20px <kbd-ui> pins to the TOP */
 ```
 
-**What went wrong:** a flex item with `align-self: stretch` **and** a definite cross-axis size (`height` / `block-size`) does not stretch — the explicit size wins and the item positions at **flex-start** (top), not center. A `<kbd-ui>` (`height: 1.25rem`) in a 30px chrome sat ~4px high. `stretch` only sizes auto-height items; for a fixed-height child it silently degrades to top-alignment. A sibling `<button-ui>` looked fine only because it had no blocking height and genuinely filled the chrome (center vs. stretch identical for it).
+**What went wrong:** a flex item with `align-self: stretch` **and** a definite cross-axis size (`height` / `block-size`) does not stretch, the explicit size wins and the item positions at **flex-start** (top), not center. A `<kbd-ui>` (`height: 1.25rem`) in a 30px chrome sat ~4px high. `stretch` only sizes auto-height items; for a fixed-height child it silently degrades to top-alignment. A sibling `<button-ui>` looked fine only because it had no blocking height and genuinely filled the chrome (center vs. stretch identical for it).
 
 **Fix:** to vertically center a row of mixed-height affordances, use `align-self: center` and let each child keep its own token height.
 
 ```css
-/* RIGHT — center keeps each child's intrinsic height on the vertical center */
+/* RIGHT, center keeps each child's intrinsic height on the vertical center */
 [slot="field"] > [slot="trailing"] { align-self: center; }
 ```
 
-**Recognition:** a fixed-height inline affordance (kbd / icon / badge) hugging the top of a taller flex container while a full-height sibling looks correct — suspect `align-self: stretch` on a mixed-height row.
+**Recognition:** a fixed-height inline affordance (kbd / icon / badge) hugging the top of a taller flex container while a full-height sibling looks correct, suspect `align-self: stretch` on a mixed-height row.
 
 **Real fix:** input-ui's leading/trailing affordance slots used `align-self: stretch`; the ⌘K `<kbd-ui>` hint sat 4px high. `center` fixed it and let `<button-ui>` children honor their own `--button-height` token (bug-60).
 
@@ -374,13 +374,13 @@ Ever. If you need it, specificity is wrong somewhere. Fix the layering.
 ### AP-L1 · Inline arrow passed to `addEventListener`
 
 ```javascript
-// WRONG — cot.js (pre-fix)
+// WRONG, cot.js (pre-fix)
 this.#summaryEl.addEventListener('click', () => {
   this.collapsed = !this.collapsed;
 });
 ```
 
-**What went wrong:** `removeEventListener(type, anInlineArrow)` can't match — new function instance each time. The listener stays bound. If the component is re-attached, a SECOND listener binds too. Accumulates.
+**What went wrong:** `removeEventListener(type, anInlineArrow)` can't match, new function instance each time. The listener stays bound. If the component is re-attached, a SECOND listener binds too. Accumulates.
 
 **Fix:** stable `#field` arrow.
 
@@ -402,7 +402,7 @@ disconnected() {
 ### AP-L2 · Duplicate `disconnected()` method
 
 ```javascript
-// WRONG — chart.js (pre-fix)
+// WRONG, chart.js (pre-fix)
 class UIChart extends UIElement {
   connected() { /* ... */ this.#ro = new ResizeObserver(...); }
 
@@ -435,7 +435,7 @@ disconnected() {
 ### AP-L3 · Missing `super.connected()` / `super.disconnected()`
 
 ```javascript
-// WRONG — UIFormElement subclass missing super call
+// WRONG, UIFormElement subclass missing super call
 class UIInput extends UIFormElement {
   connected() {
     // super.connected() NOT called
@@ -444,7 +444,7 @@ class UIInput extends UIFormElement {
 }
 ```
 
-**What went wrong:** `ElementInternals` registration skipped. The component doesn't participate in forms — no value submission, no validation, no form-reset handling. Silent.
+**What went wrong:** `ElementInternals` registration skipped. The component doesn't participate in forms, no value submission, no validation, no form-reset handling. Silent.
 
 **Fix:** `super.connected()` first line of the method. `super.disconnected()` first line of its method too.
 
@@ -485,7 +485,7 @@ connected() {
   this.#ro.observe(this);
 }
 
-// Later — new options, recreated
+// Later, new options, recreated
 updateConfig(opts) {
   this.#ro = new ResizeObserver(...); // ← old one leaks
   this.#ro.observe(this);
@@ -505,7 +505,7 @@ updateConfig(opts) {
 ### AP-L7 · Empty template wipes authored light-DOM children
 
 ```javascript
-// WRONG — drawer.js (pre-fix)
+// WRONG, drawer.js (pre-fix)
 class UIDrawer extends UIElement {
   static template = () => html``;   // ← looks harmless. It isn't.
 
@@ -518,12 +518,12 @@ class UIDrawer extends UIElement {
 
 **What went wrong:** `UIElement`'s base `connectedCallback` runs an effect that calls `stamp(template(this), this)`. `stamp` calls `mount`, which calls `container.replaceChildren(fragment)`. Even an "empty" `html\`\``produces a non-null result, so`replaceChildren`runs and clears every authored child (header/section/footer) out of the host element. The component's own`render()` then tries to migrate children that no longer exist.
 
-Symptom: drawers render with a close button in an empty panel; all authored content is gone. Hard to debug because the children WERE in the DOM at `connected()` time — they get wiped milliseconds later when the effect runs.
+Symptom: drawers render with a close button in an empty panel; all authored content is gone. Hard to debug because the children WERE in the DOM at `connected()` time, they get wiped milliseconds later when the effect runs.
 
 **Fix:** drop the override entirely. The base class already defines `static template = () => null;`, and `stamp()` is skipped when the result is null:
 
 ```javascript
-// RIGHT — no template override
+// RIGHT, no template override
 class UIDrawer extends UIElement {
   // base UIElement.template returns null → stamp() is skipped →
   // authored light-DOM children survive through render().
@@ -533,17 +533,17 @@ class UIDrawer extends UIElement {
 }
 ```
 
-**Recognition:** light-DOM components that compose authored children (card-ui, drawer-ui, list-item-ui, menu-ui, anything with slots) must NOT declare any template — not even an empty one. If the component needs to stamp structural parts (dialog, panel, scrim), use `static parts = {...}` and `this.ensure('name')` instead; parts append once and don't wipe siblings.
+**Recognition:** light-DOM components that compose authored children (card-ui, drawer-ui, list-item-ui, menu-ui, anything with slots) must NOT declare any template, not even an empty one. If the component needs to stamp structural parts (dialog, panel, scrim), use `static parts = {...}` and `this.ensure('name')` instead; parts append once and don't wipe siblings.
 
 ### AP-L8 · `setAttribute('value', …)` on `input-ui` after first render
 
 ```javascript
-// WRONG — expected to update the visible text
+// WRONG, expected to update the visible text
 input.setAttribute('value', 'Liam Johnson');
 // …user still sees an empty field
 ```
 
-**What went wrong:** `input-ui.connected()` copies `this.value` to `#textEl.textContent` exactly once. `render()` does NOT re-sync when the `value` attribute changes externally — this is intentional, to prevent external re-renders from clobbering in-progress user input. But it means declarative value updates after mount have no visible effect.
+**What went wrong:** `input-ui.connected()` copies `this.value` to `#textEl.textContent` exactly once. `render()` does NOT re-sync when the `value` attribute changes externally: this is intentional, to prevent external re-renders from clobbering in-progress user input. But it means declarative value updates after mount have no visible effect.
 
 **Fix:** set the attribute AND mirror the text slot when you need to update the displayed value from outside:
 
@@ -555,12 +555,12 @@ if (textSlot) textSlot.textContent = 'Liam Johnson';
 
 **Real fix:** drawer-populating setup code (admin-dashboard transaction drawer, report drawer) hit this when filling input-ui fields from a clicked row. Worked around with an explicit text-slot mirror; a proper fix would be for `input-ui.render()` to re-sync `#textEl.textContent` when the `value` property changes while the field isn't focused.
 
-**Recognition:** if you're setting an `input-ui` / `textarea-ui` `value` from JavaScript and the field looks empty, you've hit this. `<stat-ui>` and `<select-ui>` do sync on attribute change — the gap is only in the contenteditable-backed text field.
+**Recognition:** if you're setting an `input-ui` / `textarea-ui` `value` from JavaScript and the field looks empty, you've hit this. `<stat-ui>` and `<select-ui>` do sync on attribute change: the gap is only in the contenteditable-backed text field.
 
 ### AP-L9 · Radio cards without a `role="radiogroup"` parent
 
 ```html
-<!-- WRONG — radios never cross-deselect -->
+<!-- WRONG, radios never cross-deselect -->
 <list-ui>
   <list-item-ui>
     <card-ui>
@@ -574,7 +574,7 @@ if (textSlot) textSlot.textContent = 'Liam Johnson';
 </list-ui>
 ```
 
-**What went wrong:** `radio-ui.#select` does a sibling lookup via `this.closest('fieldset, [role="radiogroup"]') || this.parentElement`. When each radio sits inside its own `<span slot="icon">`, the "parent" contains only that one radio — no siblings to deselect. Clicking one doesn't uncheck the others, and the initial `checked` state may or may not render visually depending on mount order.
+**What went wrong:** `radio-ui.#select` does a sibling lookup via `this.closest('fieldset, [role="radiogroup"]') || this.parentElement`. When each radio sits inside its own `<span slot="icon">`, the "parent" contains only that one radio, no siblings to deselect. Clicking one doesn't uncheck the others, and the initial `checked` state may or may not render visually depending on mount order.
 
 **Fix:** wrap the whole group in an element `role="radiogroup"`:
 
@@ -648,9 +648,8 @@ Source: ADR-0027.
 
 ### AP-R2 · Folding two visually-converging widgets into a shared module (ADR-0101)
 
-Two widgets can converge visually — same tab-strip chrome, same header
-band, same "looks like the same component" impression on the catalog page
-— while carrying fundamentally different content models underneath. That
+Two widgets can converge visually, same tab-strip chrome, same header
+band, same "looks like the same component" impression on the catalog page, while carrying fundamentally different content models underneath. That
 visual overlap alone is not sufficient reason to extract a shared module
 or fold one into the other.
 
@@ -660,7 +659,7 @@ imperatively and repeatedly after connect via `update()`/`setHTML()`) and
 shown two fixed ways) look like the same tabbed-view widget. They aren't:
 folding one into the other would force the static-capture component to
 grow a second, incompatible imperative-update mode it doesn't need for the
-job it already does correctly everywhere it's used — added surface, not
+job it already does correctly everywhere it's used, added surface, not
 removed surface. Extracting a shared tab-view module was evaluated and
 rejected for the same reason: no common substrate exists beneath the
 visual layer that both widgets could share without also merging their
@@ -670,18 +669,18 @@ different content models (`tabs-ui`'s synthesized strip vs. a hand-rolled
 **The resolution is a mirror, not a merge:** keep both components on their
 own contracts; restyle the trailing one to match the leading one's chrome
 via scoped CSS only (`@scope (inspector-ui)` overrides copying
-`preview-ui`'s header-tab anatomy, tokens, and typography) — no shared
+`preview-ui`'s header-tab anatomy, tokens, and typography), no shared
 component, no deprecation. The tradeoff this accepts: because the
 mirroring is duplicated CSS, not a shared module, a future visual change
 to the pattern's source component doesn't automatically propagate: check
 the mirrored block for parallel drift when you next touch the pattern
-that's being mirrored — the same "primitives that compose primitives
+that's being mirrored, the same "primitives that compose primitives
 don't auto-import" discipline ADR-0027 already requires (AP-R1, above),
 now applied to a duplicated CSS block instead of a duplicated import.
 
 Before extracting a shared module for two things that "look the same,"
 verify they'd actually share the extracted contract (props, update
-semantics, lifecycle) — not just its rendered chrome. If they wouldn't,
+semantics, lifecycle), not just its rendered chrome. If they wouldn't,
 mirror the chrome and keep both components separate.
 
 Source: ADR-0101.
@@ -694,33 +693,33 @@ One line each; every entry is a shipped bug or a CRITICAL gate. Same axes as abo
 
 ### API / silent-failure class
 
-- **Components silently accept ANY made-up attribute and no-op** (`text-ui muted`, `card-ui hover-elevate`, `description-list-ui variant="columns"`) — check the component's yaml for the real prop list before authoring any attribute.
-- **`empty-state-ui` takes `[heading]`, not `[title]`** — `title=` becomes the invisible native tooltip and the message never renders (the AP-04 collision in the wild).
-- **A hardcoded `open` on a `showModal` overlay (`modal-ui` / `drawer-ui`) bricks the whole page** — no console error; only a live click / `elementFromPoint` probe catches it.
-- **Set `select-ui.options = [...]` for dynamic options, never `appendChild(<option>)`** — the listbox popover is stamped around the INITIAL `<option>` children at connect; later-appended options land outside it as visible flow content.
-- **`<thead>/<tbody>/<tr>/<th>/<td>` are foster-parented OUT of the DOM inside any non-`<table>` ancestor, including custom elements** — gone before JS runs; never author them inside a custom element.
-- **The elements above still get foster-parented inside `table-ui` (no internal `<table>`, `table.class.js:18`) — but their TEXT survives, and `table-ui` never clears it**, so a raw `<thead>/<tbody>` mistake renders its own "No data" empty-state stacked on a garbled text dump instead of erroring (gh#921/#923/#924, 3 separate demo files — fix by rewriting to the real `col-def`/`data` contract, never by touching table-ui).
+- **Components silently accept ANY made-up attribute and no-op** (`text-ui muted`, `card-ui hover-elevate`, `description-list-ui variant="columns"`), check the component's yaml for the real prop list before authoring any attribute.
+- **`empty-state-ui` takes `[heading]`, not `[title]`**, `title=` becomes the invisible native tooltip and the message never renders (the AP-04 collision in the wild).
+- **A hardcoded `open` on a `showModal` overlay (`modal-ui` / `drawer-ui`) bricks the whole page**, no console error; only a live click / `elementFromPoint` probe catches it.
+- **Set `select-ui.options = [...]` for dynamic options, never `appendChild(<option>)`**: the listbox popover is stamped around the INITIAL `<option>` children at connect; later-appended options land outside it as visible flow content.
+- **`<thead>/<tbody>/<tr>/<th>/<td>` are foster-parented OUT of the DOM inside any non-`<table>` ancestor, including custom elements**, gone before JS runs; never author them inside a custom element.
+- **The elements above still get foster-parented inside `table-ui` (no internal `<table>`, `table.class.js:18`), but their TEXT survives, and `table-ui` never clears it**, so a raw `<thead>/<tbody>` mistake renders its own "No data" empty-state stacked on a garbled text dump instead of erroring (gh#921/#923/#924, 3 separate demo files, fix by rewriting to the real `col-def`/`data` contract, never by touching table-ui).
 
 ### UIElement / reactivity class
 
-- **Declaring `textContent` / `innerHTML` / `className` / `id` in `static properties` breaks the native accessor** — `installProps` swaps it for a signal, so `el.textContent = ''` becomes a signal write, not a child-wipe.
-- **`customElements.whenDefined(tag)` never rejects; an unimported tag never resolves** — a `Promise.all([...]).then(bootstrap)` gate hangs forever with no console error (chrome renders via tag-keyed CSS; the page is just "empty").
-- **A MutationObserver that watches its own host AND mutates it in the callback hangs** — drain with `this.#observer.takeRecords()` after every absorb pass.
-- **A document-listening trait must NOT re-emit the same-named event on its host with `bubbles: true`** — the bubble re-reaches document and re-fires the handler (infinite loop); use distinct incoming vs outgoing names.
-- **Parent `render()` that filters children by an attribute the child sets in its OWN `connected()` races the upgrade** — match by tag name too.
-- **Sync icon-registry checks (`isIconName` / `hasIcon`) at connect race the async manifest on static (non-Vite) deploys** — pair with `whenIconRegistryReady` deferred re-stamping.
+- **Declaring `textContent` / `innerHTML` / `className` / `id` in `static properties` breaks the native accessor**, `installProps` swaps it for a signal, so `el.textContent = ''` becomes a signal write, not a child-wipe.
+- **`customElements.whenDefined(tag)` never rejects; an unimported tag never resolves**, a `Promise.all([...]).then(bootstrap)` gate hangs forever with no console error (chrome renders via tag-keyed CSS; the page is just "empty").
+- **A MutationObserver that watches its own host AND mutates it in the callback hangs**, drain with `this.#observer.takeRecords()` after every absorb pass.
+- **A document-listening trait must NOT re-emit the same-named event on its host with `bubbles: true`**, the bubble re-reaches document and re-fires the handler (infinite loop); use distinct incoming vs outgoing names.
+- **Parent `render()` that filters children by an attribute the child sets in its OWN `connected()` races the upgrade**, match by tag name too.
+- **Sync icon-registry checks (`isIconName` / `hasIcon`) at connect race the async manifest on static (non-Vite) deploys**, pair with `whenIconRegistryReady` deferred re-stamping.
 
 ### Registration / packaging class
 
-- **Composites render internal `*-ui` tags the author never wrote** (`chat-input-ui` stamps `textarea-ui` + `select-ui`) — a consumer importing only the composite must also import those primitives (or the cluster barrel `packages/web-modules/<cluster>/index.js`) or they stay unregistered and collapse to 0px.
-- **A NEW yaml prop with `reflect: true` is not load-bearing alone** — the class's `static properties` block is hand-authored, not codegen'd from yaml; add both.
-- **Every `[slot="X"]` a component's CSS positions MUST be declared in the yaml `slots:` block** (including auto-stamped internal slots) — the slot-vocab-vs-CSS audit in `npm run check` fails CRITICAL otherwise.
-- **A new primitive's CSS must be registered in `packages/web-components/styles/components.css`** (the hand-maintained CSS aggregator) — separate from the `components/index.js` JS barrel; miss it and the element registers but renders unstyled.
+- **Composites render internal `*-ui` tags the author never wrote** (`chat-input-ui` stamps `textarea-ui` + `select-ui`), a consumer importing only the composite must also import those primitives (or the cluster barrel `packages/web-modules/<cluster>/index.js`) or they stay unregistered and collapse to 0px.
+- **A NEW yaml prop with `reflect: true` is not load-bearing alone**: the class's `static properties` block is hand-authored, not codegen'd from yaml; add both.
+- **Every `[slot="X"]` a component's CSS positions MUST be declared in the yaml `slots:` block** (including auto-stamped internal slots), the slot-vocab-vs-CSS audit in `npm run check` fails CRITICAL otherwise.
+- **A new primitive's CSS must be registered in `packages/web-components/styles/components.css`** (the hand-maintained CSS aggregator), separate from the `components/index.js` JS barrel; miss it and the element registers but renders unstyled.
 - **A primitive that programmatically creates a form-bearing primitive needs a `COMPOSITION_PAIR` entry in `scripts/release/check-composes-passthrough.mjs`** or the passthrough gate flags it.
 
 ## Meta-pattern: the "just this once" trap
 
-All of these bugs started as "just this once" exceptions — a component author thought "I'll fix it later," or "this component is special," or "the linter isn't catching it so it's fine." Each "just this once" became a template for the next author.
+All of these bugs started as "just this once" exceptions, a component author thought "I'll fix it later," or "this component is special," or "the linter isn't catching it so it's fine." Each "just this once" became a template for the next author.
 
 The audit found 100 findings in iteration 1. Fifteen were novel; eighty-five were different authors cargo-culting the same five shapes.