v4 CSS-first 配置

1. @theme：定义设计 token

@theme 是 v4 最核心的新指令，替代了 v3 的 tailwind.config.js 中的 theme 配置。在 @theme 块中定义 CSS 自定义属性，Tailwind 会自动将其注册为工具类。

/* style.css —— 完整的 v4 设计系统配置示例 */
@import "tailwindcss";

@theme {
  /* 品牌色 */
  --color-brand: #06B6D4;
  --color-brand-light: #22D3EE;
  --color-brand-dark: #0891B2;

  /* 语义色 */
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-danger: #ef4444;

  /* 自定义字体 */
  --font-sans: 'Inter Variable', ui-sans-serif, sans-serif;
  --font-mono: 'Fira Code', ui-monospace, monospace;
  --font-display: 'Playfair Display', serif;

  /* 自定义间距 */
  --spacing-18: 4.5rem;   /* 自定义 p-18, m-18 等 */
  --spacing-88: 22rem;

  /* 圆角 */
  --radius-brand: 10px;

  /* 自定义阴影 */
  --shadow-brand: 0 4px 20px rgba(6,182,212,0.3);

  /* 断点（覆盖默认）*/
  --breakpoint-sm: 480px;
  --breakpoint-3xl: 1920px;

  /* 自定义动画 */
  --animate-shimmer: shimmer 1.5s infinite;
}

@keyframes shimmer {
  from { background-position: -200% 0; }
  to { background-position: 200% 0; }
}

<!-- 使用 @theme 中定义的 token -->
<button class="bg-brand hover:bg-brand-dark text-white rounded-brand shadow-brand">
  品牌按钮
</button>
<h1 class="font-display text-brand text-4xl">品牌标题</h1>
<p class="text-success">操作成功！</p>

2. @layer：层叠规则

CSS 层叠（Cascade Layers）是 v4 管理样式优先级的核心机制。Tailwind v4 使用三个层：

• @layer base 基础样式，如重置（reset）、全局默认。优先级最低，会被 components 和 utilities 覆盖。
• @layer components 组件级样式，如 .btn、.card。优先级中等，可被 utilities 覆盖（这是 utility-first 的关键：工具类总能覆盖组件样式）。
• @layer utilities 工具类层，Tailwind 的所有 bg-*、p-* 等工具类都在此层。优先级最高。

@import "tailwindcss";

/* 全局基础样式 */
@layer base {
  * { box-sizing: border-box; }
  body { font-family: var(--font-sans); }
  h1 { font-size: 2rem; font-weight: 800; }
  a { color: var(--color-brand); }
}

/* 可复用组件 */
@layer components {
  .btn {
    display: inline-flex;
    align-items: center;
    gap: var(--spacing-2);
    padding: var(--spacing-2) var(--spacing-4);
    border-radius: var(--radius-lg);
    font-weight: 600;
    transition: all 0.2s;
  }
  .btn-primary {
    background: var(--color-brand);
    color: white;
  }
}

3. @utility：自定义工具类

v4 用 @utility 替代了 v3 的 plugin(addUtilities(...))，直接在 CSS 中定义可在 HTML 中使用的工具类。

@import "tailwindcss";

/* 定义自定义工具类 */
@utility scrollbar-hide {
  scrollbar-width: none;
  &::-webkit-scrollbar { display: none; }
}

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

@utility glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

/* 支持 Tailwind 修饰符的工具类（函数式）*/
@utility tab-* {
  tab-size: var(--tab-size-*);
}

<!-- 使用自定义工具类，支持所有变体前缀 -->
<div class="overflow-x-auto scrollbar-hide">隐藏滚动条</div>
<h2 class="text-balance text-3xl font-bold">文字均衡排版</h2>
<div class="glass rounded-xl p-6 hover:glass">毛玻璃效果</div>
<pre class="tab-4">4格 tab 缩进</pre>

4. @variant：自定义变体

@variant 允许创建自定义状态前缀，类似于内置的 hover:、focus:。可以封装任何 CSS 选择器逻辑。

@import "tailwindcss";

/* 自定义 dark 策略（class 模式）*/
@variant dark (&:where(.dark, .dark *));

/* 自定义 featured 变体：当元素有 data-featured 属性时 */
@variant featured (&[data-featured]);

/* 支持嵌套选择器 */
@variant sidebar-expanded {
  .sidebar-open & {
    @slot;
  }
}

/* 媒体查询变体 */
@variant tall {
  @media (min-height: 800px) {
    @slot;
  }
}

<!-- 使用自定义变体 -->
<div class="featured:ring-2 featured:ring-yellow-400" data-featured>
  推荐内容
</div>

<div class="w-64 sidebar-expanded:w-80 transition-all">
  侧边栏宽度随父类变化
</div>

<section class="h-48 tall:h-96">高屏时增大高度</section>