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欄位。
圖片
- 在建築、設計與藝術課程中，優先使用對比配對（一個失敗案例 vs. 一個成功案例），以兩個連續的
aula.imagem區塊呈現，標題分別為「改進前：…」/「改進後：…」。請學生先觀察再閱讀。texto欄位要說明看哪裡以及圖片未顯示的內容（平面圖、比例、材質、背景），且只描述看得見的部分。 - 優先使用 Wikimedia Commons。在檔案頁面確認作者與授權條款，並填寫
credito、licenca與link（檔案頁面的網址）。 - 使用圖片的直接連結（
upload.wikimedia.org/...）作為src。 - 絕對不要使用未標明出處或來自禁止轉載網站的圖片。
5. 透過檢視確認 —— 強制執行
渲染沒有錯誤並不代表視覺是正確的。在撰寫區塊之後：
- 等待約 3 秒（頁面會自動更新）。
- [Claude Code] 在應用程式的瀏覽器中，捲動到該區塊並擷取螢幕截圖（例如，使用
javascript_tool執行document.querySelectorAll('[data-tipo="diagrama"]')→ 最後一個 →scrollIntoView()，然後使用computer→screenshot）。 在其他代理中：請學生查看並確認。 - 以批判性角度檢查：
- 每條箭頭都指向正確的方向嗎？每個關係都是真實的嗎？
- 數字與比例是否與數據一致？
- 是否有任何標籤被截斷、重疊或無法辨識？
- 是否出現紅框「圖表錯誤」？→ 修正語法。
- 圖片：是否有載入？(
img.naturalWidth > 0) - 只看一眼就能理解概念嗎？
- 修正後再次檢查。如果無法產生正確且清晰的視覺，請移除該區塊並改用文字解釋。