tailwind-v4-shadcn

Name: tailwind-v4-shadcn
Author: secondsky

github.com/secondskyデザイン・UI2408.1k 回インストール5 週間前に更新

tailwind-v4-shadcn について

tailwind-v4-shadcnは、Tailwind v4とshadcn/uiの設定ガイド、テンプレート、トラブルシューティングを提供するエージェントスキルです。Vite設定、セマンティックカラーのトークン、ダークモードのパターンを扱います。

主な機能

01Tailwind v4とshadcn/uiの設定ガイド
02Vite設定とファイルテンプレート
03CSS変数とセマンティックトークンのパターン
04ダークモード設定ガイド
05トラブルシューティングと移行資料

活用シーン

01Tailwind v4を使うViteプロジェクトの設定
02shadcn/uiのカラートークン設定
03テーマやビルド設定の問題の調査
04Tailwind v3のパターンからの移行

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/secondsky/claude-skills --skill tailwind-v4-shadcn

インストール後、Claude Code で/tailwind-v4-shadcnを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

advanced-usage.md

common-gotchas.md

dark-mode.md

migration-guide.md

plugins-reference.md

templates/

components.json

index.css

theme-provider.tsx

tsconfig.app.json

utils.ts

vite.config.ts

詳細

Tailwind v4 + shadcn/ui 本番環境向けスタック

本番環境でテスト済み：WordPress Auditor（https://wordpress-auditor.webfonts.workers.dev） 最終更新日：2025-12-04 ステータス：本番環境で使用可能 ✅

始める前に
クイックスタート
4 ステップのアーキテクチャ
ダークモードの設定
重要なルール
セマンティックカラーのトークン
よくある問題と修正方法
ファイルのテンプレート
セットアップチェックリスト
高度なトピック
依存関係
Tailwind v4 プラグイン
リファレンスドキュメント
リファレンスを読み込むタイミング

⚠️ 始める前に（必ずお読みください！）

AI エージェントにとって重要：Tailwind v4 のセットアップを支援する Claude Code の場合：

会話の最初に、このスキルを使用していることを明示してください
一般知識ではなく、スキルに記載されたパターンを参照してください
reference/common-gotchas.md に記載されている既知の問題を未然に防いでください
推測しないでください。確信がない場合は、スキルのドキュメントを確認してください

ユーザーの操作が必要です：まずこのスキルを確認するよう、Claude に伝えてください！

次のように伝えます：「Tailwind v4 + shadcn/ui をセットアップしています。まず tailwind-v4-shadcn スキルを確認してください」

重要な理由（実際の結果）

スキルを有効にしない場合：

❌ セットアップ時間：約 5 分
❌ 発生したエラー：2～3 件（tw-animate-css、@layer base の重複）
❌ 必要な手動修正：2 件以上のコミット
❌ トークン使用量：約 65k
❌ ユーザーの自信：デバッグが必要

スキルを有効にした場合：

✅ セットアップ時間：約 1 分
✅ 発生したエラー：0 件
✅ 必要な手動修正：0 件
✅ トークン使用量：約 20k（70% 削減）
✅ ユーザーの自信：すぐに成功

このスキルで防げる既知の問題

tw-animate-css のインポートエラー（v4 では非推奨）
@layer base ブロックの重複（shadcn の初期化時に独自のブロックが追加される）
誤ったテンプレートの選択（vanilla TS と React の取り違え）
初期化後のクリーンアップ漏れ（互換性のない CSS ルール）
誤ったプラグイン構文（@plugin ディレクティブではなく、@import または require() を使用）

スキルが有効な場合、これらの問題はすべて自動的に処理されます。

クイックスタート（5 分。必ずこの順序で実行してください）

1. 依存関係をインストールする

bun add tailwindcss @tailwindcss/vite
# or: npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# Note: Using pnpm for shadcn init due to known Bun compatibility issues
# (bunx has "Script not found" and postinstall/msw problems)
pnpm dlx shadcn@latest init

2. Vite を設定する

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. components.json を更新する

{
  "tailwind": {
    "config": "",              // ← CRITICAL: Empty for v4
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. tailwind.config.ts を削除する

rm tailwind.config.ts  # v4 doesn't use this file

4 ステップのアーキテクチャ（重要）

このパターンは必須です。手順を省略すると、テーマが正しく動作しなくなります。

ステップ 1：ルートレベルで CSS 変数を定義する

/* src/index.css */
@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... all light mode colors */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... all dark mode colors */
}

重要なルール：

✅ ルートレベルで定義する（@layer base の中ではない）
✅ すべてのカラー値を hsl() で囲む
✅ ダークモードには .dark を使用する（.dark { @theme { } } は使用しない）

ステップ 2：変数を Tailwind ユーティリティにマッピングする

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... map ALL CSS variables */
}

これが必要な理由：

ユーティリティクラス（bg-background、text-primary）を生成する
これがないと、bg-primary などは存在しない

ステップ 3：ベーススタイルを適用する

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() here */
    color: var(--foreground);
  }
}

重要なルール：

✅ 変数を直接参照する：var(--background)
❌ 二重に囲まない：hsl(var(--background))

ステップ 4：結果 — ダークモードが自動的に適用される

<div className="bg-background text-foreground">
  {/* No dark: variants needed - theme switches automatically */}
</div>

ダークモードの設定

1. ThemeProvider を作成する

完全な実装は reference/dark-mode.md を参照するか、テンプレートを使用してください。

// Copy from: templates/theme-provider.tsx

2. アプリをラップする

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. テーマ切り替えを追加する

pnpm dlx shadcn@latest add dropdown-menu

ModeToggle コンポーネントのコードは reference/dark-mode.md を参照してください。

重要なルール（必ず守ってください）

✅ 必ず実施すること：

:root と .dark では、色の値を hsl() で囲みます
```
--background: hsl(0 0% 100%);  /* ✅ Correct */
```
すべての CSS 変数のマッピングには @theme inline を使用します
```
@theme inline {
  --color-background: var(--background);
}
```
components.json で "tailwind.config": "" を設定します
```
{ "tailwind": { "config": "" } }
```
tailwind.config.ts が存在する場合は削除します
@tailwindcss/vite プラグインを使用します（PostCSS は使用しません）

条件付きクラスには cn() を使用します

import { cn } from "@/lib/utils"
<div className={cn("base", isActive && "active")} />

❌ 絶対にしないこと：

:root や .dark を @layer base の中に配置します

/* WRONG */
@layer base {
  :root { --background: hsl(...); }
}

.dark { @theme { } } のパターンを使用します

/* WRONG - v4 doesn't support nested @theme */
.dark {
  @theme {
    --color-primary: hsl(...);
  }
}

色を二重に囲みます

/* WRONG */
body {
  background-color: hsl(var(--background));
}

テーマカラーに tailwind.config.ts を使用します

/* WRONG - v4 ignores this */
export default {
  theme: {
    extend: {
      colors: { primary: 'hsl(var(--primary))' }
    }
  }
}

@apply ディレクティブを使用します（v4 では非推奨です）

セマンティックカラーに dark: バリアントを使用します

/* WRONG */
<div className="bg-primary dark:bg-primary-dark" />

/* CORRECT */
<div className="bg-primary" />

セマンティックカラートークン

色には常にセマンティックな名前を使用します：

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* Red - errors, critical */
  --success: hsl(142.1 76.2% 36.3%);        /* Green - success states */
  --warning: hsl(38 92% 50%);               /* Yellow - warnings */
  --info: hsl(221.2 83.2% 53.3%);           /* Blue - info, primary */
}

使用方法：

<div className="bg-destructive text-destructive-foreground">Critical</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>

よくある問題と簡単な修正方法

症状	原因	修正方法
`bg-primary` が機能しない	`@theme inline` のマッピングがない	`@theme inline` ブロックを追加する
すべての色が黒または白になる	`hsl()` による二重ラップ	`hsl(var(--color))` ではなく `var(--color)` を使用する
ダークモードが切り替わらない	ThemeProvider がない	アプリを `<ThemeProvider>` で囲む
ビルドに失敗する	`tailwind.config.ts` が存在する	ファイルを削除する
テキストが見えない	コントラストカラーが間違っている	`:root`／`.dark` の色の定義を確認する

トラブルシューティングの詳細については、reference/common-gotchas.md を参照してください。

ファイルテンプレート

すべてのテンプレートは templates/ ディレクトリにあります：

index.css - すべての色変数を含む CSS の完全なセットアップ
components.json - shadcn/ui v4 の設定
vite.config.ts - Vite と Tailwind プラグインのセットアップ
tsconfig.app.json - パスエイリアスを設定した TypeScript
theme-provider.tsx - localStorage を使用するダークモードプロバイダー
utils.ts - クラスを結合する cn() ユーティリティ

これらのファイルをプロジェクトにコピーし、必要に応じてカスタマイズしてください。

セットアップの完全なチェックリスト

高度なトピック

高度なパターンについては references/advanced-usage.md を読み込んでください。以下の内容が含まれています：

カスタムカラー：デフォルトのパレット以外のセマンティックカラーを追加する
v3 からの移行：完全なガイドについては references/migration-guide.md を参照
コンポーネントのベストプラクティス：セマンティックトークン、cn() ユーティリティ、コンポジションパターン

簡単な例：

:root { --brand: hsl(280 65% 60%); }
@theme inline { --color-brand: var(--brand); }

使用方法：<div className="bg-brand">Branded</div>

詳しいパターンやコンポーネントのコンポジション例については、references/advanced-usage.md を読み込んでください。

依存関係

✅ こちらをインストールしてください

{
  "dependencies": {
    "tailwindcss": "^4.1.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.554.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@vitejs/plugin-react": "^5.2.0",
    "vite": "^7.2.4",
    "typescript": "~5.9.3"
  }
}

❌ 絶対にインストールしないでください（v4 では非推奨）

# These packages will cause build errors:
bun add tailwindcss-animate  # ❌ Deprecated
# or: npm install tailwindcss-animate  # ❌ Deprecated

bun add tw-animate-css      # ❌ Doesn't exist

これらのパッケージのインポートエラーが表示された場合は、削除し、代わりにネイティブ CSS アニメーションまたは @tailwindcss/motion を使用してください。

Tailwind v4 プラグイン

Tailwind v4 では、CSS 内の @plugin ディレクティブを使って公式プラグインをサポートしています。

簡単な例：

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

よくあるエラー： ❌ 誤り：@import "@tailwindcss/typography"（動作しません） ✅ 正しい：@plugin "@tailwindcss/typography"（@plugin ディレクティブを使用）

**組み込み機能：**コンテナークエリーがコア機能になったため、@tailwindcss/container-queries プラグインは不要です。

Typography プラグイン（prose クラス）、Forms プラグイン、インストール手順、よくあるプラグインのエラーを含む詳細なドキュメントについては、references/plugins-reference.md を読み込んでください。

リファレンスドキュメント

詳しくは、以下をご覧ください。

common-gotchas.md - 発生しうる問題とその解決方法
dark-mode.md - ダークモードの完全な実装
migration-guide.md - ハードコードされた色を CSS 変数に移行する方法
plugins-reference.md - 公式 Tailwind v4 プラグイン（Typography、Forms）
advanced-usage.md - カスタムカラーと高度なパターン

リファレンスを読み込むタイミング

ユーザーの具体的なニーズに応じて、リファレンスファイルを読み込みます。

次の場合は `references/common-gotchas.md` を読み込みます：

ユーザーから「色が機能しない」または「bg-primary が見つからない」と報告された場合
ダークモードが正しく切り替わらない場合
Tailwind のエラーでビルドが失敗する場合
ユーザーが CSS や設定に関する問題に遭遇した場合
テーマの問題をデバッグする場合

次の場合は `references/dark-mode.md` を読み込みます：

ユーザーからダークモードの実装を求められた場合
テーマの切り替えが機能しない場合
ThemeProvider コンポーネントのコードが必要な場合
システムテーマの検出について質問された場合

次の場合は `references/migration-guide.md` を読み込みます：

Tailwind v3 から v4 へ移行する場合
ユーザーがハードコードされた色を移行する必要がある場合
v3 から v4 への変更について質問された場合
移行チェックリストが必要な場合

次の場合は `references/plugins-reference.md` を読み込みます：

ユーザーが Typography プラグイン（prose クラス）を必要としている場合
ユーザーが Forms プラグインを必要としている場合
@plugin ディレクティブについて質問された場合
プラグインのインストールエラーが発生した場合

次の場合は `references/advanced-usage.md` を読み込みます：

ユーザーからデフォルト以外のカスタムカラーについて質問された場合
高度なコンポーネントパターンが必要な場合
コンポーネントのベストプラクティスについて質問された場合
コンポーネントの合成について質問された場合

公式ドキュメント

shadcn/ui Vite Setup：https://ui.shadcn.com/docs/installation/vite
shadcn/ui Tailwind v4 Guide：https://ui.shadcn.com/docs/tailwind-v4
shadcn/ui Dark Mode (Vite)：https://ui.shadcn.com/docs/dark-mode/vite
Tailwind v4 Docs：https://tailwindcss.com/docs
shadcn/ui Theming：https://ui.shadcn.com/docs/theming

安全なインストール

Tailwind および shadcn/ui パッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください。

インストール後のスクリプトをブロックする — npm config set ignore-scripts true（または Bun：デフォルトで無効）
クールダウン期間 — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待ちます
インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認します

完全なセキュリティ設定（Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI による適用を含む）については、dependency-upgrade スキルを読み込んでください。

本番環境での例

このスキルは WordPress Auditor プロジェクトに基づいています。

公開環境：https://wordpress-auditor.webfonts.workers.dev
技術スタック：Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
ダークモード：システム／ライト／ダークの完全なサポート
バージョン：Tailwind v4.1.17 + shadcn/ui latest（2025 年 11 月）

このスキルに含まれるすべてのパターンは、本番環境で検証済みです。

質問や問題がありますか？

まず reference/common-gotchas.md を確認します
4 ステップのアーキテクチャの全手順を確認します
components.json に "config": "" が含まれていることを確認します
tailwind.config.ts が存在する場合は削除します
公式ドキュメントを確認します：https://ui.shadcn.com/docs/tailwind-v4

Markdown 対応

ログインしてコメント

基本情報

作者: secondsky
リポジトリ: secondsky/claude-skills
カテゴリ: デザイン・UI
インストール数: 8,109
GitHub スター: 240

問題を報告