component-library

Component Library - shadcn/ui Architecture

shadcn/ui のパターンを使用して、本番環境ですぐに使える React コンポーネントを生成し、プロジェクトごとに 8〜10 時間を節約できます。

クイックスタート

コンポーネントを生成する際は、以下を行います。

1. /components/ui/ のディレクトリ構成を作成する
2. 最初に cn() ヘルパーを含む lib/utils.ts を生成する
3. 要求されたコンポーネントを、完全な TypeScript、バリアント、アクセシビリティ対応とともに作成する
4. 各コンポーネントの使用例を含める

コアセットアップファイル

常に最初に以下を生成します。

lib/utils.ts - 必須の cn() ヘルパー：

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

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

components.json - コンポーネントレジストリ：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

コンポーネントのカテゴリ

フォームコンポーネント

• Input - バリアント（default、ghost、underline）を備えたテキスト入力
• Select - 検索と複数選択オプションを備えたカスタムドロップダウン
• Checkbox - indeterminate 状態に対応
• Radio - カスタムスタイルのラジオグループ
• Switch - ラベル付きのトグルスイッチ
• Textarea - 自動リサイズ、文字数カウントのバリアント
• DatePicker - カレンダー連携、範囲選択
• FileUpload - ドラッグ＆ドロップ、プレビュー、進捗表示
• Slider - マークとツールチップを備えた範囲入力
• Form - バリデーション機能を備えた React Hook Form ラッパー

表示コンポーネント

• Card - ヘッダー／フッター用スロットを備えたコンテナー
• Table - 並べ替え、フィルター、ページネーションに対応
• Badge - バリアントを備えたステータスインジケーター
• Avatar - 画像／イニシャルとフォールバック
• Progress - 線形および円形のバリアント
• Skeleton - 読み込み状態
• Separator - 視覚的な区切り線
• ScrollArea - カスタムスクロールバー

フィードバックコンポーネント

• Alert - 情報／警告／エラー／成功の各状態
• Toast - アクション付き通知
• Dialog/Modal - アクセシブルなオーバーレイ
• Tooltip - ホバー時の情報表示
• Popover - 配置可能なコンテンツ
• AlertDialog - 確認ダイアログ

ナビゲーションコンポーネント

• Navigation - モバイルメニューを備えたレスポンシブナビゲーション
• Tabs - キーボード操作に対応したタブパネル
• Breadcrumb - パスナビゲーション
• Pagination - ページ操作
• CommandMenu - コマンドパレット（⌘K）
• ContextMenu - 右クリックメニュー
• DropdownMenu - アクションメニュー

レイアウトコンポーネント

• Accordion - 折りたたみ可能なセクション
• Collapsible - コンテンツの表示／非表示
• ResizablePanels - ドラッグ可能な分割ペイン
• Sheet - スライド式パネル
• AspectRatio - アスペクト比を維持

コンポーネントの実装パターン

すべてのバリアントに CVA を使用します。

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

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

アクセシビリティ要件：

• すべてのインタラクティブ要素に ARIA ラベルとロールを設定する
• キーボード操作（Tab、矢印キー、Enter、Escape）
• モーダルのフォーカス管理とフォーカストラップ
• スクリーンリーダーへの通知
• セマンティックな HTML 要素

ダークモード対応：

• Tailwind の dark: 修飾子を使用する
• テーマカラーには CSS 変数を使用する
• モード間の切り替えをスムーズにする

レスポンシブデザイン：

• モバイルファーストのアプローチ
• 適切な場合はコンテナクエリを使用する
• タッチ操作しやすいタップ領域（最小 44x44px）
• レスポンシブなタイポグラフィのスケール

依存関係

package.json に以下を含めます。

{
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-avatar": "^1.0.4",
    "@radix-ui/react-checkbox": "^1.0.4",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-popover": "^1.0.7",
    "@radix-ui/react-progress": "^1.0.3",
    "@radix-ui/react-radio-group": "^1.1.3",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slider": "^1.1.2",
    "@radix-ui/react-switch": "^1.0.3",
    "@radix-ui/react-tabs": "^1.0.4",
    "@radix-ui/react-toast": "^1.1.5",
    "@radix-ui/react-tooltip": "^1.0.7",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "cmdk": "^0.2.0",
    "date-fns": "^2.30.0",
    "lucide-react": "^0.263.1",
    "react-day-picker": "^8.8.0",
    "react-hook-form": "^7.45.4",
    "tailwind-merge": "^1.14.0",
    "tailwindcss-animate": "^1.0.7"
  }
}

実装ワークフロー

1. 要件を評価する：必要なコンポーネントを特定します
2. ベースファイルを生成する：utils.ts と components.json を作成します
3. コンポーネントを作成する：要求されたコンポーネントを、すべての機能とともに生成します
4. 使用例を提示する：各コンポーネントの使用例を含めます
5. Props をドキュメント化する：JSDoc コメント付きの TypeScript インターフェースを追加します

高度なパターン

複雑な要件については、以下を参照してください。

• references/form-patterns.md - 高度なフォーム処理
• references/data-tables.md - 複雑なテーブルの実装
• references/animation-patterns.md - Framer Motion との連携
• references/testing-setup.md - コンポーネントのテストパターン

パフォーマンスの最適化

• コストの高いコンポーネントには React.memo を使用する
• 長いリストには仮想スクロールを実装する
• 重いコンポーネントは遅延読み込みする
• ツリーシェイキングでバンドルサイズを最適化する
• レイアウトの安定性には CSS containment を使用する

コンポーネント生成のヒント

コンポーネントを生成する際は、以下を行います。

• すべてのバリアントの組み合わせを含めます
• 適切な TypeScript 型を追加します
• キーボードショートカットを実装します
• 読み込み状態とエラー状態を含めます
• Storybook のストーリー構成を用意します
• プロパティの包括的なドキュメントを追加します
• アクセシビリティ属性を含めます
• スクリーンリーダーでテストします