shadcn/ui コンポーネント

テーマ化されたReactプロジェクトにshadcn/uiコンポーネントを追加します。このスキルは tailwind-theme-builder がCSS変数、ThemeProvider、ダークモードをセットアップした AFTER に実行されます。コンポーネントのインストール、カスタマイズ、およびコンポーネントを動作するパターンに組み合わせることを処理します。

前提条件: テーマインフラストラクチャが存在する必要があります (CSS変数、components.json、cn()ユーティリティ)。セットアップされていない場合は、まず tailwind-theme-builder を使用してください。

インストール順序

依存関係の順序でコンポーネントをインストールします。基盤コンポーネントを最初にインストールしてから、機能コンポーネントをインストールします:

基盤 (最初にインストール)

pnpm dlx shadcn@latest add button
pnpm dlx shadcn@latest add input label
pnpm dlx shadcn@latest add card

機能コンポーネント (必要に応じてインストール)

# Forms
pnpm dlx shadcn@latest add form        # needs: react-hook-form, zod, @hookform/resolvers
pnpm dlx shadcn@latest add textarea select checkbox switch

# Feedback
pnpm dlx shadcn@latest add toast        # needs: sonner
pnpm dlx shadcn@latest add alert badge

# Overlay
pnpm dlx shadcn@latest add dialog sheet popover dropdown-menu

# Data Display
pnpm dlx shadcn@latest add table        # for data tables, also: @tanstack/react-table
pnpm dlx shadcn@latest add tabs separator avatar

# Navigation
pnpm dlx shadcn@latest add navigation-menu command

外部依存関係

コンポーネント	必須
Form	react-hook-form, zod, @hookform/resolvers
Toast	sonner
Data Table	@tanstack/react-table
Command	cmdk
Date Picker	date-fns (オプション)

外部依存関係を別途インストール: pnpm add react-hook-form zod @hookform/resolvers

既知の落とし穴

これらは一般的なバグを防ぐための文書化された修正です:

Radix Select — 空の文字列なし

// 空の文字列値を使用しないでください
<SelectItem value="">All</SelectItem>           // 壊れます

// センチネル値を使用します
<SelectItem value="__any__">All</SelectItem>    // 動作します
const actual = value === "__any__" ? "" : value

React Hook Form — Null値

// {...field}をスプレッドしないでください — nullを渡してInputが拒否します
<Input
  value={field.value ?? ''}
  onChange={field.onChange}
  onBlur={field.onBlur}
  name={field.name}
  ref={field.ref}
/>

Lucide Icons — Tree-Shaking

// 動的インポートを使用しないでください — 本番環境ではアイコンがツリーシェイクされます
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName]  // 本番環境で壊れます

// 明示的なマップを使用します
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]

Dialog幅のオーバーライド

// デフォルトのsm:max-w-lgはmax-w-6xlでオーバーライドされません
<DialogContent className="max-w-6xl">       // 動作しません

// 同じブレークポイント接頭辞を使用します
<DialogContent className="sm:max-w-6xl">    // 動作します

コンポーネントのカスタマイズ

shadcnコンポーネントはテーマからのセマンティックCSSトークンを使用します。カスタマイズするには:

バリアント拡張

src/components/ui/ のコンポーネントファイルを編集してカスタムバリアントを追加します:

// button.tsx — "brand"バリアントを追加
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      brand: "bg-brand text-brand-foreground hover:bg-brand/90",
      // ... existing variants
    },
  },
})

色のオーバーライド

テーマからのセマンティックトークンを使用します — 生のTailwind色は使用しないでください:

// 生の色を使用しないでください
<Button className="bg-blue-500">             // 間違い

// セマンティックトークンを使用します
<Button className="bg-primary">              // 正解
<Card className="bg-card text-card-foreground">  // 正解

ワークフロー

ステップ1: ニーズを評価

プロジェクトが必要とするUIパターンを決定します:

ニーズ	コンポーネント
検証を使用したフォーム	Form, Input, Label, Select, Textarea, Button, Toast
ソート機能付きデータ表示	Table, Badge, Pagination
管理CRUD インターフェース	Dialog, Form, Table, Button, Toast
マーケティング/ランディングページ	Card, Button, Badge, Separator
設定/環境設定	Tabs, Form, Switch, Select, Toast
ナビゲーション	NavigationMenu (デスクトップ), Sheet (モバイル), ModeToggle

ステップ2: コンポーネントをインストール

基盤を最初にインストールしてから、特定されたニーズの機能コンポーネントをインストールします。上記のコマンドを使用してください。

ステップ3: レシピを構築

コンポーネントを動作するパターンに組み合わせます。完全な動作例については references/recipes.md を参照してください:

• Contact Form — Form + Input + Textarea + Button + Toast
• Data Table — Table + Column sorting + Pagination + Search
• Modal CRUD — Dialog + Form + Button
• Navigation — Sheet + NavigationMenu + ModeToggle
• Settings Page — Tabs + Form + Switch + Select + Toast

ステップ4: カスタマイズ

テーマからのセマンティックトークンを使用して、プロジェクト固有の色とバリアントを適用します。

リファレンスファイル

用途	読む
コンポーネント選択、インストールコマンド、プロップ	references/component-catalogue.md
完全なUIパターンの構築	references/recipes.md