Tailwind CSS v3.4+ 设计令牌定制 + 一些"高级"用法

Tailwind 的核心是 utility-first CSS，但生产里要配合品牌设计系统，
直接用默认色板 / 间距是不行的。下面是 5 个把 Tailwind 用到位的点。

1. 设计令牌：用 CSS 变量做主题

/* src/styles/tokens.css */
@layer base {
  :root {
    --color-brand: 220 90% 56%;        /* HSL，分量分开存便于 alpha */
    --color-brand-soft: 220 90% 96%;
    --color-text: 222 47% 11%;
    --color-bg: 0 0% 100%;
    --radius: 0.75rem;
  }

  .dark {
    --color-brand: 220 90% 65%;
    --color-text: 210 40% 96%;
    --color-bg: 222 47% 11%;
  }
}

tailwind.config.ts：

export default {
  content: ['./src/**/*.{ts,tsx}'],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        brand: 'hsl(var(--color-brand) / <alpha-value>)',
        'brand-soft': 'hsl(var(--color-brand-soft) / <alpha-value>)',
        text: 'hsl(var(--color-text) / <alpha-value>)',
        bg: 'hsl(var(--color-bg) / <alpha-value>)',
      },
      borderRadius: {
        DEFAULT: 'var(--radius)',
      },
    },
  },
}

之后：

<div class="bg-brand text-white rounded">
  <p class="text-brand/80">透明度 80%</p>
</div>

/80 是 Tailwind v3.1+ 的 alpha 语法，配合 <alpha-value> 占位让 HSL
变量与 opacity 联动。

切换 dark mode：

document.documentElement.classList.toggle('dark')

所有 token 通过 CSS 变量级联变化。

2. 自定义 plugin

// tailwind.config.ts
import plugin from 'tailwindcss/plugin'

export default {
  plugins: [
    plugin(({ addUtilities, theme }) => {
      addUtilities({
        '.text-balance': { 'text-wrap': 'balance' },
        '.scrollbar-thin': {
          'scrollbar-width': 'thin',
        },
        // 用 theme 引用其它 token
        '.no-x-scroll': {
          'overflow-x': 'hidden',
          'background': theme('colors.bg / 50%'),
        },
      })
    }),
  ],
}

<div class="text-balance"> 应用 text-wrap: balance（让标题换行均衡）。

3. 任意值 / arbitrary values

<div class="w-[273px] grid-cols-[200px_1fr_auto] before:content-['→']">

方括号语法让你写一次性的非标准值，避免为了某个奇异需求改 config。
但常用值还是放 config 里。

4. group / peer 改善交互样式

<!-- 父 hover 时子元素响应 -->
<div class="group">
  <h3 class="group-hover:text-brand">Title</h3>
  <p class="group-hover:opacity-100 opacity-50">Detail</p>
</div>

<!-- 兄弟元素影响 -->
<input type="checkbox" class="peer">
<label class="peer-checked:text-brand">Toggle me</label>

<!-- 命名 peer -->
<input type="checkbox" class="peer/agree">
<label class="peer-checked/agree:underline">同意条款</label>

group-* / peer-* 是 Tailwind 的 ":has" 替代品，不需要 JS。

5. responsive + container queries

<!-- 视口响应式 -->
<div class="text-sm md:text-base lg:text-lg">

<!-- 容器查询（Tailwind v3.4+） -->
<div class="@container">
  <div class="@md:flex @lg:grid">

启用 container queries 插件：

import containerQueries from '@tailwindcss/container-queries'
export default {
  plugins: [containerQueries],
}

6. dark mode 策略

darkMode: 'class'       // 用 .dark 类
// 或：
darkMode: 'media'       // 用 prefers-color-scheme
// 或最新：
darkMode: ['selector', '[data-mode="dark"]']

class 模式最灵活——可以手动切；media 跟随系统。
现代项目通常 class + 手动初始化跟随系统。

7. arbitrary properties

<div class="[mask:linear-gradient(black,transparent)]">
<div class="[--my-var:42px] [width:var(--my-var)]">

让任何 CSS 属性都能写在 class 里——逃生舱。

8. apply（谨慎用）

.btn {
  @apply px-4 py-2 rounded bg-brand text-white;
}

.btn:hover {
  @apply bg-brand-dark;
}

@apply 让你把 Tailwind class 抽成自定义类。适合：

公司风格按钮 / input 等基础组件
把超长 class 列表抽出（可读性）

不适合：日常 UI（违反 utility-first 哲学）。

9. just-in-time（JIT）默认开启

Tailwind v3+ 默认 JIT 模式：

只生成你用到的 class
任意值（w-[273px]）即时编译
watch 模式毫秒级重新生成

生产 CSS 体积通常 5-20 KB（gzipped），比传统 CSS 框架轻。

10. 与 shadcn/ui

shadcn/ui 不是组件库，是 "复制粘贴的 Tailwind 组件代码"：

npx shadcn-ui@latest init
npx shadcn-ui@latest add button card dialog

把组件 .tsx 文件复制到你的项目里，你拥有源码可改。
2024 后 React 项目用 Tailwind + shadcn 几乎是 default。

11. typography 插件

npm i -D @tailwindcss/typography

<article class="prose dark:prose-invert">
  <h1>...</h1>
  <p>...</p>
</article>

给纯 markdown 渲染的文章一键加上专业排版（标题大小、行高、代码块、
列表等）。

12. forms 插件

npm i -D @tailwindcss/forms

normalize 浏览器默认 input / select / checkbox 样式差异，
让你 utility class 控制更可预测。

踩过的坑

content 配置漏路径：JIT 扫不到你的源文件，class 没生成 → 看着没样式。
确认 content: ['./src/**/*.{ts,tsx,html}'] 覆盖。
类名拼接 / 动态字符串：text-{color} 这种 Tailwind 扫描不到。
改成完整字符串 text-red-500 写出来，或在 safelist 里列出。
@apply 滥用：所有按钮都 .btn .btn-lg .btn-primary，最后 CSS
比手写还多。utility-first 才是 Tailwind 的正道。
dark mode class 加错位置：必须在 <html> 而不是 <body> 上，否则
某些组件查不到。