uiux

/uiux — UI/UX 全体再設計

体系的かつ再帰的に再設計を進めるループです。優先度の高い画面から低い画面まで順に確認し、コードの記述ではなく、実際にレンダリングされた UI の見た目を基準に、各画面がピクセル単位で完璧になるまで反復します。

開始前に、~/.claude/skills/ui-design-principles/SKILL.md を読みます。色、タイポグラフィ、余白、階層に関するルールはすべてここに記載されており、全工程に自動的に適用されます。

プロジェクトのルートに DESIGN-BRIEF.md がある場合は、ファイルに手を加える前に読みます。ここでビジュアルの方向性（パレット、タイポグラフィ、コンポーネントのスタイル、アニメーションのレベル、代表的な画面）が定められています。ブリーフに記載されたデザイン上の決定はデフォルトより優先されます。すでに決定済みの内容を再検討しないでください。

---

フェーズ 0 — 環境のセットアップ

0a. 開発サーバーの確認／起動

curl -s --max-time 2 -o /dev/null -w "%{http_code}" http://localhost:3000

結果が 200 でない場合は、開発コマンド（pnpm dev、npm run dev など）を見つけてバックグラウンドで起動します。その後、起動するまで待ちます。

until curl -s --max-time 2 http://localhost:3000 > /dev/null 2>&1; do sleep 1; done
echo "Server ready"

0b. Playwright の確認

node -e "require('@playwright/test')" 2>/dev/null && echo "ready" || echo "missing"

見つからない場合：

pnpm add -D @playwright/test && npx playwright install chromium

インストールできない場合は、修正のたびにスクリーンショットを共有するようユーザーに依頼します。実際の視覚情報なしに、見た目について断定しないでください。

0c. スクリーンショットスクリプトの作成

プロジェクトのルートにこのファイルを書き込みます（node_modules を解決できるようにするためです）。このファイルはセッション全体を通して保持し、フェーズ 4 で削除します。

_uiux_screenshot.mjs（プロジェクトのルートに書き込み）：

import { chromium } from '@playwright/test';

const get = (flag) => {
  const i = process.argv.indexOf(flag);
  return i !== -1 ? process.argv[i + 1] : null;
};

const url    = get('--url');
const output = get('--output');
const width  = parseInt(get('--width')  ?? '1280');
const height = parseInt(get('--height') ?? '900');
const auth   = get('--auth');

if (!url || !output) { console.error('--url and --output required'); process.exit(1); }

const browser = await chromium.launch();
const context = await browser.newContext({
  viewport: { width, height },
  ...(auth ? { storageState: auth } : {}),
});
const page = await context.newPage();
await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
await page.screenshot({ path: output, fullPage: true });
await browser.close();
console.log('saved:', output);

使用方法 — デスクトップ：

node _uiux_screenshot.mjs --url http://localhost:3000<ROUTE> --output /tmp/uiux-<name>-desktop.png

使用方法 — モバイル（375px）：

node _uiux_screenshot.mjs --url http://localhost:3000<ROUTE> --output /tmp/uiux-<name>-mobile.png --width 375 --height 812

使用方法 — 認証済み：

node _uiux_screenshot.mjs --url http://localhost:3000<ROUTE> --output /tmp/uiux-<name>-desktop.png --auth /tmp/uiux-auth-state.json

スクリーンショットを撮るたびに、画像ファイルを実際に確認するため、Read ツールを使います。コードではなく、画像を正とします。

0d. 認証で保護された画面への対応

認証ミドルウェアやプロバイダー（middleware.ts、next-auth、clerk、supabase、lucia、ルートガード）を確認します。

認証がある場合は、プロジェクトのルートに次のファイルを書き込み、テスト用認証情報（TEST_EMAIL、TEST_PASSWORD）とログイン後の URL パターン（SUCCESS_URL、例：**/dashboard**）をユーザーに尋ねます。

_uiux_auth.mjs（プロジェクトのルートに書き込み）：

import { chromium } from '@playwright/test';

const { TEST_EMAIL, TEST_PASSWORD, LOGIN_URL, SUCCESS_URL } = process.env;
if (!TEST_EMAIL || !TEST_PASSWORD) {
  console.error('Set TEST_EMAIL and TEST_PASSWORD'); process.exit(1);
}

const browser = await chromium.launch();
const page    = await browser.newPage();
await page.goto(LOGIN_URL ?? 'http://localhost:3000/sign-in');
await page.fill('input[type="email"]',    TEST_EMAIL);
await page.fill('input[type="password"]', TEST_PASSWORD);
await page.click('button[type="submit"]');
await page.waitForURL(SUCCESS_URL ?? '**/dashboard**', { timeout: 15000 });
await page.context().storageState({ path: '/tmp/uiux-auth-state.json' });
await browser.close();
console.log('Auth session saved → /tmp/uiux-auth-state.json');

プロジェクトのルートから実行します：

[email protected] TEST_PASSWORD=secret LOGIN_URL=http://localhost:3000/sign-in SUCCESS_URL="**/dashboard**" node _uiux_auth.mjs

テスト用認証情報がない場合は、今すぐ公開画面のスクリーンショットを撮り、保護された画面には auth-blocked と記録して、認証情報が提供された時点で再確認します。

0e. デザイントークンの確認

トークンレイヤー（packages/tokens/、tokens.css、tailwind.config.ts、グローバルファイルの CSS カスタムプロパティ）を検索します。余白、色、フォントサイズがどこで定義されているかを記録します。全体に適用する修正はコンポーネントではなく、トークンに加えます。

---

フェーズ 1 — 画面の監査

コードベースを調べ、異なる画面をすべて列挙します。それぞれについて、次の項目を記録します。

• ルートパスとファイルパス
• 1 行で説明
• 認証で保護されているか：はい／いいえ
• スクリーンショットを撮る（保護された画面には --auth フラグを付ける）。画像を確認し、品質を評価する：崩れている／粗い／まずまず／洗練されている

画面を次の場所から見つけます。

• App Router：すべての app/**/page.tsx
• Pages Router：pages/**/*.tsx（_app、_document、api/ は除外）
• モーダル／ドロワーコンポーネント
• 空、エラー、読み込み、見つからない状態
• 認証フロー（サインイン、サインアップ、パスワードを忘れた場合、メール認証）
• オンボーディング、設定、プロフィール、請求ページ

品質評価を含む全画面の番号付きリストを提示してから、次に進みます。

---

フェーズ 2 — 優先順位の決定

各画面を採点します。

要素	ポイント
入口／第一印象	+3
収益またはコンバージョンに直結	+3
トラフィックが最も多い／最も多く見られる	+2
現在の品質が崩れている、または粗い	+2
認証でブロックされている（まだスクリーンショットを撮れない）	−1
パワーユーザー専用	−1

スコアの高い順にランキングを作成します（最高スコアが 1 位）。上位 5 件の理由を示します。フェーズ 3 を始める前に、ユーザーに確認または並べ替えを依頼します。

---

フェーズ 3 — 再帰的な再設計ループ

ランキング順に画面を進めます。画面ごとの反復は最大 3 回です。3 回実施してもチェックリストを満たさない場合は、要対応として記録して次に進みます。共通コンポーネントの修正は全体を通して追跡します（3f）。

---

3a. 修正前のスクリーンショット

デスクトップとモバイルのスクリーンショットを撮ります。**両方の画像ファイルを確認します。**実際に見える内容を 2〜3 文で説明し、ベースラインとして記録します。

3b. 分析

ページコンポーネント、レイアウトラッパー、子コンポーネント、CSS／Tailwind クラスを確認します。スクリーンショットとすべて照合してください。スクリーンショットの内容は、コードからの推測より優先します。次の各項目を確認してください。

階層 — 画面ごとに明確な MIT が 1 つありますか？視線は自然に流れますか？ 色 — 状態は S+B ルールに基づいていますか？60-30-10 は適用されていますか？WCAG AA を満たしていますか？ タイポグラフィ — フォントは最大 2 種類ですか？見出しと本文の比率は 1.75× 以上ですか？ウェイトは適切ですか？ 余白 — パディングのリズムは一貫していますか？余白は十分に快適な量の 2 倍ありますか？ シャドウと奥行き — 光源は天頂にありますか？シャドウの不透明度は輝度に合っていますか？ コントロール — 作用する対象の近くにありますか？不要なドロップダウンはありませんか？ 画像上のテキスト — オーバーレイ／ぼかし／下端フェードを使用していますか？ 配置 — 配置の基準線はありますか？アイコンや箇条書きがぶら下がっていませんか？ 空の状態 — 空白のままではなく、設計され、使い方がわかる状態になっていますか？ レスポンシブ — スクリーンショットでモバイル幅 375px の表示が崩れていませんか？ アクセシビリティ — タップ対象は 44px 以上ですか？aria ラベルはありますか？色だけに頼った表示になっていませんか？

3c. 問題リスト

重要度ごとにグループ化して番号を付けます。

• 重大 — 動作しない、読めない、アクセシビリティ上の問題
• 大 — 階層が不適切、カラ―システムに違反、余白が不適切
• 小 — 仕上げ、アニメーション、エッジケース

3d. 修正 — まずトークン、次にコンポーネント

コンポーネントに手を加える前に、次の点を確認します。この修正は 2 つ以上の画面に適用されますか？

• はい → トークン／設定ファイルを編集します。コンポーネントに値を直接ハードコードしないでください。
• いいえ → コンポーネントを直接編集します。

重大な問題から順に、すべて修正します。ルールは許可を求めず自動的に適用します。

• 暗い状態：S を上げ、B を下げ、色相を 0°／120°／240° 方向に移動
• 明るい状態：S を下げ、B を上げ、色相を 60°／180°／300° 方向に移動
• ニュートラルなサーフェス：ブランド色相をかすかに含めます（クロマ約 0.005）。純粋なグレーは使いません
• 余白：多すぎると感じるまで 2 倍にします。それが適切です
• MIT は 1 つだけ — ページタイトルだけに最大限のポップアップ効果を適用
• フォントサイズ：本文は 15px 以上、ラベルは 12px 以上
• 明るい背景でのシャドウ：不透明度 20～30％。暗い背景では 40～50％
• 選択肢が 5 個以下のドロップダウンは、セグメントコントロール、トグル、ステッパー、またはタイプアヘッドに置き換えます

3e. ホットリロードを待ってからスクリーンショットを撮る

編集後、開発サーバーの再コンパイルが完了するまで待ちます。

sleep 3

次に、デスクトップとモバイルのスクリーンショットを撮ります。両方の画像ファイルを確認してください。 before のスクリーンショットと視覚的に比較します。

コードではなく画像を見て、次の点に答えてください。

1. MIT — スクリーンショットを見たとき、最も重要な要素に真っ先に目が行きますか？
2. 流れ — 視線は適切な順序で移動しますか？
3. 余白 — 画面にゆとりがありますか？それとも窮屈ですか？
4. 一貫性 — この画面は他の画面と同じ製品のものだと感じられますか？

答えが 1 つでも「いいえ」の場合は、3b に戻ります（反復回数を増やし、最大 3 回まで）。

3f. 共通コンポーネントの追跡

複数の画面で使われるコンポーネントに修正を加える場合：

SHARED FIX: <ComponentName> — affects screens: [list routes]

その後、該当する画面に進んだら、再修正は省略します。ただし、スクリーンショットを撮り、その画面でもコンポーネントが正しく表示されることを確認してください。

3g. ピクセル単位の精度チェックリスト

すべての項目を、コードではなくスクリーンショットで確認します。

• スクリーンショットを見て、MIT がすぐにわかる
• 色の状態は S+B ルールに基づいている（不透明度の直接指定による回避策を使っていない）
• ニュートラルなサーフェスにはブランド色相がかすかに含まれ、純粋なグレーではない
• 本文は 15px 以上、ラベルは 12px 以上、見出しと本文の比率は 1.75× 以上
• 余白は 2 倍に拡張済み — すべての辺でパディングがフォントサイズ以上
• 余白のリズムが一貫している（4／8／16／24／32／48px）
• シャドウの不透明度が背景の輝度に合っている
• すべてのコントロールが作用する対象の近くにある
• タップ対象は 44px 以上 — モバイルのスクリーンショットで確認済み
• WCAG AA のコントラスト比を満たしている：本文は 4.5:1、見出しは 3:1
• 空の状態が設計されている（空白ではない）
• 不要なドロップダウンがない
• アイコンの線の太さと角の丸みが書体に合っている
• 画像上のテキストにはオーバーレイ／テキストボックス／ぼかし／下端フェードを使用している
• 画面全体で配置の基準線が一貫している
• モバイル 375px：はみ出しがなく、レイアウトが崩れていない

不合格の項目があれば、3d に戻り、反復回数を増やします。3 回目の反復後は、問題を記録して次に進みます。

フェーズ 4 — クリーンアップと進捗レポート

プロジェクトのルートディレクトリから一時スクリプトを削除します：

rm -f _uiux_screenshot.mjs _uiux_auth.mjs

各画面の後：

✓ Screen name (rank N, iteration K) — A critical + B major + C minor fixed
  Shared fixes: [list or none] | Flagged: [list or none]

すべての画面を確認した後、詳細なサマリーテーブルを作成します：

順位	画面	ルート	修正した問題	反復回数	状態
1	...	...	...	...	✓ 仕上げ済み / ⚠ 要確認 / 🔒 認証でブロック

フラグを付けた画面と認証でブロックされた画面をすべて、未解決の項目を具体的に示して最後に列挙します。

---

ルール

1. すべてのスクリーンショットを Read ツールで読み取ります。 コードだけをもとに UI を説明してはいけません。画像を優先します。
2. コンポーネントより先にトークンを確認します。 グローバルな修正は、まずトークン／設定レイヤーで行います。
3. 共通コンポーネントは一度だけ修正します。 一度修正し、影響を受ける画面を記録して、各画面のコンテキストで検証します。
4. 画面ごとの反復は最大 3 回です。 フラグを付けて次に進みます。行き詰まらないようにします。
5. デザインルールを自動的に適用します。 色、余白、タイポグラフィの変更に許可は不要です。
6. 機能を維持します。 ロジック、ルーティング、データ取得、アクセシビリティのセマンティクスは変更しません。
7. モバイルを優先します。 すべての修正は、完了前に幅 375px で問題がないことを確認します。
8. 認証でブロックされた画面。 まず現時点で撮影できるスクリーンショットを撮ります。認証情報が提供されたら再確認します。
9. 一度に一画面ずつ進めます。 次に進む前に、チェックリストとすべての反復を完了します。
10. 進捗を報告します。 どの画面を作業中か、残りがいくつかを常にユーザーに知らせます。

---

対応するプロジェクトタイプ

Next.js（App Router または Pages）、React + Vite、SvelteKit、Nuxt、Astro、プレーンな HTML/CSS に対応します。見つかったプロジェクト構造に合わせてファイルの調査方法を調整してください。

デザインに関するナレッジベースのクイックリファレンス全体については、PRINCIPLES.md を参照してください。