bmad-ux

BMAD UX — ビジュアルシステムとエクスペリエンスの計画

後続のストーリー作成者と外部の開発ツールが利用する、2つのドキュメントから成る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 に記録してください。

3つのインテント

• 作成 — 2つのドキュメントを一から作成します（最も一般的）。
• 更新 — 要件の変更に応じて特定のセクションを修正し、変更内容と理由を説明する日付入りのエントリを 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 を推奨）、コンポーネント階層、および名前付きの状態をすべて記載します。

• デフォルト — 初回読み込み時の通常の状態。
• 読み込み中 — スケルトンまたはスピナーを表示し、aria-live="polite" で通知します。
• 空 — データがない状態と、役立つ行動喚起を表示します。
• エラー — 問題の内容と復旧アクションを表示します。
• 成功 — 確認フィードバックを表示します。
• 無効 — アクセスが制限されている理由を示します。

3. 分岐点と代替経路

各ジャーニーの分岐点（検証失敗、認証が必要な場合、ネットワークエラー、タイムアウトなど）をマッピングします。各分岐について、発生条件、表示内容、復旧経路を記載します。

4. インタラクションとアニメーションに関する注記

トランジションのタイミングとイージングを記載します。prefers-reduced-motion に従います。どのアニメーションが装飾的なものか、意味を伝えるものかを記します。

サブエージェント戦略

主要なジャーニーが 4 つを超えるプロジェクトでは、サブエージェントを並行して稼働させます。

エージェント	タスク	出力ファイル
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	主要なユーザージャーニーを 1 つ担当し、画面の状態を定義	bmad-output/ux-journey-N-draft.md

エージェントを起動する前に、共有コンテキスト（ペルソナ、ブランドの意図、ブレークポイント）を bmad-output/ux-shared-context.md に記述します。メインコンテキストでドラフトを 2 つの最終ドキュメントにまとめ、すべての画面について WCAG チェックリストを実施します。

サブエージェントへのプロンプト例：

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 のみ、CLI のみ、バックグラウンドサービスなど）は、このスキルを完全にスキップし、その判断を decision-log.md に記録します。
• 「実装」の前に停止します。2 つのドキュメントの承認後、ストーリー作成スキルに引き継ぎます。

デザインパターンライブラリ、ブレークポイントの完全なリファレンス、コンポーネント状態マトリクスについては、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 に帰属します。