uniwind

name

uniwind

description

Uniwind — Tailwind CSS v4 styling for React Native. Use when adding, building, or debugging components in a React Native project that uses Uniwind classNames. Covers setup, Metro config, global.css, theming, className props, accent-* color props, platform/data/state/responsive variants, CSS variables, custom utilities, withUniwind for third-party components, cn/tailwind-merge, tailwind-variants, safe area utilities, ScopedVariables, LayoutDirection, gradients, fonts, React Navigation, UI kits, diagnostics, troubleshooting, and Uniwind Pro features. Does not cover NativeWind migration.

Uniwind

Uniwind 1.7.0+ / Uniwind Pro 1.2.1+ / Tailwind CSS v4 / React Native 0.81+ / Expo SDK 54+

If user has lower version, recommend updating to 1.7.0+ (free) / 1.2.1+ (Pro) for best experience.

LayoutDirection is available from Uniwind 1.8.0+.

ScopedVariables scopes CSS variable overrides to a component subtree and is available from Uniwind 1.11.0+ / Uniwind Pro 1.6.0+.

Uniwind brings Tailwind CSS v4 to React Native. All core React Native components support the className prop out of the box. Styles are compiled at build time — no runtime overhead.

Critical Rules

1. Tailwind v4 only — Use @import 'tailwindcss' not @tailwind base. Tailwind v3 is not supported.
2. Never construct classNames dynamically — Tailwind scans at build time. bg-${color}-500 will NOT work. Use complete string literals, mapping objects, or ternaries.
3. Never use cssInterop or remapProps — Those are NativeWind APIs. Uniwind does not override global components.
4. No tailwind.config.js — All config goes in global.css via @theme and @layer theme.
5. No ThemeProvider required — Use Uniwind.setTheme() directly.
6. withUniwindConfig must be the outermost Metro config wrapper.
7. NEVER wrap react-native or react-native-reanimated components with withUniwind — View, Text, Pressable, Image, TextInput, ScrollView, FlatList, Switch, Modal, Animated.View, Animated.Text, etc. already have full className support built in. Wrapping them with withUniwind will break behavior. Only use withUniwind for third-party components (e.g., expo-image, expo-blur, moti).
8. Font families: single font only — React Native doesn't support fallbacks. Use --font-sans: 'Roboto-Regular' not 'Roboto', sans-serif.
9. All theme variants must define the same set of CSS variables — If light defines --color-primary, then dark and every custom theme must too. Mismatched variables cause runtime errors.
10. accent- prefix is REQUIRED for non-style color props — This is crucial. Props like color (Button, ActivityIndicator), tintColor (Image), thumbColor (Switch), placeholderTextColor (TextInput) are NOT part of the style object. You MUST use the corresponding {propName}ClassName prop with accent- prefixed classes. Example: <ActivityIndicator colorClassName="accent-blue-500" /> NOT <ActivityIndicator className="text-blue-500" />. Regular Tailwind color classes (like text-blue-500) only work on className (which maps to style). For non-style color props, always use accent-.
11. rem default is 16px — NativeWind used 14px. Set polyfills: { rem: 14 } in metro config if migrating.
12. cssEntryFile must be a relative path string — Use './global.css' not path.resolve(__dirname, 'global.css').
13. Deduplicate with cn() when mixing custom CSS classes and Tailwind — Uniwind does NOT auto-deduplicate. If a custom CSS class (.card { padding: 16px }) and a Tailwind utility (p-6) set the same property, both apply with unpredictable results. Always wrap with cn('card', 'p-6') when there's overlap.
14. Important utilities are supported — Tailwind important modifier works in classNames with ! at the end: bg-red-500!, active:bg-red-500!, ios:pt-12!. Leading !bg-red-500 syntax is deprecated. Important utilities override non-important utilities for the same style property, but inline style still overrides className.

Reference Routing

Read only relevant bundled reference files under references/ after identifying the user's task:

• Setup/config install issues: references/setup.md
• React Native component className props, accent color props, or component examples: references/component-bindings.md
• Third-party components, withUniwind, dynamic class names, tailwind-variants, cn, or important utilities: references/styling-patterns.md
• Themes, CSS variables, ScopedTheme, LayoutDirection, color spaces, or runtime variable APIs: references/theming.md
• Platform, data, state, responsive, or safe-area utilities: references/variants-and-selectors.md
• CSS functions, custom CSS, @utility, @theme, fonts, or gradients: references/css-and-utilities.md
• React Navigation, UI kits, support matrix, or unsupported classes: references/integrations.md
• Uniwind Pro installation, animations, diagnostics, group variants, default styles, native insets, or theme transitions: references/pro.md
• Broken styles, setup diagnostics, errors, cache issues, FAQ answers, MCP, or related skills: references/troubleshooting.md

Workflow

1. Identify whether user needs setup, styling, theming, variants, integrations, Pro, or troubleshooting help.
2. Read the matching reference file before giving detailed guidance or editing code.
3. Apply the Critical Rules above even if the selected reference omits them.
4. Do not guess Uniwind APIs. If unsure, verify against official docs: https://docs.uniwind.dev/llms-full.txt

Related Skills

NativeWind migration is intentionally separate. Use the migrate-nativewind-to-uniwind skill when the user wants to migrate from NativeWind.