用途：在把 Tailwind CSS v3 代码库升级到 v4 时，处理静默的视觉回归、切换导入后的构建错误以及行为变化。它是一份 v3 到 v4 的升级陷阱目录，逐条列出破坏性变更的症状、根因、精准修复方式，并在适用时给出 @layer base 兼容层，用于分阶段迁移期间恢复 v3 行为。
主要能力：覆盖变体堆叠顺序（v3 从右到左，v4 从左到右）、默认边框颜色由 gray-200 变为 currentColor、默认 ring 宽度由 3px 变为 1px、阴影与圆角尺度整体位移、透明度修饰符移除、前缀语法改为变体、important 修饰符由前置改为后置、outline-none 改名为 outline-hidden、任意 CSS 变量改用括号语法、任意值中空格改用下划线、transform 拆分为独立属性、@layer utilities 改为 @utility、hover 被包进 @media (hover: hover) 等。还列出被移除的配置项（corePlugins、safelist、separator）与被移除的工具类（flex-shrink-、flex-grow-、overflow-ellipsis、decoration-slice、decoration-clone）及其替代。
使用方式：先运行官方 codemod：npx @tailwindcss/upgrade，它可机械处理约 80% 的重命名；再依据本技能目录人工审查 codemod 不会自动修复的部分。文中给出决策树，按代码库规模选择策略：小于 50k LOC 运行 codemod 后人工审计；50k 到 200k 结合 codemod、陷阱目录与视觉回归测试；大于 200k 采用分阶段迁移，用 @layer base 兼容层处理默认值变更类陷阱，按包运行 codemod 并逐次合并审计。
适用场景：升级过程中出现边框消失或颜色错误、焦点环变细或不可见、阴影观感异常、子元素变体顺序失效、透明度工具类被忽略、important 工具类失效、自定义前缀类无法解析、任意 [--var] 值无法解析等情况。
限制：兼容层应视为临时方案，长期正确做法是给每个带边框元素显式添加 border-gray-200 等令牌，并在一个发布周期后审计移除；不要机械交换变体顺序而不检查语义；不要长期保留默认颜色兼容层；v4 中 bg-opacity-* 与 text-opacity-* 不再生效。具体浏览器支持矩阵、完整重命名表与审计脚本见其 references 文件，本次资料未提供其内容。