chenjackle45/html-visualizer/diagram-design

本機適配（優先於下方上游各章）

用途：agent 產給人看的 HTML（html-visualizer skill），開在本機瀏覽器，沒有 sandbox、沒有 CSP、可用 <script>。

1. 入口不是這份：畫圖先讀 html-visualizer skill 的 references/structure-diagrams.md（蒸餾版：選型、六條連線規則、預算、字級、SVG 起手片段）。進到這份主要為三件事（另外兩種：架構圖要元件 icon 讀 references/primitive-icons.md；蒸餾版沒列的 27 型讀 §3 表對應的 type-*.md）：(a) 選定圖型後讀 assets/example-<type>.html 一份當幾何參考；(b) 內容是「行為」（瓶頸、分岔、信任邊界、控制目錄）時讀 references/semantic-patterns.md；(c) 讀者要「一步一步看」時讀 references/animation.md ＋ assets/template-motion.html。
2. 跳過：§0 品牌閘與 onboarding.md／profiles.md（顏色一律用 html-visualizer 的 token，見蒸餾版對照表）；§3 尾「畫前確認圖型與 size preset」（直接畫，假設寫在圖旁）；§9 三個 python3 勾（其中 verify-geometry.py / verify-motion.py 只在上游 repo checkout 有、安裝版不存在）與 §11 匯入流程；scripts/（self_check 只認單一動畫腳本，對含 Tailwind 與拍板腳本的整頁會誤報）；PNG／SVG 匯出。assets/ 隨包 base 與 *-full 兩種變體；example-*-dark.html 48 檔已移除（claude.ai 上傳限 200 檔，且本機顏色一律換 token、深色範例無用），§10 表格列到 example-<type>-dark.html 時改讀 base 版。但上游 repo 才有的東西沒隨包：scripts/verify-*.py 等驗證腳本、四個 *-extended*.html 範例、以及 §9 與各 type-*.md 提到的 python3 檢查關卡——安裝版沒有這些檔，那些步驟請跳過。文件提到的 /diagram-design:* 斜線指令同理，本 plugin 不含 commands。
3. 字型：不用 Geist／Google Fonts <link>。字型靠外層頁面 CSS 繼承（sans 系統字堆疊、mono ui-monospace）；範例裡的 font-family 屬性照抄時要拿掉。中文字級 ≥12，不 uppercase、不加字距；上游 7／8／9px 只給純拉丁等寬字。
4. 顏色：上游 hex 換成 html-visualizer token（例外：link-blue #2e5aa8 標 HTTP／外部呼叫可保留；箭頭用 muted #87867f、次要文字用 #3d3d3a）（paper #faf9f5、ink #141413、muted #87867f、accent #d97757、accent-dark #b85c3e、border #d1cfc5、accent-soft #fbe9df）。
5. 圖放進頁面的結構：.figure{overflow-x:auto} 包 <svg viewBox … style="display:block;width:100%;height:auto">，min-width 等於 viewBox 寬（或至少 0.85 倍）；viewBox 先排版、後定框（內容 bbox 進位到 4 的倍數，每邊 +40）。上游 §7「Page layout」的整頁 header／summary card 不用——圖是頁面裡的一個段落，不是整頁。
6. 可及性與 id：<svg role="img" aria-labelledby="<slug>-title <slug>-desc">；marker／mask 的 id 一律加 slug 前綴，同頁多張圖不撞。
7. 4px grid：上游要求字級與座標全是 4 的倍數；本機字級以蒸餾版 §5 為準（12／13），座標 grid 建議照守但不強制——中文標籤寬度不是 4 的倍數，硬對齊會讓遮罩貼線。
8. 動畫可用：本機沒有內容過濾（若你的頁面要嵌進會剝掉 script 與 data-* 的環境就不適用），references/animation.md 的 step-through 控制腳本可以放；仍守「靜態幀資訊完整」原則，動畫只做逐步高亮、不承載唯一資訊。

Diagram Design

Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system.

Thirty-nine visual types. Semantic patterns describe behavior independently; type references describe layout. Details load from references/ only when selected.

0. First-time setup — style guide gate

Before generating your first diagram in a new project, verify the style guide has been customized.

Don't silently ship default-skinned diagrams into a branded project.

First check the project root for a .diagram-design marker and resolve it per `references/profiles.md`. A valid marker whose profile exists selects that file directly and skips this gate; profile: default also skips it. A malformed or missing-profile marker follows the visible failure handling in that reference. Never copy a marker-selected profile over the installed working copy.

Open `references/style-guide.md` and check the default tokens. If they're still the shipped defaults (paper #f5f5f5, ink #2d3142, accent #eb6c36 atomic-tangerine), pause and ask the user:

"This is your first diagram in this project. The style guide is still at the default (neutral white-smoke + atomic-tangerine). Do you want to customize it to match your brand first? Options: (a) pull from your website URL, (b) extract from an installed skill, (c) extract from a local folder / design-system directory, (d) paste tokens manually, (e) proceed with the default for now, (f) load a saved client profile."

Then branch per the matching section of `references/onboarding.md`; for (f) follow `references/profiles.md`.

Once the style guide has been customized (or the user explicitly opted for default), skip this gate on subsequent runs. A leading profile header names the copied-in active profile. Without a header, any semantic-role value or typography family differing from shipped defaults means custom-unsaved: skip the gate and offer to save it as a profile. All-default tokens with no marker/header trigger the gate. At the end of every onboarding method, offer to save the result as a named client profile per references/profiles.md.

1. Philosophy

The highest-quality move is usually deletion.

Applied to schematics:

• Every node represents a distinct idea. Two nodes that always travel together are one node.
• Every connection carries information. If the relationship is obvious from layout, remove the line.
• Coral is editorial, not a flag. 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.
• The schematic isn't done when everything is added. It's done when nothing can be removed.

Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.

2. When to Use

Use for any of the 39 visual types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.

Don't use for:

• Quick unicode diagrams → use wiretext.
• Lists of things → table or bullets.
• Simple before/after → table.
• One-shape "diagrams" → just write the sentence.

Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw.

3. Selection: semantic pattern, then visual type

When behavior, state, enforcement, or risk carries the meaning, first load `references/semantic-patterns.md` and choose one primary pattern. Then choose the nearest visual type for layout. If no pattern matches, choose the type directly.

The pattern owns semantic primitives and its tighter budget; the type owns layout grammar. Use `references/animation.md` only when motion is requested or materially clarifies ordered change; static remains the default.

Visual-type guide (39)