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 将 Tailwind CSS v4 带到了 React Native。所有 React Native 核心组件皆原生支持 className 属性。样式在构建阶段（build time）即完成编译 — 零运行时开销（runtime overhead）。

核心规则（Critical Rules）

1. 仅限 Tailwind v4 — 请使用 @import 'tailwindcss'，而非 @tailwind base。不支持 Tailwind v3。
2. 切勿动态拼装 className — Tailwind 在构建阶段扫描代码。bg-${color}-500 将无法生效。请使用完整的字符串字面量、映射对象（mapping objects）或三元运算符。
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 不支持字体后备机制（fallbacks）。请使用 --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 类与 Tailwind 时需使用 cn() 去重 — Uniwind 不会自动去重。如果自定义 CSS 类（如 .card { padding: 16px }）与 Tailwind 工具类（p-6）设置了相同的属性，两者都会被应用，导致不可预测的结果。当样式存在重叠时，请务必使用 cn('card', 'p-6') 进行包裹。
14. 支持 Important 工具类 — Tailwind 的 important 修饰符可以在 className 末尾加上 ! 生效：如 bg-red-500!、active:bg-red-500!、ios:pt-12!。前置 !bg-red-500 语法已被弃用。针对同一个样式属性，Important 工具类会覆写 Non-important 工具类，但内联 style 仍可覆写 className。

参考资料路由（Reference Routing）

在确认用户的任务后，仅读取 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 变体、默认样式、原生 Safe Area Insets 或主题切换过渡：references/pro.md
• 样式失效、配置诊断、错误排查、缓存问题、常见问题解答（FAQ）、MCP 或相关 Skill：references/troubleshooting.md

工作流程（Workflow）

1. 确认用户需要的是环境配置、样式设定、主题构建、变体应用、第三方集成、Pro 功能还是疑难排解协助。
2. 在提供详细指导或修改代码前，先阅读对应的参考文件。
3. 即使选定的参考文件未提及上述“核心规则”，也必须严格遵守。
4. 切勿凭空猜测 Uniwind API。若不确定，请查阅官方文档验证：https://docs.uniwind.dev/llms-full.txt

相关 Skill（Related Skills）

NativeWind 的迁移指南已独立拆分。当用户希望从 NativeWind 迁移时，请使用 migrate-nativewind-to-uniwind Skill。