Html Effectiveness Diagram

05-diagram — 插画与图表

> "Inline SVG gives the agent a real pen. Ask for the figures for a post or a flowchart of a process and get vector art you can tweak by hand or paste straight into the final document."

何时用

| 用户说 | 用哪个范式 | 模板 | |-------|-----------|------| | "画一下我们的 deploy pipeline" | 流程图 | ../../templates/flowchart.html | | "状态机长什么样" | 同上 | 同上 | | "request flow / data flow 怎么走" | 同上（或参考 [01-explore](../01-explore/SKILL.md) 的 plan 数据流） | — | | "给这篇博客配几张图" | SVG 插图集 | 自建（见下） |

> 不要用 mermaid / d3 / excalidraw。直接写 inline SVG——更可控、零依赖、可手改。

---

范式 5.1 · SVG 插图集

空间形状：一个文档要的所有图都画在一页。每个 `` 单独一块——读者右键-检查-复制 outerHTML 就能拿到一张图。

HTML 骨架：

  Figure 1 · Token bucket
  
    
    
    
    
    
    
    
    
    refill rate/sec
  
  A bucket holds at most burst tokens; refills at rate/sec.

  Figure 2 · LRU cache eviction
  ...
  ...

SVG 坐标手算法（不要让 LLM 蒙数字）：

• viewBox 用整除值：0 0 240 160、0 0 800 400
• 节点对齐 20px 网格
• 文本居中：text-anchor="middle" dominant-baseline="middle"
• 配色用 var(--clay) 等 baseline 变量（如果 SVG 不在 base.css 同页则改成 hex）

无独立模板（按图不同而异）。

---

范式 5.2 · 流程图

空间形状：节点（盒子）+ 边（箭头）+ 状态颜色（pass/fail）+ 节点可点击展开"这步运行什么"。

典型场景：deploy pipeline、状态机、决策树。

HTML 骨架：

  
    
      
    
  

  
  
    
    CI · lint+typecheck
    ~2 min · ci.yml
  

  
    
    tests pass?
  

  
    
    ✓ Deploy complete
  

  
  
  

  
  

  
  
    Solid = pass · Dashed = fail
  

  CI · lint + typecheck
  ~2 min · .github/workflows/ci.yml. Runs eslint + tsc --noEmit.

关键 CSS：

.flowchart .node rect, .flowchart .node polygon {
  fill: var(--white); stroke: var(--gray-300); stroke-width: 1.5;
}
.flowchart .node.terminal.success rect { fill: rgba(120,140,93,0.15); stroke: var(--success); }
.flowchart .node text { font-size: 12px; font-family: var(--font-sans); fill: var(--slate); }
.flowchart .node text.sub { font-size: 10px; fill: var(--gray-500); }
.flowchart .node[tabindex] { cursor: pointer; }
.flowchart .node:focus rect { stroke: var(--clay); stroke-width: 2; outline: none; }

.flowchart .edge { fill: none; stroke: var(--slate); stroke-width: 1.5; }
.flowchart .edge.fail { stroke: var(--danger); }

关键 JS（节点点击展开详情）：

document.querySelectorAll('.node[data-detail]').forEach(n => {
  n.onclick = () => {
    const id = n.dataset.detail;
    document.querySelectorAll('aside[id]').forEach(a => a.hidden = a.id !== id);
  };
});

直接可用模板：[../../templates/flowchart.html](../../templates/flowchart.html) — 11 节点的 deploy pipeline 骨架，含 process / decision / terminal 三种节点形状、success（实线）/ fail（虚线）双路径、键盘可达的节点点击展开详情面板、内嵌的节点详情 JSON。修改方式：替换 SVG 节点的 transform 坐标和文本、调整 path d 走线、把 `` 里的 detail data 换成你的 pipeline 内容。

---

共同原则

• 永远用 inline SVG，不要外链 lib——agent 应该会用 ` `
• 失败路径必须视觉上区分——通常用 stroke-dasharray="6 4" + --danger 颜色
• 图例必须显示——读者第一眼看不懂图就放弃了
• 节点可点击是奢侈但有用——用户能查"这步在做什么"
• 节点形状有语义：长方形 = process，菱形 = decision，圆角胶囊 = terminal，圆形 = state

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Azhi-ss
• Source: Azhi-ss/html-effectiveness
• License: MIT
• Homepage: https://thariqs.github.io/html-effectiveness/

Install and usage instructions live in the source repository linked above.