ui-review

UI デザインレビュー

使用する場面

デザインシステムへの準拠、アクセシビリティ、ベストプラクティスについて UI コードをレビューする必要がある場合に、このスキルを使用します。

使用しない場面

• アクセシビリティのみの問題 → /ss-a11y を使用してください
• Nielsen の UX ヒューリスティック → /ss-audit を使用してください
• 手早く自動チェックしたい場合 → /ss-lint を使用してください
• UI 以外のコード（データ取得、ビジネスルール）

レビューするファイル：$ARGUMENTS

このチェックリストは、上流の StyleSeed の規約を対象としています。実際のプロジェクトのデザインシステムをまず確認してください。フォント、間隔、角丸に関するルールや、参照されている CLAUDE.md/VISUAL-CRAFT.md はプロジェクト固有の規約であり、アクセシビリティの普遍的な要件ではありません。また、これらのファイルはここには含まれていません。他のプロジェクトにこれらの規約を適用するのではなく、コンテキストが利用できないことを明記してください。

チェックリスト

1. デザイントークンへの準拠

• ハードコードされた 16 進数カラーを使用していない（text-foreground、bg-brand などのセマンティックトークンを使用）
• Tailwind でハードコードされた px 単位の間隔を使用していない（p-[24px] ではなく p-6 を使用）
• 影に CSS 変数を使用している（shadow-[var(--shadow-card)]）
• 角丸がスケールに従っている（rounded-md、rounded-lg、rounded-2xl）

2. コンポーネントの規約

• data-slot 属性を使用している
• className の結合に cn() を使用している
• Props の型に React.ComponentProps<> を使用している
• className prop による上書きをサポートしている
• 名前付きエクスポートを使用している（コンポーネントにデフォルトエクスポートを使用しない）
• className を追加するだけのラッパーコンポーネントがない

3. アクセシビリティ（a11y）

• ポインターターゲットはデザイン目標として 44x44 CSS ピクセルを推奨します。WCAG 2.2 AA SC 2.5.8 では 24x24、または適用可能な例外が基準であるため、それより小さいコントロールが自動的に AA 違反になるわけではありません（W3C）
• すべてのインタラクティブ要素に focus-visible スタイルを設定している
• 必要に応じて適切な aria-* 属性を使用している
• 色のコントラストが WCAG AA を満たしている（テキストは 4.5:1、大きなテキストは 3:1）
• アニメーションが prefers-reduced-motion に対応している
• 画像に alt テキストがある
• フォーム入力に対応するラベルがある

4. モバイル向けのベストプラクティス

• 横方向のオーバーフローがない
• インタラクティブ要素の間隔がタッチ操作に適している
• ノッチ付きデバイス向けにセーフエリアのインセットを処理している
• 読みやすさのため、テキストサイズが 12px 以上である
• スクロール可能なコンテナに -webkit-overflow-scrolling: touch を設定している

5. パフォーマンス

• 不要な再レンダリングがない（参照の安定化、必要に応じたメモ化）
• 画面外の画像は効果がある場合に遅延読み込みする。ファーストビュー内の重要な画像や LCP 画像を自動的に遅延させない
• 負荷の大きいコンポーネントをコード分割している

6. タイポグラフィ

• Pretendard/Inter のフォントスタックを使用している
• 14 段階のスケールからフォントサイズを選んでいる（10-48px、CLAUDE.md を参照）
• 適切なフォントウェイトを使用している（400、500、600、700）
• ディスプレイテキスト（36-48px）：leading-none + tracking-[-0.02em]
• 見出しテキスト（18-24px）：leading-snug + tracking-[-0.01em]
• 本文テキスト（14-17px）：leading-normal（カスタムトラッキングなし）
• キャプションの大文字表記（10-13px）：tracking-[0.05em] または tracking-wide
• ディスプレイテキストや見出しに line-height: 1.5 を使用していない（広すぎるため）

7. 間隔の一貫性

• すべての間隔の値が 6px の倍数である（p-1.5、p-3、p-6 など）
• 任意の間隔を使用していない（p-5=20px、gap-3.5=14px は違反）
• w-* h-* ではなく size-* の省略記法を使用している
• ml-*/mr-* ではなく ms-*/me-* を使用している（論理プロパティ）
• モーションのトランジションにデザイントークンを使用している（duration-[var(--duration-fast)]）

8. 一貫性（VISUAL-CRAFT.md §C0 — 「軸ごとに1つの選択」という法則）

UI が「AI 生成っぽく」見える最大の理由は、醜いパーツではなく、混在した パーツです。以下の各軸がプロジェクト全体で1つの値を使用しているか確認し、混在を些細な指摘ではなく実際の問題としてフラグを立ててください。

• 1つの角丸の個性 — シャープ（0〜4px）OR ソフト（8〜12px）OR ピル型を、すべてのカード/ボタン/入力/モーダルに適用します。混在は避けてください（例: rounded-none のパネルに rounded-full のボタン）。
• インタラクティブな強調には1つのアクセントカラー（+ 意味的な赤/緑/アンバーのみ） — 2つ以上の競合するアクセントは避けます。
• UI アイコンとして絵文字を使わない（🚗🧺⭐ をリスト/ナビ/ステータス/カテゴリのマーカーとして使うなど） — 制御不能な多くの色相を持ち込みます。currentColor の1つのラインアイコンセットを使用してください。
• ステータスカラー = 深刻度であり、装飾ではない — 通常/OK/「보통」の状態はニュートラルなグレー（色付きではない）とし、色は注意が必要な少数の行だけを示します。同じ値 → 同じ色です。
• 装飾的な色相を使わない — お気に入りの星、カテゴリのドット、アバターはアクセントまたはグレーを使用し、それぞれに新しい色を使わないでください。
• 1つのシャドウ言語 — 同じ光の方向、同じスケール/色合いとし、黒もあれば色付きもあり、上向き照明もあれば下向き照明もある、という状態にしないでください。
• ファイル全体で1つのアイコンファミリー / 塗りモード / ストロークの太さ。
• ネストした角丸の法則 — 角丸のコンテナ内の要素は、同じ角丸ではなく inner = outer − padding を使用します（同じにすると膨らんで見えます）。
• 一貫したコントロールの高さ — ボタン、入力、セレクトは高さのセット（例: 40px）を共有します。
• エラー/状態は色だけに依存しません（アイコン + テキストも併用します）。

出力形式

以下を提供してください:

1. スコア: Pass / Needs Improvement / Fail
2. 問題点: 各違反を file:line 参照とともに列挙
3. 修正案: 各問題に対する具体的なコード変更

例

ユーザーのリクエスト:

デザインシステムへの準拠、アクセシビリティ、ベストプラクティスについて UI コードをレビューしてください。

制限事項

• このスキルは、タスクがその上流ソースおよびローカルプロジェクトのコンテキストと明確に一致する場合にのみ使用してください。
• 変更を適用する前に、コマンド、生成されたコード、依存関係、認証情報、外部サービスの動作を検証してください。
• 例を、環境固有のテスト、セキュリティレビュー、または破壊的もしくは高コストな操作に対するユーザーの承認の代わりとして扱わないでください。