kalei/docs/product/kalei-complete-user-journey.md

Kalei — Complete User Journey Map

Version 2.0 — February 2026 Updated to include Ritual, Rehearsal, Evidence Wall, and full cross-feature integration

---

Overview

This document maps every user-facing flow in Kalei from first launch to long-term mastery. It serves as the single source of truth for what the user experiences, when, and why — covering all 7 features across the 5-tab architecture.

Navigation Architecture: Turn ◇ | Mirror ✦ | Lens ◎ | Gallery ▦ | You ●

Core Features (4 Pillars):

• The Turn (Kaleidoscope) — Perspective shifting via cognitive reframing
• The Mirror — Awareness through freeform journaling with AI fragment detection
• The Lens — Direction through goal setting, visualization, and action planning
• Gallery — Pattern collection and history

Connector Features (3 Bridges):

• The Ritual — Context-anchored daily habit sequences chaining Mirror → Turn → Lens
• The Rehearsal — Guided multi-sensory visualization (Lens sub-feature)
• The Evidence Wall — Mastery tracking mosaic (You tab sub-feature)

Intelligence Layer (Phase 2):

• The Spectrum — AI-powered self-knowledge dashboard

---

Journey Stage 1: First Launch & Onboarding

Screen 1: Splash

• Breathing logo animation (soft-elegance iris, slow rotation, core pulse)
• Background: Void (#050508) with subtle breathing aura
• Duration: 2 seconds, auto-advance

Screen 2: Welcome — "Same pieces. New angle."

• Hero kaleidoscope pattern (6-blade prismatic, screen blend mode)
• Tagline in Space Grotesk display font
• Single CTA: "See how it works" (Amethyst shimmer button)

Screen 3: The Metaphor — Fragment Introduction

• Visual: A single thought fragment (◇) appears, glowing Amber
• Copy: "Your thoughts are like pieces of glass in a kaleidoscope."
• Interaction: User taps the fragment → it pulses with detected-state animation
• Copy continues: "Sometimes you see sharp edges. Sometimes beautiful patterns."

Screen 4: The Turn Demo — Live Reframe

• Pre-populated negative thought: "I always mess everything up"
• Auto-animated Turn sequence (1.5s): collapse → multiply → crystallize → settle
• Three reframed perspectives appear as jewel-toned cards (Amethyst, Sapphire, Emerald)
• Copy: "Same pieces. New angle. That's a Turn."

Screen 5: Choose Your Style

• 4 coaching style cards with fragment icons:
  • Stoic Sage (Sapphire ◇) — "Clear-eyed perspective"
  • Compassionate Friend (Rose ◇) — "Gentle understanding"
  • Pragmatic Coach (Emerald ◇) — "Practical next steps"
  • Growth Catalyst (Amber ◇) — "Opportunity in everything"
• User selects default (can change later)

Screen 6: Notification Permission

• Copy: "When would you like a gentle nudge to check in?"
• Time picker with morning/evening presets
• Skip option available

Screen 7: Account Creation

• Email + password OR Apple/Google SSO
• Minimal fields — name optional at this stage
• Privacy assurance: "Your thoughts stay yours. Always encrypted."

Screen 8: First Real Turn

• Empty Turn input with prompt: "What's weighing on you right now?"
• User types their first real negative thought
• Full Turn animation plays
• 3 reframed perspectives appear
• User can save favorites (→ Gallery) or dismiss
• Success burst animation on save

Screen 9: Welcome Complete

• Copy: "Welcome to Kalei. Your kaleidoscope is ready."
• Mini kaleidoscope pattern generated from their first Turn (deterministic, seeded from input)
• CTA: "Start exploring" → Tab bar appears, Turn tab active

---

Journey Stage 2: Daily Core Loop

2A: The Turn (Tab 1 — Amethyst ◇)

Entry: User opens app → Turn tab is default home

Empty State:

• Breathing logo at center, subtle floating shards in background
• Rotating prompts: "What thought keeps circling?", "What would you like to see differently?", "What feels heavy right now?"
• Single large text input area

Active Flow:

1. User types or speaks a negative thought
2. Tap "Turn it" button (Amethyst shimmer)
3. Turn animation plays (1.5s kaleidoscope rotation)
4. 3 reframed perspectives appear as cards:
   • Each card has a coaching style label, the reframe text, and a fragment icon
   • Cards use jewel tone gradients matching their style
5. Below perspectives: "If-Then Micro-Action" card
   • Format: "If [situation], then I will [specific action]"
   • Emerald accent, action-oriented
6. User actions:
   • Save any perspective → goes to Gallery as a Keepsake
   • Save micro-action → goes to Lens as a suggested action
   • Share → generates Pattern Card (kaleidoscope pattern + reframe text)
   • Dismiss → confirmation, thought is discarded

Turn History:

• Scrollable list below input showing today's Turns
• Each entry: timestamp, first line of thought, fragment count badge, pattern thumbnail

Rate Limiting (Free tier):

• 3 Turns per day
• After limit: "You've used your 3 Turns today. Upgrade to Kalei Prism for unlimited Turns."
• Gentle, never punishing

2B: The Mirror (Tab 2 — Amber ✦)

Entry: Mirror tab → New session or continue existing

Empty State:

• Soft amber glow background
• Copy: "What's on your mind? Write freely — no judgment, no rules."
• Suggested prompts rotate: "How are you feeling right now?", "What happened today?", "What's been on repeat in your head?"

Active Session Flow:

1. User writes freely in chat-like interface (user messages appear as dark bubbles)
2. After each message, AI processes silently (AI thinking animation: 3 oscillating fragments)
3. AI responds with warm, reflective prompts (light bubbles with subtle amber border)
4. Simultaneously, AI detects cognitive distortions in user's text
5. Detected fragments appear as inline highlights:
   • Amber glow underline beneath the distorted phrase
   • Small ◇ icon at start of highlight
   • Highlight appears post-message (never while typing)
6. User taps a highlight → Half-sheet modal:
   • Distortion type name + icon (from icons-distortions.svg)
   • Brief explanation: "Catastrophizing: Assuming the worst possible outcome"
   • 1-2 quick reframes
   • "Take to Turn" button → opens Turn with this thought pre-filled
   • Dismiss to continue writing

Session Close:

• User taps "End Session" or navigates away
• AI generates Reflection:
  • Themes detected
  • Fragment count and types
  • One-line insight
  • Unique kaleidoscope pattern (seeded from session content)
• Reflection saved to Gallery

Nudge System:

• If user ignores 5+ highlighted fragments, ONE gentle offer:
  • "I noticed a few patterns in what you wrote. Want to look at them together?"
  • Max once per session
  • Dismissible

Rate Limiting (Free): 2 sessions per week, 3 distortion types detected (Catastrophizing, Black-and-White, Should Statements). Prism: unlimited sessions, all 10 types.

2C: The Lens (Tab 3 — Emerald ◎)

Entry: Lens tab → Goal dashboard

Dashboard View:

• Active goals displayed as cards with progress rings
• Each goal card shows: title, progress percentage, next action, streak indicator
• "Add Goal" floating action button (Emerald gradient)

Goal Creation Flow (6 Steps):

Step 1: Decide — Set a SMART Goal

• AI-guided conversation to refine a vague desire into a specific goal
• Template: "I want to [specific outcome] by [date] measured by [metric]"
• AI suggests refinements if goal is vague

Step 2: See It — The View (Vision Board)

• AI generates a visualization description based on goal
• User can add personal images or AI-generated imagery
• "The View" appears as a full-screen card they can revisit

Step 3: Believe — Capability Building

• Evidence Wall integration: surfaces past achievements relevant to this goal
• AI generates affirmations based on goal + user's history
• Daily affirmation card appears at Lens tab top

Step 4: Notice — Attention Training

• AI prompts awareness exercises: "Today, notice one moment where you [goal-related behavior]"
• Prompts delivered via notification at user-chosen time
• User logs noticed moments → feeds Evidence Wall

Step 5: Act — If-Then Micro-Actions

• AI generates situation-specific implementation intentions
• Format: "If [context], then [specific action]"
• User can mark actions complete → feeds Evidence Wall
• Action completion streak tracking

Step 6: Compound — Habit Tracking

• Visual habit tracker (fragment-shaped step indicators)
• Streak counter with flame icon
• Weekly review of consistency

The Rehearsal (Lens Sub-Feature):

• Accessed from goal detail screen → "Rehearse" button
• Timer ring appears (default: 10 minutes)
• AI generates personalized visualization script:
  • First-person perspective
  • Multi-sensory (see, hear, feel, smell)
  • Process-oriented (not just outcome)
  • Includes obstacle rehearsal ("When X happens, I will Y")
• Script plays as text cards with breathing animation pacing
• Progress ring counts down
• Completion → Success burst → logged to Evidence Wall
• Free: 1 Rehearsal per week. Prism: unlimited.

2D: Gallery (Tab 4 — Sapphire ▦)

Entry: Gallery tab → Collection view

Views:

• All Patterns (default): Reverse-chronological grid of kaleidoscope pattern thumbnails
• Keepsakes: Saved reframes, reflections, and insights
• By Feature: Filter by Turn / Mirror / Lens source
• By Distortion: Filter by cognitive distortion type

Pattern Card Detail:

• Full kaleidoscope pattern (hero variant, animated)
• Source content (the reframe or reflection that generated it)
• Date, feature source, distortion types tagged
• Share button → exports as Pattern Card image
• Delete with confirmation

Search:

• Text search across all saved content
• Filter chips: date range, feature, distortion type, favorites

2E: You (Tab 5 — Soft Light ●)

Entry: You tab → Profile dashboard

Sections:

• Profile: Name, avatar, member since
• Stats Overview: Total Turns, Mirror sessions, Goals active, Streak count
• Evidence Wall (prominent card → opens full view)
• Settings: Coaching style, notification times, theme (dark only for now), data export
• Subscription: Current plan, upgrade CTA (if free)
• Support: FAQ, contact, crisis resources

The Evidence Wall (You Sub-Feature):

• Accessed from You tab → "Your Evidence Wall" card
• Opens full-screen mosaic view

Evidence Wall States:

Empty State (0-2 items):

• Ghost tile outlines (dashed borders) showing where tiles will appear
• Central fragment icon with breathing animation
• Copy: "Start collecting evidence. Each Turn adds a tile to your wall."

Early State (3-7 items):

• Small cluster of tiles, connections forming
• Tiles are mixed shapes (diamond, hex, rectangle, pentagon, triangle)
• Each tile represents one proof point:
  • Completed action (Emerald border)
  • Saved keepsake (Sapphire border)
  • Self-correction in Mirror (Amber border)
  • Streak milestone (Amethyst border)
  • Goal completion (Emerald border, larger tile)
  • Reframe echo (Indigo border) — when user's later writing echoes a saved reframe

Mid State (8-20 items):

• Mosaic takes shape, dashed connection lines between related tiles
• Tiles glow softly when tapped → detail half-sheet

Full State (20+ items):

• Dense mosaic with visible connection web
• Zoom/pan enabled
• Most impactful tiles glow brighter

Contextual Surfacing:

• During low self-efficacy moments (detected in Mirror or Turn), the Evidence Wall surfaces 1-2 relevant tiles
• Example: User writes "I can never stick to anything" → Evidence Wall suggests: "You completed 12 actions in the last month and maintained a 7-day streak"
• Presented as a gentle card, not a correction

---

Journey Stage 3: The Ritual (Connector Feature)

The Ritual chains Mirror → Turn → Lens into a single context-anchored daily flow.

Access: Dedicated "Start Ritual" button at top of Turn tab, or via notification

Template Selection:

Morning Ritual (15-20 min):

1. Mirror check-in: "How are you waking up today?" (3 min writing)
2. Turn: AI identifies strongest fragment from Mirror → offers reframe (2 min)
3. Lens: Today's priority action from active goal (1 min review)
4. Affirmation: Daily affirmation card
5. Set intention: One sentence for the day

Evening Ritual (10-15 min):

1. Mirror reflection: "What stood out about today?" (3 min writing)
2. Turn: Process any unresolved thought from the day (2 min)
3. Lens review: Mark completed actions, log noticed moments
4. Gratitude: One thing from today (saved to Gallery)

Quick Ritual (5 min):

1. One-line check-in
2. Fastest Turn (single perspective)
3. One action reminder

Ritual Flow UI:

• Step indicators using fragment-shaped progress bar (from progress-indicators.svg)
• Each step has a timer (visible but not pressuring)
• Smooth transitions between steps (fragment scatter/converge animation)
• Completion → Success burst → streak updated

Ritual Tracking:

• Streak calendar (7-day week view, Amber jewel tone)
• Context consistency tracking (Wood et al.): same time, same place → stronger habit
• Ritual completion logged to Evidence Wall

Rate Limiting (Free): Quick Ritual only. Prism: all 3 templates.

---

Journey Stage 4: Spectrum (Phase 2 — Intelligence Layer)

Unlock: After 2 weeks of active use (minimum 5 Turns, 2 Mirror sessions)

Teaser Period:

• Notification: "Something is forming... Your Spectrum is almost ready."
• Small locked card on You tab with shimmer animation

Launch Reveal:

• Full-screen animation: fragments converge into prismatic kaleidoscope
• User's first Spectrum dashboard appears

Dashboard Components:

The River (Emotional Flow):

• Flowing prismatic gradient band showing emotional valence over time
• Data points as fragment icons at key moments
• X-axis: days/weeks, Y-axis: emotional valence
• Hover/tap any point → detail card with source Turn/Mirror session

Your Glass (Distortion Distribution):

• Radar/spider chart showing which of the 10 distortion types appear most
• Amber jewel tone data shape on hex grid
• Vertices as fragment icons
• Evolves weekly as patterns shift

Turn Impact (Before/After):

• Bar chart pairs showing emotional metrics before and after Turns
• Metrics: Distress level, Clarity, Hope
• Ruby bars (before) vs Emerald bars (after)
• Rolling 30-day average

Rhythm Detection (Your Cycles):

• Time-of-day engagement pattern
• Bubble sizes represent intensity
• Peak labels with fragment accents
• Helps user identify best times for practice

Growth Trajectory (The Long View):

• Line chart with fragment data points
• Y-axis: Resilience Score (composite of fragment density, self-correction rate, reframe adoption, distortion diversity, Turn-to-insight ratio)
• Milestone markers (10th Turn, 30-day streak, etc.)
• Monthly trend with prismatic gradient fill under curve

Cadence:

• Weekly summary: Sunday evening notification with 1 key insight
• Monthly deep dive: First of month with month-over-month comparison
• In-context nudges: Insights surface within Mirror/Turn/Lens at natural moments

Rate Limiting (Free): Simplified weekly summary (1 insight, no visuals, basic fragment counts). Prism: full dashboard, all 5 components, weekly/monthly deep dives, growth trajectory, export.

---

Journey Stage 5: Engagement Deepening & Retention

Streak System

• Daily streak counter (consecutive days with at least 1 Turn or Ritual)
• Visual: flame icon with Amber gradient, pulse animation
• Milestones: 3, 7, 14, 30, 60, 90, 180, 365 days
• Each milestone → special pattern generated, saved to Gallery
• Streak freeze: 1 free per week (Prism: 3 per week)

Push Notifications

• Daily check-in at user's chosen time
• Streak maintenance reminders (if about to break)
• Milestone celebrations
• Weekly Spectrum insights (Prism)
• Ritual reminders at consistent time/place
• Never more than 2 per day

Empty States

• Every screen has a warm, encouraging empty state
• Uses breathing logo animation or floating shard clusters
• Copy examples:
  • Turn: "What would you like to see differently today?"
  • Mirror: "Ready to write? There's no wrong way to start."
  • Lens: "What are you working toward? Let's build a path."
  • Gallery: "Your first pattern is waiting to be created."
  • Evidence Wall: "Every small step is evidence. Start collecting."

Upgrade Moments (Free → Prism)

• After hitting 3 Turn limit: "You're on a roll. Unlock unlimited Turns."
• After 2nd Mirror session: "Want to explore all 10 distortion types?"
• After first Rehearsal: "That felt good, right? Get unlimited Rehearsals."
• After Evidence Wall shows 10+ tiles: "Your evidence is growing. See the full picture with Spectrum."
• Never blocks current action — always shows after completion

---

Journey Stage 6: System States

Loading States

• Initial load: Breathing logo animation
• Feature transitions: Fragment scatter/converge
• AI processing: 3-fragment oscillation (AI thinking bubble)
• Data loading: Skeleton shimmer (text lines + card shapes)
• Long operations: Iris spinner with progress text

Error States

• Network error: "Lost connection. Your data is safe — we'll sync when you're back."
• AI error: "Our thinking engine needs a moment. Try again in a few seconds."
• Rate limit: Feature-specific messaging (see each feature above)
• Generic: Ruby-accent toast with retry option

Success States

• Turn saved: Emerald toast "Turn saved" with fragment icon
• Goal completed: Success burst animation (expanding rings + particle fragments)
• Streak milestone: Special celebration with pattern generation
• Ritual complete: Prismatic ring completion animation

Offline Mode

• Turn input cached locally, syncs when online
• Mirror sessions continue with local fragment detection (basic)
• Gallery browsable offline
• Clear indicator: "Offline — your work will sync automatically"

---

Monetization Tiers

Kalei (Free)

Feature	Limit
Turn	3 per day
Mirror	2 sessions per week, 3 distortion types
Lens	1 active goal, basic actions
Rehearsal	1 per week
Ritual	Quick template only
Evidence Wall	30-day window
Gallery	Full access
Spectrum	Simplified weekly summary (text only)

Kalei Prism ($7.99/month)

Feature	Access
Turn	Unlimited
Mirror	Unlimited sessions, all 10 distortion types, unlimited inline reframes
Lens	Unlimited goals, AI-refined actions
Rehearsal	Unlimited
Ritual	All 3 templates
Evidence Wall	Full history, no time window
Gallery	Full access + export
Spectrum	Full dashboard, all 5 components, weekly/monthly insights, growth trajectory

---

Appendix: Screen Inventory

#	Screen	Tab	Feature
1	Splash	—	System
2	Welcome	—	Onboarding
3	Fragment Intro	—	Onboarding
4	Turn Demo	—	Onboarding
5	Style Selection	—	Onboarding
6	Notification Permission	—	Onboarding
7	Account Creation	—	Onboarding
8	First Turn	—	Onboarding
9	Welcome Complete	—	Onboarding
10	Turn Home (empty)	Turn	Turn
11	Turn Input Active	Turn	Turn
12	Turn Animation	Turn	Turn
13	Turn Results	Turn	Turn
14	Turn History	Turn	Turn
15	Mirror Home (empty)	Mirror	Mirror
16	Mirror Session Active	Mirror	Mirror
17	Mirror Fragment Highlight	Mirror	Mirror
18	Mirror Fragment Detail (half-sheet)	Mirror	Mirror
19	Mirror Session Reflection	Mirror	Mirror
20	Lens Dashboard	Lens	Lens
21	Lens Goal Creation Step 1	Lens	Lens
22	Lens Goal Creation Step 2	Lens	Lens
23	Lens Goal Creation Step 3	Lens	Lens
24	Lens Goal Creation Step 4	Lens	Lens
25	Lens Goal Creation Step 5	Lens	Lens
26	Lens Goal Creation Step 6	Lens	Lens
27	Lens Goal Detail	Lens	Lens
28	Lens Daily Affirmation	Lens	Lens
29	Rehearsal Session	Lens	Rehearsal
30	Rehearsal Complete	Lens	Rehearsal
31	Gallery All Patterns	Gallery	Gallery
32	Gallery Keepsakes	Gallery	Gallery
33	Gallery Pattern Detail	Gallery	Gallery
34	Gallery Search/Filter	Gallery	Gallery
35	You Profile	You	You
36	You Stats	You	You
37	You Settings	You	Settings
38	You Subscription	You	Billing
39	Evidence Wall (empty)	You	Evidence Wall
40	Evidence Wall (early)	You	Evidence Wall
41	Evidence Wall (mid)	You	Evidence Wall
42	Evidence Wall (full)	You	Evidence Wall
43	Evidence Wall Tile Detail	You	Evidence Wall
44	Ritual Template Selection	Turn	Ritual
45	Ritual Morning Flow	Turn	Ritual
46	Ritual Evening Flow	Turn	Ritual
47	Ritual Quick Flow	Turn	Ritual
48	Ritual Complete	Turn	Ritual
49	Ritual Streak View	Turn	Ritual
50	Spectrum Dashboard	You	Spectrum
51	Spectrum The River	You	Spectrum
52	Spectrum Your Glass	You	Spectrum
53	Spectrum Turn Impact	You	Spectrum
54	Spectrum Rhythm	You	Spectrum
55	Spectrum Growth	You	Spectrum
56	Spectrum Weekly Summary	You	Spectrum
57	Spectrum Monthly Deep Dive	You	Spectrum
58	Upgrade Modal	—	Billing
59	Rate Limit Notice	—	System
60	Crisis Response	—	Safety
61	Pattern Card Share	—	Social
62	Notification Settings	You	Settings
63	Data Export	You	Settings
64	Account Deletion Confirm	You	Settings