shadcn-component-review

shadcn コンポーネントレビュー

カスタムコンポーネントが shadcn のデザインパターン、プロジェクトで選択したビジュアルスタイル、最新のコンポジション規約に沿っていることを確認するための体系的な監査プロセスです。

公式 shadcn スキルとの補完関係

公式の shadcn スキル（CLI v4 に同梱）は、生成時にルールを適用します。「space-y-* ではなく gap-* を使う」「セマンティックカラーを使う」「幅と高さを同じにする場合は size-* を使う」などをエージェントに指示します。新しいコードを書くときには、これが適切な動作です。

このスキルは、事後監査を目的としています。すでに存在するコンポーネント（Claude、チームメイト、以前のイテレーションによって書かれたもの）を、同じルールに加え、テーマによって異なるビジュアルスタイル固有のパターン（Vega のスペーシングは Maia と異なり、Maia は Mira と異なります）に照らしてレビューします。両方のスキルが適用される場合、公式スキルは前向きなコード生成を、このスキルは遡及的なレビューを担当します。競合することはありません。同じルールを異なる方向から確認します。

基本原則

レビューによってずれを見つけます。公式スキルが生成時にルールを適用していても、コンポーネントは時間の経過とともにずれていきます。古いプロジェクトからコピーされたり、LLM が space-y-4 を提案して誰も気づかなかったり、プロジェクトが Maia に標準化される前にコンポーネントが作られていたり、コントリビューターがセマンティックトークンではなく Tailwind のカラー・スケールを使ったりすることがあります。このスキルは、そうした問題を体系的に見つけます。

起動するタイミング

自発的な起動条件（コンポーネントの作成後に有効化）：

• Claude がカスタムコンポーネントの作成または変更を終えた直後
• ユーザーが「これを作りました」と言ってコンポーネントを貼り付ける
• ユーザーが既存の要素へのスタイル追加を依頼する
• ユーザーがレイアウトを反復調整している

明示的な起動条件（ユーザーが直接レビューを依頼）：

• 「このコンポーネントをレビューして」
• 「スペーシングを確認して」
• 「shadcn の慣用的な書き方になっている？」
• 「パターンに沿っている？」
• 「このレイアウトを監査して」

レビュー前：プロジェクトのコンテキスト

テーマ固有のパターンを適用する前に、プロジェクトを把握します。shadcn CLI が利用可能な場合は、次を実行します。

npx shadcn@latest info --json

次の情報が返されます：フレームワーク（Next.js / Vite など）、Tailwind のバージョン、ベースライブラリ（radix または base）、インストール済みコンポーネント、アイコンライブラリ、解決済みのファイルパス、現在のスタイルです。この出力を使って、次のことを行います。

• スペーシングや形状の想定を、プロジェクトのビジュアルスタイルに合わせる
• プリミティブのベースに応じた適切なコンポジションパターンを適用する（Radix と Base UI では API が異なります）
• すでにインストール済みのコンポーネントと、インストールを提案するコンポーネントを把握する

CLI を利用できない場合は、components.json から直接推測するか、ユーザーに「このプロジェクトではどのビジュアルスタイルを使っていますか？ Vega、Nova、Maia、Lyra、Mira のどれですか？」と尋ねます。

レビューワークフロー

ステップ 1：構造とコンポジション

コンポーネントが shadcn の規約に沿った構造になっているか確認します。

data-slot 属性。 コンポーネント内の各セマンティック要素には、その役割を示す data-slot 属性を付ける必要があります。これにより、スタイリング用フック、テストセレクター、一貫したテーマ設定が可能になります。shadcn のソースで確認されている現在のパターンです（例：<button data-slot="button" data-variant={variant} data-size={size}>）。

変更ではなくコンポジション。 カスタムコンポーネントでは、プリミティブをフォークして変更するのではなく、@/components/ui/* のプリミティブを組み合わせます。プリミティブに異なる動作が必要な場合はラップし、ソースは編集しません。

プリミティブのベースを把握する。 プロジェクトが Radix（--base radix）を使っている場合は、asChild と Slot のパターン、および Radix の data-state 属性を想定します。Base UI（--base base）を使っている場合は、異なるコンポジション API を想定します。インストール済みのプリミティブについては、最新のドキュメントを参照してください：npx shadcn@latest docs <component>。

ステップ 2：スペーシングの監査

スペーシングは、スタイルのずれが最も起きやすい箇所です。プロジェクトのビジュアルスタイルと照らし合わせて確認してください。スタイルごとのパターンについては、references/theme-styles.md を参照してください。

共通ルール（すべてのテーマに適用）：

• flex/grid コンテナーでは gap-* を使い、space-y-* / space-x-* やマージンは使いません
• Tailwind の標準スペーシングスケールを使います（4px の倍数：1、1.5、2、4、6、8。3、5、7 は避けてください）
• 幅と高さが等しい場合は size-* を使います（w-10 h-10 ではなく size-10）
• レスポンシブなスペーシングには gap-X md:gap-Y パターンを使います

スタイル固有のルール： スタイルによって密度や角丸の基準は異なります。詳細は references/theme-styles.md を参照してください。

ステップ 3：デザイントークン

セマンティックトークンのみが使われていることを確認し、ハードコードされた Tailwind のカラー値は使わないでください。

カテゴリー	使用する値	避ける値
テキストカラー	text-foreground、text-muted-foreground、text-primary	text-neutral-500、text-gray-900、text-slate-700
背景	bg-background、bg-card、bg-muted、bg-accent	bg-gray-100、bg-white、bg-neutral-50
ボーダー	border-border、border-input	border-gray-200、border-neutral-300
角丸	rounded-md、rounded-lg（--radius を使用）	rounded-[20px]、rounded-[8px]

ハードコードされたカラーを検出する簡単な grep：

grep -rE '\b(neutral|gray|slate|zinc|stone)-[0-9]{2,3}\b' <path>

ステップ 4：コンポーザビリティ

コンポーネントを変更せずに再利用できることを確認してください。

• className プロパティを受け取り、cn() を使ってマージします
• バリエーションが想定される場合は、CVA でバリアントを公開します
• コンテンツをハードコードせず、children またはコンテンツ形式のプロパティを受け取ります
• 特定のデータモデルやルートに密結合していません

ステップ 5：レスポンシブ対応とアクセシビリティ

• モバイルファーストの基準（768px 未満のデザイン）とし、md:、lg: で段階的に機能を拡張します
• インタラクティブ要素のタッチターゲットは最小約44pxにします
• オーバーフローを防ぐため、flex の子要素に min-w-0 を指定します
• セマンティック HTML を使います（ボタンはスタイルを設定した <div> ではなく <button> にします）
• フォーカス可視状態を設定します（focus-visible:ring-*、focus-visible:border-*）
• アニメーションは motion-safe: / prefers-reduced-motion に従います

拡張版チェックリストは references/review-checklist.md を参照してください。

基本パターン

CVA（Class Variance Authority）

バリアントは cva() で宣言し、VariantProps で型付けします。

import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-all",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        outline: "border bg-background hover:bg-accent",
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3 text-xs",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants>

新しいバリアントを追加し、ベースレイヤーは変更しないでください。

cn() ユーティリティ

clsx（条件分岐）と tailwind-merge（競合解決）を組み合わせます。className の合成には必ず使ってください。

import { cn } from "@/lib/utils"

<div className={cn(
  "base-classes",
  isActive && "active-classes",
  className // consumer overrides win
)} />

テーマ対応スタイリング

shadcn のテーマでは CSS 変数を使います（2025年以降は OKLCH ベース）。主な変数：--radius、--background、--foreground、--primary、--secondary、--accent、--muted、--card、--popover、--destructive、--border、--input、--ring。

ハードコードされた値ではなく、これらに対応する Tailwind のセマンティックなクラス名（rounded-md → --radius、bg-primary → --primary）を使ってください。

アニメーション

簡単な規約：

• ホバー／フォーカス／アクティブ：Tailwind のトランジション、150ms
• 色／状態のトランジション：200ms
• DOM 要素の表示／非表示：Radix の data-state と Tailwind の animate-in / animate-out、または Motion の AnimatePresence
• transform ベースのアニメーションでは、常に motion-safe: を尊重してください

詳しいガイドは references/animation-patterns.md を参照してください。

ビジュアルスタイルのリファレンス

shadcn には、npx shadcn create またはプリセットコード（CLI v4）で設定できる公式ビジュアルスタイルが5種類あります。

スタイル	密度	形状	代表的な用途
Vega	標準	クラシック	shadcn のデフォルトの外観
Nova	コンパクト	標準	高密度な UI、データ量の多いアプリ
Maia	ゆったり	ソフト／丸み（ピル型が多い）	コンシューマー向けアプリ、親しみやすいインターフェース
Lyra	標準	ボックス型／角張った形	開発者向けツール、等幅フォント
Mira	高密度	コンパクト	管理ダッシュボード、パワーユーザー

各スタイルは、スペーシングのスケール、境界線の角丸、コンポーネントの寸法に影響します。スタイルごとのスペーシングパターンとよくある間違いについては、references/theme-styles.md を参照してください。

プリセット（CLI v4 で追加）では、スタイル、テーマ、フォント、アイコン、角丸を1つの短いコードにまとめ、npx shadcn@latest apply --preset <code> で適用できます。レビュー時には、プロジェクトにプリセットが設定されている場合、それを確認してください。これらの規約の多くにおける信頼できる情報源です。

対象範囲：このスキルで適用しないこと

shadcn の標準仕様とプロジェクト固有の規約の違いを明確にしてください。このスキルでは shadcn の標準仕様に照らしてレビューします。プロジェクト固有の規約（例：「フォームフィールド間には常に gap-4 を使う」）は、このスキルではなく、プロジェクト独自のスタイルガイドまたはプロジェクト固有のスキルに記載してください。

判断に迷ったら、根拠を示してください。「shadcn のコンポーネントでは data-slot を使います。ボタンのソースは ui.shadcn.com/docs/components/button を参照してください」のように述べます。「このプロジェクトではフォームフィールド間に一貫して gap-4 を使っています」と述べる場合とは区別してください。

出力形式

優れたレビューでは、次のようにします。

1. レビューした内容を1行で要約します
2. 問題をカテゴリ別に分類します（構造、スペーシング、トークン、コンポーザビリティ、レスポンシブ／アクセシビリティ）
3. 各問題に重大度を付けます：✅ 問題なし、⚠️ 提案、❌ ブロッキング
4. 修正方法を示します。短く明確な修正はその場に記載し、複雑な場合は該当するパターンファイルを参照します
5. ユーザーが希望する場合に修正を適用することを提案します

ざっと確認できる形式にしてください。問題のない項目をくどく説明する必要はありません。良い点は ✅ の要約1行で十分です。

レビュー出力の例

## Review: `<PageHeader />`

**Structure** ✅ `data-slot` present, composition clean
**Spacing** ⚠️ Uses `space-y-4` in flex container — swap to `gap-4`
**Tokens** ❌ `text-neutral-500` on line 12 — use `text-muted-foreground`
**Composability** ✅ Accepts className, variant props via CVA
**Responsive/a11y** ⚠️ Missing `min-w-0` on flex child (may overflow on narrow screens)

Fixes:
- Line 8: `space-y-4` → `gap-4`
- Line 12: `text-neutral-500` → `text-muted-foreground`
- Line 18: Add `min-w-0` to wrapping `<div>`

Want me to apply these?

参考ファイル

• references/theme-styles.md — スタイルごとのスペーシング、形状、よくある間違い
• references/review-checklist.md — カテゴリ別の詳細な監査チェックリスト
• references/animation-patterns.md — タイミング、イージング、Radix の data-state、Motion のパターン

リソース

• 公式 shadcn ドキュメント： ui.shadcn.com
• コンポーネントリファレンス（最新）： npx shadcn@latest docs <component> — 最新のドキュメントとサンプル URL を返します
• プロジェクトコンテキスト： npx shadcn@latest info --json
• テーマ作成ツール： ui.shadcn.com/create
• TweakCN（インタラクティブなテーマエディター）： tweakcn.com