ACVE/student_experience_planish.md

ACVE Student Experience Plan (UX + Visual Quality)

Objective

Upgrade the student-facing product so it feels intentional, modern, and trustworthy while staying MVP-compatible.

This plan focuses on:

• Better visual hierarchy (less oversized type, reduced empty space).
• Cleaner information density (more useful content per viewport).
• Consistent interaction patterns (cards, tabs, progress, actions).
• A polished learning flow from discovery to lesson completion.

Current UX Problems (Observed)

• Excess whitespace on core pages (/courses, /case-studies, /practice) creates low information density.
• Heading/body type scale is too large in many sections, causing visual imbalance and "shouting" UI.
• Inconsistent card depth and spacing across pages.
• Weak content rhythm: sections do not form a predictable scan path.
• Placeholder areas appear disconnected from real actions (resources, modules, uploads).

Experience Principles

• Dense, not crowded: every fold should provide clear options or useful context.
• Strong hierarchy: heading sizes and spacing should reflect importance.
• Familiar learning patterns: follow proven edtech structures (clear hero, category rails, progress surfaces, action clusters).
• Trust by consistency: repeated visual language for statuses, metadata, and actions.
• Mobile parity: same clarity and intent on small screens.

Visual Direction

Typography System

• Introduce a controlled type ramp:
  • Display: 40-48px max (home hero only)
  • H1: 32-36px
  • H2: 24-28px
  • H3: 18-22px
  • Body-lg: 18px
  • Body: 16px
  • Meta: 13-14px
• Reduce line-length for long text blocks (max-width around 60-72ch).
• Reduce heading usage of very large serif text outside hero sections.

Spacing & Layout

• Use a spacing scale (4, 8, 12, 16, 24, 32, 48, 64).
• Standard section padding:
  • Desktop: 32-48px
  • Mobile: 16-24px
• Enforce consistent card height and internal spacing.
• Reduce vertical gaps between filter bars and content grids.

Components & Surfaces

• Standardize card anatomy:
  • Header: title + level/status chips
  • Body: summary + key stats
  • Footer: instructor + primary action
• Unify chip styles:
  • Level chip
  • Status chip (Draft, Published)
  • Access chip (Preview, Locked)
• Introduce one reusable "empty state" component with icon, message, CTA.

Student Journey Improvements

Discovery (/, /courses, /case-studies, /practice)

• Add compact "Quick Continue" strip at top for logged-in learners.
• Improve course list density:
  • 3-column desktop, 2-column tablet, 1-column mobile.
  • Show progress, lesson count, duration, rating without large gaps.
• Case studies:
  • Left index list with tighter cards.
  • Main detail panel with clearer section hierarchy and less oversized title.
• Practice:
  • Show module status (Available, Coming soon) plus expected duration.

Course Detail (/courses/[slug])

• Improve hero balance:
  • Course metadata row (level, status, rating, duration) in compact badges.
  • Right side sticky panel for progress + CTA.
• Add "What you will learn" bullet block (placeholder content allowed).
• Add "Course structure" preview (module/lesson count summary).

Learning Player (/courses/[slug]/learn)

• Keep two-column layout with stronger purpose:
  • Left: module/lesson navigation.
  • Right: lesson content, resources, completion action.
• Add lesson context strip:
  • Module X, Lesson Y, estimated time, content type.
• Add "Next lesson" CTA after completion.
• Keep resources placeholder but place it in a consistent right-panel section.

Practice Session (/practice/[slug])

• Add pre-quiz panel:
  • Difficulty, question count, expected time.
• During quiz:
  • Fixed progress header.
  • Cleaner answer state colors and spacing.
• Post-quiz:
  • Score summary card + "Review answers" placeholder.
  • Attempt history visible below summary.

Navigation & Account Experience

• Navbar should remain compact and consistent across pages.
• Add contextual breadcrumbs on deep routes:
  • Courses > [Course] > Learn
  • Practice > [Module]
• Logged-in state:
  • Show quick links (Continue, My Courses, Practice).
• Teacher-only controls remain isolated and clearly labeled.

Motion & Feedback

• Add subtle page-enter animation (fade + 12px rise, 180-220ms).
• Card hover:
  • slight elevation + border emphasis.
• Keep micro-interactions purposeful only (no decorative animation noise).

Accessibility & Readability

• Minimum contrast ratio compliant for text and controls.
• 44px minimum hit targets for buttons/tabs.
• Keyboard focus ring visible on all actionable components.
• Avoid placing essential information by color only.

Performance Constraints

• Avoid heavy media in above-the-fold learner screens.
• Use optimized image sizing and only essential shadows/blur.
• Keep layout shifts minimal (reserve card/media sizes).

Implementation Phases

Phase 1: Foundation (Design Tokens + Layout Baseline)

Status: DONE

• Create/update tokens in global styles:
  • type scale
  • spacing scale
  • surface/elevation tokens
  • badge/chip variants
• Normalize top-level content container widths and section paddings.
• Deliverable: consistent baseline on all public pages.

Phase 2: Discovery Page Refresh

Status: DONE

• Refine /courses, /case-studies, /practice for density and hierarchy.
• Standardize card and metadata patterns.
• Deliverable: cleaner listing UX with less visual noise.

Phase 3: Learning Flow Polish

Status: DONE

• Upgrade /courses/[slug] and /courses/[slug]/learn.
• Improve lesson progression and contextual guidance.
• Deliverable: student can move through lessons with clear momentum.

Phase 4: Practice Flow Polish

Status: DONE

• Upgrade /practice/[slug] session flow and result state.
• Improve attempt history readability.
• Deliverable: practice looks structured and rewarding.

Phase 5: Final QA + Consistency Pass

Status: DONE

• Accessibility checks (focus, contrast, tap targets).
• Mobile layout QA for all student routes.
• Copy and empty-state consistency.

Route-by-Route Checklist

• / Home: DONE
• /courses: DONE
• /courses/[slug]: DONE
• /courses/[slug]/learn: DONE
• /case-studies: DONE
• /case-studies/[slug]: DONE
• /practice: DONE
• /practice/[slug]: DONE
• /assistant: DONE

Progress Log

• 2026-02-11: Phase 1 baseline implemented with global spacing/type tokens and shared page spacing utilities in app/globals.css.
• 2026-02-11: Main content container tightened in app/layout.tsx to reduce visual spread.
• 2026-02-11: Discovery listings rebalanced for typography density in app/(public)/courses/page.tsx, app/(public)/case-studies/page.tsx, and app/(public)/practice/page.tsx.
• 2026-02-11: Shared card typography normalized in components/CourseCard.tsx.
• 2026-02-11: Strong discovery refresh shipped with denser hero bands, compact metadata surfaces, and clearer scan hierarchy on /courses, /case-studies, and /practice.
• 2026-02-11: Phase 3 update shipped for /courses/[slug] and /courses/[slug]/learn with clearer learning outcomes, structure preview, lesson context strip, and guided next-lesson progression.
• 2026-02-11: Demo auth persistence aligned across student pages by reading fallback cookies where Supabase is unavailable.
• 2026-02-11: Phase 4 shipped for /practice/[slug] with explicit pre-quiz briefing, cleaner in-quiz state, and results actions with persistent attempt history.
• 2026-02-11: Phase 5 completed with focus-visible accessibility baseline, hit-target reinforcement for primary/secondary buttons, and consistency pass on /, /case-studies/[slug], and /assistant.

Success Criteria

• Visual balance: no oversized heading blocks outside hero contexts.
• Density: key pages show actionable content above fold without clutter.
• Consistency: chips, cards, spacing, and metadata presentation are unified.
• Student flow: discovery -> course -> lesson -> completion feels continuous.
• QA: no major accessibility regressions; mobile parity achieved.

Risks and Mitigation

• Risk: Over-designing before backend data.
  • Mitigation: keep placeholders schema-aligned and componentized.
• Risk: Inconsistent execution across routes.
  • Mitigation: enforce shared UI primitives and route checklist signoff.
• Risk: Rework after backend integration.
  • Mitigation: keep layout and data contracts decoupled.

Working Agreement

• Every UI change references this file and marks route checklist progress.
• No route is considered complete without desktop + mobile verification.
• Keep this as the source of truth for student-facing UX decisions.