converting-css-modules-to-tailwind

将 CSS Modules 转换为 Tailwind

将组件从 CSS Modules（.module.css / .module.scss）迁移到 Tailwind 工具类。

工作流程

1. 清点模块

阅读 .module.css 文件和导入该文件的组件。将每个 styles.xxx 引用映射到它对应的 CSS 规则。

// Before
import styles from './Card.module.css';
<div className={styles.card}>
  <h2 className={styles.title}>{title}</h2>
  <p className={styles.body}>{children}</p>
</div>

/* Card.module.css */
.card { display: flex; flex-direction: column; gap: 16px; padding: 24px; border-radius: 12px; background: white; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
.title { font-size: 20px; font-weight: 600; color: #111827; }
.body { font-size: 14px; color: #6b7280; line-height: 1.6; }

2. 转换每个类

将 styles.xxx 替换为等效的 Tailwind 工具类：

// After
<div className="flex flex-col gap-4 p-6 rounded-xl bg-white shadow-sm">
  <h2 className="text-xl font-semibold text-gray-900">{title}</h2>
  <p className="text-sm text-gray-500 leading-relaxed">{children}</p>
</div>

3. 处理 CSS Modules 模式

composes 关键字：

.base { padding: 8px 16px; border-radius: 4px; }
.primary { composes: base; background: blue; color: white; }

→ 展开为一组工具类。如果需要复用，请提取组件，而不是类。

使用 clsx/classnames 的条件类名：

// Before
className={clsx(styles.button, isActive && styles.active)}
// After
className={clsx("px-4 py-2 rounded", isActive && "bg-blue-600 text-white")}

动态类选择：

// Before
className={styles[variant]}
// After — use a lookup object
const variantClasses = {
  primary: "bg-blue-600 text-white hover:bg-blue-700",
  secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
  danger: "bg-red-600 text-white hover:bg-red-700",
};
className={variantClasses[variant]}

CSS Modules 全局覆盖：

:global(.some-library-class) { ... }

→ 移至 globals.css 中的 @layer components { }，或在全局样式表中使用 Tailwind 的 @apply。

SCSS 功能（嵌套、变量、混入）：

• 嵌套选择器 → 展开为应用于每个元素的工具类
• SCSS $variables → 映射到 tailwind.config.ts 主题值
• 混入 → 替换为工具类组合或提取组件

4. 清理

1. 移除 import styles from './Xxx.module.css' 这一行
2. 删除 .module.css / .module.scss 文件
3. 如果组件有一个同目录的 index.ts 入口文件重新导出了样式，请更新它
4. 搜索代码库，查找对已删除模块的其他导入
5. 运行应用并进行视觉验证，检查是否有回归问题

规则

• 一次转换一个组件，不要批量转换整个目录
• 将条件逻辑保留在 clsx() 或模板字面量中，而不是 CSS 中
• 如果模块有伪元素样式（:before、:after 带 content），需要在 Tailwind 中使用 before: / after: 前缀和 content-['...']
• 对于 :nth-child、:first-of-type 等，检查 Tailwind 是否有对应变体；否则保留最精简的 CSS 规则
• 不要创建 @apply 类来复现模块原有的效果，目标是消除这种间接层