geist-learning-lab

Geist Learning Lab

Build interactive learning experiences that teach by making the learner do something, get feedback, and iterate — using Geist's dark-first, minimal, precise UI language.

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)

Every lesson repeats this cycle:

"Aha Moment" Design Patterns

Quick Color Reference (Learning Semantics)

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

Layout Patterns

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