D-20260813-05｜Mermaid 自然尺寸、決定性拆圖與無障礙檢視

背景與驅動力

MkDocs 將大型 Mermaid 強制縮到內容欄寬，節點與標籤因此不可讀；單純加寬全站會傷害一般文字 行長。生成式關聯圖若無固定拆分規則，也會隨 traversal 或物件列舉順序改變頁數與跨頁邊，讓 derived 文件難以 review。只提供滑鼠縮放又排除鍵盤與螢幕閱讀器使用者。

考慮過的選項

• 全站內容欄加寬：大型圖較大，但所有文字頁的閱讀尺度一起退化。
• 所有圖只靠水平捲動：實作最小，仍缺大圖雙向移動、縮放與 focus 管理。
• 圖保留自然尺寸與有界 overflow；大型生成圖決定性拆分；成功渲染後提供原生 dialog：採納。

決定

Flowchart／sequence 關閉 Mermaid 強制 useMaxWidth，內嵌圖維持自然尺寸、可聚焦且在容器內捲動。 成功渲染才附加具名放大按鈕；原生 dialog 複用同一 SVG，支援雙向捲動、0.5–3 倍縮放、重設、Esc、 focus trap／return、backdrop、instant navigation 清理、print 與 reduced-motion fallback。生成圖使用 TB；超過 30 nodes 或 50 edges 時，先依 weakly connected components，再按 canonical node IDs 決定性分頁，跨頁邊以可連結表保留。手寫流程圖沿用相同方向與門檻規則。

後果與影響

大型圖不需犧牲全站文字行長即可閱讀，鍵盤與輔助科技有正式操作面。生成式圖的 page split 成為 可重現輸出；提高門檻或改拆分算法會改 derived docs review 面，必須同步規範與測試。