@adia-ai/adia-ui-forge 0.1.2

package/skills/adia-ui-authoring/references/worked-example.md

@@ -0,0 +1,351 @@
+# Worked Examples
+
+Two annotated examples: a light presentation component (`<badge-ui>`) and a form-associated component (`<counter-ui>`). Copy the structure; adapt the content.
+
+## Example 1 — Light presentation component: `<badge-ui>`
+
+A small inline container for status labels. Supports cosmetic variants (accent/success/danger) and an optional remove button that fires a `remove` event.
+
+### File layout
+
+```text
+packages/web-components/components/badge/
+  badge.js
+  badge.css
+```
+
+### `badge.js`
+
+```javascript
+import { AdiaElement } from '../../core/element.js';
+
+/**
+ * <badge-ui> — Compact inline status label.
+ *
+ * Props:
+ *   variant    — 'neutral' | 'accent' | 'success' | 'danger' (default 'neutral')
+ *   removable  — show an inline × button that fires 'remove' on click
+ *
+ * Events:
+ *   remove — user clicked the × button (bubbles)
+ */
+class AdiaBadge extends AdiaElement {
+  static properties = {
+    variant:   { type: String,  default: 'neutral', reflect: true },
+    removable: { type: Boolean, default: false,     reflect: true },
+  };
+
+  static template = () => null;
+
+  #removeBtn = null;
+
+  #onRemove = (e) => {
+    e.stopPropagation();
+    this.dispatchEvent(new CustomEvent('remove', { bubbles: true }));
+  };
+
+  connected() {
+    // Lazy-append the remove button on first render when the attribute is present.
+    // If authors want to control the markup, they can pre-slot their own button
+    // and we skip the injection.
+    if (this.removable && !this.querySelector('[data-badge-remove]')) {
+      this.#removeBtn = document.createElement('button');
+      this.#removeBtn.type = 'button';
+      this.#removeBtn.setAttribute('data-badge-remove', '');
+      this.#removeBtn.setAttribute('aria-label', 'Remove');
+      this.#removeBtn.textContent = '×';
+      this.appendChild(this.#removeBtn);
+      this.#removeBtn.addEventListener('click', this.#onRemove);
+    }
+  }
+
+  disconnected() {
+    this.#removeBtn?.removeEventListener('click', this.#onRemove);
+    this.#removeBtn = null;
+  }
+}
+
+customElements.define('badge-ui', AdiaBadge);
+export { AdiaBadge };
+```
+
+**Annotations:**
+
+- **Class name `AdiaBadge`, tag `badge-ui`** — three-way naming.
+- **`variant` default `'neutral'`** — string enum, default is the absent- attribute state. No special behavior to "opt into."
+- **`removable: default false`** — Boolean false (rule 1). Reflects so CSS can match `:scope[removable]`.
+- **`#removeBtn` private field** — cached DOM ref, nulled on teardown.
+- **`#onRemove` stable arrow** — reference equality works for `removeEventListener`.
+- **Symmetric connected/disconnected** — single listener, single removal.
+- **Idempotent `connected()`** — checks `querySelector('[data-badge-remove]')` before injecting, so an author who pre-slots their own button isn't overridden.
+
+### `badge.css`
+
+```css
+@scope (badge-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --badge-bg:         var(--a-bg-muted);
+    --badge-fg:         var(--a-fg);
+    --badge-border:     1px solid var(--a-border-subtle);
+    --badge-radius:     var(--a-radius-sm);
+    --badge-padding:    var(--a-space-1) var(--a-space-2);
+    --badge-gap:        var(--a-space-1);
+    --badge-font-size:  var(--a-caption-size);
+  }
+
+  :scope {
+    /* ── Base styles — consume component tokens only ── */
+    display: inline-flex;
+    align-items: center;
+    gap: var(--badge-gap);
+    padding: var(--badge-padding);
+    background: var(--badge-bg);
+    color: var(--badge-fg);
+    border: var(--badge-border);
+    border-radius: var(--badge-radius);
+    font-size: var(--badge-font-size);
+    line-height: 1;
+    white-space: nowrap;
+  }
+
+  /* ── Variants — token-only overrides ── */
+  :scope[variant="accent"] {
+    --badge-bg: var(--a-accent-bg);
+    --badge-fg: var(--a-accent-fg);
+    --badge-border: 1px solid transparent;
+  }
+  :scope[variant="success"] {
+    --badge-bg: var(--a-success-bg);
+    --badge-fg: var(--a-success-fg);
+    --badge-border: 1px solid transparent;
+  }
+  :scope[variant="danger"] {
+    --badge-bg: var(--a-danger-bg);
+    --badge-fg: var(--a-danger-fg);
+    --badge-border: 1px solid transparent;
+  }
+
+  /* ── Removable state ── */
+  :scope[removable] > [data-badge-remove] {
+    all: unset;
+    cursor: pointer;
+    padding: 0 var(--a-space-1);
+    margin-inline-start: var(--a-space-1);
+    color: inherit;
+    opacity: 0.7;
+    border-radius: var(--a-radius-sm);
+  }
+  :scope[removable] > [data-badge-remove]:hover {
+    opacity: 1;
+    background: color-mix(in oklab, currentColor 15%, transparent);
+  }
+  :scope[removable] > [data-badge-remove]:focus-visible {
+    outline: 2px solid var(--a-focus-ring);
+    outline-offset: 1px;
+  }
+}
+```
+
+**Annotations:**
+
+- **Two blocks:** `:where(:scope)` for tokens, `:scope` for base. Variants and state third.
+- **Variants override tokens only.** No `display`, `padding`, etc. in the variant bodies — they just reassign the component's token values.
+- **Zero raw colors.** Every color is a token.
+- **Zero raw px** — spacing via `--a-space-*`, radius via `--a-radius-*`. The only numeric literal is `1px` for the border (allowed carve-out).
+- **Stem `--badge-*`** matches the scope tag `badge-ui`.
+- **`color-mix()` on `currentColor`** is the idiomatic hover tint — stays theme-aware without introducing a new token.
+
+---
+
+## Example 2 — Form-associated component: `<counter-ui>`
+
+A numeric input that shows value + increment/decrement buttons. Form- participating — submits a string value with the host form.
+
+### `counter.js`
+
+```javascript
+import { AdiaFormElement } from '../../core/form.js';
+
+/**
+ * <counter-ui> — Integer counter with +/− controls. Form-associated.
+ *
+ * Props:
+ *   value — number, default 0 (syncs to form value as string)
+ *   min   — number, default null (no lower bound)
+ *   max   — number, default null (no upper bound)
+ *   step  — number, default 1
+ */
+class AdiaCounter extends AdiaFormElement {
+  static properties = {
+    ...AdiaFormElement.properties,
+    value: { type: Number,  default: 0,    reflect: true },
+    min:   { type: Number,  default: null, reflect: true },
+    max:   { type: Number,  default: null, reflect: true },
+    step:  { type: Number,  default: 1,    reflect: true },
+  };
+
+  static template = () => null;
+
+  #decBtn = null;
+  #incBtn = null;
+  #valueEl = null;
+
+  #onDecrement = () => this.#commit(this.value - this.step);
+  #onIncrement = () => this.#commit(this.value + this.step);
+
+  #commit(next) {
+    if (this.min != null) next = Math.max(this.min, next);
+    if (this.max != null) next = Math.min(this.max, next);
+    if (next === this.value) return;
+    this.value = next;
+    this.syncValue(String(next)); // inherited from AdiaFormElement
+    this.dispatchEvent(new Event('change', { bubbles: true }));
+    this.render();
+  }
+
+  connected() {
+    super.connected(); // registers ElementInternals — do not omit
+
+    if (!this.querySelector('[data-counter-dec]')) {
+      this.innerHTML = `
+        <button type="button" data-counter-dec aria-label="Decrement">−</button>
+        <span data-counter-value>${this.value}</span>
+        <button type="button" data-counter-inc aria-label="Increment">+</button>
+      `;
+    }
+
+    this.#decBtn   = this.querySelector('[data-counter-dec]');
+    this.#incBtn   = this.querySelector('[data-counter-inc]');
+    this.#valueEl  = this.querySelector('[data-counter-value]');
+
+    this.#decBtn?.addEventListener('click', this.#onDecrement);
+    this.#incBtn?.addEventListener('click', this.#onIncrement);
+  }
+
+  disconnected() {
+    super.disconnected(); // unregisters form participation
+    this.#decBtn?.removeEventListener('click', this.#onDecrement);
+    this.#incBtn?.removeEventListener('click', this.#onIncrement);
+    this.#decBtn = null;
+    this.#incBtn = null;
+    this.#valueEl = null;
+  }
+
+  render() {
+    if (this.#valueEl) this.#valueEl.textContent = String(this.value);
+  }
+}
+
+customElements.define('counter-ui', AdiaCounter);
+export { AdiaCounter };
+```
+
+**Annotations:**
+
+- **`AdiaFormElement` superclass** — inherits `name`, `disabled`, `required` etc. via the spread.
+- **`super.connected()` / `super.disconnected()`** — both present. Without them, form association silently fails.
+- **`min`/`max` default `null`** — no magic sentinels. `null` = "no constraint."
+- **`#commit()` is the one-place-value-changes** — clamps, short-circuits on no-op, fires `change`, calls `syncValue`, triggers `render()`.
+- **`syncValue(String(next))`** — inherited from `AdiaFormElement`, updates the form-submitted string representation.
+- **Two stable handlers** — `#onDecrement`, `#onIncrement`. Both paired in `disconnected()`.
+- **`render()` updates internal DOM** only when a reflected prop (`value`) changes and CSS selectors can't express the update (text content). CSS handles the disabled state via `:scope[disabled]`.
+
+### `counter.css`
+
+```css
+@scope (counter-ui) {
+  :where(:scope) {
+    --counter-bg:         var(--a-bg);
+    --counter-fg:         var(--a-fg);
+    --counter-border:     1px solid var(--a-border);
+    --counter-radius:     var(--a-radius);
+    --counter-gap:        var(--a-space-2);
+    --counter-padding:    var(--a-space-1) var(--a-space-2);
+    --counter-btn-size:   var(--a-size-sm);
+  }
+
+  :scope {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--counter-gap);
+    padding: var(--counter-padding);
+    background: var(--counter-bg);
+    color: var(--counter-fg);
+    border: var(--counter-border);
+    border-radius: var(--counter-radius);
+  }
+
+  :scope > [data-counter-dec],
+  :scope > [data-counter-inc] {
+    all: unset;
+    width: var(--counter-btn-size);
+    height: var(--counter-btn-size);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    border-radius: var(--a-radius-sm);
+  }
+
+  :scope > [data-counter-dec]:hover,
+  :scope > [data-counter-inc]:hover {
+    background: var(--a-bg-muted);
+  }
+
+  :scope > [data-counter-value] {
+    min-width: 3ch;
+    text-align: center;
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* Disabled state — inherited from AdiaFormElement */
+  :scope[disabled] {
+    --counter-fg: var(--a-fg-muted);
+    --counter-border: 1px solid var(--a-border-subtle);
+    pointer-events: none;
+    opacity: 0.6;
+  }
+}
+```
+
+**Annotations:**
+
+- **No variants** in this example — the component is functional, not cosmetic. All state communicated via tokens and the `[disabled]` selector.
+- **`:scope > [data-*]`** for slotted-like children without `::slotted()`.
+- **`pointer-events: none` + `opacity` in the disabled body** — this is allowed because `pointer-events` is an interaction property, not a layout property. Same for `cursor`.
+- **`min-width: 3ch`** is a non-layout metric (character-based), not a px literal; no carve-out needed.
+
+---
+
+## Checklist — did this component pass?
+
+Run the 30-second self-check from the main SKILL.md against each example:
+
+**Attributes:**
+
+- ✓ No Boolean `default: true`.
+- ✓ No numeric sentinels (`min: null`, `max: null`).
+- ✓ `attribute:` correct (or omitted where auto-conversion works).
+- ✓ State-bearing Booleans reflect (`removable`, inherited `disabled`).
+- ✓ No reserved-name anti-patterns.
+- ✓ `-ui` tag + `Adia<Component>` class.
+
+**CSS:**
+
+- ✓ `@scope (component-ui)` with two blocks.
+- ✓ Variants are token-only.
+- ✓ Zero raw colors.
+- ✓ Spacing/radius via tokens; `1px` border allowed.
+- ✓ Stem matches scope tag.
+- ✓ Variants consume L2 family tokens (the component-local values in `:where(:scope)` ARE the L3 aliases; overriding them in the variant body is the pattern). No direct L2 in state-change bodies.
+
+**Lifecycle:**
+
+- ✓ Every `addEventListener` paired.
+- ✓ Stable `#field` arrows.
+- ✓ `super.connected()` / `super.disconnected()` in the `AdiaFormElement` subclass.
+- ✓ DOM refs nulled.
+- ✓ `disconnected()` declared once.
+
+Pass. Ship.

package/skills/adia-ui-authoring/references/yaml-contract.md

@@ -0,0 +1,224 @@
+# YAML component contract — `<name>.yaml` schema
+
+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.
+
+---
+
+## Canonical fields (top-level)
+
+```yaml
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$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
+version: 1                   # Schema version (always 1 for now)
+status: stable               # Stability tier — see §status field below
+description: >-
+  Short one-paragraph description of what the component does and when
+  to use it. Used by the docs site, sidecar, and a2ui registry. Be
+  concrete about behavior + appearance, not generic ("a button").
+props:
+  …                          # Prop schemas — see §props field below
+events:
+  …                          # Event schemas — fired by the component
+slots:
+  …                          # Named slot semantics
+css-vars:
+  …                          # CSS custom properties the component reads
+```
+
+---
+
+## `status:` field — stability tier
+
+**Required** for all new components. Existing components default to `stable` if unset, but new yamls MUST set this explicitly.
+
+| Value | When to use |
+| --- | --- |
+| `stable` | Public API contract; safe for consumers to depend on. The vast majority of shipped components. No docs-site badge. |
+| `beta` | Functional but API may change in MINOR releases. Docs site shows a `warning`-variant `<tag-ui>` badge labeled "beta". |
+| `experimental` | Early prototype; expect breaking changes. Docs site shows a `ghost`-variant badge labeled "experimental". |
+| `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". |
+
+**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.
+- Only set `stable` after the component has shipped at least one MINOR cycle and gathered consumer feedback. The bar for `stable` is "no API changes anticipated in the next 3 MINOR releases."
+- `deprecated` requires a `related:` entry pointing at the replacement. Without one, consumers can't recover.
+
+**Sidecar emission**: `x-adiaui.status` field in `<name>.a2ui.json`. The docs site (`site/site.js`) reads this and injects the badge automatically — no HTML change needed in `<name>.examples.html`.
+
+**Verification**: `grep -L '^status:' packages/web-components/components/*/*.yaml` should return empty (every yaml has a status). Run before opening any authoring PR that adds new yamls.
+
+---
+
+## `props:` field — prop schemas
+
+Each prop is a top-level key inside `props:`. The full prop schema:
+
+```yaml
+props:
+  label:
+    description: >-
+      Visible label for the field. Wires aria-labelledby on the
+      editable surface so screen readers announce it.
+    type: string              # string | number | boolean | enum
+    default: ""               # default value (omit for boolean true)
+    required: true            # ← see §required field below
+    reflect: true             # mirror attribute ↔ property
+    enum: [primary, ghost]    # for type: enum
+    values:                   # alternative enum syntax (legacy)
+      - primary
+      - ghost
+```
+
+### `required: true` field
+
+**When to use**: only for props where omitting them makes the component meaningless or inaccessible.
+
+| Use `required: true` | Don't use `required: true` |
+| --- | --- |
+| `field-ui.label` — no visible/accessible label without it | `button-ui.variant` — has a sensible default |
+| `icon-ui.name` — nothing renders without it | `select-ui.placeholder` — useful but optional |
+| `nav-item-ui.text` — empty nav item | `card-ui.size` — affects styling, not function |
+| `chart-ui.type` — can't render a chart of "nothing" | `stat-ui.change-indicator` — optional enhancement |
+| `tabs-ui.value` — needs an initial selected tab | `tag-ui.variant` — has a default |
+
+**Heuristic**: ask "if I author `<my-component-ui></my-component-ui>` with nothing else, is the component **broken** or just **default-styled**?" If broken → mark required. If default-styled → don't.
+
+**Representative props marked required**:
+
+- `field-ui.label`
+- `icon-ui.name`
+- `nav-item-ui.text`
+- `chart-ui.type`
+- `stat-ui.label`, `stat-ui.value`
+- `check-ui.label`
+- `badge-ui.text`
+- `rating-ui.value`
+- `tabs-ui.value`
+
+**Sidecar emission**: `required: true` propagates to the JSON Schema `required` array in `<name>.a2ui.json`. The A2UI validator + MCP tools consume this array — correct marking improves validation quality on generated UI trees.
+
+**Anti-pattern**: marking ALL props required because they all "have a useful value." That defeats the validation signal. `required` is a strict-failure constraint, not a "recommended" hint.
+
+---
+
+## Reserved `data-*` attribute names (admin-shell scope)
+
+`admin-shell.helpers.css` (in `packages/web-modules/shell/admin-shell/css/`) reserves 5 layout-utility `data-*` attribute names with `admin-shell [data-X]` ancestor scoping:
+
+| Attribute | Effect | Use within `<admin-shell>` |
+| --- | --- | --- |
+| `[data-col]` | `display: flex; flex-direction: column; gap: var(--page-grid-gap)` | column layout helper |
+| `[data-row]` | `display: flex; align-items: center; gap: var(--page-grid-gap)` | row layout helper |
+| `[data-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-grid="3"`) | 2- or 3-col grid helper |
+| `[data-actions]` | `display: flex; align-items: center; gap: var(--page-actions-gap)` | action button cluster |
+| `[data-spacer]` | `flex: 1` | flex spacer for pushing content to edges |
+
+**Authoring contract**:
+
+1. **DO NOT use these attribute names for any other purpose** (table column markers, sort-state, etc.) inside `<admin-shell>` descendants. The CSS rules will apply unintended layout. Use namespaced names instead (`data-page-col`, `data-sort-col`, `data-my-actions`).
+2. **`admin-shell` ancestor is required**. An earlier dist CSS shipped bare global selectors that applied to ANY element with these attributes on ANY page loading `admin-shell.min.css` — including `<table>` headers (silent layout breakage in Safari/WebKit). Source + dist now both prefix `admin-shell` ancestor. This is a hard constraint: the parent-tag selector is the only reliable CDN-safe scoping mechanism (LightningCSS strips `@scope` blocks).
+3. **Outside `<admin-shell>`, these names have NO EFFECT**. If you need `[data-col]` semantics on a non-admin-shell page, you must author your own CSS (the helpers do not apply globally).
+
+**Documented for consumers** in the adia-ui-factory plugin's consumer composition skill (§CSSPolicy → "Reserved layout-helper attribute names (admin-shell scoping)").
+
+---
+
+## Build pipeline
+
+```bash
+npm run build:components       # regenerates all <name>.a2ui.json sidecars from yamls
+npm run verify:components      # verifies no drift (CI gate)
+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`
+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)
+
+**Never hand-edit `<name>.a2ui.json`** — it's regenerated from the yaml. The yaml is the SoT.
+
+---
+
+## Component creation playbook (full lifecycle)
+
+This is the canonical end-to-end procedure for creating a new component yaml + js + css + examples.html + sidecar. Run in order:
+
+1. **Author `<name>.yaml`** with all required fields:
+   - `name:`, `tag:`, `component:`, `category:`, `version: 1`
+   - `status:` — pick from the table above
+   - `description:` — concrete one-paragraph
+   - `props:` with per-prop `type:`, `default:`, optional `required: true`, optional `enum:` / `values:`
+   - `events:`, `slots:`, `css-vars:` as applicable
+2. **Author `<name>.js`** following the `AdiaElement` / `AdiaFormElement` patterns (see [code-style.md](code-style.md))
+3. **Author `<name>.css`** following the light-DOM cascade rules (see [css-patterns.md](css-patterns.md))
+4. **Build the sidecar**:
+
+   ```bash
+   npm run build:components
+   ```
+
+   This generates `<name>.a2ui.json`.
+
+5. **Author `<name>.examples.html`** with at minimum:
+   - A `<h1>` matching the component name
+   - One `<section data-section data-property="usage">` with the canonical worked example
+   - Per-prop demo sections matching `data-property="<prop-name>"` (one per prop)
+6. **Run the anatomy sweep**:
+
+   ```bash
+   node scripts/docs/anatomy-sweep.mjs
+   ```
+
+   This auto-generates the **canonical anatomy sections** (`slots`, `data-attrs`, `keyboard`, `css-vars`, `a2ui`, `related`) from the sidecar. The sweep is idempotent — skip-on-already-present, safe to re-run. Hand-author `accessibility` and any prop-demo sections; the sweep covers the schema-derivable sections only.
+
+   Canonical `data-property` vocabulary for `<section data-section data-property="X">`:
+   - `usage` — canonical worked example
+   - `props` — prop reference table
+   - `slots` — named-slot semantics
+   - `events` — fired events
+   - `data-attrs` — `data-*` attributes the component reads
+   - `css-vars` — CSS custom properties
+   - `keyboard` — keyboard interaction model
+   - `accessibility` — ARIA, screen-reader notes
+   - `a2ui` — A2UI runtime integration notes
+   - `related` — sibling/replacement components
+   - `<prop-name>` — visual demo for a specific prop
+
+   The sweep also **normalizes legacy section data-properties**: `Properties` → `props`, `Events` → `events`, `CSS Tokens` → `css-vars`, `Usage` → `usage`. Run with `--dry` first to preview changes:
+
+   ```bash
+   node scripts/docs/anatomy-sweep.mjs --dry
+   ```
+
+7. **Run the full verify gate**:
+
+   ```bash
+   node scripts/build/components.mjs --verify   # sidecar drift
+   npm run verify:traits                         # 100% coverage
+   ```
+
+After the playbook, the component is consumable by the docs site, the A2UI runtime, and any harness reading the sidecar.
+
+---
+
+## Cross-references
+
+- `docs/specs/component-token-contract.md` — token/variant/mode contract
+- `docs/specs/component-implementation-patterns.md` — implementation patterns
+- [code-style.md](code-style.md) — JS code style rules
+- [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)