# Course UX

> Audits and improves course player UX against LMS best practices, covering layout proportions, progressive disclosure, progress psychology, sidebar hierarchy, video sizing, light/dark harmony, sidebar naming, cohort pacing, and AI integration points.

- Skill: `joshuashepherd/course-ux` (Agent Skill)
- Install (CLI): `npx skillmds add joshuashepherd/course-ux`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/course-ux/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning, User Research
- Tags: Course Player, Light Dark Mode, Lms, Progressive Disclosure, Sidebar, Ux Audit, Video Player
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/joshuashepherd/course-ux

---


Audit 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 dimension
- `fix 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:

1. `src/components/courses/learn/CourseLearnLayout.tsx` — layout structure (sidebar + content proportions)
2. `src/components/courses/learn/CourseLearnSidebar.tsx` — sidebar navigation, week grouping, progress display
3. `src/components/courses/learn/CourseTopbar.tsx` — progress bar, next section nav
4. `src/components/courses/learn/LessonPanel.tsx` — lesson content wrapper
5. `src/components/courses/learn/LessonContent.tsx` — content dispatcher
6. `src/components/courses/learn/LessonTabs.tsx` — tabbed content (overview, transcript, resources)
7. `src/components/courses/learn/LessonPanelFooter.tsx` — prev/next navigation
8. `src/components/courses/sections/VideoSection.tsx` — video section rendering
9. `src/components/content/VideoPlayer.tsx` — video player component
10. `src/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-1` or 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-6` AND content area adds `p-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-primary` not 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-video` or 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-card` not `bg-background` for 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:

1. **Watch the Introduction** — weekly video intro
2. **Begin the Conversation** — AI Interaction 1: Dissonance conversation (~10 min). Provokes curiosity, introduces tension.
3. **Explore the Week's Content** — teaching content (video, reading, articles). Flexible per week.
4. **Discern Your Next Step** — AI Interaction 2: Discernment conversation (~10 min). Connects content to a concrete micro-practice.
5. **Reflect on the Week** — AI Interaction 3: Reflection (~10 min). Processes insights, integrates learning.
6. **Meet with Your Cohort** — synchronous cohort gathering.
7. **Close Out the Week** — exit ticket / closing activity.

**Week 1 variant (onboarding):**

1. Watch the Introduction
2. Get Oriented
3. Introduce Yourself
4. Begin the Conversation
5. 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):**
1. Visually de-emphasize future weeks (muted text, reduced opacity)
2. Collapse future weeks with no expand affordance (or expand shows "Available [date]")
3. Accordion with future weeks locked (click shows "Opens with your cohort on [date]")
4. 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`:

1. Run the audit first — present findings to user
2. For each fix:
   - Show the specific file and current code
   - Explain what changes and why (reference LMS best practice)
   - Apply the edit
3. After all fixes, re-audit the affected dimension to confirm resolution
4. 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