把视觉参考图或网址逆向工程为可验证的设计系统 YAML

当需要从截图、情绪板、品牌板、电影剧照、产品界面图或线上站点 URL 提取生产级设计令牌、艺术方向与动效规则时，用可追溯证据生成一份通过校验的 YAML 设计系统。

适用场景

解决思路

1. 确认至少有一个参考物可用且可读，并在日志中记录该参考物的名称。
2. 用 `mise run schema-tools skeleton --output extraction.yaml` 加载骨架；字段含义不清时用 `mise run schema-tools field <dotted.path>` 或 `mise run schema-tools group <name>` 查询 schema 契约，不要通读整个文件。
3. 严格复制骨架的键顺序，不重命名、不重排、不删除顶层 section，也不额外新增（除非用户要求更窄的产物）；section 内部可把不支持的层折叠为 not-applicable 对象，或保留其键与适用性键并列，两种形式都通过。
4. 先填 `meta`、`source_analysis` 和 `confidence_scores`，把观察到的事实、推断的逻辑、推测的外推分开放置；在 `meta.rarity_floor` 记录本次执行的稀有度下限，在 `meta.extracted_at` 记录运行日期，每个参考物对应一条 `source_types` 条目。
5. 填写视觉基础层：color、spacing、layout、grid、sizing、borders、radii、shadows、gradients、materials、textures、lighting；每个 token 都带 `value`、`usage`、`visual_grounding`、`confidence`、`inference_basis`，颜色额外带 `hex`、`rgb`、`hsl`，动效额外带 `duration`、`easing`、`trigger`；对照 `assets/minimal-extraction.yaml` 中每种 token 的示例形状。
6. 阅读 `references/font-sourcing.md`，根据可见的字体证据填写 `assets/font-brief.json`，然后用 `mise run font-set -- --brief <brief.json>` 一次性填满所有字体角色；适配度与可读性决定选择，稀有度用于打破平局，配对检查可否决获胜者。
7. 填写 `typography`，为每个选中的字族记录 `catalog_snapshot`、精确的 `rarity` 块，以及带 `fit_score`、`legibility_score`、`evidence` 的 `fit` 块；确保所有 rarity 块共享同一个 `retrieved_at` 日期，并对每个字族运行 `mise run font-verify -- --family "<name>"` 且退出码为 0。
8. 填写体验层：motion、animation、camera、composition、environment、setting、wardrobe、props、iconography 以及图像与渲染风格；不支持的层使用 not-applicable 对象而不是猜测。
9. 按 schema 顺序填写产品层：`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` 为空（即每个必需 token 组都到达页面）。
11. 用 `mise run screenshot-preview preview.html --output preview.png` 截图，确认 PNG 文件存在。
12. 查看 PNG，对八项标准逐一给出判定和一条观察到的理由：`legibility`、`contrast`、`hierarchy`、`font_pairing`、`spacing_rhythm`、`color_harmony`、`state_distinction`、`reference_fidelity`；判定理由要描述图像所示，不能只是重复 token 值。
13. 任何标准失败时，修改有问题的 token，然后重复渲染、截图、判定三步；最多迭代三次，第三次仍失败就停止并报告失败标准，不得声称成功。
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，不带校验报告、不带代码围栏、不带前后说明文字。
17. 字体选择前先通过 `mise run validate` 加载 `references/font-sourcing.md`，该文件定义实时目录权威、稀有度下限、适配与可读性门槛、稀有度作为平局裁决、常见字体例外、集合配对、回退规则、必需记录以及 feed 失败契约。
18. 注意 feed 报告的排名可能高于字族总数：分母是排名上限（本次运行中的最高排名），精确记录返回的排名与上限。
19. 两个字族百分位相同时，`popularity_rank` 更高者更稀有；发现流程已按此排序，所以第一行就是最稀有的匹配。
20. `--subset` 和 `--variable-only` 会大幅缩小稀有尾部并可能隐藏最稀有的字族，只在参考物要求时使用，并在放宽时说明代价。
21. `meta.rarity_floor` 具有约束力：校验器会读取它并把自己的下限提升到相同值，所以记录 90.0 会让之后每次重新校验都强制 90.0。
22. 默认校验会把记录的排名与实时目录对比，排名漂移即失败，这是门禁在正常工作；上个月稀有的字族今天可能不再稀有。
23. 常见界面默认字体即使周围文字为其辩护也会被按名拒绝，除非 `common_face_reason` 给出可见证据。
24. 百分位保持在 100.0 以下（分母是排名上限加一），使最稀有的字族不再饱和，平局也不再隐藏在共享的 100.0 之后。
25. 更稀有但未通过可读性下限的字族是拒绝而非可争辩的取舍：报告为拒绝并说明下限。
26. 内联链接在所有模式下都采用强调色角色，所以深色画布系统通过修改强调色 token 来修复失败的 `contrast` 判定；链接停留在浏览器默认样式是测试框架 bug，不是 token 决策。
27. 当某项标准无法用任何 token 值修复时，明说并指出测试框架的限制；编辑页面来掩盖问题不算通过。
28. `rarity_reason` 解释测量到的数字，绝不能用「不寻常」「被忽视」之类词语替代。
29. 回退字体栈必须命名真实存在的字族，并以通用字族结尾。
30. 不要按 section 分别运行校验；捆绑的校验器是唯一的机械门禁。
31. 不要通读 schema 契约，一次只查询一个字段或一个组。
32. section 顺序、置信度标签和字体下限都来自 schema 契约；在契约中改规则所有门禁都会跟随，在脚本中硬编码值会破坏这种联动。
33. 只有满足以下全部条件才算完成：新一次校验退出码为 0 且 `live_fonts_checked` 为 true（或其失败已用平实语言报告）、每个选中字族都有达到或超过强制下限的稀有度记录且 `fit` 块通过其角色下限、字体集合通过配对检查、每个不支持的层使用 not-applicable 对象、渲染页面已截图并通过全部八项标准且 `meta.viability.verdict: pass`、回复中只包含通过校验的 YAML。
34. 维护本包时（`maintain`）：先建立失败状态（门禁拒绝有效输入、缺失行为或用户指出的确切缺口），添加聚焦测试并看它失败，再加最小改动使其通过，然后运行文件顶部列出的五项检查，每项退出码为 0 才能报告；长细节放 `references/`，可执行检查放具名 Mise 任务，模板放 `assets/`，完整运行记录放 `examples/`；规则变更使示例过时就在同一次编辑中更新该示例。

适用边界 · 注意事项

• 不用于生成图像。
• 不用于无需先解码参考物的普通前端工作。
• 没有附带或可访问的参考物时不要凭描述凭空发明设计系统，应停下来索要图像、截图、情绪板、风格帧或 URL。