| name | bmad-ux |
| description | Solutioning-phase UX planning skill (optional; activate when the project has a UI).
Produces TWO planning documents: DESIGN.md (the visual system — design tokens, color
palette, typography, spacing, component specs, WCAG 2.1 AA contract) and
EXPERIENCE.md (user journeys, flow diagrams, screen states, error/empty/loading
handling). Use when the user says "design the UX", "create UX planning docs",
"define the design system", "map the user flows", "UX for this feature",
"wireframe the flows", "what are the user journeys", "accessibility design",
"WCAG compliance", "design tokens", "responsive design plan", "mobile-first design",
or "create DESIGN.md / EXPERIENCE.md". Runs after architecture is drafted and before
stories are created. Supports Create / Update / Validate intents.
|
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, TodoWrite |
BMAD UX — Visual System & Experience Planning
Produces the two-document UX contract that downstream story authors and the external
dev tool rely on. This is a planning skill. It produces specifications, not code.
What it produces
Under bmad-output/ (or the folder in config.yaml):
bmad-output/
├── DESIGN.md # Visual system: tokens, components, accessibility contract
└── EXPERIENCE.md # Journeys, flows, states, error/empty/loading specs
Both documents are locked planning artifacts. The external dev tool may read them
but must not edit them. All design decisions should be recorded in decision-log.md.
Three intents
- Create — generate both documents from scratch (most common).
- Update — revise specific sections when requirements change; append a dated entry
to
decision-log.md explaining what changed and why.
- Validate — audit existing documents for completeness and WCAG 2.1 AA gaps. Run
the WCAG checklist; report findings but do not alter the project's code.
Pre-flight reads
Before drafting, read (in order):
bmad-output/config.yaml — project name, track, output folder.bmad-output/project-context.md — user personas, platform targets, constraints.bmad-output/prd.md (if present) — feature list, user stories, acceptance criteria.bmad-output/architecture.md (if present) — component boundaries, API contracts.
If any of these are missing, ask the user for the key inputs before proceeding.
DESIGN.md — Visual System
Use ${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/design.template.md.
The document covers:
1. Design Tokens
Commit to concrete values. Placeholders are not acceptable for tokens.
- Color palette: primary, secondary, semantic (success / warning / error / info),
neutral scale. All color pairs used for text must be WCAG 2.1 AA verified.
- Typography: font families, size scale (mobile → desktop), weight, line-height.
Minimum 16px body on mobile (prevents iOS zoom). Base unit: 8px.
- Spacing scale (8px grid), border-radius set, shadow/elevation set.
- Breakpoints: 320px (mobile), 768px (tablet), 1024px (desktop), 1440px (desktop XL).
2. Component Specs
For each component: visual defaults, all interaction states (default / hover / focus /
active / disabled / loading / error / success), responsive behavior, and accessibility
annotations (ARIA roles, aria-label placement, focus-trap rules, min touch target
44×44px on mobile).
Core components to specify: buttons (primary / secondary / destructive), text inputs,
select / checkbox / radio, cards, modals, navigation (desktop + mobile hamburger),
loading/skeleton states, error banners.
3. WCAG 2.1 AA Contract
Enumerate the concrete accessibility requirements the visual system guarantees:
- Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large text ≥ 18px or bold ≥ 14px).
- UI component / graphic contrast ≥ 3:1.
- Visible focus indicator (2px solid outline minimum).
- All functionality reachable via keyboard.
- No horizontal scroll at 320px viewport width.
- Touch targets ≥ 44×44px with ≥ 8px spacing.
Run the checklist to produce the contract summary:
bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/wcag-checklist.sh"
Check specific color pairs with:
python "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/contrast-check.py"
Verify responsive breakpoint rules:
bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/responsive-breakpoints.sh"
EXPERIENCE.md — User Experience Plan
Use ${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/experience.template.md.
The document covers:
1. User Journeys
One section per major journey (onboarding, core workflow, settings, error recovery, etc.).
Each journey: goal, persona, entry points, happy-path flow diagram (ASCII or bullet
steps), estimated time, and drop-off risk notes.
2. Screen / State Inventory
For every screen or major view: purpose, layout wireframe (ASCII encouraged),
component hierarchy, and all named states:
- Default — normal first-load state.
- Loading — skeleton or spinner;
aria-live="polite" announced.
- Empty — zero-data state with helpful call-to-action.
- Error — what went wrong + recovery action.
- Success — confirmation feedback.
- Disabled — why access is restricted.
3. Decision Points & Alternative Paths
For each journey, map the branch points (validation failure, auth required, network
error, timeout, etc.). Each branch: trigger, display, and recovery path.
4. Interaction & Animation Notes
Timing and easing for transitions. Respect prefers-reduced-motion. Note which
animations are decorative vs. meaningful.
Subagent strategy
For projects with more than four major journeys, fan out parallel subagents:
| Agent | Task | Output file |
|---|
| Agent 1 | Design tokens + color/contrast pairs → DESIGN.md §1 | bmad-output/ux-tokens-draft.md |
| Agent 2 | Core component specs → DESIGN.md §2 | bmad-output/ux-components-draft.md |
| Agent 3 | WCAG contract + a11y annotations | bmad-output/ux-a11y-draft.md |
| Agent N | One major user journey + screen states | bmad-output/ux-journey-N-draft.md |
Write shared context to bmad-output/ux-shared-context.md (personas, brand intent,
breakpoints) before launching agents. The main context assembles the drafts into the
two final documents and runs the WCAG checklist across all screens.
Example subagent prompt:
Task: Design the [journey name] user flow with full state coverage.
Context: Read bmad-output/ux-shared-context.md for personas, tokens, and component patterns.
Objective: Produce the [journey name] section of EXPERIENCE.md covering: entry points,
happy-path flow diagram, all screen states (loading/empty/error/success), decision
branch map, and accessibility annotations.
Output: Write to bmad-output/ux-journey-[name]-draft.md.
Constraints:
- Follow design tokens from context (colors, spacing, typography).
- WCAG 2.1 AA compliance: 4.5:1 contrast, keyboard accessible, 44px touch targets.
- Design mobile-first (320px), then scale to tablet and desktop.
- Specify all interaction states per component.
- No application code — planning specifications only.
Guardrails
- This skill produces planning documents. It never writes application code, CSS,
component implementations, or test suites.
- If the project has no UI (API-only, CLI-only, background service), skip this skill
entirely and note the decision in
decision-log.md.
- Stop before "implement". Hand off to the story-creation skill once the two documents
are approved.
See REFERENCE.md for design pattern library, full breakpoint reference, and
component state matrix.
Part of the BMAD Planning & Orchestrator plugin — a Claude Code harness for the BMAD Method by the BMAD Code Organization (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of bmad-ux-designer. All methodology credit belongs to the BMAD Code Organization.
