course-ux
Audit and fix course player UX against LMS best practices — layout proportions, progressive disclosure, progress psychology, sidebar hierarchy, video sizing, light/dark harmony, sidebar naming & learn
SKILL.mdclaude/content/course-ux/SKILL.md
GitHubAudit and improve the course learn experience UX: $ARGUMENTS
$ARGUMENTS can be:
audit— Full UX audit, report only (no changes)audit [dimension]— Audit a single dimension (e.g.,audit proportions)fix [dimension]— Audit + apply fixes for a dimensionfix all— Audit + apply all fixes (confirm with user before each change)- Empty — defaults to
audit
Before Starting
Read these files to understand the current state:
src/components/courses/learn/CourseLearnLayout.tsx— layout structure (sidebar + content proportions)src/components/courses/learn/CourseLearnSidebar.tsx— sidebar navigation, week grouping, progress displaysrc/components/courses/learn/CourseTopbar.tsx— progress bar, next section navsrc/components/courses/learn/LessonPanel.tsx— lesson content wrappersrc/components/courses/learn/LessonContent.tsx— content dispatchersrc/components/courses/learn/LessonTabs.tsx— tabbed content (overview, transcript, resources)src/components/courses/learn/LessonPanelFooter.tsx— prev/next navigationsrc/components/courses/sections/VideoSection.tsx— video section renderingsrc/components/content/VideoPlayer.tsx— video player componentsrc/app/globals.css— CSS variables, light/dark mode tokens
Also read the course overview page if auditing course entry:
src/app/(public)/content/courses/[slug]/learn/page.tsx
Audit Dimensions
1. CONTENT AREA PROPORTIONS
Best practice: Video and primary content should occupy 70-75% of viewport width on desktop. Sidebar should be 25-30%.
Check:
- Sidebar width is 240-300px fixed (not percentage-based)
- Content area uses
flex-1or equivalent to fill remaining space - Video player stretches to full content-area width (no unnecessary padding/margins)
- On tablet (768-1024px), sidebar collapses to drawer — content goes full-width
- Reading content has a max-width constraint (65-75ch) but video does NOT
- No double-padding (layout padding + content padding stacking)
Common violations:
- Content area too narrow because sidebar is too wide
- Video constrained by a
max-w-*meant for text content - Padding stacking: layout adds
p-6AND content area addsp-6
2. PROGRESSIVE DISCLOSURE
Best practice: Show learners only what they need now. Hide future complexity. "Bird by bird" — Anne Lamott principle applied to LMS.
Check:
- Total section count is NOT prominently displayed (no "0 of 69 sections")
- Progress shows week-level granularity: "Week 1 of 8" not "Section 3 of 69"
- Current week is expanded in sidebar; future weeks are collapsed by default
- Past weeks show completion state but are collapsed
- Only current + next section are emphasized in navigation
- Course overview does not overwhelm with full 8-week breakdown on first visit
Best-in-class pattern (Coursera/Thinkific):
- Sidebar: current week expanded, all others collapsed
- Progress: "Week N" with a small ring/bar, not raw fraction
- Topbar: "Next: [section name]" — single forward action
Violations to flag:
- Raw "0 / 69" displayed anywhere
- All weeks expanded simultaneously
- Section-level counting exposed to user
- Full course outline visible without interaction
3. PROGRESS BAR & MOTIVATION
Best practice: Progress UI should encourage, not overwhelm. Show momentum, not distance remaining.
Check:
- Progress indicator shows percentage OR visual fill — not raw fraction
- Week-level progress preferred over course-level on the topbar
- No "0%" displayed on first visit (use "Just getting started" or hide until >0)
- Progress bar has sufficient visual weight (not a tiny 2px line)
- Completion celebrations exist (checkmark, color change, subtle animation)
- Progress ring/bar uses
bg-primarynot hardcoded colors - Topbar progress does not compete visually with main content
Kajabi pattern: percentage badge + thin progress bar, warm color fill Thinkific pattern: circular progress ring per module, checkmarks on completion
4. SIDEBAR HIERARCHY & BALANCE
Best practice: Sidebar should feel like a table of contents, not a wall of text. Visual weight draws the eye to "where you are now."
Check:
- Active section has strong visual indicator (background highlight + left border or accent)
- Inactive sections are visually recessed (muted text, no background)
- Week headers are visually distinct from section items (bolder, larger, or different style)
- Completed sections show a subtle checkmark or muted state
- Section type icons are present and consistent (video icon, reading icon, etc.)
- Sidebar has its own scroll independent of main content (sticky with overflow-y-auto)
- Vertical spacing between items is consistent (not cramped, not too loose)
- Sidebar header area (course title, overall progress) does not take excessive vertical space
Visual weight check:
- Course title/progress area: ~15% of sidebar height
- Navigation items: ~85% of sidebar height
- No large empty gaps or unbalanced whitespace
5. VIDEO PLAYER SIZING
Best practice: Video is the primary content type in most LMS sections. It should be the hero element, not squeezed.
Check:
- Video player fills full content-area width (minus reasonable padding: 16-24px each side)
- Video maintains 16:9 aspect ratio via
aspect-videoor equivalent - No max-width constraint narrower than the content area on video
- Video section has minimal chrome above/below — section title, then video, then transcript
- Transcript accordion/dropdown sits directly below video, same width
- No duplicate transcript rendering (both accordion AND tab)
- "Video coming soon" placeholder is styled and sized to match video dimensions
6. TRANSCRIPT & SUPPLEMENTARY CONTENT
Best practice: Transcript should be accessible but not compete with video. Single rendering, clear hierarchy.
Check:
- Transcript appears in ONE location only (either tabs OR accordion — not both)
- If using tabs: "Overview" is default tab, "Transcript" is secondary
- If using accordion: collapsed by default, below video
- Transcript text has readable typography (16px+, good line-height, max-width ~75ch)
- Resources tab/section exists if the lesson has resources
- Tabs/accordion use same width as the video player (visual alignment)
Preferred pattern: Tabs below video (Overview | Transcript | Resources)
- This is the pattern used by Coursera, Udemy, and most modern LMS platforms
7. LIGHT/DARK MODE HARMONY
Best practice: Both modes must feel intentional, not like one is an afterthought.
Check:
- Scan all course learn components for color token usage
- No hardcoded colors (grep for hex, rgb,
bg-{color}-{shade}) - Background layers create clear depth separation:
- Dark: sidebar slightly lighter than main bg, or subtle border separation
- Light: sidebar slightly tinted or bordered, not flat white-on-white
- Text contrast meets WCAG AA in BOTH modes
- Interactive elements (buttons, links, active states) are visible in both modes
- Video player area has neutral dark background in both modes (video always looks best on dark)
- Progress indicators have sufficient contrast in light mode
- Card/surface backgrounds use
bg-cardnotbg-backgroundfor elevated elements
Light mode specific checks:
- Primary accent color is not too dark/heavy for light backgrounds
- Sidebar does not feel washed out or invisible
- Borders/dividers provide structure without heaviness
8. SPACING & VERTICAL RHYTHM
Best practice: Consistent spacing creates visual calm. Inconsistent spacing creates unease.
Check:
- Topbar height is consistent and not cramped (48-56px)
- Gap between topbar and content is intentional (16-24px)
- Section title to content gap is consistent across section types
- Sidebar item padding is uniform (12-16px vertical, 16-20px horizontal)
- Content area has symmetric horizontal padding
- Footer navigation (prev/next) has clear separation from content above
- No spacing jumps between different section types
- Typography margins follow a consistent scale (use Tailwind spacing)
Scan for spacing antipatterns:
- Arbitrary values:
p-[13px],mt-[7px],gap-[11px] - Inconsistent padding between similar elements
- Missing gap between video and transcript
- Topbar content not vertically centered
9. CONTEXT DISCOVERY FLOW
Best practice: Onboarding should be structured (form), not open-ended (chat). Reduce cognitive load at course entry.
Check:
- Context Discovery section uses a structured form, not a chat interface
- Form is <=10 minutes estimated completion time
- Form collects: learner background, goals, experience level, context
- Form exists as a reusable component (shared with AI Lab intro if applicable)
- After form completion, transitions to lesson content — not more questions
- If chat IS used, it's positioned AFTER form completion, not as the entry point
Components to check:
- Any ContextDiscovery* or Intake* components in
src/components/courses/ - The section type mapping for context_discovery in SectionContent.tsx
10. AI INTEGRATION POINTS
Best practice: AI assistance should be contextually relevant, not omnipresent. It should enhance learning, not distract from it.
Check:
- AI Lab drawer/button is present but non-intrusive (bottom-right FAB or sidebar icon)
- AI drawer is contextually aware of current lesson (passes lesson context)
- AI is NOT auto-opened or auto-prompted on lesson load
- During video playback, AI button does not overlay video controls
- AI availability respects feature flags (
tenant.features.chat) - Consider: should AI be hidden during certain section types (e.g., reflection, journaling)?
11. SIDEBAR NAMING & LEARNING FLOW
Best practice: Sidebar titles should guide learner action, not describe content. The sidebar answers "What should I do next?" — not "What is this about?" This is the Kajabi/Teachable guided-journey pattern vs the Udemy table-of-contents pattern.
Two-title system:
- Sidebar titles = action-based CTAs (verbs). Guide learner flow. These are navigation labels.
- Content page titles = topic-based. Describe the lesson content. Editable by course creator.
- Sidebar title does NOT need to match content page title.
Check:
- Sidebar items use action/verb language, not topic nouns
- Content page titles remain subject-matter titles (unchanged by this dimension)
- Sidebar title and content title are stored/rendered independently
- No sidebar item reads like a chapter heading (e.g., "Recovering Apostolic Genius" should be "Watch the Introduction")
Standard weekly flow (Weeks 2–7):
Each week follows a consistent 7-step rhythm. Learners should recognize this pattern week to week:
- Watch the Introduction — weekly video intro
- Begin the Conversation — AI Interaction 1: Dissonance conversation (~10 min). Provokes curiosity, introduces tension.
- Explore the Week's Content — teaching content (video, reading, articles). Flexible per week.
- Discern Your Next Step — AI Interaction 2: Discernment conversation (~10 min). Connects content to a concrete micro-practice.
- Reflect on the Week — AI Interaction 3: Reflection (~10 min). Processes insights, integrates learning.
- Meet with Your Cohort — synchronous cohort gathering.
- Close Out the Week — exit ticket / closing activity.
Week 1 variant (onboarding):
- Watch the Introduction
- Get Oriented
- Introduce Yourself
- Begin the Conversation
- Close Out the Week
Week 8 variant (closing):
- May differ from Weeks 2–7. Audit should flag if Week 8 uses a non-standard flow and confirm it's intentional.
AI interaction naming rules:
- Sidebar CTAs do NOT explicitly reference "AI" — the AI is the facilitator, not the feature.
- "Begin the Conversation" not "Chat with AI about dissonance"
- "Discern Your Next Step" not "AI-guided practice selection"
Violations to flag:
- Sidebar items using topic-based language (nouns, chapter titles)
- Inconsistent flow order between weeks (e.g., reflection before content)
- AI interactions surfaced as "AI Chat" or "Talk to AI" in sidebar
- Week 1 using the standard Weeks 2–7 flow instead of onboarding flow
- Missing steps in the weekly flow
12. COHORT PACING & WEEK VISIBILITY
Best practice: Cohort-paced courses should focus the learner on the current week. Showing the full 8-week structure creates cognitive noise and undermines the guided-journey feel. Kajabi's "drip content" and Teachable's "scheduled publishing" patterns apply here.
This course is cohort-paced and facilitator-guided — learners progress together week by week and cannot jump ahead arbitrarily.
Check:
- Current week is prominently expanded in sidebar
- Future weeks are collapsed, locked, or visually de-emphasized
- Past weeks are accessible but collapsed (learners can review)
- No "browse all 8 weeks" view by default — the sidebar is not a course catalog
- Week header shows week number + title (e.g., "Week 3 — Jesus-Shaped Gospel")
- Locked/future weeks show a lock icon or muted state — not just collapsed
Acceptable implementation approaches (lightest to heaviest):
- Visually de-emphasize future weeks (muted text, reduced opacity)
- Collapse future weeks with no expand affordance (or expand shows "Available [date]")
- Accordion with future weeks locked (click shows "Opens with your cohort on [date]")
- Hide future weeks entirely from sidebar
Implementation constraint: Prefer the lightest approach that achieves focus. Do NOT introduce heavy cohort-management infrastructure for this dimension — visual treatment in the sidebar component is sufficient.
Interaction with progressive disclosure (Dimension 2):
- Dimension 2 says "current week expanded, others collapsed" — this dimension adds the why (cohort pacing) and the lock/gate behavior for future weeks specifically.
- Dimension 2 is about reducing visual noise. This dimension is about enforcing a pacing model.
Violations to flag:
- All 8 weeks visible and expandable simultaneously
- No visual distinction between current, past, and future weeks
- Future weeks fully navigable (learner can click into Week 8 content on day 1)
- No indication of cohort schedule or week availability
Output Format
## Course UX Audit: [slug or "Learn Infrastructure"]
### Overall: X/12 dimensions passing
### Summary
[2-3 sentence executive summary of the biggest UX issues]
### 1. Content Area Proportions: PASS/WARN/FAIL
- Current state: [what it is now]
- Issue: [if any]
- Fix: [specific file:line and what to change]
### 2. Progressive Disclosure: PASS/WARN/FAIL
- Current state: [what's exposed to user]
- Issue: [if any]
- Fix: [specific change]
[... repeat for all 12 dimensions ...]
### Priority Fixes (ordered by user impact)
1. [HIGH] — [description] — [file:line]
2. [HIGH] — [description] — [file:line]
3. [MEDIUM] — [description] — [file:line]
4. [LOW] — [description] — [file:line]
### Quick Wins (< 30 min each)
- [ ] [description] — [file:line]
- [ ] [description] — [file:line]
Fix Mode
When invoked with fix [dimension] or fix all:
- Run the audit first — present findings to user
- For each fix:
- Show the specific file and current code
- Explain what changes and why (reference LMS best practice)
- Apply the edit
- After all fixes, re-audit the affected dimension to confirm resolution
- Do NOT touch generated files — if a fix requires a generated file change, note it and suggest regeneration
Rules
- 8 weeks, numbered 1-8. No Week 0.
- Read actual code — do not assume from file names
- Reference specific LMS platforms (Coursera, Thinkific, Kajabi, Teachable) when citing best practices
- Every issue must include a file path and line number
- Distinguish between layout/structural issues and cosmetic polish
- Do not modify
src/components/ui/*— fix at the correct layer (layout, section, or globals.css) - Use semantic color tokens — never introduce hardcoded colors
- This skill audits UX patterns and visual harmony — for code quality use
/course-audit, for content validation use/course-validate - When fixing, prefer minimal changes that address the specific issue — do not refactor surrounding code