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