diagram-design 架構(gòu)圖繪制指南editorial 風(fēng)格系統(tǒng)架構(gòu)圖的布局語法、正交連接器與安全邊界規(guī)范【免費(fèi)下載鏈接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/diagram-design本文基于 diagram-design 技能庫中的 type-architecture.md 類型規(guī)范展開講解如何用自包含 HTML 內(nèi)聯(lián) SVG 繪制系統(tǒng)總覽architecture類示意圖涵蓋分層布局約定、強(qiáng)制性的圓角正交連接器語法、交叉箭頭橋接bridge/hop原語、信任邊界區(qū)域zone分組規(guī)則以及配套的驗(yàn)證腳本。讀完本文你可以直接照章產(chǎn)出一張符合該設(shè)計(jì)系統(tǒng)、可被verify-geometry.py驗(yàn)證通過的架構(gòu)圖并理解每一項(xiàng)規(guī)則背后的排版與渲染原理。一、適用場(chǎng)景什么時(shí)候選擇 Architecture 類型根據(jù) SKILL.md 視覺類型選擇表當(dāng)你要表達(dá)「組件 連接」的系統(tǒng)視圖時(shí)Architecture 類型是首選。它的典型用途包括系統(tǒng)總覽system overviews展示一個(gè)系統(tǒng)由哪些組件組成、彼此如何連接數(shù)據(jù)流圖data-flow diagrams請(qǐng)求、數(shù)據(jù)在組件之間的流轉(zhuǎn)路徑集成地圖integration maps多個(gè)外部系統(tǒng)與本系統(tǒng)的集成拓?fù)浠A(chǔ)設(shè)施拓?fù)鋓nfra topology分層展示前端、后端、數(shù)據(jù)層或公網(wǎng)/私網(wǎng)邊界。在語義模式選擇上如果內(nèi)容的核心是「信任邊界 允許/禁止的入站或部署路徑」應(yīng)優(yōu)先加載 semantic-patterns.md 中的Secure paved road模式其最近視覺類型即 Architecture。該模式要求≤3 個(gè)信任區(qū)、≤8 個(gè)組件、≤10 條路徑、≤2 條被禁止的路徑、一個(gè)特權(quán)門privileged gate并且禁止箭頭跨越進(jìn)入受保護(hù)區(qū)。注意區(qū)分相近類型數(shù)據(jù)流Data flow強(qiáng)調(diào)角色作用域下的管道步驟DP integration 描述數(shù)據(jù)平臺(tái)的「源 → 核心 → 消費(fèi)」拓?fù)銬eployment 關(guān)注軟件運(yùn)行位置主機(jī)、副本、端口。Architecture 聚焦于組件與連接本身。二、布局約定分層、流向與 z-order架構(gòu)圖不是隨意擺放的方框集合type-architecture.md 給出了四條硬性布局約定按層級(jí)或信任邊界分組典型分組是 frontend → backend → data或 public → private。同層組件橫向?qū)R層與層之間體現(xiàn)數(shù)據(jù)流向。主流向固定主流程要么統(tǒng)一從左到右left→right要么統(tǒng)一從上到下top→down。選定一個(gè)方向后全程保持一致不要混用否則讀者無法快速建立閱讀路徑。先畫箭頭、后畫方框SVG 中先聲明箭頭path/line、再聲明節(jié)點(diǎn)rect利用 z-order 讓連接線落在組件之下、被節(jié)點(diǎn)遮擋其端點(diǎn)。這一約定在 SKILL.md §6 Mandatory connector rules 中同樣被列為強(qiáng)制項(xiàng)。1–2 個(gè) coral 焦點(diǎn)節(jié)點(diǎn)珊瑚色accent默認(rèn)#eb6c36只用于最重要的集成點(diǎn)、主數(shù)據(jù)存儲(chǔ)或關(guān)鍵決策節(jié)點(diǎn)。焦點(diǎn)節(jié)點(diǎn)使用accent-tint填充 accent描邊參見 SKILL.md 節(jié)點(diǎn)類型 → 處理表。復(fù)雜度預(yù)算方面SKILL.md §7 規(guī)定單圖最多9 個(gè)節(jié)點(diǎn)、12 條箭頭、2 個(gè) coral 元素超過預(yù)算就拆成 overview detail 兩張圖。三、連接器樣式圓角正交連接器是強(qiáng)制項(xiàng)type-architecture.md 最核心、也最容易被違反的規(guī)則是所有非水平/垂直的連接必須使用圓角右角正交連接器。在兩個(gè)坐標(biāo)軸都不對(duì)齊off-axis的節(jié)點(diǎn)之間畫對(duì)角線line屬于硬性失敗hard fail對(duì)應(yīng) SKILL.md §6 六條強(qiáng)制連接器規(guī)則 的第 1 條。標(biāo)準(zhǔn)的兩彎肘形路徑two-bend elbow公式如下r8是每個(gè)彎角的四分之一圓弧半徑!-- rightdown: from (x1,y1) to (x2,y2), mid (x1x2)/2 -- path dM x1,y1 H mid-8 Q mid,y1 mid,y18 V y2-8 Q mid,y2 mid8,y2 H x2 fillnone stroke… stroke-width1.2 marker-endurl(#arrow)/要點(diǎn)解讀Q mid,y1 mid,y18是從水平段過渡到垂直段的四分之一圓弧向右上走rightup時(shí)翻轉(zhuǎn)垂直方向的符號(hào)即可只有當(dāng)兩個(gè)端點(diǎn)共享同一個(gè) x 或 y 坐標(biāo)時(shí)才允許使用普通line箭頭標(biāo)簽放在垂直段上水平方向以mid為中心垂直方向位于兩個(gè)拐角之間的中點(diǎn)。端口選擇port selection垂直路徑走 top/bottom當(dāng)目標(biāo)節(jié)點(diǎn)明顯位于源節(jié)點(diǎn)的上方或下方時(shí)應(yīng)從源節(jié)點(diǎn)的上/下邊緣出口從目標(biāo)節(jié)點(diǎn)的上/下邊緣入口使用單彎 L 形路徑水平 → 拐角 → 垂直進(jìn)入節(jié)點(diǎn)而不是從左右側(cè)端口進(jìn)出!-- entering a node from its bottom (destination above source) -- path dM x1,y_src H x2-8 Q x2,y_src x2,y_src-8 V y_dst fillnone stroke… stroke-width1.2 marker-endurl(#arrow)/左右側(cè)端口只留給以水平為主的連接。如果一條以垂直為主的路徑從節(jié)點(diǎn)側(cè)面進(jìn)入視覺上就像箭頭「刺穿」了節(jié)點(diǎn)的臉而不是從上方/下方抵達(dá)——這是排版層面的失敗。虛線路徑路由規(guī)則不變Optional、return、async、passive 流使用stroke-dasharray4,3和更輕的線寬stroke-width1。關(guān)鍵約定虛線只改變語義權(quán)重不改變路由語法——它與實(shí)線遵守完全相同的正交路由、端口選擇和橋接規(guī)則。當(dāng)一條虛線必須與實(shí)線交叉時(shí)橋接虛線它按定義是次要連接。區(qū)域標(biāo)簽留白zone label margin區(qū)域眉標(biāo)eyebrow label底部與第一個(gè)被包含節(jié)點(diǎn)頂部之間至少保留16px。區(qū)域矩形要預(yù)留出這段頭部間隙區(qū)域y node_top ? 32標(biāo)簽掩膜y zone_y 4。四、交叉箭頭bridge / hop 原語兩條正交箭頭必須交叉時(shí)在語義上次要的那條箭頭交叉點(diǎn)處加一個(gè)小弧hop/bridge重要箭頭保持連續(xù)不中斷!-- Horizontal hop over a vertical crossing at xcx, on a line at y -- path dM x1,y H cx-8 a 8,8 0 0,1 16,0 H x2 fillnone stroke… stroke-width1.2 marker-endurl(#arrow)/SVG 弧命令解析a 8,8 0 0,1 16,0rxry8large-arc0sweep1弧線視覺上向上拱起水平前進(jìn) 16px形成跨越交叉點(diǎn)上方的一個(gè) 8px 半徑半圓凸起垂直方向的 hop 跨越水平線時(shí)在垂直路徑上使用a 8,8 0 0,0 0,16。橋接哪一條的判斷標(biāo)準(zhǔn)橋接語義上更不重要的那條——passive、secondary、write-back 流或線寬更輕的那條虛線、muted。永遠(yuǎn)不要兩條都橋接。這與 SKILL.md §6 規(guī)則 3禁止連接器重疊 配套交叉點(diǎn)只能是一個(gè)點(diǎn)兩條箭頭不能共享路徑或疊繪。五、區(qū)域分組Zone信任邊界與層級(jí)的容器把服務(wù)于同一層級(jí)或同一信任邊界的 2 個(gè)節(jié)點(diǎn)用區(qū)域矩形包起來。繪制順序在箭頭和節(jié)點(diǎn)之前完整 z-order 為背景 → 區(qū)域 → 箭頭 → 標(biāo)簽 → 節(jié)點(diǎn)這一順序正是 verify-geometry.py 判定標(biāo)簽掩膜是否被后續(xù)節(jié)點(diǎn)裁剪的理論依據(jù)。rect x{x} y{y} width{w} height{h} rx8 fillrgba(45,49,66,0.02) strokergba(45,49,66,0.10) stroke-width0.8/ rect x{label_x} y{y4} width{label_w} height12 rx2 fill{paper}/ text x{label_cx} y{y13} fillrgba(45,49,66,0.40) font-size7 font-familyGeist Mono, monospace text-anchormiddle letter-spacing0.14emLAYER/text區(qū)域規(guī)則頂部留白 12–16px眉標(biāo)eyebrow label坐在這個(gè)邊距里不壓住第一個(gè)節(jié)點(diǎn)填充強(qiáng)度rgba(45,49,66,0.02)即 2% 的「墨洗」ink wash。任何更強(qiáng)的填充都會(huì)與節(jié)點(diǎn)填充競(jìng)爭(zhēng)視覺權(quán)重?cái)?shù)量上限每圖最多3 個(gè)區(qū)域。超過 3 個(gè)會(huì)讀起來像泳道圖swimlane此時(shí)應(yīng)改用 Swimlane 類型對(duì)應(yīng) SKILL.md 視覺類型表暗色模式把rgba(45,49,66,…)換成rgba(245,245,245,…)保持相同透明度標(biāo)簽掩膜填充改為暗色paper。實(shí)際暗色示例可參考 example-architecture-dark.html--color-paper: #2d3142、accent 換為#f08a59。區(qū)域眉標(biāo)的掩膜mask與節(jié)點(diǎn)是兩種東西掩膜尺寸小寬 20–200px、高 8–14px節(jié)點(diǎn)是至少 60×40 的矩形——verify-geometry.py 的形狀啟發(fā)式 正是靠這一尺寸差來區(qū)分二者。六、從源碼示例看完整實(shí)現(xiàn)type-architecture.md 末尾列出的三個(gè)示例文件在倉庫中實(shí)際存在是本文所有規(guī)則的可運(yùn)行實(shí)現(xiàn)變體文件用途Minimal lightexample-architecture.html截圖就緒圖 標(biāo)題暖色紙張Minimal darkexample-architecture-dark.html暗色站點(diǎn)、幻燈片、高對(duì)比場(chǎng)景Full editorialexample-architecture-full.html長(zhǎng)文 Hero 圖帶摘要卡與頁腳以 example-architecture.html 為例可以對(duì)照驗(yàn)證前文每條規(guī)則z-orderSVG 中先繪制背景 rect第 73–74 行→ CONTENT 區(qū)域第 77–81 行→ 四條箭頭第 84–93 行→ 箭頭標(biāo)簽掩膜第 96–109 行→ 五個(gè)節(jié)點(diǎn)第 111–151 行→ 圖例條第 153–179 行與文檔規(guī)定的繪制順序完全一致正交連接器從 Astro 頂部出口到 MDX Bundle 底部的路徑M 496,240 H 692 Q 700,240 700,232 V 224正是文中的 L 形單彎路徑虛線返回路徑M 220,288 H 168使用stroke-dasharray4,3且stroke-width1箭頭顏色語義#2e5aa8link-blueHTTPS 外部請(qǐng)求、#eb6c36accentSSR 主流程、#4f5d75muted內(nèi)部連接與 SKILL.md 箭頭顏色表 一致節(jié)點(diǎn)類型處理Astro Origin 是唯一 focalrgba(235,108,54,0.08)填充 coral 描邊 序號(hào)02Reader 是 Externalmuted 填充 soft 描邊MDX Bundle 是 Backend白色 ink 描邊Content CMS 是 Storeink 0.05填充——五種節(jié)點(diǎn)類型各司其職coral 只出現(xiàn)一次圖例水平底部條hairline 分隔線 LEGEND 字樣絕不懸浮在圖區(qū)內(nèi)部。暗色變體的差異點(diǎn)--color-paper: #2d3142、--color-ink: #f5f5f5、accent 變#f08a59背景 rect 填充#2d3142所有標(biāo)簽掩膜和節(jié)點(diǎn)底層 mask 改為fill#2d3142MDX Bundle 的 Backend 節(jié)點(diǎn)填充改為#393e53相當(dāng)于暗色下的白色抬升。Full 變體在 SVG 之外增加了 editorial 外殼paper-2背景的 diagram-container8px 圓角 1px rule 邊框 1.5rempadding、寬度不等的三張摘要卡1.1fr 1fr 0.9fr、以及 Geist Mono 的 colophon 頁腳——完整對(duì)應(yīng) SKILL.md §7 Page layout 與 §8 Summary Card Pattern。七、反模式一眼識(shí)別 AI 拼貼式架構(gòu)圖type-architecture.md 明確列出的三類反模式每個(gè)盒子都用 coralthis is important too——層級(jí)與焦點(diǎn)全部坍塌。coral 是編輯決策不是信號(hào)系統(tǒng)單圖限 1–2 個(gè)雙向箭頭而方向其實(shí)不言自明——布局已經(jīng)暗示流向時(shí)箭頭是多余信息。SKILL.md 哲學(xué)部分同樣強(qiáng)調(diào)If the relationship is obvious from layout, remove the line圖例懸浮在圖區(qū)內(nèi)部——圖例必須是底部水平條與節(jié)點(diǎn)碰撞即失敗。此外 SKILL.md §4 通用反模式 還涵蓋任何對(duì)角線斜線、標(biāo)簽接觸自己線條、掩膜被后繪節(jié)點(diǎn)裁剪、路徑重疊、共享附著點(diǎn)、非端點(diǎn)盒子背后穿過——每一條都是自動(dòng)失敗項(xiàng)。八、驗(yàn)證用倉庫腳本把規(guī)則變成檢查項(xiàng)兩條連接器規(guī)則標(biāo)簽掩膜不接觸線條、掩膜不被后繪節(jié)點(diǎn)裁剪無法靠肉眼穩(wěn)定把關(guān)倉庫為此提供了兩個(gè)自動(dòng)化工具幾何驗(yàn)證標(biāo)簽 vs 節(jié)點(diǎn)裁剪python3 scripts/verify-geometry.py skills/diagram-design/assets/example-architecture.html # 或全量檢查 python3 scripts/verify-geometry.py --all腳本把rect按尺寸分成節(jié)點(diǎn)≥60×40與掩膜寬 20–200、高 8–14對(duì)每個(gè)掩膜檢查是否有聲明在它之后的節(jié)點(diǎn)與它部分重疊——因?yàn)楣?jié)點(diǎn)后繪制會(huì)蓋住掩膜導(dǎo)致文字碎片懸在節(jié)點(diǎn)邊框上。掩膜完全落在節(jié)點(diǎn)內(nèi)部屬于合法那是EXT/EDGE/ORIG這類 badge chip掩膜與區(qū)域重疊也合法區(qū)域先繪制。技能自檢可訪問性 SVG 契約、單文件安全、動(dòng)效基礎(chǔ)python3 skills/diagram-design/scripts/self_check.py file在生成架構(gòu)圖后的 SKILL.md §9 Pre-Output Checklist 中與連接器強(qiáng)相關(guān)的檢查項(xiàng)包括off-axis 節(jié)點(diǎn)間是否全部使用r8圓角肘路徑、無對(duì)角線每個(gè)箭頭標(biāo)簽與其線條是否有可見 6–10px 間隙交叉是否使用 bridge/hop同一盒子同一邊進(jìn)出是否各自獨(dú)立附著點(diǎn)間距 ≥12px以及「圖元坐標(biāo)是否 4px 網(wǎng)格對(duì)齊」x/y、寬高、字號(hào)全部是 4 的倍數(shù)見 SKILL.md §7 4px grid。九、動(dòng)手步驟小結(jié)按 SKILL.md §10 創(chuàng)建新圖流程生成一張合格架構(gòu)圖的完整路徑是復(fù)制最接近的變體模板minimal 用assets/template.htmlfull editorial 用assets/template-full.html若行為語義是重點(diǎn)信任邊界、允許/禁止路由先選 Secure paved road 語義模式并加載 semantic-patterns.md隨后必讀 type-architecture.md 布局語法替換 eyebrow、h1 與 SVG 主體按「背景 → 區(qū)域 → 箭頭 → 標(biāo)簽 → 節(jié)點(diǎn) → 圖例」的順序書寫元素并遵守 ≤9 節(jié)點(diǎn)、≤12 箭頭、≤2 coral、≤3 區(qū)域、單方向主流的預(yù)算補(bǔ)充title/desc并保證svg帶roleimg與aria-labelledby可訪問性契約細(xì)節(jié)見 SKILL.md §12運(yùn)行verify-geometry.py與self_check.py驗(yàn)證跑完 §9 味覺門禁taste gate再交付。整個(gè)類型規(guī)范的設(shè)計(jì)前提是架構(gòu)圖是自包含的單 HTML 文件內(nèi)聯(lián) SVG、無陰影、無外部圖片這與項(xiàng)目「No shadows. No Mermaid slop.」的設(shè)計(jì)主張一致——排版規(guī)則服務(wù)于「讀者一眼讀懂組件、流向與邊界」而不是堆砌視覺裝飾。【免費(fèi)下載鏈接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/diagram-design創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考