aj-geddes/bmad-ux

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