React Native Design

react-native-design

This skill guides the creation of distinctive, production-grade React Native UI that avoids generic "AI slop" aesthetics and respects the hard constraints of the mobile platform. It acts as a complete UX/UI replacement — capable of generating color systems, designing screens from scratch, critiquing and improving existing UI, and making every design decision that a professional designer would make.

The user provides a screen, component, UI direction, app concept, or design problem. They may include context about the purpose, audience, target platform, existing styling approach, or preferred colors.

Core Philosophy

1. Every pixel is a decision. Nothing should be accidental — not a color, not a spacing value, not a font choice.
2. Design is problem-solving, not decoration. The UI must serve the user's task, not look impressive in a screenshot.
3. Platform correctness is non-negotiable. Beautiful design that crashes or renders incorrectly is worthless.
4. Consistency compounds. A simple system applied rigorously beats complex rules applied inconsistently.
5. Intentionality over trends. A deliberate choice to be minimal is as powerful as a choice to be bold.

Design Thinking — Expanded Framework

Before touching any code, answer these questions (internally or by asking the user):

1. Purpose & Audience

• What problem does this app/screen solve?
• Who is the target user? (age, tech literacy, context of use — commuting? at home? at work?)
• What emotional response should the UI trigger? (trust, excitement, calm, urgency, delight)
• Will users spend seconds or minutes on this screen?

2. Aesthetic Direction

Commit to ONE personality. Do not default to "clean and modern" — that is a non-choice.

3. Theme Preference

• Dark: Depth, layers, glowing accents, contrast through luminosity
• Light: Whitespace, shadows for depth, color used sparingly
• Both (dual): Requires a token system that maps semantic roles, not hardcoded values

4. Differentiation

• What is the ONE thing a user will notice and remember?
• What makes this different from the 10 closest competitors?

CRITICAL: Intentionality beats intensity. A well-executed minimal design and a well-executed maximalist design are both excellent. A half-hearted attempt at either is not.

Color System — Complete Theory & Generation

This section enables creating professional color palettes from scratch, from user-provided colors, or improving existing ones.

Color Theory Fundamentals

Every professional palette is built on color relationships:

Palette Generation Process

Starting from an app concept (no user colors):

1. Identify the emotional tone → pick a dominant hue family:

   • Trust/stability → Blue (210°–240°)
   • Energy/passion → Red-Orange (0°–30°)
   • Growth/health → Green (120°–160°)
   • Creativity/luxury → Purple (270°–310°)
   • Warmth/optimism → Yellow-Orange (30°–60°)
   • Calm/nature → Teal-Cyan (170°–200°)
   • Sophistication/tech → Blue-Violet (240°–270°)

2. Choose a relationship scheme (split-complementary is the safest default)

3. Generate the full system using the token structure below

Starting from user-provided colors (1-3 colors):

1. Identify the provided color(s) as HSL values

2. Determine their role: is it accent? background? brand mark?

3. Derive the missing roles:

   • If user gives 1 accent color: build surfaces around it (dark: desaturate + darken for backgrounds; light: tint for surfaces)
   • If user gives 2 colors: determine their relationship, fill remaining slots
   • If user gives a brand palette: respect the hierarchy, add functional colors (semantic states, surface layers)

4. Generate tints/shades of the accent at these stops: 50, 100, 200, 300, 400, 500 (base), 600, 700, 800, 900, 950

Improving an existing palette:

1. Read ALL color tokens in the project
2. Check for these common problems:
   • Accent too close to semantic colors (can't distinguish "success" from "primary")
   • Surface layers without enough contrast between steps (< 5% luminosity gap = invisible)
   • Text colors that don't meet WCAG AA (4.5:1 for body, 3:1 for large text)
   • Too many unique colors that don't relate to each other
   • Borders/strokes that create unintended halos against their backgrounds
3. Propose specific fixes with before/after hex values

Color Token Architecture — Mandatory Structure

Every theme MUST have these semantic layers. Names can vary by project convention, but the roles must be present:

SURFACES (background layers — establish depth)
├── base         → absolute deepest background (dark: #070B11-ish, light: #F8FAFC-ish)
├── main         → primary screen background
├── elevated     → cards, modals, floating elements
├── overlay      → scrim behind modals (semi-transparent)
└── interactive  → hover/pressed states on surfaces

ACCENT (brand color)
├── main         → primary accent (buttons, links, active states)
├── container    → filled surfaces with accent (CTAs, badges, selected states)
├── subtle       → tinted surfaces (sidebar active item, selected card bg)
├── on-accent    → text/icon color ON the accent fill

TEXT (foreground hierarchy)
├── primary      → highest contrast — titles, critical content
├── secondary    → body text, descriptions
├── tertiary     → muted — placeholders, metadata, timestamps
├── disabled     → clearly inactive
└── on-color     → text on colored surfaces (accent, semantic)

BORDERS (stroke hierarchy)
├── default      → card borders, dividers
├── subtle       → barely visible separators
├── strong       → focused inputs, active states
└── accent       → accent-colored borders

SEMANTIC (functional — MUST differ from accent)
├── success      → main + surface + text
├── warning      → main + surface + text
├── error        → main + surface + text
└── info         → main + surface + text

COMPONENT-SPECIFIC (optional but recommended)
├── button       → primary/secondary/ghost/danger states
├── input        → default/focused/error fills and strokes
├── navigation   → tab colors, active indicators
└── card         → specific card backgrounds if they differ from general surfaces

Dark Theme Color Rules

Light Theme Color Rules

Dual Theme System (Light + Dark)

When building both themes:

1. Never hardcode colors in components — always reference semantic tokens
2. Map by role, not by value — background.main resolves to different hex per theme
3. Implementation patterns (detect what the project uses):

// styled-components: ThemeProvider swap
const darkTheme = { colors: { bg: { main: '#0C1219' }, ... } };
const lightTheme = { colors: { bg: { main: '#F8FAFC' }, ... } };

// NativeWind: dark: prefix OR CSS variables
// className="bg-surface-main dark:bg-surface-main-dark"

// Context-based: useTheme() hook returning current tokens

4. Test both themes — every component must be verified against both palettes

Accessibility — Color Contrast Requirements

Quick contrast check formula (for dark themes):

• Text at rgba(255,255,255, 0.87) on #1C1C1E = ~12:1 ✓
• Text at rgba(255,255,255, 0.60) on #1C1C1E = ~8:1 ✓
• Text at rgba(255,255,255, 0.38) on #1C1C1E = ~5:1 ✓ (large text only)

For accents as text: The accent color must have ≥4.5:1 against its surface. Teal #2DD4BF on #0C1219 ≈ 9:1 ✓. But teal on #253244 ≈ 5.5:1 — use with caution on elevated surfaces.

Theme Creation — Step-by-Step Workflows

Workflow A: Create a Theme from Scratch (New App)

When a user says "I'm building an app for X, create a theme":

1. Ask or infer the app category, audience, and aesthetic direction
2. Choose a dominant hue based on the emotional tone (see table above)
3. Select a color scheme (default to split-complementary unless the app is clearly monochromatic)
4. Generate the full token structure following the Color Token Architecture
5. Select fonts:
   • Display/brand: distinctive, memorable (not Inter/Roboto/system default)
   • Body/UI: highly legible, with available weight variants
   • Use @expo-google-fonts for easy loading
6. Define the type scale (minimum: display, title, headline, body, caption, label)
7. Define spacing (4pt or 8pt base grid)
8. Define border radius (consistent set: none, sm, md, lg, full)
9. Output: Complete theme file + type definitions + font loading instructions

Workflow B: Improve an Existing Theme

When a user says "improve my colors" or "the UI feels off":

1. Read all theme files (colors, typography, spacing, components)
2. Audit against the rules in this skill:
   • Surface contrast steps sufficient?
   • Accent readable on all its surfaces?
   • Semantic colors distinct from accent?
   • Typography hierarchy has enough range? (min 3:1 ratio between smallest and largest)
   • Spacing consistent with a grid?
3. Identify top 3 issues — prioritize by visual impact
4. Propose changes with exact hex values, showing before → after
5. Explain the reasoning briefly (not pages of theory — just "this fixes X because Y")

Workflow C: Create a Theme from User Colors

When a user provides specific colors:

1. Analyze the colors — convert to HSL, identify hue family, saturation, luminosity
2. Assign roles: which is accent? which is surface? Let the most saturated/distinctive color be the accent
3. Generate complementary colors using the theory above
4. Build the full surface stack around the provided colors
5. Verify contrast of every text/surface combination
6. Output: Complete theme, noting which colors are user-provided vs generated

Workflow D: Design a Specific View

When a user says "design a login screen" or "create a profile view":

1. Inspect existing theme and components — work within what exists
2. Select the appropriate screen pattern from the catalog below
3. Apply the theme tokens — never introduce new colors not in the system
4. Structure the layout following the Layout Decision Framework
5. Handle all states: default, loading, error, empty, success
6. Output: Complete view code, styles, and types if applicable

Screen Pattern Catalog

Reference designs for common screens. Each pattern includes structure, key design decisions, and what separates good from great.

Authentication (Login / Register / Forgot Password)

Structure: Centered form, minimal distraction, clear primary CTA, secondary links below.

Great: Smooth keyboard transitions, immediate field validation, subtle brand personality through font/color choice, haptic on submit.

Home / Dashboard

Structure: Scrollable surface with sections — greeting/status → primary content → secondary content.

Great: Content-first (data visible without scrolling), progressive disclosure, personalized ordering.

Detail View (Item/Product/Content)

Structure: Hero image/visual → title + metadata → body content → actions.

Great: Smooth scroll-linked transitions, image loading with shimmer/blur-up, rich metadata without clutter.

List / Collection

Structure: Optional filters/tabs at top → scrollable list → empty state.

Great: Smooth scroll performance (FlatList + getItemLayout), item animations on appear, pull-to-refresh with custom animation.

Profile / Settings

Structure: Avatar + info header → sections grouped by category → danger zone at bottom.

Great: Smooth avatar upload with crop, grouped sections with clear visual separation, confirmation for destructive actions.

Search

Structure: Search input (auto-focused) → recent/suggestions → results.

Great: Instant results feeling (optimistic UI), search highlighting in results, filter integration.

Onboarding / Walkthrough

Structure: 2-4 pages maximum → skip option → final CTA.

Great: Subtle page transition animations, micro-interactions on illustrations, progress feels fast (never sluggish).

Modal / Bottom Sheet

Structure: Handle (for sheets) → title → content → actions.

Tab / Navigation Structure

Layout Decision Framework

When deciding HOW to structure a view, follow this decision tree:

Content Type → Layout Choice

Is the content a list of similar items?
├── YES → Are items visual (images/thumbnails)?
│   ├── YES → Grid (2-3 cols) OR horizontal scroll carousel
│   └── NO  → Vertical list (FlatList)
└── NO  → Is it a form?
    ├── YES → Vertical scroll, single column, generous spacing
    └── NO  → Is it mixed content (hero + details + actions)?
        ├── YES → ScrollView with sections
        └── NO  → Is it a dashboard with multiple data types?
            ├── YES → Sections with different component types
            └── NO  → Centered content (auth, empty states, confirmation)

Spacing Rules

Component Size Reference

Project Context — Detect Before Designing

Before proposing any changes, determine what kind of project you are working with:

New project (no existing screens or theme)

• Full creative freedom. Follow Workflow A from Theme Creation.
• Define a color system, type scale, and spacing unit before writing any component.
• Apply the Visual Aesthetics Guidelines without constraint.

Existing project (screens, components, or theme already present)

Run this diagnostic first:

1. Inspect the theme/token system — check for a colors.ts, theme.ts, tailwind.config, or equivalent. Understand the existing palette, surface layers, and typography scale.
2. Inspect the existing screens — identify the current hierarchy (header, content, empty states, interactive elements).
3. Evaluate impact ceiling — ask yourself: if I only work within the existing design system, will the changes be visually meaningful or just incremental noise?

If working within the existing system is enough (the theme has sufficient depth, the type scale has range, the spacing system is solid): proceed and apply the Visual Aesthetics Guidelines within those constraints.

If the existing system limits impact (flat color palette, no typographic hierarchy, uniform spacing, no surface layers): stop and ask the user:

"I've analyzed the current design system. To make a meaningful visual improvement, I'd need to [describe what's missing — e.g. add a display font, introduce surface elevation, extend the color palette]. Do you want me to: A) Work strictly within what exists (smaller but safer changes) B) Propose additions to the design system to unlock bolder improvements (I'll show you what I'd add before touching any code)"

Never silently extend the design system. Never silently stay within it if doing so produces only pixel-level changes. Make the trade-off visible to the user.

Impact check (applies to both cases)

Before finalizing any design proposal, verify:

• Has the typographic hierarchy changed? (sizes, weights, or scale — not just tokens)
• Has the layout structure changed? (not just padding values — actual arrangement of elements)
• Is there at least one decision that the user will notice immediately on first look?

If none of these are true, the work is not done. Incremental token swaps are not design decisions.

Technical baseline (always inspect first)

Before making code changes, inspect the project's runtime and styling baseline:

1. App runtime — detect Expo vs framework-less React Native. Check package.json, app.json/app.config.*, and the entry file.
2. React Native version — note the RN version when available. Some styling capabilities are version-dependent.
3. Architecture support — detect whether the project uses the New Architecture before relying on newer style props such as boxShadow.
4. Core UI libraries — check for react-native-safe-area-context, react-native-reanimated, react-native-gesture-handler, expo-router / @react-navigation/*, expo-blur, and image libraries.
5. Styling stack — detect whether the project uses StyleSheet.create, NativeWind, styled-components, Restyle, or another established pattern.

If the project already has a clear stack and conventions, follow them. Do not introduce a new styling system or theming model unless the user explicitly wants that change.

React Native Platform Constraints

These are hard rules — not preferences. Violating them produces broken or incorrect UI.

Layout Engine

• All layout uses Flexbox. There is no CSS Grid, no display: block, no float.
• flexDirection defaults to column (NOT row like on the web).
• alignItems defaults to stretch. alignContent defaults to flex-start.
• flexShrink defaults to 0 (web default is 1).
• All dimensions are unitless density-independent pixels — never px, em, rem, or vw/vh.
• Use Dimensions.get('window') or useWindowDimensions() for screen-relative sizing.
• Percentage values work (width: '50%') but require a parent with defined dimensions.

Gradients

• CSS background: linear-gradient(...) does NOT work in React Native. It is silently ignored.
• Use expo-linear-gradient (<LinearGradient>) or react-native-linear-gradient for all gradients.
• Pass colors as an array: colors={['#000', '#333']}. Control direction with start and end props.

Shadows

• iOS: Use shadowColor, shadowOffset, shadowOpacity, shadowRadius.
• Android: Use elevation (integer). It also affects z-index stacking.
• There is no universally safe single cross-platform shadow property — handle iOS shadow props and Android elevation explicitly unless the project already relies on a newer supported API.
• Modern React Native exposes boxShadow, but it is tied to the New Architecture and newer platform support. Treat it as a version-gated enhancement, not a baseline assumption.
• overflow: 'hidden' on Android clips shadows completely. Avoid it on shadow containers.

Images

• Static local images: <Image source={require('./img/photo.png')} /> — dimensions are inferred automatically.
• Network images: <Image source={{ uri: '...' }} style={{ width: 200, height: 200 }} /> — you must specify dimensions manually, or the image will not render.
• Provide @2x and @3x variants for static images to target screen densities.
• Use <ImageBackground> for background images, NOT background-image CSS.
• Modern RN supports per-corner radius props on <Image>, but rounded-image behavior can still be inconsistent depending on platform, resize mode, and image type. If corners do not render correctly, wrap the image in a clipping container or use Android overlayColor when appropriate.
• resizeMode values: cover, contain, stretch, repeat, center.

Color

• Supports: hex (#fff, #ffffff), rgb(), rgba(), hsl(), hsla(), named CSS3 colors (lowercase only).
• Use PlatformColor to reference system colors (adapts to dark/light mode automatically).
• Use DynamicColorIOS to specify explicit light/dark color pairs on iOS.
• Use useColorScheme() (from react-native) as the base hook to detect the current theme ('light' | 'dark' | null). This is the entry point for any manual dark/light theming.
• Prefer token-based color systems (a colors.ts constant file, a theme context, or Tailwind semantic tokens) over hardcoded values.

Touch & Interaction

• Use <Pressable> as the default touchable primitive — it supports pressed state via render prop.
• <TouchableOpacity> is acceptable for simple opacity feedback.
• On Android, <Pressable> with android_ripple provides Material Design ripple — use it.
• The touch area never extends past the parent view bounds — use hitSlop to expand tap targets.
• Minimum tap target size: 44×44 points (Apple HIG) / 48×48dp (Material Design).

Blur & Visual Effects

• Use expo-blur (<BlurView>) for frosted-glass effects — translucent modals, floating headers, tab bars with depth.
• BlurView has a tint prop: 'light', 'dark', 'default', 'prominent' (iOS) and 'regular'/'prominent' (Android API 31+).
• On Android < API 31, BlurView renders a semi-transparent fallback — always provide a solid backgroundColor as a graceful fallback.
• Do NOT simulate blur with opacity alone — it looks flat and does not match platform conventions.

Lists

• Use <FlatList> for any list that could exceed the screen height — it virtualizes items and avoids memory issues.
• Use <ScrollView> only for short, bounded content (forms, detail screens with a fixed number of items).
• Always provide keyExtractor on <FlatList> — never rely on index as key for dynamic data.
• Provide getItemLayout if all items have a fixed height — it dramatically improves scroll performance and jump-to-index.
• Design empty states and loading skeletons as first-class UI — a blank screen or spinner-only state is an unfinished design.
• ListEmptyComponent has no parent height — flex: 1 inside it does nothing. To vertically center empty state content, use minHeight with Dimensions.get('window').height and justifyContent: 'center' instead.

Typography

• React Native does not support web fonts by default — use expo-font or @expo-google-fonts/* to load custom fonts.
• Platform defaults: iOS uses San Francisco (SF Pro), Android uses Roboto. These are acceptable for body/UI text — they are familiar to users. Override them for display/brand purposes only.
• lineHeight in RN is absolute (not a multiplier like CSS) — lineHeight: 24 means 24pt, not 1.5×.
• letterSpacing is supported but has subtle platform differences.
• Avoid fontWeight: 'bold' on custom fonts — specify the exact weight variant (fontFamily: 'Inter_700Bold').

Platform Differences

• Treat negative margin on Android as unsafe. React Native still documents it as a known platform mismatch; prefer transforms, absolute positioning, or parent layout changes instead.
• zIndex works but is less reliable on Android — prefer elevation for stacking.
• position: 'static' only available with the New Architecture.
• Safe area insets differ by device — always use <SafeAreaView> or useSafeAreaInsets() from react-native-safe-area-context.
• Keyboard behavior differs: use <KeyboardAvoidingView behavior={Platform.OS === 'ios' ? 'padding' : 'height'}>.

Visual Aesthetics Guidelines

Reference Apps by Category

Study these apps for specific design qualities. When designing for a particular domain, reference the relevant category:

Media & Entertainment (Dark-first, immersive)

• Letterboxd — deep black surfaces, careful typographic hierarchy, film-poster imagery, muted accent colors
• Spotify — layered dark grays (not pure black), dominant art color extraction, generous spacing
• Netflix — full-bleed imagery, minimal chrome, red as the only accent, auto-playing heroes
• Apple Music — blurred album backgrounds, adaptive colors, clean segmented controls

Productivity & Utility

• Things 3 — radical whitespace, ultra-clean typography, color used sparingly for status only
• Notion — generous padding, clean card system, subdued iconography, type as the hero
• Linear — dark purple-black surfaces, vibrant status colors, excellent keyboard shortcuts UX
• Todoist — clear priority system through color, satisfying completion animations

Finance & Data

• Robinhood — minimal chrome, data as the hero, strong typographic scale, green/red only for gains/loss
• Revolut — premium dark theme, card-as-hero design, smooth transitions between sections
• Coinbase — clean data visualization, restrained color, clear hierarchy in complex data

Social & Communication

• Discord — comfortable dark theme for long sessions, clear hierarchy between channels/messages/servers
• Threads — minimal, content-first, generous whitespace, typography-driven

Health & Wellness

• Headspace — warm illustrations, rounded shapes, calming palette, clear progress tracking
• Strava — activity-centric, maps as heroes, motivational use of personal data

E-commerce

• GOAT/StockX — product-as-hero, clean detail views, clear pricing hierarchy
• Airbnb — map + list integration, excellent photo galleries, clear booking flow

Dark Theme Principles

• Never use pure #000000 as a background — prefer #0D0D0D to #1C1C1E. Better yet, tint the base with your brand hue at very low saturation (e.g., for a teal accent: hsl(210, 25%, 5%) gives a blue-black with soul).
• Create depth through surface layers: background → card

…(truncated)