Learn English Zero.

User Flow & Screen Design - Learn English Zero

Design Date: 2026-01-09 Version: 1.1 Status: Brainstorming Complete - Ready for Review Designer: AI-assisted brainstorming session Context: Project Brief section "Tính năng chính"

Constants Reference: Xem definitions.md cho tất cả constants và enums.

Design Philosophy

Target Audience Psychology

  • Fear of mistakes > Fear of not knowing → AI never judges, always encourages
  • Sensitive to comparison → No leaderboards, personal achievements only
  • Need clear structure → 120-day roadmap, sequential lessons
  • Need small wins → Each lesson = one small success

Key Principles

  1. Transparency: Show clear progress and expectations
  2. Non-judgmental: AI coach is supportive, never critical
  3. Structured flexibility: Clear path with gentle re-entry options
  4. No abandonment: Clear next steps even after completion

1. Onboarding Flow

Path: Landing → Diagnosis Test → Results → Google Login → Additional Questions → Prescription → Start Learning

1.1 Landing Page

Purpose: Attract and convert target users (18-35 year-old Vietnamese who failed learning English before)

Content:

  • Hero Section

    • Headline: "Lần đầu học tiếng Anh không đáng sợ"
    • Subheadline: "Lộ trình 120 ngày miễn phí với AI Coach 24/7"
    • CTA: "Làm bài test dưới 10 phút để bắt đầu" (prominent button)

  • Value Propositions (visible above fold)

    • ✓ Miễn phí 100%
    • ✓ Lộ trình 120 ngày rõ ràng
    • ✓ AI Coach hỗ trợ 24/7
    • ✓ Không cần kiến thức nền

  • Social Proof (if available)

    • Testimonials from early users
    • Number of students helped: "Đã giúp [X] người Việt học tiếng Anh"

  • How It Works (3 simple steps)

    1. Test chẩn đoán 5 phút
    2. Nhận đơn thuốc học tập cá nhân hóa
    3. Học 120 ngày với AI

1.2 Diagnosis Test

Duration: 5-10 minutes Purpose: Assess 4 "illnesses" (Mù/Điếc/Câm/Yếu phản xạ)

UI Components:

  • Progress Indicator: "Câu 3/20" or progress bar at top

  • Section Headers: Clearly mark each of 4 sections

    • Phần 1: Đọc (Reading comprehension)
    • Phần 2: Nghe (Listening)
    • Phần 3: Nói (Speaking - record audio)
    • Phần 4: Phản xạ (Reaction time)

  • Question Types:

    • Reading: Multiple choice comprehension
    • Listening: Audio playback + questions
    • Speaking: Record pronunciation of words/sentences
    • Reaction: Timed translation/response exercises

  • AI Avatar: Friendly character explaining each section

    • "Bây giờ chúng ta kiểm tra khả năng nghe nhé!"

  • Design: Clean, distraction-free, mobile-friendly

1.3 Test Results

Design Decision: Show detailed percentages with visualization

Layout:

┌─────────────────────────────────────┐
│  Kết Quả Chẩn Đoán Của Bạn         │
├─────────────────────────────────────┤
│                                     │
│   [Radar Chart or Bar Chart]       │
│                                     │
│   Mù (Thiếu từ vựng):       70%    │
│   ████████████████░░░░              │
│                                     │
│   Điếc (Nghe kém):          50%     │
│   ████████████░░░░░░░░░░            │
│                                     │
│   Câm (Phát âm yếu):        30%     │
│   ████████░░░░░░░░░░░░░░            │
│                                     │
│   Yếu phản xạ:              20%     │
│   ██████░░░░░░░░░░░░░░░░            │
│                                     │
├─────────────────────────────────────┤
│  💡 Điểm yếu chính: Mù (thiếu từ)  │
│  Đơn thuốc đề xuất: Đơn Mù         │
├─────────────────────────────────────┤
│  [Đăng nhập Google để lưu kết quả] │
│         và nhận đơn thuốc           │
└─────────────────────────────────────┘

Content:

  • Visualization: Radar chart or horizontal bars
  • Percentages: Clear numbers for each "illness"
  • Brief Explanations: 1-2 sentences per illness
    • "Mù: Bạn đọc được chữ nhưng không hiểu nghĩa do thiếu từ vựng"
  • Recommendation: Which prescription is suggested
  • CTA: Google login button

1.4 Google Login Modal

Timing: Appears immediately after user views results

Design Decision: Require login to save results and continue

Modal Content:

  • Header: "Lưu kết quả và bắt đầu học"
  • Message: "Đăng nhập Google để lưu kết quả chẩn đoán và nhận đơn thuốc học tập cá nhân hóa của bạn"
  • Privacy Assurance:
    • "✓ Hoàn toàn miễn phí"
    • "✓ Không spam, không yêu cầu thẻ tín dụng"
    • "✓ Chỉ dùng để lưu tiến độ học tập"
  • Button: Google OAuth button (official styling)
  • Close Option: Small X to close (but limits access)

1.5 Additional Questions

Design Decision: 3-5 short multiple choice questions

Purpose: Personalize learning experience

UI:

  • Progress Dots: ● ○ ○ ○ ○ (one question per screen)
  • Question Format: Large, clear text with 3-4 options
  • Navigation: "Tiếp tục" button (no back button to keep flow simple)

Questions:

  1. Nghề nghiệp của bạn?

    • Office worker / Nhân viên văn phòng
    • Student / Sinh viên
    • Freelancer
    • Other / Khác

  2. Mục tiêu chính khi học tiếng Anh?

    • Travel / Du lịch
    • Work / Công việc
    • Personal interest / Sở thích cá nhân
    • Prepare for advanced courses / Chuẩn bị học tiếp

  3. Bạn có thể dành bao nhiêu thời gian mỗi ngày?

    • 15 phút
    • 30 phút (recommended)
    • 45 phút
    • 60 phút

  4. Môi trường làm việc/học tập có dùng tiếng Anh không?

    • Yes, frequently / Có, thường xuyên
    • Sometimes / Thỉnh thoảng
    • Rarely / Hiếm khi
    • No / Không

  5. Bạn đã từng học tiếng Anh ở đâu?

    • School only / Chỉ ở trường
    • Language center / Trung tâm
    • Self-study / Tự học
    • Never seriously / Chưa học nghiêm túc

Database Field Mapping:

Câu hỏi Database Field Values
Nghề nghiệp profession Free text
Mục tiêu learning_goals Array: ["travel", "work", "personal", "advanced"]
Thời gian available_study_time_minutes 15, 30, 45, 60
Môi trường tiếng Anh uses_english_at_work + work_environment Boolean + Free text
Đã từng học previous_learning_experience "school", "center", "self", "never"

Cross-reference: Xem database-schema.md table user_profiles và definitions.md Section 7 để biết chi tiết schema.

1.6 Prescription Page ("Đơn Thuốc")

Purpose: Explain personalized learning path

Layout:

┌──────────────────────────────────────┐
│  Đơn Thuốc Của Bạn                   │
├──────────────────────────────────────┤
│  Dựa trên chẩn đoán, bạn nên bắt đầu │
│  với:                                │
│                                      │
│  📋 ĐƠN MÙ - Học Từ Vựng            │
│                                      │
│  Mục tiêu:                           │
│  • Học 3,000 từ Oxford phổ biến      │
│  • Học qua hình ảnh + âm thanh       │
│  • Thời gian: 90-120 ngày            │
│                                      │
│  Lộ trình 120 ngày:                  │
│  [Visual timeline or milestones]     │
│  Day 1-30: 1,000 từ cơ bản          │
│  Day 31-60: 1,000 từ nâng cao       │
│  Day 61-90: 1,000 từ chuyên đề     │
│  Day 91-120: Ôn tập + thực hành     │
│                                      │
│  [Bắt đầu Ngày 1]                   │
└──────────────────────────────────────┘

Content:

  • Prescription Type: Which "đơn thuốc" was assigned
  • Explanation: What this focuses on and why
  • Goal: Clear target (e.g., 3,000 words)
  • Timeline: Visual representation of 120 days
  • CTA: "Bắt đầu Ngày 1" button

2. Daily Learning Flow

Path: Login → Dashboard → Today's Lesson → Activities → Complete → Dashboard

2.1 Dashboard (Home)

Purpose: Central hub for daily learning

Layout:

┌────────────────────────────────────────┐
│  Learn English Zero        [Profile ▾] │
├────────────────────────────────────────┤
│  Xin chào [Name]! 👋                   │
│  [AI Coach avatar]                     │
│  "Sẵn sàng học bài mới hôm nay chưa?"  │
├────────────────────────────────────────┤
│                                        │
│  📚 HÔM NAY (Prominent card)           │
│  ┌──────────────────────────────────┐ │
│  │ Day 5 of 120                     │ │
│  │ 20 Từ Vựng: Food & Drinks        │ │
│  │ ⏱ ~30 phút                       │ │
│  │ [Bắt đầu học →]                  │ │
│  └──────────────────────────────────┘ │
│                                        │
│  📊 TIẾN ĐỘ                           │
│  🔥 Streak: 4 ngày                    │
│  ✓ Hoàn thành: 4/120 bài (3%)        │
│  🎯 Cột mốc tiếp theo: 10 ngày       │
│                                        │
│  🏆 THÀNH TÍCH GẦN ĐÂY                │
│  • Hoàn thành Day 4                   │
│  • Pronunciation score: 85/100        │
│                                        │
│  [Xem chi tiết tiến độ →]             │
│                                        │
├────────────────────────────────────────┤
│              [AI Coach 💬]      (Float)│
└────────────────────────────────────────┘

Components:

  1. Welcome Message: Personalized greeting with AI avatar
  2. Today's Lesson Card:
    • Most prominent element
    • Shows: Day number, topic, estimated time
    • Clear CTA button
  3. Quick Stats:
    • Streak counter (with fire emoji)
    • Completion percentage
    • Next milestone
  4. Recent Achievements: 2-3 latest accomplishments
  5. Navigation: Access to Progress page
  6. Floating AI Coach Button: Bottom-right, always visible

Navigation Bar:

  • Home (current)
  • Progress
  • Settings
  • Profile dropdown

2.2 Lesson Page

Design Decision: Strict sequential unlock (must complete Day N to unlock N+1)

Layout:

┌────────────────────────────────────────┐
│  ← Dashboard              Day 5 of 120 │
├────────────────────────────────────────┤
│  20 Từ Vựng: Food & Drinks             │
│  ●●●○○ Progress: 3/5 activities        │
├────────────────────────────────────────┤
│                                        │
│  [Current Activity Content]            │
│                                        │
│  Activity sequence:                    │
│  1. ✓ Giới thiệu                      │
│  2. ✓ Flashcards (20 từ)              │
│  3. → Phát âm (5 từ)          (active)│
│  4. ○ Mini-test                       │
│  5. ○ Tổng kết                        │
│                                        │
│  [Tiếp tục →]                          │
│                                        │
├────────────────────────────────────────┤
│              [AI Coach 💬]      (Float)│
└────────────────────────────────────────┘

Components:

  • Header: Back button, day number, lesson title
  • Progress Indicator: Dots or bar showing activity completion
  • Activity Content: Changes based on current activity
  • Navigation: "Tiếp tục" or "Hoàn thành" button
  • Activity Sidebar: Shows all activities with status (completed/active/locked)

Lock Mechanism:

  • Day 6 shows as locked until Day 5 is complete
  • Locked lessons display:
    • Grayed out card
    • Padlock icon 🔒
    • Tooltip: "Hoàn thành Day 5 để mở khóa"
  • Can review any completed lesson anytime

2.3 Activity Types

A. Flashcards (Vocabulary)

Layout:

┌────────────────────────────────────────┐
│  Flashcards: 20 từ vựng về Food        │
│  Từ 8/20                               │
├────────────────────────────────────────┤
│                                        │
│         [Large Image of Apple]         │
│                                        │
│              APPLE                     │
│              /ˈæp.əl/                  │
│              [🔊 Nghe]                 │
│                                        │
│  ─────────── Tap to flip ───────────  │
│                                        │
│  [← Trước]              [Sau →]       │
│                                        │
│  Đánh dấu:                             │
│  😊 Đã biết    🤔 Còn nhớ mơ hồ       │
│                                        │
└────────────────────────────────────────┘

(Flipped side)
┌────────────────────────────────────────┐
│         [Same Image of Apple]          │
│                                        │
│           APPLE - Táo                  │
│                                        │
│  Ví dụ:                                │
│  "I eat an apple every day."           │
│  "Tôi ăn một quả táo mỗi ngày."        │
│  [🔊 Nghe câu]                         │
│                                        │
│  [← Trước]              [Sau →]       │
│                                        │
└────────────────────────────────────────┘

Features:

  • Image + Word + Audio: Multi-sensory learning
  • Phonetic: Show pronunciation guide
  • Flip: Tap/click to see Vietnamese + example
  • Navigation: Swipe or arrow buttons
  • Self-assessment: Mark as "know" or "still learning"
    • Tracks which words need more review
  • Progress: "Từ 8/20" counter

Technical Notes:

  • Images from Oxford or free stock photos
  • Audio from Text-to-Speech API or recorded
  • Store self-assessment for spaced repetition

B. Pronunciation Practice

Layout:

┌────────────────────────────────────────┐
│  Luyện Phát Âm                         │
│  Từ 2/5                                │
├────────────────────────────────────────┤
│                                        │
│  Hãy đọc từ này:                       │
│                                        │
│         RESTAURANT                     │
│         /ˈres.tə.rɑːnt/                │
│                                        │
│  [🔊 Nghe mẫu]                         │
│                                        │
│  [🎤 Bấm để ghi âm]                    │
│                                        │
│  ────────────────────────────────      │
│                                        │
│  (After recording)                     │
│  Điểm của bạn: 78/100                  │
│  ████████████░░░░░░                    │
│                                        │
│  💡 Gợi ý cải thiện:                   │
│  "Âm /t/ cuối hơi nhẹ. Thử nhấn mạnh   │
│   hơn nhé!"                            │
│                                        │
│  [🔄 Thử lại]    [Tiếp tục →]         │
│                                        │
└────────────────────────────────────────┘

Features:

  • Target Word/Sentence: Clear display with phonetic
  • Sample Audio: Play correct pronunciation
  • Record: Capture user's pronunciation
  • AI Scoring: 0-100 score with visual indicator
  • Specific Feedback: Targeted improvement suggestions
    • Uses Azure Speech API or similar
    • Identifies specific phoneme errors
  • Retry: Unlimited attempts
  • Threshold: Need 60+ to pass (but can retry)

Technical Implementation:

  • Azure Speech API for pronunciation assessment
  • Record audio in browser
  • Send to API for scoring
  • Display results with actionable feedback

C. Mini-Test

Layout:

┌────────────────────────────────────────┐
│  Mini-Test: Food Vocabulary            │
│  Câu 3/10                              │
├────────────────────────────────────────┤
│                                        │
│  Điền từ đúng:                         │
│                                        │
│  I drink _____ every morning.          │
│                                        │
│  A) bread                              │
│  B) coffee                             │
│  C) chicken                            │
│  D) apple                              │
│                                        │
│  [Chọn đáp án]                         │
│                                        │
│  ────────────────────────────────      │
│                                        │
│  (After answer)                        │
│  ✓ Chính xác! Tuyệt vời!              │
│                                        │
│  (Or if wrong)                         │
│  ✗ Chưa đúng. Đáp án là B) coffee     │
│  💡 Coffee = Cà phê                   │
│                                        │
│  [Câu tiếp theo →]                     │
│                                        │
└────────────────────────────────────────┘

Features:

  • Question Types:
    • Multiple choice
    • Fill in the blank
    • Match words to images
    • Listen and choose
  • Immediate Feedback: After each answer
    • ✓ Correct: Encouraging message
    • ✗ Wrong: Correct answer + brief explanation
  • No Penalty: Can't fail, just for reinforcement
  • Score at End: "8/10 - Tuyệt vời!"
  • Review Wrong Answers: Option to see what they missed

Passing Criteria:

  • No strict requirement (70%+ recommended)
  • Can proceed regardless (trust the process)
  • Tracked for AI coach to offer help if struggling

D. Lesson Summary

Layout:

┌────────────────────────────────────────┐
│  🎉 Hoàn thành Day 5!                  │
├────────────────────────────────────────┤
│                                        │
│  Hôm nay bạn đã:                       │
│  ✓ Học 20 từ vựng mới về Food         │
│  ✓ Luyện phát âm 5 từ                 │
│  ✓ Đạt 8/10 điểm mini-test            │
│                                        │
│  Từ mới:                               │
│  apple, banana, coffee, restaurant...  │
│                                        │
│  Tiến độ:                              │
│  Tổng từ vựng: 100/3000 từ            │
│  Streak: 🔥 5 ngày                    │
│                                        │
│  ────────────────────────────────      │
│                                        │
│  💬 Lời nhắn từ AI Coach:              │
│  "Phát âm của bạn tiến bộ rõ rệt đấy!  │
│   Ngày mai chúng ta sẽ học về Travel.  │
│   Hẹn gặp lại! 😊"                    │
│                                        │
│  [Về Dashboard]                        │
│                                        │
└────────────────────────────────────────┘

Components:

  • Celebration: Visual celebration (confetti animation optional)
  • Summary: What was accomplished
  • Key Vocabulary: Learned words listed
  • Progress Update: Streak, total vocabulary count
  • AI Coach Message: Personalized encouragement
  • CTA: Return to dashboard (Day 6 now unlocked if sequential)

3. AI Coach Interaction

Design Decision: Floating button + slide-in chat panel

3.1 Floating Button

Position: Bottom-right corner of every page

Design:

  • Icon: Friendly AI avatar (not generic chatbot icon)
  • Size: 60x60px (mobile: 50x50px)
  • Color: Accent color (e.g., vibrant blue/purple)
  • Badge: Red notification dot if unread messages
  • Shadow: Subtle drop shadow for visibility
  • Z-index: Always on top

States:

  • Default: Gentle pulse animation to show it's active
  • Hover: Slight scale up
  • Unread: Notification badge
  • Minimized: Shows avatar only
  • Expanded: Chat panel open

3.2 Slide-in Chat Panel

Animation: Slides from right when button clicked

Dimensions:

  • Desktop: 400px wide, 600px tall
  • Mobile: Full screen (overlay)

Layout:

┌─────────────────────────────────┐
│  AI Coach        [─] [×]       │
├─────────────────────────────────┤
│                                 │
│  [Chat History - Scrollable]   │
│                                 │
│  AI: Chào bạn! Tôi có thể      │
│      giúp gì không? 😊         │
│                                 │
│  User: "Restaurant" phát âm    │
│        như thế nào?             │
│                                 │
│  AI: "Restaurant" phát âm là   │
│      /ˈres.tə.rɑːnt/           │
│      [🔊 Nghe]                 │
│      Âm khó nhất là...         │
│                                 │
│  ···                            │
│                                 │
├─────────────────────────────────┤
│  Quick Actions:                 │
│  [Giải thích từ]               │
│  [Tình huống thực tế]          │
│  [Động viên tôi]               │
├─────────────────────────────────┤
│  [Type message...]    [Send 🚀] │
└─────────────────────────────────┘

Components:

  1. Header:

    • Title: "AI Coach"
    • Minimize button: Collapse to floating button
    • Close button: Fully close panel

  2. Chat History:

    • Scrollable area
    • AI messages: Left-aligned, light background
    • User messages: Right-aligned, accent color
    • Timestamps: Subtle, relative ("2 phút trước")
    • Typing indicator: "AI đang trả lời..."

  3. Quick Actions (shortcuts):

    • "Giải thích từ này" → Opens prompt to ask about vocabulary
    • "Tình huống thực tế" → Starts conversation scenario
    • "Động viên tôi" → AI gives encouragement
    • "Tôi muốn bỏ cuộc" → Special response with support

  4. Input Area:

    • Text input field
    • Send button
    • Optional: Voice input button 🎤
    • Character limit: 500 characters (show counter when close)

3.3 AI Coach Capabilities

Personality:

  • Friendly, supportive, patient
  • Uses Vietnamese for explanations (with English examples)
  • Never judges or shows frustration
  • Celebratory when user succeeds

Core Functions:

  1. Vocabulary & Grammar Help

    • User: "What does 'restaurant' mean?"
    • AI: "Restaurant nghĩa là nhà hàng. Ví dụ: 'Let's go to a restaurant' = 'Đi nhà hàng nào!'"

  2. Pronunciation Guidance

    • User: "How to pronounce 'three'?"
    • AI: [Provides phonetic, audio, and tip about /θ/ sound]

  3. Motivation & Encouragement

    • User: "Tôi muốn bỏ cuộc"
    • AI: "Tôi hiểu bạn đang cảm thấy mệt mỏi. Nhưng bạn đã học được 100 từ rồi đấy! Thử nghỉ ngơi 1 ngày rồi quay lại nhé. Bạn làm được mà! 💪"

  4. Practice Conversations

    • User: "Tình huống đặt phòng khách sạn"
    • AI: "Okay! Tôi sẽ đóng vai nhân viên lễ tân. Bắt đầu nào! AI: Good evening! How can I help you? [User responds...] AI: [Continues conversation, corrects gently if needed]"

  5. Progress Insights

    • User: "Tôi học được gì rồi?"
    • AI: "Bạn đã học 100 từ trong 5 ngày! Điểm phát âm trung bình là 78/100. Bạn giỏi nhất ở từ vựng về Food. 🎉"

  6. Learning Tips

    • User: "Làm sao nhớ từ lâu hơn?"
    • AI: "Mẹo hay nhất là dùng từ trong câu! Thử tự tạo câu với từ mới. Ví dụ: 'I eat an apple' → 'I eat an apple for breakfast every day.' Cụ thể hơn sẽ nhớ lâu hơn!"

Technical Implementation:

  • Azure OpenAI GPT-4 or similar
  • System prompt defines personality and rules
  • Context includes user's progress data
  • Conversation history stored for continuity
  • Vietnamese language support

Guardrails:

  • Cannot do homework for user (encourages learning)
  • Redirects off-topic questions gently
  • Escalates if user expresses distress (provide resources)

4. Progress Dashboard

Purpose: Show personal achievements and learning patterns

Design Decision: Comprehensive dashboard with personal stats only (NO leaderboard/comparison)

Layout:

┌────────────────────────────────────────┐
│  Progress              [Settings ⚙️]   │
├────────────────────────────────────────┤
│  📊 TỔNG QUAN                          │
│  ┌──────────────────────────────────┐ │
│  │  🔥 Streak: 7 ngày               │ │
│  │  ✓ Hoàn thành: 15/120 (12.5%)   │ │
│  │  📅 Ước tính kết thúc:          │ │
│  │     15 tháng 5, 2026             │ │
│  └──────────────────────────────────┘ │
│                                        │
│  🏆 CỘT MỐC                           │
│  ┌──────────────────────────────────┐ │
│  │  ✓ 10 ngày  ○ 30 ngày           │ │
│  │  ○ 60 ngày  ○ 90 ngày           │ │
│  │  ○ 120 ngày (Hoàn thành!)       │ │
│  └──────────────────────────────────┘ │
│                                        │
│  📈 BIỂU ĐỒ TIẾN ĐỘ                  │
│  [Line/Bar Chart: Lessons/week]       │
│   │                                   │
│ L │     ╭─╮                           │
│ e │  ╭──╯ ╰╮                          │
│ s │╭─╯     ╰─╮                        │
│ s │           ╰─                      │
│ o │                                   │
│ n │                                   │
│ s │─────────────────────────          │
│     W1  W2  W3  W4  W5               │
│                                        │
│  💪 KỸ NĂNG CỤ THỂ                    │
│  ┌──────────────────────────────────┐ │
│  │ Từ vựng: 750/3000                │ │
│  │ ██████████░░░░░░░░░░░░░ (25%)    │ │
│  │                                   │ │
│  │ Phát âm: Điểm TB 78/100          │ │
│  │ ████████████████░░░░░░            │ │
│  │                                   │ │
│  │ Practice Scenarios: 12 hoàn thành│ │
│  │ ██████░░░░░░░░░░░░░░░░            │ │
│  │                                   │ │
│  │ AI Conversations: 25 phiên       │ │
│  │ ██████████░░░░░░░░░░░░            │ │
│  └──────────────────────────────────┘ │
│                                        │
│  💬 AI COACH                          │
│  ┌──────────────────────────────────┐ │
│  │ "Bạn đã tiến bộ 15% trong phát   │ │
│  │  âm tuần này! Âm /th/ của bạn    │ │
│  │  rõ ràng hơn rất nhiều đấy. Tiếp │ │
│  │  tục phát huy nhé! 🎉"           │ │
│  └──────────────────────────────────┘ │
│                                        │
└────────────────────────────────────────┘

Sections:

4.1 Overview Stats (Top)

Metrics:

  • Streak: Days studied consecutively (🔥 icon)
    • Resets if miss a day
    • Shown prominently
  • Completion: X/120 days with percentage
    • Visual progress bar optional
  • Estimated Completion: Based on current pace
    • "Ước tính kết thúc: [date]"
    • Motivating to see end date

4.2 Milestone Badges

Visual: Medal/badge icons

Milestones:

  • 10 days: "Kiên trì 10 ngày" 🥉
  • 30 days: "Một tháng thành công" 🥈
  • 60 days: "Nửa chặng đường" 🥇
  • 90 days: "Sắp đến đích" 🏆
  • 120 days: "Hoàn thành lộ trình" 🎓

Design:

  • Unlocked: Full color, prominent
  • Locked: Grayscale with lock icon
  • Hover: Shows criteria and benefits
  • Click: Shows more details about achievement

4.3 Progress Chart

Type: Line chart or bar chart

Data:

  • X-axis: Time (weeks or days)
  • Y-axis: Lessons completed OR time spent (minutes)
  • Shows consistency and patterns
  • Helps identify when user is most active

Insights:

  • "Bạn học nhiều nhất vào buổi sáng"
  • "Tuần này bạn giảm hoạt động 20% so với tuần trước"
  • Gentle nudges, not judgmental

4.4 Skill Breakdown

Metrics:

  1. Vocabulary:

    • Count: "750/3000 words learned"
    • Progress bar: Visual percentage
    • Breakdown: By topic if applicable

  2. Pronunciation:

    • Average score: "78/100"
    • Trend: "↑ +5 điểm so với tuần trước"
    • Top challenge: "Âm /θ/ còn cần luyện"

  3. Practice Scenarios:

    • Count: "12 scenarios completed"
    • List: Which ones (Airport, Restaurant, Shopping...)

  4. AI Conversations:

    • Count: "25 conversation sessions"
    • Total time: Optional
    • Topics: What they practiced most

Visual: Progress bars for each with percentage

4.5 AI Coach Encouragement

Purpose: Personalized, data-driven motivation

Content:

  • Weekly update (changes every 7 days)
  • Based on actual progress data
  • Specific praise: "Âm /th/ của bạn rõ ràng hơn"
  • Gentle nudge: "Thử luyện thêm Listening tuần này nhé!"
  • Always positive, never critical

Examples:

  • "Bạn đã tiến bộ 15% trong phát âm tuần này! Âm /th/ rõ ràng hơn rất nhiều. 🎉"
  • "Streak 7 ngày - bạn đang rất kiên trì! Hãy tiếp tục như vậy! 💪"
  • "Tuần này bạn học ít hơn chút, nhưng không sao! Nghỉ ngơi cũng quan trọng. Sẵn sàng bắt đầu lại chưa?"

4.6 What NOT to Include

Deliberately excluded:

  • ❌ Leaderboard ("You're ranked #47")
  • ❌ Comparisons ("You're ahead of 60% of users")
  • ❌ Competition ("Beat your friends!")
  • ❌ Public profiles
  • ❌ Social features (follows, likes)

Reason: Target users fear comparison and have failed before

5. Exit/Completion Flow (Day 120)

Path: Day 120 Complete → Celebration → Final Assessment → Next Steps → Continued Access

Design Decision: Celebration → Final test → Personalized recommendations

5.1 Completion Celebration

Trigger: User completes Day 120

Full-Screen Experience:

┌────────────────────────────────────────┐
│                                        │
│          🎉🎓🎊                        │
│                                        │
│     CHÚC MỪNG!                         │
│     BẠN ĐÃ HOÀN THÀNH                 │
│     120 NGÀY!                          │
│                                        │
│  [Confetti animation]                  │
│                                        │
│  Thành tích của bạn:                   │
│  ✓ 3,000 từ vựng đã học               │
│  ✓ 120 bài học hoàn thành             │
│  ✓ [X] giờ học tập                    │
│  ✓ Streak cao nhất: [Y] ngày          │
│                                        │
│  [Tiếp tục →]                          │
│                                        │
└────────────────────────────────────────┘

Elements:

  • Animation: Confetti, fireworks, or celebration animation
  • Message: Clear celebration of completion
  • Stats: Key achievements highlighted
    • Total words learned
    • Total lessons completed
    • Total time invested
    • Longest streak
  • Optional: Share to social media (Facebook, Twitter)
    • Pre-filled message: "Tôi vừa hoàn thành 120 ngày học tiếng Anh với Learn English Zero! 🎉"

5.2 Final Assessment

Purpose: Measure progress from diagnosis to completion

Message: "Làm bài test cuối để xem bạn đã tiến bộ bao nhiêu!"

Format: Same as initial diagnosis test

  • 4 sections: Đọc, Nghe, Nói, Phản xạ
  • 5-10 minutes
  • Same question types

Results Comparison:

┌────────────────────────────────────────┐
│  KẾT QUẢ TIẾN BỘ CỦA BẠN              │
├────────────────────────────────────────┤
│                                        │
│  [Side-by-side comparison]             │
│                                        │
│  Ngày 1          →      Ngày 120      │
│  ─────────────────────────────────     │
│  Mù: 70%         →      20% 🎉        │
│  ████████████████░░░░                  │
│                                        │
│  Điếc: 50%       →      15% 🎉        │
│  ████████████░░░░░░░░░░                │
│                                        │
│  Câm: 30%        →      10% 🎉        │
│  ████████░░░░░░░░░░░░░░                │
│                                        │
│  Phản xạ: 20%    →      5% 🎉         │
│  ██████░░░░░░░░░░░░░░░░                │
│                                        │
│  Cải thiện tổng thể: 65% 🚀           │
│                                        │
│  [Xem gợi ý bước tiếp theo →]         │
│                                        │
└────────────────────────────────────────┘

Content:

  • Before/After Visualization: Radar chart or bars
  • Improvement Percentage: Overall improvement score
  • Specific Wins: Highlight biggest improvements
  • Encouragement: "Bạn đã tiến bộ rất nhiều!"

5.3 Personalized Next Steps

Purpose: Ensure users aren't abandoned; provide clear path forward

Layout:

┌────────────────────────────────────────┐
│  BƯỚC TIẾP THEO                        │
├────────────────────────────────────────┤
│  Dựa trên kết quả test, chúng tôi      │
│  gợi ý:                                │
│                                        │
│  🎯 Trình độ hiện tại: A2-B1          │
│                                        │
│  ────────────────────────────────      │
│                                        │
│  📺 TỰ HỌC TIẾP                       │
│  ┌──────────────────────────────────┐ │
│  │ YouTube Channels:                │ │
│  │ • English with Lucy              │ │
│  │ • BBC Learning English           │ │
│  │ • [Specific Vietnamese channels] │ │
│  │                                   │ │
│  │ Podcasts:                        │ │
│  │ • 6 Minute English (BBC)         │ │
│  │ • The English We Speak           │ │
│  └──────────────────────────────────┘ │
│                                        │
│  🏫 HỌC TẠI TRUNG TÂM                 │
│  ┌──────────────────────────────────┐ │
│  │ Nếu muốn học có giáo viên:       │ │
│  │                                   │ │
│  │ • VUS (Intermediate level)       │ │
│  │ • ILA (Communication focus)      │ │
│  │ • Apollo (General English)       │ │
│  │                                   │ │
│  │ Lưu ý: Với nền tảng A2-B1, bạn   │ │
│  │ sẽ học hiệu quả hơn rất nhiều!   │ │
│  └──────────────────────────────────┘ │
│                                        │
│  📚 ỨNG DỤNG HỌC NÂNG CAO            │
│  ┌──────────────────────────────────┐ │
│  │ • Cake (Conversation practice)   │ │
│  │ • ELSA (Pronunciation)           │ │
│  │ • Memrise (Vocabulary B2+)       │ │
│  └──────────────────────────────────┘ │
│                                        │
│  ────────────────────────────────      │
│                                        │
│  💬 "Bạn vẫn có thể quay lại review   │
│     bất kỳ lúc nào. Chúc bạn thành    │
│     công!" - AI Coach                 │
│                                        │
│  [Về Dashboard]                        │
│                                        │
└────────────────────────────────────────┘

Content Categories:

  1. Current Level: A2-B1 or based on final test

  2. Self-Study Resources:

    • YouTube Channels: 3-5 specific recommendations
      • Criteria: Vietnamese-friendly, A2-B1 level, high quality
    • Podcasts: 2-3 beginner-friendly podcasts
    • Apps: Complementary apps (not competitors)

  3. Language Centers (if ready):

    • 3-4 reputable centers in Vietnam
    • Brief description of each
    • Level placement suggestion
    • Positioning: "Với nền tảng A2-B1, bạn sẽ học hiệu quả hơn!" (not "you need to pay now")

  4. Books/Resources (optional):

    • Grammar books
    • Reading materials at their level

Personalization:

  • If final test shows weak Listening → Recommend podcasts
  • If weak Speaking → Recommend conversation apps/centers
  • If strong overall → Suggest B2 materials

Tone: Supportive, not pushy. Recommendations, not requirements.

5.4 Continued Access

What Users Keep:

  • ✓ Full access to all 120 lessons (for review)
  • ✓ AI Coach still available for questions
  • ✓ Progress dashboard (frozen at completion state)
  • ✓ Can retake lessons anytime
  • ✓ Can redo final assessment to track continued progress

What Changes:

  • No more "daily" lessons unlocking
  • Dashboard shows "Completed" status
  • Optional: Email digest with tips (monthly)

No Pressure:

  • No upsells or paywalls
  • No "premium features" locked
  • Truly complete experience

6. Edge Cases

6.1 Returning After Long Absence (2-4 weeks)

Scenario: User hasn't logged in for 14+ days

Flow: Login → Welcome Back Modal → Optional Review → Dashboard

Welcome Back Modal:

┌────────────────────────────────────────┐
│  CHÀO MỪNG TRỞ LẠI! 👋                │
├────────────────────────────────────────┤
│                                        │
│  Chúng tôi nhớ bạn!                    │
│  Bạn đã nghỉ 18 ngày.                  │
│                                        │
│  Tiến độ của bạn vẫn được giữ nguyên: │
│  ✓ Bạn đang ở Day 6                   │
│  ✓ Đã học 100 từ vựng                 │
│                                        │
│  ────────────────────────────────      │
│                                        │
│  💡 Gợi ý: Thử ôn lại Day 5 để lấy    │
│  lại cảm giác nhé!                     │
│                                        │
│  [Preview: 5 flashcards from Day 5]   │
│                                        │
│  [Ôn bài Day 5]    [Tiếp tục Day 6]  │
│                                        │
└────────────────────────────────────────┘

Design Decisions:

  • No Shame: Message is welcoming, not judgmental
  • Preserve Progress: Clearly state progress is saved
  • Suggest Review: Optional, can skip
  • Preview: Show few flashcards to jog memory
  • Choice: User decides to review or continue

Dashboard Changes:

  • Streak reset: "Streak: 0 ngày (đã reset, bắt đầu lại nào!)"
  • AI Coach message:
    • "Không sao cả! Việc bắt đầu lại là hoàn toàn bình thường. Nhiều người học giỏi cũng từng nghỉ giữa chừng. Quan trọng là bạn đã quay lại! 💪"

Retention Email (optional, if user gives permission):

  • After 7 days: Gentle reminder
  • After 14 days: Show progress, encourage return
  • After 30 days: "We miss you" with benefits of returning
  • Never spam, max 3 emails

6.2 Wants to Reset Progress

Scenario: User wants to start completely over

Access: Settings → Reset Progress

Warning Modal:

┌────────────────────────────────────────┐
│  ⚠️  XÓA TIẾN ĐỘ                      │
├────────────────────────────────────────┤
│                                        │
│  Bạn chắc chắn muốn xóa hết tiến độ   │
│  và bắt đầu lại từ Day 1?              │
│                                        │
│  Điều này sẽ xóa:                      │
│  • 15 bài học đã hoàn thành           │
│  • 300 từ vựng đã học                 │
│  • Tất cả tiến độ và streak           │
│  • Lịch sử AI Coach conversations     │
│                                        │
│  ⚠️  Hành động này KHÔNG THỂ hoàn tác │
│                                        │
│  Để xác nhận, nhập: RESET              │
│  [____________]                        │
│                                        │
│  [Hủy]              [Xóa và bắt đầu]  │
│                                        │
└────────────────────────────────────────┘

Design Decisions:

  • Strong Warning: Make consequences very clear
  • Friction: Require typing "RESET" to confirm
    • Prevents accidental resets
  • Prominent Cancel: Cancel button is more visible
  • Explain What's Lost: Show specific progress being deleted

After Reset:

  • Redirect to diagnosis test (optional: skip if recent)
  • Or directly to Day 1
  • Fresh start, all progress cleared
  • Keep email/account (not deleted)

Alternative (recommended):

  • Instead of full reset, offer "Review Mode"
    • Go back through lessons without losing progress
    • Mark as "reviewing" not "redoing"

6.3 Locked Lesson Click (Trying to Skip)

Scenario: User clicks Day 7 when Day 6 not complete

Interaction:

Visual State:

  • Day 7 card is grayed out
  • Padlock icon 🔒 visible
  • Hover shows tooltip

Tooltip:

┌────────────────────────┐
│ 🔒 Chưa mở khóa       │
│ Hoàn thành Day 6      │
│ để học bài này        │
└────────────────────────┘

If User Clicks Anyway → Modal:

┌────────────────────────────────────────┐
│  Bài này chưa mở khóa                  │
├────────────────────────────────────────┤
│                                        │
│  Day 7 sẽ mở sau khi bạn hoàn thành   │
│  Day 6.                                │
│                                        │
│  Tại sao vậy?                          │
│  Để đảm bảo bạn học vững từng bước!   │
│  Mỗi bài xây dựng trên bài trước.     │
│                                        │
│  [Về Day 6]          [Đóng]           │
│                                        │
└────────────────────────────────────────┘

Design Decisions:

  • Explain Why: Not arbitrary; helps learning
  • Gentle Tone: Educational, not punishing
  • Easy Exit: "Về Day 6" button to guide them

Exception:

  • Can always review completed lessons
  • Day 1-5 completed? Can review any of those anytime

6.4 Struggling With Lessons (Multiple Failures)

Scenario: User scores low on mini-tests repeatedly (e.g., <50% on 3 consecutive tests)

Trigger: AI Coach proactively intervenes

AI Coach Message:

┌────────────────────────────────────────┐
│  AI Coach 💬                           │
├────────────────────────────────────────┤
│  Mình để ý bạn đang gặp khó khăn với  │
│  những bài gần đây.                    │
│                                        │
│  Không sao cả - học ngôn ngữ có lúc   │
│  khó khăn là bình thường!              │
│                                        │
│  Bạn có muốn:                          │
│  • Ôn lại bài trước (Day 8)?          │
│  • Xem tips học từ vựng hiệu quả?     │
│  • Chat với mình để được giải đáp?    │
│                                        │
│  [Ôn bài]  [Xem tips]  [Chat ngay]    │
│                                        │
└────────────────────────────────────────┘

Options:

  1. Review Previous Lesson: Go back to reinforce
  2. Learning Tips: Show proven study techniques
    • Spaced repetition
    • Creating example sentences
    • Using words in context
  3. Chat with AI: Discuss specific challenges

Tone: Supportive, not critical. Frame as normal part of learning.

6.5 Technical Errors (API Failures, Loading Issues)

Scenario: Azure Speech API is down, can't score pronunciation

Error Handling:

┌────────────────────────────────────────┐
│  ⚠️  Lỗi tạm thời                      │
├────────────────────────────────────────┤
│  Hệ thống chấm phát âm đang gặp sự cố │
│  tạm thời.                             │
│                                        │
│  Bạn có thể:                           │
│  • Thử lại sau vài phút               │
│  • Bỏ qua phần này (không ảnh hưởng   │
│    tiến độ)                            │
│  • Tiếp tục phần tiếp theo            │
│                                        │
│  [Thử lại]  [Bỏ qua]  [Tiếp tục]     │
│                                        │
└────────────────────────────────────────┘

Design Decisions:

  • Transparent: Explain what went wrong
  • Options: Give user control
  • No Penalty: Progress not blocked by technical issues
  • Retry: Easy to retry when ready

Logging:

  • Track errors for debugging
  • Alert admins if widespread
  • Provide fallback (e.g., manual "I completed this" option)

6.6 Browser Compatibility Issues

Scenario: User's browser doesn't support Web Audio API (for recording)

Detection: Check on page load

Warning:

┌────────────────────────────────────────┐
│  ⚠️  Trình duyệt không hỗ trợ          │
├────────────────────────────────────────┤
│  Một số tính năng (ghi âm phát âm)    │
│  không hoạt động trên trình duyệt này.│
│                                        │
│  Để trải nghiệm tốt nhất, vui lòng    │
│  dùng:                                 │
│  • Google Chrome (khuyên dùng)        │
│  • Microsoft Edge                      │
│  • Safari (iOS/Mac)                    │
│                                        │
│  Bạn vẫn có thể học nhưng sẽ bỏ qua  │
│  phần luyện phát âm.                   │
│                                        │
│  [Tiếp tục]          [Tải Chrome]     │
│                                        │
└────────────────────────────────────────┘

Graceful Degradation:

  • Skip pronunciation exercises on unsupported browsers
  • All other features still work
  • Suggest compatible browser

Summary of Key Design Decisions

Aspect Decision Rationale
Test Results Display Show detailed % with visualization Builds trust through transparency, aligns with medical metaphor
Login Timing After viewing test results User sees value before commitment, natural conversion point
Additional Questions 3-5 multiple choice after login Balances personalization data vs. signup friction
Lesson Unlock Strict sequential (must complete previous) Ensures solid foundation for target audience who need structure
AI Coach UI Floating button + slide-in chat panel Always accessible, familiar pattern (Intercom), non-intrusive
Returning Users Welcome + suggest optional review No shame/guilt, gentle re-entry, preserves progress
Progress Dashboard Personal achievements only (NO leaderboard) Respects target audience's fear of comparison
Exit Flow Celebration → Assessment → Next steps Clear completion, shows progress, no abandonment
Edge Cases Supportive handling, no penalties Reinforces "AI coach supports, never judges" philosophy

Technical Implementation Notes

Priority for MVP

Phase 1 (MVP):

  1. Onboarding flow (Landing → Test → Login → Questions → Prescription)
  2. Daily learning flow (Dashboard → Lesson → Flashcards → Mini-test)
  3. AI Coach basic (floating button, text chat only)
  4. Progress dashboard (basic stats, no charts yet)

Phase 2: 5. Pronunciation practice (Azure Speech integration) 6. Progress charts and visualizations 7. Advanced AI Coach features (scenarios, voice input) 8. Exit/completion flow

Phase 3: 9. Edge case refinements 10. Email notifications 11. Mobile app (if needed)

Key Technologies

  • Frontend: Next.js, React, Tailwind CSS
  • Charts: Recharts or Chart.js
  • Animations: Framer Motion
  • Audio: Web Audio API, HTML5 Audio
  • AI: Azure OpenAI (GPT-4), Azure Speech
  • Storage: Supabase PostgreSQL
  • Auth: Supabase Auth (Google OAuth)

Next Steps

  1. Review & Feedback: Team review of this design doc
  2. UI Mockups: Create visual mockups in Figma
  3. User Testing: Test wireframes with 3-5 target users
  4. Technical Planning: Break down into implementation tasks
  5. Development: Start with Phase 1 (MVP)

References & Dependencies

  • definitions.md: Single source of truth cho constants và enums
  • diagnosis-test.md: Chi tiết bài test và prescription logic (5 prescription types)
  • don-mu-vocabulary.md: Nội dung học cho RX_MU
  • gamification.md: Streak rules, milestones, copy guidelines
  • ai-coach-behavior.md: AI Coach messages và behavior
  • database-schema.md: Schema cho user data và field mappings

UI Component Dependencies

  • Dashboard ← gamification.md (streak display rules, longest streak)
  • Prescription Page ← diagnosis-test.md (5 prescription types)
  • AI Coach Panel ← ai-coach-behavior.md (message templates)
  • Additional Questions ← database-schema.md (field mapping)

Document Status: ✅ Complete - Ready for review Last Updated: 2026-01-09 Next Review: After stakeholder feedback