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

• Every lesson must include at least one attempt+feedback loop — No passive-only pages
• Every interactive control must have a visible effect — Within ~100ms or show loading state
• Progress/review must exist even in a prototype — Track steps completed, checkpoints passed
• Active attempt before explanation — Ask a question or show a task, then explain
• Immediate, specific feedback — "Correct" isn't enough; explain *why*
• Multiple representations — Always at least 2 of: text, code, visual, interactive, real data
• Color is learning signal — Green=correct, Red=incorrect, Amber=hint/warning, Blue=info/definition
• Progressive disclosure by default — Depth behind "Why?", "Edge Cases", "Formal Definition"
• 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:

| Step | What Happens | Component |

|------|-------------|-----------|

| Orient | What you'll learn in 5-10 min | Heading + learning objective |

| Attempt | Learner predicts/answers/edits first | QuickCheck, CodePlayground, ParameterDock |

| Feedback | Immediate + specific response | Feedback surface (green/red panel) |

| Explain | Short explanation anchored to their attempt | Callout, WorkedExample |

| Extend | Variation, edge case, or transfer task | BeforeAfterSplit, ConceptExplorer |

| Checkpoint | Quick recall question | QuickCheck with ConfidenceRating |

| Reflect | "What changed in your understanding?" | Optional text input or self-rating |

"Aha Moment" Design Patterns

| Pattern | How It Works | When to Use |

|---------|-------------|-------------|

| Prediction Gap | "What do you think happens if...?" then reveal | Before introducing a concept |

| Contrast Pair | Two near-identical cases with different outcomes | Clarifying subtle distinctions |

| Slider to Failure | Let learner push a parameter until it breaks | Understanding boundaries/limits |

| Time Travel | Scrub algorithm step-by-step, watch invariants | Algorithms, state machines |

| Misconception Trap | Tempting wrong option, then explain why wrong | Common errors in a domain |

Quick Color Reference (Learning Semantics)

| Signal | Color Token | Hex | Usage |

|--------|------------|-----|-------|

| Correct | green-700 | #46A758 | Success feedback, completed steps |

| Incorrect | red-700 | #E5484D | Error feedback, failed checks |

| Hint/Caution | amber-700 | #FFB224 | Hints, warnings, "watch out" |

| Info/Definition | blue-700 | #0070F3 | Definitions, current step, links |

| Default | gray-400 | #737373 | Everything else: borders, muted text |

| Progress done | green-700 dot | #46A758 | Completed step indicator |

| Progress current | blue-700 ring | #0070F3 | Current step focus state |

| Progress pending | gray-400 dot | #737373 | Upcoming steps |

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

| Element | What It Means | Style |

|---------|--------------|-------|

| Big heading | "What you're doing" | text-heading-{32\|24} semibold, negative tracking |

| Small label | "Where you are" | text-label-{14\|12} gray-400 |

| Mono | "What the computer sees" | text-copy-14-mono or text-label-14-mono |

| Body | Reading content | text-copy-14 or text-copy-16, max-w-2xl |

Layout Patterns

| Context | Max Width | Structure |

|---------|-----------|-----------|

| Reading content | max-w-2xl / max-w-4xl | Single column, comfortable line length |

| Interactive lab | max-w-6xl | Two panels: explanation + playground |

| Full explorer | max-w-7xl | Three zones: nav + content + lab panel |

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