Skip to content

Learner Guided UX

A Brainly-style guided home for learners that replaces the blank chat-first front door. B2C learners go through a short onboarding wizard on first signup; B2B learners inherit institution context. Both then land on /learn, a task-shaped home where every action primes the chat with subject and topic context before the message bar opens.

Naming note: this doc says "learner", but the code still uses the legacy student identifiers: KWILO_STUDENT_MODES, StudentHomePage, pages/student/, education_stage. Match the code identifiers when implementing; the rename is a separate cleanup.

How it works

The chat is never the front door. Every learner-initiated chat session has subject and (sometimes) topic context primed by the intent the learner picked. Mode chips are gone from the learner chat: the intent is the mode.

Learner logs in
  │
  ▼
B2C without onboarding?  ─yes─▶  /onboarding (3-step wizard)
  │ no                                │
  ▼                                   ▼
/learn home                      complete or skip
  │
  ├── Continue learning row (renders only with data) ──▶ /lessons/:id
  │
  ├── 2×2 intent grid:
  │   ├── Get help with a problem  ─┐
  │   ├── Understand a topic        │  micro-pickers (subject + topic)
  │   ├── Practice for a test       │  ──▶ /ai-tutor (chat) or quiz
  │   └── Revise weak topics       ─┘
  │
  └── secondary nav: My courses · Assignments · Achievements

Onboarding wizard (B2C only). Runs once at /onboarding, gated by onboarding_completed_at IS NULL. Three steps: education stage, subjects, optional goal. Mandatory but every step has "Skip for now". B2B learners skip the wizard entirely; their context comes from institution enrollment.

The /learn home. A greeting, an optional Continue-learning row (hidden when there's no in-progress data), a 2×2 grid of five intents, and a secondary nav row to courses, assignments, and achievements. Four intents are chat-bound and open a micro-picker (subject chip → topic chip → input) that gathers context before chat opens. The fifth, Continue learning, is navigation-only and routes to the last lesson.

Post-answer chips. After every AI response, up to four chips: Simplify, Explain more, Show example, Try a question. Tapping a chip sends a structured follow-up. Short responses show only Explain more; the rest hide when not applicable.

Solu, the brand guide. A small floating-spirit mascot carries contextual hints. Two surfaces: an inline Solu beside page content with a speech bubble (/onboarding, /learn), and a floating SoluCompanion fixed bottom-right and persistent across the app. Pages register hints via <SoluTip>{copy}</SoluTip> (latest mounted wins; hidden on auth routes and pages already showing an inline Solu). The companion is dismissible via a "Hide Solu" button backed by a zustand+persist store (kwilo:solu-companion). Tip copy lives in common.solu.tips.* i18n keys.

Visual language is lean: wizard pills are text-only, intent tiles carry one Heroicon outline glyph each, and /learn has no XP, streak, or achievement chrome.

Edge cases

  • B2C user skips the wizard. Lands on /learn with a persistent banner ("Finish setting up your profile so we can personalize your home") linking to the first incomplete step. The four intents still work with neutral defaults.
  • No in-progress course. Continue-learning row is hidden; no placeholder.
  • No mastery data. The Revise intent shows "Take a 5-question diagnostic to find your weak spots" and routes to the Understand picker (the diagnostic generation is deferred).
  • home-context API error. Continue-learning row hidden; quiet inline retry pill at top. The four intents still work.
  • Quota exhausted (B2C freemium). Picker opens; Send is disabled with an inline message linking to /pricing. Reuses the existing useCapability hook.
  • Returning B2C user who signed up pre-wizard. Redirected once from /learn to /onboarding on next login.

Where it lives

Routes: /learn (StudentHomePage), /onboarding (B2COnboardingWizard, B2C only), /ai-tutor (chat, demoted from the post-login default).

API: POST /api/v1/onboarding/profile (save wizard data to UserLearningProfile), GET /api/v1/learner/home-context (one call powers the home), GET /api/v1/curriculum/topics?subject_id=X (topic chips).

Key files: apps/web/src/pages/learner/StudentHomePage/, apps/web/src/pages/b2c/OnboardingWizard/, packages/ui/src/surfaces/IntentTile.tsx, packages/ui/src/brand/Solu.tsx and SoluCompanion.tsx.