@adia-ai/adia-ui-forge 0.8.62 → 0.8.64

package/skills/primitive-authoring/references/trait-pages.md

@@ -1,15 +1,15 @@
-# Trait Detail Pages — the required template
+# Trait Detail Pages, the required template
 
 Every trait detail page under `site/pages/traits/<name>/` follows one binding section template. The 41-page Phase B sweep proved what a loose contract produces: bimodal quality (portfolio-grade pages next to abstract-box demos) and zero pages teaching restraint. Navigate-by-template is the contract. Source: ADR-0019.
 
-Trait pages are this skill's charter (traits live in `packages/web-components/traits/`); `site-docs-authoring` owns `site/pages/{architecture,getting-started,guides,patterns,reference}` — not `traits/`.
+Trait pages are this skill's charter (traits live in `packages/web-components/traits/`); `site-docs-authoring` owns `site/pages/{architecture,getting-started,guides,patterns,reference}`, not `traits/`.
 
 ## Required sections, in order
 
 | # | Section (`data-property=`) | Required? | Purpose |
 |---|---|---|---|
 | 1 | `<header>` | always | `<h1>` trait name + `<tag-ui>trait</tag-ui>` + category tag matching `_catalog.json` SoT |
-| 2 | `hero` | always | "In context" demo with real product chrome — no abstract boxes |
+| 2 | `hero` | always | "In context" demo with real product chrome, no abstract boxes |
 | 3 | `minimal` | always | Single-tag declarative usage; `<h2>` reads "Bare minimum" |
 | 4 | `declarative` | always | `<X traits="trait-name">` code-ui block |
 | 5 | `config` | conditional | Only when the trait declares `config` attrs in `defineTrait()`; live sliders + readouts |
@@ -26,13 +26,13 @@ Trait-specific extras (`state`, `lifecycle`, scenario `usage` recipes) slot betw
 
 - `data-property` values are lowercase hyphen-separated tokens; canonical set as in the table. **`minimal`, not `bare`.**
 - `data-artifact-label` values are lowercase descriptive prose ("settle log") OR code-shaped strings describing the demo axis (`speed=120 (slow, dramatic)`). HTML-entity escapes inside attribute values are correct.
-- Header category tag MUST match the trait's `category` in `packages/web-components/traits/_catalog.json` — catalog SoT, never page-author judgment.
-- Imports in code-ui blocks use the full package name `@adia-ai/web-components/traits` — never internal aliases like `@traits/index.js`.
+- Header category tag MUST match the trait's `category` in `packages/web-components/traits/_catalog.json`, catalog SoT, never page-author judgment.
+- Imports in code-ui blocks use the full package name `@adia-ai/web-components/traits`, never internal aliases like `@traits/index.js`.
 - Inline-style tokens use canonical names: `--a-border` (dashed borders), `--a-radius-md` / `--a-radius-lg`, `--a-accent` / `--a-accent-fg`.
 
 ## The two teeth
 
-- **`when-not-to-use` is the highest-impact section.** A page shipping without it defaults to "this trait is good, please use it" — wrong for every trait once overuse, density, or a11y tradeoffs enter. The restraint mandate is the pedagogy differentiator (Motion / GSAP / React Spring all whiff on it). Fewer than 2 bullets requires an articulated why.
-- **Composes must SHOW.** Listing trait names with prose-only descriptions does not satisfy the contract — at least one composition runs as a working demo.
+- **`when-not-to-use` is the highest-impact section.** A page shipping without it defaults to "this trait is good, please use it", wrong for every trait once overuse, density, or a11y tradeoffs enter. The restraint mandate is the pedagogy differentiator (Motion / GSAP / React Spring all whiff on it). Fewer than 2 bullets requires an articulated why.
+- **Composes must SHOW.** Listing trait names with prose-only descriptions does not satisfy the contract, at least one composition runs as a working demo.
 
-No mechanical gate enforces this template yet (ADR-0019's verify-trait-pages.mjs was deferred and does not exist) — the 11-section contract is enforced at PR review. Source: ADR-0019.
+No mechanical gate enforces this template yet (ADR-0019's verify-trait-pages.mjs was deferred and does not exist): the 11-section contract is enforced at PR review. Source: ADR-0019.

package/skills/primitive-authoring/references/worked-example.md

@@ -2,7 +2,7 @@
 
 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>`
+## Example 1, Light presentation component: `<badge-ui>`
 
 A small inline container for status labels. Supports cosmetic variants (primary/success/danger) and an optional remove button that fires a `remove` event.
 
@@ -10,24 +10,24 @@ A small inline container for status labels. Supports cosmetic variants (primary/
 
 The REAL anatomy every shipped primitive carries (this example's code blocks
 below show only the two hand-authored core files, but "copy the structure"
-means all of these — the yaml SoT and its regenerated artifacts are not
+means all of these: the yaml SoT and its regenerated artifacts are not
 optional):
 
 ```text
 packages/web-components/components/badge/
-  badge.yaml           # SoT — props/slots/events contract (yaml-contract.md); edit FIRST
+  badge.yaml           # SoT, props/slots/events contract (yaml-contract.md); edit FIRST
   badge.class.js       # the class, non-registering export (test isolation / subclassing)
   badge.js             # side-effect registration wrapper: import class + defineIfFree()
   badge.css            # @scope'd styles
   badge.html           # standalone demo page
   badge.examples.html  # docs-site examples
   badge.examples.md    # examples prose
-  badge.a2ui.json      # GENERATED from the yaml (npm run build:components) — never hand-edit
+  badge.a2ui.json      # GENERATED from the yaml (npm run build:components), never hand-edit
   badge.d.ts           # GENERATED types
 ```
 
 The code below collapses the class + registration into one `badge.js` for
-reading compactness only — a real component splits them
+reading compactness only, a real component splits them
 (`badge.class.js` exports, `badge.js` registers).
 
 ### `badge.js`
@@ -36,14 +36,14 @@ reading compactness only — a real component splits them
 import { UIElement } from '../../core/element.js';
 
 /**
- * <badge-ui> — Compact inline status label.
+ * <badge-ui>, Compact inline status label.
  *
  * Props:
- *   variant    — 'neutral' | 'primary' | 'success' | 'danger' (default 'neutral')
- *   removable  — show an inline × button that fires 'remove' on click
+ *   variant, 'neutral' | 'primary' | 'success' | 'danger' (default 'neutral')
+ *   removable, show an inline × button that fires 'remove' on click
  *
  * Events:
- *   remove — user clicked the × button (bubbles)
+ *   remove, user clicked the × button (bubbles)
  */
 class UIBadge extends UIElement {
   static properties = {
@@ -87,13 +87,13 @@ export { UIBadge };
 
 **Annotations:**
 
-- **Class name `UIBadge`, 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.
+- **Class name `UIBadge`, 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`
 
@@ -111,7 +111,7 @@ export { UIBadge };
   }
 
   :scope {
-    /* ── Base styles — consume component tokens only ── */
+    /* ── Base styles, consume component tokens only ── */
     display: inline-flex;
     align-items: center;
     gap: var(--badge-gap);
@@ -125,7 +125,7 @@ export { UIBadge };
     white-space: nowrap;
   }
 
-  /* ── Variants — token-only overrides ── */
+  /* ── Variants, token-only overrides ── */
   :scope[variant="primary"] {
     --badge-bg: var(--a-primary-bg);
     --badge-fg: var(--a-primary-fg);
@@ -166,17 +166,17 @@ export { UIBadge };
 **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.
+- **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).
+- **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.
+- **`color-mix()` on `currentColor`** is the idiomatic hover tint, stays theme-aware without introducing a new token.
 
 ---
 
-## Example 2 — Form-associated component: `<counter-ui>`
+## 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.
+A numeric input that shows value + increment/decrement buttons. Form- participating, submits a string value with the host form.
 
 ### `counter.js`
 
@@ -184,13 +184,13 @@ A numeric input that shows value + increment/decrement buttons. Form- participat
 import { UIFormElement } from '../../core/form.js';
 
 /**
- * <counter-ui> — Integer counter with +/− controls. Form-associated.
+ * <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
+ *   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 UICounter extends UIFormElement {
   static properties = {
@@ -221,7 +221,7 @@ class UICounter extends UIFormElement {
   }
 
   connected() {
-    super.connected(); // registers ElementInternals — do not omit
+    super.connected(); // registers ElementInternals, do not omit
 
     if (!this.querySelector('[data-counter-dec]')) {
       this.innerHTML = `
@@ -259,12 +259,12 @@ export { UICounter };
 
 **Annotations:**
 
-- **`UIFormElement` 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 `UIFormElement`, updates the form-submitted string representation.
-- **Two stable handlers** — `#onDecrement`, `#onIncrement`. Both paired in `disconnected()`.
+- **`UIFormElement` 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 `UIFormElement`, 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`
@@ -315,7 +315,7 @@ export { UICounter };
     font-variant-numeric: tabular-nums;
   }
 
-  /* Disabled state — inherited from UIFormElement */
+  /* Disabled state, inherited from UIFormElement */
   :scope[disabled] {
     --counter-fg: var(--a-fg-muted);
     --counter-border: 1px solid var(--a-border-subtle);
@@ -327,14 +327,14 @@ export { UICounter };
 
 **Annotations:**
 
-- **No variants** in this example — the component is functional, not cosmetic. All state communicated via tokens and the `[disabled]` selector.
+- **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`.
+- **`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?
+## Checklist, did this component pass?
 
 Run the 30-second self-check from [authoring-cycle.md](authoring-cycle.md) Step 4 against each example: