Synced from the repo — do not edit here

Canonical source: docs/claude/app-redesign-roadmap.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

App Redesign Roadmap — basishybrid → Editorial + AI-Personalizable

Status: Plan approved 2026-07-09. Research validated same day via 5-agent parallel pass. Ready to execute pending user inputs (see bottom). Owner: Georges Target: 7-10 working days for full redesign + Android submission, then white-label kickoff.

Three phases

App redesign (Days 1-7) — end-to-end restyle + real-data wiring for every screen, on a future-proof architecture
Android submission prep + release (Days 8-9) — first-ever Android submission
White-label first flavor — Hatter Labs (Day 10+) — apply flavor + brand + submit

Research findings (2026-07-09) — 8 decisions this forces

Source: 5 parallel research passes covering (a) WWDC 2026 + iOS 27, (b) X/Twitter thought leaders on AI mobile UX, (c) AI-native app teardowns, (d) health/longevity competitors, (e) design system trends. Full source list at end of doc.

Concrete decisions the research forces:

Home = "one big thing" + Atlas card + composite score — NOT a tile wall. Oura Ring 4, Whoop 5.0 Coach, Function Health, Superpower all converged on this. Kill the grid; hero the single most-relevant thing right now.
Editorial warm-neutral palette (Everlab-style: greens/browns/warm neutrals with terracotta/ochre/cream accents) — NOT slate/blue. "Blue is now invisible" — corporate default blue is dated. Pure #000000 reads cheap; near-black #09090B warm-graphite is the 2026 baseline.
Serif display + geometric sans for data — Fraunces + Inter (warm human) or Editorial New + Söhne (design-conference tier) or GT Alpina + Söhne. Serif for headers only; workhorse sans for data-dense views. Numbers always sans.
Every AI card gets confidence + source + "why" — medical AI without these is now considered underdesigned. Function's "Clinician Notes → Summary" and Perplexity's "blue frames" (highlighting what the AI is reading) are the canonical patterns.
Voice-in / structured-out, NEVER voice-out — Rabbit R1 (9.2s spoken replies → 37-52% cognitive load over phone) and Humane Pin (voice couldn't cover 80% of tasks) failed on this. Voice is the query; the CARD is the answer.
Chat is NOT a paradigm — cards + artifacts + inline generative UI are — the 2026 consensus (UX Collective April 2026, Claude Artifacts, OpenAI Projects, Google A2UI protocol). LLM output should render as scoped surfaces (card / range slider / date picker / plan tweak), not paragraphs.
App Intents mandatory — SiriKit was deprecated at WWDC 2026 with 2-3 year sunset. Every core action (log meal, start protocol activity, check sleep, book appointment, view biomarker) needs an App Intent using the new schemas or the app is invisible to the new Siri.
AFM 3 (Foundation Models framework, on-device) for extraction chores — real cost lever. Free for App Store devs. Multimodal image input + structured Swift output + tool calling. Perfect for lab OCR, food-photo macro extraction, med-bottle recognition. Flutter needs a MethodChannel bridge (basis_apple_intelligence plugin). EU/China unavailable — fallback to cloud LanguageModel (existing Claude via basis-functions).

Design principles (baked in Day 1 — these enable 1-2 year robustness)

Three architectural primitives to build up front. Without them the redesign is short-lived; with them the app absorbs AI personalization + new clinics without rewrites.

1. Section registry as first-class primitive

Every screen composes from registered sections (id, category, data source, priority, dismiss behavior). A LayoutResolver takes (screen, WhiteLabelConfig, UserPreferences, AtlasContext) → ordered section list. No screen hardcodes its layout as a raw Column. Enables clinic reorder via config, per-user reorder via preference learning, Atlas dynamic injection, A/B testing.

2. Tokens as sole source of visual truth — 3-tier + 2-mode + brand override

Research-validated architecture (Widgetbook + Shahriar Hu + Dmytro Hanin references):

Tier 1 — Primitives (raw, no meaning): primitives.color.stone.50…900, primitives.color.terracotta.50…900, primitives.radius.xs…2xl, primitives.space.1…12, primitives.font.serif = "Fraunces", primitives.font.sans = "Inter". NEVER referenced by widgets.
Tier 2 — Semantic (role, not value): semantic.surface.canvas, semantic.surface.raised, semantic.text.default, semantic.text.muted, semantic.interactive.primary, semantic.status.success/warning/critical. Widgets read ONLY these.
Tier 3 — Component (only when component needs local override): component.button.primary.bg. Optional.
Two modes: light + dark. Never invert primitives; each mode gets its own semantic mapping.
Brand override layer (WhiteLabelConfig): clinics override a SMALL ALLOWLIST — interactive.primary, surface.brand, font.display. NOT text.default, radii, spacing, or status.critical (safety-critical).
Personalization layer (per-user AI): sits between semantic and widget. Only touches personalization.* sub-namespace (accent tint, density, motion intensity, haptic strength). Never overrides status colors or default text.

File layout:

basiscoreui/lib/src/theme/tokens/primitives.dart
basiscoreui/lib/src/theme/tokens/semantic_light.dart + semantic_dark.dart
basiscoreui/lib/src/theme/tokens/brand_overrides.dart
basiscoreui/lib/src/theme/app_theme.dart — ThemeExtension<AppTokens> binding

Delivery: author in Figma Variables (3 collections: Primitives, Semantic, Brand); export to tokens.json (W3C Design Tokens spec); generate Dart via figma_puller or Specify in CI.

3. Data sources abstracted from render

Each section declares its data dependency (sleep_summary_today, upcoming_appointment, protocol_progress). A DataResolver handles Firestore / cache / Atlas / whatever and returns normalized shape. Render stays dumb.

Backend data contracts the UI assumes are specified in companion docs:

app-redesign-data-contracts.md — workout auto-merge / auto-complete (assigned ⋈ user-logged ⋈ wearable-synced → one record) + insight-card → backend detection map (every Atlas insight → detector, signals, grounding, clinician-rule schema).

app-redesign-scores.md — Biological Age composite (Levine PhenoAge blood component + Oura-style wearable cardio-age, weighted by data availability/recency, with a completeness %). Renamed from "Ready Age".

app-redesign-onboarding-config.md — onboarding as clinic-configurable templates (enable/disable/reorder/brand per clinic; auth + consent + device-sync + permissions are locked/mandatory).

AI personalization horizon (Levels 1-5 mapped to concrete 2026 references)

Architecture must support all five from Day 1.

Level	Pattern	Canonical reference	Ship window
L1 — Learned defaults	Section reorder based on user behavior	Spotify home (podcast users → podcast shelf floats up); iOS 18 Control Center	Now (Day 1)
L2 — LLM-generated cards	Diagnostic cards ("Sleep -12pts because HRV disrupted 3-4am") with data + one action	Oura Advisor; Function Health Clinician Notes; Whoop Coach Daily Outlook	~3 months
L3 — Contextual next-action	Atlas picks THE action; persistable artifact (protocol tweak) saves into plan, not ephemeral chat	Claude Artifacts pattern applied to protocols; Cursor Mobile / Claude Cowork (client approves clinician-AI-drafted change)	~6 months
L4 — Voice-first Q&A	Voice-in, structured card out; live transcription in-place	Whoop Coach + Oura Advisor voice; Perplexity Comet (OpenAI Realtime 1.5)	~9-12 months
L5 — Proactive nudges	Pattern-detected cards ("you skip Tuesday workouts 60% → move to Wednesday?")	Samsung Health Proactive Intelligence; Oura Health Radar (background scanning)	~12-18 months

All five must fit the architecture from Day 1 without touching UI code.

Convergent patterns (bet on these — 5+ premium apps agree)

Score-first hero — every leading app: Superpower Score, Lifescore, WHOOP Recovery, Oura Readiness, Function Biological Age, Everlab bio-age.
Biological age / composite pace-of-aging as north-star metric — table stakes across Function, Superpower, Lifeforce, Everlab, Whoop, Bryan Johnson.
Personal baseline > population norm — Oura Vitals: "your resting HR trending 4bpm above YOUR rolling baseline."
Grounded conversational AI mid-page card, not floating icon — Function, Superpower, Fountain Life (Zori), Oura Advisor, Whoop Coach.
Sparkline + reference-range chip + clinician note on every biomarker card — Function's canonical pattern.
Longitudinal timeline as core mental model — Everlab's "years of data points," Oura's Timeline, Whoop journal correlations.
Wearable-agnostic sync — no premium app owns hardware anymore; sync from Oura + Whoop + Apple Health + Garmin.
Three-tab-max IA — Oura went 5→3 (Today / Vitals / My Health). Whoop, Function, Superpower converged shallow.
Bottom sheet as default surface, modal reserved for consequence — "does dismissing cost the user anything?" No → sheet.
Springs replace linear easing — iOS 26 Liquid Glass shipped real spring APIs (.bouncy(duration: 0.35), .spring(response: 0.3, dampingFraction: 0.6)).
Haptics compound with gesture — silent swipe = broken. Telegram-style haptic-per-gesture is the bar.
Layout adapts to observed behavior after ~5 sessions — Spotify home, Apple Control Center, CARROT Weather.
Progressive disclosure with "why am I seeing this" — collapsed by default, one tap to expand causation.
Live Activities across 7 surfaces — Dynamic Island + Lock Screen + StandBy + Watch Smart Stack + Mac menu bar + CarPlay (one implementation).
Confidence + source on every AI-generated card — medical AI standard 2026.

Divergent patterns (contested — choose, don't hedge)

AI-first vs. clinician-first — Superpower/Function/Fountain Life put AI at front door; Lifeforce/HLI/Wild Health keep clinicians at front door with AI backing. Both hit 4.9 stars — pick a posture. Our recommendation: hybrid — Atlas as home hero + clinician summary block always visible above Atlas. Our real clinicians are a genuine differentiator vs. Superpower's AI-only model.
Score obsession vs. behavior obsession — Bryan Johnson/Whoop/Oura reward pushing a score; Function/Everlab/Superpower reward completing protocols and re-testing. Our recommendation: behavior-obsessed (matches longevity clinic business model where the clinic wants adherence, not gamification).
Warm-editorial vs. dark-minimal vs. clinical-light — Everlab (warm-editorial) vs. Ultrahuman (dark-minimal) vs. Function (clinical-light). No consensus — strong performers commit hard. Our recommendation: warm-editorial dark (matches "Everlab-style" brief, differentiates from cold clinical competitors).
Motion + mascotry vs. still editorial calm — Ultrahuman leans confetti/pulse/mascot; Everlab is quiet. Our recommendation: quiet + restrained motion with haptic per gesture. Confetti clashes with clinical trust.
Modular add-ons vs. one integrated experience — Ultrahuman PowerPlugs marketplace vs. Function all-in-one. Our recommendation: one integrated experience (per WhiteLabelConfig section toggles, not per-user paid add-ons — those confuse the premium tier).

Failed patterns (avoid — 2026 evidence)

Failed	Root cause	Rule for our app
Chat-only as home	<8% 30-day retention (Sora); "chat is what shipped, not what worked"	Never make chat the home tab; cards + Atlas embedded in Today
Voice-only	Humane/Rabbit failed — voice can't cover 80% of tasks; users need to see lists, compare, re-read	Voice-in / structured-out. Card is always the answer surface.
Ambient always-listening	PHI consent nightmare + battery cost + user distrust (Limitless/Bee)	Don't add always-listening; wearables already deliver passive data
Standalone AI section/tab	Users don't visit it; Meta AI's `@mention`-embedded model wins with 3B users	Bake Atlas into Today/Health/Plan tabs — no dedicated AI tab
Corporate blue as primary	"Blue is now invisible" in 2026 (Recursion)	Warm-neutral palette + terracotta/ochre accent
Pure `#000000` dark	Reads cheap; contrast rings; NN/G contrast fail	`#09090B` warm-graphite baseline
Silent gesture	Reads broken to users trained on Telegram / iOS 26 haptics	Every gesture pairs with haptic (see matrix)
Long linear/cubic-bezier	Reads like 2019 web app	Springs default; cubic-bezier only for scroll-linked interpolation
Skeleton loaders that don't match final layout	2026 direction: structure-aware skeletons	Skeleton mirrors rendered layout at runtime
Hardcoded hex	Every 2026 write-up flags this	Widgets read only semantic tokens
Fully generative-at-runtime layouts	Impressive demo, but consistency + trust cost too high for health	Static layouts + AI-reordered sections (Level 1), not AI-generated components (yet)
Liquid Glass everywhere	Apple themselves toned it down in iOS 27 (failed NN/g contrast)	Sparingly — nav chrome, sheet handles, confirm cards — with user tint control
Cluely-style ambient overlay	5-10s latency = negative value; credibility scandals	Skip. Not appropriate for health anyway.

Apple 2026 platform must-haves (integrate Days 6-8)

From WWDC 2026 + iOS 27 research:

App Intents (mandatory, Day 6-7)

SiriKit deprecated 2-3 year sunset. Ship App Intents for every core action using new schemas:

LogMealIntent
LogSupplementIntent
StartProtocolActivityIntent
CheckSleepIntent
BookAppointmentIntent
ViewBiomarkerIntent
LogBiomarkerValueIntent

Also implement the View Annotations API — map visible views to entities so users can say "log this one" and Siri knows what's on screen. This makes us first-class in the new Siri chatbot.

Foundation Models (AFM 3) — cost lever (Day 6+ opportunity)

Free on-device 3B + 20B models. Multimodal image input. Structured Swift output.
Wire via a basis_apple_intelligence Flutter plugin (MethodChannel/Pigeon).
Use for: lab-report OCR, med-bottle recognition, food-photo macro extraction.
Fallback path: cloud LanguageModel (Claude via basis-functions) for Android, EU, China, or non-Apple-Intelligence devices.
Real cost saving vs. current cloud round-trip for these tasks.

Live Activities (Day 6+ opportunity)

One ActivityKit implementation renders on: portrait/landscape Dynamic Island, Lock Screen, StandBy, Apple Watch Smart Stack, Mac menu bar, CarPlay Dashboard. 4KB payload cap.

Ship as Live Activities:

Active protocol day (progress + next step)
Fasting timer / focused workout
Med countdown
Next appointment countdown (existing feature — upgrade to Live Activity)

Visual Intelligence camera parity

iOS 27 shipped system-level "point at food, get calories." Our wedge is protocol-aware macros + clinician visibility + supplement stacking, NOT the calorie count itself. Camera-first entry sheet: launch → auto-classify → confirm-card → log.

Health / HealthKit

No major new HKQuantityType in WWDC 2026 (verified).
Perimenopause + menopause tracking added — surface via Cycle Tracking integration if we support women's health.
HKUserAnnotatedMedication + HKMedicationDoseEvent (WWDC25) — wire if we track meds/peptides.
Project Mulberry (Apple's AI health coach) DELAYED past WWDC → 12-18 month window before first-party competition ships to consumers.

Liquid Glass discipline

Use sparingly (nav chrome, sheet handles, confirm cards) — NOT every surface.
Ship a user-facing tint slider matching Apple's own.
ALWAYS respect Reduce Transparency accessibility flag.
Existing warm-graphite tokens are the safer bet than glass-everywhere.

Design DNA to steal (per canonical app)

Steal from	Pattern	Apply to
Oura Ring 4	"One big thing today" hero on Today tab (changes throughout day: morning=sleep debrief, midday=protocol nudge, evening=tomorrow booking prep)	Home v2 hero card (Day 2)
Oura Advisor	AI renders app's own chart types inline in chat responses	Atlas chat surface (Day 6)
Oura Vitals	Color coding against personal baseline (not population norm) with haptic-on-graph interaction	Biomarker detail (Day 5)
Everlab	Warm-neutral palette (greens/browns/warm neutrals) + lifestyle photography blended into UI + longitudinal history as motivating narrative	Token palette (Day 1) + Home hero imagery
Function Health	Sparkline + reference-range chip + one-line clinician note on every biomarker card; "Snapshot" grouped by body system	Biomarker cards (Day 5)
Whoop 5.0 Coach	LLM narration of biometrics + Daily Outlook proactive card + on-demand clinician video (convergent with our exact model)	Atlas card + Chat action cards (Day 6)
Superpower	AI Concierge grounded in labs; wearable-agnostic sync ceiling	Atlas positioning (existing)
Linear (agent UX)	Six Saarinen principles: Disclosure, Native Integration, Immediate Feedback, Transparency, Respect Disengagement, Human Accountability. Agent Sessions expose reasoning; peer status with human actions.	Chat action cards + Atlas surfaces (Days 6-7)
Perplexity Comet	"Blue frame" transparency — highlight what the AI is currently reading	"Why am I seeing this?" affordance on every AI card
Claude Artifacts	LLM output persists as scoped surface (canvas, plan, chart), not ephemeral chat message	Atlas protocol-tweak cards saving back to plan (Day 6+)
Cursor mobile / Claude Cowork mobile	Phone as remote control for the clinician's AI — "your clinician's AI drafted a protocol update — approve/discuss/decline"	Chat inline action cards spec (Day 6)
Google A2UI protocol	Formal spec for inline generative UI (text → cards → artifacts → self-composing)	Level 2 personalization roadmap
Spotify home	Shelf reordering by observed behavior (podcast users → podcast top); time-of-day awareness	Level 1 personalization (Day 1 primitive)
Cash App / Superhuman mobile	Camera-first entry sheet; glance-based interactions	Meal / lab / med logging (Day 5-6)
Apple Fitness / Health redesign 2026	Scan-and-go dashboards (quick check-ins <1s, deep drill optional)	Home v2 architecture

Token specifications (Day 1 build target)

Color primitives (warm-neutral system)

primitives.color.stone.{50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950}
primitives.color.terracotta.{50..900}   // accent
primitives.color.ochre.{50..900}         // secondary accent
primitives.color.cream.{50..300}         // light canvas
primitives.color.coffee.{700..950}       // dark canvas anchor
primitives.color.moss.{200..700}         // success / in-range
primitives.color.amber.{300..600}        // warning
primitives.color.clay.{400..700}         // out-of-range warm-red

Semantic (dark mode target — warm-graphite base)

semantic.dark.surface.canvas     = coffee.950  (#0F0B0A warm near-black)
semantic.dark.surface.raised     = coffee.900  (#1A1410)
semantic.dark.surface.overlay    = stone.800 @ 0.8
semantic.dark.text.default       = cream.50
semantic.dark.text.muted         = stone.400
semantic.dark.text.inverse       = coffee.950
semantic.dark.interactive.primary = terracotta.500
semantic.dark.interactive.primary.on = cream.50
semantic.dark.border.subtle      = stone.800
semantic.dark.status.success     = moss.400
semantic.dark.status.warning     = amber.400
semantic.dark.status.critical    = clay.500

Motion tokens (spring-first)

Token	Value	Use
`motion.spring.snappy`	response 0.25, damping 0.8	Toggle, tab underline, chip
`motion.spring.gentle`	response 0.35, damping 0.75	Sheet present/dismiss, card expand
`motion.spring.bouncy`	response 0.4, damping 0.6	Booking-confirmed celebration
`motion.duration.instant`	100ms	Hover/focus tint
`motion.duration.fast`	180ms	Icon swap
`motion.duration.base`	240ms	Standard fade
`motion.duration.slow`	400ms	Sheet dismiss, hero transition
`motion.stagger`	40ms/child	List entrance

Haptic matrix (semantic-named, iOS + Android)

Event	iOS API	Android API	Rationale
`haptics.success` (booking confirm)	`.notificationOccurred(.success)`	`CONFIRM`	Distinct "something good happened"
`haptics.error`	`.notificationOccurred(.error)`	`REJECT`	Must feel different from success
`haptics.warning` (before "are you sure?")	`.notificationOccurred(.warning)`	`LONG_PRESS`	Between success + error
`haptics.tabSelect`	`.selectionChanged()`	`SEGMENT_TICK`	Very frequent → subtle
`haptics.buttonPress` (primary)	`.impact(.light)`	`VIRTUAL_KEY`	Keyclick — 10-20ms max
`haptics.sheetSnap` (bottom-sheet detent)	`.impact(.medium)`	`GESTURE_END`	"Clicks into place"
`haptics.deleteSwipeReveal`	`.impact(.rigid)` at snap	`GESTURE_THRESHOLD_ACTIVATE`	Commit point on progressive gesture
`haptics.pullToRefresh`	`.impact(.medium)` at threshold	`GESTURE_THRESHOLD_ACTIVATE`	Confirms release will fire
`haptics.scanDetected` (camera-first)	`.notificationOccurred(.success)`	`CONFIRM`	Same weight as booking confirm
`haptics.aiReplyReady`	`.impact(.light)`	`VIRTUAL_KEY`	Nudges glance without demanding
`haptics.aiStreaming`	Silent	Silent	Streaming = background

Also encode personalization.haptic.intensity: subtle | standard | strong for per-user tuning.

Pipeline (7-10 working days) — research-informed

Day 1 — Foundation

Build 3-tier token file (basiscoreui/lib/src/theme/tokens.dart) with warm-neutral palette
Build motion + haptic tokens with semantic names
Build primitive components: HeroCard, ScoreCard, DiagnosticCard (AI card with confidence+source), SparklineCard, MetricCard, ProgressCard, ProductCard, ActionCard, SectionHeader, ListItem, EmptyState, Skeleton (structure-aware), ErrorState
Build SectionRegistry + LayoutResolver primitives with Level-1 personalization hook
Build BottomSheetDetail + StickyBottomAction + HapticButton primitives
Run robustness test (8-question checklist below)
User input needed: brand guidance, references

Day 2 — Home v2 finish + More tab

Home v2: implement Oura's "one big thing" hero card that changes by time-of-day (morning = sleep debrief; midday = protocol nudge; evening = tomorrow booking prep)
Composite score card (biological age / "Ready Age") as secondary hero
Real appointment data + real Your Protocol section beneath
More tab as list-driven screen

Day 3 — Plan tab (Programs / Tasks / Learn)

Restyle three sub-tabs
Protocol detail with milestone timeline
User input: 1 reference for Plan aesthetic

Day 4 — Detail modals

Appointment detail modal (preserve all 1000+ LOC behavior)
Sleep/workout summary modal (preserve source switcher + zone interactions)
Habit/protocol detail
All migrate to bottom-sheet-as-default per 2026 pattern

Day 5 — Biomarkers tab (net-new + hardest)

Merged biomarkers + labs summary screen with Function-style sparkline + range chip + clinician note per card
"One big thing" biomarker hero (the marker most out-of-baseline right now)
Health Insights formula = biological age composite (validated by research — everyone has this now)
Per-analyte detail with range bar + history chart + haptic-on-graph (Oura pattern)
Upload documents flow retheme with camera-first entry sheet

Day 6 — Chat v2 finish + inline action cards + App Intents mandatory

Inline action card schema + Cloud Function handler + client widgets per card type (~8)
Every AI card ships with confidence badge + source link + "why am I seeing this" expand
Chat action cards = "approve / discuss / decline" pattern (Cursor mobile / Claude Cowork DNA)
App Intents for LogMealIntent, StartProtocolActivityIntent, CheckSleepIntent, BookAppointmentIntent, ViewBiomarkerIntent, LogBiomarkerValueIntent, LogSupplementIntent
View Annotations API for on-screen entity awareness
Persistent mic in action bar (voice-in) — never voice-out

Day 7 — Scheduling flow polish + fix 6 timezone bugs

Slot list restyle
Booking confirm restyle
Reschedule modal restyle
Build shared ClinicTimeFormatter helper (uses appointment's location.timezone via tz.TZDateTime.from)
Fix 6 buggy surfaces + backend push (functions_appointment_notifications.py:147)
Add TZ abbreviations only when device ≠ clinic TZ (option B from prior analysis)

Day 8 — Onboarding + Android + AFM 3 bridge opportunity

Morning: onboarding step config schema, redesigned step screens (2 questions → first meaningful action in 60s per 2026 pattern)
Afternoon: Android build verification, AndroidManifest audit, Play Console listing prep, Data Safety form, Health Connect decision, content rating, internal test build
Opportunity slot: begin basis_apple_intelligence Flutter plugin for AFM 3 (if time)

Day 9 — Android submit + Live Activities + polish

Submit Android internal test → closed alpha
Ship Live Activities for: active protocol day, fasting timer, next appointment countdown, med countdown (one implementation → 7 surfaces)
Batch any remaining feedback from redesign week

Day 10 — Hatter white-label kickoff

Flavor scaffolding
Hatter WhiteLabelConfig doc (uses SMALL ALLOWLIST of overridable semantic tokens)
First Hatter IPA to their App Store
Runbook doc for future flavors

Robustness test (verify before committing Day 1 code)

For the design system to survive 1-2 years:

All "yes" → foundation is solid.

Android submission specifics

Basishybrid is Flutter — it builds for Android already. Gap is submission, not code.

Prerequisites (user needs)

Google Play Console account ($25 one-time)
Upload keystore (I walk through gen)
Privacy policy URL (reuse iOS)
Screenshots + 1024×500 feature graphic
Content rating

Android-specific engineering tasks

AndroidManifest permissions audit
Health Connect integration decision — Android's HealthKit equivalent (~4-6h if we integrate; defer means Android users get Terra-only)
App Links deep-link parity with iOS
FCM push (already cross-platform)
Play Billing vs Stripe web-view decision — Google requires Play Billing for digital goods; physical/subs stay Stripe. User must confirm.
Data Safety declaration

Timeline

Day 8 pm: prep + internal build
Day 9: closed alpha submit (24-48h review)
Day 10-12: monitor + iterate
Day 14-16: production

White-label (post-redesign)

Reference: MEMORY.md project entries on Hatter, WhiteLabelConfig approach
Modifiable vs not-supported list from 2026-07-08 conversation — TODO extract to docs/claude/white-label-scope.md
Flavor approach: single codebase, per-flavor WhiteLabelConfig doc + bundle ID + icon + splash

Working rhythm

Per screen: user sends 1-3 references + verbal guidance (~5 min) → I audit via Explore (~5-10 min) → I implement + wire real data (~30-90 min) → user reviews on hot reload (~5-10 min) → 1-2 iterations
Total user time: ~3-5 hours over the week
Total edit time: ~25-35 hours over the week

Immediate to-dos (pre-Day-1 hygiene, from prior conversation)

Timezone display bugs — 6 surfaces + backend push (see Day 7)
Waitlist FCM push deep-link verify — post-IPA
Service charge naming verify — post-IPA
Upload IPA 1.7.66 to TestFlight
SH1-SH5 booking bugs

What I need from user before Day 1

Reference set — 5-10 screenshots (any app) capturing desired aesthetic. My rec (research-validated) baselines: Everlab (warm-editorial), Oura Ring 4 Today tab (one-big-thing), Function Health biomarker cards (sparkline+range+note), Linear (agent UX principles).
One-line brand guidance — e.g., "editorial warm-dark clinical, minimal chrome, big serif headers on data screens, terracotta accent"
Google Play Console account status
~~Health Insights formula~~ — resolved by research: biological age composite unless user objects
Play Billing vs Stripe decision — needed by Day 8

Send 1, 2, 3 today → Day 1 starts tomorrow.

Research sources (2026-07-09 pass)

WWDC 2026 + iOS 27

X/Twitter thought leaders + AI UX

AI-native app teardowns

Health/longevity competitors

Design system + editorial mobile

Full source lists per research pass are in the individual agent output files (session directory).

Figma to-do (screens still on the previous design — need redesign)

Added 2026-07-10 (George):

Loading / splash screen — currently previous design. Redesign in editorial language, then build into the real app.
Intro screen — currently previous design. Redesign in editorial language, then build into the real app.

Three phases​

Research findings (2026-07-09) — 8 decisions this forces​

Design principles (baked in Day 1 — these enable 1-2 year robustness)​

1. Section registry as first-class primitive​

2. Tokens as sole source of visual truth — 3-tier + 2-mode + brand override​

3. Data sources abstracted from render​

AI personalization horizon (Levels 1-5 mapped to concrete 2026 references)​

Convergent patterns (bet on these — 5+ premium apps agree)​

Divergent patterns (contested — choose, don't hedge)​

Failed patterns (avoid — 2026 evidence)​

Apple 2026 platform must-haves (integrate Days 6-8)​

App Intents (mandatory, Day 6-7)​

Foundation Models (AFM 3) — cost lever (Day 6+ opportunity)​

Live Activities (Day 6+ opportunity)​

Visual Intelligence camera parity​

Health / HealthKit​

Liquid Glass discipline​

Design DNA to steal (per canonical app)​

Token specifications (Day 1 build target)​

Color primitives (warm-neutral system)​

Semantic (dark mode target — warm-graphite base)​

Motion tokens (spring-first)​

Haptic matrix (semantic-named, iOS + Android)​

Pipeline (7-10 working days) — research-informed​

Day 1 — Foundation​

Day 2 — Home v2 finish + More tab​

Day 3 — Plan tab (Programs / Tasks / Learn)​

Day 4 — Detail modals​

Day 5 — Biomarkers tab (net-new + hardest)​

Day 6 — Chat v2 finish + inline action cards + App Intents mandatory​

Day 7 — Scheduling flow polish + fix 6 timezone bugs​

Day 8 — Onboarding + Android + AFM 3 bridge opportunity​

Day 9 — Android submit + Live Activities + polish​

Day 10 — Hatter white-label kickoff​

Robustness test (verify before committing Day 1 code)​

Android submission specifics​

Prerequisites (user needs)​

Android-specific engineering tasks​

Timeline​

White-label (post-redesign)​

Working rhythm​

Immediate to-dos (pre-Day-1 hygiene, from prior conversation)​

What I need from user before Day 1​

Research sources (2026-07-09 pass)​

WWDC 2026 + iOS 27​

X/Twitter thought leaders + AI UX​

AI-native app teardowns​

Health/longevity competitors​

Design system + editorial mobile​

Figma to-do (screens still on the previous design — need redesign)​