Kit Preamble — mobile-uiux

---

name: mobile-uiux description: Establishes a mobile design philosophy based on kickoff outputs, and generates a mobile design system/wireframes/React Native (Expo) prototype. Recommended flow: /prd → /kickoff → /mobile-uiux argument-hint: [PRD.md path (optional)] disable-model-invocation: false allowed-tools: Task, Read, Glob, Grep, Write, Edit, Bash, WebSearch

Kit Preamble — mobile-uiux

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

Project Context Detection

Run these checks silently at the start. Use results to adapt behavior:

• [ -f issues.md ] — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
• [ -f docs/sprint_state.md ] — if true and Status shows running, a sprint is active. Be aware of parallel work in worktrees.
• [ -f docs/prd_digest.md ] — if true, read it for quick project context before starting.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

Prerequisites

• /kickoff must be run first so that the following files exist:
  • docs/ux_spec.md (core input — IA, flows, screen inventory)
  • docs/requirements.md (functional/non-functional requirements)
  • docs/architecture.md (tech stack reference)
• The PRD file is supplementary reference. If kickoff outputs are missing, guide the user to run /kickoff.

Algorithm

Phase 1 — Context Gathering

1. Read kickoff outputs (required):
   • docs/ux_spec.md — extract screen inventory, IA, flows
   • docs/requirements.md — identify UI elements from functional requirements
   • docs/architecture.md — confirm tech stack, API endpoints
2. Read PRD ($ARGUMENTS or PRD.md) as supplementary context. If docs/prd_digest.md exists, read it for quick PRD summary.
3. If docs/ux_spec.md does not exist:
   • Stop and tell the user: "Kickoff outputs are missing. Please run /kickoff PRD.md first."
   • Exception: if the user explicitly wants to skip kickoff, proceed with PRD only (warn about limited context).
4. Check for existing shared assets:
   • docs/design_philosophy.md — check if already generated by web /uiux
   • docs/copy_guide.md — check if already generated by web /uiux
5. Scan the project for existing mobile code:
   • Glob for **/*.tsx, **/*.ts, app.json, app.config.js, app.config.ts
   • If found, read key files to understand current patterns, navigation structure, and tech stack.

Phase 1.5 — Design Interview (conditional)

5.5) Check if docs/design_philosophy.md already exists AND contains a "Decision Matrix" section:

• If exists with Decision Matrix: Skip interview — reuse web decisions. Present to user for confirmation.
• If not exists or missing Decision Matrix: Run the Design Interview below.

Ask the user the following questions to anchor the design direction. These answers become binding constraints for Phase 2. Present all questions at once (not one-by-one) and wait for answers. Also tell the user: "If any of these are hard to answer right now, just say 'skip'. You can also skip the entire interview."

a) Brand Personality: "If this product were a person, who would they be?" (e.g., a luxury hotel concierge, a neighborhood cafe barista, a strict operating room nurse, a playful friend)

b) Emotional Target: "What one emotion do you want users to feel when they see the first screen?" (e.g., trust, curiosity, relief, excitement, calm)

c) Anti-Reference: "What competing product or design should this absolutely NOT look like?" (a feeling you want to avoid, or a specific product name)

d) Aspiration Reference: "Is there a product or brand you'd like to reference for design? (doesn't have to be the same domain)" (e.g., Stripe's cleanliness, Nintendo's playfulness, Aesop's luxury)

5.6) Handle user response:

Case A — User answers (partially or fully): Record answers in memory — these become HARD CONSTRAINTS for Phase 2. If the user skips individual questions, note them as "unconstrained" but still avoid generic defaults.

Case B — User skips the entire interview (says "skip", "pass", etc.):

• Do NOT silently proceed with generic defaults.
• Instead, the agent MUST auto-derive initial constraints from the PRD/UX spec: a) Brand Personality → infer from target user personas and product category in PRD b) Emotional Target → infer from the product's core value proposition c) Anti-Reference → infer from competitor analysis in PRD (if any), otherwise mark "unconstrained" d) Aspiration Reference → mark "unconstrained"
• Present the auto-derived constraints to the user: "Since you skipped the interview, here's what I inferred from the PRD: [constraints]. Shall I proceed with these?"
• If approved, proceed with these as soft constraints (not hard).
• If rejected, re-offer the interview questions or accept corrections.

CHECKPOINT — MANDATORY — NEVER SKIP Verify Phase 1 outputs: docs/ux_spec.md exists, PRD was read, interview answers (or auto-derived/reused constraints) are recorded. If any required input is missing: STOP and report to user.

Phase 2 — Design Philosophy (conditional — CRITICAL before any code)

6. Check if docs/design_philosophy.md already exists:

   • If exists: Read the file, present it to the user, and ask: "A design philosophy generated for the web version exists. Should I apply it to mobile as well, or adapt it for mobile?"
     • If approved: reuse as-is, proceed to Phase 3.
     • If modification requested: create a mobile-adapted version, updating the philosophy while maintaining brand consistency.
   • If not exists: Generate from scratch (same process as web /uiux):

7. Analyze the product's identity from PRD and UX spec:

   • Who are the users? What's the emotional tone?
   • What category does this product belong to?
   • Are there competitor/reference apps mentioned? 7.5) Reference Research — image-grounded only (NO WebFetch for visual extraction).

   WebFetch returns parsed text, not pixels. Asking the model to extract hex values or spring constants from a Mobbin URL via WebFetch is fabrication. Visual references MUST arrive as actual images.

   Pick exactly ONE of three paths:

   • Path (a) — user-provided images (preferred):

     • The user supplies 1–3 mobile screenshots / hero shots (image URLs ending in .png/.jpg/.webp OR local file paths). App-store screenshots are ideal.
     • Read each image with the Read tool (image input).
     • For each image, extract concrete cues from what you actually see: dominant hex guesses (≈#…), font category (SF/Roboto/grotesque/serif/mono with weight), spacing/grid, tab bar / nav treatment, dark-mode strategy, presence of glass/blur/elevation. Spring/haptic constants cannot be extracted from a static image — leave those to the Signature Move, not the Reference Anchors.

   • Path (b) — page URLs:

     • For each reference page URL, run:

       python3 scripts/capture_reference.py <url> --viewport 390x844
       

       This headless-captures the page at a mobile viewport into docs/references/<slug>.png. If the script exits non-zero, STOP this path and switch to Path (a) or Path (c).
     • Read every captured PNG.
     • Extract cues grounded in the actual capture.

   • Path (c) — no images available:

     • Skip the Reference Anchors section entirely. Print this one-line warning to the user: Reference Anchor skipped: no image provided. Pass 1–3 mobile screenshot paths or a page URL (with Playwright/Chrome installed) to populate this section.
     • Proceed to step 8 (aesthetic direction) WITHOUT a Reference Anchors section. The Signature Move + Decision Matrix still anchor the design.

   Anti-reference: WebSearch for anti-reference titles is acceptable. Anti-cues are written from the model's own knowledge of patterns being avoided.

   Synthesis (when Path (a) or (b) ran — output goes into docs/design_philosophy.md "Reference Anchors"):

   • 2–3 strong cues to adopt, each as: cue (≤12 words) — exact value or token (e.g., OLED black #000 + #0A0A0A surface, SF Pro Display 34/40 + SF Mono 13) — source image path under docs/references/ OR user-provided image URL/path. Strong = present in the chosen images, specific enough that no Phase 5 implementer can fall back to a Material/HIG default. Fewer-and-deeper beats more-and-shallow.
   • 1 literal quote (MANDATORY when Phase 1.5 interview was NOT skipped): a specific word, number, or glyph drawn from the brand or domain that MUST appear verbatim in the rendered prototype screens. Format: literal_quote: "<exact string>" — <where it appears>. Examples:
     • literal_quote: "조용한" — set in 48pt SF Pro Display, onboarding hero
     • literal_quote: "47.2-A" — sample order ID, mono on the order detail screen
     • literal_quote: "회" — quantity unit in the picker
     • Reject abstract concepts ("luxury", "trust") — the literal quote is text/digits/glyphs the prototype renders.
   • 3–5 cues to explicitly avoid, each with one-line reason tied to the anti-reference.
   • Each adopted cue must be specific enough that a Phase 5 implementer cannot fall back to a Material/HIG default. Prose-only cues are rejected.
   • Never invent hex / font / spacing values without an image to point at. Mark uncertain extractions with ≈ and cite the source image.

   Verbatim render check — Phase 5B is required to render the literal_quote string verbatim in at least one screen file under prototype-mobile/. The Phase 2 CHECKPOINT below verifies the field is populated; Phase 5B verifies it appears in rendered output.

8. Commit to a BOLD aesthetic direction with mobile lens:

   • Apply the mobile design lens: one-handed usability, first 3-second impression, memorable gestures

9. Generate docs/design_philosophy.md:

   • Named aesthetic (2-3 words)
   • 2-3 paragraphs: how the philosophy manifests through space/form, color/material, scale/rhythm, composition
   • Signature Move (MANDATORY — the single biggest anti-slop anchor): one specific, non-default mobile visual decision with exact numeric values or token names that MUST appear on every screen of the prototype. Must be:
     • Numeric or token-named (pt / % / deg / ms / spring damping/stiffness / haptic intensity) — never prose-only.
     • Implementable as 1–3 props/styles on a reusable React Native component, OR as a Reanimated worklet of < 20 lines.
     • Visible on every screen, not just the splash or onboarding.
     • Bad (rejected — too soft): "Bold typography", "Smooth animations", "Warm palette"
     • Good mobile examples:
       • "All primary press states trigger Haptics.impactAsync(Medium) + scale(0.96) with spring damping=20 stiffness=300 — never opacity dim"
       • "Every screen entry: translateY(40 → 0) with spring damping=18 stiffness=180, staggered 60ms per child"
       • "List items use borderLeftWidth: 4 in colors.accent on the focused/active row only — no background highlight"
       • "FABs offset 16pt above the home indicator and overhang the safe area by -12pt — never centered"
       • "Bottom sheet snap points: 35% / 70% / 100% with swipeDownEnabled + Haptic.Light on snap"
   • Reference Anchors section (from step 7.5 image-grounded research): 2–3 strong adopted cues each citing an image (path under docs/references/ or a user-provided image URL/path), 1 literal_quote: field (mandatory unless Phase 1.5 was skipped), 3–5 avoided cues with reasons. If step 7.5 took Path (c) and skipped this section, omit it here too and proceed.
   • What makes this design UNFORGETTABLE (should align with and reinforce the Signature Move).

10. Present the design philosophy to the user and ask for approval before proceeding.

    • If rejected, iterate on the direction.

CHECKPOINT — MANDATORY — NEVER SKIP Verify docs/design_philosophy.md exists with: (a) a Signature Move that is numeric/token-specific (not prose-only); (b) either a populated Reference Anchors section OR an explicit "Reference Anchors skipped (no image input)" line; AND (c) when Reference Anchors is present, exactly 2–3 adopted cues (not 1, not 4+), each citing an image path, plus a literal_quote: field with a concrete word/number/glyph (NOT an adjective like "luxury"). The literal_quote may only be omitted if Phase 1.5 interview was explicitly skipped — in which case literal_quote: (skipped — interview not run) must appear instead of the field being absent. If any of (a) / (b) / (c) fails: STOP and fix before proceeding.

Phase 3 — Mobile Design System

11. Generate docs/design_system_mobile.md reflecting the chosen aesthetic:
    • Color palette: TypeScript token objects. Dominant colors with sharp accents. OLED dark mode strategy with pure black backgrounds and incremental surface elevation.
    • Typography: Platform font choices (SF Pro/Roboto or custom). Tighter modular scale (1.125 or 1.2). Dynamic Type config (allowFontScaling, maxFontSizeMultiplier).
    • Spacing: 4pt-based scale (xs:4, sm:8, md:12, lg:16, xl:24, xxl:32, xxxl:48, xxxxl:64)
    • Components: Mobile-specific — Bottom Sheet, Action Sheet, Swipe Actions, Pull-to-Refresh. States: default, pressed, disabled, loading (NO hover). Touch targets: minimum 48pt.
      • MUST include: Text Input (focus/error/placeholder/character count/keyboard type), Segment Control/Toggle (if app has mode switching), Loading indicators (skeleton, pull-to-refresh, button loading)
      • MUST include: FlatList/SectionList patterns (ItemSeparator, ListHeader, ListEmpty, key extractor)
      • MUST include: Stack header styling (back button, title alignment, header background)
    • Shadows: ios (shadowColor/Offset/Opacity/Radius) vs android (elevation) separated
    • Motion tokens: Duration (micro 80-120ms to large 400-600ms, max 700ms), spring configs (damping/stiffness/mass), easing (Reanimated), haptic mapping (expo-haptics)
      • Signature animations: MUST include full worklet code for at least one signature animation, not just prose descriptions or comment stubs
    • Loading states: Skeleton screen spec, pull-to-refresh indicator, cold start visual (splash → skeleton → content → interactive)
    • Platform tokens: ios/android keys for platform-specific values
    • All values expressed as TypeScript objects (NOT CSS custom properties)
12. Ask the user if the design system direction looks right before proceeding.

Phase 4 — Wireframes & Interaction Spec

13. Generate docs/wireframes_mobile.md:
    • Navigation architecture (Stack + Bottom Tab / Drawer hierarchy, tab bar items, stack depth)
    • Screen inventory with navigation position and type
    • Per-screen details: navigation context, safe area handling, layout zones (header/content/action), components, states (default/loading/empty/error/offline), gestures, keyboard behavior, orientation
    • Numeric layout commitments (MANDATORY): per screen, declare exact React Native StyleSheet values, not prose:
      • Flex ratios for layout zones — e.g., header flex: 0 0 56pt, content flex: 1, action flex: 0 0 88pt
      • Padding and gap as exact pt — e.g., paddingHorizontal: 20, gap: 12
      • Safe area handling — exact pt above home indicator (e.g., paddingBottom: insets.bottom + 16)
      • Tab bar height, header height, FAB offsets as numbers
      • Asymmetry deltas — e.g., hero overhangs left edge by -16pt, card bleeds into safe area by 8pt
      • Per-device-class overrides at 375 / 390 / 428 — list only the values that change
    • Reject prose-only layout phrases ("compact layout", "generous spacing"). Re-state every layout description with at least one numeric value tied to a StyleSheet property.
    • Responsive behavior per device class (375pt / 390pt / 428pt / tablet optional)
14. Generate docs/interactions_mobile.md:
    • User flows with trigger (tap/swipe/long-press/deep link/push), steps with animation + haptic, offline behavior
    • Screen transitions with navigation model, back behavior (iOS swipe vs Android system), transition map with spring configs
    • Gesture specs: swipe (direction/threshold/action/haptic), long press, pull-to-refresh, pinch, pan/drag
    • Page load choreography: cold start (splash→skeleton→content→interactive), tab switch, push, modal
    • State management: loading (skeleton/refresh/button), empty, error (network/permission), permission prompts (pre-prompt→system→denial)
    • Form behavior: KeyboardAvoidingView, keyboard dismiss, input focus flow, keyboard type per input
    • Haptic feedback map: interaction → haptic type table
    • Platform differences: iOS vs Android table (back, alerts, date picker, share, haptics)
    • Accessibility: VoiceOver/TalkBack, Dynamic Type, reduced motion

Phase 4.5 — Copy Guide (conditional)

15. Check if docs/copy_guide.md already exists:
    • If exists: Read the file. Check if it already has a ## Mobile Adaptations section.
      • If no mobile section: append a ## Mobile Adaptations section covering:
        • Shorter labels for constrained mobile UI (tab bar, buttons, headers)
        • Push notification copy templates
        • Permission request pre-prompt copy
        • Offline state messaging
        • Haptic-paired feedback copy (e.g., success messages that pair with success haptic)
      • If mobile section exists: review and update if needed.
    • If not exists: Run the copywriter agent to generate docs/copy_guide.md:
      • Input: docs/ux_spec.md, docs/design_philosophy.md, docs/wireframes_mobile.md, docs/interactions_mobile.md, PRD
      • Output: Voice & tone definition, copy inventory per screen, patterns, glossary, mobile adaptations section
      • Include FULL CONTENT of input documents in the subagent prompt.
      • This step MUST complete before Phase 5 so the prototype uses real copy.
    • Banned copy tells (enforce on every string): zero em-dashes (—/–) — use -, comma, period, or colon; no filler verbs (Elevate, Seamless, Unleash, Next-Gen, Revolutionize); no generic person names (John Doe) or startup-slop brand names (Acme, Nexus, SmartFlow); no fake-perfect numbers (99.99%, round 50%) — use organic values. See "Specific AI Tells" in Anti-AI-Slop Rules. 16-a) Accessibility labels (REQUIRED): Ensure copy_guide.md includes accessibilityLabel for EVERY interactive element (buttons, toggles, list items, navigation items, form inputs). Also include state-change announcement strings for VoiceOver/TalkBack (e.g., "Run completed", "Run unchecked"). This is mandatory per NFR accessibility requirements.

CHECKPOINT — MANDATORY — NEVER SKIP Verify docs/design_system_mobile.md, docs/wireframes_mobile.md, docs/interactions_mobile.md, and docs/copy_guide.md all exist. Cross-check: every component in wireframes has a definition in design_system_mobile.md. If any output is missing: STOP and generate it before proceeding.

Phase 5 — React Native Prototype

16. Create the prototype-mobile/ directory structure:

    prototype-mobile/
      App.tsx
      app.json
      package.json
      babel.config.js
      tsconfig.json
      .gitignore
      src/
        types/
          index.ts (shared types)
        theme/
          tokens.ts
          typography.ts
          spacing.ts
          colors.ts
        components/
          Button.tsx
          Card.tsx
          Input.tsx
          ... (as needed per design system)
        screens/
          ... (one .tsx per screen from wireframes)
        navigation/
          index.tsx
    

17. Generate prototype-mobile/package.json:
    • "main": MUST be "node_modules/expo/AppEntry.js" (NOT "App.tsx")
    • Required dependencies (MUST include all of these):
      • expo, babel-preset-expo, expo-asset — core Expo runtime
      • react, react-native — framework
      • @react-navigation/native, @react-navigation/native-stack, @react-navigation/bottom-tabs — navigation
      • react-native-reanimated, react-native-worklets — animation (worklets is required for Reanimated v4+)
      • react-native-gesture-handler, react-native-safe-area-context, react-native-screens — navigation native deps
      • expo-haptics, expo-status-bar — interaction/UI
      • expo-font (only if custom fonts are used)
    • Use the latest stable Expo SDK — do NOT pin to an older version for Expo Go compatibility
    • Use ~ ranges for Expo ecosystem packages
    • After generating package.json, run: cd prototype-mobile && npm install && npx expo install --fix to resolve exact compatible versions 17-a) Generate prototype-mobile/babel.config.js:
    • ONLY use babel-preset-expo as preset
    • Do NOT manually add react-native-reanimated/plugin — babel-preset-expo handles it automatically (SDK 54+) 17-b) Generate prototype-mobile/.gitignore:
    • Standard Expo gitignore: node_modules, .expo, dist, *.jks, *.keystore, .env 17-c) Generate prototype-mobile/tsconfig.json:
    • Extends expo/tsconfig.base
    • If using path aliases, also configure babel-plugin-module-resolver (Metro ignores tsconfig paths)
18. Generate prototype-mobile/app.json:
    • Expo config with app name, slug, orientation, userInterfaceStyle
    • Do NOT reference asset files (icon, splash.image) unless they physically exist in the project
    • plugins array: ONLY include packages that provide a config plugin (e.g., expo-font). Do NOT include expo-haptics (it has no config plugin)
19. Generate prototype-mobile/src/theme/:
    • colors.ts — color palette from design system
    • spacing.ts — spacing scale
    • typography.ts — font families, scale, Dynamic Type config
    • tokens.ts — re-exports all theme tokens + shadows, radii, motion config
20. Generate prototype-mobile/src/components/:
    • Reusable components matching the design system
    • Each component uses theme tokens, supports pressed/disabled/loading states
    • Haptic feedback integrated where specified in interaction spec
    • Signature Move encoding (MANDATORY): the Signature Move from docs/design_philosophy.md MUST be implemented as a reusable component, hook, or HOC (e.g., <PressSignature>, useEntryStagger(), withSignatureScale()). It must be referenceable from any screen — not duplicated per-screen.

20.5) PHASE 5A — Pilot screens & gate (multi-archetype, catches AI slop before full generation): - Step 1 — Archetype classification & pilot pick: - Classify every screen in docs/wireframes_mobile.md into one of these mobile archetypes: list/feed, detail/show, form/input, hub/tabs, modal-sheet, onboarding/wizard, empty/cold-start. - Pick TWO pilot screens from the two most-distinct archetypes present in the inventory (typically one consumption + one input). If only one archetype exists, fall back to a single pilot and note it. - Step 2 — Pilot-only generation: - Generate ONLY the 2 pilot .tsx files in prototype-mobile/src/screens/. - Generate a TEMPORARY minimal prototype-mobile/src/navigation/index.tsx that mounts ONLY the 2 pilots in a Stack (no full tab/drawer setup yet). - Generate prototype-mobile/App.tsx (SafeAreaProvider + NavigationContainer + theme provider) so the pilots are runnable. - Do NOT generate the remaining screens or the full navigation yet. - Step 2.5 — PILOT GATE — observe → critique → specificity → auto-correct → user HOLD Generator-as-judge fails: the same context that produced the pilot will not reliably catch its own slop. This block routes critique through a separate sub-agent context and runs up to 3 auto-correction cycles before presenting. Mobile pilots run live in Expo (no PNG capture in this skill), so the critique inputs are the pilot .tsx source + the design system. This is treated as degraded mode by default — record pilot_degraded: no_screenshot_input in the critique log so the user sees the limitation. Do NOT silently skip the critique.

  - **Step 2.5.0 — Neutral observation** (mandatory; BEFORE judgment).
    For each pilot `.tsx`, write 5 plain factual statements about what would render.
    **Banned vocabulary**: `signature move`, `aesthetic`, `archetype`, `philosophy`, `direction`, `taste`, `slop`, `generic`, `bold`, `restrained`, `premium`, brand names, the chosen aesthetic name. Use only colors, sizes, shapes, positions, counts, content categories.
    Save to `prototype-mobile/src/screens/<pilot>.observations.md`.

  - **Step 2.5.1 — Separate-context critique** (mandatory). Invoke `design-auditor` via the Task tool. **Do NOT inline-critique in the generator's context.**
    Pass:
      - the pilot `.tsx` path
      - `prototype-mobile/src/screens/<pilot>.observations.md`
      - `docs/design_philosophy.md`
      - `docs/design_system_mobile.md`
    Ask for a 6-axis 1–5 score (Philosophy / Hierarchy / Execution / Specificity / Restraint / Variety), one cited evidence per axis referencing observation indices, and a list of slop signals.
    Where ui-reviewer's scope applies (state coverage in the pilot, copy usage), invoke `ui-reviewer` separately. Disjoint scopes (ISSUE-013) — surface both outputs.
    Save the structured output to `prototype-mobile/src/screens/<pilot>.critique.md`.

  - **Step 2.5.2 — Specificity check** (mandatory). Ask design-auditor:
    *"Name 3 details visible in this pilot that ONLY make sense for THIS specific product / domain / user. Generic UI primitives don't count. Domain content does count (real entity names, the literal_quote from Reference Anchors, brand-specific shortcuts/units). Fewer than 3 → FAIL."*
    The literal_quote (from ISSUE-012) counts as exactly **1** of the 3.

  - **Step 2.5.3 — Auto-correction cycle** (hard cap N=3). If any score < 3, specificity FAIL, or slop signals fire:
    1. Identify the patch layer (philosophy / system / layout / pilot only).
    2. Apply the patch.
    3. Re-observe → re-critique → re-specificity.
    4. Increment cycle counter. Append to `prototype-mobile/src/screens/<pilot>.cycles.log`:
       `cycle N: layer=<L> change="<summary>" scores=P5 H4 E5 S3 R5 V4 specificity=PASS|FAIL`.
    5. **Hard stop at N=3.** After cycle 3, freeze and surface to the user with the full history.
    Record final scores at the top of the pilot screen file: `// pre-emit critique cycle=N: P5 H4 E5 S4 R5 V5 specificity=PASS`.

- **Step 3 — PILOT GATE — present and HOLD for user** (do not auto-proceed):
  - Tell the user how to run:
    ```bash
    cd prototype-mobile && npx expo start --ios   # or --android
    ```
  - Share `prototype-mobile/src/screens/<pilot>.critique.md` and `<pilot>.cycles.log`.
  - Ask: "Please run the pilots on simulator/emulator and confirm:
    (a) Is the **Signature Move** (`<paste exact text>`) visible and applied on both pilots?
    (b) Do both pilots feel like `<aesthetic name>` and read as the same family across the two archetypes?
    (c) Do the 3 product-specific details from the specificity check belong to *this* product?
    (d) Any slop signals — generic Material/HIG defaults, default Inter/SF feel, flat spring physics, missing haptics?"
  - WAIT for explicit approval before continuing to Phase 5B.
- **Step 4 — On rejection** (route to the correct layer):
  - Signature Move wrong/absent → revisit Phase 2 step 9.
  - Color / type / spring tokens off → revisit Phase 3 design system.
  - Layout reads as generic → revisit Phase 4 numeric layout commitments.
  - Tokens are right but pilot implementation is generic → fix the pilot `.tsx` and components only.
  - Do NOT proceed to Phase 5B with an unaddressed pilot rejection.

Phase 5B — Full Prototype (after pilot approval)

21. Generate remaining screen files in prototype-mobile/src/screens/:
    • One .tsx file per remaining screen from wireframes (the 2 pilots are already done).
    • Use the approved pilots as the visual template — match their component usage, spacing rhythm, Signature Move application, gesture/haptic patterns. Do not re-explore the aesthetic mid-prototype.
    • Uses design system components and theme tokens
    • Implements all states: default, loading (skeleton), empty, error
    • Uses actual copy from docs/copy_guide.md
    • Signature Move per-screen check: every screen must reference the Signature Move's reusable component/hook at least once.
22. Replace the temporary navigation with the full prototype-mobile/src/navigation/index.tsx:
    • React Navigation structure matching wireframe navigation architecture
    • Stack navigators nested in bottom tab navigator (or as specified)
    • Screen options: header config, tab bar config, transition animations
23. Update prototype-mobile/App.tsx if the full navigation needs additional providers or status bar config beyond what the pilot version already set up.

Phase 5.5 — Prototype Verification (REQUIRED before presenting to user)

24. Expo project setup check:
    • package.json "main" is "node_modules/expo/AppEntry.js" (NOT "App.tsx")
    • babel-preset-expo and expo-asset are in dependencies
    • react-native-worklets is in dependencies (required for Reanimated v4+)
    • babel.config.js uses ONLY babel-preset-expo preset (no manual reanimated plugin)
    • app.json does NOT reference non-existent asset files
    • app.json plugins does NOT include packages without config plugins (e.g., expo-haptics)
    • tsconfig.json exists with "extends": "expo/tsconfig.base"
    • .gitignore exists
25. Token compliance check:
    • Scan all files in src/screens/ and src/components/ for hardcoded style values
    • Every color, spacing, font size, border radius, and shadow MUST use imports from src/theme/
    • Fix any hardcoded values found before proceeding
26. Screen coverage check:
    • Count screens defined in docs/wireframes_mobile.md
    • Count .tsx files in src/screens/
    • Every wireframe screen (except explicitly P2+ deferred screens) MUST have a corresponding screen file
27. State coverage check:
    • Every screen MUST implement at least default + one additional state (loading, empty, or error as applicable)
    • Empty state MUST use copy from docs/copy_guide.md, not placeholder text
28. Animation completeness check:
    • At least ONE signature animation from docs/design_philosophy.md MUST be fully implemented with Reanimated worklet code
    • useReducedMotion() MUST be respected globally, not just in one component 28.3) Contrast sweep (CRITICAL — catches the failures that ship most):
    • For every text/icon color vs its computed background, verify WCAG ratio: body text needs ≥ 4.5:1; large text (≥24pt / ≥18pt bold), icons, and focus indicators need ≥ 3:1.
    • Fail on any of: button label ≈ button fill (the black-on-black bug — label colour within ~5% lightness of the fill); an accent-filled surface carrying text without a verified accent-ink colour; any dark surface (lightness < 50%) that did not flip its <Text> color (ink-on-ink). Most-missed: text in a card that switched backgroundColor but kept the default ink color.
    • List failing pairs as file:component, fix, and re-check before proceeding. 28.4) State & motion mechanics sweep:
    • TextInput fields satisfy the state rules from Anti-AI-Slop ("Motion & input mechanics"): constant borderWidth, input height == button height, reserved helper/error slot, multi-channel disabled.
    • Reanimated worklets animate only transform/opacity (no layout props); overshoot springs appear only on gesture-driven interactions, not incidental state changes; no element stacks multiple simultaneous effects.
    • List violations as file:line, fix, and re-sweep. 28.5) Signature Move check:
    • docs/design_philosophy.md must contain a Signature Move with numeric/token specificity (not prose-only).
    • The Signature Move must be implemented as a reusable component/hook/HOC under src/components/ or src/theme/.
    • Every .tsx file in src/screens/ (including the pilots) must reference that reusable Signature Move primitive at least once.
    • If any check fails: list violations, fix, and re-verify before proceeding. 28.6) Literal quote verbatim render check (skip if Phase 1.5 was explicitly skipped):
    • Read literal_quote: from docs/design_philosophy.md Reference Anchors.
    • Grep src/screens/*.tsx for the literal string. The string MUST appear verbatim in at least one screen file (inside a string literal, NOT inside a comment).
    • If absent: name the screens that would naturally host it (per the anchor's "where it appears" hint), inject the quote into that screen, and re-grep. Do not skip by widening the search.
    • Example: literal_quote: "47.2-A" MUST appear as the literal characters 47.2-A — not 47-2-A, not interpolated from a variable, not inside {/* */}.
29. Performance check:
    • List item components used in FlatList MUST use React.memo
    • Event handlers passed to memoized children MUST use useCallback 29.5) AI Tell sweep (CRITICAL):
    • Sweep every .tsx file in src/screens/ and src/components/ for the banned tells in "Specific AI Tells" (Anti-AI-Slop Rules): em-dash (—/–) in any string literal, generic person/brand names, fake-perfect numbers, section-number eyebrows, version labels, <View>-based fake product UI, decorative status dots, locale/time strips, scroll cues.
    • List every violation as file:line, fix it, and re-sweep. Zero tolerance on em-dash and View-based fake product UI — these must be 0 before presenting.

Phase 6 — Review & Iterate

30. Present deliverables summary to the user:
    • List all generated files with brief descriptions
    • Highlight the design philosophy and key aesthetic choices
    • Report verification results from Phase 5.5 (token compliance, screen coverage, state coverage)
    • Suggest running on simulator (NOT Expo Go — SDK version mismatch issues):

      cd prototype-mobile
      npx expo start --ios      # iOS Simulator (requires Xcode)
      npx expo start --android  # Android Emulator (requires Android Studio)
      

    • Note: dependencies are already installed during Phase 5 (npm install && npx expo install --fix)
    • Ask for feedback on any screen
31. Iterate based on user feedback:
    • Modify specific screens, adjust design system, add missing states
    • Each iteration updates both docs and prototype files consistently
    • If aesthetic direction needs major change, go back to Phase 2

Shared Registry Files

• None. This skill produces standalone deliverables — no issues.md or STATUS.md updates.
• Since /kickoff has already created issues, if additional UI/UX-related issues are needed, add them manually to issues.md or re-run /kickoff.

Error Handling

• If docs/ux_spec.md not found: stop and suggest running /kickoff first (unless user explicitly opts to skip).
• If PRD file not found: stop immediately, report missing path.
• If docs/ cannot be created: stop and report filesystem error.
• If existing mobile code uses a different framework (Flutter, SwiftUI, etc.): adapt the prototype to match that framework instead of defaulting to React Native. Note the framework in docs/design_system_mobile.md.
• If PRD is too vague for mobile UI design (no user stories, no features): ask the user targeted questions about screens and user flows before proceeding.

Rollback

• This skill is additive (writes new files/directories). No destructive rollback needed.
• Re-running /mobile-uiux overwrites all outputs — safe to retry.
• Prototype directory (prototype-mobile/) can be safely deleted if not needed.

Anti-AI-Slop Rules (CRITICAL)

These rules prevent Claude from converging on generic, forgettable mobile defaults.

Primary anchor — the Signature Move. The single most effective slop-blocker is the numeric/token-specific Signature Move defined in Phase 2 step 9 and enforced at the Phase 5A pilot gate (step 20.5) and Phase 5.5 step 28.5. Negative rules below are secondary; if the Signature Move is weak or missing, the rules below will not save the output.

NEVER:

• Uncustomized default navigation bar with system back button and plain title
• Personality-free Material Design 3 components straight from the library
• iOS patterns on Android or Android patterns on iOS without intentional design
• 16px uniform padding on all sides of every screen
• 5 identical-weight icons in a tab bar with no visual hierarchy
• Ignoring safe areas (notch, home indicator, status bar)
• Hardcoded pixel values that don't scale across device sizes
• Generic potted plant / astronaut / magnifying glass illustrations for empty states
• System default keyboard and picker styles without customization context

INSTEAD:

• Platform-appropriate custom design that respects conventions while expressing personality
• Intentional system font usage (custom weights, tracking, sizing) OR well-chosen custom fonts
• Dynamic Type support with allowFontScaling and maxFontSizeMultiplier
• Haptic feedback mapped to interaction meaning, not sprinkled randomly
• Spring animations as the default (more natural than timed easing on mobile)
• OLED-aware dark mode with true black and incremental surface elevation
• Thumb-zone-aware layout: primary actions in the bottom third
• Signature gesture or interaction that defines the app's personality

Specific AI Tells (hard bans — sweep every screen before presenting). Concrete signatures LLMs default to. Banned unless the brief explicitly calls for one.

Content & data:

• Generic person names ("John Doe", "Sarah Chan") or startup-slop brand names ("Acme", "Nexus", "SmartFlow", "Cloudly") → invent contextual, locale-appropriate, real-sounding names.
• Fake-perfect numbers (99.99%, round 50%, 1,234,567) → organic messy values (47.2%, +1 (312) 847-1928).
• Filler verbs ("Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize") → concrete verbs only.
• Em-dash (—) and en-dash-as-separator (–): zero tolerance in all visible text (titles, labels, body, empty/error copy). Use a regular hyphen -, comma, period, colon, or line break. The single most-violated tell.

Fake product UI:

• NEVER fake a product surface out of styled <View> rectangles (fake chart, fake feed, fake map) to fill a hero/onboarding slide. Use a real screenshot, generated image, real component, or skip it.
• No fake version footers / sync stamps (v0.6.2-rc.1, last sync 4s ago) as decoration.

Decorative meta:

• No section-number eyebrows (001 · Capabilities) or 01 / 4 pagination labels — name the topic in plain language.
• No version labels (V0.6, BETA, EARLY ACCESS, ALPHA) unless the brief is explicitly a launch/preview.
• No decorative status dots before every list row/tab/badge (only for real semantic state, sparingly).
• No locale/time/weather strips (Lisbon 14:23 · 18°C), no scroll cues (↓ Scroll), no mono-caps decoration strips (BRAND. MOTION. SPATIAL.).
• Ration the middle dot · to max 1 per metadata line; never as a universal separator.

Typography & interaction tells:

• No italic headings. fontStyle: 'italic' on title/display/hero-stat <Text> is a top tell. Emphasis = weight, accent colour, or a drawn underline. Italic only inside running body copy.
• No celebratory success toast/haptic for an action whose effect is already visible on screen (silent success; reserve toasts for failures and invisible effects).
• Auto-advancing carousels/banners must be pausable and never the only way to reach content.

Motion & input mechanics (React Native):

• Animate only transform / opacity in Reanimated worklets; never animate layout props (width, height, margin, padding, top, left) that trigger re-layout per frame.
• Reserve overshoot/bouncy springs for gesture-driven / physical interactions (press, drag, pull-to-refresh, sheet) — not for incidental state changes (colour, opacity, content swaps).
• No stacking multiple simultaneous effects (scale + translate + shadow + rotate) on one element.
• TextInput states: keep borderWidth constant across default/focus/error (change borderColor/background, never width — it shifts layout); input height == adjacent button height (44pt floor); reserve the helper/error slot height so an appearing error doesn't push content; disabled needs three channels — dimmed style + editable={false} + accessibilityState={{ disabled: true }} (never opacity alone).

Guidelines

• React Native (Expo) first: Prototype targets Expo managed workflow. No bare workflow or native modules unless absolutely necessary.
• No web patterns: No CSS, no <div>, no media queries. Use React Native primitives (View, Text, Pressable, FlatList, etc.).
• Accessibility first: accessibilityLabel, accessibilityRole, Dynamic Type, VoiceOver/TalkBack support.
• Mobile-first responsive: Design for 390pt standard, adapt down to 375pt and up to 428pt.
• Realistic content: Domain-appropriate placeholder text, not lorem ipsum.
• Intentional design: Every choice (font, color, spacing, haptic, spring config) must serve the design philosophy. No defaults.
• Shared assets: Reuse docs/design_philosophy.md and docs/copy_guide.md from web /uiux when they exist. Don't duplicate, extend.