Design the RN app as a system of tokens and hierarchy — not screens with loose hex values. It should feel native on iOS and Android, with the same visual language as the product.
Native Compose/SwiftUI: better-mobile-interface. Navigation: react-native-expo-navigation. General app: react-native-development.
Expected result
- Obvious hierarchy in 3 seconds (title, supporting text, CTA).
- Light and dark with the same semantic roles .
- Consistent spacing and radii throughout the flow.
- Touch targets ≥ 44–48 dp; AA contrast.
- No “AI template UI” (generic purple, glass everywhere, too many pills).
Semantic tokens (required)
| Role | Function |
|---|---|
background |
Screen background |
surface / surfaceElevated |
Cards, sheets |
textPrimary / textSecondary / textTertiary |
Text hierarchy |
border / separator |
Dividers |
accent / onAccent |
CTA and brand |
success / warning / danger |
Feedback |
overlay |
Scrim |
- Define light/dark pairs in the same table.
- Consume via theme (
useTheme, context, NativeWind tokens or StyleSheet factory) — never#RRGGBBscattered across screens. - If the project already has a design system, it wins.
Typography and space
- Named scale:
display,title,body,label,caption. - Prefer the system font or the app’s brand font; at most two families.
- 4/8 base: margins 16–20; gaps from the scale.
allowFontScaling; layouts don’t break with large font.- Conscious truncation (
numberOfLines) in lists.
RN layout
SafeAreaProvider+ insets; respect the home indicator and notches.- Predictable Flexbox; avoid absolute for main structure.
- One primary action per screen (filled / accent button).
- Lists: title → subtitle → meta; separators with
separatortoken. - Empty / loading / error are designed states (skeleton or copy + CTA).
- Keyboard:
KeyboardAvoidingView/KeyboardStickyViewfrom the project stack.
Light and dark
Checklist:
- All roles have a light/dark pair
- StatusBar / navigation bar contrast with the background
- Images/icons legible in both modes (tint / variants)
- Borders visible in dark (not just shadow)
- Accent with contrast in both
Forbidden: dark = #000 + illegible gray; light = white + #999 in long body text.
Components
- Buttons: primary / secondary / tertiary with pressed/disabled states.
- Inputs: permanent label; error below; minimum touchable height.
- Cards: radius
md/lgfrom the system; consistent internal padding. - Tab bar / headers: use tokens, not hardcoded navigator colors.
NativeWind/Tamagui/Restyle: ok if they are already the standard — map classes/tokens to the roles above.
Motion
- 200–350 ms; Reanimated/LayoutAnimation aligned with the project.
- Respect Reduce Motion (
AccessibilityInfo/useReducedMotion). - Touch feedback (opacity/haptic) without overdoing it.
Anti-patterns
- Literal hex values in every screen
- Cloning web UI (mental divs, hover-only)
- Inconsistent density between navigation stacks
- Dark mode “later” with light-only leftovers
- Excess badges, gradients, and shadows
Completion criteria
- Touched screens use only tokens
- Light and dark reviewed side by side
- Touch targets and contrast ok
- Empty/loading/error states covered
- Consistent with navigation and app branding