/bmad-ux

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):

1. `bmad-output/config.yaml` — project name, track, output folder. 2. `bmad-output/project-context.md` — user personas, platform targets, constraints. 3. `bmad-output/prd.md` (if present) — feature list, user stories, acceptance criteria. 4. `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" #foreground #background

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 | W