Geruyang/agent-skills-library

shadcn/ui

あなたは shadcn/ui のエキスパートです。shadcn/ui は、Radix UI プリミティブと Tailwind CSS をベースにした、美しくデザインされ、アクセシブルでカスタマイズ可能な React コンポーネントのコレクションです。コンポーネントは依存関係としてインストールされるのではなく、ソースコードとしてコードベースに直接追加されます。

主要な概念

shadcn/ui は従来の意味での コンポーネントライブラリではありません。パッケージとしてインストールするものではありません。代わりに、CLI がコンポーネントのソースコードをプロジェクトにコピーし、完全な所有権とカスタマイズ機能を提供します。

CLI コマンド

初期化（非対話型 — 常にこれを使用）

重要: shadcn init はデフォルトで対話型です。非対話型の初期化には常に -d（デフォルト）を使用してください：

# デフォルトで非対話型 init — これを使用
npx shadcn@latest init -d

# プリセットを使用した非対話型 init（一貫したデザインシステムに推奨）
npx shadcn@latest init --preset <code> -f

# 明示的なベースライブラリ選択による非対話型 init
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# フルプロジェクトテンプレートのスキャフォールディング（CLI v4）

AI Elements の互換性: プロジェクトが AI Elements を使用する、または使用する可能性がある場合は、常に --base radix（デフォルト）を使用してください。AI Elements コンポーネントは Radix API に依存しており、Base UI では型エラーが発生します。

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

オプション:

• -d, --defaults — デフォルト設定を使用し、すべての対話型プロンプトをスキップ（CI/エージェント利用に必須）
• -y, --yes — 確認プロンプトをスキップ（ライブラリ選択はスキップしません — 代わりに -d を使用）
• -f, --force — 既存の設定を強制的に上書き
• -t, --template — フルプロジェクトテンプレートをスキャフォールディング（next、vite、react-router、astro、laravel、tanstack-start）
• --preset — デザインシステムプリセット（色、テーマ、アイコン、フォント、半径）を単一の共有可能なコードとして適用
• --base — プリミティブライブラリを選択: radix（デフォルト）または base-ui
• --monorepo — モノレポ構造をセットアップ

警告: -y/--yes だけでは init は完全に非対話型にはなりません — コンポーネントライブラリの選択を求められます。すべてのプロンプトをスキップするには常に -d を使用してください。

CLI v4 で非推奨: --style、--base-color、--src-dir、--no-base-style、--css-variables フラグは削除され、エラーになります。registry:build および registry:mcp レジストリタイプも非推奨です。代わりに registry:base と registry:font を使用してください。

init コマンドは:

1. フレームワーク（Next.js、Vite、React Router、Astro、Laravel、TanStack Start）を検出
2. 必要な依存関係（Radix UI、tailwind-merge、class-variance-authority）をインストール
3. components.json 設定を作成
4. cn() ユーティリティ関数をセットアップ
5. テーマ設定用の CSS 変数を構成

コンポーネントの追加

# 特定のコンポーネントを追加
npx shadcn@latest add button dialog card

# 利用可能なすべてのコンポーネントを追加
npx shadcn@latest add --all

# カスタムレジストリから追加
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# AI Elements レジストリから追加
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

オプション:

• -o, --overwrite — 既存のファイルを上書き
• -p, --path — カスタムインストールパス
• -a, --all — すべてのコンポーネントをインストール
• --dry-run — ファイルを書き込まずに追加される内容をプレビュー
• --diff — 既存のコンポーネントを更新する際の差分を表示
• --view — レジストリアイテムのソースコードをインラインで表示

検索と一覧表示

npx shadcn@latest search button
npx shadcn@latest list @v0

ビルド（カスタムレジストリ）

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

表示、情報、ドキュメント（CLI v4）

# インストール前にレジストリアイテムのソースを表示
npx shadcn@latest view button

# プロジェクト診断を表示 — 設定、インストール済みコンポーネント、依存関係
npx shadcn@latest info

# 任意のコンポーネントのドキュメント、コード、例を取得（エージェントフレンドリーな出力）
npx shadcn@latest docs button
npx shadcn@latest docs dialog

shadcn docs はコーディングエージェントにプリミティブを正しく使用するためのコンテキストを提供します — コード例、API リファレンス、使用パターンをインラインで返します。

移行

npx shadcn@latest migrate rtl    # RTL サポート移行
npx shadcn@latest migrate radix  # 統合 radix-ui パッケージへの移行
npx shadcn@latest migrate icons  # アイコンライブラリの変更

# デフォルトの ui ディレクトリ外のコンポーネントを移行
npx shadcn@latest migrate radix src/components/custom

shadcn/skills（CLI v4）

shadcn/skills は、コーディングエージェントがコンポーネントとレジストリを正しく操作するために必要なコンテキストを提供します。Radix と Base UI の両方のプリミティブ、更新された API、コンポーネントパターン、レジストリワークフローをカバーしています。このスキルは CLI の使用方法、呼び出すタイミング、渡すフラグを知っているため、エージェントはデザインシステムに一致するコードを生成できます。

インストール: pnpm dlx skills add shadcn/ui

統合 Radix UI パッケージ（2026年2月）

new-york スタイルは、個別の @radix-ui/react-* パッケージの代わりに、単一の radix-ui パッケージを使用するようになりました:

// 旧 — 個別パッケージ
import * as DialogPrimitive from "@radix-ui/react-dialog"

// 新 — 統合パッケージ
import { Dialog as DialogPrimitive } from "radix-ui"

既存のプロジェクトを移行するには: npx shadcn@latest migrate radix。移行後、package.json から未使用の @radix-ui/react-* パッケージを削除してください。

Base UI サポート（2026年1月）

shadcn/ui は、基本となるプリミティブライブラリとして Radix UI に代わる Base UI をサポートするようになりました。コンポーネントは、選択したライブラリに関係なく、同じように見え、動作します — 変更されるのは内部実装のみです。

init 時に選択: npx shadcn@latest init --base base-ui

CLI はプロジェクト設定に基づいて、正しいコンポーネントバリアントを自動的に取得します。

設定（components.json）

components.json ファイルは、プロジェクトでの shadcn/ui の動作を設定します:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",  // オプション: gray, neutral, slate, stone, zinc, mauve, olive, mist, taupe
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "v0": {
      "url": "https://v0.dev/chat/api/registry"
    },
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

名前空間付きレジストリ

プロジェクトに複数のレジストリを設定:

{
  "registries": {
    "acme": {
      "url": "https://acme.com/registry/{name}.json"
    },
    "private": {
      "url": "https://internal.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

名前空間構文を使用してインストール:

npx shadcn@latest add @acme/header @private/auth-form

テーマ設定

CSS 変数

shadcn/ui はテーマ設定に CSS カスタムプロパティを使用し、globals.css で定義します:

@theme inline {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.488 0.243 264.376);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.269 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.396 0.141 25.723);
  --color-border: oklch(0.269 0 0);
  --color-input: oklch(0.269 0 0);
  --color-ring: oklch(0.488 0.243 264.376);
  --radius: 0.625rem;
  /* CLI v4: 半径トークンは加算ではなく乗算計算を使用 */
  --radius-xs: calc(var(--radius) * 0.5);
  --radius-sm: calc(var(--radius) * 0.75);
  --radius-md: calc(var(--radius) * 0.875);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.5);
}

ダークモード

ダークモードを使用するには、<html> に dark クラスを使用します:

// app/layout.tsx
<html lang="en" className="dark">

または、next-themes を使用して切り替えます:

import { ThemeProvider } from 'next-themes'

<ThemeProvider attribute="class" defaultTheme="dark">
  {children}
</ThemeProvider>

カスタムカラー

shadcn のデフォルトに加えてアプリケーション固有の色を追加:

@theme inline {
  /* 上記の shadcn デフォルト... */

  /* カスタムアプリカラー */
  --color-priority-urgent: oklch(0.637 0.237 15.163);
  --color-priority-high: oklch(0.705 0.213 47.604);
  --color-status-done: oklch(0.723 0.219 149.579);
}

コンポーネントで使用:

<span className="text-[var(--color-priority-urgent)]">Urgent</span>
// または Tailwind v4 theme() を使用:
<span className="text-priority-urgent">Urgent</span>

最も一般的なコンポーネント

コンポーネント	ユースケース
button	アクション、フォーム送信
card	コンテンツコンテナ
dialog	モーダル、確認プロンプト
input / textarea	フォームフィールド
select	ドロップダウン
table	データ表示
tabs	ビュー切り替え
command	コマンドパレット（Cmd+K）
dropdown-menu	コンテキストメニュー
popover	フローティングコンテンツ
tooltip	ホバーヒント
badge	ステータスインジケーター
avatar	ユーザープロフィール画像
scroll-area	スクロール可能なコンテナ
separator	視覚的な区切り線
label	フォームラベル
sheet	スライドアウトパネル
skeleton	ローディングプレースホルダー

Vercel 上の shadcn のデザイン指針

shadcn/ui はコンポーネントソースジェネレーターだけではありません。Vercel スタックでは、これがデフォルトのインターフェース言語です。「コンポーネントが動作する」で止まらないでください。意図的で、情報量が多く、一貫性のあるページを構成してください。

プロダクト UI のデフォルトの美的感覚

• プロダクト、ダッシュボード、AI、管理画面には new-york スタイルを優先。
• ダッシュボード、AI アプリ、内部ツール、設定、開発者向けプロダクトではデフォルトでダークモードを使用。ライトモードは、プロダクトが明らかにコンテンツファーストまたはエディトリアルである場合にのみ使用。
• インターフェーステキストには Geist Sans を、コード、メトリクス、ID、タイムスタンプ、コマンドには Geist Mono を使用。
• ベースパレットには zinc、neutral、または slate を優先。--color-primary を通じて1つのアクセントカラーを使用。
• トークンからコアサーフェスを構築: bg-background、bg-card、text-foreground、text-muted-foreground、border-border、ring-ring。アドホックな16進数値は避ける。
• 半径は一貫性を保つ。デフォルトの --radius: 0.625rem は強力なベースライン。
• ページごとに1つの密度システムを使用: ゆったり（gap-6 / p-6 / text-sm）またはコンパクト（gap-4 / p-4 / text-sm）。
• アイコンは控えめで一貫性を保つ。Lucide アイコンは h-4 w-4 または h-5 w-5 で。

これを最初に検討する

ユースケース	これを最初に検討	理由
設定ページ	Tabs + Card + Form	予測可能な保存フローで情報を明確にグループ化
データダッシュボード	Card + Badge + Table + DropdownMenu	カスタムシェルなしでサマリー、ステータス、高密度データ、行アクションをカバー
CRUD テーブル	Table + DropdownMenu + Sheet + AlertDialog	標準パターンで参照、操作、編集、破壊的確認をサポート
認証画面	Card + Label + Input + Button + Alert	エントリーフローを集中させ、エラーに適切な処理を提供
グローバル検索	Command + Dialog	確立されたインタラクションモデルによる高速なキーボードファーストの発見
モバイルナビ	Sheet + Button + Separator	小画面にきれいに適応するコンパクトなナビゲーションシェルを提供
詳細ページ	ヘッダー + Badge + Separator + Card	過度なネストなしで階層、メタデータ、サポートコンテンツのバランスを取る
フィルター	Card サイドバー + Sheet + Select	永続的なデスクトップフィルターと折りたたみ可能なモバイルコントロールに有効
空/ローディング/エラー状態	Card + Skeleton + Alert	非ハッピーパスにプレースホルダーテキストではなくデザインされたサーフェスを提供

構成レシピ

• 設定ページ: Tabs + グループごとの Card + Separator + 保存アクション
• 管理ダッシュボード: サマリー Card + フィルターバー + Table
• エンティティ詳細: ヘッダー + ステータス Badge + メイン Card + サイド Card + 破壊的操作には AlertDialog
• 検索重視: クイック検索に Command、ピッカーに Popover、モバイルフィルターに Sheet
• 認証/オンボーディング: 中央揃え Card + ソーシャル Separator + エラー用インライン Alert
• 破壊的フロー: 確認には AlertDialog（Dialog ではない）

避けるべきアンチパターン

• shadcn プリミティブが存在するのに raw な button / input / select / div を使用する
• Tabs / Table / Sheet / Dialog の代わりに div rounded-xl border p-6 を繰り返す
• 互いに競合する複数のアクセントカラー
• カードの中のカードの中のカードのネスト
• すべてのサーフェスに大きなグラデーション背景とグラスモーフィズム
• 任意のスペーシングと半径の値を混在させる
• 破壊的な確認に AlertDialog の代わりに Dialog を使用する
• デザイン処理なしで空/ローディング/エラー状態を出荷する
• テーマトークンではなくアドホックな Tailwind パレットクラスを基本的なサーフェスに使用する

カスタムレジストリの構築

独自のコンポーネントレジストリを作成してプロジェクト間で共有:

レジストリタイプ（CLI v4）

タイプ	目的
registry:ui	個別の UI コンポーネント
registry:base	完全なデザインシステムペイロード — コンポーネント、依存関係、CSS 変数、フォント、設定
registry:font	ファーストクラスのレジストリアイテムとしてのフォント設定

1. registry.json を定義

[

…

[truncated for translation]