bmad-ux

BMAD UX — 视觉系统与体验规划

生成下游故事作者和外部开发工具依赖的双文档 UX 契约。这是一项规划技能，产出的是规范，而不是代码。

产出内容

在 bmad-output/（或 config.yaml 中指定的文件夹）下：

bmad-output/
├── DESIGN.md         # Visual system: tokens, components, accessibility contract
└── EXPERIENCE.md     # Journeys, flows, states, error/empty/loading specs

这两份文档都是锁定的规划成果。外部开发工具可以读取，但不得编辑。所有设计决策都应记录在 decision-log.md 中。

三种意图

• 创建 — 从头生成两份文档（最常见）。
• 更新 — 需求变更时修订指定章节；在 decision-log.md 中追加带日期的条目，说明变更内容及原因。
• 验证 — 审核现有文档的完整性和 WCAG 2.1 AA 差距。运行 WCAG 检查清单；报告发现的问题，但不要修改项目代码。

预先阅读

起草前，按顺序阅读：

1. bmad-output/config.yaml — 项目名称、开发轨道、输出文件夹。
2. bmad-output/project-context.md — 用户角色、目标平台、约束。
3. bmad-output/prd.md（如果存在）— 功能列表、用户故事、验收标准。
4. bmad-output/architecture.md（如果存在）— 组件边界、API 契约。

如果缺少其中任何文件，请先向用户询问继续所需的关键信息。

DESIGN.md — 视觉系统

使用 ${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/design.template.md。

文档涵盖：

1. 设计令牌

确定具体值。令牌不得使用占位符。

• 色彩调色板：主色、次色、语义色（成功 / 警告 / 错误 / 信息）和中性色阶。所有用于文本的颜色组合都必须通过 WCAG 2.1 AA 验证。
• 字体排印：字体系列、字号阶梯（移动端 → 桌面端）、字重、行高。移动端正文最小字号为 16px（可防止 iOS 缩放）。基准单位：8px。
• 间距阶梯（8px 网格）、圆角规格、阴影 / 高程规格。
• 断点：320px（移动端）、768px（平板）、1024px（桌面端）、1440px（桌面端 XL）。

2. 组件规格

对每个组件，说明视觉默认样式、所有交互状态（默认 / 悬停 / 焦点 / 激活 / 禁用 / 加载中 / 错误 / 成功）、响应式行为和无障碍标注（ARIA 角色、aria-label 的放置位置、焦点陷阱规则、移动端最小触控目标为 44×44px）。

需要指定的核心组件：按钮（主按钮 / 次按钮 / 危险操作）、文本输入框、选择框 / 复选框 / 单选框、卡片、模态框、导航（桌面端 + 移动端汉堡菜单）、加载 / 骨架屏状态、错误横幅。

3. WCAG 2.1 AA 契约

列出视觉系统保证的具体无障碍要求：

• 文本对比度 ≥ 4.5:1（普通文本），≥ 3:1（大号文本 ≥ 18px 或粗体文本 ≥ 14px）。
• UI 组件 / 图形对比度 ≥ 3:1。
• 焦点指示器清晰可见（实线描边最小为 2px）。
• 所有功能都可通过键盘访问。
• 视口宽度为 320px 时，不得出现水平滚动。
• 触控目标 ≥ 44×44px，间距 ≥ 8px。

运行检查清单，生成契约摘要：

bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/wcag-checklist.sh"

使用以下命令检查特定颜色组合：

python "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/contrast-check.py" #foreground #background

验证响应式断点规则：

bash "${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/scripts/responsive-breakpoints.sh"

EXPERIENCE.md — 用户体验计划

使用 ${CLAUDE_PLUGIN_ROOT}/skills/bmad-ux/templates/experience.template.md。

本文档涵盖：

1. 用户旅程

每个主要旅程（入门、核心工作流、设置、错误恢复等）单独成节。 每个旅程包括：目标、用户角色、入口点、顺畅路径流程图（ASCII 图或项目符号 步骤）、预计耗时，以及流失风险说明。

2. 屏幕／状态清单

对于每个屏幕或主要视图，说明其用途、布局线框图（推荐使用 ASCII）、 组件层级，以及所有命名状态：

• Default — 正常的首次加载状态。
• Loading — 骨架屏或加载指示器；通过 aria-live="polite" 播报。
• Empty — 无数据状态，并提供实用的行动号召。
• Error — 说明出错原因和恢复操作。
• Success — 确认反馈。
• Disabled — 说明访问受限的原因。

3. 决策点与替代路径

为每个旅程绘制分支节点（验证失败、需要身份验证、网络错误、超时等）。每个 分支包括：触发条件、显示内容和恢复路径。

4. 交互与动画说明

说明过渡效果的时长和缓动方式。遵循 prefers-reduced-motion。注明哪些动画 是装饰性的，哪些具有实际意义。

子 Agent 策略

对于主要旅程超过 4 个的项目，拆分任务并行交给子 Agent：

Agent	任务	输出文件
Agent 1	设计令牌 + 颜色／对比度组合 → DESIGN.md §1	bmad-output/ux-tokens-draft.md
Agent 2	核心组件规范 → DESIGN.md §2	bmad-output/ux-components-draft.md
Agent 3	WCAG 规范 + 无障碍注释	bmad-output/ux-a11y-draft.md
Agent N	一个主要用户旅程 + 屏幕状态	bmad-output/ux-journey-N-draft.md

启动 Agent 前，将共享上下文（用户角色、品牌意图、断点）写入 bmad-output/ux-shared-context.md。主上下文负责将草稿整合为两份最终文档，并 对所有屏幕执行 WCAG 检查清单。

子 Agent 提示词示例：

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.

限制

• 此技能用于生成规划文档。它不会编写应用代码、CSS、组件实现或测试套件。
• 如果项目没有 UI（仅 API、仅命令行或后台服务），则完全跳过此技能，并在 decision-log.md 中记录该决定。
• 在“实现”之前停止。两份文档获批后，交接给故事创建技能。

有关设计模式库、完整断点参考和组件状态矩阵，请参阅 REFERENCE.md。

---

BMAD Planning & Orchestrator 插件的一部分——由 BMAD Code Organization 为 BMAD Method 提供的 Claude Code 承载环境（https://github.com/bmad-code-org/BMAD-METHOD）。体现了 bmad-ux-designer 的理念。所有方法论贡献均归 BMAD Code Organization 所有。