/mobile-styling-nativewind

name: mobile-styling-nativewind
description: NativeWind v4+ - Tailwind CSS utility classes for React Native, className prop, CSS variables, dark mode, platform prefixes, animations, theming, third-party component integration

NativeWind Patterns

> **Quick Guide:** NativeWind brings Tailwind CSS utility classes to React Native via `className` prop. Styles compile to `StyleSheet.create` at build time with a lightweight runtime for conditional logic (dark mode, hover, focus). Always declare both light AND dark styles (no CSS cascade in RN). Use `vars()` for runtime theming with CSS variables. Platform prefixes (`ios:`, `android:`, `native:`) replace `Platform.select` for styling. Use `remapProps` for third-party components with multiple style props; reserve `cssInterop` for components needing style-to-prop extraction.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST always declare BOTH light and dark styles -- `className="text-black dark:text-white"` not just `className="dark:text-white"` -- React Native has no CSS cascade)**

**(You MUST use `remapProps` for third-party components with multiple style props and `cssInterop` ONLY when style attributes need extraction to props -- NEVER use either for your own custom components)**

**(You MUST import `"./global.css"` at your app entry point -- without it no styles render)**

**(You MUST add `/// <reference types="nativewind/types" />` in a `nativewind-env.d.ts` file for TypeScript className support)**

**(You MUST use `nativewind/preset` in `tailwind.config.js` presets -- without it platform-specific features break)**

</critical_requirements>

---

**Auto-detection:** NativeWind, nativewind, className on React Native components, nativewind/preset, nativewind/babel, nativewind/metro, withNativeWind, cssInterop, remapProps, vars(), useColorScheme from nativewind, useUnstableNativeVariable, dark: prefix in React Native, ios: prefix, android: prefix, native: prefix, global.css tailwind directives, nativewind-env.d.ts

**When to use:**

• Styling React Native components with Tailwind CSS utility classes
• Implementing dark mode with automatic system detection or manual toggle
• Creating dynamic themes with CSS variables via `vars()`
• Applying platform-specific styles with `ios:`/`android:`/`native:` prefixes
• Integrating className support with third-party React Native libraries
• Adding transitions and animations to React Native components

**Key patterns covered:**

• className prop usage and custom component patterns
• Dark mode with `useColorScheme` (system preference and manual toggle)
• CSS variables for runtime theming via `vars()` and `useUnstableNativeVariable()`
• Platform prefixes (`ios:`, `android:`, `web:`, `native:`) for cross-platform styling
• Third-party component integration (`remapProps` vs `cssInterop`)
• Animations and transitions (experimental, powered by react-native-reanimated)
• Variant components with class merging libraries

**When NOT to use:**

• Web-only React projects (use standard Tailwind CSS)
• Projects that need zero runtime overhead (use `StyleSheet.create` directly)
• Apps on legacy React Native architecture that cannot adopt New Architecture dependencies

**Detailed Resources:**

• [examples/core.md](examples/core.md) - className usage, custom components, variants, conditional styling
• [examples/theming.md](examples/theming.md) - Dark mode, CSS variables, theme switching, useColorScheme
• [examples/platform-and-interop.md](examples/platform-and-interop.md) - Platform prefixes, cssInterop, remapProps, third-party integration
• [reference.md](reference.md) - Decision frameworks, API cheat sheet, migration notes

---

<philosophy>

Philosophy

NativeWind bridges Tailwind CSS and React Native by compiling utility classes into `StyleSheet.create` objects at build time and providing a runtime for conditional style logic (dark mode, hover states, focus). The `className` prop works directly on React Native core components via a JSX transform -- no wrapper components needed.

**Core principles:**

1. **Build-time compilation** -- Tailwind classes compile to native `StyleSheet.create` objects, keeping runtime overhead minimal (~2ms per render vs 0ms for raw StyleSheet) 2. **className is first-class** -- The JSX transform makes `className` available inside your components, enabling compatibility with class merging libraries (clsx, tailwind-variants, cva) 3. **No CSS cascade on native** -- React Native does not cascade styles. You must always declare both sides of conditional styles (`text-black dark:text-white`, not just `dark:text-white`) 4. **Platform prefixes over Platform.select** -- For styling concerns, `ios:shadow-lg android:elevation-4` is more declarative than wrapping in `Platform.select` 5. **Custom components just merge classNames** -- Never use `cssInterop` or `remapProps` on your own components. Simply accept a `className` prop and merge it with defaults 6. **Third-party integration is explicit** -- Use `remapProps` (lightweight) or `cssInterop` (full runtime) only for third-party components that need className support

**Architecture:**

NativeWind's JSX transform intercepts component rendering. On native, it resolves className strings into `StyleSheet.create` IDs and applies conditional logic. On web, it passes className through as standard CSS. This means:

• `react-native-reanimated` is a peer dependency (powers animations and transitions)
• `react-native-safe-area-context` is a peer dependency (used for safe area utilities)
• `tailwindcss ^3.4` is required (v4 uses Tailwind CSS v3 config format; NativeWind v5 targets Tailwind CSS v4)
• Inline `style` props merge with className-based styles, with inline taking precedence

**rem units:** NativeWind uses rem: 14 on native (matching React Native's default 14px font size) an