@adia-ai/adia-ui-forge 0.8.54 → 0.8.56

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

@@ -114,13 +114,93 @@ 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`.
+lists onto `x-adiaui` → `catalog-a2ui_1_0.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.
+canonical v1.0 key space (yaml `Segmented` → catalog `Segmented`, canonical
+per gh#2116) across the five opt-out-scoped catalogs (`adia.core.json`,
+`adia.navigation.json`, `adia.data.json`, `adia.agent.json`,
+`adia.shells.json`, gh#2211/ADR-0093), where the vendored `@genui/core`
+validator enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier
+yamls (web-modules) now carry a v1.0 sidecar too and land in `adia.shells`.
+
+---
+
+## `examples:` field — a2ui example ids (semantic-id grammar, gh#2492)
+
+Each `examples[].a2ui` block is a JSON array of component nodes (the same
+`updateComponents.components[]` shape `.claude/docs/specs/a2ui-editor.md`
+documents for the editor's live doc store). That spec's line "other
+component ids are free-form (convention: `c-{n}` for generated ids)" governs
+**editor-generated** ids only — ids the editor mints when a human drags a
+component onto the canvas. It was never a license for **authored** ids
+inside a component's own yaml examples, and treating it as one produced a
+corpus-wide drift toward cryptic, positional ids (`q`, `k1`, `k1v`, `hdr`)
+that don't describe what they are once an example has more than one or two
+nodes — reported in gh#2492 against `blockquote.yaml`, `badge.yaml`,
+`aside.yaml`, `alert.yaml`, and `anchor-bar.yaml` (the last four
+corroborating it as a corpus-wide pattern, not a one-off).
+
+**Grammar — authored `a2ui.examples[]` ids only:**
+
+- **Kebab-case, role-descriptive.** The id names what the node IS or DOES in
+  the example, not its position in the array. `quote-body`, not `q` or
+  `node-2`.
+- **Unique per example.** Scoped to one `examples[]` entry, not the whole
+  yaml — reusing `header` across two examples in the same file is fine;
+  reusing an id twice inside one example is not (the renderer's flat
+  `children: string[]` lookup would collide).
+- **Compound ids read parent-then-role** for a node that belongs to a named
+  cluster: `kpi-revenue`, `kpi-revenue-value`, `kpi-revenue-label` — not
+  `k1`, `k1v`, `k1l`. This is what lets a reader studying the copy-paste-able
+  example understand the structure from the ids alone, without cross-
+  referencing the tree.
+- **Exception — the root/wrapper id may stay short when the example has
+  exactly one top-level container and the short id is still a real word**,
+  e.g. `card`, `row`, `panel`, as long as every id it contains follows the
+  grammar. A single generic wrapper doesn't need `card-wrapper-root`; a
+  wrapper's *children* still do.
+- Ids are internal wiring keys (`children: string[]` references, rendered
+  only as `data-a2ui-id`) — never user-visible copy — but they double as the
+  readable structure of the example a consumer studies, which is the whole
+  reason this grammar exists.
+
+**Before / after** (`blockquote.yaml`'s `default` example, gh#2492's
+reported repro):
+
+```jsonc
+// before
+[
+  { "id": "q", "component": "Blockquote", "cite": "…", "children": ["body"] },
+  { "id": "body", "component": "Text", "textContent": "Stay hungry. Stay foolish." }
+]
+
+// after
+[
+  { "id": "quote", "component": "Blockquote", "cite": "…", "children": ["quote-body"] },
+  { "id": "quote-body", "component": "Text", "textContent": "Stay hungry. Stay foolish." }
+]
+```
+
+```jsonc
+// before (badge.yaml chart-dashboard, positional style mixed with semantic
+// ids in the SAME example — k1/k1h/k1v alongside header-row/dash-title)
+{ "id": "k1", "component": "Card", "children": ["k1h", "k1v"] }
+
+// after
+{ "id": "kpi-revenue", "component": "Card", "children": ["kpi-revenue-label", "kpi-revenue-value"] }
+```
+
+**Enforcement**: `scripts/verify/check-example-ids.mjs` walks every yaml's
+`examples[].a2ui` nodes and reports ids that fail the grammar (a bare
+1-2 char id, a `^[a-z]\d+` positional pattern like `k1`/`c2`, non-kebab-case,
+or a within-example duplicate). gh#2492 Phase 2 swept the corpus-wide 526
+violations across 48 files to zero and flipped the gate to `npm run
+check:example-ids:strict` in the `npm run check` chain (non-zero exit on
+any violation) — a new example that violates the grammar now fails the
+build immediately, not just on a future sweep. Known gap: the checker's
+positional-pattern regex catches `letter+digits` (`k1`, `c2`) but not a
+`letter-digit-letter-digit` chain like `g1i1` — out of scope for this
+sweep (nothing flagged it), left for a future refinement.
 
 ---
 
@@ -235,7 +315,7 @@ manifest format. ADR-0066 refines it three ways:
 
 - **`origin: primitive | module` on every L0 entry** — both YAML source
   roots (web-components primitives AND web-modules composites) compile into
-  the same `catalog-a2ui_0_9.json` through one shared contract;
+  the same `catalog-a2ui_1_0.json` through one shared contract;
   `derive-catalog-tiers.mjs` stamps which root an entry came from onto
   `tier-index.json`. A module is legitimately a member of TWO rungs at two
   grains: its component API (props/events/slots) is L0, its assembled shell
@@ -283,6 +363,31 @@ props:
       - ghost
 ```
 
+### Synthesized universal props — `slot` / `hidden` / `ariaLive` / `traits`
+
+`deriveProps()` (`scripts/build/derive-genui-catalog.mjs`) prepends three
+props to every component's generated catalog schema before it ever reads a
+yaml's own `props:` block: `slot: {type: string}`, `hidden: {type:
+boolean}`, `ariaLive: {type: string}` (REQ-013 accessibility pair, gh#1353).
+**No yaml SoT declares any of these** — they're synthesized, not authored,
+and a sidecar that ever DOES declare one of these keys itself simply
+overwrites the synthesized definition.
+
+**Decided but not yet implemented:** ADR-0097
+(`docs/ops/adr/adr-0097-traits-as-a2ui-synthesized-universal-prop.md`,
+ratified via PR #2524) rules that `traits: {type: string}` becomes a fourth
+member of this synthesized set, carrying the same space-separated grammar
+as the existing HTML `[traits="…"]` declarative attribute
+(`.claude/docs/specs/traits.md`, "Method 3" — `"ripple confetti-burst"`,
+not a JSON array) — making `traits` legal on every component's A2UI wire
+schema with no renderer change, and, once wired, checked by
+`catalog-validator.js` against the live trait registry
+(`packages/web-components/traits/_catalog.json`) with a **hard FAIL on an
+unknown trait name** (the same rejection behavior the raw HTML mechanism
+already has). As of this writing `deriveProps()` still synthesizes only the
+three props above and `catalog-validator.js` has no trait-name check —
+gh#2513 tracks the build.
+
 ### `required: true` field
 
 **When to use**: only for props where omitting them makes the component meaningless or inaccessible.
@@ -427,7 +532,7 @@ The build:
 **Downstream of the sidecars — two more derived artifacts (gh#970's release-PR stop):**
 
 ```bash
-node scripts/build/derive-genui-catalog.mjs   # genui base.json + adia-pack.json derive FROM the sidecars
+node scripts/build/derive-genui-catalog.mjs   # genui's five opt-out-scoped catalogs derive FROM the sidecars
 npm run check:genui-catalog                    # the drift gate that fails PR CI if you skip the above
 ```