Mobile UI

Mobile UI

MANDATORY FOR ALL AI AGENTS: Every visual value MUST come from a design token — never a literal in a component. Every screen MUST handle four states: loading, empty, error, content. Every interactive element MUST have an accessible label and a touch target of at least 44×44 pt. All user-facing strings MUST come from the i18n catalogue, never hardcoded. UI code lives ONLY in ui/ — see mobile-architecture.md.

Companion commands: /mobile-init-project (tokens, primitives, state components), /mobile-add-screen (screen with all four states, route, accessibility).

Framework and library choices: react-native.md. Conventions: typescript-code-style.md.

1. Styling engine and component strategy

Two decisions people conflate. Decide them separately.

Styling engine — pick one, record it as an ADR

⚠️ Unistyles and Tamagui are native modules. They do not load in Jest’s environment, so every component test must load the library’s mock in setupFiles — before any module that imports it — or every suite fails at import time. Unistyles ships react-native-unistyles/mocks. Budget this when choosing; NativeWind has no such cost.

This is a team and product decision, not a performance one — all of the above perform acceptably. Choose for how the team thinks and what the product must look like, then stop revisiting it.

Component kit — build your own primitives

A component kit and a distinctive visual identity are in tension. React Native Paper gives you Material Design; if the product must not look like Material, you fight the library on every screen and lose.

Default: own primitives on top of your tokens (§2), plus unstyled libraries for the interactions that are genuinely hard to build:

Exception: internal tools and back-office apps, where delivery speed outweighs identity — adopt React Native Paper or gluestack-ui wholesale. That is a legitimate choice and an ADR, not a default.

Never adopt two kits. Never wrap a kit in your own primitives “in case we swap it later” — the abstraction leaks and you carry both costs.

2. Design tokens

One source of truth. Components consume semantic names, never raw values.

1
export const palette = {
2
  green900: '#16241D',
3
  green100: '#DCE9D5',
4
  paper:    '#F7F9F4',
5
  red600:   '#A3312A',
6
} as const
7

8
export const lightTheme = {
9
  color: {
10
    background:      palette.paper,
11
    surface:         palette.green100,
12
    textPrimary:     palette.green900,
13
    textSecondary:   '#5C6E64',
14
    danger:          palette.red600,
15
    border:          '#C9D6C2',
16
  },
17
  space:  { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 },
18
  radius: { none: 0, sm: 4, md: 8, full: 9999 },
19
  type: {
20
    display: { size: 48, weight: '400' },
21
    body:    { size: 16, weight: '400' },
22
    caption: { size: 12, weight: '500' },
23
  },
24
} as const
25

26
export type Theme = typeof lightTheme

Two tiers. palette holds raw values; the theme maps them to roles. Components use color.danger, never palette.red600. Dark mode then means swapping one object, not auditing every file.

Rules:

• No marginTop: 17 anywhere. Spacing comes from the scale.
• No hex literal in a component.
• The scale is small on purpose. Ten spacing values means no one knows which to use.
• Adding a token is a deliberate act, not a reflex.

3. Theming and dark mode

Dark mode is not optional; the OS toggles it and users expect it to be honoured.

1
export function useTheme(): Theme {
2
  const scheme = useColorScheme()
3
  return scheme === 'dark' ? darkTheme : lightTheme
4
}

• Both themes define the same keys. A missing key in one is a runtime crash in only one mode — invisible until a user reports it.
• Dark mode is not an inversion. Pure black backgrounds with pure white text cause halation; large saturated areas that worked on light look aggressive on dark. Desaturate and reduce contrast slightly.
• Follow the system by default. A manual override is a feature, and an ADR.
• Review both modes on device before merging. They cannot be judged from code.

4. Component structure

Three tiers, aligned with the folder layout of mobile-architecture.md:

Primitives never import a domain type. Feature components never import from another feature — shared pieces move up to ui/design/.

Wrap RN’s Text and View in your own primitives from day one. Retrofitting a design system across 200 direct <Text> uses is a week of work; starting with <Text variant="body"> costs nothing.

5. The four screen states

A screen that only renders content is incomplete, not “to be finished later”. Users meet the error path on the subway, and the empty path on day one.

1
export function ExpenseListScreen() {
2
  const { data, isLoading, error, refetch } = useExpenses()
3

4
  if (isLoading)        return <ScreenSkeleton />
5
  if (error)            return <ErrorState error={error} onRetry={refetch} />
6
  if (data.length === 0) return <EmptyState onAction={goToCreate} />
7

8
  return <FlashList data={data} renderItem={renderExpense} />
9
}

Distinguish offline from server error — the user can act on one and not the other.

Error copy explains and directs; it never apologises and is never vague. “Couldn’t load expenses. Check your connection and try again.” — not “Oops! Something went wrong.”

6. Accessibility

Not a polish pass. It is a build gate, and — per mobile-testing.md §6 — it makes tests better, because getByRole only works on accessible components.

Required on every interactive element:

1
<Pressable
2
  accessibilityRole="button"
3
  accessibilityLabel={t('expense.delete.label')}
4
  accessibilityHint={t('expense.delete.hint')}
5
  accessibilityState={{ disabled: isPending }}
6
  hitSlop={8}
7
>

Test with the real tools: VoiceOver on iOS, TalkBack on Android. An audit that never ran a screen reader has not audited anything.

7. Internationalisation

Extract strings from the first screen. Retrofitting i18n is a refactor of the entire UI.

• Catalogue per locale; keys namespaced by feature: expense.list.empty.title.
• ❌ Never concatenate translated fragments — word order differs across languages. Use interpolation: t('expense.count', { count }).
• Plurals through the library’s plural rules, never count === 1 ? … : ….
• Dates, numbers and currency through Intl, respecting the device locale. Never a hand-rolled formatter.
• Design for +30% text length — German and Spanish overflow layouts that fit English.
• Test RTL early if Arabic or Hebrew are plausible. Use start/end, never left/right.

Currency display formats a domain Money (integer minor units, per mobile-architecture.md §4) — the formatter never receives a float.

8. Layout

• Flexbox. No absolute positioning except for genuine overlays.
• SafeAreaView / useSafeAreaInsets — notches, dynamic islands and gesture bars are not optional.
• KeyboardAvoidingView on every screen with a text input. Test with the keyboard open — the most commonly missed state.
• Spacing via a Stack/Spacer primitive, not stray margins. Margins belong to the parent’s layout decision, not the child’s identity.
• Test the smallest supported device and the largest. A layout that only works on the reviewer’s phone is not done.

9. Interaction

• Every touchable has a visible pressed state.
• Haptics for meaningful events (expo-haptics), never on every tap — constant vibration is noise.
• Disable a submit button while its mutation is in flight. Double-submit is the most common duplicate-record bug.
• Destructive actions confirm, and say what will be lost. Prefer undo over confirmation where feasible.
• Optimistic updates need a defined rollback and a visible failure. A silent revert makes users think the app is broken.

10. Motion

Animation earns its place by explaining a change; otherwise it delays the user.

• Reanimated (UI thread), never core Animated.
• Short: 150–300 ms for most transitions.
• Purposeful: show where something came from, or that state changed. Not decoration.
• prefers-reduced-motion is honoured. For some users motion causes nausea — this is an accessibility requirement, not a preference.
• One signature moment beats scattered effects everywhere.

11. Anti-patterns

12. Pre-merge checklist

• No literal colour, spacing or font size in any component
• Light and dark themes define identical keys, reviewed on device
• Every new screen handles all four states
• Every interactive element has a role, a label, and a ≥44 pt target
• Contrast meets AA in both themes
• Layout holds at the largest Dynamic Type size
• All strings come from the i18n catalogue; no concatenation
• Dates, numbers and currency formatted through Intl
• Reduced motion honoured
• Verified with VoiceOver and TalkBack
• Verified on the smallest and largest supported devices, keyboard open