ui-ux-design

name	ui-ux-design
version	1.0.0
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: 情報収集（サブエージェントで並行実行）

以下のスキャンを並行して実施する:

スキャン対象	手法	検出内容
ハードコード色値	src/ 配下の .tsx .ts .css を Grep で #[0-9a-fA-F]{3,8} rgb\( rgba\( hsl\( パターン検索	DS トークン未使用箇所
インラインスタイル	Grep で style={{ style=\{ パターン検索	トークン外のマジックナンバー
Tailwind 任意値	Grep で \-\[.*\] パターン検索（text-[#...] p-[13px] 等）	DS スケール外の値
コンポーネント使用パターン	各フィーチャーの Page/Container コンポーネントで使用している共通コンポーネント（Button, Card, Dialog, Sheet, Input 等）を集計	同種UIの実装バラつき
レスポンシブパターン	Grep で useMediaQuery md: lg: sm: のブレークポイント使用を集計	ブレークポイント不統一
a11y パターン	Grep で role= aria- tabIndex を集計、<div onClick で button 代替を検出	a11y 不足箇所
アイコン使用	Grep で lucide-react からの import を集計	アイコン使用の一貫性
空状態・ローディング	各ページで isLoading isEmpty empty パターンの有無を確認	UX状態の抜け漏れ

Phase 2: パターン分析

収集データを基に以下を分析する:

1. カラートークン使用率: src/index.css で定義されたトークンの使用率 vs ハードコード値の残存数
2. コンポーネント一貫性マトリクス: 各フィーチャーが共通UIコンポーネントをどう使っているかの比較表
   • 例: Button の variant/size 使い方がフィーチャー間で統一されているか
   • 例: Dialog/Sheet の使い分け基準が一貫しているか
3. スペーシング統計: 使用されているスペーシング値の分布（Tailwind スケール内 vs 任意値）
4. レスポンシブ戦略の統一性: モバイル/PC の切り替え方式がフィーチャー間で一致しているか
5. インタラクションパターンの統一性: ローディング・エラー・空状態の表現方法が揃っているか

Phase 3: 不整合の分類と優先度付け

検出した不整合を以下の基準で分類:

分類	基準	優先度
トークン違反	DS で定義されたトークンを使用していない	HIGH
パターン不一致	同種の UI 要素がフィーチャー間で異なる実装	MEDIUM
欠落	他フィーチャーにはある UX 状態（空状態等）が欠けている	MEDIUM
a11y 不備	セマンティック HTML 未使用、ARIA 不足	HIGH
微差	動作に影響しないが統一すべき些細な差異	LOW

Phase 4: レポート出力 or 自動修正

• --fix なし: 監査レポートを output/reports/review/DESIGN_AUDIT_{YYYYMMDD}.md に出力
• --fix あり: HIGH → MEDIUM の順に自動修正を実施し、修正サマリーを出力
  • 自動修正の対象: トークン違反（ハードコード色値→セマンティックカラー）、Tailwind 任意値→スケール値
  • 自動修正の対象外: パターン不一致（設計判断が必要）、欠落（新規実装が必要）
  • 修正後にビルド・lint・テストを実行して破壊的変更がないことを確認

監査スコープの制御

デフォルトでは src/ 全体をスキャンするが、スコープを絞ることも可能:

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

自動修正のルール

自動修正は以下の安全基準を満たす変更のみ行う:

1. 機械的に一意に変換可能: #ffffff → bg-background のような 1:1 マッピング
2. 視覚的に等価: 修正前後で見た目が変わらない
3. テストが通る: 修正後にテストが全件パスする
4. 判断が必要な変更はスキップ: 複数候補がある場合やコンテキスト依存の場合はレポートに記載して人間に委ねる

レビュー観点

1. デザインシステム準拠

• プロジェクトで指定されたデザインシステムのガイドラインに沿っているか
• カラーパレット・タイポグラフィ・スペーシングが一貫しているか
• コンポーネントの使い方がデザインシステムの推奨パターンに合っているか

2. カラー・テーマ

• セマンティックカラー（CSS変数・デザイントークン）を使用しているか
• ハードコードされた色値がないか
• ダークモードで十分なコントラスト比（WCAG AA: 4.5:1以上）が確保されているか
• フォーカス状態・ホバー状態のスタイルが定義されているか

3. タイポグラフィ

• フォントサイズ・ウェイトがデザインシステムのスケールに沿っているか
• 見出し階層（h1〜h6）が論理的か
• 行間・文字間が読みやすいか

4. レイアウト・スペーシング

• デザインシステムのスペーシングスケールを使用しているか
• グリッド・フレックスの使い方が適切か
• 余白が視覚的階層を適切に表現しているか

5. アクセシビリティ（a11y）

• セマンティックHTMLを使用しているか（button, nav, main 等）
• ARIA属性が適切か（過剰でも不足でもなく）
• キーボードナビゲーションが可能か
• スクリーンリーダーで意味が通じるか
• フォーカスインジケータが視認できるか

6. レスポンシブデザイン

• ブレークポイントが適切に設定されているか
• モバイル〜デスクトップで崩れないか
• タッチターゲットが適切なサイズか（44x44px以上推奨）

7. インタラクション

• ローディング状態が適切にフィードバックされているか
• エラー状態が視覚的に明確か
• 遷移・アニメーションが自然か（過剰でないか）
• 空状態（Empty State）のデザインがあるか

出力契約

レビューモード出力仕様

セクション	必須	制約
概要	✅	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改善提案、インタラクション強化	空状態デザイン、ローディング表示

総合判定の列挙値

判定	条件
承認	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