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

核心规则

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..."

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

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

每节课都会重复以下循环：

步骤	内容	组件
定位	5-10分钟内你将学到的内容	标题 + 学习目标
尝试	学习者先进行预测/作答/编辑	QuickCheck、CodePlayground、ParameterDock
反馈	即时且具体的回应	反馈区域（绿/红面板）
讲解	结合学习者尝试的简短解释	Callout、WorkedExample
拓展	变体、边缘情况或迁移任务	BeforeAfterSplit、ConceptExplorer
检查点	快速回忆问题	带ConfidenceRating的QuickCheck
反思	“你的理解有什么变化？”	可选文本输入或自我评分

"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

信号	颜色令牌	十六进制值	用途
正确	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

学习场景中的排版

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

元素	含义	样式
大标题	“你正在做什么”	`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

布局模式

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

场景	最大宽度	结构
阅读内容	`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
```
— 步骤过渡、反馈展示、图表动画、低动效合规性",