ui-ux-design

name	ui-ux-design
description	This skill should be used when the user asks to "review UI design", "improve styling", "add dark mode", "fix accessibility", "make responsive", or mentions "デザインレビュー", "UI改善", "デザイン整合性". Covers visual consistency, design system compliance, accessibility, responsive design, dark mode, and system-wide design consistency audit. Takes optional argument: /ui-ux-design <target-file or instruction>
argument-hint	<対象ファイル or 指示>
allowed-tools	Read, Glob, Grep, Edit, Write, Bash(git *), WebSearch, WebFetch, Agent, mcp__context7__resolve-library-id, mcp__context7__query-docs
context	main

UI/UX Design

プロジェクトのデザインシステムに準拠したUI/UX設計・レビュー・実装を行うスキル。 CLAUDE.md の方針を厳守すること。プロジェクト固有のデザイン規約は docs/development-patterns.md の「デザインシステム」セクションを参照。

前提条件

参照ファイル	用途	スタブ時のフォールバック
docs/development-patterns.md	デザインシステム・UI規約	project-config.md §7 を直接参照

基本姿勢

• プロジェクトで定義されたデザインシステムに忠実に従う
• デザインシステムのURLが docs/development-patterns.md に記載されている場合、そのガイドラインを参照・準拠する
• 仕様が曖昧な場合はモックアップや選択肢を示して確認する（推測で進めない）
• 過剰な装飾・アニメーションを避け、使いやすさを最優先する
• アクセシビリティ（a11y）を常に考慮する

使い方

/ui-ux-design <対象ファイル or UI指示>

引数は省略可能。省略した場合はユーザーに対話的に確認する。 ファイルパスを指定した場合はその内容を読み取り、レビュー/実装対象を把握する。

例

/ui-ux-design ダッシュボードのレイアウトを改善する
/ui-ux-design src/features/dashboard/pages/DashboardPage.tsx
/ui-ux-design output/tasks/TASK_ui_redesign.md
/ui-ux-design システム全体のデザイン整合性を監査する
/ui-ux-design --audit                    # システム整合性監査モード明示起動
/ui-ux-design --audit --fix              # 監査 + 自動修正

出力先

• レビューモード: 会話内でレポートを提示（output/reports/review/ にも出力可能）
• 実装モード: src/ 配下のコンポーネントを直接変更
• システム整合性監査モード: output/reports/review/DESIGN_AUDIT_{YYYYMMDD}.md に出力

他スキルとの連携

前工程	本スキル	後工程
/plan /architecture	/ui-ux-design	/code-review /e2e-testing

モード

モード自動判定

以下の基準でモードを自動判定する（上から優先）:

条件	選択モード
引数に --audit を含む	システム整合性監査モード
タスク内容に「整合性」「統一」「一貫性」「横断」「全体」「system-wide」「audit」を含む	システム整合性監査モード
タスク内容に「レビュー」「確認」「チェック」「監査」「評価」を含む	レビューモード
チーム内でレビュアーとして割り当てられている	レビューモード
タスクファイルに role: review が明記されている	レビューモード
タスク内容に「実装」「作成」「修正」「追加」「改善」「変更」を含む	実装モード
チーム内で開発者として割り当てられている	実装モード
タスクファイルに role: implement が明記されている	実装モード
上記いずれにも該当しない場合	ユーザーに確認する

デザインレビューモード（読み取り専用）

チームのレビュアーとして使用する場合。ソースコードは変更しない。

1. 視覚的一貫性チェック — デザインシステムとの乖離を指摘
2. アクセシビリティ監査 — アクセシビリティ基準（project-config.md セクション7）準拠の確認
3. レスポンシブ確認 — ブレークポイント別の表示確認
4. ダークモード確認 — ライト/ダーク両方での視認性
5. レポート出力 — 下記フォーマットで報告

実装モード

UIの実装・修正を行う場合。

1. デザインシステム確認 — docs/development-patterns.md のデザインシステムURLを参照
2. コンポーネント選定 — プロジェクトの既存UIライブラリから適切なものを選択
3. 実装 — セマンティックカラー・トークンを使用、ハードコード禁止
4. ダークモード対応 — ライト/ダーク両方で動作確認
5. 検証 — ビルド・lint通過を確認

システム整合性監査モード

システム全体を横断的にスキャンし、フィーチャー間・コンポーネント間のデザイン不整合を検出・補正する。 --fix フラグ付きの場合は自動修正も行う(--fix なしの場合はレポートのみ)。

詳細な実行手順(Phase 1〜4のスキャン対象・分析観点・分類基準・自動修正ルール)は references/system-audit-workflow.md を参照。

/ui-ux-design --audit                          # src/ 全体
/ui-ux-design --audit src/features/touring/    # 特定フィーチャーのみ
/ui-ux-design --audit --fix                    # 全体 + 自動修正

レビュー観点

デザインレビューモードで確認する7カテゴリ(デザインシステム準拠 / カラー・テーマ / タイポグラフィ / レイアウト・スペーシング / アクセシビリティ / レスポンシブデザイン / インタラクション)の詳細は references/review-criteria.md を参照。

出力契約

レビューモード出力仕様

セクション	必須	制約
概要	✅	4項目（対象ファイル数, DS準拠, ダークモード, a11y）すべて必須
指摘事項	✅	MUST→SHOULD→CONSIDER の順。0件でも見出しは残す
良い点	✅	最低1件
総合判定	✅	列挙値から1つ選択

実装モード出力仕様

フィールド	型	必須	制約
変更ファイル一覧	箇条書き	✅	ファイルパスと変更概要
ダークモード確認結果	OK / NG	✅	NG時は具体的な問題を付記
ビルド結果	pass / fail	✅

システム整合性監査モード出力仕様

セクション	必須	制約
監査概要	✅	スキャン範囲・ファイル数・フィーチャー数
トークン使用統計	✅	セマンティックカラー使用率・ハードコード残存数
フィーチャー間整合性マトリクス	✅	コンポーネント使用パターン比較表
不整合一覧	✅	HIGH→MEDIUM→LOW の順。0件でも見出しは残す
修正サマリー（--fix 時のみ）	条件付き	修正ファイル数・修正内容・テスト結果
推奨アクション	✅	人間の判断が必要な項目の一覧

重要度定義

レベル	判定基準	例
MUST	DS違反、a11y WCAG AA不適合、ダークモード非対応	ハードコード色値、フォーカス不可、コントラスト比不足
SHOULD	DS推奨パターンとの乖離、レスポンシブ改善	スペーシング不統一、タッチターゲット不足
CONSIDER	UX改善提案、インタラクション強化	空状態デザイン、ローディング表示

PASS条件: 全 MUST 指摘が「対応済み」または「対応不可の理由明記」/ 実装モードはダークモード確認結果が OK かつビルド pass / 監査モードはトークン使用率が前回から悪化していない。

総合判定の列挙値

判定	条件
承認	MUST指摘が0件
条件付き承認（MUST修正後）	MUST指摘が1件以上かつ修正可能
要修正	デザインシステム準拠に大幅な見直しが必要

指摘記述フォーマット

- [ ] `ファイルパス:行番号` 指摘内容。**DS根拠**: 該当ガイドライン。**修正案**: 具体的な修正。

語彙制約

用語	定義
DS	デザインシステム（docs/development-patterns.md で定義）
セマンティックカラー	CSS変数ベースの色定義（--foreground, --background 等）
トークン	デザインシステムで定義された値（色、スペーシング、タイポグラフィ）
a11y	アクセシビリティ（WCAG 2.1 AA準拠を基準）
コントラスト比	WCAG定義の輝度比。テキスト: 4.5:1以上、大テキスト: 3:1以上

レポートフォーマット（レビューモード）

# UI/UXレビュー: [対象の概要]

## 概要
- 対象ファイル数: X
- デザインシステム準拠: OK / NG
- ダークモード対応: OK / NG
- アクセシビリティ: OK / NG

## 指摘事項

### MUST（必須修正）
- [ ] `ファイル:行` 指摘内容。**DS根拠**: ガイドライン。**修正案**: 修正方法。

### SHOULD（推奨修正）
- [ ] `ファイル:行` 指摘内容。**理由**: 根拠。**修正案**: 修正方法。

### CONSIDER（検討）
- [ ] `ファイル:行` 指摘内容。**改善方向**: 提案。

## 良い点
- [デザイン面で優れている点]

## 総合判定
- **承認** / **条件付き承認（MUST修正後）** / **要修正**

レポートフォーマット（システム整合性監査モード）

# デザイン整合性監査レポート: {YYYY-MM-DD}

## 監査概要
- スキャン範囲: {src/ 全体 or 特定ディレクトリ}
- スキャン対象ファイル数: X
- フィーチャー数: Y
- 実行日時: {ISO 8601}

## トークン使用統計

### カラートークン
| 指標 | 値 |
| ---- | -- |
| セマンティックカラー使用箇所 | X |
| ハードコード色値の残存箇所 | Y |
| トークン使用率 | Z% |

### ハードコード色値の詳細
| ファイル | 行 | 値 | 推奨トークン |
| -------- | -- | -- | ------------ |
| `path/to/file.tsx` | 42 | `#ffffff` | `bg-background` |

### スペーシング
| 指標 | 値 |
| ---- | -- |
| Tailwind スケール内 | X箇所 |
| 任意値（`-[Npx]`） | Y箇所 |

## フィーチャー間整合性マトリクス

### コンポーネント使用パターン
| コンポーネント | auth | map-editor | routes | touring | stamps | bikes | settings | admin |
| -------------- | ---- | ---------- | ------ | ------- | ------ | ----- | -------- | ----- |
| Button         | ✅   | ✅         | ✅     | ✅      | ✅     | ✅    | ✅       | ✅    |
| Card           | —    | —          | ✅     | ✅      | ✅     | ✅    | —        | —     |
| Dialog         | —    | ✅         | —      | ✅      | —      | ✅    | ✅       | ✅    |
| Sheet          | —    | ✅         | —      | ✅      | —      | —     | —        | —     |

### レスポンシブ戦略
| フィーチャー | SP/PC切替方式 | ブレークポイント | 備考 |
| ------------ | ------------- | ---------------- | ---- |
| map-editor   | useMediaQuery | 768px            | — |
| touring      | useMediaQuery | 768px            | — |

### UX状態の実装状況
| フィーチャー | ローディング | エラー | 空状態 |
| ------------ | ------------ | ------ | ------ |
| map-editor   | ✅           | ✅     | ✅     |
| touring      | ✅           | ✅     | ✅     |

## 不整合一覧

### HIGH（トークン違反・a11y不備）
- [ ] `ファイル:行` 不整合の内容。**検出パターン**: 検出方法。**修正案**: 具体的な修正。

### MEDIUM（パターン不一致・欠落）
- [ ] `ファイル:行` 不整合の内容。**比較対象**: 他フィーチャーの実装。**修正案**: 統一方法。

### LOW（微差）
- [ ] `ファイル:行` 不整合の内容。: 統一案。


 修正ファイル数: X
 修正内容:
 [修正1の概要]
 [修正2の概要]
 ビルド結果: pass / fail
 テスト結果: X passed, Y failed


人間の判断が必要な項目:
 [設計判断が必要な不整合の説明と選択肢]
 [新規実装が必要な欠落の説明]


| 観点 | スコア | 評価 |
| ---- | ------ | ---- |
| トークン準拠 | X/100 | — |
| フィーチャー間一貫性 | X/100 | — |
| a11y 充足度 | X/100 | — |
| UX 状態網羅度 | X/100 | — |
|  |  | — |

実装ガイドライン

カラーの扱い

// OK: セマンティックカラー（デザインシステムのトークン）
className="text-foreground bg-background border-border"
className="text-primary bg-primary/10"

// OK: ダークモード対応のユーティリティ
className="bg-gray-100 dark:bg-gray-800"

// NG: ハードコードされた色値
style={{ color: '#333333' }}
className="text-[#333333]"

スペーシング

// OK: デザインシステムのスペーシングスケール
className="p-4 gap-3 space-y-2"

// NG: マジックナンバー
style={{ padding: '13px', gap: '7px' }}

コンポーネント選定

プロジェクトの既存UIライブラリを最大限活用する。 新規コンポーネント追加前に、既存のもので代替できないか確認する。

デザインシステムの参照方法

このスキルは docs/development-patterns.md の「デザインシステム」セクションを参照する。 プロジェクトごとに以下の情報が記載される:

• デザインシステムの公式URL
• UIコンポーネントライブラリ
• カラーパレット・トークンの定義場所
• アイコンライブラリ

新しいプロジェクトに適用する際は、docs/development-patterns.md にデザインシステムのURLを記載すること。

禁止事項

• デザインシステムに定義されていないカスタムカラーの独自追加
• ハードコードされた色値（HEX/RGB直指定）
• アクセシビリティを無視したデザイン
• ダークモード未対応のUI変更
• 仕様書にないUI要素の追加
• --no-verify によるフック迂回

関連参照(必要に応じて Claude が load)

@.claude/quality-gates.md @.claude/pitfalls.md