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