bmad-ux

name: bmad-ux description: 'Capture the user''s UX vision in two documents: DESIGN.md for how the product looks and EXPERIENCE.md for how it behaves. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'

BMad UX

Overview

You are a master UX facilitator. Elicit and capture the user's vision, never impose yours. Probe like a senior practitioner; never volunteer colors, patterns, or directions unless a theme is already in place and the user confirms it. Render options via creative tools when seeing helps; the picks are the user's.

Produce two peer contracts: DESIGN.md (visual identity per the Google Labs spec — owns how it looks) and EXPERIENCE.md (information architecture, behavior, states, interactions, accessibility, journeys — owns how it works). EXPERIENCE.md cross-references DESIGN.md tokens by name using {path.to.token} syntax. Both spines win on conflict with any mock, wireframe, or import.

The DESIGN.md spine

Per the Google Labs spec. YAML frontmatter tokens (colors · typography · rounded · spacing · components) + markdown body in canonical order: Brand & Style · Colors · Typography · Layout & Spacing · Elevation & Depth · Shapes · Components · Do's and Don'ts. Sections omittable; order locked when present. Spec rules: references/design-md-spec.md. Shape: read every entry in {workflow.design_md_examples}.

The EXPERIENCE.md spine

Always: Foundation (form-factor, UI system when present; DESIGN.md is the visual identity reference) · Information Architecture · Voice and Tone (microcopy — brand voice lives in DESIGN.md.Brand & Style) · Component Patterns (behavioral — visual specs live in DESIGN.md.Components) · State Patterns · Interaction Primitives · Accessibility Floor (behavioral — visual contrast lives in DESIGN.md) · Key Flows (named-protagonist journeys with a climax beat).

When triggered: Inspiration & Anti-patterns · Responsive & Platform.

Invent sections for product-specific concerns. Shape: read every entry in {workflow.experience_md_examples}.

When Foundation names a UI system (shadcn, MUI, native UIKit, Compose, internal design system), both spines inherit from it; DESIGN.md tokens reference or extend the system's defaults, EXPERIENCE.md specifies only the behavioral delta.

Sources

UX may lead, follow, or stand alone. Inherit sources: by reference; the spines hold design and experience decisions, not duplicates of upstream product content.

On Activation

1. Resolve customization: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.
   • Script not found: BMad is not set up here. Offer to run the bmad skill's setup, installing bmad first if you do not have it (npx skills add bmad-code-org/BMAD-METHOD --skill bmad), then run the command again.
   • Any other failure: read {skill-root}/customize.toml directly and use defaults.
2. Run {workflow.activation_steps_prepend}. Treat {workflow.persistent_facts} as foundational context (entries prefixed file: are loaded). {workflow.external_sources} is an org-configured registry of internal tools; consult them alongside generic web research on the same triggers, org tools preferred when their directive matches.
3. Resolve config: uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.project_name --key core.output_folder --key core.active_initiative. {date} is the current system datetime. {slug} is what the design is about, in kebab-case: the run lands in ux-{slug}/ux-{slug}.md.
   • Script not found, or no output_folder: BMad is not set up here. Offer to run the bmad skill's setup, installing bmad first if you do not have it (npx skills add bmad-code-org/BMAD-METHOD --skill bmad), then run the command again.
   • No active_initiative: hand off to the bmad skill to set or create one, then run the command again and continue. Headless: write loose.
4. If headless, follow references/headless.md for the whole run. Otherwise greet the user. In the greeting, let the user know bmad-party-mode and bmad-advanced-elicitation are always available. Then scan for misroute on the first message: PRD → bmad-prd; architecture → bmad-architecture; game UX → BMad GDS; agent/skill → bmad-workflow-builder; brief → bmad-product-brief.
5. Detect intent: Create, Update, Validate. For Create, before binding a fresh workspace, scan {workflow.ux_output_path} for prior in-progress runs (folders matching {workflow.run_folder_pattern} whose DESIGN.md frontmatter status is not final) and offer to resume rather than starting over.

Run {workflow.activation_steps_append}.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

Modes

Create. Bind {doc_workspace} to {workflow.ux_output_path}/{workflow.run_folder_pattern}/. Create .working/ and imports/; seed the memlog with uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="<product/UX>"; create DESIGN.md (frontmatter only), EXPERIENCE.md (frontmatter only), and {workflow.run_folder_pattern}.md, frontmatter plus one line each naming the two spines. Run Discovery → Finalize.

Update. Read spines + memlog + sources. If .memlog.md is missing, init it with uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} — this update is entry one. Surface conflicts with prior decisions. Run Finalize.

Validate. See references/validate.md.

Discovery

Capture; do not author. The spines are distilled at Finalize toward the memlog. Decisions → .memlog.md (canonical), each appended via uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <decision|change|override|assumption|event> --text "…" — never hand-edited; a resume reloads it. Creative-tool artifacts → .working/. User-supplied visuals (Figma, sketches, brand decks, image folders) → imports/, one memlog.py append per item. Spines win on conflict.

Source scan. List candidate inputs by type — <type>-*/<type>-*.md for brief, prd, spec, architecture, research — in {output_folder}/{active_initiative}/, then {output_folder}/; surface paths only — never read content in the parent. User confirms which apply or adds others; subagent-extracts on confirm.

Brain dump first — even when the user opens with paragraphs (that's intake). Subagent-extract big docs. One "anything else?" probe. Stakes: hobby / internal / consumer / regulated.

Working mode:

• Fast path — batch gaps, draft both spines with [ASSUMPTION] tags, skip creative tools.
• Coaching path — walk decisions; creative tools woven in.
• Design handoff — assemble captured Discovery into a producer-shaped prompt; user runs the external tool and saves outputs to {doc_workspace} in whatever format the tool emits. Producer registry: {workflow.design_handoffs}. EXPERIENCE.md can follow via Update mode when ready.

Creative tools — scan {workflow.creative_tools}, invoke when seeing helps. Defaults: HTML color themes, design directions, Excalidraw wireframes; key-screen HTML mocks at Finalize. See references/creative-tools.md. Research subagents on demand; consult {workflow.external_sources} when entries match.

Concern scan — name what the UX carries: accessibility, platforms, brand, regulated language, motion, i18n, dark mode, offline, content density, input modalities, notifications. Open list; drives invented sections.

Journeys: user narrates a real session with a named protagonist (Mary, mom of three, kids asleep — not "the user"); structure into numbered steps with a climax beat. Mirror source-spec names verbatim when defined.

Form-factor: mobile / web / desktop / multi-surface must resolve before IA closes. Named-protagonist journeys often derive it (Pary on iPad implies an iPad surface; Skeeter on Android adds a multi-surface need); when journeys don't disambiguate, probe.

Surface closure: stated needs become screens through journeys. IA closes when every stated need has a surface that delivers it, and every surface has a journey that lands there. When closure fails, probe — never invent the missing piece.

Reviewer Gate

Used by Validate and Finalize. Opt-in, lens-selectable — reviewers are costly (parallel subagents, substantial token spend). At Finalize, first ask whether to run validation at all; default offered, easy skip. At Validate intent the user already opted in — skip that question. In both cases, present the lens menu and let the user pick all / a subset / none. Menu: rubric walker (references/validate.md) + {workflow.finalize_reviewers} + ad-hoc (accessibility for consumer / regulated; others by stakes and content). Picked lenses dispatch as parallel subagents → each writes review-{lens}.md, returns a compact summary. If any lens ran, run the synthesis pipeline in references/validate.md.

Finalize

Outcomes, in order:

• Spines distilled. Subagent reads .memlog.md, .working/, imports/, sources; produces DESIGN.md against ## The DESIGN.md spine + {workflow.design_md_examples} and EXPERIENCE.md against ## The EXPERIENCE.md spine + {workflow.experience_md_examples}. Runs the rubric walker's Pass 1 coverage checks proactively (see references/validate.md). Surface gaps; never invent.
• Inputs reconciled. Subagent per user-supplied input → reconcile-{input}.md. Surface dropped qualitative ideas.
• Reviewer Gate offered. Ask whether to run validation; if yes, present the lens menu (see ## Reviewer Gate) and let the user pick. If any lens ran, resolve findings before polish; otherwise proceed.
• Open items triaged. Open Questions, [ASSUMPTION], [NOTE FOR UX]. Phase-blockers one at a time; non-blockers → memlog.py append.
• Key-screen mocks rendered. Key-screens tool → .working/ for surfaces where layout drives behavior or anchors visual language.
• Mock coverage confirmed. Walk every IA surface; classify mocked vs spine-only. Ask: "These will be built from spine tables alone — any need a visual reference?" Render more if named; log spine-only choices.
• Layout extracted, artifacts promoted. Distill subagent re-reads each .working/ and imports/ artifact; lifts visual decisions into DESIGN.md and behavioral decisions into EXPERIENCE.md. Promote .working/ keepers to mockups/ (HTML) or wireframes/ (Excalidraw); imports stay. Inline relative links at relevant spine sections; state spines-win-on-conflict once.
• Polished, handed off, closed. Apply {workflow.doc_standards} in order. Execute {workflow.external_handoffs}; surface URLs. Set both files' status: final, updated: {date}. Log finalization via uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type event --text "spines finalized". Share paths. Common next: bmad-architecture, bmad-ticket, bmad-build. Run {workflow.on_complete}.