tech-diagram-gif

Tech Diagram GIF — 技術圖表繪製與 GIF 匯出

不引入 Python/cairosvg 渲染管線的技術圖表流程：手寫 SVG（依 vendored 風格規範）→ 瀏覽器渲染自檢 → 匯出無縫循環 GIF。 渲染與匯出全程靠瀏覽器與 ffmpeg，不裝 cairosvg / Pillow 等套件；scripts/verify-geometry.py 是唯一的 Python，純標準庫、無 pip 依賴，只做座標算術，缺 python3 時退化為人工計算，不阻擋出圖。 風格規範 vendored 自 fireworks-tech-graph（MIT，見 LICENSE.txt）； 只收編其 markdown 規範，不引入其 Python/cairosvg/FFmpeg 管線。

硬閘門

1. 先判斷該不該畫 — 動筆前問一句：讀者從這張圖學到的，會比從一段文字或一張表格多嗎？ 不會就別畫，直接寫清楚。純清單、簡單前後對照、單一形狀的「圖」一律退回文字。 使用者明確指定要圖時跳過此閘門，但仍可提一句更省的做法（提一次，不反覆）。
2. 結構未確認前，不寫任何 SVG — 先用純文字把節點/分組/連線定案（工作流程第 1 步）。
3. 交付物只有 GIF（使用者硬規則）。SVG 僅為中間產物：GIF 產出並驗證後即刪除， 不留在交付目錄。唯一例外：環境無 ffmpeg 時依第 5 步退化交付 SVG 並附裝法與資安說明 （SVG 格式可含 script，收件方有信任成本；本 skill 產的 SVG 零 script，交付前必驗證）。
4. 渲染自檢不可省 — 沒親眼看過渲染結果不得宣稱完成。

工作流程

1. 結構確認（純文字，不畫圖）

把要畫的內容整理成清單給使用者確認，格式：

節點（N）：① 名稱（語意桶）→ ② …
分組（M）：分組名 / 涵蓋節點
連線與語意：A→B 主流程（金）/ C⇢D 條件檢查（虛線）/ 自迴圈…

清單交出去前先過下方 Taste Gate 的「結構清單」組 —— 數量上限在這一步就數得出來 （節點／連線／分組三個數字見該組，本節不複製），此時超標只要改清單； 等到第 4 步才發現，只能整份重來。 使用者確認或修改 → 定案才進下一步。內容事實（節點名稱、流程順序）不確定時回問，不自行腦補。

2. 選風格與動畫模式

風格	檔案	何時用
Style 8 Dark Luxury（預設）	references/style-8-dark-luxury.md	架構、流程、資料流、拓撲 — 通用首選
Style 2 Dark Terminal	references/style-2-dark-terminal.md	開發者風格；UML 類（ER/時序/狀態機/use case）優先用此 — Style 8 深底吃 UML 細節與人形，比較表也不適合
Style 11 Event Transit	references/style-11-event-transit.md	事件流/串流拓撲（Kafka/Pulsar/NATS、消費者群、DLQ）— 提到「事件流」「地鐵圖」「Kafka 拓撲」時用
Style 12 Ops Pulse	references/style-12-ops-pulse.md	事故排查/SLO review（golden signals、critical path、trace 瀑布）— 提到「事故圖」「golden signals」「reliability」時用

動畫兩種模式（詳見 references/motion-narrative.md）：

• 循環流動（預設）：小球沿線跑（animateMotion）或 dash 脈衝
• 建置 → 營運（敘事）：開場無連線 → 逐條畫入 → 營運流動 → 淡出循環 — 對外展示/README hero 用

使用者無明示偏好時用預設，不必多問；圖型落在特定風格的甜蜜區時主動建議換風格（一句話，不反覆）。

3. 手寫 SVG

• 版面規則照 references/svg-layout-best-practices.md（間距 ≥80px、正交轉角、標籤偏移、z-order； 該檔僅取版面規則，其 cairosvg/PNG 匯出段落不適用本 skill）
• 節點複雜或含 DB/佇列/使用者/決策時，用 references/icons.md 的語意圖形 （DB 圓柱、佇列管、LLM 雙框、Agent 六角形、User 人形、決策菱形、文件摺角）取代一律圓角矩形
• 量化預算三組 —— showcase profile 表（交叉／折數／繞路比／間距）、「元素數量預算」、 「連線可量測規則」—— 數字全在 references/composition-quality-contract.md，本節不複製。 撰寫時開那張表照著寫，操作用的逐項版本見下方 Taste Gate；兩處不符一律以 contract 為準。 超出 → 調節點位置，或拆成總覽 + 細節兩張；不縮字級、不壓間距硬塞
• 節點間距 80px vs 40px、標籤三個間隙數字各量什麼 —— 裁決與說明見 contract 「與上表衝突時取嚴」節，不要自行挑一個用
• 節點、容器、連線、標籤遮罩一律加 data-role（node / container / edge / mask） —— scripts/verify-geometry.py 優先讀這個標記；沒有標記時它會退化用畫法猜並印警告， 猜錯就是靜默漏檢（實測踩過：矩形節點被當成菱形而誤報溢出；漸層畫布讓兩項遮罩檢查 一起空轉卻印「全部通過」）
• 版面順序與走廊：先排容器與列才排線、保留跨層走廊、legend 不進流程走廊
• 色票/節點語意色桶照所選風格檔；畫布建議 viewBox 0 0 1440 1080 — 注意風格檔的字級/間距以 960 寬為基準，用 1440 畫布時需等比放大（約 ×1.5）
• 字體堆疊必含跨平台 CJK 後備（以本段為準，覆蓋風格檔的 PingFang SC）： 襯線 Georgia,'Times New Roman','Songti TC','Noto Serif CJK TC',serif、 無襯線 -apple-system,'Helvetica Neue','PingFang TC','Noto Sans CJK TC',sans-serif （macOS 已驗證；Linux 走 Noto 後備，未實測）
• 小球規則：核心 r4 + 光暈 r8 opacity 0.22、顏色跟隨箭頭語意、等速（dur ∝ 路徑長）、 長路徑放 2 顆錯開半週期
• 所有動畫 dur 與 begin 必須整除同一個總循環長（如 7.2s）— GIF 才能無縫循環
• dash 脈衝模式：實線疊亮色 stroke-dasharray: 7 41 動 stroke-dashoffset；位移量須為 dasharray 週期整數倍