brachnha-insight/_bmad-output/planning-artifacts/ux-design-specification.md

---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
inputDocuments: 
  - '/home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md'
  - '/home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md'
---

# UX Design Specification Test01

**Author:** Max
**Date:** 2026-01-20

---

<!-- UX design content will be appended sequentially through collaborative workflow steps -->

## Executive Summary

### Project Vision

Test01 is a mobile-first "venting machine" that transforms a data analytics learner's daily struggles into authentic, high-value personal branding content. It replaces the daunting "blank page" with a supportive chat ritual, using a dual-agent system (Teacher + Ghostwriter) to turn raw frustration into professional "vlog-style" narratives that resonate with recruiters.

### Target Users

*   **Primary: The Exhausted Learner (Alex)** - Bootcamp grad, burnt out, needs to post but lacks energy. Value: "Venting" feels good; getting a post for free feels like magic.
*   **Secondary: The Hiring Manager (Sarah)** - Wants to see problem-solving capability, not just code snippets. Value: Authentic windows into the candidate's mind.

### Key Design Challenges

*   **The "Magic Moment" Visualization**: Clearly showing the transformation from "messy rant" to "polished gold" without it feeling jarring.
*   **Frictionless Entry**: The chat interface must feel as low-pressure as texting a friend (WhatsApp-style), completely removing the "I'm writing a document" pressure.
*   **Trust & Control**: Users need to feel they own the final post, even if AI wrote it (Edit distance metric).

### Design Opportunities

*   **Split-Interaction UI**: A visual "Before/After" split view that reinforces the value payoff immediately.
*   **Pastel/Soft Aesthetic**: Moving away from "Code/Dark Mode" to a more "Wellness/Journaling" vibe to reduce anxiety.
*   **Gamified Consistency**: Subtle progress indicators for "streak" or "posts generated" to encourage the daily ritual.

## Core User Experience

### Defining Experience

The core experience is a **"Guided Venting Ritual."** The user opens the app not to "work," but to release tension. The interface mimics a messaging app (private, safe). The user types a raw, unpolished thought. The system's response is not a solution to the bug, but a *validation* of the learning value, followed instantly by a tangible reward: a polished public artifact (the post).

### Platform Strategy

*   **Primary:** Mobile Web / PWA.
*   **Usage Context:** Commuting after class, taking a coffee break, or lying on the couch.
*   **Requirement:** Must load instantly and retain state (chat history) locally or effectively.

### Effortless Interactions

*   **The "No-Start" Start:** No "New Project" method. The home screen IS the chat input.
*   **Auto-Drafting:** The "Ghostwriter" triggers automatically after sufficient context is gathered (or on button press), without requiring prompt engineering from the user.

### Critical Success Moments

*   **The First Draft:** The first time valid content appears from raw complaint.
*   **The "Post" Action:** Copying the text to clipboard must provide immediate visual feedback (confetti? haptic?) to close the loop validation.

### Experience Principles

*   **"Venting is Input"**: Design for tired people. Low cognitive load.
*   **"Teacher, not Encyclopedia"**: The AI asks questions, it doesn't just lecture.
*   **"Magic Mirror"**: The output should reflect the user's best self back to them.

## Desired Emotional Response

### Primary Emotional Goals
*   **Validation & Relief:** The immediate feeling of dropping a heavy mental load ("Ugh, this bug") and having it acknowledged.
*   **Competence:** The feeling of seeing their "struggle" framed as "growth." The "Magic Mirror" effect.

### Emotional Journey Mapping
*   **Before:** Anxiety, Fatigue, Imposter Syndrome.
*   **During (Venting):** Safety, Release, Conversational Flow.
*   **After (Draft Generation):** Surprise, Delight, "I did something productive today."

### Design Implications
*   **Tone:** Empathetic, warm, encouraging (never critical). The AI is a "Study Buddy," not a "Grader."
*   **Visuals:** Calming, clean, spacious. Avoid "Alert Red" or aggressive prompts.
*   **Feedback:** Celebrate the "Vent" as a win. "Great insight!" not "Input received."

## UX Pattern Analysis & Inspiration

### Inspiring Products Analysis

*   **Medium:**
    *   *Why:* "Self-improvement without the noise." Serious, clean design.
    *   *Lesson:* Use serif fonts for the "Final Draft" to signal quality/intellect. Use whitespace generously. Remove "feed anxiety."
*   **Instagram (Stories):**
    *   *Why:* "Easy to post."
    *   *Lesson:* The transition from "Creation" to "Published" is seamless. The AI processing is our "Filter" - it takes raw input and makes it "Instagrammable" (or "LinkedIn-able").
*   **Telegram:**
    *   *Why:* "My chatting app."
    *   *Lesson:* The input interface should clone standard chat patterns (bottom bar, speech bubbles, ticks). Zero learning curve.

### Transferable UX Patterns

*   **Chat-to-Preview (Telegram -> Medium):** The screen splits or transitions from a "Chat View" (Input) to a "Reader View" (Output).
*   **"The Polish Button" (Instagram):** A single, prominent action that applies the "Magic" (AI transformation), similar to regularizing a photo filter.
*   **Calm Reading (Medium):** The "Ghostwriter" draft shouldn't look like a code editor. It should look like a finished article to inspire confidence.

### Anti-Patterns to Avoid

*   **The "Reddit Thread":** Avoid complex nesting or "arguing" UI. This is a dialogue with a supportive AI, not a forum.
*   **The "Feed of Doom":** Do not maximize time-in-app via scrolling. Maximize "Post Creation."

## Design System Foundation

### 1.1 Design System Choice

**ShadCN UI** (Tailwind CSS + Radix UI)

### Rationale for Selection

*   **Balance of Speed & Control:** ShadCN provides accessible, copy-pasteable components (Dialogs, Sheets, Inputs) that are robust "out of the box" but fully customizable via Tailwind. This allows us to rapidly build the "App" structure (menus, menus, inputs) without fighting an opinionated framework when we need to do custom typography for the "Medium-style" reading view.
*   **"Premium" Aesthetic:** The default ShadCN aesthetic is clean, minimalist, and "calm," aligning perfectly with our "Wellness/Journaling" vibe goals.
*   **Accessibility:** Built on Radix primitives, ensuring the app is accessible by default.

### Implementation Approach

*   **Base:** Next.js + Tailwind CSS.
*   **Components:** Install ShadCN for structural elements (Cards, Buttons, Inputs, Dialogs).
*   **Typography:** Custom font config in `tailwind.config.js` to support the "Medium-style" serif readability.

### Customization Strategy

*   **The "Chat" Bubble:** We will build a custom chat bubble component using Tailwind directly (not ShadCN) to match the "Telegram" look exactly.
*   **The "Vlog" Card:** Custom card design for the final post preview.
*   **Colors:** We will override the default "Zinc" palette with a softer, pastel-infused palette to match the emotional goal of "Relief" rather than "SaaS Product."

## 2. Core User Experience

### 2.1 Defining Experience

The defining experience is the **"Draft Iteration Loop."** It bridges the gap between unstructured venting and structured publishing. The user doesn't "write"; they "chat." The system honors this input by converting it into a polished draft, but critically, it allows for a *Conversational feedback loop* if the draft isn't quite right, mirroring how one would work with a human editor.

### 2.2 User Mental Model

*   **Current Model:** "I have to open a blank document, stare at the cursor, and sweat over every word." (High Anxiety)
*   **New Model:** "I just tell my AI buddy what happened today, and it hands me a finished post. If I don't like it, I just say 'no, not like that' and it fixes it." (Low Anxiety)

### 2.3 Success Criteria

*   **Speed to Draft:** < 3 minutes from opening app to seeing the first draft.
*   **Validation Loop:** The "Thumbs Up/Down" mechanism must feel incredibly fast.
*   **Closure:** The "You're done!" animation provides the dopamine hit that replaces the anxiety of hitting "Publish."

### 2.4 Novel UX Patterns

*   **"Conversation as Editor":** Unlike standard chat bots, this chat has a dedicated "End/Draft" trigger that shifts the mode from "conversation" to "artifact creation."
*   **"Refinement Loop":** The feedback on the artifact (Thumbs Down) *re-opens* the chat context specifically to debug the draft ("What didn't you like?"), creating a tight loop between the two modes.

### 2.5 Experience Mechanics

**1. Initiation (Home Screen):**
*   **View:** Displays the latest generated review (Post) to remind user of value.
*   **Action:** Large "+" or "New" button at the bottom.
*   **Result:** Opens the Chat Interface.

**2. Interaction (The Vent):**
*   **Interface:** Standard chat (Telegram-style).
*   **Flow:** User types -> AI replies (validates/asks).
*   **Trigger:** User taps "**End of Conversation**" (or "Draft It").

**3. The Magic (Draft Generation):**
*   **Transition:** New screen slides up/appears.
*   **Content:** The polished "Ghostwriter" post is displayed (Medium-style typography).
*   **Feedback:** Two clear buttons: "👍 Like" or "👎 Not Like".

**4. Refinement Loop (If Disliked):**
*   **Action:** User taps "Thumbs Down".
*   **Response:** System returns to Chat Interface.
*   **Prompt:** AI asks "What didn't you like?" or "What should we change?"
*   **Loop:** User explains -> AI confirms -> User taps "End/Draft" again -> New Draft appears.

**5. Completion (If Liked):**
*   **Action:** User taps "Thumbs Up".
*   **Reward:** "You're done, great job!" Animation (Confetti/Success state).
*   **Access:** Post is saved to history.
*   **Export:** "Copy to Clipboard" button available now (and later in history view).

## Visual Design Foundation

### Color System

**Theme:** "Morning Mist" (Cool & Professional)
*   **Primary Action:** Slate Blue (`#64748B`) - Calming, trustworthy.
*   **Background:** Off-White / Cool Grey (`#F8FAFC`) - Clean slate.
*   **Surface:** White (`#FFFFFF`) - Chat bubbles, Cards.
*   **Text:** Deep Slate (`#334155`) - High contrast but softer than black.
*   **Accents:** Soft Blue (`#E2E8F0`) - Borders, Dividers.

### Typography System

*   **Interface Font (UI):** `Inter` or `Geist Sans`
    *   Used for: Navigation, Chat Bubbles, Buttons, Settings.
    *   Why: Highly legible, standard for modern web apps (ShadCN default).
*   **Content Font (The Post):** `Merriweather` or `Playfair Display`
    *   Used for: The "Ghostwriter" draft view.
    *   Why: Serif fonts signal "published work" and authority, distinguishing the "Draft" from the "Chat."

### Spacing & Layout Foundation

*   **Mobile-First Grid:** Single column, comfortable margins (16px/24px).
*   **Touch Targets:** Minimum 44px for all interactive elements.
*   **Whitespace:** Generous padding between chat bubbles to prevent "wall of text" anxiety.

### Accessibility Considerations

*   **Contrast:** All text variations will pass WCAG AA standards (4.5:1 ratio).
*   **Dark Mode:** The "Morning Mist" theme will have a properly mapped "Evening Mist" dark mode (Deep Slate background + Light text).

## Design Direction Decision

### Design Directions Explored

We explored three distinct directions:
1.  **The "Buddy" Chat:** Maximizing familiarity and reducing friction (Telegram-style).
2.  **The "Journal" Focus:** High-focus, minimalist, solitary writing experience.
3.  **The "Result" View:** A premium, "published" look for the generated artifact.

### Chosen Direction

**The Hybrid Model**
*   **Input (The Vent):** Uses the **"Buddy" Chat** interface.
    *   *Why:* It feels seamless, safe, and requires zero learning curve. It lowers the barrier to "just complain."
*   **Output (The Reward):** Uses the **"Result" View** interface.
    *   *Why:* It creates a distinct "Magic Moment." The visual shift from "Chat Bubble" to "Polished Card" reinforces the value the AI added.

### Design Rationale

This "Split-Personality" UI mirrors the user's mental shift:
*   **Mode 1 (Venting):** Low cognitive load, messy, fast. (Chat UI)
*   **Mode 2 (Reviewing):** High pride, clean, authoritative. (Card/Article UI)

### Implementation Approach

*   **Chat Component:** Custom Tailwind component (bubbles, timestamps, avatars) to look native.
*   **Draft Component:** Standard ShadCN Card with custom typography (Serif headings) and distinct background elevation.
*   **Transition:** A smooth slide-up pane (BottomSheet on mobile) to present the Draft, keeping the Chat context available underneath.

## User Journey Flows

### 1. Onboarding (The Gate)

**Goal:** Convert a visitor into a registered user (and potentially a subscriber) before they access the core value, then transition them immediately into their first "Win."

```mermaid
graph TD
    A[App Launch] --> B[Splash / Value Prop]
    B --> C{Login Required}
    C --> D[Sign Up / Login Screen]
    D --> E[Auth Success]
    E --> F[Subscription Wall]
    F -->|Subscribe| G[Premium Onboarding]
    F -->|Skip/Trial| H[Standard Onboarding]
    G & H --> I[Home Screen / First Chat]
    I --> J[AI: 'What are you working on today?']
```

**Optimization Principles:**
*   **Value First:** The Splash screen must succinctly promise "Turn stress into personal branding" to justify the login wall.
*   **Frictionless Auth:** Use Google/GitHub/LinkedIn social login to make the "Wall" feel lower.

### 2. The Daily Vent (Core Loop)

**Goal:** The primary use case. Turning a raw thought into a polished artifact.

```mermaid
graph TD
    A[Home / Chat] --> B[User Types Vent]
    B --> C[AI Responds / Validates]
    C --> D{Happy?}
    D -->|Keep Venting| B
    D -->|Ready to Post| E[User Taps 'Draft It']
    E --> F[Ghostwriter Generates Draft]
    F --> G[Card View Slide-Up]
    G --> H{Review}
    H -->|Thumbs Down| I[Back to Chat: 'What to fix?']
    I --> B
    H -->|Thumbs Up| J[Success Animation]
    J --> K[Copy to Clipboard]
    K --> L[Home / History Updated]
```

**Optimization Principles:**
*   **The "Draft It" Trigger:** Always visible or suggested by AI after 3-4 turns to prevent endless chatting.
*   **Quick Loop:** The transition from "Thumbs Down" back to "Chat" must be instant, preserving the context.

### 3. History & Reflection

**Goal:** Retrieving value from the past.

```mermaid
graph TD
    A[Home Screen] --> B[Scroll History Feed]
    B --> C[Select Past Post]
    C --> D[View Polished Card]
    D --> E{Action}
    E -->|Copy| F[Copy to Clipboard]
    E -->|Continue| G[Re-open Chat Context]
    G --> H[Resume Venting/Editing]
```

## Journey Patterns

*   **"The Slide-Up" (Output Mode):** The "Result" view (the polished card) always appears as a modal/sheet over the chat. Dismissing it returns you exactly where you were (safe navigation).
*   **"The Loop" (Correction):** Correction is not done by editing text manually; it is done by *talking* to the agent. "Make it shorter" -> Agent regenerates.
*   **"Success State":** Every successful "Thumbs Up" ends with a high-dopamine visual reward and an auto-save.

## Component Strategy

### Design System Components
*   **Framework:** ShadCN UI (Tailwind + Radix).
*   **Icons:** Lucide React (Clean, consistent, standard).
*   **Base Components:** `Button`, `Input`, `Sheet` (for Draft View), `Dialog` (for Auth), `Card`.

### Custom Components

#### 1. `ChatBubble`
*   **Purpose:** Core interaction container.
*   **Variants:**
    *   `User`: Brand Color (`bg-slate-700`), Text White, Right-aligned.
    *   `AI`: Neutral (`bg-slate-100`), Text Slate-800, Left-aligned.
    *   `System`: Centered, small text, for timestamps or "Draft Saved".
*   **Content:** Supports Markdown rendering (important for code blocks).

#### 2. `DraftCard` component
*   **Purpose:** The "Magic Moment" display.
*   **Anatomy:**
    *   Header: "Draft Ready" badge + Title.
    *   Body: Merriweather font, comfortable reading line-height.
    *   Footer: Sticky action bar (Thumbs Up/Down).
*   **States:** `Skeleton` (Loading), `Ready` (Interactive).

#### 3. `AuthWall`
*   **Purpose:** High-conversion entry gate.
*   **Elements:** Value Prop Headline ("Turn Stress into Success") + Large Social Auth Buttons.

### Implementation Roadmap
1.  **Phase 1 (MVP):** `AuthWall`, `ChatBubble` mechanics, and `DraftCard` (Sheet implementation).
2.  **Phase 2 (Retention):** `HistoryList` with virtual scrolling.
3.  **Phase 3 (Delight):** Confetti animations on "Post", Swipe gestures for history.

## UX Consistency Patterns

### Button Hierarchy

*   **Primary (Brand Color):** "Post It", "Draft It", "Confirm". The high-value actions.
*   **Secondary (Outline/Ghost):** "Cancel", "Back", "Skip".
*   **Destructive (Red/Warning):** "Delete Draft".

### Feedback Patterns

*   **Success:** Toast notification *and* Haptic feedback on mobile.
*   **Loading:**
    *   **Chat:** "Teacher is typing..." indicator (dots).
    *   **Draft Generation:** Skeleton card loader (shimmering lines) to show "work is happening."

### Navigation Patterns

*   **Core Nav:** Bottom Tab Bar (Home, History, Profile).
*   **Modals vs Sheets:**
    *   **Sheet (Bottom slide-up):** For context-preserving tasks (Viewing Draft, Settings).
    *   **Dialog (Center):** For critical interruptions (Auth, Deletions).

## Responsive Design & Accessibility

### Responsive Strategy

**Mobile-First Approach**
*   **Core Experience:** Optimized for narrow screens (375px+).
*   **Desktop Adaptation:** "Centered App" pattern. The app does not stretch to fill 1920px. It stays in a constrained 600px wide "Mobile Container" in the center of the screen, with a generous calming background (Morning Mist).
*   **Reason:** Chat interfaces degrade when stretched too wide (eye-scanning fatigue).

### Breakpoint Strategy

*   **Core Breakpoint:** `md` (768px).
*   **Behavior:**
    *   **Below 768px:** Full width, native mobile feel. Bottom tabs.
    *   **Above 768px:** Centered card interface. Extra whitespace. Sidebar navigation instead of bottom tabs? (Possibly keep it simple for MVP and keep bottom tabs inside the container).

### Accessibility Strategy

**WCAG Level AA Compliance**
*   **Color Contrast:** "Morning Mist" palette enforces 4.5:1 text contrast.
*   **Zoom:** UI supports 200% text zoom without breaking (Chat bubbles expand vertically).
*   **Focus Management:** Keyboard focus stays trapped in Modals/Sheets until dismissed.
*   **Screen Readers:** All icon-only buttons (like "Up Arrow") must have `aria-label="Send Message"`.

### Testing Strategy

*   **Automated:** Axe/Lighthouse audits on every deployment.
*   **Manual:** "Keyboard Only" run-through. Can I perform the entire "Vent -> Draft -> Post" loop without a mouse?