design-critique

デザインレビュー

既存のデザインを体系的に評価し、具体的で実行可能な改善案をコードとともに提示します。

前提条件

• .agents/design-context.md（design-contextを参照）を読み、ブランドカラー、フォント、スタイルのアーキタイプ、対象ユーザー、トーンを確認してください。「ブランドに合っているか」は好みではなく、このファイルに基づいて判断します。ファイルが存在しない場合は、ブランドコンテキストなしで一貫性／美しさのスコアを判断したことを伝えてください。
• プロジェクトの目的、対象ユーザー、デザインが促すべき1つのアクションを把握してください。
• ソースコードだけを見てレビューしてはいけません。まずレンダリング結果を確認してください（ステップ0）。

---

ステップ0：成果物を取得する（必ず最初に実施）

成果物	確認方法
HTMLファイル／ローカル開発サーバー／URL	以下のキャプチャスクリプトを実行し、出力されたPNGをすべて読み取ります
PNG/JPG/WebP（スクリーンショット、生成画像、ポスター）	ファイルを読み取ります。細部を確認するには、Pillowで切り抜き／拡大（Image.open(p).crop(box).resize(...)）して、切り抜いた画像を読み取ります
Figmaフレーム	接続されている場合はFigma MCPのget_screenshot（トークンについてはget_variable_defsも）を使います。接続されていない場合は、エクスポートを依頼します
React/Vueコンポーネント	プロジェクトの開発サーバーまたはStorybookでレンダリングし、URLとして扱います

キャプチャスクリプト -- <design-critique>/scripts/audit.mjs（<design-critique>はこのスキルのディレクトリ）に同梱されています。PlaywrightとChromiumが必要です。npm i -D axe-coreを実行するとオフラインでアクセシビリティチェックを利用できます（実行しない場合はCDNからaxeを読み込みます）。

node <design-critique>/scripts/audit.mjs <url-or-html-file> audit/            # 375, 768, 1440 px
node <design-critique>/scripts/audit.mjs http://localhost:3000 audit/ --widths 390,1280

{mobile,tablet,desktop}-fold.png（第一印象）、*-full.png、desktop-dark-fold.png、およびreport.json（標準出力にも表示）を出力します。ファイルには次の内容が含まれます。

セクション	測定内容
widths.<name>	水平方向のはみ出し、使用中のフォントサイズ／フォントファミリー／テキストカラー（一貫性）、4pxグリッドから外れた余白、24px未満のタップ領域、最も近い単色背景に対してWCAGコントラストを満たさないテキスト、画像上に配置されたテキスト（目視で確認）
darkMode	prefers-color-scheme: darkでのコントラストの問題
structure	lang、viewportメタタグ、h1の数、見出しレベルの飛び、altのない画像、ラベルのないフォームコントロール、最初のビューポートにある遅延読み込み画像（LCPリスク）、prefers-reduced-motionルールのないアニメーション
axe	axe-coreの違反：ルールID、影響度、件数、最初のセレクター

数値は判定結果ではなく、根拠として扱ってください。無効化されたコントロールや装飾的なテキストであれば、コントラストの「不合格」が問題ない場合もあります。その場合は明確に説明してください。

手順（レビューを比較できるよう、毎回同じ順序で進めます）：

1. desktop-fold.pngを5秒間見て、最初、次、三番目に気づいた点と、ページがユーザーに何を求めているかを書き留めます。これを視覚的階層の根拠とします。
2. スクリーンショットとJSONを使って、ステップ1～7を順に確認します。すべての指摘に、スクリーンショット上の領域、測定値、またはaxeのルールIDのいずれかを根拠として示してください。
3. 重要度（ステップ8）とスコア（ステップ10）を付け、レポートを作成します。
4. 修正を適用した後、キャプチャを再実行し、修正前後のスクリーンショットを比較します（ステップ9）。

静止画像（ポスター、広告、ソーシャルグラフィック、生成画像）にはDOMがありません。キーボード操作とパフォーマンスのチェックは省略し、Pillow（im.getpixel((x, y))）でピクセルカラーをサンプリングしてWCAGの計算式でコントラストを推定してください。また、実際の表示サイズでも評価してください（例：サムネイルを幅320pxに縮小して読み取る）。生成画像を修正するには、CSSではなくimage-generationスキル向けの具体的な編集指示を提示してください。

---

ステップ1：視覚的階層の評価

デザインがどれだけ効果的にユーザーの視線を誘導しているかを評価します。

チェックリスト

• 主要な焦点：最初に注意を引く要素が明確に1つありますか？
• 副次的な要素：重要度の第2、第3レベルが明確にわかりますか？
• サイズのコントラスト：最も重要な要素が最大ですか？各レベルのサイズに十分な差がありますか？
• 色のコントラスト：主要なCTAに最も強い色を使っていますか？副次的な要素が視覚的に後退していますか？
• ウェイトのコントラスト：見出しは本文より太く見えますか？
• 余白：最も重要な要素の周囲に最もゆとりがありますか？
• 読み進める流れ：レイアウトはFパターン（コンテンツ）またはZパターン（ランディングページ）に沿っていますか？

よくある修正

/* Problem: All elements same visual weight */
/* Fix: Create clear hierarchy with size and color */

/* Before: flat hierarchy */
.heading { font-size: 1.5rem; color: #333; }
.subheading { font-size: 1.25rem; color: #333; }
.body { font-size: 1rem; color: #333; }

/* After: clear hierarchy */
.heading { font-size: 2.5rem; font-weight: 800; color: var(--gray-900); letter-spacing: -0.02em; }
.subheading { font-size: 1.25rem; font-weight: 500; color: var(--gray-500); }
.body { font-size: 1rem; font-weight: 400; color: var(--gray-700); line-height: 1.65; }

---

ステップ2：色の使い方を評価する

チェックリスト

• パレットの統一感：すべての色が同じ系統／システムに属していますか？それとも、場違いに感じられる色がありますか？
• 色の意味：それぞれの色に目的（ブランド、意味、装飾）がありますか？
• 色数：色が多すぎませんか？（ブランドカラー1〜2色＋意味を示す色4色＋ニュートラルカラーを目安にしてください。）
• コントラスト比：すべてのテキストがWCAG AA（通常テキストは4.5:1、24px以上または太字で18.66px以上は3:1）を満たしていますか？axeのcolor-contrastの結果を使ってください。画像／グラデーション上のテキストについては、スクリーンショット内で最も条件の悪い箇所を測定してください。
• 意味を示す色の一貫性：赤は常にエラー、緑は常に成功を示していますか？
• ダークモード：ダークモードがある場合、色は適切に調整されていますか（単に反転させるだけになっていませんか）？
• 色だけに依存した情報：色だけで伝えている情報はありませんか？（色だけで伝えるべきではありません。）

よくある修正

/* Problem: Text fails contrast check */
/* Before: light gray on white */
.muted-text { color: #aaa; } /* ~2.3:1 on white -- FAILS AA */

/* Fix: darken until AA passes */
.muted-text { color: #737373; } /* 4.74:1 on white -- passes AA (design-context Neutral 500) */

/* Problem: Link indistinguishable from text */
/* Fix: underline + color */
a { color: var(--brand-500); text-decoration: underline; text-underline-offset: 2px; }

---

ステップ3：タイポグラフィの一貫性を確認する

チェックリスト

• フォント数：書体は最大2種類（等幅フォントを含める場合は3種類）ですか？それ以上だとまとまりがなく感じられます。
• サイズのスケール：サイズは一貫した比率のスケールに沿っていますか？それとも任意に決められていますか？
• ウェイトの使い方：使用しているウェイトは2〜3種類だけですか？（400、600、700が適切な組み合わせです。）
• 行の高さ：本文の行の高さは1.5〜1.75ですか？見出しは1.1〜1.3ですか？
• 行の長さ：本文の1行あたりの文字数は45〜75文字に収まっていますか？
• 一貫性：同じ種類の要素には、全体を通して同じスタイルが使われていますか？
• テキストの折り返し：見出しにtext-wrap: balanceを使っていますか（最終行が1語だけにならないようにしていますか）？
• スケールの根拠：キャプチャのJSONのfontSizesには、おおよそ5〜8種類のサイズが示されていますか？12種類以上の場合、スケールが設定されていません。
• レスポンシブ対応：モバイルではテキストのサイズが適切に調整されていますか？

よくある修正

/* Problem: Line length too long */
/* Before: text spans full 1400px container */
.content { max-width: 1400px; }

/* Fix: constrain prose */
.content { max-width: 1400px; }
.content .prose { max-width: 65ch; }

/* Problem: Arbitrary font sizes -- Fix: adopt the typography skill's modular scale */
:root {
  --type-ratio: 1.25; /* design-context Scale Ratio */
  --text-base: 1rem;
  --text-lg: calc(var(--text-base) * var(--type-ratio));
  --text-xl: calc(var(--text-lg) * var(--type-ratio)); /* ...see typography Step 1 */
}

---

ステップ4：間隔と配置を監査する

チェックリスト

• 間隔の一貫性：似た要素間の間隔は同じですか？
• 間隔のスケール：間隔は基本単位（4pxまたは8pxの倍数）に沿っていますか？
• 配置：要素はグリッドに沿って配置されていますか？左端は揃っていますか？
• 近接性：関連する項目は、関連しない項目より近くに配置されていますか？
• パディングのバランス：コンポーネント内のパディングは一貫していますか？
• 垂直方向のリズム：垂直方向の間隔に一貫したリズムがありますか？
• 端の一貫性：セクション間でページの余白は一貫していますか？

よくある修正

/* Problem: Inconsistent spacing */
/* Before: random pixel values */
.card { padding: 17px; margin-bottom: 23px; }
.section { padding: 45px 30px; }

/* Fix: use a 4px/8px scale */
.card { padding: var(--space-5); margin-bottom: var(--space-6); }
.section { padding: var(--space-12) var(--space-8); }

/* Problem: Misaligned elements */
/* Fix: use consistent padding and max-width */
.container {
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: var(--space-6);
}

---

ステップ5：アクセシビリティを確認する

コントラスト

• 通常のテキスト：最小コントラスト比は4.5:1です。
• 大きなテキスト（24px以上、または太字で18.66px以上）：最小コントラスト比は3:1です。
• UIコンポーネント（境界線、アイコン）：隣接する色に対して3:1です。
• フォーカスインジケーター：隣接する背景に対して3:1です。

キーボード操作

• すべてのインタラクティブ要素にフォーカスできます。
• フォーカスの順序は視覚的な順序に沿っています。
• フォーカスインジケーターが見え、十分なコントラストがあります。
• キーボードトラップがありません（ユーザーは常にTabキーで移動できます）。
• コンテンツへのスキップリンクがあります。

スクリーンリーダー

• 画像には意味のある代替テキストがあります（装飾目的の場合はalt=""）。
• フォーム入力には対応するラベルがあります。
• アイコンのみのボタンにはaria-labelがあります。
• 見出しが論理的な階層を構成しています（階層を飛ばしていません）。
• 動的コンテンツの変更が通知されます（aria-live領域）。

よくある修正

/* Problem: Custom focus style removed */
/* Before */
*:focus { outline: none; } /* NEVER DO THIS */

/* Fix: custom but visible focus */
*:focus-visible {
  outline: 2px solid var(--brand-500);
  outline-offset: 2px;
}

/* Problem: No skip link */
/* Fix: */
.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  padding: 0.5rem 1rem;
  background: var(--brand-500);
  color: white;
  z-index: 9999;
}

.skip-link:focus {
  top: 0;
}

<a href="#main-content" class="skip-link">Skip to main content</a>

---

ステップ6：レスポンシブ動作を確認する

チェックリスト

• モバイルレイアウト：小さな画面で、レイアウトは適切に縦積みになりますか？
• タッチターゲット：最低 24x24px（WCAG 2.2 AA、SC 2.5.8。JSON の smallTargets を参照）。モバイルでは 44x44px を推奨します。
• テキストの読みやすさ：モバイルで本文のテキストサイズは 16px 以上ですか（ズーム不要）？
• 横スクロール：横方向にはみ出すコンテンツはありますか？
• 画像：画像は適切なサイズに調整されますか（max-width: 100%）？
• ナビゲーション：モバイルナビゲーションは利用しやすく、使いやすいですか？
• ブレークポイント：ブレークポイント間でレイアウトはスムーズに切り替わりますか？

よくある修正

/* Problem: Fixed widths cause overflow */
/* Before */
.card { width: 400px; }

/* Fix: flexible with max */
.card { width: 100%; max-width: 400px; }

/* Problem: Small touch targets */
/* Before */
.icon-button { width: 24px; height: 24px; }

/* Fix: larger hit area, same visual icon (works with box-sizing: border-box) */
.icon-button {
  min-width: 44px;
  min-height: 44px;
  display: inline-grid;
  place-items: center;
}

/* Problem: Images overflow container */
img {
  max-width: 100%;
  height: auto;
}

---

ステップ 7：パフォーマンスへの影響の評価

チェックリスト

• フォントの読み込み：font-display: swap を使用していますか？重要なフォントをプリロードしていますか？
• 画像形式：フォールバックとともに AVIF/WebP を使用し、srcset と sizes を指定して、スマートフォンがデスクトップ向けの画像をダウンロードしないようにしていますか？
• 画像サイズ：画像は適切なサイズですか（400px の表示領域に対して 4000px になっていませんか）？
• アニメーションのパフォーマンス：アニメーションで transform と opacity のみを使用していますか？
• CSS の効率性：冗長なスタイルや上書きするスタイルはありませんか？
• レイアウトシフト：画像や埋め込みコンテンツ用の寸法を確保していますか（aspect-ratio、width/height）？
• 過剰なシャドウやぼかし：頻繁に描画される要素に複雑な box-shadow を使用していませんか？

よくある修正

/* Problem: Animation causes layout recalculation */
/* Before */
.card:hover { margin-top: -5px; }  /* triggers layout */

/* Fix: use transform */
.card:hover { transform: translateY(-5px); }  /* GPU composited */

/* Problem: Layout shift from images */
/* Fix: put the intrinsic size in HTML (<img width="1600" height="900">), then: */
img { max-width: 100%; height: auto; }

---

ステップ 8：重大度と推奨事項の形式

重大度レベル（各問題に必ず 1 つ割り当てる）

重大度	基準	例
Critical	ユーザーが主要なタスクを完了できなくなる、または主要コンテンツが WCAG A/AA に適合しない	本文のコントラスト比が 2.3:1、モバイルで CTA が見えない、キーボードトラップ、モバイルでの横スクロール、フォームフィールドのラベル不足
High	主要なタスクは機能するものの、明らかに使いにくい、またはデザインが主な目的を損なっている	明確な主要 CTA がない、注目ポイントが競合している、ブランドに合わない色やフォント、タップターゲットが 24px 未満
Medium	目につく仕上がりや一貫性の問題で、多くのユーザーが気づくものの回避できる	フォントサイズが 10 種類以上、グリッドから外れた余白、角丸の不統一、二次的な階層が弱い
Low	デザイナーなら気づく程度の微調整	見出しのウィドウ、やや広すぎる字間、軽微な配置のずれ

修正リストは重大度の高い順に並べ、同じ重大度内では影響度 ÷ 作業量の順に並べてください。

推奨事項の形式

### [Severity] Issue: [What's wrong]
**Category**: Hierarchy | Color | Typography | Spacing | Accessibility | Responsive | Performance
**Evidence**: [screenshot + region, measured value, or axe rule id]
**Problem**: [1-2 sentences: what's wrong and why it matters]
**Fix**: [Specific CSS/HTML using the project's tokens]
**Impact**: [What improves]

例

### [High] Issue: Hero headline, subtitle, and CTA compete for attention
**Category**: Hierarchy
**Evidence**: desktop-fold.png -- headline 28px/600, subtitle 24px/600, CTA is a gray outline button
**Problem**: Nothing reads first, and the only action looks secondary.
**Fix**: .hero-headline { font-size: clamp(2.5rem, 5vw + 1rem, 5rem); font-weight: 800; }
         .hero-subtitle { font-size: var(--text-xl); color: var(--text-secondary); max-width: 50ch; }
         .hero-cta { background: var(--interactive-primary); color: white; }
**Impact**: Headline -> value prop -> CTA reads in order within 3 seconds.

---

ステップ 9：修正前後の検証

修正内容をレンダリング後のページで確認するまで、評価は完了ではありません。

1. 各修正について、現在の CSS（修正前）と改善後の CSS（修正後）を示し、何を変更したか、その理由を説明してください。既存のトークン（--space-*、--text-*、--bg-*、--text-primary、--interactive-primary、--radius-*、--shadow-*）を使用し、新しいハードコード値を導入しないでください。
2. 修正を適用した場合は、キャプチャスクリプトを新しいフォルダーに対して再実行し、同じビューポートの修正前と修正後のスクリーンショットを読み込んで、並べて比較してください。
3. Critical/High の問題がすべて解決されていること（axe の違反がなく、オーバーフローが false で、ターゲットが 24px 以上）と、他の幅やダークモードで問題が再発していないことを確認してください。この確認後にのみ、再採点してください。

---

ステップ 10：スコアリングの枠組み

以下の各観点について、デザインを 1～10 で評価してください。

カテゴリ

カテゴリ	配点	評価項目（チェックリストの手順）
階層	25%	明確な焦点、一覧性、誘導される流れ（ステップ1、5秒テスト）
一貫性	25%	余白のスケール、カラーシステム、タイポグラフィシステム、ブランドとの一致（ステップ2～4、JSON を記録）
美しさ	25%	色の調和、余白、仕上がり、スタイルの類型との適合性
使いやすさ	25%	アクセシビリティ、レスポンシブ対応、明瞭さ、パフォーマンス（ステップ5～7、axe）

総合評価 = 加重平均を小数第1位に丸めた値です。上限を設けて評価の妥当性を保ちます。未解決の重大な問題がある場合、そのカテゴリの評価は4点、総合評価は6点が上限となります。未解決の高優先度の問題がある場合、そのカテゴリの評価は7点が上限となります。美しさの評価では、「モダンに見える」と述べるだけでなく、少なくとも1つの具体的な所見を挙げてください。

評価基準

評価	意味
1-2	根本的に機能していません。大幅な作り直しが必要です。
3-4	大きな問題があります。複数の領域で対応が必要です。
5-6	機能しますが、仕上がりが不十分です。明確な改善点があります。
7-8	良好です。細かな調整でさらに向上します。
9-10	非常に優れています。プロ品質で、完成度の高い仕上がりです。

レポートテンプレート

## Design Critique Report

### Overall Score: X/10

| Category    | Score | Notes                                |
|-------------|-------|--------------------------------------|
| Hierarchy   | X/10  | [brief note]                         |
| Consistency | X/10  | [brief note]                         |
| Aesthetics  | X/10  | [brief note]                         |
| Usability   | X/10  | [brief note]                         |

### Top 3 Strengths
1. [What's working well]
2. [What's working well]
3. [What's working well]

### Issues by Severity
| # | Severity | Category | Issue | Evidence |
|---|----------|----------|-------|----------|
| 1 | Critical | ...      | ...   | ...      |

### Fixes (in priority order, with code -- Step 8 format)

### Quick Wins (< 5 min each)
- [Small change, big impact]
- [Small change, big impact]

---

批評プロセスの概要

0. 記録：成果物をキャプチャし（ステップ0）、コードを読む前にスクリーンショットを確認します。
1. デザインの背景を把握し、目標を理解します。
2. 視覚的な階層を評価します：1-2-3の明確な優先順位がありますか？
3. 色を評価します：統一感がありますか？アクセシビリティに配慮されていますか？意図的に使われていますか？
4. タイポグラフィを確認します：スケールに一貫性がありますか？行の長さは適切ですか？読みやすいですか？
5. 余白を監査します：システムに基づいていますか？配置は揃っていますか？一貫していますか？
6. アクセシビリティをレビューします：コントラスト、フォーカス、ラベル、キーボード操作は適切ですか？
7. レスポンシブ対応をテストします：モバイルでの積み重ね、タッチターゲット、はみ出しを確認します。
8. パフォーマンスを確認します：アニメーションは効率的ですか？画像サイズは適切ですか？フォントは読み込まれていますか？
9. 具体的な修正案を提示します：説明だけで済ませず、必ずコードを含めます。
10. 評価して優先順位を付けます：深刻度を割り当て、上限を適用し、修正項目を順位付けします。
11. 再検証します：修正後に再度キャプチャし、重大および高優先度の問題が解消されていることを確認します（ステップ9）。