mobile-rn-screen

name	mobile-rn-screen
description	Polish an existing React Native screen to feel intentional, native, and human-crafted. Catches RN-specific silent failures — safe area violations, sub-minimum touch targets, keyboard occlusion, JS-thread animation jank, gesture conflicts, tab-bar content clipping, double safe-area insets, and FlatList re-render storms — alongside the platform-agnostic composition failures shared with the web skills (active-state mass mismatch, brand-color competition, monochromatic surfaces, information duplication per screen, left-anchored stacks). Use for "this screen looks off", "feels clunky on iOS", "Android version looks wrong", "jank when scrolling", "button is unreachable", or any RN-specific UX polish pass. Applies to bare React Native, Expo bare workflow, and Expo managed workflow. Pairs with mobile-emulator-start and mobile-emulator-test. For web/PWA surfaces use enhance-web-ui or enhance-web-ux instead.
license	MIT

Which enhance skill? (surface router)

Your surface	Use
Web product page / dashboard — composition, hierarchy, spacing, motion	enhance-web-ui
Web product page — UX heuristics, flows, data wiring	enhance-web-ux
Web landing / marketing / portfolio (greenfield, anti-slop)	enhance-web-landing
Web existing site upgrade (audit-first, preserve behavior)	enhance-web-redesign
Web 3D / WebGL / cinematic scroll on an existing site (audit-first)	enhance-web-web3d
React Native screen (Expo / bare)	mobile-rn-screen
Capacitor / hybrid shell (one web app shipped to iOS + Android)	enhance-capacitor-ui (axis architecture first) → then the web or rn skill
Repo README showcase	enhance-readme

You are here: mobile-rn-screen. Native iOS/Android (SwiftUI / Compose, no web layer) is out of scope for all of these — use Apple HIG / Material directly.

Enhance Screen — React Native

Turn an existing RN screen into a composed, native-feeling interface: calmer hierarchy, correct platform idioms, tight safe-area and keyboard handling, purposeful motion, and component primitives that work on both iOS and Android without forking.

Vague-but-visceral native feedback ("button is weirdly big", "text gets cut off on my phone", "scrolling feels janky", "can't tap that", "looks like a web page") almost always maps to one of the Hidden Failure Modes (N1–N15) below — start there, not at decoration.

Before taking any screenshots, follow mobile-emulator-start SKILL.md to bring up a working dev loop on the Android emulator. For iOS, trigger a CI build and install via TestFlight; the JS layer is verified on Android first (90%+ of "iOS bugs" are platform-agnostic RN/JS bugs).

---

Critical Rules

Compose before decorating. Fix hierarchy, grouping, alignment, safe-area handling, and touch targets before adding colour, motion, blur, or shadows. An overlapping status bar is worse than a dull palette.

iOS and Android are co-equal targets. Every change must be verified on both platforms. Shadow props are platform-split (iOS: shadow*; Android: elevation). Haptics are iOS-first. Ripple is Android-first. Write both.

No hex literals in screen/component code. Route all colours through the design-token system (theme.colors.*, withAlpha, named constants from @<org>/design-tokens). Hard-coded hex values bypass dark/high-contrast mode support and make tier-A → tier-B colour scaling impossible.

Touch targets: 44×44 pt (iOS HIG) / 48×48 dp (M3) minimum. A 16 dp icon inside a 40×40 dp Pressable is too small. Extend invisibly with hitSlop or a negative-margin Pressable wrapper; do not inflate the visual chrome to achieve the target.

Safe area is ScreenContainer's job — never add it twice. If ScreenContainer (or your repo's equivalent) already applies useSafeAreaInsets(), adding insets again in a child component produces a double-counted gap. ScreenBackButton uses top: 8, not top: 8 + insets.top, for exactly this reason.

Primitive-first patch. When a layout, colour, or wrap bug appears on multiple screens, fix the shared primitive — not every consumer site. A HubRowItem with wrong spacing fixed in one place heals every screen that uses it.

Never ship mock, dead, or rogue UI. Visual feedback must be backed by real data contracts, backend state, or domain helpers. Don't fake progress bars, streak counts, or status chips in the component; wire them to the real source or add the smallest schema extension needed.

Respect ReduceMotion. Every animation must check AccessibilityInfo.isReduceMotionEnabled() (or your repo's ReduceMotionContext) and fall back to an instant state change. This is non-negotiable; it is required by both Apple HIG and Android accessibility guidelines.

Use the local design system. The repo's token system and component primitives exist for a reason. Extend an existing primitive before inventing a one-off <View style={{...}}>.

---

Workflow Checklist

Copy and track:

RN ENHANCE /<ScreenName>
- [ ] 0. PLATFORM TIER: domain class → colour-tier (A vibrant / B expressive /
 C productive / D restrained) — see §1.5
- [ ] 1. RECON: screen file, component tree, navigation type, data shape, tokens,
 primitives, ScreenContainer/safe-area wrapper chain
- [ ] 2. CONTENT RANK: primary / secondary / metadata / actions / ambient
- [ ] 3. LIVE READ: screenshots at 3 device configs (small / standard / large phone)
 + tablet if relevant; inspect safe area, keyboard behaviour, landscape
- [ ] 3.5 DEVICE FORENSICS: onLayout measurements for repeated elements, conditional-
 slot zero-state, dup-datum scan per screen, accessibility large-text probe
- [ ] 4. PAIN INVENTORY: user-reported + silent issues from forensics pass
- [ ] 5. HEURISTIC MAP: each pain → NN/g # + RN-specific failure mode
- [ ] 6. PRIMITIVE MATCH: each fix → existing component / token / helper
- [ ] 7. IMPLEMENT: primitive-level fixes first, smallest per-screen diffs after
- [ ] 8. VERIFY: re-screenshot at 3 configs + keyboard up + large-text + dark/light +
 Android + iOS (TestFlight or CI screenshot)
- [ ] 9. WRITE-UP: pain → heuristic → fix → before/after

---

Step 1 — Recon: Understand the Screen Before Touching It

1a. Read the screen file

Glob: apps/mobile/src/screens/**/<ScreenName>.tsx
Read: the screen file in full

Extract:

• Navigation context: native stack / modal / bottom sheet / tab root? What presents this screen, what does it navigate to?
• Primary task: the ONE thing a user comes here to do.
• Data shape: entities displayed, all fields available (not just shown).
• ScreenContainer / SafeAreaView chain: which wrapper handles safe-area insets? Is headerShown: false? Are there nested scroll containers?

1b. Map the component tree

Build a small ASCII tree:

<ScreenContainer>
├── <BlurHeader> — title + back button
├── <EditorialScrollView> — main scrollable body
│ ├── <HubRowItem> — list rows (repeated)
│ └── <FooterBand> — stats / actions
└── <FloatingCTA> — primary action

Also note every wrapper in the layout chain from the outer safe-area provider down to the leaf Pressable. This is where double-inset bugs and gesture conflicts hide.

1c. Inventory the data shape

For every entity rendered, list ALL fields available — including unused ones. Many enhancement opportunities are "we already have this data, we just don't show it" (e.g. lastStudied, masteryPercent, streakCount).

Read: packages/api/src/<entity>/index.ts
Read: apps/mobile/src/state/<entity>.ts
Read: packages/core/src/<entity>/ helpers

1d. Inventory primitives + tokens (NON-NEGOTIABLE)

Glob: apps/mobile/src/components/ui/*.tsx
Glob: apps/mobile/src/components/layout/*.tsx
Read: packages/design-tokens/src/ — semantic colour tokens, grove tokens,
 market-card constants, shadow tokens
Read: apps/mobile/src/lib/theme.ts (or your repo's theme hook)

Write the token/primitive list down. Every fix in Step 7 must reference one of these — never invent a one-off {backgroundColor: '#2C2C2E'}.

1e. Check forbidden patterns

Grep: "DO NOT|FORBIDDEN|avoid|deprecated" in the screen file + component headers
Grep: hex literals in apps/mobile/src/ (ESLint no-restricted-syntax should catch these)

---

Step 1.5 — Domain Colour & Density Tier

Before touching any colour, name the product class. The same /8 tint that reads "premium and restrained" on a B2B dashboard reads "monochromatic and dead" on a learning app.

Tier	Examples	Surface bg tint	Accent fill	Categorical hue use
A — Vibrant / Gamified	Duolingo, language learning, fitness, casual games	/15–/25 + ring /30–/40	solid token, white-on-solid	every meaningful category has a distinct hue (correct/error/streak/xp/premium)
B — Expressive Consumer	Spotify, Notion playful, lifestyle apps	/10–/18 + ring /20–/28	semi-solid	3–5 semantic hues, decorative palette restrained
C — Productive / Pro Tools	Linear, GitHub Mobile, design tools	/6–/12 tint + ring /15	one accent + 4 semantic states	accent for primary action only
D — Restrained / Data-Dense	Finance, analytics, healthcare, admin	mostly neutral; /4–/8 on status only	one accent for CTA	colour reserved for data signal

How to detect tier:

1. Read the app's onboarding — "play, streak, level, fun, journey, master" → A/B; "workspace, dashboard, report, audit, pipeline" → C/D.
2. Look at the primary CTA: solid saturated with chunky shadow → A; solid muted → B/C; outline/ghost → D.
3. Count semantic hues in the token set. More than 5 with brand meaning (xp, streak, premium, tone-1..6, correct, error) → tier A.

Tier mismatch is the top hidden cause of "looks dull" feedback on consumer apps. A tier-A app with tier-D /8 tints will look washed-out even though every token is technically "correct".

---

Step 2 — Content Rank Before Layout

Classify every visible element:

Rank	Meaning	Default treatment in RN
Primary	What the screen is about	largest fontSize, strongest contrast, most vertical space
Secondary	Helps interpret primary	near primary, smaller, grouped
Metadata	Dates, counts, stats, status	bottom row of a card, trailing Text in a row
Actions	What user can do	stable Pressable hit area, no overlap with keyboard
Ambient	Brand, mood, decorative	background, low-opacity, non-tappable

Rules:

• If everything is primary, nothing is primary.
• Never stack metadata above the headline; pin it to the row's trailing edge or a card footer.
• If an action has numberOfLines={1} and still wraps on a small phone, abbreviate it.
• If a grid has dead space, adjust numColumns, card flex, or aspect ratio before adding more content.

---

Step 3 — Live Read: Screenshot on Real Devices

3a. Three-device-config pass

Use the mobile-emulator-start SKILL.md to bring up the Android emulator. Take screenshots at these three configs (change with adb shell wm size):

360×800 compact phone (Android S, older iPhones at ~375pt)
412×917 standard phone (Pixel 7 / iPhone 16 default) — PRIMARY test target
430×932 large phone (iPhone 16 Plus / large Android)

For tablet-relevant screens add:

768×1024 tablet portrait (iPad / Android medium tablet)

Screenshot commands:

adb shell screencap -p /sdcard/sc.png && adb pull /sdcard/sc.png ./screenshot-360.png
adb shell wm size 412x917 && adb shell screencap -p /sdcard/sc.png && adb pull /sdcard/sc.png ./screenshot-412.png
adb shell wm size 430x932 && adb shell screencap -p /sdcard/sc.png && adb pull /sdcard/sc.png ./screenshot-430.png
adb shell wm size reset

3b. What to note per screenshot

For each config, write 2–3 lines:

360×800 — "XP bar truncates label to 2 lines; bottom CTA hidden behind tab bar"
412×917 — "Layout looks clean; streak count duplicated in header AND in hero card"
430×932 — "Dead space in the 2-up grid; right card 40px wider than left"

3c. Keyboard probe

Tap the first text input on any screen that has one. Note:

• Does KeyboardAvoidingView / KeyboardAwareScrollView scroll the focused input into view?
• Does the primary CTA remain tappable above the keyboard?
• On Android: behavior='height'. On iOS: behavior='padding'.

3d. Squint test — two passes

Run both; the second is the one most enhancers skip:

Pass	Question	Failure
Hierarchy squint	"Where is my eye pulled first?"	Multiple elements equally loud — primary not chosen
Category squint	"Can I tell related items apart by colour alone, without reading?"	All tiles same neutral → must read every label (NN/g #6 violation)

---

Step 3.5 — Device Forensics (catch the silent bugs)

Screenshots show what looks wrong. Device forensics shows why. Run this before declaring the screen understood.

3.5a — Repeated-element measurement gate

For every group that should render with uniform widths/heights — grid cards, tab bar items, stat chips, row cells — measure them with onLayout:

// Drop this temporarily on any repeated component to measure it:
<View onLayout={e => console.log('MEASURE', e.nativeEvent.layout)} />

Or use a quick probe in the JS console (Metro/Hermes debugger):

// In Metro remote debugger / React DevTools
// Add onLayout logging to the repeated element, trigger a render,
// read the Metro output for { x, y, width, height } per instance.

Expected: widths within 1–2dp of each other for elements in the same row or grid. Width spread > 4dp on elements that should be equal → Yoga flex bug (see N-F1).

3.5b — Conditional-slot zero-state probe

For every optional region (media slot, illustration, aside, footerBand, secondaryCTA), test with the smallest realistic content (empty account, zero streak, no achievements). Look for:

• A minHeight floor reserving space when the slot's content is absent.
• A View that renders an empty container with visible padding.
• A card that is ≥ 120 dp tall but contains only an icon and "0".

Fix: conditionally render the wrapper ({slot && <Region>{slot}</Region>}) or collapse the floor on compact screens.

3.5c — Information-duplication scan per screen

List every datum (number, percentage, status word, streak count) visible on the screen and how many times it appears:

HomeScreen @ 412×917:
- "12 words today" ×3 (hero chip, progress bar label, footer row)
- streak "5d" ×2 (hero badge, streak section title)
- "68%" ×2 (progress bar, Today metric tile)

Anything appearing ≥2× on the same screen is a duplicate. Pick the most actionable placement; delete the others. Each delete is a hierarchy upgrade for what stays. (NN/g #8 Aesthetic & Minimalist.)

3.5d — Category-squint colour pass

For a tier-A/B product, take the standard-phone screenshot and apply a 10–15px blur. A 3-up or 4-up of category tiles should show as 3–4 distinct colour blobs. If they blur to the same neutral → token tints are the wrong tier (see H15 in this skill's Hidden Failure Modes).

3.5e — Large dynamic type probe

In the emulator: Settings → Accessibility → Font size → set to the largest option. Reload the app and screenshot. Look for:

• Text overflowing its container (fixed-height Views with Text inside).
• Row items wrapping to 2 lines when they should stay on one.
• Buttons that clip their label.

Fix: remove fixed heights on Text containers; use numberOfLines={1} + adjustsFontSizeToFit for labels that must stay on one line; maxFontSizeMultiplier={2} on critical UI labels.

---

Step 4 — Pain Inventory

Maintain a single table. Include user-reported pains AND silent ones from Step 3.5.

#	Source	Pain	Config	Notes
1	user	"Back button overlaps the header title"	390pt	double safe-area inset
2	user	"Streak number shows up twice on the home screen"	all	dup-datum — H14
3	live	Tab bar clips last row of FlatList	360px	missing contentInset
4	live	CTA wraps to 2 lines on 360px	compact	label too long — S9
5	live	All 3 tone cards blur to same neutral	412px	tier-A with tier-D tints

Do not skip silent pains. The user reports the loudest issue; the worst ones are often invisible to them.

4b — Silent-Pain Catalogue for RN (always check these)

#	Pain class	Where to look	NN/g	Symptom
S1	Safe area violation	Screenshot on notched device; check top/bottom edges	#1 Visibility	Status bar overlaps content; home indicator covers CTA
S2	Sub-minimum touch target	onLayout on Pressable; < 44×44pt (iOS) / 48×48dp (Android)	Fitts's, #4	Users mis-tap; icon buttons always affected
S3	Keyboard occlusion	Tap input, keyboard opens; is the field visible?	#1 Visibility	Active input hidden behind keyboard
S4	Tab bar content clipping	Scroll FlatList to last item	#8 Minimalist	Bottom card partially hidden behind tab bar
S5	Large text breakage	Enable Accessibility → largest font size	#4 Consistency	Labels wrap; containers clip; icons misalign
S6	Platform shadow mismatch	Compare iOS and Android screenshots	#4 Consistency	Cards flat on Android, lifted on iOS (or vice versa)
S7	Gesture conflict	Try swipe on a SwipeRow inside a ScrollView	#3 User Control	Swipe opens but also scrolls; one gesture cancels the other
S8	JS-thread jank	Trigger animation while scrolling a long list	#1 Visibility	Animation stutters; 60fps drops below 30fps
S9	Wrapping label / CTA	Screenshot at 360×800	#4 Consistency, Fitts's	Button text breaks to 2 lines at compact width
S10	Information duplication	Step 3.5c scan	#8 Minimalist	Same count/status shown 2–3× on one screen
S11	Wrapper-collapsed tiles	Step 3.5a onLayout measurements	#4 Consistency	Grid tiles uneven; some narrower than expected
S12	Dead conditional slot	Step 3.5b zero-state probe	#8 Minimalist	Reserved space for absent illustration/media
S13	Active-state mass mismatch	Compare active vs inactive tab/dock items	#4 Consistency	Active tab uses full-cell background fill — looks 1.5× heavier
S14	Brand-color competition	Count brand-tinted elements per zone	Visual hierarchy	Multiple brand-colored surfaces in one region; CTA loses scent
S15	Monochromatic surface	Step 3.5d category squint	#1 Visibility, #6 Recognition	Tier-A app with tier-D /5–/8 tints; tiles all same neutral
S16	Left-anchored stacked cards	Screenshot	#4 Consistency	Every card full-width, every label left; no horizontal balance
S17	Missing Android ripple	Tap Pressable on Android with ripple=null	#1 Visibility	No visual feedback on Android tap
S18	Double safe-area inset	Check wrapper chain for 2× useSafeAreaInsets	#4 Consistency	Extra gap at top/bottom; ScreenBackButton appears too low

---

Step 5 — Heuristic Map

For each pain, name the violated heuristic. A pain that cannot be tied to a heuristic is probably a personal taste call — defer it.

#	Pain	NN/g #	RN failure mode	Why it violates
1	Back button overlaps title	#4 Consistency	N13 (double inset)	Two inset additions produce layout inconsistency
2	Streak shown twice	#8 Minimalist	S10 (info duplication)	Redundant copies fragment attention
3	Tab bar clips FlatList	#1 Visibility	N4 (tab bar clipping)	System-status element (tab bar) hides content
4	CTA wraps at 360px	#4 Consistency, Fitts	S9 (wrapping CTA)	Hit-target shape unstable across screen widths
5	All tone cards same neutral	#1 Visibility, #6 Recognition	S15 (monochromatic)	Category signal hidden; user must read every label

---

Step 6 — Primitive Match (no inventions)

For each fix, match an existing primitive or token:

#	Fix	Primitive / token	File
1	Remove double inset	ScreenContainer already applies insets; remove the extra useSafeAreaInsets().top from the child	ScreenName.tsx
2	Delete duplicate streak display	Remove the footer strip; keep the hero badge (most actionable placement)	HomeScreen.tsx
3	Add contentInsetAdjustmentBehavior or contentInset to FlatList	FlatList prop	ScreenName.tsx
4	Abbreviate CTA label or use numberOfLines={1} + icon	existing Button primitive	ScreenName.tsx
5	Bump tile tint from /8 to /20 + ring	design-token constants from @org/design-tokens	tile component

If a fix would add a new primitive, stop and ask: "could this be a variant on an existing component?" Almost always: yes.

6b — Primitive-First Patch Decision

Same rule as enhance-web-ui — fix the wrapper, not the consumer:

Does the bug appear on more than one screen?
├── Yes → Walk UP the component tree. Find the first shared component
│ that hosts the bug. If ≥ 3 screens use it → fix at the primitive.
└── No → Fix at the consumer. Document: "if a 2nd screen reuses this
 pattern, move the fix to the primitive."

Concrete RN cues that the primitive is broken:

• FlatList on 3 screens all missing contentInset → add it to a shared ScreenList wrapper.
• Every Pressable in the codebase has hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }} copy-pasted → make it the default in a TouchablePrimitive wrapper.
• Every screen's Text for metadata has fontSize: 12, color: theme.colors.secondary inline → create a MetaText primitive.

---

Further reading

• Step 7 — Enhancement Plan and more