等角 SVG 動畫
一個腳本 (node build.mjs) 將每個形狀以 平面單位 定位,投影到等角視角,並產生一個自包含的 diagram.svg(內嵌 CSS 關鍵影格,可作為純 <img> 播放)以及 preview.html(同一份 SVG 內嵌並縮放至視窗大小)。沒有任何部分是手繪的:每次修正都是修改程式碼並重新建置。
在編寫腳本之前,請先閱讀 參考資料/generator.md:了解其章節結構,以及投影、卡片、地面文字、路線、關鍵影格、平台與組合的核心程式碼。
步驟
- 故事。 閱讀系統本身的文件,然後將圖表的故事濃縮成一句話:輸入什麼、處理什麼、驅動什麼、輸出什麼。流程由左下至右上。當流程中的每個階段都能用一到三個詞命名,且使用者同意這條線時,即完成此步驟。
- 簡報。 取得一張參考圖片作為風格參考(線條粗細、密度、平台樣式);若使用者沒有參考圖片,則展示 參考資料/examples.md 中的圖表,讓他們挑選。確定主題、長寬比(1.6:1 適合一個瀏覽器視窗),以及 SVG 將放置的位置。當上述四項都寫入腳本標頭註解時,即完成此步驟。
- 靜態建置。 平台、節點、路線、標籤;暫無動畫。當建置的稽核報告顯示無重疊、無過於貼近的轉角,且使用者已簽核佈局的螢幕截圖時,即完成此步驟。
- 動畫。 加入循環。當一次循環能依序講述完整的故事,且「減少動畫」模式顯示完成狀態時,即完成此步驟。
- 匯出。 請參閱下方的「匯出」說明。
每一輪審查:一次只處理一則使用者意見,在修改任何內容前先回答問題,在進行重大變更前將目前建置複製到 versions/ 目錄中,並回覆螢幕截圖。當使用者需要在名稱或圖示之間做選擇時,請並排顯示選項。
原則
內容
- 單一流程,細節精簡。每個節點以其實際功能命名;若名稱有爭議,說明哪個名稱準確及其原因,然後讓使用者選擇。
- 每個標籤對陌生人來說都應能獨立閱讀。需要解釋的標籤應重寫或刪除。
- 只有當物件確實是堆疊(例如報告的頁面)時,才使用多層板塊;其他節點皆使用單張卡片。
- 誠實的側路徑應保留繪製(跳過某個階段的輸入),即使會佔用空間。
- 外部系統應與內部系統使用相同的平台填色;僅以虛線邊緣標示其為外部系統。
- 鬆散的輸入元件平放在地面上,下方無平台。
幾何結構
- 到處都使用平面單位:
a沿流程方向(螢幕右上),b橫跨流程方向(螢幕右下),z向上。位置、尺寸、間距和路線皆為平面單位;螢幕像素僅存在於投影之中。 - 卡片包含一個頂面及一個側邊帶(其頂部與底部輪廓的凸殼),外輪廓有一條描邊,面與厚度相接處無線條。平台則在其頂面加上描邊,因為該面位於網格上。
- 所有卡片與模組膠囊使用相同的厚度。名稱膠囊平放,無厚度。
- 按圖層繪製(地面、平台、線路、物件、標籤),並在每個圖層內依深度排序。
文字
- 每個標籤放在地平面,基線沿著
a方向。字形在建置時輪廓化成路徑,因此 SVG 作為<img>在任何地方呈現效果一致,且無需載入字型。 - 字型大小來自一個小型表格(膠囊、標籤、小字、說明、標題)。平台標題採用等寬大寫字母,並保留間距。
佈局
- 地面網格間距為 2 單位。平台邊緣向外對齊網格線;平台之間以及列之間的間距為整數網格單位;共享的主幹線路由其間距中央的網格線運行。
- 平台會自動調整大小:每個節點與標籤將其佔用空間註冊至所屬平台,平台即為該區塊加上統一的內邊距,並對齊網格。同一列的平台共享其相鄰邊緣。
- 平台標題與左邊緣的距離,等於與前邊緣的距離(測量至其大寫字母底部),並與內容左對齊。
- 網格延伸至畫面邊緣之外,並透過與畫面長寬比相同的橢圓漸層淡出,因此圖片無硬邊緣。背景為透明。
- 每次建置都會輸出 稽核報告:每個平台的四個邊距、平台之間的間距、標籤與標籤、標籤與卡片的重疊情況,以及轉角半徑過於狹窄之處。在展示任何東西之前,先讀取此報告。
線條
- 每個連接皆為一條連續路徑:正交,轉角為四分之一圓角,固定半徑,因此共享同一段路徑的路線會精確重疊,分支則沿切線從主幹分出。先繪製路線,再繪製節點於其上;結果無殘段、分叉或間隙。
- 線條類型依圖案區分:實線代表流程,虛線代表外部連結,圓點代表唯讀存取。
色調
- 色調即狀態。 僅使用中性色(R = G = B)。淺色 = 尚未到達,深一階 = 輸入已就緒,最深色 = 此輪已完成。圖示與輪廓遵循相同規則,因此任何「為什麼這個顏色比較深?」的問題,都能用狀態來回答。最深的墨水為中深灰色;避免使用純黑色和實心深色區塊。
- 線條呈現極淺色,只有在光線沿其路徑運行後才會變深。
- 顏色代表 正在運作:卡片保持白色,同時其下方隱約透出一點品牌漸層,並帶有微弱的發光效果。光線的顏色來自橫跨整個圖片的單一漸層,並沿著流程方向。
- 用於特定階段的強調色(例如拾取輸入時),僅在點亮時顯示,之後恢復為原本的灰色。
動畫
- SVG 動畫:CSS 關鍵影格內嵌於 SVG 中,無腳本,可作為
<img>播放。僅在要求時才提供渲染的影片。 - 靜止樣式即為完成運行後的狀態;關鍵影格從未運行的狀態開始每個循環。因此「減少動畫」模式和靜態匯出會顯示完成的圖表。
- 時間來自幾何結構。 光線以固定的螢幕速度(約 400 px/s)移動;每個抵達時間為 起始時間 + 路線長度 ÷ 速度,下一個事件為該抵達時間加上停頓時間。移動節點,時間軸就會隨之更新。在編寫任何關鍵影格之前,先計算完整時間軸以及循環長度。
- 一次循環講述一次故事:輸入進入、驅動器從上到下運行、元件聚集、輸出組合、匯出、暫停、清除、重複。速度應慢到足以跟隨(約 20 秒)。
- 光線是一條沿其路線運行的短虛線,帶有較柔和、較寬的光暈;在其後方會留下一條較暗的軌跡,直到循環清除。運作中的節點會升起幾個像素、發光,並閃爍其漸層面。
渲染成本
作為 <img>,任何正在運行的動畫都會使瀏覽器在每一影格重新柵格化整個圖片。
- 遮罩、濾鏡和群組應保持小型:網格透過其自身的描邊漸層淡出,遮罩則緊貼其所揭示的路徑。
- 任何看不見的東西都應設為
visibility: hidden(即使透明度為 0 或虛線偏離路徑,仍會被繪製)。 - 相同的關鍵影格只寫一次。
匯出
- 靜態 PNG:開啟 SVG 文件本身,並啟用「減少動畫」模擬後進行螢幕截圖。在
<img>內部,模擬效果無法傳遞至 SVG,因此您會捕捉到循環的第一影格。 - 預覽頁面存在於一個獨立且在本機提供的頁面中,位於使用者的網站外部,直到使用者放置 SVG 為止。