Tw93
9.4 KiB
Diagrams
kami 的绘图能力。不重新造 13 种图，只做 3 种最通用的、能嵌进 long-doc / portfolio / slides 里增强论述的图：架构、流程、象限。皮肤 100% 沿用 kami 设计语言（parchment + 油墨蓝 + 暖灰），不引入第二种设计系统。
所有图都是自包含的 HTML + inline SVG。没有 Mermaid、没有 JS、没有构建步骤。要么作为独立页面浏览，要么把 <svg>...</svg> 块整段复制进 long-doc 的 <figure> 里。
1. 选择表
| 你要表达的是… | 选这个 | 模板 |
|---|---|---|
| 系统组件 + 它们之间的连接 | 架构图 | assets/diagrams/architecture.html |
| 决策分支 · "如果 A 则 B，否则 C" | 流程图 | assets/diagrams/flowchart.html |
| 两个维度上的定位 / 优先级 | 象限图 | assets/diagrams/quadrant.html |
不在这三种里的情况：
- 时序 / 阶段：用 long-doc 自带的 timeline 组件（resume.html / one-pager.html 里都有）。不新造图。
- 对比两件事：用表格。三列就能说清的事不要画图。
- hierarchy / 缩进列表：markdown 嵌套 ul 就够。
- 一个方框一个标签：删掉方框，直接写一句话。
绘图前的质问
如果把这张图换成一段好写的话，读者学到的会少吗？
答"不会"就别画。图是给"层次、方向、量级"加信号的，不是给文字加装饰的。
2. 克制密度
目标密度 4/10。够表达完整系统，但读者不需要图例指南就能看懂。
- 节点数 > 9 -> 这不是一张图，是两张
- 两个永远一起出现的节点 -> 合并成一个
- 有线但层级从位置就能读出来 -> 去掉这条线
- 5 个节点都是油墨蓝 -> 你没想清楚什么是焦点
焦点规则：一张图 1-2 个焦点（#1B365D + #EEF2F7 填充）。其他全走中性色。焦点的意义来自对比，不是数量。
3. 嵌入 long-doc / portfolio 的姿势
独立浏览
直接打开 assets/diagrams/architecture.html（或 flowchart / quadrant）。每份都是完整 HTML，包含标题 + SVG + caption。
嵌入到 kami 文档里
从模板 HTML 里只抠 <svg>...</svg> 块（不要带 frame / h1 / eyebrow），丢进 long-doc 的 <figure> 里：
<figure>
<svg viewBox="0 0 960 460" xmlns="http://www.w3.org/2000/svg">
<!-- 从 architecture.html 里复制的 svg 内容 -->
</svg>
<figcaption>图 1 · {{简短描述，编辑风}}</figcaption>
</figure>
long-doc.html 的 <style> 已经定义好 figure / figcaption 样式，不需要额外 CSS。
改动节点 / 文字
直接改 SVG 里的 <text> 和 <rect> 坐标。规矩：
- 所有坐标、宽度、间距都能被 4 整除。这一条是防 AI-slop 的底线，违反之后图就会开始像"差不多就行"。
- 节点宽度：128 / 144 / 160（三档够用，别再加）。小图（viewBox 宽 < 360）允许缩到 2 档，但仍限定 2 档，不要每个节点量体裁衣。
- 节点高度：32（pill）/ 64（标准）
- 字号：7（小标签 mono）/ 9（sublabel mono）/ 12（name sans）
- 箭头端点落在节点边缘：起点
(box.x + box.w, box.y + box.h/2)、终点(box.x, box.y + box.h/2)，不能"大概靠近"。悬空 10px 人眼就看得出来。 - SVG 顶部文字留白：SVG 的
<text y="…">是 baseline 位置。y 必须 ≥ font-size × 1.2，否则字母顶部伸出 viewBox 被裁（典型是 "TOOLS" 变 "TOULS"）。要么放宽 viewBox 顶部、要么把 y 加到安全区。 - 环形图的弧线控制点：四节点闭环，每条弧用 Q-curve，控制点落在两节点切线轴的外侧交点，不是节点的角。例如 PLAN（上）→ ACT（右）这段弧：起点是 PLAN 右边缘中点、终点是 ACT 顶边缘中点，控制点是
(ACT.x + ACT.w/2, PLAN.y + PLAN.h/2)。这样出发切线是纯水平、到达切线是纯垂直，弧形读起来像标准四分之一圆。控制点落在节点角上会把弧挤扁。 - 闭环图加一层 dashed 圆框：四条有向弧单独存在时，读者要在脑里自己拼成环。加一个 dashed 圆圈（圆心在视觉中心，半径略大于中心到节点内缘的距离），瞬间说清"这是一个闭环"。圆画在节点下面，节点实色填充遮住圆穿过节点那一段，只在节点之间可见。
- chevron 箭头而非实心三角：
<path d="M2 1 L8 5 L2 9" fill="none" stroke=... stroke-width="1.5" stroke-linecap="round"/>。实心三角读起来像技术 UI，两笔 open chevron 是编辑感。kami 默认用 chevron。注意 WeasyPrint 不支持<marker orient="auto">，marker 方向全部固定为 0°（朝右）。解法是不用 marker，每个箭头端点手动画一条 chevron<path>，方向写死（详见 production.md #15）。
颜色 token 映射
三种图共用的 token 角色，直接对应 kami 设计系统：
| SVG 角色 | kami token | 值 |
|---|---|---|
| 画布 | --parchment |
#f5f4ed |
| 标准节点填充 | （白） | #ffffff |
| 标准节点描边 | --near-black |
#141413 |
| Store 节点填充 | near-black 5% | rgba(20,20,19,0.05) |
| Store 节点描边 | --olive |
#5e5d59 |
| Cloud 节点填充 | near-black 3% | rgba(20,20,19,0.03) |
| Cloud 节点描边 | near-black 30% | rgba(20,20,19,0.30) |
| External 节点填充 | olive 8% | rgba(94,93,89,0.08) |
| External 节点描边 | --stone |
#87867f |
| 焦点填充 | --brand-tint |
#EEF2F7 |
| 焦点描边 | --brand |
#1B365D |
| 标准箭头 | --olive |
#5e5d59 |
| 焦点箭头 | --brand |
#1B365D |
| 文本主色 | --near-black |
#141413 |
| 文本辅助色 | --olive |
#5e5d59 |
| 文本三级色 / 小 mono 标签 | --stone |
#87867f |
别加第四种状态（比如 "warning 橙" 或 "success 绿"）。kami 只有一种强调色。
4. AI slop 反模式（看到这些就知道是 AI 默认输出）
写图 / review 图的时候扫一遍：
| 反模式 | 为什么失败 |
|---|---|
| 深色底 + 青紫色辉光 | "科技感"的廉价符号，没有设计决策 |
| 所有节点一样大小 | 消除层级 |
| JetBrains Mono 当通用"开发"字体 | Mono 只给技术内容（端口、URL、字段类型）。名字用 sans |
| 图例浮在图内部 | 和节点冲撞 |
| 箭头文字没有遮罩矩形 | 文字被线穿过去 |
| 箭头上竖排文字 | 读不懂 |
| 默认 3 个等宽总结卡片 | 模板感，宽度需要有变化 |
| 任何元素加 shadow | kami 只用 ring / whisper shadow |
rounded-2xl / border-radius: 16px+ 给节点 |
最大 6-10 px 圆角，否则开始像 App Store UI |
| 油墨蓝撒满每个"重要"节点 | 焦点规则是 1-2 个，不是信号系统 |
| 表情符号 🚀 📊 💡 做图标 | 灾难 |
| 渐变背景 | kami 禁用 |
| 焦点与标题论点不一致 | 标题说 "Simple core"，图里却把 ACT 染成油墨蓝，两个 focal 打架。focal 的颜色必须和 caption 里用 <span class="hl"> 强调的那个词对应 |
| 循环图里既画虚线环、又画四段有向弧 | 同一条回路被画两遍，读者以为有两套流 |
| SVG 文字顶部被 viewBox 裁切 | text 的 y 是 baseline，字母顶部伸到 y 负值区域。给顶部留 font-size × 1.2 的 padding，或改 viewBox |
| 箭头起点/终点与节点边缘有 5-10px 缝隙 | 看起来像"箭头悬在半空"。endpoints 要锚到 box.x / box.x+w / box.y / box.y+h 的精确值 |
| 同一张图里节点大小各自量体裁衣 | 四个步骤的宽度 60/76/80/100 给人"手工凑出来"的感觉。小图 2 档、大图 3 档，够了 |
| 参考外部图表时把每类节点着一个 accent 色（紫/琥珀/绿/红） | kami 只有一种强调色。移植外部图时，把 focal 迁移到 caption 里 <span class="hl"> 强调的那个词上，把颜色集中在那一个元素，不要铺给每个节点 |
| 环形图所有节点都是单词、中心什么都没有 | 四个框轮流转，读者没有锚。要么节点带副标题，要么环心放一句话（"20 LOC"、exit condition 等），二选一 |
5. 常见组合
技术白皮书
- 架构图（系统全景）+ 时序组件（long-doc 自带的 timeline）
- 每章最多 1 张架构图。超过 1 张说明这一章讲了两个东西，应该拆章
作品集项目页
- 象限图（竞争定位）或架构图（你负责的那一层）
- 不要每个项目都画图。只在这张图能说清而文字说不清的时候才画
一页纸方案
- 象限图（优先级） 或 流程图（决策路径）
- 只能有 1 张。如果想放 2 张，砍掉文字凑图的冲动，选最关键的那张
简历
- 不画图。简历空间比图值钱。极少数例外：展示系统架构能力时，附一个 URL 指到 portfolio
Slides
- 每页最多 1 张图。图占屏幕主体，文字是 caption，不是另外一栏
6. 构建 / 预览
python3 scripts/build.py diagram-architecture
python3 scripts/build.py diagram-flowchart
python3 scripts/build.py diagram-quadrant
# 或全部
python3 scripts/build.py
浏览器里打开 assets/diagrams/*.html 也能直接看。
7. 参考
这套能力的灵感来自 Cathryn Lavery 的 diagram-design（Claude Code skill，13 种编辑风 diagram）。kami 只吸收了它的做法（inline SVG、语义 token、复杂度预算、反 AI-slop 表），没有整体移植——13 种会把 kami 撑开，3 种够用于所有 kami 文档场景。