@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/references/common-gotchas-consumer.md

@@ -0,0 +1,522 @@
+---
+name: common-gotchas-consumer
+load-when: Before Phase 4 (Author) when composing AdiaUI primitives in a consumer app, OR when debugging visual defects in already-composed surfaces. Use as a checklist alongside `component-literacy.md`'s pre-flight gate.
+load-size-tokens: ~2,200
+required-for:
+  - Mode 1-4 composition that embeds composites with their own @scope CSS layouts
+  - Any surface containing toolbars / button clusters / form-control rows
+  - Any surface using container queries for responsive layout
+  - Debugging a "passes audit but looks broken" defect
+companion-skill: "adia-ui-authoring v1.8.2 (sister skill's `references/common-gotchas.md` — same patterns, substrate-side framing)"
+sister-postmortems:
+  - ".brain/postmortems/2026-05-24-component-css-illiteracy.md"
+  - ".brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md"
+---
+
+# Common gotchas — consumer composition traps
+
+Four concrete failure modes recurring across the 2026-05-24 billing-overview + 8-demo cohort. The kit's `component-literacy.md` gate forces CSS reads at selection time, but **reading is not recognizing**. These four patterns recur in consumer code even after literacy is established — they're the next layer of discipline.
+
+Each entry: pattern + how to detect + the right fix + sister-skill citation.
+
+This reference parallels `adia-ui-authoring`'s `references/common-gotchas.md` (5 gotchas; the 5th — nested HTML comments in design-plan blocks — is substrate-side authoring-specific and not relevant to consumer composition).
+
+---
+
+## §1 — Composite used without using its composition grammar
+
+**Pattern**: Consumer wraps multiple `<X-ui>` primitives in an embedded composite (e.g., card-ui, drawer-ui) and stamps arbitrary `<div>` children inside instead of using the composite's expected slot grammar. Composite's `@scope` rules ONLY activate when their canonical children are present. Direct `<div>` children fall through to `display: block` → no inset, no grid, no slot positioning.
+
+**Example** (consumer-side):
+
+```html
+<!-- WRONG — card-ui's grammar never activates -->
+<card-ui>
+  <div class="my-icon"><icon-ui name="user"></icon-ui></div>
+  <div class="my-text">Profile · Settings</div>
+  <div class="my-actions"><button-ui></button-ui></div>
+</card-ui>
+
+<!-- RIGHT — card-ui's header grammar activates -->
+<card-ui>
+  <header>
+    <span slot="icon"><icon-ui name="user"></icon-ui></span>
+    <span slot="heading">Profile · Settings</span>
+    <span slot="action"><button-ui></button-ui></span>
+  </header>
+</card-ui>
+```
+
+**How to detect**:
+- `npm run audit:card-structure --strict` in the consuming repo (substrate audit; runs against any HTML the consumer authors)
+- Visual: chrome looks "flat" — no inset between border and content, sibling divs touching the card edge
+
+**The right fix**: USE the composite's grammar. Pre-flight Component Literacy (`references/component-literacy.md`) is the upstream defense; this gotcha is what happens when literacy is skipped.
+
+**Sister postmortem**: `.brain/postmortems/2026-05-24-component-css-illiteracy.md`
+**Sister commit**: chat-ui `4e86400c9` (payment-method-list rewrite to canonical grammar)
+
+---
+
+## §2 — Parent CSS overriding child primitive's intrinsic display
+
+**Pattern**: Consumer writes a parent that toggles visibility of an embedded primitive via `display: none` ↔ `display: block`. The `display: block` override beats the primitive's own `:scope { display: flex }` from its own `@scope` (specificity 0,2,0 vs 0,1,0). Primitive's intrinsic layout silently collapses.
+
+**Example** (consumer-side):
+
+```css
+/* WRONG — clobbers <empty-state-ui>'s flex column layout */
+.my-list-wrapper > [data-empty] { display: none; }
+.my-list-wrapper[empty] > [data-empty] { display: block; }
+```
+
+When the `[empty]` state activates, the empty-state-ui's `display: flex; flex-direction: column; align-items: center` is overridden to `display: block`. Icon, heading, description flow inline as a mash:
+**`⊡ No itemsAdd one to get started.`**
+
+**Right fix** — invert the toggle so no display value is set when shown:
+
+```css
+/* RIGHT — child primitive's intrinsic display remains intact */
+.my-list-wrapper:not([empty]) > [data-empty] { display: none; }
+```
+
+**How to detect**:
+- Visual: empty-state / loading-state / error-state primitives that render inline-text instead of stacked
+- DevTools: inspect the affected primitive; look for `display: block` coming from a parent rule beating the `:scope { display: flex }` rule
+
+**Sister commit**: chat-ui `4223a4147` (4 billing composites fixed simultaneously — same pattern)
+
+---
+
+## §3 — Mixed sizes across form/control groups
+
+**Pattern**: Consumer composes a toolbar or button cluster mixing multiple form/control primitives. Each primitive has a different default height. `<button-ui>` defaults to `md`; `<input-ui>` defaults larger; `<search-ui>` (which wraps `<input-ui>`) doesn't forward size to its inner control. Same row, mismatched baselines.
+
+**Example** (consumer-side):
+
+```html
+<!-- WRONG — three different control heights side-by-side -->
+<row-ui>
+  <button-ui icon="filter" text="Filter"></button-ui>            <!-- 32px default -->
+  <search-ui placeholder="Find..."></search-ui>                  <!-- 36px (no size) -->
+  <tag-ui data-filter-chip text="Active"></tag-ui>               <!-- 24px sm -->
+</row-ui>
+
+<!-- RIGHT — all controls explicitly sized the same -->
+<row-ui>
+  <button-ui size="sm" icon="filter" text="Filter"></button-ui>
+  <search-ui placeholder="Find..."></search-ui>                  <!-- no size= prop; search-ui fills its row (height from the inner input) -->
+  <tag-ui size="sm" data-filter-chip text="Active"></tag-ui>
+</row-ui>
+```
+
+**How to detect**:
+- Visual: controls in a row don't share a baseline
+- Playwright probe: measure `getBoundingClientRect().height` of each control; mismatched → fix
+
+**Right fix**:
+- Set the SAME `size` attribute on every control in the group explicitly (don't rely on defaults — they diverge)
+- If a wrapper primitive doesn't forward `[size]` to its inner control, file a substrate FB ticket; do NOT work around it by reaching into the wrapper's internals
+
+**Sister commit**: chat-ui `1298fb064` (search-ui forwarding + toolbar size=sm consistency)
+
+---
+
+## §4 — `minmax(<min>, 1fr)` inside `repeat()` fighting container queries
+
+**Pattern**: Consumer writes a grid with `repeat(N, minmax(<min>, 1fr))` AND the container has `@container` queries collapsing column count at breakpoints. The minmax fights the breakpoints — narrow viewports hit the minmax floor and overflow BEFORE the breakpoint reduces N.
+
+**Example** (consumer-side):
+
+```css
+/* WRONG — minmax fights container queries */
+.my-kpi-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(16em, 1fr));
+}
+@container (max-width: 48em) {
+  .my-kpi-grid { grid-template-columns: 1fr; }   /* this fights the minmax floor */
+}
+
+/* RIGHT — clean equal share; breakpoints own responsive */
+.my-kpi-grid {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+}
+@container (max-width: 48em) { .my-kpi-grid { grid-template-columns: 1fr; } }
+```
+
+**How to detect**:
+- Visual: at narrow widths the grid overflows horizontally BEFORE the breakpoint collapses it
+- Code review: `repeat()` with `minmax()` AND `@container` queries in the same stylesheet = fighting
+
+**Right fix**: When using container queries for responsive collapse, use plain `repeat(N, 1fr)` columns. minmax is for grids WITHOUT container-query-driven N changes.
+
+**Sister commit**: chat-ui `94d497557` (dashboard-layout KPI grid)
+
+---
+
+## §5 — `<admin-page-header>` / `<admin-page-body>` without inner column-owner
+
+**Pattern**: Consumer drops content directly inside `<admin-page-header>` or `<admin-page-body>` (bare `<h1>`, bare `<card-ui>`, `<col-ui>`, `<grid-ui>`, etc.) without the required inner `<header>` / `<section>` element. The bespoke wrappers handle full-width chrome (sticky, border, background, scroll sizing); padding + max-width + section-gap all live on `admin-page-header > :is(header, header-ui)` and `admin-page-body > :is(section, section-ui)`. Skipping the inner element drops 40px of inset silently. Page renders, no errors, just looks "off."
+
+A second axis of the same trap: wrapping `<admin-page>`'s children in a routing `<div>` (`<admin-page><div id="view">...</div></admin-page>`) breaks the `admin-page > admin-page-header` direct-child selector entirely. `<admin-page-body>` falls back to `display: inline` (HTMLUnknownElement) — catastrophic, but still silent.
+
+**Example** (consumer-side):
+
+```html
+<!-- WRONG — bare h1 + bare card; loses padding/max-width on both axes -->
+<admin-page>
+  <admin-page-header>
+    <h1>Dashboard</h1>
+  </admin-page-header>
+  <admin-page-body>
+    <card-ui>…</card-ui>
+  </admin-page-body>
+</admin-page>
+
+<!-- RIGHT — inner column-owners present -->
+<admin-page>
+  <admin-page-header>
+    <header><h1>Dashboard</h1></header>
+  </admin-page-header>
+  <admin-page-body>
+    <section>
+      <card-ui>…</card-ui>
+    </section>
+  </admin-page-body>
+</admin-page>
+```
+
+**How to detect**:
+- `npm run audit:admin-page-structure --strict` in the consuming repo (substrate audit; flags any `<admin-page-{header,body}>` whose direct child isn't a canonical column-owner — `:is(header, header-ui, section, section-ui, iframe, editor-shell, pane-ui)`)
+- Visual: cards/grids/charts flush against the leading edge of the content area; no inset to viewport edge
+- DevTools: `getComputedStyle(adminPageBody).padding` returns `0px` (should be `var(--page-content-inset)` ≈ 40px)
+- DevTools: `getComputedStyle(adminPageHeader).position` returns `static` instead of `sticky` (root cause: a wrapping `<div>` broke the direct-child selector)
+
+**Right fix**: Always nest `<header>` inside `<admin-page-header>` and `<section>` inside `<admin-page-body>`. For routing/view-switching between multiple `<admin-page>` instances, use `<router-ui>` or sibling `<admin-page id="…" hidden>` — never wrap `<admin-page>`'s children in a `<div>`. See `patterns-shells.md` §Wrapper-vs-column rule + §Routing inside admin-shell.
+
+**Sister postmortem**: filed via FB-68 / FB-69 (claims-ui-v11, 2026-05-25)
+**Substrate audit gate**: none yet (forward work — see §What the substrate-side audit currently catches table below)
+
+---
+
+## §6 — Bare `[slot="icon"]` + `[slot="heading"]` brand chrome instead of `<admin-entity-item>`
+
+**Pattern**: Consumer authors `<admin-topbar slot="header">` brand chrome by composing `[slot="icon"]` + `[slot="heading"]` siblings (or wrapping them in `<a>`) instead of using the canonical `<admin-entity-item>` primitive. The bare-slot shape is structurally valid — both slots are documented in admin-topbar's CSS — but it misses the dedicated identity-row primitive (shipped `@adia-ai/web-modules@0.7.13`, FB-38) whose entire purpose is "shell-tier icon + label + badge identity row that collapses as one slottable unit and aligns with `<nav-item-ui>` icons."
+
+Two consequences:
+
+1. **8px horizontal misalignment with `<nav-item-ui>` icons.** Bare brand icon sits at `--page-sidebar-px` (4px); `<nav-item-ui>` icons in `<section-ui><nav-ui>` sit at 12px (`<section-ui>` 4px + `<nav-item-ui>` 8px). admin-entity-item's geometry mirrors `<select-ui>`'s trigger row → brand icon at 12px → 0px delta with nav.
+2. **No shared collapse boundary** in collapsible sidebars. Bare `[slot="icon"]` and `[slot="heading"]` rely on separate CSS cleanup rules; admin-entity-item collapses as one unit (icon survives, label + badge hide together).
+
+Per admin-entity-item's own a2ui rule: *"Do NOT re-implement it with a bare `<span>` or an ad-hoc flex `<div>` — those have no shared collapse boundary."* The kit skill agrees in v3.7.5+.
+
+**Example** (consumer-side):
+
+```html
+<!-- WRONG — bare slots, 8px misaligned with nav, no shared collapse boundary -->
+<admin-topbar slot="header">
+  <span slot="icon"><icon-ui name="lightning"></icon-ui></span>
+  <span slot="heading">Claims Portal</span>
+</admin-topbar>
+
+<!-- RIGHT — canonical identity-row primitive -->
+<admin-topbar slot="header">
+  <admin-entity-item slot="heading">
+    <icon-ui slot="icon" name="lightning"></icon-ui>
+    <span slot="label">Claims Portal</span>
+    <!-- Optional: <badge-ui slot="badge" text="Staging" size="sm" variant="warning"></badge-ui> -->
+  </admin-entity-item>
+</admin-topbar>
+```
+
+**How to detect**:
+- `npm run audit:brand-chrome --strict` in the consuming repo (substrate audit; flags any `<admin-topbar slot="header">` inside `<admin-sidebar slot="leading">` whose direct child carries `slot="icon"` or `slot="heading"` AND isn't `<admin-entity-item>`)
+- Visual: brand icon sits at the leading edge (4px); nav icons sit indented (12px). 8px gap reads as inconsistent padding.
+- DevTools probe: `document.querySelector('admin-topbar [slot="icon"]').getBoundingClientRect().left` returns `4` (should be `12` to match nav).
+- Code review: any `[slot="icon"]` + `[slot="heading"]` pair in `<admin-topbar slot="header">` of a `<admin-sidebar slot="leading">` should be `<admin-entity-item slot="heading">` with the icon/label as inner slots.
+
+**Right fix**: Wrap the icon + label (+ optional badge) in `<admin-entity-item slot="heading">`. Same primitive already used in the `<admin-statusbar slot="footer">` for user identity — consistent identity-row geometry top and bottom of the sidebar.
+
+**Sister ticket**: FB-71 (claims-ui-v11, 2026-05-25). The discovery gap: v3.7.4's §Brand chrome H3 canonized bare-slot Pattern A without pointing at `<admin-entity-item>`, which was buried in a footer-only comment block in `patterns-recipes.md`. Closed in v3.7.5.
+
+---
+
+## §7 — `<router-ui>` silently renders empty when the provider isn't registered
+
+**Pattern**: Consumer does `import '@adia-ai/web-components'` (the main barrel), drops `<router-ui></router-ui>` into the admin-shell scroll region, sets `router.routes = [...]` — and the route content area stays empty. No console error, no warning, no network activity. The shell chrome renders correctly; only the route content is missing.
+
+**Root cause** (pre-v0.6.40): `<router-ui>` lives at `core/provider.js`, not in the components index, and the main barrel did not side-effect-import it. `document.querySelector('router-ui')` returned `HTMLUnknownElement`, and the `routes` property assignment was a no-op on a plain DOM element. Symptomatic only when route content was expected — completely silent otherwise.
+
+**Fixed**: At `@adia-ai/web-components@0.7.13+` the main barrel now side-effect-imports `core/provider.js` alongside `core/icons-phosphor.js`. The cold-start path "just works" with the standard barrel import.
+
+**Remaining gotcha — subpath-import consumers**: Apps with bundle-size SLOs that skip the barrel (`import '@adia-ai/web-components/components/<x>'` per primitive) still need to register the provider explicitly:
+
+```ts
+// Bundle-size-conscious cold-start — barrel skipped
+import '@adia-ai/web-components/components/button';
+import '@adia-ai/web-components/components/table';
+// ...
+import '@adia-ai/web-components/core/provider';  // <-- router lives here
+```
+
+**How to detect**:
+- Browser DevTools: `document.querySelector('router-ui').constructor.name === 'HTMLUnknownElement'` (should be `UIRouter`)
+- Network panel: no request for the `content:` URLs after `router.routes = […]` assignment
+- The route content area stays at its initial empty state across navigation
+
+**Right fix**: Use the main barrel (default), OR add `import '@adia-ai/web-components/core/provider'` to your subpath-import cold-start.
+
+**Sister ticket**: FB-72 (claims-ui-v15, 2026-05-25). Closed in v3.7.8 — substrate barrel patched + skill callout added to `patterns-recipes.md` "Admin shell anatomy" Route setup.
+
+---
+
+## §8 — `<table-toolbar-ui>` double chrome from hand-rolled children
+
+**Pattern**: Consumer drops filter inputs (`<input-ui>`, `<select-ui>`) as **children** of `<table-toolbar-ui>`, expecting them to appear in the toolbar bar. They render — and so does the toolbar's auto-rendered Filter / Sort / Columns / Search row beneath them. Two competing chrome bands.
+
+**Root cause**: `<table-toolbar-ui>` is a **chrome-owning primitive**, not a chrome container. Its default rendering shows search + filter + sort + columns affordances; each is opt-out-able via a `noXxx` boolean attribute. Slotted children render as additional content **above** the auto-chrome, producing the double-band layout. (Reference: `table-toolbar.yaml` props lines 32-81 + a2ui rule "Do NOT also use `<card-ui>`'s `<header>` on the same card — that produces a doubled chrome row.")
+
+The mirror anti-pattern: replicating the same filter / search buttons in the parent `<card-ui>`'s `<header>` while `<table-toolbar-ui>` is also mounted. Same doubled-chrome class.
+
+**Example**:
+
+```html
+<!-- WRONG — double chrome from hand-rolled children -->
+<table-toolbar-ui for="orders">
+  <input-ui placeholder="Search…" icon="magnifying-glass"></input-ui>
+  <select-ui placeholder="Status"></select-ui>
+</table-toolbar-ui>
+
+<!-- WRONG — chrome duplication in card header -->
+<card-ui>
+  <header>
+    <h3 slot="heading">Orders</h3>
+    <span slot="action">
+      <button-ui icon="funnel" aria-label="Filter"></button-ui>           <!-- redundant -->
+      <button-ui icon="magnifying-glass" aria-label="Search"></button-ui> <!-- redundant -->
+    </span>
+  </header>
+  <section bleed>
+    <table-toolbar-ui for="orders"></table-toolbar-ui>
+    <table-ui id="orders"></table-ui>
+  </section>
+</card-ui>
+
+<!-- RIGHT — let the toolbar own its chrome; use slot="actions" for primary buttons -->
+<table-toolbar-ui for="orders" text="Recent orders">
+  <button-ui slot="actions" text="New" variant="primary" icon="plus"></button-ui>
+</table-toolbar-ui>
+```
+
+**How to detect**:
+- Visual: two adjacent rows of toolbar-shaped chrome above the table
+- DOM: `<table-toolbar-ui>` with any non-`[slot="actions"]` child element
+- Code review: presence of filter / search affordances in a card's `<header>` while `<table-toolbar-ui>` is also mounted on the same card
+
+**Right fix**: Drop hand-rolled toolbar children. Use the boolean opt-outs (`no-filter`, `no-sort`, `no-columns`, `no-search`) to suppress unwanted auto-chrome. Use `slot="actions"` for trailing primary buttons (Invite / Export / +New). Keep the toolbar as the sole chrome owner — no parallel chrome in card headers.
+
+**Sister ticket**: FB-72 Finding 2 (claims-ui-v15, 2026-05-25). Closed in v3.7.8 — canonical no-children shape added to `patterns-data.md` "Data Table".
+
+---
+
+## §9 — `<table-toolbar-ui>` + `<table-ui>` inside one `<section bleed>` makes toolbar controls touch card edge
+
+**Pattern**: Consumer wraps both `<table-toolbar-ui>` and `<table-ui>` in a single `<section bleed>` inside `<card-ui>`, because "the table needs bleed for edge-to-edge rows." The toolbar's Filter / Sort / Columns buttons + search input then sit flush against the card's leading edge — no inset, looks like a layout bug.
+
+**Root cause**: `bleed` is a per-`<section>` knob, not a per-`<card-ui>` knob. When two children share a single bleed section, both get edge-to-edge treatment. The toolbar's chrome wants normal card-inset; the table wants edge-to-edge. They need separate sections.
+
+Likewise, both inside one bare `<section>` (no bleed) puts card-padding on every table row — wasted horizontal real estate.
+
+**Example**:
+
+```html
+<!-- WRONG — toolbar buttons touch card edge -->
+<card-ui>
+  <header><h3 slot="heading">Orders</h3></header>
+  <section bleed>
+    <table-toolbar-ui for="orders"></table-toolbar-ui>
+    <table-ui id="orders" sortable></table-ui>
+  </section>
+</card-ui>
+
+<!-- WRONG — table rows waste horizontal space -->
+<card-ui>
+  <header><h3 slot="heading">Orders</h3></header>
+  <section>
+    <table-toolbar-ui for="orders"></table-toolbar-ui>
+    <table-ui id="orders" sortable></table-ui>
+  </section>
+</card-ui>
+
+<!-- RIGHT — two adjacent sections, per-element bleed -->
+<card-ui>
+  <header><h3 slot="heading">Orders</h3></header>
+  <section>
+    <table-toolbar-ui for="orders"></table-toolbar-ui>
+  </section>
+  <section bleed>
+    <table-ui id="orders" sortable></table-ui>
+  </section>
+</card-ui>
+
+<!-- ALSO RIGHT — yaml-canonical: toolbar OUTSIDE card -->
+<col-ui gap="3">
+  <table-toolbar-ui for="orders" text="Orders"></table-toolbar-ui>
+  <card-ui>
+    <section bleed>
+      <table-ui id="orders" sortable></table-ui>
+    </section>
+  </card-ui>
+</col-ui>
+```
+
+**How to detect**:
+- Visual: toolbar's leftmost control (filter button or search input) leftmost-pixel aligned to card's leading border, zero gap
+- DevTools probe: `getBoundingClientRect().left` for the first toolbar control = card's leading border position
+- DOM scan: `<card-ui> <section[bleed]> table-toolbar-ui ~ table-ui` (both siblings, bleed parent)
+
+**Right fix**: Either the two-section split (toolbar in normal `<section>`, table in `<section bleed>`) when keeping the toolbar inside the card, OR yaml-canonical: pair them as `<col-ui gap="3"><table-toolbar-ui></table-toolbar-ui><card-ui>...</card-ui></col-ui>` with the toolbar OUTSIDE the card. The yaml rule in `table-toolbar.yaml` a2ui.rules prefers the outside-card form.
+
+**Sister ticket**: FB-73 (claims-ui-v15, 2026-05-25). Closed in v3.7.8 — both patterns documented in `patterns-data.md` "Data Table".
+
+---
+
+## §10 — `<table-ui>` columns rendered as flat text — cell-types not engaged
+
+**Pattern**: Consumer pre-formats every value in the data layer (`amount: '$240.00'`, `status: 'Approved'`, `submitted: 'May 19, 2026'`, `tags: 'priority, paid'`) and uses bare `[{key, label}]` column descriptors. Result: status column is flat text (no badge / no color coding), amount column is left-aligned (no right-alignment for numeric columns), tags column is a comma-joined string with substring truncation (no chips).
+
+**Root cause**: `<table-ui>` ships **12 built-in cell types** (`text` / `number` / `currency` / `percent` / `date` / `datetime` / `boolean` / `badge` / `avatar` / `link` / `progress` / `actions`) + a `render(value, row, cell, meta)` escape hatch for custom rendering. Each cell type owns:
+
+- How to **format** the value (`Intl.NumberFormat` / `Intl.DateTimeFormat` / etc.)
+- How to **render** into the cell (text-only, or `<badge-ui>` / `<avatar-ui>` / `<progress-ui>` / etc.)
+- The default **alignment** (`text` → left, `number` / `currency` / `percent` → right, `boolean` / `actions` → center)
+- The default **sort comparator** (alphanumeric / numeric / datetime / basic)
+
+Pre-formatting in the data layer means the cell-type never engages — every column falls back to `type: 'text'`, left-aligned, alphanumeric sort, no rendering primitives. A consumer-set `align: 'end'` on the column descriptor has no effect without a matching `type:`.
+
+**Example**:
+
+```js
+// WRONG — pre-formatted strings, cell-types defeated
+table.columns = [
+  { key: 'status',    label: 'Status' },
+  { key: 'amount',    label: 'Amount', align: 'end' },  // no effect — text type ignores align:end
+  { key: 'submitted', label: 'Submitted' },
+];
+table.data = [{
+  status: 'Approved',                  // → flat text
+  amount: '$240.00',                   // → left-aligned text
+  submitted: 'May 19, 2026',           // → flat text
+}];
+
+// RIGHT — raw values + cell-types
+table.columns = [
+  { key: 'status',    label: 'Status',    type: 'badge',
+    meta: { variants: { approved: 'success', denied: 'danger' } } },
+  { key: 'amount',    label: 'Amount',    type: 'currency',
+    meta: { currency: 'USD' } },
+  { key: 'submitted', label: 'Submitted', type: 'date' },
+];
+table.data = [{
+  status: 'approved',                  // → <badge-ui variant="success">
+  amount: 240.00,                      // → "$240.00" right-aligned
+  submitted: '2026-05-19T22:34:03Z',   // → "May 19, 2026" via Intl.DateTimeFormat
+}];
+```
+
+For multi-element cells (tag chip rows, avatar stacks), use the
+`render(value, row, cell, meta)` escape hatch — write DOM directly into
+the cell via `cell.replaceChildren()` + `cell.appendChild(...)`.
+
+**How to detect**:
+- Visual: numeric columns aren't right-aligned; status columns are flat text with no color cues; date columns aren't formatted
+- DevTools: `document.querySelector('table-ui').columns[N].type === undefined` (should be one of the 12 registered types)
+- Code review: any data-layer string that contains `'$'` / `'%'` / a comma-joined chip list is a candidate for hoisting into a cell-type
+
+**Right fix**: Pass raw values (numbers, ISO dates, enum strings, arrays) in `table.data` and configure `type:` / `render:` on every column descriptor. See `patterns-data.md` §Data Table for the full 12-type catalog + render-constraints (cell-element-write, memoize-per-row, `sortable: false` for non-scalar cells, `format()` text-export fallback).
+
+**Sister ticket**: FB-74 (claims-ui-v15, 2026-05-25). Closed in v3.7.8 — `patterns-data.md` "Data Table" gained cell-types catalog table + worked example + custom-render section.
+
+---
+
+## §11 — Wrong attribute name on a primitive — silent no-op + layout-as-content
+
+**Pattern**: Consumer authors a primitive with an attribute that "feels right" (matches the visible label, mirrors a sibling primitive's API, follows generic HTML conventions) but isn't the name the primitive's yaml documents. The browser accepts any attribute; the primitive's installProps only binds the names it declared. The intended behavior silently no-ops — no console error, no visual cue at the call site. Cluster of seven that recur across consumer-authored composites and gen-UI outputs.
+
+**The seven**:
+
+| Wrong | Right | Why it fails | yaml citation |
+|---|---|---|---|
+| `<accordion-item-ui label="…">` | `<accordion-item-ui text="…">` | Header label is the `text` prop (matches `<button-ui>` / `<nav-item-ui>` family convention). `label=` is silently ignored; the row renders with no visible header text — first child becomes the de-facto label. | `accordion-item.yaml` props.text |
+| `<col-def field="amount" …>` | `<col-def key="amount" …>` | `<table-ui>` parser reads `el.getAttribute('key')` for the row-data accessor. `field=` is silently dropped; column renders as empty cells (header shows, rows blank). | `table.class.js:358-365` parseColDefs |
+| `<nav-group-ui text="Settings">…children…</nav-group-ui>` | `<nav-group-ui text="Settings" open>…children…</nav-group-ui>` | Default `open: false` collapses the group; only the chevron + label render. Group children stay hidden until a click toggles it. Sidebar nav typically wants groups expanded by default. | `nav-group.yaml` props.open default false |
+| `<chat-input-ui></chat-input-ui><button-ui icon="paper-plane-right" variant="primary">Send</button-ui>` | `<chat-input-ui></chat-input-ui>` (alone) | `<chat-input-ui>` stamps its OWN send button (`paper-plane-right`, `variant="primary"`). Adding a sibling Button produces two side-by-side send buttons. | `chat-input.yaml` description + a2ui.rules + anti_patterns[0] |
+| `<card-ui><header>Snippet</header><section><code-ui language="js">…</code-ui></section><footer><button-ui icon="copy">Copy</button-ui></footer></card-ui>` | `<card-ui><header><h3>Snippet</h3></header><section bleed><code-ui language="js">…</code-ui></section></card-ui>` | `<code-ui>` renders its own header chrome (language label + copy button) UNLESS `[bare]` is set. A wrapper card with explicit Copy footer duplicates that chrome. The copy button is built in. | `code.yaml` description + props.bare |
+| `<progress-row-ui label="Storage" value="0.42" meta="42 GB / 100 GB">` | `<progress-row-ui label="Storage" value="42" meta="42 GB / 100 GB">` | `value` is the 0–100 percent (not a 0.0–1.0 fraction). 0.42 renders as a 0.42% fill (essentially empty bar). Mirrors `<progress-ui>` `value` semantics — yaml documents "0-100; null = indeterminate". | `progress-row.yaml` props.value range |
+| `<integration-card-ui provider="slack" name="Slack"><button-ui slot="action" text="Connect"></button-ui></integration-card-ui>` | `<integration-card-ui provider="slack" name="Slack" status="available"></integration-card-ui>` | The action button is derived from `[status]` — `available → Connect (primary)`, `connected → Configure (outline)`, `error → Retry`, `pending → spinner`, `coming-soon → hidden`. Slotting a Button produces TWO buttons side-by-side. The `actions` slot is for an overflow `<menu-ui>` only (Reauthenticate / Disconnect entries). | `integration-card.yaml` props.status enum + a2ui.rules + anti_patterns |
+
+**How to detect**:
+- Visual: row / column / group / button renders empty, wrong-shaped, or duplicated relative to the spec
+- DOM: `document.querySelector('accordion-item-ui').text` is `undefined` instead of the intended string (silent prop-bind miss)
+- Component Literacy gate: every primitive's `embed_gotchas` field should capture these — when a primitive in your composition appears in the table above and you didn't read its yaml, you skipped the gate
+- Code review: any attribute that looks like it "should match the visible string" but isn't `text` / `key` / `label` is a candidate; verify against `<name>.yaml` props block
+
+**Right fix**: Read the primitive's `<name>.yaml` `props:` block before authoring. The seven above all stem from "the obvious attribute name isn't the one the primitive declared." `component-literacy.md`'s `default_render` + `slot_sizing_rules` + `exposed_tokens` fields are unfabricable precisely to catch this class — you can't fill them in without reading the file.
+
+**Sister source**: chat-ui `adia-ui-gen-review` cycle 17 (2026-05-26) — gallery review of 59 pre-hydrated prompts surfaced these seven as the recurring "wrong attribute = silent no-op" cluster across multiple chunks (accordion-faq, api-keys-table, sidebar-nav, chat-interface, code-snippet, billing-overview, integrations-grid). All seven are visible at canvas time, none at HTML-author time.
+
+---
+
+## §12 — Same attribute name, different enum across components (`drawer` `side` ≠ `pane` `side`)
+
+**Pattern**: Consumer authors `<drawer-ui side="trailing">` (or `side="leading"`), carrying over the `side` vocabulary from `<pane-ui>`. The drawer "opens" (`showModal()` fires) but the panel never appears — it renders at `opacity:0`, collapsed in the top-left corner. Looks like the drawer is broken.
+
+**Root cause**: two components share the attribute NAME `side` but use DIFFERENT enums. `<drawer-ui>` takes **physical** edges — `left | right | top | bottom` (default `right`). `<pane-ui>` takes **logical** sibling-edges — `leading | trailing`. `trailing`/`leading` aren't in drawer's enum, so no `[side="…"]` rule matches and the panel keeps its pre-open (hidden, off-canvas, `opacity:0`) state. The browser accepts any attribute value; only the matching CSS rule is missing, so there's no error and no console warning.
+
+**Fix**: use the component's own enum — a right-anchored drawer is `side="right"`, not `side="trailing"`.
+
+```html
+<!-- WRONG — pane vocabulary on a drawer → invisible panel -->
+<drawer-ui side="trailing" size="md">…</drawer-ui>
+<!-- RIGHT — drawer takes physical edges -->
+<drawer-ui side="right" size="md">…</drawer-ui>
+```
+
+**Recognition**: an overlay/drawer that "opens but shows nothing." Check the `side` value against the component's *own* yaml enum — sibling primitives that share an attribute name don't necessarily share its vocabulary. Inverse trap: `<pane-ui side="right">` (pane wants `leading`/`trailing`). Caught as bug-50 (v0.7.0): a demo used `side="trailing"` on a `<drawer-ui>`.
+
+---
+
+## §Meta-pattern across all twelve
+
+**Composites and primitives have layered contracts. Consumer code shouldn't reach into a primitive's layout territory; primitive code shouldn't fight its consumer's responsive constraints. The audit catches structural shape, not visual proportion; visual review catches the rest until proportional audits land.**
+
+These gotchas all share a structural cause: **defaults aren't contracts.** The primitive's default display, default size, default columns are starting points — when consumers override them, the override beats the default by virtue of specificity, NOT by correctness. Reading the primitive's `.css` end-to-end (`component-literacy.md` pre-flight gate) catches what `setAttribute()` calls reveal at consumer-write time.
+
+---
+
+## §When to apply
+
+- **Before Phase 4 Author**: review your sketch/plan for all four patterns
+- **When debugging "audit passes but looks broken"**: walk this list first; one of these four covers most cases
+- **Visual review checklist**: open the rendered surface; specifically look at empty-states, toolbars, KPI grids, and embedded composites
+
+## §What the substrate-side audit currently catches
+
+| Gotcha | Substrate audit gate |
+|---|---|
+| §1 Composition grammar | `audit:card-structure` (HTML + JS scan — see chat-ui commit `2778367e4`); similar for drawer-ui exists; avatar/alert/aside-ui forward work |
+| §2 Parent overrides child display | None; visual review only |
+| §3 Mixed control sizes | None; visual review only |
+| §4 `minmax(min, 1fr)` vs `@container` | None; visual review only |
+| §5 admin-page-{header,body} inner-column-owner missing | `audit:admin-page-structure` / `check:admin-page-structure` (chat-ui infra; runs against any HTML the consumer authors). Scans for `<admin-page-{header,body}>` whose direct child is NOT `:is(header, header-ui, section, section-ui, iframe, editor-shell, pane-ui)`. Wired into the master `check` cascade. |
+| §6 bare-slot brand chrome instead of `<admin-entity-item>` | `audit:brand-chrome` / `check:brand-chrome` (chat-ui infra; runs against any HTML the consumer authors). Scans for `<admin-topbar slot="header">` inside `<admin-sidebar slot="leading">` whose direct child carries `slot="icon"` or `slot="heading"` AND isn't `<admin-entity-item>`. Trailing-sidebar panel headers correctly excluded. Wired into the master `check` cascade. |
+| §7 router-ui silently renders empty when provider isn't registered | None yet (substrate fix at @adia-ai/web-components@0.7.13 retires the cold-start case — barrel side-effect-imports `core/provider.js`). Subpath-import consumers still vulnerable; forward work: add a console.warn at `<router-ui>` connect if `customElements.get('router-ui')` is HTMLUnknownElement (heuristic). |
+| §8 table-toolbar-ui double chrome from hand-rolled children | None yet; forward work: lint-style audit that flags any `<table-toolbar-ui>` with non-`[slot="actions"]` children. Visual symptom obvious during normal QA. |
+| §9 table-toolbar-ui + table-ui in same `<section bleed>` | None yet; forward work: HTML scan for `<card-ui> <section[bleed]> :is(table-toolbar-ui) ~ :is(table-ui)` (siblings inside bleed). |
+| §10 table-ui columns rendered as flat text — cell-types not engaged | None yet (data-layer state, not HTML state — audits don't see data binding). Forward work: dev-only runtime warning in `table-ui` if a column descriptor has `key` matching `amount` / `total` / `price` / `*_at` / `status` etc. heuristic names without a `type:` field. |
+| §11 Wrong attribute name — silent no-op | None mechanizable from HTML alone (any attribute is legal HTML). Component Literacy gate (`component-literacy.md`'s `embed_gotchas` field) is the upstream defense; cycle-style visual review catches the rest. Forward work per-primitive: dev-only `console.warn('<accordion-item-ui>: [label] is not a known prop; did you mean [text]?')` heuristic in `connected()`. |
+| §12 Cross-component enum confusion (drawer `side` vs pane `side`) | None from HTML alone (any value is legal HTML); the value is only wrong relative to the component's yaml enum. Component Literacy gate + visual review ("opens but shows nothing") catch it. Forward work per-primitive: dev-only `console.warn` in `connected()` when `[side]` isn't in the declared enum. |
+
+Forward work on substrate audit coverage is tracked in `.brain/handoffs/2026-05-25-session-handoff.md` (next-20 items #12-14, #15) + the five §7-11 forward-work entries above.