tailwind-variants

Tailwind Variants

当工作涉及 Tailwind Variants（tv、slots、compound variants、extend、cn/cx/cnMerge、/lite，或跨 TV 主版本迁移）时，使用此技能。

工作流

1. 更改代码前，检查本地样式技术栈：
   • 软件包：tailwind-variants 版本、Tailwind CSS 主版本（v4 还是 v3）、是否直接使用 tailwind-merge，以及 Prettier Tailwind 插件。
   • 导入路径：默认的 tailwind-variants 还是 tailwind-variants/lite。
   • 使用的模式：单元素 tv、slots、extend、共享的 createTV/defaultConfig、组件上的 VariantProps。
2. 版本不明确，或工作涉及合并配置、lite 构建或主版本升级时，更新文档。请从 source-map.md 开始。
3. 安装、默认与 lite 构建、cn/cnMerge/cx 和配置相关内容，请使用 setup-core.md。
4. variants、布尔/复合 variants、slots 和 compoundSlots 相关内容，请使用 variants-slots.md。
5. extend、覆盖、TypeScript VariantProps 和 DX 工具相关内容，请使用 composition-typescript.md。
6. 冲突解决、自定义 twMergeConfig 以及 v0/v1/v2/v3 迁移相关内容，请使用 production-migration.md。

实现判断

• TV v3.x 与 Tailwind CSS v4.x 搭配使用。如果项目仍在使用 Tailwind CSS v3，请使用 tailwind-variants v0.x（或先升级 Tailwind）。
• 设计系统相关工作优先使用默认构建（import { tv, cn } from 'tailwind-variants'）。仅在关注包体积且不需要合并时使用 /lite。
• 在 v3.3.0+ 中，默认构建已内置冲突解决功能——不要仅为了 TV 而要求使用 tailwind-merge。只有当应用直接调用 tailwind-merge 时才保留它。使用 slots 时，请锁定 v3.3.1+（v3.3.0 会在交错调用之间泄漏 slot 状态）。
• 返回字符串的配方不要包含 slots。传入 slots: {} 会启用 slot 模式（隐式 base slot）——避免意外创建空 slot 对象。
• 类型化组合优先使用 extend，不要将 tv 的结果拼接到 base 数组中。
• 使用 class / className 属性供使用者覆盖；启用合并时，让合并机制解决冲突。
• 使用 VariantProps<typeof recipe> 为 React/Vue 属性添加类型。当默认值不合适时，使用 Omit/Required 将 variants 设为必填。
• 不要使用已移除的 responsiveVariants。请将响应式前缀（md:、lg:）直接放在类字符串中。
• 优先使用 cx，而不是已弃用的 cnBase。合并类名时优先使用 cn；仅在需要单次调用的合并配置时使用 cnMerge。

验证

优先使用仓库现有的检查。对于重要的 Tailwind Variants 更改，请包含相关的检查子集：

• 对 VariantProps、slot 返回类型和 extend 合并进行类型检查。
• 对关键 variant/compound 组合的配方输出字符串进行单元断言（尤其是启用和禁用合并时）。
• 对被覆盖的 slots 和组合组件进行视觉/浏览器冒烟测试。
• 在默认构建与 /lite 之间切换或添加较重的 twMergeConfig 时，检查包体积。
• 如果编辑器不再为 tv 中的类名提供自动补全，请检查 IntelliSense/tailwindFunctions: ['tv'] 是否正常。