Blaise1030/astro-marketing

Tailwind 設計系統 (v4)

使用 Tailwind CSS v4 建立可供生產環境使用的設計系統，包含 CSS-first 配置、設計代碼、元件變體、響應式模式和無障礙性。

注意：此技能針對 Tailwind CSS v4 (2024+)。若為 v3 專案，請參閱升級指南。

何時使用此技能

• 使用 Tailwind v4 建立元件庫
• 使用 CSS-first 配置實作設計代碼和主題
• 建立響應式且無障礙的元件
• 在程式碼庫中標準化 UI 模式
• 從 Tailwind v3 遷移到 v4
• 使用原生 CSS 功能設定深色模式

主要的 v4 變更

v3 模式	v4 模式
tailwind.config.ts	CSS 中的 @theme
@tailwind base/components/utilities	@import "tailwindcss"
darkMode: "class"	@custom-variant dark (&:where(.dark, .dark *))
theme.extend.colors	@theme { --color-*: value }
require("tailwindcss-animate")	CSS @keyframes 在 @theme 中 + 用於進入動畫的 @starting-style

快速開始

/* app.css - Tailwind v4 CSS-first 配置 */
@import "tailwindcss";

/* 使用 @theme 定義你的主題 */
@theme {
  /* 使用 OKLCH 的色彩語意代碼，以獲得更好的色彩感知 */
  --color-background: oklch(100% 0 0);
  --color-foreground: oklch(14.5% 0.025 264);

  --color-primary: oklch(14.5% 0.025 264);
  --color-primary-foreground: oklch(98% 0.01 264);

  --color-secondary: oklch(96% 0.01 264);
  --color-secondary-foreground: oklch(14.5% 0.025 264);

  --color-muted: oklch(96% 0.01 264);
  --color-muted-foreground: oklch(46% 0.02 264);

  --color-accent: oklch(96% 0.01 264);
  --color-accent-foreground: oklch(14.5% 0.025 264);

  --color-destructive: oklch(53% 0.22 27);
  --color-destructive-foreground: oklch(98% 0.01 264);

  --color-border: oklch(91% 0.01 264);
  --color-ring: oklch(14.5% 0.025 264);

  --color-card: oklch(100% 0 0);
  --color-card-foreground: oklch(14.5% 0.025 264);

  /* 焦點狀態的環狀偏移 */
  --color-ring-offset: oklch(100% 0 0);

  /* 圓角代碼 */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;

  /* 動畫代碼 - 當透過 --animate-* 變數引用時，@theme 中的 keyframes 才會輸出 */
  --animate-fade-in: fade-in 0.2s ease-out;
  --animate-fade-out: fade-out 0.2s ease-in;
  --animate-slide-in: slide-in 0.3s ease-out;
  --animate-slide-out: slide-out 0.3s ease-in;

  @keyframes fade-in {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }

  @keyframes fade-out {
    from {
      opacity: 1;
    }
    to {
      opacity: 0;
    }
  }

  @keyframes slide-in {
    from {
      transform: translateY(-0.5rem);
      opacity: 0;
    }
    to {
      transform: translateY(0);
      opacity: 1;
    }
  }

  @keyframes slide-out {
    from {
      transform: translateY(0);
      opacity: 1;
    }
    to {
      transform: translateY(-0.5rem);
      opacity: 0;
    }
  }
}

/* 深色模式變體 - 使用 @custom-variant 進行基於 class 的深色模式 */
@custom-variant dark (&:where(.dark, .dark *));

/* 深色模式主題覆寫 */
.dark {
  --color-background: oklch(14.5% 0.025 264);
  --color-foreground: oklch(98% 0.01 264);

  --color-primary: oklch(98% 0.01 264);
  --color-primary-foreground: oklch(14.5% 0.025 264);

  --color-secondary: oklch(22% 0.02 264);
  --color-secondary-foreground: oklch(98% 0.01 264);

  --color-muted: oklch(22% 0.02 264);
  --color-muted-foreground: oklch(65% 0.02 264);

  --color-accent: oklch(22% 0.02 264);
  --color-accent-foreground: oklch(98% 0.01 264);

  --color-destructive: oklch(42% 0.15 27);
  --color-destructive-foreground: oklch(98% 0.01 264);

  --color-border: oklch(22% 0.02 264);
  --color-ring: oklch(83% 0.02 264);

  --color-card: oklch(14.5% 0.025 264);
  --color-card-foreground: oklch(98% 0.01 264);

  --color-ring-offset: oklch(14.5% 0.025 264);
}

/* 基本樣式 */
@layer base {
  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground antialiased;
  }
}

核心概念

1. 設計代碼階層

品牌代碼 (抽象)
    └── 語意代碼 (用途)
        └── 元件代碼 (特定)

範例：
    oklch(45% 0.2 260) → --color-primary → bg-primary

2. 元件架構

基本樣式 → 變體 → 尺寸 → 狀態 → 覆寫

詳細模式與實作範例

詳細的模式文件位於 references/details.md。當上述導覽層級不足時，請閱讀該文件。