uniwind

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Uniwind Best Practices

Uniwind 最佳实践

Comprehensive performance optimization and best practices guide for Uniwind - the fastest Tailwind CSS bindings for React Native. Contains 45+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

这是针对Uniwind（React Native最快的Tailwind CSS绑定库）的全面性能优化与最佳实践指南。包含8个分类下的45+条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Setting up Uniwind in a new React Native project
Configuring Metro plugin and CSS entry points
Building theme systems with CSS variables
Integrating third-party components with className support
Creating responsive layouts for mobile and tablet
Optimizing styling performance
Migrating from NativeWind to Uniwind

在以下场景中可参考本指南：

在新的React Native项目中配置Uniwind
配置Metro插件与CSS入口文件
使用CSS变量构建主题系统
集成支持className属性的第三方组件
为手机与平板创建响应式布局
优化样式性能
从NativeWind迁移至Uniwind

Rule Categories by Priority

按优先级划分的规则分类


build-
theme-
comp-
resp-
perf-
plat-
state-
compat-

Priority	Category	Impact	Prefix
1	Build-Time Configuration	CRITICAL	`build-`
2	Theme Architecture	CRITICAL	`theme-`
3	Component Integration	HIGH	`comp-`
4	Responsive Design	HIGH	`resp-`
5	Performance Optimization	MEDIUM-HIGH	`perf-`
6	Platform Patterns	MEDIUM	`plat-`
7	State & Interaction	MEDIUM	`state-`
8	Migration & Compatibility	LOW-MEDIUM	`compat-`


build-
theme-
comp-
resp-
perf-
plat-
state-
compat-

优先级	分类	影响程度	前缀
1	构建时配置	关键	`build-`
2	主题架构	关键	`theme-`
3	组件集成	高	`comp-`
4	响应式设计	高	`resp-`
5	性能优化	中高	`perf-`
6	平台适配模式	中	`plat-`
7	状态与交互	中	`state-`
8	迁移与兼容性	中低	`compat-`

Quick Reference

快速参考

1. Build-Time Configuration (CRITICAL)

1. 构建时配置（关键）

```
build-metro-config
```
- Configure Metro Plugin with Required Options
```
build-css-entry
```
- Place CSS Entry File in App Root Directory
```
build-typescript-types
```
- Configure TypeScript Definition File Location
```
build-restart-metro
```
- Restart Metro After Configuration Changes
```
build-debug-mode
```
- Enable Debug Mode During Development
```
build-rem-polyfill
```
- Configure rem Base Value for Design System Consistency

```
build-metro-config
```
- 配置Metro插件并设置必要选项
```
build-css-entry
```
- 将CSS入口文件放置在应用根目录
```
build-typescript-types
```
- 配置TypeScript定义文件的存放位置
```
build-restart-metro
```
- 配置变更后重启Metro
```
build-debug-mode
```
- 开发阶段启用调试模式
```
build-rem-polyfill
```
- 配置rem基准值以保证设计系统一致性

2. Theme Architecture (CRITICAL)

2. 主题架构（关键）

```
theme-css-variables
```
- Define Theme Variables with @theme Directive
```
theme-variant-blocks
```
- Use @variant Blocks for Theme Definitions
```
theme-consistent-variables
```
- Define Identical Variables Across All Themes
```
theme-custom-registration
```
- Register Custom Themes in Metro Config
```
theme-oklch-colors
```
- Use OKLCH Color Space for Perceptual Uniformity
```
theme-light-dark-function
```
- Use light-dark() Function for Adaptive Colors
```
theme-no-provider
```
- Remove ThemeProvider Wrapper from App

```
theme-css-variables
```
- 使用@theme指令定义主题变量
```
theme-variant-blocks
```
- 使用@variant块定义主题
```
theme-consistent-variables
```
- 在所有主题中定义相同的变量
```
theme-custom-registration
```
- 在Metro配置中注册自定义主题
```
theme-oklch-colors
```
- 使用OKLCH色彩空间实现感知一致性
```
theme-light-dark-function
```
- 使用light-dark()函数实现自适应色彩
```
theme-no-provider
```
- 移除应用中的ThemeProvider包装器

3. Component Integration (HIGH)

3. 组件集成（高）

```
comp-with-uniwind
```
- Use withUniwind for Third-Party Components
```
comp-module-level
```
- Define Wrapped Components at Module Level
```
comp-prop-mapping
```
- Use Custom Prop Mappings for Non-Style Props
```
comp-accent-colors
```
- Use accent-* Classes for Color Prop Extraction
```
comp-reanimated
```
- Reanimated Components Work Without withUniwind
```
comp-custom-css
```
- Use Custom CSS Classes for Complex Reusable Styles

```
comp-with-uniwind
```
- 对第三方组件使用withUniwind
```
comp-module-level
```
- 在模块级别定义包装后的组件
```
comp-prop-mapping
```
- 对非样式属性使用自定义属性映射
```
comp-accent-colors
```
- 使用accent-*类提取颜色属性
```
comp-reanimated
```
- Reanimated组件无需withUniwind即可正常工作
```
comp-custom-css
```
- 对复杂可复用样式使用自定义CSS类

4. Responsive Design (HIGH)

4. 响应式设计（高）

```
resp-mobile-first
```
- Design Mobile-First with Progressive Enhancement
```
resp-limit-breakpoints
```
- Limit Breakpoints to 3-5 for Maintainability
```
resp-visibility-toggle
```
- Use hidden/flex for Responsive Visibility
```
resp-custom-breakpoints
```
- Define Custom Breakpoints with Semantic Names
```
resp-responsive-spacing
```
- Scale Spacing and Typography Responsively

```
resp-mobile-first
```
- 采用移动优先设计并逐步增强功能
```
resp-limit-breakpoints
```
- 将断点数量限制在3-5个以提升可维护性
```
resp-visibility-toggle
```
- 使用hidden/flex实现响应式可见性切换
```
resp-custom-breakpoints
```
- 使用语义化名称定义自定义断点
```
resp-responsive-spacing
```
- 响应式调整间距与排版

5. Performance Optimization (MEDIUM-HIGH)

5. 性能优化（中高）

```
perf-static-classnames
```
- Use Complete Static Class Names for Build-Time Resolution
```
perf-use-resolve-sparingly
```
- Use useResolveClassNames Sparingly
```
perf-memoize-variants
```
- Memoize Variant Style Objects
```
perf-tailwind-merge
```
- Use tailwind-merge for Class Deduplication
```
perf-avoid-inline-styles
```
- Prefer className Over Inline style Prop
```
perf-combine-styles
```
- Combine className and style Prop Correctly

```
perf-static-classnames
```
- 使用完整的静态类名以支持构建时解析
```
perf-use-resolve-sparingly
```
- 谨慎使用useResolveClassNames
```
perf-memoize-variants
```
- 对变体样式对象进行记忆化处理
```
perf-tailwind-merge
```
- 使用tailwind-merge实现类名去重
```
perf-avoid-inline-styles
```
- 优先使用className而非内联style属性
```
perf-combine-styles
```
- 正确组合className与style属性

6. Platform Patterns (MEDIUM)

6. 平台适配模式（中）

```
plat-ios-android-selectors
```
- Use Platform Selectors for iOS/Android Differences
```
plat-safe-area-context
```
- Use react-native-safe-area-context for Safe Areas
```
plat-yoga-layout
```
- Understand Yoga Layout Engine Differences
```
plat-web-selector
```
- Use web: Selector for Cross-Platform Apps
```
plat-font-families
```
- Configure Font Families Without Fallbacks

```
plat-ios-android-selectors
```
- 使用平台选择器处理iOS/Android差异
```
plat-safe-area-context
```
- 使用react-native-safe-area-context处理安全区域
```
plat-yoga-layout
```
- 了解Yoga布局引擎的差异
```
plat-web-selector
```
- 对跨平台应用使用web:选择器
```
plat-font-families
```
- 配置字体族时不使用回退字体

7. State & Interaction (MEDIUM)

7. 状态与交互（中）

```
state-pressable-states
```
- Use Pressable with active:/focus:/disabled: States
```
state-data-selectors
```
- Use Data Selectors for Component State Styling
```
state-no-hover
```
- Avoid hover: on Native - Use active: Instead
```
state-group-variants
```
- Use Group Variants for Parent-Child Styling (WIP)
```
state-dark-mode
```
- Use dark: Variant for Dark Mode Styles

```
state-pressable-states
```
- 将Pressable与active:/focus:/disabled:状态配合使用
```
state-data-selectors
```
- 使用数据选择器实现组件状态样式
```
state-no-hover
```
- 原生平台避免使用hover:，改用active:
```
state-group-variants
```
- 使用组变体实现父子组件样式（开发中）
```
state-dark-mode
```
- 使用dark:变体实现暗黑模式样式

8. Migration & Compatibility (LOW-MEDIUM)

8. 迁移与兼容性（中低）

```
compat-nativewind-migration
```
- Follow NativeWind Migration Checklist
```
compat-tailwind-4-syntax
```
- Use Tailwind 4 CSS-First Configuration
```
compat-rem-default
```
- Account for Different rem Default Values
```
compat-cssinterop-replacement
```
- Replace cssInterop with withUniwind
```
compat-safe-area-changes
```
- Replace *-safe Classes with Safe Area Context

```
compat-nativewind-migration
```
- 遵循NativeWind迁移清单
```
compat-tailwind-4-syntax
```
- 使用Tailwind 4的CSS优先配置
```
compat-rem-default
```
- 适配不同的rem默认值
```
compat-cssinterop-replacement
```
- 用withUniwind替代cssInterop
```
compat-safe-area-changes
```
- 用安全区域上下文替代*-safe类

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明与代码示例：

Section definitions - 分类结构与影响级别说明
Rule template - 添加新规则的模板

Reference Files

参考文件

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	分类定义与排序说明
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息