📌 Version

Current release: v2.2.1 · See the Changelog · All releases

No build tools, dependencies, or runtime required — this is a pure instruction & knowledge layer for AI agents.

✨ What It Does

🚀 Quick Start

Option A — Install with npx (recommended)

Drop the kit into any project, no clone needed:

npx ux-ui-agent-skills init          # full kit into the current folder
npx ux-ui-agent-skills add tokens taste design-systems   # just some areas
npx ux-ui-agent-skills list          # see all areas

Flags: --force (overwrite existing files) · --dry (preview, change nothing).

Option B — Clone

git clone https://github.com/plugin87/ux-ui-agent-skills.git
cp -r ux-ui-agent-skills/ your-project/

Then start using — open the project in Claude Code or any Claude-powered IDE. CLAUDE.md loads automatically, activating the agent persona with full access to every tokens / components / taste / design-system file and the runnable /skills.

"Design a notification component with all states and accessibility"
"Review this login page against WCAG 2.2 and Nielsen's heuristics"
"Generate React + Tailwind code for a data table with sorting and pagination"
"Create a color token palette for a fintech brand using blue as the primary"
"Audit this form for accessibility issues — give me a prioritized findings table"
"Write the empty state and error copy for the onboarding flow"
"Spec the motion for the modal open/close with reduced-motion fallback"

🎮 How to Use

📖 New here? Read 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)

CLAUDE.md loads automatically, so plain requests already route to the right knowledge. Describe what you want and the agent self-routes via the built-in Request Router:

"Generate a Svelte button with all states and dark mode"
"Make this landing page feel like Linear"
"Migrate our Material 3 colors into this token system"

2. Run a skill explicitly (/skill)

Type a slash command to invoke a capability directly. Each skill loads only the files it needs and can run its own scripts.

/design-code  a pricing card in Vue, dark-mode aware
/apply-aesthetic  stripe   →  make the dashboard feel like Stripe
/a11y-audit  this checkout form
/migrate-design-system  from Material 3 to our tokens

3. Run the scripts (real, no dependencies)

Plain python3 — useful in the terminal or CI:

python3 scripts/validate_tokens.py                 # validate token JSON + alias refs
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/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

1. /apply-aesthetic linear      → set the visual direction (tokens re-pointed)
2. /design-component Combobox    → spec it with states + a11y
3. /design-code  Combobox in React + Tailwind   → production code
4. /a11y-audit                   → verify contrast, keyboard, focus
5. /design-review                → score + findings before ship

Tip: skills compose. apply-aesthetic always re-verifies contrast through a11y-audit; redesign calls design-review + a11y-audit automatically.

📂 Project Structure

.
├── CLAUDE.md                  # Agent persona & master instructions
│
├── .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/                   # Real helper scripts (python3, no deps)
│   ├── validate_tokens.py     # JSON + alias validation for tokens/
│   ├── contrast.py            # WCAG 2.2 contrast-ratio checker
│   ├── design_systems.py      # Browse/search the 138-system library
│   └── scaffold_component.py  # Emit a component spec stub
│
├── tokens/                    # Design tokens (DTCG format) — 13 files
│   ├── colors · typography · spacing · shadows · borders · breakpoints · motion
│   └── gradients · opacity · blur · sizing · states · theming
│
├── taste/                     # 🎭 Aesthetic judgment layer
│   ├── design-taste.md        # Anti-slop doctrine, banned defaults, pre-flight check
│   ├── aesthetic-systems.md   # Archetypes + catalog of 138 design systems
│   └── motion-choreography.md # Motion grammar + reduced-motion parity
│
├── design-systems/            # 🔌 Interop + brand library
│   ├── interop-protocol.md    # Map to/from ANY design system
│   ├── crosswalk.md           # Material 3 · Apple HIG · Fluent · Carbon · shadcn · Radix
│   │                          # · Ant · Polaris · Primer · Atlassian · Bootstrap
│   └── library/<name>/        # 138 brand-grade DESIGN.md specs
│
├── content/                   # UX writing & content design
│   └── voice-tone.md          # Voice & tone, error/empty-state copy, microcopy, inclusive language
│
├── components/                # Component specs (Atomic Design) — 50 components
│   ├── atoms · molecules · organisms · templates
│   ├── navigation · feedback · forms-advanced · overlays
│   └── data-display · data-viz · icon-system
│
├── accessibility/             # WCAG & ARIA references + inclusive design
│   ├── wcag-checklist.md      # WCAG 2.2 checklist (POUR, P0/P1/P2)
│   ├── aria-patterns.md       # WAI-ARIA patterns for 19 components
│   ├── cognitive.md · vision.md · i18n-rtl.md   # cognitive · low-vision/CVD/forced-colors · RTL
│   └── wcag-aaa.md            # AAA upgrade delta
│
├── workflows/                 # Design process + ops/pipeline guides
│   ├── design-review.md · design-to-code.md · prototyping.md · redesign-audit.md
│   └── governance.md · token-build.md · figma-integration.md · design-qa.md · performance.md
│
└── frameworks/                # Implementation patterns — ANY framework
    ├── adapter-protocol.md    # Universal translation contract
    ├── react-tailwind.md · nextjs.md · swiftui.md   # full references
    └── adapters/              # vue · svelte · angular · solid · web-components-lit · qwik · astro
                               # mui · mantine · chakra · bootstrap
                               # react-native · flutter · jetpack-compose · vanilla-css · css-in-js

[!NOTE] The design-taste layer (taste/) and the 138-system library (design-systems/library/) set visual direction; the system (tokens, components, accessibility) keeps it correct. Taste serves the Aesthetics tier and never overrides accessibility. Skills under .claude/skills/ run with agent permissions — review before use.

🎨 Token Architecture

The design token system follows a 3-tier hierarchy using the DTCG standard:

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│  COMPONENT TOKENS   │ ──► │  SEMANTIC TOKENS    │ ──► │  PRIMITIVE TOKENS   │
│  button-bg-primary  │     │  action.primary     │     │  blue.600 = #2563EB │
│  (use in code)      │     │  (use in design)    │     │  (raw palette)      │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘

Dark mode works by swapping semantic tokens — primitives stay the same.

🧰 Supported Frameworks — any

The Framework Adapter Protocol defines a universal token→framework contract, so the agent can target a stack even with no dedicated file (it generates an adapter on demand).

Full references

Concise adapters — Vue 3 · Svelte 5 · Angular · SolidJS · Web Components (Lit) · React Native · Flutter · Jetpack Compose · vanilla CSS · CSS-in-JS (emotion/vanilla-extract/Panda)

🔌 Design-System Interop — any

Adopt, build on, or migrate between external design systems via a role-based crosswalk (interop-protocol + crosswalk). Curated tables: Material Design 3 · Apple HIG · Fluent 2 · Carbon · shadcn/ui · Radix (others derived on demand). Plus a library of 138 brand-grade design systems (apple, linear, stripe, vercel, notion, spotify, tesla…) under design-systems/library/.

♿ Accessibility Standards

All outputs follow WCAG 2.2 Level AA as a minimum:

• ✅ Color contrast: 4.5:1 (text), 3:1 (UI components)
• ✅ Keyboard navigable with visible focus indicators
• ✅ Screen reader compatible with proper ARIA roles and live regions
• ✅ Touch targets: 24×24px minimum (WCAG 2.5.8)
• ✅ WCAG 2.2 criteria: Focus Not Obscured, Target Size, Accessible Authentication

⭐ Design Review Output

When reviewing designs, the agent scores across 6 weighted dimensions:

Findings are categorized: 🔴 Critical (must fix) → 🟠 Major (fix this sprint) → 🟡 Minor (when convenient) → 🔵 Enhancement (backlog).

🛠️ Customization

This is a starter kit — make it yours:

• Brand colors — edit tokens/colors.json primitives, then update semantic references
• Typography — swap font families in tokens/typography.json and framework files
• Components — add new components following the existing spec format in components/
• Frameworks — add new framework files in frameworks/ (e.g., vue.md, flutter.md)
• Workflows — adapt review rubrics and checklists in workflows/ to your team's process

📋 Requirements

• Claude Code CLI or any Claude-powered IDE
• A Claude model with sufficient context (Sonnet, Opus, or Haiku)

📝 Changelog

v2.2.1

• 🧪 State-aware WCAG gate — scripts/verify_states.mjs (npm run test:states) measures real computed contrast of every interactive element in default / hover / focus (light + dark), catching state bugs the resting-state gate missed (e.g. a secondary button picking up the primary fill on hover). Wired into accuracy_report (now 11 checks, 100%).
• 📐 Verification Protocol — new top-of-CLAUDE.md rule: never report a quality number you didn't measure; verify all states; run the gate before declaring done; build with the gates. design-code step 13 and a11y-audit now run the render gates instead of eyeballing.
• 🩹 Fixed real hover-state AA failures in examples/apple-demo; added examples/brandkit-demo (generated OKLCH foundation, light+dark, every state AA).

v2.2.0

• ⚡ 2 new runnable skills (15 → 17) — image-to-code (reference image/screenshot → infer the design system → token-driven, verified code) and brandkit (brief → complete primitive→semantic→component DTCG token foundation + theme.css, light + dark, WCAG-verified). Both native, fit the kit's gates.
• 🎨 Render-based taste audit — scripts/taste_audit.mjs (npm run taste) measures structural slop tells from real computed styles: timid type-scale contrast, uniform repetition, over-wide measure, palette sprawl. Wired into the design-code taste pre-flight. Heuristic by design — a strong signal, not proof (taste is subjective).
• 🧹 De-emoji'd the taste doctrine itself; router rows + skills list updated.

v2.1.0

• ✅ Accuracy report — npm run verify (scripts/accuracy_report.mjs) runs every objective correctness gate as one all-or-nothing, reproducible check: token validity + alias resolution, WCAG contrast (token pairs), component-spec completeness, no hardcoded values (golden + sample), theme-ref resolution, no-emoji, and real headless-Chrome WCAG measurement (sample-app, light + dark). Prints N/N = 100% or the exact failures.
• 🧱 Block-level lint exemption — scripts/lint_hardcodes.py supports ds-allow-hardcode:start / :end for justified illustration blocks (e.g. CSS product art), keeping the rest of the file strictly token-only.

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: 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
• ⟨⟩ 6 new framework adapters — Qwik, Astro, MUI, Mantine, Chakra, Bootstrap → 16 adapters
• 🔌 Extended interop crosswalks — Ant Design 5, Shopify Polaris, GitHub Primer, Atlassian, Bootstrap (color-role tables + per-system notes)
• ♿ Accessibility depth — cognitive.md (load, plain language, dyslexia, reduced-data), i18n-rtl.md (logical properties, RTL mirroring, text expansion), vision.md (color blindness, low vision, forced-colors), wcag-aaa.md (AAA upgrade delta); +4 ARIA patterns (Carousel, Grid, Toolbar, Feed)
• ⚙️ Ops & pipeline workflows — governance.md (SemVer, contribution, deprecation), token-build.md (Style Dictionary / DTCG → multi-platform), figma-integration.md (token↔Variable sync, Figma MCP), design-qa.md (visual regression + a11y CI), performance.md (Core Web Vitals)

v1.1.0

• 📦 npm package — install into any project with npx ux-ui-agent-skills init (zero-dependency CLI: init / add / list, --force/--dry)
• ⚡ Runnable skills — 10 invocable /skills under .claude/skills/ + real helper scripts (validate_tokens.py, contrast.py, design_systems.py, scaffold_component.py)
• 🧠 Intelligence layer — Request Router in CLAUDE.md; Framework Adapter Protocol (target any framework) with 10 concise adapters; Design-System Interop Protocol + crosswalk (map to/from any design system)
• 🎭 Native design-taste — taste/ (anti-slop doctrine, aesthetic archetypes, motion choreography) + a library of 138 brand-grade design systems
• ➕ 6 new token categories — gradients, opacity, blur, sizing, states, theming (multi-brand + density)
• 🧩 16 new component specs — Tabs, Breadcrumb, Pagination, Stepper, Menu, Toast, Banner, Skeleton, Progress, Empty State, Combobox, Select, Slider, Date Picker, File Upload, Popover, Command Palette, Divider
• 🧹 Removed the externally-bundled taste skills in favor of native, first-party content

v1.0.1

• ➕ Motion tokens — tokens/motion.json: duration scale, easing curves, transition presets, keyframes, reduced-motion strategy
• ➕ UX writing guide — content/voice-tone.md: voice & tone system, error/empty-state formulas, microcopy patterns, inclusive language, pre-ship checklist
• 🎨 Added cover.html repo cover image

v1.0.0

• 🎉 Initial release — agent persona, 6 token files, 26 components (Atomic Design), WCAG 2.2 + ARIA references, 3 workflow guides, 3 framework guides

📄 License

Released under the MIT License.