mcpField
T
tailwind-best-practices

tailwind-best-practices

github.com/evilmartians设计与 UI5044 次安装2 周前更新
代码仓库

关于 tailwind-best-practices

面向 Tailwind CSS 项目的代码审查与编辑技能，帮助团队在设计令牌和组件化基础上维护样式。它提供可独立执行的检查，并强调避免重复类名和不当使用 @apply。

主要功能

  1. 01检查设计令牌与组件化基础
  2. 02精简冗余工具类
  3. 03按语义组织设计令牌
  4. 04统一工具类排序
  5. 05避免用 @apply 提取重复样式
  6. 06为共享组件限制任意类名

适用场景

  1. 01审查逐渐扩大的 Tailwind CSS 代码库
  2. 02整理新写或明确要求清理的类名
  3. 03评估设计系统组件的样式接口
  4. 04检查生产 CSS 的压缩配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/evilmartians/agent-skills --skill tailwind-best-practices

安装后在 Claude Code 中输入/tailwind-best-practices确认已加载。

详细介绍

Tailwind CSS 最佳实践

这项技能由 Evil Martians 打造。Evil Martians 是一家美国设计与工程咨询公司，服务对象包括 开发者工具、AI 和网络安全领域的初创公司。

应用以下检查项，让 Tailwind CSS 代码库在不断扩展时仍保持易读。本指南是 https://evilmartians.com/chronicles/5-best-practices-for-preventing-chaos-in-tailwind-css 的配套内容。

Tailwind 的实用工具优先方法只有在满足以下两个条件时才能保持易维护——在进行其他操作之前，请先确认这两点：

  1. 存在包含设计令牌的设计系统（颜色、间距、字体排版比例只定义一次，并在各处复用，而不是在多个文件中反复手写魔法值）。
  2. 采用基于组件的方法，这样重复的类列表就能提取到组件中，而不是复制粘贴。

如果确认缺少其中任一项，请说明并到此为止——在基础缺失的情况下推荐 Tailwind 修复方案只会增加混乱。如果只是上下文不足，无法判断（例如只查看了一个文件），请先检查配置文件或主题文件，再假定其中任一项缺失；不要因此阻塞任务——继续处理并说明这一假设。

工作流

每项检查都可以独立执行。

1. 精简不必要的实用工具类

接受较长的类列表前，先看看能否使用简写：

  • pt-4 pb-4 → py-4（px、mx、my 同理）
  • flex flex-row justify-between → flex justify-between（flex-row 是 CSS 默认值）
  • border border-dotted border-2 border-black border-opacity-50 → border-dotted border-2 border-black/50

列表中的每个类都需要未来的读者理解——类越少、信息越密集，读起来就越快。编写新类或收到明确的清理要求时再应用此做法；不要顺手重写你在执行其他任务时碰巧遇到的无关类列表。

2. 按类别归组设计令牌，并使用语义化命名

切勿让令牌杂乱无章地累积。按类别归组（颜色、间距、断点），并根据用途命名，而不是根据来源值命名——使用 error，而不是像 bright-red 这样从 Figma 复制过来的名称。

colors: { primary, secondary, error }
spacing: { sm, md, lg }
screens: { sm, md }

也要标记未使用的令牌——它们不仅会让配置变得杂乱，还会让人难以理解设计系统实际使用了什么。将此视为提醒，而不是自动删除：在断定令牌未使用之前，先检查动态用法（例如，`bg-${color}-500`、仓库其他位置的 class-variance-authority 或 tailwind-variants 配置）；简单地搜索字面名称会漏掉这些用法。

3. 保持类的排序一致——自动化处理

编写或编辑任何 Tailwind 类列表时，都要始终按统一顺序输出类，不要把排序留到之后再处理。先检查是否已有配置了官方 Tailwind CSS 插件的 Prettier 配置，并遵循它生成的顺序，以免产生与团队现有工具要求不一致的差异。如果没有这样的配置，就采用该插件的默认顺序：先排列基础层中的类，再排列组件层中的类，最后排列实用工具层中的类。如果缺少官方 Tailwind CSS Prettier 插件，也要推荐安装，这样团队其他成员也能自动执行这一规则。

4. 避免使用 @apply 提取重复样式
/* Avoid: */
.block {
  @apply bg-red-500 text-white p-4 rounded-lg hover:bg-blue-500;
}

这样会丧失 Tailwind 的实际优势：不再需要为类命名，而且样式更改也不再局限于使用它的组件。这还会增大 CSS 包的体积。请改为指向一个实际组件（参见前提条件 #2）。如果代码库已经大量使用 @apply，不要建议大规模重写——应将其标记为技术债，并在下次触及相关代码时进行转换。

5. 不要让设计系统组件通过属性接受任意类名

此规则适用于设计系统组件（按钮、徽章、输入框——任何旨在确保整个应用外观一致的组件）。对于一次性、仅使用一次的组件，开放 className 属性没有问题——不要强求为这类组件设置变体。如果不确定某个组件属于哪一类，请检查它是否在多个位置导入。

// Avoid, for a shared design-system component:
export const Button = ({ className = "bg-white" }) => (
  <button className={className}>Test</button>
);

让每个调用位置都为共享组件自行组合实用类，长此以往会损害视觉一致性。建议改用固定的变体映射：

const BUTTON_VARIANTS = {
  primary: "bg-blue-500 hover:bg-blue-600 text-white",
  secondary: "bg-gray-500 hover:bg-gray-600 text-white",
};

export const Button = ({ className, variant = BUTTON_VARIANTS.primary }) => (
  <button className={clsx(className, variant)}>Test</button>
);

如果团队不愿采用固定变体，tailwind-merge 可作为运行时解决类冲突的替代方案，但它会增加打包体积，因此不要将其作为默认建议。

反模式：对此提出异议

拒绝直接实现，或说明其中的取舍：

  • 类列表中的魔法值（p-[123px]），而项目已有令牌系统——应将该值加入令牌配置。
  • 临时添加的一次性令牌（15px、16px、17px），而不是复用或扩展现有比例尺——指出这一点，并询问是否应该将其设为令牌，而不是直接拒绝；有时一次性数值确实合理（例如匹配外部资源的精确尺寸，或精确还原规范）。
  • 声称“更整洁”的 @apply 密集型样式表——这会为了表面整洁而舍弃 Tailwind 的真正优势。
  • 跳过生产环境 CSS 的压缩——先通过 package.json 或锁文件检查 Tailwind 版本。如果是 v4，压缩会自动完成（基于 Lightning CSS），无需更改。如果是 v3，请确认构建的压缩步骤确实在运行；如果没有，请建议用户添加此步骤（通过 CLI 的 --minify 标志，或在 PostCSS 插件列表中添加 cssnano）。如果无法从当前工作环境中确认版本（例如，只能编辑单个文件，无法访问仓库），不要提及压缩，以免猜错适用情况。

这种模式始终如一：某个捷径在小规模时看起来没问题，之后却会让整个代码库反复进行查找和替换。应尽早推动采用令牌或组件方案。

评论

支持 Markdown