---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
inputDocuments:
- _bmad-output/planning-artifacts/prd-phase1-mvp-ai.md
- docs/component-inventory.md
- docs/project-overview.md
workflowType: 'ux-design'
lastStep: 14
documentTitle: 'UX Design Specification - Phase 1 MVP AI'
focusArea: 'AI-Powered Note Taking Features'
status: 'complete'
createdAt: '2026-01-10'
completedAt: '2026-01-10'
---
# UX Design Specification - Phase 1 MVP AI
**Project:** Memento
**Author:** Ramez
**Date:** 2026-01-10
**Focus:** UX Design for AI-Powered Note Taking Features
---
## Executive Summary
### Project Vision
**Memento Phase 1 MVP AI** transforms the existing note-taking application into a **proactive cognitive partner** with the philosophy **"Zรฉro Prise de Tรชte"** (Zero-Friction Intelligence).
**Core Philosophy:** "Suggest and facilitate, never impose"
**What Makes It Special:**
- **Contextual Smart Assistance**: AI features appear only when relevant, not overwhelming
- **Hybrid Semantic Discovery**: Unified search that "just works" - users don't distinguish keyword vs semantic
- **Memory Echo** โญ: Proactive connections between notes that users hadn't seen (the "Aha!" moment)
- **Privacy-First Multi-Provider**: Ollama (100% local) OR OpenAI (cloud) - user choice
**The "Aha!" Moment:**
> *"I didn't search, it found me"*
>
> ๐ก *"I noticed something..."*
> *"You noted `[Node.js performance tips]` in January and `[Next.js optimization]` this week. These notes are connected - want me to link them?"*
### Target Users
**Primary Personas (from PRD User Journeys):**
**1. Alex - Creative Developer (Success Path)**
- **Profile:** Freelance Creative & Developer, 32, Paris
- **Problem:** 300+ notes, can't find anything, spends 20min searching
- **Goals:** Instant capture, intelligent organization
- **Discovery:** Toast title suggestions โ Memory Echo reveals invisible connections โ "Hooked!"
**2. Max - Privacy Advocate**
- **Profile:** Privacy Advocate & Software Engineer, 28, Berlin
- **Problem:** Wants AI but refuses to let data leave his laptop
- **Goals:** Total control + verifiable (checks DevTools for 0 external calls)
- **Discovery:** Verifies Ollama = 0 external API calls โ Builds trust
**3. Lรฉa - System Admin** (Phase 2, not MVP)
- **Profile:** DevOps Engineer, 35, Lyon - Team admin
- **Problem:** Configure AI for 15 devs, monitor costs
- **Goals:** Admin dashboard + AI analytics
**4. Sophie - Skeptic to Trust**
- **Profile:** Content Marketing Manager, 29, Bordeaux
- **Problem:** AI makes mistakes, learns to trust through customization
- **Goals:** Personalizable AI settings, feedback learning
**User Characteristics:**
- **Tech-savvy**: Developers, knowledge workers, creatives
- **Devices**: Desktop (laptop) + Mobile (smartphone/tablet)
- **Context**: Async work, quick capture in subway, meetings
### Key Design Challenges
**1. Contextual Smart Assistance Pattern**
- **Challenge:** Make AI features appear only when relevant
- **Example:** Title suggestions AFTER 50+ words without title
- **Question:** How to avoid overwhelming users with too many AI features?
**2. Memory Echo - "I Didn't Search, It Found Me"**
- **Challenge:** Surface proactive connections without appearing spammy
- **Constraint:** Max 1 insight/day (configurable 0-3)
- **Question:** How to make every insight feel valuable?
**3. Privacy-First Multi-Provider**
- **Challenge:** Communicate that Ollama = 100% local processing
- **Solution:** Connection status indicators, verifiable in DevTools
- **Question:** How to clearly communicate local vs cloud difference?
**4. Feedback & Learning**
- **Challenge:** AI makes mistakes, how to recover user trust?
- **Solution:** ๐๐ buttons, "Why is this wrong?" modal, customizable settings
- **Question:** How to make feedback learning visible and reassuring?
### Design Opportunities
**1. Toast Notification Pattern - Natural Discovery**
- Instead of hiding features in menus, discover them when relevant
- Example: "I have 3 title ideas for your note, view them?"
- **Benefit:** Users discover features without tutorial
**2. "Exact Match | Semantic Match" Badges**
- Hybrid search that "just works" - users don't know how it works
- Visual badges to distinguish keyword vs semantic results
- **Benefit:** Educates users without confusing them
**3. Memory Echo Card - The "Aha!" Moment**
- Proactive notification: "I noticed something..."
- Display 2 connected notes side-by-side
- ๐๐ buttons for learning
- **Benefit:** Creates unique emotional moment ("Wow, that's clever!")
**4. Granular AI Settings - Total Control**
- ON/OFF checkboxes for each AI feature
- Memory Echo frequency slider (0-3/day)
- **Benefit:** User feels in control, not "spied on by AI"
---
## Core User Experience
### Defining Experience
**Core Experience:** "Fast Capture + Intelligent Discovery"
Memento Phase 1 MVP AI combines two fundamental experiences:
1. **Fast Capture** (Primary - Existing Enhanced)
- Instant note creation with zero friction
- Content first, title comes later (or AI-suggested)
- Markdown supported but not required
- Capture anywhere: desktop (laptop), mobile (subway, meetings), tablet
2. **Intelligent Discovery** (New - Phase 1)
- AI organizes silently in background
- Title suggestions appear contextually (after 50+ words without title)
- Semantic search that "just works"
- Memory Echo reveals invisible connections between notes
**Core User Loop:**
```
Capture โ AI Organizes โ Discover โ Capture โ ...
โ_____________โ
Seamless Flow
```
The critical insight: Capture must remain instant (no AI friction), while AI enhances organization in the background.
### Platform Strategy
**Primary Platform:** Web Application (Responsive)
No native mobile apps - modern browsers provide sufficient capabilities.
**Device Breakdown:**
| Platform | Viewport | Usage | Interaction Style |
|----------|----------|-------|-------------------|
| **Desktop** | 1024px+ | Primary - serious work, content creation | Mouse + Keyboard (shortcuts, power users) |
| **Tablet** | 640px-1023px | Intermediate - comfortable reading | Touch + Keyboard (hybrid) |
| **Mobile** | 320px-639px | Quick capture on-the-go | Touch-first (44x44px tap targets) |
**Technical Stack:**
- Next.js 16.1.1 (SSR + App Router)
- React 19.2.3 (Server + Client Components)
- Tailwind CSS 4 (utility-first styling)
- Radix UI (accessible primitives)
**Responsive Design Strategy:**
- Mobile-first approach
- Progressive enhancement
- Touch-optimized on mobile, keyboard-optimized on desktop
**Offline Requirements:** None for MVP (Phase 2: PWA with offline mode)
### Effortless Interactions
**1. Zero-Friction Capture**
- Opening Memento โ Type immediately (no login friction after first session)
- No "choose a title first" โ Content comes first
- Optional markdown formatting (not required)
- Auto-save as you type
**2. Natural Feature Discovery**
- Toast notification: "I have 3 title ideas for your note, view them?"
- Options: "View | Not now | Don't ask for this note"
- User discovers AI features when relevant, not via tutorial
- Non-intrusive, respectful of user's flow
**3. Memory Echo "Aha!" Moment**
- Subtle notification: "I noticed something..."
- Max 1 insight/day (configurable 0-3)
- When relevant โ User thinks: "That's clever!"
- Not spammy, each insight feels valuable
**4. Search That "Just Works"**
- User types naturally: "how to optimize React performance"
- Results show with badges: "Exact Match | Semantic Match"
- User doesn't know how it works, but it finds the note
- Hybrid search = keywords + semantic mixed, no user configuration needed
**5. Privacy-First Transparency**
- Clear indicators: "โ Connected to local Ollama" vs "โ Connected to OpenAI Cloud"
- Verifiable in DevTools (Max checks for 0 external API calls)
- Users can see and trust where their data goes
### Critical Success Moments
**Moment 1: First Title Suggestion Accepted**
- **Trigger:** User writes 50+ words without title
- **Interaction:** Toast appears โ User clicks "View" โ Sees 3 relevant suggestions
- **Success Metric:** User accepts suggestion (>60% acceptance target)
- **User Thought:** "Wow, that saved me time!"
- **Failure:** Suggestions irrelevant โ User dismisses permanently
**Moment 2: Memory Echo "Aha!" Discovery**
- **Trigger:** Background analysis finds strong connection (cosine >0.75)
- **Interaction:** Notification shows 2 connected notes side-by-side
- **Success Metric:** User clicks "View Connection" (>40% CTR target)
- **User Thought:** "I hadn't seen that link before!"
- **Failure:** Connection feels random โ User clicks ๐ or disables feature
**Moment 3: Semantic Search Finds the Unfindable**
- **Trigger:** User searches naturally (not exact keywords)
- **Interaction:** Results show with "Semantic Match" badge
- **Success Metric:** Semantic result in top 3 (>30% of complex searches)
- **User Thought:** "How did it find that? I searched for X, not Y!"
- **Failure:** Doesn't find what exists โ User returns to Ctrl+F
**Moment 4: Privacy Verification (Max's Journey)**
- **Trigger:** Privacy-conscious user selects Ollama
- **Interaction:** Checks DevTools โ Confirms 0 external API calls
- **Success Metric:** Trust established, continues using AI features
- **User Thought:** "Good, they kept their word. My data stays local."
- **Failure:** Any data leak โ Uninstalls immediately
### Experience Principles
**Guiding Principles for All UX Decisions:**
**1. Capture First, Organize Later**
- Content comes before title
- AI organizes in background, never intrusive during capture
- "Zero friction" for creation
- **Implication:** No AI processing blocks note creation
**2. Contextual, Not Constant**
- AI features appear only when relevant
- No permanent AI toolbar (overwhelming)
- Temporary toast notifications with "Not now" option
- Single-interaction rule (only one AI prompt at a time)
- **Implication:** Prioritize which AI feature to show if multiple triggered
**3. Hybrid by Design**
- Keywords AND semantic mixed (user doesn't distinguish)
- Local AND cloud providers (user chooses)
- Manual AND auto (user controls automation level)
- **Implication:** Don't expose complexity, blend approaches seamlessly
**4. Transparent Control**
- Every AI feature has granular ON/OFF
- Connection status indicators (local vs cloud)
- Feedback ๐๐ visible and impactful
- Settings explain what's happening
- **Implication:** Users feel in control, not "spied on by AI"
**5. Progressive Disclosure**
- Simple by default, powerful when needed
- Basic usage: Just capture notes
- Advanced usage: Customize AI thresholds, frequency, providers
- **Implication:** Don't overwhelm new users with settings
**6. Graceful Degradation**
- If AI fails, core note-taking still works
- Fallback to alternative provider automatically
- User-friendly error messages (no technical jargon)
- **Implication:** AI enhances, doesn't block core functionality
---
## Desired Emotional Response
### Primary Emotional Goals
**Core Emotional Reaction:** "Wow, Memento understands my knowledge better than I do!"
The defining emotional moment occurs when Memory Echo reveals an invisible connection:
> ๐ก *"I noticed something..."*
> *"You noted `[Node.js performance tips]` in January and `[Next.js optimization]` this week. These notes are connected."*
**User's Internal Monologue:**
- "I hadn't made that connection!" (Surprise)
- "That's brilliant!" (Admiration)
- "Memento is smarter than me!" (Trust in AI)
**This is THE differentiator** from Google Keep/Notion which lack proactive intelligence.
**Primary Emotional Goal:** Create recurring "Aha!" moments where users feel the AI is genuinely helpful, not intrusive.
### Emotional Journey Mapping
Based on the 4 User Journeys from the PRD, the emotional progression:
**Stage 1: First Discovery - Curiosity**
- *Opening Memento:* "Ok, a notes app. Standard."
- *First capture:* "Fast, it works. Good."
- *No surprise or wow yet* - Just solid functionality
**Stage 2: First AI Interaction - Interest**
- *Toast "I have 3 title ideas...":* "Oh? What's this?"
- *Relevant suggestions:* "Hey, that's actually pretty good!" (Positive)
- *Applying title:* "Cool, saved time."
**Stage 3: Memory Echo - THE "Aha!" Moment** โญ
- *Notification "I noticed something...":* "What's this about?"
- *Seeing 2 connected notes:* "WOAH! I never saw that link!" (Surprise)
- *Click "View Connection":* "Memento understands my knowledge better than I do!" (Trust)
**Stage 4: Trust Building - Confidence**
- *Granular AI Settings:* "I can control everything. Nice."
- *Ollama Local (Max):* "Zero external calls. Perfect!"
- *Feedback ๐๐:* "My opinion matters. The AI learns."
**Stage 5: Long-term - Satisfaction**
- *Finding the unfindable:* "Thanks Memento, you saved me."
- *Less mental load:* "Finally, I'm organized without effort."
### Micro-Emotions
Subtle but critical emotional states that determine success:
**1. Trust vs. Skepticism** โ CRITICAL
- **Sophie (Skeptic):** "AI will spam me or get things wrong."
- **Transformation:** ๐ feedback โ "Why?" modal โ AI learns โ "Ok, it listens to me."
- **Target Micro-emotion:** **Trust building through transparency**
**2. Control vs. Overwhelm** โ CRITICAL
- **Risk:** Too many AI features = overwhelming
- **Solution:** Toast "Not now" option, granular ON/OFF settings
- **Target Micro-emotion:** **"I'm in control, not the AI"**
**3. Efficiency vs. Frustration** โ CRITICAL
- **Alex before Memento:** "I spend 20min finding this note!" (Frustration)
- **After Memory Echo:** "Found in 2 seconds!" (Efficiency)
- **Target Micro-emotion:** **"I'm smarter with Memento"**
**4. Surprise vs. Annoyance**
- **Risk:** Toast notifications = perceived as spam
- **Solution:** Contextual triggers (50+ words), "Don't ask for this note"
- **Target Micro-emotion:** **"Oh, that's useful!" not "Another notification..."**
**5. Privacy vs. Anxiety**
- **Max:** "Will my personal data go to the cloud?"
- **Solution:** Status indicators (โ 100% Local Ollama), DevTools verifiable
- **Target Micro-emotion:** **"My data is safe, I'm in control"**
### Design Implications
Connecting desired emotions to specific UX design choices:
**1. Trust โ Transparency**
- **UX Choice:** Visual status indicators (โ Local Ollama | โ OpenAI Cloud)
- **UX Choice:** ๐๐ buttons with visible feedback ("Thanks, we're learning!")
- **UX Choice:** Settings explain WHAT the AI does (no black box)
- **Implementation:** Tooltip/badge explaining "I analyzed 150 notes to find this connection"
**2. Control โ Granular Settings**
- **UX Choice:** Individual ON/OFF checkboxes for EACH AI feature
- **UX Choice:** Memory Echo frequency slider (0-3/day)
- **UX Choice:** "Don't ask for this note" respected immediately
- **Implementation:** `/settings/ai` page as most important page in product
**3. Efficiency โ Instant Results**
- **UX Choice:** Semantic search < 300ms (no slow loading spinner)
- **UX Choice:** Title generation < 2s (feels instant)
- **UX Choice:** Memory Echo background processing (< 100ms UI freeze)
- **Implementation:** Skeleton screens, optimistic UI updates
**4. Positive Surprise โ Contextual Triggers**
- **UX Choice:** Toast ONLY after 50+ words (not at first word)
- **UX Choice:** Memory Echo max 1/day (not spammy)
- **UX Choice:** "Exact Match | Semantic Match" badges to educate without confusing
- **Implementation:** Single-interaction rule (prioritize which AI feature to show)
**5. Security โ Privacy Indicators**
- **UX Choice:** Lock icon ๐ for Ollama local
- **UX Choice:** Clear message "Your data never leaves your device" for Ollama
- **UX Choice:** "100% Local" badge visible in Settings
- **Implementation:** Provider selection screen with clear visual distinction
### Emotional Design Principles
**Guiding Principles for Creating Desired Emotional Responses:**
**1. "Aha!" Moments Over Features**
- Prioritize discovery moments (Memory Echo) over feature quantity
- Create 1-2 memorable "Wow" moments rather than 10 mediocre features
- **Design Implication:** Invest UX effort in Memory Echo = maximum emotional ROI
**2. Trust Through Transparency**
- Never hide what the AI is doing
- Show the work ("I analyzed 150 notes to find this connection")
- **Design Implication:** Loading states, badges, tooltips explain the "why"
**3. Control Reduces Anxiety**
- Every AI feature can be disabled independently
- User chooses automation level
- **Design Implication:** AI Settings page = most important product page
**4. Speed = Intelligence**
- If it's fast, AI seems smart
- If it's slow, AI seems "dumb" or "heavy"
- **Design Implication:** Optimize performance (< 2s titles, < 300ms search) = emotional UX
**5. Fail Gracefully, Recover Quickly**
- When AI errs, UX says "Sorry, I'm learning!" not "System error"
- ๐ feedback = trust-building opportunity (not failure)
- **Design Implication:** "Why is this wrong?" modal + "Thanks for teaching me!"
**6. Contextual > Constant**
- AI features appear only when relevant
- No permanent AI toolbar (overwhelming)
- **Design Implication:** Temporary toast notifications with dismissal options
---
## UX Pattern Analysis & Inspiration
### Inspiring Products Analysis
Based on the personas (Alex, Max, Lรฉa, Sophie) and competitive landscape, here are the key inspiring products:
**1. Google Keep** (Direct Competitor)
- **What they do well:** Ultra-fast capture, clean interface, masonry grid layout
- **What's missing:** Proactive AI, semantic search, connections between notes
- **Pattern to learn:** Simplicity of capture, Masonry layout optimization
- **Already in Memento:** MasonryGrid component exists (from component inventory)
**2. Notion** (Indirect Competitor)
- **What they do well:** Power features, databases, on-demand AI
- **What's missing:** Contextual (too complex), no proactive insights
- **Pattern to learn:** Rich text editor, slash commands
- **Not applicable:** Too complex for Memento's "zero-friction" philosophy
**3. GitHub Copilot** (AI Reference - Developers)
- **What they do well:** Non-intrusive contextual suggestions
- **Pattern inspiration:** AI appears when relevant, no permanent toolbar
- **Connection to Memento:** Contextual Smart Assistance for title suggestions
- **Key insight:** Single-interaction rule (don't overwhelm with multiple AI prompts at once)
**4. Linear** (UX Reference - Tech-Savvy Users)
- **What they do well:** Speed = intelligence perception, keyboard-first, native dark mode
- **Pattern inspiration:** Performance creates perceived intelligence
- **Connection to Memento:** < 2s title generation, < 300ms semantic search
- **Key insight:** If AI is fast, users think it's smart. If slow, it seems "dumb"
**5. Obsidian** (Notes Reference - Power Users)
- **What they do well:** Graph view (visual connections), plugin ecosystem
- **What's missing:** Proactive AI (connections are manual)
- **Pattern inspiration:** Connections between notes
- **Memento innovation:** Memory Echo = PROACTIVE connections (AI finds them, not user)
**6. Slack/Notion AI** (Anti-Pattern Reference)
- **What they do poorly:** Too frequent AI notifications = perceived as spam
- **Anti-pattern to avoid:** Insufficient contextualization
- **Connection to Memento:** Max 1 insight/day to avoid annoyance
- **Key lesson:** Restrictive frequency limits build trust
### Transferable UX Patterns
**Pattern 1: Contextual Triggers (from GitHub Copilot)**
- **Source:** Copilot suggests only when relevant, not permanently
- **Memento application:** Toast titles after 50+ words (not at first word)
- **Why it works:** Natural discovery, not overwhelming
- **Design implication:** Single-interaction rule (only one AI feature at a time)
- **Implementation:** Priority queue if multiple AI triggers fire simultaneously
**Pattern 2: Masonry Layout (from Google Keep)**
- **Source:** Google Keep uses masonry grid for notes
- **Memento application:** Already implemented in component inventory (MasonryGrid)
- **Why it works:** Space optimization, visually pleasing
- **Design implication:** Reuse existing MasonryGrid, add AI badges
- **Implementation:** AI badges on NoteCard ("Title Suggested", "Semantic Match")
**Pattern 3: Speed = Intelligence (from Linear)**
- **Source:** Linear feels "smart" because it's ultra-fast
- **Memento application:** < 2s titles, < 300ms semantic search
- **Why it works:** Fast AI = perceived intelligence
- **Design implication:** Optimistic UI, skeleton screens, background processing
- **Implementation:** Show "Generating..." only if > 1s (otherwise appears instant)
**Pattern 4: Graph Connections โ Memory Echo (from Obsidian)**
- **Source:** Obsidian shows manual graph view of connections
- **Memento application:** Memory Echo PROACTIVELY reveals connections
- **Innovation:** AI finds connections, not user
- **Design implication:** Subtle notification, max 1/day, ๐๐ feedback
- **Implementation:** Background cosine similarity analysis, user-triggered dismissal
**Pattern 5: Slash Commands โ Contextual Menu (from Notion)**
- **Source:** Notion uses `/` for commands
- **Memento application:** Reformulation via "..." menu on NoteCard (not slash)
- **Why different:** Slash commands too intrusive for simple notes
- **Design implication:** Contextual menu, not memorized commands
- **Implementation:** NoteCard overflow menu โ "Reformulate with AI" option
### Anti-Patterns to Avoid
**Anti-Pattern 1: Too Frequent AI Notifications (Slack AI, Notion AI)**
- **Problem:** "Hey! Try this feature!" every day = spam
- **Consequence:** Users disable all AI notifications
- **Memento solution:** Contextual triggers (50+ words), max 1 insight/day
- **Design implication:** Respect "Don't ask for this note" immediately
**Anti-Pattern 2: Permanent AI Toolbar (Too Many Apps)**
- **Problem:** Toolbar with 10 AI features = overwhelming
- **Consequence:** Users ignore everything, "analysis paralysis"
- **Memento solution:** Temporary toasts, features appear when relevant
- **Design implication:** No permanent "AI Features" badge in header
**Anti-Pattern 3: Black Box AI (ChatGPT, Claude UI)**
- **Problem:** Users don't know what AI is doing with their data
- **Consequence:** Skepticism, trust erosion (Sophie persona)
- **Memento solution:** Transparency ("I analyzed 150 notes"), explanatory badges
- **Design implication:** Tooltips, badges, status indicators explain "why"
**Anti-Pattern 4: Slow Loading Spinners (Legacy Apps)**
- **Problem:** 5+ second spinner = AI seems "slow" or "dumb"
- **Consequence:** Users think "not better than manual"
- **Memento solution:** < 2s titles, < 300ms search = perceived intelligence
- **Design implication:** Skeleton screens, optimistic UI, background jobs
**Anti-Pattern 5: Hidden AI Settings (Too Many SaaS)**
- **Problem:** AI settings buried 3 levels deep in obscure menu
- **Consequence:** Users don't know how to disable, frustration
- **Memento solution:** `/settings/ai` page visible, link in header
- **Design implication:** AI Settings = most important page in product
### Design Inspiration Strategy
**ADOPT (Take as-is):**
1. **Masonry Layout (Google Keep)**
- **Why:** Already implemented, works well
- **Usage:** Reuse existing MasonryGrid component
- **Addition:** AI badges on NoteCard ("Title Suggested", "Semantic Match")
2. **Contextual Triggers (GitHub Copilot)**
- **Why:** Non-intrusive, natural discovery
- **Usage:** Toast after 50+ words without title
- **Design:** Same pattern as Copilot - appear when relevant, not constant
3. **Speed Perception (Linear)**
- **Why:** Fast = smart
- **Usage:** < 2s title generation, < 300ms semantic search
- **Implementation:** Optimistic UI, skeleton screens, background processing
**ADAPT (Modify for Memento):**
1. **Graph View (Obsidian) โ Memory Echo Card**
- **Obsidian:** Manual graph view, see all connections
- **Memento:** Proactive notification, 1 connection at a time
- **Adaptation:** Subtle vs. visual, proactive vs. manual
2. **Slash Commands (Notion) โ Contextual Menu**
- **Notion:** `/` to access all features
- **Memento:** "..." menu on NoteCard for reformulation
- **Adaptation:** No commands to memorize, discovery via UI
3. **AI Sidebar (ChatGPT) โ Toast + Settings**
- **ChatGPT:** Permanent sidebar with AI chat
- **Memento:** Temporary toasts + granular Settings page
- **Adaptation:** Non-intrusive vs. always-visible, contextual vs. general
**AVOID (Anti-patterns to NOT reproduce):**
1. โ **Frequent AI notifications** (Slack/Notion AI) โ Max 1 insight/day
2. โ **Permanent AI toolbar** (Too many apps) โ Temporary toasts
3. โ **Black box** (ChatGPT) โ Full transparency
4. โ **Slow spinners** (Legacy) โ Optimistic UI
5. โ **Hidden settings** (Obscure SaaS) โ Visible `/settings/ai` page
**Summary Strategy:**
- **Learn** from Google Keep's simplicity + Copilot's proactivity
- **Innovate** with Memory Echo (no one has proactive connections)
- **Avoid** Slack/Notion AI mistakes (too intrusive)
- **Prioritize** speed (Linear) for perceived intelligence
---
## Design System Foundation
### Design System Choice
**Existing Design System:** Radix UI + Tailwind CSS 4
Memento already has a proven design system in place. No need to change - we'll extend it for Phase 1 AI features.
**Current Stack:**
- **UI Primitives:** Radix UI (accessible, unstyled components)
- **Styling:** Tailwind CSS 4 (utility-first framework)
- **Icons:** Lucide React
- **Layout:** Muuri (masonry), @dnd-kit (drag & drop)
**This is a "Themeable System" approach** - maximum flexibility with proven foundation.
### Rationale for Selection
**1. Development Speed** โก
- **Timeline constraint:** 8-12 weeks for MVP
- **20+ existing components:** NoteCard, LabelSelector, MasonryGrid already built
- **Focus on AI logic:** Don't waste time on basic UI components
- **Result:** Ship Phase 1 faster, concentrate on innovation (Memory Echo)
**2. Accessibility-First** โฟ
- **WCAG 2.1 AA compliance:** Radix UI provides this out-of-the-box
- **11 accessibility NFRs:** Keyboard nav, ARIA, focus management included
- **Screen reader support:** Critical for "Announce AI-generated content" (NFR-A11Y-002)
- **Result:** Meet legal requirements without custom ARIA work
**3. Customization Flexibility** ๐จ
- **Tailwind utilities:** Rapid styling for new AI components
- **Radix primitives:** Unstyled = full control over appearance
- **Consistent + unique:** Match existing look while differentiating AI features
- **Result:** Coherent UX, AI features feel integrated (not bolted-on)
**4. Long-Term Maintenance** ๐ง
- **Active communities:** Radix & Tailwind have excellent maintenance
- **Industry standards:** Not risking abandoned libraries
- **Future-proof:** Compatible with Next.js 16, React 19, TypeScript 5
- **Result:** Safe technical choice for years to come
**5. Performance** ๐
- **Tree-shakeable:** Import only used components (NFR-PERF-007: < 200KB bundle)
- **Tailwind purge:** Automatic CSS removal (only used styles in bundle)
- **RSC compatible:** Works with React Server Components (Next.js App Router)
- **Result:** Fast load times = perceived AI intelligence
### Implementation Approach
**Strategy: Extended Design System**
**1. Reuse 100% of Existing Components**
- NoteCard, MasonryGrid, LabelSelector, Header, Sidebar - all stay
- **No redesign:** Maintain visual consistency for current users
- **AI enhancements:** Add badges, indicators, states to existing components
**2. Create 7 New AI-Specific Components**
| Component | Purpose | Radix Primitive | Timeline |
|-----------|---------|-----------------|----------|
| **AIToast** | Contextual notification for title suggestions | `Toast` | Week 2 |
| **TitleSuggestions** | Dropdown with 3 AI title options | `DropdownMenu` | Week 2 |
| **MemoryEchoCard** | Card displaying 2 connected notes | Custom + `Dialog` | Week 4 |
| **ReformulationModal** | Paragraph selection + reformulation UI | `Dialog` | Week 3 |
| **AISettingsPanel** | Granular ON/OFF switches for AI features | Form + `Switch` | Week 5 |
| **SemanticBadge** | "Exact Match \| Semantic Match" indicator | Custom | Week 3 |
| **ProviderIndicator** | "โ Local Ollama \| โ OpenAI Cloud" status | Custom | Week 1 |
**3. Define AI Design Tokens**
```css
/* AI-specific colors (Tailwind config extension) */
--ai-primary: #8B5CF6; /* Purple - AI intelligence */
--ai-accent: #3B82F6; /* Blue - semantic matches */
--ai-success: #10B981; /* Green - positive feedback */
--ai-warning: #F59E0B; /* Yellow - processing states */
--ai-error: #EF4444; /* Red - errors, negative feedback */
/* AI-specific spacing */
--ai-toast-margin: 1rem; /* Toast positioning */
--ai-card-gap: 1.5rem; /* Gap between Memory Echo notes */
/* AI-specific animations */
@keyframes ai-fade-in {
from { opacity: 0; transform: translateY(8px); }
to { opacity: 1; transform: translateY(0); }
}
@keyframes ai-scale-up {
from { opacity: 0; transform: scale(0.98); }
to { opacity: 1; transform: scale(1); }
}
```
**4. Component Hierarchy (Extended)**
```
Existing Components (Keep)
โโโ Layout
โ โโโ Header โ HeaderWrapper โ UserNav
โ โ โโโ ADD: ProviderIndicator (new)
โ โโโ Sidebar
โ โโโ MasonryGrid
โ โโโ NoteCard (enhanced)
โ โโโ ADD: SemanticBadge (new)
โ โโโ ADD: ReformulationMenu (new)
โ
New AI Components
โโโ AIToast (contextual notification)
โโโ TitleSuggestions (dropdown)
โโโ MemoryEchoCard (proactive insights)
โโโ ReformulationModal (paragraph AI)
โโโ AISettingsPanel (granular control)
```
### Customization Strategy
**Brand Differentiation (Phase 1 - Minimal):**
**1. Color Strategy**
- **Purple (#8B5CF6)** = Primary AI color (intelligence, differentiation)
- **Keep existing note colors:** Red, orange, yellow, green, teal, blue, purple, pink, gray
- **AI badge color:** Blue gradient (#3B82F6 โ #60A5FA) for semantic matches
- **Rationale:** Purple = "AI is special but not alienating"
**2. Typography (No Change)**
- **System font stack** (Tailwind default)
- **Reason:** Fast loading, familiar to users, zero-config
- **AI text:** Same fonts, semantic meaning via color + icon
**3. Spacing (No Change)**
- **Tailwind spacing scale:** 4px base unit (4, 8, 12, 16, 24, 32...)
- **AI components:** Use existing scale for consistency
- **Rationale:** Maintain visual rhythm, not "another design language"
**4. Component Shape (Consistent)**
- **Border radius:** Match NoteCard (likely `rounded-md`)
- **Shadows:** Match existing cards (elevation system)
- **AI components:** Same shape language = feeling of integration
**5. Animation Standards**
| Animation | Duration | Easing | Use Case |
|-----------|----------|--------|----------|
| **ai-fade-in** | 200ms | ease-out | Toast appearance |
| **ai-slide-up** | 250ms | ease-out | Suggestions dropdown |
| **ai-scale-up** | 150ms | ease-out | Memory Echo card |
| **ai-pulse** | 2s | ease-in-out | Provider connection status |
**Rationale:** Subtle, fast animations = "AI is snappy and responsive"
---
## Core User Experience with Notebooks
### Defining Experience: Memory Echo in Notebook Context
**The Core Interaction that Makes Memento Special:**
> **"Memento reveals connections between my notes (within notebooks) that I hadn't seen"**
Every successful product has a defining experience - the interaction that, if nailed, makes everything else follow.
**Famous examples:**
- Tinder: "Swipe to match with people"
- Snapchat: "Share photos that disappear"
- Instagram: "Share perfect moments with filters"
- Spotify: "Discover and play any song instantly"
**For Memento Phase 1, the defining experience is:**
**Memory Echo:** "I noticed something..." - The AI proactively reveals a connection between notes within the user's current notebook context that they hadn't discovered.
This is THE moment users will describe to their friends:
> *"You have to see this! Memento showed me that I had two related notes from January and this week that I hadn't connected!"*
This is the "Aha!" moment that creates the emotion: "Wow, that's clever!" (from Emotional Response analysis).
**Critical Innovation:** Memory Echo operates within **Notebook context** by default, making connections more relevant and scoped to the user's current work area.
### User Mental Model
**How users currently think about note-taking:**
**Current Mental Model (Before Memento Phase 1):**
```
My notes = Disconnected silos
โโโ I capture ideas
โโโ I try to remember them later
โโโ I lose connections between ideas (human = limited)
```
**Problems:**
- "I noted that somewhere, but I don't remember where"
- "I know I thought about that, but I can't find the note"
- "My ideas are connected, but my notes don't show it"
**Enhanced Mental Model (With Memento Notebooks + Memory Echo):**
```
My Notes = Organized Network
โโโ I organize into Notebooks (Work, Personal, Projects...)
โโโ Memento organizes within each Notebook in background
โโโ Memento reveals invisible connections (Notebook-scoped)
```
**Transformation:**
- **Before:** "I search my notes" (active, effort)
- **After:** "Memento finds what I forgot" (proactive, surprise)
- **Notebooks provide:** Contextual scope = more relevant connections
**Notebook Mental Model:**
- **Physical analogy:** Real notebooks (Work, Personal, Ideas...)
- **Clear separation:** Work vs. Personal = mental boundaries
- **Scalability:** 1000+ notes distributed across notebooks = manageable
- **Natural organization:** Like having different physical notebooks for different purposes
**User Expectations:**
1. **Fast capture** = Instant (Google Keep style)
2. **Organized structure** = Notebooks provide organization
3. **Proactive discovery** = Memory Echo within current notebook context
4. **Control** = Can switch notebooks, view global connections optionally
**Potential Confusions:**
- "Does Memento read all my notes?" โ Yes, but locally (privacy-first, Ollama)
- "How does it know they're connected?" โ Explanation: Semantic embeddings
- "Is it always accurate?" โ No, hence ๐ feedback learning system
- "Are connections across notebooks or within?" โ Within by default, optional global view
### Success Criteria
**When does the defining experience "just work"?**
**1. "It Just Works" - Magic Happens**
- **Trigger:** Background analysis finds cosine similarity > 0.75 within current notebook
- **Interaction:** "I noticed something..." notification appears
- **Success:** User clicks "View Connection" (> 40% CTR target from PRD)
- **Feedback:** Two connected notes clearly show semantic link
- **User thought:** "Oh wow! I hadn't seen that connection!"
- **Notebook context:** Connection within current notebook = more relevant
**2. Perceived Intelligence - AI Feels Smart**
- **Trigger:** Memory Echo notification appears
- **Success:** < 100ms UI freeze (feels instantaneous)
- **Feedback:** No slow loading spinner (perceived as "dumb")
- **User thought:** "Wow, that's instant, Memento is smart!"
- **Notebook enhancement:** Scoped context = appears more intelligent
**3. Relevant, Not Spammy - Right Moment, Right Place**
- **Trigger:** Max 1 insight/day (configurable 0-3)
- **Success:** User thinks "That's useful" not "Another notification..."
- **Feedback:** User doesn't disable Memory Echo feature
- **User thought:** "Interesting, thanks Memento!"
- **Notebook relevance:** "This helps with my current work in this notebook"
**4. Trust Building - Confidence Establishes**
- **Trigger:** First Memory Echo connection
- **Success:** Connection IS relevant (not hallucination)
- **Feedback:** ๐๐ buttons available and respected
- **User thought:** "I'm in control, no problem if it's wrong"
- **Notebook control:** User can switch notebooks to find different connections
**5. Notebook Organization - Structure Feels Natural**
- **Trigger:** User creates/accesses notes in specific notebooks
- **Success:** Notes automatically organized by notebook context
- **Feedback:** Sidebar shows notebook hierarchy clearly
- **User thought:** "Finally, my work is organized!"
- **Inbox concept:** Unassigned notes go to "Inbox" notebook (default)
**Success Indicators:**
- โ > 40% CTR on "View Connection" (PRD requirement)
- โ > 3:1 ๐ ratio (quality threshold)
- โ < 1% users disable Memory Echo (not frustrating)
- โ User quote: "Memento surprised me by finding X in my Work notes!"
- โ Notebook adoption: > 80% users create custom notebooks beyond "Inbox"
### Novel UX Patterns
**Pattern Analysis:**
**Memory Echo = Novel Pattern in Note-Taking**
**Current Market State:**
- **Google Keep:** No AI proactive features at all
- **Notion:** On-demand AI (slash commands), not proactive
- **Obsidian:** Manual graph view (no AI)
- **Roam Research:** Graph view, no proactive insights
- **Evernote:** Notebook organization exists, but no AI connections
**Memento Innovation:**
- **FIRST** to combine:
- **Notebook organization** (familiar structure)
- **Semantic search** (embeddings)
- **Proactive notifications** (Memory Echo)
- **Feedback learning** (๐ system)
- **Privacy-first** (local processing option)
- **Notebook-scoped insights** (contextual relevance)
**This is HYBRID innovation:**
- **Base:** Notebook organization (Evernote-like) โ **Established**
- **Base:** Graph connections (Obsidian-like) โ **Established**
- **Innovation:** AI proactive + feedback loop + notebook scope โ **Novel**
**User Education:**
**Familiar Metaphors:**
- "Like an assistant thinking about your notes while you sleep"
- "Like Google Photos grouping photos, but for your ideas"
- "Like Spotify Discover Weekly, but for your notes within each notebook"
**Progressive Onboarding:**
1. User captures notes in "Inbox" (familiar, single notebook)
2. Title suggestions toast (discovery of AI)
3. Create custom "Work" notebook (structure discovery)
4. Memory Echo appears in "Work" context (surprise "Aha!")
5. Granular settings (control discovery)
**Notebook-Specific Education:**
- "Each notebook is like a separate world - Memento finds connections within it"
- "Switch notebooks to discover connections in different contexts"
- "Use 'Inbox' for quick capture, organize into notebooks later"
### Experience Mechanics
**Detailed breakdown of Memory Echo interaction within Notebook context:**
#### 1. Initiation (Trigger)
**Backend (Silent, Invisible):**
- **Timing:** Every hour (cron job)
- **Scope:** Analyze embeddings within **current notebook**
- **Process:**
1. Fetch all note embeddings from **current notebook**
2. Calculate cosine similarity matrix (notebook-scoped)
3. Filter: similarity > 0.75 (threshold)
4. Sort by score descending
5. Fetch top 1 connection
- **Duration:** < 100ms UI freeze (background job)
- **Notebook isolation:** Each notebook has independent similarity analysis
**Frontend (User-Visible):**
- **Trigger:** Notification appears (no "Run Memory Echo" button)
- **Timing:** Max 1 time/day (configurable 0-3)
- **Condition:** At least 2 notes with embeddings in **current notebook**
- **Notebook indicator:** Notification shows which notebook: "๐ก I noticed something in your **Work** notes..."
**Visual:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ก I noticed something... โ
โ โ
โ In your "Work" notes: โ
โ โ
โ You noted "Node.js performance" โ
โ and "Next.js optimization". These โ
โ notes are connected. โ
โ โ
โ [View Connection] [Dismiss] [ร] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
#### 2. Interaction (User Actions)
**Option A: "View Connection" (Success Path)**
1. **Click** โ MemoryEchoCard modal/panel opens
2. **Display:** 2 notes side-by-side (desktop) or stacked (mobile)
3. **Visualization:**
- Note A: "Node.js performance tips"
- Note B: "Next.js optimization"
- Highlight: Connected words/phrases emphasized
- Badge: "93% match" (cosine similarity)
- **Notebook context:** "From: Work notebook"
4. **Available actions:**
- "Link these notes" (create shared label?)
- ๐ "This is helpful" (positive feedback)
- ๐ "Not relevant" (negative feedback)
- [ร] Close
**Option B: "Dismiss" (Neutral Path)**
1. **Click** โ Notification disappears
2. **Feedback:** "Ok, maybe next time"
3. **No data stored** (no learning)
**Option C: [ร] Close (Same as Dismiss)**
1. **Click** โ Notification disappears
2. **No feedback**
#### 3. Feedback (Learning Loop)
**Positive Feedback (๐):**
- **Action:** User clicks ๐ after "View Connection"
- **System response:**
- Toast: "Thanks! We'll show more insights like this in **Work** notes."
- Data: Store +1 score for this connection type within notebook context
- Learning: Increase cosine threshold for this connection type in this notebook
- **Future:** More of this connection type in this notebook
**Negative Feedback (๐):**
- **Action:** User clicks ๐ after "View Connection"
- **System response:**
- Modal: "Why wasn't this relevant?" (optional)
- "Wrong connection"
- "Not useful right now"
- "Too many notifications"
- "Wrong notebook context"
- Toast: "Thanks for teaching us! We'll improve."
- Data: Store -1 score for this connection type in this notebook
- Learning: Decrease cosine threshold for this connection type in this notebook
- **Future:** Less of this connection type in this notebook
**No Feedback (Dismiss/Close):**
- **No learning** (neutral)
- **Counts as "non-action"** in analytics
#### 4. Completion & Notebook Context
**Success Path Completed:**
- **Outcome:** User discovered invisible connection within notebook
- **Next steps:**
- Can link notes (action: create shared label)
- Can continue work in current notebook
- **Option:** "See connections in other notebooks" (toggle global)
- Next Memory Echo: Tomorrow (max 1/day)
**Switching Notebooks:**
- **User action:** Click different notebook in sidebar
- **System response:**
- Switch view to that notebook's masonry grid
- Update Memory Echo context to new notebook
- Background analysis now scopes to new notebook
- **Notification:** "๐ก Switched to **Personal** notebook"
**Global Connections (Optional Feature):**
- **User action:** Toggle "Show connections across all notebooks"
- **System response:**
- Memory Echo scope expands beyond current notebook
- Notification: "๐ก I noticed something **across your notes**..."
- Badge: "Global connection" vs. "Notebook connection"
- **Use case:** User wants serendipitous cross-notebook discoveries
**Dismiss Path Completed:**
- **Outcome:** Notification closed, no learning
- **Next steps:**
- Continue normal capture in current notebook
- Next Memory Echo: Tomorrow (frequency unchanged)
**Settings Path (Control):**
- **User navigates:** `/settings/ai`
- **Actions:**
- Change "Memory Echo frequency" (1 โ 0 to disable)
- "Notebook scope" toggle: Current notebook vs. All notebooks
- Per-notebook frequency: Work = daily, Personal = weekly
- **Respect:** Immediate, no "are you sure?"
---
## Visual Design Foundation
### Color System
#### Philosophy: Intelligence + Clartรฉ
The color palette balances **AI modernity** (violet/bleu) with **content-first design** (blanc pur), ensuring user notes remain the focal point while AI interactions are clearly visible and trustworthy.
#### Core Palette
```css
/* Brand Colors */
--primary: #8B5CF6; /* Violet - IA Intelligence */
--primary-light: #A78BFA;
--primary-dark: #7C3AED;
--secondary: #3B82F6; /* Bleu - Confiance */
--secondary-light: #60A5FA;
--secondary-dark: #2563EB;
--accent: #10B981; /* Vert รฉmeraude - Success, Positive Feedback */
```
**Rationale:**
- **Violet (#8B5CF6)**: Evokes AI creativity and intelligence, modern and tech-forward
- **Bleu (#3B82F6)**: Builds trust for privacy-conscious users, stable and professional
- **Vert (#10B981)**: Positive reinforcement for AI feedback system (๐๐), encourages engagement
#### Semantic Colors
```css
/* Functional Colors */
--success: #10B981; /* Green - Success, accepted suggestions */
--warning: #F59E0B; /* Amber - Processing states, caution */
--error: #EF4444; /* Red - Errors, rejected suggestions */
--info: #3B82F6; /* Blue - Informational */
```
#### AI-Specific Colors
```css
/* AI Feature Colors */
--ai-primary: #8B5CF6; /* Primary AI interactions */
--ai-accent: #3B82F6; /* Semantic search matches */
--ai-processing: #F59E0B; /* Background processing state */
--ai-connection: #8B5CF6; /* Memory Echo link highlights */
--ai-suggestion: #A78BFA; /* Suggested titles, reformulations */
```
**Usage:**
- **Memory Echo cards**: Purple border (`--ai-connection`) + subtle purple background
- **Title suggestions**: Purple text (`--ai-suggestion`) for AI-generated options
- **Semantic search badges**: Blue (`--ai-accent`) for "Semantic Match" indicators
- **Processing states**: Amber spinner (`--ai-processing`) during embedding generation
#### Neutral Colors
```css
/* Background & Surface */
--background: #FFFFFF; /* Pure white - content focus */
--surface: #F9FAFB; /* Very light gray - subtle separation */
--surface-elevated: #FFFFFF; /* Cards, modals (elevated on white) */
/* Text Colors */
--text-primary: #111827; /* Nearly black - main content */
--text-secondary: #6B7280; /* Medium gray - metadata, secondary */
--text-muted: #9CA3AF; /* Light gray - timestamps, hints */
/* Borders & Dividers */
--border: #E5E7EB; /* Light gray - subtle separation */
--border-hover: #D1D5DB; /* Medium gray - interactive states */
```
**Design Philosophy:**
- **Blanc pur background**: Ensures notes are the hero, not the interface
- **Subtle surfaces**: Light grays (#F9FAFB) provide visual hierarchy without distraction
- **High contrast text**: Meets WCAG AA standards (4.5:1 minimum contrast ratio)
#### Accessibility Compliance
โ **WCAG 2.1 Level AA**:
- All text-to-background contrast ratios โฅ 4.5:1
- Large text (18px+) contrast โฅ 3:1
- Interactive elements (buttons, links) have visible focus states
- Color not used as the only visual means of conveying information
โ **Color Independence**:
- AI features use color + icon + text label (triple coding)
- Memory Echo: Purple + ๐ก icon + "I noticed..." text
- Semantic badges: Blue + "Semantic Match" label + dashed underline
---
### Typography System
#### Philosophy: Performance + Lisibilitรฉ
Using **system fonts** eliminates external font loading (zero DevOps, maximum performance) while ensuring native OS optimization and multilingual support (French accents, emojis).
#### Font Family Stack
```css
--font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
sans-serif;
```
**Rationale:**
- **Performance**: No external HTTP requests, instant rendering
- **Native feel**: Each OS shows its optimized font (San Francisco on Mac, Segoe UI on Windows)
- **Multilingual**: Native support for French accents, emojis, special characters
- **Accessibility**: System fonts are designed for screen readers and zoom
#### Type Scale (Perfect Fourth - 1.333)
```css
/* Font Sizes */
--text-xs: 0.75rem; /* 12px - Captions, metadata */
--text-sm: 0.875rem; /* 14px - Secondary text, labels, helper text */
--text-base: 1rem; /* 16px - Body content (WCAG recommended minimum) */
--text-lg: 1.125rem; /* 18px - Lead paragraphs, emphasized content */
--text-xl: 1.25rem; /* 20px - Note titles in cards */
--text-2xl: 1.5rem; /* 24px - Cahier (notebook) titles in sidebar */
--text-3xl: 1.875rem; /* 30px - Page headings */
--text-4xl: 2.25rem; /* 36px - Hero text, empty states */
```
**Scale Choice**: Perfect Fourth (1.333 ratio) provides harmonious progression while maintaining distinct hierarchy levels.
#### Line Heights
```css
/* Line Spacing */
--leading-tight: 1.25; /* Headings - compact, impactful */
--leading-normal: 1.5; /* UI text, labels - standard readability */
--leading-relaxed: 1.75; /* Body content - optimal for long-form */
```
#### Font Weights
```css
--font-normal: 400; /* Body text, standard content */
--font-medium: 500; /* UI emphasis, button text */
--font-semibold: 600; /* Headings, important labels */
--font-bold: 700; /* Strong emphasis, CTAs */
```
#### Typographic Usage Guidelines
| Element | Size | Weight | Line Height | Use Case |
|---------|------|--------|-------------|----------|
| Page Headings | `text-3xl` (30px) | Semibold (600) | Tight (1.25) | Page titles, empty state headers |
| Cahier Titles | `text-2xl` (24px) | Semibold (600) | Normal (1.5) | Sidebar notebook names |
| Note Card Titles | `text-xl` (20px) | Semibold (600) | Normal (1.5) | Main note title in masonry grid |
| Lead Paragraphs | `text-lg` (18px) | Normal (400) | Relaxed (1.75) | Emphasized intro text |
| Body Content | `text-base` (16px) | Normal (400) | Relaxed (1.75) | Note content, long-form text |
| Secondary Text | `text-sm` (14px) | Normal (400) | Normal (1.5) | Metadata, timestamps, hints |
| Captions | `text-xs` (12px) | Medium (500) | Normal (1.5) | AI badges, helper text |
#### Responsive Typography
Typography scales with viewport width for optimal readability:
```css
/* Mobile-first approach */
@media (min-width: 768px) {
/* Tablet+: Increase base size slightly */
:root {
--text-base: 1.125rem; /* 18px on larger screens */
}
}
```
#### Accessibility Features
โ **Text Zoom Support**:
- Layout supports up to 200% text zoom without horizontal scrolling
- Flexible units (rem) ensure proportional scaling
โ **Readability**:
- Minimum body text: 16px (WCAG recommended)
- Line height: 1.75 for body content (prevents walls of text)
- Max line length: 65-75 characters for optimal reading speed
โ **Screen Reader Optimization**:
- Semantic HTML heading hierarchy (h1 โ h2 โ h3)
- System fonts render consistently across assistive technologies
---
### Spacing & Layout Foundation
#### Philosophy: Balanced Density
Using an **8px grid system** provides industry-standard spacing that balances content visibility with breathing room, ensuring the interface feels neither cluttered nor wasteful.
#### Spacing Scale (8px Base Unit)
```css
/* 8px Grid Scale */
--space-0: 0; /* No spacing */
--space-1: 0.25rem; /* 4px - Micro spacing between related elements */
--space-2: 0.5rem; /* 8px - Base unit, tight grouping */
--space-3: 0.75rem; /* 12px - Compact separation */
--space-4: 1rem; /* 16px - Comfortable spacing (most common) */
--space-5: 1.25rem; /* 20px - Section separation */
--space-6: 1.5rem; /* 24px - Major component gaps */
--space-8: 2rem; /* 32px - Component grouping */
--space-10: 2.5rem; /* 40px - Page margins */
--space-12: 3rem; /* 48px - Large section separation */
--space-16: 4rem; /* 64px - Hero sections, empty states */
```
**Why 8px?**
- Industry standard (Bootstrap, Material Design, Tailwind)
- Highly divisible (16, 24, 32, 40, 48 are all multiples)
- Natural visual rhythm
- Tailwind CSS native support (spacing-2 = 8px)
#### Layout Component Spacing
**Masonry Grid (Notes within Cahiers):**
- Gap between cards: `--space-4` (16px) - comfortable separation
- Padding within cards: `--space-4` (16px) - content breathing room
- Card corner radius: `8px` (rounded-lg) - modern but not distracting
**Sidebar (Cahiers Navigation):**
- Width: `256px` (w-64) on desktop, full width on mobile
- Padding vertical: `--space-4` (16px)
- Padding horizontal: `--space-3` (12px)
- Gap between cahier items: `--space-2` (8px)
**Header (Top Bar):**
- Height: `64px` (h-16)
- Padding horizontal: `--space-4` (16px)
- Gap between search and user menu: `--space-4` (16px)
**AI Toast/Notifications:**
- Padding: `--space-4` (16px) all around
- Margin from viewport edge: `--space-4` (16px)
- Gap between toasts: `--space-3` (12px)
**Memory Echo Card:**
- Padding: `--space-6` (24px)
- Border: 2px solid `--ai-connection` (#8B5CF6)
- Corner radius: `12px` (rounded-xl) - distinctive from note cards
#### Grid System: 12 Columns (Adaptive)
**Why 12 Columns?**
- Highly flexible (divisible by 2, 3, 4, 6)
- Supports multiple layout patterns (2-col, 3-col, 4-col, 6-col)
- Industry standard (Bootstrap, Foundation, Tailwind)
**Breakpoints:**
```css
/* Tailwind Standard Breakpoints */
--breakpoint-sm: 640px; /* Mobile large */
--breakpoint-md: 768px; /* Tablet portrait */
--breakpoint-lg: 1024px; /* Desktop, laptop */
--breakpoint-xl: 1280px; /* Desktop large */
```
**Responsive Masonry Layout:**
| Screen Size | Columns | Column Width | Notes Visible |
|-------------|---------|--------------|---------------|
| Mobile (< 768px) | 1 | 100% | Single column stack |
| Tablet (768-1024px) | 2 | ~48% each | 2-column grid |
| Desktop (1024-1280px) | 3 | ~32% each | 3-column grid |
| Desktop XL (> 1280px) | 4 | ~24% each | 4-column grid |
**Notebook Sidebar Layout:**
- **Desktop (> 1024px)**: Fixed 256px sidebar on left, main content fills remaining width
- **Tablet/Mobile (< 1024px)**: Collapsible sidebar (hamburger menu) to maximize content space
#### Layout Principles
1. **Content-First Hierarchy**:
- Pure white background (`#FFFFFF`) ensures notes are focal point
- Subtle surface colors (`#F9FAFB`) separate sections without distraction
2. **Visual Rhythm**:
- Consistent 16px padding inside cards and components
- 16px gaps between masonry items for consistent whitespace
3. **Responsive Flexibility**:
- Masonry grid adapts column count based on viewport width
- Sidebar collapses on mobile to preserve screen real estate
4. **AI Feature Prominence**:
- Memory Echo cards use 24px padding (larger than note cards' 16px) for emphasis
- AI toasts float 16px from edges to ensure visibility without blocking content
5. **Accessibility Spacing**:
- Minimum touch target size: 44ร44px (WCAG 2.5.5)
- Focus indicators have 2px outline with sufficient contrast
---
### Accessibility Considerations
#### Visual Accessibility
โ **Color Contrast** (WCAG 2.1 Level AA):
- All normal text: Minimum 4.5:1 contrast ratio
- Large text (18px+): Minimum 3:1 contrast ratio
- Interactive elements: Minimum 3:1 contrast ratio
โ **Text Scaling**:
- Layout supports 200% text zoom without horizontal scrolling
- Rem-based units ensure proportional scaling
- No fixed-width containers that break on zoom
โ **Focus Indicators**:
- All interactive elements have visible focus states
- 2px solid outline in primary color (`#8B5CF6`)
- Focus outline offset: 2px from element
#### Color Independence
โ **Triple Coding for AI Features**:
- **Color**: Purple/blue for AI interactions
- **Icon**: ๐ก for Memory Echo, ๐ for search, โจ for suggestions
- **Text**: Clear labels ("I noticed something...", "Semantic Match")
โ **Example - Memory Echo**:
- Color: Purple border + purple tint background
- Icon: ๐ก lightbulb icon
- Text: "I noticed something..." headline + explanation
#### Screen Reader Support
โ **Semantic HTML**:
- Proper heading hierarchy (h1 โ h2 โ h3)
- ARIA labels for custom components (Memory Echo cards, AI toasts)
- Live regions for dynamic content (AI notifications)
โ **Example - Memory Echo Card**:
```html
๐ก
I noticed something...
```
#### Keyboard Navigation
โ **Full Keyboard Support**:
- Tab: Navigate through interactive elements
- Enter/Space: Activate buttons, links
- Escape: Close modals, dismiss toasts
- Arrow keys: Navigate within lists (cahiers, tags)
โ **Visible Focus**:
- 2px purple outline on focused elements
- High contrast (4.5:1 minimum) against backgrounds
- No outline removal on focus (`outline-none` only for mouse users via `:focus-visible`)
#### Motion Sensitivity
โ **Respects `prefers-reduced-motion`**:
- Animations disabled for users who prefer reduced motion
- Transitions: `0.2s ease-out` (gentle, not jarring)
- Memory Echo appearance: Fade-in (no slide/bounce for motion-sensitive users)
---
### Visual Foundation Strategy Summary
**Color System:**
- Intelligence-focused palette (violet/bleu) with pure white background
- AI features clearly distinguished with semantic colors
- WCAG AA compliant contrast ratios
**Typography:**
- System fonts for maximum performance and native feel
- Perfect Fourth scale (1.333) for harmonious hierarchy
- 16px base with 1.75 line height for optimal readability
- Supports French accents, emojis, and special characters
**Spacing & Layout:**
- 8px grid system for consistent visual rhythm
- 12-column adaptive layout for responsive masonry grid
- 16px component padding/gaps for balanced density
- Cahiers sidebar: 256px desktop, collapsible on mobile
**Accessibility:**
- Color independence (triple coding for AI features)
- 200% text zoom support
- Full keyboard navigation
- Screen reader optimization with semantic HTML + ARIA
This foundation ensures **consistency across all design decisions** while maintaining the "Zรฉro Prise de Tรชte" philosophy - the design system is invisible, letting users focus on their notes and AI-powered insights.
---
## Design Direction Decision
### Design Directions Explored
Three distinct design directions were evaluated for Memento Phase 1 MVP AI:
**Direction A: "Invisible IA"** (Chosen)
- Philosophy: AI is present but never intrusive - appears when needed, then recedes
- Layout: Full-screen masonry grid with minimal sidebar (256px, collapsible)
- AI Presentation: Contextual elements (toasts, hover states, dropdowns) only
- Visual Density: High (maximize note visibility)
- Color Dominance: Pure white with violet/blue accents for AI only
**Direction B: "IA Partenaire"** (Evaluated)
- Philosophy: AI as visible copilot, always present to assist
- Layout: Masonry grid + sidebar + permanent AI Panel (320px right)
- AI Presentation: Always-visible suggestions, connections, insights
- Visual Density: Medium (balance content and AI context)
- Color Dominance: White with AI-colored zones (light purple backgrounds)
**Direction C: "Hydra Contextuelle"** (Evaluated)
- Philosophy: Interface adapts dynamically to user intent
- Layout: Adaptive modes (Capture, Discovery, Focus)
- AI Presentation: Mode-specific interfaces with animated transitions
- Visual Density: Variable per mode
- Color Dominance: Adaptive white โ blue โ purple based on mode
### Chosen Direction
**Direction A: "Invisible IA" with Direction B Enhancement**
The chosen direction combines the **content-first minimalism** of Direction A with the **AI visibility** element from Direction B:
**Core Principles:**
1. **Content is King**: Pure white background, masonry grid fills viewport
2. **AI Contextual**: AI features appear only at relevant moments
3. **Non-Intrusive Discovery**: Memory Echo creates "Aha!" without permanent UI
4. **Progressive Enhancement**: Users discover AI features naturally through use
**Key Design Elements:**
**Layout Structure:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Header (64px) โ
โ [Logo] [Search] [โจ AI: On โผ] [User] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Cahiers โ Masonry Grid (Notes) โ
โ Sidebar โ โ
โ (256px) โ [Note Card] [Note Card] [Note Card]โ
โ โ [Note Card] [Note Card] โ
โ Inbox โ โ
โ Work โ โ
โ Personal โ โ
โ + New โ โ
โโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**AI Feature Integration:**
1. **Memory Echo** โญ (Defining "Aha!" Experience)
- **Presentation**: Floating toast notification (bottom-right)
- **Appearance**: Fade-in with subtle purple border
- **Content**: "๐ก I noticed something in your **Work** notes..."
- **Interaction**: Dismissible card with ๐๐ feedback
- **Persistence**: Auto-dismiss after 30s, or manual close
- **No permanent space**: Appears, delivers value, recedes
2. **Title Suggestions** (Feature 1)
- **Trigger**: On note title focus/blur after content entry
- **Presentation**: Dropdown menu below title field
- **Content**: 3 AI-generated title options with โจ indicator
- **Interaction**: Click to select, ESC to dismiss
- **Visual**: Purple text for AI suggestions, hover state with bg-purple-50
3. **Semantic Search** (Feature 2)
- **Presentation**: Unified search bar (no visible keyword/semantic toggle)
- **Result Indication**: Blue badge "Semantic Match" next to relevant results
- **Visual**: Dashed blue underline for semantic match terms
- **No separation**: Users don't distinguish keyword vs semantic - "it just works"
4. **Paragraph Reformulation** (Feature 3)
- **Trigger**: Manual "โจ Reformulate" button appears on paragraph hover
- **Presentation**: Modal dialog with comparison (original | AI suggestion)
- **Interaction**: Accept/Reject/Retry options
- **Visual**: Purple border for modal, green checkmark for accepted text
5. **AI Status Badge** (Direction B Enhancement)
- **Location**: Header, right side (before user menu)
- **Content**: "โจ AI: On" with dropdown access to settings
- **Purpose**: Permanent AI visibility without occupying UI space
- **Dropdown**: Quick access to AI features status, settings, provider info
**Color Strategy (Direction A):**
- **Background**: Pure white (#FFFFFF) - content focus
- **Cards**: White with subtle gray border (#E5E7EB) + shadow-sm
- **AI Elements**: Violet (#8B5CF6) and Blue (#3B82F6) ONLY for AI interactions
- **No permanent AI zones**: No dedicated AI panel backgrounds or colored sections
**Spacing Strategy:**
- **Masonry Gap**: 16px (space-4) - comfortable breathing room
- **Card Padding**: 16px (space-4) - consistent with 8px grid
- **Sidebar Width**: 256px (w-64) - sufficient for cahier names
- **Header Height**: 64px (h-16) - compact but functional
**Typography Strategy:**
- **Cahier Titles**: 24px semibold (text-2xl font-semibold) - clear navigation
- **Note Card Titles**: 20px semibold (text-xl font-semibold) - scannable
- **Body Content**: 16px normal (text-base font-normal) - optimal readability
- **AI Text**: System fonts, purple color for AI-generated content
### Design Rationale
**Why "Invisible IA" with AI Badge?**
**1. Alignment with "Zรฉro Prise de Tรชte" Philosophy**
- Users focus on **capturing notes**, not managing AI features
- AI appears **contextually** (toasts, hover states) without cluttering the interface
- No permanent AI panel means **maximum space for content**
- Progressive discovery: Users encounter AI features **naturally** through use
**2. Optimal for Cahiers Structure**
- Masonry grid maximizes **note visibility** within each notebook
- Sidebar Cahiers + full-screen grid = **clear mental model**
- Switching notebooks shows **different note collections** instantly
- Memory Echo scoped to current Cahier = **relevant, not overwhelming** connections
**3. Creates Strong "Aha!" Emotional Response**
- Memory Echo toast appearing from "nowhere" = **surprise and delight**
- "I didn't search, it found me" = **proactive intelligence**
- No permanent AI UI means the AI feels **magical, not mechanical**
- Purple/blue accents make AI moments **visually distinctive**
**4. MVP Simplicity**
- Fewer components to build (no permanent AI panel, no mode switching)
- Focus on **4 core features** without complex UI state management
- Easier to test and iterate on **individual AI interactions**
- Faster to implement with **existing Radix UI primitives** (Toast, Dropdown, Dialog)
**5. Scalability**
- Can add AI Panel later if users request more visibility
- Badge AI provides **hook for future AI features** (chat, commands)
- Invisible IA foundation means **new features can be added** without redesign
- User behavior analytics will inform **which AI features need more visibility**
**Why the AI Badge Element?**
**From Direction B Evaluation:**
- Users need **assurance AI is working** (especially Ollama local users)
- Badge provides **quick access to AI settings** without hunting
- Dropdown menu enables **future AI feature discovery** (as features are added)
- Balances **invisibility with visibility** - AI is present but not intrusive
**Badge Placement Strategy:**
- Header right = **standard location** for status indicators
- Before user menu = **associates AI with user identity**
- Purple sparkle emoji โจ = **clear visual marker** of AI presence
- Dropdown reveals **AI feature status** (e.g., "Memory Echo: Daily", "Provider: Ollama")
### Implementation Approach
**Phase 1: Core Layout (Week 1-2)**
1. **Sidebar (Cahiers Navigation)**
- Use existing Radix UI `NavigationMenu` or custom sidebar
- 256px width (w-64), collapsible on mobile (hamburger menu)
- Cahier items: Icon + Name + Note count badge
- Active state: Purple left border + purple text
- "Inbox" as default cahier (first item)
2. **Masonry Grid (Note Display)**
- Use existing `MasonryGrid` component from component inventory
- Responsive: 1 col (mobile) โ 2 col (tablet) โ 3-4 col (desktop)
- Gap: 16px (space-4)
- Note cards: White bg, border gray-200, shadow-sm, hover:shadow-md
3. **Header (Top Bar)**
- 64px height (h-16)
- Left: Logo + Cahier name (breadcrumb)
- Center: Search bar (unified keyword + semantic)
- Right: โจ AI Badge (dropdown) + User menu
**Phase 2: AI Feature Components (Week 2-4)**
4. **Memory Echo Toast**
- Radix UI `Toast` primitive with custom styling
- Position: bottom-right, 16px from edges
- Animation: fade-in (0.2s ease-out), respects `prefers-reduced-motion`
- Purple border (2px solid #8B5CF6), white bg with purple-50 tint
- Content: ๐ก icon + "I noticed something..." + connection details
- Actions: Link notes button, ๐๐ feedback, dismiss (X)
- Accessibility: `role="alert"`, `aria-live="polite"`
5. **Title Suggestions Dropdown**
- Radix UI `DropdownMenu` triggered on title focus/blur
- Content: 3 title options with โจ prefix
- Visual: Purple text (text-purple-600), hover:bg-purple-50
- Interaction: Click to accept, ESC to close
- Trigger logic: Show after user types content, then focuses title
6. **Semantic Search Badges**
- Component: Small badge next to search results
- Content: "Semantic Match" in blue (text-blue-600)
- Position: Below note title, above content preview
- Visual: Blue border, dashed underline for matched terms
- Logic: Show when cosine similarity > 0.75
7. **Reformulation Modal**
- Radix UI `Dialog` with comparison view
- Layout: Two-column (original | AI suggestion)
- Visual: Purple border (2px), gray-50 background for comparison
- Actions: Accept (green button), Reject (gray button), Retry (purple button)
- Trigger: "โจ Reformulate" button on paragraph hover
8. **AI Badge Dropdown (Direction B Element)**
- Radix UI `DropdownMenu` in header
- Trigger: "โจ AI: On" button
- Content:
- Feature status (Memory Echo: Daily, Provider: Ollama)
- Quick settings links (Configure AI, Privacy)
- Provider indicator (Local ๐ | Cloud โ๏ธ)
- Visual: Purple text, hover:bg-purple-50
**Phase 3: Responsive Behavior (Week 4)**
9. **Mobile Adaptations**
- Sidebar: Hamburger menu (collapse to off-canvas)
- Masonry: Single column, full-width cards
- Memory Echo: Full-width toast at bottom
- Search: Expand on focus (compact icon โ full bar)
- AI Badge: Compact on mobile (โจ icon only, tap for menu)
10. **Tablet Optimizations**
- Sidebar: 200px width or collapsible
- Masonry: 2 columns
- Memory Echo: Bottom-right toast (same as desktop)
- Touch targets: Minimum 44ร44px (WCAG)
**Phase 4: Polish & Micro-interactions (Week 5)**
11. **Animations**
- Masonry: Fade-in cards (0.2s ease-out)
- Memory Echo: Slide-up fade-in (0.3s ease-out)
- Hover states: 0.15s transitions
- Respect `prefers-reduced-motion` for all animations
12. **Accessibility**
- Focus indicators: 2px purple outline
- Keyboard navigation: Tab through all interactive elements
- Screen reader: ARIA labels for AI components
- Color contrast: 4.5:1 minimum (WCAG AA)
13. **Loading States**
- AI processing: Amber spinner (#F59E0B) with "AI thinking..." text
- Semantic search: Skeleton cards while computing embeddings
- Provider status: Green check (Ollama running) or red X (offline)
**Component Timeline Summary:**
| Component | Radix Primitive | Week | Priority |
|-----------|-----------------|------|----------|
| Sidebar Cahiers | NavigationMenu | 1 | P0 |
| Masonry Grid | Custom (existing) | 1 | P0 |
| Header | Flex layout | 1 | P0 |
| AI Badge Dropdown | DropdownMenu | 1 | P0 |
| Memory Echo Toast | Toast | 2 | P0 (Defining) |
| Title Suggestions | DropdownMenu | 2 | P1 |
| Semantic Search Badge | Custom | 3 | P1 |
| Reformulation Modal | Dialog | 3 | P1 |
| Mobile Responsive | Media queries | 4 | P1 |
**Design Tokens Implementation (Tailwind Config):**
```javascript
// tailwind.config.js extension
module.exports = {
theme: {
extend: {
colors: {
ai: {
primary: '#8B5CF6', // Violet
accent: '#3B82F6', // Blue
success: '#10B981', // Green
warning: '#F59E0B', // Amber
light: '#F5F3FF', // Purple-50
}
},
spacing: {
'18': '4.5rem', // 72px - card gap large
}
}
}
}
```
**Success Criteria for Direction A:**
โ **Masonry grid fills โฅ70% of viewport** (content-first metric)
โ **AI features appear in โค200ms** (responsive feel)
โ **Memory Echo creates "Aha!" moment** (user testing)
โ **Users discover โฅ2 AI features organically** (no tutorial needed)
โ **Cahier switching takes โค100ms** (instant mental model)
โ **Mobile single-column works without horizontal scroll** (responsive)
โ **WCAG AA compliance** (accessibility)
**What This Direction Avoids (from other directions):**
โ No permanent AI panel (Direction B) - maximizes content space
โ No mode switching (Direction C) - reduces cognitive load
โ No colored background zones - maintains clean white aesthetic
โ No complex transitions - faster to implement, less to go wrong
---
## User Journey Flows
### Journey 1: Fast Capture avec Cahiers & Title Suggestions
**Persona:** Alex - Creative Developer qui veut capturer vite
**Parcours:** Capturer une idรฉe dans un Cahier โ Recevoir suggestions de titres โ Accepter/refuser
**Flow Diagram:**
```mermaid
flowchart TD
Start([Alex ouvre Memento]) --> SelectCahier{Sรฉlectionne Cahier}
SelectCahier -->|Inbox par dรฉfaut| ViewGrid[Voir grille masonry Inbox]
SelectCahier -->|Cahier existant| ViewGrid
SelectCahier -->|Nouveau Cahier| CreateCahier[Crรฉer nouveau Cahier]
CreateCahier --> ViewGrid
ViewGrid --> ClickNew[Click '+ New Note']
ClickNew --> NoteEditor[Note Editor: Focus sur contenu]
NoteEditor --> TypeContent[Alex tape frรฉnรฉtiquement 50+ mots en 2min]
TypeContent --> CheckTitle{Titre prรฉsent?}
CheckTitle -->|Oui| SaveNote[Sauvegarder note]
CheckTitle -->|Non| TriggerAI[AI Trigger: 50+ mots sans titre]
TriggerAI --> ShowToast[๐ Toast subtil: ๐ญ '3 idรฉes de titres?']
ShowToast --> UserDecision{Action Alex?}
UserDecision -->|Ignore Continue| AutoDismiss[Auto-dismiss 30s]
UserDecision -->|Click 'Voir'| ShowDropdown[Dropdown avec 3 titres โจ Titre 1 โจ Titre 2 โจ Titre 3]
UserDecision -->|Click 'Ne plus demander'| DismissPerm[Dismiss pour cette note]
ShowDropdown --> SelectTitle{Alex choisit?}
SelectTitle -->|Click Titre 1| ApplyTitle1[Appliquer Titre 1]
SelectTitle -->|Click Titre 2| ApplyTitle2[Appliquer Titre 2]
SelectTitle -->|Click Titre 3| ApplyTitle3[Appliquer Titre 3]
SelectTitle -->|ESC/Click outside| DismissDropdown[Fermer dropdown]
ApplyTitle1 --> SaveNote
ApplyTitle2 --> SaveNote
ApplyTitle3 --> SaveNote
DismissDropdown --> ManualTitle[Alex tape titre manuel]
DismissPerm --> ManualTitle
AutoDismiss --> ManualTitle
ManualTitle --> SaveNote
SaveNote --> ShowInCard[Note apparaรฎt dans masonry avec titre appliquรฉ]
ShowInCard --> EmbedAsync[Background: Gรฉnรฉrer embedding pour semantic search]
EmbedAsync --> End([Fin: Note capturรฉe])
style TriggerAI fill:#8B5CF6,color:#fff
style ShowToast fill:#F5F3FF
style ShowDropdown fill:#8B5CF6,color:#fff
style EmbedAsync fill:#3B82F6,color:#fff
```
**Optimizations "Zรฉro Prise de Tรชte":**
- โ **No interruption:** Toast appears without blocking typing
- โ **Default value:** Inbox = default Cahier for ultra-fast capture
- โ **Respect choice:** "Don't ask again" = immediate, no confirmation
- โ **Background processing:** Embedding generated without blocking UI
**Moments of Delight:**
- ๐ **Positive surprise:** "Wow, the first one captures exactly the essence!"
- โก **Performance:** Instant dropdown (< 200ms)
---
### Journey 2: Semantic Search Discovery
**Persona:** Alex - Cherche une note mais se souvient du sens, pas des mots
**Parcours:** Rechercher avec intention naturelle โ Voir rรฉsultats sรฉmantiques โ Dรฉcouvrir la bonne note
**Flow Diagram:**
```mermaid
flowchart TD
Start([Alex veut retrouver sa note React]) --> ClickSearch[Click barre de recherche header center]
ClickSearch --> SearchExpand[Search bar s'agrandit placeholder: 'Rechercher...']
SearchExpand --> TypeQuery[Alex tape naturellement: 'comment optimiser les performances des hooks']
TypeQuery --> Debounce[Debounce 300ms]
Debounce --> SearchHybrid[Hybrid Search: 1. Keyword Search 2. Semantic Search]
SearchHybrid --> KeywordResults[Keyword Search: Rรฉsultats avec mots exacts]
SearchHybrid --> SemanticResults[Semantic Search: Vector embeddings]
KeywordResults --> CombineResults[Combiner & Ranker]
SemanticResults --> SimilarityThreshold{Cosine Similarity > 0.75?}
SimilarityThreshold -->|Oui| AddSemantic[Ajouter badge 'Semantic Match' Score: 0.82]
SimilarityThreshold -->|Non| KeywordOnly[Rรฉsultats keyword uniquement]
AddSemantic --> CombineResults
KeywordOnly --> CombineResults
CombineResults --> ShowResults[Afficher 10 rรฉsultats masonry style]
ShowResults --> ResultBadges[Badges sur rรฉsultats: ๐ฏ Correspondance exacte ๐ฏ Correspondance sรฉmantique]
ResultBadges --> AlexScans[Alex scanne les rรฉsultats]
AlexScans --> TopResult[1er rรฉsultat: Titre: 'React State Management' Badge: ๐ฏ Correspondance sรฉmantique Score: 0.82]
TopResult --> AlexRealize{Alex rรฉalise}
AlexRealize -->|Wow!| NoteNoKeywords[Note ne contient PAS 'hook' ou 'performance']
AlexRealize -->|Click| OpenNote[Ouvrir la note]
NoteNoKeywords --> ConceptMatch[IA a compris le CONCEPT, pas juste les mots-clรฉs]
ConceptMatch --> AhaMoment[Alex: 'C'est exactement ce que je cherchais!']
OpenNote --> NoteFull[Alex voit note complรจte: Content parle de useMemo pour optimiser les performances]
NoteFull --> Success([Succรจs: Note retrouvรฉe])
AhaMoment --> Success
style SearchHybrid fill:#3B82F6,color:#fff
style SemanticResults fill:#8B5CF6,color:#fff
style AddSemantic fill:#3B82F6,color:#fff
style AhaMoment fill:#10B981,color:#fff
```
**Optimizations "Zรฉro Prise de Tรชte":**
- โ **Unified search:** No visible keyword/semantic toggle - "it just works"
- โ **Explicit badges:** User understands WHY this result appears
- โ **Confidence score:** Cosine similarity > 0.75 = false positive filtering
**Moments of Delight:**
- ๐ฏ **Intention understood:** "It understood what I meant, not what I typed!"
- โก **Instant:** Results < 500ms
---
### Journey 3: Memory Echo "Aha!" Moment
**Persona:** Alex/Max - Dรฉcouverte proactive de connexions invisibles
**Parcours:** Recevoir notification inattendue โ Voir connexion โ Feedback ๐๐
**Flow Diagram:**
```mermaid
flowchart TD
Start([Alex utilise Memento normalement]) --> BackgroundProcess[Background Daily: Analyser embeddings du Cahier actuel]
BackgroundProcess --> FindSimilar{Cosine Similarity > 0.75 entre notes?}
FindSimilar -->|Non| NoInsight[Pas d'insight aujourd'hui]
FindSimilar -->|Oui| TimeFilter{Notes de pรฉriodes diffรฉrentes?}
TimeFilter -->|Non| NoInsight
TimeFilter -->|Oui| CheckFrequency{Frequency setting OK? (max 1/jour)}
CheckFrequency -->|Non| NoInsight
CheckFrequency -->|Oui| CheckLastShown{Dรฉjร montrรฉ cette connexion?}
CheckLastShown -->|Oui| NoInsight
CheckLastShown -->|Non| PrepareEcho[Prรฉparer Memory Echo]
PrepareEcho --> GetNoteA[Rรฉcupรฉrer Note A: 'Node.js performance tips']
PrepareEcho --> GetNoteB[Rรฉcupรฉrer Note B: 'Next.js optimization']
PrepareEcho --> Connection[Connexion identifiรฉe: Server-side rendering optimization]
GetNoteA --> ShowToast
GetNoteB --> ShowToast
Connection --> ShowToast
ShowToast[๐ก Toast Notification: 'J'ai remarquรฉ quelque chose dans tes notes Work...']
ShowToast --> AlexReaction{Rรฉaction d'Alex?}
AlexReaction -->|Ignore/Dismiss| AutoDismiss[Auto-dismiss 30s]
AlexReaction -->|Click 'Voir la connexion'| ShowModal[Modal Memory Echo Card]
ShowModal[Modal: 2 notes cรดte ร cรดte Note A | Note B 'Toutes deux traitent de server-side rendering optimization']
ShowModal --> AlexReads[Alex lit les deux notes]
AlexReads --> AlexRealizes{Alex rรฉalise la connexion}
AlexRealizes -->|Wow!| ClickLink[Click 'Lier les notes']
AlexRealizes -->|Faux| ClickReject[Click ๐ 'Faux']
ClickLink --> ApplyTag[Ajouter tag commun 'SSR optimization']
ApplyTag --> ShowSuccess[โ Notes liรฉes!]
ShowSuccess --> FeedbackPrompt[Prompt feedback: ๐ 'Clever!' | ๐ 'Faux']
ClickReject --> FeedbackModal[Modal: 'Pourquoi pas pertinent?']
FeedbackModal --> UserExplanation[Alex explique: LearnSystem[Systรจme apprend: Rรฉduire poids similaritรฉ]
FeedbackPrompt --> FeedbackChoice{Alex choisit?}
FeedbackChoice -->|๐| LearnGood[Apprendre: Augmenter poids ce type connexion]
FeedbackChoice -->|๐| LearnBad[Apprendre: Rรฉduire poids]
FeedbackChoice -->|Skip| NoLearn
LearnGood --> End([Fin: Insight mรฉmorisรฉ])
LearnBad --> End
LearnSystem --> End
NoLearn --> End
AutoDismiss --> End
NoInsight --> End([Fin: Pas d'insight])
style BackgroundProcess fill:#3B82F6,color:#fff
style ShowToast fill:#8B5CF6,color:#fff
style ShowModal fill:#F5F3FF
style ClickLink fill:#10B981,color:#fff
style LearnGood fill:#10B981,color:#fff
style LearnBad fill:#EF4444,color:#fff
```
**Optimizations "Zรฉro Prise de Tรชte":**
- โ **Non-intrusive:** Max 1 insight/day, no overwhelm
- โ **Cahier scope:** Analysis only in current Cahier (relevant connections)
- โ **Immediate feedback:** ๐๐ trains the system, no confirmation
- โ **Global toggle:** Option for cross-Cahier connections
**"Aha!" Moment:**
- ๐ก **Surprise & Discovery:** "I never made the connection!"
- ๐ฏ **Serendipity:** "I didn't search, it found me!"
---
### Journey 4: AI Error Recovery & Control
**Persona:** Sophie - L'IA se trompe, elle ajuste les settings
**Parcours:** Recevoir mauvaise suggestion โ Feedback nรฉgatif โ Ajuster settings โ Retrouver la confiance
**Flow Diagram:**
```mermaid
flowchart TD
Start([Sophie crรฉe une note]) --> WriteContent[Sophie รฉcrit 70 mots sur stratรฉgie contenu]
WriteContent --> TriggerAI[AI Trigger: Title Suggestions]
TriggerAI --> ShowSuggestions[Affiche 3 titres: 1. 'Stratรฉgie B2B' 2. 'Marketing 2025' 3. 'Idรฉes Articles']
ShowSuggestions --> SophieReaction{Sophie rรฉagit}
SophieReaction -->|Dรฉรงue| ClickDismiss[Click 'Ne plus demander']
SophieReaction -->|Choisit| SelectTitle[Sรฉlectionne titre]
ClickDismiss --> DismissNote[Toast: 'Pas de soucis, je ne te redemanderai pas pour cette note']
DismissNote --> SophieManual[Sophie tape titre manuel]
SophieManual --> SaveNote[Sauvegarder]
SaveNote --> NextDay[Jour suivant:]
NextDay --> MemoryEcho[Memory Echo: Recettes smoothies + SEO]
MemoryEcho --> SophieConfused{Sophie confuse}
SophieConfused -->|Pas de rapport!| ClickThumbsDown[Click ๐ 'Faux']
ClickThumbsDown --> FeedbackModal[Modal: 'Pourquoi pas pertinent?']
FeedbackModal --> SophieExplains[Sophie explique: 'Smoothies = personnel SEO = pro']
SophieExplains --> SystemLearn[Systรจme apprend: Contexte personnel vs pro]
SystemLearn --> DismissToast[Toast: 'Merci! Je ferai mieux next time']
DismissToast --> SophieSettings[Sophie va dans Settings > AI]
SophieSettings --> SeeCurrent[Voit settings actuels: โ Title Suggestions: 50+ mots โ Memory Echo: Max 1/jour]
SeeCurrent --> SophieAdjusts{Sophie ajuste}
SophieAdjusts -->|Title Suggestions| AdjustTitle[Ajuster: 'Me demander seulement si > 100 mots']
SophieAdjusts -->|Memory Echo| AdjustEcho[Ajuster: 'Seulement notes des 30 derniers jours']
SophieAdjusts -->|Language| AdjustLang[Forcer langue = FR pour รฉviter titres EN]
AdjustTitle --> SaveSettings[Sauvegarder settings]
AdjustEcho --> SaveSettings
AdjustLang --> SaveSettings
SaveSettings --> WeekLater[Une semaine plus tard:]
WeekLater --> NewNote[Sophie รฉcrit 200 mots]
NewNote --> BetterSuggestions[Meilleures suggestions: 1. 'Content Marketing: Comment crรฉer...' 2. 'Guide Marketing: De la stratรฉgie...' 3. 'Stratรฉgie: Les 5 piliers B2B']
BetterSuggestions --> SophieHappy[Sophie: 'Number 3 is perfect!']
SophieHappy --> ApplyTitre3[Appliquer Titre 3]
ApplyTitre3 --> TrustRestored[Confiance restaurรฉe!]
TrustRestored --> MemoryEcho2[Memory Echo: Deux notes marketing 30 derniers jours]
MemoryEcho2 --> SophieClickThumbsUp[Sophie clique ๐]
SophieClickThumbsUp --> LearnPositive[Systรจme apprend: Connexions pertinentes]
LearnPositive --> Success([Fin: Sophie personnalisรฉ son expรฉrience IA])
style ClickDismiss fill:#F59E0B
style ClickThumbsDown fill:#EF4444,color:#fff
style FeedbackModal fill:#FEE2E2
style SophieSettings fill:#3B82F6,color:#fff
style SophieHappy fill:#10B981,color:#fff
style TrustRestored fill:#10B981,color:#fff
style Success fill:#10B981,color:#fff
```
**Optimizations "Zรฉro Prise de Tรชte":**
- โ **Granular control:** Each feature has independent settings
- โ **Immediate respect:** "Don't ask again" = no confirmation
- โ **Explanatory feedback:** Modal explains why system is asking
- โ **Learning curve:** System improves over time
**Trust Recovery:**
- ๐ **User control:** Sophie can customize EVERYTHING
- ๐ **Progression:** 55% acceptance โ trust restored
---
### Journey Patterns
Based on the 4 flows above, here are the **reusable patterns**:
#### Navigation Patterns
**Pattern 1: Cahier-First Navigation**
- **Entry:** Always in a Cahier (Inbox default)
- **Switching:** Click Cahier in sidebar โ instant switch (< 100ms)
- **Breadcrumb:** Header shows "Memento > Work > [Current note]"
- **Mental Model:** 1 Cahier = 1 work context
**Pattern 2: Contextual AI Appearance**
- **Principle:** AI appears at the right moment, not before
- **Triggers:** Titles (50+ words), Memory Echo (daily), Reformulation (hover)
- **Dismiss:** One-click dismiss, immediate respect
- **Reappear:** Only if criteria met again
#### Decision Patterns
**Pattern 1: Progressive Disclosure**
- **Show:** Information revealed progressively
- **Dropdown:** 3 options (not more, reduced overwhelm)
- **Modal:** For complex decisions (Memory Echo)
- **Inline:** For simple feedback (๐๐)
**Pattern 2: Default + Override**
- **Default:** Inbox Cahier for fast capture
- **Override:** User can choose different Cahier
- **AI Settings:** Team defaults + user overrides
- **Frequency:** Max limits, user can lower
#### Feedback Patterns
**Pattern 1: Triple Coding Feedback**
- **Visual:** Color (purple/blue for AI)
- **Icon:** ๐ก for Memory Echo, โจ for suggestions
- **Text:** Explicit labels ("Correspondance sรฉmantique")
**Pattern 2: Learning Loop**
- **User Action:** ๐ or ๐
- **System Response:** "Thanks!" toast
- **Explanation:** Modal explains why (if ๐)
- **Adaptation:** Next suggestions improved
---
### Flow Optimization Principles
**1. Minimize Steps to Value**
- **Fast Capture:** Inbox โ Type โ Save (3 steps)
- **Semantic Search:** Type โ Results (no extra clicks)
- **Cahier switching:** 1 click = instant switch
**2. Reduce Cognitive Load**
- **Unified Search:** No keyword/semantic choice
- **Cahier Context:** Memory Echo scoped = relevant connections
- **Smart Defaults:** Inbox = default, no thinking required
**3. Clear Feedback & Progress**
- **Toast Notifications:** "๐ก I noticed something..."
- **Badges:** "๐ฏ Semantic Match" with score
- **Loading States:** Spinner + "AI thinking..." text
**4. Moments of Delight**
- **Title Suggestions:** "Wow, the first one captures exactly the essence!"
- **Semantic Search:** "It understood what I meant, not what I typed!"
- **Memory Echo:** "I never made the connection!"
**5. Graceful Error Recovery**
- **"Don't ask again":** Immediate dismiss, no confirmation
- **๐ Feedback:** Explanatory modal for learning
- **Settings Access:** Quick access via AI Badge dropdown
---
## Component Strategy
### Design System Components
**Available from Radix UI:**
Memento's chosen design system (Radix UI + Tailwind CSS) provides comprehensive primitive components:
- โ **Dialog** - Modal overlays (Reformulation comparison)
- โ **Dropdown Menu** - Menus and dropdowns (Title suggestions, AI Badge)
- โ **Toast** - Temporary notifications (Memory Echo base)
- โ **Switch** - Toggle controls (AI settings ON/OFF)
- โ **Navigation Menu** - Sidebar navigation (Cahiers)
- โ **Scroll Area** - Scrollable containers (Masonry grid)
- โ **Tooltip** - Help text and icon explanations
- โ **Separator** - Visual dividers and borders
**Available from Component Inventory (Existing Memento):**
Based on component inventory analysis, these components are already built:
- โ **NoteCard** - Note cards in masonry grid
- โ **MasonryGrid** - Responsive masonry layout
- โ **Header** - Top bar with logo, search, user menu
- โ **Sidebar** - Side navigation (adapt for Cahiers)
- โ **LabelSelector** - Tag selection component
- โ **NoteEditor** - Rich text note editor
- โ **LoginForm** - Authentication UI
**Gap Analysis:**
AI features require **7 custom components** not available in Radix UI or existing inventory:
1. โ **MemoryEchoCard** - Specialized toast with 2 notes side-by-side
2. โ **SemanticSearchBadge** - "Semantic Match" badge with confidence score
3. โ **TitleSuggestionsDropdown** - Dropdown with 3 AI-generated titles
4. โ **ReformulationModal** - Comparison modal (original | AI suggestion)
5. โ **ProviderIndicator** - AI provider status (Local/Cloud + connection)
6. โ **AIToast** - AI-styled toast with purple border
7. โ **ProcessingIndicator** - "AI thinking..." spinner with text
---
### Custom Components
#### Component 1: MemoryEchoCard
**Purpose:** Proactively display a connection between 2 notes (defining "Aha!" experience)
**Anatomy:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ก I noticed something in your **Work** notes... โ
โโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Note A โ Note B โ
โ "Node.js tips" โ "Next.js optimization" โ
โ Preview: 50 chars โ Preview: 50 chars โ
โโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Connection: Server-side rendering optimization โ
โ [Dismiss] [View] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Appears as toast notification (bottom-right, 16px from edges)
- Shows 2 notes with semantic similarity > 0.75
- Displays connection explanation (AI-generated context)
**States:**
- **Appearing:** Fade-in slide-up (0.3s ease-out)
- **Visible:** Subtle border pulse (purple)
- **Hover:** Shadow increase (shadow-lg), solid border
- **Dismissed:** Fade-out slide-down (0.2s)
**Accessibility:**
- `role="alert"` - Important notification
- `aria-live="polite"` - Non-interruptive
- `aria-label="AI notification: Note connection discovered"`
- Keyboard: ESC to dismiss, Tab to "View Connection" button
**Content Guidelines:**
- Headline: "๐ก I noticed something in your **[Cahier name]** notes..."
- Connection: 1-2 sentence explanation of semantic link
- Note previews: 50 characters max, truncation with "..."
**Interaction Behavior:**
- Auto-dismiss after 30 seconds
- Dismissible with X button (top-right)
- "View Connection" โ Opens link notes action or modal
- ๐๐ feedback buttons after viewing
**Design Tokens:**
- Border: `2px solid var(--ai-connection)` (#8B5CF6)
- Background: `var(--background)` (#FFFFFF) with `var(--ai-light)` tint (#F5F3FF)
- Shadow: `shadow-lg` on hover
- Corner radius: `rounded-xl` (12px)
---
#### Component 2: SemanticSearchBadge
**Purpose:** Indicate that a search result is a semantic match (not keyword match)
**Anatomy:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Note Title: "React State..." โ
โ ๐ฏ Semantic Match (Score: 0.82) โ โ Badge here
โ Content preview... โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Appears below note title in search results
- Only shows when cosine similarity > 0.75
- Indicates semantic understanding vs exact keyword match
**States:**
- **Default:** Blue background (bg-blue-50), blue text (text-blue-600)
- **Hover:** Blue-100 background, underline
- **Focus:** 2px blue outline (focus-visible)
**Accessibility:**
- `aria-label="Semantic match with 82% confidence"`
- Screen reader: "Semantic Match, 82 percent confidence"
**Content Guidelines:**
- Text: "๐ฏ Semantic Match (Score: X.XX)"
- Score format: 2 decimal places (0.82, not 0.823456)
- Tooltip on hover: "This result matches the meaning, not exact words"
**Variants:**
- **Exact Match:** No badge (default keyword search result)
- **Semantic Match:** Blue badge with score
---
#### Component 3: TitleSuggestionsDropdown
**Purpose:** Display 3 AI-generated title suggestions
**Anatomy:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โจ 3 Title Suggestions โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โจ React State Management: useMemo... โ โ Hover state
โ โจ Performance Hook Pattern pour... โ
โ โจ Astuce React: mรฉmoisation avec... โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Triggered when user types 50+ words without title
- Appears below title field in note editor
- Shows 3 AI-generated title options
**States:**
- **Closed:** Hidden
- **Opening:** Fade-in (0.2s ease-out)
- **Open:** List visible, items hoverable
- **ItemSelected:** Green checkmark, background green-50
**Accessibility:**
- `role="listbox"` - Selectable list
- `aria-label="AI-generated title suggestions"`
- Keyboard: โโ to navigate, Enter to select, ESC to close
**Content Guidelines:**
- Icon: โจ (sparkle) for each suggestion
- Max 3 items (no scroll)
- Title length: 60-80 characters optimal
- Truncate long titles with "..."
**Interaction Behavior:**
- Trigger: 50+ words without title, focus on title field
- Position: Below title field (DropdownMenu positioning)
- Selection: Click to apply, replaces empty title
- ESC or click outside: Dismiss (user can type manual title)
**Design Tokens:**
- Item text: `text-purple-600` (AI suggestion color)
- Item hover: `hover:bg-purple-50`
- Selected: `bg-green-50` with โ checkmark
---
#### Component 4: ReformulationModal
**Purpose:** Compare original text with AI reformulation side-by-side
**Anatomy:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โจ Reformulate this Paragraph โ
โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Original โ AI Suggestion โ
โ "This is bad text" โ "This text needs improve..." โ
โ โ โ
โ [Keep Original] โ [Apply Suggestion] โ
โโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ [Retry] [Cancel] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Triggered by "โจ Reformulate" button on paragraph hover
- Shows original text vs AI reformulation
- User chooses to keep or replace
**States:**
- **Opening:** Fade-in scale (0.2s)
- **Comparing:** Two-column view, 50% width each
- **Applied:** Green checkmark, modal closes (0.1s)
- **Cancelled:** Fade-out (0.1s)
**Accessibility:**
- `role="dialog"` - Interactive modal
- `aria-labelledby="reformulation-modal-title"`
- `aria-describedby="reformulation-modal-desc"`
- Focus trap within modal
- ESC to close
**Content Guidelines:**
- Header: "โจ Reformulate this Paragraph"
- Left column: "Original" (gray-500 label)
- Right column: "AI Suggestion" (purple-600 label)
- Buttons: "Keep Original" (gray), "Apply" (green), "Retry" (purple)
**Interaction Behavior:**
- Trigger: Hover paragraph โ "โจ Reformulate" button appears (top-right)
- Apply: Replaces paragraph text, green checkmark (0.5s), modal closes
- Keep: Returns to original text, modal closes
- Retry: Generates new suggestion (show ProcessingIndicator)
**Design Tokens:**
- Modal border: `2px solid var(--ai-primary)` (#8B5CF6)
- Background: `var(--surface-elevated)` (#FFFFFF)
- Button primary (Apply): `bg-green-600 hover:bg-green-700`
---
#### Component 5: ProviderIndicator
**Purpose:** Indicate AI provider status (Local Ollama / Cloud OpenAI / Custom)
**Anatomy:**
```
In AI Badge Dropdown:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AI Status โ
โ ๐ Local (Ollama) โ โ Indicator
โ โ Connected: localhost:11434 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Displayed in AI Badge dropdown menu
- Shows current provider and connection status
- Critical for user trust (Max's privacy journey)
**States:**
- **Local:** ๐ icon + "Local (Ollama)"
- **Cloud:** โ๏ธ icon + "Cloud (OpenAI)"
- **Custom:** โ๏ธ icon + "Custom (OpenAI-compatible)"
- **Connected:** โ green + URL/host
- **Disconnected:** โ red + "Not available"
- **Loading:** ๐ spinner + "Connecting..."
**Accessibility:**
- `aria-label="AI provider status: Local Ollama, Connected"`
- Screen reader: "AI provider: Local Ollama, Connected to localhost port 11434"
**Content Guidelines:**
- Local: "๐ Local (Ollama)"
- Cloud: "โ๏ธ Cloud (OpenAI)"
- Custom: "โ๏ธ Custom (OpenAI-compatible)"
- Status: "โ Connected: [URL]" or "โ Disconnected"
**Variants:**
- **Compact:** Icon only (for mobile)
- **Full:** Icon + label + status (desktop)
---
#### Component 6: AIToast
**Purpose:** Custom toast for AI notifications (Memory Echo, suggestions, feedback)
**Anatomy:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ก I noticed something... [X] โ
โ โ
โ Connection details... โ
โ [View Connection] [Dismiss] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Base component for all AI notifications
- Extends Radix UI Toast with AI-specific styling
- Used by MemoryEchoCard, TitleSuggestions, etc.
**States:**
- **Entering:** Slide-up fade-in (0.3s ease-out)
- **Visible:** Purple border (2px solid #8B5CF6)
- **Hover:** Shadow-lg, border 3px
- **Exiting:** Slide-down fade-out (0.2s)
**Accessibility:**
- `role="alert"` - Important notification
- `aria-live="polite"` - Non-interruptive
- `aria-label="AI notification"`
- Auto-dismiss respects `prefers-reduced-motion`
**Design Tokens:**
- Border: `2px solid var(--ai-connection)` (#8B5CF6)
- Background: `var(--background)` (#FFFFFF) with `var(--ai-light)` tint (#F5F3FF)
- Shadow: `shadow-lg` on hover
- Corner radius: `rounded-xl` (12px)
- Padding: `space-4` (16px) all around
**Interaction Behavior:**
- Position: Bottom-right, 16px from edges (desktop)
- Position: Bottom-center, full-width on mobile
- Auto-dismiss: Configurable (10-60s default 30s)
- Dismissible: X button (top-right) or ESC key
---
#### Component 7: ProcessingIndicator
**Purpose:** Indicate that AI is processing a request
**Anatomy:**
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [Spinner] AI thinking... โ
โ Generating embeddings โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Usage:**
- Shows during AI operations (embedding generation, reformulation)
- Provides feedback during long-running operations (> 500ms)
**States:**
- **Idle:** Hidden
- **Processing:** Amber spinner + "AI thinking..." text
- **Success:** Green checkmark (0.5s display) โ fade
- **Error:** Red X + error message
**Accessibility:**
- `role="status"` - Status indicator
- `aria-live="polite"` - Status updates
- `aria-busy="true"` during processing
**Design Tokens:**
- Spinner color: `var(--ai-processing)` (#F59E0B)
- Text: `text-sm text-secondary` (#6B7280)
- Animation: Spin 1s linear infinite
- Respects `prefers-reduced-motion`
**Content Guidelines:**
- Default text: "AI thinking..."
- Contextual text: "Generating embeddings...", "Reformulating..."
- Error text: "AI unavailable. Try again later."
---
### Component Implementation Strategy
**Foundation Components (from Radix UI):**
Leverage Radix UI primitives with Tailwind styling:
| Radix Primitive | Usage in Memento | Custom Styling |
|----------------|------------------|----------------|
| Dialog | Reformulation modal, Memory Echo details | Purple border, AI-specific padding |
| DropdownMenu | Title suggestions, AI Badge menu | Purple text on hover, โจ icons |
| Toast | Base for AIToast | Extended with purple border, custom positioning |
| Switch | AI settings toggles | Default Radix + labels |
| NavigationMenu | Cahiers sidebar | Active state = purple left border |
**Custom Components (IA-specific):**
Build 7 custom components on top of Radix primitives:
1. **MemoryEchoCard** - Extended AIToast with 2-column note comparison
2. **SemanticSearchBadge** - Custom badge component (blue styling)
3. **TitleSuggestionsDropdown** - Radix DropdownMenu + โจ icons + purple text
4. **ReformulationModal** - Radix Dialog with 2-column layout
5. **ProviderIndicator** - Custom status indicator (icon + text + status)
6. **AIToast** - Extended Radix Toast (purple border, positioning)
7. **ProcessingIndicator** - Custom spinner + status text
**Implementation Approach:**
1. **Create IA-specific component variants**
- Extend Radix components with AI styling
- Use composition over inheritance
- Share design tokens (colors, spacing)
2. **Use design tokens for consistency**
- All AI components use `--ai-*` color tokens
- Spacing from 8px grid (space-2, space-4, etc.)
- Typography from system fonts scale
3. **Follow accessibility patterns**
- Leverage Radix's built-in ARIA attributes
- Add custom ARIA for AI-specific content
- Ensure keyboard navigation (ESC, Tab, Enter)
- Test with screen readers
4. **Create reusable patterns**
- AIToast wrapper around Radix Toast
- BaseModal component (extends Dialog) for all modals
- AIBadge base component (purple border, common props)
---
### Implementation Roadmap
**Phase 1 - Core Components (Week 1-2) - P0**
| Component | Priority | User Journey | Rationale |
|-----------|----------|--------------|-----------|
| ProviderIndicator | P0 | Max (Privacy) | Essential for user trust, shows AI status |
| AIToast | P0 | All journeys | Base component for all AI notifications |
| TitleSuggestionsDropdown | P0 | Alex (Fast Capture) | Most-used AI feature, high user value |
**Deliverables:**
- โ ProviderIndicator with local/cloud states
- โ AIToast base component with purple styling
- โ TitleSuggestionsDropdown with 3 options
- โ Design tokens extension (AI colors)
**Week 1:** ProviderIndicator, AIToast
**Week 2:** TitleSuggestionsDropdown + testing
---
**Phase 2 - AI Features (Week 3-4) - P1**
| Component | Priority | User Journey | Rationale |
|-----------|----------|--------------|-----------|
| SemanticSearchBadge | P1 | Alex (Search) | Feature 2 (Semantic Search) |
| ReformulationModal | P1 | Alex (Enhancement) | Feature 3 (Reformulation) |
| ProcessingIndicator | P1 | All journeys | Feedback during AI operations |
**Deliverables:**
- โ SemanticSearchBadge with confidence scores
- โ ReformulationModal with 2-column comparison
- โ ProcessingIndicator with loading/success/error states
**Week 3:** SemanticSearchBadge, ProcessingIndicator
**Week 4:** ReformulationModal + integration
---
**Phase 3 - Advanced (Week 5) - P2**
| Component | Priority | User Journey | Rationale |
|-----------|----------|--------------|-----------|
| MemoryEchoCard | P2 | Alex/Max (Aha!) | Feature 4 (Memory Echo) - defining experience but complex |
**Deliverables:**
- โ MemoryEchoCard with 2-note comparison
- โ Background processing (cosine similarity)
- โ ๐๐ feedback system
**Week 5:** MemoryEchoCard + testing + refinement
---
**Prioritization Rationale:**
**P0 (Critical Path):**
- **ProviderIndicator:** Trust blocker - Max won't use AI without status visibility
- **AIToast:** Foundation for all AI notifications
- **TitleSuggestions:** Highest user value (80% acceptance rate in PRD)
**P1 (High Value):**
- **SemanticSearchBadge:** Key differentiator vs keyword search
- **ReformulationModal:** Enhancement feature, improves writing quality
- **ProcessingIndicator:** UX requirement - users need feedback during AI ops
**P2 (Strategic):**
- **MemoryEchoCard:** Defining "Aha!" experience but most complex (background processing, embeddings, feedback learning)
---
## UX Consistency Patterns
### Button Hierarchy
**When to Use:**
- **Primary Buttons:** Main actions (Save note, Apply suggestion, Create Cahier)
- **Secondary Buttons:** Alternative actions (Cancel, Keep original)
- **Tertiary Buttons:** Low-emphasis actions (Dismiss, Skip, Later)
- **AI Buttons:** AI-specific actions (โจ Reformulate, View Connection)
**Visual Design:**
| Button Type | Tailwind Classes | Usage | Example |
|-------------|------------------|-------|---------|
| Primary | `bg-purple-600 hover:bg-purple-700 text-white font-medium py-2 px-4 rounded-lg` | Main action, high emphasis | "Save Note", "Apply Suggestion" |
| Secondary | `bg-gray-100 hover:bg-gray-200 text-gray-700 font-medium py-2 px-4 rounded-lg` | Alternative action | "Cancel", "Keep Original" |
| Tertiary | `text-gray-500 hover:text-gray-700 font-medium py-2 px-2` | Low emphasis, text-only | "Dismiss", "Skip" |
| AI Action | `bg-purple-50 hover:bg-purple-100 text-purple-600 font-medium py-2 px-4 rounded-lg border border-purple-200` | AI-specific action | "โจ Reformulate", "View Connection" |
| Success | `bg-green-600 hover:bg-green-700 text-white font-medium py-2 px-4 rounded-lg` | Positive confirmation | "Link Notes", "Accept" |
| Destructive | `bg-red-600 hover:bg-red-700 text-white font-medium py-2 px-4 rounded-lg` | Destructive action | "Delete Note", "Remove" |
**Behavior:**
- **Focus:** 2px purple outline (`focus-visible:ring-2 ring-purple-600`)
- **Active:** Slightly darker shade (`active:scale-95`)
- **Disabled:** `opacity-50 cursor-not-allowed` with `aria-disabled="true"`
- **Loading:** Show spinner, disable button, preserve width
**Accessibility:**
- Minimum touch target: 44ร44px (WCAG 2.5.5)
- Clear visual labels (no icon-only buttons without labels)
- Keyboard: Enter/Space to activate
- Focus indicators always visible
**Mobile Considerations:**
- Full-width buttons on mobile for primary actions
- Minimum 44px height for touch targets
- Adequate spacing between buttons (8px minimum)
---
### Feedback Patterns
**When to Use:**
- **Success Feedback:** Actions completed successfully (Note saved, Suggestion applied)
- **Error Feedback:** Actions failed (AI unavailable, Connection error)
- **Warning Feedback:** Caution needed (Last Cahier, AI limit reached)
- **Info Feedback:** Neutral information (AI processing, Feature discovery)
**Visual Design:**
**Success Feedback:**
```tsx
// Toast notification