uniwind-best-practices

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

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

章节定义 - 类别结构与影响级别说明
规则模板 - 添加新规则的模板

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	版本与参考信息