Uniwind Best Practices

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.

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

Rule Categories by Priority

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-

Quick Reference

1. Build-Time Configuration (CRITICAL)

• 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

2. Theme Architecture (CRITICAL)

• 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

3. Component Integration (HIGH)

• 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

4. Responsive Design (HIGH)

• 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

5. Performance Optimization (MEDIUM-HIGH)

• 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

6. Platform Patterns (MEDIUM)

• 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

7. State & Interaction (MEDIUM)

• 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

8. Migration & Compatibility (LOW-MEDIUM)

• 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

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