uniwind

Uniwind

Uniwind 1.7.0+ / Uniwind Pro 1.2.1+ / Tailwind CSS v4 / React Native 0.81+ / Expo SDK 54+

如果用户使用的是更早的版本，建议升级到 1.7.0+（免费版）/ 1.2.1+（Pro），以获得最佳体验。

LayoutDirection 从 Uniwind 1.8.0+ 起可用。

ScopedVariables 可将 CSS 变量覆盖范围限定在组件子树中，从 Uniwind 1.11.0+ / Uniwind Pro 1.6.0+ 起可用。

从 Uniwind 1.13.0+ / Uniwind Pro 1.9.0+ 起，原生 CSS 层叠顺序（层、优先级、源代码顺序）会得到遵循。较早版本以不同方式处理互相冲突的自定义类和工具类。

Uniwind 将 Tailwind CSS v4 引入 React Native。所有核心 React Native 组件开箱即支持 className 属性。样式会在构建时编译，不会产生运行时开销。

关键规则

1. 仅支持 Tailwind v4 — 使用 @import 'tailwindcss'，不要使用 @tailwind base。不支持 Tailwind v3。
2. 绝不要动态构造 classNames — Tailwind 会在构建时扫描。bg-${color}-500 不会生效。请使用完整的字符串字面量、映射对象或三元表达式。
3. 绝不要使用 cssInterop 或 remapProps — 这些是 NativeWind API。Uniwind 不会覆盖全局组件。
4. 不要使用 tailwind.config.js — 所有配置都通过 global.css 中的 @theme 和 @layer theme 完成。
5. 无需 ThemeProvider — 直接使用 Uniwind.setTheme()。
6. withUniwindConfig 必须是 Metro 配置包装器的最外层。
7. 绝不要用 withUniwind 包装 react-native 或 react-native-reanimated 组件 — View、Text、Pressable、Image、TextInput、ScrollView、FlatList、Switch、Modal、Animated.View、Animated.Text 等组件已内置完整的 className 支持。用 withUniwind 包装它们会破坏功能。仅对第三方组件（例如 expo-image、expo-blur、moti）使用 withUniwind。
8. 字体族：仅使用单个字体 — React Native 不支持回退字体。使用 --font-sans: 'Roboto-Regular'，不要使用 'Roboto', sans-serif。
9. 所有主题变体必须定义相同的一组 CSS 变量 — 如果 light 定义了 --color-primary，那么 dark 和每个自定义主题也必须定义它。变量不匹配会导致运行时错误。
10. 非样式颜色属性必须使用 accent- 前缀 — 这一点至关重要。color（Button、ActivityIndicator）、tintColor（Image）、thumbColor（Switch）、placeholderTextColor（TextInput）等属性不属于 style 对象。你必须使用对应的 {propName}ClassName 属性，并为类名添加 accent- 前缀。例如：<ActivityIndicator colorClassName="accent-blue-500" />，而不是 <ActivityIndicator className="text-blue-500" />。常规 Tailwind 颜色类（如 text-blue-500）仅对 className（它映射到 style）生效。对于非样式颜色属性，始终使用 accent-。
11. rem 默认值为 16px — NativeWind 使用 14px。如果要迁移，请在 Metro 配置中设置 polyfills: { rem: 14 }。
12. cssEntryFile 必须是相对路径字符串 — 使用 './global.css'，不要使用 path.resolve(__dirname, 'global.css')。
13. 原生端遵循 CSS 层叠规则（Uniwind 1.13.0+ / Pro 1.9.0+） — 冲突按浏览器中的规则解决：先看 !important，再看层叠层，然后是选择器优先级，最后是编译后 CSS 中的顺序。className 内类名的顺序无关紧要。Tailwind 工具类位于 @layer utilities 中，因此对于普通（非 !important）声明，无层叠层的自定义类（.card { border-radius: 12px }）优先于 rounded-2xl。若要让工具类覆盖自定义类，请在 @layer components { ... } 中声明自定义类。cn() / tailwind-merge 只会对彼此重复的 Tailwind 工具类进行去重；它们不会移除 card 这样的自定义类。
14. 支持重要工具类 — Tailwind 的重要修饰符可在 classNames 中使用，! 放在末尾：bg-red-500!、active:bg-red-500!、ios:pt-12!。前置 !bg-red-500 的写法已弃用。对于同一 style 属性，重要工具类会覆盖非重要工具类，但内联 style 仍会覆盖 className。

参考资料路由

识别用户的任务后，只阅读 references/ 下相关的内置参考文件：

• 安装或配置问题：references/setup.md
• React Native 组件的 className 属性、强调色属性或组件示例：references/component-bindings.md
• 第三方组件、withUniwind、动态类名、tailwind-variants、cn、重要工具类或样式优先级：references/styling-patterns.md
• 主题、CSS 变量、ScopedTheme、LayoutDirection、色彩空间或运行时变量 API：references/theming.md
• 平台、数据、状态、响应式或安全区域工具类：references/variants-and-selectors.md
• CSS 函数、自定义 CSS、@utility、@theme、字体或渐变：references/css-and-utilities.md
• React Navigation、UI 工具包、支持矩阵或不支持的类：references/integrations.md
• Uniwind Pro 安装、动画、诊断、group 变体、默认样式、原生内边距或主题过渡：references/pro.md
• 样式失效、安装诊断、错误、缓存问题、常见问题、MCP 或相关技能：references/troubleshooting.md

工作流程

1. 判断用户需要的是安装、样式、主题、变体、集成、Pro 还是故障排查方面的帮助。
2. 在提供详细指导或编辑代码之前，先阅读匹配的参考文件。
3. 即使选定的参考文件中没有提及，也要遵守上述关键规则。
4. 不要猜测 Uniwind API。如有疑问，请查阅官方文档：https://docs.uniwind.dev/llms-full.txt

相关技能

NativeWind 迁移与此技能有意分开。用户希望从 NativeWind 迁移到 Uniwind 时，请使用 migrate-nativewind-to-uniwind 技能。