npm - @adia-ai/adia-ui-factory - Versions diffs - 0.2.2 → 0.2.4 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (95) hide show

package/.claude-plugin/plugin.json +12 -3
package/.mcp.json +1 -1
package/CHANGELOG.md +12 -0
package/README.md +24 -1
package/bin/adia-scaffold +93 -13
package/package.json +1 -1
package/references/shell-embed.md +10 -0
package/references/spa-architecture.md +7 -0
package/skills/adia-ui-kit/CHANGELOG.md +41 -0
package/skills/adia-ui-kit/SKILL.md +442 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/Guidelines.md +87 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/components.md +142 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/styles.md +118 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/tokens.md +120 -0
package/skills/adia-ui-kit/assets/team-scaffold/archive-README.md +30 -0
package/skills/adia-ui-kit/assets/team-scaffold/drafts-README.md +57 -0
package/skills/adia-ui-kit/assets/team-scaffold/inbox-README.md +76 -0
package/skills/adia-ui-kit/assets/team-scaffold/outbox-README.md +46 -0
package/skills/adia-ui-kit/assets/team-scaffold/team-root.README.md +51 -0
package/skills/adia-ui-kit/assets/team-scaffold/tickets-README.md +208 -0
package/skills/adia-ui-kit/assets/team-scaffold/tickets-REGISTRY.md +81 -0
package/skills/adia-ui-kit/assets/templates/AGENTS.template.md +128 -0
package/skills/adia-ui-kit/assets/templates/CLAUDE.template.md +1 -0
package/skills/adia-ui-kit/assets/templates/FEEDBACK-OMISSIONS-DEFENSE.template.md +150 -0
package/skills/adia-ui-kit/assets/templates/FEEDBACK.template.md +213 -0
package/skills/adia-ui-kit/assets/templates/RESPONSE.template.md +114 -0
package/skills/adia-ui-kit/assets/templates/figma-make-guidelines.md +90 -0
package/skills/adia-ui-kit/evals/adversarial-content-trust.json +83 -0
package/skills/adia-ui-kit/evals/evals.json +55 -0
package/skills/adia-ui-kit/evals/routing-corpus.json +121 -0
package/skills/adia-ui-kit/evals/teach-routing-cases.json +92 -0
package/skills/adia-ui-kit/references/capabilities.md +245 -0
package/skills/adia-ui-kit/references/catalog-lookup.md +186 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v1.md +8 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v2.md +3585 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v3.md +1899 -0
package/skills/adia-ui-kit/references/common-gotchas-consumer.md +522 -0
package/skills/adia-ui-kit/references/component-literacy.md +291 -0
package/skills/adia-ui-kit/references/composition.md +245 -0
package/skills/adia-ui-kit/references/correction-loop.md +462 -0
package/skills/adia-ui-kit/references/css-policy.md +343 -0
package/skills/adia-ui-kit/references/decision-model.md +158 -0
package/skills/adia-ui-kit/references/diagnostic-output.md +57 -0
package/skills/adia-ui-kit/references/docs-catalog.md +239 -0
package/skills/adia-ui-kit/references/exclusions.md +225 -0
package/skills/adia-ui-kit/references/feedback-authoring.md +466 -0
package/skills/adia-ui-kit/references/figma-make.md +244 -0
package/skills/adia-ui-kit/references/flows-auth.md +307 -0
package/skills/adia-ui-kit/references/flows-content.md +206 -0
package/skills/adia-ui-kit/references/flows-data.md +348 -0
package/skills/adia-ui-kit/references/flows-interaction.md +181 -0
package/skills/adia-ui-kit/references/flows-shells.md +336 -0
package/skills/adia-ui-kit/references/gap-detection.md +266 -0
package/skills/adia-ui-kit/references/harness.md +284 -0
package/skills/adia-ui-kit/references/loading-protocol.md +406 -0
package/skills/adia-ui-kit/references/local-link.md +198 -0
package/skills/adia-ui-kit/references/mcp.md +401 -0
package/skills/adia-ui-kit/references/migration.md +116 -0
package/skills/adia-ui-kit/references/mission.md +194 -0
package/skills/adia-ui-kit/references/mode-routing.md +298 -0
package/skills/adia-ui-kit/references/patterns-agent.md +223 -0
package/skills/adia-ui-kit/references/patterns-data.md +1065 -0
package/skills/adia-ui-kit/references/patterns-forms.md +223 -0
package/skills/adia-ui-kit/references/patterns-layout.md +326 -0
package/skills/adia-ui-kit/references/patterns-recipes.md +1416 -0
package/skills/adia-ui-kit/references/patterns-shells.md +1097 -0
package/skills/adia-ui-kit/references/patterns-traits.md +259 -0
package/skills/adia-ui-kit/references/patterns-wiring.md +339 -0
package/skills/adia-ui-kit/references/pev-rationale.md +137 -0
package/skills/adia-ui-kit/references/reasoning-gate.md +146 -0
package/skills/adia-ui-kit/references/reasoning-methodologies.md +112 -0
package/skills/adia-ui-kit/references/recon.md +192 -0
package/skills/adia-ui-kit/references/rendering-model.md +431 -0
package/skills/adia-ui-kit/references/response-authoring.md +398 -0
package/skills/adia-ui-kit/references/session-log-schema.md +203 -0
package/skills/adia-ui-kit/references/session-log-template.md +118 -0
package/skills/adia-ui-kit/references/setup.md +652 -0
package/skills/adia-ui-kit/references/skill-hygiene.md +135 -0
package/skills/adia-ui-kit/references/spec-to-ui-reasoning.md +394 -0
package/skills/adia-ui-kit/references/state.md +229 -0
package/skills/adia-ui-kit/references/teach-protocol.md +421 -0
package/skills/adia-ui-kit/references/theme.md +142 -0
package/skills/adia-ui-kit/references/version-check.md +69 -0
package/skills/adia-ui-kit/scripts/audit-decision-trace.mjs +198 -0
package/skills/adia-ui-kit/scripts/audit-kit-roster.mjs +366 -0
package/skills/adia-ui-kit/scripts/changelog-archive.mjs +126 -0
package/skills/adia-ui-kit/scripts/check-adia-versions.py +404 -0
package/skills/adia-ui-kit/scripts/run-skill-evals.mjs +358 -0
package/skills/adia-ui-kit/scripts/validate-session-log.mjs +242 -0
package/skills/adia-ui-kit/skill.json +102 -0
package/skills/adia-ui-migration/CHANGELOG.md +47 -0
package/skills/adia-ui-migration/SKILL.md +381 -0
package/skills/adia-ui-migration/skill.json +29 -0
package/skills/adia-ui-spa/SKILL.md +1 -1
package/skills/adia-ui-verify/SKILL.md +2 -2

package/skills/adia-ui-kit/references/theme.md ADDED Viewed

@@ -0,0 +1,142 @@
+---
+name: theme
+load-when: When customizing theme — color schemes, density, brand colors, custom themes, toggle-scheme, Cmd+K command palette
+load-size-tokens: ~1,200
+required-for:
+  - theme customization
+  - brand integration
+---
+# §Theme — Color scheme, density, custom themes
+AdiaUI ships a three-knob theming contract. All themes are CSS-only,
+no runtime JS required.
+### Three knobs
+| Knob | What it controls | How to set |
+|---|---|---|
+| **Named theme** | Token palette (`[theme="ocean"]` swaps `--a-*` values) | `<html theme="ocean">` |
+| **Color scheme** | Light / dark within a theme | `<html style="color-scheme: light">` or use `<toggle-scheme-ui>` |
+| **Density / radius** | `--a-density` (0–1), `--a-radius-k` (multiplier) | inline `style` or `[data-density="cozy"]` |
+Eight named themes ship by default (`default`, `ocean`, `forest`, `sunset`,
+`graphite`, `paper`, `ink`, `neon`). Add `theme="<slug>"` to `<html>` or
+any ancestor element to apply.
+### Add a scheme toggle (light/dark)
+```html
+<!-- One-line scheme toggle, persists to localStorage -->
+<toggle-scheme-ui scheme="auto"></toggle-scheme-ui>
+```
+> **Placement.** Put `<toggle-scheme-ui>` in the shell topbar's trailing
+> `slot="action"` cluster — inside `<admin-topbar slot="header">` of
+> `<admin-content>`. That is the persistent top-right home for app-wide
+> preference controls. Do **not** put it in the sidebar footer: a global
+> preference buried there reads as navigation and vanishes when the
+> sidebar collapses.
+The component:
+- Reads `prefers-color-scheme` for `auto`
+- Writes the resolved scheme to `<html style="color-scheme: ...">`
+- Persists to `localStorage` under the `adia-theme-` namespace
+- Swaps moon/sun icon automatically
+Attributes: `scheme="auto|light|dark"`, `target="<selector>"` (default `:root`).
+```js
+// Listen for scheme changes
+document.querySelector('toggle-scheme-ui').addEventListener('scheme-change', e => {
+  console.log('new scheme:', e.detail.scheme);  // 'light' | 'dark'
+});
+```
+### Full theme panel (settings page)
+`<theme-panel>` exposes all three knobs in one composition. Drop into a
+settings section or popover.
+```html
+<popover-ui>
+  <button-ui slot="trigger" icon="palette" variant="ghost"></button-ui>
+  <theme-panel slot="content"
+    parametric
+    presets
+    scheme-toggle>
+  </theme-panel>
+</popover-ui>
+```
+Imports (not in barrel — composes 5 primitives):
+```js
+import '@adia-ai/web-components/components/toggle-scheme/toggle-scheme.js';
+import '@adia-ai/web-modules/theme/theme-panel/theme-panel.js';
+```
+### Brand-color overrides
+To override the brand palette without a full custom theme, write a small
+CSS block that targets the semantic tokens:
+```css
+/* main.css — after `@adia-ai/web-components/css` */
+:root {
+  --a-primary-bg:     #3b82f6;   /* your brand blue */
+  --a-primary-fg:     white;
+  --a-primary-strong: #1d4ed8;
+  --a-accent-bg:      #ec4899;   /* your accent pink */
+  --a-accent-fg:      white;
+}
+/* Dark scheme override */
+:root[style*="color-scheme: dark"] {
+  --a-primary-bg: #60a5fa;
+  --a-primary-strong: #93c5fd;
+}
+```
+Only override semantic tokens (`--a-*-bg`, `--a-*-fg`, `--a-*-strong`).
+Never override component-internal tokens (`--button-ui-padding`, etc.) —
+those are implementation details and will break with version bumps.
+### Custom theme (`[theme="my-brand"]`)
+For a full custom palette across many tokens, define a theme block:
+```css
+/* themes/my-brand.css */
+[theme="my-brand"] {
+  /* Surface */
+  --a-bg:           hsl(220 20% 99%);
+  --a-bg-muted:     hsl(220 20% 96%);
+  --a-bg-strong:    hsl(220 20% 92%);
+  --a-fg:           hsl(220 30% 12%);
+  --a-fg-subtle:    hsl(220 15% 45%);
+  /* Chrome / borders */
+  --a-chrome-strong: hsl(220 15% 80%);
+  --a-chrome-bg:     hsl(220 15% 90%);
+  /* Primary / accent / danger / success / warning / info */
+  --a-primary-bg:    hsl(252 100% 60%);
+  --a-primary-fg:    white;
+  --a-accent-bg:     hsl(340 80% 55%);
+  /* ... */
+}
+[theme="my-brand"][style*="color-scheme: dark"] {
+  --a-bg: hsl(220 30% 8%);
+  /* ... */
+}
+```
+Apply with `<html theme="my-brand">`.
+> **Token reference:** see `node_modules/@adia-ai/web-components/styles/tokens.css`
+> for the full semantic-token surface. Roughly 80 tokens across surfaces,
+> chrome, semantic colors, spacing, radius, and motion.
+---

package/skills/adia-ui-kit/references/version-check.md ADDED Viewed

@@ -0,0 +1,69 @@
+---
+name: version-check
+load-when: Before any authoring — verifies that the installed `@adia-ai/*` version matches the kit's targeted shape (current lockstep is v0.6.33)
+load-size-tokens: ~750
+required-for:
+  - cold-start version sanity
+  - pre-author bundle gate companion
+---
+# §VersionCheck — Verify the install matches what the skill describes
+**Why this gate exists.** The 9 `@adia-ai/*` packages ship in lockstep,
+and skill guidance is version-sensitive. Before trusting a stale install,
+run:
+```bash
+scripts/check-adia-versions.py
+```
+(Path relative to the consumer project that has this skill installed.
+If running from another consumer, pass `--root /path/to/consumer`.)
+The script reports three sources side-by-side: **installed**
+(node_modules), **declared** (package.json), **latest** (npm registry).
+It classifies drift and exits non-zero when something needs attention.
+**Exit codes**
+- `0` — install is clean: lockstep aligned, declarations match installs,
+  and installed ≥ latest published (or you used `--offline`).
+- `1` — drift detected. The text output names every package + suggests
+  the fix (`npm install @adia-ai/X@latest`, `npm install`, or wipe +
+  reinstall to repair split lockstep).
+- `2` — unrecoverable (no `package.json` or no `node_modules` at root).
+**Status legend**
+| Marker | Meaning | Fix |
+|---|---|---|
+| ✓ ok | installed == declared, matches latest | — |
+| ⚠ stale | installed < latest published | `npm install @adia-ai/<pkg>@latest` |
+| ⚠ split | lockstep broken — packages disagree on version | wipe `node_modules` + lockfile, reinstall |
+| ⚠ undeclared | user-facing package installed but not in package.json | add to `dependencies` |
+| ⚠ uninstalled | declared but missing from node_modules | `npm install` |
+| ⓘ ahead | installed > latest published (dev cut / local tarball) | informational, not an error |
+**Flags**
+- `--offline` — skip `npm view` (no network). Still verifies lockstep
+  + declared vs. installed; just can't tell you about staleness.
+- `--json` — machine-readable for agent harnesses.
+- `--root <path>` — explicit consumer root (default: cwd).
+**When to run it**
+- Once at the start of any new project work (cold-start gate).
+- After any `npm install` or `npm update` involving `@adia-ai/*`.
+- Before filing a feedback ticket — version coherence is required
+  evidence (see §FeedbackDiscipline principle 4 "verify before
+  claiming").
+- When a piece of skill guidance contradicts your install (the script
+  tells you which side is stale).
+**Monorepo-root behavior.** The script auto-detects the `@adia-ai/*`
+source monorepo via the `workspaces` field and suppresses "undeclared"
+warnings there. The "ⓘ ahead" status is expected in the monorepo when
+sources are bumped but not yet published.
+---

package/skills/adia-ui-kit/scripts/audit-decision-trace.mjs ADDED Viewed

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * audit-decision-trace.mjs (adia-ui-kit v3.1.0+)
+ *
+ * Walks a JSONL session log (per references/session-log-schema.md) and
+ * audits component-trace coverage: every component_named event should
+ * trace to ≥1 decision_made event whose possible_actions array contains
+ * (or whose chosen_action equals) the named component.
+ *
+ * Per REFACTOR-SPEC P5(b). See references/decision-model.md for the
+ * contract.
+ *
+ * Default mode: --advisory — prints findings + summary; exit 0 even if
+ * orphans found (advisory rollout — collecting baseline for v3.2.0
+ * promotion to hard-fail).
+ *
+ * Strict mode: --strict — exits 1 on any orphan finding.
+ *
+ * Usage:
+ *   node audit-decision-trace.mjs <session-log.jsonl>
+ *   node audit-decision-trace.mjs <session-log.jsonl> --strict
+ *   node audit-decision-trace.mjs <session-log.jsonl> --json
+ *   node audit-decision-trace.mjs <session-log.jsonl> --allowlist=path/to/.decision-trace-allowlist.json
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(__filename);
+const KIT_DIR = path.dirname(SCRIPT_DIR);
+function loadAllowlist(allowlistPath) {
+  if (!allowlistPath) return new Set();
+  if (!fs.existsSync(allowlistPath)) return new Set();
+  try {
+    const obj = JSON.parse(fs.readFileSync(allowlistPath, 'utf8'));
+    return new Set((obj.allowed_orphans || []).map(e => e.tag));
+  } catch (err) {
+    console.error(`⚠ Could not parse allowlist ${allowlistPath}: ${err.message}`);
+    return new Set();
+  }
+}
+function readJsonlEvents(logPath) {
+  const content = fs.readFileSync(logPath, 'utf8');
+  const lines = content.split('\n').filter(l => l.trim().length > 0);
+  const events = [];
+  lines.forEach((line, idx) => {
+    try {
+      events.push({ ...JSON.parse(line), _line: idx + 1 });
+    } catch {
+      // skip malformed lines (validate-session-log surfaces them separately)
+    }
+  });
+  return events;
+}
+function extractDecisionsAndComponents(events) {
+  const decisions = events.filter(e => e.event_type === 'decision_made');
+  const components = events.filter(e => e.event_type === 'component_named');
+  return { decisions, components };
+}
+/**
+ * Normalize an action string to a canonical component tag.
+ * Examples:
+ *   "button-ui variant=primary [type=submit] [loading]" → "button-ui"
+ *   "input-ui type=email" → "input-ui"
+ *   "form-field with input-ui" → "form-field" (and also matches "input-ui")
+ *   "none (raw)" → "none" (sentinel)
+ */
+function extractTagsFromAction(action) {
+  if (!action || typeof action !== 'string') return [];
+  // Match anything that looks like a component tag (lowercase-with-hyphens, ending in -ui or known suffix or containing -)
+  const tagPattern = /\b([a-z][a-z0-9]*(?:-[a-z0-9]+)+)\b/g;
+  const tags = new Set();
+  let m;
+  while ((m = tagPattern.exec(action)) !== null) {
+    tags.add(m[1]);
+  }
+  return [...tags];
+}
+function auditTrace(events, allowlist) {
+  const { decisions, components } = extractDecisionsAndComponents(events);
+  // Build the universe of tags traced to any decision (possible_actions ∪ chosen_action)
+  const tracedTags = new Set();
+  for (const d of decisions) {
+    const p = d.payload || {};
+    const actions = Array.isArray(p.possible_actions) ? p.possible_actions : [];
+    for (const action of actions) {
+      for (const tag of extractTagsFromAction(action)) {
+        tracedTags.add(tag);
+      }
+    }
+    if (p.chosen_action) {
+      for (const tag of extractTagsFromAction(p.chosen_action)) {
+        tracedTags.add(tag);
+      }
+    }
+  }
+  // Walk component_named events; flag any tag not in tracedTags ∪ allowlist
+  const findings = [];
+  const allTagsObserved = new Set();
+  for (const c of components) {
+    const tag = c.payload?.tag;
+    if (!tag) continue;
+    allTagsObserved.add(tag);
+    if (tracedTags.has(tag)) continue;
+    if (allowlist.has(tag)) continue;
+    findings.push({
+      line: c._line,
+      severity: 'orphan',
+      tag,
+      session_id: c.session_id,
+      context: c.payload?.context || '(no context)',
+      msg: `Component "${tag}" named at line ${c._line} but no decision_made event lists it in possible_actions or chosen_action, and it's not in the allowlist.`,
+    });
+  }
+  return {
+    decision_count: decisions.length,
+    component_named_count: components.length,
+    unique_tags_observed: [...allTagsObserved].sort(),
+    unique_tags_traced: [...tracedTags].sort(),
+    allowlist_size: allowlist.size,
+    orphan_count: findings.length,
+    findings,
+  };
+}
+function main() {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const strict = args.includes('--strict');
+  // Default: advisory
+  const advisory = args.includes('--advisory') || !strict;
+  const allowlistArg = args.find(a => a.startsWith('--allowlist='));
+  const logPath = args.find(a => !a.startsWith('--'));
+  if (!logPath) {
+    console.error('Usage: audit-decision-trace.mjs <session-log.jsonl> [--strict] [--json] [--allowlist=path]');
+    process.exit(2);
+  }
+  if (!fs.existsSync(logPath)) {
+    console.error(`✗ Session log not found: ${logPath}`);
+    process.exit(2);
+  }
+  // Try kit-default allowlist if not specified
+  const defaultAllowlist = path.join(KIT_DIR, '.decision-trace-allowlist.json');
+  const allowlistPath = allowlistArg
+    ? allowlistArg.slice('--allowlist='.length)
+    : (fs.existsSync(defaultAllowlist) ? defaultAllowlist : null);
+  const allowlist = loadAllowlist(allowlistPath);
+  const events = readJsonlEvents(logPath);
+  const result = auditTrace(events, allowlist);
+  const mode = strict ? 'STRICT' : 'ADVISORY';
+  if (json) {
+    console.log(JSON.stringify({ mode, allowlist_path: allowlistPath, ...result }, null, 2));
+  } else {
+    console.log(`\n══ audit-decision-trace — ${logPath} ══`);
+    console.log(`Mode:             ${mode}${advisory && !strict ? ' (default: never fails; v3.2.0 may promote to hard-fail — see references/decision-model.md)' : ''}`);
+    console.log(`Allowlist:        ${allowlistPath || '(none)'} (${result.allowlist_size} entries)`);
+    console.log(`Decisions:        ${result.decision_count}`);
+    console.log(`Components named: ${result.component_named_count}`);
+    console.log(`Unique tags:      ${result.unique_tags_observed.length} observed; ${result.unique_tags_traced.length} traced`);
+    console.log(`Orphan findings:  ${result.orphan_count}`);
+    if (result.findings.length > 0) {
+      console.log(`\nOrphan-component findings (named without traced decision):`);
+      for (const f of result.findings) {
+        console.log(`  ⚠ line ${f.line}: tag="${f.tag}" context="${f.context}"`);
+      }
+      console.log(`\nResolution paths:`);
+      console.log(`  1. Retroactively add a decision_made event with this tag in possible_actions.`);
+      console.log(`  2. Add the tag to .decision-trace-allowlist.json with a rationale.`);
+      console.log(`  3. Remove the orphan component from the composition.`);
+    } else {
+      console.log(`\n✓ No orphan-component findings.`);
+    }
+  }
+  if (strict && result.orphan_count > 0) {
+    process.exit(1);
+  }
+  process.exit(0);
+}
+main();