uniwind

name	uniwind
description	Uniwind best practices for React Native styling with Tailwind CSS. This skill should be used when writing, reviewing, or refactoring React Native code using Uniwind. Triggers on tasks involving Uniwind, className styling, Tailwind in React Native, NativeWind migration, or theming.

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