ui-ux-design

name	ui-ux-design
description	Reviews and implements UI/UX following project design systems. Triggers: design review, UI improvement, styling, accessibility, dark mode, responsive, layout, component design. Covers: visual consistency, design system compliance, accessibility, responsive design, and dark mode. Takes optional argument: /ui-ux-design <target-file or instruction>

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

出力先

• レビューモード: 会話内でレポートを提示（output/reports/review/ にも出力可能）
• 実装モード: src/ 配下のコンポーネントを直接変更

他スキルとの連携

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

モード

モード自動判定

以下の基準でレビューモードと実装モードを自動判定する:

条件	選択モード
タスク内容に「レビュー」「確認」「チェック」「監査」「評価」を含む	レビューモード
チーム内でレビュアーとして割り当てられている	レビューモード
タスクファイルに 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通過を確認

レビュー観点

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	✅

重要度定義

レベル	判定基準	例
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修正後）** / **要修正**

実装ガイドライン

カラーの扱い

// 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 によるフック迂回