# Course Audit

> Audit the course learn experience — checks section components, sidebar rendering, progress tracking, responsiveness, design tokens, and accessibility. Use before shipping a course.

- Skill: `joshuashepherd/course-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joshuashepherd/course-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/course-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/joshuashepherd/course-audit

---


Audit the course learn experience: $ARGUMENTS

$ARGUMENTS should be a course slug or "all" for the full learn system. If empty, audit the shared learn infrastructure.

## Before Starting

1. Read `src/components/courses/sections/SectionContent.tsx` — the section router
2. Read `src/lib/config/lesson-types.ts` — canonical types, labels, icons
3. Read `src/lib/schemas/course-learn.ts` — SECTION_TYPES
4. Read `src/components/courses/learn/CourseLearnLayout.tsx` — layout structure
5. Read `src/components/courses/learn/CourseLearnSidebar.tsx` — sidebar
6. Read `src/components/courses/learn/LessonPanel.tsx` — lesson wrapper
7. Read `src/components/courses/learn/LessonContent.tsx` — content dispatcher

## Audit Checks

### 1. SECTION COMPONENT COVERAGE

For every type in SECTION_TYPES, verify a component exists:

- [ ] Grep `SectionContent.tsx` for each section_type case
- [ ] Verify the import exists and the component file is present
- [ ] Check the fallback case (should be ReadingSection)
- [ ] Flag any SECTION_TYPES that have no dedicated component

If auditing a specific course, also check:
- [ ] All section_types used in the course data have matching components
- [ ] No unknown types in the course data

### 2. SIDEBAR RENDERING

- [ ] All lesson types have entries in LESSON_TYPE_LABELS (no raw keys shown)
- [ ] All lesson types have entries in LESSON_TYPE_ICONS (no missing icons)
- [ ] Week grouping renders correctly (weeks numbered 1-8)
- [ ] Section count per week is displayed
- [ ] Progress indicators work (completed badge, percentage)
- [ ] Active section is highlighted
- [ ] Mobile drawer opens/closes correctly (check responsive logic)

### 3. LEARN LAYOUT

- [ ] Desktop: Sidebar (280px) + flex-1 main content
- [ ] Mobile: Drawer sidebar with backdrop
- [ ] Sticky sidebar with correct height calc (`calc(100vh - var(--header-height))`)
- [ ] Content max-width: `max-w-[var(--measure,65ch)]`
- [ ] Prev/next navigation works across week boundaries
- [ ] URL deep linking: `?week=N&section=slug` params handled
- [ ] Keyboard: Escape closes mobile sidebar

### 4. DESIGN TOKEN COMPLIANCE

Scan all course components for violations:

- [ ] No hardcoded colors (`bg-blue-*`, `text-gray-*`, hex values, rgb())
- [ ] All colors use semantic tokens (`bg-primary`, `text-muted-foreground`, `border-border`)
- [ ] No hardcoded font sizes (use Tailwind scale)
- [ ] No hardcoded spacing (use Tailwind/CSS variable scale)
- [ ] `course-content-html` class used on all dangerouslySetInnerHTML containers
- [ ] Dark mode works (no light-only styles)

Search patterns:
```
# Hardcoded colors (should find zero)
grep -r "bg-\(red\|blue\|green\|yellow\|gray\|slate\|zinc\|neutral\|stone\)" src/components/courses/
grep -r "#[0-9a-fA-F]\{3,6\}" src/components/courses/
grep -r "rgb\|rgba" src/components/courses/
```

### 5. TENANT ISOLATION

- [ ] No hardcoded tenant-specific strings in course components
- [ ] Course titles/descriptions come from data, not hardcoded
- [ ] Feature flags checked where applicable (e.g., `tenant.features.chat` for Formation Companion)
- [ ] Uses `tenantConfig` or `useTenant()` for any tenant-varying text

### 6. ACCESSIBILITY

- [ ] All interactive elements have visible focus states
- [ ] ARIA labels on icon-only buttons (sidebar collapse, prev/next)
- [ ] Heading hierarchy: H1 (course title) → H2 (section title) → H3+ (content headings)
- [ ] Tab order is logical (sidebar → main content → navigation)
- [ ] Screen reader: section type announced (via labels, not just icons)
- [ ] Tap targets minimum 44x44px (sidebar items, navigation buttons)
- [ ] `prefers-reduced-motion` respected on any animations
- [ ] Video sections: captions/transcript available (or flagged as needed)

### 7. DATA FLOW & HOOKS

- [ ] No raw `fetch()` calls — all data via React Query hooks
- [ ] Error states handled (course not found, section not found)
- [ ] Loading states shown (skeleton or spinner)
- [ ] Empty states handled (no sections in a week, no content in a section)
- [ ] Progress mutations use optimistic updates (or at minimum, invalidate correctly)

### 8. SECTION COMPONENT QUALITY (spot check 3-4 sections)

For each section component checked:
- [ ] Props: `{ section: CourseSection }` — correct type
- [ ] HTML content: rendered via `dangerouslySetInnerHTML` with `course-content-html` class
- [ ] Child items: maps reflection_questions/discussion_prompts/exercises arrays correctly
- [ ] Local state: managed with useState, not leaking to parent
- [ ] shadcn/ui: uses Card, Button, Textarea etc. — not raw HTML
- [ ] No console.log or debug code

## Output Format

```
## Course Learn Audit: [slug or "Infrastructure"]

### Overall: X/8 checks passing

### 1. Section Coverage: ✅/❌
- Covered: [N] / [total SECTION_TYPES]
- Missing components: [list]
- Unused components: [list]

### 2. Sidebar: ✅/❌
- [details]

### 3. Layout: ✅/❌
- [details]

### 4. Design Tokens: ✅/❌
- Violations found: [N]
- [file:line — violation description]

### 5. Tenant Isolation: ✅/❌
- [details]

### 6. Accessibility: ✅/❌
- [details]

### 7. Data Flow: ✅/❌
- [details]

### 8. Component Quality: ✅/❌
- Spot-checked: [component names]
- [details]

### Priority Fixes
1. [HIGH] — [description] — [file:line]
2. [MEDIUM] — [description] — [file:line]
3. [LOW] — [description] — [file:line]
```

## Rules

- 8 weeks, numbered 1-8. No Week 0.
- Read actual code — don't assume based on file names
- Use Grep and Glob for systematic scans, not manual file-by-file
- Be specific: report file paths and line numbers for every issue
- Distinguish between issues in shared infrastructure vs. course-specific content
- This audit is about the learn experience UX/code quality — for Charter/content validation use `/course-validate`