interactive-study-guide

交互式学习指南

将静态的学习指南 Markdown 文件转变为沉浸式交互学习体验，并通过本地 Web 应用提供访问。最终效果应如《纽约时报》的交互专题或 Pudding.cool 的文章——采用编辑风格的字体、大量留白、有目的的动画，以及能揭示结构而非仅作装饰的可视化。

指导原则

• 克制胜过炫技。 每个动画都必须物有所值，揭示静态文本无法呈现的内容。避免无谓的动态效果。
• 内容决定形式。 每个部分都应采用最适合其内容类型的布局和交互方式——不要在文字叙述效果更好时，强行加入可视化。
• 以滚动讲述故事。 主要交互方式是滚动。使用滚动驱动的内容展示、粘性元素和节点过渡，营造阅读节奏。
• 自信的字体排印。 使用大型衬线标题、适中的行长和充裕的垂直间距。在加载任何交互效果之前，文本本身就应赏心悦目。
• 渐进式增强。 即使 JavaScript 失效，页面仍应易于阅读且实用。交互效果在此基础上逐步增强。

工作流

步骤 1：定位并解析学习指南

接收学习指南 Markdown 文件的路径。使用 codebase-study-guide 中已知的模板格式，将其解析为结构化章节：

章节	标题模式	内容类型
目的	## 1. Why This Exists	包含问题、方法和用户的文字叙述
核心概念	## 2. The Big Ideas	带代码位置的命名概念
系统地图	## 3. System Map	Mermaid 图表和表格
请求流程详解	## 4. Walking Through a Request	时序图和带注释的代码步骤
深入探讨	## 5. System Deep Dives	多个 ### 5.X 子章节
模式	## 6. Patterns & Conventions	命名模式和命名表
边界	## 7. Boundaries & External Systems	外部系统表格
测试	## 8. Testing Strategy	带探索提示的文字叙述
后续步骤	## 9. Your Next Steps	按天划分的清单

如果 Markdown 不符合此精确结构，请灵活调整——根据标题内容而非编号检测章节。

步骤 2：设置项目

运行脚手架脚本以创建 Vite 项目：

bash scripts/scaffold.sh <output-directory> "<project-name>"

这会创建一个已配置的 Vite 项目，并预装 D3、Prism.js 和编辑风格设计系统。完成脚手架搭建后，在输出目录中运行 npm install。

第 3 步：逐节构建

将解析后的每个章节转换为对应的交互式内容。有关各章节类型的详细可视化模式和代码示例，请参阅 references/section-strategies.md。所有字体、颜色、间距和动效令牌，请参阅 references/design-system.md。

章节与可视化方式的对应关系：

章节	交互设计
目的	使用大号衬线字体的全屏宽幅主视觉。文字在加载时以渐显动画呈现。问题陈述以醒目的引用语呈现。不需要交互——让文字自在呈现。
阈值概念	默认折叠的卡片，只显示概念名称。点击后通过平滑的高度过渡展开。将“你会在这些文件中看到”的路径显示为可点击的标签。为相关概念添加低调的连接线。
系统图	使用交互式 D3 力导向图替代 Mermaid 图表。节点可拖动。悬停时显示表格中的单行用途说明。点击节点可滚动到对应的深入解析章节。动态边线展示数据流方向。
请求流程解析	由滚动驱动的逐步展示。左侧固定图表面板会随着读者滚动浏览右侧带注释的代码步骤而动态变化。每一步都会在图表中突出显示当前系统。代码块采用语法高亮，并逐行显示。
深入解析	使用标签页界面，每个系统对应一个标签页。每个标签页包含：醒目标题形式的用途说明、可点击徽章形式的模式名称、抽象概念表、以小型连接图展示的接口，以及置于醒目提示框中的探索任务。
模式	可搜索和筛选的卡片网格。每张卡片显示模式名称、出现位置（以代码位置标签呈现）及原因。点击卡片可翻转或展开，查看完整说明。命名约定以样式化参考表呈现。
边界	简洁的数据表格，悬停行即可展开。每行展示外部系统、其作用和集成模式。可以添加简单的边界图，展示系统内外部的划分。
测试	采用简洁样式——以醒目的交互式提示框（复选框，勾选后显示提示）呈现探索提示。
后续步骤	带本地存储持久化功能的交互式清单。顶部显示进度条。各天以水平时间线节点呈现。完成项目时播放令人满意的勾选动画。

第 4 步：连接导航与过渡效果

构建一个精简的导航系统：

• 左侧边栏（桌面端）或底部面板（移动端）：将章节标题作为导航链接，并通过滚动侦测高亮显示当前章节
• 进度指示器：视口顶部的细条，显示阅读进度
• 平滑滚动：点击导航链接后，平滑滚动至对应章节
• 章节过渡：每个章节进入视口时，使用 IntersectionObserver 触发渐显效果

第 5 步：启动开发服务器

构建完所有组件后：

cd <output-directory> && npx vite --open

第 6 步：完善细节

向用户展示之前，请确认：

• 字体层级清晰——标题、正文、代码和说明文字在视觉上各有区别
• 留白充足——章节舒展自然，不显拥挤
• 动画流畅且恰到好处——没有卡顿，也没有多余的弹跳效果
• 系统图具有交互性——节点可拖动，悬停时显示信息，点击后可导航
• 代码块采用与代码库语言相匹配的语法高亮
• 移动端布局正常——单列布局，交互便于触控
• 遵循 prefers-reduced-motion 设置——所有动画都能平稳禁用
• 颜色对比度符合 WCAG AA 标准——尤其是代码块和弱化文本
• 导航的滚动侦测能准确跟踪当前章节
• 交互元素（标签页、卡片、清单）响应即时，无需加载状态

资源

scripts/scaffold.sh

创建配置好的 Vite 项目，并包含依赖项和编辑设计系统。用法请参阅步骤 2。

references/section-strategies.md

每个学习指南章节的详细可视化策略和代码模式。构建时的主要参考资料——编写任何章节组件之前都应查阅。

references/design-system.md

完整的编辑设计系统：字体排版比例、调色板、间距、动效令牌和组件级样式。所有视觉决策都应参考这些令牌。