design-review

デザインレビュー

UI コードのデザインレビューを行い、優先順位を付けた批評を返します。レビューの視点は、Emil Kowalski のデザインエンジニアリング哲学――センスが差別化要因であり、見えない細部が積み重なり、視線の誘導先を示す――を、Refactoring UI、WCAG、MDN のヒューリスティクスに基づいて具体化したものです。

これは読み取り専用のレビュー用スキルです。問題を診断して修正案を提示しますが、コードベースを書き換えることはありません。各指摘では、コードが陥った誤ったデフォルト、具体的な修正方法、そしてその重要性を説明します。

適用する場面

• ユーザーがコンポーネント、画面、ページについて「この UI をレビューして」「デザインレビューを実施して」「批評して」と依頼した場合。
• ユーザーが出力を「なんだか違う」「AI が生成したように見える」「ワイヤーフレームのように見える」「ありきたりに感じる」と述べ、その理由を知りたい場合。
• PR で CSS／JSX／Tailwind が変更され、ユーザーがマージ前にデザイン面のフィードバックを求めている場合。
• 既存のインターフェースのビジュアルの完成度やアクセシビリティを高めたい場合。

UI をゼロから構築する用途ではありません（web-taste を使用してください）。アニメーションのルールを網羅的に確認する用途でもありません（emilkowal-animations を使用してください）。

レビューの進め方

2 つのモードがあります。 静的レビューではコードを読みます。これがデフォルトです。ランタイムレビューでは、さらに実際のブラウザーを操作して、コードからは確認できないアニメーションのタイミングやフレーム落ち、レイアウトシフト、実際のフォーカス順序とアクセシビリティツリー、複数ページを最後までクリックして進むフローを測定します。結論がレンダリング後の挙動（motion-、interact-、flow- カテゴリー）に左右される場合は、runtime-capture.md に従ってランタイムレビューに切り替えてください。

1. 全体を把握する――0.5 秒テスト。 1 行ずつ読む前に、レンダリングされた画面を思い描きます。最初に視線が向かうのはどこですか？ 焦点は 1 つに絞られていますか、それともすべてが同じ強さを持っていますか？ これを基に、この UI で重要なカテゴリーを判断します。
2. カテゴリーを優先順位順に確認する（下の表）。コードに含まれる判断ごとに、対応するリファレンスファイルを読み、コードと照らし合わせます。最も大きく、最も頻繁に問題が見つかるのは視覚的階層と余白です。まずここから始めます。
3. 複数ページまたはインタラクション主導の UX は、ブラウザーで実際にたどる。 依頼がフロー（「このオンボーディングをレビューして」など）に関するもの、または問題が動作中に発生するもの（カクつき、ルート表示時の一瞬の空白、フォーカスの喪失など）なら、runtime-capture.md に従ってランタイムの証拠を収集します。これにより、「Before」列を推測ではなく実測値にできます。
4. 各問題を指摘として記録する。 Before（正確なコードまたは測定値）、After（具体的な修正）、Why（原則）、そして状況に応じた重大度を記載します。
5. 結論で締めくくる。 影響の大きい順に、優先して行う修正を 3 つ挙げ、作成者が何から変更すればよいかを明確にします。

出力形式（必須）

指摘事項は単一の Markdown テーブルで報告し、問題ごとに 1 行を使ってください。説明文や、別々の行に Before: / After: を記載する形式は使わないでください。

重大度	修正前	修正後	理由
High	transition: all 300ms ease-in	transition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1)	ease-in は開始時の動きが鈍く感じられます。プロパティを指定し、強いイーズアウト曲線を使ってください
High	すべてのボタンが bg-indigo-600	塗りつぶしのプライマリボタンを 1 つにし、ほかはゴースト／アウトラインにする	すべてのボタンの強さが同じだと競合します。プライマリボタンを 1 つにすると、次のステップが明確になります
Medium	#fff に対する color: #000	color: hsl(222 47% 11%)	純粋な黒はインクのような色よりもきつく、 stark な印象になります
Critical	<div onClick={remove}>	<button type="button" onClick={remove}>	div はキーボードで操作できず、スクリーンリーダーにも認識されません

誤った形式 — 絶対に使わないでください：

Before: transition: all 300ms
After: transition: opacity 180ms ease-out
────────────────────────────
Before: color #000
After: color slate-900

重大度ガイド（UI における影響度に応じて、指摘ごとに割り当てます）：

重大度	意味
Critical	使いやすさやアクセシビリティを損ないます — コントラスト不足、キーボード操作不可、テキストが読めない
High	デザインを明らかに損ないます — 階層がない、余白が窮屈、プライマリアクションが競合する
Medium	仕上がりに目立つ改善点があります — デフォルトのイージング、均一な行の高さ、押下時のフィードバックがない
Low	細かな調整 — 値がスケールから少し外れている

最後に、優先度の高い修正 3 件を記載してください。影響の大きい行を、対応すべき順に並べます。

ルールのカテゴリ

#	カテゴリ	プレフィックス	対象
1	視覚的階層	hier-	焦点、強調手法、プライマリアクションを 1 つにする、ラベルより値を目立たせる、境界線より余白を使う
2	余白とレイアウト	space-	余白のスケール、ゆとりのあるホワイトスペース、近接によるグループ化、幅の制約
3	タイポグラフィ	type-	文字サイズのスケール、行の長さ、行の高さ、配置、読みやすい本文
4	色とコントラスト	color-	黒に近いテキスト、WCAG コントラスト、HSL ランプ、アクセントの抑制、色と手がかりの併用
5	コンポーネントの状態とフィードバック	state-	押下時のフィードバック、focus-visible、すべての状態のマトリックス、空の状態
6	モーションとアニメーション	motion-	目的／頻度、イーズアウト曲線、300ms 未満、開始位置／スケール、transform のみ
7	レスポンシブ対応とタッチ	resp-	モバイルファーストの流動的なレイアウト、44px のターゲット、ホバーの適用条件
8	アクセシビリティとセマンティクス	access-	セマンティック要素、アクセシブルな名前、モーションの軽減
9	フローとナビゲーション	flow-	アプリシェルの一貫性、ビュー状態の保持、エントリーポイントの整合性、現在地の把握
10	インタラクションの連続性	interact-	ルート遷移の橋渡し、非同期フィードバック、ナビゲーション時のフォーカス

クイックリファレンス

1. 視覚的階層（hier-）

• hier-one-focal-point — 画面ごとに明確な焦点を 1 つ設ける
• hier-emphasis-color-weight — サイズだけでなく、色とウェイトを使って強調する
• hier-one-primary-action — 各ビューのプライマリアクションを 1 つに絞る
• hier-values-over-labels — ラベルより値を目立たせる
• hier-replace-borders-with-space — 境界線を余白と背景に置き換える

2. 余白とレイアウト（space-）

• space-use-a-scale — 一貫したスケールに基づいて余白のサイズを決める
• space-start-generous — 必要だと感じる以上に、レイアウトにホワイトスペースを設ける
• space-proximity-groups — グループのまとまりがわかるよう、余白に差をつける
• space-constrain-measure — ページコンテナの幅を制限し、中央に配置する

3. タイポグラフィ（type-）

• type-modular-scale — 小さな文字サイズスケールからフォントサイズを選びます
• type-limit-line-length — 読みやすさのため、本文の行の長さを制限します
• type-line-height-by-size — フォントサイズに応じて行の高さを設定します
• type-left-align-prose — 複数行のテキストを左揃えにします
• type-readable-body-size — 本文を読みやすい大きさと太さに保ちます

4. 色とコントラスト（color-）

• color-avoid-pure-black — 純黒ではなく、黒に近い色を使います
• color-meet-contrast — 本文のテキストでWCAGのコントラスト基準を満たします
• color-hsl-scales — HSLの色合いの段階として色を定義します
• color-limit-accents — アクセントカラー1色とニュートラルカラーにパレットを絞ります
• color-not-only-signal — 状態を示す際は、色に別の手がかりを組み合わせます

5. コンポーネントの状態とフィードバック（state-）

• state-press-feedback — 押せる要素に押下時のフィードバックを与えます
• state-focus-visible — アクセシブルなフォーカスインジケーターを維持します
• state-design-all-states — デフォルトだけでなく、すべてのインタラクティブな状態を設計します
• state-empty-state — ガイダンスを含む空の状態を設計します

6. モーションとアニメーション（motion-）

• motion-needs-purpose — 目的がある場合にのみアニメーションを使います
• motion-ease-out-custom — UIのトランジションに、カスタムカーブのイーズアウトを使います
• motion-under-300ms — UIのトランジションを300ms未満に保ちます
• motion-enter-origin-scale — 近いスケールとトリガーの起点から表示します
• motion-transform-opacity-only — transformとopacityのみをアニメーションさせます

ドラッグ、ジェスチャー、スプリング、スタガー、clip-path、およびタイミング／イージングの全表については、emilkowal-animationsスキルを参照してください。

7. レスポンシブ対応とタッチ（resp-）

• resp-fluid-not-fixed — モバイルファーストで、幅が流動的に変化するように構築します
• resp-touch-target-size — タッチターゲットを少なくとも44pxの大きさにします
• resp-gate-hover — ポインタークエリを使って、ホバーのみの操作要素を制御します

8. アクセシビリティとセマンティクス（access-）

• access-semantic-elements — インタラクティブなコントロールにはセマンティックな要素を使います
• access-name-icon-controls — アイコンのみのコントロールにアクセシブルな名前を付けます
• access-respect-reduced-motion — 動きを抑える設定を尊重します

9. フローとナビゲーション（flow-）

1画面だけのレビューでは見えない、ページをまたいだ体験をレビューします。ブラウザーでフローを確認してください（runtime-capture.md）。

• flow-consistent-shell — ページ間でアプリのシェルに一貫性を保ちます
• flow-preserve-state-on-nav — ナビゲーションをまたいでスクロール位置と表示状態を保持します
• flow-entry-point-integrity — すべてのページが最初の入口として機能するようにします
• flow-wayfinding — ユーザーの現在地と戻る方法を示します

10. インタラクションの継続性（interact-）

時間の経過や画面遷移をまたいでも、体験が継続するかを評価します。これはスクリーンショットでは確認できない観点です。キャプチャしたトレース（runtime-capture.md）と照らし合わせて評価するのが最適です。

• interact-bridge-route-transitions — 画面が一瞬でも真っ白にならないよう、ルート変更をスムーズにつなぐ
• interact-feedback-spans-async — インタラクションの処理中に生じる待ち時間を埋める
• interact-move-focus-on-navigation — クライアントサイドナビゲーション後に、新しいコンテンツへフォーカスを移動する

使用方法

レビュー対象のコードで判断が必要になったら、該当するリファレンスファイルを読んでください。各ルールでは、修正対象となる誤ったデフォルトを示し、標準的な修正方法を説明します（誤った方法が実際に陥りやすい罠となる場合に限り、「誤り／正解」の対比を示します）。作成者が詳しく確認できるよう、「理由」列にルールのスラッグを記載してください。

• ランタイムキャプチャ — 静的な確認だけでは不十分な場合に、実際のブラウザー（chrome-devtools-mcp）を操作して、モーション、ジャンク、フォーカス順序、複数ページにまたがるフローを測定する
• セクション定義 — カテゴリーの構成と順序
• ルールテンプレート — 新しいルールを追加するためのテンプレート
• AGENTS.md — すべてのルールをまとめた自動生成の目次

関連スキル

• emilkowal-animations — アニメーションに関する網羅的なルールセット（イージング、ジェスチャー、スプリング、スタガー）です。このスキルでは、モーションの詳細をこちらに委ねています。
• web-taste — すぐれたセンスを反映しながら、React/Next/Tailwind UI を一から構築します（このレビューに対応する構築用スキルです）。
• tailwind-ui-refactor — Tailwind のリファクタリングとして、これらの修正を適用します。
• ui-design — より幅広い構築時のフロントエンドリファレンス（Core Web Vitals、フォーム、ダークモード）です。両者の対象が重なる場合（セマンティクス、コントラスト、フォーカス、単一の主要アクション）は、作成時には ui-design、レビュー時には design-review を利用してください。

リファレンスファイル

ファイル	説明
references/_runtime-capture.md	ブラウザー操作によるキャプチャの手引き（mcporter 経由の chrome-devtools-mcp）
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとソースの参照情報