From 43489eb53c78fc6ad042915fe1b9cd46b651795e Mon Sep 17 00:00:00 2001 From: Matt Date: Mon, 9 Feb 2026 17:06:09 +0100 Subject: [PATCH] Add Kalei documentation - App blueprint - Brand guidelines and metaphor - Complete design specification - Mirror feature documentation - Spectrum phase 2 plan Co-Authored-By: Claude Sonnet 4.5 --- docs/app-blueprint.md | 1453 ++++++++++++++++++++++++++++++++ docs/kalei-brand-guidelines.md | 1288 ++++++++++++++++++++++++++++ docs/kalei-brand-metaphor.md | 403 +++++++++ docs/kalei-complete-design.md | 1023 ++++++++++++++++++++++ docs/kalei-mirror-feature.md | 354 ++++++++ docs/kalei-spectrum-phase2.md | 405 +++++++++ 6 files changed, 4926 insertions(+) create mode 100644 docs/app-blueprint.md create mode 100644 docs/kalei-brand-guidelines.md create mode 100644 docs/kalei-brand-metaphor.md create mode 100644 docs/kalei-complete-design.md create mode 100644 docs/kalei-mirror-feature.md create mode 100644 docs/kalei-spectrum-phase2.md diff --git a/docs/app-blueprint.md b/docs/app-blueprint.md new file mode 100644 index 0000000..b66044e --- /dev/null +++ b/docs/app-blueprint.md @@ -0,0 +1,1453 @@ +# [APP NAME TBD] — Complete Product Blueprint + +### Science-Backed Manifestation & Thought Transformation App +**Version:** 1.0 — February 2026 +**Author:** Matt (concept & research) + Claude (architecture & strategy) +**Status:** Pre-development — Ready for implementation + +--- + +## Table of Contents + +1. [Executive Summary](#1-executive-summary) +2. [The Problem & Opportunity](#2-the-problem--opportunity) +3. [Scientific Foundation](#3-scientific-foundation) +4. [The 6 Steps to Manifestation](#4-the-6-steps-to-manifestation) +5. [Product Vision & Core Features](#5-product-vision--core-features) +6. [User Experience Flows](#6-user-experience-flows) +7. [AI Strategy & Prompt Architecture](#7-ai-strategy--prompt-architecture) +8. [Technical Architecture](#8-technical-architecture) +9. [Database Schema](#9-database-schema) +10. [Monetization Model](#10-monetization-model) +11. [Cost Estimates](#11-cost-estimates) +12. [Implementation Roadmap](#12-implementation-roadmap) +13. [Building with Claude Code & Codex](#13-building-with-claude-code--codex) +14. [App Store Strategy](#14-app-store-strategy) +15. [Growth & Future Features](#15-growth--future-features) +16. [Naming Candidates](#16-naming-candidates) +17. [Research References](#17-research-references) +18. [Appendix: AI Prompt Templates](#18-appendix-ai-prompt-templates) + +--- + +## 1. Executive Summary + +This app is a science-backed personal transformation tool that does two things no competitor does well together: + +1. **Transforms negative thoughts on the spot** using AI personalized to the user's preferred coaching style — brutal honesty, gentle guidance, logical analysis, philosophical perspective, or humor. +2. **Guides users through a structured 6-step manifestation system** grounded in peer-reviewed research from goal-setting theory, implementation intentions, self-efficacy, selective attention, habit formation, and network effects. + +Unlike the vast majority of manifestation apps (which lean on "Law of Attraction" magical thinking), this app is built on published, peer-reviewed psychology and neuroscience research. The critical differentiator is Step 3: "Believe it's possible — but not guaranteed." This aligns with Bandura's self-efficacy theory (capability belief, not outcome certainty) and avoids the toxic positivity trap that causes most people to abandon manifestation when results aren't immediate. + +**Target users:** Adults 18-45 interested in personal growth, goal achievement, and mental wellness — but skeptical of woo-woo self-help. The "I want to improve my life, but I want science, not crystals" market. + +**Revenue model:** Freemium with premium subscription ($8/mo or $60/yr). + +**Tech stack:** React Native + Expo (frontend) → Supabase (backend/database/auth) → Claude API (AI engine). + +--- + +## 2. The Problem & Opportunity + +### The Problem + +The self-help/manifestation app space is dominated by two extremes: + +1. **Pure woo-woo apps** — Vision boards, affirmations, "raise your vibration" content. No scientific backing. Users get a dopamine hit, then quit when nothing changes because the app never connected belief to *action*. + +2. **Clinical CBT/therapy apps** — Evidence-based but clinical, cold, and expensive. Feel like homework. Users who aren't in acute distress don't stick with them. + +There's a massive gap in the middle: people who want to actively shape their lives using *proven* methods, delivered in a way that feels personal, warm, and actionable — not clinical or magical. + +### The Opportunity + +- The meditation/mindfulness app market (Calm, Headspace) proved people will pay monthly for daily mental wellness tools. But meditation isn't for everyone — many people want *active* thought work, not passive stillness. +- AI makes personalized coaching scalable for the first time. What previously required a $200/hour therapist or coach (personalized thought reframing, goal scaffolding) can now happen instantly on a phone. +- The "manifestation" keyword has massive search volume but almost zero credible competition. Most results are embarrassingly unscientific. An app that owns "science-backed manifestation" has a blue ocean. + +### Competitive Landscape + +| App | Category | Weakness vs. Our App | +|---|---|---| +| Reframe (alcohol reduction) | Behavioral change | Focused solely on drinking, not general thought transformation | +| Reframe AI (mental health) | CBT-based reframing | Generic AI coaches, no manifestation/goal system | +| Headspace / Calm | Meditation | Passive, not active thought work | +| Manifest (various) | Affirmations/vision boards | Zero science, pure "Law of Attraction" | +| BetterHelp / Talkspace | Therapy | Expensive ($240+/mo), requires scheduling, clinical positioning | + +**Our moat:** The combination of (1) AI-powered personalized reframing with (2) a structured, research-cited goal achievement system, delivered with (3) anti-toxic-positivity guardrails and transparent science. + +--- + +## 3. Scientific Foundation + +Every feature in this app maps to published, peer-reviewed research. This isn't decoration — it's the product's structural integrity. + +### Research Pillars + +**Goal Setting & Clarity** +- Locke & Latham (2002) — *Building a Practically Useful Theory of Goal Setting and Task Motivation: A 35-Year Odyssey* +- Locke, Latham, et al. — *New Directions in Goal-Setting Theory* +- Core insight: Specific, challenging goals with clear commitment lead to higher performance than vague "do your best" goals. This drives our Step 1 (Decide/Clarity) and the AI-guided SMART goal creation process. + +**Implementation Intentions (Planning & Action)** +- Gollwitzer (1999) — *Implementation Intentions: Strong Effects of Simple Plans* +- Gollwitzer (2006) — *Implementation Intentions and Goal Attainment* +- Core insight: "If-then" plans ("If situation X arises, then I will do Y") dramatically increase follow-through on goals. This is the backbone of our Step 5 (Act in Alignment) and every micro-action the AI generates. + +**Visualization & Mental Practice** +- Schuster et al. (2011) — *Best Practice for Motor Imagery: A Systematic Literature Review* +- Liu et al. (2025) — *Effects of Imagery Practice on Athletes' Performance* +- Seok et al. (2023) — *Mental Practice in Stroke Rehabilitation* +- Core insight: Mental rehearsal improves real-world performance across domains. Drives our Step 2 (See It) with personalized visualization scripts. + +**Self-Efficacy (Belief → Behavior)** +- Bandura (1977) — *Self-Efficacy: Toward a Unifying Theory of Behavioral Change* +- Core insight: Belief in one's *capability* (not guaranteed outcomes) is the strongest predictor of goal achievement. This shapes our Step 3 (Believe It's Possible — But Not Guaranteed), which is the app's philosophical soul. We explicitly reject certainty-based belief ("the universe will provide") in favor of capability-based belief ("I have or can develop the skills to make this happen"). + +**Attention & Selective Processing** +- Yantis (2008) — *The Neural Basis of Selective Attention* +- Stevens & Bavelier (2012) — *Attention, Learning, and Brain Plasticity* +- Koch & Tsuchiya (2007) — *Attention vs Consciousness* +- Core insight: What you pay attention to shapes your reality — not metaphysically, but neurologically. Your brain filters millions of inputs daily, and attention training can literally change what you perceive. This drives our Step 4 (Notice Differently) and the Reframer's pattern analysis. + +**Habits & Repetition** +- Wood, Mazar & Neal (2021) — *Habits and Goals in Human Behavior* +- Wood & Neal (2007) — *A New Look at Habits and the Habit-Goal Interface* +- Core insight: ~43% of daily behavior is habitual, not deliberate. Sustained change requires building automatic routines, not just willpower. Drives our Step 6 (Repeat and Compound) and streak tracking. + +**Network Effects & Opportunity** +- Granovetter (1973) — *The Strength of Weak Ties* +- Core insight: Transformative opportunities come disproportionately from weak social ties, not close friends. Drives future community features where anonymous sharing creates unexpected connections and inspiration. + +**Expectancy Effects & Placebo** +- Pardo-Cabello et al. (2022) — *Placebo/Nocebo Effects: Mechanisms & Evidence* +- Stetler et al. (2013) — *Expectations & Placebo Response* +- Core insight: Expectations directly influence physiological and behavioral outcomes. Supports the overall premise that structured positive expectation (when combined with action) measurably improves outcomes. + +--- + +## 4. The 6 Steps to Manifestation + +These steps form the app's conceptual spine. Every feature maps back to them. + +``` +┌─────────────────────────────────────────────────────────┐ +│ │ +│ Step 1: DECIDE (Clarity) │ +│ ───────────────────────── │ +│ Define exactly what you want and why it matters. │ +│ Research: Locke & Latham goal-setting theory │ +│ │ +│ Step 2: SEE IT (Mental Rehearsal) │ +│ ───────────────────────────────── │ +│ Visualize the process and outcome with specificity. │ +│ Research: Schuster et al., Liu et al. motor imagery │ +│ │ +│ Step 3: BELIEVE IT'S POSSIBLE (But Not Guaranteed) │ +│ ────────────────────────────────────────────────── │ +│ Build capability-based confidence, not blind faith. │ +│ Research: Bandura self-efficacy theory │ +│ │ +│ Step 4: NOTICE DIFFERENTLY (Attention) │ +│ ────────────────────────────────────── │ +│ Train your brain to filter for aligned evidence. │ +│ Research: Yantis, Stevens & Bavelier selective attn │ +│ │ +│ Step 5: ACT IN ALIGNMENT (Daily) │ +│ ──────────────────────────────── │ +│ Execute micro-actions using if-then planning. │ +│ Research: Gollwitzer implementation intentions │ +│ │ +│ Step 6: REPEAT AND COMPOUND │ +│ ─────────────────────────── │ +│ Build automatic habits that sustain momentum. │ +│ Research: Wood & Neal habit formation │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +### Why Step 3 Is the App's Soul + +Most manifestation content says: "Believe with absolute certainty and the universe will deliver." + +This app says: "Believe you're *capable* of making this happen — but understand it's not guaranteed, and that's okay. Certainty isn't the point. Aligned action is." + +This single distinction: +- Prevents the toxic positivity trap (and subsequent crash when things don't work) +- Aligns with Bandura's actual research (self-efficacy is about capability, not outcomes) +- Builds resilience when setbacks happen (because they were expected as possible) +- Makes the app credible to the skeptical-but-curious demographic that most manifestation apps repel + +--- + +## 5. Product Vision & Core Features + +The app has two core pillars that work independently but compound together. + +### Pillar 1: The Reframer (Daily Thought Transformer) + +This is the app's sticky daily-use feature and primary acquisition tool. It's what users come for before they even know about the Manifestation Engine. + +**What it does:** User inputs a negative thought or experience → AI generates a personalized reframe in their chosen coaching style → ends with a micro-action (if-then implementation intention). + +**Reframe Styles (user selects primary + secondary during onboarding):** + +| Style | Tone | Example Response | +|---|---|---| +| **Brutal Honesty** | Direct, no-nonsense | "You're catastrophizing. Here's what's actually true..." | +| **Gentle Coach** | Warm, empathetic | "That sounds really hard. Let's find what you can take from this..." | +| **Logical Analyst** | Structured, evidence-based | "Let's break this down. What evidence supports vs contradicts this thought?" | +| **Philosophical** | Big-picture, perspective-shifting | "Consider: what would this look like from 10 years in the future?" | +| **Humor** | Light, disarming | "Okay, worst case scenario... you become a cautionary tale in a self-help book. Best case?" | + +**Reframe Structure (every response follows this pattern):** +1. **Acknowledge** — Never dismiss the feeling. Validate first. +2. **Reframe** — Apply the research-backed perspective shift. When appropriate, cite the science: "Your brain is doing what Yantis's research on selective attention predicts — you're filtering for the negative." +3. **Micro-action** — End with a Gollwitzer-style if-then intention: "If [situation] happens again, then I will [specific response]." + +**Sub-features:** +- **Daily prompt** — Push notification at user-set time: "What's weighing on you today?" +- **Reframe history & pattern analysis** — Over time, the app surfaces patterns: "You tend to catastrophize about work on Mondays" or "Your negative thoughts cluster around relationships." This is Step 4 (Notice Differently) applied to the user's own thought life. +- **"Flip It" quick mode** — One-tap mode for acute stress. Voice-record or quick-type → instant reframe. Zero friction. + +### Pillar 2: The Manifestation Engine (Goal System) + +This is the premium feature. A structured journey through all 6 steps, guided by AI. + +**Step 1 — Decide (Clarity):** +- AI guides user through Locke & Latham's SMART framework via conversational prompts +- Makes it feel personal, not corporate ("What would change in your life if you achieved this?" not "Define a measurable objective") +- Output: Crystal-clear goal statement + personal "why it matters" statement +- Free tier: Users can create ONE goal (enough to get invested, creates cliffhanger for premium) + +**Step 2 — See It (Mental Rehearsal):** +- AI generates a personalized visualization script based on the user's goal +- Text format initially; optional audio in later phases (text-to-speech) +- Based on Schuster et al.'s motor imagery best practices: first-person, sensory-rich, process-focused (not just outcome) +- User sees this as a "Vision Summary" they can revisit daily + +**Step 3 — Believe It's Possible:** +- AI walks user through identifying self-efficacy barriers +- Prompts: "What makes you doubt this is possible?" → systematically addresses each doubt +- Sources of evidence: past successes, transferable skills, role models, small wins +- Generates a "Belief Statement" — a personalized, evidence-based declaration of capability +- Anti-toxic-positivity: Never says "you definitely will." Says "you have real reasons to believe you *can*." + +**Step 4 — Notice Differently:** +- Daily "attention prompts" — "Today, notice one thing that's already aligned with your goal" +- Trains selective attention (Yantis, Stevens & Bavelier) toward goal-aligned evidence +- Users log observations → builds an "Evidence Journal" that reinforces belief over time +- Over time, AI surfaces patterns: "You've noticed 23 instances of alignment this month. Your brain is rewiring." + +**Step 5 — Act in Alignment:** +- AI generates daily micro-actions using Gollwitzer's if-then structure +- Format: "If it's [time/situation], then I will [specific 15-minute action toward goal]" +- Users check off completed actions +- Streak tracking with smart reminders +- AI adapts difficulty: starts tiny (2-minute actions), scales up as habit solidifies + +**Step 6 — Repeat & Compound:** +- Habit tracking dashboard showing compound progress over time +- Visual growth charts, milestone celebrations +- AI periodically revisits and updates the plan based on progress +- Weekly AI-generated summary: reframes, patterns, goal progress, suggested adjustments +- Celebrates the *process* (consistency) not just outcomes + +### Additional Features + +**Anti-Manifestation Guard:** +When the AI detects a user spiraling into toxic positivity, magical thinking, or unhealthy attachment to outcomes, it gently course-corrects: +> "Manifestation isn't about wishing — it's about aligning your attention, beliefs, and actions with what you want. Let's focus on what you can control today." + +**Science Drawer:** +Each step has an expandable "Why This Works" section citing the actual research. Example: +> "This technique is based on Gollwitzer's 1999 research on Implementation Intentions, which showed that people who create if-then plans are 2-3x more likely to follow through on goals than those who simply set intentions." + +This builds trust and differentiates from every competitor that says "trust the process" without explaining why. + +**Weekly Reflection:** +AI-generated weekly summary covering: +- Reframe count and patterns +- Mood trajectory (inferred from thought inputs) +- Goal progress against daily actions +- Suggested adjustments for the coming week + +**Streak & Gamification (Light):** +- Daily streaks for reframing and goal actions +- "Reframe count" milestone celebrations (10, 50, 100, 500...) +- Level-ups tied to *consistency* (not volume — doing it daily matters more than doing 10 in one day) +- No leaderboards, no competitive mechanics. This is personal transformation, not a game. + +--- + +## 6. User Experience Flows + +### Flow 1: First Open (Onboarding) + +``` +1. Welcome screen + "Transform your thinking. Achieve your goals. Backed by science." + [Get Started] + +2. How this works (3 swipeable cards) + Card 1: "Reframe your negative thoughts daily with AI" + Card 2: "Build a science-backed plan for what you want in life" + Card 3: "Watch your thinking patterns transform over time" + +3. Choose your reframe style + "When life gets hard, how do you prefer to hear the truth?" + [Show 5 style cards with examples — user taps primary, then secondary] + +4. Set your daily check-in time + "When should we ask how you're doing?" + [Time picker — defaults to 8:00 PM] + +5. Create account + [Email / Google / Apple Sign-In] + +6. First reframe + "Let's try it right now. What's been on your mind?" + [Text input → AI reframe → "wow" moment] + +7. Home screen +``` + +### Flow 2: Daily Reframe + +``` +1. Push notification: "What's weighing on you today?" + [User taps → opens app to input screen] + +2. Input screen + Text field: "What happened? What's bothering you?" + [Optional: voice input button] + [Submit] + +3. Processing (1-3 seconds) + Brief animation (not a spinner — something warm) + +4. Reframe card + ┌─────────────────────────────────────┐ + │ Your thought: │ + │ "I bombed the presentation and │ + │ everyone thinks I'm incompetent" │ + │ │ + │ [Brutal Honesty] reframe: │ + │ │ + │ "Let's be real: you're not a mind │ + │ reader. You have zero evidence that │ + │ 'everyone' thinks anything. What │ + │ you DO know is one presentation │ + │ didn't go as planned..." │ + │ │ + │ 💡 Your micro-action: │ + │ "If I start replaying the │ + │ presentation, then I will write │ + │ down 3 things that DID go right." │ + │ │ + │ 📚 Why this works ▼ │ + │ │ + │ [Save] [Share] [Try Different Style] │ + └─────────────────────────────────────┘ + +5. Save → returns to home with updated streak +``` + +### Flow 3: Manifestation Engine (Goal Creation Wizard) + +``` +1. "Create a Manifestation" [+] + +2. Step 1: Decide + AI conversation (3-5 exchanges): + "What do you want to achieve?" + → "Why does this matter to you personally?" + → "What would your life look like if this happened?" + → "Let's make this specific..." [SMART refinement] + → Output: Clarity Statement displayed as a card + +3. Step 2: See It + AI generates visualization script + "Close your eyes and imagine..." + [User reads/listens → marks as complete] + +4. Step 3: Believe + AI conversation: + "What makes you doubt this is possible?" + → [User lists doubts] + → AI addresses each with evidence + past successes + → Output: Belief Statement card + +5. Step 4: Notice + AI sets up attention prompts + "Starting tomorrow, I'll send you one prompt per day" + [Preview first prompt] + +6. Step 5: Act + AI generates first week of if-then micro-actions + [User reviews and confirms] + +7. Step 6: Compound + Dashboard appears showing the full system: + - Goal card + - Today's attention prompt + - Today's micro-action + - Streak counter + - Progress timeline + +8. "Your manifestation engine is running. Show up daily." +``` + +### Flow 4: Weekly Summary + +``` +Push notification (Sunday evening): +"Your weekly transformation report is ready ✨" + +┌─────────────────────────────────────┐ +│ WEEK 3 SUMMARY │ +│ │ +│ 🔄 Reframes this week: 6 │ +│ Pattern: Work stress (Mon/Tue) │ +│ Shift: Catastrophizing → present │ +│ │ +│ 🎯 Goal: [user's manifestation] │ +│ Actions completed: 5/7 │ +│ Evidence logged: 4 observations │ +│ │ +│ 📈 Trend: Your negative thoughts │ +│ are 23% less catastrophic than │ +│ Week 1. Your brain is learning. │ +│ │ +│ 💡 Suggestion for next week: │ +│ "Your Tuesday stress pattern │ +│ suggests a preparation ritual │ +│ Monday night could help..." │ +│ │ +│ [View Full Report] [Share Progress] │ +└─────────────────────────────────────┘ +``` + +--- + +## 7. AI Strategy & Prompt Architecture + +### Why Claude API + +Claude is the right AI engine for this app because: +1. **Tone control** — Claude excels at adopting specific communication styles while maintaining safety guardrails +2. **Nuance** — Thought reframing requires acknowledging complexity, not defaulting to toxic positivity. Claude handles nuance better than most models. +3. **Safety** — Claude's constitutional AI approach means it won't encourage harmful thinking patterns, which is critical for a mental wellness app +4. **Cost** — Claude Haiku (for simple reframes) and Sonnet (for complex goal guidance) provide a cost-effective tier structure + +### Model Selection by Feature + +| Feature | Model | Rationale | Est. Cost/Call | +|---|---|---|---| +| Simple reframe | Claude Haiku 4.5 | Fast, cheap, good enough for single-thought reframes | ~$0.003 | +| Complex reframe (with patterns) | Claude Sonnet 4.5 | Needs to analyze history + generate nuanced response | ~$0.008 | +| Goal creation wizard | Claude Sonnet 4.5 | Multi-turn conversation requiring coherent guidance | ~$0.015 | +| Visualization script | Claude Sonnet 4.5 | Creative, sensory-rich, personalized writing | ~$0.012 | +| Weekly summary | Claude Sonnet 4.5 | Pattern analysis across multiple data points | ~$0.020 | +| Pattern detection | Claude Haiku 4.5 | Categorization task, doesn't need deep reasoning | ~$0.003 | + +### System Prompt Architecture + +All AI calls go through Supabase Edge Functions (never direct from client). Each function includes: + +1. **System prompt** — Defines the AI's role, constraints, and output format +2. **User context** — Injected from the database (reframe style, goal data, history) +3. **Research grounding** — Relevant citations pre-loaded so the AI can reference them naturally +4. **Anti-toxicity guardrails** — Explicit instructions to avoid toxic positivity, magical thinking, and dismissal of real problems + +See [Appendix: AI Prompt Templates](#18-appendix-ai-prompt-templates) for full prompt examples. + +### Rate Limiting & Cost Control + +- Free tier: 2 reframes/day (hard limit enforced at Edge Function level) +- Premium tier: Unlimited (soft limit of 20/day with warning, hard limit of 50/day) +- All responses cached for 24 hours — if user submits identical thought, return cached reframe +- Goal creation wizard: Max 10 AI exchanges per goal setup +- Weekly summaries: Generated once per week via cron job, not on-demand + +--- + +## 8. Technical Architecture + +### Stack Overview + +| Layer | Technology | Why This Choice | +|---|---|---| +| **Frontend** | React Native + Expo | Single codebase for iOS, Android, web. JavaScript/TypeScript (most transferable skill). Expo handles 90% of native complexity. Huge community + AI coding tool support. | +| **Backend/DB** | Supabase | Managed Postgres DB, built-in auth (email, Google, Apple Sign-In), Edge Functions (Deno runtime), file storage, real-time subscriptions. No servers to manage. | +| **AI Engine** | Claude API (Anthropic) | Called via Supabase Edge Functions. Never direct from client (cost control, rate limiting, prompt security). | +| **Push Notifications** | Expo Push Notifications | Free, built into Expo, works on both platforms out of the box. | +| **Payments** | RevenueCat | Handles App Store + Google Play subscriptions. Way easier than native in-app purchase implementation. Manages receipts, trials, and entitlements. | +| **App Builds** | Expo EAS | Cloud builds for iOS and Android. Handles code signing, certificates, TestFlight, and OTA updates. | +| **Analytics** | PostHog (or Mixpanel free tier) | Open-source product analytics. Event tracking, funnels, retention analysis. | + +### Architecture Diagram + +``` +┌──────────────────────────────────────────────────────────────┐ +│ User's Phone / Web Browser │ +│ (React Native + Expo App) │ +│ │ +│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ +│ │Reframer │ │Manifest. │ │ History │ │ Settings │ │ +│ │ Screen │ │ Engine │ │ & Stats │ │ & Profile │ │ +│ └────┬────┘ └────┬─────┘ └────┬─────┘ └───────┬────────┘ │ +│ │ │ │ │ │ +│ └───────────┴────────────┴────────────────┘ │ +│ │ │ +│ Supabase JS Client SDK │ +└──────────────────────────┬───────────────────────────────────┘ + │ HTTPS + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ Supabase │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Auth (email, Google Sign-In, Apple Sign-In) │ │ +│ │ - JWT tokens, session management │ │ +│ │ - Row Level Security (RLS) on all tables │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ PostgreSQL Database │ │ +│ │ - profiles (user preferences, reframe style) │ │ +│ │ - reframes (thought log + AI responses) │ │ +│ │ - manifestations (goals, clarity statements) │ │ +│ │ - daily_actions (if-then micro-actions) │ │ +│ │ - attention_logs (evidence journal) │ │ +│ │ - streaks (habit tracking) │ │ +│ │ - subscriptions (premium status via RevenueCat) │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Edge Functions (Deno TypeScript) │ │ +│ │ - POST /reframe → validates, calls Claude, saves │ │ +│ │ - POST /generate-plan → goal wizard AI calls │ │ +│ │ - POST /generate-visualization → Step 2 scripts │ │ +│ │ - POST /weekly-summary → pattern analysis + report │ │ +│ │ - POST /check-subscription → RevenueCat validation │ │ +│ │ - All functions enforce rate limits & auth │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Storage │ │ +│ │ - Profile pictures │ │ +│ │ - Audio visualization scripts (Phase 2+) │ │ +│ │ - Exported reports (PDF generation, Phase 3+) │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Cron Jobs (pg_cron or Supabase scheduled functions) │ │ +│ │ - Weekly summary generation (Sundays 6pm user TZ) │ │ +│ │ - Streak reset check (daily midnight user TZ) │ │ +│ │ - Pattern analysis batch job (weekly) │ │ +│ └──────────────────────────────────────────────────────┘ │ +└──────────────────────────┬───────────────────────────────────┘ + │ HTTPS (from Edge Functions only) + ▼ +┌──────────────────────────────────────────────────────────────┐ +│ Claude API (Anthropic) │ +│ │ +│ - Thought reframing (Haiku for simple, Sonnet for complex) │ +│ - Goal guidance & conversational wizards │ +│ - Visualization script generation │ +│ - Pattern analysis & weekly summaries │ +│ - Anti-toxicity guardrails baked into system prompts │ +└──────────────────────────────────────────────────────────────┘ + +┌──────────────────────────────────────────────────────────────┐ +│ External Services │ +│ │ +│ RevenueCat ──── Subscription management, receipt validation │ +│ Expo EAS ────── Cloud builds, OTA updates, push notifs │ +│ PostHog ─────── Product analytics, funnel tracking │ +└──────────────────────────────────────────────────────────────┘ +``` + +### Key Architecture Decisions + +**Why Supabase Edge Functions for AI calls (not direct from client):** +1. API key security — never expose the Claude API key in the client bundle +2. Rate limiting — enforce free/premium limits server-side +3. Prompt security — system prompts stay on the server (can't be extracted) +4. Cost control — can add caching, deduplication, and usage tracking +5. Response formatting — can sanitize/validate AI responses before sending to client + +**Why Expo over bare React Native:** +1. Managed workflow — no need to touch Xcode or Android Studio for most tasks +2. EAS Build — cloud builds mean Matt doesn't need a Mac for iOS builds +3. OTA updates — push bug fixes without App Store review +4. Built-in push notifications — no Firebase setup needed +5. Web support — same codebase runs on web via Expo Web + +**Why RevenueCat over native IAP:** +1. Handles the nightmare of App Store receipt validation +2. Single API for both iOS and Android subscriptions +3. Built-in analytics (MRR, churn, trial conversion) +4. Webhook support for server-side subscription status +5. Free up to $2,500/mo MTR + +--- + +## 9. Database Schema + +### Core Tables + +```sql +-- ========================================== +-- PROFILES +-- User preferences and settings +-- ========================================== +CREATE TABLE profiles ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL UNIQUE, + display_name TEXT, + reframe_style_primary TEXT NOT NULL DEFAULT 'gentle_coach' + CHECK (reframe_style_primary IN ( + 'brutal_honesty', 'gentle_coach', 'logical_analyst', + 'philosophical', 'humor' + )), + reframe_style_secondary TEXT + CHECK (reframe_style_secondary IN ( + 'brutal_honesty', 'gentle_coach', 'logical_analyst', + 'philosophical', 'humor' + )), + notification_time TIME DEFAULT '20:00:00', + timezone TEXT DEFAULT 'UTC', + onboarding_completed BOOLEAN DEFAULT FALSE, + subscription_tier TEXT DEFAULT 'free' + CHECK (subscription_tier IN ('free', 'premium')), + reframes_today INTEGER DEFAULT 0, + last_reframe_date DATE, + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW() +); + +-- ========================================== +-- REFRAMES +-- Thought transformation history +-- ========================================== +CREATE TABLE reframes ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL, + original_thought TEXT NOT NULL, + reframed_response TEXT NOT NULL, + reframe_style_used TEXT NOT NULL, + category TEXT, -- AI-inferred: 'work', 'relationships', 'health', 'finance', 'self-worth', 'general' + sentiment_score DECIMAL(3,2), -- -1.00 to 1.00 (negative to positive) + if_then_action TEXT, -- The micro-action from the reframe + is_quick_flip BOOLEAN DEFAULT FALSE, -- Was this a "Flip It" quick reframe? + created_at TIMESTAMPTZ DEFAULT NOW() +); + +-- Index for history queries and pattern analysis +CREATE INDEX idx_reframes_user_date ON reframes(user_id, created_at DESC); +CREATE INDEX idx_reframes_user_category ON reframes(user_id, category); + +-- ========================================== +-- MANIFESTATIONS +-- Goal/manifestation tracking (the 6-step engine) +-- ========================================== +CREATE TABLE manifestations ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL, + title TEXT NOT NULL, + -- Step 1: Decide + clarity_statement TEXT, + why_it_matters TEXT, + -- Step 2: See It + visualization_text TEXT, + visualization_audio_url TEXT, -- Future: TTS audio file + -- Step 3: Believe + belief_statement TEXT, + doubts_addressed JSONB, -- Array of {doubt, response} objects + -- Metadata + status TEXT DEFAULT 'active' + CHECK (status IN ('active', 'paused', 'completed', 'archived')), + current_step INTEGER DEFAULT 1 CHECK (current_step BETWEEN 1 AND 6), + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_manifestations_user ON manifestations(user_id, status); + +-- ========================================== +-- DAILY ACTIONS +-- If-then micro-actions (Step 5) +-- ========================================== +CREATE TABLE daily_actions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL, + manifestation_id UUID REFERENCES manifestations(id) ON DELETE CASCADE NOT NULL, + if_trigger TEXT NOT NULL, -- "If it's 7am..." + then_action TEXT NOT NULL, -- "...then I will spend 15 min writing" + scheduled_date DATE NOT NULL, + completed BOOLEAN DEFAULT FALSE, + completed_at TIMESTAMPTZ, + created_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_daily_actions_user_date ON daily_actions(user_id, scheduled_date); + +-- ========================================== +-- ATTENTION LOGS +-- Evidence journal entries (Step 4) +-- ========================================== +CREATE TABLE attention_logs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL, + manifestation_id UUID REFERENCES manifestations(id) ON DELETE CASCADE NOT NULL, + prompt_text TEXT, -- The attention prompt that was shown + observation TEXT NOT NULL, -- What the user noticed + created_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_attention_logs_user ON attention_logs(user_id, created_at DESC); + +-- ========================================== +-- STREAKS +-- Habit tracking data +-- ========================================== +CREATE TABLE streaks ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL, + streak_type TEXT NOT NULL + CHECK (streak_type IN ('reframe', 'daily_action', 'attention_log', 'overall')), + current_count INTEGER DEFAULT 0, + longest_count INTEGER DEFAULT 0, + last_activity_date DATE, + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW(), + UNIQUE(user_id, streak_type) +); + +-- ========================================== +-- WEEKLY SUMMARIES +-- Pre-generated weekly reports +-- ========================================== +CREATE TABLE weekly_summaries ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL, + week_start DATE NOT NULL, + week_end DATE NOT NULL, + summary_text TEXT NOT NULL, + reframe_count INTEGER DEFAULT 0, + action_completion_rate DECIMAL(5,2), + attention_log_count INTEGER DEFAULT 0, + top_category TEXT, + mood_trend TEXT, -- 'improving', 'stable', 'declining' + created_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_weekly_summaries_user ON weekly_summaries(user_id, week_start DESC); + +-- ========================================== +-- ROW LEVEL SECURITY +-- Users can only access their own data +-- ========================================== +ALTER TABLE profiles ENABLE ROW LEVEL SECURITY; +ALTER TABLE reframes ENABLE ROW LEVEL SECURITY; +ALTER TABLE manifestations ENABLE ROW LEVEL SECURITY; +ALTER TABLE daily_actions ENABLE ROW LEVEL SECURITY; +ALTER TABLE attention_logs ENABLE ROW LEVEL SECURITY; +ALTER TABLE streaks ENABLE ROW LEVEL SECURITY; +ALTER TABLE weekly_summaries ENABLE ROW LEVEL SECURITY; + +-- Policy template (apply to each table): +CREATE POLICY "Users can only access own data" ON profiles + FOR ALL USING (auth.uid() = user_id); +-- Repeat for each table... +``` + +### Schema Relationships + +``` +auth.users (Supabase built-in) + │ + ├── profiles (1:1) + │ + ├── reframes (1:many) + │ + ├── manifestations (1:many) + │ │ + │ ├── daily_actions (1:many per manifestation) + │ │ + │ └── attention_logs (1:many per manifestation) + │ + ├── streaks (1:4 — one per streak_type) + │ + └── weekly_summaries (1:many — one per week) +``` + +--- + +## 10. Monetization Model + +### Freemium with Smart Gate + +**Free Tier (acquisition & habit building):** +- 2 reframes per day (enough to build habit, not enough to feel unlimited) +- Access to Step 1 of Manifestation Engine (Decide/Clarity) — user creates a goal and feels invested, but can't access the full system +- Reframe history (last 7 days only) +- Basic streak tracking +- All research citations accessible + +**Premium ($8/month or $60/year):** +- Unlimited reframes (soft limit 20/day, hard limit 50/day) +- Full 6-step Manifestation Engine +- Complete reframe history + pattern analysis +- Weekly AI summaries +- Multiple active manifestations (up to 5 concurrent goals) +- Audio visualizations (when available) +- Priority AI response (Sonnet for all calls vs. Haiku for free tier) + +### Pricing Strategy + +- **$8/month** — The "coffee a week" mental anchor. Positioned against therapy ($200+/session) and coaching ($100+/session). +- **$60/year** ($5/month effective) — 25% discount incentivizes annual commitment. Display prominently as the recommended option. +- **7-day free trial** for premium features — Lets users experience the full Manifestation Engine before committing. +- No lifetime purchase option initially — recurring revenue is more sustainable and aligns with the "daily practice" message. + +### Revenue Projections (Conservative) + +| Metric | Month 3 | Month 6 | Month 12 | +|---|---|---|---| +| Total downloads | 1,000 | 5,000 | 20,000 | +| Free → Premium conversion | 5% | 5% | 5% | +| Paying users | 50 | 250 | 1,000 | +| ARPU (blended monthly/annual) | $6.50 | $6.50 | $6.50 | +| MRR | $325 | $1,625 | $6,500 | +| ARR | $3,900 | $19,500 | $78,000 | + +These are conservative estimates assuming organic growth + basic ASO. Paid acquisition or viral mechanics could significantly accelerate. + +--- + +## 11. Cost Estimates + +### Launch Phase (0-1,000 users) + +| Service | Plan | Cost | +|---|---|---| +| Supabase | Free tier (500MB DB, 50K auth, 500K edge invocations) | $0 | +| Claude API | Pay-as-you-go (~$0.003-0.015/call) | $50-100/mo | +| Expo EAS | Free tier (30 builds/month) | $0 | +| RevenueCat | Free (up to $2,500 MTR) | $0 | +| PostHog | Free tier (1M events/mo) | $0 | +| Apple Developer | Annual fee | $99/yr ($8.25/mo) | +| Google Play Developer | One-time | $25 | +| **Total** | | **~$60-110/mo** | + +### Growth Phase (1,000-10,000 users) + +| Service | Plan | Cost | +|---|---|---| +| Supabase | Pro ($25/mo) | $25/mo | +| Claude API | Increased usage | $100-200/mo | +| Expo EAS | Production ($99/mo) | $99/mo | +| RevenueCat | 1% of revenue after $2.5K MTR | Variable | +| PostHog | Still free tier likely | $0 | +| **Total** | | **~$225-325/mo** | + +### Breakeven Analysis + +At $6.50 ARPU, breakeven on $250/mo infrastructure requires ~39 paying users. With 5% conversion, that's ~780 total users. Achievable within the first 2-3 months with moderate marketing effort. + +--- + +## 12. Implementation Roadmap + +### Phase 1 — MVP: The Reframer (4-6 weeks) + +**Goal:** Ship the core reframing feature. Get it into users' hands. Validate the concept. + +**Week 1-2: Foundation** +- Initialize Expo project with TypeScript +- Set up Supabase project (database, auth, edge functions) +- Implement auth flow (email + Google + Apple Sign-In) +- Create database tables and RLS policies +- Build basic navigation structure (tab navigator: Home, Reframe, History, Profile) + +**Week 2-3: Onboarding** +- Welcome screens (swipeable intro cards) +- Reframe style selection (5 styles with example previews) +- Notification time picker +- Profile creation flow + +**Week 3-4: Core Reframer** +- Text input screen for negative thoughts +- Supabase Edge Function: `/reframe` — takes thought + user context, calls Claude, returns reframe +- Reframe display card (with the three-part structure: acknowledge → reframe → micro-action) +- "Why This Works" expandable science section +- Save reframe to database +- "Try Different Style" button (re-call with different style) + +**Week 4-5: History & Streaks** +- Reframe history list (chronological, filterable by category) +- Basic streak counter (current + longest) +- Daily reframe counter (enforce free tier limit) +- Push notification for daily check-in + +**Week 5-6: Polish & Internal Testing** +- Error handling and loading states +- Offline support (queue reframe requests) +- App icon, splash screen, basic branding +- Internal TestFlight / Google Play internal testing + +### Phase 2 — Manifestation Engine (4-6 weeks) + +**Goal:** Build the full 6-step goal system. This is the premium feature. + +**Week 7-8: Goal Creation Wizard (Steps 1-3)** +- Conversational AI flow for Step 1 (Decide) — multi-turn chat interface +- Visualization script generation for Step 2 (See It) +- Self-efficacy barrier identification for Step 3 (Believe) +- Save manifestation with all generated content + +**Week 9-10: Daily System (Steps 4-5)** +- Attention prompts (push notifications with goal-specific prompts) +- Evidence journal (log observations) +- Daily if-then action generation and tracking +- Check-off interface with streak integration + +**Week 10-11: Compound & Summary (Step 6)** +- Progress dashboard (visual timeline of actions, evidence, streaks) +- Weekly AI summary generation (cron job + display) +- Milestone celebrations + +**Week 11-12: Subscription Gate** +- RevenueCat integration (iOS + Android) +- Paywall screen (appears when free user tries to access Steps 2-6) +- Premium entitlement checks throughout the app +- 7-day free trial flow +- Restore purchases functionality + +### Phase 3 — Polish & Launch (2-4 weeks) + +**Week 13-14: App Store Preparation** +- App Store screenshots and preview video +- App Store description (ASO-optimized) +- Privacy policy and terms of service +- App Store review compliance check +- Submit to Apple App Store and Google Play + +**Week 14-16: Launch & Iteration** +- Analytics integration (PostHog events for all key actions) +- Crash reporting (Sentry or similar) +- Bug fixes from beta feedback +- Web version deployment (Expo Web → Vercel/Netlify) +- First marketing push + +### Phase 4 — Growth Features (Ongoing) + +- Voice input for quick reframes (Expo Audio → Whisper API or native STT) +- Audio visualization scripts (TTS generation, downloadable) +- Community features (anonymous sharing of reframes and wins) +- Pattern analysis dashboard (deeper insights into thought patterns) +- Widget support (iOS/Android home screen widget showing streak + daily prompt) +- Dark mode +- Multi-language support + +--- + +## 13. Building with Claude Code & Codex + +This section provides the exact workflow for building the app using AI-assisted development tools. + +### Development Environment Setup + +```bash +# 1. Install Node.js (LTS version) +# Download from https://nodejs.org or use nvm: +nvm install --lts +nvm use --lts + +# 2. Install Expo CLI +npm install -g @expo/cli + +# 3. Create the project +npx create-expo-app@latest [app-name] --template tabs +cd [app-name] + +# 4. Install core dependencies +npx expo install @supabase/supabase-js +npx expo install expo-secure-store # For secure token storage +npx expo install expo-notifications # Push notifications +npx expo install react-native-purchases # RevenueCat +npx expo install expo-av # Audio playback (future) + +# 5. Install navigation & UI +npx expo install @react-navigation/native @react-navigation/bottom-tabs +npx expo install react-native-screens react-native-safe-area-context + +# 6. Development dependencies +npm install -D typescript @types/react +``` + +### Claude Code Workflow + +Claude Code (the CLI tool) is ideal for this project. Here's how to use it effectively: + +**Project initialization prompt:** +``` +I'm building a React Native + Expo app with Supabase backend. +The app is a science-backed manifestation tool with two core features: +1. AI-powered thought reframing (user inputs negative thought → Claude API reframes it) +2. A 6-step goal achievement system + +Tech stack: Expo (TypeScript), Supabase (Postgres + Edge Functions + Auth), Claude API. +Monetization: Freemium with RevenueCat. + +Start by setting up the project structure, Supabase client configuration, +and auth flow (email + Google + Apple Sign-In). +``` + +**Iterative development approach:** +1. Describe the feature you want to build +2. Let Claude Code scaffold the files +3. Review and test +4. Iterate with specific refinements +5. Move to next feature + +**Recommended Claude Code commands for this project:** +```bash +# Start Claude Code in the project directory +claude + +# Example prompts for each phase: + +# Auth setup +"Set up Supabase auth with email, Google, and Apple Sign-In. +Create a useAuth hook and an AuthContext provider." + +# Reframer +"Create the reframe input screen with a text area, submit button, +and loading state. It should call a Supabase Edge Function at /reframe." + +# Edge Function +"Write a Supabase Edge Function that takes a negative thought and user's +reframe style preference, calls the Claude API with a system prompt for +thought reframing, and returns the structured response." + +# Database +"Generate the SQL migration for creating the reframes table with RLS policies." +``` + +### Codex (OpenAI) Workflow + +Codex can be used alongside Claude Code for: +- Generating boilerplate React Native components +- Writing database migration scripts +- Creating test files +- Generating TypeScript types from the schema + +**Complementary usage:** Use Claude Code for architecture decisions and complex logic. Use Codex for repetitive scaffolding and boilerplate generation. They don't conflict — they complement. + +### File Structure + +``` +[app-name]/ +├── app/ # Expo Router file-based routing +│ ├── (tabs)/ # Tab navigator screens +│ │ ├── index.tsx # Home / Dashboard +│ │ ├── reframe.tsx # Reframe input screen +│ │ ├── goals.tsx # Manifestation Engine +│ │ ├── history.tsx # Reframe history +│ │ └── profile.tsx # Settings & profile +│ ├── (auth)/ # Auth screens +│ │ ├── login.tsx +│ │ ├── register.tsx +│ │ └── onboarding.tsx +│ ├── reframe/ +│ │ └── [id].tsx # Individual reframe detail +│ ├── manifestation/ +│ │ ├── create.tsx # Goal creation wizard +│ │ └── [id].tsx # Goal detail / dashboard +│ └── _layout.tsx # Root layout +├── components/ +│ ├── ui/ # Generic UI components +│ │ ├── Button.tsx +│ │ ├── Card.tsx +│ │ ├── TextInput.tsx +│ │ └── LoadingSpinner.tsx +│ ├── reframe/ +│ │ ├── ReframeCard.tsx # Displays a reframe result +│ │ ├── StyleSelector.tsx # Reframe style picker +│ │ └── PatternInsight.tsx # Pattern analysis display +│ ├── manifestation/ +│ │ ├── StepProgress.tsx # 6-step progress indicator +│ │ ├── ActionCard.tsx # Daily action card +│ │ └── EvidenceEntry.tsx # Attention log entry +│ └── shared/ +│ ├── ScienceDrawer.tsx # "Why This Works" expandable +│ └── StreakBadge.tsx # Streak display component +├── hooks/ +│ ├── useAuth.ts # Authentication hook +│ ├── useReframe.ts # Reframe CRUD operations +│ ├── useManifestation.ts # Goal CRUD operations +│ ├── useStreak.ts # Streak tracking +│ └── useSubscription.ts # RevenueCat integration +├── lib/ +│ ├── supabase.ts # Supabase client init +│ ├── constants.ts # App-wide constants +│ └── types.ts # TypeScript interfaces +├── contexts/ +│ ├── AuthContext.tsx # Auth state provider +│ └── SubscriptionContext.tsx # Premium status provider +├── supabase/ +│ ├── migrations/ # SQL migration files +│ │ ├── 001_create_profiles.sql +│ │ ├── 002_create_reframes.sql +│ │ ├── 003_create_manifestations.sql +│ │ ├── 004_create_daily_actions.sql +│ │ ├── 005_create_attention_logs.sql +│ │ ├── 006_create_streaks.sql +│ │ └── 007_create_weekly_summaries.sql +│ └── functions/ # Edge Functions +│ ├── reframe/index.ts +│ ├── generate-plan/index.ts +│ ├── generate-visualization/index.ts +│ ├── weekly-summary/index.ts +│ └── check-subscription/index.ts +├── assets/ +│ ├── images/ +│ └── fonts/ +├── app.json # Expo config +├── tsconfig.json +└── package.json +``` + +--- + +## 14. App Store Strategy + +### App Store Optimization (ASO) + +**Primary keywords to target:** +- "manifestation app" +- "reframe negative thoughts" +- "positive thinking app" +- "goal setting app" +- "science-based self help" +- "thought reframing" +- "daily affirmation" (high volume, position as the "scientific" alternative) + +**App Store title format:** +`[App Name] — Science-Backed Manifestation` + +**Subtitle (30 chars):** +`Reframe Thoughts. Achieve Goals.` + +**Description strategy:** +Lead with the unique differentiator (science-backed), include social proof (research citations), address the skeptic ("not another woo-woo app"), and end with clear feature list. + +### Review Strategy + +- Prompt for review after the user's 7th reframe (proven they find value) +- Never prompt during or after a negative reframe (bad timing) +- Prompt after completing Step 1 of a manifestation (feeling accomplished) + +### Privacy & Compliance + +- All data encrypted at rest (Supabase handles this) +- GDPR compliance: data export and deletion capability +- No third-party data sharing +- Mental health disclaimer: "This app is not a substitute for professional therapy or medical advice" +- Terms of service clearly stating AI-generated content limitations +- Age gate: 17+ (due to AI-generated content about potentially sensitive thoughts) + +--- + +## 15. Growth & Future Features + +### Phase 4+ Feature Ideas (Prioritized) + +**High Impact / Lower Effort:** +1. **iOS/Android widget** — Home screen widget showing streak count + "Reframe Now" button. Reduces friction to zero. +2. **Dark mode** — Table stakes for a daily-use app. +3. **Voice input** — Speak your thought instead of typing. Uses Expo Audio + speech-to-text. +4. **Share reframes** — Export a reframe as a beautiful card image for social sharing (viral loop). + +**High Impact / Higher Effort:** +5. **Audio visualizations** — Text-to-speech generation of visualization scripts. Users can listen during meditation or commute. +6. **Community** — Anonymous sharing of reframes and wins. Based on Granovetter's weak ties research. Users see how others transformed similar thoughts. +7. **Pattern dashboard** — Deep analytics on thought categories, time patterns, sentiment trends. "Your catastrophizing has decreased 40% since you started." +8. **Partner/friend feature** — Invite someone to share streaks and encourage each other (optional, privacy-first). + +**Moonshot / Future:** +9. **AI-generated daily podcast** — Personalized 3-minute audio each morning based on current goals and recent patterns. +10. **Integration with calendar** — Auto-schedule if-then actions as calendar blocks. +11. **Wearable integration** — Apple Watch / WearOS app for quick-flip reframes. +12. **Therapist dashboard** — Optional feature where users can share their reframe/goal data with their actual therapist. + +### Potential Pivots / Expansions + +- **B2B:** Corporate wellness programs (companies buy bulk subscriptions for employees) +- **Education:** Student-focused version for schools/universities +- **Coaching platform:** Let certified coaches use the app as a tool with their clients, with shared dashboards + +--- + +## 16. Naming Candidates + +The app name is TBD. Here are the current candidates explored and their status: + +### Taken / Conflicts + +| Name | Issue | +|---|---| +| Reframe | Multiple apps (alcohol reduction, AI mental health, mindfulness) | +| MindShift | Existing CBT-based anxiety app | +| Prism | Multiple apps | +| Forge / MindForge | Various tech companies | +| Lumen | Metabolism tracker app | +| Myndset | Multiple companies (therapeutics, ideation) | +| Neurashift | AI consulting company | +| Mentavi | ADHD diagnostic platform | +| Soteria | Psychiatric treatment term | +| GrowMind | IT solutions + e-learning | +| Mindrift | AI freelance platform | + +### Current Shortlist (Availability Needs Final Verification) + +**Clareo** +- Latin: "clareo" = to be bright, to be clear +- Pronunciation: "cla-REE-oh" +- Directly connects to Step 1 (Clarity) +- Premium, international sound +- Existing "Clareo" entities are in B2B consulting (Chicago) and LED lighting (France) — zero overlap with self-help/wellness app category +- Status: Clean in app stores for our category + +**Crux** +- English: the decisive or most important point +- "Getting to the crux of the matter" +- Short, strong, memorable, easy to spell +- Existing "Crux" apps: education (India) and rock climbing — different categories +- Status: Clean in app stores for our category + +**Cairn** (previously top recommendation) +- Metaphor: Stone stacks hikers build to mark paths +- Meaning: Small daily actions stacking up, guiding forward +- Strong visual branding potential (stackable stones logo) +- Maps to Step 6 (Repeat and compound) +- Status: Need to verify + +**Anneal** +- Metallurgy: heat and slowly cool metal to strengthen it +- Perfect metaphor for thought transformation (heat = challenge, cooling = reframing, result = stronger) +- Intellectual, science-forward brand positioning +- Status: Need to verify + +### Other Viable Directions Worth Exploring + +- Verge — "on the verge of change" +- Tether — grounded in reality +- Lucen — Latin "lucere" (to shine) +- Patina — beauty developed over time +- Aperion — Greek "infinite potential" +- Novis — Latin "new" + +--- + +## 17. Research References + +### Full Citation List with Open Access Links + +1. **Locke, E.A. & Latham, G.P. (2002).** Building a Practically Useful Theory of Goal Setting and Task Motivation: A 35-Year Odyssey. *American Psychologist, 57*(9), 705-717. [PDF](https://med.stanford.edu/content/dam/sm/s-spire/documents/PD.locke-and-latham-retrospective_Paper.pdf) + +2. **Locke, E.A., Latham, G.P., et al.** New Directions in Goal-Setting Theory. [PDF](https://www.lyondellbasell.com/4aeca6/globalassets/sustainability/lifebeats/advancing-health/life/goals/newdirectioningoalsetting_locke-et-al..pdf) + +3. **Gollwitzer, P.M. (1999).** Implementation Intentions: Strong Effects of Simple Plans. *American Psychologist, 54*(7), 493-503. [PDF](https://prospectivepsych.org/sites/default/files/pictures/Gollwitzer_Implementation-intentions-1999.pdf) + +4. **Gollwitzer, P.M. (2006).** Implementation Intentions and Goal Attainment. [Chapter PDF](https://cancercontrol.cancer.gov/sites/default/files/2020-06/goal_intent_attain.pdf) + +5. **Schuster, C., Hilfiker, R., Amft, O., et al. (2011).** Best Practice for Motor Imagery: A Systematic Literature Review on Motor Imagery Training Elements in Five Different Disciplines. *BMC Medicine, 9*, 75. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC3141540) + +6. **Liu, Y., et al. (2025).** Effects of Imagery Practice on Athletes' Performance. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC12109254) + +7. **Seok, H., et al. (2023).** Mental Practice in Stroke Rehabilitation: A Systematic Review and Meta-Analysis. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC10689861) + +8. **Bandura, A. (1977).** Self-Efficacy: Toward a Unifying Theory of Behavioral Change. *Psychological Review, 84*(2), 191-215. [PDF](https://educational-innovation.sydney.edu.au/news/pdfs/Bandura%201977.pdf) + +9. **Yantis, S. (2008).** The Neural Basis of Selective Attention: Cortical Sources and Targets of Attentional Modulation. *Current Directions in Psychological Science, 17*(2), 86-90. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC2681259) + +10. **Stevens, C. & Bavelier, D. (2012).** The Role of Selective Attention on Academic Foundations: A Cognitive Neuroscience Perspective. *Developmental Cognitive Neuroscience, 2*, S30-S48. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC3375497) + +11. **Koch, C. & Tsuchiya, N. (2007).** Attention and Consciousness: Two Distinct Brain Processes. *Trends in Cognitive Sciences, 11*(1), 16-22. [PDF](https://philarchive.org/archive/KOCAAC-2) + +12. **Wood, W., Mazar, A. & Neal, D.T. (2021).** Habits and Goals in Human Behavior: Separate but Interacting Systems. *Perspectives on Psychological Science, 17*(2), 590-605. [PDF](https://dornsife.usc.edu/wendy-wood/wp-content/uploads/sites/183/2023/10/Wood.Mazar_.Neal_.2021.pdf) + +13. **Wood, W. & Neal, D.T. (2007).** A New Look at Habits and the Habit-Goal Interface. *Psychological Review, 114*(4), 843-863. [Academia](https://www.academia.edu/1237676/A_new_look_at_habits_and_the_habit_goal_interface) + +14. **Granovetter, M.S. (1973).** The Strength of Weak Ties. *American Journal of Sociology, 78*(6), 1360-1380. [PDF](https://snap.stanford.edu/class/cs224w-readings/granovetter73weakties.pdf) + +15. **Pardo-Cabello, A.J., et al. (2022).** Placebo and Nocebo Effects and Mechanisms Associated with Pharmacological Interventions. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC9361274) + +16. **Stetler, D.A., et al. (2013).** The Role of Expectations in Treatment Outcome and the Placebo/Nocebo Effect. [PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC3851940) + +--- + +## 18. Appendix: AI Prompt Templates + +### Reframe System Prompt + +``` +You are a thought reframing assistant inside a science-backed personal +transformation app. Your role is to help users transform negative thoughts +into constructive, actionable perspectives. + +USER'S PREFERRED STYLE: {{reframe_style}} + +STYLE DEFINITIONS: +- brutal_honesty: Direct, no-nonsense. Challenge cognitive distortions bluntly + but with respect. Don't sugarcoat. +- gentle_coach: Warm, empathetic. Always validate feelings first. Use + encouraging language while gently shifting perspective. +- logical_analyst: Structured, evidence-based. Use CBT-style questioning. + Identify logical fallacies in the thought pattern. +- philosophical: Big-picture thinking. Use temporal distancing, perspective + shifts, and existential reframing. +- humor: Light, disarming. Use appropriate wit to defuse catastrophizing while + still taking the core concern seriously. + +RESPONSE STRUCTURE (always follow this): +1. ACKNOWLEDGE: Start by validating the feeling (1-2 sentences). Never dismiss. +2. REFRAME: Provide the perspective shift in your style (3-5 sentences). + Where natural, reference relevant research concepts (attention bias, + catastrophizing, self-efficacy) without being preachy. +3. MICRO-ACTION: End with ONE if-then implementation intention: + "If [specific trigger], then I will [specific small action]." + +CRITICAL RULES: +- NEVER use toxic positivity ("everything happens for a reason", "just think + positive", "the universe has a plan") +- NEVER minimize real problems (grief, abuse, discrimination, health crises) +- If the thought describes a genuinely dangerous or crisis situation, + acknowledge it seriously and suggest professional support +- Keep responses under 200 words +- Do not use bullet points or numbered lists in the response body +- Sound human, not like a chatbot +- Use "you" not "the user" + +CONTEXT (if available): +- User's recent reframe categories: {{recent_categories}} +- Recurring patterns: {{patterns}} +- Active manifestation goals: {{active_goals}} +``` + +### Goal Creation Wizard System Prompt (Step 1: Decide) + +``` +You are a goal-setting guide inside a science-backed manifestation app. +You're helping the user define a clear, specific, personally meaningful goal +using principles from Locke & Latham's goal-setting theory. + +This is a CONVERSATIONAL flow. Ask ONE question at a time. Be warm and +curious, not clinical. Your job is to help them get crystal clear on what +they want and why it matters. + +CONVERSATION FLOW: +1. Ask what they want to achieve (open-ended) +2. Ask why this matters to them personally (emotional connection) +3. Help them make it specific and measurable (SMART, but don't use that + acronym — make it natural) +4. Help them set a realistic but challenging timeframe +5. Summarize their goal as a "Clarity Statement" — a 1-2 sentence + declaration that is specific, personally meaningful, and time-bound + +RULES: +- One question per response. Keep it conversational. +- Don't lecture about goal-setting theory. Just apply it naturally. +- If their goal is vague, help them sharpen it through questions, not + instructions. +- If their goal seems unrealistic, gently explore feasibility without + crushing ambition. Ask about intermediate milestones. +- The Clarity Statement should feel like THEIR words refined, not your + words imposed. +- Keep responses under 100 words per exchange. +``` + +### Visualization Script System Prompt (Step 2: See It) + +``` +You are generating a personalized visualization script for the user's goal. +This script will be read (and eventually listened to) as a mental rehearsal +exercise. + +GOAL: {{clarity_statement}} +WHY IT MATTERS: {{why_it_matters}} + +VISUALIZATION PRINCIPLES (from Schuster et al., 2011): +- First person perspective ("I am..." not "You are...") +- Sensory-rich: include visual, auditory, kinesthetic, and emotional details +- Process-focused: visualize the ACTIONS and JOURNEY, not just the outcome +- Realistic: include small challenges that are overcome (builds resilience) +- Present tense: written as if happening right now + +FORMAT: +- 300-500 words +- Written as a guided meditation script +- Begin with a grounding instruction ("Take a deep breath...") +- Move through the process of achieving the goal +- End with the emotional state of having achieved it +- Close with a return to the present moment + +TONE: Calm, vivid, personal. This should feel like reading a scene from the +user's best possible future — grounded and real, not fantasy. +``` + +### Weekly Summary System Prompt + +``` +You are generating a weekly transformation report for a user of a science- +backed manifestation app. Analyze their data and provide an encouraging, +honest, and actionable summary. + +USER DATA FOR THIS WEEK: +- Reframes completed: {{reframe_count}} +- Reframe categories: {{category_breakdown}} +- Average sentiment shift: {{sentiment_delta}} +- Active manifestation(s): {{active_goals}} +- Daily actions completed: {{actions_completed}} / {{actions_total}} +- Attention logs recorded: {{attention_count}} +- Current streak: {{streak_count}} days +- Comparison to last week: {{week_over_week}} + +RESPONSE STRUCTURE: +1. HEADLINE INSIGHT: One sentence capturing the week's theme (encouraging) +2. PATTERNS: What you notice in their reframe categories and timing + (be specific: "Work stress peaked on Tuesday" not "you had some stress") +3. PROGRESS: Goal achievement metrics with genuine encouragement +4. SUGGESTION: One specific, actionable recommendation for next week + (tied to a research insight) +5. MOTIVATION: Close with something that connects their daily effort to + their bigger goal + +RULES: +- Be honest. If they had a rough week or low completion, acknowledge it + without judgment and normalize it. +- Use specific numbers from their data. +- Keep under 250 words. +- Never use generic platitudes. Every sentence should be specific to THIS + user's data. +``` + +--- + +## Document History + +| Version | Date | Changes | +|---|---|---| +| 1.0 | 2026-02-09 | Initial comprehensive blueprint | + +--- + +*This document is a living blueprint. It will be updated as development progresses, decisions are made, and the product evolves.* + +*Built with 🧠 science + 🤖 AI + 💪 daily action* diff --git a/docs/kalei-brand-guidelines.md b/docs/kalei-brand-guidelines.md new file mode 100644 index 0000000..81707ee --- /dev/null +++ b/docs/kalei-brand-guidelines.md @@ -0,0 +1,1288 @@ +# Kalei — Brand Guidelines + +### Version 1.0 · February 2026 + +> *A kaleidoscope for your mind. Same pieces. New angle.* + +This document defines how Kalei looks, sounds, and feels across every touchpoint — from a push notification to a billboard. It is the single source of truth for anyone designing, writing, coding, or marketing anything that carries the Kalei name. + +--- + +# Table of Contents + +1. Brand Foundation +2. Logo & Wordmark +3. Color System +4. Typography +5. Iconography & Visual Elements +6. Pattern System +7. Photography & Imagery +8. Layout & Spacing +9. Motion & Animation +10. Voice & Tone +11. Writing Guidelines +12. UI Component Standards +13. App Store & Marketing +14. Social Media +15. Email & Notifications +16. Accessibility +17. Brand Misuse +18. Asset Checklist + +--- +--- + +# 1. Brand Foundation + +## 1.1 Brand Story + +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. + +This isn't toxic positivity. A kaleidoscope doesn't pretend the glass isn't broken. It proves that broken things can still be beautiful. + +## 1.2 Mission + +To help people see their lives from new angles — turning negative thought patterns into genuine perspectives that are grounded, actionable, and beautiful. + +## 1.3 Vision + +A world where changing the angle is a reflex — where people instinctively look for the pattern in the fragment, the opportunity in the setback, the facet they haven't considered yet. + +## 1.4 Brand Positioning + +**Category:** AI-powered mental wellness +**For:** People who want to think clearer, not just feel better +**Unlike:** Meditation apps (passive relaxation) or therapy platforms (clinical treatment) +**Kalei is:** An active tool for seeing your life from new angles — grounded in cognitive science, powered by AI, wrapped in beauty + +## 1.5 Brand Personality + +| Trait | What it means | What it doesn't mean | +|-------|--------------|---------------------| +| **Wise** | Sees beauty in hard things, offers genuine perspective | Preachy, lecturing, condescending | +| **Warm** | Feels like a caring friend, never clinical | Saccharine, bubbly, over-eager | +| **Grounded** | Rooted in science and reality, no false promises | Dry, academic, boring | +| **Poetic** | Finds the right words, values beauty in language | Flowery, pretentious, vague | +| **Confident** | Knows what it is, doesn't over-explain or apologize | Aggressive, arrogant, dismissive | +| **Calm** | Steady presence, never frantic or urgent | Passive, sleepy, disengaged | + +**If Kalei were a person:** A quiet, thoughtful friend who always seems to notice what you missed — not because they're smarter than you, but because they look from a different angle. They don't tell you everything will be fine. They show you what's already fine that you couldn't see. + +## 1.6 Brand Values + +1. **Angles over answers** — We show new perspectives. We don't prescribe solutions. +2. **Beauty in the broken** — We believe hard things contain beauty. We never hide the hard part. +3. **Clarity over comfort** — We'd rather give you a real perspective than a comfortable lie. +4. **Science under poetry** — Every feature is grounded in cognitive behavioral science. The poetry is how we deliver it. +5. **Respect over rescue** — We treat users as capable people having a hard moment, not broken people who need saving. + +## 1.7 Core Metaphor System + +| Optical Element | Feature | Role | +|----------------|---------|------| +| **Mirror** | The Mirror | Reflects your thoughts back so you can see patterns | +| **Kaleidoscope** | The Kaleidoscope (Turn) | Takes fragments and reveals beautiful patterns | +| **Lens** | The Lens | Focuses your vision on what you're building toward | +| **Prism** | The Spectrum | Separates your experience into its full emotional range | + +--- +--- + +# 2. Logo & Wordmark + +## 2.1 Primary Logo + +The Kalei logo consists of two elements: + +1. **The Mark** — A geometric, faceted symbol that suggests a kaleidoscope viewed from the front. It should feel crystalline, symmetrical, and luminous. Abstract enough to scale to a favicon, detailed enough to be recognizable at billboard size. + +2. **The Wordmark** — "Kalei" set in a clean geometric sans-serif with subtle angular characteristics. The letterforms should echo the faceted quality of the mark — no rounded terminals, slightly sharp joints. + +**Logo lockup options:** +- **Stacked:** Mark above wordmark (primary, use for app icon and centered layouts) +- **Horizontal:** Mark left of wordmark (use for headers, navigation bars, partnerships) +- **Wordmark only:** For contexts where the mark is already present (in-app, after brand recognition is established) +- **Mark only:** For favicons, app icons, loading states, and small-format contexts + +## 2.2 Logo Clear Space + +Minimum clear space around the logo equals the height of the "K" in the wordmark on all sides. No other elements, text, or imagery may enter this space. + +## 2.3 Logo Sizing + +| Context | Minimum width | +|---------|--------------| +| App icon | 1024×1024px (source), renders at all standard sizes | +| Favicon | 32×32px (mark only) | +| In-app header | 120px wide (horizontal lockup) | +| Social media avatar | 400×400px (mark only) | +| Print (business card) | 1 inch wide minimum | +| Print (large format) | No maximum | + +## 2.4 Logo Color Variations + +| Variant | Usage | +|---------|-------| +| **Full color on dark** | Primary. Prismatic mark + white wordmark on dark backgrounds. Default for all digital. | +| **Full color on light** | Prismatic mark + deep navy wordmark on light backgrounds. Use sparingly — Kalei is a dark-first brand. | +| **Monochrome white** | Mark + wordmark in white. For overlays on photography, video, dark UI contexts. | +| **Monochrome dark** | Mark + wordmark in Kalei Navy. For print on white paper, legal documents, partnerships. | + +**Never:** +- Place the full-color logo on a busy or patterned background +- Recolor the mark in non-brand colors +- Add shadows, glows, or effects to the logo +- Stretch, rotate, or distort the logo +- Recreate the wordmark in a different typeface +- Place the logo on backgrounds that don't provide sufficient contrast + +## 2.5 App Icon + +The app icon uses the **mark only** on a deep navy (#0A0E1A) background. The mark should fill approximately 65-70% of the icon area. The mark uses the prismatic gradient (see Color System). Apply standard iOS/Android corner radius masking. + +No text in the app icon. No borders. No additional decoration. + +--- +--- + +# 3. Color System + +## 3.1 Design Philosophy + +Kalei's color system is inspired by light passing through glass — jewel tones that glow against darkness. This is not a typical wellness app palette. No pastels. No sage green. No cream. Kalei is dark, rich, and luminous. + +A kaleidoscope works by reflecting light against a dark interior. The dark backgrounds are the tube. The jewel tones are the fragments catching light. + +## 3.2 Primary Palette + +### Background Colors + +| Name | Hex | RGB | Usage | +|------|-----|-----|-------| +| **Void** | `#050508` | 5, 5, 8 | Deepest background. Main app background. | +| **Kalei Navy** | `#0A0E1A` | 10, 14, 26 | Primary surface color. Cards, sheets, modals. | +| **Deep Glass** | `#121628` | 18, 22, 40 | Elevated surfaces. Active states. Input fields. | +| **Twilight** | `#1C2240` | 28, 34, 64 | Subtle borders, dividers, inactive elements. | + +### Jewel Tones (Fragment Colors) + +| Name | Hex | RGB | Usage | +|------|-----|-----|-------| +| **Amethyst** | `#8B5CF6` | 139, 92, 246 | Primary accent. CTAs, interactive elements, links. | +| **Sapphire** | `#3B82F6` | 59, 130, 246 | Information, secondary actions, Turn-related UI. | +| **Emerald** | `#10B981` | 16, 185, 129 | Success states, growth metrics, Lens features. | +| **Ruby** | `#EF4444` | 239, 68, 68 | Error states, destructive actions only. Never for fragment highlighting. | +| **Amber** | `#F59E0B` | 245, 158, 11 | Fragment highlights in Mirror. Warmth. Attention without alarm. | +| **Rose** | `#EC4899` | 236, 72, 153 | Accent for sharing, social features, celebration moments. | + +### Text Colors + +| Name | Hex | RGB | Usage | +|------|-----|-----|-------| +| **Pure Light** | `#FFFFFF` | 255, 255, 255 | Primary text on dark backgrounds. | +| **Soft Light** | `#E2E8F0` | 226, 232, 240 | Secondary text, body copy, descriptions. | +| **Dim Light** | `#94A3B8` | 148, 163, 184 | Tertiary text, timestamps, metadata, placeholders. | +| **Faint Light** | `#475569` | 71, 85, 105 | Disabled text, subtle labels. | + +## 3.3 The Prismatic Gradient + +Kalei's signature visual element. A multi-color gradient that simulates light refracting through a prism. + +**Standard Prismatic Gradient:** +``` +Direction: 135° (top-left to bottom-right) +Stops: + 0% — #8B5CF6 (Amethyst) + 25% — #3B82F6 (Sapphire) + 50% — #10B981 (Emerald) + 75% — #F59E0B (Amber) + 100% — #EC4899 (Rose) +``` + +**Usage:** +- Logo mark fill +- Premium upgrade CTAs ("See the full spectrum") +- Pattern Card borders +- Celebration/milestone moments +- Loading shimmer animation base +- Section dividers (as a thin 2px line) + +**Reduced Prismatic Gradient** (for subtlety): +Same stops at 30% opacity over Kalei Navy. Use for background washes, hover states, and ambient decoration. + +**Never:** +- Use the prismatic gradient for body text +- Apply it to large background areas at full opacity (overwhelming) +- Use it on light backgrounds (loses impact) +- Recreate it with different colors + +## 3.4 Semantic Colors + +| State | Color | Token | +|-------|-------|-------| +| Primary action | Amethyst `#8B5CF6` | `color-action-primary` | +| Secondary action | Sapphire `#3B82F6` | `color-action-secondary` | +| Success | Emerald `#10B981` | `color-success` | +| Warning / Fragment highlight | Amber `#F59E0B` | `color-warning` | +| Error / Destructive | Ruby `#EF4444` | `color-error` | +| Disabled | Twilight `#1C2240` | `color-disabled` | +| Focus ring | Amethyst at 50% opacity | `color-focus` | + +## 3.5 Color Accessibility + +All text/background combinations must meet WCAG 2.1 AA minimum contrast ratios: + +| Combination | Ratio | Passes | +|-------------|-------|--------| +| Pure Light on Void | 19.8:1 | ✓ AAA | +| Pure Light on Kalei Navy | 18.2:1 | ✓ AAA | +| Soft Light on Kalei Navy | 13.1:1 | ✓ AAA | +| Dim Light on Kalei Navy | 6.8:1 | ✓ AA | +| Amethyst on Kalei Navy | 5.2:1 | ✓ AA | +| Amber on Kalei Navy | 8.4:1 | ✓ AAA | + +**Rule:** Never use Jewel Tones for text smaller than 16px. Use Pure Light or Soft Light for body text. Jewel Tones are for accents, icons, and interactive elements. + +## 3.6 Dark Mode / Light Mode + +**Kalei is dark-first.** The primary experience is dark mode. There is no "light mode" in v1. + +If a light mode is introduced in the future, it should invert backgrounds to warm off-whites (`#F8F7F4`) while keeping jewel tones as accents. The prismatic gradient should remain on dark surfaces even in light mode (e.g., dark cards or headers). + +--- +--- + +# 4. Typography + +## 4.1 Type Philosophy + +Kalei's typography is clean and modern with subtle geometric qualities — like cut glass. It should feel precise, not cold. Clear, not clinical. Every letterform is a facet. + +## 4.2 Type Scale + +### Primary Typeface — Headlines & UI + +**Inter** (or equivalent geometric sans-serif: Outfit, Satoshi, or General Sans) + +Selected for: clean geometry, excellent screen rendering, wide weight range, open-source availability. + +### Secondary Typeface — Display & Marketing (Optional) + +**Space Grotesk** (or equivalent: DM Sans, Plus Jakarta Sans) + +Selected for: slightly more personality than Inter, angular terminals that echo the faceted aesthetic, strong at large sizes. + +Use only for marketing headlines, hero text, and App Store screenshots. Never for body text or UI elements. + +## 4.3 Type Scale — App + +| Token | Size | Weight | Line Height | Letter Spacing | Usage | +|-------|------|--------|-------------|---------------|-------| +| `display-xl` | 40px | Bold (700) | 48px | -0.02em | Onboarding hero text | +| `display-lg` | 32px | Bold (700) | 40px | -0.02em | Screen titles | +| `display-md` | 24px | Semibold (600) | 32px | -0.01em | Section headers | +| `heading` | 20px | Semibold (600) | 28px | -0.01em | Card titles, modal headers | +| `subheading` | 16px | Semibold (600) | 24px | 0 | Labels, tab bar, navigation | +| `body-lg` | 17px | Regular (400) | 26px | 0 | Primary body text (iOS default) | +| `body` | 15px | Regular (400) | 22px | 0 | Secondary body text | +| `body-sm` | 13px | Regular (400) | 18px | 0.01em | Captions, metadata, timestamps | +| `label` | 11px | Medium (500) | 16px | 0.05em | Badges, tags, overlines (uppercase) | + +## 4.4 Type Scale — Marketing + +| Token | Size | Weight | Usage | +|-------|------|--------|-------| +| `hero` | 64–80px | Bold | Landing page hero, billboard | +| `headline` | 40–56px | Bold | Section titles, feature headers | +| `subhead` | 24–32px | Regular/Medium | Supporting text under headlines | +| `body` | 18–20px | Regular | Marketing body copy | +| `fine` | 14px | Regular | Legal, footnotes, disclaimers | + +## 4.5 Typography Rules + +1. **Never center body text.** Center alignment is only for headlines, single-line labels, and empty states. +2. **Maximum line width:** 65–75 characters for body text. Longer lines reduce readability. +3. **Use sentence case everywhere.** No Title Case except in the logo wordmark. "Turn a fragment" not "Turn A Fragment." +4. **No all-caps body text.** Uppercase is reserved for `label` token (badges, tags, overlines) only. +5. **Maintain hierarchy.** Every screen should have one clear `display` or `heading` element. Don't use two display sizes in the same view. +6. **Minimum text size:** 13px in-app, 14px on web. Nothing smaller, ever. + +--- +--- + +# 5. Iconography & Visual Elements + +## 5.1 Icon Style + +Kalei icons are **geometric, faceted, and angular.** They suggest crystalline structures — the fragments of glass inside a kaleidoscope. + +**Characteristics:** +- 24×24px base grid with 2px stroke (line icons) +- Straight lines and sharp angles preferred over curves +- Hexagonal and triangular motifs where possible +- Symmetrical when it reinforces the kaleidoscope metaphor +- Consistent 2px corner radius on corners (not fully rounded) + +**Avoid:** +- Rounded, bubbly icon styles (that's every other wellness app) +- Filled icons by default (use filled only for active/selected states) +- Highly detailed or illustrative icons +- Emoji-style icons + +## 5.2 Core Navigation Icons + +| Feature | Icon Description | Active State | +|---------|-----------------|-------------| +| **Turn** (Kaleidoscope) | Geometric diamond/shard — ◇ | Filled with Amethyst gradient | +| **Mirror** | Hexagonal mirror shape — ✦ | Filled with Amber gradient | +| **Lens** | Concentric circles (lens cross-section) — ◎ | Filled with Emerald gradient | +| **Gallery** | Grid of small geometric shapes — ▦ | Filled with Sapphire gradient | +| **You** (Profile) | Angular avatar silhouette — ● | Filled with Soft Light | + +**Active state treatment:** Selected tab icon fills with its assigned Jewel Tone. Unselected icons render in Dim Light (`#94A3B8`). + +## 5.3 Action Icons + +| Action | Icon | Color | +|--------|------|-------| +| Turn (submit reframe) | Rotating diamond | Amethyst | +| Save keepsake | Angular bookmark/gem | Amber | +| Share pattern | Angular arrow-out | Soft Light | +| Expand / Full Turn | Chevron-diamond | Sapphire | +| Dismiss | Angular X | Dim Light | +| Settings gear | Hexagonal gear | Dim Light | +| Streak flame | Angular flame | Amber | + +## 5.4 Fragment Type Icons + +Each cognitive distortion type has a unique small icon used in the Mirror and Spectrum: + +| Distortion | Icon Motif | Reasoning | +|------------|-----------|-----------| +| Catastrophizing | Downward-pointing angular arrow | Predicting the worst | +| Black-and-white | Split diamond (half light, half dark) | All-or-nothing | +| Mind reading | Angular thought bubble | Assuming thoughts | +| Fortune telling | Angular crystal ball / forward arrow | Predicting negative future | +| Personalization | Inward-pointing arrows → center | Taking everything personally | +| Discounting positives | Dimmed/struck-through star | Minimizing good things | +| Emotional reasoning | Heart → equals sign | Feelings as facts | +| Should statements | Rigid angular ruler | Self-imposed rules | +| Labeling | Angular tag/label | Identity-level judgment | +| Overgeneralization | Single dot → many dots | One event to universal | + +These icons are always rendered in Amber (`#F59E0B`) when highlighting fragments and in their respective Jewel Tones in the Spectrum dashboard. + +--- +--- + +# 6. Pattern System + +## 6.1 What Patterns Are + +Every reframing session in Kalei generates a unique, procedurally-created kaleidoscope pattern. These patterns are central to the brand identity — they are the visual proof that broken fragments can become beautiful. + +## 6.2 Pattern Generation Rules + +- **Deterministic:** The same input text always generates the same base pattern (creates personal meaning) +- **Symmetrical:** All patterns exhibit kaleidoscopic symmetry (6-fold or 8-fold rotational) +- **Jewel-toned:** Patterns use colors from the Kalei Jewel Tone palette only +- **Dark-grounded:** Patterns render on Void or Kalei Navy backgrounds +- **Unique:** No two different inputs should produce visually identical patterns + +## 6.3 Pattern Types + +| Source | Visual Style | Save Location | +|--------|-------------|--------------| +| **Turn pattern** | Sharp, geometric, high-contrast. Angular fragments in full symmetry. | Gallery → Turns | +| **Mirror Reflection pattern** | Softer geometry, more 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 | + +## 6.4 Pattern Usage + +| Context | Format | Size | +|---------|--------|------| +| In-app Gallery tile | Square | 360×360px | +| Pattern Card (Instagram Story) | 9:16 | 1080×1920px | +| Pattern Card (Feed/Square) | 1:1 | 1080×1080px | +| Pattern Card (iMessage) | ~3:2 | 1200×800px | +| Onboarding animation | Full screen | Device resolution | +| Marketing / print | Vector (SVG) | Scalable | + +## 6.5 Pattern Card Layout + +Pattern Cards are shareable images generated when a user saves a keepsake. Layout: + +``` +┌──────────────────────────┐ +│ │ +│ │ +│ [Kaleidoscope │ +│ Pattern │ +│ centered, │ +│ 60% of card height] │ +│ │ +│ │ +├──────────────────────────┤ +│ │ +│ "The reframed thought │ +│ goes here in Soft │ +│ Light, centered." │ +│ │ +│ ◇ kalei │ +│ │ +└──────────────────────────┘ + +Background: Void (#050508) +Pattern: Jewel Tones +Text: Soft Light (#E2E8F0), body-lg, centered +Branding: Kalei mark + wordmark in Dim Light, bottom center +``` + +**Rules:** +- Only the reframed thought (pattern) appears on the card — never the original negative thought (fragment) +- Maximum 2 lines of text. If the reframe is longer, truncate with "..." +- The Kalei branding is subtle (Dim Light, small) — the pattern and reframe are the heroes + +--- +--- + +# 7. Photography & Imagery + +## 7.1 Photography Style + +Kalei uses photography sparingly — the brand's visual identity is built on patterns, geometry, and color, not photos. When photography is used (marketing, App Store, social media), it should follow these guidelines: + +**Mood:** Contemplative, still, luminous. Moments of quiet clarity — not action shots. + +**Subjects:** +- Light interacting with objects: prisms, glass, water surfaces, crystal formations +- Macro/close-up abstract textures: faceted gems, ice, refracted light +- People in moments of quiet reflection (never staged positivity, never cheering/jumping) +- Architecture with geometric patterns and symmetry +- Natural landscapes at transitional moments: dawn, dusk, golden hour + +**Treatment:** +- Dark and moody with selective areas of vivid color +- High contrast between dark backgrounds and illuminated subjects +- Desaturated overall with selective jewel-tone color grading +- Shallow depth of field to create a "looking through a lens" feeling + +**Avoid:** +- Stock photo energy (diverse group laughing around laptop) +- Bright, flat, evenly-lit scenes +- Nature clichés (sunsets, mountaintops, ocean waves used generically) +- Faces in obvious distress or obvious joy — Kalei lives in the nuanced middle +- Any image that could be mistaken for a meditation app or therapy platform + +## 7.2 Illustration Style + +Kalei does not use illustration in v1. If introduced later, illustrations should be: +- Geometric and angular (consistent with icon style) +- Limited to Kalei color palette +- Abstract or symbolic, never literal or cartoonish +- Used for educational content (explaining CBT concepts) only + +--- +--- + +# 8. Layout & Spacing + +## 8.1 Grid System + +**App (Mobile):** +- 4-column grid +- 16px margins (left and right) +- 12px gutters between columns +- Content width: screen width − 32px + +**Web (Marketing/Landing Page):** +- 12-column grid +- Maximum content width: 1200px +- 24px gutters +- 80px margins on desktop, 24px on tablet, 16px on mobile + +## 8.2 Spacing Scale + +Based on a 4px base unit: + +| Token | Value | Usage | +|-------|-------|-------| +| `space-1` | 4px | Minimal spacing. Between icon and label. | +| `space-2` | 8px | Tight spacing. Between related elements. | +| `space-3` | 12px | Default inner padding. Card padding (compact). | +| `space-4` | 16px | Standard spacing. Between sections, card padding (standard). | +| `space-5` | 20px | Comfortable spacing. | +| `space-6` | 24px | Between distinct content blocks. | +| `space-8` | 32px | Between major sections. Screen padding top/bottom. | +| `space-10` | 40px | Large spacing. Between feature sections. | +| `space-12` | 48px | Hero spacing. Onboarding screen padding. | +| `space-16` | 64px | Maximum spacing. Between landing page sections. | + +## 8.3 Component Sizing + +| Component | Height | Corner Radius | +|-----------|--------|---------------| +| Primary button | 52px | 12px | +| Secondary button | 44px | 10px | +| Text input | 48px | 10px | +| Text area (Mirror) | Auto (min 120px) | 12px | +| Card | Auto | 16px | +| Modal (half-sheet) | Auto (max 70% screen) | 20px (top corners only) | +| Tab bar | 83px (with safe area) | 0px | +| Chip / Tag | 32px | 16px (full pill) | +| Avatar | 40px | 20px (circle) | + +## 8.4 Corner Radius Philosophy + +Kalei uses **moderate corner radii** — not sharp rectangles (too harsh) and not fully rounded (too soft). The corners should feel like faceted glass: slightly softened but still geometric. + +| Element type | Radius | +|-------------|--------| +| Buttons, inputs | 10–12px | +| Cards, modals | 16–20px | +| Chips, tags, pills | Full (height / 2) | +| Icons | 2px | +| App icon | Platform standard (iOS: continuous curve) | + +--- +--- + +# 9. Motion & Animation + +## 9.1 Motion Philosophy + +Kalei's motion design reflects the physics of light and glass: smooth, precise, and mesmerizing without being distracting. Every animation serves a purpose — either providing feedback, guiding attention, or reinforcing the metaphor. + +## 9.2 Timing Curves + +| Curve | Easing | Duration | Usage | +|-------|--------|----------|-------| +| **Standard** | ease-out (0.0, 0.0, 0.2, 1.0) | 200–300ms | Most UI transitions, button feedback | +| **Decelerate** | ease-out (0.0, 0.0, 0.0, 1.0) | 300–400ms | Elements entering the screen | +| **Accelerate** | ease-in (0.4, 0.0, 1.0, 1.0) | 200–250ms | Elements leaving the screen | +| **Dramatic** | ease-in-out (0.4, 0.0, 0.2, 1.0) | 500–800ms | The Turn animation, pattern reveals | +| **Gentle** | ease-out (0.0, 0.0, 0.4, 1.0) | 400–600ms | Fragment highlights appearing, ambient motion | + +## 9.3 Signature Animations + +### The Turn (Core Animation) + +The most important animation in the app. Triggered when a user submits a thought for reframing. + +**Sequence:** +1. **Collapse** (200ms): Input text compresses into a single angular shard (fragment icon) +2. **Multiply** (400ms): The shard duplicates into 6 copies, rotating outward +3. **Crystallize** (600ms): Copies arrange into kaleidoscopic symmetry, colors bloom from center outward +4. **Settle** (300ms): Pattern locks into final position; reframed perspectives fade in beneath + +**Total duration:** ~1.5 seconds. Should feel like one fluid motion, not four discrete steps. + +**Technical:** Implement with React Native Reanimated 2+ or Skia. Not Lottie — needs to be dynamic based on input. + +### Fragment Highlight (Mirror) + +When the AI detects a cognitive distortion in Mirror text: + +1. **Glow** (400ms): Amber underline fades in beneath the detected text, left to right +2. **Pulse** (200ms): A single subtle pulse of brightness, then settles to steady glow +3. **Icon appear** (200ms): Small ◇ fragment icon fades in at the end of the highlight + +**Feel:** Like sunlight falling on a piece of glass — natural, gentle, drawing the eye without shouting. + +### Pattern Card Generation + +When a user saves a keepsake and the Pattern Card generates: + +1. **Fragments scatter** (300ms): Random colored fragments spread across the card area +2. **Coalesce** (600ms): Fragments draw toward center, rotating and aligning +3. **Symmetry snap** (200ms): Pattern locks into final kaleidoscopic arrangement +4. **Text fade** (300ms): Reframed thought fades in below the pattern + +### Loading States + +**Prismatic shimmer:** A slow-moving prismatic gradient sweeps across placeholder elements. Direction: left to right. Speed: 1.5s per cycle. Colors: Reduced prismatic gradient at 20% opacity. + +**Never use:** Spinning circles, bouncing dots, or generic loading indicators. + +## 9.4 Transition Patterns + +| Transition | Animation | Duration | +|-----------|-----------|----------| +| Screen push (forward) | Slide from right + subtle scale (0.97→1.0 on entering, 1.0→0.97 on exiting) | 300ms | +| Screen pop (back) | Reverse of push | 250ms | +| Modal present | Slide up from bottom with backdrop fade | 350ms | +| Modal dismiss | Slide down with backdrop fade | 250ms | +| Tab switch | Crossfade (no slide) | 200ms | +| Card expand | Shared element transition (card → full screen) | 400ms | +| Toast/snackbar | Slide down from top + fade | 300ms in, 200ms out | + +## 9.5 Motion Accessibility + +- **Respect "Reduce Motion"** system setting. When enabled: replace all animations with instant cuts or simple fades (200ms max) +- The Turn animation should degrade to: input disappears → pattern appears with fade (no rotation or multiplication) +- Fragment highlights should appear instantly (no glow animation) +- Loading states should use a static shimmer (no movement) + +--- +--- + +# 10. Voice & Tone + +## 10.1 Brand Voice (Constant) + +Kalei's voice is the personality that remains consistent across all contexts. It never changes. + +**Kalei sounds like:** A wise friend who sees beauty in hard things — not a therapist, not a guru, not a cheerleader. + +**Voice attributes:** +- **Clear** — Say it simply. If a sentence needs re-reading, rewrite it. +- **Warm** — Kindness without softness. Care without coddling. +- **Grounded** — Rooted in reality. No fairy dust. No "everything happens for a reason." +- **Poetic** — When a beautiful phrase captures it better than a plain one, use it. But never at the cost of clarity. +- **Respectful** — The user is a capable person having a hard moment. Not a patient. Not a project. + +## 10.2 Tone (Variable) + +Tone shifts based on context while the voice stays constant. + +| Context | Tone | Example | +|---------|------|---------| +| **Onboarding** | Inviting, intriguing, slightly mysterious | "This is a thought. Change the angle... and the same piece becomes part of something beautiful." | +| **Turn (Reframing)** | Calm, steady, perspective-offering | "Let's see what this looks like from another angle." | +| **Mirror (Highlighting)** | Gentle, observational, non-judgmental | "This sounds like mind reading — assuming someone else's thoughts without evidence." | +| **Lens (Goals)** | Focused, encouraging, forward-looking | "Your focus is getting sharper." | +| **Milestone** | Quiet pride, not celebration overload | "There it is. A pattern worth keeping." | +| **Re-engagement** | Patient, no guilt, always welcoming | "Still here. Ready when you are." | +| **Error state** | Honest, brief, solution-oriented | "Something went wrong. Let's try that Turn again." | +| **Upgrade prompt** | Confident, value-focused, never desperate | "See the full spectrum." | +| **Crisis detection** | Immediate warmth, resourceful, no reframing | "What you're feeling matters. Here are people who can help right now." | + +## 10.3 Tone Calibration + +**The 1-10 scale for emotional weight:** + +| User state | Kalei's tone weight | Example | +|-----------|--------------------|---------| +| Casual/browsing (1-3) | Light, slightly playful | "Ready for today's Turn? 🔮" | +| Processing/reflecting (4-6) | Warm, steady, grounded | "Let's see what this looks like from another angle." | +| Distressed/venting (7-8) | Gentle, careful, deeply respectful | "I noticed a few fragments in what you wrote. Want to look at them together?" | +| In crisis (9-10) | Immediate, warm, resource-focused — **no reframing** | "What you're feeling matters. If you need to talk to someone right now: [crisis resources]" | + +**Critical rule:** Kalei NEVER reframes suicidal ideation, self-harm thoughts, or crisis-level distress. These are not "fragments to be turned." They are signals to provide immediate support resources. + +--- +--- + +# 11. Writing Guidelines + +## 11.1 Vocabulary + +See the complete Brand Vocabulary table in the Brand Metaphor document. Key rules: + +**Always say:** +| Concept | Kalei word | +|---------|-----------| +| Negative thought | Fragment | +| Reframe | Turn | +| Reframed perspective | Pattern | +| Save | Keep / Keepsake | +| Journal session | Reflection | +| History | Gallery | +| Cognitive distortion | Fragment type (in-app) | +| Premium | Prism | + +**Never say:** +- "Fix" (implies user is broken) +- "Heal" (too clinical) +- "Transform" (too dramatic) +- "Positive vibes" (trivializes) +- "Journey" (overused) +- "Self-care" (generic) +- "Unlock your potential" (cliché) +- "You've got this!" (patronizing) + +## 11.2 Grammar & Style + +1. **Sentence case everywhere.** Headlines, buttons, labels, navigation. "Turn a fragment" not "Turn a Fragment" or "TURN A FRAGMENT." +2. **No periods on single-sentence UI text.** Button labels, headlines, toasts, and single-line descriptions omit the period. Multi-sentence body text uses periods. +3. **Use contractions.** "It's" not "It is." "You've" not "You have." Kalei is warm, not formal. +4. **Active voice default.** "Kalei found 3 fragments" not "3 fragments were found by Kalei." +5. **Second person.** "Your Gallery" not "The Gallery." "You turned 10 fragments" not "10 fragments have been turned." +6. **Present tense for actions.** "Turn this fragment" not "Turning this fragment" or "Fragment will be turned." +7. **No exclamation marks in UI text.** The only exceptions: milestone celebrations and streak messages, limited to one per message. +8. **Oxford comma.** Always. "Fragments, patterns, and keepsakes." +9. **Numbers:** Spell out one through nine. Use digits for 10+. Always use digits for stats and data. "You turned 3 fragments" but "Your 10th Turn." +10. **Em dashes over parentheses.** For asides and elaboration. "Your Mirror session — your most honest yet — revealed three new fragments." + +## 11.3 Error Messages + +Error messages should be brief, honest, and never blame the user. + +**Formula:** [What happened] + [What to do next] + +| ❌ Bad | ✅ Good | +|--------|---------| +| "Error 500: Server failure" | "Something went wrong on our end. Try again in a moment." | +| "Invalid input! Please try again." | "We couldn't read that. Try rephrasing your fragment." | +| "Network error" | "Lost connection. Your Turn is saved — we'll send it when you're back online." | +| "You've exceeded your free limit!" | "You've used your 3 free Turns today. Unlock unlimited with Prism, or come back tomorrow." | + +## 11.4 Empty States + +Empty states are moments of opportunity — the first thing a new user sees in each section. + +**Formula:** [Aspirational description of what will be here] + [Light encouragement to take action] + +| Screen | Empty state copy | +|--------|-----------------| +| Gallery | "Your Gallery is waiting. The next pattern you save will appear here." | +| Mirror | "Start writing. Say whatever's on your mind. Kalei will listen." | +| Lens | "What are you focusing on? Set your first Lens." | +| Turn history | "Every kaleidoscope starts with a single Turn." | +| Keepsakes | "No keepsakes yet. When a pattern feels worth keeping, you'll find it here." | + +## 11.5 Microcopy Quick Reference + +| Element | Style | Example | +|---------|-------|---------| +| Button (primary) | 1–3 words, verb-first | "Turn" · "Keep this pattern" | +| Button (secondary) | 1–3 words | "Not now" · "Dismiss" | +| Input placeholder | Question or gentle instruction | "What's the fragment?" · "Start writing" | +| Toast notification | 1 sentence, no period | "Pattern saved to your Gallery" | +| Section header | 1–4 words, sentence case | "Recent patterns" · "Your Glass" | +| Tooltip | 1 sentence explaining function | "Tap a highlighted fragment to see it from a new angle" | + +--- +--- + +# 12. UI Component Standards + +## 12.1 Buttons + +### Primary Button +- Background: Amethyst (`#8B5CF6`) +- Text: Pure Light, `subheading` token (16px Semibold) +- Height: 52px +- Corner radius: 12px +- Padding: 16px horizontal +- Pressed state: Amethyst at 80% brightness +- Disabled state: Twilight background, Faint Light text +- Full-width on mobile by default + +### Secondary Button +- Background: Deep Glass (`#121628`) +- Border: 1px Twilight (`#1C2240`) +- Text: Soft Light, `subheading` token +- Height: 44px +- Corner radius: 10px +- Pressed state: Twilight background + +### Ghost Button +- Background: Transparent +- Text: Amethyst, `subheading` token +- No border +- Pressed state: Amethyst at 10% opacity background + +### Destructive Button +- Background: Ruby (`#EF4444`) at 15% opacity +- Text: Ruby +- Border: 1px Ruby at 30% opacity +- Use only for irreversible actions (delete account, clear Mirror data) + +## 12.2 Input Fields + +- Background: Deep Glass (`#121628`) +- Border: 1px Twilight, transitions to 1px Amethyst on focus +- Text: Pure Light, `body-lg` token +- Placeholder: Dim Light +- Height: 48px (single line), auto-grow for multi-line (Mirror) +- Corner radius: 10px +- Padding: 14px horizontal, 12px vertical + +### Mirror Input (Special) + +- Appears as a chat-style input bar at the bottom of the screen +- Send button: Angular arrow icon in Amethyst +- No character count (unrestricted) +- Auto-grow up to 5 lines before scrolling internally + +## 12.3 Cards + +- Background: Kalei Navy (`#0A0E1A`) +- Border: 1px Twilight (optional, for elevated contexts) +- Corner radius: 16px +- Padding: 16px (standard), 12px (compact) +- Shadow: None (Kalei uses borders and background shifts, not shadows) +- Pressed state: Background shifts to Deep Glass + +### Pattern Card (Gallery) +- Square aspect ratio +- Pattern fills upper 65% +- Fragment type badge: top-left corner, Chip component +- Date: bottom-right, `body-sm` in Dim Light + +### Insight Card (Spectrum) +- Full-width +- Left accent border: 3px in relevant Jewel Tone +- Body text: `body-lg` in Soft Light +- Action: Ghost button aligned right + +## 12.4 Bottom Sheet / Modal + +- Background: Kalei Navy +- Corner radius: 20px (top-left and top-right only) +- Handle: 36×5px pill in Twilight, centered, 8px from top +- Backdrop: Void at 60% opacity +- Max height: 70% of screen +- Scrollable when content exceeds max height + +**Used for:** +- Fragment reframe cards (Mirror tap) +- Turn results (expanded view) +- Keepsake save confirmation +- Settings pickers + +## 12.5 Tab Bar + +- Background: Kalei Navy with subtle top border (1px Twilight) +- Height: 49px + safe area +- Icons: 24×24px +- Labels: `label` token (11px Medium, uppercase) +- Inactive: Dim Light icon + label +- Active: Jewel Tone icon (filled) + Pure Light label +- No badge counts (Kalei doesn't create anxiety about unseen content) + +## 12.6 Chips & Tags + +- Height: 32px +- Corner radius: 16px (full pill) +- Background: Deep Glass +- Text: Soft Light, `body-sm` token +- Fragment type chips: Amber text on Amber at 15% opacity background +- Selection chips: Amethyst border when selected + +## 12.7 Toast / Snackbar + +- Position: Top of screen, below status bar +- Background: Deep Glass with 1px Twilight border +- Text: Soft Light, `body` token +- Duration: 3 seconds, dismissable with swipe up +- Corner radius: 12px +- Max width: screen width − 32px +- No action buttons on toasts. If an action is needed, use a bottom sheet. + +--- +--- + +# 13. App Store & Marketing + +## 13.1 App Store Listing + +**App Name:** Kalei — A new way to see + +**Subtitle (30 chars):** Same pieces. New angle. + +**Keywords:** reframe, perspective, mindset, CBT, mental wellness, journal, AI, thought patterns, positivity, cognitive + +**Category:** Primary: Health & Fitness. Secondary: Lifestyle. + +**App Store Description:** See Brand Metaphor document for full draft. + +## 13.2 Screenshot Style + +App Store screenshots should follow a consistent template: + +- **Background:** Void with subtle prismatic gradient wash +- **Device frame:** Minimal or none (floating screen style) +- **Headline text above screen:** `display-lg` in Pure Light, centered +- **Screen content:** Actual app UI, not mockups +- **Pattern decoration:** Subtle kaleidoscope patterns in corners at low opacity + +**Screenshot sequence (recommended):** +1. "A kaleidoscope for your mind" — Onboarding or hero screen +2. "Turn a fragment" — Kaleidoscope feature with reframe results +3. "The Mirror listens" — Mirror session with highlighted fragments +4. "Your patterns, your Gallery" — Gallery grid view +5. "Focus through the Lens" — Lens/goal feature +6. "Same pieces. New angle." — Brand statement with pattern visual + +## 13.3 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. | + +**Usage guidance:** "Same pieces. New angle." is the primary tagline and should appear in the majority of marketing materials. Other taglines are supporting options for specific contexts (ads, social, feature marketing). + +## 13.4 Boilerplate Descriptions + +**One-liner (10 words):** +Kalei turns negative thoughts into new perspectives. AI-powered. + +**Short (30 words):** +Kalei is a kaleidoscope for your mind. Give it a negative thought and it reveals the beautiful patterns hidden inside — genuine perspective shifts grounded in cognitive science. + +**Medium (75 words):** +Kalei is an AI-powered app that helps you see your life from new angles. Write freely in the Mirror and Kalei highlights the negative patterns you can't see yourself. Take any thought to the Kaleidoscope and see it reframed from multiple perspectives. Focus your clarity through the Lens toward the goals that matter. Every session generates a unique kaleidoscope pattern — building a personal Gallery of the moments you chose to see differently. + +--- +--- + +# 14. Social Media + +## 14.1 Platform Presence + +| Platform | Handle | Primary use | +|----------|--------|------------| +| Instagram | @kalei.app | Pattern Cards, brand visuals, reframe inspiration | +| TikTok | @kalei.app | Short-form demos, "Turn this" challenges, founder content | +| X (Twitter) | @kaleiapp | Product updates, CBT insights, engagement | +| LinkedIn | Kalei | Company updates, hiring, thought leadership | + +## 14.2 Content Pillars + +1. **Pattern of the day** (40%) — Shareable Pattern Cards with powerful reframes. These are the viral mechanic. +2. **Turn this** (25%) — Present a common negative thought and show the Turn. Educational and engaging. +3. **The science behind it** (20%) — Short, accessible explanations of CBT concepts, cognitive distortions, and the psychology of perspective. +4. **Product** (15%) — Feature demos, updates, user testimonials (anonymized), milestone celebrations. + +## 14.3 Social Visual Standards + +- **Background:** Always Void or Kalei Navy. Never white. Never platform defaults. +- **Text overlay:** Pure Light or Soft Light. Maximum 15 words per image. +- **Patterns:** Use real generated patterns, not stock geometric art. +- **No stock photos.** No generic wellness imagery. If photos are used, they follow the Photography guidelines. +- **Video:** Dark backgrounds, jewel-tone accents, subtle motion. No fast cuts or aggressive transitions. + +## 14.4 Hashtag Strategy + +**Branded:** +- #Kalei (primary) +- #TurnIt (for reframe challenges) +- #SamePiecesNewAngle (tagline) +- #KaleiPatterns (for shared patterns) + +**Community:** +- #MindsetShift #PerspectiveShift #CognitiveReframing #MentalWellness #ThinkDifferently + +--- +--- + +# 15. Email & Notifications + +## 15.1 Push Notification Voice + +Push notifications are the most intimate touchpoint — they appear on the user's lock screen alongside messages from real people. They must feel personal, not promotional. + +**Rules:** +- Maximum 60 characters (visible without expanding on most devices) +- No ALL CAPS words +- No exclamation marks (except rare milestone celebrations) +- No guilt-tripping ("We miss you!", "Don't break your streak!") +- One emoji maximum, and only 🔮 (crystal ball — the Kalei emoji) + +**Notification types and cadence:** + +| Type | Frequency | Time | +|------|-----------|------| +| Daily Turn prompt | 1x/day (if user opted in) | User-configured, default 9am | +| Streak maintenance | Only on day 3, 7, 30 milestones | Evening (7pm) | +| Streak at risk | Once, after 36 hours of no activity | Morning (10am) | +| Weekly Spectrum | 1x/week (Prism users) | Sunday 6pm | +| Feature announcement | Max 1x/month | Varies | +| Re-engagement | Once after 7 days inactive, once after 30 | Morning (10am) | + +**Never send more than 1 push notification per day.** + +## 15.2 Email Design + +- **From name:** Kalei +- **From address:** hello@kalei.ai +- **Template:** Dark background (Void), single column, 600px max width +- **Logo:** Horizontal lockup, full-color on dark, top center +- **Headlines:** `display-md` equivalent, Pure Light +- **Body text:** `body` equivalent, Soft Light +- **CTA button:** Amethyst background, Pure Light text, rounded corners +- **Footer:** Dim Light text, minimal links (unsubscribe, privacy, help) +- **Pattern decoration:** Subtle pattern element in header area + +**Email types:** +1. Welcome series (3 emails over first week) +2. Weekly Spectrum summary (Prism users) +3. Monthly progress narrative +4. Product updates (max 1x/month) +5. Re-engagement (7-day and 30-day) + +--- +--- + +# 16. Accessibility + +## 16.1 Commitment + +Kalei is built to be used by everyone. Accessibility is not an afterthought — it's a design constraint from day one. All features must meet WCAG 2.1 AA standards at minimum. + +## 16.2 Visual Accessibility + +- **Contrast ratios:** All text meets AA minimum (4.5:1 for normal text, 3:1 for large text). See Color Accessibility section. +- **Color is never the only indicator.** Fragment highlights use underline + icon + color. Success/error states use icon + color + text. +- **Dark mode only (v1)** reduces the need for light/dark switching, but ensure all elements have sufficient contrast on dark backgrounds. +- **Scalable text:** Support Dynamic Type (iOS) and system font scaling (Android). UI must not break at 200% text size. +- **Touch targets:** Minimum 44×44px for all interactive elements (Apple HIG standard). + +## 16.3 Motion Accessibility + +- **Respect "Reduce Motion" settings.** All animations degrade to crossfades or instant transitions. +- **No autoplay video or animation** that cannot be paused. +- **The Turn animation must degrade gracefully** — still communicates "processing → result" without rotation. +- **No flashing content.** Nothing flashes more than 3 times per second. + +## 16.4 Screen Reader Support + +- All interactive elements have descriptive `accessibilityLabel` properties +- Pattern images include alt text describing the emotional context ("Kaleidoscope pattern from your February 3rd Turn about work stress") +- Fragment highlights in the Mirror announce via screen reader: "[highlighted text] — possible [distortion type]. Double-tap to see another angle." +- Gallery patterns are navigable and describable +- Turn results are announced sequentially: "Pattern 1 of 3: [reframe text]" + +## 16.5 Cognitive Accessibility + +- **Simple, clear language** throughout the UI. Kalei vocabulary is poetic but never jargon-heavy. +- **No time pressure.** No countdown timers, no disappearing content, no "limited time" messaging. +- **Predictable navigation.** Tab bar is always visible. Back buttons always go back. No hidden gestures required for core functionality. +- **Error recovery.** Every action is undoable or confirmation-gated. Deleted Mirror sessions go to a 30-day recovery bin. + +--- +--- + +# 17. Brand Misuse + +## 17.1 Logo Misuse + +**Never:** +- ✗ Rotate, skew, or distort the logo +- ✗ Apply drop shadows, outer glows, or bevels +- ✗ Place on busy or patterned backgrounds without sufficient contrast +- ✗ Recolor the mark or wordmark in non-brand colors +- ✗ Outline the mark (it should always be filled) +- ✗ Crop or partially obscure the logo +- ✗ Recreate the wordmark in a different typeface +- ✗ Animate the logo in ways not specified in this guide +- ✗ Use the logo as a pattern element or wallpaper tile +- ✗ Place the logo smaller than minimum size specifications + +## 17.2 Color Misuse + +**Never:** +- ✗ Use Jewel Tones on light/white backgrounds (they lose their luminous quality) +- ✗ Replace Void/Navy backgrounds with grey or white +- ✗ Use pastel versions of the Jewel Tones +- ✗ Apply the prismatic gradient to large filled areas at full opacity +- ✗ Use Ruby (error red) for any purpose other than errors and destructive actions +- ✗ Mix Kalei colors with external brand colors in co-marketing without approval + +## 17.3 Voice Misuse + +**Never write Kalei copy that:** +- ✗ Uses exclamation marks excessively +- ✗ Sounds clinical ("Your cognitive distortion has been identified") +- ✗ Sounds overly casual ("Yo, let's fix that bad thought!") +- ✗ Sounds desperate ("PLEASE come back! We miss you SO much!") +- ✗ Makes medical claims ("Kalei cures anxiety") +- ✗ Guarantees outcomes ("You WILL feel better") +- ✗ Guilt-trips ("You're letting yourself down by not using Kalei") +- ✗ Compares to therapy ("Better than a therapist!") +- ✗ Uses gendered language ("Hey girl!") +- ✗ References specific religions or spiritual practices + +## 17.4 Content Misuse + +**Kalei should never be used or presented in contexts involving:** +- ✗ Medical diagnosis or treatment claims +- ✗ Replacement for professional therapy or psychiatric care +- ✗ Political content or partisan messaging +- ✗ Religious or spiritual promotion +- ✗ Multi-level marketing or affiliate schemes +- ✗ Content that trivializes mental health conditions + +--- +--- + +# 18. Asset Checklist + +## 18.1 Required Brand Assets + +| Asset | Formats | Sizes | Status | +|-------|---------|-------|--------| +| Logo — Stacked (color on dark) | SVG, PNG | 1x, 2x, 3x | TBD | +| Logo — Stacked (mono white) | SVG, PNG | 1x, 2x, 3x | TBD | +| Logo — Stacked (mono dark) | SVG, PNG | 1x, 2x, 3x | TBD | +| Logo — Horizontal (color on dark) | SVG, PNG | 1x, 2x, 3x | TBD | +| Logo — Horizontal (mono white) | SVG, PNG | 1x, 2x, 3x | TBD | +| Logo — Horizontal (mono dark) | SVG, PNG | 1x, 2x, 3x | TBD | +| Mark only (color) | SVG, PNG | 1x, 2x, 3x | TBD | +| Mark only (mono) | SVG, PNG | 1x, 2x, 3x | TBD | +| App icon (iOS) | PNG | 1024×1024 | TBD | +| App icon (Android) | PNG | 512×512 | TBD | +| Favicon | ICO, PNG | 32×32, 16×16 | TBD | +| Social avatar | PNG | 400×400 | TBD | +| OG image (default) | PNG | 1200×630 | TBD | +| Pattern Card template | Figma, PNG | 1080×1920, 1080×1080 | TBD | +| App Store screenshots | PNG | Per platform spec | TBD | +| Icon set (navigation) | SVG | 24×24 | TBD | +| Icon set (actions) | SVG | 24×24 | TBD | +| Icon set (distortion types) | SVG | 20×20 | TBD | +| Prismatic gradient (CSS) | CSS/code | — | Defined in this doc | +| Color tokens (design system) | JSON/Figma | — | Defined in this doc | +| Type tokens (design system) | JSON/Figma | — | Defined in this doc | +| Spacing tokens (design system) | JSON/Figma | — | Defined in this doc | + +## 18.2 Design File Structure (Figma) + +``` +Kalei Design System/ +├── 🎨 Foundations/ +│ ├── Colors +│ ├── Typography +│ ├── Spacing & Grid +│ ├── Shadows & Elevation +│ └── Motion specs +├── 🧩 Components/ +│ ├── Buttons +│ ├── Inputs +│ ├── Cards +│ ├── Navigation +│ ├── Modals & Sheets +│ ├── Chips & Tags +│ ├── Toasts +│ └── Empty States +├── 📱 Screens/ +│ ├── Onboarding +│ ├── Turn (Kaleidoscope) +│ ├── Mirror +│ ├── Lens +│ ├── Gallery +│ ├── Spectrum (Phase 2) +│ ├── Profile & Settings +│ └── Upgrade Flow +├── 🖼️ Patterns/ +│ ├── Generation examples +│ ├── Pattern Card templates +│ └── Marketing patterns +├── 📣 Marketing/ +│ ├── App Store screenshots +│ ├── Social templates +│ ├── Email templates +│ └── Landing page +└── 📋 Brand/ + ├── Logo usage + ├── Icon library + └── Photography moodboard +``` + +--- +--- + +# Appendix: Color Token Reference (Code) + +```javascript +// Kalei Design Tokens — Colors +export const colors = { + // Backgrounds + void: '#050508', + navy: '#0A0E1A', + deepGlass: '#121628', + twilight: '#1C2240', + + // Jewel Tones + amethyst: '#8B5CF6', + sapphire: '#3B82F6', + emerald: '#10B981', + ruby: '#EF4444', + amber: '#F59E0B', + rose: '#EC4899', + + // Text + pureLight: '#FFFFFF', + softLight: '#E2E8F0', + dimLight: '#94A3B8', + faintLight: '#475569', + + // Semantic + actionPrimary: '#8B5CF6', // amethyst + actionSecondary: '#3B82F6', // sapphire + success: '#10B981', // emerald + warning: '#F59E0B', // amber + error: '#EF4444', // ruby + disabled: '#1C2240', // twilight + focus: '#8B5CF680', // amethyst 50% +}; + +// Prismatic Gradient (CSS) +export const prismaticGradient = + 'linear-gradient(135deg, #8B5CF6 0%, #3B82F6 25%, #10B981 50%, #F59E0B 75%, #EC4899 100%)'; + +// Prismatic Gradient (Reduced, for backgrounds) +export const prismaticGradientSubtle = + 'linear-gradient(135deg, rgba(139,92,246,0.3) 0%, rgba(59,130,246,0.3) 25%, rgba(16,185,129,0.3) 50%, rgba(245,158,11,0.3) 75%, rgba(236,72,153,0.3) 100%)'; +``` + +# Appendix: Typography Token Reference (Code) + +```javascript +// Kalei Design Tokens — Typography +export const typography = { + displayXl: { size: 40, weight: '700', lineHeight: 48, letterSpacing: -0.8 }, + displayLg: { size: 32, weight: '700', lineHeight: 40, letterSpacing: -0.6 }, + displayMd: { size: 24, weight: '600', lineHeight: 32, letterSpacing: -0.2 }, + heading: { size: 20, weight: '600', lineHeight: 28, letterSpacing: -0.2 }, + subheading:{ size: 16, weight: '600', lineHeight: 24, letterSpacing: 0 }, + bodyLg: { size: 17, weight: '400', lineHeight: 26, letterSpacing: 0 }, + body: { size: 15, weight: '400', lineHeight: 22, letterSpacing: 0 }, + bodySm: { size: 13, weight: '400', lineHeight: 18, letterSpacing: 0.1 }, + label: { size: 11, weight: '500', lineHeight: 16, letterSpacing: 0.5 }, +}; + +export const fontFamily = { + primary: 'Inter', + display: 'Space Grotesk', // Optional, marketing only +}; +``` + +# Appendix: Spacing Token Reference (Code) + +```javascript +// Kalei Design Tokens — Spacing +export const spacing = { + 1: 4, + 2: 8, + 3: 12, + 4: 16, + 5: 20, + 6: 24, + 8: 32, + 10: 40, + 12: 48, + 16: 64, +}; + +export const radius = { + sm: 2, // Icons + md: 10, // Buttons, inputs + lg: 16, // Cards, modals + xl: 20, // Bottom sheets + full: 999, // Pills, chips, avatars +}; +``` + +--- + +*The glass hasn't changed. But you have.* + +**© 2026 Kalei. All rights reserved.** diff --git a/docs/kalei-brand-metaphor.md b/docs/kalei-brand-metaphor.md new file mode 100644 index 0000000..4ab174e --- /dev/null +++ b/docs/kalei-brand-metaphor.md @@ -0,0 +1,403 @@ +# Kalei — Brand Metaphor & Experience Design + +## The Core 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. + +--- + +## Brand Vocabulary + +Every app builds an unconscious vocabulary through the words it uses in buttons, headers, notifications, and empty states. Kalei's vocabulary should reinforce 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 +- "Manifest" — save for the Manifestation Engine context only +- "Positive vibes" — trivializes the process +- "Journey" — overused in wellness apps + +--- + +## Feature Naming + +### The Reframer → **The Kaleidoscope** (or just **Turn**) + +The flagship feature. User inputs a negative thought (a fragment), and Kalei reveals multiple reframed perspectives (patterns). + +- **CTA button:** "Turn" (verb — active, simple, one word) +- **Input prompt:** "Drop in a fragment" or "What's on your mind?" +- **Loading state:** A subtle kaleidoscope rotation animation +- **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" + +### Manifestation Engine → **The Lens** + +The goal-setting and manifestation feature. If the Kaleidoscope shows you new patterns in what already exists, the Lens focuses your vision on what you're building toward. + +- **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" + +### Combined Narrative + +> The Kaleidoscope helps you see beauty in what's already there. +> The Lens helps you focus on what's ahead. +> Together, they're Kalei — a new way to see your life. + +--- + +## Onboarding Flow + +The onboarding should teach the metaphor through experience, not explanation. + +### Screen 1 — The Fragment + +Visual: A single shard of colored glass on a dark background. Simple. Stark. + +> **"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 transition. + +> **"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. Color blooms. + +> **"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 2–3 reframed perspectives. The user experiences the core value proposition within 60 seconds of opening the app. + +### Screen 5 — Welcome + +> **"Welcome to Kalei."** +> *Every day is a new turn.* + +--- + +## Visual Design Language + +### The Kaleidoscope Aesthetic + +The visual identity should evoke the feeling of looking through a kaleidoscope without being literal or childish. + +**Color Palette:** +- **Primary:** Deep jewel tones — amethyst purple, sapphire blue, emerald green +- **Secondary:** Warm golds and soft amber (the light passing through glass) +- **Background:** Near-black or deep navy (the dark tube of a kaleidoscope — the fragments shine against darkness) +- **Accent:** Prismatic gradients for highlights and CTAs (light refracting) + +**Why dark backgrounds:** A kaleidoscope works by reflecting light against darkness. The dark UI makes the colorful elements pop — and also 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) +- One geometric or slightly decorative font for headlines (faceted, angular — like cut glass) + +**Iconography:** +- Geometric and faceted — hexagons, triangles, crystalline shapes +- Avoid circles and soft curves (that's every other wellness app) +- Subtle symmetry in icon design (mirrors the symmetry of kaleidoscope patterns) + +### Signature Animation: The Turn + +The core micro-interaction of the app. 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). Subtle, smooth, 1.5–2 seconds +3. **Reveal phase:** Fragments settle into a symmetric pattern. The reframed perspectives appear beneath or within the pattern + +This animation should become iconic — the "Kalei Turn" — recognizable in screenshots, marketing, and social media. + +### Pattern Generation + +Each reframing session could generate a unique, procedurally-created kaleidoscope pattern based on the input. These patterns become: + +- **Visual identity for saved reframes** — each keepsake has its own pattern +- **Gallery items** — your collection of patterns grows over time +- **Shareable cards** — "My pattern for today" with the reframe text overlaid +- **Profile decoration** — your most-used patterns become part of your visual identity + +This is a powerful retention mechanic: **users build a gallery of beautiful, personal, unique patterns.** Each one tied to a moment where they chose to see things differently. + +--- + +## Navigation & Information Architecture + +### Tab Bar (4 tabs) + +| Icon | Label | Function | +|------|-------|----------| +| ◇ (geometric shard) | **Turn** | The Kaleidoscope — reframe a thought | +| ◎ (lens/circle) | **Lens** | The Manifestation Engine — goals & focus | +| ▦ (grid of patterns) | **Gallery** | History of all your Turns and patterns | +| ● (profile) | **You** | Settings, stats, subscription, profile | + +### Turn Tab (Home) + +- 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) + +### Lens Tab + +- Current focus (active goal) displayed prominently +- Today's affirmation +- Vision board / The View +- Progress tracker with "sharpening" visual metaphor + +### Gallery Tab + +- Grid view of kaleidoscope patterns, each linked to a saved reframe +- Filterable by date, mood tag, or theme +- Tap to expand: see the original fragment, the patterns revealed, and any notes +- Option to reshare or re-Turn (reframe the same thought again for fresh perspectives) + +### You Tab + +- Streak counter: "X-day turning streak" +- Stats: Total turns, patterns saved, most common themes +- Settings, subscription management +- "Your spectrum" — a visual breakdown of the emotional themes you've explored + +--- + +## Notification & Engagement Copy + +### 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." + +### Empty States + +- Gallery (no saves yet): "Your Gallery is waiting. The next pattern you save will appear here." +- Lens (no goal set): "What are you focusing on? Set your first Lens." +- Turn history (new user): "Every kaleidoscope starts with a single turn." + +--- + +## Subscription & Monetization Naming + +### Free Tier → **Kalei** + +- 3 Turns per day +- Basic pattern generation +- Gallery (last 30 days) + +### Premium Tier → **Kalei Prism** + +- Unlimited Turns +- Full Gallery (all history) +- The Lens (Manifestation Engine) +- Advanced reframe styles (Stoic, Compassionate, Pragmatic, Growth) +- Custom pattern themes +- Export & share patterns + +**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. + +**CTA for upgrade:** "See the full spectrum" or "Unlock your Prism" + +### Pricing Display + +> **Kalei Prism — $7.99/month** +> *Unlimited Turns. Full Gallery. The Lens. Your complete spectrum.* + +--- + +## Social & Sharing Mechanics + +### Pattern Cards + +When a user saves a reframe, they can generate a **Pattern Card** — a shareable image featuring: + +- Their unique kaleidoscope pattern (procedurally generated) +- The reframed thought (the pattern, not the fragment — we never share the negative thought) +- Subtle Kalei branding + +These are designed to be **Instagram Story and iMessage native** — correct aspect ratios, visually striking against both light and dark backgrounds. + +### "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 to the app through a natural, non-spammy mechanic. + +### Community Gallery (Future, v2+) + +An opt-in public gallery where users can share their best patterns anonymously. Browse how other people turned their fragments into patterns. Upvote the most powerful reframes. This builds community without requiring social profiles or exposing personal information. + +--- + +## Marketing & Brand Voice + +### Tagline Options + +1. **"Same pieces. New angle."** — the core proposition in five words +2. **"Turn how you see it."** — active, empowering, references the mechanic +3. **"Find the pattern."** — mysterious, inviting, implies hidden beauty +4. **"A new way to see."** — simple, universal + +**Recommended primary tagline:** *Same pieces. New angle.* + +### Brand Voice Guidelines + +**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. + +**Examples:** + +| 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." | + +### App Store Description (Draft) + +> **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 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. + +### Elevator Pitch + +> "Kalei is a kaleidoscope for your mind. You give it a negative thought — a broken fragment — and it shows you the beautiful patterns hidden inside. It's AI-powered cognitive reframing that helps you see the same situation from new angles. Not toxic positivity. Real perspective shifts, grounded in science. Same pieces, new angle." + +--- + +## Technical Implementation Notes + +### Procedural Pattern Generation + +Each reframing session should generate a unique kaleidoscope pattern. Implementation approach: + +- Use the **input text as a seed** — same thought always generates the same base pattern (creates personal connection) +- Apply **reframe variant as a rotation** — Pattern 1, Pattern 2, Pattern 3 are visual rotations of the base +- Render using **Canvas/WebGL** in React Native (or pre-rendered SVG for performance) +- Patterns should be **deterministic** — reopening a saved reframe shows the same pattern +- Export patterns as **PNG at 1080×1920** for Instagram Stories and **1080×1080** for feed posts + +### Animation 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, not standard iOS slide) +- **Pattern reveal:** Fragments drift into position with slight parallax depth (0.3s stagger per fragment) + +### Reframe Prompt Engineering + +The Claude API prompts for reframing should be structured to match the metaphor: + +``` +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." +``` + +--- + +## Summary: The Metaphor at Every Layer + +| Layer | How the metaphor 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 Kaleidoscope, The Lens, The Gallery | +| **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 | + +--- + +*The glass hasn't changed. But you have.* diff --git a/docs/kalei-complete-design.md b/docs/kalei-complete-design.md new file mode 100644 index 0000000..3132031 --- /dev/null +++ b/docs/kalei-complete-design.md @@ -0,0 +1,1023 @@ +# 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 Four Pillars + +Kalei is built on four optical instruments. Each one does something different with light. Together, they form a complete system for seeing your life from new angles. + +| 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 | + +These four pillars form a natural progression: + +``` +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 +``` + +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 when a user flows through all four, that's the **Kalei experience** at its deepest — and the Spectrum ties it all together with longitudinal intelligence. + +--- + +## 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.* + +### 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 + - **1–2 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.* + +### 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.* + +### 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.* + +### 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 2–3 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 2–3 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." + +--- +--- + +# Experience Design + +--- + +## Visual Design Language + +### 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, sapphire blue, emerald green +- **Secondary:** Warm golds and soft amber (the light passing through glass) +- **Background:** Near-black or deep navy (the dark tube of a kaleidoscope — fragments shine against darkness) +- **Accent:** Prismatic gradients for highlights and CTAs (light refracting) + +**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) +- One geometric or slightly decorative font for headlines (faceted, angular — like cut glass) + +**Iconography:** +- Geometric and faceted — hexagons, triangles, crystalline shapes +- Avoid circles and soft curves (that's every other wellness app) +- Subtle symmetry in icon design (mirrors the symmetry of kaleidoscope patterns) + +--- + +## 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.5–2 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 + +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 2–3 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 + +### 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 1–2:** Users are engaged with the Mirror and Kaleidoscope. Everything is new. + +**Week 3–4:** 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 | +| **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 1–2 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 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 + + ◇ ◇ + Kalei Free Kalei Prism + 3 Turns/day Unlimited everything + 2 Mirror/week + Full Spectrum + Basic Lens + Weekly/monthly insights + + Growth trajectory + + Fragment analytics +``` + +--- + +*The glass hasn't changed. But you have.* diff --git a/docs/kalei-mirror-feature.md b/docs/kalei-mirror-feature.md new file mode 100644 index 0000000..7cf0663 --- /dev/null +++ b/docs/kalei-mirror-feature.md @@ -0,0 +1,354 @@ +# The Mirror — Kalei's Notebook Feature + +## The 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 underlines or 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. The Kaleidoscope (Turn) is the active tool. The Mirror is the quiet awareness that makes the tool work. + +**Metaphor alignment:** +- 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 + +--- + +## How It Works — User Flow + +### Entry Point + +The Mirror lives as the **fifth element** in the app's navigation, or as a secondary action within the Turn tab. Two options: + +**Option A — Dedicated tab (recommended):** + +| Icon | Label | Function | +|------|-------|----------| +| ◇ | **Turn** | Quick structured reframe | +| ✦ | **Mirror** | Freeform notebook with AI awareness | +| ◎ | **Lens** | Manifestation Engine | +| ▦ | **Gallery** | History of patterns and reflections | +| ● | **You** | Profile and settings | + +**Option B — Nested under Turn:** +Turn tab has two modes: "Quick Turn" (current structured input) and "Open Mirror" (freeform). Toggle at top. + +**Recommendation:** Option A. The Mirror is different enough in intent and behavior that it deserves its own space. Users will develop separate habits — quick Turns for specific thoughts, Mirror sessions for processing. + +### The Writing Experience + +**Visual:** Chat-style interface. The user's messages appear as bubbles or blocks on one side. Clean, minimal, dark background consistent with Kalei's aesthetic. 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 or writing in a stream. No character limits. No structure required. Just write. + +### The Highlighting — "Fragment Detection" + +As the user writes (or after each message is sent), Kalei's AI analyzes the text for **cognitive distortion patterns** — the same patterns that cognitive behavioral therapy 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 a warm amber/gold color — the color of light catching a fragment +- The highlight is gentle, not aggressive. It shouldn't feel like a red pen correcting homework. It should feel like sunlight falling on a piece of glass — drawing attention naturally +- A small **◇ icon** (fragment symbol) appears at the end of the highlighted phrase, indicating this fragment can be Turned +- Highlights appear **after the user finishes a message** (not while typing — that would be intrusive and anxiety-inducing) + +**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, not full screen — user can still see their writing above) +2. The card shows: + - The original fragment, quoted + - The cognitive pattern name in plain language (e.g., "This sounds like catastrophizing — predicting the worst outcome") + - **1–2 reframed alternatives** — shorter and lighter than a full Turn, designed for quick insight + - A "Full Turn" button if they want to take this fragment into the Kaleidoscope for deeper exploration + - A "Dismiss" option — user can say "I see it, moving on" without reframing + +**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 the highlight. 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 unprompted +- Inject unsolicited advice +- 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 (see below) + +**Why not make it a chatbot?** Because the whole point is that the user is thinking out loud. Inserting AI responses between every message 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 at the end of the stream: + +> "I noticed a few fragments in what you wrote. Want to look at them together?" +> **[Show me]** · **[Not now]** + +This is the only time the AI initiates. Once per session maximum. + +--- + +## Session Wrap-Up — The Reflection + +When the user signals they're done writing (closes the Mirror, presses a "Done" button, or after a period of inactivity), Kalei generates a **Reflection** — a brief session summary. + +**The Reflection includes:** + +1. **The Mosaic** — a high-level summary of what the user wrote about (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 chose to engage 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 alongside their Turn patterns. Mirror sessions get their own visual style — perhaps slightly different geometry (softer, more organic) to distinguish them from structured Turns + +5. **An optional one-line insight** — the AI's single most important observation from the session + > "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. Users can revisit their sessions, re-read what they wrote, see which fragments they explored, and track how their patterns evolve over time. + +--- + +## Where the Mirror Fits in the User's Journey + +The three core features now form a **progression**: + +``` +THE MIRROR THE KALEIDOSCOPE THE LENS +(Awareness) → (Perspective) → (Direction) + +"What am I "How else can I "What am I + feeling?" see this?" building toward?" + +Freeform Structured Goal-focused +writing reframing manifestation + +Fragments Fragments → Patterns Patterns → Focus +detected revealed applied +``` + +**The natural user flow:** + +1. **Mirror** — User dumps their raw thoughts. AI highlights the fragments they can't see themselves +2. **Turn** — User takes the most charged fragment and gives it a full Turn in the Kaleidoscope, getting deep, multi-angle reframes +3. **Lens** — The insights from reframing inform the user's goals. What they thought was a setback becomes fuel for what they're building toward + +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 when a user does flow through all three, that's the **Kalei experience** at its deepest. + +--- + +## Engagement & Retention Mechanics + +### Mirror Streaks + +Track separately from Turn streaks: +- "You've written in the Mirror 5 days in a row" +- Mirror sessions tend to be longer and more personal → higher engagement signal + +### Fragment Tracking Over Time + +The Gallery can show **fragment patterns over time**: +- "This month, your most common fragment type was **should statements**" +- "You've reduced catastrophizing by 40% compared to last month" +- A visual "spectrum" chart showing which cognitive distortions appear most frequently + +This turns the Mirror from a journal into a **self-awareness engine**. Users can literally see their thinking patterns change over time. + +### Mirror 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." + +These are optional, dismissible, and only shown on empty-state. + +--- + +## Monetization Placement + +| Feature | Free (Kalei) | Premium (Kalei Prism) | +|---|---|---| +| Mirror access | 2 sessions/week | Unlimited | +| Fragment highlighting | Basic (3 distortion types) | Full spectrum (all 10 types) | +| Inline reframes | 1 per session | Unlimited | +| Session Reflections | Summary only | Full Reflection with insight | +| Fragment tracking over time | ✗ | ✓ | +| Export Mirror sessions | ✗ | ✓ | + +The free tier gives enough Mirror access to experience the value. The paywall hits at the point where the user wants **depth and consistency** — which is exactly when they're most likely to convert. + +--- + +## Technical Implementation Notes + +### AI Processing Pipeline + +Each message the user sends in the Mirror 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 (highlighting something that isn't actually distorted thinking) would erode trust quickly. + +**Latency:** Analysis should complete within 1–2 seconds after message sent. Highlights appear with a subtle fade-in animation — fragments "catching the light." + +### Reframe Generation (On Tap) + +When user taps a highlighted fragment, a second API call generates the inline reframe: + +``` +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 if user wants deeper exploration" +} +``` + +### Data Storage + +Mirror sessions stored in Supabase: + +```sql +-- Mirror sessions table +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, -- for generating the visual pattern + created_at TIMESTAMPTZ DEFAULT NOW() +); + +-- Mirror messages table +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() +); + +-- Detected fragments within messages +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() +); +``` + +### Privacy & Sensitivity + +Mirror content is the most personal data in the app. Requirements: + +- **End-to-end encryption** for all Mirror content at rest +- **No Mirror content used for model training** — explicit policy +- **Local-first option** (future): Allow users to keep Mirror data on-device only +- **Easy deletion**: User can delete any session or all Mirror data +- **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 + +--- + +## Updated App Structure + +With the Mirror, Kalei now has three pillars that map to a complete mental model: + +| Pillar | Feature | Metaphor | User need | Interaction style | +|--------|---------|----------|-----------|-------------------| +| **Awareness** | The Mirror | Reflective surface that shows you your fragments | "I need to process" | Freeform writing, passive AI | +| **Perspective** | The Kaleidoscope | The turn that reveals patterns in fragments | "I need to see this differently" | Structured input → output | +| **Direction** | The Lens | Focused vision toward what you're building | "I need to move forward" | Goal setting, affirmations, tracking | + +**Together:** You become aware of your patterns (Mirror), you learn to see them differently (Kaleidoscope), and you channel that clarity into what you're building (Lens). + +**Tagline still holds:** *Same pieces. New angle.* + +**Elevator pitch (updated):** +> "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." + +--- + +*The mirror doesn't tell you what to see. It shows you what's already there.* diff --git a/docs/kalei-spectrum-phase2.md b/docs/kalei-spectrum-phase2.md new file mode 100644 index 0000000..331e2f7 --- /dev/null +++ b/docs/kalei-spectrum-phase2.md @@ -0,0 +1,405 @@ +# The Spectrum — Kalei Phase 2 + +## Emotional Intelligence, Not Mood Tracking + +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. + +It also completes the optical metaphor system: + +| Feature | Optical element | What it does | +|---------|----------------|--------------| +| The Mirror | Mirror | Reflects your thoughts back to you | +| The Kaleidoscope | Kaleidoscope | Rearranges fragments into patterns | +| The Lens | Lens | Focuses your vision on what's ahead | +| The Spectrum | Prism | Reveals the full range of what you're feeling | + +--- + +## What The Spectrum Shows + +### 1. The Emotional Landscape + +A visual representation of your emotional state over time — not from self-reporting, but from **AI analysis of your Mirror sessions, Turns, and Lens check-ins.** + +**How it works:** + +Every Mirror message and Turn input is analyzed for emotional signatures across multiple 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 result looks like light passing through a prism: your emotional spectrum, laid out across days and weeks. + +**The user sees:** +- The overall color/tone of their week at a glance +- Shifts and transitions (Tuesday was dark and activated → Wednesday calmed down 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. You look at it and *feel* whether things are moving in the right direction. + +### 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." + +> "Your top 3 fragment types this month: catastrophizing, discounting positives, and black-and-white thinking." + +**Why this matters:** Most people have 2-3 dominant cognitive distortions they don't know about. Seeing them named and tracked over time is genuinely transformative — it's 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. + +**How it works:** + +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 that day or the next day +- 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." + +> "Your most impactful Turn this month was on Feb 3 — the shift in your writing afterward was significant." + +> "Turns on work-related fragments have the strongest positive effect for you. Relationship fragments take 2-3 Turns before the shift shows up." + +This is the **evidence engine** for Kalei's core thesis: that changing the angle actually changes how you feel. Users can see the proof in their own data. + +### 4. Rhythm Detection — "Your Cycles" + +Identifies recurring emotional patterns tied to time. + +**Weekly rhythms:** +> "Your Mirror sessions on Mondays contain 3x more should statements than any other day." +> "Fridays tend to be your most positive writing days." + +**Monthly rhythms:** +> "The last week of each month shows elevated anxiety patterns — possibly tied to deadlines or financial cycles." + +**Event correlation (Lens integration):** +> "When you check in with your Lens goals in the morning, your afternoon Mirror sessions show 40% fewer negative fragments." + +**Contextual patterns:** +> "After writing about [work] topics, catastrophizing spikes. After writing about [relationships], personalization is more common." + +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. That awareness alone is a superpower. + +### 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: How many distortions per 100 words in Mirror sessions (trending down = growth) +- Self-correction rate: How often the user identifies their own fragments before Kalei highlights them (measured by editing/deleting mid-message) +- Reframe adoption: How often saved patterns from Turns echo in subsequent Mirror writing (user naturally using new perspectives) +- Distortion diversity: Whether the user is getting stuck on one pattern or successfully addressing multiple types +- Turn-to-insight ratio: How many Turns result in a saved keepsake vs. dismissed patterns + +**Visualization:** A single, evolving kaleidoscope pattern that represents your overall growth. The more you use Kalei, the more complex, colorful, and beautiful the pattern becomes. At month 1, it might be simple and muted. At month 6, it's intricate and vivid. + +This becomes the **centerpiece of the Spectrum dashboard** — your personal growth, visualized as a living kaleidoscope pattern. + +**Milestone moments:** + +> "Your fragment density has dropped 30% since you started. You're catching your own patterns now." + +> "This week, you naturally reframed a catastrophizing thought in your Mirror session without needing a Turn. That's new." + +> "You've explored all 10 fragment types. You're seeing the full spectrum." + +--- + +## The Spectrum Dashboard — Layout + +### Top Section: The River +Your emotional landscape as a flowing color gradient. Swipe horizontally to scroll through time. Tap any point to see the Mirror session or Turn from that day. + +### Middle Section: Your Glass +The faceted gem visualization showing fragment type distribution. Toggle between "This week," "This month," "All time." Tap any facet for the distortion deep-dive. + +### Bottom Section: Insights Feed +A scrollable feed of AI-generated insights, refreshed weekly. Each insight is a card with: +- A one-line observation +- Supporting data (subtle, not overwhelming) +- An action suggestion when relevant + +### Floating Element: Your Pattern +Your evolving kaleidoscope pattern, accessible from the top corner. Tap to expand full-screen. Shareable as a "growth snapshot." + +--- + +## When Insights Are Delivered + +The Spectrum doesn't bombard users with data. Insights surface at natural moments: + +### Weekly Reflection (Push Notification) +Every Sunday evening (or user-configured day): +> "Your Spectrum updated. See what this week's light revealed. 🔮" + +Opens to a **Weekly Spectrum Summary:** +- Dominant emotional color this week +- Top fragment type +- Most impactful Turn +- One insight +- The week's addition to your evolving pattern + +### Monthly Deep Dive +First of each month: +> "January's Spectrum is ready. See how your light shifted." + +A richer summary with month-over-month comparisons, rhythm detection insights, and growth trajectory updates. + +### In-Context Nudges +Subtle, non-intrusive insights surfaced within other features: +- In the 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." +- In the Lens: "Your Lens focus on [career growth] aligns with the fragments you've been processing. You're working on the right things." + +--- + +## Monetization + +The Spectrum is a **Kalei Prism exclusive feature**. It's the single strongest reason to upgrade in Phase 2. + +**Free tier gets:** +- A simplified weekly emotional summary (1 insight, no visualizations) +- Fragment type counts (basic numbers only) +- A teaser of what the full Spectrum shows: "Upgrade to see your full Spectrum" + +**Prism tier gets:** +- Full Spectrum dashboard with all 5 sections +- Weekly and monthly deep dives +- Growth trajectory and evolving pattern +- Rhythm detection +- Turn impact analysis +- Export and sharing of Spectrum snapshots + +**Upgrade CTA:** +> "You've written 47 Mirror sessions and completed 23 Turns. There's a story in that data. See your full Spectrum." + +This is a natural paywall because the Spectrum **requires usage history to be valuable.** By the time a user has enough data for the Spectrum to be meaningful, they've already experienced Kalei's value through the free tier and are primed to convert. + +--- + +## Privacy Architecture + +The Spectrum analyzes deeply personal data. Trust is non-negotiable. + +### Principles + +1. **All analysis happens on aggregated patterns, never exposed raw content.** The Spectrum shows "your catastrophizing increased this week" — it never shows "you wrote 'my life is falling apart' on Tuesday" +2. **No Spectrum data leaves the user's account.** Not for model training, not for anonymized research, not for anything +3. **Users control the window.** They can exclude any Mirror session or Turn from Spectrum analysis. They can set the Spectrum to only analyze the last 30/60/90 days +4. **Full deletion.** "Reset my Spectrum" erases all analyzed data and starts fresh +5. **Transparency.** A "How this works" section explains exactly what the AI analyzes and what it doesn't + +### 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 runs to compute trends, rhythms, and insights +- The Spectrum dashboard reads from aggregated data only + +```sql +-- Emotional analysis per Mirror session +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() +); + +-- Emotional analysis per Turn +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, -- emotional state of input + post_valence FLOAT, -- emotional state after reframe engagement + distortion_type VARCHAR(50), + reframe_saved BOOLEAN, + topic_cluster VARCHAR(100), + created_at TIMESTAMPTZ DEFAULT NOW() +); + +-- Weekly aggregated insights +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, -- {"catastrophizing": 5, "mind_reading": 3, ...} + fragment_density FLOAT, -- fragments per 100 words + turn_impact_score FLOAT, -- measured shift after turns + insight_text TEXT, -- AI-generated weekly insight + created_at TIMESTAMPTZ DEFAULT NOW(), + UNIQUE(user_id, week_start) +); + +-- Monthly deep dive +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, -- composite improvement metric + rhythm_insights JSONB, -- detected patterns tied to time + month_over_month_delta JSONB, -- comparison with previous month + top_fragment_types JSONB, -- ranked list + most_impactful_turn UUID, -- references turn with biggest shift + pattern_complexity_score FLOAT, -- drives evolving visual pattern + narrative_summary TEXT, -- AI-generated monthly narrative + created_at TIMESTAMPTZ DEFAULT NOW(), + UNIQUE(user_id, month_start) +); +``` + +--- + +## Notification Copy — Spectrum Voice + +The Spectrum speaks with slightly more authority than other Kalei features — it has data behind it. But still warm, still poetic. + +### Weekly + +- "Your Spectrum shifted this week. Come see the colors." +- "7 days of fragments and patterns. Here's what the light reveals." +- "This week had a rhythm. The Spectrum caught it." + +### 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 + +- "First month of Spectrum data. Your baseline is set — now watch it evolve." +- "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." + +--- + +## The Spectrum as Retention Engine + +The Spectrum solves the biggest problem in wellness apps: **the drop-off after the initial novelty fades.** + +**Week 1-2:** Users are engaged with the Mirror and Kaleidoscope. Everything is new. + +**Week 3-4:** Novelty fades. This is where most wellness apps lose people. + +**With the Spectrum (Phase 2 timing — 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). + +--- + +## Phase 2 Launch Sequence + +### Pre-Launch (2 weeks before) + +Notification to existing users: +> "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 for the first time — the river visualization populating with their historical data, the gem forming its facets, the evolving pattern appearing. + +This should be a **wow moment.** The user's own emotional history, visualized beautifully for the first time. Data they generated without thinking about it, now reflecting back as genuine self-knowledge. + +### Post-Launch (ongoing) + +Weekly and monthly cadence takes over. The Spectrum becomes a background engine that surfaces insights at the right moments and gives users a reason to maintain their Mirror and Turn habits. + +--- + +## Updated Feature Map — Full Kalei Ecosystem + +``` +PHASE 1 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 + + ◇ ◇ + Kalei Free Kalei Prism + 3 Turns/day Unlimited everything + 2 Mirror/week + Full Spectrum + Basic Lens + Weekly/monthly insights + + Growth trajectory + + Fragment analytics +``` + +--- + +*White light looks simple. The Spectrum shows you everything it's made of.*