glyph-kit

Glyph kit

你只需编写一个小型 JSON 对象，即 spec；一个无需依赖项的脚本就能绘制它。工具包会排布每个图形，因此输出始终对齐：只要有对应类型，就不要手动画图形。

请在用户的文件夹中操作，而不是在此技能的文件夹中，这样 spec 和输出文件都会保存在那里。下文中的 <skill> 指此技能的文件夹；本指南中的文件路径均相对于该文件夹。

创建一个图形

1. 从此表中选择类型；它将填入 spec 的 kind 字段。

   任务涉及	类型
   访谈、调查、可用性测试、引述	likert themeMatrix affinity quoteCard taskStats emotionCurve
   漏斗、留存、A/B 结果、指标、图表	funnel cohort abResult metricPanel barChart compare forecast meter sparkline heatmap calendarStrip
   带决策的流程、状态机、用户旅程、站点地图	flow branchFlow stateMachine journeyMap tree
   路线图、优先级、归属、时间线、决策	board impactEffort swimlane gantt statusKey decisionLog
   屏幕：单个屏幕、应用外壳、卡片网格、列表与详情、模态框	screen responsive appShell cardGrid listDetail modal
   令牌、比例、对比度、组件状态、图层	spacingScale typeScale contrast stateMatrix layerStack tokenTable table
   标注线、QA 检查清单、组件解剖图、前后对比	redline qaChecklist anatomy compare
   动效意图、时序、过渡、交错、缓动	motionTiming intentCard transitionSpec stagger filmstrip easingTable
   随时间推进的工作：返工循环、状态机、队列、发布、加载	loop states queue rollout loading
   单页完整交付物：汇报、仪表盘、PR 摘要、设计评审、状态更新	readout dashboard prSummary designReview statusUpdate

   不确定该选哪种？请阅读对应领域的指南 reference/areas/<area>.md（research、metrics、flows、planning、wireframes、systems、handoff、motion、process、layouts）：其中展示了每种类型的绘制效果。

2. 获取其数据结构：运行 node <skill>/scripts/glyph-kit.mjs guide <kind>，即可打印该类型的示例 spec 和注意事项。请复制该结构；不要阅读脚本。

3. 将 spec 写成 JSON，并与使用它的文档放在一起：

   {
     "kind": "funnel",
     "title": "Signup to paid, last 30 days",
     "intent": "Find the step where most people leave.",
     "source": "Product analytics export, 2026-10-15",
     "data": [{ "label": "Visited pricing", "value": 12400 }, { "label": "Paid", "value": 610 }]
   }
   

   数据应来自用户或其文件（"data": "@results.csv" 会读取 spec 同目录下的文件），绝不能由你编造。如果缺少数字，请询问。只有在用户仍希望绘制草图时，才以 "Illustrative" 开头填写 source：此时每种格式都会附带 SAMPLE DATA 标记。没有 source 的数字 spec 会被拒绝。

4. 用一条命令渲染、修正，再次渲染：

   node <skill>/scripts/glyph-kit.mjs render spec.json --to markdown > figure.md
   

   如果工具包无法如实绘制某个 spec，就会拒绝并用一句话说明原因。超出上限的标签（通常为 24 个单元格）会被截断为 "…"；工具包会在 stderr 中逐一列出这些标签及其上限。请缩短这些标签后重新渲染：带有 "…" 的图形会丢失文字。

5. 在图形周围的句子中写出结论。 图形用于佐证结论。

工具包输出无需进一步检查：构造过程会确保图框闭合且宽度合适。只有手绘图形才运行 node <skill>/scripts/lint.mjs <file.md>。

其他输出

每条命令的格式都是 node <skill>/scripts/glyph-kit.mjs <command>。

输出	命令	先阅读
文本、Markdown	render spec.json [--to text|markdown]	无
HTML 页面；screen 会变成可用原型	render spec.json --to html [--map design-system.map.json]	用于原型和代码的 reference/fidelity.md
演示文稿	deck deck.json > deck.html	guide deck
报告（封面、摘要、各章节）	export report.json --to html|pdf	guide report
任意内容的 MDX、SVG、PNG、PDF	export <file> --to md|mdx|html|svg|png|pdf	reference/export.md
动态图表：随时间变化的流程	live spec.json --to html（或用 --to markdown 输出静态版本）	reference/live.md
将多个布局合为一份文档	export layouts.json --to html|pdf，每个布局占一页	reference/areas/layouts.md

HTML 输出都是自包含的（字体、样式，以及动态页面内嵌的播放器）：40–200 KB。不要读回 HTML 输出进行检查；改为将同一份 spec 渲染为 --to text。PDF 和 PNG 使用机器上已有的 Chromium 浏览器；其他格式都不需要任何额外工具。

如果其他 Agent 或后续轮次需要该图示，请传递 spec（几百字节），而不是图。如果必须将图放入模型的上下文，请添加 --compact（纯 ASCII，布局不变）。

规则

1. 每个字符都有指代对象：数字、状态或结构。不要使用装饰，不要使用黑底绿字或字符雨，除非产品是终端。
2. 每份文档中，每个字符只表示一种含义。 █ 表示实测值或已完成，░ 表示预测值或量表中的空余部分，· 表示空单元格。
3. 数字以文本形式印在字符旁边，且每个含数字的图示都要标明来源。
4. 标签可使用任何文字体系。 宽度按单元格计：中日韩字符占两格。设置 lang 以确定大小写和数字格式。字体和从右向左书写的限制见：reference/characters.md。
5. HTML 和演示文稿中的每种类型都要有动态效果。 流程以及带有随时间变化读数的测试结果要保持动态；其他所有类型都只出现一次，按能传达其要点的顺序呈现，然后保持静止。每种类型都要有一张传达相同要点的静态图；减少动态效果、打印和 Markdown 中显示的都是这张静态图。在图示旁的句子中说明动态效果所展示的内容。
6. 手工绘制（仅在没有合适类型时）：使用 reference/characters.md 中的字符，遵循 reference/layout.md（框内留出两格内边距，框间留出四格，最多 80 列），然后运行 lint。
7. 提高保真度（原型、生产代码）：只能使用设计系统映射中列出的组件和令牌；如果映射中没有对应条目，请先询问。reference/spec.md 介绍 spec 字段和映射。

如果用户查看时图示看起来没有对齐，说明字体绘制字符时使用了错误的宽度：建议使用 Departure Mono（免费，departuremono.com），但不要强制要求。