A.4 课程视觉使用规则

图片是教学内容，不是装饰。只有当图片能降低学习者理解成本时，才值得添加或保留。

先检查学习深度

修改课程页面前，先把自己放到学习者视角，检查页面是否同时照顾三层读者：

学习者层级	页面必须提供	警讯
新人	一个可运行的小动作、白话解释、预期输出、失败后的恢复路径	页面只解释术语，但没有让人运行或检查的东西
实践者	判断规则、常见失败、需要保留的证据、下一步项目动作	页面有 demo，但没有说明怎样判断结果好不好
有经验学习者	取舍、边界情况、调试信号、评估习惯或生产约束	页面像词汇表，没有更深入的问题可思考

如果页面太短，优先围绕学习者卡点加深，而不是堆更多定义。好页面应该让新人完成一个动作，也让有经验的人看到一个设计或评估问题。

选择合适的视觉类型

学习需求	最适合的视觉类型	文字要短
新概念、章节入口、故事、对比	image2 教学插画或漫画	是
精确公式、坐标、矩阵、代码执行顺序	SVG 或代码生成图	是
真实项目结果	截图或生成的 mock 结果	是
训练曲线、指标图、分布图	代码生成图	是
查阅型清单	紧凑表格或图解	是

移动端和三语图片规则

图片方向要根据教学目的选择。分步骤教学、移动端优先阅读、需要上下展开解释的难点，适合竖版 9:16。时间线、左右对比、架构图、仪表盘或需要横向扫描的信息，适合横图。单个对象、模式或清单，可以用紧凑的方图或近方图。目标是让学习更清楚，而不是固定一种比例。

教学图片要按中文、英文、日文三语一组生成。三语版本应共享同一个场景、版式、教学目标、关键数值和视觉节奏，只替换面向学习者的标题、副标题、标签和 alt 文案。

同一组源文件使用这个命名模式，并用同样模式同步发布图：

topic-name.png
topic-name-en.png
topic-name-ja.png

topic-name.webp
topic-name-en.webp
topic-name-ja.webp

图片生成后，按项目目前做法发布：转换或同步为 WebP 后再在课程页面引用。可以缩小文件大小，但不要过度压缩。标题、标签、公式、代码片段、坐标轴、指标数值和箭头在移动端仍然必须清楚可识别。如果压缩后变糊或读不清，就保留更大的 WebP，或先简化图片再发布。

重构课程时，可以先放清晰占位，最后统一生成正式图片。占位也要记录教学目标、目标页面、图片方向和三语文件名组，这样后续批量生成时风格和目的不会跑偏。

不要只给某一个语言新增单语图片，除非它是明确的临时占位，并且有后续补齐计划。遇到精确数值输出、公式、代码顺序或指标值时，优先使用 SVG 或锁定同一批数据的实验结果图三语组。

替换模板感太强的 SVG

有些旧 SVG 很准确，但像重复的幻灯片模板：彩色盒子、箭头和大段文字。章节入口页和大概念页，优先换成更有画面感的 image2 PNG。

这些情况保留 SVG：

• 矩阵尺寸
• 向量几何
• 终端路径和命令
• Python 求值顺序
• 精确数据/表格形状

这些情况优先换 image2：

• Agent 执行闭环
• RAG 应用闭环
• 章节级路线图
• 项目流程
• 历史转折点
• 前后对比

图片插入节奏

教学页内部尽量按这个顺序：

1. 先看图。
2. 跑最小代码或操作。
3. 看输出或结果。
4. 只解释刚刚看到的部分。

最小生产闭环

1. 找到学习者卡点。
2. 用一句话定义图片意图。
3. 根据教学目的选择图片方向和比例。
4. 先放占位，或按三语一组生成/绘制合适类型的图。
5. 对正式图片，将课程发布图转换或同步为 WebP，并保持文字和关键细节清晰。
6. 插入英文、中文、日文页面，并配套一致的 alt 文案。
7. 验证图片能解析、移动端仍可读，站点能构建。

不要因为页面空就加图。要因为下一步更好理解才加图。