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 |