@adia-ai/adia-ui-forge 0.8.39 → 0.8.41

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

@@ -0,0 +1,277 @@
+# SVG authoring — coordinate, color, and hit-testing quirks
+
+SVG content behaves differently from HTML in ways that don't show up until a
+primitive is placed inside a themed, resizable, or bled container. This file
+collects the SVG-specific rules — everything else about authoring a
+primitive (yaml, tokens, lifecycle) is the rest of this skill's charter, not
+repeated here. Load this file when modifying `chart-ui`, `qr-code-ui`,
+`icon-ui`, or authoring any NEW primitive whose `class.js` builds `<svg>`
+markup (via `document.createElementNS`/`innerHTML`) rather than plain HTML.
+
+## 0. Which primitives actually render SVG (scope check first)
+
+Not every chart-family or chart-adjacent primitive renders SVG — check
+before assuming this file applies:
+
+- **Genuinely SVG-rendered**: `chart-ui` (`packages/web-components/components/chart/chart.class.js` — builds a `<svg>` string per chart type, §§#renderBar/#renderLine/etc.), `qr-code-ui` (`packages/web-components/components/qr-code/qr-code.class.js:107-118` + `qr-encoder.js:609-631`'s `matrixToSVG`), `icon-ui` (`packages/web-components/components/icon/icon.class.js:97-98` — stamps a Phosphor `<svg>` string via `getIcon()`).
+- **NOT SVG** despite living in the chart family: `chart-legend-ui` (`packages/web-components/components/chart-legend/chart-legend.class.js` — composes `<badge-ui>` + `<swatch-ui>`, no `<svg>` anywhere) and `swatch-ui` (`packages/web-components/components/swatch/swatch.class.js` — plain `<span data-tile>` divs styled via CSS `background`/`border`, confirmed by `grep -rn svg` returning nothing in either file). gh#1344's own body assumed `chart-legend-ui` was SVG-adjacent; it isn't — its swatch shapes (dot/square/line/dashed) are CSS box-model tricks, not paths.
+
+A future primitive whose `class.js` calls `createElementNS('http://www.w3.org/2000/svg', ...)` or sets `innerHTML` to a string containing `<svg>` is in scope for every rule below; one that only composes other `*-ui` elements (however chart-shaped visually) is not.
+
+## 1. viewBox is a coordinate system, not a size — two sizing strategies coexist
+
+`viewBox="minX minY width height"` defines the SVG's INTERNAL coordinate
+system; the element's rendered box size is separate (CSS `width`/`height` or
+SVG `width`/`height` attributes). Every number emitted into the SVG markup
+(`x`, `y`, `r`, `stroke-width`, `font-size`) is in viewBox units, not CSS
+pixels — the browser scales the whole coordinate system to fit the rendered
+box (`preserveAspectRatio`, default `xMidYMid meet`).
+
+Two different sizing strategies are in use, deliberately:
+
+- **`chart-ui` — responsive viewBox, CSS owns the box.** `chart.css:143-149` sets `svg { width: 100%; height: auto; max-height: 100%; overflow: visible }`; `#dims()` (`chart.class.js:405-457`) computes `width`/`height` FROM `this.clientWidth`/`clientHeight` every render, and `#renderChart()` sets `viewBox="0 0 ${width} ${height}"` (e.g. `chart.class.js:523`) to match. Because the viewBox is recomputed from the actual container size on every render, viewBox units and CSS px are numerically equal in the steady state — a `stroke-width: 2` in `chart.css:199` reads as 2 real px. A `ResizeObserver` (`chart.class.js:363-380`, debounced via `requestAnimationFrame`) keeps this in sync across container resizes; there's a brief window between a resize and the debounced re-render where the OLD viewBox is still active against the NEW box size, during which strokes/dots/fonts visually scale up or down with the mismatch — this is inherent to the responsive-viewBox strategy, not a bug to fix per-primitive.
+- **`qr-code-ui` — fixed pixel viewBox, explicit width/height attributes.** `matrixToSVG` (`qr-encoder.js:609-631`) sets `viewBox="0 0 ${total} ${total}"` AND `width="${total}" height="${total}"` (equal, so no scaling happens at generation time); `qr-code.class.js:123-127` then overwrites the `width`/`height` ATTRIBUTES (not CSS) to the `[size]` prop after `innerHTML` is set. `qr-code.css:23-28` documents why it does NOT use `width: 100%`: the host is `display: block` sized-to-content (the SVG itself), so a CSS-percentage width on the SVG would create a circular sizing dependency — "trust the SVG attributes" is the comment's own words.
+
+**When authoring a new SVG primitive**, pick one of these two strategies deliberately and document which: responsive-viewBox (chart-ui's approach — needed when the primitive must fill an arbitrary, resizable container) or fixed-attribute (qr-code-ui's approach — needed when the primitive has a scannable/pixel-exact payload where uncontrolled scaling would break fidelity, and the `[size]` prop is the only sizing lever a consumer needs).
+
+## 2. `stroke-width` and other bare numbers scale with the coordinate system
+
+Because `stroke-width`, circle `r`, and `font-size` values written into the
+SVG markup are viewBox-unit numbers (see §1), they are NOT the same kind of
+value as a CSS `border-width` or `font-size` on an HTML element — an HTML
+border stays a fixed px regardless of ancestor `transform: scale()` (the
+border itself doesn't get bigger, only the box does); an SVG stroke drawn in
+viewBox units scales proportionally with ANY transform that changes the
+effective viewBox-to-rendered-size ratio, including a CSS `transform: scale()`
+on the `<svg>` or an ancestor, and including the responsive-viewBox mismatch
+window described in §1. `chart.css:198-203`'s `[data-line] { stroke-width:
+var(--chart-line-width) }` (unitless — SVG interprets an unadorned number as
+user units) is a concrete example: at steady state this renders at the CSS
+`--chart-line-width` value in real px, but during a `transform: scale(1.5)`
+hover-zoom on a chart card it renders at 1.5× that, same as every other
+number in the shape's geometry — there is no way to pin stroke-width to a
+fixed screen px independent of the coordinate system short of
+`vector-effect: non-scaling-stroke` (not used anywhere in this codebase
+today — flag it if a future primitive needs scale-independent strokes).
+
+## 3. `text-anchor`/`dominant-baseline` position an anchor POINT, not a box corner
+
+SVG `<text>` has no intrinsic box model — `x`/`y` mark a single anchor
+point, and `text-anchor`/`dominant-baseline` say which part of the glyph run
+sits at that point. Getting this wrong is the single most common SVG label
+bug (text drifts off its intended mark as content length changes). Every
+label renderer in `chart.class.js` picks the anchor deliberately:
+
+- **Y-axis labels** — `text-anchor="end"` (`chart.class.js:1053`): the anchor point sits at the RIGHT edge of the label so labels of different digit-widths ("5", "5,000") stay right-aligned against the axis rather than growing rightward from a fixed left point.
+- **X-axis / value labels** — `text-anchor="middle"` (`chart.class.js:1068`, `1109`): centers over each bar/point regardless of label width.
+- **Donut center total/label, gauge value, funnel stage/value/drop, radar labels, sankey node labels** — `dominant-baseline="central"` (e.g. `chart.class.js:1270-1271`, `1585,1587`, `1642-1648`, `1357`, `1846,1852`): vertically centers the glyph on its `y` coordinate — needed anywhere a label sits beside or inside a shape whose center, not its top, is the meaningful reference point (a donut's numeric center, a radial label at a computed angle).
+- **Treemap tile labels — `dominant-baseline` switches per available space** (`chart.class.js:1766-1771`): `hanging` (top-aligned, the default vertical-metrics baseline) for a "tall" tile where label + value stack top-down, `central` for a "short" tile where only the label fits and it should sit mid-height rather than clipped against the top edge. Pick the baseline that matches the layout decision, not a single default for the whole primitive.
+
+Rule of thumb: `text-anchor` picks the horizontal anchor (`start`/`middle`/`end`), `dominant-baseline` picks the vertical one (`hanging`/`central`/`middle`/the default alphabetic baseline) — set both explicitly whenever a label's position depends on computed geometry rather than a fixed corner.
+
+## 4. Card-boundary clipping — `overflow: visible` is the default; a bleed section changes the contract
+
+`chart.css:143-149`'s `svg { overflow: visible }` is intentional: chart
+labels routinely extend slightly past the nominal plot rectangle (Y-axis
+labels sit at `pad.left - 4`, per §3), and `overflow: visible` lets that
+render instead of clipping at the SVG's own box edge. That default is safe
+inside a normally-inset `card-ui` section. It stops being safe the moment
+the SAME chart sits inside a `<section bleed>` — `card-ui`'s `:scope` itself
+clips at `overflow: hidden` with a rounded `border-radius` (`card.css`, top
+of file), and `[bleed]` zeroes the section's own margin/padding
+(`card.css:342` onward) — so a chart's axis-label overhang, or gridlines
+extending to the plot edge, lands flush against that rounded corner and
+clips silently. This was gh#1095's real incident (PR #1105): a bar/line
+chart's Y-axis labels clipped under a bled card's corner.
+
+**The fix is the canonical convention** — `card.css:400-422` (comment block
++ rule):
+
+```css
+/* Guide/value/legend safety inset (gh#1095) — [bleed]'s zero-inset is
+   only collision-free for the bare-marks case: a sparkline, or any other
+   chart-ui type with BOTH [hide-grid] and [hide-values] set. */
+& > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-grid])),
+& > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-values])),
+& > section[bleed]:has(> chart-legend-ui) {
+  margin: var(--card-inset);
+  padding: 0;
+}
+```
+
+This restores the card's own inset automatically the moment a bled chart
+still draws guides/values/a legend — a `:has()`-based fail-safe rather than
+relying on every author to remember. `#renderSparkline()` is the ONLY
+renderer that never emits axis ticks, gridlines, value text, or a legend
+(`chart.class.js`'s sparkline branch) — it's the sole type where genuine
+edge-to-edge bleed is collision-free with no attribute needed. Every other
+type needs BOTH `[hide-grid]` and `[hide-values]` set to opt into true
+bleed; short of that, the safety inset applies and the chart renders inset
+like a normal card section — expected, not a bug.
+
+**The generalized rule for any new SVG primitive placed inside a bleed
+section**: an SVG whose content can extend past its own nominal box
+(`overflow: visible`, or geometry computed with negative padding) needs
+either a "bare marks" mode (no overhanging content) that's safe to bleed, or
+a CSS `:has()` safety net analogous to `card.css:400-422` that restores
+inset automatically when the overhanging content is present. Don't assume
+`overflow: hidden` on the ancestor container will clip cleanly — SVG content
+drawn PAST an ancestor's padding box (not its own) clips at whatever
+ancestor in the chain actually sets `overflow: hidden`, which for
+`card-ui` is the rounded-corner boundary itself, producing the specific
+silently-clipped-under-a-curve look #1095 reported.
+
+## 5. CSS custom properties don't resolve inside raw SVG attribute strings — only inside actual CSS declarations
+
+A CSS custom property (`var(--foo)`) only resolves where the CSS cascade
+parses it: inside a stylesheet rule, or inside an inline `style="..."`
+attribute. It does NOT resolve inside an arbitrary SVG presentation
+attribute value written as a plain string (`fill="var(--foo)"` is invalid —
+the literal text `var(--foo)` is not a recognized SVG color, and the shape
+renders with the initial/inherited fill instead, silently). `currentColor`
+is different: it's a CSS-wide keyword the SVG spec itself recognizes inside
+presentation attributes, and it resolves against the computed `color`
+property the normal way — so `fill="currentColor"` written directly into
+markup DOES cascade correctly. `icon-ui` relies on exactly this: the
+installed Phosphor SVGs ship `fill="currentColor"` on their root `<svg>`
+(confirmed: `node_modules/@phosphor-icons/core/assets/regular/caret-right.svg`
+— `<svg ... fill="currentColor">`), and `icon.css`'s `:scope { color:
+var(--icon-color) }` (`icon.css:11`) drives it through the ordinary
+`color` inheritance chain — no `var()` inside the SVG markup is needed
+because `currentColor` isn't a custom property.
+
+`chart-ui` hit this distinction directly and got it wrong once (gh#561,
+documented in `chart.class.js:548-560`): an earlier version wrote
+`--color-{key}: var(--chart-N)` as an inline STYLE on the chart HOST, then
+tried to reference `--color-{key}` from series-colored shapes — but because
+inline styles win the cascade over everything except `!important`, a
+consumer's own `--color-MAU` set on an ancestor lost to the chart's own
+inline default, making the documented "override `--color-{key}` to recolor
+a series" hook unusable. **The fix, and the pattern to follow**: never set
+the color custom property on the host; instead emit it as an inline `style`
+attribute ON THE SHAPE ITSELF, with the fallback chain built into the same
+declaration — `#seriesFill()`/`#seriesStroke()` (`chart.class.js:568-575`)
+emit ` style="fill: var(--color-${seriesKey}, var(--chart-${slotIdx}))"` per
+`<path>`/`<circle>`. Because this IS a real CSS declaration (inside
+`style=""`), `var()` resolves normally, an ancestor-set `--color-{key}`
+flows through the cascade and wins, and an unset one falls through to the
+palette slot — exactly the semantics a bare attribute string can't provide.
+
+**`qr-code-ui` shows the failure mode `chart-ui` avoided**: `qr-code.css:7-8`
+declares `--qr-code-fg: currentColor` / `--qr-code-bg: transparent` and sets
+them as `color`/`background` on the HOST (`qr-code.css:17-18`) — but the
+actual QR modules are painted via `matrixToSVG` (`qr-encoder.js:609-631`),
+which bakes `fill="${fg}"`/`fill="${bg}"` as literal hex strings
+(`options.color || '#000'`, `qr-code.class.js:115-116` passes
+`this.color || '#000000'`) directly into the generated markup at render
+time. The `--qr-code-fg`/`--qr-code-bg` tokens are real and declared, but
+nothing in the render path ever reads them — setting `color` on an ancestor
+of a default `<qr-code-ui>` does nothing to its rendered fill; only the
+explicit `[color]`/`[background]` HTML attributes do (and deliberately so —
+the code comment at `qr-code.class.js:110-115` explains theme-aware
+`currentColor` would produce light-on-dark QR codes that most phone cameras
+refuse to scan). **When authoring a new SVG primitive with a
+"theming token" in its CSS, verify the render path actually consumes it as
+a live CSS value (inline `style=` per shape, or a bare `currentColor`
+keyword) rather than baking a computed color into the generated markup as a
+one-time string — a declared-but-dead token is a real trap for the next
+author who tries to theme the primitive from outside.**
+
+## 6. Hit-testing: `fill: transparent` is clickable, `fill: none` is not
+
+SVG's default `pointer-events: visiblePainted` treats a shape as
+hit-testable only if it's "painted" — `fill: transparent` counts as painted
+(alpha-zero, but still a fill), `fill: none` does not. `chart.css:381-386`
+states this explicitly as the reason its hit-target circles are always
+`fill: transparent !important` rather than `fill: none`:
+
+```css
+/* Hit-target overlays must never be filled by the slice palette —
+   they're meant to be invisible pointer-event surfaces. */
+circle[data-hit] {
+  fill: transparent !important;
+  stroke: none;
+}
+```
+
+This matters most for THIN shapes — a `<path data-line>` stroke has almost
+zero hit area along its own geometry, so `chart.class.js` renders a SEPARATE,
+generously-radiused invisible circle per point (`data-hit`, `hitR =
+Math.max(dotR, 10)` at `chart.class.js:1157/1165`, similarly `1450` for
+scatter) purely to catch pointer/click events, decoupled from the visible
+dot's actual radius. The average-line overlay is the same pattern applied to
+a LINE instead of a point: the visible dashed average line is `stroke-width:
+1.5` (`chart.css:259-263`), effectively unclickable, so a second invisible
+line with `stroke: transparent stroke-width="12"` rides on top purely for
+hit area (`chart.class.js:1119,1177`, labeled "Wider invisible hit target so
+the thin dashed line is hoverable" in the source comment). By contrast,
+FILLED shapes with real area — bars (`<path data-bar>`), pie/donut slices,
+radial-bar arcs — carry their `tip()` data attributes directly on the
+visible shape (`chart.class.js:1106`, `1209`, `1514`) with no separate hit
+overlay needed, because the visible fill already satisfies
+`visiblePainted`.
+
+**Rule for a new SVG primitive**: any interactive target whose visible
+stroke/fill area is too thin or too small to reliably hit with a pointer
+needs an invisible, generously-sized `fill: transparent` (never `fill:
+none`) overlay shape carrying the actual event data — don't rely on the
+visible geometry's own hit area once its rendered stroke-width or radius
+drops below a comfortable pointer target size (chart-ui's overlays use
+`r ≥ 10`, `stroke-width ≥ 12` as the floor).
+
+## 7. `shape-rendering` — pixel-grid content vs. smooth curves
+
+`qr-code.css:29`/`qr-encoder.js:629` set `shape-rendering: crispEdges` on
+the generated QR `<svg>` — this disables anti-aliasing so each QR module
+renders as a hard-edged square rather than a slightly blurred one, which
+matters for scanner reliability (soft edges reduce contrast at module
+boundaries a camera decoder relies on). `chart-ui` sets no `shape-rendering`
+override anywhere — its curves (`smoothPath`'s Catmull-Rom bezier
+conversion, `chart.class.js:158-180`) are meant to anti-alias normally.
+**When authoring a new SVG primitive rendering a hard pixel/module grid
+(a matrix code, a pixel-art preview, anything where edge crispness affects
+correctness rather than just aesthetics), set `shape-rendering: crispEdges`
+explicitly** — the browser default (`auto`, effectively anti-aliased) is
+correct for everything else and should stay the default.
+
+## 8. Attribute-shadowing on SVG-adjacent primitives (ADR-0053/0054)
+
+Two of the pre-existing global-attribute-grammar collisions gh#1335 surfaced
+are specifically SVG-rendered primitives, and both cite the SVG-specific
+reasoning for their proposed resolution rather than the generic
+rename/converge path:
+
+- **`qr-code-ui[color]`** — a free-form CSS color string (drives the raw
+  `fill` baked into the generated matrix SVG, §5 above), structurally
+  identical to the already-ratified `swatch-ui`/`noodles-ui[color]` §11
+  exemptions ("the component's entire subject is a color") — proposed for
+  the same exemption rather than a rename.
+- **`icon-ui[weight]`** — Phosphor's icon-rendering weight vocabulary
+  (`thin/light/regular/bold/fill/duotone`, selecting which pre-rendered SVG
+  asset variant `getIcon()` loads) is a DIFFERENT CONCEPT from CSS
+  `font-weight` (`thin/light/normal/medium/semibold/bold`) despite the
+  shared attribute name — gh#1335 names it "the strongest candidate for a
+  ratified §11 exemption rather than a rename," the same reasoning as
+  `swatch-ui[color]`.
+
+Neither is resolved yet (both remain in `check-attribute-shadowing.mjs`'s
+`KNOWN_FINDINGS` list per gh#1335) — cite this section, not a fresh
+investigation, if either surfaces again in a yaml audit.
+
+## When to load this file
+
+Any authoring task touching `chart-ui`, `qr-code-ui`, `icon-ui`, or a new
+primitive whose `class.js` emits `<svg>` markup — a new chart type, a
+label-positioning fix, a card-bleed interaction, a hit-target bug, or a
+color/theming prop on an SVG-rendered primitive. NOT for `chart-legend-ui`
+or `swatch-ui` (§0) — those are HTML/CSS primitives despite the chart-family
+name; their authoring questions route through the general
+[css-patterns.md](css-patterns.md) / [api-contract.md](api-contract.md)
+same as any other component. The `--chart-*` and `--qr-code-*` TOKEN
+declarations themselves (naming, `:where(:scope)` placement) still follow
+[token-contract.md](token-contract.md) — this file covers only what's
+SVG-specific once those tokens reach the render path. The ≤2px raw
+`stroke-width` carve-out in [css-patterns.md](css-patterns.md)'s "Raw
+values" section is the general rule this file's §2 explains the SVG-specific
+mechanism behind — cite both together when a stroke-width literal comes up
+in review.

package/skills/primitive-authoring/references/token-contract.md

@@ -133,7 +133,7 @@ mechanics; never work from this summary alone):
   *explicit* per-element overrides (non-inheriting), while `[size]`/`[density]`
   are *ambient* context-setters (inheriting by design). Which axis an attribute
   sits on decides its `@property` registration and how components read it.
-- **No shadowing** (`docs/adr/adr-0053-no-shadowing-global-attributes.md`): a
+- **No shadowing** (`docs/ops/adr/adr-0053-no-shadowing-global-attributes.md`): a
   component-local attribute may not share a name with any global attribute —
   the global name always means the global thing. Before minting any attribute
   in a component yaml, check it against the spec's attribute inventory; the

package/skills/primitive-authoring/references/yaml-contract.md

@@ -2,7 +2,7 @@
 
 Authoritative source-of-truth fields for `packages/web-components/components/<name>/<name>.yaml` and `packages/web-modules/<cluster>/<name>/<name>.yaml`. The build pipeline (`scripts/build/components.mjs`) reads these yamls + emits sidecar JSON (`<name>.a2ui.json`) that feeds the docs site, the A2UI runtime registries, and consumer harnesses.
 
-This is the authoritative schema reference for the authoring lane. The full validator + JSON Schema lives at `scripts/schemas/component.yaml.schema.json` (referenced by every yaml's `$schema:` key). This file covers the human-facing contract: what each field means, when to use which value, and the canonical shape of a complete yaml.
+This is the authoritative schema reference for the authoring lane. The JSON Schema lives at `scripts/schemas/component.yaml.schema.json` (referenced by every yaml's `$schema:` key). Amended 2026-08-16 per ADR-0057: that schema is the documented contract + IDE aid, not a run validator — no build step evaluates it against the yamls. The build-time checks that DO exist are hand-written throws in `compileComponent()` (`scripts/build/components.mjs`): a missing `component:` field, a `component: Surface` (reserved — the A2UI v1.0 implicit root container, SPEC REQ-011/gh#1353), a `status:` value outside the five-value enum (see §`status:` below), a missing `category:` field OR a `category:` value outside the twelve-value enum (see §`category:` below, ADR-0065), and malformed `a2ui.allowedParents`/`a2ui.allowedChildren` composition constraints (see §composition constraints below — plus a full-build cross-reference check that every referenced name is a real `component:` in the catalog). Every other schema constraint (`required: [name, tag, component, description]`, `minLength`, …) is IDE-visible only. This file covers the human-facing contract: what each field means, when to use which value, and the canonical shape of a complete yaml.
 
 ---
 
@@ -14,7 +14,7 @@ $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIMyComponent          # Class name (PascalCase, UI-prefixed)
 tag: my-component-ui         # Custom element tag (kebab-case, -ui-suffixed)
 component: MyComponent       # Short component name (no UI- prefix)
-category: form               # Category — form / display / layout / chrome / a2ui / shell
+category: form               # Category — see §category field below (ADR-0065, twelve-value enum)
 version: 1                   # Schema version (always 1 for now)
 status: stable               # Stability tier — see §status field below
 description: >-
@@ -26,13 +26,104 @@ props:
 events:
   …                          # Event schemas — fired by the component
 slots:
-  …                          # Named slot semantics
+  …                          # Consumer-fillable light-DOM insertion points — see §slots vs parts below
+parts:
+  …                          # Template-owned anatomy — see §slots vs parts below
 css-vars:
   …                          # CSS custom properties the component reads
 ```
 
 ---
 
+## `slots:` vs `parts:` — consumer-fillable vs template-owned anatomy (ADR-0067)
+
+**Decision rule**: does an author (a human, or an LLM generating an A2UI
+document) ever place their OWN content at this named span? If yes — even
+with a stamped fallback when nothing is supplied — it's `slots:`. If the
+component's own `render()`/template ALWAYS stamps it itself, from a prop or
+attribute, and no author-supplied content is ever accepted there — it's
+`parts:`. **Check element source, never the description prose alone**
+(AGENTS.md: source wins) — a name that *sounds* internal
+(`actions`, `text`, `leading`) can still be a real insertion point in a
+given component; `table-toolbar.yaml`'s `actions` slot LOOKS stamped by
+name but its `class.js` explicitly absorbs pre-existing `[slot="actions"]`
+children (a real, author-fillable insertion point) — the opposite of
+`check.yaml`'s `box`, which `static template = () => html\`<span
+slot="box"></span>\`` stamps unconditionally every render.
+
+Both keys share the identical `Slot` schema shape (`description:` required,
+`fallback:` optional) — the only difference is which key an entry lives
+under. `scripts/build/components.mjs` forwards both verbatim onto the
+sidecar (`x-adiaui.slots` / `x-adiaui.parts`) with no other processing.
+
+**Why the split matters — three real consumers read `slots:` and present
+every entry as fillable, with no code-level filtering for anything under
+`parts:`:**
+
+- `packages/gen-ui/engine/retrieval/component-entry.js`'s
+  `serializeReference()` — feeds the LLM-facing `reference`-detail catalog
+  entry (MCP tools, `getComponentAPI()`).
+- `packages/gen-ui/engine/compose/strategies/monolithic/_shared.js`'s
+  `adaptV09Component()` — feeds the monolithic engine's prompt catalog.
+- `scripts/docs/anatomy-sweep.mjs`'s `genSlots()` — renders the docs-site
+  "slots" anatomy section.
+
+A `parts:` entry never reaches any of the three above — moving template-owned
+anatomy there is a structural fix, not a naming convention alone. An
+existing entry under `slots:` that's actually template-owned (e.g. a
+component predating this ADR) is a real bug: it advertises to an LLM that
+filling it does something, when the component's own template replaces
+whatever's there on the next render — the exact gh#284 destructive-replace
+shape, applied to a *documented* slot instead of an undocumented one.
+
+`scripts/dev/audit-slot-vocab-vs-css.mjs` (the yaml-vs-CSS `[slot="X"]`
+cross-check) reads BOTH `slots:` and `parts:` — a `parts:` entry is still a
+real `slot="X"` DOM attribute the component's own CSS may position, just
+never author-fillable, so it stays in that audit's declared-vocabulary set.
+`scripts/dev/audit-template-child-conflict.mjs` (the gh#284 container-shape
+check) is unaffected either way — it only checks for a slot literally named
+`default`.
+
+---
+
+## `a2ui.allowedParents:` / `a2ui.allowedChildren:` — composition constraints (SPEC REQ-011, gh#1353)
+
+Optional keys inside the `a2ui:` block, alongside `rules:`. Each is a
+non-empty list of catalog `component:` names (NOT tags) naming the direct
+parents this component may sit under / the direct children it may contain.
+The reserved name `Surface` (the A2UI v1.0 implicit root container) is legal
+only in `allowedParents` and means "may sit at the surface root". **Omitted
+means unconstrained** — never write an empty list (that would mean "allowed
+nowhere"; the build refuses it).
+
+```yaml
+a2ui:
+  allowedParents:
+    - Accordion        # AccordionItem only makes sense inside an Accordion
+  rules:
+    - …
+```
+
+**Authoring rule — verify against element source, exactly like the
+`slots:`/`parts:` decision above.** Declare a constraint only when the
+component's own source enforces or assumes it (e.g. `stepper.class.js`
+queries `stepper-item-ui`; `segmented.class.js` warns on non-`segment-ui`
+children). A parent that adopts items through wrappers (menu.class.js's
+deliberate descendant query) must NOT constrain — a declared constraint
+stricter than the source is a defect, not documentation.
+
+Pipeline: `components.mjs` validates the shape per-yaml, cross-checks every
+referenced name against the full catalog on a full build, and forwards the
+lists onto `x-adiaui` → `catalog-a2ui_0_9.json`.
+`scripts/build/derive-genui-catalog.mjs` then translates them into the
+canonical v1.0 key space (yaml `Segmented` → catalog `SegmentedControl`) on
+`base.json`/`adia-pack.json`, where the vendored `@genui/core` validator
+enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier yamls
+(web-modules) carry constraints as dialect-catalog metadata only — modules
+have no v1.0 sidecar.
+
+---
+
 ## `status:` field — stability tier
 
 **Required** for all new components. Existing components default to `stable` if unset, but new yamls MUST set this explicitly.
@@ -45,6 +136,8 @@ css-vars:
 | `deprecated` | Has a replacement; check the component's `related:` section. Docs site shows a `danger`-variant badge labeled "deprecated". |
 | `early-access` | Customer-preview tier; release notes gate. Docs site shows an `info`-variant badge labeled "early access". |
 
+**Ratified, closed enum — compiler-enforced at build time, mirrored in the schema (ADR-0057, ratified 2026-08-15).** The five values above are the whole vocabulary; `draft` is NOT a value (the one `draft` in the estate, `embed-shell.yaml`, was corrected to `experimental` when the enum went live — a sixth value on a single occurrence is data-entry drift, not a vocabulary gap). Enforcement: `scripts/build/components.mjs:105` holds `STATUS_VALUES` and `compileComponent()` (`components.mjs:258-260`) throws on any out-of-enum `status:` at the same place it throws on a missing `component:` — so `npm run verify:components` (`node scripts/build/components.mjs --verify`, a member of the `npm run check` aggregate) hard-fails the yaml with a file-and-value error. An invalid status no longer merely skips a docs badge; it stops the build. `scripts/schemas/component.yaml.schema.json:23-27` declares the same enum (default `stable`) for the `$schema:` IDE contract, but no validator runs that file — the hand-synced constant in `components.mjs` is the live gate. `status` is orthogonal to the ADR-0050 L0–L4 tier ladder (tier = what a component is composed of; status = how much to trust its contract today), and nothing in `packages/gen-ui/engine/retrieval/` filters or ranks on it. Source: ADR-0057.
+
 **Guidance**:
 
 - Set `beta` or `experimental` at FIRST AUTHORING for any component that's not in the stable API contract yet. Don't default to `stable` and bump later — the badge is consumer-facing, and stable→beta is a downgrade signal.
@@ -57,6 +150,33 @@ css-vars:
 
 ---
 
+## `category:` field — functional grouping
+
+**Required.** Every yaml sets this; `scripts/build/components.mjs` forwards it verbatim onto the sidecar as `x-adiaui.category`, and `packages/gen-ui/engine/retrieval/catalog.js` reads it from there for every YAML-backed component — no second, hand-maintained category list for anything with a yaml SoT. `catalog.js` does still carry one small, DELIBERATE exception: a 3-entry `PSEUDO_TYPE_CATEGORY` map (`section`/`header`/`footer` → `card-child`) for `@adia-ai/a2ui` registry pseudo-types that have no yaml SoT at all (v0.9 composition slot-children, not real primitives) — nothing to derive from, so this one small map stays hand-maintained by design, not drift.
+
+| Value | When to use |
+| --- | --- |
+| `action` | A standalone, click-to-fire trigger (`button-ui`, `toggle-scheme-ui`). |
+| `agent` | AI/agent-facing surfaces — chat, trace, tool output, tabular/chart data views (`chat-thread-ui`, `agent-trace-ui`, `table-ui`, `chart-ui`, `embed-ui`). |
+| `container` | A chrome/wrapping surface that holds other content (`card-ui`, `modal-ui`, `drawer-ui`, `menu-ui`, `command-ui`). |
+| `data` | Structured/tabular data display, not a full agent surface (`tree-ui`, `heatmap-ui`). |
+| `display` | Passive content rendering — text, media, status glyphs (`text-ui`, `icon-ui`, `badge-ui`, `avatar-ui`, `link-ui`, `mark-ui`, `richtext-ui` — a non-editable renderer, not a form field). |
+| `feedback` | Status/notification/progress communication (`spinner-ui`, `inline-message-ui`, `progress-ui`, `progress-row-ui`, `step-progress-ui`, `feed-ui`, `feed-item-ui`). |
+| `form` | Data-entry composite/field-level components, not raw bindable controls (`field-ui`, `fields-ui`, `rating-ui`, `toggle-option-ui`). |
+| `input` | Bindable form controls (`input-ui`, `select-ui`, `check-ui`, `switch-ui`, `textarea-ui`, `radio-ui`). |
+| `layout` | Pure structural/spatial primitives — no content semantics of their own (`row-ui`, `col-ui`, `grid-ui`, `stack-ui`, `list-ui`). |
+| `navigation` | Wayfinding/switcher controls, including a switcher family's child items (`breadcrumb-ui`, `pagination-ui`, `menu-item-ui`, `segmented-ui`/`segment-ui`, `tabs-ui`/`tab-ui`, `stepper-ui`/`stepper-item-ui`). `toggle-group-ui` is `navigation` too, but its child `toggle-option-ui` is `form` (a wrapper/item split, like `menu-ui`/`menu-item-ui` — not a same-category pair). |
+| `shells` | Page-level app-shell composites (`simple-shell-ui` and its siblings). |
+| `utility` | Non-visual/accessibility helpers (`skip-nav-ui`, `visually-hidden-ui`). |
+
+**Ratified, closed enum — compiler-enforced at build time, mirrored in the schema (ADR-0065).** These twelve values are the whole vocabulary; the census that ratified them found 18 free-form values in live use (typos like `forms`/`data-display`, one-off singletons, and three named misclassifications) — all folded or corrected onto this set as part of the same change. Enforcement: `scripts/build/components.mjs` holds `CATEGORY_VALUES` and `compileComponent()` throws on a MISSING `category:` field (unlike `status:`, `category:` is required, not defaulted) as well as on any out-of-enum value, the same place and severity as the `status:` check above — so `npm run verify:components` hard-fails an invalid OR absent category. `scripts/schemas/component.yaml.schema.json`'s `category` enum mirrors this list for the `$schema:` IDE contract; the hand-synced constant in `components.mjs` is the live gate, same relationship as `status`. Source: ADR-0065.
+
+**A sibling family (a wrapper + its child items, e.g. `tabs-ui`/`tab-ui`) is not required to share one category by default** — `menu-ui` (`container`) + `menu-item-ui` (`navigation`) is a deliberate, working split. Where a family's sibling values disagreed with no evident rationale, ADR-0065 unified them; new families should pick per-component, not assume unification is required.
+
+**Sidecar emission**: `x-adiaui.category` field in `<name>.a2ui.json`. `packages/gen-ui/engine/retrieval/catalog.js`'s `buildCatalog()` reads this directly per entry — no separate registration step.
+
+---
+
 ## `props:` field — prop schemas
 
 Each prop is a top-level key inside `props:`. The full prop schema:
@@ -160,6 +280,46 @@ string-list schema is the exact silent-mismatch shape.
 
 ---
 
+## `data-msg-*` — exempt component-side config family (gh#1332/#1464, ADR-0060)
+
+`data-msg-required` / `data-msg-pattern` / `data-msg-minlength` /
+`data-msg-maxlength` / `data-msg-min` / `data-msg-max` / `data-msg-bad-input`
+are read directly by form-associated components (`core/form.js`'s shared
+`UIFormElement` validation path, plus `input`, `select`, `tags-input`,
+`code`, `date-range-picker`, `datetime-picker`, and
+`payment-method-form.class.js`) to override a native constraint-violation's
+default message with a consumer-supplied string.
+
+**Disposition: EXEMPT — never declared as a yaml `states:`/`props:` entry.**
+Both yaml surfaces this contract offers are the wrong shape for this family:
+
+- `states:` declares **presence-boolean host state the component itself
+  reflects outward** (idle/loaded/error, this file's own §Reserved section's
+  neighbor pattern) — `data-msg-*` carries no state at all; it is a
+  consumer-authored string the component only ever *reads*, never sets.
+- `props:` would need one string prop per validation-message key, repeated
+  across every one of the 7+ consuming components — but the read path is
+  `core/form.js`'s shared mixin, not any single component's own yaml SoT.
+  Declaring it per-component would multiply one shared mixin contract across
+  every consumer's yaml with no single owning SoT to declare it once — a
+  cross-cutting mixin-contract change, not a per-component yaml edit.
+
+ADR-0060's own boundary discriminator (§Decision 3) already places this
+family outside the trait-tier `data-*` ratification and explicitly routes it
+"to gh#1332's Category A/D triage for its own converge-or-ratify call" — this
+section IS that call. The family stays `data-*`, undeclared in any yaml,
+with its contract documented at the shared source instead: `core/form.js`'s
+own header JSDoc (the mixin all consumers share) and the canonical
+`form-system` pattern doc (`packages/web-components/patterns/form-system/
+form-system.examples.html`, mirrored at `site-a2ui/pages/
+site__patterns__form-system.a2ui.json`) — both already enumerate the full
+family with a worked example. A future architectural pass that wants to
+promote this to a declared per-component contract needs its own ADR (the
+scope is a mixin-wide contract change, not a small-ticket edit); nothing
+here forecloses that, it only records today's call.
+
+---
+
 ## Build pipeline
 
 ```bash
@@ -171,7 +331,7 @@ node scripts/build/components.mjs --verify   # same as above, direct invocation
 The build:
 
 1. Reads every `<name>.yaml` under `packages/web-components/components/` and `packages/web-modules/<cluster>/`
-2. Validates against `scripts/schemas/component.yaml.schema.json`
+2. Hand-checks the source yaml in `compileComponent()` — missing `component:` and out-of-enum `status:` both throw (`components.mjs:255-260`). Amended 2026-08-16 per ADR-0057: it does NOT run `scripts/schemas/component.yaml.schema.json` as a validator (an earlier revision of this list claimed it did); the schema file is documentation + IDE contract only.
 3. Emits `<name>.a2ui.json` (the sidecar) co-located with the yaml + js + css
 4. Emits the `traits/_catalog.json` aggregate
 5. `--verify` mode: re-runs steps 1-4 in-memory and fails if any sidecar drifts from disk content (CI hard-fail)
@@ -263,4 +423,4 @@ After the playbook, the component is consumable by the docs site, the A2UI runti
 - [css-patterns.md](css-patterns.md) — light-DOM CSS cascade rules
 - [api-contract.md](api-contract.md) — props/events/slots conventions
 - [authoring-cycle.md](authoring-cycle.md) — the 5-step authoring procedure
-- `scripts/schemas/component.yaml.schema.json` — JSON Schema (authoritative)
+- `scripts/schemas/component.yaml.schema.json` — JSON Schema (documented contract + IDE aid; not run as a validator — `compileComponent()` enforces only `component:` and the `status` enum, see §Build pipeline)

package/skills/ssr-compatibility/SKILL.md

@@ -3,9 +3,10 @@ name: ssr-compatibility
 description: >-
   Answers why an AdiaUI component crashes, drops content, or renders wrong
   under SSR (linkedom/Astro consumers) — the four known failure shapes,
-  what's fixed vs open, how to test without a linkedom install. Use when
+  what's fixed vs open, how to prove a fix under the linkedom shim gate. Use when
   asked "does this work under SSR", why a component crashes on
-  attachInternals/ResizeObserver/adoptedStyleSheets under a DOM shim, why
+  attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/`instanceof Node`
+  under a DOM shim, why
   table-ui/chart-ui/select-ui or a container CE renders empty or loses its
   nested children when server-rendered, whether it's safe to call
   getBoundingClientRect() synchronously in connectedCallback, or whether a
@@ -64,10 +65,10 @@ Full symptom → root-cause → status detail, cited to the actual shipped/open
 | Ask | Answer from |
 | --- | --- |
 | "why does `<text-ui>`/`<avatar-ui>`/a container lose its content under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §2 — shape 2, NARROWED (doesn't currently reproduce against any shipped component; see the survey before assuming a new report fits this shape) |
-| "why does this crash / throw at construction under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 |
+| "why does this crash / throw at import, construction or connect under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED twice (gh#285, gh#1430/#1436) and now GATED by `scripts/dev/ssr-linkedom-smoke.mjs`; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 — feature-detect the API, never `typeof window` |
 | "is this connect-time `getBoundingClientRect()`/measurement read safe" | [`failure-shapes.md`](references/failure-shapes.md) §3 + [`guard-patterns.md`](references/guard-patterns.md) §3 — the fixed component's exact shape, and the "unknown ≠ confirmed" principle to apply elsewhere |
 | "what's fixed vs still open for SSR support" | [`status-ledger.md`](references/status-ledger.md) — re-verify against `gh issue view` before trusting it, it drifts |
-| "how do I test an SSR gap — we have no linkedom installed" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — the delete/try/finally pattern, and what it does NOT prove |
+| "how do I test / prove an SSR gap or fix" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — run the linkedom shim gate first (`node scripts/dev/ssr-linkedom-smoke.mjs`, the consumer's exact global surface), then the unit-level delete/try/finally pattern and what it does NOT prove |
 | "what's the consumer's current workaround, and can they drop it yet" | [`consumer-workarounds.md`](references/consumer-workarounds.md) |
 | "table/chart/select renders empty in the SSR response" | [`failure-shapes.md`](references/failure-shapes.md) §4 — shape 5, CLOSED (table-ui's `data="[…]"` attribute); check whether the reporting component is registered server-side first if it still reproduces |
 
@@ -76,7 +77,11 @@ Full symptom → root-cause → status detail, cited to the actual shipped/open
 Every fix pattern this pack cites ([`guard-patterns.md`](references/guard-patterns.md))
 carries the reasoning for why it looks the way it does — the no-op `ElementInternals`
 shim exists because leaving the field `undefined` would relocate a crash, not remove
-it; deletion-based testing exists because this repo has no `linkedom` devDependency.
+it; the linkedom shim gate (`scripts/dev/ssr-linkedom-smoke.mjs`, gh#1430) exists
+because happy-dom implements every API in the documented shape-1 cases that linkedom
+lacks (matchMedia, rAF, the Observers, `Node`/`Element` globals, rect APIs), so the
+unit suite is blind to that class by construction — deletion-based testing is the unit-level complement, not
+the proof.
 If a new case doesn't fit an existing pattern's reasoning, that's a signal to design a
 new pattern. Route it through `primitive-authoring` — don't force-fit the nearest existing
 shape.

package/skills/ssr-compatibility/references/consumer-workarounds.md

@@ -21,12 +21,20 @@ and force-assigned `document.adoptedStyleSheets = []`. Two named fragilities:
   `globalThis.ResizeObserver` affects EVERY component and every other library in the
   same process, not just AdiaUI's.
 
-**Status as of gh#285's fix (PR #292, merged 2026-07-17): this shim should no longer
-be necessary** — the framework guards its own call sites now. This pack's own routing
-corpus / the issue thread is where confirmation from the consumer would land; don't
-assume it's been removed without checking the issue's comment thread for that
-confirmation, since a consumer removing a workaround is THEIR change, not something
-this fix does automatically.
+**Status as of gh#285's fix (PR #292, merged 2026-07-17): the AdiaUI-facing sections
+of this shim are no longer necessary** — the framework guards its own call sites now.
+**Consumer-confirmed 2026-08-17 (gh#1430 §Additional context, against 0.8.40):**
+`attachInternals`, the four Observer stubs and `adoptedStyleSheets` are all confirmed
+unnecessary. **But gh#285's closing comment over-reached** in saying the shim "as a
+whole" can go: two of its sections patch `CustomElementRender.prototype` — a
+`setAttribute` null-guard and a `renderShadow` null-guard — i.e. they patch
+`custom-elements-ssr` itself, which reads `shadowRoot.innerHTML` unconditionally and
+AdiaUI is light-DOM-only, so `shadowRoot` is always `null`. Remove those two and every
+SSR'd fixture dies with `Cannot read properties of null (reading 'innerHTML')`. No fix
+in this repo can retire them; they belong to the renderer. Tell the next consumer that
+explicitly rather than "the shim is unnecessary". (Also from that trial: `matchMedia`
+was a further AdiaUI-side gap the #292 sweep missed — fixed by gh#1430, so a
+`matchMedia` stub is not needed either from the version carrying it.)
 
 ## Attribute-only SSR registration restriction (gh#284 — likely no longer necessary, unconfirmed)