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

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