niamkvn/shadcn-svelte

shadcn-svelte は何をしますか？

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

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

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

プロジェクトルートにある components.json を読み取り、ライブファイルレイアウトが必要な場合は、aliases.ui パスで指定されたディレクトリをリスト表示してください（CLI と同じルールで解決します）。

インポート（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 を書く前に Components を確認してください。
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-* は使わない。 flex と gap-* を使用してください。垂直方向のスタックには flex flex-col gap-* を使用します。
• 幅と高さが等しい場合は size-* を使用する。 size-10 を使用し、w-10 h-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 を使用する。 フォームレイアウトに生の div と space-y-* や grid gap-* を使用しないでください。
• 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 を使用する。 Field には data-invalid、コントロールには aria-invalid を設定します。無効の場合：Field には data-disabled、コントロールには disabled を設定します。

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

• アイテムは常にそのグループ内に配置する。 Select.Item → Select.Group。DropdownMenu.Item → DropdownMenu.Group。Command.Item → Command.Group。
• カスタムトリガー。 コントロールを Dialog.Trigger / AlertDialog.Trigger でラップするか、ルートで bind:open を使用して開閉状態を制御します — コンポーネントのドキュメントを参照してください。
• Dialog、Sheet、Drawer には常に Title が必要。 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() を使用します。
• Separator を使用する。 <hr> や境界線のみのクラスを持つ div の代わりに使用します。
• ローディングプレースホルダには Skeleton を使用する。 カスタムの animate-pulse div は使わないでください。
• Badge を使用する。 カスタムスタイルの span の代わりに使用します。

アイコン → 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、 div + Label ではありません。 -->
<Field.FieldGroup>
  <Field.Field>
    <Field.FieldLabel for="email">メールアドレス</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>

<!-- バリデーション: Field に data-invalid、コントロールに aria-invalid -->
<Field.Field data-invalid>
  <Field.FieldLabel for="email">メールアドレス</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>無効なメールアドレスです。</Field.FieldDescription>
</Field.Field>

<!-- ボタン内のアイコン: data-icon、サイズクラスは不要 -->
<Button>
  <SearchIcon data-icon="inline-start" />
  検索
</Button>

<!-- 間隔: gap-*、space-y-* ではありません。 -->
<div class="flex flex-col gap-4"></div>

<!-- 等しい寸法: size-*、w-* h-* ではありません。 -->
<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="ユーザー" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>

<!-- 状態色: Badge バリアントまたはセマンティックトークン、生の色ではありません。 -->
<Badge variant="secondary">+20.1%</Badge>

コンポーネント選択

ニーズ	使用するコンポーネント
ボタン/アクション	適切な variant の 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

主要フィールド

components.json とファイルシステムを使用します。別個の info コマンドは使用しません：

• aliases → 設定からの実際のエイリアスプレフィックス（例：$lib/）を使用します。無関係なプロジェクトをハードコードしないでください。
• tailwind.css → テーマ変数が存在するグローバル CSS ファイル。テーマの調整にはこのファイルを編集します。ユーザーが既に使用していない限り、2つ目のグローバルファイルを追加しないでください。
• 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 またはアイテムを確認します。

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

ユーザーが DESIGN.md（またはブランド仕様）からデザインシステムを要求した場合、プリセットの有無にかかわらず、design-system.md に従って最初から最後まで実行します：

1. 新しいアプリの場合、npx sv create <app> で SvelteKit をスキャフォールドし（または要求に応じて Svelte + Vite）、npx shadcn-svelte@latest init --preset <code> で初期化します。コードがない場合は、DESIGN.md に合ったスタイルを選び、その名前を渡します（例：init --preset luma）。React のプリセットコードとスキャフォールディングフラグは適用されません。既存のアプリでは、ローカルのカスタマイズを保持します。
2. 新しいアプリでは add --all --yes ですべてのコンポーネントをインストールします。既存のアプリでは不足しているコンポーネントのみを追加します。
3. 編集前に DESIGN.md のフロントマター、Do's and Don'ts、既知のギャップを読みます。
4. そのトークンを components.json の tailwind.css の変数にマッピングします。半径スケール、シャドウ、フォント、type-* ユーティリティを固定します。
5. インストール済みの tailwind-variants バリアントと関連スタイル CSS を再スタイリングします。コントロールの高さを一緒に変更します。
6. design-system-page.md に従ってページを構築します：コントラストチェックされたカラーロール、タイプ見本、固定状態行列、エッジケース、Do/Don't ペア、レシピ。scripts/showcase-coverage.mjs でインポートを確認し、すべてのコンポーネントがレンダリングされることを確認します。
7. ブラウザで確認：svelte-check、SSR を含むプロダクションビルド、コンソールエラーなし、上部に読み込まれる、横方向オーバーフローなし、ダークモード。

コンポーネントの更新

update コマンドを使用して、プロジェクト内のコンポーネントの最新レジストリバージョンを取得します。update 後は git diff で変更をレビューします。

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

クイックリファレンス

# yo プロジェクトで shadcn-svelte を初期化

…

[翻訳のために一部省略]