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
- 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 patternsreferences/explorable-explanations.md — ParameterDock, LiveOutputPanel, ConceptExplorer, InteractiveDiagram, BeforeAfterSplit, TimelineExplorer, ConceptMapreferences/code-learning.md — CodePlayground (read-only/guided/free), DiffEditor, TaskRunner, SnippetCopyreferences/quiz-assessment.md — QuickCheck, ConfidenceRating, HintLadder, MistakeAnalyzer with feedback patternsreferences/reading-support.md — GlossaryPopover, Callout variants, WorkedExample with stepwise revealreferences/pedagogical-framework.md — The Learning Loop doctrine, progressive disclosure rules, aha patterns, scaffolded complexityreferences/architecture.md — Next.js App Router routing, MDX content system, state management, file organizationreferences/progress-state.md — Progress schema, localStorage adapter, spaced repetition, URL state for explorationsreferences/learning-animations.md — Step transitions, feedback reveals, diagram animations, reduced-motion compliance
1---2name: geist-learning-lab3description: Build explorative, interactive learning experiences as Next.js apps using the Geist design system. Use when creating tutorials, explorable explanations, interactive lessons, code sandboxes, quizzes, or any educational UI. Covers the Learning Loop pedagogy, 23+ learning component patterns, progress tracking, spaced repetition, and Bret-Victor-style interactive exploration — all with Geist's dark-first minimal aesthetic.4---56# Geist Learning Lab78Build interactive learning experiences that teach by making the learner *do something, get feedback, and iterate* — using Geist's dark-first, minimal, precise UI language.910## Design Philosophy1112- **Learning loops, not pages** — Every screen completes: prompt → attempt → feedback → refinement → checkpoint13- **Cognitive load management** — Progressive disclosure, chunking, one concept + one action at a time14- **Error-friendly design** — Mistakes are expected; the UI normalizes them and turns them into learning moments15- **Interactive representations** — Sliders, toggles, diagrams, live code — not just text16- **Geist precision** — Dark backgrounds, tight tracking, semantic color, 4px grid, Swiss typography1718## Critical Rules19201. **Every lesson must include at least one attempt+feedback loop** — No passive-only pages212. **Every interactive control must have a visible effect** — Within ~100ms or show loading state223. **Progress/review must exist even in a prototype** — Track steps completed, checkpoints passed234. **Active attempt before explanation** — Ask a question or show a task, then explain245. **Immediate, specific feedback** — "Correct" isn't enough; explain *why*256. **Multiple representations** — Always at least 2 of: text, code, visual, interactive, real data267. **Color is learning signal** — Green=correct, Red=incorrect, Amber=hint/warning, Blue=info/definition278. **Progressive disclosure by default** — Depth behind "Why?", "Edge Cases", "Formal Definition"289. **URL state for exploration** — Shareable slider/toggle configurations via search params2910. **Misconception-first design** — Bake in common traps: "Most people get this wrong because..."3031## The Learning Loop (Central Doctrine)3233Every lesson repeats this cycle:3435| Step | What Happens | Component |36|------|-------------|-----------|37| **Orient** | What you'll learn in 5-10 min | Heading + learning objective |38| **Attempt** | Learner predicts/answers/edits first | QuickCheck, CodePlayground, ParameterDock |39| **Feedback** | Immediate + specific response | Feedback surface (green/red panel) |40| **Explain** | Short explanation anchored to their attempt | Callout, WorkedExample |41| **Extend** | Variation, edge case, or transfer task | BeforeAfterSplit, ConceptExplorer |42| **Checkpoint** | Quick recall question | QuickCheck with ConfidenceRating |43| **Reflect** | "What changed in your understanding?" | Optional text input or self-rating |4445## "Aha Moment" Design Patterns4647| Pattern | How It Works | When to Use |48|---------|-------------|-------------|49| **Prediction Gap** | "What do you think happens if...?" then reveal | Before introducing a concept |50| **Contrast Pair** | Two near-identical cases with different outcomes | Clarifying subtle distinctions |51| **Slider to Failure** | Let learner push a parameter until it breaks | Understanding boundaries/limits |52| **Time Travel** | Scrub algorithm step-by-step, watch invariants | Algorithms, state machines |53| **Misconception Trap** | Tempting wrong option, then explain why wrong | Common errors in a domain |5455## Quick Color Reference (Learning Semantics)5657| Signal | Color Token | Hex | Usage |58|--------|------------|-----|-------|59| Correct | green-700 | `#46A758` | Success feedback, completed steps |60| Incorrect | red-700 | `#E5484D` | Error feedback, failed checks |61| Hint/Caution | amber-700 | `#FFB224` | Hints, warnings, "watch out" |62| Info/Definition | blue-700 | `#0070F3` | Definitions, current step, links |63| Default | gray-400 | `#737373` | Everything else: borders, muted text |64| Progress done | green-700 dot | `#46A758` | Completed step indicator |65| Progress current | blue-700 ring | `#0070F3` | Current step focus state |66| Progress pending | gray-400 dot | `#737373` | Upcoming steps |6768## Component Library (23 Patterns)6970### Lesson Flow & Progress71`<LessonShell />` `<ProgressRail />` `<StepFlow />` `<CheckpointCard />` `<ResumeBanner />`7273### Explorable Explanations74`<ParameterDock />` `<LiveOutputPanel />` `<ConceptExplorer />` `<InteractiveDiagram />` `<BeforeAfterSplit />` `<TimelineExplorer />` `<ConceptMap />`7576### Code Learning77`<CodePlayground />` `<DiffEditor />` `<TaskRunner />` `<SnippetCopy />`7879### Quizzes & Active Recall80`<QuickCheck />` `<ConfidenceRating />` `<HintLadder />` `<MistakeAnalyzer />`8182### Reading Support83`<GlossaryPopover />` `<Callout />` `<WorkedExample />`8485## Typography in Learning Context8687| Element | What It Means | Style |88|---------|--------------|-------|89| Big heading | "What you're doing" | `text-heading-{32\|24}` semibold, negative tracking |90| Small label | "Where you are" | `text-label-{14\|12}` gray-400 |91| Mono | "What the computer sees" | `text-copy-14-mono` or `text-label-14-mono` |92| Body | Reading content | `text-copy-14` or `text-copy-16`, max-w-2xl |9394## Layout Patterns9596| Context | Max Width | Structure |97|---------|-----------|-----------|98| Reading content | `max-w-2xl` / `max-w-4xl` | Single column, comfortable line length |99| Interactive lab | `max-w-6xl` | Two panels: explanation + playground |100| Full explorer | `max-w-7xl` | Three zones: nav + content + lab panel |101102## App Router Structure103104```105/ → Landing / course picker106/learn → Course catalog + resume107/learn/[courseSlug] → Course overview, modules, progress108/learn/[courseSlug]/[moduleSlug] → Module overview109/learn/[courseSlug]/[moduleSlug]/[lessonSlug] → Lesson shell110```111112## File Organization113114```115content/courses/<courseSlug>/course.json → Metadata, module order116content/courses/<courseSlug>/<module>/<lesson>.mdx → Lesson content117components/learning/ → Reusable learning components118lib/learning/progress.ts → Schema + storage adapters119lib/learning/grading.ts → Quiz validation, code tests120lib/learning/spaced.ts → Review scheduling121```122123## References124125- `references/lesson-shell.md` — LessonShell, ProgressRail, StepFlow, CheckpointCard, ResumeBanner TSX patterns126- `references/explorable-explanations.md` — ParameterDock, LiveOutputPanel, ConceptExplorer, InteractiveDiagram, BeforeAfterSplit, TimelineExplorer, ConceptMap127- `references/code-learning.md` — CodePlayground (read-only/guided/free), DiffEditor, TaskRunner, SnippetCopy128- `references/quiz-assessment.md` — QuickCheck, ConfidenceRating, HintLadder, MistakeAnalyzer with feedback patterns129- `references/reading-support.md` — GlossaryPopover, Callout variants, WorkedExample with stepwise reveal130- `references/pedagogical-framework.md` — The Learning Loop doctrine, progressive disclosure rules, aha patterns, scaffolded complexity131- `references/architecture.md` — Next.js App Router routing, MDX content system, state management, file organization132- `references/progress-state.md` — Progress schema, localStorage adapter, spaced repetition, URL state for explorations133- `references/learning-animations.md` — Step transitions, feedback reveals, diagram animations, reduced-motion compliance
Vercel Labs