@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/docs-catalog.md

@@ -0,0 +1,239 @@
+---
+name: docs-catalog
+load-when: When you need the canonical docs URLs: ui-kit.exe.xyz catalog, llms.txt index, per-component examples.html, ADR pointers, MCP server install pages
+load-size-tokens: ~3,300
+required-for:
+  - answering "where are the docs"
+  - component reference lookup
+  - live demo handoff
+---
+
+# §Docs — Where the documentation lives
+
+AdiaUI documentation is distributed across the repo, the live site, and
+the per-component source. **When sources disagree, follow this trust
+order** (matches `.claude/docs/guides/INDEX.md`):
+
+1. **Component source** — `packages/web-components/components/<name>/`
+2. **Architecture spec** — `.claude/docs/specs/package-architecture.md`
+3. **Per-component demo pages** — `/site/pages/components/<name>.html`
+4. **Schema pages** — `.claude/docs/guides/30-79*.md` (hand-written; may lag)
+
+
+### URL manifest (machine-parseable)
+
+Construct any AdiaUI documentation URL by substituting `<name>`. The LLM
+should treat this as the canonical reference — **do not guess URLs**.
+
+```yaml
+# Live site (ui-kit.exe.xyz) — current production deployment
+live_site:
+  base: "https://ui-kit.exe.xyz"
+  routes:
+    component_demo:  "/site/components/<name>"        # e.g. /site/components/button
+    module_demo:     "/site/modules/<name>"           # e.g. /site/modules/admin-shell
+    guide:           "/site/pages/guides/<slug>"      # e.g. /site/pages/guides/10-tokens
+    pattern:         "/site/pages/patterns/<slug>"    # e.g. /site/pages/patterns/admin-dashboard
+    getting_started: "/site/pages/getting-started"
+    token_reference: "/site/pages/reference/tokens"
+    catalog_index:   "/site/components"
+
+# Repo paths (for local consumers + in-repo agents)
+local:
+  component_yaml:    "node_modules/@adia-ai/web-components/components/<name>/<name>.yaml"
+  component_a2ui:    "node_modules/@adia-ai/web-components/components/<name>/<name>.a2ui.json"
+  component_types:   "node_modules/@adia-ai/web-components/components/<name>/<name>.d.ts"
+  component_test:    "node_modules/@adia-ai/web-components/components/<name>/<name>.test.js"
+  component_css:     "node_modules/@adia-ai/web-components/components/<name>/<name>.css"
+  module_yaml:       "node_modules/@adia-ai/web-modules/<cluster>/<name>/<name>.yaml"
+  package_readme:    "node_modules/@adia-ai/<package>/README.md"
+  usage_doc:         "node_modules/@adia-ai/web-components/USAGE.md"
+
+# GitHub source (for in-repo and contributor agents)
+github:
+  base: "https://github.com/adiahealth/gen-ui-kit"
+  routes:
+    component_dir:   "/tree/main/packages/web-components/components/<name>"
+    component_examples: "/blob/main/packages/web-components/components/<name>/<name>.examples.html"
+    guide:           "/blob/main/docs/guides/<file>"
+    spec:            "/blob/main/docs/specs/<file>"
+    changelog:       "/blob/main/packages/<package>/CHANGELOG.md"
+    issues:          "/issues"
+    new_issue:       "/issues/new"
+
+# Cluster names (substitute for <cluster>)
+clusters:
+  - shell      # admin-shell + 10 admin-* children (sidebar, content, topbar, statusbar, scroll, page, page-header, page-body, command, entity-item)
+  - chat       # chat-shell, chat-thread, chat-composer, chat-empty, chat-header, chat-sidebar, chat-status
+  - editor     # editor-shell, editor-toolbar, editor-sidebar, editor-canvas, editor-canvas-empty, editor-canvas-toolbar, editor-statusbar
+  - simple     # simple-shell, simple-hero, simple-content
+  - runtime    # a2ui-root
+  - theme      # theme-panel
+```
+
+**Validity check:** all routes above were audited 2026-05-19. If a URL
+returns 404, the route may have moved — fall back to the GitHub source
+or report it via `write ui-kit bug ticket`.
+
+
+### Documentation map
+
+| Surface | Path | What's there | Authoritative for |
+|---|---|---|---|
+| **Per-component yaml** | `node_modules/@adia-ai/web-components/components/<name>/<name>.yaml` | Props, slots, events, tokens, anti-patterns | Props/slots/events — always |
+| **Per-component a2ui.json** | `<name>.a2ui.json` (generated from yaml) | A2UI JSON schema for the component | A2UI message shape |
+| **Per-component examples** | `<name>.examples.html` (in-repo only) | Canonical HTML usage fragments | Real-world markup patterns — **NOT in npm** |
+| **Per-component test** | `<name>.test.js` (ships in npm) | Vitest spec | Behavioral contract |
+| **Live demo pages** | `https://ui-kit.exe.xyz/site/components/<name>` | Interactive rendered demos | Visual behavior |
+| **Web-modules yaml** | `packages/web-modules/<cluster>/<name>/<name>.yaml` | Shell + composite specs (30 files) | Module-tier components |
+| **Guides** | `.claude/docs/guides/` (22 files, numbered) | Hand-written narrative docs | Concepts + recipes |
+| **Specs** | `.claude/docs/specs/` (31 files) | Architecture + system specs | System architecture |
+| **Package READMEs** | `packages/<name>/README.md` | Per-package entry-point | Package surface |
+| **Migration guide** | `.claude/docs/MIGRATION GUIDE.md` | Version-by-version upgrade notes | Version migration |
+| **Browser compat** | `.claude/docs/BROWSER-COMPAT.md` | Supported browsers, polyfill baselines | Browser support |
+| **Live docs site** | `https://ui-kit.exe.xyz/` | Production-deployed full site | Public reference |
+
+### The numbered guides (`.claude/docs/guides/`)
+
+The guides are organized by topic-prefix. Skim the INDEX first
+(`.claude/docs/guides/INDEX.md`); then dive into specific files:
+
+```
+01-introduction.md         Project overview
+02-quick-start.md          External consumer cold-start (overlaps §Setup here)
+03-architecture.md         Layer model, signals/template/element split
+
+10-tokens.md               Parametric spacing, radius, shadows, sizing
+11-colors.md               OKLCH parametric color system
+12-typography.md           13 type roles, productive/moderate/expressive modes
+13-fields.md               Field tokens (shared height, radius, colors)
+14-accessibility.md        Focus management, ARIA, keyboard nav
+
+20-adia-element.md         UIElement base class — reactive properties + lifecycle
+21-adia-form-element.md    UIFormElement — ElementInternals + form participation
+22-css-patterns.md         @scope, :where(:scope) tokens, slot selectors
+23-authoring.md            End-to-end guide to authoring a new component
+
+70-theming.md              Theming contract (named theme / scheme / density)
+71-recipes.md              Common composition recipes
+72-admin-layout.md         Admin shell composition patterns
+
+80-llm-providers.md        @adia-ai/llm package — providers + TypeScript
+81-proxy-server.md         packages/llm/server.js — dev proxy + production
+82-vite-config.md          Vite aliases, proxy, build config
+
+91-token-reference.md      Complete --a-* token catalog
+92-naming.md               Naming conventions
+```
+
+### The key specs (`.claude/docs/specs/`)
+
+For deep architecture questions, the specs are the authoritative
+documents. Most consumers don't need these — they're for component
+authors and integrators.
+
+```
+package-architecture.md           Source of truth for monorepo layout
+component-token-contract.md       What --a-* tokens components may consume
+component-implementation-patterns.md  Patterns shared across components
+component-yaml-contract.md        The yaml schema each component must follow
+traits.md                         The trait system (pressable, focusable, etc.)
+typescript-first-substrate.md     TS substrate spec (v0.6+ sealed)
+semantic-validator.md             A2UI semantic validation
+genui-multiturn-architecture.md   Multi-turn sessionId/state-cache model
+theme-panel-module.md             theme-panel composition + token swap
+compose-constitution.md           A2UI generation engine architecture
+exe-dev-platform-reference.md     Production deployment platform reference
+```
+
+INDEX at `.claude/docs/specs/INDEX.md`.
+
+### Per-package READMEs
+
+```
+packages/web-components/README.md      Light-DOM components overview
+packages/web-components/USAGE.md       In-depth usage patterns + framework guide
+packages/web-modules/README.md         Composite shells + clusters
+packages/llm/README.md                 @adia-ai/llm package
+packages/a2ui/runtime/README.md        A2UI renderer + registry
+packages/a2ui/compose/README.md        Generation engines (monolithic, zettel)
+packages/a2ui/mcp/README.md            MCP server install + transports
+packages/a2ui/corpus/README.md         Pre-authored chunk + composition corpus
+packages/a2ui/retrieval/README.md      Domain router + pattern search
+packages/a2ui/validator/README.md      A2UI JSON validator
+```
+
+### Pattern recipe library (`references/` in this skill)
+
+The `.agents/skills/adia-ui-kit/references/` directory ships seven
+substantive pattern recipe books, ~2,300 lines total, covering composition
+patterns more deeply than §Patterns / §Flows in this file:
+
+```
+references/patterns-agent.md     Agent/chat surfaces (gen-ui-chat, gen-ui-thread, gen-ui-canvas, gen-ui-inspector, pipeline-status)
+references/patterns-data.md      Tables, dashboards, charts, data-stream wiring, KPI grids — 722 lines, deepest recipes
+references/patterns-forms.md     Field anatomy, form layouts, validation, multi-step wizards
+references/patterns-layout.md    Grid, stack, page primitives, density modes
+references/patterns-shells.md    App shell, admin shell, editor shell, section-nav, route slot
+references/patterns-traits.md    Trait wiring, attaching behaviors declaratively
+references/patterns-wiring.md    A2UI JSON wiring, data binding patterns, registerResolver flows
+```
+
+Read these when §Flows / §Patterns in this file is too brief — they go
+deeper on shell APIs, composition recipes, and edge cases.
+
+### Live site (`ui-kit.exe.xyz`)
+
+The production deployment serves:
+
+- **`/site/components/<name>`** — interactive demos with live rendering,
+  prop tables, accessibility notes, and source code
+- **`/site/pages/getting-started/`** — onboarding flow
+- **`/site/pages/guides/`** — rendered versions of `.claude/docs/guides/`
+- **`/site/pages/patterns/`** — pattern gallery
+- **`/site/pages/reference/`** — token + type reference
+
+This is the most consumer-friendly entry point. Browse here first when
+exploring; drop to source files for definitive answers.
+
+### Discovery commands
+
+```bash
+# What components exist?
+ls node_modules/@adia-ai/web-components/components/ | sort
+
+# What does <name> accept?
+cat node_modules/@adia-ai/web-components/components/<name>/<name>.yaml
+
+# How is <name> used in real code?
+cat node_modules/@adia-ai/web-components/components/<name>/<name>.examples.html
+
+# Live demo (no install needed)
+open https://ui-kit.exe.xyz/site/components/<name>
+
+# Architecture deep-dive
+cat node_modules/@adia-ai/web-components/USAGE.md | less
+
+# Browse a topic
+ls node_modules/@adia-ai/web-components/../../docs/guides/ | grep -i theme
+```
+
+### When to read each surface
+
+| Question | Where to look first |
+|---|---|
+| "What props does X accept?" | `<name>.yaml` |
+| "What does X look like?" | `ui-kit.exe.xyz/site/components/<name>` |
+| "How do I use X in real markup?" | `<name>.examples.html` |
+| "How do I compose X and Y?" | `.claude/docs/guides/71-recipes.md` or §Patterns/§Flows here |
+| "How do I author a new component?" | `.claude/docs/guides/23-authoring.md` |
+| "What's the token system?" | `.claude/docs/guides/10-tokens.md` + `91-token-reference.md` |
+| "How do I theme?" | `.claude/docs/guides/70-theming.md` or §Theme here |
+| "How does the generation engine work?" | `.claude/docs/specs/compose-constitution.md` |
+| "Why does X behave this way?" | `<name>.test.js` (behavioral contract) |
+| "What changed in v0.6?" | `.claude/docs/MIGRATION GUIDE.md` |
+| "What browsers are supported?" | `.claude/docs/BROWSER-COMPAT.md` |
+| "How do I deploy the MCP server?" | `packages/a2ui/mcp/README.md` |
+
+
+---

package/skills/adia-ui-kit/references/exclusions.md

@@ -0,0 +1,225 @@
+---
+name: exclusions
+load-when: When defending why a feature ISN'T in the kit (or shouldn't be added). Documents the explicit exclusions + the rationale + when to escalate to substrate vs absorb into the kit
+load-size-tokens: ~2,500
+required-for:
+  - scope-creep defense
+  - absorption proposal triage
+  - Teach landing decisions
+---
+
+# Items deliberately NOT included (defending the exclusions)
+
+To avoid duplicate filings, the following were considered and
+explicitly left out. Each was verified against the installed
+@adia-ai/web-components@<version> source where applicable.
+
+- **<Item>** — already shipped. Verified at
+  `node_modules/@adia-ai/web-components/components/<name>/<name>.yaml:<line>`.
+
+- **<Item>** — already exists with the exact shape needed. NOT
+  feedback — this is a **consumer-side dogfooding miss** captured
+  separately in `.adia-ui-kit/notes/<date>-miss.md`.
+
+- **<Item>** — third-party tool issue (Vite cache stale). Workaround
+  is `rm -rf node_modules/.vite`. Listed in related-observations for
+  documentation benefit but not a code ask on this recipient.
+
+- **<Item>** — speculative; no concrete pain-point yet. Filing
+  without a use-case would be P3 noise.
+
+If any of the above is wrong or stale relative to a newer release,
+please flag in the response.
+```
+
+Each exclusion must cite **either**:
+- A specific file/line in the installed package that proves it's shipped, OR
+- A CHANGELOG entry that resolved it, OR
+- A `.adia-ui-kit/notes/` path where the issue is tracked elsewhere, OR
+- An explicit statement that it's out of scope and why
+
+**"Already shipped — trust me" is not acceptable. Cite or include.**
+
+#### Step 6b — (Optional) Split exclusions into a companion file
+
+If your exclusion list is **15+ items across 4+ rationale categories**,
+or the ticket will face hostile leadership review, split the defense
+block into a sibling file:
+
+```
+.adia-ui-kit/tickets/
+  2026-05-19-feedback-<topic>.md             # the asks
+  2026-05-19-feedback-<topic>-OMISSIONS.md   # the exclusions, expanded
+```
+
+Group omissions by **rationale category**, not by priority. Each
+omission has:
+- **Evidence tag** (uppercase: `VERIFIED IN SOURCE`, `RESOLVED IN v0.6.5`, `CONSUMER MISS`)
+- **Defense paragraph** (1-3 sentences)
+- **Confidence rating** (`High` / `Medium` / `Low`)
+
+Cross-link the companion in the main ticket's front-matter:
+
+```yaml
+references:
+  - "2026-05-19-feedback-<topic>-OMISSIONS"
+```
+
+And in §6 of the main ticket, replace the bullet list with a one-line
+pointer:
+
+> Items considered and deliberately excluded are tracked in
+> `2026-05-19-feedback-<topic>-OMISSIONS.md` — 15 omissions across 5
+> rationale categories with verification anchor and confidence rating.
+
+#### Step 7 — Cross-reference prior tickets
+
+If this ticket relates to prior feedback you've filed, list them in
+front-matter `references:` and call them out in the body:
+
+- **Sibling tickets** — "Item §2 is related to ticket-XX `§N`"
+- **Duplicates** — "Item §4 is the same ask as ticket-XX `§N`; can collapse"
+- **Supersession** — "This obsoletes ticket-YY §M after the v0.6.5 fix"
+
+#### Step 8 — Set front-matter correctly
+
+```yaml
+---
+id: "<NN>"                                        # serial per recipient
+type: feedback                                    # feedback | bug | request
+recipient: adia-ui
+date: "YYYY-MM-DD"
+author: "<role> (<session-context>)"              # don't claim a human author
+project: "<your project name>"
+status: draft                                     # draft until submitted
+references:
+  - "<prior-ticket-id>"                           # every prior touchpoint
+version: "@adia-ai/web-components@<X.Y.Z>"        # version verified against
+priority: p0                                      # highest priority in the doc
+---
+```
+
+`status: draft` is the starting point. Only the user (or an explicit
+submit instruction) should bump to `submitted`.
+
+---
+
+### Sniff tests before sending
+
+Walk each one before declaring the ticket ready:
+
+1. **Reproduction test:** Can a stranger paste your repro code into a
+   fresh project and see the symptom? If not, P0/P1 status is wrong.
+
+2. **Exclusion test:** Pick one item from "Items deliberately NOT
+   included." Can you defend it in 30 seconds with a file path?
+
+3. **Cost test:** Can the recipient roughly estimate their effort
+   from your cost block? "Medium — new component + tests + a2ui
+   example" is good. "Some work" is not.
+
+4. **Duplicate test:** Have you searched `.adia-ui-kit/tickets/` for
+   keywords overlapping your asks? If matches exist, cross-reference
+   or remove your duplicate.
+
+5. **Scope test:** Is any item really a third-party tool issue or a
+   consumer-side miss? If yes, move it out of the feedback ticket.
+
+6. **Pre-mortem test:** If your team lead asks "why did you ship this
+   and not item X?" — do you have an answer? If "I didn't think of X"
+   is the honest answer, X probably belongs in the doc.
+
+---
+
+### Pitfalls (verify before filing)
+
+**Common AdiaUI false alarms** — verify these are real bugs before filing:
+
+- **Binding contract** — `*-ui` form controls and template re-renders
+  share a contract that surfaces as ~4 symptoms but is ONE root cause:
+  1. `.value=${() => x.value}` (getter function) silently fails on
+     `slider-ui` / `switch-ui`. Use `.value=${x.value}` (direct expression).
+  2. `style="background:${v}"` renders literal `style="background:{{p:0}}"`.
+     Use `style="${precomputed}"` (whole-attribute) or `.style=${expr}`.
+  3. Template doesn't re-render when a signal changes inside a nested
+     callback. Cause: the *template function itself* never read the signal.
+     Read every dependency at the top: `const _doc = doc.value; void _doc`.
+  4. `OKLCHColor.h = NaN` → `#NaNNaNNaN` → `<input type="color">`
+     console-flood. Sanitize at the conversion boundary, not the binding.
+
+  Symptoms 1-3 are documented in USAGE.md `property-binding-patterns` section.
+  Symptom 4 is a consumer bug. **Run a Playwright probe before filing
+  any of these as a framework bug.**
+
+- **Phosphor icon name verification is non-optional.** `<icon-ui name="X">`
+  warns at runtime if `X` doesn't exist. Common mistakes: `plus` (use
+  `plus-circle`), `arrows-counter-clockwise` (singular: `arrow-counter-clockwise`).
+  Verify with `ls node_modules/@phosphor-icons/core/assets/regular/ | grep <pattern>`
+  before claiming a registry gap.
+
+- **Vite CSS cache is real and silent.** CSS edits not reaching the
+  browser? Symptom: file on disk differs from `curl http://localhost:5173/src/style.css`.
+  Fix: `rm -rf node_modules/.vite && pkill -f vite && npm run dev`.
+  NOT an AdiaUI bug.
+
+- **Don't conflate "I didn't find it" with "it doesn't exist."**
+  Before claiming a feature is missing, grep the installed package source
+  AND the yaml, a2ui.json, USAGE.md. Use the §Docs URL manifest to find
+  documentation.
+
+- **Don't file separate tickets for the same root cause.** Slider
+  getter-function, signal-binding stuckness, partial-attr interpolation
+  all stem from "template re-runs only on direct signal reads." File
+  ONE root-cause ticket with N symptoms.
+
+- **Don't file workaround-as-bug if USAGE.md prescribes the workaround.**
+  USAGE.md `property-binding-patterns` section documents `.foo=${expr}` for
+  property binding; `foo="${expr}"` failing is documented behavior, not
+  a bug.
+
+- **Lockstep PATCH releases are common.** AdiaUI ships PATCH bumps with
+  no source change (lockstep version cuts). Before claiming a fix
+  "should have shipped in vX," check `git log` between cuts. Don't file
+  a regression for an issue resolved in the prior MINOR.
+
+---
+
+### Final ticket location + delivery
+
+**Output path:** `.adia-ui-kit/tickets/<YYYY-MM-DD>-<type>-<slug>.md`
+
+Where `<type>` is one of `bug`, `feature`, `feedback`.
+
+**Deliver via:**
+
+1. **GitHub issue:** paste contents to `https://github.com/adiahealth/gen-ui-kit/issues/new`
+2. **Team channel:** share the ticket file path with teammates
+3. **AdiaUI authors directly:** if you have a contact, share the file
+
+The ticket file should be committed to your project repo so it's
+preserved for future agents and team members. After upstream merge,
+mark `status: closed` and link the merge commit.
+
+---
+
+### Verification before declaring the ticket done
+
+- [ ] Working tree clean (`git status --short`)
+- [ ] `.adia-ui-kit/tickets/README.md` registry has your new entry
+- [ ] Every numbered section has at minimum "What happened" + "Request"
+- [ ] "Items deliberately NOT included" cites a verification anchor for
+      every exclusion (file path, version reference, or `.adia-ui-kit/notes/` path)
+- [ ] Every P0/P1 has a reproduction block or stack trace
+- [ ] Front-matter `references:` lists every prior ticket touching the
+      same components
+
+**The stranger test:** Can a stranger open your ticket cold and:
+
+1. Reproduce every P0/P1
+2. Understand why each exclusion was made
+3. Estimate the effort for each ask
+4. Find the relevant prior conversation
+
+If yes — the ticket is defensible.
+
+---