# Audit Experience

> Audits the course learn experience for section coverage, sidebar rendering, layout, design token compliance, tenant isolation, accessibility, data flow, and component quality. Use when reviewing course UI code quality or diagnosing learn experience issues. Pass a course slug or "all".

- Skill: `joshuashepherd/audit-experience` (Agent Skill)
- Install (CLI): `npx skillmds add joshuashepherd/audit-experience`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/audit-experience/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend, Security, Accessibility
- Tags: Accessibility, Component Quality, Course Ui, Data Flow, Design Tokens, Learn Experience, React, Tenant Isolation
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/joshuashepherd/audit-experience

---


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 `{{COURSE_SECTIONS_DIR}}/SectionContent.tsx` — the section router
2. Read `src/lib/config/lesson-types.ts` — canonical types, labels, icons
3. Read `{{SCHEMAS_DIR}}/course-learn.ts` — SECTION_TYPES
4. Read `{{COURSE_COMPONENTS_DIR}}/learn/CourseLearnLayout.tsx` — layout structure
5. Read `{{COURSE_COMPONENTS_DIR}}/learn/CourseLearnSidebar.tsx` — sidebar
6. Read `{{COURSE_COMPONENTS_DIR}}/learn/LessonPanel.tsx` — lesson wrapper
7. Read `{{COURSE_COMPONENTS_DIR}}/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\)" {{COURSE_COMPONENTS_DIR}}/
grep -r "#[0-9a-fA-F]\{3,6\}" {{COURSE_COMPONENTS_DIR}}/
grep -r "rgb\|rgba" {{COURSE_COMPONENTS_DIR}}/
```

### 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., `brand.features.chat` for Formation Companion)
- [ ] Uses `brandConfig` or `useBrand()` 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`