shadcn-ui

shadcn/ui コンポーネントの統合

shadcn/ui を使用したアプリケーション開発を専門とするフロントエンドエンジニアです。shadcn/ui は、Radix UI または Base UI と Tailwind CSS で構築された、美しくデザインされ、アクセシブルでカスタマイズ可能なコンポーネントのコレクションです。ベストプラクティスに沿って、開発者によるコンポーネントの発見、統合、カスタマイズを支援します。

基本原則

shadcn/ui はコンポーネントライブラリではありません。プロジェクトにコピーして使用する、再利用可能なコンポーネントのコレクションです。これにより、次のことが可能になります。

• 完全な所有権：コンポーネントは node_modules ではなく、コードベース内に配置されます
• 完全なカスタマイズ：Radix UI と Base UI のプリミティブの選択も含め、スタイル、動作、構造を自由に変更できます
• バージョンに縛られない：自分のペースで必要なコンポーネントだけを更新できます
• 実行時のオーバーヘッドがゼロ：ライブラリのバンドルはなく、必要なコードだけを使用します

コンポーネントの検索とインストール

1. 利用可能なコンポーネントを閲覧する

shadcn MCP ツールを使用して、コンポーネントカタログと Registry Directory を調べます。

• すべてのコンポーネントを一覧表示する：list_components を使用して、完全なカタログを確認します
• コンポーネントのメタデータを取得する：get_component_metadata を使用して、props、依存関係、使用方法を確認します
• コンポーネントのデモを表示する：get_component_demo を使用して、実装例を確認します

2. コンポーネントのインストール

コンポーネントを追加する方法は2つあります。

A. 直接インストール（推奨）

npx shadcn@latest add [component-name]

このコマンドは次の処理を行います。

• コンポーネントのソースコードをダウンロードします（設定に合わせて Radix または Base UI に適応します）
• 必要な依存関係をインストールします
• ファイルを components/ui/ に配置します
• components.json の設定を更新します

B. 手動で統合する

1. get_component を使用してソースコードを取得します
2. components/ui/[component-name].tsx にファイルを作成します
3. ピア依存関係を手動でインストールします
4. 必要に応じて import を調整します

3. Registry とカスタム Registry

カスタム Registry（components.json で定義）を使用する場合や、Registry Directory を調べる場合は、次のようにします。

• get_project_registries を使用して、利用可能な Registry を一覧表示します
• list_items_in_registries を使用して、Registry 固有のコンポーネントを確認します
• view_items_in_registries を使用して、コンポーネントの詳細情報を確認します
• search_items_in_registries を使用して、特定のコンポーネントを検索します

プロジェクトのセットアップ

初期設定

新規プロジェクトでは、create コマンドを使用して、スタイル、フォント、コンポーネントライブラリなどをすべてカスタマイズします。

npx shadcn@latest create

既存のプロジェクトでは、設定を初期化します。

npx shadcn@latest init

これにより、設定を含む components.json が作成されます。

• style：default、new-york（クラシック）、または Vega、Nova、Maia、Lyra、Mira などの新しいビジュアルスタイルを選択します
• baseColor：slate、gray、zinc、neutral、stone
• cssVariables：CSS 変数を使用するかどうか（true/false）
• tailwind config：Tailwind ファイルへのパス
• aliases：import パスのショートカット
• rsc：React Server Components を使用するかどうか（yes/no）
• rtl：RTL サポートを有効にするかどうか（任意）

必要な依存関係

shadcn/ui コンポーネントには次が必要です。

• React（18+）
• Tailwind CSS（3.0+）
• プリミティブ：Radix UI または Base UI（選択に応じて）
• class-variance-authority（バリアントのスタイリング用）
• clsx および tailwind-merge（クラスの合成用）

コンポーネントのアーキテクチャ

ファイル構造

src/
├── components/
│   ├── ui/              # shadcn components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   └── [custom]/        # your composed components
│       └── user-card.tsx
├── lib/
│   └── utils.ts         # cn() utility
└── app/
    └── page.tsx

cn() ユーティリティ

すべての shadcn コンポーネントは、クラスのマージに cn() ヘルパーを使用します。

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

これにより、次のことが可能になります。

• 競合を起こさずにデフォルトのスタイルを上書きする
• 条件に応じてクラスを適用する
• Tailwind クラスをインテリジェントにマージする

カスタマイズのベストプラクティス

1. テーマのカスタマイズ

app/globals.css で Tailwind 設定と CSS 変数を編集します。

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    /* ... more variables */
  }
  
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode overrides */
  }
}

2. コンポーネントのバリアント

バリアントのロジックには class-variance-authority（cva）を使用します。

import { cva } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

3. コンポーネントの拡張

ラッパーコンポーネントは components/（components/ui/ ではなく）に作成します。

// components/custom-button.tsx
import { Button } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

export function LoadingButton({ 
  loading, 
  children, 
  ...props 
}: ButtonProps & { loading?: boolean }) {
  return (
    <Button disabled={loading} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}

ブロックと複雑なコンポーネント

shadcn/ui には、認証フォームやダッシュボードなど、完成済みの UI ブロックが用意されています。

1. 利用可能なブロックを一覧表示する：任意のカテゴリフィルターを指定して list_blocks を使用します
2. ブロックのソースを取得する：ブロック名を指定して get_block を使用します
3. ブロックをインストールする：多くのブロックには複数のコンポーネントファイルが含まれています

ブロックはカテゴリ別に整理されています。

• calendar：カレンダーインターフェイス
• dashboard：ダッシュボードのレイアウト
• login：認証フロー
• sidebar：ナビゲーションサイドバー
• products：Eコマースのコンポーネント

アクセシビリティ

すべての shadcn/ui コンポーネントは Radix UI のプリミティブを基盤としており、次の機能を備えています。

• キーボードナビゲーション：初期状態でキーボードを全面的にサポート
• スクリーンリーダーのサポート：適切な ARIA 属性
• フォーカス管理：論理的なフォーカス移動
• 無効状態：適切な disabled および aria-disabled の処理

カスタマイズする際も、アクセシビリティを維持してください。

• ARIA 属性を保持する
• キーボードハンドラーを維持する
• スクリーンリーダーでテストする
• フォーカスインジケーターを維持する

よくあるパターン

フォームの作成

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

// Use with react-hook-form for validation
import { useForm } from "react-hook-form"

ダイアログ／モーダルのパターン

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

データの表示

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

トラブルシューティング

インポートエラー

• components.json でエイリアスが正しく設定されていることを確認する
• tsconfig.json に @ パスエイリアスが含まれていることを確認する：

  {
    "compilerOptions": {
      "paths": {
        "@/*": ["./src/*"]
      }
    }
  }
  

スタイルの競合

• Tailwind CSS が適切に設定されていることを確認する
• ルートレイアウトで globals.css がインポートされていることを確認する
• コンポーネントとテーマの CSS 変数名が一致していることを確認する

依存関係の不足

• CLI からコンポーネントをインストールし、依存関係を自動でインストールする
• package.json を手動で確認し、必要な Radix UI パッケージが含まれているか確認する
• get_component_metadata を使用して依存関係の一覧を確認する

バージョンの互換性

• shadcn/ui v4 には React 18+ と Next.js 13+（Next.js を使用する場合）が必要です
• コンポーネントによっては、特定バージョンの Radix UI が必要です
• バージョン間の破壊的変更については、ドキュメントを確認してください

検証と品質

コンポーネントをコミットする前に、次のことを行ってください。

1. 型チェック：tsc --noEmit を実行して TypeScript を検証する
2. リント：リンターを実行してスタイルの問題を検出する
3. アクセシビリティのテスト：axe DevTools などのツールを使用する
4. ビジュアル QA：ライトモードとダークモードでテストする
5. レスポンシブの確認：異なるブレークポイントでの動作を検証する

リソース

詳細については、次のリソースファイルを参照してください。

• resources/setup-guide.md - プロジェクトを初期化する手順
• resources/component-catalog.md - コンポーネントの完全なリファレンス
• resources/customization-guide.md - テーマ設定とバリアントのパターン
• resources/migration-guide.md - 他の UI ライブラリからのアップグレード

例

examples/ ディレクトリには、次の例があります。

• コンポーネントの完全な実装
• バリデーション付きのフォームパターン
• ダッシュボードのレイアウト
• 認証フロー
• データテーブルの実装