# 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.