HTML 圖表與簡報 是做什麼的?
此技能(一個代理技能:Claude Code、GitHub Copilot 及其他代理會讀取它)提供了兩個小型圖表函式庫、一個簡報引擎、三個主題與三個範本。每個結果都是一個 HTML 檔案,在 GSAP 快取後可離線運作,會遵循檢視者的淺色或深色主題,並可作為 claude.ai 的成品發布。
| 路徑 | 說明 |
|---|---|
lib/edgediagram.js | 宣告式 SVG 圖形:zone、node、text、link(預設為正交、箭頭、標籤、封包流)、fan(一個點饋送多個節點)、bindFocus、steps,以及在每個步驟進行版面檢查 |
lib/edgesketch.js | 在網格上繪製的手繪圖形:zone、box(自動調整文字大小;垂直欄位與置中長條)、arrow(直角、雙箭頭)、connect(方塊到方塊)、fan、text;以及 EdgeSketch.check,適用於任何 SVG 的版面檢查,包含斜線與曲線 |
lib/icons.js | window.EDGE_ICONS:在 24 單位網格上的 50 個線條圖示(網格設備、運算、信任、操作) |
lib/edgedeck.js | EdgeDeck.run:一個 1600×900 的投影片舞台,支援每張投影片的步驟、說明文字、鍵盤、滑動與 #n 連結 |
themes/*.css | 顏色與字型主題,支援淺色與深色模式,共用一個 Token 合約:engineering(綠灰色上的藍色,使用 Archivo Narrow 與 IBM Plex)、indigo(薰衣草灰色上的靛藍色,使用 Space Grotesk 與 Inter)、drafting(暖色紙張上的青綠色,使用 Barlow Condensed 與 Source Sans 3) |
templates/diagram.html | 一個帶有步驟的 EdgeDiagram 圖形,包含說明文字、上一頁/下一頁按鈕與點點導航 |
templates/sketch.html | 一個手繪的 EdgeSketch 圖形:從左到右的區域、欄位、服務、雙向箭頭、圖例 |
templates/deck.html | 一張標題投影片加上一張內容投影片,其圖形會逐步建構 |
scripts/inline.py | 將函式庫檔案與主題內嵌到頁面中,使其發布為單一檔案;若找不到任何內容則失敗 |
scripts/shot.sh | 無頭螢幕截圖(淺色或深色模式、任何寬度、在指定的點擊後、使用 --only 指定元素、使用 --full 擷取整頁)以及 --check,對頁面上的每個圖形進行版面檢查 |
scripts/todrawio.sh | 將已建置頁面中的一個圖形匯出為 draw.io 檔案,以便在該處編輯:EdgeDiagram 圖形(附帶其連結)、手繪 SVG 圖形、HTML 圖形 |
scripts/check_theme.py | 檢查主題在淺色與深色模式下的 WCAG 對比度,並確保其兩個深色區塊一致 |
scripts/theme_from_design.py | 從 DESIGN.md 檔案(品牌的顏色與字型)製作一個主題,支援淺色與深色模式,每個配對都達到其對比度要求 |
scripts/test.sh | 執行 tests/ 中的測試;在變更 lib/、scripts/ 或 themes/ 後執行此指令 |
scripts/vendor.sh | 將函式庫複製到另一個專案,使用 --check 可以顯示該副本是否落後 |
references/api.md | 兩個函式庫與簡報引擎的所有選項 |
references/conventions.md | Token、每個色調的含義、版面規則、發布以及要執行的檢查 |
examples/ci-canary-deck.html | 一個關於中立工作流程(CI/CD,然後是金絲雀部署)的完整兩張投影片簡報 |
examples/isometric/ | 一個等角層次圖形產生器(SGAM 立方體),包含學到的經驗教訓 |
examples/design-md/DESIGN.md | 一個範例 DESIGN.md(Harbor)用於製作主題 |
工作流程
- 決定圖形必須展示什麼。 命名機制、其所依賴的零件,以及揭示它的順序。一句話能說清楚的就比圖形更好。
- 選擇函式庫。 由帶有意義連線的零件組成的圖形,逐步揭示:EdgeDiagram(
templates/diagram.html)。一個方塊網格、層疊堆疊或從左到右的平台視圖,其排列方式傳達含義:EdgeSketch(templates/sketch.html)。簡報:templates/deck.html,可在投影片上使用任一函式庫。 - 複製範本 到工作目錄,例如
cp <skill>/templates/sketch.html ./my-figure.html。修正<script src>與主題路徑,使其指向<skill>/lib/與<skill>/themes/,或者最後使用--lib與--themes參數執行inline.py。 - 在網格上佈局。 選擇 viewBox,然後是區域,接著是方塊(大小相等、間距均勻),最後是連線(請參閱下方的連接器)。將彼此通訊的方塊放在同一行或同一列,這樣它們的連線就是一條直線。為有意義的連結添加
info。閱讀references/api.md以了解選項。 - 編寫步驟(EdgeDiagram)。步驟 0 是靜止狀態。之後的每個步驟新增一個想法,並附帶一個簡短的說明。使用
flows表示移動的資料,使用dim或hide表示步驟中已略過的內容。 - 主題。 頁面連結一個主題,
<link rel="stylesheet" href="../themes/engineering.css">;變更名稱即可切換主題。engineering適用於密集的技術材料,indigo適用於產品與軟體交付,drafting適用於閱讀起來像文件的提案與研究。保持每個色調的含義(references/conventions.md)。若要使用品牌的外觀,請從其 DESIGN.md 製作主題:python3 <skill>/scripts/theme_from_design.py DESIGN.md -o themes/<name>.css(examples/design-md/DESIGN.md是範例)。手動操作時,複製一個主題,保留每個 Token 名稱,變更值,然後執行scripts/check_theme.py themes/<name>.css直到通過。 - 建置、檢查與檢視:
修正python3 <skill>/scripts/inline.py my-figure.html > build/my-figure.html <skill>/scripts/shot.sh --check build/my-figure.html # 檢查每個圖形;如有任何問題則退出碼為 1 <skill>/scripts/shot.sh --only '#my-fig' build/my-figure.html /tmp/f-light.png light 1280 <skill>/scripts/shot.sh --only '#my-fig' build/my-figure.html /tmp/f-dark.png dark 1280 <skill>/scripts/shot.sh build/my-figure.html /tmp/sN.png dark 1280 'for(var i=0;i<5;i++)document.getElementById("next").click()'--check報告的所有問題。然後開啟 PNG 檔案,修正它無法看到的問題,例如未對齊網格的方塊、碰撞的箭頭或擁擠的標籤,並再次以寬度 420 檢視。螢幕截圖會將封包凍結在連線起點附近,因此請在真實瀏覽器中判斷動畫效果。 - 應要求提供可編輯的副本。
<skill>/scripts/todrawio.sh build/my-figure.html <svg id 或選擇器> out.drawio "名稱"會將一個圖形寫入 draw.io 檔案,使用淺色主題並處於其最後一個步驟。說明它無法攜帶的內容:動畫、步驟、工具提示以及矩形與橢圓以外的填充形狀(它會列印出省略了多少個)。 - 發布。 內嵌後的檔案即為頁面:將其作為檔案分享、提交,或者在 Claude 中,將其提供給 Artifact 工具(重新發布相同的路徑或 URL 以更新它)。
連接器
連線是讀者關注的路徑,因此它們必須看起來是經過特意安排的:
- 僅限水平與垂直。 絕不使用對角線或曲線。EdgeDiagram 連結預設為
ortho:省略route。'straight'僅適用於兩個端點已在同一條直線上的情況,而'curve'僅在使用者要求時使用。在 EdgeSketch 中,使用s.arrow、s.connect與s.fan,它們會以直角轉彎。在手寫的 SVG 中,使用H與V路徑指令繪製連線,並且僅在角落處使用圓角。 - 當方塊面對面時使用一條直線。 省略位置 (
t),EdgeDiagram 或s.connect會在兩個方塊共享一個跨度時將兩端對齊。如果檢查報告出現幾個像素的偏移,請移動方塊使兩端對齊;不要微調t。 - 一個來源饋送多個方塊應使用扇出,而非一捆單獨的連線。
d.fan(id, {from: [src, 'bottom'], to: ['a', 'b', 'c']}),或s.fan(src, 'bottom', [a, b, c]),會繪製一條主幹、一個直角匯流排以及進入每個方塊的分支,並在每個交匯處加上一個點。多個方塊饋送一個方塊則是相同的扇出,只是交換了列表({from: [[...], ...], to: [...]}或{into: true})。 - 少彎曲,無交叉。 選擇連接側邊,使每條連線最多轉彎兩次。展開共享同一側邊的連線(
'auto')。繞過方塊佈線,絕不穿越它們。 shot.sh --check會報告傾斜、彎曲與偏移的連線。像修正任何其他問題一樣修正它們。使用data-route="free"標記一個故意的例外,例如等角圖形。
規則
- 不要使用其他函式庫。GSAP 3(來自 cdnjs)是可選的:沒有它時,每個步驟都會顯示其最終狀態。
- 每個顏色都來自一個 Token,因此元件絕不包含文字顏色值。
- 每個具有
info的節點、方塊或連結都是鍵盤可聚焦的。SVG 具有role="img"和一個說明圖形主張的aria-label。 - 比手機螢幕更寬的圖形應在其自身的
overflow-x: auto容器內滾動,而不是影響頁面本身。 - 將內部名稱、客戶名稱和地址排除在將被分享的頁面之外。