shadcn-ui

shadcn/ui コンポーネント

テーマ設定済みの React プロジェクトに shadcn/ui コンポーネントを追加します。このスキルは、tailwind-theme-builder が CSS 変数、ThemeProvider、ダークモードを設定した後に実行します。コンポーネントのインストール、カスタマイズ、コンポーネントを組み合わせた実用的なパターンの構築を行います。

前提条件：テーマの基盤（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 — 空文字列は使用不可

// Don't use empty string values
<SelectItem value="">All</SelectItem>           // BREAKS

// Use sentinel value
<SelectItem value="__any__">All</SelectItem>    // WORKS
const actual = value === "__any__" ? "" : value

React Hook Form — Null 値

// Don't spread {...field} — it passes null which Input rejects
<Input
  value={field.value ?? ''}
  onChange={field.onChange}
  onBlur={field.onBlur}
  name={field.name}
  ref={field.ref}
/>

Lucide Icons — ツリーシェイキング

// Don't use dynamic import — icons get tree-shaken in production
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName]  // BREAKS in prod

// Use explicit map
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]

Dialog の幅のオーバーライド

// Default sm:max-w-lg won't be overridden by max-w-6xl
<DialogContent className="max-w-6xl">       // DOESN'T WORK

// Use same breakpoint prefix
<DialogContent className="sm:max-w-6xl">    // WORKS

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

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

バリアントの拡張

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

// button.tsx — add a "brand" variant
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      brand: "bg-brand text-brand-foreground hover:bg-brand/90",
      // ... existing variants
    },
  },
})

色のオーバーライド

テーマのセマンティックトークンを使用し、Tailwind の色を直接指定しないでください。

// Don't use raw colours
<Button className="bg-blue-500">             // WRONG

// Use semantic tokens
<Button className="bg-primary">              // RIGHT
<Card className="bg-card text-card-foreground">  // RIGHT

ワークフロー

ステップ 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 を参照してください。

• お問い合わせフォーム — Form + Input + Textarea + Button + Toast
• データテーブル — Table + 列のソート + Pagination + 検索
• モーダル CRUD — Dialog + Form + Button
• ナビゲーション — Sheet + NavigationMenu + ModeToggle
• 設定ページ — Tabs + Form + Switch + Select + Toast

ステップ 4：カスタマイズする

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

参考ファイル

用途	参照先
コンポーネントの選択、インストールコマンド、props	references/component-catalogue.md
UI パターン全体の構築	references/recipes.md