Skip to content

feat(flashcards): UX revamp with cross-deck review and gamification#135

Merged
Peleke merged 10 commits intostagingfrom
feature/flashcard-ux-revamp
Jan 7, 2026
Merged

feat(flashcards): UX revamp with cross-deck review and gamification#135
Peleke merged 10 commits intostagingfrom
feature/flashcard-ux-revamp

Conversation

@Peleke
Copy link
Owner

@Peleke Peleke commented Dec 23, 2025

Summary

Major UX revamp of the flashcard system implementing Anki-like power-user efficiency with Duolingo-style gamification (toggleable).

Schema Changes

  • Added language field to flashcard_decks (es, la, is, mixed) with auto-inheritance from course
  • Added gamification fields to user_profiles: streak_freezes_available, streak_freeze_used_at, gamification_enabled
  • Streak freeze awarded automatically every 7-day streak milestone

API Enhancements

  • Cross-deck review with mode=all and language filtering
  • New /api/flashcards/stats/due-by-language for language-grouped due counts
  • New /api/flashcards/stats/gamification for GET/PATCH gamification settings
  • XP integration: 5 XP per card, 25 completion bonus, streak bonus up to 100

New Review Page (/flashcards/review)

  • 3D flip animation with CSS transforms
  • Touch swipe gestures (up to reveal, left/right to rate)
  • "Good" button visually dominant (large, green)
  • XP gain animation overlay
  • Keyboard shortcuts: Space (reveal), 1-4 (rate), Esc (exit)

Dashboard Updates

  • "Review All Due" cross-deck button
  • Language filter buttons with per-language due counts
  • Gamification stats header (XP, streak, freezes)

Profile Page

  • Gamification settings section with toggle
  • Stats display when enabled

Test Plan

  • Run migrations against staging database
  • Test cross-deck review flow (all languages)
  • Test single-language review filter
  • Test single-deck review
  • Verify XP accumulation after each review
  • Verify streak increments after daily reviews
  • Test streak freeze earned at 7-day milestone
  • Toggle gamification off and verify XP/streak hidden
  • Test 3D flip animation on desktop and mobile
  • Test swipe gestures on mobile devices
  • Test keyboard shortcuts (Space, 1-4, Esc)
  • Verify completion bonus (25 XP) on session complete

🤖 Generated with Claude Code

Peleke Sengstacke and others added 7 commits December 23, 2025 06:00
@claude
fix(tts): correct ElevenLabs API key env var name
443b193 
Change ELEVEN_LABS_API_KEY to ELEVENLABS_API_KEY to match
the deployment configuration in GitHub Actions workflows.

Closes #129

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(exercises): make translation direction detection language-agnostic
4a23d55 
Replace hardcoded "spanish"/"latin" string matching with dynamic
language name lookup. Now correctly detects translation direction
for all supported languages including Icelandic.

Closes #130

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(exercises): add language-aware feedback to Training Ground
19fa627 
- Add getExerciseFeedback() utility for language-specific success/failure messages
- Update FillBlankExercise, MultipleChoiceExercise, and TranslationExercise
  to accept language prop and display localized feedback
- Update ExercisesRegion to pass language prop to exercise components

Feedback by language:
- Spanish: ¡Correcto! / No del todo
- Latin: Recte! / Non recte
- Icelandic: Rétt! / Ekki alveg

Closes #131

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(ui): add dark mode support to Profile and Flashcards components
7efbe6f 
- Add dark mode variants to NotificationSettings component (alerts, status boxes)
- Add dark mode variants to PWAInstallBanner component
- Add dark mode variants to Flashcards deck management page (25+ fixes)
- Add dark mode variant to Flashcards practice page (mark element)
- Replace text-sepia-* with semantic text-foreground/text-muted-foreground
- Add E2E tests for multi-language exercise feedback

Closes #133 (related diagnosis)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(ui): eliminate extra scroll space on mobile
3b76ad4 
- Replace min-h-screen with min-h-[100dvh] for dynamic viewport height
- Remove redundant min-h-screen from nested mobile dashboard container
- Update hub-container and classic-container CSS classes
- Add pb-8 to mobile dashboard for proper bottom spacing

The 100dvh unit uses dynamic viewport height which properly accounts
for mobile browser chrome (address bar) appearing/disappearing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
feat(flashcards): Add UX revamp with cross-deck review and gamification
ba1531f 
Schema changes:
- Add language field to flashcard_decks (es, la, is, mixed)
- Add gamification fields to user_profiles (streak_freezes_available,
  streak_freeze_used_at, gamification_enabled)
- Add trigger to auto-populate deck language from course
- Add trigger to award streak freeze every 7-day streak milestone

API updates:
- Update get_due_flashcards RPC with language filter parameter
- Add get_due_counts_by_language RPC for dashboard stats
- Add /api/flashcards/stats/due-by-language endpoint
- Add /api/flashcards/stats/gamification GET/PATCH endpoints
- Update practice API with mode=all and language filter support
- Integrate XP awards into review endpoint (5 XP/card, 25 completion bonus)

New review page (/flashcards/review):
- 3D flip animation with CSS transforms
- Touch swipe gestures (up to reveal, left/right to rate)
- Dominant "Good" button with secondary rating options
- XP gain animation overlay
- Cross-deck review with language filtering via query params
- Keyboard shortcuts (Space, 1-4, Esc)

Dashboard updates:
- Cross-deck "Review All Due" button with total due count
- Language filter buttons showing per-language due counts
- Gamification stats display (XP, streak, freezes)
- Language badge on deck cards

Profile page:
- Gamification settings section with toggle
- Stats display (XP, streak, level, freezes)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
feat: Add flashcard tests, dashboard CTA, and reader/library fixes
a79fc70 
Tests:
- Add 38 unit tests for flashcard service (MockScheduler, XP_AWARDS, cloze parsing)
- Add E2E tests for flashcard review flows (flip animation, keyboard shortcuts, rating)

Dashboard:
- Add FlashcardCTA component showing due card count
- Display on both mobile and desktop dashboard views
- Links to cross-deck review when cards are due

Reader/Library Fixes:
- Fix language auto-select when loading readings (API now returns language field)
- Add title input field to TextInputPanel for custom reading titles
- Fix library service to transform timestamps (snake_case to camelCase)
- Fix library service to return actual language instead of hardcoded 'es'
- Add Icelandic language support to LibraryCard display

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@Peleke
Copy link
Owner Author

Peleke commented Dec 23, 2025

🧪 User Acceptance Testing (UAT) Guide

Pre-requisites

  • Have at least one flashcard deck with cards
  • Have gamification enabled (toggle in /profile)
  • Have at least one text saved in Library

1️⃣ Flashcard Dashboard & Review Flow

1.1 Cross-Deck Review

  1. Navigate to /flashcards
  2. Click "Review All Due" button (if cards are due)
  3. Expected: Review page loads with flashcard
  4. Test flip animation: Click the card or press Space
  5. Expected: Card flips with 3D animation, shows answer + rating buttons
  6. Test rating: Click "Good" or press 3
  7. Expected: Card advances, XP animation shows (if gamification enabled)
  8. Complete session
  9. Expected: Session complete screen with stats and "Back to Decks" button

1.2 Single Deck Review

  1. On /flashcards, find a deck with due cards
  2. Click "Practice" on that deck
  3. Expected: URL contains deckId= parameter
  4. Expected: Only cards from that deck appear

1.3 Keyboard Shortcuts

  • Space - Reveal card
  • 1 - Rate "Again"
  • 2 - Rate "Hard"
  • 3 - Rate "Good"
  • 4 - Rate "Easy"
  • Escape - Exit review → /flashcards

2️⃣ Dashboard Flashcard CTA

  1. Navigate to /dashboard
  2. If cards are due:
    • Expected: See "X cards ready for review" CTA with indigo gradient
    • Click the CTA
    • Expected: Navigates to /flashcards/review?mode=all
  3. If no cards due: CTA should not appear

3️⃣ Gamification Toggle

  1. Navigate to /profile
  2. Find "Flashcard Gamification" section
  3. Expected: See current stats (XP, Streak, Level, Freezes)
  4. Toggle gamification OFF
  5. Navigate to /flashcards and review a card
  6. Expected: No XP animation after rating
  7. Toggle gamification back ON
  8. Review another card
  9. Expected: XP animation appears (+5 XP base)

4️⃣ Reader Language Auto-Select

4.1 From Lesson

  1. Open a Spanish lesson with a reading (e.g., from a course)
  2. Click "Open in Reader"
  3. Expected: Reader opens with language dropdown set to "Spanish"

4.2 From Library

  1. Navigate to /library
  2. Click "Read" on a text that was saved as Latin
  3. Expected: Reader opens with language dropdown set to "Latin"

5️⃣ Reader Title Input

  1. Navigate to /reader directly (no libraryId param)
  2. Expected: See "Title (optional)" input field above the text area
  3. Enter a custom title like "My Test Reading"
  4. Paste some text and click "Render Interactive Text"
  5. Navigate to /library
  6. Expected: See the reading with title "My Test Reading"

6️⃣ Library Timestamps & Language Display

  1. Navigate to /library
  2. Expected: Each card shows:
    • Correct language badge (🇪🇸 Spanish, 🏛️ Latin, or 🇮🇸 Icelandic)
    • Valid timestamp (e.g., "Dec 23, 2024")
  3. Expected: No "Invalid Date" or "undefined" errors
  4. Create a new Icelandic reading in /reader
  5. Expected: Library shows 🇮🇸 Icelandic badge

📋 Test Coverage Summary

Feature Unit Tests E2E Tests
MockScheduler ✅ 7 tests -
XP Calculation ✅ 9 tests -
Cloze Parsing ✅ 10 tests -
Card Generation ✅ 12 tests -
Flashcard Review - ✅ 23 tests
Dashboard CTA - (manual)
Reader/Library - (manual)

✅ Sign-off Checklist

  • Cross-deck review flow works end-to-end
  • Single deck review filters correctly
  • Keyboard shortcuts work as expected
  • Dashboard CTA appears when cards are due
  • Gamification toggle works in profile
  • Reader auto-selects language from readings
  • Reader title input saves to library
  • Library shows correct language and timestamps

Peleke Sengstacke and others added 3 commits December 25, 2025 14:36
@claude
docs: Update slides for investor/customer focus
a4b1c9e 
- Replace Part IV "Technical Deep Dive" with "The Opportunity"
- Add market size, underserved segments, timing factors
- Add B2C/B2B customer segments with pricing
- Add competitive advantage matrix
- Add "What We Need" launch/scale roadmap
- Keep Parts I-III: Problem, Demo, Roadmap

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
Fix: Add missing cloze_count column to flashcards table
42dff86 
The get_due_flashcards function references f.cloze_count but this
column wasn't added to the flashcards table. This fix:

1. Adds cloze_count column to flashcards table
2. Creates index for efficient cloze card queries
3. Backfills existing cloze cards with correct count

Without this, practice endpoint fails with:
"column f.cloze_count does not exist"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude
fix(flashcards): Make XP animation subtle top-right toast
a6268fc 
Changed XP gain animation from:
- Centered, bouncing, large overlay blocking card view
To:
- Top-right corner toast-style notification
- Smaller, pill-shaped badge with fade-in animation
- No longer obstructs the next card

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@Peleke
Copy link
Owner Author

Peleke commented Jan 7, 2026

✅ UAT Complete

Tests Performed

Cross-Deck Review

  • Enabled cross-deck review from flashcards page
  • Reviewed cards from multiple decks in single session
  • Result: ✅ Cards from all decks appear correctly

Flashcard Review Flow

  • Tested card flipping and rating (1-5 scale)
  • Verified spaced repetition scheduling
  • Result: ✅ Review flow works smoothly

XP Animation

  • Completed flashcard reviews to earn XP
  • Verified animation appears as subtle top-right toast
  • Result: ✅ Animation is non-intrusive (fixed from full-screen overlay)

Gamification Elements

  • Streak tracking displays correctly ✅
  • XP accumulation works ✅
  • Progress indicators update in real-time ✅

Fixes Cherry-Picked from UAT

  • 1bc0fc8 Fix: Add missing cloze_count column to flashcards table
  • e9bbd42 fix(flashcards): Make XP animation subtle top-right toast

Migrations Required

  1. 20251223_cross_deck_practice.sql (includes cloze_count fix)
  2. 20251223_flashcard_ux_revamp.sql

Ready to merge 🚀

@Peleke Peleke merged commit 85475a6 into staging Jan 7, 2026
2 checks passed
@Peleke Peleke deleted the feature/flashcard-ux-revamp branch January 7, 2026 20:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Peleke