Tailwind CSS Patterns

何时使用

• 在 Tailwind v4 项目里搭建主题、定义设计令牌（颜色/间距/字体）。
• 需要 CSS-first 配置：把配置从 tailwind.config.js 迁到 CSS 的 @theme 指令。
• 实现容器查询（@container）、深色模式、现代栅格/Flex 布局或 OKLCH 颜色体系。

不该用：

• 不要用于深挖 v3 JS 配置或 v3→v4 完整迁移工程（本条只给原则，不给逐项迁移脚本）。
• 不要用于纯手写原生 CSS 或非 Tailwind 的 UI 框架（如 Bootstrap、MUI）。
• 输出不能替代真实环境的构建验证与设计评审；缺少设计规范或令牌口径时先问清再做。

步骤

1. 建立 CSS-first 配置：用 @theme 声明令牌，所有令牌自动暴露为 --* CSS 变量。v4 配置文件已是可选项。
2. 令牌分三层：Primitive（原始值，如 --blue-500）→ Semantic（语义，如 --color-primary）→ Component（组件级，如 --button-bg）。颜色优先用 OKLCH（感知均匀）。
3. 选响应式策略：页面级布局用视口断点（md: 等），组件级响应式用容器查询（与上下文解耦，组件可复用）。遵循移动优先：无前缀写移动端，再用前缀叠加大屏。
4. 配置深色模式：手动切换用 class（.dark 切换），跟随系统用 media，复杂主题用 v4 的 selector。
5. 抽组件：同一串 class 出现 3 次以上、或有复杂状态变体时抽离；动态用 React/Vue 组件，静态可用 @apply（但克制使用）。

指令

• 启用引擎：v4 默认 Oxide（Rust，约 10x 提速）、JIT 常开、原生 CSS 嵌套，无需 PostCSS 插件。
• 扩展 vs 覆盖：新增值用「扩展」，整套替换默认刻度用「覆盖」，项目专有命名用「语义令牌」。
• 性能：避免动态拼接 class（如模板字符串），否则无法被静态提取；未用样式 v4 自动 purge；CI/CD 开启构建缓存。

示例

@theme 定义令牌（结尾自动生成 --color-primary 等变量）：

@theme {
  /* 颜色 - 用语义命名 */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);

  /* 间距刻度 */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;

  /* 字体 */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

常用模式：

• 容器查询：父级 @container，子级 @sm:/@md:/@lg:；需指定时用命名容器 @container/card。
• 移动优先列宽：w-full md:w-1/2 lg:w-1/3。
• 自适应栅格：grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]；侧栏布局 grid grid-cols-[auto_1fr]。
• 深色配色：bg-white dark:bg-zinc-900、text-zinc-900 dark:text-zinc-100、border-zinc-200 dark:border-zinc-700。
• 居中：flex items-center justify-center；悬停：hover:scale-105 transition-transform。

断点：sm:640 / md:768 / lg:1024 / xl:1280 / 2xl:1536。

注意事项

反模式（避免）：

• 到处用任意值 → 应走设计系统刻度。
• 用 !important → 应正确处理优先级。
• 用内联 style= → 应用工具类。
• 重复长 class 串 → 抽组件。
• v3 配置与 v4 混用 → 应完整迁到 CSS-first。
• 重度依赖 @apply → 优先组件化。
• 布局倾向：相比对称三列栅格，更推荐非对称 / Bento 布局。

互见

• 研发/前端域内的「响应式布局」「设计系统与令牌」相关条目。

采编自 sickn33/antigravity-awesome-skills（MIT）。