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

build-

theme-

comp-

resp-

perf-

plat-

state-

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