/mobile-styling-unistyles

name: mobile-styling-unistyles
description: Unistyles 3.0 styling - C++ powered StyleSheet superset with zero re-renders, theming, breakpoints, variants, dynamic functions, runtime values

Unistyles 3.0 Patterns

> **Quick Guide:** Unistyles 3.0 is a StyleSheet superset powered by Nitro Modules (C++/JSI). Import `StyleSheet` from `react-native-unistyles` instead of `react-native` -- same API, but with themes, breakpoints, variants, dynamic functions, and runtime values. Zero re-renders: styles update via the Shadow Tree, not React state. Configure with `StyleSheet.configure()` before any `StyleSheet.create()`. Never spread styles (`{...a, ...b}`) -- use array syntax (`[a, b]`). Requires New Architecture (RN 0.78+).

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST import `StyleSheet` from `react-native-unistyles`, NOT from `react-native` -- the Unistyles version is a superset that enables all features)**

**(You MUST call `StyleSheet.configure()` BEFORE any `StyleSheet.create()` -- configure in your entry file before importing components)**

**(You MUST use array syntax `[styles.a, styles.b]` for merging styles -- NEVER spread `{...styles.a, ...styles.b}` as it destroys C++ state)**

**(You MUST NOT use `useUnistyles` hook in regular components -- it forces full re-renders, defeating Unistyles' zero-render architecture)**

**(You MUST pass only serializable arguments to dynamic functions -- strings, numbers, booleans, arrays, objects (no functions or components))**

</critical_requirements>

---

**Auto-detection:** Unistyles, react-native-unistyles, StyleSheet.configure, UnistylesRuntime, UnistylesThemes, UnistylesBreakpoints, useVariants, compoundVariants, ScopedTheme, withUnistyles, useUnistyles, miniRuntime, rt.insets, rt.screen, mq.only, Display, Hide

**When to use:**

• Styling React Native apps that need dynamic theming (light/dark or custom themes)
• Building responsive layouts with breakpoints and media queries across mobile and web
• Creating reusable component variants (size, color, state) without conditional logic
• Accessing runtime device values (insets, screen size, font scale) inside stylesheets
• Migrating from Unistyles 2.x to 3.0

**When NOT to use:**

• Apps that cannot use the New Architecture (requires RN 0.78+, Fabric)
• Expo Go apps (requires development builds with native modules)
• Minimal apps with no theme switching or responsive needs (plain StyleSheet suffices)
• Apps using a utility-class approach (consider a utility-class styling solution instead)

**Key patterns covered:**

• StyleSheet.configure: themes, breakpoints, settings registration
• StyleSheet.create with theme and miniRuntime (rt) access
• Variants and compound variants for reusable component styles
• Dynamic functions with serializable parameters
• Breakpoints, media queries, and Display/Hide components
• Runtime values: insets, screen dimensions, font scale, color scheme
• Scoped themes and adaptive themes
• withUnistyles for third-party component integration
• Style merging with array syntax (never spread)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - StyleSheet setup, theme access, dynamic functions, style merging
• [examples/theming.md](examples/theming.md) - Theme configuration, adaptive themes, scoped themes, runtime switching
• [examples/responsive.md](examples/responsive.md) - Breakpoints, media queries, Display/Hide, runtime values
• [examples/variants.md](examples/variants.md) - Variants, compound variants, boolean variants, component props pattern
• [reference.md](reference.md) - API quick reference, decision frameworks, v2-to-v3 migration

---

<philosophy>

Philosophy

Unistyles 3.0 is a **StyleSheet superset** -- if you know React Native's `StyleSheet.create`, you know 80% of Unistyles. The remaining 20% is what makes it powerful: themes, responsive breakpoints, variants, and runtime values, all managed in C++ via JSI with **zero React re-renders**.

**How it works:**

1. **Babel plugin** analyzes StyleSheets at build time, detecting dependencies (theme, runtime, breakpoints) 2. **C++ core** reconstructs StyleSheets natively and tracks which styles depend on what 3. **Shadow Tree updates** bypass React entirely -- when a theme changes or the device rotates, only the affected ShadowNodes update their styles directly

**Core principles:**

1. **Zero re-renders** -- No hooks, no context, no state updates for style changes. The C++ core updates the Shadow Tree directly. 2. **StyleSheet superset** -- Same API as React Native's StyleSheet. Replace the import, keep your code. 3. **Type-safe themes** -- TypeScript declarations ensure full autocompletion for theme properties. 4. **Selective recalculation** -- Only styles that depend on a changed value (theme, breakpoint, inset) are recalculated. 5. **Cross-platform** -- Same styles work on iOS, Android, and web (with automatic CSS class generation for web).

**When Unistyles adds value over plain StyleSheet:**

• Multiple themes (dark/light/custom) with instant switching
• Responsive layouts that adapt to screen size, orientation, or device type
• Component variants (primary/secondary, small/large) without conditional style logic
• Runtime-dependent styles (safe area insets, font scale, keyboard height)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: StyleSheet.create with Theme and Runtime

Replace `react-native` import with `react-native-unistyles`. The create function accepts a callback with `theme` and `rt` (miniRuntime) for dynamic styles. Static styles (no theme/runtime) work identically to plain StyleSheet.

import { StyleSheet } from "react-native-unistyles";

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    backgroundColor: theme.colors.background,
    paddingTop: rt.insets.top,
  },
  text: {
    color: theme.colors.typography,
    fontSize: rt.fontScale * 16,
  },
  // Static styles work exactly lik