tailwind-css

Tailwind CSS v4

实现前先验证：对于 v4 特有的语法（@theme、@variant、CSS 优先配置），请先通过 Context7（query-docs）查阅当前文档，再编写代码。Tailwind v4 与 v3 相比变化很大，训练数据可能已过时。

工作规则

• 将工具类名称保留为完整的源代码字面量，并确认其所在文件会被扫描。
• 使用共享设计令牌，并保持可见性机制一致。
• 修改源代码或配置后检查生成的 CSS；仅凭 JSX 字符串无法证明工具类确实存在。
• 布局包含方式发生变化时，在浏览器中测试滚动、覆盖层和焦点行为。

编码规则

• 优先使用 gap，而非 space-x/space-y —— gap 可处理换行；space-* 在换行时会失效
• 尺寸相同时优先使用 size-*，而非 w-* h-*
• 优先使用 min-h-dvh，而非 min-h-screen —— dvh 会考虑移动浏览器的界面栏
• 使用不透明度修饰符（bg-black/50）—— v4 已移除 *-opacity-* 工具类
• 优先使用设计令牌，而非任意值 —— 使用 [#hex] 前先检查 @theme
• 绝不动态拼接类名 —— text-${color}-500 不会被检测到；请使用完整类名
• 优先使用 @utility，而非结合 @layer 使用 @apply —— v4 中，@apply 用于 @layer 类时会失败
• 优先使用父元素内边距，而非最后一个子元素的外边距 —— 在容器上设置内边距，不要给最后一个子元素设置底部外边距
• overflow-x-auto 会在两个轴上都创建滚动容器 —— 该工具类只输出 overflow-x: auto，但根据 CSS Overflow 3 的计算规则，一旦任一轴可滚动，另一轴上的 visible 值也会变为 auto。因此，纯粹为了支持水平平移而添加的包装元素，可能会悄悄裁剪或滚动其垂直方向上溢出的内容：未使用 portal 的下拉菜单、弹出框、工具提示、自定义选择框或焦点环。jsdom 不执行布局，因此单元测试无法捕获此问题——请逐一检查在新包装元素内渲染的所有组件，并确认每个类似覆盖层的组件都能脱离该包装元素。启用 portal 需要显式操作，并非自动完成：Radix 将其作为单独的 *.Portal 部分公开，用于包装 *.Content；因此请阅读组件代码，不要想当然地认为库会处理此事。反过来，也要应用相同的计算值规则：在归咎于页面级滚动条之前，逐一检查所有祖先元素的 overflow，并指出实际发生滚动的元素
• 绝不同时使用原生 hidden 属性和显示工具类来表示可见性 —— 这两者在不同版本中的生效方向相反。v4 的 Preflight 会提供 [hidden]:where(:not([hidden="until-found"])) { display: none !important }，因此该属性会优先生效，预期应显示的元素仍会隐藏；在 v3 中，或 Preflight 被禁用或未加载时，无论优先级如何，作者来源的工具类（block、flex、grid）都会胜过 UA 来源的 [hidden] 规则，导致设置了 hidden 的元素仍显示在屏幕上。只切换一种机制：clsx(base, open ? 'block' : 'hidden')。这两种情况都无法通过 jsdom 的 toBeInTheDocument 检测——只有 toBeVisible 或真实浏览器引擎才能捕获问题

验证

• 构建通过且没有错误（npm run build 或同等命令）
• 修改过的文件中没有残留 v3 类名（如果可用，请使用 @tailwindcss/upgrade --dry-run 检查）
• 同一元素上没有相互冲突的类

参考资料

• 组件模式 —— tailwind-variants 插槽、CVA、复合组件
• 布局模式 —— 网格区域、容器查询、z-index 管理、流式排版

特定任务参考

在实现或审核相应行为前，请阅读相关参考文档：

• 关于主题令牌、构建配置、版本迁移、深色模式或样式缺失，请参阅：configuration-and-migration.md。
• 关于类合并、扫描路径、变体或 lint 集成，请参阅：class-generation-and-composition.md。

适用时，请参阅现有专项参考文档：

• v3-to-v4-migration.md。