Guide

September 14, 2026 · View on GitHub

The reference half of the documentation: how the skills compose, what the repo contains, the token architecture, the frameworks and design systems it targets, and how to set a new product project up. The README is the short version.

Start a New Design Project
How to Use
Project Structure
Token Architecture
Supported Frameworks — any
Design-System Interop — any
Accessibility Standards
Design Review Output
Customization
Using it as a Claude Code plugin
Look before installing
Install from a clone
Requirements

Start a New Design Project

The kit is the engine. A product repo that uses it wants its own lean layout, and templates/product-design/ is that starter, shipped ready to copy:

your-product/
  CLAUDE.md              the brief Claude reads every session (lean, placeholders to fill)
  CLAUDE.local.md        your personal prefs, gitignored
  .mcp.json              Figma / Notion connections, env-expanded, no secrets
  .claude/
    rules/               components.md · tokens.md · accessibility.md — load only when relevant
    skills/              repeatable workflows your team adds
    commands/            /gate — the project's own all-or-nothing check
    settings.json        shared permissions, checked into git
  design-tokens.json     source of truth: color, type, spacing (light + dark, WCAG-verified)
  src/components/        the real UI Claude reads and edits
  public/images/         real images so prototypes do not break
  reference/             real screens Claude studies for context

In Claude Code, from a clone of this repo:

/scaffold-project ../your-product

It copies the template, installs the engine areas next to it (npx ux-ui-agent-skills add tokens components taste accessibility workflows content frameworks design-systems scripts skills), and walks the placeholders with you. The project brief stays short on purpose: it loads on every turn, so everything that is not needed every turn lives in .claude/rules/ or a skill.

The seeded theme is not a guess. python3 scripts/validate_template.py proves the layout is complete, every alias resolves, and the required contrast pairs pass WCAG 2.2 AA in both light and dark before a project starts from it.

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.

Each SKILL.md carries an invocation field, so it is clear which ones you drive and which ones the agent reaches for on its own. Both kinds can be typed as a slash command.

User-invoked — you start them, they orchestrate a whole job

Command	What it does
`/brandkit`	A whole brand foundation from a brief: tokens, light + dark, one theme.css, WCAG-verified
`/redesign`	Audit-first upgrade of an existing UI without breaking it
`/image-to-code`	A screenshot or mockup becomes token-driven, accessible code
`/prototype`	Move up the fidelity ladder and plan the usability test
`/migrate-design-system`	Map to or from Material 3, Apple HIG, shadcn, Radix, and the rest
`/governance`	Version, contribute, deprecate: how the system is allowed to change

Model-invoked — the discipline the agent applies while it works

Command	What it does
`/design-tokens`	Generate, extend, or validate DTCG tokens, palettes, multi-brand theming
`/design-component`	Spec a component: anatomy, variants, the 8 states, a11y
`/design-code`	Generate code for any framework via the Adapter Protocol
`/design-review`	Score a design across 6 dimensions plus Nielsen, with a findings table
`/a11y-audit`	WCAG 2.2 audit and contrast checks
`/apply-aesthetic`	Apply an archetype or one of 138 named design systems
`/design-qa`	Stand up the CI gates that keep regressions out
`/ux-writing`	Write or review buttons, errors, empty states, microcopy
`/token-build`	Tokens to CSS, Tailwind, iOS, Android, Compose
`/figma-integration`	Token to Figma Variable sync and component parity
`/performance`	Core Web Vitals, layout shift, animation cost

Five slash commands round it out: /grill-me interrogates the brief before anything is built, /gate runs the whole gate and reports the real N/N, /critique hands the result to an adversarial reviewer, /ship adds the release checklist, and /scaffold-project starts a new product repo from the template.

/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
python3 scripts/validate_template.py               # the starter template stays sound
python3 scripts/validate_instruction_surface.py    # no always-on rule got demoted
node    evals/run.mjs --self-test                  # the cold-start scorer still works

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, gates, router — the always-on brief (~270 lines)
├── CONTEXT.md                 # Ubiquitous language — shared domain vocabulary
├── CLAUDE.local.md            # Personal prefs (gitignored, per-machine)
├── .mcp.example.json          # Optional Figma MCP for THIS repo — copy to .mcp.json to use
│
├── .claude/rules/             # Depth split out of CLAUDE.md, loaded only when relevant
│   └── tokens-and-color · typography-and-spacing · components · accessibility
│       frameworks · review-and-research · brand-and-operations
├── .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
├── .claude/commands/          # Slash commands — /grill-me · /gate · /critique · /ship · /scaffold-project
├── .claude/settings.json      # Shared permissions (scripts allowlist), checked into git
├── .claude/agents/            # design-critic — the adversarial reviewer behind /critique
│
├── evals/                     # Cold-start briefs + run.mjs — 14 objective gates on produced work
│
├── reference/                 # Real screens the agent studies before designing/reviewing
│
├── templates/product-design/  # Starter layout for a NEW product repo — /scaffold-project
│   ├── CLAUDE.md · CLAUDE.local.md.template · .mcp.json · design-tokens.json
│   └── .claude/{rules,skills,commands,settings.json} · src/components · public/images · reference
│
├── 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)      │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘

Tier	Role	Example
Primitive	Raw color/size values — never referenced directly	`blue.600`, `space.4`
Semantic	Purpose-based aliases — used in design	`action.primary`, `text.secondary`, `surface.card`
Component	Scoped to specific components — used in code	`button.primary-bg`, `input.border-focus`

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

Framework	Version	Key Patterns
React + Tailwind	React 19, Tailwind v4	`forwardRef`, `cva`, `cn()`, CSS custom properties
Next.js	15 (App Router)	Server/Client Components, `next/font`, `next/image`, Server Actions
SwiftUI	6 (iOS 18+)	`ButtonStyle`, `ViewModifier`, `@ScaledMetric`, Dynamic Type

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:

Dimension	Weight	Dimension	Weight
Visual Hierarchy	20%	Usability	20%
Consistency	20%	Responsiveness	10%
Accessibility	20%	Performance	10%

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

Using it as a Claude Code plugin

/plugin marketplace add plugin87/ux-ui-agent-skills
/plugin install ux-ui-agent-skills@ux-ui-agent-skills

The marketplace is this repository: add clones it and validates .claude-plugin/marketplace.json, install registers the plugin from it. In the Claude Code UI, /plugin then Discover browses the same thing.

What lands in your session

Kind	What
Skills (19)	`design-doctrine` plus every runnable skill: tokens, component, code, review, a11y-audit, aesthetic, brandkit, data-dashboard, image-to-code, redesign, interop, prototype, ux-writing, governance, token-build, figma, qa, performance
Commands (5)	`/grill-me`, `/gate`, `/critique`, `/ship`, `/scaffold-project`
Agent	`design-critic`, the adversarial reviewer behind `/critique`
MCP servers	none - deliberately. The repo's own `.mcp.json` ships as `.mcp.example.json` so installing a design kit never registers a third-party server on your machine

design-doctrine exists because a plugin's root CLAUDE.md is not loaded as project context - claude plugin validate says so outright. Without it an install would ship every file and none of the rules, so the verification protocol, the no-emoji rule, the five non-negotiables and the routing table travel as a skill instead.

Managing it

claude plugin details ux-ui-agent-skills     # component inventory + projected token cost
claude plugin list                           # everything installed
claude plugin update ux-ui-agent-skills      # pull a newer version (restart to apply)
claude plugin uninstall ux-ui-agent-skills
claude plugin marketplace list | update <name> | remove <name>
claude plugin validate .                     # validate a manifest before committing it

Skills and commands appear in a fresh session. If /gate or /design-component is not offered right after installing, start a new session and check claude plugin details.

Token cost. claude plugin details prints it: the always-on cost is the description line of every skill, and each skill's body is only paid when it fires. Budget the always-on number, not the sum.

Look before installing

npx ux-ui-agent-skills demo [dest]     # default: ./ux-ui-demo

Copies the bundled examples/ - the reference app, 23 component harnesses, two aesthetic demos, all rendering from one token theme - and opens the index in a browser. --no-open copies without launching anything, --dry reports what it would copy and writes nothing. The folder is a throwaway: nothing is installed into your project.

Install from a clone

For working on the kit itself, or vendoring it into a monorepo:

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

The plugin and npx paths in the README are what most projects want. See CONTRIBUTING.md for the full development setup, including the gates.

Requirements

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

Back to the README, the changelog, or the live demo.