glyph-kit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Glyph kit

You write a spec, a small JSON object; a script with no dependencies draws it. The kit lays out every figure, so its output always lines up: never draw a figure by hand when a type covers it.

Work in the user's folder, not this skill's, so specs and outputs land there.

<skill>

below is this skill's folder; file paths in this guide are relative to it.

你编写一个 spec，即一个小型 JSON 对象；由一个无依赖脚本负责绘制。该工具包会布局每一个图示，因此输出始终对齐：当已有类型可以覆盖需求时，绝不要手动绘制图示。

请在用户文件夹中工作，而不是本 skill 的文件夹，这样 spec 和输出文件都会落在用户目录。下文的

<skill>

代表本 skill 的文件夹；本指南中的文件路径均相对于该文件夹。

Make one

创建一个

Pick the type from this table; it goes in the spec's

kind

field.

The task is about	Types
Interviews, surveys, usability tests, quotes	`likert` `themeMatrix` `affinity` `quoteCard` `taskStats` `emotionCurve`
Funnels, retention, A/B results, metrics, charts	`funnel` `cohort` `abResult` `metricPanel` `barChart` `compare` `forecast` `meter` `sparkline` `heatmap` `calendarStrip`
Flows with decisions, state machines, journeys, sitemaps	`flow` `branchFlow` `stateMachine` `journeyMap` `tree`
Roadmaps, priorities, ownership, timelines, decisions	`board` `impactEffort` `swimlane` `gantt` `statusKey` `decisionLog`
Screens: one screen, an app shell, a card grid, list and detail, a modal	`screen` `responsive` `appShell` `cardGrid` `listDetail` `modal`
Tokens, scales, colour, contrast, component states, layers	`spacingScale` `typeScale` `palette` `colourRoles` `contrast` `stateMatrix` `layerStack` `tokenTable` `table`
Redlines, QA checklists, component anatomy, before and after	`redline` `qaChecklist` `anatomy` `compare`
Motion intent, timing, transitions, stagger, easing	`motionTiming` `intentCard` `transitionSpec` `stagger` `filmstrip` `easingTable`
Work moving over time: rework loops, state machines, queues, rollouts, loading	`loop` `states` `queue` `rollout` `loading`
A whole deliverable on one page: readout, dashboard, PR summary, design review, status update	`readout` `dashboard` `prSummary` `designReview` `statusUpdate`

Unsure between two? Read the area's guide,

reference/areas/<area>.md

(research, metrics, flows, planning, wireframes, systems, handoff, motion, process, layouts): it shows each type drawn.

Get its data shape:
```
node <skill>/scripts/glyph-kit.mjs guide <kind>
```
prints the kind's example spec and what to watch for. Copy that shape; don't read the scripts.

Write the spec as JSON next to the document that uses it:

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 comes from the user or their files (

"data": "@results.csv"

reads a file next to the spec), never from you. If numbers are missing, ask. Only if the user wants a sketch anyway, start

source

with "Illustrative": every format then carries a SAMPLE DATA stamp. A spec with numbers and no

source

is refused.

Render, fix, render again in one command:
bash
```
node <skill>/scripts/glyph-kit.mjs render spec.json --to markdown > figure.md
```
The kit refuses a spec it can't draw truthfully and says why in a sentence. Labels over the limit (usually 24 cells) are cut with "…", and the kit lists each one on stderr with its limit. Shorten those labels and render again: a figure with "…" loses words.
Put the conclusion in the sentence around the figure. The figure supports it.

Kit output needs no further checking: frames close and widths fit by construction. When a spec is refused, run

check spec.json

to see every problem at once instead of fixing them one draw at a time. Run

node <skill>/scripts/lint.mjs <file.md>

only on figures drawn by hand.

选择类型，从下表选取；类型值填入 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`
Token、刻度、颜色、对比度、组件状态、图层	`spacingScale` `typeScale` `palette` `colourRoles` `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）；其中展示了每种类型的实际绘制效果。

获取其数据结构：
```
node <skill>/scripts/glyph-kit.mjs guide <kind>
```
会输出该 kind 的 spec 示例以及需要注意的事项。复制该结构；不要阅读脚本。
将 spec 写为 JSON，放在使用它的文档旁：
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 旁边的文件），绝不能自行编造。如果缺少数字，应向用户询问。只有在用户明确仍希望得到草图时，才让
```
source
```
以 "Illustrative" 开头；这样每种输出格式都会带有 SAMPLE DATA 标记。包含数字但缺少
```
source
```
的 spec 会被拒绝。
渲染、修复，再次渲染，一条命令即可完成：
bash
```
node <skill>/scripts/glyph-kit.mjs render spec.json --to markdown > figure.md
```
如果无法如实绘制某个 spec，工具包会拒绝处理，并在一句话中说明原因。超过长度上限的标签（通常为 24 个单元格）会以 "…" 截断，工具包还会在 stderr 中列出每个超限标签及其上限。请缩短这些标签后重新渲染：带 "…" 的图示会丢失文字内容。
把结论写在图示周围的文字中。图示为结论提供支撑。

工具包的输出无需进一步检查：边框会正确闭合，宽度在构造时就能适配。如果 spec 被拒绝，运行

check spec.json

即可一次查看所有问题，而不是每次绘制只修复一个问题。仅对手动绘制的图示运行

node <skill>/scripts/lint.mjs <file.md>

。

Other outputs

其他输出

Every command is

node <skill>/scripts/glyph-kit.mjs <command>

Output	Command	Read first
Text, Markdown	`render spec.json [--to text\|markdown]`	nothing
HTML page; a `screen` becomes a working prototype	`render spec.json --to html [--map design-system.map.json]`	`reference/fidelity.md` for prototypes and code
Deck	`deck deck.json > deck.html`	`guide deck`
Report (cover, summary, sections)	`export report.json --to html\|pdf`	`guide report`
MDX, SVG, PNG, PDF of anything	`export <file> --to md\|mdx\|html\|svg\|png\|pdf`	`reference/export.md`
Every problem with a spec at once	`check spec.json` or `check notes.md`	nothing
A figure that stays editable in Markdown	`render spec.json --to markdown --with-spec` , then `redraw notes.md` after a spec change or `read notes.md` after a drawing edit	`reference/editing.md`
Your colours, or a palette	`--theme ink` , `--theme theme.json` or `--theme mixed:#7a5cff` ; roles from your tokens with `--map`	`reference/colour.md`
Moving diagram: a process over time	`live spec.json --to html` (or `--to markdown` for its still)	`reference/live.md`
Several layouts as one document	`export layouts.json --to html\|pdf` , a layout to a page	`reference/areas/layouts.md`

Decks and reports open with the kit's logo: ░▒▓█ side by side, in that order and in one colour. Keep it that way when you edit their HTML or draw a title card or still yourself.

HTML outputs are self-contained (font, styles and, for moving pages, the player inlined): 40–200 KB. Don't read them back to check them; render the same spec

--to text

instead. PDF and PNG use a Chromium browser already on the machine; everything else needs nothing.

When another agent or a later turn needs the figure, pass the spec (a few hundred bytes), not the drawing. If a drawing must go into a model's context, add

--compact

(plain ASCII, same layout).

所有命令均为

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`
一次查看 spec 中的所有问题	`check spec.json` 或 `check notes.md`	无
在 Markdown 中保持可编辑的图示	`render spec.json --to markdown --with-spec` ，spec 变更后运行 `redraw notes.md` ，绘图编辑后运行 `read notes.md`	`reference/editing.md`
你的配色，或一套调色板	`--theme ink` 、 `--theme theme.json` 或 `--theme mixed:#7a5cff` ；从 token 中读取配色角色时加上 `--map`	`reference/colour.md`
动态图示：随时间推进的流程	`live spec.json --to html` （或用 `--to markdown` 输出静态版本）	`reference/live.md`
将多种布局合并为一个文档	`export layouts.json --to html\|pdf` ，每种布局对应一页	`reference/areas/layouts.md`

演示文稿和报告会以工具包标志开头：░▒▓█ 按此顺序并排显示，并使用同一种颜色。编辑其 HTML，或自行绘制标题卡或静态图时，也要保持这一形式。

HTML 输出均为自包含文件（字体、样式以及动态页面的播放组件均已内联）：40–200 KB。不要回读这些文件进行检查；改为将同一个 spec 渲染为

--to text

。PDF 和 PNG 使用机器上已有的 Chromium 浏览器；其他所有格式无需任何额外依赖。

当另一个 Agent 或后续轮次需要该图示时，应传递 spec（仅数百字节），而不是图示本身。如果必须把图示放入模型上下文，请添加

--compact

（纯 ASCII，布局不变）。

Rules

规则

Every glyph has a referent: a number, a state or a structure. No decoration, no green-on-black or glyph rain unless the product is a terminal.
One meaning per glyph per document.
```
█
```
measured or done,
```
░
```
projected or the empty part of a scale,
```
·
```
an empty cell.
To call something out, use
focus
, never a colour. "Highlight the drop-off", "show where it fails": name it as drawn in
```
focus.on
```
, pick a tone, and say the point in
```
focus.say
```
(
```
reference/spec.md
```
). It colours, recedes the rest and arrives last in every form, and the text keeps a
```
►
```
line.
Numbers are printed as text next to the glyphs, and every figure with numbers shows its source.
Labels may use any script. Width is counted in cells: CJK takes two. Set
```
lang
```
for casing and number format. Font and right-to-left limits:
```
reference/characters.md
```
.
Every type moves in HTML and decks. The processes and a test result with readings over time keep moving; every other type arrives once, in the order that carries its point, then stays still. Each keeps a still that makes the same point; it is what reduced motion, print and Markdown show. Say what the motion shows in the sentence next to it.
Drawing by hand (only when no type fits): use the glyphs in
```
reference/characters.md
```
, follow
```
reference/layout.md
```
(two cells of padding inside a box, four between boxes, at most 80 columns), then lint.
Going up in fidelity (prototype, production code): use only the components and tokens the design-system map names, and ask when it has no entry.
```
reference/spec.md
```
describes the spec fields and the map.

If figures look misaligned where the user reads them, the font is drawing a glyph at the wrong width: suggest Departure Mono (free, departuremono.com), never require it.

每个 glyph 都有明确的指代对象：一个数字、一种状态或一种结构。除非产品本身就是终端应用，否则不要添加装饰，不要使用黑底绿字，也不要制造 glyph 雨。
每份文档中，同一个 glyph 只表达一种含义。
```
█
```
表示已衡量或已完成，
```
░
```
表示预测值或刻度中的空值部分，
```
·
```
表示空单元格。
需要突出某项内容时，使用
```
focus
```
，绝不要依赖颜色。例如“突出显示流失环节”“展示失败发生在哪里”：按图中显示的名称在
```
focus.on
```
中指定目标，选择一种色调，并在
```
focus.say
```
中说明重点（
```
reference/spec.md
```
）。它会为目标着色、弱化其余内容，并在所有输出形式中最后呈现；文本会保留一行
```
►
```
标记。
数字以文本形式打印在 glyph 旁；每个包含数字的图示都必须显示数据来源。
标签可以使用任意文字系统。宽度按单元格计算：CJK 字符占两个单元格。通过
```
lang
```
设置大小写规则和数字格式。字体和从右到左文字的限制参见
```
reference/characters.md
```
。
所有类型在 HTML 和演示文稿中都会呈现动态效果。流程以及包含连续读数的测试结果会持续播放动画；其他类型则按能传达要点的顺序逐项出现一次，随后保持静止。每种类型都有一张表达相同要点的静态图；在减少动态效果、打印和 Markdown 输出中显示的就是该静态图。请在旁边的文字中说明动态效果展示了什么。
手动绘制（仅当现有类型都不适用时）：使用
```
reference/characters.md
```
中的 glyph，并遵循
```
reference/layout.md
```
（框内留两个单元格的边距，框之间留四个单元格，每行最多 80 列），然后执行 lint 检查。
提高保真度（原型、生产代码）时：只使用 design-system map 中列出的组件和 token；如果 map 中没有对应项，应向用户询问。
```
reference/spec.md
```
介绍了 spec 字段和 map。