用途：本技能用于指导在本仓库中编写、审查和重构 Tailwind CSS v4 代码，说明如何写出地道的 v4 写法，并识别仍可编译但不应出现在新代码中的 v3 时代语法。
版本与来源：使用较新工具类前先查看项目 package.json 中固定的 tailwindcss 版本（撰写时为 4.3.3，包含 scrollbar-、zoom-、tab-* 等 v4.3 工具类）。不确定某工具类、变体或指令是否存在时，应查阅官方文档而非猜测。工具类与变体参考：https://tailwindcss.com/docs；v3 到 v4 迁移：https://tailwindcss.com/docs/upgrade-guide；各小版本新增内容：https://tailwindcss.com/blog/tailwindcss-v4（以及 /tailwindcss-v4-1、/tailwindcss-v4-3 等）。
CSS 优先配置：Tailwind v4 在 CSS 中配置，而非 JavaScript。使用 @import 'tailwindcss' 而非 @tailwind base/components/utilities；用 @theme { --color-x: ...; } 定义可生成工具类的 token，而非新建 tailwind.config.ts；用 @utility name { ... } 定义自定义工具类，而非 @layer utilities；用 @custom-variant dark (&:is(.dark *)) 而非 JS 插件或 addVariant；用 @source 指定额外来源或安全列表；用 @variant 在自定义 CSS 中应用 Tailwind 变体；用 @reference 支持在 Vue、CSS Modules 等作用域样式中使用 @apply；在 CSS 中使用 var(--color-x)。@config 和 @plugin 仅用于兼容既有 JS 配置。@theme 变量本身就是 API：既输出原生 CSS 变量又生成工具类；普通 :root 变量不生成任何工具类。值引用其他变量时应在 @theme inline 中声明。
v3 到 v4 改名：裸名称整体下移一级，v3 写法会静默变小或变浅，如 shadow-sm→shadow-xs、blur-sm→blur-xs、rounded-sm→rounded-xs、outline-none→outline-hidden（a11y 安全）、ring（3px）→ring-3（默认 1px currentColor）、bg-opacity-50→bg-black/50、bg-gradient-to-r→bg-linear-to-r、!bg-red-500（前缀）→bg-red-500!（后缀）、flex-shrink-→shrink-、bg-[--var]→bg-(--var)、grid-cols-[a,b] 需用下划线等。
优先使用生成的工具类而非任意值：间距刻度无限，大多数 v3 任意值都有命名形式，如 min-w-[400px]→min-w-100、size-6、mt-17、grid-cols-15、h-dvh、max-w-7xl、data-current:opacity-100、bg-(--row-bg) 等。方括号仍适用于真正的一次性值，如 max-h-[calc(100dvh-3rem)]、grid-cols-[200px_minmax(0,1fr)] 和 [mask-type:luminance] 等任意属性。类字符串必须完整且可静态检测，不能拼接如 bg-${tone}-500。
不要为变体已覆盖的场景手写 CSS 或 JS：如用 active:bg-surface5 代替 .btn:active，用 focus-visible:outline-accent1，用 aria-expanded:rotate-180，用 data-[state=open]:opacity-100，用 group/group-hover:、peer/peer-checked:，用 has-checked:，用 mask-b-from-80%，用 pointer-coarse:，用 first:/last:/odd:/nth-3:，用 *:rounded-full 与 **:data-avatar:rounded-full 等。
新能力：field-sizing-content 实现自动增高 textarea；wrap-anywhere/wrap-break-word 处理长词换行；items-center-safe/justify-center-safe；pointer-coarse:/pointer-fine:；user-valid:/user-invalid:；starting: 与 transition-discrete；text-shadow-、mask-t-from-/mask-b-to-*、scheme-dark、3D 变换等。
行为变化：变换使用独立 CSS 属性，自定义过渡列表需 transition-[opacity,scale]；hover: 仅在支持悬停的设备生效；默认 border-、divide-、ring、outline 颜色为 currentColor；变体堆叠从左到右；space-x/y-* 选择器改变，建议用 flex/grid 加 gap-*；内置容器查询，父级 @container、子级 @sm:/@max-md:。
动效：装饰性动画用 motion-safe:/motion-reduce: 门控；可复用动画用 --animate-* token 并在 @theme 内定义 @keyframes，局部动画用 animate-(--local-animation) 或 animate-[...]。