视觉解说生成 remybroun/infographic

infographic

Represent the world.

一个技能，把文档、数据集或主题变成设计过的可视化解读：可直接印刷的 PDF，或者一个连续滚动的页面，HTML 就是交付物。

它不是图表库。它是一组约束，让模型产出图形文档，而不是一篇正文里钉着几张图的文章。这些约束大多会在构建时直接失败，而不是只给个提醒。

/infographic

安装

npx skills@latest add remybroun/infographic

这条命令会把它放进你的智能体查找技能的位置，Claude Code 也在其中；npx skills update infographic 拉取后续版本。默认装进当前项目；加上 -g 则装给所有项目。

也可以手动做同样的事，因为技能不过是一个目录，里面放一份 SKILL.md，Claude Code 下次会话就能找到：

git clone https://github.com/remybroun/infographic.git ~/.claude/skills/infographic

只想让某个项目用，就克隆到 <project>/.claude/skills/infographic。

验证

python3 scripts/ig.py selftest # 423 assertions
python3 scripts/ig.py validate --all # every theme through the colour checks
python3 scripts/ig.py selftest --render # also builds all six fixtures, to PDF
sh assets/build_gallery.sh # rebuilds every image on this page

前三条是 CI 每次推送都会跑的，上面的徽章就是那次运行。第四条是下面这些图的复现命令：本页每张图都是这个技能的输出，一条命令就能从源码重建全部十三张。

产出什么

左侧是一页正文，标注 2,086 words 和一张图表。一个标着 budget 的箭头指向右侧，那里是一页带标题、条形图和两个短标签的内容，标注 150 words a page。

scripts/lib/density.py 里的字数预算在任何渲染开始之前运行，一旦超限就是构建错误。这个数字不是随便定的：这个技能的第 1 版发布过一份八页的讲解文档，里面塞了 2,086 words 和一张图表，而其中每一段单独拿出来都站得住脚。之所以要有预算，是因为时间压力下的品味永远会选「再加一句解释」。

它用来作画的词汇

六个带标签的分组，每组展示三个微型样例：数量用条形、棒棒糖图和热力图；变化用折线、斜率图和哑铃图；部分与整体用环形、华夫图和占比条；结构用链、树和维恩图；示意图用分层、泳道和记分卡；编辑类用大数字、标注和分隔线。

七个家族共 51 种块类型，另有 52 个别名，让你能用日常词汇写规格（pie → donut，waffle → unit，2x2 → quadrant，flow → process，2x2 → quadrant）。

那张图是一张地图。图下面是块本身的实际渲染：样例画廊 十张图里的三张，画廊画出了这个仓库有真实数据支撑的全部 41 种形式。其中每个数字都在构建时从仓库里读出来，来源包括注册表、字数预算、五个随仓库发布的样例、linter 自己的检查以及 git log，所以它不会和它所记录的代码脱节，也没有任何数字是为了凑满一个形状而编造的。

六张数量图表渲染出来：一张棒棒糖图，展示每个随仓库发布的示例的图形化程度；一张热力图，展示每个家族的块数量；一张条形图，展示九个渲染目标的可用打印面积；一张分组柱状图，对比图形块与文本块；一张散点图，对比块数量与图形块数量；一张发散条形图，对比海报与滚动页面中各家族的使用情况。

五个块渲染出来：一座金字塔，按五条原则互相覆盖的先后顺序排列；一张维恩图，展示自绘图形与内置块的共同点；一个流程，展示五条命令；一个循环，展示 render、look、find、fix；一个象限图，按「是否需要数字」和「是否需要顺序」给各家族分类。

当目录里没有能表达某个想法的形状时，你就自己画。figure 块接收自绘 SVG，并保留内置块的所有保证：必须有 alt，必须有配套的数据孪生，拒绝颜色字面量，标签也要计入预算。每份文档最多三个，因为不设上限的话，「画出目录缺少的形状」就会变成「什么都手绘」，一致性也就没了。
四块渲染结果：一张桑基图，从 56 种块类型经族系连到每种是否绘制或设置文本；一棵仓库树；一幅手工绘制的图，围绕同一组事实给出三种论证并高亮选中项；一张记分卡，列出每个主题通过的颜色检查，旁边是一根量表，显示随附示例展示了多少词汇量。

那张图上手工绘制的图形是一个 figure。同一组事实上的三条主线，既不是树（它们不划分任何东西），也不是流程（它们是备选方案，不是步骤），也不是象限图（没有坐标轴）。要给它安上最接近的块类型名字，就得加一句「嗯，差不多吧」——这正是需要手工绘制这个形状的检验标准。

一份文档是怎么做出来的

步骤 1–6.5 靠判断，无法自动化。7–11 大多可以。

1. 来源：读它，或者 ig.py extract source.pdf
2. 读者与模式：谁读这份文档，他们有没有这个概念，缺的是哪些词？
2.5. 简报：ig.py brief out/brief.json --new。从这里到步骤 7 的所有决定都写进这一个文件，别处不写
3. 三条主线：围绕同一组事实给出三种论证，然后选一条
4. 载体：纸张、海报、幻灯片，还是连续滚动的页面
5. 场景：这份文档成败系于哪几张图，在打开目录之前就想好，且任意两张不能来自同一视角
6. 形式：每个剩余论点配一种 6.5. 检查简报：ig.py brief out/brief.json --read，在动笔画线之前
7. 规格：一次一节，ig.py brief --order <id>，画两遍，两种构图都用 ig.py sketch 单独渲染
8. 主题：经过校验，绝不手工挑选
9. 渲染：ig.py render out/spec.json --out-dir out
10. 亲眼看：ig.py shoot out/doc.html。linter 从没看过。然后 ig.py blind out/doc.html，因为你读不了自己写的文档。
11. 交付：规格、文档，以及它是怎么做出来的

有三个顺序至关重要。先解释，后论证，因为一条主线是一个主张加上支撑它的推理，而这是为已经了解主题的人写文档的框架。先有三条主线，再选一条，因为最先冒出来的论证几乎总是机制。那是来源本身已有的形状，却很少是读者真正关心的那一个。还有先命名场景，再打开目录，因为目录一打开，问题就悄悄从这看起来像什么？变成了56 种形状里哪个最接近？

解释，而非论证

有三个版本里，这个技能能为任何事实挑出好形式，却教不了任何东西，原因出在结构上。它的第一个产物是一份事实清单。第二个是一个主张，定义为读者读完应该相信的一句话。两者都是论证的框架，于是每份文档都从结论开篇、倒着往回写，这正是为已经了解主题的人。

{"meta": {"mode": "lesson", "ladder": [
{"says": "One program can run many separate company websites.",
"introduces": ["application"], "at": "one-program"},
{"says": "The web address is what tells it which company you want.",
"introduces": ["web address"], "at": "address-picks"}
]}}

阶梯就是讲解本身，在选定任何形式之前先写出来：台阶按读者攀爬的顺序排列，每级写明它教的术语，以及它落在哪个区块。某个区块用到的术语，如果教它的台阶还没出现，就是构建错误。 这是这里唯一能看出「圈内人腔调」的检查。其余检查都只量密度、形式或几何，一份文档可以全部通过，却在开头就用上一个读者还要再读四个区块才会遇到的词。

每级台阶限 24 个词，这个上限正是关键。「先彻底想清楚怎么讲，再动手画」——这条指令产出了这个技能发布过的最差文档。画图之前就把讲解完整写出来，那叫论文，图只是后来配上去的插图。

ig.py brief --read 只把骨架交给一个毫无背景的读者，此时什么都还没渲染；这和 ig.py blind 最后跑的是同一个测试，只是后者要付一次重建的代价。

构建拒绝渲染什么

水平条形图，显示图形密度下各文本字段允许的词数：figure text 40，quote 26，callout 24，note 18，subtitle 16，title 14，item detail 12，chart label 6。

三种失败会直接中止构建：超出词数预算、手绘图超过三张、绘图里出现颜色字面量。其余只警告。

这些防护每一条都对应一份真实发布过、本不该发布的文档：

| 防护 | 催生它的失败 |
| 词数预算，在代码里强制执行 | 版本 1 八页共 2,086 词，只带一张图表 |
| 手绘图最多三张 | 版本 2 修好了词数，却把所有东西都手绘，一致性全丢 |
| 绘图里拒绝颜色字面量 | 手绘图正是计算颜色最先失控的地方 |
| 手写表格计入预算 | 某节改写成三张表格就通过了，因为单元格不计入 |
| 标识符计入，且不许用术语表豁免 | 某页带了 30 个标识符却通过；后来各页用术语网格来应付行话，这个区块被删掉了 |
| 图形形式与上一版比对 | 一次重新生成回来 93% 相同，而每一步都老老实实做了 |
| 框里没有文字的不算图 | checklist、comparison、chips 和 kpi 什么都没画，却被算作图形，于是满页打勾句子、要点面板、胶囊标签和数字方块都冒充图形优先通过了。这四个全部删除，并按名字拒绝 |
| invert 不带 bleed | 它翻转墨色，却不铺底色，于是图画渲染成浅色叠浅色 |
| 在教它的那一级之前就使用某个术语 | 一份说明文档，开篇就是乐谱和术语表，结果谁也没教会，却通过了上面所有检查 |
| 任何形式的术语表都不允许 | 一格格加粗术语配一行注释，在它出现的每一页都被读成填充内容。这个区块已经删掉，术语表、，或者任何问「这些名字是什么意思」的章节，都会让构建失败 |

这个模式值得直白地说出来，因为它反复出现：

输出不对时，去找让错误做法最省事的激励，而不是去找缺失的规则。

linter 奖励散文，于是就有了散文。目录框住了每个想法，于是想法出来都是目录形状。表格单元格不受字数预算约束，于是段落变成了表格。标签上限六个词，让 skipped_bucket 比「收件人关掉了那个分组」更省事，于是页面上的标签全是只有作者才看得懂的标识符。

主题

default（中性编辑风）· iris（主主题，陶土与蓝）· rentos（橄榄编辑风，Instrument Serif）· mono（灰阶，适合印刷）。

本页每张图都是 iris，所以你看到的是一个主题在完整履职，而且它和页面顶部的标志是同一个主题。它的页面底色是标志的奶油色，强调色是标志的陶土色，两条顺序色阶都取自标志自身的两个色相角，在 OKLCH 里是 39.9° 和 251.1°。它的发散色阶从蓝到陶土，正是标志所基于的同一种反转。区块标题用展示字体，其余地方一律用无衬线；衬线字体按主题选择启用（type.block_title），因为展示字体就是无衬线字体的主题，从中什么也得不到。

状态色出自主题，不来自外部。 good 是主题的绿色槽位，warning 是它的金色，serious 和 critical 是同一深红往下两级，这很诚实，因为严重程度本就是有序的。上一个版本里 critical 在色相 29°，强调色在 40°，于是 DON'T 面板把自己涂成了主色；good 的绿在主题里别处都不出现，于是对勾读起来像框架自带的装饰。现在每个状态色相都离强调色至少 36°。

八个分类槽位刻意不用品牌色。 图表需要八个可区分的身份，品牌只有两个，硬把槽位塞进品牌色相，正是「品牌安全」配色最后变得不可读的原因。陶土和蓝领衔，其余六个靠搜索得出，遵循三条检查本身查不了的规则：色相间隔至少 36°，任何两个槽位都不会塌进同一色系；目标函数最大化任意一对里最差的那对，而不是相邻最差的那对；前三个槽位拉开明度差，因为散点图会把它们并排放。每条规则的存在，都是因为搜索少了它就崩。评分只看相邻关系时，它返回了四个橙色和四个蓝色。给定 32° 的间隔，它返回了两个深绯红色，相隔 33°。两者都合法，因为过了第三个槽位，闸门只测量相邻对，而两者在图例里都没用。闸门是下限，不是目标。

第三条规则有个上限值得写下来，因为它是页面的属性，不是搜索的属性。奶油色底阻止色度填充在 L 0.65 以上达到 3:1 的对比度，而两个品牌槽位固定在 L 0.590 和 L 0.441，所以第三个槽位只有约 0.06 的明度可动。更糟的是，你想从它那里得到的东西互相打架：高对比度的第三个槽位必须够暗，这就让它在明度上贴近 navy，只剩色相能区分它们，而这正是红色盲夺走的东西。有个候选在页面上测出舒适的 4.70:1，对红色盲来说与 navy 的距离却是没用的 7.5 ΔE。所以第三个槽位从浅色一侧取，三色组合的色觉下限保持在 15 ΔE，防止回退。

其中一项检查是新增的，新增是因为这个主题没通过它。色阶本应在最暗处最饱和；第一版 iris 色阶用正弦驱动色度，而正弦在两端都为零，于是最后两步成了中性灰，热力图读起来像披着彩色图例的灰度图。没有任何检查抓到它：序数闸门测量色相分布和明度单调性，而灰色没有色相可分布，渐变为灰也完全单调。闸门现在要求色阶的暗半段保持该色阶自身峰值色度的 40%。所有内置主题都通过（rentos 最接近，41%）；3.3.0 发布的色阶只保持了 9%。

四个主题都通过可计算的色彩检查：对比度、分类分离度、色阶饱和度、色觉缺陷距离。iris 是唯一无需豁免的；rentos 记录了一项豁免，因为品牌橄榄色测出色度 0.087，低于 0.10 的下限，而品牌色不能重新取步。新主题是 JSON 文件，不是代码。上表中的评分卡按主题统计检查项；mono 运行的检查更少，因为灰度要分离的分类槽位更少，不是因为得分更差。

python3 scripts/ig.py validate --all
python3 scripts/ig.py catalog --sheet out/sheet.pdf --theme mono

布局

SKILL.md what Claude loads first
references/ one file per decision; load the one that owns it
pipeline.md the eleven steps
graphic-first.md the word budget, and why it is code
scenes.md deciding what gets drawn by hand
anti-patterns.md check every document against this before shipping
teaching.md the ladder, and the mode that enforces it
catalog/ the 51 block types, by family
scripts/
ig.py the CLI
build.py spec → HTML
check_document.py the linter
lib/density.py the word budget
lib/ladder.py 依赖项是否都在使用它之前讲清楚 lib/derivation.py 重新生成有没有改动任何东西 lib/leading_numbers.py 那行统计数字值不值得占这个位置 fixtures/specs/ 六个完整、可渲染的实例 GALLERY.md 技能画出的每一种形式，都画了出来 assets/ gen_readme.py 本页的三张幻灯片 gen_gallery.py 十张样本页，取自本仓库自己的数据 build_gallery.sh 一条命令重建这里的每张图 measure_blocks.py 每个块排版后有多高，好让行能配对 trim_png.py 裁掉栅格化页面末尾的空白

环境要求

Python 3.12+ 标准库，外加一个 Chromium 系浏览器，用于渲染和截图（找不到就设置 CHROME_PATH）。poppler 可选，用于构建文档：它读取 PDF 源文件，并测量每页的墨水覆盖率；重建本页的图片时必须装它，这些图片通过 pdftoppm 栅格化。不用 pip 安装，不用 npm，也不用 matplotlib。

关于本页

这里的每张图都由技能生成。sh assets/build_gallery.sh 一条命令从源码重建全部十三张。

三张宽图是 16:9 幻灯片，来自 gen_readme.py，按分页目标构建，因为 README 图片是固定画幅，分页页面能填满它，不会像滚动布局那样留下空列。样本页是 A4 纵向，这也是有意的：文本标签的尺寸以毫米固定，所以页面宽度决定它在 GitHub 的栏里显示多大。A4 纵向把 8pt 标签放在约 12px；338mm 的幻灯片把同样的标签放在约 7px。

样本页设置 meta.spacing: "tight"，它会一起缩放装裱块内部的行间距、行间隙和内边距。只缩放间隙读起来不会更紧凑：两张装裱图表之间隔着 pad + gap + pad，默认值下是 62px，其中间隙占 26。tight 不是默认值，因为在一篇论证性的文档里，间隙告诉读者一个想法已经讲完了。

十一个流水线步骤和守卫表不是图片。有序列表和表格原生渲染，可搜索、可复制，还跟随你的主题。图片只有在想法是空间性的时候才值得占位置。

三张幻灯片是本仓库唯一设置 tables: false 的地方。无障碍副本是 元素，而在栅格图像里，那是个没人能操作的控件，所以它本该承载的值改为放在每张图旁边的正文里。样本页把副本留在 HTML 里。

还有三处问题，没有一处是伪造的：

- 图片是浅色的，所以在深色模式下刺眼。 要妥善解决，需要一个经过验证的深色主题，目前还没有。
- 图表构建报告三条发现，一条都不压制。 那个
gallery 会警告说，它的 cycle 样例在 330px 宽的栏里要求 380px，它说得对；样例表排布块比文档更紧凑。README 的三帧条带设了 tables: false，所以 no-table-view 报错，sparse-pages 报警告。这两项检查对文档是对的，对栅格图像帧是错的，因为那里 的孪生体是个没人能操作的控件。这就是 assets/build_gallery.sh 里那唯一一处 || true，原因就写在旁边。
- rentos 主题的字体不在本仓库里。 它的 fonts_dir 指向同级的品牌目录，所以新克隆下来渲染时用的是 Georgia 和 Helvetica，而不是 Instrument Serif 和 Inter。现在构建时如果声明的字体文件缺失会给出警告，不再静默回退，但资源仍然没有随仓库提供。

工具做不到的那一件事

linter 检查结构。它从没看过一眼文档，也说不出标签撞了、箭头指向空处、画错了图、或者论点没立住。

ig.py shoot 就是让你能看，ig.py sketch 让看一张图只要两秒而不是整轮渲染，这就是「选定的构图」和「凑合的构图」之间的差别。

然后还有你也做不到的那部分。这项技能的全部主张是：陌生人看一眼就懂这页。而作者恰恰是唯一不陌生的读者：你知道每个标签什么意思、这页想说什么，所以你看到的是意图中的文档，不是印出来的文档。ig.py blind 会打印一份简报，给完全没有上下文的读者。他们说这页讲什么，这页就是讲什么。

品牌

本页顶部的标志是 iris：一个从中间劈开的圆盘，两半各有一条有序色阶，两半让色阶朝相反方向走，于是圆盘沿自己的轴翻转。它参照两幅 Hilma af Klint 的画作绘制，结构取自 The Swan（1915），填充取自 Series VIII Utgångsbild（1920）。

这种二元性靠明度而不是色相承载，所以单色版本不是它的降级复制，在 16px 下也依然可读。它的八级色阶通过了这项技能给每个主题指定的同一个校验器，以 --ordinal 模式运行，因为色阶不是一组类别。

文件、用法规则和确切的校验命令都在 branding/。那里的一切都是生成的： bash
python3 branding/gen_brand.py

许可证

MIT。见 LICENSE。