/SKILL.md

name, description

name	description
tailwind-design-system	Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.

Tailwind Design System (v4)

构建生产就绪的设计系统，使用 Tailwind CSS v4，包括 CSS 优先配置、设计令牌、组件变体、响应式模式和可访问性。

注意：本技能针对 Tailwind CSS v4（2024+）。对于 v3 项目，请参考升级指南。

何时使用本技能

• 使用 Tailwind v4 创建组件库
• 使用 CSS 优先配置实现设计令牌和主题化
• 构建响应式和可访问的组件
• 在代码库中标准化 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 优先配置 */
@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;

  /* 动画令牌——@theme 中的 keyframes 在被 --animate-* 变量引用时才会输出 */
  --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。当上述导航层级不足以满足需求时，请阅读该文件。