Claude Code × Tailwind CSS v4 デザインシステム構築ガイド｜@themeトークン・shadcn/ui統合・ダークモード・CLAUDE.md設定

# 自動移行ツールで一括変換
npx @tailwindcss/upgrade

# 手動で必要なもの:
# 1. tailwind.config.jsの内容をglobals.cssの@themeに移す
# 2. darkModeの設定を@custom-variantに移す
# 3. tailwindcss-animateをtw-animate-cssに置換

@import "tailwindcss";

/* デフォルトテーマをリセットして独自トークンのみ定義する場合 */
@theme {
  /* カラー: --color-* で定義 → bg-primary, text-primary 等が使える */
  --color-primary-50:  oklch(0.97 0.02 250);
  --color-primary-100: oklch(0.93 0.04 250);
  --color-primary-500: oklch(0.60 0.16 250);
  --color-primary-600: oklch(0.53 0.16 250);
  --color-primary-900: oklch(0.25 0.08 250);

  --color-gray-50:  oklch(0.98 0 0);
  --color-gray-100: oklch(0.96 0 0);
  --color-gray-500: oklch(0.55 0 0);
  --color-gray-900: oklch(0.15 0 0);

  /* フォント: --font-* → font-sans, font-mono が使える */
  --font-sans: "Inter", "Noto Sans JP", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* 角丸: --radius-* → rounded-sm, rounded-md 等が使える */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
  --radius-xl: 1rem;

  /* シャドウ */
  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px oklch(0 0 0 / 0.07);
}

/* Layer 1: Base（プリミティブ） */
:root {
  --color-blue-500: oklch(0.60 0.16 250);
  --color-blue-600: oklch(0.53 0.16 250);
  --color-gray-50: oklch(0.98 0 0);
  --color-gray-900: oklch(0.15 0 0);
}

/* Layer 2: Semantic（意図ベース） */
:root {
  --background: var(--color-gray-50);
  --foreground: var(--color-gray-900);
  --primary: var(--color-blue-600);
  --primary-foreground: oklch(0.98 0 0);
  --destructive: oklch(0.55 0.22 25);
}
.dark {
  --background: var(--color-gray-900);
  --foreground: var(--color-gray-50);
  --primary: oklch(0.65 0.16 250);
}

/* Layer 3: Tailwindユーティリティに接続 */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-destructive: var(--destructive);
}

/* globals.css */
@custom-variant dark (&:where(.dark, .dark *));

/* これで dark:bg-gray-900 等が .dark クラスの子要素で有効になる */

import { useEffect, useState } from "react";

export function ThemeToggle() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    // 初期値: OS設定 or localStorage
    const saved = localStorage.getItem("theme");
    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    setDark(saved === "dark" || (!saved && prefersDark));
  }, []);

  useEffect(() => {
    document.documentElement.classList.toggle("dark", dark);
    localStorage.setItem("theme", dark ? "dark" : "light");
  }, [dark]);

  return (
    <button onClick={() => setDark((d) => !d)}>
      {dark ? "☀️ ライト" : "? ダーク"}
    </button>
  );
}

# Claude Codeにshadcn/uiの知識を追加
pnpm dlx skills add shadcn/ui

# → Claude Codeがshadcn/uiの最新API・バリアント・プロパティを
#   正確に把握した状態でコンポーネントを生成できるようになる

# プリセットで初期設定を一括投入
pnpm dlx shadcn@latest init --preset a1Dg5eFl

# 変更を事前確認（ファイル変更なし）
pnpm dlx shadcn@latest add dialog --dry-run

# 差分を確認
pnpm dlx shadcn@latest add dialog --diff

# コンポーネントのドキュメントを取得
pnpm dlx shadcn@latest docs combobox

UserProfileCardコンポーネントを作成してください。

要件:
- shadcn/ui Card をベースに
- Avatar（shadcn/ui）で丸アバター表示
- 名前（font-bold）、メールアドレス、ロールバッジ（Badge）
- ダークモード対応（dark: プレフィックス使用）
- レスポンシブ: モバイルは縦積み、md以上で横並び
- loading時のSkeleton状態も含める
- TypeScript型定義付き
- デザイントークン（globals.css）の変数を使用すること

import { Card, CardContent } from "@/components/ui/card";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import { Skeleton } from "@/components/ui/skeleton";

interface UserProfileCardProps {
  user?: {
    name: string;
    email: string;
    avatarUrl: string;
    role: "admin" | "member" | "viewer";
  };
  loading?: boolean;
}

const roleBadgeVariant = {
  admin: "destructive",
  member: "default",
  viewer: "secondary",
} as const;

export function UserProfileCard({ user, loading }: UserProfileCardProps) {
  if (loading) {
    return (
      <Card>
        <CardContent className="flex flex-col md:flex-row items-center gap-4 p-6">
          <Skeleton className="h-16 w-16 rounded-full" />
          <div className="space-y-2">
            <Skeleton className="h-4 w-32" />
            <Skeleton className="h-3 w-48" />
          </div>
        </CardContent>
      </Card>
    );
  }

  if (!user) return null;

  return (
    <Card>
      <CardContent className="flex flex-col md:flex-row items-center gap-4 p-6">
        <Avatar className="h-16 w-16">
          <AvatarImage src={user.avatarUrl} alt={user.name} />
          <AvatarFallback>{user.name.charAt(0)}</AvatarFallback>
        </Avatar>
        <div className="text-center md:text-left">
          <p className="font-bold text-foreground">{user.name}</p>
          <p className="text-sm text-muted-foreground">{user.email}</p>
          <Badge variant={roleBadgeVariant[user.role]} className="mt-1">
            {user.role}
          </Badge>
        </div>
      </CardContent>
    </Card>
  );
}

## デザインシステム

### テクノロジースタック
- Tailwind CSS v4（CSS-First。tailwind.config.jsは使わない）
- shadcn/ui（Radix UIベース。CLIでインストール。直接編集禁止）
- Lucide React（アイコン）

### カラー
- プライマリ: primary-500〜primary-900（globals.cssの@theme定義を使う）
- グレースケール: gray-50〜gray-900
- すべてOKLCH形式で定義
- ハードコードされた色（#ff0000等）は禁止。必ずデザイントークンを使う

### スペーシング
- コンポーネント間: gap-4 (16px) 以上
- セクション間: py-16 (64px) 以上
- 任意値（pl-[17px]等）は禁止。デフォルトスケールから選ぶ

### タイポグラフィ
- Sans: Inter + Noto Sans JP
- Mono: JetBrains Mono
- 見出し: font-bold tracking-tight
- 本文: text-base leading-relaxed

### コンポーネントルール
- 新規UI部品はshadcn/uiを先に検討。なければTailwindで自作
- dark:対応は必須（すべてのコンポーネント）
- inline style禁止
- !important禁止
- className: clsx() または cn() で条件付きクラスを結合

### 命名規約
- ファイル: kebab-case (user-profile-card.tsx)
- コンポーネント: PascalCase (UserProfileCard)
- Props: TypeScript interface定義必須

/* カスタムユーティリティ: hover:やdark:等全バリアントが自動適用される */
@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* 使い方: <div class="scrollbar-hidden hover:scrollbar-auto"> */

@utility text-balance {
  text-wrap: balance;
}

/* 使い方: <h1 class="text-balance"> */

/* ダークモード（class戦略） */
@custom-variant dark (&:where(.dark, .dark *));

/* RTL対応 */
@custom-variant rtl (&:where([dir="rtl"] *));

/* 使い方: <div class="rtl:text-right"> */

/* 印刷時のスタイル */
@custom-variant print (@media print);

/* 使い方: <div class="print:hidden"> */