bmad-ux

Name: bmad-ux
Author: aj-geddes

26installs73forks

How to install bmad-ux?

aj-geddes/claude-code-bmad-skills/bmad-ux

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-ux

Installs into the current project.

Summary

Solutioning-phase UX planning skill (optional; activate when the project has a UI). Produces TWO planning documents: DESIGN.md (the visual system — design tokens, color palette, typography, spacing, component specs, WCAG 2.1 AA contract) and EXPERIENCE.md (user journeys, flow dia

Files · 1

View on GitHub

SKILL.md

1	# BMAD UX — Visual System & Experience Planning
2
3	Produces the two-document UX contract that downstream story authors and the external
4	dev tool rely on. This is a planning skill. It produces specifications, not code.
5
6	## What it produces
7
8	Under `bmad-output/` (or the folder in `config.yaml`):
9
10	```
11	bmad-output/
12	├── DESIGN.md # Visual system: tokens, components, accessibility contract
13	└── EXPERIENCE.md # Journeys, flows, states, error/empty/loading specs
14	```
15
16	Both documents are locked planning artifacts. The external dev tool may read them
17	but must not edit them. All design decisions should be recorded in `decision-log.md`.
18
19	## Three intents
20
21	- Create — generate both documents from scratch (most common).
22	- Update — revise specific sections when requirements change; append a dated entry
23	to `decision-log.md` explaining what changed and why.
24	- Validate — audit existing documents for completeness and WCAG 2.1 AA gaps. Run
25	the WCAG checklist; report findings but do not alter the project's code.
26
27	## Pre-flight reads
28
29	Before drafting, read (in order):
30
31	1. `bmad-output/config.yaml` — project name, track, output folder.
32	2. `bmad-output/project-context.md` — user personas, platform targets, constraints.
33	3. `bmad-output/prd.md` (if present) — feature list, user stories, acceptance criteria.
34	4. `bmad-output/architecture.md` (if present) — component boundaries, API contracts.
35
36	If any of these are missing, ask the user for the key inputs before proceeding.
37
38	## DESIGN.md — Visual System
39
40	Use `${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/design.template.md`.
41
42	The document covers:
43
44	1. Design Tokens
45
46	Commit to concrete values. Placeholders are not acceptable for tokens.
47
48	- Color palette: primary, secondary, semantic (success / warning / error / info),
49	neutral scale. All color pairs used for text must be WCAG 2.1 AA verified.
50	- Typography: font families, size scale (mobile → desktop), weight, line-height.
51	Minimum 16px body on mobile (prevents iOS zoom). Base unit: 8px.
52	- Spacing scale (8px grid), border-radius set, shadow/elevation set.
53	- Breakpoints: 320px (mobile), 768px (tablet), 1024px (desktop), 1440px (desktop XL).
54
55	2. Component Specs
56
57	For each component: visual defaults, all interaction states (default / hover / focus /
58	active / disabled / loading / error / success), responsive behavior, and accessibility
59	annotations (ARIA roles, aria-label placement, focus-trap rules, min touch target
60	44×44px on mobile).
61
62	Core components to specify: buttons (primary / secondary / destructive), text inputs,
63	select / checkbox / radio, cards, modals, navigation (desktop + mobile hamburger),
64	loading/skeleton states, error banners.
65
66	3. WCAG 2.1 AA Contract
67
68	Enumerate the concrete accessibility requirements the visual system guarantees:
69
70	- Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large text ≥ 18px or bold ≥ 14px).
71	- UI component / graphic contrast ≥ 3:1.
72	- Visible focus indicator (2px solid outline minimum).
73	- All functionality reachable via keyboard.
74	- No horizontal scroll at 320px viewport width.
75	- Touch targets ≥ 44×44px with ≥ 8px spacing.
76
77	Run the checklist to produce the contract summary:
78
79	```bash
80	bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/wcag-checklist.sh"
81	```
82
83	Check specific color pairs with:
84
85	```bash
86	python "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/contrast-check.py" #foreground #background
87	```
88
89	Verify responsive breakpoint rules:
90
91	```bash
92	bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/responsive-breakpoints.sh"
93	```
94
95	## EXPERIENCE.md — User Experience Plan
96
97	Use `${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/experience.template.md`.
98
99	The document covers:
100
101	1. User Journeys
102
103	One section per major journey (onboarding, core workflow, settings, error recovery, etc.).
104	Each journey: goal, persona, entry points, happy-path flow diagram (ASCII or bullet
105	steps), estimated time, and drop-off risk notes.
106
107	2. Screen / State Inventory
108
109	For every screen or major view: purpose, layout wireframe (ASCII encouraged),
110	component hierarchy, and all named states:
111
112	- Default — normal first-

People who liked this also viewed

6 picks

Type

bmad-ux

26installs73forks

View on GitHub

How to install bmad-ux?

aj-geddes/claude-code-bmad-skills/bmad-ux

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-ux

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# BMAD UX — Visual System & Experience Planning
2
3	Produces the two-document UX contract that downstream story authors and the external
4	dev tool rely on. This is a planning skill. It produces specifications, not code.
5
6	## What it produces
7
8	Under `bmad-output/` (or the folder in `config.yaml`):
9
10	```
11	bmad-output/
12	├── DESIGN.md # Visual system: tokens, components, accessibility contract
13	└── EXPERIENCE.md # Journeys, flows, states, error/empty/loading specs
14	```
15
16	Both documents are locked planning artifacts. The external dev tool may read them
17	but must not edit them. All design decisions should be recorded in `decision-log.md`.
18
19	## Three intents
20
21	- Create — generate both documents from scratch (most common).
22	- Update — revise specific sections when requirements change; append a dated entry
23	to `decision-log.md` explaining what changed and why.
24	- Validate — audit existing documents for completeness and WCAG 2.1 AA gaps. Run
25	the WCAG checklist; report findings but do not alter the project's code.
26
27	## Pre-flight reads
28
29	Before drafting, read (in order):
30
31	1. `bmad-output/config.yaml` — project name, track, output folder.
32	2. `bmad-output/project-context.md` — user personas, platform targets, constraints.
33	3. `bmad-output/prd.md` (if present) — feature list, user stories, acceptance criteria.
34	4. `bmad-output/architecture.md` (if present) — component boundaries, API contracts.
35
36	If any of these are missing, ask the user for the key inputs before proceeding.
37
38	## DESIGN.md — Visual System
39
40	Use `${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/design.template.md`.
41
42	The document covers:
43
44	1. Design Tokens
45
46	Commit to concrete values. Placeholders are not acceptable for tokens.
47
48	- Color palette: primary, secondary, semantic (success / warning / error / info),
49	neutral scale. All color pairs used for text must be WCAG 2.1 AA verified.
50	- Typography: font families, size scale (mobile → desktop), weight, line-height.
51	Minimum 16px body on mobile (prevents iOS zoom). Base unit: 8px.
52	- Spacing scale (8px grid), border-radius set, shadow/elevation set.
53	- Breakpoints: 320px (mobile), 768px (tablet), 1024px (desktop), 1440px (desktop XL).
54
55	2. Component Specs
56
57	For each component: visual defaults, all interaction states (default / hover / focus /
58	active / disabled / loading / error / success), responsive behavior, and accessibility
59	annotations (ARIA roles, aria-label placement, focus-trap rules, min touch target
60	44×44px on mobile).
61
62	Core components to specify: buttons (primary / secondary / destructive), text inputs,
63	select / checkbox / radio, cards, modals, navigation (desktop + mobile hamburger),
64	loading/skeleton states, error banners.
65
66	3. WCAG 2.1 AA Contract
67
68	Enumerate the concrete accessibility requirements the visual system guarantees:
69
70	- Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large text ≥ 18px or bold ≥ 14px).
71	- UI component / graphic contrast ≥ 3:1.
72	- Visible focus indicator (2px solid outline minimum).
73	- All functionality reachable via keyboard.
74	- No horizontal scroll at 320px viewport width.
75	- Touch targets ≥ 44×44px with ≥ 8px spacing.
76
77	Run the checklist to produce the contract summary:
78
79	```bash
80	bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/wcag-checklist.sh"
81	```
82
83	Check specific color pairs with:
84
85	```bash
86	python "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/contrast-check.py" #foreground #background
87	```
88
89	Verify responsive breakpoint rules:
90
91	```bash
92	bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/responsive-breakpoints.sh"
93	```
94
95	## EXPERIENCE.md — User Experience Plan
96
97	Use `${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/experience.template.md`.
98
99	The document covers:
100
101	1. User Journeys
102
103	One section per major journey (onboarding, core workflow, settings, error recovery, etc.).
104	Each journey: goal, persona, entry points, happy-path flow diagram (ASCII or bullet
105	steps), estimated time, and drop-off risk notes.
106
107	2. Screen / State Inventory
108
109	For every screen or major view: purpose, layout wireframe (ASCII encouraged),
110	component hierarchy, and all named states:
111
112	- Default — normal first-

People who liked this also viewed

6 picks

Type