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+ 及更高版本中可用。

Uniwind 为 React Native 带来 Tailwind CSS v4 体验。所有 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. 绝对不要给 react-native 或 react-native-reanimated 的组件套 withUniwind — 如 View、Text、Pressable、Image、TextInput、ScrollView、FlatList、Switch、Modal、Animated.View、Animated.Text 等已内置完整的 className 支持。重复包裹 withUniwind 会破坏组件行为。withUniwind 仅适用于第三方组件（如 expo-image、expo-blur、moti）。
8. 字体配置：仅支持单一字体 — React Native 不支持字体回退机制（fallback）。请使用 --font-sans: 'Roboto-Regular'，而不能写成 'Roboto', sans-serif。
9. 所有主题变体必须定义完全一致的 CSS 变量集 — 如果 light 主题定义了 --color-primary，那么 dark 及每个自定义主题也必须定义该变量。变量不匹配会导致运行时报错。
10. 非 style 类的颜色属性必须加 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）生效。对于非 style 的颜色属性，务必使用 accent-。
11. rem 默认基准值为 16px — NativeWind 使用的是 14px。如果是从 NativeWind 迁移过来的，请在 Metro 配置中设置 polyfills: { rem: 14 }。
12. cssEntryFile 必须是相对路径字符串 — 请使用 './global.css'，不要用 path.resolve(__dirname, 'global.css')。
13. 混合使用自定义 CSS 类与 Tailwind 时，务必用 cn() 去重 — Uniwind 不会自动去重。如果自定义 CSS 类（如 .card { padding: 16px }）与 Tailwind 工具类（p-6）作用于同一属性，两者都会生效且顺序不可控。存在样式重叠时，务必使用 cn('card', 'p-6') 进行包裹去重。
14. 支持 Important 修饰符 — Tailwind 的重要修饰符支持在 classNames 末尾加上 !，例如：bg-red-500!、active:bg-red-500!、ios:pt-12!。前置 !bg-red-500 语法已被废弃。Important 类的优先级高于同一样式属性的普通类，但内联 style 的优先级仍然高于 className。

参考路由（文档指南）

在明确用户的具体任务后，请仅阅读 references/ 目录下对应的参考文件：

• 环境搭建 / 配置安装问题：references/setup.md
• React Native 组件的 className 属性、accent 颜色属性或组件示例：references/component-bindings.md
• 第三方组件、withUniwind、动态类名、tailwind-variants、cn 或 important 修饰符：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 变体、默认样式、原生安全边距（native insets）或主题过渡：references/pro.md
• 样式失效、配置诊断、报错、缓存问题、FAQ、MCP 或相关 Skills：references/troubleshooting.md

工作流

1. 确认用户是需要环境搭建、样式编写、主题化、变体、集成、Pro 特性还是疑难解答方面的帮助。
2. 在给出具体指导或修改代码前，先阅读对应的参考文件。
3. 即使选定的参考文件未提及，也必须严格遵守上述【关键规则】。
4. 切勿凭空猜测 Uniwind API。如果不确定，请查阅官方文档校验：https://docs.uniwind.dev/llms-full.txt

相关 Skill

从 NativeWind 迁移是独立拆分出来的。当用户想要从 NativeWind 迁移到 Uniwind 时，请使用 migrate-nativewind-to-uniwind Skill。