shadcn

shadcn/ui

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

IMPORTANT: すべての CLI コマンドは、プロジェクトのパッケージランナーを使用して実行してください。npx shadcn@latest、pnpm dlx shadcn@latest、または bunx --bun shadcn@latest のうち、プロジェクトの packageManager に応じたものを使用します。以下の例では npx shadcn@latest を使用していますが、プロジェクトに適したランナーに置き換えてください。

新しいプロジェクトでは、デフォルトで Bun を使用してください。既存のプロジェクトでは、設定済みのパッケージマネージャーを引き続き使用します。

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

プロジェクトのパッケージランナーを使って shadcn@latest info --json を実行し、返された設定とコンポーネントの一覧を確認してください。スキルの実行時に、すべてのクライアントでシェルの文字列展開が行われるとは限らないため、前提にしないでください。プロジェクトのベースに対応したドキュメントを参照するには、shadcn@latest docs <component> を使用してください。

原則

1. まず既存のコンポーネントを使用してください。 カスタム UI を作成する前に、npx shadcn@latest search を使ってレジストリを確認してください。コミュニティのレジストリも確認してください。
2. 一から作らず、組み合わせてください。 設定ページなら Tabs + Card + フォームコントロール、ダッシュボードなら Sidebar + Card + Chart + Table を使用します。
3. カスタムスタイルより組み込みのバリアントを優先してください。 variant="outline"、size="sm" などを使用します。
4. セマンティックカラーを使用してください。 bg-primary、text-muted-foreground を使用し、bg-blue-500 のような直接指定の値は使用しないでください。

重要なルール

このデザインシステムのデフォルトとして、以下のルールを使用してください。プロジェクトで明示された要件はそのまま維持してください。各リンク先のファイルには、誤ったコードと正しいコードの組み合わせが記載されています。

スタイル設定と Tailwind → styling.md

• className はスタイル設定ではなく、レイアウトに使用してください。 コンポーネントの色やタイポグラフィを上書きしないでください。
• space-x-* や space-y-* は使用しないでください。 gap-* を指定した flex を使用します。縦方向に並べる場合は flex flex-col gap-* を使用してください。
• 幅と高さが同じ場合は size-* を使用してください。 w-10 h-10 ではなく size-10 を使用します。
• 省略表記の truncate を使用してください。 overflow-hidden text-ellipsis whitespace-nowrap は使用しないでください。
• dark: による色の手動上書きはしないでください。 セマンティックトークン（bg-background、text-muted-foreground）を使用します。
• 条件付きクラスには cn() を使用してください。 テンプレートリテラルを使った手動の三項演算子は記述しないでください。
• オーバーレイコンポーネントに z-index を手動で指定しないでください。 Dialog、Sheet、Popover などが独自にスタック順序を処理します。

フォームと入力 → forms.md

• フォームには FieldGroup + Field を使用してください。 フォームのレイアウトに、space-y-* や grid gap-* を指定した生の div は使用しないでください。
• InputGroup では InputGroupInput／InputGroupTextarea を使用してください。 InputGroup 内で生の Input／Textarea を使用しないでください。
• 入力の中にボタンを配置する場合は、InputGroup + InputGroupAddon を使用してください。
• 選択肢のセット（2～7 個）には ToggleGroup を使用してください。 Button をループで表示し、アクティブ状態を手動で管理しないでください。
• 関連するチェックボックスやラジオボタンをまとめる場合は、FieldSet + FieldLegend を使用してください。 見出しを含む div は使用しないでください。
• フィールドのバリデーションには data-invalid + aria-invalid を使用してください。 data-invalid は Field に、aria-invalid はコントロールに指定します。無効化する場合は、data-disabled を Field に、disabled をコントロールに指定します。

コンポーネントの構造 → composition.md

• アイテムは必ず対応する Group の中に配置してください。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• インストール済みのベースが提供するコンポジション API を使用してください。 Radix では asChild、Base UI では render を使用します。React Aria では、いずれかのパターンを無条件に適用せず、Aria コンポーネントのドキュメントを取得してください。shadcn@latest info の base フィールドを確認してください。→ base-vs-radix.md
• Dialog、Sheet、Drawer には必ず Title が必要です。 アクセシビリティのため、DialogTitle、SheetTitle、DrawerTitle が必要です。視覚的に非表示にする場合は className="sr-only" を使用してください。
• 該当する Card スロットを使用してください。 ヘッダー、説明、フッターは、その内容がある場合にのみ追加します。
• Button には isPending／isLoading がありません。 Spinner + data-icon + disabled を組み合わせてください。
• TabsTrigger は必ず TabsList の中に配置してください。 トリガーを Tabs に直接レンダリングしないでください。
• Avatar には必ず AvatarFallback が必要です。 画像の読み込みに失敗した場合に表示されます。

カスタムマークアップではなく、コンポーネントを使います → composition.md

• カスタムマークアップより既存のコンポーネントを優先します。 スタイル付きの div を書く前に、利用できるコンポーネントがないか確認してください。
• コールアウトには Alert を使います。 カスタムのスタイル付き div は作成しないでください。
• 空の状態には Empty を使います。 空の状態を表すカスタムマークアップは作成しないでください。
• トーストはプロジェクトの基盤に合わせます。 Base UI プロジェクトでは toast コンポーネントの toast を使います。Radix および React Aria プロジェクトでは、sonner の toast() を使います。
• <hr> や <div className="border-t"> の代わりに、Separator を使います。
• 読み込み中のプレースホルダーには Skeleton を使います。 カスタムの animate-pulse div は作成しないでください。
• カスタムのスタイル付き span の代わりに、Badge を使います。

アイコン → icons.md

• Button 内のアイコンには data-icon を使います。 アイコンに data-icon="inline-start" または data-icon="inline-end" を指定します。
• コンポーネント内のアイコンにサイズ指定クラスを付けないでください。 アイコンのサイズはコンポーネントが CSS で調整します。size-4 や w-4 h-4 は使わないでください。
• アイコンは文字列キーではなく、オブジェクトとして渡します。 icon={CheckIcon} のように指定し、文字列で検索しないでください。

チャットとメッセージ → chat.md

• チャット UI はチャットプリミティブを組み合わせて構成します。 会話には MessageScroller、行には Message、表示領域には Bubble を使います。独自に作成した吹き出しの div や、生のスクロールコンテナーは使わないでください。
• スクロール動作は MessageScroller が担います。 ストリーミング時の追従、アンカリング、最新メッセージへのジャンプ（MessageScrollerButton）は組み込み済みです。useStickToBottom／ResizeObserver フックは作成しないでください。
• 添付ファイルには Attachment を、システムメモや区切りには Marker を使います。 Item カードや、ラベル付きの Separator は使わないでください。
• アシスタントのアクティビティには Trace を使います。 推論、ツール呼び出し、ソース、ステップは、メッセージパーツの各実行につき 1 つの Trace にまとめた TraceLine とします。動作を囲む要素には TraceCollapsible、シートのトリガー、またはリンクを使います。独自に作成した Collapsible や Marker は使わないでください。

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> を使います。

主なパターン

これらは、正しい shadcn/ui コードを特徴づける最も一般的なパターンです。例外的なケースについては、上記のリンク先にあるルールファイルを参照してください。

// Form layout: FieldGroup + Field, not div + Label.
<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>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>

// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong

// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong

// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

コンポーネントの選択

必要なもの	使用するもの
ボタン／アクション	適切なバリアントの Button
フォーム入力	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
2～5 個の選択肢の切り替え	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、Trace

主なフィールド

info --json のプロジェクトコンテキストには、次の主なフィールドが含まれます。

• aliases → インポートには実際のエイリアスプレフィックス（例：@/、~/）を使用し、ハードコードしないでください。
• isRSC → true の場合、useState、useEffect、イベントハンドラー、またはブラウザー API を使用するコンポーネントでは、ファイルの先頭に "use client" が必要です。このディレクティブについて案内する際は、必ずこのフィールドを参照してください。
• tailwindVersion → "v4" では @theme inline ブロックを使用し、"v3" では tailwind.config.js を使用します。
• tailwindCssFile → カスタム CSS 変数が定義されているグローバル CSS ファイルです。必ずこのファイルを編集し、新しいファイルは作成しないでください。
• style → コンポーネントのビジュアルスタイル（例：nova、vega）。
• base → プリミティブライブラリ（radix、base、aria）。コンポーネントの API と利用可能なプロパティに影響します。
• iconLibrary → アイコンのインポート先を決定します。lucide には lucide-react、tabler には @tabler/icons-react などを使用します。lucide-react を前提にしないでください。
• resolvedPaths → コンポーネント、ユーティリティ、フックなどの正確なファイルシステム上の保存先です。
• framework → ルーティングとファイルの規則（例：Next.js App Router と Vite SPA の違い）。
• packageManager → shadcn 以外の依存関係をインストールする際は、これを使用してください（例：pnpm add date-fns と npm install date-fns）。
• preset → 現在のプロジェクトで解決されたプリセットコードと値です。プリセット情報だけが必要な場合は、npx shadcn@latest preset resolve --json を使用してください。

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

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

npx shadcn@latest docs <component> を実行すると、コンポーネントのドキュメント、例、および API リファレンスの URL を取得できます。これらの URL にアクセスして、実際の内容を取得してください。

npx shadcn@latest docs button dialog select

コンポーネントの作成、修正、デバッグ、または使用時には、必ず npx shadcn@latest docs を実行し、最初に URL にアクセスしてください。 これにより、推測に頼らず、正しい API と使用パターンに基づいて作業できます。

ワークフロー

1. プロジェクトのコンテキストを取得する — プロジェクトのランナーを使って shadcn@latest info --json を実行します。
2. 最初にインストール済みのコンポーネントを確認する — add を実行する前に、必ずプロジェクトのコンテキストから components リストを確認するか、resolvedPaths.ui ディレクトリを一覧表示します。追加されていないコンポーネントをインポートしたり、すでにインストール済みのコンポーネントを再追加したりしないでください。
3. コンポーネントを探す — npx shadcn@latest search を実行します。
4. ドキュメントとサンプルを取得する — npx shadcn@latest docs <component> を実行して URL を取得し、その URL にアクセスします。未インストールのレジストリーアイテムを確認するには、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. 追加したコンポーネントを確認する — いずれかのレジストリーからコンポーネントまたはブロックを追加した後は、必ず追加されたファイルを読み、正しいことを確認してください。サブコンポーネントの不足（例：SelectGroup がない SelectItem）、インポートの不足、誤った構成、重要なルールへの違反がないか確認します。また、アイコンのインポートはすべて、プロジェクトのコンテキストにある iconLibrary に置き換えます（例：レジストリーアイテムが lucide-react を使っていて、プロジェクトが hugeicons を使っている場合は、それに応じてインポートとアイコン名を変更します）。次に進む前に、すべての問題を修正してください。
8. コンテキストに基づいてレジストリーを選ぶ — プロジェクトで設定されたレジストリー、または標準コンポーネント用の @shadcn を使います。候補となるソースによって依頼された結果が大きく変わる場合は、確認してください。
9. プリセットを切り替える — まずユーザーに、上書き、部分適用、マージ、スキップのどれにするか尋ねます。
   • 現在のプリセットを確認する：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、aria）を自動的に維持します。一時的な作業ディレクトリ（例：--dry-run の比較用）を使う必要がある場合は、--base <current-base> を明示的に指定してください。プリセットコードにはベースが含まれていません。

DESIGN.md からのデザインシステム作成

ユーザーがプリセットの有無を問わず、DESIGN.md（またはブランド仕様）からデザインシステムを作成するよう依頼した場合は、design-system.md に最初から最後まで従います。

1. init --preset <code> --template <vite|next> --name <app> --no-monorepo -y を実行します。プリセットコードがない場合は、最も近いスタイルを選び、--base base --preset <style> を指定します。その後、add --all -y を実行します。
2. 編集を始める前に、DESIGN.md のフロントマター、「Do's and Don'ts」、「Known Gaps」を読みます。
3. DESIGN.md のトークンを tailwindCssFile の shadcn 変数に割り当てます。角丸のスケール、シャドウ、フォント、type-* ユーティリティを固定します。
4. cva バリアントを編集してコンポーネントのスタイルを変更します。コントロールの高さはまとめて変更します。
5. design-system-page.md に従ってデザインシステムページを作成します。コントラストを確認したカラーの役割、書体見本、固定表示の状態マトリクス、エッジケース、Do/Don't のペア、レシピを含めます。scripts/showcase-coverage.mjs でカバレッジを確認します。
6. ブラウザーで検証します。型チェック、コンソールエラーがないこと、ページ最上部からの読み込み、横方向のオーバーフローがないこと、ダークモードを確認します。

コンポーネントの更新

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

1. npx shadcn@latest add <component> --dry-run を実行し、影響を受けるファイルをすべて確認します。
2. ファイルごとに npx shadcn@latest add <component> --diff <file> を実行し、上流の変更とローカルの変更を確認します。
3. 差分に基づいてファイルごとに判断します。
   • ローカルの変更がない → 安全に上書きできます。
   • ローカルの変更がある → ローカルファイルを読み、差分を分析し、ローカルの変更を維持しながら上流の更新を適用します。
   • ユーザーが「すべてそのまま更新して」と言った場合 → --overwrite を使用しますが、事前に確認してください。
4. ユーザーから明示的な許可を得ずに --overwrite を使用してはいけません。

クイックリファレンス

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

# Create a design system app (then follow design-system.md).
npx shadcn@latest init --name my-ds --preset b0 --template vite --no-monorepo -y
npx shadcn@latest init --name my-ds --base base --preset maia --template vite --no-monorepo -y
npx shadcn@latest add --all -y

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

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

# 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（2026-10-01 確認済み。現在のプリセット定義を参照）。 テンプレート： 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、Trace、ストリーミング、アンカリング、最新メッセージへのジャンプ、アシスタントのアクティビティ行
• 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 レジストリのルール
• customization.md — テーマ設定、CSS 変数、コンポーネントの拡張
• design-system.md：DESIGN.md（プリセットの有無を問わず）からテーマ設定済みアプリを作成する方法：スタイル選定、トークンの割り当て、角丸、フォント、文字サイズのスケール、コントロールの高さ、ショーケースでの注意点、検証
• design-system-page.md：デザインシステムページに含める内容とその作成方法：基礎、コンポーネントの階層、固定表示の状態マトリクス、コントラストのペア、エッジケース、Do/Don't、レシピ