ux-ui-agent-skills 1.2.0 → 2.0.0

package/.claude/skills/design-code/SKILL.md

@@ -19,3 +19,14 @@ Render components into a target framework via the adapter system.
 
 ## Output rules (mandatory)
 Use tokens (never hardcode) · include a11y on every interactive element · handle all applicable of the 8 states · support dark mode at the semantic layer · mobile-first · honor reduced motion · **deliver complete files, no placeholders** (`workflows/redesign-audit.md` → Output Completeness).
+
+## Verification (mandatory before declaring done)
+Code is the highest-stakes output — self-check every time:
+1. **No hardcoded values** — every color/size/radius/shadow/duration/**font** traces to a token (CSS var / theme key / asset). Run `scripts/lint_hardcodes.py` over the output; zero raw hex/px/ms AND zero raw Tailwind palette utilities (`bg-gray-500`, `text-blue-600`) — use semantic utilities/tokens (`bg-surface`, `text-primary`). Run `scripts/validate_theme_refs.py` so every `var(--…)` resolves to a defined theme token (no floating tokens). One allowed exception: 3rd-party theme-config (MUI/Mantine) mapping our tokens INTO their API.
+2. **All applicable states present** — Default, Hover, Focus(-visible ring), Active, Disabled, Loading(+`aria-busy`), Error, Selected — or justified N/A.
+3. **Accessibility wired** — correct role/ARIA per `accessibility/aria-patterns.md`, keyboard model, focus management, ≥24px target; verify contrast (`scripts/contrast.py`) for any new color pair.
+4. **Dark mode + reduced motion + responsive** — semantic tokens swap; motion has a `prefers-reduced-motion` fallback; layout is mobile-first.
+5. **Completeness** — full files, no `// ...`; if asked for N, deliver N. If any check fails, fix before returning (run `a11y-audit` if unsure).
+6. **Single-theme consistency** — consume the project's ONE shared token theme (the root CSS-var layer); never define a per-page palette or new colors. Across multiple pages/screens, the same semantic tokens must drive every surface so the whole product stays visually identical and themeable from one place (CLAUDE.md → Single-Theme Consistency).
+7. **One shared primitive layer** — build ONE reusable component per atom (`Button`, `Input`, `Modal`, `Badge` via `cva`/equivalent); never repeat utility-class clusters inline across files or hand-roll a div-as-modal per screen. Overlays reuse the single `Modal` primitive: focus trap, `role="dialog"`, `aria-modal="true"`, `aria-labelledby`, Escape, **return focus on close**, backdrop (WCAG 2.4.3 + 2.1.2). See `examples/golden/Button.tsx` + `examples/golden/Modal.tsx`.
+8. **Font loading** — NEVER `@import` web fonts in CSS (render-blocking). Use a framework loader (`next/font`) or `<link rel="preconnect">` + `<link rel="preload">` with `font-display: swap`; self-host when possible. Font family comes from a token (`--font-sans`), never a literal.

package/.claude/skills/design-qa/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: design-qa
+description: Set up or run design QA gates — token + hardcoded-value lint, automated a11y (axe), contrast, visual regression across variants/states/themes/RTL, and the manual a11y checklist. Use when the user wants CI quality gates, to prevent design regressions, or to QA a component/screen before shipping.
+---
+
+# Skill: Design QA
+
+Stand up the automated + manual gates that stop quality from regressing.
+
+## Steps
+1. Read `workflows/design-qa.md` (the QA pyramid: token/lint gates → automated a11y → visual regression → manual a11y).
+2. Wire the **fast gates** first (every commit/PR): `python3 scripts/validate_tokens.py`, `python3 scripts/validate_contrast.py` (batch WCAG over the token pairs), and `python3 scripts/lint_hardcodes.py <src>` (no raw hex/px/timing in component code). The repo's `.github/workflows/ci.yml` runs these.
+3. Add **automated a11y** (axe-core / Pa11y) over each component's states (error/loading/disabled/expanded/selected), zero serious/critical to merge.
+4. Add **visual regression** snapshots across variants × sizes × states × light/dark + key breakpoints + RTL; freeze animations + deterministic data.
+5. Sign off the **manual a11y** checklist per release (keyboard, screen reader, 400% reflow, 200% text-spacing, reduced-motion, forced-colors — `accessibility/*`).
+
+## Verification (definition of done)
+- An unreviewed PR cannot introduce an unresolved token alias, a contrast failure, a raw hex/px, or an axe violation — a gate blocks each.
+- Snapshots cover dark mode + RTL + the semantic-changing states, not just the happy path.
+- Manual a11y checklist signed off for the release.

package/.claude/skills/figma-integration/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: figma-integration
+description: Keep Figma and code in sync — map the 3-tier DTCG tokens to Figma Variables (collections + modes), sync in either direction, use the Figma MCP when connected, and verify component parity (variants/states). Use when the user wants to push tokens/components to Figma, pull a design into code, set up token↔Variable sync, or check design-code drift.
+---
+
+# Skill: Figma Integration
+
+Bridge design (Figma) and code (this repo) in both directions. The token JSON stays the source of truth; Figma Variables mirror it.
+
+## Steps
+1. Read `workflows/figma-integration.md` (token↔Variable mapping, sync directions, MCP usage, parity).
+2. Map the 3-tier hierarchy → three Figma collections (Primitives → Semantic → Component) with aliasing; dark/brand/density → Figma **Modes** (`tokens/theming.json`).
+3. Choose ONE authoritative sync direction (code→Figma publish, or Figma→code extract via Tokens Studio / Variables REST API). The other side is generated — never hand-edit both.
+4. **If a Figma MCP server is connected:** prefer its tools/skills (load its mandatory prerequisite skill first). Use it to read frames/variables/screenshots into code, build Variables/components from our tokens, or wire Code Connect to `components/*`.
+5. Check component parity: Figma variants/properties must cover our variants + sizes + the 8 states; flag gaps.
+
+## Verification (definition of done)
+- Every Figma Variable resolves to a token in `tokens/*.json` (no orphan hex in designs).
+- One authoritative direction; the generated side has zero hand edits.
+- Variant sets cover all 8 states; Code Connect points to the right `components/*` file.
+- After any token import: `python3 scripts/validate_tokens.py` passes.

package/.claude/skills/governance/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: governance
+description: Govern how the design system evolves — SemVer for tokens/components, the contribution workflow, deprecation policy, and change communication. Use when the user wants to add/promote/deprecate a component or token, decide a version bump, set up a contribution process, or keep the system from fragmenting.
+---
+
+# Skill: Governance
+
+Keep the system consistent as it grows. Apply versioning, contribution, and deprecation rules.
+
+## Steps
+1. Read `workflows/governance.md` (SemVer table, contribution workflow, deprecation policy, change comms).
+2. Classify the change: **major** (breaking — renamed/removed token or prop, changed anatomy/default), **minor** (additive — new token/component/variant/optional prop), **patch** (fix — contrast/bug/doc/value tweak in tolerance).
+3. For a **new** component/token: confirm it serves a real, repeated need (≥ 2 places) before promoting product → candidate → core. Design it to the full quality bar (CLAUDE.md Component Quality Bar).
+4. For a **deprecation**: mark with reason + replacement + removal version; keep working ≥ 1 minor cycle; provide a migration map (`design-systems/crosswalk.md` style); remove only in a major.
+5. Wire any new file into `CLAUDE.md` (File Reference Map + relevant table/router) and add a changelog entry.
+
+## Verification (definition of done)
+- Change has a SemVer level **and** a changelog entry.
+- Removals have a deprecation window, a replacement, and a migration table.
+- New spec meets the 8-state + a11y + token-mapping bar and is reachable via the router.
+- `python3 scripts/validate_tokens.py` passes; contrast re-checked if colors changed.

package/.claude/skills/performance/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: performance
+description: Optimize UI performance against Core Web Vitals — LCP, INP, CLS — with loading/code-split strategy, layout-shift prevention, and animation performance rules. Use when the user wants to improve speed, fix jank or layout shift, hit Web Vitals budgets, or make a UI feel fast on low-end devices.
+---
+
+# Skill: Performance
+
+Make the UI fast and stable. Treat performance as an accessibility concern — slow/janky UIs fail low-end devices first.
+
+## Steps
+1. Read `workflows/performance.md` (Core Web Vitals targets, loading strategy, layout-shift, animation perf, design-system runtime cost).
+2. Diagnose against budgets: **LCP ≤ 2.5s**, **INP ≤ 200ms**, **CLS ≤ 0.1**. Measure on a mid-tier mobile profile (throttle slow 4G + 4× CPU).
+3. Loading: render above-fold first (SSR/Server Components), code-split by route + heavy widget, lazy-load below-fold/behind-interaction (Astro islands / Qwik), preload one critical font weight, modern responsive images.
+4. Kill layout shift: size skeletons to final dimensions, reserve media space via `aspect-ratio` (`tokens/sizing.json`), never inject content above existing.
+5. Animation: only `transform`/`opacity`, `will-change` sparingly, 100–300ms (`tokens/motion.json`), honor `prefers-reduced-motion`. Prefer CSS state styling over JS for low INP; tree-shake/per-component imports.
+
+## Verification (definition of done)
+- Lighthouse / field data meets LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1 on mid-tier mobile.
+- First interaction stays responsive under slow-4G + 4× CPU throttle.
+- Skeletons + media reserve space (zero CLS on load); no non-compositor animation in loops.

package/.claude/skills/prototype/SKILL.md

@@ -17,3 +17,9 @@ Guide work through the right fidelity level with validation.
 
 ## Output
 The artifact at the chosen fidelity + an explicit "what we validate next" plan.
+
+## Verification (before declaring done)
+- The fidelity matches the question being answered — no level skipped.
+- Flows include decision points, **error paths, and edge cases** (empty/loading/overflow), not just the happy path.
+- A concrete validation step is named (tasks + success criteria), not "test later".
+- High-fi/code artifacts pass the same token + a11y bar as `design-code` (no hardcoded values, contrast, states).

package/.claude/skills/redesign/SKILL.md

@@ -13,7 +13,10 @@ Audit-first redesign that preserves behavior.
 3. **Diagnose** with the Banned Defaults checklist (`taste/design-taste.md`) + the review rubric (`design-review` skill). Produce a prioritized findings table.
 4. **Direct**: choose an archetype/system (`apply-aesthetic` skill) that fits the brand.
 5. **Apply** in order — tokens first, then typography/spacing, then component states, then motion — without changing routes/data/markup semantics (except a11y fixes).
-6. **Verify**: re-run `design-review` + `a11y-audit`; smoke-test every previously working flow; dark mode + responsive spot-check.
+6. **Verify**: re-run `design-review` + `a11y-audit`; smoke-test every previously working flow; dark mode + responsive spot-check. Run `scripts/validate_contrast.py` on the token source and `scripts/lint_hardcodes.py` over the changed code.
 
 ## Guardrails
 Never sacrifice a working feature for aesthetics. Never ship a brand color that fails contrast. Never remove existing accessibility affordances. Deliver complete files — no placeholders.
+
+## Single-theme consistency (critical for multi-page apps)
+Consolidate to ONE shared token theme and make **every page** consume it — a redesign that leaves different pages on different palettes has failed. Replace per-page/ad-hoc colors with semantic tokens; verify with `scripts/lint_hardcodes.py` that no page reintroduces off-theme values. Theme switches must come from the single token source, not page edits (CLAUDE.md → Single-Theme Consistency).

package/.claude/skills/token-build/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: token-build
+description: Set up or run the token build pipeline — transform the DTCG tokens/*.json (source of truth) into platform artifacts (CSS variables, Tailwind @theme, JS/TS, iOS Asset Catalog, Android, Compose) with Style Dictionary / Tokens Studio / W3C DTCG export. Use when the user wants to generate platform theme files from tokens, wire token CI, or multi-platform token output.
+---
+
+# Skill: Token Build
+
+Turn the DTCG token source of truth into platform-ready outputs. Tokens are authored once; every platform output is generated.
+
+## Steps
+1. Read `workflows/token-build.md` (architecture, tool options, resolution rules, output targets, CI).
+2. Pick the tool: **Style Dictionary** (multi-platform, the default), **Tokens Studio** (Figma-owned tokens — pairs with `figma-integration`), W3C DTCG export, or a small custom script (model on `scripts/validate_tokens.py`).
+3. Honor the resolution rules: resolve aliases to final values per platform; expose semantic + component tokens (primitives stay internal); emit base + dark/brand/density overrides (`tokens/theming.json`) as deltas only; format by `$type`.
+4. Generate the requested target(s): CSS `:root` vars, Tailwind v4 `@theme`, typed JS/TS, iOS Asset Catalog + `Color.DS`/`Spacing`, Android `colors.xml`/Compose theme.
+5. Wire CI: on `tokens/*.json` change, run `scripts/validate_tokens.py`, regenerate, fail if committed artifacts are stale; gate colors with `scripts/contrast.py`.
+
+## Verification (definition of done)
+- `python3 scripts/validate_tokens.py` passes (no unresolved aliases).
+- Regenerating produces no diff vs. committed artifacts.
+- Dark/brand/density outputs contain only deltas, not full duplicates.

package/.claude/skills/ux-writing/SKILL.md

@@ -19,3 +19,10 @@ Produce or critique interface copy in the project's voice.
 
 ## Output
 Final copy (or a redline review) that reads naturally aloud and passes the checklist. Keep within any character limits for tight UI.
+
+## Verification (mandatory before declaring done)
+Run every line through the 10-item pre-ship checklist in `content/voice-tone.md` — do not skip it:
+- Reads naturally **aloud**; frontloaded verb on actions; no jargon/blame/dead-ends.
+- Errors follow what→why→how; empty states give value→action; no bare "No data"/"Error".
+- Mechanics: sentence case, numerals, labels (not placeholders), no color/direction-only cues, inclusive language.
+- Within character limits; translatable (no concatenation — see `accessibility/i18n-rtl.md`).

package/CLAUDE.md

@@ -36,6 +36,15 @@ Match the request to the files to load (and the runnable skill, invocable via `/
 | Map to/from another design system | `migrate-design-system` | `design-systems/interop-protocol.md` + `crosswalk.md` |
 | Prototype / wireframe / user flow / usability test | `prototype` | `workflows/prototyping.md` |
 | Write/review UI copy | `ux-writing` | `content/voice-tone.md` |
+| Versioning / contribution / deprecation / add-or-promote a component | `governance` | `workflows/governance.md`; `scripts/validate_tokens.py` |
+| Token build pipeline → CSS/Tailwind/iOS/Android (Style Dictionary, DTCG) | `token-build` | `workflows/token-build.md`; `scripts/validate_tokens.py` |
+| Figma ↔ code sync, Variables, Code Connect, Figma MCP | `figma-integration` | `workflows/figma-integration.md` |
+| QA gates / CI / visual regression / prevent regressions | `design-qa` | `workflows/design-qa.md`; `scripts/validate_contrast.py`, `scripts/lint_hardcodes.py` |
+| Performance / Core Web Vitals / jank / layout shift | `performance` | `workflows/performance.md` |
+| Charts / data-viz / chart colors | `design-component` | `components/data-viz.md`, `tokens/data-viz.json` |
+| Calendar / Carousel / Tree | `design-component` | `components/data-display.md` |
+| Icon system / icon sizing / icon a11y | `design-component` | `components/icon-system.md` |
+| Cognitive a11y / i18n-RTL / low-vision / WCAG AAA | `a11y-audit` | `accessibility/cognitive.md`, `accessibility/i18n-rtl.md`, `accessibility/vision.md`, `accessibility/wcag-aaa.md` |
 
 ---
 
@@ -132,7 +141,7 @@ Examples: `semantic.text.primary`, `component.button.primary-bg-hover`, `semanti
 |---------|--------------|---------|
 | Normal text (< 24px) | 4.5:1 | `text.primary` on `surface.page` = 15.4:1 ✓ |
 | Large text (≥ 24px or ≥ 18.66px bold) | 3:1 | `text.secondary` on `surface.page` = 5.7:1 ✓ |
-| UI components & graphical objects | 3:1 | `border.default` on `surface.page` = 1.4:1 ✗ — use `border.strong` for essential borders |
+| UI components & graphical objects | 3:1 | `border.strong` on `surface.page` = 4.8:1 ✓ (use for essential control borders). `border.default` = 1.2:1 is decorative-only (dividers/card edges) |
 | Focus indicators | 3:1 | Focus ring uses `shadow.focus-ring` double ring |
 
 ### Color Usage Rules
@@ -149,6 +158,16 @@ Use **OKLCH color space** for perceptually uniform shade scales:
 3. Verify 500 shade meets 4.5:1 contrast on white for text use
 4. Verify 600 shade meets 3:1 contrast on white for UI use
 
+### Single-Theme Consistency (cross-page — non-negotiable)
+Every page, screen, and component in a project MUST render from **one shared token theme** — never a per-page palette or ad-hoc colors. This is what keeps a 50-screen product visually identical and themeable from one place.
+
+1. **One source of truth** — the project's `tokens/*.json` → a single CSS-variable layer (`:root` + `[data-theme="dark"]`) imported **once** at the app root. Every page references the same semantic tokens; none redefines colors.
+2. **No off-theme values** — zero hardcoded hex/px/timing in component/page code. Enforced by `scripts/lint_hardcodes.py` (the one allowed exception: adapter theme-config that maps our tokens *into* a 3rd-party API, e.g. MUI/Mantine).
+3. **Real WCAG, on the source** — the token theme itself passes WCAG 2.2 in **both** light and dark before any page ships. Enforced by `scripts/validate_contrast.py` (required text/action pairs fail the build; tertiary/decorative are advisory).
+4. **One CI enforces all of it** — `.github/workflows/ci.yml` runs `validate_tokens` + `validate_contrast` + `validate_component_spec` + `npm test` on every push/PR. A page that introduces drift, a contrast regression, or an off-theme color cannot merge.
+
+> Switching brand/theme = editing the token source once → every page updates. If a page "looks different," it's a bug: it bypassed the theme.
+
 ---
 
 ## Typography Guidelines
@@ -493,5 +512,10 @@ frameworks/
 .claude/skills/           ← Runnable skills (invoke via /name): design-tokens, design-component,
                             design-code, design-review, a11y-audit, apply-aesthetic, redesign,
                             migrate-design-system, prototype, ux-writing
-scripts/                  ← validate_tokens.py · contrast.py · design_systems.py · scaffold_component.py
+scripts/                  ← validate_tokens.py · contrast.py · validate_contrast.py (batch WCAG, light+dark)
+                            · validate_component_spec.py · lint_hardcodes.py (hex/px/ms + Tailwind palette + font)
+                            · validate_theme_refs.py (every var(--…) resolves to the theme) · lint_taste.py
+                            · design_systems.py · scaffold_component.py
+.github/workflows/        ← ci.yml (quality gates: tokens + contrast + spec + npm test on push/PR)
+                            · release.yml (auto GitHub Release + npm publish on tag)
 ```

package/README.md

@@ -8,7 +8,7 @@ A comprehensive kit of structured instructions, design tokens, runnable skills,
 
 <br>
 
-[![Version](https://img.shields.io/badge/version-1.2.0-6366f1?style=for-the-badge)](https://github.com/plugin87/ux-ui-agent-skills/releases)
+[![Version](https://img.shields.io/badge/version-2.0.0-6366f1?style=for-the-badge)](https://github.com/plugin87/ux-ui-agent-skills/releases)
 [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge)](#-license)
 [![WCAG 2.2 AA→AAA](https://img.shields.io/badge/WCAG-2.2_AA→AAA-a855f7?style=for-the-badge)](#-accessibility-standards)
 
@@ -17,7 +17,7 @@ A comprehensive kit of structured instructions, design tokens, runnable skills,
 [![npm](https://img.shields.io/npm/v/ux-ui-agent-skills?style=flat-square&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ux-ui-agent-skills)
 [![npm downloads](https://img.shields.io/npm/dt/ux-ui-agent-skills?style=flat-square&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ux-ui-agent-skills)
 ![Tokens](https://img.shields.io/badge/Design_Tokens-DTCG-fbbf24?style=flat-square)
-![Skills](https://img.shields.io/badge/runnable_skills-10-14b8a6?style=flat-square)
+![Skills](https://img.shields.io/badge/runnable_skills-15-14b8a6?style=flat-square)
 ![Design Systems](https://img.shields.io/badge/design_systems-138-f97316?style=flat-square)
 ![Frameworks](https://img.shields.io/badge/frameworks-any-8b5cf6?style=flat-square)
 ![Adapters](https://img.shields.io/badge/framework_adapters-16-22d3ee?style=flat-square)
@@ -32,7 +32,7 @@ A comprehensive kit of structured instructions, design tokens, runnable skills,
 
 ## 📌 Version
 
-**Current release: `v1.2.0`** · See the [Changelog](#-changelog) · [All releases](https://github.com/plugin87/ux-ui-agent-skills/releases)
+**Current release: `v2.0.0`** · See the [Changelog](#-changelog) · [All releases](https://github.com/plugin87/ux-ui-agent-skills/releases)
 
 > No build tools, dependencies, or runtime required — this is a pure instruction & knowledge layer for AI agents.
 
@@ -100,6 +100,8 @@ cp -r ux-ui-agent-skills/ your-project/
 
 ## 🎮 How to Use
 
+> 📖 **New here?** Read [**docs/WORKFLOW.md**](docs/WORKFLOW.md) for the full end-to-end picture — how the Request Router loads layers on demand, real usage scenarios, and the automated release pipeline.
+
 There are **three ways** to drive the kit. Use whichever fits the moment.
 
 ### 1. Just ask (zero commands)
@@ -142,12 +144,17 @@ Plain `python3` — useful in the terminal or CI:
 
 ```bash
 python3 scripts/validate_tokens.py                 # validate token JSON + alias refs
-python3 scripts/contrast.py "#1d1d1f" "#ffffff"    # WCAG contrast ratio + pass/fail
+python3 scripts/validate_contrast.py               # batch WCAG gate: token pairs, light + dark
+python3 scripts/contrast.py "#1d1d1f" "#ffffff"    # WCAG contrast ratio for one pair
+python3 scripts/validate_component_spec.py         # every component spec is complete
+python3 scripts/lint_hardcodes.py src/             # no off-theme hex/px/timing (consistency)
+python3 scripts/lint_taste.py page.html            # heuristic anti-slop taste check
 python3 scripts/design_systems.py list             # browse the 138-system library
-python3 scripts/design_systems.py show apple        # inspect one system
 python3 scripts/scaffold_component.py "Date Picker" # emit a component spec stub
 ```
 
+These are the same gates CI runs (`.github/workflows/ci.yml`) — token validity, **WCAG contrast in light + dark**, spec completeness, and zero hardcoded values — so theme/color stays consistent across every page and accessibility is enforced, not assumed.
+
 ### Typical flow
 
 ```text
@@ -315,6 +322,24 @@ This is a **starter kit** — make it yours:
 
 ## 📝 Changelog
 
+### `v2.0.0` — Enforcement layer (breaking)
+
+> **Breaking:** dark-mode token values changed (link, primary action) and `border.strong` now meets 3:1 — re-verify any snapshots/visual tests. The kit moves from *advisory* guidance to *enforced* gates.
+
+**Theme consistency + real WCAG, enforced (driven by real-world audit feedback):**
+- 🎨 **Single-theme consistency** — every page renders from ONE shared token theme; CLAUDE.md rule + `examples/golden/` (theme.css with full color/type/spacing/breakpoint tokens, Button.tsx, Modal.tsx). `design-code`/`redesign` require consuming the one theme — no per-page palettes.
+- 🚫 **Hardcode linter catches real drift** — `scripts/lint_hardcodes.py` now flags raw hex/px/ms, **raw Tailwind palette utilities** (`bg-gray-500`, `text-blue-600`), and literal `font-family` (the 527-hardcode problem).
+- 🔗 **No floating tokens** — `scripts/validate_theme_refs.py` proves every `var(--…)` a component uses is defined in the theme (precision/consistency gate).
+- ✅ **Real WCAG gate** — `scripts/validate_contrast.py` checks required text/action/**border** pairs in **light + dark**; fixed genuine dark-mode contrast bugs (link, primary action) and made `border.strong` meet 3:1 for essential control borders.
+- 🪟 **One Modal primitive** — golden `Modal.tsx` + hardened spec: focus trap, `role="dialog"`, `aria-modal`, return-focus on close (fixes the 0/14-focus-trap class of bug, WCAG 2.4.3 + 2.1.2).
+- 🤖 **One CI enforces all of it** — `.github/workflows/ci.yml` runs tokens + contrast + spec + hardcode + theme-ref + `npm test` on every push/PR. Drift, contrast regressions, off-theme colors, and floating tokens cannot merge.
+- ⚡ **5 new runnable skills** (10 → **15**) — `governance`, `token-build`, `figma-integration`, `design-qa`, `performance`; verification steps added to `design-code`/`prototype`/`ux-writing`; router rows for all newer knowledge.
+- 🧹 `validate_component_spec.py` + `lint_taste.py`; fixed `validate_tokens.py` cross-file aliases; atoms Button/Input document all 8 states.
+
+### `v1.2.1`
+- 📖 **Docs** — added [`docs/WORKFLOW.md`](docs/WORKFLOW.md): end-to-end how-it-works guide (Request Router, on-demand layer loading, real usage scenarios, automated release pipeline) + linked from the README
+- 🤖 **CI** — first release shipped fully automatically by the `release.yml` workflow (GitHub Release notes from this changelog + `npm publish --provenance` on tag push)
+
 ### `v1.2.0`
 - 🧩 **8 new component specs** — `data-display.md` (Calendar, Carousel, Tree) + `data-viz.md` (Bar, Line/Area, Pie/Donut, Sparkline, Scatter) → **50 components**; plus `components/icon-system.md`
 - 📊 **Data-viz tokens** — `tokens/data-viz.json`: color-blind-aware (Okabe–Ito) categorical/sequential/diverging palettes + axis/grid/tooltip → **14 token files**

package/components/atoms.md

@@ -26,13 +26,15 @@ The primary interactive control for triggering actions.
 | md | 40px | 16px × 10px | body-base (16px) | 20px |
 | lg | 48px | 24px × 12px | body-lg (18px) | 24px |
 
-**States (6):**
+**States (8):**
 1. **Default** — resting state
 2. **Hover** — cursor over; background shifts one shade
-3. **Active/Pressed** — mouse down; background shifts two shades
-4. **Focus** — keyboard focus; apply `focus-ring` shadow token
+3. **Focus** — keyboard focus; apply `focus-ring` shadow token
+4. **Active/Pressed** — mouse down; background shifts two shades
 5. **Disabled** — `opacity: 0.5`, `cursor: not-allowed`, `pointer-events: none`
 6. **Loading** — replace icon with spinner, add `aria-busy="true"`, disable interaction
+7. **Error** — N/A for a standalone button; a submit button reflects form error via the form, not its own style
+8. **Selected** — for toggle/segmented buttons only: `interactive.selected-bg` + `aria-pressed`/`aria-selected`
 
 **Accessibility:**
 - Native `<button>` element always; never `<div>`
@@ -58,13 +60,15 @@ Single-line text entry field.
 | md | 40px | 12px × 10px | body-base |
 | lg | 48px | 16px × 12px | body-lg |
 
-**States (6):**
+**States (8):**
 1. **Default** — `input.border` (gray-200)
 2. **Hover** — `input.border-hover` (gray-300)
 3. **Focus** — `input.border-focus` (blue-500) + focus ring
-4. **Error** — `input.border-error` (red-500) + error icon + message
+4. **Active** — N/A for text entry (no pressed state); typing reflects via the caret/value
 5. **Disabled** — `input.bg-disabled` + reduced opacity
-6. **Read-only** — same as default but non-editable, no hover state
+6. **Loading** — async validation/lookup: trailing spinner + `aria-busy="true"`
+7. **Error** — `input.border-error` (red-500) + error icon + message + `aria-invalid`
+8. **Selected** — filled/has-value styling; read-only is a variant of default (non-editable, no hover)
 
 **Accessibility:**
 - Always associate with `<label>` via `for`/`id`

package/components/data-viz.md

@@ -4,6 +4,8 @@ Charts and graphs. Color comes from `tokens/data-viz.json` (color-blind-aware ca
 
 ---
 
+**Anatomy (shared):** `[plot area] + [axes + tick labels] + [gridlines] + [series (bars/lines/points)] + [legend] + [tooltip on hover] + [optional title/caption]`. Every chart composes from these regions; color/axis/grid styling comes from `tokens/data-viz.json`.
+
 ## Universal chart rules
 
 1. **Token-driven series color** — map series to `dataviz.categorical.*`; sequences to `dataviz.sequential.*`; +/− to `dataviz.diverging.*` / `dataviz.semantic.*`. Limit to ≤ 8 categorical series; beyond that, group "Other" or switch encoding.

package/components/organisms.md

@@ -221,6 +221,8 @@ A structured data display with sorting, filtering, pagination, and row actions.
 
 A focused overlay that interrupts workflow for critical information or action.
 
+> **Non-negotiable — build ONE reusable Modal primitive and reuse it for every dialog.** Never hand-roll a div-as-modal per screen. Every instance MUST have: focus trap, `role="dialog"`, `aria-modal="true"`, `aria-labelledby`, Escape-to-close, **focus returned to the trigger on close**, and a backdrop. Missing the focus trap violates WCAG 2.4.3 + 2.1.2. Reference implementation: `examples/golden/Modal.tsx`.
+
 **Grid Structure:**
 ```
 ┌──────────── Overlay ─────────────────┐

package/docs/WORKFLOW.md

@@ -0,0 +1,171 @@
+# How It Works — End-to-End Workflow
+
+This document explains how the kit operates from both sides: the **consumer** (a designer/developer who installs it into a project and uses it through Claude) and the **maintainer** (who edits the knowledge files and ships releases).
+
+> TL;DR — **Easy to use, smart on the inside, automated on release.** There is no runtime, no build step, and no dependency. The kit is a pure knowledge + instruction layer that Claude loads on demand.
+
+---
+
+## 1. What it actually is
+
+This is **not a library you import or build** — it's a "brain" you plug into Claude (knowledge files + an instruction router). Once installed in a project, Claude in that project behaves like a Senior Design Architect: it answers design-system questions with real principles — design tokens, accessibility, and taste — and generates production-ready output.
+
+```
+A normal UI library          This kit
+─────────────────────        ─────────────────────────────
+import { Button }             you talk to Claude / run /skills
+npm build                     no build, no runtime
+ships JS/CSS to the browser   ships KNOWLEDGE to the model
+```
+
+---
+
+## 2. Consumer workflow (real usage)
+
+```
+┌─ Install once ─────────────────────────────────────────┐
+│  npx ux-ui-agent-skills init                            │
+│  → copies the knowledge files + .claude/skills/ in      │
+└────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+        You talk to Claude normally, or invoke a /skill
+                          │
+          ┌───────────────┴───────────────┐
+          ▼                               ▼
+  "build me a Button in React"     /design-tokens "make a purple palette"
+          │                               │
+          ▼                               ▼
+┌─────────────────────────────────────────────────────────┐
+│  Claude reads CLAUDE.md → the "Request Router"          │
+│  matches your intent → knows exactly which files to load │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│  Loads only the relevant LAYERS and composes them:      │
+│   tokens/  +  components/  +  accessibility/  +  taste/   │
+│   +  frameworks/adapters/ (when you ask for a framework) │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+   Output: code / spec / review that is token-driven and
+   accessible by default (no hardcoded colors, all 8 states,
+   dark-mode aware, ARIA wired).
+```
+
+### The Request Router is the core
+
+Claude does **not** read every file on every request (that would waste context). Instead, `CLAUDE.md` contains a routing table — Claude reads it and pulls only what the task needs:
+
+| You ask for… | Claude loads |
+|--------------|--------------|
+| Generate / edit tokens | `tokens/*.json` + `scripts/validate_tokens.py` |
+| A component spec | `components/*` + `accessibility/aria-patterns.md` |
+| Code in any framework | `frameworks/adapter-protocol.md` → the matching adapter |
+| A design review / audit | `workflows/design-review.md` + `taste/` |
+| An accessibility check | `accessibility/*` + `scripts/contrast.py` |
+| A specific look / vibe | `taste/` + one of 138 design systems |
+
+This is what makes the kit feel "intelligent" — it self-routes instead of dumping a flat file list into context.
+
+---
+
+## 3. Three real scenarios
+
+**A. A developer wants code**
+```
+You:    /design-code build a Card component in Vue
+Claude: → router points to frameworks/adapters/vue.md + components/molecules.md
+        → returns a .vue file using CSS-variable tokens, with
+          hover/focus/disabled states and dark mode.
+```
+
+**B. A designer wants a specific look**
+```
+You:    /apply-aesthetic make it feel like Linear
+Claude: → loads design-systems/library/linear-app + taste/
+        → remaps tokens (color/shadow/radius/font), then re-checks contrast.
+```
+
+**C. QA before shipping**
+```
+You:    /a11y-audit does this screen pass WCAG?
+Claude: → accessibility/wcag-checklist.md + runs scripts/contrast.py
+        → returns a table: criterion + severity + exact fix.
+```
+
+The ten runnable skills: `design-tokens`, `design-component`, `design-code`, `design-review`, `a11y-audit`, `apply-aesthetic`, `redesign`, `migrate-design-system`, `prototype`, `ux-writing`.
+
+---
+
+## 4. Is it complex or hard to use?
+
+| Perspective | Difficulty | Why |
+|-------------|------------|-----|
+| **Consumer (designer/dev)** | 🟢 Very easy | Just talk in plain language or type `/skill`. No config, no build, no API to memorize. The complexity is hidden inside the knowledge files. |
+| **Install** | 🟢 One command | `npx ux-ui-agent-skills init` and you're done. |
+| **Maintainer (releasing)** | 🟢 Easy now | A release is two commands (see §5). |
+| **Contributor (adding a component/adapter)** | 🟡 Moderate | Must follow the house style and wire the file into `CLAUDE.md`. `workflows/governance.md` is the guide. |
+
+**Bottom line:** the intelligence lives in the files, so the hard part is *authoring the kit* (already done), not *using it*. Consumers have almost nothing to learn.
+
+---
+
+## 5. Maintainer workflow (the release pipeline)
+
+```
+Edit knowledge files → commit
+        │
+        ▼
+  npm version patch                  ← bumps package.json + creates a git tag
+  git push origin main --follow-tags ← pushes code + tag
+        │
+        ▼  (tag vX.Y.Z lands on GitHub)
+┌──────────────────────────────────────────────┐
+│  GitHub Action: .github/workflows/release.yml │
+│   job 1 "release"  → creates a GitHub Release  │
+│                      (notes pulled from the    │
+│                       README changelog block)  │
+│   job 2 "publish"  → guards tag == pkg version │
+│                      → npm publish --provenance │
+│                        (uses the NPM_TOKEN      │
+│                         repo secret)            │
+└──────────────────────────────────────────────┘
+        │
+        ▼
+  ✅ GitHub Release is live   +   ✅ npm is updated   — automatically.
+```
+
+### Setup (one-time, already done)
+- **Repo secret `NPM_TOKEN`** = an npm **Automation token** (bypasses 2FA so CI can publish).
+- The workflow also supports **manual backfill**: Actions → *Release on tag* → *Run workflow* → enter an existing tag (this creates the Release only; it does **not** re-publish to npm).
+
+### Day-to-day releasing
+```bash
+npm version patch          # or minor / major
+git push origin main --follow-tags
+```
+That's the entire release. CI creates the GitHub Release and publishes to npm — no manual `gh` or `npm login`, no 2FA prompts.
+
+> Before this pipeline existed, each of these steps was manual (npm login, 2FA, hand-writing release notes, creating the Release page). Now it's two commands.
+
+---
+
+## 6. Mental model
+
+```
+        CONSUMER SIDE                         MAINTAINER SIDE
+   (uses Claude in a project)            (edits this repo, ships versions)
+
+   talk / /skill  ─┐                      edit files ─┐
+                   │                                  │
+        CLAUDE.md (Request Router)            npm version + git push
+                   │                                  │
+        loads layers on demand                GitHub Action
+                   │                                  │
+   token-driven, a11y, on-brand          Release page + npm publish
+        output                                  (automatic)
+```
+
+Easy at the edges, smart in the middle.

package/examples/golden/Button.tsx

@@ -0,0 +1,49 @@
+// Button.tsx — golden reference. Token-driven, all 8 states, accessible, dark-mode safe.
+// Every value comes from theme.css variables — zero hardcoded colors/sizes (passes lint_hardcodes).
+import { forwardRef, type ButtonHTMLAttributes } from "react";
+
+type Props = ButtonHTMLAttributes<HTMLButtonElement> & {
+  variant?: "primary" | "secondary";
+  loading?: boolean;
+  selected?: boolean;
+};
+
+export const Button = forwardRef<HTMLButtonElement, Props>(function Button(
+  { variant = "primary", loading = false, selected, disabled, children, ...rest },
+  ref
+) {
+  return (
+    <button
+      ref={ref}
+      data-variant={variant}
+      aria-pressed={selected}
+      aria-busy={loading || undefined}
+      disabled={disabled || loading}
+      className="ds-btn"
+      {...rest}
+    >
+      {loading && <span className="ds-spinner" aria-hidden="true" />}
+      {children}
+    </button>
+  );
+});
+
+/*
+.ds-btn {
+  display: inline-flex; align-items: center; gap: var(--space-2);
+  block-size: var(--size-control-md); padding-inline: var(--space-4);
+  border-radius: var(--radius-button); border: 0;
+  background: var(--color-action-primary); color: var(--color-text-on-action);
+  transition: background var(--transition-micro);
+}
+.ds-btn:hover { background: var(--color-action-primary-hover); }              /* Hover */
+.ds-btn:focus-visible { outline: none; box-shadow: var(--shadow-focus-ring); } /* Focus */
+.ds-btn:active { filter: brightness(0.95); }                                   /* Active */
+.ds-btn:disabled { opacity: var(--opacity-disabled); pointer-events: none; }   /* Disabled */
+.ds-btn[aria-busy="true"] { cursor: progress; }                                /* Loading */
+.ds-btn[aria-pressed="true"] { background: var(--color-action-primary-hover); }/* Selected */
+.ds-btn[data-variant="secondary"] {
+  background: transparent; color: var(--color-text-primary);
+  box-shadow: inset 0 0 0 1px var(--color-border-strong);
+}
+*/