kalei/docs/product/kalei-complete-design.md

1406 lines
73 KiB
Markdown
Raw Normal View History

# Kalei — Product & Experience Design
### *A kaleidoscope for your mind. Same pieces. New angle.*
---
## The Metaphor
A kaleidoscope takes broken, random fragments of glass and reveals them as beautiful, symmetrical patterns. It never changes the pieces — it changes the **angle**. Turn it once, and chaos becomes art. Turn it again, and the same fragments form something entirely new.
Kalei does the same thing with your thoughts.
Your situation hasn't changed. Your circumstances are the same fragments they were a moment ago. But Kalei shifts the angle — and suddenly you see the pattern, the meaning, the opportunity that was always there.
This isn't toxic positivity. A kaleidoscope doesn't pretend the glass isn't broken. It proves that broken things can still be beautiful.
---
## The Core System
Kalei is built on four optical instruments plus three science-driven engagement features. The optical instruments are the primary experience. The engagement features weave them into a cohesive daily practice.
### The Four Pillars
| Pillar | Feature | Optical Element | User Need | Phase |
|--------|---------|----------------|-----------|-------|
| **Awareness** | The Mirror | Mirror | "I need to process" | Phase 1 |
| **Perspective** | The Kaleidoscope | Kaleidoscope | "I need to see this differently" | Phase 1 |
| **Direction** | The Lens | Lens | "I need to move forward" | Phase 1 |
| **Intelligence** | The Spectrum | Prism | "I need to understand myself" | Phase 2 |
### The Three Connectors
| Feature | Science Pillar | User Need | Phase |
|---------|---------------|-----------|-------|
| **The Rehearsal** | Visualization & Mental Imagery (Schuster, Liu, Seok) | "I need to prepare" | Phase 1 (Lens sub-feature) |
| **The Ritual** | Habit Formation (Wood & Neal) | "I need consistency" | Phase 1 |
| **The Evidence Wall** | Self-Efficacy: Mastery Experiences (Bandura) | "I need proof I can do this" | Phase 1 (You tab) |
### How They Flow Together
```
THE MIRROR THE KALEIDOSCOPE THE LENS THE SPECTRUM
(Awareness) → (Perspective) → (Direction) → (Intelligence)
"What am I "How else can I "What am I "What patterns
feeling?" see this?" building toward?" define me?"
Freeform Structured Goal-focused AI-powered
writing reframing manifestation self-knowledge
Fragments Fragments → Patterns Patterns → Focus All data → Insight
detected revealed applied understood
↕ ↕
THE RITUAL THE REHEARSAL
(Daily Flow) (Mental Preparation)
Sequences all Visualizes the
features into process of getting
one habit there
THE EVIDENCE WALL
(Proof of Capability)
Collects mastery evidence
from all features
```
Not every session follows this sequence. Some days you just need a quick Turn. Some days you just need to write in the Mirror. Some days you go straight to the Lens. But the **Ritual** makes the daily practice automatic, the **Rehearsal** makes the goals vivid, and the **Evidence Wall** makes the progress undeniable.
---
## Brand Language
### Vocabulary
Every app builds an unconscious vocabulary through the words it uses in buttons, headers, notifications, and empty states. Kalei's vocabulary reinforces the metaphor without being heavy-handed.
**Primary Terms (Use Frequently)**
| Instead of... | Kalei says... | Why |
|----------------------|----------------------|--------------------------------------------------------|
| Reframe | **Turn** | You "turn" a kaleidoscope to see a new pattern |
| Negative thought | **Fragment** | Broken glass — raw material, not a flaw |
| Reframed perspective | **Pattern** | The beautiful arrangement revealed by a new angle |
| Journal entry | **Reflection** | Light + mirrors = what a kaleidoscope runs on |
| Daily session | **Turn of the day** | Each day you take a fresh turn |
| Progress/history | **Gallery** | A collection of the patterns you've created |
| Insight | **Facet** | One face of a multifaceted view |
| Saved reframe | **Keepsake** | A pattern worth holding onto |
**Secondary Terms (Use Sparingly for Flavor)**
- **Shift** — a small adjustment in perspective
- **Prism** — the tool that splits one beam into many colors
- **Mosaic** — the bigger picture built from many small pieces
- **Spectrum** — the full range of ways to see something
- **Illuminate** — to light up what was hidden
- **Refract** — to bend light in a new direction
**Words to Avoid**
- "Fix" — implies the user is broken
- "Heal" — too clinical, positions app as therapy
- "Transform" — too dramatic, overpromises
- "Positive vibes" — trivializes the process
- "Journey" — overused in wellness apps
- "Self-care" — generic, says nothing
### Voice & Tone
**Kalei speaks like:** A wise friend who sees beauty in hard things — not a therapist, not a guru, not a cheerleader. Calm. Grounded. A little poetic. Never preachy.
**Tone:** Warm but not soft. Confident but not aggressive. Poetic but not flowery.
| Situation | ❌ Wrong tone | ✅ Kalei tone |
|-----------|-------------|-------------|
| User inputs a negative thought | "Let's turn that frown upside down!" | "Let's see what this looks like from another angle." |
| User completes a reframe | "Amazing job! You're so strong!" | "There it is. A pattern worth keeping." |
| User hasn't opened app in a week | "We miss you! Come back!" | "Still here. Ready when you are." |
| Explaining the app | "AI-powered cognitive reframing tool" | "A kaleidoscope for your mind." |
---
---
# Feature Design
---
## The Mirror — Awareness
> *The mirror doesn't tell you what to see. It shows you what's already there.*
### Scientific Basis
The Mirror is grounded in selective attention research. Yantis (2008) demonstrated that selective attention is an intrinsic component of perception — what you attend to literally shapes what your brain represents. Stevens & Bavelier (2012) showed that attentional control is trainable and transfers across domains. Koch & Tsuchiya's work distinguishing attention from consciousness means that training attention (a controllable process) can shift what enters conscious awareness without requiring mystical explanations.
The Mirror applies this by acting as an external attentional spotlight — pointing at cognitive patterns the user's own attentional system has habituated to and stopped noticing. The AI doesn't create insight; it redirects attention toward what was always there.
### Concept
The Kaleidoscope (Turn) is structured: one fragment in, patterns out. It works when you **know** what's bothering you.
But most of the time, people don't. They're carrying a vague heaviness — a bad day, an argument replaying in their head, a worry they can't articulate. They don't need a tool yet. They need a space to **think out loud** first.
**The Mirror** is that space.
It's a freeform notebook with a chat-like interface where you write whatever's on your mind — stream of consciousness, venting, processing. As you write, Kalei's AI reads along quietly and does two things:
1. **Highlights fragments** — gently marks phrases that carry negative cognitive patterns (catastrophizing, black-and-white thinking, personalization, fortune-telling, etc.)
2. **Offers to Turn them** — tapping a highlighted fragment opens a mini-reframe inline, without leaving the flow of writing
You're not journaling into a void. You're writing into a mirror that reflects back what you can't see yourself.
### Why "The Mirror"
A kaleidoscope is built from mirrors. The mirrors are what create the symmetry — what take a random fragment and reveal the pattern. Without the mirrors, it's just broken glass. The Mirror feature is the reflective surface of Kalei.
- You write freely → you're pouring fragments onto the table
- Kalei highlights patterns → the mirror reflects back what you couldn't see
- You tap to reframe → you choose which fragments to Turn
- The session becomes a Reflection → saved to your Gallery with its own pattern
### The Writing Experience
**Visual:** Chat-style interface. The user's messages appear as bubbles or blocks on one side. Clean, minimal, dark background. No AI responses appear unprompted — the AI is **listening**, not talking.
**Prompt on empty state:**
> "Start writing. Say whatever's on your mind. I'll listen."
> *Kalei will gently highlight patterns it notices. You decide what to do with them.*
**User writes freely.** They can send multiple messages in sequence, like texting a friend. No character limits. No structure required.
### Fragment Detection
As the user writes (after each message is sent), Kalei's AI analyzes the text for **cognitive distortion patterns** — the same patterns CBT identifies as drivers of negative thinking:
| Distortion | Example | What Kalei detects |
|---|---|---|
| Catastrophizing | "This is going to ruin everything" | Absolutist prediction language |
| Black-and-white thinking | "I always fail at this" | Always/never, all-or-nothing |
| Mind reading | "They probably think I'm an idiot" | Assuming others' thoughts |
| Fortune telling | "This will never get better" | Predicting negative outcomes |
| Personalization | "It's all my fault" | Taking undue responsibility |
| Discounting positives | "That win was just luck" | Minimizing good things |
| Emotional reasoning | "I feel like a failure so I must be one" | Feelings presented as facts |
| Should statements | "I should be further along by now" | Rigid self-imposed rules |
| Labeling | "I'm such a loser" | Identity-level negative labels |
| Overgeneralization | "Nothing ever works out for me" | One event → universal pattern |
**How highlighting appears:**
- Detected phrases get a **subtle underline or soft glow** in warm amber/gold — the color of light catching a fragment
- The highlight is gentle, not aggressive. It should feel like sunlight falling on a piece of glass — drawing attention naturally, not correcting homework
- A small **◇ icon** (fragment symbol) appears at the end of the highlighted phrase
- Highlights appear **after the user finishes a message** — never while typing
**Critical UX principle:** The highlighting must feel like **noticing**, not **judging**. The AI is a mirror, not a critic. The user should feel seen, not corrected.
### Tapping a Fragment — Inline Reframing
When the user taps a highlighted fragment:
1. A **mini-card slides up** from below (half-sheet modal — user can still see their writing above)
2. The card shows:
- The original fragment, quoted
- The cognitive pattern name in plain language
- **12 reframed alternatives** — shorter and lighter than a full Turn
- A "Full Turn" button to take the fragment into the Kaleidoscope for deeper exploration
- A "Dismiss" option
**Example interaction:**
> **User writes:** "Had a terrible meeting today. My manager barely acknowledged my presentation. She probably thinks I'm not cut out for this role. I should just start looking for another job."
> **Kalei highlights:** "She probably thinks I'm not cut out for this role"
> **User taps. Card appears:**
> **◇ Fragment detected**
> *"She probably thinks I'm not cut out for this role"*
>
> This looks like **mind reading** — assuming someone else's thoughts without evidence.
>
> **A different angle:**
> There are many reasons a manager might seem distracted that have nothing to do with your performance. What you observed was her behavior. What she thinks is something you don't have access to yet — but you could ask.
>
> **[Full Turn ◇]** · **[Dismiss]**
### The AI's Role — Passive, Not Conversational
**This is critical.** The Mirror is NOT a chatbot. The AI does not respond to every message, ask follow-up questions, inject unsolicited advice, or break the user's flow with interjections.
The AI **only** does three things:
1. Highlights fragments (passively, after each message)
2. Provides reframes when the user taps a highlight (on demand)
3. Generates a session summary when the user ends the session
**Why not a chatbot?** Because the whole point is that the user is thinking out loud. Inserting AI responses turns it into a conversation with a bot, which changes the psychology entirely. The user stops introspecting and starts performing. The Mirror should feel like writing in a journal that occasionally catches the light — not like talking to a therapist.
**Exception — The Nudge:** If the user has written 5+ messages with zero taps on any highlights and significant negative patterns are accumulating, Kalei can offer ONE gentle nudge:
> "I noticed a few fragments in what you wrote. Want to look at them together?"
> **[Show me]** · **[Not now]**
Once per session maximum.
### Session Wrap-Up — The Reflection
When the user signals they're done writing (closes the Mirror, presses "Done," or after inactivity), Kalei generates a **Reflection**:
1. **The Mosaic** — a high-level summary of themes (not specifics)
> "Today's Mirror covered: work frustration, self-doubt about career, and a conflict with your manager."
2. **Fragments Found** — count of cognitive patterns detected
> "4 fragments noticed. You explored 2 of them."
3. **Patterns Revealed** — the reframes the user engaged with
> "You looked at mind reading and catastrophizing from new angles."
4. **A Generated Pattern** — a unique kaleidoscope visual for this session, saved to the Gallery. Mirror sessions get their own visual style — softer, more organic geometry to distinguish from structured Turns.
5. **An optional one-line insight** — the AI's single most important observation
> "You were hardest on yourself about things you haven't confirmed are true."
The Reflection is saved to the Gallery as a distinct type: a Mirror Reflection.
---
## The Kaleidoscope — Perspective
> *The Kaleidoscope helps you see beauty in what's already there.*
### Scientific Basis
The Turn draws on two research pillars. First, Bandura's self-efficacy theory (1977): every reframe is designed to build capability belief, not provide comfort. The AI shifts users from outcome fixation ("Will this work out?") to capability focus ("What can I do about this?") — directly implementing Bandura's finding that efficacy expectations are the strongest predictor of behavioral change. Second, the attentional retraining from Yantis (2008) and Stevens & Bavelier (2012): each Turn is an exercise in redirecting attention from threat-focused perception to opportunity-aware perception. Repeated Turns train the brain's attentional filters to automatically surface alternative interpretations.
### Concept
The flagship feature. User inputs a negative thought (a fragment), and Kalei reveals multiple reframed perspectives (patterns). This is the core mechanic — structured, immediate, and satisfying.
### User Flow
- **CTA button:** "Turn" (verb — active, simple, one word)
- **Input prompt:** "Drop in a fragment" or "What's on your mind?"
- **Loading state:** A kaleidoscope rotation animation (~1.5 seconds)
- **Results header:** "Here's what the same pieces look like from a new angle"
- **Individual reframes:** Displayed as "Pattern 1," "Pattern 2," "Pattern 3" — each a different arrangement of the same facts
- **Save action:** "Keep this pattern"
### Turn Tab (Home Screen)
- Hero area: "What's the fragment?" — text input
- Below: "Turn of the day" — a featured prompt or previous pattern
- Below: "Recent patterns" — quick access to last 3 Turns
- Floating action: Quick Turn button (always accessible)
### Reframe Styles (Prism)
Premium users can select a reframing perspective:
- **Stoic** — what would Marcus Aurelius say
- **Compassionate** — self-compassion and kindness angle
- **Pragmatic** — practical next-step focus
- **Growth** — how this builds future strength
### Prompt Engineering
```
System prompt context:
"You are the engine behind Kalei, a kaleidoscope for the mind.
The user gives you a fragment — a negative thought or situation.
Your job is to reveal the patterns — multiple genuine, grounded
perspectives on the same situation. You never change the facts.
You change the angle.
You are not a therapist. You are not toxic positivity.
You are a kaleidoscope: you show what was already there,
arranged in a way the user hadn't seen before."
```
---
## The Lens — Direction
> *The Lens helps you focus on what's ahead.*
### Scientific Basis
The Lens is built on three pillars of the research. Locke & Latham's goal-setting theory (2002, 2006) provides the structure: specific, challenging goals with feedback loops consistently outperform vague aspirations. The AI-guided goal creation process implements their specificity principle directly — moving users from "I want to be healthier" to measurable, time-bound commitments.
Gollwitzer's implementation intentions (1999) power every micro-action the Lens generates. The "if-then" format ("If it's 7am Monday, then I put on my running shoes") dramatically increases follow-through by delegating action initiation to environmental cues rather than willpower.
The visualization and mental imagery research (Schuster et al. 2011, Liu et al. 2025) informs the Lens's "The View" feature — guided mental rehearsal sessions that are process-oriented (imagining the steps), not just outcome fantasy (imagining the result). Liu et al.'s meta-analysis found optimal dosage at ~10 minutes, 3x per week — informing the suggested visualization cadence.
### Concept
If the Kaleidoscope shows you new patterns in what already exists, the Lens focuses your vision on what you're building toward. Goal-setting and manifestation, powered by AI.
### Vocabulary
- **Section header:** "Your Lens"
- **Goal creation:** "Set your focus"
- **Daily affirmation:** "Today's focus"
- **Vision board:** "The View" — what you see when you look through the lens
- **Progress check-in:** "Sharpen your focus"
- **Milestone reached:** "Crystal clear"
### Lens Tab
- Current focus (active goal) displayed prominently
- Today's affirmation
- Vision board / The View
- Progress tracker with "sharpening" visual metaphor
### Integration with Other Features
The Lens connects insights from other features to forward momentum:
- Patterns discovered in the Mirror inform what goals matter
- Reframes from the Kaleidoscope become fuel for goal pursuit
- The Spectrum (Phase 2) validates that Lens check-ins correlate with reduced negative patterns
---
## The Spectrum — Intelligence (Phase 2)
> *White light looks simple. The Spectrum shows you everything it's made of.*
### Scientific Basis
The Spectrum synthesizes insights from across the research library. The expectation effects literature (Stetler 2014, Pardo-Cabello et al. 2022) provides the theoretical foundation: when users see concrete evidence that reframing works (Turn Impact data), this creates a positive feedback loop where expectations of benefit increase actual benefit. Stetler showed that consistent adherence reinforces positive expectations — the Spectrum's evidence engine accelerates this cycle.
The habit formation research (Wood & Neal 2007, Wood et al. 2021) informs Rhythm Detection and streak mechanics. Wood et al. found that ~43% of daily behavior is habitual, and that context stability predicts habit formation. The Spectrum tracks not just frequency but context consistency, reinforcing the context-response links that make Kalei usage automatic.
The attention research (Yantis 2008, Stevens & Bavelier 2012) powers Fragment Pattern tracking. By surfacing which cognitive distortions appear most frequently, the Spectrum makes unconscious attentional biases visible — the same principle as the Mirror, but operating at a longitudinal scale.
### Concept
Every wellness app asks you to rate your mood on a scale. Tap a smiley face. Drag a slider. It's self-reported, inaccurate, and most people stop doing it after two weeks because it feels like homework.
Kalei doesn't need to ask how you feel. **It already knows.**
By Phase 2, users have weeks or months of Mirror sessions, Turns, and Lens activity. Every word they've written, every fragment detected, every pattern revealed, every reframe they saved or dismissed — it's all data. Rich, personal, longitudinal emotional data that the user generated naturally while using features they already love.
The Spectrum turns that data into **self-knowledge**.
### Why "The Spectrum"
Light enters a prism and exits as a spectrum — the full range of colors that were always present but invisible to the naked eye. The Spectrum takes the raw light of your daily Kalei usage and separates it into its component colors so you can see what's really going on inside.
### The Five Components
#### 1. The Emotional Landscape — "The River"
A visual representation of emotional state over time — not from self-reporting, but from **AI analysis of Mirror sessions, Turns, and Lens check-ins.**
Every Mirror message and Turn input is analyzed for emotional signatures across six dimensions:
- **Valence:** Positive ↔ Negative
- **Arousal:** Calm ↔ Activated
- **Certainty:** Confident ↔ Uncertain
- **Agency:** In control ↔ Helpless
- **Social orientation:** Connected ↔ Isolated
- **Temporal focus:** Past-dwelling ↔ Present ↔ Future-focused
These dimensions are plotted over time as a **flowing gradient visualization** — not a line chart, but a river of color that shifts and blends. Warm colors for activated states, cool for calm, dark for negative, bright for positive.
**The user sees:**
- The overall color/tone of their week at a glance
- Shifts and transitions (Tuesday was dark and activated → Wednesday calmed after a Turn)
- Long-term trends (past month trending brighter, or a slow slide they hadn't noticed)
**What they don't see:** Numbers, scores, or ratings. The Spectrum is visual and intuitive, not clinical.
#### 2. Fragment Patterns — "Your Glass"
A breakdown of which cognitive distortion types appear most frequently in the user's writing.
**Visualization:** A faceted gem or crystal with different faces representing different distortion types. The larger the face, the more frequently that pattern appears. The gem evolves over time as patterns shift.
**Insights delivered in plain language:**
> "This month, **should statements** made up 34% of your fragments — up from 22% last month. You're putting more pressure on yourself than usual."
> "**Mind reading** dropped significantly since you started Turning those fragments. You assumed others' thoughts 8 times in January, only twice in February."
Most people have 23 dominant cognitive distortions they don't know about. Seeing them named and tracked over time is genuinely transformative — the kind of insight you'd normally get after months of therapy.
#### 3. Turn Impact — "Before & After"
Tracks the measurable effect of reframing on subsequent emotional state.
The AI compares the emotional tone of Mirror sessions **before and after** a Turn:
- User writes in Mirror (frustrated, catastrophizing)
- User takes a fragment to the Kaleidoscope
- User writes in Mirror again later
- The Spectrum measures the shift
**What the user sees:**
> "After Turning a fragment, your next Mirror session is 62% more likely to show increased agency and reduced catastrophizing."
> "Turns on work-related fragments have the strongest positive effect for you. Relationship fragments take 23 Turns before the shift shows up."
This is the **evidence engine** for Kalei's core thesis: changing the angle actually changes how you feel. Users see the proof in their own data.
#### 4. Rhythm Detection — "Your Cycles"
Identifies recurring emotional patterns tied to time.
> "Your Mirror sessions on Mondays contain 3x more should statements than any other day."
> "The last week of each month shows elevated anxiety patterns — possibly tied to deadlines or financial cycles."
> "When you check in with your Lens goals in the morning, your afternoon Mirror sessions show 40% fewer negative fragments."
The user starts to see their emotional life as a **landscape with terrain** rather than random weather. Some hills are always there. Some valleys are seasonal.
#### 5. Growth Trajectory — "The Long View"
The headline metric: how is this person's relationship with their own thinking changing over time?
**Tracked indicators:**
- Fragment density: distortions per 100 words in Mirror sessions (trending down = growth)
- Self-correction rate: how often users identify their own fragments before Kalei highlights them
- Reframe adoption: how often saved patterns echo in subsequent Mirror writing
- Distortion diversity: whether the user addresses multiple types or gets stuck on one
- Turn-to-insight ratio: how many Turns result in a saved keepsake
**Visualization:** A single, evolving kaleidoscope pattern representing overall growth. The more you use Kalei, the more complex, colorful, and beautiful the pattern becomes. At month 1, simple and muted. At month 6, intricate and vivid.
This becomes the **centerpiece of the Spectrum dashboard** — personal growth as a living kaleidoscope pattern.
### Dashboard Layout
- **Top: The River** — emotional landscape gradient. Swipe horizontally through time. Tap any point for that day's Mirror session or Turn.
- **Middle: Your Glass** — faceted gem showing fragment distribution. Toggle week/month/all-time. Tap any facet for distortion deep-dive.
- **Bottom: Insights Feed** — scrollable AI-generated insights, refreshed weekly. Each insight is a card with a one-line observation, supporting data, and action suggestion.
- **Floating: Your Pattern** — evolving kaleidoscope pattern, top corner. Tap to expand full-screen. Shareable as a "growth snapshot."
### Insight Delivery Timing
The Spectrum doesn't bombard users with data. Insights surface at natural moments:
**Weekly Reflection** (Sunday evening): "Your Spectrum updated. See what this week's light revealed. 🔮" Opens to a Weekly Spectrum Summary with dominant emotional color, top fragment type, most impactful Turn, one insight, and the week's addition to the evolving pattern.
**Monthly Deep Dive** (first of each month): Month-over-month comparisons, rhythm detection insights, and growth trajectory updates.
**In-Context Nudges** within other features:
- Mirror: "You've used the phrase 'I should' 4 times this session. That's a pattern worth noticing."
- After a Turn: "This is the 3rd time you've Turned a work-related fragment this week. The Spectrum can show you more about this pattern."
- Lens: "Your Lens focus on [career growth] aligns with the fragments you've been processing. You're working on the right things."
---
## The Rehearsal — Guided Visualization (Lens Sub-Feature)
> *The Lens shows you where you're going. The Rehearsal helps you see yourself getting there.*
### Scientific Basis
The Rehearsal is the most direct implementation of the visualization and mental imagery research — a gap in the current feature set that the science explicitly calls for.
**Schuster et al. (2011)** reviewed motor imagery across five disciplines and found that structured mental rehearsal is most effective when: (1) combined with physical practice (not used in isolation), (2) sessions follow a clear protocol, and (3) imagery is vivid, first-person, and process-oriented. Pure outcome fantasy ("imagine yourself on the podium") can actually *decrease* performance by providing premature satisfaction. Process visualization ("imagine yourself preparing, executing, recovering from mistakes") is what drives results.
**Liu et al. (2025)** meta-analyzed 86 studies with 3,593 athletes and identified an optimal dosage: approximately **10 minutes, 3 times per week, over ~100 days**. Combining imagery with 1-2 additional psychological skills (self-talk, goal setting) produced stronger effects than imagery alone.
**Seok & Choi (2023)** demonstrated that mental practice activates overlapping neural circuits with actual physical execution — even when the body cannot currently perform the action. This confirms that visualization isn't metaphorical; it's neurological preparation.
### Concept
The Rehearsal is a guided visualization feature nested within the Lens. After a user sets a goal, the Rehearsal generates AI-powered, personalized mental rehearsal scripts that walk them through the *process* of achieving it — not just imagining the end state.
This is not meditation. This is not affirmation. This is **cognitive preparation** — the same technique elite athletes use, backed by the same research, adapted for personal goals.
### How It Works
**Entry point:** Within the Lens tab, beneath the active goal. A "Rehearse" button appears alongside "Today's Focus" and "The View."
**Session structure (following Schuster et al.'s best-practice protocol):**
1. **Grounding** (~1 min) — Brief settling. Eyes closed or soft focus. "Take a breath. We're going to walk through something together."
2. **Process visualization** (~5-7 min) — The AI generates a first-person, present-tense script specific to the user's goal and upcoming actions. Multi-sensory: what you see, hear, feel, think. Example for a job interview goal:
> "It's Tuesday morning. You're walking into the building. Notice the weight of your bag, the sound of your shoes on the floor. You're prepared — you reviewed your notes last night. You sit down across from the interviewer. They ask the question you've been anticipating. You feel a quick pulse of nerves — that's normal, that's your body getting ready. You take a breath, and you begin..."
3. **Obstacle rehearsal** (~2 min) — The script includes a moment where something goes imperfectly, and the user mentally rehearses recovering. This prevents the toxic positivity trap and builds realistic self-efficacy.
> "Midway through your answer, you lose your train of thought. You pause. That's fine — you've practiced pausing before. You take a beat, reconnect with your main point, and continue. The interviewer nods."
4. **Close** (~1 min) — Return to present. Anchor the feeling. "You've just walked through it. Your brain now has a draft of this experience. When the real moment comes, it won't be the first time."
**Session length:** ~10 minutes (per Liu et al.'s optimal dosage finding).
**Suggested cadence:** 3x per week, tied to active Lens goals. The app suggests: "You have a Rehearsal ready for [goal]. Best done in the morning."
### Vocabulary
- **Feature name:** "The Rehearsal" or "Rehearse"
- **CTA:** "Rehearse" (verb, like "Turn")
- **Session label:** "A Rehearsal"
- **Completion:** "Rehearsal complete. Your brain has a draft."
- **In the Gallery:** Rehearsal sessions get their own visual style — more fluid, less geometric, like light passing through a lens
### Visual Design (SVG-Native)
The Rehearsal UI is text-driven — the AI-generated script is the experience, not complex graphics. Visual elements are minimal and SVG-generated:
- **Background:** A slow, subtle radial gradient animation (CSS-only on an SVG circle) — simulating light focusing through a lens. Deep jewel tones fading inward.
- **Progress indicator:** A simple SVG ring that fills as the session progresses (similar to a meditation timer). Prismatic gradient stroke.
- **Step transitions:** Gentle SVG fade between Grounding → Process → Obstacle → Close, with a small geometric icon per step (a circle, a path, a crack, a diamond).
- **Completion pattern:** A unique SVG pattern generated from the session — simpler and more fluid than Turn patterns. Think concentric lens rings with soft color shifts, procedurally generated from the goal text seed.
- **No custom illustrations, no photography, no complex animations.** The Rehearsal is an intimate, text-focused experience. The visual design supports focus, not spectacle.
### Key Design Rules
1. **Always process-oriented, never pure outcome fantasy.** The script walks through steps, not podiums.
2. **Always include obstacle rehearsal.** A visualization without setbacks is toxic positivity in disguise.
3. **Always pair with action.** A Rehearsal without a corresponding micro-action in the Lens is incomplete. After each session: "Now make it real. Here's your next step."
4. **First-person, present tense, multi-sensory.** Per Schuster et al.'s findings.
5. **Personalized to the user's goal and context.** Not generic scripts. The AI uses the goal details, timeline, and any Mirror/Turn data about related anxieties to make the Rehearsal feel personal.
### Monetization
| | Free (Kalei) | Prism |
|---|---|---|
| Rehearsal access | 1 per week | Unlimited |
| Script personalization | Basic | Deep (uses Mirror/Turn context) |
| Obstacle rehearsal | ✗ | ✓ |
| Audio playback | ✗ | ✓ (AI-generated narration) |
### Technical Notes
The Rehearsal script is generated via the AI gateway using the user's active Lens goal, upcoming actions, and optionally relevant Mirror fragments/Turn history. The prompt must enforce: first-person perspective, present tense, multi-sensory detail, process focus, obstacle inclusion, and ~10 minute reading pace. Output is cached per goal and refreshed when actions change.
---
## The Ritual — Context-Anchored Daily Flow
> *A kaleidoscope isn't turned randomly. The best patterns come from consistent, deliberate turns.*
### Scientific Basis
The Ritual directly implements Wood & Neal's (2007) core finding: habits form through the gradual learning of associations between responses and **context features** (physical settings, time of day, preceding actions). Once formed, perception of the context triggers the habitual response without a mediating goal — the behavior becomes automatic.
Wood, Mazar & Neal (2021) extended this: ~43% of daily behavior is habitual, not deliberate. Sustained change requires building automatic routines, not just relying on willpower. The single biggest predictor of habit formation is **context stability** — doing the same thing, at the same time, in the same place, in the same sequence.
Current Kalei features track streaks (measuring repetition) but don't actively **scaffold** the context-response link. The Ritual bridges that gap.
### Concept
The Ritual is a timed, sequenced daily flow that chains 2-3 Kalei activities into a single context-anchored routine. Instead of the user deciding each day whether to open Kalei, what to do, and in what order — the Ritual removes all decision points and delivers a pre-structured 5-10 minute experience tied to a specific daily moment.
The user isn't building three separate habits (Mirror, Turn, Lens). They're building **one habit** — "My morning Ritual" — that contains all three.
### Ritual Templates
**The Morning Ritual (~7 minutes)**
Best for: users building a proactive practice
1. **Check-in** (1 min) — Quick Mirror prompt: "One sentence. How are you showing up today?"
2. **Focus** (2 min) — Lens daily action review: "Here's what's on your plate. Which one matters most?"
3. **Rehearse** (3 min) — Abbreviated Rehearsal for today's key action (shorter than a full Rehearsal session)
4. **Set the angle** (1 min) — One-line intention for the day, saved as a fragment seed
**The Evening Ritual (~5 minutes)**
Best for: users who need to process and decompress
1. **Release** (2 min) — Quick Mirror dump: "What are you still carrying from today?"
2. **Turn** (2 min) — AI surfaces the heaviest fragment from the dump and offers a quick Turn
3. **Acknowledge** (1 min) — Lens action review: "What did you complete today?" + Evidence Wall entry
**The Quick Ritual (~3 minutes)**
Best for: busy days, maintaining the streak
1. **One Turn** — AI surfaces a prompt based on recent patterns or a random fragment seed
2. **One action** — Lens shows the single most important action for today
3. **Done** — "That's your Ritual. Same pieces. New angle. See you tomorrow."
### How It Works
**Setup:** During onboarding (or first week), the user selects a Ritual template and anchors it to a context:
- **When:** "Every morning after my first coffee" / "Every evening before bed" / custom
- **What:** Morning / Evening / Quick
- **Notification:** "Your Ritual is ready" sent at the anchored time
**The experience:** The Ritual opens as a single, flowing screen — not tabbed navigation between Mirror/Turn/Lens. Each step transitions seamlessly into the next with a gentle visual progression (the kaleidoscope pattern building as they complete each step). No menus, no choices, no friction. Just follow the light.
**Completion:** "Ritual complete" + updated streak + optional one-line insight. The Ritual pattern (a simpler, more structured pattern than Mirror or Turn patterns) saves to the Gallery.
### Context Stability Tracking
Per Wood et al.'s findings, the app tracks not just *whether* the Ritual was completed, but *when* and *how consistently*:
> "You've completed your Morning Ritual within the same 30-minute window for 12 days. This is becoming automatic."
> "Your Ritual timing drifted this week — 7am Monday, 9am Wednesday, skipped Friday. Consistency is the engine. Can we lock in a time?"
This is the most direct implementation of the habit formation science anywhere in the app.
### Vocabulary
- **Feature name:** "The Ritual"
- **CTA:** "Start your Ritual"
- **Completion:** "Ritual complete"
- **Streak label:** "X-day Ritual streak"
- **Context anchor:** "Your Ritual time"
- **Notification:** "Your Ritual is ready" (not "Time for your Ritual" — no pressure)
### Monetization
| | Free (Kalei) | Prism |
|---|---|---|
| Ritual access | Quick Ritual only | All 3 templates |
| Customization | Fixed template | Customize steps and order |
| Context tracking | Basic streak | Full consistency analytics |
| Ritual patterns in Gallery | ✗ | ✓ |
### Visual Design (SVG-Native)
The Ritual is a flowing, minimal experience. No complex UI — just a sequence of steps with clean transitions.
- **Ritual screen:** A single scrolling view. Each step is a card with a subtle SVG border (thin geometric frame, prismatic gradient stroke). Steps stack vertically, each revealing as the previous completes.
- **Progress visualization:** A simple SVG horizontal bar or arc that fills step-by-step. Each completed step adds a faceted segment in a different jewel tone. Think a prismatic progress bar — 3-5 colored geometric segments filling left to right.
- **Completion state:** All segments filled → the bar pulses once with a soft glow (CSS animation on SVG), then collapses into a small Ritual pattern icon (a simple symmetric SVG — like a mandala made from 3-5 triangles) that saves to the Gallery.
- **Timer overlay:** A minimal SVG circle timer for timed steps (Mirror check-in, Rehearsal). Thin stroke, ambient color.
- **No illustrations, no photography, no Lottie animations.** The Ritual's premium feel comes from spacing, typography, and color — not complexity. Think Apple Health's simplicity meets Kalei's jewel-tone palette.
### Retention Impact
The Ritual addresses the week 3-4 retention cliff head-on. By that point:
- The novelty of individual features (Mirror, Turn, Lens) has faded
- But the *Ritual habit* is forming — context cues are starting to trigger automatic behavior
- The user opens Kalei not because they decided to, but because it's 7am and they just poured coffee
- By the time the Spectrum launches (Phase 2), the Ritual has already made daily usage automatic
This is the difference between an app that relies on motivation (which declines) and one that builds habits (which compound).
---
## The Evidence Wall — Mastery Tracking
> *A kaleidoscope collects fragments. The Evidence Wall collects proof.*
### Scientific Basis
Bandura (1977) identified four sources of self-efficacy, ranked by potency:
1. **Mastery experiences** — successfully doing the thing (strongest source by far)
2. **Vicarious experience** — watching someone similar succeed
3. **Verbal persuasion** — being told you can do it (what reframes primarily provide)
4. **Physiological states** — interpreting your body's signals as capability vs. inadequacy
The Turn and Mirror currently operate primarily through **verbal persuasion** (reframes that tell you "you can handle this") — Bandura's *weakest* efficacy source. The Evidence Wall adds the *strongest* source: concrete evidence of past mastery.
When a user hits a setback and their self-efficacy dips, the most powerful intervention isn't a new reframe. It's their own track record: "Look at what you've already done."
### Concept
The Evidence Wall is a dedicated section (accessible from the "You" tab or within the Lens) that automatically collects and curates evidence of the user's growing capability:
- **Completed micro-actions** from the Lens
- **Turning points** — Turns that produced a saved keepsake
- **Self-corrections** — moments in Mirror sessions where the user caught their own fragment before Kalei highlighted it (detected by self-editing patterns)
- **Streak milestones** — consistency evidence
- **Goal completions** — finished Lens goals
- **Reframe echoes** — instances where language from a saved Turn pattern appeared organically in later Mirror writing (the user internalized the reframe)
- **Spectrum growth markers** — fragment density drops, new distortion types addressed
### How It Shows Up
**Passive collection:** The Evidence Wall populates automatically from usage data. The user doesn't need to manually log anything — the evidence accumulates naturally as they use Kalei.
**Active surfacing — The "Remember" Moment:** When the AI detects a self-efficacy dip (repeated catastrophizing, increased helplessness language in Mirror sessions, abandoned Lens actions), it can surface Evidence Wall entries contextually:
> **In a Mirror session:**
> "I notice you're being hard on yourself about your ability to follow through. Here's what I've seen: you've completed 23 micro-actions this month, hit your running goal 3 weeks in a row, and last Tuesday you caught a catastrophizing pattern before I even highlighted it. That's your track record."
> **After a Turn:**
> "This pattern — doubting your capability — has come up before. Last time, you Turned it and saved this keepsake: [displays saved reframe]. Since then, you've completed 4 of the 5 actions you set for yourself."
**The Wall itself:** A visual timeline or mosaic in the "You" tab. Each evidence type gets its own visual marker (faceted shapes in different colors). The Wall grows denser and more colorful over time — a literal accumulation of proof.
### Vocabulary
- **Feature name:** "The Evidence Wall" or "Your Evidence"
- **Section in You tab:** "Your Evidence"
- **Individual entries:** "Proof points"
- **AI surfacing:** "Here's what I've seen" (not "remember when you..." — the AI presents evidence, not nostalgia)
- **Milestone:** "New proof point added to your Wall"
### Key Design Rules
1. **Evidence, not cheerleading.** The Wall presents facts ("You completed 23 actions"), not encouragement ("You're doing amazing!"). Bandura's research shows that mastery evidence works because it's *credible* — the user can't argue with their own track record.
2. **Automatic, not manual.** If the user has to log their own wins, it becomes a gratitude journal (which is a different thing). The power is that the evidence accumulates without effort.
3. **Contextual surfacing, not nagging.** The AI only surfaces evidence when it detects a dip in self-efficacy language. Unsolicited "look how great you're doing!" messages feel performative and erode trust.
4. **Concrete and specific.** "23 actions completed" not "you've been consistent." Numbers, dates, specific Turns and reframes. The more specific, the more credible, the stronger the efficacy effect.
### Integration with Other Features
| Feature | Evidence Collected |
|---|---|
| **Mirror** | Self-correction moments, reduced fragment density over time |
| **Turn** | Saved keepsakes, reframe echoes in later writing |
| **Lens** | Completed actions, hit goals, streak milestones |
| **Rehearsal** | Completed rehearsals (preparation as evidence) |
| **Ritual** | Consistency streaks, context stability data |
| **Spectrum** | Growth trajectory markers, distortion reduction data |
### Monetization
| | Free (Kalei) | Prism |
|---|---|---|
| Evidence collection | Last 30 days | Full history |
| AI surfacing in sessions | ✗ | ✓ |
| Visual Evidence Wall | Basic count | Full timeline visualization |
| Export/share proof points | ✗ | ✓ |
### Visual Design (SVG-Native)
The Evidence Wall's visual identity is a growing mosaic — each proof point is a small geometric SVG tile that accumulates into a larger pattern.
- **Individual proof points:** Small SVG shapes — hexagons, diamonds, triangles — color-coded by source (amber for Mirror self-corrections, emerald for Lens completions, sapphire for Turn keepsakes, amethyst for Spectrum milestones). Simple flat fills with thin borders. No icons, no illustrations — just colored geometric shapes.
- **The Wall view:** A grid/mosaic layout of these shapes in the "You" tab. As proof points accumulate, the mosaic grows denser and more colorful. Early on it's sparse (a few shapes scattered on dark background). After months, it's a rich tapestry. This creates the same "collection" satisfaction as the Gallery but for evidence instead of patterns.
- **Timeline mode:** Toggle from mosaic to a simple SVG timeline — a horizontal line with proof point markers along it. Colored dots on a dark line. Tap any dot to see the detail.
- **AI surfacing card:** When the Evidence Wall surfaces contextually in a Mirror or Turn session, it appears as a simple card with a thin prismatic border, a count, and 2-3 specific proof points. No fancy animations — just clean typography and jewel-tone accents on dark background.
- **No complex data visualizations.** The Evidence Wall is a collection, not a dashboard. Its visual simplicity is intentional — the evidence itself is the feature, not the presentation.
### Why This Matters
Without the Evidence Wall, Kalei's self-efficacy building relies entirely on verbal persuasion (reframes). With it, the app deploys Bandura's *strongest* efficacy mechanism. The difference:
- **Without Evidence Wall:** "You can handle this" (the AI says so)
- **With Evidence Wall:** "You've handled 23 things like this in the last month" (the data says so)
The second is dramatically more powerful. It shifts self-efficacy from something the app *tells* the user to something the user *knows* because they can see the proof.
---
---
# Experience Design
---
## Visual Design Language
### SVG-First Design Philosophy
Kalei's visual identity is built to be implemented without external designers or complex asset pipelines. Every visual element should be achievable with **SVGs (hand-crafted or procedurally generated), CSS gradients, and minimal animation**. The premium feel comes from restraint — jewel tones on dark backgrounds, geometric precision, generous spacing, and quality typography. Not from illustrations, photography, or complex motion graphics.
**This means:**
- All patterns (Turn, Mirror, Rehearsal, Ritual, Evidence Wall) are procedurally generated SVGs using the input text as a seed
- All icons are geometric SVG shapes — faceted, angular, simple
- All backgrounds use CSS/SVG gradients — no raster images
- All animations are CSS transitions on SVG elements — no Lottie, no After Effects
- The "premium" feel comes from: dark backgrounds, jewel-tone color palette, precise geometric shapes, quality typography, and intentional negative space
### The Kaleidoscope Aesthetic
The visual identity evokes the feeling of looking through a kaleidoscope without being literal or childish.
**Color Palette:**
- **Primary:** Deep jewel tones — amethyst purple (#7B2D8E), sapphire blue (#1E3A5F), emerald green (#2D5F3E)
- **Secondary:** Warm golds and soft amber (#D4A574, #C8956C) (the light passing through glass)
- **Background:** Near-black (#0A0A0F) or deep navy (#0D1117) (the dark tube of a kaleidoscope — fragments shine against darkness)
- **Accent:** Prismatic gradients for highlights and CTAs (linear-gradient sweeps through the jewel tones)
- **Fragment highlight:** Warm amber glow (#D4A574 at 40% opacity)
**Why dark backgrounds:** A kaleidoscope works by reflecting light against darkness. The dark UI makes colorful elements pop — and positions Kalei as premium, not bubbly.
**Avoid:** Pastel wellness aesthetic. No sage green, no cream, no watercolor blobs. Kalei is jewel-toned, rich, and confident.
**Typography:**
- Clean, modern sans-serif for body text (clarity, legibility) — Inter or similar
- One geometric or slightly decorative font for headlines (faceted, angular — like cut glass) — consider Lexend, Space Grotesk, or similar geometric sans-serif
**Iconography:**
- Geometric and faceted — hexagons, triangles, crystalline shapes — all SVG
- Avoid circles and soft curves (that's every other wellness app)
- Subtle symmetry in icon design (mirrors the symmetry of kaleidoscope patterns)
- All icons deliverable as single-path SVGs with stroke or fill in brand colors
---
## Navigation & Information Architecture
### Tab Bar (5 tabs)
| Icon | Label | Function |
|------|-------|----------|
| ◇ (geometric shard) | **Turn** | The Kaleidoscope — quick structured reframe |
| ✦ (hexagonal mirror) | **Mirror** | Freeform notebook with AI awareness |
| ◎ (lens/circle) | **Lens** | Goals, focus, and manifestation |
| ▦ (grid of patterns) | **Gallery** | History of all patterns and reflections |
| ● (profile) | **You** | Settings, stats, subscription, profile |
### Gallery Tab
- Grid view of kaleidoscope patterns, each linked to a saved reframe or Mirror Reflection
- Filterable by date, mood tag, or theme
- Tap to expand: see original fragment, patterns revealed, and notes
- Option to reshare or re-Turn (reframe same thought for fresh perspectives)
### You Tab
- Streak counter: "X-day turning streak"
- Stats: Total turns, patterns saved, most common themes
- Settings, subscription management
- Spectrum access (Prism users, Phase 2)
---
## Signature Animations
### The Turn (Core Animation)
The most important animation in the app. Triggered when a user submits a thought for reframing:
1. **Input phase:** Fragment icon — a single angular shard
2. **Processing phase:** The shard begins to rotate and multiply (kaleidoscope turning). Smooth, 1.52 seconds
3. **Reveal phase:** Fragments settle into a symmetric pattern. Reframed perspectives appear beneath
This animation should become iconic — the "Kalei Turn" — recognizable in screenshots, marketing, and social media.
### Technical Specs
- **Turn animation:** 1.5s ease-in-out rotation, fragments multiplying from 1→6→full symmetry
- **Loading shimmer:** Prismatic color shift across a geometric skeleton screen
- **Tab transitions:** Subtle faceted wipe (diagonal geometric transition)
- **Pattern reveal:** Fragments drift into position with slight parallax depth (0.3s stagger per fragment)
- **Fragment highlight (Mirror):** Amber glow fading in left-to-right after message sent, single subtle pulse, then ◇ icon appears
---
## Pattern System
### Procedural Generation
Each reframing session generates a unique kaleidoscope pattern:
- **Input text as seed** — same thought always generates the same base pattern (creates personal connection)
- **Reframe variant as rotation** — Pattern 1, 2, 3 are visual rotations of the base
- **Render using Canvas/WebGL** in React Native (or pre-rendered SVG)
- **Deterministic** — reopening a saved reframe shows the same pattern
- **Export:** 1080×1920 for Stories, 1080×1080 for feed posts
### Pattern Types
| Source | Visual Style | Save Location |
|--------|-------------|--------------|
| **Turn pattern** | Sharp, geometric, high-contrast. Angular fragments in full symmetry. | Gallery → Turns |
| **Mirror Reflection** | Softer geometry, organic curves blended with facets. Amber-dominant. | Gallery → Reflections |
| **Growth pattern** (Spectrum) | Evolving complexity over time. Starts simple, gains layers and color range. | Spectrum dashboard |
### Pattern Cards (Sharing)
When a user saves a reframe, they can generate a **Pattern Card** — a shareable image featuring their unique pattern, the reframed thought (never the original negative thought), and subtle Kalei branding. Designed for Instagram Story and iMessage formats.
### "Turn It" Sharing
A user can share a prompt with a friend: "Turn this fragment" — challenging someone else to reframe a thought. This introduces new users through a natural, non-spammy mechanic.
### Community Gallery (Future)
An opt-in public gallery where users share their best patterns anonymously. Browse how other people turned fragments into patterns. Upvote the most powerful reframes.
---
## Onboarding Flow
### Scientific Note on Onboarding
The onboarding serves a dual purpose grounded in the placebo/expectation research (Pardo-Cabello et al. 2022, Stetler 2014). First, it creates a mastery experience (Bandura 1977) within 60 seconds — the user successfully reframes a real thought, building immediate self-efficacy. Second, it primes legitimate expectation effects: the experience of "this actually works" on the very first use sets up the positive expectation-behavior loop that Stetler identified as the mechanism behind adherence benefits.
The onboarding teaches the metaphor through experience, not explanation.
**Screen 1 — The Fragment**
Visual: A single shard of colored glass on a dark background.
> **"This is a thought."**
> *On its own, it can feel sharp. Random. Hard to make sense of.*
**Screen 2 — The Turn**
Visual: The shard multiplies and rotates into a kaleidoscope pattern. Animated.
> **"But change the angle..."**
> *...and the same piece becomes part of something beautiful.*
**Screen 3 — The Reveal**
Visual: A full, stunning kaleidoscope pattern fills the screen.
> **"Kalei doesn't change your reality."**
> *It changes how you see it.*
**Screen 4 — First Turn (Interactive)**
> **"Let's try your first Turn."**
> *Type something that's been weighing on you.*
The user types a real negative thought. Kalei processes it and returns 23 reframed perspectives. Core value proposition experienced within 60 seconds.
**Screen 5 — Welcome**
> **"Welcome to Kalei."**
> *Every day is a new turn.*
---
---
# Engagement & Monetization
---
## Notifications & Engagement Copy
### Scientific Note on Engagement Design
All engagement mechanics are grounded in Wood & Neal's habit formation research (2007, 2021). Notifications are timed to reinforce context-response links (same time, same trigger → same behavior). Streak tracking measures the repetition necessary for habit crystallization. The goal is automaticity — the point where opening Kalei becomes a reflexive response to context cues, not a willpower-dependent decision. Stetler (2014) further supports this: consistent adherence creates a positive expectation-behavior feedback loop that compounds over time.
### Daily Prompt (Push Notification)
Rotate through styles:
- "Ready for today's Turn? 🔮"
- "Same pieces, new angle. What fragment are you carrying today?"
- "Your Gallery is growing. Add today's pattern."
- "The glass hasn't changed. But the view can. Take a Turn."
### Streak Maintenance
- Day 3: "Three days of turning fragments into patterns. Keep going."
- Day 7: "A week of new angles. Your Gallery is filling up."
- Day 30: "30 days. 30 Turns. You're seeing things most people never will."
- Streak broken: "The kaleidoscope is still here when you're ready. No pressure."
### Milestone Celebrations
- First Turn: "Your first pattern. This is where it starts."
- 10th Turn: "10 fragments turned into 10 beautiful patterns."
- 50th Turn: "You've looked at 50 hard things and found something worth keeping in every one."
- 100th Turn: "100 Turns. You don't just see the bright side — you see every side."
### Mirror-Specific Prompts
For days when the user opens the Mirror but doesn't know what to write:
- "What happened today that you're still thinking about?"
- "What would you say to a friend if they were feeling what you're feeling?"
- "What's one thing you're avoiding thinking about?"
- "Describe your mood in a sentence. Then ask yourself why."
### Spectrum Notifications (Phase 2)
**Weekly:**
- "Your Spectrum shifted this week. Come see the colors."
- "7 days of fragments and patterns. Here's what the light reveals."
**Monthly:**
- "A month of Turns. Your Spectrum has a story to tell."
- "January's light, separated into its colors. Your monthly Spectrum is ready."
**Milestone Insights:**
- "Your fragment density dropped below 5 per 100 words for the first time. You're catching yourself."
- "3 consecutive weeks of increasing agency in your writing. Something shifted."
- "You haven't catastrophized in 12 days. That's your longest streak."
**Growth Pattern Evolution:**
- "Your pattern grew a new layer this month. Tap to see it."
- "Remember your first pattern? Compare it to today's. Look how far you've come."
### Empty States
| Screen | Copy |
|--------|------|
| Gallery (no saves) | "Your Gallery is waiting. The next pattern you save will appear here." |
| Mirror (first open) | "Start writing. Say whatever's on your mind. Kalei will listen." |
| Lens (no goal set) | "What are you focusing on? Set your first Lens." |
| Turn history (new user) | "Every kaleidoscope starts with a single turn." |
| Keepsakes (empty) | "No keepsakes yet. When a pattern feels worth keeping, you'll find it here." |
---
## Retention Strategy
### The Spectrum as Retention Engine (Phase 2)
The Spectrum solves the biggest problem in wellness apps: **the drop-off after initial novelty fades.**
**Week 12:** Users are engaged with the Mirror and Kaleidoscope. Everything is new.
**Week 34:** Novelty fades. This is where most wellness apps lose people.
**With the Spectrum** (launched when early users hit this exact window):
- "Your first Spectrum is ready" re-engages users with a new reason to open the app
- The evolving pattern creates **collection psychology** — users want to see it grow
- Weekly insights create a **recurring appointment** with the app
- Growth trajectory shows **concrete progress** — "this is working" evidence
- Fragment tracking creates **self-competition** — users try to beat their own patterns
- Monthly deep dives become **anticipated events** — not notifications to dismiss
The Spectrum turns Kalei from a tool you use when you feel bad into a **dashboard you check because you're curious about yourself.** That's the difference between reactive usage (declining) and proactive usage (compounding).
### Mirror Streaks & Fragment Tracking
Mirror streaks track separately from Turn streaks — Mirror sessions tend to be longer and more personal, making them a higher engagement signal.
The Gallery shows **fragment patterns over time**:
- "This month, your most common fragment type was **should statements**"
- "You've reduced catastrophizing by 40% compared to last month"
This turns the Mirror from a journal into a **self-awareness engine.** Users can literally see their thinking patterns change over time.
### Spectrum Launch Sequence
**Pre-Launch (2 weeks before):**
> "You've completed [X] Turns and [Y] Mirror sessions. Something new is coming that turns all of that into self-knowledge. Stay tuned."
**Launch Day:**
> "The Spectrum is here. Every Turn you've taken, every fragment you've noticed — it all means something. See your full emotional landscape for the first time."
Open to a dramatic reveal of their personal Spectrum — the river visualization populating with historical data, the gem forming facets, the evolving pattern appearing. This should be a **wow moment.**
---
## Monetization
### Tier Structure
| | **Kalei** (Free) | **Kalei Prism** ($7.99/mo) |
|---|---|---|
| **Kaleidoscope (Turn)** | 3 Turns per day | Unlimited |
| | Basic pattern generation | Advanced reframe styles (Stoic, Compassionate, Pragmatic, Growth) |
| | | Custom pattern themes |
| **Mirror** | 2 sessions per week | Unlimited |
| | Basic highlighting (3 distortion types) | Full spectrum (all 10 types) |
| | 1 inline reframe per session | Unlimited reframes |
| | Summary only | Full Reflection with insight |
| | | Fragment tracking over time |
| | | Export sessions |
| **Lens** | Basic goal setting | Full Lens with AI-powered affirmations |
| | | Vision board / The View |
| **Rehearsal** | 1 per week | Unlimited |
| | Basic script | Deep personalization (uses Mirror/Turn context) |
| | | Obstacle rehearsal + audio playback |
| **Ritual** | Quick Ritual only | All 3 templates (Morning/Evening/Quick) |
| | | Customize steps and order |
| | Basic streak | Full consistency analytics |
| **Evidence Wall** | Last 30 days | Full history |
| | | AI surfacing in sessions |
| | | Full timeline visualization |
| **Gallery** | Last 30 days | Full history |
| | | Export and share patterns |
| **Spectrum** | Simplified weekly summary (1 insight, no visuals) | Full dashboard with all 5 components |
| | Fragment type counts (basic numbers) | Weekly and monthly deep dives |
| | | Growth trajectory and evolving pattern |
| | | Rhythm detection + Turn impact |
**Why "Prism":** A prism takes a single beam of light and splits it into its full spectrum. Kalei Prism gives you the full spectrum of features.
**Upgrade CTAs:**
- "See the full spectrum"
- "Unlock your Prism"
- (Spectrum-specific): "You've written 47 Mirror sessions and completed 23 Turns. There's a story in that data. See your full Spectrum."
**Pricing Display:**
> **Kalei Prism — $7.99/month**
> *Unlimited Turns. Full Gallery. The Lens. Your complete spectrum.*
The free tier gives enough access to experience the value. The paywall hits at the point where the user wants **depth and consistency** — exactly when they're most likely to convert. The Spectrum deepens this further in Phase 2 by requiring usage history to be valuable — by the time a user has enough data, they've already experienced Kalei's core value and are primed to convert.
---
---
# Technical Architecture
---
## AI Processing Pipeline
### Mirror — Fragment Detection
Each message the user sends triggers a lightweight AI analysis:
```
User message → Claude API call → Returns:
{
"fragments": [
{
"text": "She probably thinks I'm not cut out for this role",
"start_index": 89,
"end_index": 143,
"distortion_type": "mind_reading",
"distortion_label": "Mind reading",
"distortion_description": "Assuming someone else's thoughts without evidence",
"confidence": 0.87
}
]
}
```
**Confidence threshold:** Only highlight fragments with confidence > 0.75 to avoid false positives. A false positive would erode trust quickly.
**Latency:** Analysis should complete within 12 seconds after message sent. Highlights appear with a subtle fade-in.
### Mirror — Reframe Generation (On Tap)
When user taps a highlighted fragment:
```
Input: fragment text + surrounding context + distortion type
Output: {
"distortion_explanation": "Plain language explanation",
"reframe": "1-2 sentence alternative perspective",
"full_turn_prompt": "Pre-filled prompt for Kaleidoscope"
}
```
---
## Database Schema
### Mirror Tables
```sql
CREATE TABLE mirror_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
started_at TIMESTAMPTZ DEFAULT NOW(),
ended_at TIMESTAMPTZ,
reflection_summary TEXT,
reflection_insight TEXT,
pattern_seed TEXT,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE mirror_messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID REFERENCES mirror_sessions(id),
content TEXT NOT NULL,
sequence_order INTEGER,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE mirror_fragments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
message_id UUID REFERENCES mirror_messages(id),
fragment_text TEXT NOT NULL,
start_index INTEGER,
end_index INTEGER,
distortion_type VARCHAR(50),
confidence FLOAT,
was_tapped BOOLEAN DEFAULT FALSE,
was_reframed BOOLEAN DEFAULT FALSE,
reframe_text TEXT,
created_at TIMESTAMPTZ DEFAULT NOW()
);
```
### Spectrum Tables (Phase 2)
```sql
CREATE TABLE spectrum_session_analysis (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
session_id UUID REFERENCES mirror_sessions(id),
session_date DATE NOT NULL,
valence FLOAT, -- -1 (negative) to 1 (positive)
arousal FLOAT, -- -1 (calm) to 1 (activated)
certainty FLOAT, -- -1 (uncertain) to 1 (confident)
agency FLOAT, -- -1 (helpless) to 1 (in control)
social_orientation FLOAT, -- -1 (isolated) to 1 (connected)
temporal_focus FLOAT, -- -1 (past) to 0 (present) to 1 (future)
fragment_count INTEGER,
word_count INTEGER,
dominant_distortion VARCHAR(50),
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE spectrum_turn_analysis (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
turn_id UUID REFERENCES turns(id),
turn_date DATE NOT NULL,
pre_valence FLOAT,
post_valence FLOAT,
distortion_type VARCHAR(50),
reframe_saved BOOLEAN,
topic_cluster VARCHAR(100),
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE spectrum_weekly (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
week_start DATE NOT NULL,
avg_valence FLOAT,
avg_arousal FLOAT,
avg_agency FLOAT,
total_fragments INTEGER,
total_turns INTEGER,
total_mirror_sessions INTEGER,
dominant_distortion VARCHAR(50),
distortion_distribution JSONB,
fragment_density FLOAT,
turn_impact_score FLOAT,
insight_text TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(user_id, week_start)
);
CREATE TABLE spectrum_monthly (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
month_start DATE NOT NULL,
growth_score FLOAT,
rhythm_insights JSONB,
month_over_month_delta JSONB,
top_fragment_types JSONB,
most_impactful_turn UUID,
pattern_complexity_score FLOAT,
narrative_summary TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(user_id, month_start)
);
```
### Data Processing
Spectrum analysis runs as a **background job**, not in real-time:
- After each Mirror session ends, emotional dimensions are computed and stored as numerical vectors — not raw text
- Fragment types are already captured during Mirror sessions
- Weekly aggregation job computes trends, rhythms, and insights
- The Spectrum dashboard reads from aggregated data only
---
## Privacy & Safety
Mirror and Spectrum content is the most personal data in the app. Trust is non-negotiable.
### Principles
1. **End-to-end encryption** for all Mirror content at rest
2. **No content used for model training** — explicit policy
3. **Local-first option** (future): Allow users to keep Mirror data on-device only
4. **Easy deletion**: User can delete any session or all Mirror data at any time
5. **Spectrum analyzes aggregated patterns, never exposes raw content.** It shows "your catastrophizing increased this week" — never "you wrote 'my life is falling apart' on Tuesday"
6. **No Spectrum data leaves the user's account.** Not for model training, not for research, not for anything
7. **Users control the analysis window.** They can exclude any session or Turn. They can limit analysis to the last 30/60/90 days
8. **Full deletion.** "Reset my Spectrum" erases all analyzed data and starts fresh
9. **Transparency.** A "How this works" section explains exactly what the AI analyzes and what it doesn't
### Content Safety
If AI detects crisis language (self-harm, suicidal ideation), surface crisis resources immediately — not as a highlight/reframe, but as a dedicated intervention with hotline numbers and a warm handoff message. Kalei never reframes crisis-level distress. These are not fragments to be Turned. They are signals to provide immediate support.
---
---
# Marketing
---
## Taglines
| Context | Tagline |
|---------|---------|
| **Primary** | Same pieces. New angle. |
| **Descriptive** | A kaleidoscope for your mind. |
| **Action** | Turn how you see it. |
| **Discovery** | Find the pattern. |
| **Aspirational** | See every side. |
## Elevator Pitch
> "Kalei is a kaleidoscope for your mind. Write freely in the Mirror and Kalei gently highlights the negative thinking patterns you can't see yourself. Take any thought into the Kaleidoscope and see it from entirely new angles. Then focus your clarity through the Lens toward the goals that matter to you. Same pieces. New angle. That's Kalei."
## App Store Description
> **Kalei — A kaleidoscope for your mind.**
>
> A kaleidoscope doesn't change the glass. It changes the angle. Suddenly, broken fragments become a beautiful pattern.
>
> Kalei does the same thing with your thoughts.
>
> Type what's weighing on you. Kalei reveals new perspectives — not toxic positivity, but genuine, research-backed ways to see the same situation differently. Every reframe is grounded in cognitive behavioral science and built to help you think clearer, not just feel better.
>
> **The Mirror** — Write freely. Kalei listens and gently highlights the negative thinking patterns you can't see yourself. Tap any highlight to see it from a different angle.
>
> **The Kaleidoscope** — Turn any negative thought into multiple new perspectives. Same facts. Different angle. Beautiful patterns.
>
> **The Lens** — Set your focus. Define what you're building toward. Daily affirmations, vision tracking, and goal clarity powered by AI.
>
> **Your Gallery** — Every Turn creates a unique pattern. Save your favorites. Watch your collection grow. See how far you've come.
>
> Same pieces. New angle. That's Kalei.
---
## The Metaphor at Every Layer
| Layer | How it shows up |
|-------|-----------------|
| **Name** | Kalei — short for kaleidoscope |
| **Tagline** | Same pieces. New angle. |
| **Core mechanic** | "Turn" a fragment into patterns |
| **Visual design** | Jewel tones, geometric shapes, dark backgrounds, prismatic gradients |
| **Animations** | Kaleidoscope rotation on every reframe |
| **Vocabulary** | Fragments, patterns, turns, facets, gallery, keepsakes |
| **Feature names** | The Mirror, The Kaleidoscope, The Lens, The Spectrum |
| **Subscription** | Kalei Prism — "See the full spectrum" |
| **Sharing** | Pattern Cards — unique generative art tied to each reframe |
| **Notifications** | Poetic, grounded, always referencing angles and patterns |
| **Brand voice** | Calm, wise, finds beauty in hard things |
| **Onboarding** | User experiences a real Turn within 60 seconds |
| **Retention** | Gallery of personal patterns grows over time — collectible, visual, meaningful |
| **Phase 2** | The Spectrum completes the optical system — mirror, kaleidoscope, lens, prism |
---
## Feature Map — Full Ecosystem
```
PHASE 1 — CORE FEATURES PHASE 2
───────────────────────────────── ──────────────────────
THE MIRROR (Awareness) ──→ feeds data to ──→ THE SPECTRUM
Write freely (Intelligence)
AI highlights fragments See your patterns
Inline reframes Track growth
Discover rhythms
THE KALEIDOSCOPE (Perspective) ──→ feeds data to ──→ Measure impact
Structured reframing Evolving visual
Fragment → Patterns
Save keepsakes
THE LENS (Direction) ──→ informed by ──→
Goal setting
Daily affirmations
Vision tracking
+ THE REHEARSAL (sub-feature)
Guided visualization sessions
Process-oriented mental rehearsal
PHASE 1 — CONNECTORS
─────────────────────────────────
THE RITUAL ──→ sequences ──→ Mirror + Turn + Lens
Morning / Evening / Quick into one daily habit
Context-anchored timing
Consistency tracking
THE EVIDENCE WALL ←── collects from ←── All features
Mastery evidence accumulation
Contextual AI surfacing
Proof-point mosaic
◇ ◇
Kalei Free Kalei Prism
3 Turns/day Unlimited everything
2 Mirror/week + Full Spectrum
Basic Lens + All Ritual templates
Quick Ritual only + Unlimited Rehearsals
1 Rehearsal/week + Full Evidence Wall
Evidence Wall (30 days) + Growth trajectory
+ Fragment analytics
```
---
*The glass hasn't changed. But you have.*