CSS Modules 与 Tailwind 实践指南：局部样式、设计令牌与团队协作怎么平衡

前端团队讨论样式方案时，经常把问题简化成“CSS Modules 还是 Tailwind”。但真实项目里，很少只有单一答案。真正需要解决的是三个维度：组件边界怎么收，设计规范怎么传播，协作成本怎么控制。

CSS Modules 强在局部封装，Tailwind 强在快速表达与令牌复用。把两者当成互斥选项，往往会错过更实用的组合方式。

1. 先看本质：两者解决的问题并不完全相同

方案	核心价值	更适合
CSS Modules	把样式作用域绑定到组件文件	复杂局部样式、结构化组件、动画细节
Tailwind	用原子类快速表达设计系统约束	页面搭建、布局编排、设计一致性

如果你的页面主要问题是“组件长得不统一、多人写出来风格飘”，Tailwind 往往更有帮助；如果问题是“组件内部状态复杂、选择器层级太乱、覆盖关系难控”，CSS Modules 更稳。

2. 什么时候优先用 Tailwind

Tailwind 最适合解决“高频、重复、可枚举”的样式表达：

布局：栅格、间距、对齐
字体：字号、字重、行高
颜色：背景、文字、边框
响应式：断点下的显隐与重排

例如一个营销卡片组件，用 Tailwind 写会非常直接：

export function PricingCard() {
  return (
    <section className="rounded-3xl border border-slate-200 bg-white p-8 shadow-sm">
      <h3 className="text-2xl font-semibold text-slate-900">Pro Plan</h3>
      <p className="mt-3 text-sm leading-6 text-slate-600">
        适合需要稳定交付和团队协作的业务站点。
      </p>
      <button className="mt-6 inline-flex rounded-full bg-slate-900 px-5 py-3 text-sm font-medium text-white transition hover:bg-slate-700">
        开始试用
      </button>
    </section>
  )
}

它的优势是信息集中，设计约束明显，评审时一眼能看出布局和视觉参数。

3. 什么时候 CSS Modules 更合适

当组件内部样式逻辑开始变得复杂，CSS Modules 通常更清晰：

多状态切换依赖伪类或 data-attribute
动画过渡较多
需要写较长的组合选择器
组件内部包含结构化子元素

import styles from './feature-card.module.css'

export function FeatureCard({ active }: { active: boolean }) {
  return (
    <article className={active ? styles.cardActive : styles.card}>
      <div className={styles.glow} />
      <h3 className={styles.title}>智能内容编排</h3>
      <p className={styles.description}>把页面结构、文案和配图流程拆成可复用模块。</p>
    </article>
  )
}

CSS Modules 在这里的价值不是“更高级”，而是让结构和视觉逻辑绑定得更稳，避免 JSX 被几十个类名淹没。

4. 更实用的团队策略：Tailwind 做外层，Modules 做内层

很多项目最终最稳定的模式其实是混合分工：

Tailwind 负责页面布局、容器间距、响应式编排
CSS Modules 负责复杂组件内部样式与动效

这样做的好处是：

页面搭建仍然快
复杂组件不会堆满原子类
设计系统令牌仍可通过 Tailwind theme 统一输出

一个常见实践是把按钮、弹层、数据卡片等基础组件保留为 Tailwind 主导，而把 Hero 动效、交互式导航、复杂图文模块交给 CSS Modules。

5. 不要忽略设计令牌，否则两种方案都会失控

无论你选哪种写法，如果颜色、间距、阴影、圆角没有统一来源，项目最后都会失控。

建议把这些值沉淀到一层令牌：

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f4f7ff',
          500: '#2952ff',
          700: '#1737c9',
        },
      },
      borderRadius: {
        xl: '1rem',
        '2xl': '1.5rem',
      },
    },
  },
}

在 CSS Modules 里则通过 CSS variables 消费同一套语义值。这样 Tailwind 与 Modules 才是协作，而不是各自积累一套视觉语言。

6. 常见失败案例：为了“统一”强迫所有样式都写成原子类

最常见的误区不是 Tailwind 本身，而是把它用成“任何样式都必须内联到 JSX”。结果通常是：

一个组件塞进 20 到 40 个类名
状态变化依赖条件拼接，阅读成本很高
复杂 hover、动画、伪元素表达困难
团队开始大量复制粘贴类名串

这时候表面上是“没有 CSS 文件了”，实际上是把复杂度转移到了 JSX。

反过来也一样。若团队坚持所有东西都进 CSS Modules，又会出现：

小改动必须频繁跨文件跳转
设计约束无法在调用点被直观看见
页面搭建速度明显变慢

所以重点不是教条统一，而是边界分工。

7. 决策清单：新组件到底该选哪种写法

创建新组件时，可以按这组问题判断：

这个组件是否以布局拼装为主
样式是否主要由设计系统已有令牌组成
是否需要大量状态、伪元素、动画细节
团队后续是否会频繁变更结构层级
代码评审时，样式意图是否需要在 JSX 中直接可见

如果前两项答案偏多，优先 Tailwind；如果中间两项更突出，优先 CSS Modules；如果两类需求并存，就分层混用。

8. Checklist：把样式方案做稳的最小要求

颜色、字号、间距先收进统一令牌
不把复杂动画强行写成难读的类名拼接
不把简单布局都下沉成大量 CSS 文件
组件对外 API 稳定，内部样式实现可替换
评审时同时看“视觉一致性”和“维护成本”
对主题、暗色模式、响应式规则有统一约定

9. 结论：样式方案不是宗教，而是协作接口

CSS Modules 与 Tailwind 之争，表面在比语法，实际在比团队如何管理样式复杂度。把 Tailwind 用来提高表达效率，把 CSS Modules 用来承接复杂内部实现，再让设计令牌成为共享底座，通常比单押一种方案更稳定。

进一步阅读：

CSS Modules 与 Tailwind 实践指南：局部样式、设计令牌与团队协作怎么平衡