User Journey Flows

Section 03

These journey flows describe what users do and see across the app surfaces. They extend the stack specification’s user flows with alternate paths, failure recovery, edge cases, roadmap candidates, and traceability back to the feature catalogue.

UI traceability convention

Canonical UI IDs will be added after Phase 5 when the UI / Hybrid inventory exists. Until then, each journey references reserved placeholders in the UI-* column. Replace the placeholders rather than changing journey IDs when the UI inventory is created.

Surface	Reserved UI ID	Notes
Animated welcome	UI-ONB-001	First-run welcome surface.
Cultural themes	UI-ONB-002	Multi-select theme picker.
Audience	UI-ONB-003	Self / child / both selector.
Accessibility quick-set	UI-ONB-004	Initial accessibility defaults.
Library home	UI-LIB-001	Home, continue, featured, new, downloaded, and checklist surfaces.
Artwork detail	UI-ART-001	Metadata, preview, action, artist credit, report.
Download state	UI-DL-001	Download progress, retry, cache status.
Canvas	UI-CAN-001	Artwork viewport, zoom, pan, fill state.
Palette	UI-PAL-001	Swatches, progress, selected colour, highlight action.
Paywall	UI-IAP-001	Pack offer, sign-in prompt, restore.
Account upgrade	UI-ID-001	Email, Apple, Google, merge confirmation.
Settings	UI-SET-001	Account, preferences, accessibility, child mode, restore, notifications.
Admin preview	UI-ADM-001	Internal-only preview and publish workflow.

Primary journeys

JRN-P01 — First-time anonymous user reaches the aha moment

Step	User does	User sees	Feature IDs	Reserved UI IDs
1	Opens the app for the first time.	Animated outcome-led welcome.	FEAT-ID-001, FEAT-ONB-001	UI-ONB-001
2	Selects one or more cultural themes.	Theme picker with culturally meaningful options.	FEAT-ONB-002	UI-ONB-002
3	Chooses audience: self, child, or both.	Audience selector and child-mode implication.	FEAT-ONB-003	UI-ONB-003
4	Confirms accessibility defaults.	Always-show-numbers on, reduce motion inherited, pattern fills optional.	FEAT-ONB-004, FEAT-ACC-001, FEAT-ACC-003	UI-ONB-004
5	Lands in the personalised library.	”Chosen for you” row and featured free starter artwork.	FEAT-ONB-005, FEAT-LIB-001, FEAT-LIB-002	UI-LIB-001
6	Starts the featured artwork.	Canvas opens with first-tap guidance.	FEAT-ONB-006, FEAT-CAN-001, FEAT-PAL-001	UI-CAN-001, UI-PAL-001
7	Selects a colour and taps matching cells.	Regions fill, palette progress updates, first satisfying fill is reached.	FEAT-CAN-003, FEAT-CAN-004, FEAT-PROG-001	UI-CAN-001, UI-PAL-001
8	Completes the starter or reaches the large-artwork milestone.	Founder’s note appears, then optional account prompt.	FEAT-ONB-007, FEAT-ONB-008, FEAT-PROG-003	UI-CAN-001, UI-ID-001

flowchart TD
    A["Open app"] --> B["Animated welcome"]
    B --> C["Choose cultural themes"]
    C --> D["Choose audience"]
    D --> E["Confirm accessibility defaults"]
    E --> F["Personalised library reveal"]
    F --> G["Open featured starter artwork"]
    G --> H["Guided first taps"]
    H --> I["First satisfying fill"]
    I --> J["Completion or 50% milestone"]
    J --> K["Founder's note"]
    K --> L["Soft account prompt"]

JRN-P02 — Returning user resumes downloaded artwork

Step	User does	User sees	Feature IDs	Reserved UI IDs
1	Opens the app.	Library home with continue row loaded from local progress.	FEAT-LIB-001, FEAT-PROG-001	UI-LIB-001
2	Selects the in-progress artwork.	Canvas opens from local cache.	FEAT-CACHE-001, FEAT-CAN-001	UI-CAN-001
3	Colours more regions.	Palette and progress update instantly.	FEAT-CAN-003, FEAT-PAL-001, FEAT-PROG-001	UI-CAN-001, UI-PAL-001
4	Comes online if previously offline.	Sync runs quietly in the background.	FEAT-PROG-002, FEAT-NET-001	UI-LIB-001

flowchart TD
    A["Open app"] --> B["Load local progress"]
    B --> C["Show Continue row"]
    C --> D["Open cached artwork"]
    D --> E["Colour offline or online"]
    E --> F["Queue local progress"]
    F --> G["Sync when online"]

JRN-P03 — Free artwork download and play

Step	User does	User sees	Feature IDs	Reserved UI IDs
1	Browses the library and opens a free artwork.	Artwork detail with free badge and download action.	FEAT-LIB-001, FEAT-ART-001	UI-LIB-001, UI-ART-001
2	Taps download.	Download progress state.	FEAT-DL-001, FEAT-DL-002	UI-DL-001
3	Waits for verification.	Download completes and action changes to play.	FEAT-DL-002, FEAT-CACHE-001	UI-DL-001, UI-ART-001
4	Taps play.	Canvas opens and remains playable offline afterwards.	FEAT-CACHE-001, FEAT-CAN-001	UI-CAN-001

JRN-P04 — Content pack purchase unlocks artwork

Step	User does	User sees	Feature IDs	Reserved UI IDs
1	Opens a locked premium artwork.	Artwork detail with premium badge and unlock action.	FEAT-ART-001, FEAT-IAP-001	UI-ART-001
2	Taps unlock.	Paywall sheet for content packs.	FEAT-IAP-002, FEAT-OBS-002	UI-IAP-001
3	Signs in if anonymous.	Account upgrade flow, then return to paywall.	FEAT-ID-002, FEAT-ID-003	UI-ID-001, UI-IAP-001
4	Starts native purchase.	Platform purchase sheet.	FEAT-IAP-003	UI-IAP-001
5	Purchase validates.	Entitlement applied; artwork download becomes available.	FEAT-IAP-003, FEAT-DL-001	UI-ART-001, UI-DL-001

flowchart TD
    A["Tap premium artwork"] --> B{"Active entitlement?"}
    B -->|Yes| C["Allow download"]
    B -->|No| D["Paywall sheet"]
    D --> E{"Anonymous?"}
    E -->|Yes| F["Account upgrade"]
    E -->|No| G["Native purchase"]
    F --> G
    G --> H["Validate receipt server-side"]
    H --> I["Persist entitlement"]
    I --> C

JRN-P05 — Content operator publishes an artwork

Step	User does	User sees	Feature IDs	Reserved UI IDs
1	Creates or receives artwork assets.	Authoring and segmentation files.	FEAT-CONT-001, FEAT-CONT-002	UI-ADM-001
2	Runs bundle generator and validator.	Errors, warnings, or valid bundle output.	FEAT-CONT-003	UI-ADM-001
3	Requests cultural review.	Review status and reviewer notes.	FEAT-CULT-001, FEAT-ADMIN-001	UI-ADM-001
4	Uploads approved bundle and metadata.	Internal preview.	FEAT-CONT-002, FEAT-ADMIN-001	UI-ADM-001
5	Publishes.	Artwork appears in the published catalogue.	FEAT-LIB-001, FEAT-ART-001	UI-LIB-001, UI-ART-001

Alternate journeys

ID	Variation	User does	User sees	Feature IDs	Reserved UI IDs
JRN-A01	User skips account prompt	Dismisses the soft account prompt after founder note.	Returns to library or canvas with local progress preserved.	FEAT-ONB-008, FEAT-PROG-001	UI-ID-001, UI-LIB-001
JRN-A02	User changes themes later	Opens settings and edits cultural themes.	Future library rows update to the new preferences.	FEAT-ONB-002, FEAT-SET-001, FEAT-LIB-002	UI-SET-001, UI-LIB-001
JRN-A03	User enables pattern fills	Turns on pattern fills in onboarding or settings.	Canvas fills include distinguishable hatching.	FEAT-ONB-004, FEAT-SET-002, FEAT-ACC-003	UI-ONB-004, UI-SET-001, UI-CAN-001
JRN-A04	User declines notifications	Declines the pre-permission screen.	No OS prompt; notifications can be enabled later from settings.	FEAT-ONB-009, FEAT-NOT-001, FEAT-SET-001	UI-ONB-001, UI-SET-001
JRN-A05	User restores instead of buying	Taps Restore Purchases from paywall or settings.	Existing entitlement is restored or a no-purchases message appears.	FEAT-IAP-004, FEAT-SET-001	UI-IAP-001, UI-SET-001
JRN-A06	User plays offline	Opens a downloaded artwork without connectivity.	Cached canvas opens; sync waits until online.	FEAT-CACHE-001, FEAT-NET-001, FEAT-PROG-002	UI-LIB-001, UI-CAN-001
JRN-A07	Reviewer requests changes	Reviewer rejects an artwork during cultural review.	Artist/operator sees notes and draft remains unpublished.	FEAT-CULT-001, FEAT-CONT-002	UI-ADM-001
JRN-A08	Existing account merge	User with anonymous progress signs into an existing account.	Progress is merged by bitset union.	FEAT-ID-002, FEAT-PROG-002	UI-ID-001

Failure journeys

ID	Failure	Trigger	Recovery path	Feature IDs	Reserved UI IDs
JRN-F01	Anonymous premium download blocked	Anonymous user requests premium artwork without entitlement.	Show sign-in-required state, then return to paywall after account upgrade.	FEAT-DL-001, FEAT-IAP-002, FEAT-ID-002	UI-ART-001, UI-IAP-001, UI-ID-001
JRN-F02	Authenticated user lacks entitlement	Signed-in user requests locked premium artwork.	Show paywall; allow purchase or restore.	FEAT-DL-001, FEAT-IAP-002, FEAT-IAP-004	UI-IAP-001
JRN-F03	Receipt validation fails	Store purchase completes locally but backend rejects or cannot validate receipt.	Keep artwork locked, show recoverable error, allow retry/restore, log `purchase_failed`.	FEAT-IAP-003, FEAT-OBS-002	UI-IAP-001
JRN-F04	Download checksum mismatch	Bundle verification fails.	Delete partial files, retry once, then show retry state and log failure.	FEAT-DL-002, FEAT-CACHE-001, FEAT-NET-001	UI-DL-001
JRN-F05	Signed URL expires mid-download	Premium download resumes after 15-minute URL expiry.	Request a fresh download URL and continue.	FEAT-DL-001, FEAT-DL-002	UI-DL-001
JRN-F06	Offline catalogue refresh fails	User opens app without connectivity.	Show cached catalogue/downloaded artwork where available; explain refresh limitation.	FEAT-LIB-001, FEAT-NET-001	UI-LIB-001
JRN-F07	Progress sync fails	Backend or network rejects sync.	Keep local progress, queue retry with backoff, emit `sync_failed`.	FEAT-PROG-002, FEAT-NET-001, FEAT-OBS-001	UI-CAN-001, UI-LIB-001
JRN-F08	Artwork version cannot map progress	New bundle changes region mapping incompatibly.	Prompt user to keep playing old version until next launch or restart on new version.	FEAT-CACHE-002, FEAT-PROG-001	UI-DL-001, UI-CAN-001
JRN-F09	Validator blocks publication	Artwork has open paths, palette issues, tiny-region errors, or missing assets.	Return actionable validator errors to content production.	FEAT-CONT-003, FEAT-CONT-002	UI-ADM-001
JRN-F10	Child-mode restricted action	Child-mode user taps purchase or external link.	Apply parental gate or redirect to safe explanation depending on platform policy.	FEAT-SET-003, FEAT-IAP-002	UI-IAP-001, UI-SET-001

flowchart TD
    A["Failure detected"] --> B{"Can recover locally?"}
    B -->|Yes| C["Preserve local progress/cache"]
    C --> D["Show retry or continue path"]
    B -->|No| E{"Requires account, entitlement, or review?"}
    E -->|Account| F["Route to account upgrade"]
    E -->|Entitlement| G["Route to paywall / restore"]
    E -->|Review| H["Return to content production"]
    D --> I["Log event or error"]
    F --> I
    G --> I
    H --> I

Edge cases

ID	Edge case	Expected behaviour	Feature IDs	Reserved UI IDs
EDGE-001	User chooses only one cultural theme.	Library still produces useful personalised rows.	FEAT-ONB-002, FEAT-LIB-002	UI-ONB-002, UI-LIB-001
EDGE-002	User selects child audience but later disables child mode.	Settings update profile and analytics policy immediately.	FEAT-ONB-003, FEAT-SET-003, FEAT-OBS-003	UI-SET-001
EDGE-003	OS has reduce motion enabled before onboarding.	Onboarding quick-set inherits reduce motion and canvas avoids non-essential animation.	FEAT-ONB-004, FEAT-ACC-003	UI-ONB-004, UI-CAN-001
EDGE-004	OS removes cached artwork under storage pressure.	Cache reconciliation removes dangling pointer and offers re-download.	FEAT-CACHE-001, FEAT-DL-002	UI-DL-001
EDGE-005	User taps a very small region.	Snap-to-nearest small region assists within the specified radius.	FEAT-CAN-003, FEAT-ACC-003	UI-CAN-001
EDGE-006	User reinstalls before account upgrade.	Anonymous progress may be lost; account prompt copy should make persistence value clear.	FEAT-ID-001, FEAT-ONB-008	UI-ID-001
EDGE-007	Family-shared entitlement exists.	Entitlement is honoured when returned by server validation.	FEAT-IAP-003, FEAT-IAP-004	UI-IAP-001
EDGE-008	Reviewer/admin opens draft artwork.	Draft is visible only to permitted roles and never to regular users.	FEAT-CULT-001, FEAT-ADMIN-001	UI-ADM-001
EDGE-009	Palette colour fails colour-vision simulation.	Validator blocks or warns before publication, depending on severity.	FEAT-CONT-003, FEAT-ACC-003	UI-ADM-001
EDGE-010	User opens invalid deep link after future deep-link support.	Route to library or artwork detail fallback without crashing.	FEAT-DEEP-001, FEAT-LIB-001	UI-LIB-001

Roadmap journey candidates

Candidate	Journey summary	Required features	Why it is not v1
Ad-supported access	User chooses a free ad-supported path for selected premium content.	FEAT-ADS-001	OD-01 recommends omission until retention data exists; child-mode privacy risk is high.
Subscription access	User subscribes for broader content access instead of buying packs.	FEAT-SUB-001	OD-02 resolved subscription out of MVP; pack conversion needs validation first.
User-generated artwork	User uploads or creates artwork and submits it for review.	FEAT-UGC-001	Moderation, rights, safety, and cultural review complexity exceed MVP scope.
Achievements	User earns badges or streaks for completion behaviour.	FEAT-ACH-001	Product tone should stay calm; MVP uses only the first-steps checklist.
Social sharing	User shares a completed artwork or profile.	FEAT-SOC-001	Public profiles and child-mode sharing require additional privacy work.
Advanced child profiles	Parent creates multiple child profiles with age-specific libraries.	FEAT-CHILD-001	MVP uses a single child-mode flag and audience setting.
Audio narration	User plays narrated cultural notes or guidance.	FEAT-AUDIO-001	Adds media pipeline and performance considerations outside the launch target.
AI artwork generation	User or operator generates artwork with AI support.	FEAT-AI-001	Cultural authenticity and rights risks need a separate policy.
Merchandise	User buys physical merchandise from completed artwork.	FEAT-MERCH-001	Commerce and fulfilment are unrelated to the initial canvas validation risk.

Journey-to-feature traceability

Journey ID	Journey	Core feature IDs
JRN-P01	First-time anonymous user reaches the aha moment	FEAT-ID-001, FEAT-ONB-001, FEAT-ONB-002, FEAT-ONB-003, FEAT-ONB-004, FEAT-ONB-005, FEAT-ONB-006, FEAT-ONB-007, FEAT-ONB-008, FEAT-CAN-001, FEAT-PAL-001, FEAT-PROG-001
JRN-P02	Returning user resumes downloaded artwork	FEAT-LIB-001, FEAT-CACHE-001, FEAT-CAN-001, FEAT-PROG-001, FEAT-PROG-002
JRN-P03	Free artwork download and play	FEAT-LIB-001, FEAT-ART-001, FEAT-DL-001, FEAT-DL-002, FEAT-CACHE-001, FEAT-CAN-001
JRN-P04	Content pack purchase unlocks artwork	FEAT-ART-001, FEAT-IAP-001, FEAT-IAP-002, FEAT-ID-002, FEAT-IAP-003, FEAT-DL-001
JRN-P05	Content operator publishes an artwork	FEAT-CONT-001, FEAT-CONT-002, FEAT-CONT-003, FEAT-CULT-001, FEAT-ADMIN-001
JRN-A01 to JRN-A08	Valid alternate paths	FEAT-ONB-008, FEAT-SET-001, FEAT-ACC-003, FEAT-NOT-001, FEAT-IAP-004, FEAT-NET-001, FEAT-CULT-001, FEAT-ID-002
JRN-F01 to JRN-F10	Failure and recovery paths	FEAT-DL-001, FEAT-IAP-002, FEAT-IAP-003, FEAT-DL-002, FEAT-NET-001, FEAT-PROG-002, FEAT-CACHE-002, FEAT-CONT-003, FEAT-SET-003