bmad-ux Skill: Capture Your UX Vision in DESIGN.md and EXPERIENCE.md

Interviews you about your product and writes two UX documents: DESIGN.md for how it looks and EXPERIENCE.md for how it behaves.

Installs: 12.9K; on skills.sh
Stars: 54.9K; on GitHub
Files: 17; besides SKILL.md
Updated: Nov 2026; last repo commit

bmad-ux is a BMad Method skill that makes Claude act as a UX facilitator. It captures your vision instead of imposing its own, and says it never volunteers colors or patterns unless a theme is already in place and you confirm it. It produces DESIGN.md, which follows the Google Labs DESIGN.md spec, and EXPERIENCE.md, which covers information architecture, states, interactions, accessibility and named-protagonist user journeys.

It has three modes: create, update and validate. When seeing helps, it renders HTML color themes, design directions, Excalidraw wireframes and key-screen mocks into a .working/ folder. It needs the BMad setup: the skill runs uv run scripts from _bmad/scripts, and the bmad skill installs those.

Good for

Designers and PMs who want the UX written down before building
Developers who need a clear visual and behavior contract for an app
Teams using the BMad Method who go from brief to UX to architecture
Anyone wanting color and layout options shown as HTML mockups

Install bmad-ux

Claude Code

Copy this prompt.

Install the bmad-ux skill in Claude Code. Run this command:

npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-method --skill bmad-ux

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js, Git, uv.

bmad-ux belongs to the bmod-method module and needs the bmad skill, which sets up the _bmad folder in your project. The README needs uv for BMad setup and Python scripts. These are the v7 preview alpha skills from the main branch, which the README says change often. There is no Claude app upload route, because the skill runs uv scripts inside a project folder. The plugin marketplace repo lists the plugins as bmad-method and bmad-toolbox, while the main README calls the second one bmad-core-tools. The plugin tree holds skills only, with no hooks or MCP files.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

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"

Sections in SKILL.md

Overview
The DESIGN.md spine
The EXPERIENCE.md spine
Sources
On Activation
Modes
Discovery
Reviewer Gate
Finalize

Key facts

Author: BMad Code (bmad-code-org)
Repository: bmad-code-org/bmad-method
Installs on skills.sh: 12,909 as of 2026-11-02
GitHub stars: 54,859 for the whole repo, 2026-11-02
Last commit to the repo: 2026-11-01
Files: 18 files including SKILL.md (11 in assets/, 4 in references/, bmod.toml and customize.toml)
License: MIT per the repo LICENSE file and README (GitHub license detection reports NOASSERTION)
Module: Part of bmod-method; needs the bmad skill and uv
Status: README calls these v7 skills a preview alpha
Outputs: DESIGN.md, EXPERIENCE.md and ux-{slug}.md in a ux-{slug} folder under the output folder

What it includes

Binds a ux-{slug} workspace, then runs Discovery and Finalize
Creates .working/ and imports/ folders, a seeded decision log and frontmatter-only DESIGN.md and EXPERIENCE.md, then fills them through discovery.
Try: “Help me plan the UX for a recipe-sharing app.”
Runs code · Create
Reads both documents and the decision log, then changes them
Surfaces conflicts with prior decisions before editing, then runs Finalize.
Write · Update
Critiques an existing DESIGN.md and EXPERIENCE.md pair without changing it
Runs the rubric in references/validate.md, with lenses you pick. Reviewers run as parallel subagents and the file says they are costly.
Read · Validate
Batch the gaps, walk decisions with visuals, or hand off to an outside tool
Fast path drafts both documents with [ASSUMPTION] tags. Design handoff assembles a prompt for a tool such as Google Stitch, and you run that tool yourself.
Fast, coaching or design-handoff path
HTML color themes, design directions, Excalidraw wireframes, key-screen mocks
Renderers write artifacts to .working/. On macOS, Linux or Windows Claude can open an HTML file in your browser with the platform opener.
Runs code · Creative tools
Visual tokens and components, plus IA, states, interactions and journeys
DESIGN.md holds colors, typography, rounded, spacing and components. EXPERIENCE.md holds Foundation, Information Architecture, Voice and Tone, Component and State Patterns, Interaction Primitives, Accessibility Floor and Key Flows.
DESIGN.md and EXPERIENCE.md
Three DESIGN.md examples, two EXPERIENCE.md examples and a spec summary
Claude reads the examples in assets/ so the output has the right shape. references/ also holds the creative tools, headless mode, spec and validate guides.
Read · Reference files

From the official docs

Permissions

Low risk

The skill writes design documents and mockups into your project and runs setup scripts. Validation uses many subagents, so choose lenses with care.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It runs scripts from your project
The skill calls uv run on scripts in _bmad/scripts, put there by the bmad skill. github.com
Validation spawns many subagents
Reviewer lenses run as parallel subagents and the guide calls them costly. It asks first, so pick only the lenses you need. github.com
Handoffs go to tools you run
The default design handoff names Google Stitch. You run that tool and save its output yourself. github.com

Technical details

Scopes	Runs uv run scripts from the project's _bmad/scripts folder Writes DESIGN.md, EXPERIENCE.md, HTML mocks, wireframes and a decision log under the output folder Can open generated HTML in your browser with the platform opener

Questions

What does bmad-ux do?

It interviews you and writes DESIGN.md for the visual identity and EXPERIENCE.md for the behavior, states, accessibility and user journeys of your product.

How do I install bmad-ux in Claude Code or Codex?

Use the install box at the top of this page. It installs the skill with the bmad hub skill and its module record. Then ask bmad to run bmad setup in your project.

Will it choose my colors and layouts?

No. SKILL.md says to elicit your vision and never volunteer colors, patterns or directions unless a theme is in place and you confirm it. It can render options for you to pick from.

Is it safe?

It writes documents, HTML mocks and a decision log into your project and runs uv scripts from _bmad/scripts. The default design handoff names Google Stitch, which you run yourself outside the skill.

Does it cost a lot of tokens?

Validation can. references/validate.md says reviewers are costly because they run as parallel subagents, so it asks before running them and lets you choose which lenses.

Does it work in the Claude app?

The install box leaves out a Claude app upload route, because the skill runs uv scripts inside your project folder. Use Claude Code, Codex or another coding tool that supports skills.

Information

updated Nov 2, 2026

Repository: bmad-code-org/bmad-method
Folder: skills/bmad-ux

bmad-code-org/bmad-method skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

BMAD-METHOD README · github.com
bmad-plugins README · github.com
bmad-plugins marketplace.json · github.com
bmad-ux SKILL.md · github.com
validate.md · github.com
creative-tools.md · github.com
customize.toml · github.com