@adia-ai/adia-ui-factory 0.8.2 → 0.8.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-factory",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "a2ui": {
       "command": "npx",
-      "args": ["-y", "@adia-ai/a2ui-mcp@0.8.2"]
+      "args": ["-y", "@adia-ai/a2ui-mcp@0.8.3"]
     }
   }
 }

package/CHANGELOG.md

@@ -1,4 +1,15 @@
 # Changelog — adia-factory
+## [0.8.3] — 2026-07-16
+
+### Added
+- **`adia-tokens` knowledge pack** (`skills/adia-tokens/`, gh#265): the consumer-facing "which color token/role" answerer — role grammar + the six pairing laws (incl. the fill-contrast operator ruling), the `--a-*`-vs-Material layer choice, and two cut-time-GENERATED references (the 8×53 role roster and the full 206-row `--a-*` → Material bridge table), regenerated + CI-gated from the framework token sources so the corpus cannot drift. Routing evals included; `adia-compose` routes token questions here.
+- **`skills/adia-llm` verify-gates table + debugging catalog**: the key-in-client gate now cites the `adia-lint` rule that mechanizes it; a source-grounded symptom→cause table headlines the two runtime traps whose docs Wave 0 corrected (`Unknown provider "google"` throw; `GEMINI_API_KEY` vs `GOOGLE_API_KEY`).
+
+### Changed
+- **`commands/` refreshed to the post-campaign estate**: `/adia-verify` dispatches the read-only consumer-verifier seat (generator ≠ critic); NEW `/adia-info`; `/adia-migrate` carries the shipped-guide path + consent options; `/adia-scaffold` surfaces inventory mode; `/adia-genui` closes with the Generation Record.
+
+### Maintenance
+- `.mcp.json` a2ui-mcp pin → 0.8.3 (invariant 8); `packages/plugins/adia-ui-factory/.claude-plugin/plugin.json` moves in lockstep (the `/plugin update` cache key).
 ## [0.8.2] — 2026-07-16
 
 ### The modernization campaign (gh#259, Waves 0–3 + the command refresh)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",

package/skills/adia-compose/SKILL.md

@@ -118,4 +118,4 @@ el.append(new Option('A', 'a'));       // wrong: renders outside the popover
 | Filing findings upstream to @adia-ai maintainers | [`references/feedback-discipline.md`](references/feedback-discipline.md) + [`assets/templates/`](assets/templates/) |
 | Seeding a Figma Make kit with adia-ui | drop [`assets/figma-make/guidelines/`](assets/figma-make/guidelines/) into the kit |
 
-Neighboring work routes out: shell selection/chrome → `adia-shells` · host registration/SSR → `adia-host` · hydration/state/CRUD → `adia-data` · generative-UI runtime → `adia-genui` · browser QA/a11y → `adia-verify`.
+Neighboring work routes out: shell selection/chrome → `adia-shells` · host registration/SSR → `adia-host` · hydration/state/CRUD → `adia-data` · generative-UI runtime → `adia-genui` · browser QA/a11y → `adia-verify` · "which token/role" questions → `adia-tokens`.

package/skills/adia-llm/SKILL.md

@@ -26,9 +26,25 @@ Standing contract for wiring `@adia-ai/llm` (the lockstep version your app insta
 - NOT in the package: tool-calling, structured-output modes, retry/backoff, token estimation — server-layer concerns, not client options.
 - `<chat-shell proxy-url="/api/chat" model="…">` auto-sends on submit and renders the stream itself; without `proxy-url` it only emits `submit` for the app to handle.
 
-## Verify target
-
-An LLM feature is done when it streams in a real page with zero console errors, all four chunk branches observably drive the UI, and no provider key is reachable in the browser — production network requests carry the provider-neutral smart-proxy body and no upstream auth headers.
+## Verify gates
+
+| Gate | Pass condition | Enforcement |
+| --- | --- | --- |
+| Key never in client `[gate]` | no provider key reachable in browser source or network requests; production requests carry the provider-neutral smart-proxy body, no upstream auth headers | mechanized: `adia-lint` `LLM-KEY-IN-CLIENT` fires on every write (server/api/proxy paths exempt); the network half is checked in the browser gate |
+| Streams live | streams in a real page, zero console/page errors | `adia-verify`'s browser gate (`bin/adia-probe.mjs`) |
+| All 4 chunk branches drive UI | `text`/`thinking`/`done`/`error` each observably changes the surface; an `error` chunk renders, never drops | self-verified — exercise each branch (the stub provider exists for exactly this) |
+| Provider name legal | `provider` ∈ anthropic \| openai \| gemini on the streamChat path — unknown names THROW | self-verified against `adapters/index.js`; the docs said `google` until 2026-07-16, real apps may carry it |
+
+## Symptom → cause (the debugging catalog)
+
+| Symptom | Cause → fix |
+| --- | --- |
+| `Unknown provider "google"` throw | the pre-0.8.2 docs' enum — use `gemini` (llm.md; the `google`/`stub` values belong to the separate `llm-bridge.js` entry) |
+| Silent auth failure on a Gemini proxy | server reads `GEMINI_API_KEY`, not `GOOGLE_API_KEY` (server.js) |
+| Chat renders but nothing streams on submit | no `proxy-url` on `<chat-shell>` — it only emits `submit` for the app to handle; set `proxy-url` for auto-send |
+| Stream stops mid-answer, no error shown | the `error` StreamChunk branch is being dropped instead of rendered — every branch drives the UI |
+| Works in dev, 401s deployed | the passthrough shape (`/api/llm/<provider>/…`) shipped to production — it puts the key in browser headers; production is the smart proxy |
+| Composer is 0px | `<chat-input-ui>` isn't in the chat barrel — import it (and its internal `textarea-ui`/`select-ui`) separately (shell-chat.md §Gotchas) |
 
 ## References
 

package/skills/adia-tokens/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: adia-tokens
+description: >-
+  Answers which color token/role an adia-ui surface should use — role
+  grammar, pairing laws, state families, the --a-* alias layer. Use when
+  asked "which token for this background/text/hover/border" or "--a-* or
+  --md-sys-color-*". ANSWERS only. NOT for composing the screen
+  (adia-compose) or designing/verifying palettes (framework-side).
+disable-model-invocation: false
+user-invocable: false
+---
+
+# adia-tokens — which color role, answered
+
+The color system's public API is semantic roles, never values: if a color
+isn't a `--md-sys-color-*` role or an `--a-*` alias, it doesn't go in UI
+code — no hex, no `oklch()`, no raw `-050…-950` stop, no `color-mix()`
+state synthesis. This pack answers the "which role" question; the values
+themselves live in the installed CSS and are never restated here.
+
+## The grammar
+
+`--md-sys-color-{palette}{suffix}` — 8 palettes (`neutral` chrome ·
+`primary` brand accent · `secondary`/`tertiary` support · the four intents
+`info/success/warning/danger`, which carry MEANING only, never decoration).
+The on-accent role uses the palette's OWN slug:
+`--md-sys-color-danger-on-danger` sits on `--md-sys-color-danger`. The full
+suffix roster with per-family meaning: [`references/role-roster.md`](references/role-roster.md)
+(GENERATED from the installed export — trust it over memory).
+
+## The laws (violating any is a defect)
+
+1. **Pairing** — ink sits only on its own palette's legal ground:
+   `-on-{p}` on the accent fill; `-on-surface` on that palette's
+   surfaces/containers/background. Never cross palettes mid-pair.
+2. **States ship as families** — where `-hover/-active/-disabled` siblings
+   exist, use them verbatim; never synthesize a state with opacity or
+   `color-mix()`. Not every role has siblings — the roster is the map.
+3. **The scheme is baked in** — every role flips via `light-dark()`; write
+   each color once. Force a subtree with `color-scheme:`, never per-color
+   `@media` overrides.
+4. **Elevation is the surface ladder** — raise/recess with
+   `-surface-{dim…bright}` / `-surface-{low…high}` tiers; shadows are
+   garnish, opacity is a defect.
+5. **On-accent ink is fixed light in both schemes, by design** — it
+   deliberately overrides per-pair contrast math (operator ruling
+   2026-07-16, recorded in the framework's color-bridge contract: fill-pair
+   contrast is an upstream design decision — do not "fix" it locally with
+   dark text or auto-contrast).
+6. **Roles by their named purpose, never by coincidental value** — no
+   `--a-bg` as a foreground, no chart identity tokens (`--a-data-0..9`)
+   for semantic state, and vice versa.
+
+Depth and adia-specific notes per law: [`references/pairing-laws.md`](references/pairing-laws.md).
+
+## Which layer — `--a-*` or `--md-sys-color-*`?
+
+Both are public. `--a-*` is the compact alias layer most component CSS and
+older app code consumes; the Material roles are the source of truth it
+reads from. Match the file you're editing (don't mix mid-file); for NEW
+code prefer the Material role — it's the finer-grained vocabulary. The
+full alias→role mapping: [`references/a-alias-layer.md`](references/a-alias-layer.md)
+(GENERATED — the authoritative bridge table).
+
+## Consult table
+
+| Ask | Answer from |
+| --- | --- |
+| "which role for this button/badge/toast/border/text" | the grammar + laws above, then [`role-roster.md`](references/role-roster.md) for the exact suffix |
+| "what does `--a-<x>` actually resolve to" | [`a-alias-layer.md`](references/a-alias-layer.md) |
+| "hover/disabled color for X" | law 2 — the role's own state family, from the roster |
+| "make it work in dark mode" | law 3 — it already does; check the subtree's `color-scheme` before touching tokens |
+| "this pair looks low-contrast" | law 5 first (on-accent is by design); genuine canvas-text pairs are gated by the framework's `verify:contrast` |
+
+The generated references are produced in the framework monorepo at cut
+time (producer-side, CI-gated) — in a consumer repo they describe the
+version you installed; never edit them. Choosing and wiring the tokens into a
+screen is `adia-compose`'s job; this pack only answers.

package/skills/adia-tokens/evals/routing-corpus.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-tokens-routing-corpus",
+  "version": "0.1.0",
+  "purpose": "Routing floor for the adia-tokens knowledge pack: 'which color token/role' asks reach it; composition, palette-design, and value-verification asks route past it.",
+  "scoring_notes": "Heuristic TF-IDF proxy (scripts/skills/run-skill-evals.mjs); the real harness routes on descriptions. Treat misroutes as description-tightening signals.",
+  "license": "internal",
+  "scope": "adia-ui-factory plugin, consumer-side. In the framework monorepo the operator's private design-systems plugin carries a broader Material-tokens skill — overlap there is inherent and acceptable; this pack exists for consumer installs without it.",
+  "minimums_per_spec": {
+    "trigger_phrases": 12,
+    "adversarial_phrases": 5,
+    "task_shapes_covered": "which-role, state-family, layer-choice, alias-resolution, dark-mode, contrast-complaint",
+    "adversarial_fraction": "29%"
+  },
+  "phrases": [
+    { "id": "tokens-role-01", "phrase": "which token should this card background use", "should_route_to_tokens": true, "expected_shape": "which-role", "rationale": "The pack's flagship ask — role for a surface." },
+    { "id": "tokens-role-02", "phrase": "what color role for the text on this danger badge", "should_route_to_tokens": true, "expected_shape": "which-role", "rationale": "Pairing-law territory: ink on an intent fill." },
+    { "id": "tokens-role-03", "phrase": "which --md-sys-color role for a subtle divider", "should_route_to_tokens": true, "expected_shape": "which-role", "rationale": "Outline-family lookup by need." },
+    { "id": "tokens-role-04", "phrase": "what token for a toast that must read as a warning", "should_route_to_tokens": true, "expected_shape": "which-role", "rationale": "Intent palette selection + container family." },
+    { "id": "tokens-state-01", "phrase": "add hover and disabled colors to this button", "should_route_to_tokens": true, "expected_shape": "state-family", "rationale": "Law 2 — baked state families, never synthesized." },
+    { "id": "tokens-state-02", "phrase": "how do I dim this control when it's disabled", "should_route_to_tokens": true, "expected_shape": "state-family", "rationale": "The opacity anti-pattern's replacement." },
+    { "id": "tokens-layer-01", "phrase": "should I use --a-primary or --md-sys-color-primary here", "should_route_to_tokens": true, "expected_shape": "layer-choice", "rationale": "The two-layer question the pack owns." },
+    { "id": "tokens-alias-01", "phrase": "what does --a-canvas-well actually resolve to", "should_route_to_tokens": true, "expected_shape": "alias-resolution", "rationale": "The generated alias table's row lookup." },
+    { "id": "tokens-dark-01", "phrase": "make this panel's colors work in dark mode", "should_route_to_tokens": true, "expected_shape": "dark-mode", "rationale": "Law 3 — scheme baked in; check color-scheme, not tokens." },
+    { "id": "tokens-elev-01", "phrase": "which surface tier makes this card read as raised", "should_route_to_tokens": true, "expected_shape": "which-role", "rationale": "Law 4 — the elevation ladder." },
+    { "id": "tokens-contrast-01", "phrase": "the white text on our warning button looks low contrast — which token fixes it", "should_route_to_tokens": true, "expected_shape": "contrast-complaint", "rationale": "Law 5 — the answer is the ruling (by design, don't patch), which only this pack carries consumer-side." },
+    { "id": "tokens-chart-01", "phrase": "which tokens color the chart series vs the error state", "should_route_to_tokens": true, "expected_shape": "which-role", "rationale": "Law 6 — identity vs state token classes." },
+    { "id": "tokens-adv-01", "phrase": "build the settings screen with proper tokens", "should_route_to_tokens": false, "expected_alternative": "adia-compose (adia-ui-factory)", "rationale": "Adversarial — composition consumes the answer; the ask is a build." },
+    { "id": "tokens-adv-02", "phrase": "design a new color ramp from our brand blue", "should_route_to_tokens": false, "expected_alternative": "framework-side palette design (not this plugin)", "rationale": "Adversarial — palette DESIGN is upstream; this pack answers consumption." },
+    { "id": "tokens-adv-03", "phrase": "check the contrast ratio of this text on this background", "should_route_to_tokens": false, "expected_alternative": "framework verify:contrast / operator tooling", "rationale": "Adversarial — value verification, not role choice." },
+    { "id": "tokens-adv-04", "phrase": "the page renders blank after my token change", "should_route_to_tokens": false, "expected_alternative": "adia-verify (adia-ui-factory)", "rationale": "Adversarial — a broken render is the browser gate's territory." },
+    { "id": "tokens-adv-05", "phrase": "add a new token to the framework's core.css", "should_route_to_tokens": false, "expected_alternative": "adia-author (adia-ui-forge)", "rationale": "Adversarial — framework token AUTHORING is forge-side." }
+  ],
+  "evaluator_notes": {
+    "known_limitations": "In the framework monorepo, the operator's private design-systems:material-design-color-tokens skill legitimately overlaps every positive here — the fence is install-context, not phrasing; do not tune descriptions to separate them.",
+    "promotion_criteria": "F1 >= 0.85 across 3+ runs",
+    "review_cadence": "on any description edit; on /eval-run findings"
+  }
+}

package/skills/adia-tokens/references/a-alias-layer.md

@@ -0,0 +1,218 @@
+<!-- GENERATED — do not edit. Source: packages/web-components/styles/colors/semantics/core.css.
+     Provenance: produced in the framework monorepo at cut time by
+     scripts/release/check-token-semantics-sync.mjs (producer-side tooling,
+     not runnable from a consumer install — in a consumer repo this file
+     describes the version you installed). -->
+
+# The `--a-*` alias layer — what each token reads
+
+The `--a-*` semantic layer is a thin alias layer reading FROM the `--md-sys-color-*` static export (the color source of truth since v0.8.0). Both layers are public; components consume `--a-*` roles or Material roles directly — the mapping below is the bridge. 206 declarations.
+
+| `--a-*` token | Reads |
+|---|---|
+| `--a-canvas-strong` | `var(--md-sys-color-neutral-surface-high)` |
+| `--a-canvas` | `var(--md-sys-color-neutral-surface)` |
+| `--a-canvas-subtle` | `var(--md-sys-color-neutral-surface-dim)` |
+| `--a-canvas-muted` | `var(--md-sys-color-neutral-surface-dimmer)` |
+| `--a-canvas-hover` | `var(--md-sys-color-neutral-hover)` |
+| `--a-canvas-active` | `var(--md-sys-color-neutral-active)` |
+| `--a-canvas-selected` | `var(--md-sys-color-neutral-container-active)` |
+| `--a-canvas-text-strong` | `var(--md-sys-color-neutral-on-surface)` |
+| `--a-canvas-text` | `var(--md-sys-color-neutral-on-surface)` |
+| `--a-canvas-text-subtle` | `var(--md-sys-color-neutral-on-surface-variant)` |
+| `--a-canvas-text-muted` | `var(--md-sys-color-neutral-on-surface-variant)` |
+| `--a-canvas-text-disabled` | `var(--md-sys-color-neutral-on-surface-disabled)` |
+| `--a-canvas-text-inverse` | `var(--md-sys-color-neutral-inverse-on-surface)` |
+| `--a-canvas-surface-inverse` | `var(--md-sys-color-neutral-inverse-surface)` |
+| `--a-canvas-well` | `var(--md-sys-color-neutral-surface-low)` |
+| `--a-canvas-inset` | `var(--md-sys-color-neutral-background)` |
+| `--a-canvas-pressed` | `var(--md-sys-color-neutral-surface-high)` |
+| `--a-canvas-well-strong` | `var(--md-sys-color-neutral-container)` |
+| `--a-canvas-border-subtle` | `var(--md-sys-color-neutral-outline-variant)` |
+| `--a-canvas-border` | `var(--md-sys-color-neutral-outline)` |
+| `--a-canvas-border-strong` | `var(--md-sys-color-neutral-outline-active)` |
+| `--a-bg` | `var(--md-sys-color-neutral-background)` |
+| `--a-bg-scrim` | `var(--md-sys-color-neutral-scrim-weakest)` |
+| `--a-bg-subtle` | `var(--md-sys-color-neutral-surface)` |
+| `--a-bg-muted` | `var(--md-sys-color-neutral-container)` |
+| `--a-bg-strong` | `var(--md-sys-color-neutral-surface-high)` |
+| `--a-bg-hover` | `var(--md-sys-color-neutral-hover)` |
+| `--a-bg-active` | `var(--md-sys-color-neutral-active)` |
+| `--a-bg-selected` | `var(--md-sys-color-neutral-container-active)` |
+| `--a-bg-disabled` | `var(--md-sys-color-neutral-container-disabled)` |
+| `--a-bg-invalid` | `var(--a-danger-muted)` |
+| `--a-fg` | `var(--md-sys-color-neutral-on-surface)` |
+| `--a-fg-subtle` | `var(--md-sys-color-neutral-on-surface-variant)` |
+| `--a-fg-muted` | `var(--md-sys-color-neutral-on-surface-variant)` |
+| `--a-fg-strong` | `var(--md-sys-color-neutral-on-surface)` |
+| `--a-fg-hover` | `var(--md-sys-color-neutral-on-surface-hover)` |
+| `--a-fg-selected` | `var(--md-sys-color-neutral-on-surface-active)` |
+| `--a-fg-disabled` | `var(--md-sys-color-neutral-on-surface-disabled)` |
+| `--a-fg-inverse` | `var(--md-sys-color-neutral-inverse-on-surface)` |
+| `--a-border` | `var(--md-sys-color-neutral-outline)` |
+| `--a-border-subtle` | `var(--md-sys-color-neutral-outline-variant)` |
+| `--a-border-strong` | `var(--md-sys-color-neutral-outline-active)` |
+| `--a-border-hover` | `var(--md-sys-color-neutral-outline-hover)` |
+| `--a-primary-strong` | `var(--md-sys-color-primary-active)` |
+| `--a-primary` | `var(--md-sys-color-primary)` |
+| `--a-primary-subtle` | `var(--md-sys-color-primary-container-high)` |
+| `--a-primary-muted` | `var(--md-sys-color-primary-container)` |
+| `--a-primary-hover` | `var(--md-sys-color-primary-hover)` |
+| `--a-primary-active` | `var(--md-sys-color-primary-active)` |
+| `--a-primary-selected` | `var(--md-sys-color-primary)` |
+| `--a-link` | `var(--md-sys-color-primary-on-surface)` |
+| `--a-link-hover` | `var(--md-sys-color-primary-on-surface-hover)` |
+| `--a-link-visited` | `var(--md-sys-color-primary-on-surface-active)` |
+| `--a-primary-text-strong` | `var(--md-sys-color-primary-on-primary)` |
+| `--a-primary-text` | `var(--md-sys-color-primary-on-surface)` |
+| `--a-primary-text-subtle` | `var(--md-sys-color-primary-on-surface-variant)` |
+| `--a-primary-text-disabled` | `var(--md-sys-color-primary-on-surface-disabled)` |
+| `--a-primary-border-subtle` | `var(--md-sys-color-primary-outline-variant)` |
+| `--a-primary-border` | `var(--md-sys-color-primary-outline)` |
+| `--a-primary-border-strong` | `var(--md-sys-color-primary-outline-active)` |
+| `--a-primary-bg` | `var(--a-primary)` |
+| `--a-primary-bg-hover` | `var(--a-primary-hover)` |
+| `--a-primary-bg-active` | `var(--a-primary-active)` |
+| `--a-primary-fg` | `var(--a-primary-text-strong)` |
+| `--a-primary-fg-hover` | `var(--a-primary-text-strong)` |
+| `--a-primary-border-hover` | `var(--a-primary-border-strong)` |
+| `--a-primary-container-disabled` | `var(--md-sys-color-primary-container-disabled)` |
+| `--a-brand-strong` | `var(--a-brand-60)` |
+| `--a-brand` | `var(--a-brand-50)` |
+| `--a-brand-subtle` | `var(--a-brand-40)` |
+| `--a-brand-muted` | `var(--a-brand-30)` |
+| `--a-brand-hover` | `var(--a-brand-60)` |
+| `--a-brand-active` | `var(--a-brand-60)` |
+| `--a-brand-selected` | `var(--a-brand-40)` |
+| `--a-brand-text-strong` | `light-dark(var(--a-brand-05-tint), var(--a-brand-05-tint))` |
+| `--a-brand-text` | `light-dark(var(--a-brand-10-tint), var(--a-brand-10-tint))` |
+| `--a-brand-text-subtle` | `light-dark(var(--a-brand-30-tint), var(--a-brand-30-tint))` |
+| `--a-brand-text-disabled` | `light-dark(var(--a-brand-60-shade), var(--a-brand-60-tint))` |
+| `--a-brand-border-subtle` | `var(--a-brand-30)` |
+| `--a-brand-border` | `var(--a-brand-45)` |
+| `--a-brand-border-strong` | `var(--a-brand-60)` |
+| `--a-brand-bg` | `var(--a-brand)` |
+| `--a-brand-bg-hover` | `var(--a-brand-hover)` |
+| `--a-brand-fg` | `var(--a-brand-text-strong)` |
+| `--a-brand-fg-hover` | `var(--a-brand-text-strong)` |
+| `--a-brand-border-hover` | `var(--a-brand-border-strong)` |
+| `--a-info-strong` | `var(--md-sys-color-info-active)` |
+| `--a-info` | `var(--md-sys-color-info)` |
+| `--a-info-subtle` | `var(--md-sys-color-info-container-high)` |
+| `--a-info-muted` | `var(--md-sys-color-info-container)` |
+| `--a-info-hover` | `var(--md-sys-color-info-hover)` |
+| `--a-info-active` | `var(--md-sys-color-info-active)` |
+| `--a-info-selected` | `var(--md-sys-color-info)` |
+| `--a-info-text-strong` | `var(--md-sys-color-info-on-info)` |
+| `--a-info-text` | `var(--md-sys-color-info-on-surface)` |
+| `--a-info-text-subtle` | `var(--md-sys-color-info-on-surface-variant)` |
+| `--a-info-text-disabled` | `var(--md-sys-color-info-on-surface-disabled)` |
+| `--a-info-border-subtle` | `var(--md-sys-color-info-outline-variant)` |
+| `--a-info-border` | `var(--md-sys-color-info-outline)` |
+| `--a-info-border-strong` | `var(--md-sys-color-info-outline-active)` |
+| `--a-info-bg` | `var(--a-info)` |
+| `--a-info-bg-hover` | `var(--a-info-hover)` |
+| `--a-info-fg` | `var(--a-info-text-strong)` |
+| `--a-info-fg-hover` | `var(--a-info-text-strong)` |
+| `--a-info-border-hover` | `var(--a-info-border-strong)` |
+| `--a-info-container-disabled` | `var(--md-sys-color-info-container-disabled)` |
+| `--a-success-strong` | `var(--md-sys-color-success-active)` |
+| `--a-success` | `var(--md-sys-color-success)` |
+| `--a-success-subtle` | `var(--md-sys-color-success-container-high)` |
+| `--a-success-muted` | `var(--md-sys-color-success-container)` |
+| `--a-success-hover` | `var(--md-sys-color-success-hover)` |
+| `--a-success-active` | `var(--md-sys-color-success-active)` |
+| `--a-success-selected` | `var(--md-sys-color-success)` |
+| `--a-success-text-strong` | `var(--md-sys-color-success-on-success)` |
+| `--a-success-text` | `var(--md-sys-color-success-on-surface)` |
+| `--a-success-text-subtle` | `var(--md-sys-color-success-on-surface-variant)` |
+| `--a-success-text-disabled` | `var(--md-sys-color-success-on-surface-disabled)` |
+| `--a-success-border-subtle` | `var(--md-sys-color-success-outline-variant)` |
+| `--a-success-border` | `var(--md-sys-color-success-outline)` |
+| `--a-success-border-strong` | `var(--md-sys-color-success-outline-active)` |
+| `--a-success-bg` | `var(--a-success)` |
+| `--a-success-bg-hover` | `var(--a-success-hover)` |
+| `--a-success-fg` | `var(--a-success-text-strong)` |
+| `--a-success-fg-hover` | `var(--a-success-text-strong)` |
+| `--a-success-border-hover` | `var(--a-success-border-strong)` |
+| `--a-success-container-disabled` | `var(--md-sys-color-success-container-disabled)` |
+| `--a-warning-strong` | `var(--md-sys-color-warning-active)` |
+| `--a-warning` | `var(--md-sys-color-warning)` |
+| `--a-warning-subtle` | `var(--md-sys-color-warning-container-high)` |
+| `--a-warning-muted` | `var(--md-sys-color-warning-container)` |
+| `--a-warning-hover` | `var(--md-sys-color-warning-hover)` |
+| `--a-warning-active` | `var(--md-sys-color-warning-active)` |
+| `--a-warning-selected` | `var(--md-sys-color-warning)` |
+| `--a-warning-text-strong` | `var(--md-sys-color-warning-on-warning)` |
+| `--a-warning-text` | `var(--md-sys-color-warning-on-surface)` |
+| `--a-warning-text-subtle` | `var(--md-sys-color-warning-on-surface-variant)` |
+| `--a-warning-text-disabled` | `var(--md-sys-color-warning-on-surface-disabled)` |
+| `--a-warning-border-subtle` | `var(--md-sys-color-warning-outline-variant)` |
+| `--a-warning-border` | `var(--md-sys-color-warning-outline)` |
+| `--a-warning-border-strong` | `var(--md-sys-color-warning-outline-active)` |
+| `--a-warning-bg` | `var(--a-warning)` |
+| `--a-warning-bg-hover` | `var(--a-warning-hover)` |
+| `--a-warning-fg` | `var(--a-warning-text-strong)` |
+| `--a-warning-fg-hover` | `var(--a-warning-text-strong)` |
+| `--a-warning-border-hover` | `var(--a-warning-border-strong)` |
+| `--a-warning-container-disabled` | `var(--md-sys-color-warning-container-disabled)` |
+| `--a-danger-strong` | `var(--md-sys-color-danger-active)` |
+| `--a-danger` | `var(--md-sys-color-danger)` |
+| `--a-danger-subtle` | `var(--md-sys-color-danger-container-high)` |
+| `--a-danger-muted` | `var(--md-sys-color-danger-container)` |
+| `--a-danger-hover` | `var(--md-sys-color-danger-hover)` |
+| `--a-danger-active` | `var(--md-sys-color-danger-active)` |
+| `--a-danger-selected` | `var(--md-sys-color-danger)` |
+| `--a-danger-text-strong` | `var(--md-sys-color-danger-on-danger)` |
+| `--a-danger-text` | `var(--md-sys-color-danger-on-surface)` |
+| `--a-danger-text-subtle` | `var(--md-sys-color-danger-on-surface-variant)` |
+| `--a-danger-text-disabled` | `var(--md-sys-color-danger-on-surface-disabled)` |
+| `--a-danger-border-subtle` | `var(--md-sys-color-danger-outline-variant)` |
+| `--a-danger-border` | `var(--md-sys-color-danger-outline)` |
+| `--a-danger-border-strong` | `var(--md-sys-color-danger-outline-active)` |
+| `--a-danger-bg` | `var(--a-danger)` |
+| `--a-danger-bg-hover` | `var(--a-danger-hover)` |
+| `--a-danger-fg` | `var(--a-danger-text-strong)` |
+| `--a-danger-fg-hover` | `var(--a-danger-text-strong)` |
+| `--a-danger-border-hover` | `var(--a-danger-border-strong)` |
+| `--a-danger-container-disabled` | `var(--md-sys-color-danger-container-disabled)` |
+| `--a-secondary-strong` | `var(--md-sys-color-secondary-active)` |
+| `--a-secondary` | `var(--md-sys-color-secondary)` |
+| `--a-secondary-subtle` | `var(--md-sys-color-secondary-container-high)` |
+| `--a-secondary-muted` | `var(--md-sys-color-secondary-container)` |
+| `--a-secondary-hover` | `var(--md-sys-color-secondary-hover)` |
+| `--a-secondary-active` | `var(--md-sys-color-secondary-active)` |
+| `--a-secondary-selected` | `var(--md-sys-color-secondary)` |
+| `--a-secondary-text-strong` | `var(--md-sys-color-secondary-on-secondary)` |
+| `--a-secondary-text` | `var(--md-sys-color-secondary-on-surface)` |
+| `--a-secondary-text-subtle` | `var(--md-sys-color-secondary-on-surface-variant)` |
+| `--a-secondary-text-disabled` | `var(--md-sys-color-secondary-on-surface-disabled)` |
+| `--a-secondary-border-subtle` | `var(--md-sys-color-secondary-outline-variant)` |
+| `--a-secondary-border` | `var(--md-sys-color-secondary-outline)` |
+| `--a-secondary-border-strong` | `var(--md-sys-color-secondary-outline-active)` |
+| `--a-secondary-bg` | `var(--a-secondary)` |
+| `--a-secondary-bg-hover` | `var(--a-secondary-hover)` |
+| `--a-secondary-fg` | `var(--a-secondary-text-strong)` |
+| `--a-secondary-fg-hover` | `var(--a-secondary-text-strong)` |
+| `--a-secondary-border-hover` | `var(--a-secondary-border-strong)` |
+| `--a-secondary-container-disabled` | `var(--md-sys-color-secondary-container-disabled)` |
+| `--a-tertiary-strong` | `var(--md-sys-color-tertiary-active)` |
+| `--a-tertiary` | `var(--md-sys-color-tertiary)` |
+| `--a-tertiary-subtle` | `var(--md-sys-color-tertiary-container-high)` |
+| `--a-tertiary-muted` | `var(--md-sys-color-tertiary-container)` |
+| `--a-tertiary-hover` | `var(--md-sys-color-tertiary-hover)` |
+| `--a-tertiary-active` | `var(--md-sys-color-tertiary-active)` |
+| `--a-tertiary-selected` | `var(--md-sys-color-tertiary)` |
+| `--a-tertiary-text-strong` | `var(--md-sys-color-tertiary-on-tertiary)` |
+| `--a-tertiary-text` | `var(--md-sys-color-tertiary-on-surface)` |
+| `--a-tertiary-text-subtle` | `var(--md-sys-color-tertiary-on-surface-variant)` |
+| `--a-tertiary-text-disabled` | `var(--md-sys-color-tertiary-on-surface-disabled)` |
+| `--a-tertiary-border-subtle` | `var(--md-sys-color-tertiary-outline-variant)` |
+| `--a-tertiary-border` | `var(--md-sys-color-tertiary-outline)` |
+| `--a-tertiary-border-strong` | `var(--md-sys-color-tertiary-outline-active)` |
+| `--a-tertiary-bg` | `var(--a-tertiary)` |
+| `--a-tertiary-bg-hover` | `var(--a-tertiary-hover)` |
+| `--a-tertiary-fg` | `var(--a-tertiary-text-strong)` |
+| `--a-tertiary-fg-hover` | `var(--a-tertiary-text-strong)` |
+| `--a-tertiary-border-hover` | `var(--a-tertiary-border-strong)` |
+| `--a-tertiary-container-disabled` | `var(--md-sys-color-tertiary-container-disabled)` |

package/skills/adia-tokens/references/pairing-laws.md

@@ -0,0 +1,63 @@
+# Pairing laws — depth and adia-specific notes
+
+_Load when a "which token" answer needs the law's reasoning or its edge
+cases, not just the rule. Stable doctrine, hand-maintained; the volatile
+rosters live in the two GENERATED siblings. Sources: the framework's
+`component-token-contract.md` + `material-color-bridge-contract.md`
+(monorepo), mirrored here for consumer installs._
+
+## 1 · Pairing — ink on its own palette's ground
+
+The defect this prevents: `neutral` ink on a `danger-container` fill reads
+fine in light, breaks in dark — the two palettes' schemes flip on different
+curves. The ink for ANY palette's surface/container/background is that same
+palette's `-on-surface` family; the ink for its solid accent fill is
+`-on-{p}`. If you're writing a fill from palette A and ink from palette B,
+stop — one of them is the wrong role.
+
+## 2 · States as families
+
+`-hover/-active/-disabled` siblings are real, tuned tokens — not derivable.
+`opacity: .5` on a disabled control also fades its border and any icon
+differently than the tuned pair does, and `color-mix()` breaks under scheme
+flip. Where the roster shows no state sibling (e.g. `background`), the role
+genuinely has no state — don't invent one.
+
+## 3 · Scheme baked in
+
+Every role is a `light-dark()` pair. Consequences: write colors once; a
+subtree forced to one scheme (`color-scheme: dark` on a preview pane)
+re-resolves every role inside it automatically; per-color
+`@media (prefers-color-scheme)` overrides fork the source of truth and are
+the first thing to rot. The embedded-app pattern's scheme owner is the
+shell element's `data-scheme`, not `html` — test dark mode there.
+
+## 4 · Elevation = the surface ladder
+
+Two axes, deliberately distinct: `-dim…-bright` shifts perceived light;
+`-lowest…-highest` shifts stacking prominence. A card that must read
+"raised" takes a `-high` tier, not a shadow bump; a recessed well takes
+`-dim`/`-low`. The `--a-canvas-*` aliases map onto this ladder (see the
+alias table) — pick the tier, not a hand-tuned value.
+
+## 5 · On-accent fixed light — the operator ruling
+
+`-on-{p}` resolves to the palette's light end in BOTH schemes, for all
+palettes — including `warning`, where white-on-amber measurably misses
+WCAG AA. Ruled 2026-07-16 (framework color-bridge contract, steps 9–10):
+the tokens are upstream-canonical; fill-pair contrast is an upstream
+design decision, accepted at kit level. Do not patch locally (dark text,
+auto-contrast, per-component overrides) — a change here arrives as a
+regenerated upstream export, never an app-side fix. Canvas-TEXT contrast
+(body text on page surfaces) is a different matter and IS gated (the
+framework's `verify:contrast`, 4.5:1 AA).
+
+## 6 · Named purpose over coincidental value
+
+- `--a-data-0..9` color IDENTITY (chart series, groups, tracks); the
+  intent palettes color STATE. Mixing them makes a chart lie.
+- Text/icons on a filled primary disc: `--a-chrome-light` (theme-stable
+  against any fill) — radio dots, step circles, badge counters.
+- A token whose current value happens to look right is still the wrong
+  token if its name says otherwise — the next palette regeneration breaks
+  exactly these.

package/skills/adia-tokens/references/role-roster.md

@@ -0,0 +1,26 @@
+<!-- GENERATED — do not edit. Source: packages/web-components/styles/colors/material-static.css.
+     Provenance: produced in the framework monorepo at cut time by
+     scripts/release/check-token-semantics-sync.mjs (producer-side tooling,
+     not runnable from a consumer install — in a consumer repo this file
+     describes the version you installed). -->
+
+# Role roster — the `--md-sys-color-*` semantic layer
+
+**Palettes (8):** neutral (53) · primary (53) · secondary (53) · tertiary (53) · info (53) · success (53) · warning (53) · danger (53) — every palette carries the full roster.
+
+Grammar: `--md-sys-color-{palette}{suffix}`. Chrome palette = `neutral`; brand accent = `primary`; `secondary`/`tertiary` support; `info/success/warning/danger` carry MEANING only. Consume via `var()` — never a raw `-050…-950` stop, never a hex.
+
+| Family | Suffixes (`{p}` = the palette's own slug) | Meaning |
+|---|---|---|
+| accent | `(bare)` | The bare accent — the palette's main solid fill (CTAs for primary; the intent color for intents) |
+| accent variants | `-dim` `-bright` `-low` `-high` | Tonal variants of the accent for de/emphasis without leaving the palette |
+| accent states | `-hover` `-active` `-disabled` | The solid accent fill's baked states — never synthesize with opacity/color-mix |
+| on-accent | `-on-{p}` `-on-{p}-variant` `-on-{p}-hover` `-on-{p}-active` `-on-{p}-disabled` | Ink on the palette's own solid fill (the accent). FIXED LIGHT in both schemes by design — never "fix" with dark text or auto-contrast |
+| on-surface | `-on-surface` `-on-surface-variant` `-on-surface-hover` `-on-surface-active` `-on-surface-disabled` | Text/icon ink on the SAME palette's surfaces/containers/background — the pairing law's ink side, with baked states |
+| placeholder | `-placeholder` | Form placeholder ink |
+| outline | `-outline` `-outline-variant` `-outline-hover` `-outline-active` `-outline-disabled` | Borders/dividers/rings, with a softer -variant and baked states |
+| container | `-container` `-container-low` `-container-high` `-container-hover` `-container-active` `-container-disabled` | Translucent tint fills for chips/badges/soft emphasis (distinct from the opaque surface ladder), with baked states |
+| inverse | `-inverse-surface` `-inverse-on-surface` | The opposite-scheme pocket (tooltips, snackbars) |
+| background | `-background` | The palette's page-level backdrop |
+| surface ladder | `-surface` `-surface-dimmest` `-surface-dimmer` `-surface-dim` `-surface-bright` `-surface-brighter` `-surface-brightest` `-surface-lowest` `-surface-lower` `-surface-low` `-surface-high` `-surface-higher` `-surface-highest` | Elevation IS this ladder (dim↔bright, low↔high) — raise/recess with surfaces, never with opacity or ad-hoc shadows |
+| scrim | `-scrim-weakest` `-scrim-weaker` `-scrim-weak` `-scrim` `-scrim-strong` `-scrim-stronger` `-scrim-strongest` | Scrim ladder — 7-step overlay dims for layering under sheets/dialogs/toasts |