Aller au contenu principal

Mobile App Guidelines

See docs/AGENTS.md for the main guidelines document. For global design direction, also follow docs/AGENTS_DESIGN.md and docs/AGENTS_FRONTEND.md.

CRITICAL RULE: Before implementing any mobile feature, review this file and AGENTS_DESIGN.md.

Target Repository​

  • This guide targets the React Native app located at ../aaperture-mobile (hyphen, not underscore).
  • Apply these rules in that repository's code and docs (../aaperture-mobile/docs/).

Scope​

Use this guide for:

  • Mobile app screens and flows
  • Typography, color, spacing, and logo decisions
  • Navigation behavior, touch ergonomics, and accessibility
  • Feature implementation constraints to pass to Codex

Codex Execution Contract​

When this file is provided to Codex, the agent must:

  1. Define or update mobile design tokens first.
  2. Use only semantic tokens in UI code (no one-off visual values in screens).
  3. Use shared brand components for logo/name rendering.
  4. Implement loading/empty/error/success states.
  5. Validate safe areas, touch targets, and accessibility labels.
  6. Include test/verification notes in the PR summary.

Use the actual stack from aaperture-mobile:

  • Runtime: React Native + Expo + TypeScript
  • Navigation: Expo Router (app/ routes and layouts)
  • Styling: NativeWind + shared UI primitives (Gluestack-based components)
  • Data fetching/cache: TanStack Query
  • Validation: Zod
  • Theme management: src/theme/AppThemeProvider.tsx + shared tokens

Component Parity Strategy (shadcn-like)​

Goal: keep a consistent design language and developer API between web and mobile.

  • Web keeps shadcn/ui.
  • Mobile uses React Native primitives (NativeWind + gluestack) with a shadcn-like API.
  • Do not try to share the exact same implementation files between web and mobile.

Rules:

  • Keep the same semantic component names across platforms whenever possible:
    • Button, Input, Card, Badge, Avatar, Dialog, Sheet, Toast
  • Keep token semantics aligned (primary, success, warning, danger, spacing scale, type scale).
  • Keep variant naming aligned (default, secondary, outline, ghost, destructive) when relevant.
  • If mobile platform constraints require divergence, document it in the component file header and in PR notes.
  • New UI work should prefer extending shared primitives before adding feature-local one-off components.

Mobile Folder Conventions​

Recommended structure:

aaperture-mobile/
  app/                    # expo-router routes (auth, tabs, stacks, layouts)
  src/
    api/                  # generated/openapi client and api adapters
    auth/                 # auth and token handling
    components/ui/        # gluestack/nativewind UI primitives
    features/             # feature modules
    i18n/                 # translations
    theme/                # runtime theme provider and palette switching
    ui/                   # app-level design tokens and wrappers
    utils/                # shared helpers

Rules:

  • Keep routing in app/ (do not move screen routing logic into random feature files).
  • Keep design tokens centralized in src/ui/theme.ts and theme mode logic in src/theme/AppThemeProvider.tsx.
  • Do not define raw colors or font sizes inside feature screens.
  • Keep brand assets/components centralized (single source of truth).

Design Tokens (Source of Truth)​

Create or maintain design tokens in ../aaperture-mobile/src/ui/theme.ts:

export const colors = {
  bg: "#0F1115",
  surface: "#171A21",
  surfaceAlt: "#1E232D",
  text: "#F3F5F8",
  textMuted: "#A8B0BF",
  border: "#2A3140",
  primary: "#D9A441",
  success: "#18A957",
  warning: "#E69A2E",
  danger: "#D64545",
  neutral: "#8A93A5",
} as const;

export const spacing = {
  0: 0,
  1: 4,
  2: 8,
  3: 12,
  4: 16,
  5: 20,
  6: 24,
  8: 32,
  10: 40,
  12: 48,
} as const;

export const radius = {
  sm: 8,
  md: 12,
  lg: 16,
  xl: 20,
  pill: 999,
} as const;

Rules:

  • Tokenize every new visual decision before component usage.
  • Keep semantic status colors aligned with AGENTS_DESIGN.md.
  • Avoid per-screen token forks.

Typography Rules​

Define typography in one place (../aaperture-mobile/src/ui/theme.ts) and consume via shared text primitives:

export const typeScale = {
  xs: { fontSize: 12, lineHeight: 16 },
  sm: { fontSize: 14, lineHeight: 20 },
  base: { fontSize: 16, lineHeight: 24 },
  lg: { fontSize: 18, lineHeight: 26 },
  xl: { fontSize: 22, lineHeight: 30 },
  "2xl": { fontSize: 28, lineHeight: 36 },
} as const;

Rules:

  • Keep one UI family and one optional display family.
  • No hardcoded fontSize in screen components.
  • Use semantic text variants via shared Text component (src/ui/Text.tsx or src/components/ui/text).

Logo and Brand Rules​

  • Use shared components only:
    • BrandLogo
    • BrandWordmark
    • BrandLockup
  • Never hardcode app name in screen JSX.
  • Keep logo clear space and scale consistent.
  • Navigation headers, auth screens, and drawer headers must use shared brand components.

Example:

<BrandLockup variant="wordmark" size="lg" />

Layout, Touch and Safe Areas​

  • Minimum touch target: 44x44 px.
  • Apply safe area insets on top-level screens.
  • Use spacing tokens only for paddings/margins/gaps.
  • Avoid fixed-width layout assumptions; support narrow and large phones.

Screen shell example:

import { SafeAreaView } from "react-native-safe-area-context";

export function ScreenContainer({ children }: { children: React.ReactNode }) {
  return <SafeAreaView style={{ flex: 1 }}>{children}</SafeAreaView>;
}
  • Use shallow task flows for frequent actions.
  • Keep navigation patterns consistent per feature area.
  • Back behavior must be deterministic and platform-consistent.
  • Each screen must include:
    • Loading state
    • Empty state
    • Error state
    • Success feedback state

Accessibility Baseline (Required)​

  • Support system font scaling.
  • Add accessibilityLabel to icon-only controls.
  • Keep contrast at WCAG AA minimum for text/actions.
  • Ensure focus and reading order are logical for screen readers.

Motion and Performance​

  • Motion explains transitions, never decorative overload.
  • Keep transitions short (150-250ms).
  • Respect reduced-motion preferences.
  • Use list virtualization and progressive rendering for heavy lists.

Mobile PR Checklist (Required)​

Each mobile PR must include:

  1. Tokens changed/added (src/ui/theme.ts, src/theme/AppThemeProvider.tsx, related UI primitives).
  2. Screens affected and state coverage (loading/empty/error/success).
  3. Accessibility checks performed (labels, contrast, dynamic text).
  4. Device verification:
    • One small iPhone/Android viewport
    • One larger iPhone/Android viewport
  5. Visual proof for brand/logo consistency in affected screens.

Definition of Done​

A mobile UI feature is done only if:

  1. Typography, colors, spacing, and radius use shared tokens.
  2. Logo/brand rendering uses shared brand components.
  3. All key UX states are implemented.
  4. Touch targets and safe areas are validated.
  5. Accessibility baseline is respected.
  6. Verification notes are included in the PR.