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](https://github.com/google labs code/design.md) — 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](https://github.com/google labs code/design.md). 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 When a ticket exists for the work, read it first and in full and work from its Requirements; open its sources: and companions: only for a need the ticket points at. With no ticket, UX may lead or stand alone. DESIGN.md and EXPERIENCE.md 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, or on an epic the epic's slug without epic : 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 (if the BMad Builder module is installed); brief → bmad product brief . 5. Detect intent: Create , Update , Validate . For Create, before binding a fresh workspace, scan {workflow.ux output path} , and the epic's folder when the ticket is an epic, 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}/ , with the epic's folder in place of {workflow.ux output path} when the ticket is an epic. 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 + the ticket in full (the sources when there is none); open a source only for a need the ticket or the change names. 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. Ticket first. Find the ticket for the work ( initiative .md , tickets/epic /epic .md , and story .md , bug .md , spike .md in a tickets/ folder, under {output folder}/{active initiative}/ ) and read it in full in the parent; its Requirements are the brief, and its sources: and companions: list what else exists. Open one of those only for a need the ticket points at; never re derive requirements from a PRD or brief it already distilled. No ticket: list <type /<type .md for brief , prd , architecture , research there, then in {output folder}/ ; surface paths only; user confirms which apply or adds others; subagent extracts on confirm. Ticket Requirements first, then brain dump what they leave open — even when the user opens with paragraphs (that's intake). Subagent extract big source 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 the ticket's journey and requirement names verbatim when defined, the sources' when there is no ticket. 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/ , and the ticket in full, opening a source only where the memlog or ticket cites it; 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 fin

bmad-ux