geist-learning-lab

Geist 学习实验室

使用 Geist 暗色优先、简约精准的 UI 语言，构建交互式学习体验，让学习者通过动手尝试、获取反馈并反复迭代来学习。

设计理念

• 学习循环，而非页面 — 每个屏幕都完成一个闭环：提示词 → 尝试 → 反馈 → 改进 → 检查点
• 认知负荷管理 — 渐进式呈现、分块，一次只讲一个概念、安排一个操作
• 对错误友好的设计 — 错误在所难免；UI 会让错误显得正常，并将其转化为学习契机
• 交互式表达 — 滑块、开关、图表、实时代码，而不只是文本
• Geist 的精准风格 — 深色背景、紧凑字距、语义化色彩、4px 网格、瑞士风格排版

关键规则

1. 每节课都必须包含至少一个尝试+反馈循环 — 不能只有被动阅读的页面
2. 每个交互控件都必须有可见的效果 — 在约 100ms 内显示，否则显示加载状态
3. 即使是原型，也必须包含进度/复习功能 — 跟踪已完成的步骤和已通过的检查点
4. 先尝试，再解释 — 提出问题或给出任务，然后再解释
5. 及时、具体地反馈 — 仅说“正确”还不够；要解释原因
6. 提供多种表达形式 — 始终至少包含以下形式中的 2 种：文本、代码、视觉内容、交互、真实数据
7. 颜色是学习信号 — 绿色=正确，红色=错误，琥珀色=提示/警告，蓝色=信息/定义
8. 默认采用渐进式呈现 — 将深入内容放在“为什么？”、“边界情况”、“形式化定义”之后
9. 通过 URL 状态探索 — 使用搜索参数分享滑块/开关配置
10. 优先考虑常见误解 — 融入常见陷阱：“大多数人会在这里出错，因为……”

学习循环（核心原则）

每节课都重复以下循环：

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

“顿悟时刻”设计模式

模式	运作方式	适用场景
预测差距	先问“你觉得如果……会发生什么？”，然后揭晓答案	引入概念之前
对比案例	展示两个几乎相同但结果不同的案例	阐明细微差别
滑块触发失败	让学习者调整参数，直到系统出错	理解边界/限制
时光回溯	逐步回放算法，观察不变量的变化	算法、状态机
误解陷阱	提供一个诱人的错误选项，然后解释其错误原因	领域中的常见错误

快速颜色参考（学习语义）

信号	颜色令牌	十六进制	用途
正确	green-700	#46A758	成功反馈、已完成的步骤
错误	red-700	#E5484D	错误反馈、检查未通过
提示/注意	amber-700	#FFB224	提示、警告、“注意”
信息/定义	blue-700	#0070F3	定义、当前步骤、链接
默认	gray-400	#737373	其他所有内容：边框、弱化文本
进度已完成	green-700 圆点	#46A758	已完成步骤指示器
当前进度	blue-700 圆环	#0070F3	当前步骤焦点状态
待完成进度	gray-400 圆点	#737373	后续步骤

组件库（23 种模式）

课程流程与进度

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

可探索式解释

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

代码学习

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

测验与主动回忆

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

阅读辅助

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

学习场景中的排版

元素	含义	样式
大标题	“你正在做什么”	text-heading-{32|24} semibold，负字距
小标签	“你当前所在位置”	text-label-{14|12} gray-400
等宽字体	“计算机看到的内容”	text-copy-14-mono 或 text-label-14-mono
正文	阅读内容	text-copy-14 或 text-copy-16，max-w-2xl

布局模式

场景	最大宽度	结构
阅读内容	max-w-2xl / max-w-4xl	单列，行长舒适
交互实验室	max-w-6xl	两个面板：说明 + 交互区
完整探索器	max-w-7xl	三个区域：导航 + 内容 + 实验室面板

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

文件组织

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/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 — The Learning Loop 教义、渐进式呈现规则、顿悟模式、脚手架式复杂度
• references/architecture.md — Next.js App Router 路由、MDX 内容系统、状态管理、文件组织
• references/progress-state.md — 进度架构、localStorage 适配器、间隔重复、探索功能的 URL 状态
• references/learning-animations.md — 步骤过渡、反馈揭示、图表动画、遵循减少动态效果偏好