visual-design-system-extractor

视觉设计系统提取器

将视觉参考转换为一份可通过解析器校验的 YAML 设计系统：其中每项结论都能追溯到可见内容，且每个选用的字体都是 Google Fonts 字体系列，并且在运行时的实时字体目录中排名为当前较少使用。

这些检查需要终端、访问实时字体目录的网络连接，以及 Mise 提供的运行时。请从此技能目录运行命令。在接受软件包之前，mise run ci 必须以退出码 0 结束。

此技能接受哪些命令？

将附带参考资料或 URL 的普通请求视为 extract。

命令	结果
help	显示此表格和当前架构版本。
extract <refs>	根据提供的参考资料生成完整的 YAML 设计系统。
fonts <brief>	返回排名靠前的冷门 Google Fonts 候选字体，不进行完整提取。
preview <file>	渲染、截图并评估文档，不重新提取。
validate <file>	对现有提取结果运行架构和字体检查。
maintain <change>	按照以下测试优先规则编辑此软件包。

如果没有附加或无法访问参考资料，请停止并索要图片、屏幕截图、情绪板、风格稿或 URL。不要仅凭描述编造设计系统。

每条命令会返回什么？

• help：以文字形式提供命令表和架构版本。
• extract：仅返回通过校验的 YAML 文档：不加代码围栏，不在前后添加文字，不总结参考资料，也不返回未通过任一检查的文档。文档包含 meta.viability 记录，因此视觉评估结果会随文档一并提供。
• extract 在三次迭代内仍无法通过可行性检查：用文字列出每项未通过的标准及观察到的视觉原因，并给出最近一次渲染和屏幕截图的路径，然后返回标记为 meta.viability.verdict: fail 的文档。绝不声称成功。
• preview：返回渲染和屏幕截图输出及其退出码，然后每项标准各用一行表格列出评估结果和观察到的原因。
• extract 限定为指定章节：仅返回所请求的章节，仍仅提供 YAML。像“给我令牌”这样的随意说法不算限定；只有用户指定章节或明确说“仅”时才进行限定。
• fonts：返回发现结果或集合 JSON，以及一段简短说明，列出适配度评分、作为平局判定依据的稀有度、胜出者优于次选字体的原因，以及按维度给出的任何搭配否决意见。
• validate：返回校验器 JSON，以及一段通俗说明，指出退出码和每个失败路径。
• 对已返回文档的后续修改：先用简短文字总结改动内容及其代价，再返回重新校验后的 YAML。
• maintain：自由文字说明。

确定性意味着相同证据会得出相同的章节、键顺序、置信度标签和不适用对象。判断仅体现在字段值中，且每个值都指向可见证据。

提取如何进行？

使用以下完整计划。在你选择的一个目录中工作，并将所有文件保存在其中：文档使用 extraction.yaml，日志使用 extraction-log.md，每个步骤占一行。无法写入文件时，在回复中保留相同记录。每完成一步，都运行指定的检查；如有失败，先修复再继续。

1. 确认至少有一份参考资料可用且可读。检查：日志中列出了该参考资料。
2. 加载骨架：mise run schema-tools skeleton --output extraction.yaml。字段含义不清楚时，使用 mise run schema-tools field <dotted.path> 或 mise run schema-tools group <name> 查询架构契约，不要阅读整个文件。检查：文件存在且以 meta: 开头。
3. 完全按照骨架中的键顺序复制。不要重命名、重新排序或删除顶层部分；除非用户要求更精简的产物，否则不要添加顶层部分。在某个部分内，你可以将不受支持的层折叠为不适用对象，或将其键与适用性键放在一起；两种形式都可通过检查。检查：部分列表与骨架一致。
4. 先填写 meta、source_analysis 和 confidence_scores，将观察到的事实、推断出的逻辑和推测性外推分别归类。在 meta.rarity_floor 中记录你采用的下限，在 meta.extracted_at 中记录运行日期，并为每份参考资料添加一个 source_types 条目。检查：观察到的事实中没有推测性内容。
5. 填写视觉基础：颜色、间距、布局、网格、尺寸、边框、圆角、阴影、渐变、材质、纹理和光照。每个令牌都应包含 value、usage、visual_grounding、confidence 和 inference_basis；颜色还需包含 hex、rgb 和 hsl，动态效果还需包含 duration、easing 和 trigger。检查：assets/minimal-extraction.yaml 展示了每种类型各一个已填写的令牌，且你的内容符合这些结构。
6. 阅读字体来源规则，根据可见的字体证据填写 assets/font-brief.json，然后一次性填写所有角色：mise run font-set -- --brief <brief.json>。适配度和易读性优先；稀有度用于打破平局，配对检查可以否决候选项。检查：命令以 0 退出，unfilled 为空，且 pairing.passes 为 true。
7. 填写 typography，记录 catalog_snapshot、完整的 rarity 块，以及每个选定字体系列的 fit 块，其中包含 fit_score、legibility_score 和 evidence。检查：所有稀有度块共用同一个 retrieved_at 日期，且对每个字体系列运行 mise run font-verify -- --family "<name>" 均以 0 退出。
8. 填写体验层：动态效果、动画、摄像机、构图、环境、场景、服装、道具、图标设计，以及图像和渲染风格。检查：不受支持的层使用不适用对象，而不是猜测。
9. 按架构顺序填写产品层：accessibility、interaction_design、ui_patterns、sound_design、narrative_tone、emotional_palette、worldbuilding、styling_rules、dos_and_donts、token_dependencies、dynamic_tokens、responsive_rules、state_variants、platform_adaptations、ai_generation_prompts 和 implementation_notes。检查：mise run schema-tools sections 列出的键与你的键顺序一致。
10. 将整个系统渲染到页面：mise run render-preview extraction.yaml --output preview.html。检查：命令以 0 退出且 problems 为空，这表示每个必需的令牌组都已呈现在页面上。
11. 截图：mise run screenshot-preview preview.html --output preview.png。检查：PNG 文件存在。
12. 查看 PNG，并根据以下八项标准进行判断，每项给出一个结论和一个观察到的理由。检查：结论没有重复令牌值，而是描述图像所呈现的内容。
13. 对任何未通过的标准，修改有问题的令牌，然后重复步骤 10 至 12。检查：最多迭代三次。第三次仍未通过时，停止并报告未通过的标准，不要声称成功。
14. 将通过的判断记录在 meta.viability 中：rendered_file、screenshot_file、iterations、verdict 和 criteria 列表。检查：下方列表中的每个标准名称都恰好出现一次。
15. 运行门禁：mise run validate-design-system-yaml extraction.yaml。必须以 0 退出。若以 1 退出，请修复列出的所有问题后重新运行。检查：最新一次运行输出 "valid": true。
16. 仅返回通过验证的 YAML，不附带验证报告。

验证器会报告什么？

报告是 stdout 上的一个 JSON 对象。只有退出码为 0，且以下每个字段都符合要求，文档才算通过。

• valid：仅当 errors 为空时为 true。
• errors：每个问题用一个句子说明。顺序问题会指出位置以及该位置上的键。
• rarity_floor：本次运行所执行的最低值，初始为 70.0；如果文档记录了更高的 meta.rarity_floor，则提高至该值；如果 --min-rarity-percentile 标志设置了更高的值，则提高至该值。
• live_fonts_checked：当记录的排名与实时目录进行过比较时为 true。为 false 表示跳过了比较，因此结果未经验证，回复必须说明这一点。
• confidence_markers：文档包含的 confidence 键数量。该数量必须达到 --min-confidence-markers 的要求，默认值为 5。
• font_entries：检查过的已选字体系列数量，包括主要字体、辅助字体和所有稀有候选字体。
• viability_recorded：仅当 meta.viability 包含渲染文件、截图文件、迭代次数，以及每项标准的一个判定时为 true。为 false 表示系统尚未经过检查，因此本次运行尚未完成。

字体规则是什么？

在选择字体之前，通过 mise run validate 加载字体来源规则。该规则定义了实时目录的权威性、稀有度下限、适配度与易读性门槛、作为平局判定依据的稀有度、常见字体例外、字体组合、回退规则、必需记录以及数据源故障约定。第 7 步仍负责每个已选字体系列的记录；数据源不可用会阻止字体排版得到验证。

如何证明系统可用？

架构验证能证明结构正确，却不能证明系统可用。渲染门禁负责验证其余部分。mise run render-preview 会直接从文档生成独立页面，因此结果可复现，而非手工编写；它会在浅色和深色模式下（如果文档声明了两种模式）应用每个设计令牌，覆盖页眉、导航栏、主视觉区域、达到阅读长度的正文、每个标题级别、各种状态的按钮、表单字段、表格、卡片网格、代码块、页脚和令牌清单。mise run screenshot-preview 会截取完整页面。

查看截图，评估以下八项标准，并写明图像实际呈现的内容，不要只写一个没有依据的数字：legibility、contrast、hierarchy、font_pairing、spacing_rhythm、color_harmony、state_distinction 和 reference_fidelity。任何一项未通过，都应回到令牌进行调整，而不是修改判定措辞。循环最多进行三次；如果运行结束时仍有未通过项，应报告未通过的标准，而不是发布结果。

何时加载什么？

Schema 契约是机器可读的 YAML，包含章节顺序、字段规则、字体规则、语法规则和自检清单。请通过 mise run schema-tools 查询，而不是全文阅读。在处理任何字体字段之前，先加载字体来源规则。仅在编辑此软件包时，才加载生成契约。

通过骨架命令加载 assets/schema-skeleton.yaml，在发现字体之前加载 assets/font-brief.json，并使用 assets/minimal-extraction.yaml 获取最简的合格文档。通过相应的 Mise 任务运行可执行检查。仅在更改脚本行为时运行 mise run test；处理行为或时序工作时，通过 mise run evals 加载 evals/。

准备运行相应命令时，加载 examples/ 中的一个文件，因为每个文件都是真实的转录，包含真实的退出代码。

• 在回答 help 前，先查看 examples/help.md。
• 首次提取前，先查看 examples/extract.md；完整的通过验证的文档见 examples/extract-output.yaml。
• 运行发现前，先查看 examples/fonts-brief.md，了解如何将填好的简报转换为命令行。
• 验证他人编写的文件前，先查看 examples/validate.md。
• 编辑此软件包前，先查看 examples/maintain.md。
• 文档已存在且用户要求寻找更冷门的字体时，查看 examples/make-it-rarer.md。
• 渲染前，查看 examples/viability-loop.md，了解当前捕获内容、八项标准的判定和重试规则。
• 验证器报告章节顺序问题时，查看 examples/failure-section-order.md；这是此技能最常导致的失败。

如何维护此软件包？

资源检查：使用此处列出的软件包文件前，先运行 mise run validate。

对于 maintain，YAML 专用响应契约不适用。先确认失败状态：检查项拒绝了有效输入、缺少某项行为，或存在用户明确指出的缺口。添加针对性测试，观察测试失败，然后进行能使测试通过的最小改动，最后运行本文件顶部列出的五项检查。每项检查都必须以退出代码 0 结束，才能报告结果。详细内容放在 references/ 中，可执行检查放在对应的 Mise 任务后，模板放在 assets/ 中，示例运行放在 examples/ 中。规则变更导致示例过时时，需在同一次编辑中更新该示例。

注意事项

• 信息流报告的排名会超过家族数量。分母是排名上限，也就是本次运行中的最高排名，因此稀有长尾仍能保持排序。请准确记录返回的排名和上限。
• 当两个家族报告相同的百分位时，popularity_rank 较高的那个更稀有。发现过程已按此方式排序，因此第一行就是最稀有的匹配项。
• --subset 和 --variable-only 会大幅缩小稀有长尾，并可能隐藏最稀有的家族。仅在参考要求时使用，并在放宽其中一项时说明取舍。
• meta.rarity_floor 具有约束力。验证器会读取该值，并将自身下限提高到与之相同，因此记录 90.0 后，之后的每次重新验证都会强制执行 90.0。
• 上个月稀有的家族今天可能已不再稀有。默认验证会将记录的排名与实时目录对比，并在数据发生偏移时失败，这说明关卡正在发挥作用。
• 即使周围的说明为常见界面默认值辩护，也会按名称拒绝这些默认值，除非 common_face_reason 指明可见证据。
• 百分位保持在 100.0 以下，因为分母是排名上限加一，因此最稀有的家族不再达到饱和值，同值排名也不再被共同的 100.0 隐藏。
• 如果更稀有的外观未达到易读性下限，就应拒绝，而不是将其作为取舍来辩解。请报告为已拒绝，并指出下限。
• 在所有模式下，内联链接都使用强调色角色，因此深色画布系统应通过更改强调色令牌来修复未通过的 contrast 判定。链接若保留浏览器默认样式，这是测试框架的问题，而不是令牌选择。
• 如果任何令牌值都无法修复某项标准，请明确说明并指出测试框架的限制。通过修改页面来掩盖问题不算通过。
• “不寻常”或“鲜为人知”等说法不能证明任何事情。rarity_reason 用于解释测量结果；它不能取代该结果。
• 后备字体栈必须列出实际存在的家族，并以通用字体家族结尾。
• 不要按不同小节分别运行验证。捆绑的验证器是唯一的机械关卡。
• 不要从头到尾阅读架构契约。一次查询一个字段或一个分组。
• 小节顺序、置信度标签和字体下限都来自架构契约。在那里更改规则，所有关卡都会随之更新；在脚本中硬编码值会破坏这种关联。

何时算提取完成？

只有在新一轮运行中验证器以 0 退出，且 live_fonts_checked 为 true（或用直白的文字报告其失败）；每个选定的家族都带有达到或超过强制下限的稀有度记录，以及达到其角色下限的 fit 区块；字体集合通过配对检查；每个不受支持的层都使用“不适用”对象；渲染后的页面已截图，并通过全部八项标准，且 meta.viability.verdict: pass；回复中只包含经过验证的 YAML 时，提取才算完成。在图片通过之前，运行尚未完成，也不得报告为已完成。

工厂执行契约

验收结果：根据视觉证据提取特定来源的设计令牌系统，并用当前渲染输出验证。保留当前视觉令牌提取行为，同时变更最小责任归属方。

1. 运行 mise run ci 冻结当前软件包并记录其摘要。
2. 运行 mise run domain-research-policy，然后评判当前视觉令牌提取来源及反证。
3. 针对指定的视觉令牌提取操作运行 mise run agentic-request。将语义选择交由模型处理。
4. 运行 mise run decision-policy、mise run ci 和行为评测。返回到最底层的失败责任归属方。
5. 运行 mise run invocation-policy -- <receipt>，并说明每项任务或其领域特定的不适用情况。
6. 可选择运行 mise run improvement-policy。仅当没有受保护维度退化时，才保留一个变更维度。

仅在需要其契约时，才通过 mise run use-case-policy 加载 assets/use-case-contract.json，并通过 mise run evals 加载 evals/evals.json。

Mise 负责可重复的机制、顺序、收据和检查。模型负责代码无法提供的解读、因果判断、创意工作和直接感知。遇到授权缺失、证据过时或门禁失败时，立即停止。