visual-design-system-extractor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual Design System Extractor

视觉设计系统提取器

Turn visual references into one parser-valid YAML design system whose every claim traces back to something visible, and whose every selected typeface is a Google Fonts family the live catalog ranks as rarely used at the moment of the run.

The gates need a terminal, a YAML parser, and network access to the live font catalog. The commands below fetch the parser through

uv

; run

mise run ci

inside this directory to check the whole package.

将视觉参考转换为符合解析器规范的YAML设计系统，其中每一项声明都可追溯到可见内容，且每一款选定的字体都是运行时实时Google Fonts目录中被列为极少使用的字体家族。

使用本工具需要终端、YAML解析器以及访问实时字体目录的网络权限。以下命令将通过

uv

获取解析器；在当前目录下运行

mise run ci

即可检查整个包。

Which commands does this skill accept?

本技能支持哪些命令？

Interpret a plain request with an attached reference as

extract

Command	Result
`help`	Show this table and the current schema version.
`extract <refs>`	Produce the full YAML design system from the supplied references.
`fonts <brief>`	Return ranked rare Google Fonts candidates without a full extraction.
`validate <file>`	Run the schema and font gates against an existing extraction.
`maintain <change>`	Edit this package under the test-first rules below.

If no reference is attached or reachable, stop and ask for the image, screenshot, moodboard, style frame, or URL. Do not invent a system from a description alone.

将带有附加参考内容的普通请求解读为

extract

命令。

命令	结果
`help`	显示此表格及当前Schema版本。
`extract <refs>`	根据提供的参考内容生成完整的YAML设计系统。
`fonts <brief>`	返回排名靠前的稀有Google Fonts候选字体，无需完整提取流程。
`validate <file>`	针对已有的提取结果运行Schema和字体校验规则。
`maintain <change>`	按照下文的测试优先规则编辑本包。

如果未附加或无法获取参考内容，请停止操作并请求提供图片、截图、情绪板、风格帧或对应URL。不得仅根据描述凭空生成设计系统。

What does the extraction return?

提取操作会返回什么？

For

extract

, return parser-valid YAML and nothing else: no code fences, no prose before or after, no separate summary of the images, and no document that failed the gate. Determinism means the same evidence yields the same sections, key order, confidence labels, and not-applicable objects. Judgment lives inside field values only, and each value points back to visible evidence.

执行

extract

命令时，仅返回符合解析器规范的YAML内容：不包含代码围栏、前后说明文字、图片单独摘要，也不返回未通过校验的文档。确定性意味着相同证据会生成相同的章节、键顺序、置信度标签和不适用对象。判断仅存在于字段值中，且每个值都指向可见证据。

How does an extraction run?

提取流程如何运行？

Use this full plan. After each step, run the stated check and fix a failure before moving on. Append one line per step to

extraction-log.md

in the working directory, or keep the same record in the reply when file writing is unavailable.

Confirm at least one reference is available and readable. Check: the reference is named in the log.

Load the skeleton:

uv run --no-project --with 'PyYAML>=6,<7' python scripts/schema_tools.py skeleton --output /tmp/extraction-skeleton.yaml

. When a field meaning is unclear, query the schema contract with

uv run --no-project --with 'PyYAML>=6,<7' python scripts/schema_tools.py field <dotted.path>

uv run --no-project --with 'PyYAML>=6,<7' python scripts/schema_tools.py group <name>

instead of reading the whole file. Check: the skeleton file exists and opens with

meta:

Copy the skeleton key order exactly. Do not rename, reorder, or drop keys, and do not add a top-level section unless the user asked for a narrower artifact. Check: the section list matches the skeleton.
Fill
```
meta
```
,
```
source_analysis
```
, and
```
confidence_scores
```
first, keeping observed facts, inferred logic, and speculative extrapolation in separate buckets. Check: nothing speculative sits in the observed bucket.
Fill the visual foundations: color, spacing, layout, grid, sizing, borders, radii, shadows, gradients, materials, textures, and lighting. Check: every token carries
```
confidence
```
and
```
inference_basis
```
.
Read the font sourcing rules, then select every typeface through the live catalog before writing the typography section. Check:
```
python3 scripts/rare_google_fonts.py verify --family "<name>"
```
exits 0 for each selected family.
Fill
```
typography
```
, recording
```
catalog_snapshot
```
plus the exact
```
rarity
```
block the tool returned for each family. Check: every rarity block shares one
```
retrieved_at
```
date.
Fill the experiential layers: motion, animation, camera, composition, environment, setting, wardrobe, props, iconography, and the image and rendering styles. Check: unsupported layers use the not-applicable object rather than a guess.
Fill the product layers: accessibility, interaction, interface patterns, sound, narrative, worldbuilding, styling rules, token dependencies, responsive rules, state variants, platform adaptations, generation prompts, and implementation notes. Check: implementation-ready requests carry token dependencies and platform adaptations.

Run the gate:

uv run --no-project --with 'PyYAML>=6,<7' python scripts/validate_design_system_yaml.py /tmp/extraction.yaml

. Exit 0 is required. On exit 1, fix every listed problem and rerun. Check: the fresh run prints

"valid": true

Return the validated YAML only, without the validation report.

请遵循以下完整流程。每一步完成后执行指定检查，修复问题后再进入下一步。在工作目录的

extraction-log.md

中为每一步添加一行记录；若无法写入文件，则在回复中保留相同记录。

确认至少有一个参考内容可用且可读。检查：参考内容已在日志中命名。

加载骨架文件：

uv run --no-project --with 'PyYAML>=6,<7' python scripts/schema_tools.py skeleton --output /tmp/extraction-skeleton.yaml

。若字段含义不明确，请通过

uv run --no-project --with 'PyYAML>=6,<7' python scripts/schema_tools.py field <dotted.path>

或

uv run --no-project --with 'PyYAML>=6,<7' python scripts/schema_tools.py group <name>

查询Schema协议，而非通读整个文件。检查：骨架文件存在且以

meta:

开头。

严格复制骨架文件的键顺序。不得重命名、重新排序或删除键，除非用户要求生成更窄范围的产物，否则不得添加顶层章节。检查：章节列表与骨架文件一致。
先填充
```
meta
```
、
```
source_analysis
```
和
```
confidence_scores
```
，将观测事实、推断逻辑和推测性外推分别归类。检查：观测部分无推测内容。
填充视觉基础内容：颜色、间距、布局、网格、尺寸、边框、圆角、阴影、渐变、材质、纹理和光影。检查：每个令牌都带有
```
confidence
```
和
```
inference_basis
```
字段。
阅读字体来源规则，然后通过实时目录选择所有字体，再填充排版章节。检查：每个选定字体家族都能使
```
python3 scripts/rare_google_fonts.py verify --family "<name>"
```
命令返回0。
填充
```
typography
```
部分，记录
```
catalog_snapshot
```
以及工具为每个家族返回的完整
```
rarity
```
块。检查：所有
```
rarity
```
块共享同一个
```
retrieved_at
```
日期。
填充体验层内容：动效、动画、镜头、构图、环境、场景、服饰、道具、图标以及图像和渲染风格。检查：不支持的层使用不适用对象，而非猜测内容。
填充产品层内容：可访问性、交互、界面模式、声音、叙事、世界观构建、样式规则、令牌依赖、响应式规则、状态变体、平台适配、生成提示和实现说明。检查：可直接用于实现的请求需包含令牌依赖和平台适配内容。
执行校验：
```
uv run --no-project --with 'PyYAML>=6,<7' python scripts/validate_design_system_yaml.py /tmp/extraction.yaml
```
。必须返回0。若返回1，请修复所有列出的问题并重新运行。检查：新运行结果显示
```
"valid": true
```
。
仅返回经过校验的YAML内容，不包含校验报告。

What are the font rules?

字体规则是什么？

One rule governs every typeface the system selects: it is published on Google Fonts, and the live catalog ranks it as rarely used right now. Both halves are measured during the run, never recalled. Rank and family count come from the live feed, and rarity percentile runs from 0.0 for the most requested family to 100.0 for the least. The floor is 70.0 unless the user sets another value.

typography.font_families.primary

typography.font_families.supporting

, and every entry in

typography.font_families.rare_unique_candidates

carry

google_fonts_family: true

and a complete

rarity

record.

typography.font_families.observed_or_implied

is different: it records what the reference shows, so a licensed or custom face belongs there and needs no rarity record.

When the live feed cannot be read, stop and report. Name the failed command, mark

typography.font_families

with the not-applicable object, and do not present the result as verified. A rarity number recalled from memory or copied from an older snapshot is a defect, not a fallback.

系统选择的每一款字体都需遵循一条规则：该字体发布在Google Fonts上，且实时目录当前将其列为极少使用的字体。这两个条件均在运行时验证，而非依赖记忆。排名和家族数量来自实时数据源，稀有度百分位数范围为0.0（最常用家族）到100.0（最不常用家族）。默认阈值为70.0，用户可自行设置其他值。

typography.font_families.primary

、

typography.font_families.supporting

以及

typography.font_families.rare_unique_candidates

中的每一项都需携带

google_fonts_family: true

和完整的

rarity

记录。

typography.font_families.observed_or_implied

则不同：它记录参考内容中显示的字体，因此授权字体或自定义字体应归入此处，且无需稀有度记录。

若无法读取实时数据源，请停止操作并报告。说明失败的命令，将

typography.font_families

标记为不适用对象，不得将结果呈现为已验证内容。依赖记忆或旧快照的稀有度数值属于缺陷，不能作为 fallback 方案。

What loads when?

各类资源何时加载？

The schema contract is machine readable YAML holding the section order, field rules, font rules, syntax rules, and self-check list. Query it through

scripts/schema_tools.py

rather than reading it whole. Load the font sourcing rules before touching any font field. Load the generation contract only when editing this package.

Load

assets/schema-skeleton.yaml

through the skeleton command to start a document. Load

assets/font-brief.json

to map visible type evidence onto catalog filters before running discovery. Load

assets/minimal-extraction.yaml

to see the smallest document that clears every gate. Load

scripts/

for the executable gates,

scripts/tests/

only when changing script behavior, and

evals/

when measuring activation, behavior, failure handling, recovery, or timing.

Schema协议是机器可读的YAML文件，包含章节顺序、字段规则、字体规则、语法规则和自检清单。请通过

scripts/schema_tools.py

查询，而非通读整个文件。在处理任何字体字段前，先加载字体来源规则。仅在编辑本包时加载生成协议。

通过骨架命令加载

assets/schema-skeleton.yaml

以启动文档。在进行发现操作前，加载

assets/font-brief.json

以将可见字体证据映射到目录过滤器。加载

assets/minimal-extraction.yaml

以查看通过所有校验的最小文档。加载

scripts/

目录下的可执行校验工具，仅在修改脚本行为时加载

scripts/tests/

，在测量激活、行为、错误处理、恢复或计时时加载

evals/

。

How is this package maintained?

如何维护本包？

For

maintain

, the YAML-only response contract does not apply. Establish the failing state first: a gate that rejects valid input, a missing behavior, or the exact gap the user named. Add the focused test, watch it fail, add the smallest change that passes it, then run

mise run ci

inside this directory. Exit 0 is required before reporting. Keep long detail in

references/

, executable checks in

scripts/

, and templates in

assets/

执行

maintain

命令时，不适用仅返回YAML的响应规则。首先确定故障状态：校验规则拒绝有效输入、缺失某项行为或用户明确指出的具体缺口。添加针对性测试，观察测试失败，再添加最小化修改使测试通过，然后在当前目录下运行

mise run ci

。必须返回0后再进行报告。将详细内容保存在

references/

，可执行校验保存在

scripts/

，模板保存在

assets/

。

Gotchas

注意事项

The live feed sometimes reports a popularity rank above the family count. The percentile clamps at 100.0; record the rank exactly as returned.
A family that was rare last month may not be rare today. The default validation compares recorded ranks against the live catalog and fails on drift, which is the gate working.
Common interface defaults are rejected by name even when the surrounding prose argues for them.
Words such as unusual or overlooked prove nothing.
```
rarity_reason
```
explains the measured number; it never replaces it.
A fallback stack must name families that exist and must end with a generic family.
Do not run separate per-section validation passes. The bundled validator is the single mechanical gate.
Do not read the schema contract end to end. Query one field or one group at a time.
The section order, the confidence labels, and the font floor all come from the schema contract. Change the rule there and every gate follows; hardcoding a value in a script breaks that link.

实时数据源有时会报告高于家族总数的流行度排名。此时百分位数将固定为100.0；按返回值精确记录排名。
上个月属于稀有的字体家族本月可能不再稀有。默认校验会将记录的排名与实时目录进行比较，若出现偏差则校验失败，这属于校验规则的正常工作机制。
常见界面默认值会被直接拒绝，即使相关说明文字支持使用它们。
“不寻常”或“被忽视”等词汇无法作为依据。
```
rarity_reason
```
用于解释测量得到的数值，绝不能替代数值本身。
回退字体栈必须包含真实存在的字体家族，且必须以通用字体结尾。
不得单独运行各章节的校验。 bundled validator是唯一的机械校验入口。
不得通读Schema协议。每次仅查询一个字段或一个分组。
章节顺序、置信度标签和字体阈值均来自Schema协议。若要修改规则，请在Schema中调整，所有校验规则都会随之更新；在脚本中硬编码值会破坏这种关联。

When is an extraction complete?

提取操作何时完成？

An extraction is complete only when the validator exits 0 on a fresh run, the live font comparison passed or its failure was reported in plain words, every selected family carries a rarity record at or above the floor, every unsupported layer uses the not-applicable object, and the reply contains the validated YAML alone.

仅当满足以下所有条件时，提取操作才算完成：校验器在新运行中返回0，实时字体对比通过（或其失败已通过文字明确报告），每个选定的字体家族都带有达到或超过阈值的稀有度记录，每个不支持的层都使用不适用对象，且回复仅包含经过校验的YAML内容。