shadcn

shadcn/ui

UI、コンポーネント、デザインシステムを構築するためのフレームワークです。コンポーネントは CLI を通じて、ソースコードとしてユーザーのプロジェクトに追加されます。

プロジェクトのパッケージランナーを使って CLI コマンドを実行してください。例：npx shadcn@latest、pnpm dlx shadcn@latest、または bunx --bun shadcn@latest。プロジェクトのコンテキストを取得する前に、package.json とリポジトリの規約からランナーを判断してください。以下の例では npx shadcn@latest を使っています。プロジェクトのランナーに置き換えてください。

現在のプロジェクトコンテキスト

現在のプロジェクトについて、実際の出力がすでに得られている場合は、該当するプロジェクトコンテキストを再利用してください。出力がない、または古くなっている場合は、シェルインジェクションに対応していないホストも含め、対象プロジェクトでパッケージランナーを使って次を実行してください。スキル内にコマンドが記載されているだけでは、実行された証拠にはなりません。

npx shadcn@latest info --json

結果を調べて、設定、インストール済みコンポーネント、解決済みのパスを確認してください。プロジェクト、設定、またはインストール済みコンポーネントのセットが変わったときに更新し、スタイルを編集するたびに更新する必要はありません。info が利用できない場合は、package.json、components.json、関連するインストール済みコンポーネントのソース、テーマファイルを直接確認してください。重要な未解決事項は明示してください。注入された出力を捏造したり、コンテキストを得るだけのためにプロジェクトを初期化したりしないでください。

原則

1. まず既存のコンポーネントを使います。 インストール済みコンポーネントと周辺の使用例を調べてください。必要なコンポーネントがない場合は、解決済みのレジストリを検索し、依頼内容またはプロジェクトコンテキストにその根拠がある場合は、コミュニティレジストリも確認してください。
2. 依頼されたインターフェースに合わせて構成します。 決め打ちのページ構成を押し付けず、タスクや周辺のプロダクトに合うプリミティブを再利用してください。
3. カスタムスタイルより、組み込みのバリアントを優先します。 variant="outline"、size="sm" などを使用してください。
4. セマンティックカラーを優先します。 テーマ上の役割には、bg-primary や text-muted-foreground などのトークンを使ってください。別の表現が適切な場合は、明示されたデザイン要件や確立されたプロジェクトの規約に従ってください。

API とアクセシビリティ要件

コンポーネントの API は、インストール済みのソース、型、選択されたプリミティブライブラリによって定義されます。必須の構成、アクセシブルな名前、キーボード操作、フォーカス処理、状態の意味を維持してください。スタイル上の好みを API 要件として扱ったり、新しい例に合わせるためだけに動作している API を変更したりしないでください。

• カスタムトリガー： Radix の asChild や Base UI の render など、プロジェクトのベースとインストール済みコンポーネントがサポートする構成 API を使用してください。該当するベースについては、base-vs-radix.md を参照してください。
• オーバーレイの名前： Dialog、Sheet、Drawer には、サポートされているタイトル機構を使ってアクセシブルな名前を指定してください。タイトルを視覚的に隠す場合は、DialogTitle、SheetTitle、または DrawerTitle に className="sr-only" を指定してください。カスタマイズする場合も、フォーカスとキーボード操作を維持してください。
• コントロールのセマンティクス： 入力にラベルを付け、関連するコントロールをセマンティックにグループ化し、インストール済みコントロールのサポートする API を通じて無効状態と非活性状態を示してください。data-invalid と data-disabled はフィールドのスタイル設定に使えますが、aria-invalid や実際の無効化動作の代わりにはなりません。forms.md を参照してください。
• 必須の構造とプロパティ： TabsList 内の TabsTrigger や InputGroup 専用の入力コンポーネントなど、インストール済みの実装で必要な親コンポーネントと子コンポーネントを維持してください。要件は選択したベースに照らして確認してください。提案されているすべてのグループ化用ラッパーが必須だと思い込まないでください。composition.md を参照してください。
• サポートされる読み込み状態： isPending や isLoading を使う前に、ローカルの Button API を確認してください。これらのプロパティがない場合は、サポートされているスピナー、アイコンの配置、無効状態を組み合わせて、実際の処理中の動作を構成してください。

スタイリングとコンポジションのデフォルト

依頼されたデザインと既存のコードに適合する場合は、以下のデフォルトを使用してください。明示的なユーザーの選択や確立されたプロジェクト規約を優先しつつ、API とアクセシビリティの要件は維持してください。これらの例と異なるという理由だけで、妥当な代替案を欠陥として報告しないでください。

• スタイリング： 組み込みのバリアントやセマンティックトークン、Flex／Grid の間隔に gap-*、等しい寸法に size-*、truncate、およびプロジェクトの cn() ユーティリティを優先してください。レイアウトや、妥当な理由のあるローカルなスタイリングには className を使用してください。オーバーライドを追加する前に、既存のオーバーレイの重なり順を確認してください。styling.md と customization.md を参照してください。
• フォーム： 適合する場合は、既存の FieldGroup／Field と InputGroup のコンポジションを優先してください。選択肢の数だけでなく、操作の意味に応じて ToggleGroup、RadioGroup、Checkbox、または Switch を選んでください。プロジェクトの fieldset パターンを使って、意味的なグループ化を維持してください。forms.md を参照してください。
• カードとグループ： Card のセクションは実際に含めるコンテンツに使用し、説明やフッターが不要なら省略してください。コンポーネントの API やコンテンツ間の関係に必要な場合は、グループ化コンポーネントを使用してください。画像を利用できず、有用な識別情報が失われる場合は、適切なアバターのフォールバックを用意してください。composition.md を参照してください。
• フィードバックと装飾： 動作やセマンティクスが適合する場合は、既存の Alert、Empty、Separator、Skeleton、Badge コンポーネントを優先してください。プロジェクトで確立されたトーストの実装を維持してください。パターンを完成させるだけの目的でコンポーネントや状態を追加しないでください。
• アイコン： 設定済みのアイコンライブラリと、インストール済みコンポーネントのサイズや配置に関する規約に従ってください。対応している場合は data-icon も使用してください。依頼されたデザインに応じてサイズをカスタマイズしてください。既存のデータ契約で識別子が必要な場合を除き、文字列による検索処理よりコンポーネント参照を優先してください。icons.md を参照してください。
• チャット： 利用可能で適切な場合は、MessageScroller、Message、Bubble、Attachment、Marker を再利用してください。これらを使う場合は必要な入れ子構造を維持し、独自の実装を重複させるより、それらのスクロールや状態に関する API を優先してください。これらのプリミティブが存在するというだけで、既存のチャット UI を置き換える必要はありません。chat.md を参照してください。

CLI の規約

• プリセットコードをデコードしたり、プリセット URL を手動で作成したりしないでください。 npx shadcn@latest preset decode <code>、preset url <code>、または preset open <code> を使用してください。プロジェクトの情報を考慮したプリセット検出には、npx shadcn@latest preset resolve を使用してください。
• プリセットコードは CLI から直接適用してください。 既存のプロジェクトには npx shadcn@latest apply <code> を使用し、初期化時には npx shadcn@latest init --preset <code> を使用してください。

主なパターン

以下の例は、前述のデフォルトを示しています。スタイリングの代替案が自動的に誤りになるわけではありません。インストール済みの API と依頼されたデザインを維持してください。

// Default form layout with the project's Field components.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel htmlFor="invalid-email">Email</FieldLabel>
  <Input id="invalid-email" aria-invalid aria-describedby="invalid-email-error" />
  <FieldDescription id="invalid-email-error">Invalid email.</FieldDescription>
</Field>

// Icon placement when supported by the installed Button.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Prefer gap for a flex layout; preserve an intentional block layout.
<div className="flex flex-col gap-4">...</div>

// Concise equal dimensions.
<Avatar className="size-10" />

// Prefer an existing status presentation when it fits.
<Badge variant="secondary">+20.1%</Badge>

コンポーネントの選択

必要なもの	使用するもの
ボタン／アクション	適切なバリアントの Button
フォーム入力	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
関連する切り替えオプション	切り替えのセマンティクスに適している場合は、ToggleGroup + ToggleGroupItem
データ表示	Table、Card、Badge、Avatar
ナビゲーション	Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination
オーバーレイ	Dialog（モーダル）、Sheet（サイドパネル）、Drawer（ボトムシート）、AlertDialog（確認）
フィードバック	toast（Base UI）、sonner（Radix/Aria）、Alert、Progress、Skeleton、Spinner
コマンドパレット	Dialog 内の Command
グラフ	Chart（Recharts をラップ）
レイアウト	Card、Separator、Resizable、ScrollArea、Accordion、Collapsible
空の状態	Empty
メニュー	DropdownMenu、ContextMenu、Menubar
ツールチップ／情報	Tooltip、HoverCard、Popover
チャット／会話 UI	MessageScroller、Message、Bubble、Attachment、Marker

主なフィールド

info のプロジェクトコンテキストには、次のフィールドが含まれる場合があります。設定を直接読み取る場合は、すべてのフィールドが存在すると仮定せず、関連ファイルから同等の情報を確認してください。

• aliases → インポートには実際のエイリアス接頭辞（例：@/、~/）を使用し、ハードコードしないでください。
• project.rsc → true の場合、useState、useEffect、イベントハンドラー、ブラウザー API を使用するコンポーネントでは、ファイルの先頭に "use client" が必要です。このディレクティブについて助言する際は、必ずこのフィールドを参照してください。
• tailwindVersion → "v4" では @theme inline ブロックを使用し、"v3" では tailwind.config.js を使用します。
• project.tailwindCss → 既存のテーマスタイルシートです。競合するグローバルスタイルシートを新たに作成せず、共有変数はプロジェクトのテーマを管理するファイルに配置してください。
• style → コンポーネントのビジュアルスタイル（例：nova、vega）。
• base → 選択したプリミティブライブラリです。コンポーネント API と利用可能な props に影響するため、そのベース向けのガイダンスを使用してください。
• iconLibrary → アイコンのインポート先を指定します。lucide には lucide-react、tabler には @tabler/icons-react などを使用してください。lucide-react を前提にしないでください。
• resolvedPaths → コンポーネント、ユーティリティ、フックなどの正確なファイルシステム上の保存先です。
• framework → ルーティングとファイルの規約（例：Next.js App Router と Vite SPA）を指定します。
• パッケージマネージャー → info では報告されません。shadcn 以外の依存関係をインストールする前に、ロックファイル（bun.lock、pnpm-lock.yaml、yarn.lock、package-lock.json）を確認してください（例：pnpm add date-fns と npm install date-fns）。
• preset → 現在のプロジェクトで解決されたプリセットコードと値です。プリセット情報だけが必要な場合は、npx shadcn@latest preset resolve --json を使用してください。

すべてのフィールドの詳細については、cli.md — info command を参照してください。

コンポーネントのドキュメント、例、使用方法

インストール済みのコンポーネントと、その周辺の使用例をまず確認します。不慣れなコンポーネントを追加する場合、API に依存する動作を変更する場合、上流の更新を比較する場合、またはローカルのソースだけでは解決できない不明点がある場合は、npx shadcn@latest docs <component> を実行し、返されたドキュメントを取得してください。

npx shadcn@latest docs button dialog select

取得済みのドキュメントが、該当するベースとコンポーネントのバージョンに引き続き合致する場合は再利用します。ローカルのソースと既存の規約で判断できる、些細な余白、色、タイポグラフィの編集では、新たにドキュメントを取得する必要はありません。関連するコンテキストが変わった場合、または API に関する疑問が残っている場合にのみ更新します。ドキュメントを取得できない場合は、十分なローカルの根拠に基づいて作業を続け、重要な不足があれば明示してください。

レジストリの解決

明示的に指定されたレジストリまたはアイテムのアドレスを優先します。それ以外の場合は、components.json、文書化された規約、周辺コンポーネントの由来、以前のユーザーの判断を確認します。根拠から既存のソースが明確な場合はそれを使用し、選択内容を簡潔に述べてください。設定されているレジストリが複数あっても、どれかが優先されるとは限りません。選択肢によってコンポーネントまたはソースが大きく変わる場合にのみ質問してください。

選択を判断するため、設定されている可能性のあるソースを読み取り専用で検索してもかまいません。アイテムを追加する前に、必要に応じて名前空間付きの指定、GitHub のアイテムアドレス、または URL を使用して、具体的なレジストリを確定してください。同じ名前のコンポーネントがあるという理由だけで、別のレジストリからコンポーネントを黙ってインストールしないでください。アドレスの意味については、registry.md を参照してください。

ワークフロー

タスクに関係する手順のみを使用してください。ローカルのスタイル編集では、レジストリの検索、インストール、プリセットの操作が不要な場合があります。

1. プロジェクトのコンテキストを取得する — 該当する既存のコンテキストを再利用するか、上記の説明に従って取得します。シェルインジェクションが実行されたと想定しないでください。
2. まずインストール済みのコンポーネントを確認する — add を実行する前に、必ずプロジェクトのコンテキストにある components リストを確認するか、resolvedPaths.ui ディレクトリを一覧表示します。追加されていないコンポーネントはインポートせず、すでにインストール済みのコンポーネントは再追加しないでください。
3. レジストリを解決してコンポーネントを探す — レジストリの解決に従い、必要に応じて選択したソースを検索します。
4. API に関する疑問を解決する — 上記の基準に従って、ローカルのソースと該当するドキュメントを参照します。未インストールのレジストリアイテムを確認するには、npx shadcn@latest view を使用します。インストール済みコンポーネントへの変更をプレビューするには、npx shadcn@latest add --diff を使用します。
5. インストールまたは更新する — npx shadcn@latest add を実行します。既存のコンポーネントを更新する場合は、まず --dry-run と --diff を使用して変更をプレビューします（下記のコンポーネントの更新を参照）。
6. サードパーティ製コンポーネントのインポートを修正する — コミュニティレジストリ（例：@bundui、@magicui）からコンポーネントを追加した後、追加された UI 以外のファイルを確認し、@/components/ui/... のようなハードコードされたインポートパスがないか調べます。これらはプロジェクトの実際のエイリアスと一致しません。npx shadcn@latest info を使用して正しい ui エイリアス（例：@workspace/ui/components）を確認し、それに合わせてインポートを書き換えます。CLI は独自の UI ファイルのインポートを書き換えますが、サードパーティのレジストリコンポーネントには、プロジェクトと一致しないデフォルトのパスが使われていることがあります。
7. 追加したコンポーネントを確認する — 追加されたファイルを読み、インポート、必要なコンポジション、およびAPI とアクセシビリティの要件を確認します。アイコンのインポートとスタイルを、要求されたデザインおよびプロジェクトの規約に合わせます。具体的な不具合は修正しますが、スタイル上のデフォルトから外れているものをすべて不具合とみなさないでください。
8. プリセットを切り替える — 操作を選択する前に、現在のプリセットと適用先のプリセットを確認します。すでに承認されている 上書き、部分適用、マージ、または スキップ の選択に従います。リクエストで重要な選択が未解決の場合、または実際の上書き範囲が承認範囲を超える場合に限り、質問します。その際は、まず対象ファイルとテーマ／設定の変更内容を具体的にします。
   • 現在のプリセットを確認する: npx shadcn@latest preset resolve。構造化された値が必要な場合は、--json を使用します。
   • 適用先のプリセットを確認する: npx shadcn@latest preset decode <code>。プリセットビルダーを共有または開くには、preset url <code> または preset open <code> を使用します。
   • 上書き: npx shadcn@latest apply <code>。検出されたコンポーネント、フォント、CSS 変数を上書きします。
   • 部分適用: npx shadcn@latest apply <code> --only theme,font。UI コンポーネントを再インストールせずに、選択したプリセット部分だけを更新します。指定できる値は theme と font です。カンマ区切りで組み合わせることもできます。アイコンの変更にはコンポーネントの完全な再インストールや変換が必要になる場合があるため、icon は意図的にサポートされていません。
   • マージ: npx shadcn@latest init --preset <code> --force --no-reinstall を実行し、次に npx shadcn@latest info でインストール済みコンポーネントを一覧表示します。その後、インストール済みの各コンポーネントに対して --dry-run と --diff を使用し、個別にスマートマージします。
   • スキップ: npx shadcn@latest init --preset <code> --force --no-reinstall。設定と CSS のみを更新し、コンポーネントはそのままにします。
   • 重要: プリセットのコマンドは、必ずユーザーのプロジェクトディレクトリ内で実行してください。apply は、components.json ファイルがある既存のプロジェクトでのみ機能します。CLI は components.json に基づいて、現在のベース（base と radix のどちらか）を自動的に保持します。スクラッチ／一時ディレクトリを使う必要がある場合は、npx shadcn@latest init --preset <code> --base <current-base> で初期化してから、そのディレクトリで add --dry-run または --diff を実行します（プリセットコードにはベースが含まれません）。apply には --base フラグも --dry-run フラグもありません。

コンポーネントの更新

ユーザーから、ローカルの変更を維持したままアップストリームのコンポーネントを更新するよう依頼された場合は、--dry-run と --diff を使って適切にマージします。GitHub から生のファイルを手動で取得してはいけません。必ず CLI を使ってください。

1. npx shadcn@latest add <component> --dry-run を実行し、影響を受けるファイルをすべて確認します。
2. 各ファイルについて、npx shadcn@latest add <component> --diff <file> を実行し、アップストリームとローカルで何が変更されたかを確認します。
3. 影響を受けるファイル、依存関係、テーマ、設定を、ユーザーが許可した範囲と照らし合わせます。その範囲内で、変更のないアップストリームのファイルを更新します。カスタマイズ済みのファイルは、カスタマイズの置き換えが明示的に許可されていない限り、ローカルでの動作を維持しながらマージします。すべてを更新するという一般的な依頼だけでは、独自のカスタマイズを破棄する許可にはなりません。
4. --overwrite は、置き換えられるすべてのファイルが許可範囲内にあり、ローカルのカスタマイズが失われることが明示的に許可されている場合に限り使用します。許可は、最初の依頼または具体的な置き換えに対する以前の承認から得られる場合があり、改めて確認する必要はありません。プレビューで、許可範囲外の追加ファイルへの影響やカスタマイズの消失が判明した場合は、未決の判断のみを確認し、解決するまで該当ファイルを維持します。

クイックリファレンス

# Create a new project.
npx shadcn@latest init --name my-app --preset nova --base base
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# Create a monorepo project.
npx shadcn@latest init --name my-app --preset nova --base base --monorepo
npx shadcn@latest init --name my-app --preset nova --base base --template next --monorepo

# Initialize existing project.
npx shadcn@latest init --preset nova --base base
npx shadcn@latest init --defaults  # shortcut: --template=next --base=base --preset=nova

# Apply a preset to an existing project.
npx shadcn@latest apply a2r6bw
npx shadcn@latest apply a2r6bw --only theme
npx shadcn@latest apply a2r6bw --only font
npx shadcn@latest apply a2r6bw --only theme,font

# Inspect preset codes and project preset state.
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset url a2r6bw
npx shadcn@latest preset open a2r6bw
npx shadcn@latest preset resolve
npx shadcn@latest preset resolve --json

# Add components.
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add owner/repo/item
npx shadcn@latest add --all

# Preview changes before adding/updating.
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx
npx shadcn@latest add owner/repo/item --dry-run

# Search registries.
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"
npx shadcn@latest search owner/repo -q "login"
npx shadcn@latest search                          # all configured registries
npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type

# Get component docs and example URLs.
npx shadcn@latest docs button dialog select

# View registry item details (for items not yet installed).
npx shadcn@latest view @shadcn/button
npx shadcn@latest view owner/repo/item

名前付きプリセット： nova、vega、maia、lyra、mira、luma、sera、rhea。base は独立した --base の選択肢です。base-nova はプリセット名ではなく、components.json 内で設定される style の値です。 テンプレート： next、vite、start、react-router、astro（すべて --monorepo に対応）および laravel（モノレポには非対応） プリセットコード： ui.shadcn.com の、バージョンプレフィックス付き base62 文字列（例：a2r6bw または b0）

詳細リファレンス

• rules/forms.md — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、検証状態
• rules/composition.md — グループ、オーバーレイ、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button の読み込み状態
• rules/chat.md — MessageScroller、Message、Bubble、Attachment、Marker、ストリーミング、アンカリング、最新メッセージへのジャンプ
• rules/icons.md — data-icon、アイコンのサイズ設定、オブジェクトとしてアイコンを渡す方法
• rules/styling.md — セマンティックカラー、バリアント、className、間隔、サイズ、省略表示、ダークモード、cn()、z-index
• rules/base-vs-radix.md — asChild と render の違い、Select、ToggleGroup、Slider、Accordion
• cli.md — コマンド、フラグ、プリセット、テンプレート
• registry.md — ソースレジストリの作成、include、項目定義、依存関係、GitHub レジストリのルール
• mcp.md — shadcn mcp サーバーの設定とツール
• customization.md — テーマ設定、CSS 変数、コンポーネントの拡張