shadcn-theming

shadcn/ui のデザイントークンとテーマ設定：CSS カスタムプロパティ（`--background`、`--primary` など）、広色域の OKLCH カラー、`.dark` クラスまたは `prefers-color-scheme` によるダーク／ライトモード、Tailwind v4 の `@theme` ディレクティブとの統合について説明します。Base UI、Radix、React Aria のすべてのベースで同じ設定を使用できます。また、7 つのベースカラー、プリセット（`init --preset`、`apply --preset --only theme,font`）、`migrate base-color`、`shadcn/tailwind.css`／`eject`、レンダリングされたマークダウン用の shadcn/typeset についても扱います。

コンポーネント → セマンティック → プリミティブな OKLCH 値というトークン階層と、検証チェックリスト（ダークモードのオーバーライド、チャート／サイドバーの変数、16 進数のハードコード禁止）について説明します。

shadcn のテーマ設定

エージェントのワークフロー（必須）

テーマ設定の作業を始める前に、各 Agent 呼び出しに name を指定して、以下のエージェントを並行して起動します。

1. fuse-ai-pilot:explore-codebase - 既存のテーマトークンを確認します
2. fuse-ai-pilot:research-expert - Context7 を使用して OKLCH のパターンを検証します

その後、検証のために fuse-ai-pilot:sniper を実行します。

概要

機能	説明
CSS 変数	--background、--foreground、--primary
OKLCH カラー	広色域の P3 色空間
ダークモード	.dark クラスまたは prefers-color-scheme
Tailwind v4	@theme inline ディレクティブとの統合 + @custom-variant dark
ベースカラー	tailwind.baseColor：neutral、stone、zinc、mauve、olive、mist、taupe（初期化時に設定し、migrate base-color --to <c> で切り替えます）
プリセット	スタイル、ベースカラー、テーマ、チャートカラー、アイコン、フォント、角丸、メニューカラー／アクセントをまとめた短いコードです（ui.shadcn.com/create で作成します）
角丸のスケール	@theme inline を介して、--radius により --radius-sm 〜 --radius-4xl を設定します

テーマ CLI（shadcn 4.21.0 で確認済み）

{runner} shadcn@latest init --preset <code>                 # new project from a preset
{runner} shadcn@latest apply --preset <code>                # switch preset: reinstalls components, keeps base + RTL
{runner} shadcn@latest apply --preset <code> --only theme   # or --only font, --only theme,font
{runner} shadcn@latest preset decode <code>                 # also: resolve (current project), url, open
{runner} shadcn@latest migrate base-color --to zinc --yes   # rewrite theme CSS vars + baseColor
{runner} shadcn@latest init --no-css-variables              # inline utilities instead of tokens (install-time only)
{runner} shadcn@latest init --pointer                       # cursor: pointer on buttons (not part of presets)
{runner} shadcn@latest eject                                # inline shadcn/tailwind.css, drop the shadcn dependency

重要なルール

1. すべてのトークンに必ず OKLCH 色空間を使用します
2. すべてのトークンに対して、必ずダークモードのオーバーライドを定義します
3. コンポーネント内で 16 進数や rgb を絶対にハードコードしません
4. Tailwind v4 との統合には @theme inline ディレクティブを使用します
5. セマンティックトークンをプリミティブな OKLCH 値に対応付けます

アーキテクチャ

app/
├── globals.css         # :root + .dark token definitions
└── tailwind.config.ts  # Optional (v3) or @theme (v4)

-> テーマの全設定については、theme-setup.md を参照してください

トークン階層

Component: --card, --card-foreground, --button-*
    ↑
Semantic: --primary, --secondary, --accent, --muted
    ↑
Primitive: oklch(55% 0.20 260), oklch(98% 0.01 260)

検証チェックリスト

[ ] CSS variables defined in :root
[ ] Dark mode overrides in .dark
[ ] OKLCH color space used
[ ] Chart variables (--chart-1 to --chart-5)
[ ] Sidebar variables if applicable
[ ] New tokens defined in :root + .dark AND exposed in @theme inline (--color-*)
[ ] No hard-coded hex in components

ベストプラクティス

推奨事項

• すべてのカラーに OKLCH を使用します
• プリミティブに対応付けたセマンティックトークンを定義します
• すべてのトークンにダークモードのオーバーライドを用意します
• Tailwind v4 との統合には @theme inline を使用します

避けるべきこと

• 16 進数や rgb 値をハードコードすること
• ダークモードの定義を省略すること
• 色空間を混在させること（hex と oklch）
• Tailwind の設定だけでトークンを定義すること

リファレンスガイド

概念

トピック	リファレンス	参照するタイミング
テーマ設定ガイド	theming-guide.md	CSS 変数、OKLCH、ベースカラー、新しいトークン、typeset

テンプレート

テンプレート	使用する場面
theme-setup.md	テーマの全設定