moai-library-shadcn

クイックリファレンス

エンタープライズ向け shadcn/ui コンポーネントライブラリのエキスパート

shadcn/cli v4、プリセットベースのデザインシステム、RTL サポート、統合された radix-ui パッケージ、OKLCH テーマ設定、最新の React アプリケーション向け AI 統合を網羅する、包括的な shadcn/ui の専門知識です。

主な機能：

• CLI v4：プリセットシステム、フレームワークテンプレート、移行コマンド、レジストリ管理
• コンポーネント：Radix UI と Base UI のプリミティブ、および統合された radix-ui パッケージ
• テーマ設定：OKLCH カラーシステム、CSS 変数、ダークモード、プリセットベースの設定
• RTL：論理 CSS プロパティを使用した、右から左へのファーストクラスのサポート
• AI 統合：shadcn/skills コンテキストシステム、AI アシスタント向け MCP サーバー
• レジストリ：カスタムコンポーネントの配布、フォントシステム、ブロックライブラリ

使用する場面：

• shadcn/ui コンポーネントライブラリのセットアップとカスタマイズ
• プリセットベースのデザインシステムの設定
• RTL レイアウトの実装または移行
• コンポーネント配布用のレジストリ作成
• shadcn/skills を使った AI 支援によるコンポーネントのスキャフォールディング

モジュール構成：

• コアコンセプト：このファイルでは、shadcn/ui の概要、アーキテクチャ、エコシステムを説明します
• CLI とレジストリ：cli-registry.md モジュールでは、CLI v4 のコマンド、プリセット、RTL、移行、レジストリを説明します
• コンポーネント：shadcn-components.md モジュールでは、コンポーネントライブラリとパターンを説明します
• テーマ設定：shadcn-theming.md モジュールでは、OKLCH カラーシステムとカスタマイズを説明します
• 高度なパターン：advanced-patterns.md モジュールでは、複雑な実装について説明します
• 最適化：optimization.md モジュールでは、パフォーマンスの調整について説明します

---

実装ガイド

shadcn/ui の概要

shadcn/ui は、Radix UI と Tailwind CSS で構築された再利用可能なコンポーネントのコレクションです。従来のコンポーネントライブラリとは異なり、npm パッケージではなく、プロジェクトにコピーして使用するコンポーネントのコレクションです。

主な利点として、コンポーネントを完全に制御して所有できること、Radix UI プリミティブ以外の依存関係がないこと、Tailwind CSS による完全なカスタマイズ、優れた型安全性を備えた TypeScript ファーストの設計、WCAG 2.1 AA 準拠のアクセシビリティが組み込まれていることが挙げられます。

アーキテクチャの理念：shadcn/ui コンポーネントは、スタイルが設定されていないアクセシブルなプリミティブを提供する Radix UI プリミティブを基盤として構築されています。Tailwind CSS はユーティリティファーストのスタイリングを提供します。TypeScript は全体を通じて型安全性を確保します。カスタマイズレイヤーにより、最終的な実装を完全に制御できます。

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

フォームコンポーネントには、Input、Select、Checkbox、Radio、Textarea があります。フォームのバリデーションは react-hook-form と Zod に統合されています。適切な ARIA ラベルにより、アクセシビリティが確保されています。

表示コンポーネントには、Card、Dialog、Sheet、Drawer、Popover があります。レスポンシブデザインのパターンが組み込まれています。ダークモードをサポートしています。

ナビゲーションコンポーネントには、Navigation Menu、Breadcrumb、Tabs、Pagination があります。キーボードナビゲーションのサポートが組み込まれています。フォーカス管理は自動的に処理されます。

データコンポーネントには、Table、Calendar、DatePicker、Charts があります。大規模なデータセット向けに仮想スクロールを利用できます。TanStack Table との統合もサポートされています。

フィードバックコンポーネントには、Alert、Toast、Progress、Badge、Avatar があります。ローディング状態とスケルトンを利用できます。エラーバウンダリーもサポートされています。

2026 年の新しいコンポーネントには、Empty、Field、Item、Button Group、Spinner、Kbd、Input Group があります。

インストールとセットアップ

手順 1：shadcn/cli v4 を使ってプロジェクトを初期化します。フレームワークテンプレート（Next.js、Vite、TanStack Start、React Router、Astro、または Laravel）を選択し、必要に応じてバンドルされたデザインシステム設定を含むプリセットを適用します。

手順 2：CLI が components.json 設定ファイルを生成します。フレームワークを検出し、Tailwind CSS（v3 または v4）を設定して、パスエイリアスを構成し、ベースとなるプリミティブライブラリ（Radix UI または Base UI）を選択します。

手順 3：add コマンドを使って、コンポーネントを個別に追加します。変更をプレビューするには --dry-run を、レジストリの更新内容を確認するには --diff を使います。shadcn info コマンドを実行すると、インストール済みのコンポーネントとプロジェクト設定が表示されます。

基盤技術

React 19 には、Server Components のサポート、並行レンダリング、自動バッチ処理、ストリーミング SSR などの機能があります。

TypeScript 5.9 は、完全な型安全性、改善された型推論、優れた開発者エクスペリエンスを提供します。

Tailwind CSS v4 には、CSS ファーストの設定、CSS 変数、OKLCH カラーのサポート、コンテナークエリなどが含まれています。

Radix UI は、統合された radix-ui パッケージを単一のインポートで使用します。代替のプリミティブライブラリとして Base UI も利用できます。

統合スタックには、フォームの状態管理に React Hook Form、スキーマ検証に Zod、バリアントに class-variance-authority、アニメーションに Framer Motion、アイコンに Lucide React が含まれています。

AI を活用したアーキテクチャ設計

ShadcnUIArchitectOptimizer クラスは、Context7 MCP 統合を使用して最適な shadcn/ui アーキテクチャを設計します。Context7 クライアント、コンポーネントアナライザー、テーマオプティマイザーを初期化します。design_optimal_shadcn_architecture メソッドは、デザインシステムの要件を受け取り、Context7 経由で shadcn/ui と React の最新ドキュメントを取得します。次に、UI コンポーネントとユーザーのニーズに基づいてコンポーネント選択を最適化し、ブランドガイドラインとアクセシビリティ要件に基づいてテーマ設定を最適化して、コンポーネントライブラリ、テーマシステム、アクセシビリティへの準拠、パフォーマンス最適化、統合パターン、カスタマイズ戦略を含む完全な ShadcnUIArchitecture を返します。

ベストプラクティス

要件には、テーマのカスタマイズに CSS 変数を使用すること、適切な TypeScript 型を実装すること、WCAG 2.1 AA 準拠のアクセシビリティガイドラインに従うこと、複雑なインタラクションに Radix UI のプリミティブを使用すること、React Testing Library でコンポーネントをテストすること、ツリーシェイキングでバンドルサイズを最適化すること、レスポンシブデザインパターンを実装することが含まれます。

重要な実装基準：

[HARD] 色の値には CSS 変数のみを使用してください。これにより、動的なテーマ設定が可能になり、ダークモードの切り替えがサポートされ、すべてのコンポーネントでデザインシステムの一貫性が保たれます。CSS 変数を使用しない場合、テーマを変更するにはコードの修正が必要になり、ダークモードが機能せず、ブランドのカスタマイズが保守困難になります。

[HARD] すべてのインタラクティブ要素にアクセシビリティ属性を含めてください。これにより、WCAG 2.1 AA 準拠、スクリーンリーダーとの互換性、障害のあるユーザーを含むすべての人にとって使いやすいエクスペリエンスが実現します。アクセシビリティ属性が不足すると、障害のあるユーザーが排除され、法令遵守要件に違反し、アプリケーションの使いやすさが低下します。

[HARD] すべてのインタラクティブコンポーネントでキーボードナビゲーションを実装してください。これにより、キーボードユーザーに不可欠なナビゲーション手段が提供され、支援技術がサポートされ、全体的なユーザーエクスペリエンスの効率が向上します。キーボードナビゲーションがないと、パワーユーザーがアプリケーションを効率的に利用できず、アクセシビリティ要件にも準拠できません。

[SOFT] 非同期処理のローディング状態を表示してください。これにより、処理の進行状況がユーザーに伝わり、体感レイテンシが低減し、アプリケーションの応答性に対するユーザーの信頼が高まります。

[HARD] コンポーネントツリーの周囲にエラーバウンダリーを実装してください。これにより、個別のコンポーネント障害によるアプリケーション全体のクラッシュを防ぎ、適切なエラー回復を可能にし、アプリケーションの安定性を保てます。

[HARD] インラインスタイルではなく Tailwind CSS クラスを適用してください。これにより、デザインシステムとの一貫性が保たれ、JIT コンパイルのメリットを活用でき、レスポンシブデザインのバリアントがサポートされ、バンドルサイズの最適化が向上します。

[SOFT] すべてのコンポーネントでダークモードをサポートしてください。これにより、ユーザーの好みに配慮し、暗い環境での目の疲れを軽減し、現代的な UI への期待に応えられます。

パフォーマンスの最適化

バンドルサイズの最適化では、未使用のコンポーネントを削除するツリーシェイキング、大きなコンポーネントのコード分割、React.lazy による遅延読み込み、負荷の高い依存関係の動的インポートを行います。

ランタイムパフォーマンスの最適化では、処理コストの高いコンポーネントに React.memo を使用し、計算に useMemo と useCallback を使用します。また、大きなリストには仮想スクロールを使用し、ユーザー操作にはデバウンスを適用します。

アクセシビリティでは、すべてのインタラクティブ要素に ARIA 属性を設定し、キーボードナビゲーションをサポートして、フォーカスを管理し、スクリーンリーダーでテストします。

---

高度なパターン

コンポーネントの合成

合成可能なパターンでは、ui/card コンポーネントから Card、CardHeader、CardTitle、CardContent をインポートします。DashboardCard コンポーネントは title と children の各プロパティを受け取り、Card の構造でラップします。この構造では、CardHeader に CardTitle を、CardContent に children を含めます。

フォームの検証

Zod と React Hook Form の統合パターンでは、react-hook-form から useForm、hookform/resolvers/zod から zodResolver、zod から z をインポートします。z.object を使用して formSchema を定義し、メールアドレスには z.string().email()、パスワードには z.string().min(8) などのフィールド検証を指定します。スキーマから FormValues 型を推論します。フォームコンポーネントでは、formSchema を渡した zodResolver とともに useForm を使用します。フォーム要素では、onSubmit ハンドラーを指定して form.handleSubmit を使用します。

---

併用すると効果的なもの

• CLI v4 のコマンド、プリセット、RTL、マイグレーション、レジストリについては modules/cli-registry.md
• 高度なコンポーネントパターンと実装については shadcn-components.md モジュール
• OKLCH テーマシステムとカスタマイズ戦略については shadcn-theming.md モジュール
• デザインシステムのアーキテクチャと原則については moai-domain-uiux
• TypeScript のベストプラクティスについては moai-lang-typescript
• フロントエンド開発パターンについては code-frontend

---

Context7 との統合

関連ライブラリ：

• /shadcn-ui/ui の shadcn/ui は、Radix UI と Tailwind で構築された再利用可能なコンポーネントを提供します
• /radix-ui/primitives の Radix UI は、スタイルを持たないアクセシブルなコンポーネントのプリミティブを提供します
• /tailwindlabs/tailwindcss の Tailwind CSS は、ユーティリティファーストの CSS フレームワークを提供します

公式ドキュメント：

• shadcn/ui ドキュメント（ui.shadcn.com/docs）
• CLI リファレンス（ui.shadcn.com/docs/cli）
• MCP サーバー（ui.shadcn.com/docs/mcp）
• Radix UI ドキュメント（radix-ui.com）
• Tailwind CSS ドキュメント（tailwindcss.com）

2026年3月時点の最新バージョン：

• shadcn/cli v4
• React 19
• TypeScript 5.9+
• Tailwind CSS v4
• 統合された radix-ui パッケージ

---

最終更新日：2026-03-28 ステータス：本番環境で利用可能