@adia-ai/adia-ui-factory 0.2.3 → 0.8.0

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

@@ -1,186 +0,0 @@
----
-name: catalog-lookup
-load-when: Before composing — when matching user intent to specific AdiaUI primitives. Covers the ladder (intent to component category to specific tag), llms.txt usage, examples.html lookup, and the canonical-tag search procedure
-load-size-tokens: ~2,500
-required-for:
-  - composition modes 1-4
-  - pre-author bundle gate
----
-
-# §1 — Catalog Lookup (before composing)
-
-Before writing any markup, look up what exists. Using attributes that
-don't exist or invoking unregistered tags is the second most common
-failure after premature rendering.
-
-> ⚠️ **Prior-art-first rule (NON-NEGOTIABLE).** Before authoring a
-> novel solution for ANY UI problem, you must FIRST exhaust the
-> existing catalog. Concretely:
->
-> 1. **`packages/web-components/components/`** (122 primitives). Scan
->    by category and by keyword. Every primitive ships a `<name>.yaml`
->    with `description`, `props`, `slots`, `events`, `composes`,
->    `keywords`, `synonyms`, and `anti_patterns` fields specifically so
->    you can find it by intent, not just by tag name. If your problem
->    is "show a loading state for a KPI card", `stat-ui[loading]` +
->    `skeleton-ui` already solve it (v0.6.18). If your problem is
->    "imperative toast", `feed-ui` + the `CustomEvent('feed')` bus
->    already solve it. Do not invent `<my-loading-card>` or a
->    re-implementation of a toast queue.
-> 2. **`packages/web-modules/`** (composite shells + canvas + a2ui-runtime).
->    Scan the four shell clusters (`shell/`, `chat/`, `editor/`,
->    `simple/`) and the `generative/` cluster. If your problem is
->    "split-pane sidebar + topbar + content scroll region", `admin-shell`
->    has already solved it; do not hand-roll a flex layout. If your
->    problem is "compose web-components from JSON", `a2ui-root` /
->    `registerResolver` already solve it.
-> 3. **Token system** (`packages/web-components/styles/tokens.css` +
->    `typography.css` + `prose.css`). Before introducing a new CSS
->    variable, check the existing ladder. `--a-canvas-{0..4}`,
->    `--a-body-{sm,md,lg}`, `--a-weight-{regular,medium,semibold,bold}`,
->    `--a-fg{,-muted,-strong}` etc. cover almost every typography +
->    surface need.
-> 4. **Traits** (`packages/web-components/traits/`, 56 traits in 9
->    categories). Cross-cutting behaviors (`dismissible`, `selectable`,
->    `resizable`, `keyboard-nav`, etc.) are encoded as traits with their
->    own examples + tests. If your problem maps to a trait, USE the
->    trait — don't re-implement the behavior inline.
->
-> **Searching is mandatory; not finding is rare.** When the v0.6.18 cut
-> shipped `text-ui` size/color/weight/text-align overlays (FB-10), the
-> skill had been documenting those props as if they existed for two
-> previous versions — because consumers naturally reached for them and
-> the existing variant-only API was missing the obvious overlay layer.
-> The substrate caught up to the doc, not the other way around. That
-> only works if you check the doc + the substrate side-by-side. If
-> what you need ISN'T in the catalog, the right move is **file a
-> FEEDBACK ticket** (see §Team Tickets) — not invent a one-off.
->
-> **How to search efficiently:**
-> - `npx adia-ui-doc <name>` — fast yaml summary for a tag you suspect exists
-> - `npx adia-ui-doc` (no arg) — list all 96 components
-> - `grep -rE "keywords:|synonyms:|description:" packages/web-components/components/*/­*.yaml | grep -i "<your intent>"`
->   — semantic search across the catalog
-> - Live site: `https://ui-kit.exe.xyz/site/components/` (browse) or
->   `/site/components/<name>` (deep dive)
-> - For modules: `ls packages/web-modules/*/`
-
-> **Where:** authoritative API in `<name>.yaml` (ships in npm). Visual
-> reference at `https://ui-kit.exe.xyz/site/components/<name>`. Full
-> URL manifest in §Docs below. If you're unsure what tools you have to
-> fetch a URL, prefer the local `.yaml` — it's always available.
-
-### Where to look
-
-**External consumer (installed via npm):**
-
-```
-node_modules/@adia-ai/web-components/components/<name>/
-  <name>.yaml         ← canonical API spec (props, slots, events, anti-patterns)  ✓ ships
-  <name>.a2ui.json    ← A2UI JSON spec (generated)                                ✓ ships
-  <name>.d.ts         ← TypeScript declarations                                   ✓ ships
-  <name>.examples.md  ← canonical usage fragments (1-3 per component)             ✓ ships (v0.6.7+)
-  <name>.test.js      ← behavioral contract (read for "why does X work this way") ✓ ships
-  <name>.examples.html ← authoring demo with full page chrome — NOT in npm
-                          → in-repo only; external consumers use .examples.md
-
-node_modules/@adia-ai/web-components/
-  custom-elements.json ← W3C Custom Elements Manifest v2.1.0 (110 modules)        ✓ ships (v0.6.7+)
-  bin/doc.mjs          ← CLI: npx adia-ai-doc <name>                              ✓ ships (v0.6.7+)
-  USAGE.md             ← deep usage patterns (incl. data-stream-* §6)             ✓ ships
-
-node_modules/@adia-ai/web-modules/<cluster>/<name>/
-  Clusters: shell | chat | editor | simple | runtime | theme | generative
-  ↑ NEW v0.6.7: `generative` subpath bundles canvas-ui + a2ui-root + registerResolver
-```
-
-> **Examples ship as Markdown** (v0.6.7+). Each component has a `.examples.md`
-> with 1-3 canonical fragments — the authoring `.examples.html` files are
-> still in-repo only (they have full demo-page chrome too heavy to ship).
-> For richer visual reference, browse `https://ui-kit.exe.xyz/site/components/<name>`.
-
-Live component docs: `https://ui-kit.exe.xyz/site/components/<name>`
-(e.g. `https://ui-kit.exe.xyz/site/components/button`)
-
-**Component stability — `status` badge** (since v0.6.32+):
-
-When browsing `/site/components/<name>`, a colored `<tag-ui>` badge
-next to the component name indicates its stability:
-
-| Badge | Variant | Meaning |
-|-------|---------|---------|
-| (no badge) | — | `status: stable` — public API; safe to use |
-| `beta` | `warning` | Functional, but API may still change in MINOR releases |
-| `experimental` | `ghost` | Early prototype; expect breaking changes |
-| `deprecated` | `danger` | Replacement exists — check the page's `Related` section |
-| `early-access` | `info` | Customer-preview tier; consult release notes before relying on it |
-
-The status is set in `<name>.yaml` (`status: <value>`) and propagated
-automatically through the sidecar to the docs site. All current
-components ship `status: stable` (the vast majority show no badge).
-Authoring guidance for new components: see `adia-ui-authoring` skill
-yaml contract.
-
-**In the AdiaUI monorepo** (`/Users/kimba/Projects/adia/gen-ui-kit`):
-
-```
-packages/web-components/components/<name>/
-packages/web-modules/<cluster>/<name>/
-docs/specs/component-token-contract.md
-docs/specs/component-implementation-patterns.md
-```
-
-### Lookup procedure
-
-**Fastest path (v0.6.7+): use the bundled CLI.**
-
-```bash
-npx adia-ui-doc <name>      # yaml summary + live URL + first example
-npx adia-ui-doc              # list all 96 components
-```
-
-The CLI reads from the installed package, so it always reflects the
-version you're actually running.
-
-**For full detail, read the artifacts directly:**
-
-1. **List the catalog** (external): `ls node_modules/@adia-ai/web-components/components/ | sort`
-   Or in-repo: `ls packages/web-components/components/ | sort`
-2. **Read the yaml** for any component you plan to use:
-   ```
-   cat node_modules/@adia-ai/web-components/components/<name>/<name>.yaml
-   ```
-   Key sections: `props:`, `slots:`, `events:`, `tokens:`, `anti_patterns:`
-3. **Check a2ui.json** for enum values and prop types:
-   ```
-   cat node_modules/@adia-ai/web-components/components/<name>/<name>.a2ui.json
-   ```
-4. **For TypeScript users:** `<name>.d.ts` has the typed prop surface:
-   ```
-   cat node_modules/@adia-ai/web-components/components/<name>/<name>.d.ts
-   ```
-5. **For canonical markup examples** (v0.6.7+, ships in npm):
-   ```
-   cat node_modules/@adia-ai/web-components/components/<name>/<name>.examples.md
-   ```
-   1-3 fragments per component. For richer visual reference, browse
-   `https://ui-kit.exe.xyz/site/components/<name>`.
-6. **For behavioral edge cases:** `<name>.test.js` is the authoritative
-   spec — vitest tests document expected behavior including focus management,
-   keyboard nav, ARIA assertions.
-7. **For IDE / tool integration** (v0.6.7+): the package ships
-   `custom-elements.json` (W3C manifest v2.1.0). VS Code LSP extensions
-   pick this up automatically for autocomplete and type-safety.
-
-### Co-located registrations
-
-Some elements register inside their parent `.js` (not a separate
-directory): `list-item-ui`, `stepper-item-ui`, `avatar-group-ui`.
-If a directory doesn't exist, grep `customElements.define` in the
-parent before assuming the element is missing.
-
-### CSS-only components
-
-`header/`, `footer/`, `section/` ship yaml + a2ui.json only — no `.js`.
-They are styled by parent slot rules. Do not try to register them.
----

package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v1.md

@@ -1,8 +0,0 @@
-# adia-ui-kit Changelog — v1.x archive
-
-> Historical entries rolled out of the live [`CHANGELOG.md`](../../CHANGELOG.md), which keeps only the most recent 3. Newest-first.
-
-## 1.0.0 (2026-04-16)
-
-- Initial version
-- Migrated from skills/ to .claude/skills/ format