Tailwind CSS & shadcn/ui デザインシステム

概要

Tailwind CSS (v4.1+) と shadcn/ui を使用して、集中管理されたデザインシステムを構築・管理するための専門家向けガイドです。このスキルは、デザイントークンの定義、CSS変数によるテーム設定、shadcn/ui プリミティブに基づいた一貫性のあるUIコンポーネントライブラリの構築を実現するための体系的なワークフローを提供します。

他のスキルとの関係:

• tailwind-css-patterns はユーティリティファースト設計、レスポンシブデザイン、一般的なTailwind CSS使用法をカバーします
• shadcn-ui は個別のコンポーネントのインストール、設定、実装をカバーします
• このスキル はシステムレベルの調整に焦点を当てています：デザイントークン、テーミング基盤、コンポーネント ラッピングパターン、およびアプリケーション全体の一貫性を確保します

使用するべき場合

• Tailwind CSS と shadcn/ui を使用して、ゼロからデザインシステムを構築するとき
• デザイントークン (色、タイポグラフィ、間隔、半径、影) を CSS 変数として定義するとき
• globals.css に集中管理されたテーミングシステム (ライト/ダークモード) を設定するとき
• shadcn/ui コンポーネントをデザインシステムプリミティブにラッピングして制約を適用するとき
• トークン駆動のコンポーネントライブラリを構築して一貫性のある UI を実現するとき
• JavaScript ベースの Tailwind 設定から CSS ファーストの設定 (v4.1+) へ移行するとき
• 知覚的均一性のための oklch 形式のカラーパレットを確立するとき
• ライト/ダーク以外の複数のテーマをサポートするとき (例：ブランドテーマ)

手順

ステップ 1: デザインシステム設定の初期化

プロジェクトを設定するために、以下のコマンドを実行してください：

# Tailwind がインストールされているか確認
npx tailwindcss --version

# Tailwind v4 の場合 (推奨)
npx @tailwindcss/vite@latest init   # または: npm install -D tailwindcss @tailwindcss/vite

# shadcn/ui CLI を初期化
npx shadcn@latest init

# コアの shadcn/ui コンポーネントをインストール
npx shadcn@latest add button card input -y

バリデーションチェックポイント: セットアップ後、以下で確認してください：

ls src/components/ui/        # インストール済みコンポーネントが表示されるはず
cat src/app/globals.css       # @tailwind ディレクティブが含まれているはず

ステップ 2: デザイントークンの定義

src/app/globals.css にデザイントークンを記述してください：

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* Brand Colors */
    --primary: oklch(0.55 0.18 250);
    --primary-foreground: oklch(0.985 0 0);

    /* Semantic Colors */
    --background: oklch(0.99 0 0);
    --foreground: oklch(0.15 0 0);
    --secondary: oklch(0.96 0.01 250);
    --secondary-foreground: oklch(0.20 0 0);

    /* Validation: all colors must have foreground pair */
    --destructive: oklch(0.55 0.22 25);
    --destructive-foreground: oklch(0.985 0 0);
  }

  .dark {
    --primary: oklch(0.65 0.20 250);
    --background: oklch(0.14 0 0);
    --foreground: oklch(0.97 0 0);
    --secondary: oklch(0.25 0.02 250);
  }
}

バリデーションチェックポイント: トークンが有効な CSS であることを確認してください：

grep -E "^[[:space:]]*--[a-z-]+:" src/app/globals.css | wc -l
# 定義されたトークンの数を返すはず (例：10 以上)

ステップ 3: テーミング基盤の設定

CSS 変数を Tailwind ユーティリティに結びつけます (Tailwind v4.1+)：

@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

components/providers/theme-provider.tsx に暗いモードのクラストグルを追加してください：

import { useEffect } from "react";
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    document.documentElement.classList.toggle("dark", isDark);
  }, []);
  return <>{children}</>;
}

バリデーションチェックポイント: ダークモードをテストしてください：

document.documentElement.classList.contains("dark") // ブラウザコンソールで実行

ステップ 4: shadcn/ui コンポーネントのラッピング

src/components/ds/Button.tsx を作成してください：

import { Button as ShadcnButton } from "@/components/ui/button";

type DSVariant = "primary" | "secondary" | "destructive" | "ghost";
const variantMap: Record<DSVariant, "default" | "secondary" | "destructive" | "ghost"> = {
  primary: "default", secondary: "secondary",
  destructive: "destructive", ghost: "ghost",
};

export function Button({ variant = "primary", ...props }: { variant?: DSVariant } & React.ComponentProps<typeof ShadcnButton>) {
  return <ShadcnButton variant={variantMap[variant]} {...props} />;
}

バリデーションチェックポイント: ビルドが成功することを確認してください：

npx tsc --noEmit src/components/ds/Button.tsx

ステップ 5: バリデーションとドキュメント

トークンバリデーションスクリプトを実行してください：

REQUIRED=("primary" "primary-foreground" "background" "foreground" "secondary" "secondary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/app/globals.css || echo "MISSING: --$token"
done

バリデーションチェックポイント: すべての shadcn コンポーネントが DS トークンを使用していることを確認してください：

grep -r "bg-primary\|text-primary\|bg-background" src/components/ds/

例

カスタムトークンの追加

globals.css の基本トークンを拡張してください：

:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

使用方法: <div className="bg-warning text-warning-foreground">Warning</div>

shadcn/ui コンポーネントをデザインシステムプリミティブとしてラッピング

完全な例については references/component-wrapping.md を参照してください。Button、Text、Stack プリミティブの完全な TypeScript 型が含まれています。

トークン使用を強制するように制約されたデザインシステムコンポーネントを作成してください。 インライン例：

import { Button as ShadcnButton } from "@/components/ui/button";

export function Button({ variant = "primary", size = "md", ...props }) {
  const variantMap = { primary: "default", secondary: "secondary" };
  const sizeMap = { sm: "sm", md: "default", lg: "lg" };
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      {...props}
    />
  );
}

マルチテーマサポート

ライト/ダーク以上の複数のブランドテーマが必要なアプリケーションの場合：

[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --primary-foreground: oklch(0.985 0 0);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --primary-foreground: oklch(0.985 0 0);
}

const [theme, setTheme] = useState("light");
useEffect(() => {
  document.documentElement.setAttribute("data-theme", theme);
}, [theme]);

デザイントークンのバリデーション

必要なすべてのトークンが定義されていることを確認してください：

#!/bin/bash
REQUIRED=("--background" "--foreground" "--primary" "--primary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/styles/globals.css || echo "Missing: $token"
done

制約と警告

• oklch カラーフォーマット: 知覚的均一性のため oklch を使用してください。すべてのブラウザが natively oklch をサポートしているわけではありません。古いブラウザをターゲットにする場合は互換性を確認してください
• トークンネーミング: shadcn/ui の規約 (--primary, --primary-foreground) に従い、シームレスな統合を実現してください
• @theme inline vs @theme: CSS 変数を Tailwind ユーティリティにブリッジする場合は @theme inline を使用してください。直接トークン定義する場合は @theme を使用してください
• コンポーネントラッピング: ラッパーコンポーネントはシンプルに保ってください。デザインシステムルールを強制する制約のみを追加し、shadcn/ui ロジックの複製を避けてください
• ダークモード: :root 内のすべてのトークンについてダークモード値を常に定義してください。ダークトークンの欠落は視覚的な退行を引き起こします
• CSS 変数スコープ: :root で定義されたトークンはグローバルです。複数テーマで競合を避けるために [data-theme] セレクタを使用してください
• パフォーマンス: 過度な CSS カスタムプロパティチェーンを避けてください。各 var() 検索はわずかですが ゼロではないオーバーヘッドを追加します
• Tailwind v4 vs v3: @theme ディレクティブと @theme inline は v4.1+ の機能です。v3 プロジェクトの場合は、tailwind.config.js で theme.extend を使用してください

ベストプラクティス

1. 単一の情報源: すべてのデザイントークンは globals.css に存在します。コンポーネント内にカラー値をハードコードしないでください
2. セマンティックネーミング: 外観ベース (--blue-500, --red-600) ではなく、目的ベース (--primary, --destructive) の名前を使用してください
3. フォアグラウンドペアリング: すべての背景トークンには、コントラスト準拠のため対応する -foreground トークンが必要です
4. トークンスケール: カスタムパレット (50-950) の完全なスケールを定義して、柔軟性を提供してください
5. コンポーネントバレルエクスポート: クリーンなインポートのため、すべての DS コンポーネントを単一の index.ts からエクスポートしてください
6. アクセシビリティ: すべてのトークンペア (背景/フォアグラウンド) が WCAG AA コントラスト (テキストは 4.5:1、大きいテキストは 3:1) を満たしていることを確認してください
7. トークンのドキュメント化: チームのためにすべてのトークンの視覚的リファレンスを保持してください
8. 一貫した間隔: 任意の値ではなく、DS コンポーネント経由で Tailwind の間隔スケール (gap-2, gap-4, gap-6) を使用してください

参照

• Tailwind CSS v4 Theme Configuration: https://tailwindcss.com/docs/theme
• Tailwind CSS Functions and Directives: https://tailwindcss.com/docs/functions-and-directives
• shadcn/ui Theming Guide: https://ui.shadcn.com/docs/theming
• shadcn/ui Installation (Manual): https://ui.shadcn.com/docs/installation/manual
• oklch Color Space: https://oklch.com