Geist Learning Lab

Design Philosophy

• Learning loops, not pages — Every screen completes: prompt → attempt → feedback → refinement → checkpoint
• Cognitive load management — Progressive disclosure, chunking, one concept + one action at a time
• Error-friendly design — Mistakes are expected; the UI normalizes them and turns them into learning moments
• Interactive representations — Sliders, toggles, diagrams, live code — not just text
• Geist precision — Dark backgrounds, tight tracking, semantic color, 4px grid, Swiss typography

Critical Rules

1. Every lesson must include at least one attempt+feedback loop — No passive-only pages
2. Every interactive control must have a visible effect — Within ~100ms or show loading state
3. Progress/review must exist even in a prototype — Track steps completed, checkpoints passed
4. Active attempt before explanation — Ask a question or show a task, then explain
5. Immediate, specific feedback — "Correct" isn't enough; explain why
6. Multiple representations — Always at least 2 of: text, code, visual, interactive, real data
7. Color is learning signal — Green=correct, Red=incorrect, Amber=hint/warning, Blue=info/definition
8. Progressive disclosure by default — Depth behind "Why?", "Edge Cases", "Formal Definition"
9. URL state for exploration — Shareable slider/toggle configurations via search params
10. Misconception-first design — Bake in common traps: "Most people get this wrong because..."

The Learning Loop (Central Doctrine)

"Aha Moment" Design Patterns

Quick Color Reference (Learning Semantics)

#46A758

#E5484D

#FFB224

#0070F3

#737373

#46A758

#0070F3

#737373

Component Library (23 Patterns)

Lesson Flow & Progress

<LessonShell />

<ProgressRail />

<StepFlow />

<CheckpointCard />

<ResumeBanner />

Explorable Explanations

<ParameterDock />

<LiveOutputPanel />

<ConceptExplorer />

<InteractiveDiagram />

<BeforeAfterSplit />

<TimelineExplorer />

<ConceptMap />

Code Learning

<CodePlayground />

<DiffEditor />

<TaskRunner />

<SnippetCopy />

Quizzes & Active Recall

<QuickCheck />

<ConfidenceRating />

<HintLadder />

<MistakeAnalyzer />

Reading Support

<GlossaryPopover />

<Callout />

<WorkedExample />

Typography in Learning Context

text-heading-{32|24}

text-label-{14|12}

text-copy-14-mono

text-label-14-mono

text-copy-14

text-copy-16

Layout Patterns

max-w-2xl

max-w-4xl

max-w-6xl

max-w-7xl

App Router Structure

/                                    → Landing / course picker
/learn                               → Course catalog + resume
/learn/[courseSlug]                   → Course overview, modules, progress
/learn/[courseSlug]/[moduleSlug]      → Module overview
/learn/[courseSlug]/[moduleSlug]/[lessonSlug]  → Lesson shell

File Organization

content/courses/<courseSlug>/course.json       → Metadata, module order
content/courses/<courseSlug>/<module>/<lesson>.mdx  → Lesson content
components/learning/                           → Reusable learning components
lib/learning/progress.ts                       → Schema + storage adapters
lib/learning/grading.ts                        → Quiz validation, code tests
lib/learning/spaced.ts                         → Review scheduling

References

• references/lesson-shell.md

  — LessonShell, ProgressRail, StepFlow, CheckpointCard, ResumeBanner TSX patterns

• references/explorable-explanations.md

  — ParameterDock, LiveOutputPanel, ConceptExplorer, InteractiveDiagram, BeforeAfterSplit, TimelineExplorer, ConceptMap

• references/code-learning.md

  — CodePlayground (read-only/guided/free), DiffEditor, TaskRunner, SnippetCopy

• references/quiz-assessment.md

  — QuickCheck, ConfidenceRating, HintLadder, MistakeAnalyzer with feedback patterns

• references/reading-support.md

  — GlossaryPopover, Callout variants, WorkedExample with stepwise reveal

• references/pedagogical-framework.md

  — The Learning Loop doctrine, progressive disclosure rules, aha patterns, scaffolded complexity

• references/architecture.md

  — Next.js App Router routing, MDX content system, state management, file organization

• references/progress-state.md

  — Progress schema, localStorage adapter, spaced repetition, URL state for explorations

• references/learning-animations.md

  — Step transitions, feedback reveals, diagram animations, reduced-motion compliance