用途:该技能面向使用 Tailwind CSS 进行样式开发的场景,重点覆盖 v4 的 CSS-first 配置、@theme 令牌、工具类、组件变体以及从 v3 迁移。资料提示 v4 与 v3 差异较大,训练数据可能过时,涉及 @theme、@variant 等 v4 专有语法时应先查阅当前文档再写代码。
主要能力与规则:工具类名需保持完整源码字面量并确认文件被扫描;使用共享设计令牌和统一的可见性机制;源码或配置变更后检查生成的 CSS,仅凭 JSX 字符串不能证明工具类存在;布局包含关系变化时在浏览器中测试滚动、浮层与焦点行为。编码规则包括:用 gap 替代 space-x/space-y,用 size-* 替代 w-* h-*,用 min-h-dvh 替代 min-h-screen,用透明度修饰符(如 bg-black/50)替代已移除的 -opacity-,优先设计令牌而非任意值,禁止动态拼接类名,用 @utility 替代 @apply 配合 @layer,用父容器内边距替代末子元素外边距。
注意事项:overflow-x-auto 会在两个轴向上形成滚动容器,可能裁剪非 portal 的下拉、弹出层、提示或焦点环,jsdom 不做布局因此单元测试无法发现,需逐一确认浮层组件是否逃逸该容器;Radix 的 portal 需显式使用 *.Portal 包裹 *.Content。不要用原生 hidden 属性加 display 工具类表达可见性,v4 Preflight 中该属性会以 !important 生效,v3 或未加载 Preflight 时则相反,应统一用一种机制切换。
验证:构建零错误;变更文件中无 v3 类名残留(可用 @tailwindcss/upgrade --dry-run 检查);同一元素无冲突类。参考资料涵盖组件模式(tailwind-variants slots、CVA、复合组件)、布局模式(网格区域、容器查询、z-index、流式排版),以及配置与迁移、类生成与组合、v3 到 v4 迁移等专题文档。具体安装命令与更多细节暂未提供。