visualizar 是做什么的？
只有当一个视觉能展示文字难以清晰表达的内容时，才将其加入课程：形状、结构、方向、关系、比例、空间。装饰性的或仅仅重复文字的视觉内容会增加认知负荷，甚至可能出错。如有疑问，宁可不用：缺少一个视觉的代价，远小于一个错误的视觉。
1. 选择类型
| 想法是… | 模块 | 示例 |
|---|---|---|
| 关系、依赖、流程、原因 → 结果 | aula.diagrama（Mermaid graph TD/LR） | 塞利克利率如何影响面包价格 |
| 参与者之间的交互序列 | aula.diagrama（sequenceDiagram） | 司法程序的各个阶段 |
| 时间线 | aula.diagrama（timeline） | 巴西宪法史 |
| 层级/分类 | aula.diagrama（graph TD 或 mindmap） | 法律规范的层级 |
| 数值数据、比例、几何图形、平面图 | aula.figura（手写 SVG） | 月度通胀率 |
| 真实的建筑、物体或地点 | aula.imagem | 阿尔沃拉达宫 |
2. 精简到只剩核心想法
- 一个视觉只讲一个想法。 如果需要两个，那就用两个视觉。
- 最多约 7 个元素（节点、条形、标签）。对每个元素都问：“如果去掉它，想法是否依然清晰？”如果清晰，就删掉。
- 标签要简短：一个词或短语，不要用句子。
- 图表内不要包含标题（模块本身已有
titulo）。
3. 整合视觉与解释（邻近原则，避免冗余）
- 使用模块的
texto字段：解释应该出现在旁边（如果视觉较宽，则出现在正下方）。 - 文本不要逐元素描述视觉——而是要指出注意看哪里和得出什么结论（例如“注意箭头是折返的：这是一个循环”）。
- 如果某个标签可以放在视觉内部，就放在那里，而不是放在单独的图例中。
4. 各类型的规则
Mermaid
- 包含特殊字符或
R$的文本需用引号括起来：A["R$ 1.000"]。 - 标签内换行：使用
<br/>。 - 使用
graph TD（从上到下）表示基础 → 结果；graph LR表示时间上的流程。
SVG（图形和曲线图）
- 用脚本（例如
node -e "..."）计算坐标，不要凭“肉眼”：错误的比例会误导。 - 使用带边距的
viewBox、font-family="Inter, sans-serif"，文本使用fill="currentColor"（在浅色和深色主题中均可正常工作）。 - 数据颜色最多 2 种 + 中性色。在
legenda中注明数据来源。
图片
- 在建筑、设计和艺术课程中，优先使用对比对（一个失败的案例 × 一个成功的案例），用两个连续的
aula.imagem，标题分别为“之前：…”/“之后：…”。邀请学生先看后读。texto中要指出注意看哪里以及图片未显示的内容（平面图、比例、材料、背景），并且仅描述能看到的部分。 - 优先使用 Wikimedia Commons。在文件页面确认作者和许可协议，并填写
credito、licenca和link（文件所在页面）。 - 在
src中使用图片的直接链接（upload.wikimedia.org/...）。 - 绝不使用无来源或来自禁止转载网站的图片。
5. 通过查看进行验证——这是必须的
渲染无误并不能证明视觉内容是正确的。在编写模块后：
- 等待约 3 秒（页面会自动更新）。
- [Claude Code] 在应用的浏览器中，滚动到该模块并截取屏幕截图（例如，使用
javascript_tool执行document.querySelectorAll('[data-tipo="diagrama"]')→ 最后一个 →scrollIntoView()，然后使用computer→screenshot）。对于其他代理：请学生查看并确认。 - 进行批判性检查：
- 每条箭头是否指向正确的方向？每种关系是否真实存在？
- 数字和比例是否与数据一致？
- 是否有标签被截断、重叠或难以辨认？
- 是否出现了红色框显示“图表错误”？→ 修正语法。
- 图片：是否已加载？（
img.naturalWidth > 0） - 仅通过视觉效果是否能理解想法？
- 修正后再次检查。如果无法生成正确且清晰的视觉内容，请移除该模块，改用文字解释。