Services

Academy Audit Normalize Polish Distill

Academy audit / normalize / polish / distill

Scope#

Reviewed the current apps/academy UI conventions and the text-first academy additions:

  • apps/academy/app/(protected)/instructor/academy/page.tsx
  • apps/academy/components/authoring/text-lecture-authoring.tsx
  • apps/academy/components/learning/lecture-learning-mode.tsx
  • apps/academy/components/learning/slide-deck-viewer.tsx
  • apps/academy/lib/authoring/*

Existing conventions to preserve#

  • Academy pages use max-w-[var(--learn-page-max-width)], text-foreground*, bg-surface-*, border-border/*, and brand-* tokens rather than raw colors.
  • Interactive elements commonly include transition-colors, hover:*, and focus-visible:ring-* states, e.g. dashboard cards and course hero CTAs.
  • Protected pages are wrapped by apps/academy/app/(protected)/layout.tsx; route pages should not add an extra <main> because the layout already owns that landmark.
  • Course pages favor clear sections, concise upper-label metadata, and rounded surface panels.

Findings#

P1 — Normalize interaction states on new controls#

  • apps/academy/components/authoring/text-lecture-authoring.tsx buttons and inputs have minimal hover/focus/disabled affordances compared with existing Academy controls.
  • apps/academy/components/learning/slide-deck-viewer.tsx previous/next buttons only expose disabled:opacity-50; add focus-visible rings, hover states, and cursor affordance.

P1 — Distill the instructor page hierarchy#

  • apps/academy/app/(protected)/instructor/academy/page.tsx currently shows a stats strip plus three separate cards after the authoring grid. This creates many equal-weight containers and no single next step.
  • Keep the essential story: course/module/status → author lecture → preview slides → attach test/lab/live session. Compress supporting status cards into a compact checklist or summary.

P1 — Avoid client/server barrel footguns#

  • apps/academy/lib/authoring/bigbluebutton.ts imports Node crypto. Keep it out of the generic @/lib/authoring client-facing barrel so client components do not accidentally pull server-only code.
  • Import BBB helpers directly only from server components or server-only modules.

P2 — Improve slide/text learner empty states#

  • apps/academy/components/learning/lecture-learning-mode.tsx and slide-deck-viewer.tsx return null when no slide exists. Provide a small empty state so authors/learners understand what happened.

P2 — Copy can be shorter and more consistent#

  • Current phrases like “Progress sync: slide …” and “Write Markdown now; generated slides stay editable” are accurate but mechanical.
  • Prefer user-facing copy: “Slide 1 of 4”, “Write once. Preview as slides.”, “Publish draft”.

P2 — Reduce duplicated slide preview/list styling#

  • Authoring slide preview and learner slide viewer both render slide title/content with separate markup. Keep separate components for editing vs viewing, but normalize spacing, line-height, and empty content treatment.
  1. Normalize components: shared button/input class constants or local helpers, focus states, client-safe barrel exports.
  2. Polish visual details: consistent section spacing, compact status labels, empty states.
  3. Distill instructor flow: replace bottom three cards with a focused readiness checklist and one primary action.
  4. Verify with focused ESLint, authoring Vitest tests, and a narrow TypeScript check for pure authoring modules.