advance

student_experience_planish.md

@@ -0,0 +1,197 @@
+# 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.