Back to Details

geist-learning-lab

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Geist Learning Lab

Geist学习实验室

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.
通过让学习者动手实践、获取反馈、反复迭代的方式构建交互式学习体验——采用Geist深色优先、极简且精准的UI语言。

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
  • 学习循环，而非单页 — 每个界面都完整遵循：提示 → 尝试 → 反馈 → 改进 → 检查点
  • 认知负荷管理 — 渐进式披露、内容分块，一次只呈现一个概念+一个操作
  • 容错友好设计 — 错误是预期之内的；UI会将其正常化，并转化为学习契机
  • 交互式呈现 — 滑块、开关、图表、实时代码——而非仅文本
  • Geist精准性 — 深色背景、紧凑字距、语义化色彩、4px网格、瑞士风格排版

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..."
  1. 每节课必须包含至少一个尝试+反馈循环 — 不允许纯被动页面
  2. 每个交互控件必须有可见效果 — 约100ms内呈现或显示加载状态
  3. 即使是原型也必须有进度/回顾功能 — 跟踪已完成步骤、已通过的检查点
  4. 先尝试后讲解 — 先提出问题或展示任务，再进行讲解
  5. 即时、具体的反馈 — 仅“正确”是不够的；要解释为什么正确
  6. 多形式呈现 — 至少包含以下2种形式：文本、代码、可视化、交互式、真实数据
  7. 色彩作为学习信号 — 绿色=正确，红色=错误，琥珀色=提示/警告，蓝色=信息/定义
  8. 默认采用渐进式披露 — 深层内容放在“为什么？”、“边缘情况”、“正式定义”之后
  9. 探索状态与URL绑定 — 通过搜索参数实现可分享的滑块/开关配置
  10. 以常见误解为核心的设计 — 融入常见陷阱：“大多数人在这里出错是因为...”

The Learning Loop (Central Doctrine)

学习循环（核心准则）

Every lesson repeats this cycle:
StepWhat HappensComponent
OrientWhat you'll learn in 5-10 minHeading + learning objective
AttemptLearner predicts/answers/edits firstQuickCheck, CodePlayground, ParameterDock
FeedbackImmediate + specific responseFeedback surface (green/red panel)
ExplainShort explanation anchored to their attemptCallout, WorkedExample
ExtendVariation, edge case, or transfer taskBeforeAfterSplit, ConceptExplorer
CheckpointQuick recall questionQuickCheck with ConfidenceRating
Reflect"What changed in your understanding?"Optional text input or self-rating
每节课都会重复以下循环：
步骤内容组件
定位5-10分钟内你将学到的内容标题 + 学习目标
尝试学习者先进行预测/作答/编辑QuickCheck、CodePlayground、ParameterDock
反馈即时且具体的回应反馈区域（绿/红面板）
讲解结合学习者尝试的简短解释Callout、WorkedExample
拓展变体、边缘情况或迁移任务BeforeAfterSplit、ConceptExplorer
检查点快速回忆问题带ConfidenceRating的QuickCheck
反思“你的理解有什么变化？”可选文本输入或自我评分

"Aha Moment" Design Patterns

“顿悟时刻”设计模式

PatternHow It WorksWhen to Use
Prediction Gap"What do you think happens if...?" then revealBefore introducing a concept
Contrast PairTwo near-identical cases with different outcomesClarifying subtle distinctions
Slider to FailureLet learner push a parameter until it breaksUnderstanding boundaries/limits
Time TravelScrub algorithm step-by-step, watch invariantsAlgorithms, state machines
Misconception TrapTempting wrong option, then explain why wrongCommon errors in a domain
模式工作原理使用场景
预测差距“你认为如果...会发生什么？”然后揭晓答案引入概念之前
对比配对两个近乎相同但结果不同的案例澄清细微差别
滑块至失效让学习者调整参数直到功能失效理解边界/限制
时光回溯逐步浏览算法，观察不变量算法、状态机
误解陷阱设置诱人的错误选项，然后解释错误原因领域内的常见错误

Quick Color Reference (Learning Semantics)

色彩参考（学习语义）

SignalColor TokenHexUsage
Correctgreen-700
#46A758
Success feedback, completed steps
Incorrectred-700
#E5484D
Error feedback, failed checks
Hint/Cautionamber-700
#FFB224
Hints, warnings, "watch out"
Info/Definitionblue-700
#0070F3
Definitions, current step, links
Defaultgray-400
#737373
Everything else: borders, muted text
Progress donegreen-700 dot
#46A758
Completed step indicator
Progress currentblue-700 ring
#0070F3
Current step focus state
Progress pendinggray-400 dot
#737373
Upcoming steps
信号颜色令牌十六进制值用途
正确green-700
#46A758
成功反馈、已完成步骤
错误red-700
#E5484D
错误反馈、未通过检查
提示/警告amber-700
#FFB224
提示、警告、“注意”
信息/定义blue-700
#0070F3
定义、当前步骤、链接
默认gray-400
#737373
其他所有内容：边框、弱化文本
已完成进度green-700 点
#46A758
已完成步骤指示器
当前进度blue-700 环
#0070F3
当前步骤聚焦状态
待完成进度gray-400 点
#737373
即将进行的步骤

Component Library (23 Patterns)

组件库（23种模式）

Lesson Flow & Progress

课程流程与进度

<LessonShell />
<ProgressRail />
<StepFlow />
<CheckpointCard />
<ResumeBanner />
<LessonShell />
<ProgressRail />
<StepFlow />
<CheckpointCard />
<ResumeBanner />

Explorable Explanations

可探索讲解

<ParameterDock />
<LiveOutputPanel />
<ConceptExplorer />
<InteractiveDiagram />
<BeforeAfterSplit />
<TimelineExplorer />
<ConceptMap />
<ParameterDock />
<LiveOutputPanel />
<ConceptExplorer />
<InteractiveDiagram />
<BeforeAfterSplit />
<TimelineExplorer />
<ConceptMap />

Code Learning

代码学习

<CodePlayground />
<DiffEditor />
<TaskRunner />
<SnippetCopy />
<CodePlayground />
<DiffEditor />
<TaskRunner />
<SnippetCopy />

Quizzes & Active Recall

测验与主动回忆

<QuickCheck />
<ConfidenceRating />
<HintLadder />
<MistakeAnalyzer />
<QuickCheck />
<ConfidenceRating />
<HintLadder />
<MistakeAnalyzer />

Reading Support

阅读支持

<GlossaryPopover />
<Callout />
<WorkedExample />
<GlossaryPopover />
<Callout />
<WorkedExample />

Typography in Learning Context

学习场景中的排版

ElementWhat It MeansStyle
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
BodyReading content
text-copy-14
or 
text-copy-16
, max-w-2xl
元素含义样式
大标题“你正在做什么”
text-heading-{32|24}
半粗体，负字距
小标签“你所处位置”
text-label-{14|12}
gray-400
等宽文本“计算机看到的内容”
text-copy-14-mono
或 
text-label-14-mono
正文阅读内容
text-copy-14
或 
text-copy-16
，max-w-2xl

Layout Patterns

布局模式

ContextMax WidthStructure
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
场景最大宽度结构
阅读内容
max-w-2xl
/ 
max-w-4xl
单列，舒适行宽
交互式实验室
max-w-6xl
双面板：讲解 + 实验区
全功能探索器
max-w-7xl
三区域：导航 + 内容 + 实验面板

App Router Structure

App Router 结构

/                                    → Landing / course picker
/learn                               → Course catalog + resume
/learn/[courseSlug]                   → Course overview, modules, progress
/learn/[courseSlug]/[moduleSlug]      → Module overview
/learn/[courseSlug]/[moduleSlug]/[lessonSlug]  → Lesson shell
/                                    → 首页 / 课程选择器
/learn                               → 课程目录 + 继续学习
/learn/[courseSlug]                   → 课程概览、模块、进度
/learn/[courseSlug]/[moduleSlug]      → 模块概览
/learn/[courseSlug]/[moduleSlug]/[lessonSlug]  → 课程外壳

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
content/courses/<courseSlug>/course.json       → 元数据、模块顺序
content/courses/<courseSlug>/<module>/<lesson>.mdx  → 课程内容
components/learning/                           → 可复用学习组件
lib/learning/progress.ts                       → 模式 + 存储适配器
lib/learning/grading.ts                        → 测验验证、代码测试
lib/learning/spaced.ts                         → 复习调度

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
  • references/lesson-shell.md
    — LessonShell、ProgressRail、StepFlow、CheckpointCard、ResumeBanner TSX 模式
  • references/explorable-explanations.md
    — ParameterDock、LiveOutputPanel、ConceptExplorer、InteractiveDiagram、BeforeAfterSplit、TimelineExplorer、ConceptMap
  • references/code-learning.md
    — CodePlayground（只读/引导/自由模式）、DiffEditor、TaskRunner、SnippetCopy
  • references/quiz-assessment.md
    — QuickCheck、ConfidenceRating、HintLadder、带反馈模式的MistakeAnalyzer
  • references/reading-support.md
    — GlossaryPopover、Callout变体、带逐步展示的WorkedExample
  • references/pedagogical-framework.md
    — Learning Loop准则、渐进式披露规则、顿悟模式、分层复杂度
  • references/architecture.md
    — Next.js App Router 路由、MDX内容系统、状态管理、文件组织
  • references/progress-state.md
    — 进度模式、localStorage适配器、间隔重复、探索状态与URL绑定
  • references/learning-animations.md
    — 步骤过渡、反馈展示、图表动画、低动效合规性",