shadcn-svelte

shadcn-svelte

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

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

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

プロジェクトルートの components.json を読み、実際のファイル構成が必要な場合は、CLI と同じルールで解決した aliases.ui パスが示すディレクトリを一覧表示してください。

インポート（Svelte）

各コンポーネントは、index.ts のバレルファイルを含む独自のフォルダーにあります。インストール手順に従ってください。

• 複数パーツのコンポーネント（dialog、select、card、field、tabs など）：import * as Dialog from "$lib/components/ui/dialog" のようにインポートし、Dialog.Content、Dialog.Title、Card.Root、Card.Header など、バレルがエクスポートするものを使用します（短い名前や Root as … のエイリアスなど）。
• 単一コンポーネントのバレル（フォルダー内に実質的なコンポーネントが 1 つだけある場合）：名前付きインポートを使用します。import { Button } from "$lib/components/ui/button" と <Button> のように記述し、import * as Button と Button.Root の組み合わせは使用しません。{ Input }、{ Badge }、{ Spinner }、{ Checkbox }、{ Separator }、{ Skeleton } なども同じパターンです。

import * as Dialog from "$lib/components/ui/dialog";
import { Button } from "$lib/components/ui/button";
import { Separator } from "$lib/components/ui/separator";

ハードコードされたパスではなく、components.json に記載された実際のエイリアス（多くの場合 $lib/components/ui/...）を使用してください。

原則

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

重要なルール

これらのルールは常に適用されます。それぞれに、不正なコードと正しいコードの例を示すファイルへのリンクがあります。

スタイリングと Tailwind → styling.md

• レイアウトには class を使い、スタイリングには使わないでください。 コンポーネントの色やタイポグラフィを上書きしないでください。
• 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

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

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

• 項目は必ずグループの中に配置します。 Select.Item → Select.Group。DropdownMenu.Item → DropdownMenu.Group。Command.Item → Command.Group。
• カスタムトリガー。 コントロールを Dialog.Trigger／AlertDialog.Trigger でラップするか、ルートの bind:open で開閉状態を制御します。コンポーネントのドキュメントを参照してください。
• Dialog、Sheet、Drawer には必ずタイトルが必要です。 アクセシビリティのため、Dialog.Title、Sheet.Title、Drawer.Title が必要です。視覚的に非表示にする場合は class="sr-only" を使用します。
• Card の構成要素をすべて使用します。 Card.Header／Card.Title／Card.Description／Card.Content／Card.Footer。すべてを Card.Content に詰め込まないでください。
• Button に isPending／isLoading はありません。 Button 内に Spinner を配置し、disabled を指定して組み合わせます。適切な間隔を確保するには、Spinner に data-icon="inline-start"／inline-end を指定します（import { Button }、import { Spinner }）。
• Tabs.Trigger は必ず Tabs.List の中に配置します。 Tabs 内にトリガーを直接レンダリングしないでください。
• Avatar には必ず Avatar.Fallback が必要です。 画像の読み込みに失敗した場合に使用します。

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

• カスタムマークアップを書く前に、既存のコンポーネントを使用します。 スタイルを設定した div を書く前に、該当するコンポーネントがあるか確認してください。
• コールアウトには Alert を使用します。 カスタムスタイルの div を作成しないでください。
• 空の状態には Empty を使用します。 カスタムの空状態用マークアップを作成しないでください。
• トーストには svelte-sonner を使用します。 UI フォルダーにある Sonner コンポーネントとともに、svelte-sonner の toast() を使用します。
• <hr> やボーダーのみのクラスを指定した div の代わりに、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 は使用しないでください。
• アイコンはコンポーネントとして渡します。 文字列キーではなく、設定済みの iconLibrary（例：@lucide/svelte）からインポートします。

CLI

• プリセット — shadcn-svelte.com のデザインシステムビルダーからエンコード済み文字列をコピーし、npx shadcn-svelte@latest init --preset <code> に渡します。

主なパターン

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

<script lang="ts">
  import * as Field from "$lib/components/ui/field";
  import { Input } from "$lib/components/ui/input";
  import { Button } from "$lib/components/ui/button";
  import SearchIcon from "@lucide/svelte/icons/search";
  import { Badge } from "$lib/components/ui/badge";
  import * as Avatar from "$lib/components/ui/avatar";
</script>


<Field.FieldGroup>
  <Field.Field>
    <Field.FieldLabel for="email">Email</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>


<Field.Field data-invalid>
  <Field.FieldLabel for="email">Email</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>Invalid email.</Field.FieldDescription>
</Field.Field>


<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>


<div class="flex flex-col gap-4"></div>


<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="User" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>


<Badge variant="secondary">+20.1%</Badge>

コンポーネントの選択

ニーズ	使用するもの
ボタン／アクション	適切なバリアントを指定した Button（import { Button }）
フォーム入力	Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider
2～5 個の選択肢の切り替え	ToggleGroup.Root + ToggleGroup.Item
データ表示	Table、Card、Badge、Avatar
ナビゲーション	Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination
オーバーレイ	Dialog（モーダル）、Sheet（サイドパネル）、Drawer（ボトムシート）、AlertDialog（確認）
フィードバック	svelte-sonner（トースト）、Alert、Progress、Skeleton、Spinner
コマンドパレット	Dialog 内の Command
チャート	Chart（LayerChart）
レイアウト	Card、Separator、Resizable、ScrollArea、Accordion、Collapsible
空の状態	Empty
メニュー	DropdownMenu、ContextMenu、Menubar
ツールチップ／情報	Tooltip、HoverCard、Popover

主なフィールド

別の info コマンドではなく、components.json とファイルシステムを使用してください。

• aliases → 設定にある実際のエイリアスプレフィックス（例：$lib/）を使用してください。無関係なプロジェクトの値をハードコードしないでください。
• tailwind.css → テーマ変数が定義されているグローバル CSS ファイルです。テーマを調整する場合はこのファイルを編集してください。ユーザーがすでに使用している場合を除き、別のグローバルファイルを追加しないでください。
• style → ビジュアルスタイル（例：nova、vega、…）とレジストリのスタイルパスです。
• iconLibrary → アイコンパッケージ（@lucide/svelte、@tabler/icons-svelte など）を特定します。@lucide/svelte と決めつけないでください。
• registry → CLI がコンポーネントを取得する場所です。デフォルトは公式レジストリの shadcn-svelte.com です。
• resolvedPaths（概念上の項目）→ CLI は aliases を絶対パスに解決します。インストール済みコンポーネントを確認するには、ディスク上の aliases.ui を一覧表示してください。

コマンドとフラグについては、cli.md を参照してください。

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

ドキュメントと例については、https://shadcn-svelte.com/docs/components/<name>.md を開いてください。コンポーネントを作成、修正、デバッグ、または使用する際は、ドキュメントに記載された API に従えるよう、まず公式ページを読んでください。

ワークフロー

1. プロジェクトのコンテキストを把握する — components.json を読み、必要に応じて UI コンポーネントのディレクトリを一覧表示します。
2. まずインストール済みのコンポーネントを確認する — add を実行する前に、解決された ui パス配下のファイルを一覧表示します。追加されていないコンポーネントはインポートせず、更新する場合を除き、すでに存在するコンポーネントを再追加しないでください。
3. コンポーネントを探す — 引数なしで npx shadcn-svelte@latest add を実行して対話形式の一覧を表示するか、ドキュメントサイトを確認します。
4. インストールまたは更新する — npx shadcn-svelte@latest add <name> またはレジストリの URL を使用します。レジストリから既存のファイルを更新するには、npx shadcn-svelte@latest update を使用します（cli.md を参照）。
5. サードパーティ製または URL から追加した項目のインポートを修正する — カスタムレジストリ URL から追加した後、プロジェクトの aliases と一致しないハードコードされたパスがないか確認します。インポートを書き換えて、components.json にあるプロジェクトの ui / lib エイリアスを使用します。
6. 追加したコンポーネントを確認する — 追加した後、追加されたファイルを読み、構成（グループ、タイトル、検証属性）を確認します。アイコンのインポートを iconLibrary に合わせます。
7. リモートレジストリの項目 — URL による追加は明示的な操作です。ユーザーが不明なソースのコンポーネントを希望する場合は、add を実行する前にレジストリ URL または項目を確認してください。

コンポーネントの更新

update コマンドを使用して、プロジェクトにすでにあるコンポーネントの最新のレジストリバージョンを取得します。update の後、git diff で変更を確認してください。

1. ローカルの作業をコミットするか、スタッシュします。
2. npx shadcn-svelte@latest update [component] または --all を実行します。
3. ファイルをカスタマイズしている場合は、マージの競合を解決します。
4. 意図的な編集が失われる場合は、ユーザーの明示的な承認なしに add で --overwrite を使用しないでください。

クイックリファレンス

# Initialize shadcn-svelte in your project.
npx shadcn-svelte@latest init

# Initialize with a preset string from the docs site builder.
npx shadcn-svelte@latest init --preset <code>

# Add components (interactive when run with no names).
npx shadcn-svelte@latest add
npx shadcn-svelte@latest add button card dialog
npx shadcn-svelte@latest add --all

# Update components already installed.
npx shadcn-svelte@latest update button
npx shadcn-svelte@latest update --all --yes

# Build a custom registry (registry authors).
npx shadcn-svelte@latest registry build

レジストリ： デフォルトは https://shadcn-svelte.com/registry です。必要に応じて components.json で上書きできます。
ドキュメント： shadcn-svelte.com

詳細なリファレンス

• rules/forms.md — Field.FieldGroup、Field.Field、InputGroup、ToggleGroup、Field.FieldSet、検証状態
• rules/composition.md — グループ、オーバーレイ、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button の読み込み状態
• rules/icons.md — data-icon、アイコンのサイズ設定、アイコンコンポーネントの渡し方
• rules/styling.md — セマンティックカラー、バリアント、class、間隔、サイズ、省略表示、ダークモード、cn()、z-index
• cli.md — コマンド、フラグ、レジストリ
• customization.md — テーマ設定、CSS 変数、コンポーネントの拡張