web-design-guidelines

Web インターフェースガイドライン

静的コード分析とブラウザーでの目視確認を通じて、Web インターフェースガイドラインへの準拠状況をレビューし、修正します。

適用範囲

• 静的サイト（HTML/CSS/JS）
• SPA フレームワーク：React / Vue / Angular / Svelte
• フルスタックフレームワーク：Next.js / Nuxt / SvelteKit
• ソースコードにアクセス可能なあらゆる Web アプリケーション

ワークフローの概要

Step 1: Information Gathering
    ↓
Step 2: Guidelines Fetch + Static Analysis
    ↓
Step 3: Visual Inspection (if URL provided)
    ↓
Step 4: Issue Fixing
    ↓
Step 5: Re-verification
    ↓
(Loop if issues remain)

---

ステップ 1：情報収集

1.1 レビューモードの判定

入力	モード	アクション
ファイル／パターンのみ	静的分析	ガイドラインに基づくコードレビュー
URL のみ	目視確認	ブラウザーベースの目視レビュー
URL ＋ ファイル	フルレビュー	静的分析と目視確認の両方

1.2 URL の確認（目視モード）

目視確認がリクエストされているものの URL が指定されていない場合は、次のように尋ねます。

レビュー対象の Web サイトの URL を指定してください（例：http://localhost:3000）

1.3 プロジェクトの検出

ワークスペース内のファイルから自動検出を試みます。

ファイル	検出対象
package.json	フレームワークと依存関係
tailwind.config.*	Tailwind CSS
next.config.*	Next.js
nuxt.config.*	Nuxt
vite.config.*	Vite

1.4 スタイリング方法の特定

方法	検出方法	編集対象
Pure CSS	*.css ファイル	グローバル CSS またはコンポーネント CSS
SCSS/Sass	*.scss、*.sass	SCSS ファイル
CSS Modules	*.module.css	Module CSS ファイル
Tailwind CSS	tailwind.config.*	コンポーネント内の className
styled-components	コード内の styled.	JS/TS ファイル
CSS-in-JS	インラインスタイル	JS/TS ファイル

---

ステップ 2：ガイドラインの取得＋静的分析

2.1 最新のガイドラインを取得

レビューのたびに、最新のガイドラインを取得します。

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

WebFetch を使って最新のルールを取得します。取得した内容には、すべてのルールと出力形式の指示が含まれています。

2.2 静的コード分析

1. 指定されたファイルを読み込む（またはユーザーにファイル／パターンを尋ねる）
2. 取得したガイドラインのすべてのルールと照合する
3. file:line 形式の参照を含めて指摘事項を収集する

---

ステップ 3：目視確認（ブラウザーモード）

3.1 前提条件

• 対象の Web サイトが稼働している必要があります（ローカル開発サーバーまたはリモート）
• ブラウザー自動化が利用可能である必要があります（Playwright MCP または cursor-browser-extension）

3.2 ページの確認

1. 指定された URL に移動する
2. スクリーンショットを撮影する
3. DOM 構造／スナップショットを取得する
4. 追加のページがある場合は、ナビゲーションをたどって確認する

3.3 ビューポートのテスト

レスポンシブ対応の問題を確認するため、次のビューポートでテストします。

名前	幅	代表的なデバイス
モバイル	375px	iPhone SE/12 mini
タブレット	768px	iPad
デスクトップ	1280px	標準的な PC
ワイド	1920px	大型ディスプレイ

3.4 目視確認のチェックリスト

レイアウトの問題

問題	説明	重大度
要素のはみ出し	コンテンツがコンテナーまたはビューポートからはみ出している	高
要素の重なり	意図しない要素の重なり	高
配置の問題	グリッドまたはフレックスの配置に関する問題	中
余白の不一致	パディング／マージンに一貫性がない	中
テキストの切り詰め	長いテキストが適切に処理されていない	中

レスポンシブ対応の問題

問題	説明	重大度
モバイル非対応	小さな画面でレイアウトが崩れる	高
ブレークポイントの問題	ブレークポイントで不自然に切り替わる	中
タッチターゲット	モバイルでボタンが小さすぎる	中

アクセシビリティの問題

問題	説明	重大度
コントラスト不足	テキストと背景のコントラスト比が低い	高
フォーカス状態がない	キーボード操作中にフォーカスを確認できない	高
alt テキストがない	画像に代替テキストがない	中

ビジュアルの一貫性

問題	説明	重大度
フォントの不一致	フォントファミリーが混在しています	中
色の不一致	ブランドカラーが統一されていません	中
余白の不一致	余白のパターンが統一されていません	低

---

ステップ 4：問題の修正

4.1 問題の優先順位付け

優先度	基準	対応
P1	機能に影響するレイアウトの問題	直ちに修正
P2	UX を損なうビジュアル上の問題	次に修正
P3	軽微なビジュアルの不一致	可能であれば修正

4.2 ソースファイルの特定

1. セレクターベースの検索：クラス名または ID でコードベースを検索します
2. コンポーネントベースの検索：要素のテキストや構造からコンポーネントを特定します
3. ファイルパターンによる絞り込み：src/**/*.css、styles/**/*、src/components/**/*

4.3 修正の原則

1. 変更は最小限に：必要最低限の変更のみ行います
2. 既存のパターンを尊重する：既存のコードスタイルに従います
3. 破壊的変更を避ける：他の箇所に影響しないよう注意します
4. コメントを追加する：必要に応じて修正理由を説明します

---

ステップ 5：再検証

5.1 修正後の確認

1. ブラウザーを再読み込みします（または HMR を待ちます）
2. 修正した箇所のスクリーンショットを撮影します
3. 修正前と修正後を比較します

5.2 回帰テスト

• 修正が他の箇所に影響していないことを確認します
• レスポンシブ表示が崩れていないことを確認します

5.3 反復

修正後も問題が残る場合は、ステップ 3 に戻ります。ユーザーに相談する前に、1 つの問題につき修正を試みるのは最大 3 回までとします。

---

出力形式

レビュー結果レポート

# Web Design Review Results

## Summary

| Item | Value |
|------|-------|
| Target | {URL or files} |
| Framework | {Detected framework} |
| Styling | {CSS / Tailwind / etc.} |
| Review Mode | {Static / Visual / Full} |
| Issues Detected | {N} |
| Issues Fixed | {M} |

## Static Analysis Findings

{file:line format findings from guidelines check}

## Visual Inspection Findings

### [P1] {Issue Title}

- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}

### [P2] {Issue Title}
...

## Unfixed Issues (if any)

### {Issue Title}
- **Reason**: {Why it was not fixed}
- **Recommended Action**: {Recommendations for user}

## Recommendations

- {Suggestions for future improvements}

---

使用例

静的解析のみ

Review my UI in src/components/
Check accessibility of my forms
Audit design of src/pages/

ビジュアル検査

Review the design at http://localhost:3000
Check the UI at http://localhost:5173/dashboard
Find layout problems on my site

全体レビュー（推奨）

Review my UI at localhost:3000 and fix issues in src/
Audit the design and fix responsive problems

---

ベストプラクティス

推奨事項

• 修正を行う前に、必ずスクリーンショットを保存します
• 一度に 1 つの問題を修正し、それぞれを検証します
• プロジェクトの既存のコードスタイルに従います
• 大規模な変更を行う前に、ユーザーに確認します

禁止事項

• 確認を得ずに大規模なリファクタリングを行う
• デザインシステムやブランドガイドラインを無視する
• 複数の問題を一度に修正する（検証が難しくなります）
• 修正後の再検証を省略する

---

トラブルシューティング

スタイルファイルが見つからない

1. package.json の依存関係を確認します
2. CSS-in-JS の可能性を検討します
3. スタイリング方法についてユーザーに確認します

修正が反映されない

1. 開発サーバーの HMR が機能しているか確認します
2. ブラウザーのキャッシュをクリアします
3. CSS の詳細度に関する問題を確認します

修正が他の箇所に影響する

1. 変更をロールバックします
2. より具体的なセレクターを使用します
3. CSS Modules またはスコープ付きスタイルを検討します