@adia-ai/adia-ui-forge 0.8.57 → 0.8.58

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -65,7 +65,7 @@ has no standing replacement — see ADR-0072 Decision 2 / gh#2410 for the
 closure record.
 
 All paths repo-relative. Specs worth reading before structural changes:
-`.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
+`.claude/docs/specs/a2ui-v1.0-catalog-guide.md` (protocol + catalog format),
 `.claude/docs/specs/genui-multiturn-architecture.md` (state cache, refiner,
 op format), `.claude/docs/specs/genui-chunk-marker.md` (chunk attributes),
 `.claude/docs/conventions/gen-ui-pipeline.md` (harvester wiring + embedding

package/skills/demo-audit/references/admin-shell-anatomy.md

@@ -30,7 +30,15 @@ the live admin-dashboard example.
    (there is no `<theme-picker-ui>`)
 9. `<admin-scroll>` wrapping optional `<aside data-subnav hidden>` +
    `<router-ui>` (or `<admin-page>` directly for non-routed)
+   **[deprecated 2026-09-01, ADR-0098]** `admin-scroll` is a wholesale
+   rename to `page-scroll` (both modes carried over); `admin-scroll` stays
+   as a working compat alias for the deprecation window only.
 10. `<admin-page>` with `<admin-page-header>` + `<admin-page-body>`
+    **[deprecated 2026-09-01, ADR-0098]** The `admin-page` family is
+    retired deprecate-then-delete in favor of `page-ui[band]` — `page-ui`
+    is now the one canonical page-chrome primitive; this anatomy still
+    describes the pre-migration shape for auditing legacy surfaces during
+    the deprecation window.
 11. `<admin-statusbar>` at content footer (version strip) — ★ commonly missing
 12. Second `<admin-sidebar slot="trailing">` (inspector rail, hidden by
     default) — strongly recommended
@@ -56,7 +64,7 @@ the live admin-dashboard example.
 | content topbar missing `[data-spacer]` / `[data-actions]` | warning — part 7 |
 | content missing trailing `<admin-statusbar>` | warning — part 11 |
 | sidebar topbar contains only plain text | warning — part 3 context switcher |
-| `<admin-scroll>` missing around `<admin-page>` | critical — part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+page wrapper the content renders flush with the topbar, no margins) |
+| `<admin-scroll>` missing around `<admin-page>` | critical — part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+page wrapper the content renders flush with the topbar, no margins) — **[deprecated 2026-09-01, ADR-0098]** `admin-scroll`/`admin-page` describe the pre-migration shape; the successor is `page-scroll` wrapping `page-ui[band]` |
 
 ## Opt-out contract
 

package/skills/demo-audit/references/app-shell-pitfalls.md

@@ -20,7 +20,7 @@ may stall — wait 30s, re-run.
 | 4 | Top-level `await` without async setup wrap | `[setup-failed]` console error | `export default async function setup(host) { … }` |
 | 5 | Vite import-analysis 500 on dynamic import | `[network-4xx] 500` for `./<name>.contents.js` | add `/* @vite-ignore */` to the dynamic import |
 | 6 | icon-ui not imported despite `<icon-ui>` / `[icon=…]` / icon-rendering composites | `[icon-ui-missing]` | `import "/packages/web-components/components/icon/icon.js"` |
-| 7 | `<admin-page-body>` emitted without its `<admin-page>` ancestor (gh#981) | *(no audit-app-shells.mjs tag — apps/-only script, doesn't sweep this surface)* | wrap in `<admin-page>` — `admin-page > admin-page-body { flex:1; … }` (`admin-shell.bespoke.css:144`) is a direct-child selector; without that literal parent, `admin-page-body` falls back to UA `display:inline` |
+| 7 | `<admin-page-body>` emitted without its `<admin-page>` ancestor (gh#981) | *(no audit-app-shells.mjs tag — apps/-only script, doesn't sweep this surface)* | wrap in `<admin-page>` — `admin-page > admin-page-body { flex:1; … }` (`admin-shell.bespoke.css:144`) is a direct-child selector; without that literal parent, `admin-page-body` falls back to UA `display:inline` — **[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-body` are retired deprecate-then-delete; author new surfaces with `page-ui[band]` instead |
 
 Secondary signals: `[collapsed-element]` (registered but 0px tall —
 `audit-app-shells.mjs`'s own threshold is <4px, so a shallower-but-still-broken

package/skills/package-release/references/cut-procedure.md

@@ -137,6 +137,9 @@ node scripts/release/check-estate-split-latch.mjs           # 29 no lockstep cut
 npm run check:catalog-tiers                    # 30 tier-index.json vs committed catalog (gh#1494 — ADR-0069 moved its PR-blocking half to derived-resync; the pre-cut roster re-asserts Class-R freshness before a tag. Gate 13 can't catch this: the harvester hashes tier-index.json as a SOURCE)
 npm run check:codex-manifests-fresh            # 31 Codex plugin.json + openai.yaml vs .claude-plugin/plugin.json SoT (gh#1888)
 npm run check:harness-manifests-fresh          # 32 Hermes/Pi plugin.yaml + __init__.py + prompts vs .claude-plugin/plugin.json + commands SoT (gh#1954)
+npm run verify:patterns-index                  # 33 pattern-index.md (mcp + adia-ui-factory) vs corpus source
+node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details  # 34 yaml events: blocks vs runtime dispatch — no phantom/missing events (gh#2829)
+node scripts/release/check-yaml-impl-coverage.mjs --strict                       # 35 yaml schema fields vs implementation coverage (gh#2829)
 ```
 
 **Gate 29 was the ADR-0048 latch; since P5 it is a permanent invariant.** Between P1 and P5 the repo was correct in-repo but deliberately **not publishable** (old-name stubs marked `private: true` that the roster still mapped, plus dependency edges onto workspace packages no cut published), and a cut in that window would have shipped broken packages that npm cannot unpublish. **P5 cleared it by landing the real thing** — the six stubs became publishable shims and `PACKAGE_ROSTER` gained the three remaining new names, at which point all 9 offending edges resolved and the gate went green on its own. No gate logic was changed.
@@ -437,6 +440,28 @@ Deploy discipline (the release tenant of the demo-site host; VM/service ops belo
 
 - Any docs **route** cited to the operator or in notes must exist in `site/sitemap.json` (`grep '"path":'`) — a plausible-looking route that isn't in the sitemap renders blank.
 
+**Milestone close (ADR-0103, gh#2729, dated addendum 2026-09-01).** Every
+lockstep cut has an open GitHub Milestone named `vX.Y.Z` (one per cut,
+created ahead of time or by the first PR scheduled into it). Close it here,
+after the GH releases above and before release notes:
+
+```bash
+number=$(gh api repos/adiahealth/gen-ui-kit/milestones --jq \
+  '.[] | select(.title == "vX.Y.Z") | .number')
+gh api -X PATCH "repos/adiahealth/gen-ui-kit/milestones/$number" -f state=closed
+```
+
+Any issue still open in that milestone at close time either ships anyway
+(re-tag it into the milestone that actually shipped it — never leave an
+already-shipped issue's milestone wrong) or slips to the next milestone
+(re-tag now, don't leave the closed milestone showing open issues). Create
+the NEXT cut's milestone here too, so scheduling work for it doesn't wait on
+this cut's tag:
+
+```bash
+gh api repos/adiahealth/gen-ui-kit/milestones -f title="vNEXT.Y.Z" -f state=open
+```
+
 Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
 
 ## §Step 11 — Author release notes (default)

package/skills/package-release/scripts/gate-roster.mjs

@@ -155,6 +155,14 @@ export const GATE_ROSTER = [
   // manifest trees. Appended, not inserted — same numbering discipline as
   // gate 30/31/32.
   { n: 33, cmd: 'npm run verify:patterns-index', what: 'pattern-index.md (mcp + adia-ui-factory) vs corpus source' },
+  // gh#2829: gh#2808/PR #2815 (ADR-0108 ticket 3) promoted both yaml gates
+  // below into `npm run check` but deliberately left this pre-cut roster
+  // untouched — a cut could still ship a yaml `events:` block that phantoms
+  // or misses a runtime dispatch, or a schema field with no implementation
+  // coverage, without either failing the pre-flight. Appended, not
+  // inserted — same numbering discipline as gate 30/31/32/33.
+  { n: 34, cmd: 'node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details', what: 'yaml events: blocks vs runtime dispatch (no phantom/missing events)' },
+  { n: 35, cmd: 'node scripts/release/check-yaml-impl-coverage.mjs --strict', what: 'yaml schema fields vs implementation coverage' },
 ];
 
 // -- CLI ------------------------------------------------------------------

package/skills/primitive-authoring/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: primitive-authoring
 description: >-
-  Author or modify AdiaUI framework source inside the monorepo — primitives
+  Author or modify AdiaUI framework source inside the monorepo — components
   (packages/web-components), shells/composites (packages/web-modules), yaml
-  SoTs, demos. Use to add a new primitive, fix a prop/slot/attribute/CSS
+  SoTs, demos. Use to add a new component, fix a prop/slot/attribute/CSS
   variant, update a yaml, build or fix a shell (chat-shell, admin-shell,
   editor-shell — sidebar/pane/bespoke-tier composition), promote repeated
   inline content into a shared module, audit a component's four-axis
@@ -100,5 +100,8 @@ then the full sequence — never suppress.
   [authoring-cycle.md](references/authoring-cycle.md) Step 3 are fixed
   immediately; contract-neutral pattern drift is proposed in review, not
   blocked on.
+- **SoT-change / component.md check**: new or changed states or aria
+  behavior on a yaml with a `component.md` sibling → component-md-authoring's
+  authored `screenReader`/`behavioral` sections may need a pass.
 - A one-line bug that touches no props, CSS contract, or lifecycle doesn't
   need this skill's overhead — just read the code and edit.

package/skills/primitive-authoring/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Primitive Authoring"
-  short_description: "Author or modify AdiaUI framework source inside the monorepo — primitives (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."
+  short_description: "Author or modify AdiaUI framework source inside the monorepo — components (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."

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

@@ -646,6 +646,46 @@ If you author a primitive that programmatically creates another (`document.creat
 
 Source: ADR-0027.
 
+### AP-R2 · Folding two visually-converging widgets into a shared module (ADR-0101)
+
+Two widgets can converge visually — same tab-strip chrome, same header
+band, same "looks like the same component" impression on the catalog page
+— while carrying fundamentally different content models underneath. That
+visual overlap alone is not sufficient reason to extract a shared module
+or fold one into the other.
+
+`inspector-ui` (a live devtools pane: four fixed panes, content pushed in
+imperatively and repeatedly after connect via `update()`/`setHTML()`) and
+`preview-ui` (static docs demo chrome: content captured once on connect,
+shown two fixed ways) look like the same tabbed-view widget. They aren't:
+folding one into the other would force the static-capture component to
+grow a second, incompatible imperative-update mode it doesn't need for the
+job it already does correctly everywhere it's used — added surface, not
+removed surface. Extracting a shared tab-view module was evaluated and
+rejected for the same reason: no common substrate exists beneath the
+visual layer that both widgets could share without also merging their
+different content models (`tabs-ui`'s synthesized strip vs. a hand-rolled
+`role="tablist"` div built for single-panel content-swap semantics).
+
+**The resolution is a mirror, not a merge:** keep both components on their
+own contracts; restyle the trailing one to match the leading one's chrome
+via scoped CSS only (`@scope (inspector-ui)` overrides copying
+`preview-ui`'s header-tab anatomy, tokens, and typography) — no shared
+component, no deprecation. The tradeoff this accepts: because the
+mirroring is duplicated CSS, not a shared module, a future visual change
+to the pattern's source component doesn't automatically propagate: check
+the mirrored block for parallel drift when you next touch the pattern
+that's being mirrored — the same "primitives that compose primitives
+don't auto-import" discipline ADR-0027 already requires (AP-R1, above),
+now applied to a duplicated CSS block instead of a duplicated import.
+
+Before extracting a shared module for two things that "look the same,"
+verify they'd actually share the extracted contract (props, update
+semantics, lifecycle) — not just its rendered chrome. If they wouldn't,
+mirror the chrome and keep both components separate.
+
+Source: ADR-0101.
+
 ---
 
 ## Rapid-fire anti-patterns (mined from incident history)

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

@@ -62,6 +62,18 @@ Every component CSS file has exactly this shape:
 
 When a parent tries to override `--component-bg`, specificity beats them. The zero-specificity layer is the contract.
 
+## Region elements never self-style (2026-09-01, ADR-0105)
+
+Native `<header>`/`<section>`/`<footer>` and `<header-ui>`/`<section-ui>`/`<footer-ui>` (a CSS-only slot-routing anatomy stub — no JS, no events, no `.css` file of its own) are **region elements**, not components in their own right. They carry zero layout CSS. Every grid, gap, sticky rule, and slot-vocabulary variant a region renders is written in the **closest host pattern's** `@scope (host-name)` block — `page-ui`, `card-ui`, `drawer-ui`, `modal-ui`, `anchor-bar`, the shells — matching the region by tag + attribute selector (`:scope > :where(header, header-ui)`, `:has(> [slot="action"])`, etc.), never in a region-owned stylesheet.
+
+**If you're authoring a new host pattern that accepts region children, you MUST ship its `@scope` treatment for every region shape it accepts before it ships.** A host that accepts `<header-ui>` without a matching grid/sticky/slot-vocabulary block is not a lesser-but-valid host — the region element structurally cannot supply the missing layout itself, so the host renders wrong (usually unstyled block flow, or — the observed failure mode — a stale layout that packs content into the wrong shape). gh#2760 is the live example: `page-ui`'s header-band `@scope` block didn't reproduce the retired `admin-page-header`'s action-cluster grid for a multi-item `[slot="action"]` containing a block-level `<tabs-ui>`, so tabs overlapped buttons instead of getting their own row — same markup, incomplete host coverage.
+
+**Bare `<header>` vs `<header-ui>`** — both reach a host's tag-matched rules identically (`:where(header, header-ui, …)` gives them equal zero specificity). They diverge only on rules keyed off a named-slot attribute selector (`:has(> [slot="icon"])`, etc.) — and there the divergence isn't mechanical (`slot=` is decorative everywhere, ADR-0033), it's documentation: `header-ui`'s own yaml is the only place the icon/heading/description/action vocabulary is written down and steered toward by `a2ui.rules`. Use bare `<header>`/`<section>`/`<footer>` only for unstructured default-slot content; use the `-ui` stub whenever content decomposes into the slot vocabulary — that's the only path an author or the A2UI generator discovers it exists.
+
+A region element acquiring its own `.css` file (layout rules scoped to `header-ui` itself, not the host) is the anti-pattern this section exists to name — see ADR-0105 for the full rationale and the corollary above.
+
+Source: [ADR-0105](../../../../../../docs/ops/adr/adr-0105-region-elements-never-self-style.md).
+
 ## Variants vs modes — the decision tree
 
 The rule: **variants change tokens; modes change layout.**

package/skills/primitive-authoring/references/form-control-sizing.md

@@ -31,6 +31,16 @@ Decision Class 1 removes the 20ch-class field-width floor for
 floor, generalizing the `button-ui` keep-square pattern already named below
 to the field-width components.
 
+**[amended 2026-08-31, gh#2534, ADR-0095]** The square-minimum rule governs
+a primitive's own OUTER inline-size floor against its own block-size only —
+it does not reach a component's INTERNAL grid-column sizing. A token like
+`field-ui[inline]`'s `--field-label-inline-min: 10ch` floors the label
+*column* inside the component's internal grid, to keep sibling rows
+aligned — not to prevent the host itself from collapsing — so it is not
+"a `--*-min-width: 20ch`-class floor" in ADR-0095's sense and is not
+retired by the Decision above. Don't apply the square-minimum rule to an
+internal grid-column token by analogy to the field-width class.
+
 *(Historical, pre-ADR-0095 rule — superseded by the retirement above, kept
 only for context on what the old convention was.)* A
 `--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on

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

@@ -448,6 +448,13 @@ Consumers (CodeMirror layout, canvas redraw, dependent UI) listen on the shell o
 
 ### admin cluster (canonical reference)
 
+**[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-header`/
+`admin-page-body` are retired deprecate-then-delete; `admin-scroll` is
+renamed wholesale to `page-scroll`. `page-ui[band]` + `page-scroll` are
+now the canonical page-chrome pair — this cluster still describes
+`admin-shell`'s pre-migration internal composition, valid during the
+deprecation window.
+
 - **3 JS-bearing children** — `<admin-shell>` (host coordinator), `<admin-sidebar>` (resize+collapse+persist), `<admin-command>` (Cmd+K palette)
 - **7 CSS-only structural children** — `<admin-content>`, `<admin-topbar>`, `<admin-statusbar>`, `<admin-scroll>`, `<admin-page>`, `<admin-page-header>`, `<admin-page-body>`
 - **CSS bridge** — `packages/web-modules/shell/admin-shell/css/admin-shell.bespoke.css` (~240 LOC)
@@ -547,7 +554,7 @@ When you encounter a legacy reference in old documentation or commit history, th
 
 - [authoring-cycle.md](authoring-cycle.md) — general 5-step authoring procedure; shell-specific rules layer on top
 - [api-contract.md](api-contract.md) — prop naming, reflection policy
-- [css-patterns.md](css-patterns.md) — two-block `@scope`, variants vs modes
+- [css-patterns.md](css-patterns.md) — two-block `@scope`, variants vs modes; §Region elements never self-style (ADR-0105) — a shell that hosts `<header-ui>`/`<section-ui>`/`<footer-ui>` region children (e.g. a bespoke `<X-header>` wrapping one) owns their `@scope` layout the same way `page-ui`/`card-ui`/`drawer-ui`/`modal-ui` do
 - [lifecycle-patterns.md](lifecycle-patterns.md) — teardown patterns; the cleanup-closure pile and document-listener rules above layer on top
 - [token-contract.md](token-contract.md) — zero-raw-color + L3 alias rules apply identically to shells
 - [module-promotion.md](module-promotion.md) — the _different_ activity of lifting a cross-cluster reusable element (theme panel, command palette) into a shared module

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

@@ -36,6 +36,23 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 }
 ```
 
+### `@scope` donor selectors must be tag-independent when a component can swap its own rendered tag (ADR-0102, 2026-09-01)
+
+A `@scope (my-component-ui)` donor selector matches by **literal tag
+name**. That's a live gap for any component whose own contract lets it
+render as a different tag than its own custom-element name — `text-ui`
+already did this coincidentally (`variant="body"` → `<p>`,
+`variant="caption"` → `<small>`), relying on ambient/bare-tag styling
+rather than the component's own `[variant]` rules. ADR-0102 (`text-ui`'s
+`level` prop, promoting the element to a real `<h1>`-`<h6>`) made this a
+first-class case, requiring the donor selector to stay tag-independent —
+e.g. `@scope (text-ui, [data-text])` with the renderer stamping a stable
+marker attribute on every such element regardless of the resolved tag —
+so a promoted `<h2 level="2" variant="heading">` keeps its component
+styling instead of silently falling back to bare-tag `:where(hN)`
+defaults elsewhere in the cascade. Any component that can render under a
+tag other than its own name needs the same tag-independent scope check.
+
 ## Hard rules
 
 1. **Zero raw color values** anywhere in component CSS
@@ -139,7 +156,8 @@ mechanics; never work from this summary alone):
   in a component yaml, check it against the spec's attribute inventory; the
   only sanctioned collisions live in the spec's §11 Global-Attribute Exemption
   List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054;
-  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070).
+  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070;
+  `badge-ui[weight]` → `icon-ui[weight]`, ADR-0100).
 
 Beyond the global grammar, ADR-0063
 (`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies seven

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

@@ -401,6 +401,22 @@ 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.
 
+### Sentinel-0 defaults and tag-promoting props (ADR-0102, 2026-09-01)
+
+Not every escape hatch belongs on `CatalogComponentCommon` — a prop scoped
+to one component's own semantics stays on that component's own yaml, even
+when it changes the rendered tag. `text-ui`'s `level` (integer 0-6,
+default `0`) is the worked example: `0` is the sentinel for "no
+promotion, current behavior" — the same `0 = off` convention `text-ui`'s
+own `lines` prop already used (`lines: 0` = no clamp) — and `1`-`6`
+promotes the rendered element to a real native `<h1>`-`<h6>`, independent
+of `variant` (which stays presentational-only: typography tokens, never a
+tag). `deriveProps()` needs no change for this — a per-sidecar prop like
+`level` already flows into the generated catalog schema generically; only
+a `CatalogComponentCommon` universal (`slot`/`hidden`/`ariaLive`/`traits`,
+above) needs a wire-schema edit. See ADR-0102 for the full contract
+(renderer branch, dead-code removal, non-goals).
+
 ### `required: true` field
 
 **When to use**: only for props where omitting them makes the component meaningless or inaccessible.