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

package/skills/adia-ui-kit/references/component-literacy.md

@@ -0,0 +1,291 @@
+---
+name: component-literacy
+load-when: Before Rung 13 (Component selection) when input is composition or PRD-derived intent. Fires in conjunction with picking AdiaUI primitives at kit §1 Catalog Lookup. The literacy gate that prevents CSS-illiteracy as accepted composition posture.
+load-size-tokens: ~2,800
+required-for:
+  - Mode 1-4 composition that selects 3+ substrate primitives
+  - Any composition that embeds composites (admin-shell, chat-shell, editor-shell, payment-method-list, etc.) — embedded composites inherit visual surface from their CSS
+  - NAILED tier of kit verify-target (structurally-verified-only does not require this; nailed does)
+companion-skill: "adia-ui-authoring v1.8.0+ (Phase 2.5a — kit's literacy gate is its sister skill's protocol applied at composition tier)"
+postmortem-precedent:
+  - ".brain/postmortems/2026-05-24-component-css-illiteracy.md (v1.8.0 — CSS-illiteracy as authoring failure mode)"
+  - ".brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md (v1.8.1 — detector ≠ enforcement; the second-order failure mode)"
+---
+
+# Component Literacy — kit's pre-Rung-13 gate
+
+> **The kit's Goodhart risk:** §Plan-Execute-Verify Mode 1-4 verify-target ("render in playground + audit scripts pass") is structurally self-passable. Audits validate recipe markup against substrate yaml SoT but never measure visual proportions, never read primitive CSS, never check token contracts beyond name validity. A composition can pass every audit gate while shipping a visual defect because the agent never opened the components' `.css` files. Authoring's 2026-05-24 CSS-illiteracy postmortem proved this is not a hypothetical failure — it is the default failure when verify metrics are author-designed and CSS reads are optional.
+
+This reference is the kit's **Rung 13 precondition gate** — fires in conjunction with kit §1 Catalog Lookup when selecting AdiaUI primitives for a composition. It does not replace §1; it forces the CSS read to happen at selection time rather than after-the-fact (or never).
+
+Sister-skill alignment: `adia-ui-authoring` v1.8.0 ships the same gate as §Phase 2.5a for composite-demo authoring. The two senior skills share the literacy discipline at different tiers of the AdiaUI workflow (kit = composition; authoring = substrate primitive authoring). Both produce a `preflight.yaml` artifact with the same shape.
+
+---
+
+## §When to load this reference
+
+Fires when:
+
+- Selecting 3+ AdiaUI primitives at kit §1 Catalog Lookup
+- Embedding ANY composite (admin-shell, chat-shell, editor-shell, simple-shell, payment-method-list, search-result, etc.) — composites inherit visual surface from their CSS at embed time
+- Targeting the `nailed` tier of kit §PEV Mode 1-4 verify-target (vs the default `structurally-verified-only`)
+- After §SpecToUi resolves Rungs 0-12 + wireframe, BEFORE handing off to §1
+
+Skip when:
+
+- Composition uses ≤2 primitives the agent has already read in this session (cite the read; don't re-read)
+- The verify-target chosen at the §Plan step is `structurally-verified-only` only (machine-signals-only — no human visual ack required)
+
+> **Next-layer companion**: after the literacy gate fires, the four recurring consumer-side composition traps live in [`common-gotchas-consumer.md`](common-gotchas-consumer.md) (composite grammar bypass · parent CSS clobbering child display · mixed control sizes · `minmax(min, 1fr)` vs container queries). Reading is not recognizing — that reference is the checklist for what the literacy reads SHOULD have made you notice. Load it before Phase 4 author or when debugging "audit passes but looks broken" defects. Sister-aligned with `adia-ui-authoring` v1.8.2.
+
+---
+
+## §What the gate enforces (3 invariants)
+
+**1. The agent cannot fill in literacy fields without opening the CSS.**
+
+The required fields (`default_render`, `slot_sizing_rules`, `exposed_tokens`, `embed_gotchas`) exist BECAUSE they are unfabricable. Skim-and-make-up is detectable in review (and self-evident on the next read by anyone else). If you cannot write three sentences about what `<table-ui>` renders at default — what its padding, border, alternation, and density signature look like — you have not read its CSS, and you are about to compose with vocabulary you do not understand.
+
+**2. `why_chosen` + `alternatives_considered` forces the choice to be argued.**
+
+If you cannot write one sentence justifying why `<table-ui>` is the right primitive for THIS decision over `<grid-ui>` of `<card-ui>` OR `<list-ui>`, the choice is not deliberate — it is pattern-matched from prompt vocabulary. That is the KP-02 anti-pattern (Shell-vocabulary primacy) at the primitive tier.
+
+**3. Embedded composites get extra fields.**
+
+When you embed a composite (e.g., `<payment-method-list>` inside an admin-page-body), you inherit its full visual surface. Reading the composite's `.class.js` stamp/render method is mandatory — semantic API knowledge of the composite is insufficient. The embed inherits its rows, its row spacing, its brand-cell proportions, its empty-state shape. If you have not read those, you are compositing against a black box and your verify is structurally inadequate.
+
+---
+
+## §Output artifact
+
+`.brain/findings/<task>.preflight.yaml` (sibling to `<task>.wireframe.md` per §SpecToUi reference) OR `.adia-ui-kit/preflight-<task>.yaml` in a consumer repo without `.brain/` directory.
+
+The artifact is required-for the `nailed` tier of kit §PEV verify; optional-for `structurally-verified-only`.
+
+### Required structure
+
+```yaml
+# Pre-flight component literacy — <task-slug>
+# Required before kit §1 Catalog Lookup locks primitive selection
+# (when targeting `nailed` tier of kit §PEV Mode 1-4 verify).
+# Audit trail field: kit verify-target audit JSON's
+# `component_literacy_path` MUST reference this file.
+
+task_slug: <task-slug>
+task_intent: <one-sentence from §SpecToUi Rung 1>
+substrate_version: "@adia-ai/*@<version from lockstep manifest>"
+pre_flight_authored_at: <ISO 8601 timestamp>
+pre_flight_author: <agent or human identifier>
+
+# ────────────────────────────────────────────────────────────────
+# PRIMITIVES — used directly in the composition
+# ────────────────────────────────────────────────────────────────
+
+primitives_used:
+  - slug: <primitive-tag-without-ui-suffix>      # e.g. card, table, button
+    css_path: packages/web-components/components/<dir>/<dir>.css
+    css_sha256: <12+ hex of file at read time>
+    css_read_at: <ISO 8601>
+    default_render: |
+      What this primitive renders with no attributes set.
+      Include actual computed dimensions (px or rem with px in parens).
+      Example: "display: block; full-width. Padding --card-inset
+      (default --a-inset = space-4 ≈ 16px). Border 1px subtle,
+      radius lg (~12px), bg --a-canvas-1, shadow-sm."
+    slot_sizing_rules:
+      - "[slot='<name>']: <how this slot sizes its content>"
+      - "..."
+    exposed_tokens:
+      - "<--token-name>: <fallback chain summary>"
+    visual_signature: |
+      One paragraph: what does this primitive look like at default?
+      Frame, padding, density, fg/bg, signature chrome.
+    embed_gotchas:
+      - <known issue or non-obvious behavior when embedding>
+    why_chosen: <one sentence: why this primitive fits this slot/region>
+    alternatives_considered:
+      - <slug>: <why rejected>
+
+# ────────────────────────────────────────────────────────────────
+# EMBEDDED COMPOSITES — composites composed into this task's surface
+# ────────────────────────────────────────────────────────────────
+
+embedded_composites:
+  - slug: <composite-tag-without-ui-suffix>      # e.g. admin-shell, payment-method-list
+    css_path: packages/web-modules/<cluster>/<dir>/<dir>.css
+    class_path: packages/web-modules/<cluster>/<dir>/<dir>.class.js
+    css_sha256: <hash>
+    class_sha256: <hash>
+    read_at: <ISO 8601>
+    composite_renders_what: |
+      Read the .class.js's stamp/render methods.
+      Describe the Level 5 tree this composite produces.
+      Include the data-* attribute regions and how they nest.
+    per_item_proportions:
+      # Honest dimensional observations from the CSS read.
+      # If a row's brand-cell is 50% icon-to-frame ratio, note it here.
+      <dimension_name>: <value + computed px>
+      <ratio_or_density_note>: <observation>
+      visual_note: |
+        Honest visual assessment. If proportions look off, say so here —
+        this is the place to surface visual-debt that the embedded
+        composite's own future cycle should address. Do NOT patch the
+        embedded composite from THIS task's cycle (cross-cycle scope
+        discipline; see §Cross-cycle-scope below).
+    embed_gotchas:
+      - <token collision, contrast issue, density issue with parent chrome>
+    why_chosen: <one sentence>
+    alternatives_considered:
+      - <slug>: <why rejected>
+
+# ────────────────────────────────────────────────────────────────
+# PATTERNS REFERENCED — named compositions from kit/site catalog
+# ────────────────────────────────────────────────────────────────
+
+patterns_referenced:
+  - pattern_id: <kebab-case>                     # e.g. admin-page-header, kpi-strip
+    canonical_source: <path>
+    composed_of: [<primitive>, <primitive>]
+    why_chosen: <one sentence>
+```
+
+---
+
+## §Worked-example reading (compressed)
+
+A real preflight entry for `<card-ui>` (kit's most-embedded primitive) reads:
+
+```yaml
+- slug: card-ui
+  css_path: packages/web-components/components/card/card.css
+  css_sha256: '4a0bdf16c687'  # pinned at read time
+  css_read_at: '2026-05-24T18:00:00Z'
+  default_render: |
+    display: block; full-width by default. Padding via --card-inset
+    token (default = --a-inset = space-4 ≈ 16px). Border 1px subtle,
+    radius lg (~12px), bg --a-canvas-1, shadow-sm by default.
+  slot_sizing_rules:
+    - "Header slot: laid out via card-ui's own header-slot grammar with --card-header-gap (space-2)."
+    - "Default content (no slot): direct children flow vertically; --card-gap sets row spacing."
+    - "Footer slot: --card-footer-gap (space-2)."
+  exposed_tokens:
+    - "--card-inset (padding)"
+    - "--card-gap (content row gap)"
+    - "--card-bg / --card-fg / --card-border"
+  visual_signature: |
+    Bordered container, rounded-lg, subtle shadow. Default chrome is
+    neutral (--a-canvas-1). When size='sm', padding shrinks; this is
+    how payment-method-list rows feel tighter than billing-overview's
+    header card.
+  embed_gotchas:
+    - "Setting --card-inset on a parent that uses card-ui changes padding for ALL nested card-ui children unless they re-declare. Cascade is intentional but easy to miss."
+    - "Header slot has its own gap; don't add an extra gap on direct children — they double up."
+  why_chosen: |
+    Header region (page-level chrome) and each KPI tile both need
+    bordered card chrome with consistent radius + padding + density.
+  alternatives_considered:
+    - "raw <header>: rejected — no consistent chrome with KPI tiles below"
+    - "<section-ui>: rejected — reading-column wrapper, not card chrome"
+```
+
+The fields that CANNOT be fabricated without reading CSS: `default_render`, `slot_sizing_rules`, `exposed_tokens`, `embed_gotchas`, `visual_signature`. These are the literacy fields. Their presence is the proof.
+
+---
+
+## §Verify-target — when is the literacy gate satisfied?
+
+The literacy gate is satisfied when:
+
+- [ ] Every primitive used in the composition has a `primitives_used` entry
+- [ ] Every embedded composite has an `embedded_composites` entry with `composite_renders_what` + `per_item_proportions`
+- [ ] All required fields per entry populated (none are `<...>` placeholders)
+- [ ] `css_sha256` values present (proves the file was read at a specific state)
+- [ ] `why_chosen` + `alternatives_considered` non-empty per entry
+- [ ] `visual_note` present in `embedded_composites` even when proportions look correct (the note is required; "no issues" is a valid value)
+
+Once satisfied, the task may target the `nailed` tier of kit §PEV verify (see kit SKILL.md §PEV verify-target table). Without the literacy gate, the maximum claim is `structurally-verified-only`.
+
+---
+
+## §Cross-cycle-scope discipline
+
+**Embedded composites are not patchable from THIS task's cycle.**
+
+If reading `<payment-method-list>` reveals that its brand-cell renders at 50% icon-to-frame (a real defect — see postmortem), the literacy artifact NOTES the observation in `per_item_proportions.visual_note`. The fix belongs in `payment-method-list`'s own composite cycle, not in the task that embeds it. The note creates a paper trail that the embed was a deliberate choice with eyes open.
+
+**Why:** mixing cross-cycle scopes leads to compounding regressions. The author of the embedding task does not own the embedded composite's verify path; patching its CSS from a downstream task bypasses its own canonical verify. The right action is:
+
+1. Author the literacy `visual_note`
+2. Open a substrate FB ticket (per kit §Team Tickets) citing the literacy artifact as evidence
+3. Proceed with the embed at `structurally-verified-only` tier (NAILED tier is unreachable until embedded composite is fixed in its own cycle)
+
+This mirrors authoring's §Phase 2.5a `visual_note` discipline. Cross-skill consistency.
+
+---
+
+## §Kit §PEV verify-target — the NAILED status contract
+
+Kit §PEV Mode 1-4 verify-target splits into TWO tiers based on whether the literacy gate fired:
+
+| Tier | Means | Required signals |
+|---|---|---|
+| `structurally-verified-only` | Machine checks pass; no human visual ack; composition is structurally sound but visual fidelity is unverified | (a) Composed surface renders in playground without errors; (b) `audit-native-primitive-leak` passes; (c) `audit-shell-composition` passes (if shell-bearing); (d) `audit-kit-recipes` passes against substrate yaml SoT |
+| `nailed` | Structurally verified AND author has done CSS literacy AND human-eyes ack | All of `structurally-verified-only` + `component_literacy_path` populated + `visual_verify_acknowledged_at` timestamp + `visual_verify_screenshot` path + `visual_verify_notes` prose |
+
+**Default tier is `structurally-verified-only`.** `nailed` is reachable only by completing the literacy + visual axis. The split exists because the 2026-05-24 authoring postmortem showed structural-pass alone is insufficient — the visual-proportion defect existed in code that passed every machine check.
+
+The kit consumer chooses the tier at the §Plan step (per §PEV). A task with high consequence (production-bound feature, brand-critical surface, multi-role workflow) should target `nailed`. A task with low consequence (internal prototype, exploration) may target `structurally-verified-only` and skip the literacy gate. **Be honest about which tier you chose** — claiming `nailed` while skipping the literacy gate is the Goodhart-on-NAILED failure mode from the postmortem.
+
+### Detector ≠ Enforcement (sibling-postmortem v1.8.1 lesson)
+
+**The audit existing is not the same as the audit firing.** This is the second-order failure mode documented in `.brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md` (companion to the CSS-illiteracy postmortem). The card-structure audit was authored, wired into `npm run check`, and exit-non-zero locally for 7 days while violations merged because (a) an upstream gate in the chained `&&` pipeline failed first, short-circuiting the downstream check; (b) branch protection allowed merges with red CI status.
+
+**Apply this to kit verify:**
+
+- The `structurally-verified-only` tier requires audits to RUN and PASS, not just to EXIST in the kit. Verify the audits ran in your verify session — don't assume `npm run check` covers them if upstream gates may have short-circuited.
+- For consumer repos, use [`npm run audit:health`](#audit-health) to surface which gates are currently silent on `main`. A gate that should be enforcing kit's contract but isn't running is a hidden hole in the verify path.
+- The `nailed` tier's `<task>.preflight.yaml` artifact is currently a MANUAL gate (mechanical `audit:preflight-completeness` is forward work). Manual + unenforced = same failure class as the card-structure audit drift. **The artifact-presence check is the enforcement surface for now.** If the kit consumer's CI doesn't fail when `phase_2_5_preflight_path` is missing from the audit JSON, the tier claim is unverified.
+
+**Tier-claim discipline (extended at kit v3.7.1):** claiming `nailed` requires THREE invariants:
+
+1. The literacy artifact EXISTS at the expected path
+2. The artifact is COMPLETE (every primitive + embedded composite covered; no `<...>` placeholders)
+3. The verify session that produced the structurally-verified-only signals ACTUALLY RAN those audits — not assumed-to-have-run via an aggregate `npm run check` that may have short-circuited upstream
+
+Without all three, the maximum honest claim is `structurally-verified-only`.
+
+<a id="audit-health"></a>
+
+### Discovery: `npm run audit:health` (chat-ui infra, kit cites)
+
+The chat-ui repository ships `npm run audit:health` (added in commit `2778367e4` — see authoring v1.8.1 forward-work closure). It runs every `check:*`, `audit:*`, `verify:*` script INDEPENDENTLY (not chained), producing a daily failure surface at `.brain/findings/audit-health-YYYY-MM-DD.md` + JSON variant via `npm run audit:health:json`.
+
+This is the substrate-side detector for silent-failure gates. **Run it before claiming `nailed`** on chat-ui-substrate-adjacent work, to confirm that the kit-relevant audits (`audit-kit-recipes`, `audit-native-primitive-leak`, `audit-shell-composition`, `audit-demo-slot-vs-css`) are actually firing in the current `main`. If any of those show in the failing-gates list, the kit's `structurally-verified-only` signals from your local verify session may be misleading — they pass locally but aren't enforced upstream.
+
+Consumer repos without `audit:health` should run kit's individual audit scripts directly per `audit-scripts.md`, then verify each script's exit code. Don't trust an aggregate `&& npm run check` to surface failures — chains short-circuit.
+
+---
+
+## §References
+
+**Sister-skill source (authoring v1.8.0–v1.8.1):**
+
+- `.agents/skills/adia-ui-authoring/references/composite-demo-protocol.md` — §Phase 2.5a Pre-flight Component Literacy + §NAILED status contract
+- `.brain/postmortems/2026-05-24-component-css-illiteracy.md` — load-bearing rationale for the literacy gate; the structural failure mode this gate prevents
+- `.brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md` — sibling-postmortem (v1.8.1); the second-order failure mode (detector exists, enforcement absent) the §Detector-≠-Enforcement section addresses
+
+**Kit references that hand off to / from this gate:**
+
+- [`spec-to-ui-reasoning.md`](spec-to-ui-reasoning.md) §SpecToUi — Rungs 0-12 must resolve BEFORE the literacy gate; the literacy gate is the Rung 13 precondition
+- [`catalog-lookup.md`](catalog-lookup.md) — kit §1 Catalog Lookup; the literacy gate fires here, not after
+- [`composition.md`](composition.md) — kit §2 Composition; consumes the literacy artifact as input (cites the read primitives)
+- [`common-gotchas-consumer.md`](common-gotchas-consumer.md) — next-layer Phase 4 author checklist; the four recurring consumer-side traps that recur even AFTER literacy is established (reading isn't recognizing). Sister-aligned with `adia-ui-authoring` v1.8.2 (commit `62f57f973`).
+- `audit-scripts.md` — the bundled audit scripts that produce the `structurally-verified-only` signal
+
+**Kit modes:**
+
+- §SpecToUi (kit mode 15) — resolves Rungs 0-12; hands off to §1 + this literacy gate
+- §1 Catalog Lookup (kit) — fires WITH this literacy gate, not before or after
+- §2 Composition (kit) — consumes the literacy artifact
+- §3 Validation (kit) — produces the structurally-verified-only signals
+- §PEV Mode 1-4 verify-target — splits into structurally-verified-only vs nailed based on whether this gate fired

package/skills/adia-ui-kit/references/composition.md

@@ -0,0 +1,245 @@
+---
+name: composition
+load-when: Authoring the actual HTML + A2UI JSON output once the primitives are selected. Covers slot vocabulary, attribute conventions, data binding, accessibility, and the composition contract
+load-size-tokens: ~2,400
+required-for:
+  - composition modes 1-4 after Catalog Lookup completes
+---
+
+# §2 — Composition
+
+### When to use this skill
+
+- Building a complete screen or flow from the component library
+  (login form, dashboard, settings page, artifact feed, chat).
+- Wiring components through the A2UI protocol (createSurface,
+  updateComponents, wireComponents).
+- Laying out content with the four layout primitives.
+- Attaching traits (pressable, focusable, draggable, resizable).
+- Writing a new page or app that uses AdiaUI components.
+
+### When NOT to use
+
+- Authoring or modifying components in `packages/web-components/` →
+  use `adia-ui-authoring` (renamed from `adia-ui-author` 2026-05-22;
+  now a 6-mode rollup that also absorbed `adia-ui-code-bestpractices`,
+  `bespoke-shell-children`, and `promote-inline-to-module`).
+- Changing generator / pattern-library internals → use `adia-ui-a2ui`.
+- Running the MCP validation pipeline → use `adia-ui-a2ui`.
+
+### First principles
+
+> **Before composing:** if you haven't looked up the components in your
+> plan, stop and run §1 Catalog Lookup. The `Concept index` below is a
+> hint, not a substitute for the yaml.
+
+1. **Every surface is a card.** The card content model (header / section /
+   footer) is mandatory for any block-level surface. When in doubt,
+   wrap in `<card-ui>`.
+
+2. **Composition is pure markup.** No `<style>` blocks, no inline `style=`,
+   no `<script>`. All variance comes from attributes on existing components.
+
+3. **Layout primitives over bare `<div>`.** `col-ui`, `row-ui`, `grid-ui`,
+   `stack-ui` are the canonical containers. Bare `<div>` is a validator flag.
+
+4. **One layout wrapper per section.** Every `<section>` inside a card
+   contains exactly one layout primitive.
+
+5. **Tokens, not raw values — and the name must exist.** CSS: `var(--a-space-3)` not `12px`.
+   Color: `var(--a-fg)` not `#111`. No raw hex anywhere.
+   **Critical trap — CSS fallback silently masks broken token names.** `font-size: var(--a-text-xs)` on a
+   non-existent token renders at the browser default with zero warning, no DevTools red, no console error.
+   Common broken-name patterns (real name → wrong guess): `--a-weight-medium` ≠ `--a-font-medium`,
+   `--a-ui-xs` ≠ `--a-text-xs`, `--a-code-family` ≠ `--a-font-mono`, `--a-canvas-0` ≠ `--a-surface`.
+   **Verify before use**: `grep -r '\-\-a-<name>' packages/web-components/styles/` — no grep hit = the
+   name is wrong. 16 broken references shipped undetected for months in a color-app session (FB-44).
+
+6. **A2UI JSON is the machine contract.** Every HTML composition has an
+   equivalent A2UI JSON representation. The JSON is what the gen-ui
+   pipeline validates and stores.
+
+### Concept index (what to reach for)
+
+| Need | Component / Pattern |
+|---|---|
+| App frame | `<admin-shell>` (admin) · `<chat-shell>` (chat) · `<editor-shell>` (editor) · `<simple-shell>` (marketing/single) — one tag per posture, no umbrella `<app-shell>` |
+| Primary nav | `<nav-ui>` with `<nav-item-ui>` children — place inside the shell's `slot="leading"` sidebar |
+| Section nav | `<tabs-ui>` (tab-style; v0.6.34+ default size is universal `--a-size` ≈ 30px — pre-v0.6.34 default was hardcoded 36px. Add `[size="lg"]` to restore the pre-v0.6.34 visual.) or `<nav-ui>` with `<nav-item-ui>` for non-tab section navigation |
+| Route tabs | `<tabs-ui>` (see size note above) |
+| Page content block | `<card-ui>` with header / section / footer slots |
+| Stacked layout | `<col-ui gap="…">` |
+| Side-by-side | `<row-ui gap="…">` |
+| Grid | `<grid-ui columns="…">` · asymmetric: `columns="5"` + `span="3"` + `span="2"` |
+| Responsive layout | `@bp` annotation on any layout prop: `columns="2 4@md"` · `gap="2 4@md"` · `justify="start between@md"` — breakpoints xs/sm/md/lg/xl (0/480/768/1024/1280 px). Never use `@media` or inline style for layout breakpoints. |
+| Stack (overlap) | `<stack-ui>` |
+| Text | `<text-ui variant="body|heading|title|display|caption|label|kicker|…">` plus optional `size="sm|md|lg"`, `color="subtle|strong|accent|danger|success|warning|default"`, `weight="regular|medium|semibold|bold"`, `text-align="start|center|end|justify"` (overlays added v0.6.18, FB-10) |
+| Button | `<button-ui variant="primary|secondary|ghost|danger">` |
+| Input | `<input-ui type="text|email|search|…">` — always in `<field-ui>` |
+| Select | `<select-ui>` — always in `<field-ui>` |
+| Checkbox | `<check-ui label="…">` — self-labeling, NOT in field-ui |
+| Switch | `<switch-ui label="…">` — self-labeling, NOT in field-ui |
+| Radio | `<radio-ui label="…">` — self-labeling |
+| Form label wrapper | `<field-ui label="…" [inline] [align="end"]>` |
+| Data table | `<table-ui>` + `<table-toolbar-ui>` (always paired) |
+| KPI number | `<stat-ui label="…" value="…" [trend="up|down"]>` |
+| Badge | `<badge-ui variant="…">` |
+| Icon | `<icon-ui name="…">` (Phosphor icon names) |
+| Avatar | `<avatar-ui>` |
+| Alert | `<alert-ui variant="info|warning|danger|success">` |
+| Modal | `<modal-ui>` wrapping `<card-ui>` |
+| Drawer | `<drawer-ui side="right|left">` |
+| Popover | `<popover-ui>` |
+| Tooltip | `<tooltip-ui content="…">` |
+| Command palette | `<command-ui>` |
+| Chat thread | `<chat-thread>` |
+| Progress | `<progress-ui>` |
+| Skeleton | `<skeleton-ui>` |
+| Divider | `<divider-ui>` |
+| Traits | `pressable`, `focusable`, `draggable`, `resizable`, `selectable` |
+
+### v0.6.34 new primitives (substrate currency — 11 new tags)
+
+Released 2026-05-23 substrate cut; ZERO kit recipes yet — full coverage will land as patterns emerge. Until then, use this keyword index to discover them:
+
+| Tag | Category | Use when |
+|---|---|---|
+| `<calendar-grid-ui>` | input (substrate) | A single-month calendar grid as a substrate primitive — NOT the user-facing date affordance. Use `<calendar-picker-ui>` (popover wrapper) for a complete date picker; reach for `<calendar-grid-ui>` only when authoring a higher-tier widget that already has its own trigger/popover. |
+| `<combobox-ui>` | input | Typeahead-filterable single-select — the constrained-choice combobox per WAI-APG. **Distinct from `<select-ui>`**: combobox lets users TYPE to filter; select is point-and-click only. Use combobox when the option list is long (>20 entries) and users know what they're looking for; use select for short, fully-scannable lists. The committed value MUST be from the options list (no free-form entry). |
+| `<date-range-picker-ui>` | input | Compound form primitive for start + end date pair with optional named preset shortcuts ("Today", "Last 7 days", "This month"). Trigger button → popover with two synchronized calendar panes + a preset side rail. Form-associated under one `name`. Emits `{from, to}` ISO 8601. For dashboard-level "current time window" controls (preset chip-row + comparison), use `<date-range-selector-ui>` instead. |
+| `<datetime-picker-ui>` | input | Single-control date + time selection. Trigger button → popover with `<calendar-picker-ui>` on the left + `<time-picker-ui>` on the right. Emits ISO 8601 datetime string. Per ADR-0025 NEVER wraps native `<input type="datetime-local">` (bespoke surface owns the affordance). Form-associated under one `name`. |
+| `<integration-card-ui>` | display | Single-tile primitive for one third-party integration (Slack, GitHub, Stripe…). Logo + name + description + status pill + primary action button whose label/variant derives from `[status]`. Compose into a grid via the SPEC-063 integrations-page composite. |
+| `<list-window-ui>` | display | Virtualized / windowed list — renders only the visible slice (~50 DOM rows) of a large items[] array. For chat threads, feeds, log streams, nav lists, search-result panes. Composes a `render`-function prop OR a slotted `<template>` for row materialization. Fixed-size fast-path + variable-size mode. |
+| `<spinner-ui>` | feedback | Circular indeterminate-loading indicator (rotating arc / full ring / three bouncing dots inside a sized box). Use when wait duration is unknown and the shape of the upcoming content isn't yet known. Fills the circular-spinner gap between `<skeleton-ui>` (rectangular placeholder) and `<progress-ui>` (linear determinate bar). Animation pauses via `[paused]`. |
+| `<time-picker-ui>` | input | Time-of-day picker with discrete segments (hour, minute, optional second, optional AM/PM). Each segment is a WAI-ARIA Spinbutton with Arrow/PageUp-Down/Home-End/Tab semantics. Form-associated under one `name`. Emits `"HH:mm"` or `"HH:mm:ss"`. |
+| `<date-range-selector-ui>` | input (module) | **Dashboard-level "current time window" chooser** — a module-tier composite pairing a preset chip-row (Today / 7d / 30d / 90d / QTD / YTD / Custom) with an embedded `<date-range-picker-ui>`. Use at the TOP of a metrics page; emits the same `{from, to}` shape as the underlying picker so downstream consumers don't care which control fired. |
+| `<confirm-dialog-ui>` | feedback (module) | Non-destructive yes/no confirmation dialog — thin composite over `<modal-ui>` with the canonical confirm shape pre-stamped (title + optional icon header, description + optional rich body, primary/secondary action footer). Reach for this instead of hand-rolling a `<modal-ui>` for every yes/no prompt. For destructive confirmations, set `[variant="danger"]` on the primary button. |
+| `<onboarding-checklist-ui>` | feedback (module) | Module-tier "Getting started" widget (the Stripe / Linear / Vercel dashboard pattern). Composes `<progress-ui>` (top fill bar) + `<list-ui>` + `<list-item-ui>` rows for each setup step. Place at the top of a dashboard page when first-run; auto-hide once `progress=100`. |
+
+Recipes for these primitives will land as patterns emerge in real consumer use. If you're authoring one and the kit lacks coverage, `node scripts/teach-route.mjs --payload="<description>"` will route the new recipe to the right `references/patterns-*.md` file.
+
+### A2UI JSON wiring
+
+Three message types for composition:
+
+```json
+[
+  {
+    "type": "createSurface",
+    "surfaceId": "s1",
+    "components": [
+      { "id": "c1", "component": "Card", "children": ["c2", "c3"] },
+      { "id": "c2", "component": "Header", "title": "Dashboard" },
+      { "id": "c3", "component": "Stat", "label": "MRR", "value": "$42K" }
+    ]
+  }
+]
+```
+
+- `component` values are PascalCase (`Card`, `Button`, `Field`, `Stat`)
+- `id` values are lowercase-kebab
+- `children` is an ordered array of child component IDs
+- `slot` overrides the default slot for a child
+- Data bindings go in a `wireComponents` message, not inline
+
+### App shell selection guide
+
+| Posture | Shell | When |
+|---|---|---|
+| Monitoring / acting | `admin-shell` | Sidebar IA, multiple routes, data-heavy |
+| Chat / conversational | `chat-shell` | Thread-centric, agent interaction |
+| Editing / creating | `editor-shell` | Canvas + toolbar + panels |
+| Single surface | `simple-shell` | Marketing, landing, auth, wizard |
+| Embedded / raw | `a2ui-root` | Gen-UI output, embedded renderers |
+
+### Form composition rules
+
+- Wide controls (`input-ui`, `select-ui`, `textarea-ui`, `slider-ui`,
+  `calendar-picker-ui`, `upload-ui`) MUST be inside `<field-ui>`.
+- Self-labeling widgets (`check-ui`, `switch-ui`, `radio-ui`, `toggle-ui`)
+  MUST NOT be inside `<field-ui>` — they carry their own `[label]`.
+- Use `<fields-ui>` for multi-column form grids.
+- Use `<field-ui align="end">` to right-align labels in a multi-field stack.
+
+### Data table pairing rule
+
+`<table-ui>` is always paired with `<table-toolbar-ui>`. The toolbar
+provides search, filter, sort, and column controls **on by default** —
+authoring a table without a toolbar is an anti-pattern (`check-composes`
+will flag it).
+
+> **Pitfall: `<table-toolbar-ui>` controls are opt-OUT, not opt-in.**
+> Search, filter, sort, and column-visibility are all enabled by default
+> the moment you place a `<table-toolbar-ui>` adjacent to a table. To
+> disable specific controls, use the **boolean opt-out attributes**:
+>
+> ```html
+> <!-- All four controls active (default) -->
+> <table-toolbar-ui id="users-toolbar"></table-toolbar-ui>
+>
+> <!-- Suppress filter + column-visibility, keep search + sort -->
+> <table-toolbar-ui id="users-toolbar" no-filter no-columns></table-toolbar-ui>
+> ```
+>
+> | Attribute | Effect |
+> | --------- | ------ |
+> | `no-search` | Hide the search input |
+> | `no-filter` | Hide the filter chips |
+> | `no-sort` | Disable the sort affordance |
+> | `no-columns` | Hide the column-visibility menu |
+>
+> **Common mistakes** (silently ignored — the toolbar still renders with
+> default behavior):
+> - `searchable` — not a real attribute. Search is already on; omit it.
+> - `exportable` — not a real attribute. The toolbar doesn't expose
+>   export functionality; use a sibling `<button-ui>` if you need an
+>   export action.
+>
+> Verified against
+> `node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.yaml`
+> (lines around `attribute: no-*`).
+
+### Theming via component-leaf tokens (OD-5 -default suffix, v0.6.34+)
+
+Two distinct token layers govern AdiaUI visuals:
+
+1. **Global semantic tokens** — `--a-bg`, `--a-fg`, `--a-accent-bg`, `--a-space-N`, `--a-radius-k`, etc. Set at `:root` (theme) or any ancestor (scope). Cascade through components. Use these for app-wide theming.
+
+2. **Component-leaf tokens** — `--button-bg`, `--tabs-button-height`, `--card-pad`, etc. Owned by individual components. Set per-instance via inline style or via a wrapper class. Used for one-off visual overrides.
+
+**OD-5 (v0.6.34) changed how the leaf layer works:** every component-leaf token now has a `-default` partner. The component CSS reads `var(--button-bg, var(--button-bg-default))` instead of `var(--a-fg)` directly. Consumer overrides at any ancestor surface now take effect; pre-v0.6.34 the leaf default shadowed wrapper overrides.
+
+```css
+/* Pre-v0.6.34 — this DIDN'T work (leaf default shadowed the override):
+.danger-zone button-ui {
+  --button-bg: red;
+}
+*/
+
+/* Post-v0.6.34 — this works as expected: */
+.danger-zone button-ui {
+  --button-bg: red;
+  /* Component CSS resolves: var(--button-bg, var(--button-bg-default))
+     → "red" wins; no shadowing. */
+}
+
+/* Theme-wide override (set at :root or theme scope): */
+:root {
+  --button-bg-default: var(--a-accent-bg);
+  /* Re-routes the default itself; instance --button-bg overrides still win. */
+}
+```
+
+**Naming convention:** for any leaf token `--X`, the substrate also exposes `--X-default`. Override `--X` for per-instance customization; override `--X-default` (typically at `:root`) to retarget the theme's resolved default. Discover tokens by inspecting `node_modules/@adia-ai/web-components/components/<name>/<name>.css` for the `:where(:scope)` block.
+
+**Global vs leaf — when each:**
+- App-wide theming → set global `--a-*` tokens at `:root` (preferred)
+- One-component customization → set its `--<component>-*` leaf token in a scope
+- New global token (theme extension) → not kit territory; substrate ADR + token registry
+
+### Notes on common pitfalls
+
+The `--a-*` global token surface remained stable across v0.6.34; only leaf tokens changed. Existing recipes that set `--a-bg`, `--a-fg`, etc. continue working unchanged.
+
+
+---