--- name: aj-geddes/bmad-ux source: https://app.decimal.ai/s/aj-geddes-bmad-ux@1/SKILL.md source_sha256: b693e4606339 --- # 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 bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/wcag-checklist.sh" ``` Check specific color pairs with: ```bash python "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/contrast-check.py" #foreground #background ``` Verify responsive breakpoint rules: ```bash 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.