用途
ui-kit-from-code 用于把项目现有的设计系统（颜色 token、尺寸阶梯、组件）从代码或运行中的网站 URL 提取出来，生成一个独立的 HTML 参考页，供设计师、开发者或 agent 像使用 Figma UI kit 一样查阅和复用。触发场景包括“把它拆成 UI kit”“用 HTML 做 Figma UI kit”“设计系统参考页”“可复用的组件画廊”。常见于项目已有稳定 token 和组件、但还没有页面把它们汇总起来的时候。
非目标：不创作新系统或调整审美；不克隆整页用于运行；不导出真正的 Figma 文件、Storybook 或 npm 包；不修改项目的组件代码。
主要能力
- 从 token 源（TS/CSS/Tailwind/Compose 等）运行出 JSON token，转成 CSS 变量
--<ns>-<role>和--k。 - 读取代码中的组件尺寸、变体、名称，生成只依赖变量的
.<ns>-*类。 - 对运行中的网站 URL 执行 discover.mjs：同源链接 BFS、滚动内部容器、点击展开 accordion/tab/details、按类型+样式+子形状生成签名去重，并通过 CDP CSS.forcePseudoState 强制 HOVER/ACTIVE/FOCUS-VISIBLE 状态，通过 aria-pressed/selected/current、data-state、class is-active 合并 SELECTED 变体。
- 产出 inventory.json、crops/*.png 和整页截图。
- 生成 ui-kit.html，包含 7 个必需部分：粘性控制栏、侧边目录、Intro、基础（颜色/字体/形状/布局尺寸）、组件、示例屏幕、脚本。
- 通过
--coverage检查每个 pattern 是否有data-sig或ui-kit-skip，状态是否有data-sig-state，要求 100% 覆盖。 - 用 Playwright 验证：0 个 JS 错误、390px 下 scrollWidth - innerWidth = 0、亮色/暗色/示例屏幕截图。
- 可将通过验证的 kit 同步到 PRIVATE 仓库 Rheinmir/ui-kits（W09），生成
<id>/vN/index.html、manifest.json 和 registry.json 记录。
使用方式
输入需要：token 源（生成颜色、字体、形状、尺寸的文件或函数）、组件清单（类型名 + 分组）、目标平台（mobile/desktop/两者及真实框尺寸）。输出为 docs/ui-kit.html（或用户指定路径）、来源报告、Playwright 证据，以及可选的私有仓库版本。
主要流程：W01 判断 token 源和组件清单；W01b 用 NODE_PATH=$(npm root -g) node references/discover.mjs <url> --out <scratch>/disc --pages 32 --saturate 4 做发现；W01c 人工查看截图并归类 pattern；W02 写临时测试/脚本 dump token JSON 后删除；W03 精简为 ROLES + PALETTES 嵌入模板；W04 编写基础与组件部分；W05 拼接示例屏幕；W05b 运行 node references/discover.mjs --coverage <scratch>/disc/inventory.json <kit.html>；W06 用 Playwright 验证；W07 人工检查截图；W08 汇报；W09 用 python3 references/sync-kit.py <kit.html> --source <目录|URL> 同步。
适用场景
- 项目已有 token 和组件，但缺少统一的设计系统参考页。
- 需要从运行中的网站提取设计系统，且网站允许爬取。
- 需要生成可离线打开、自包含的 HTML 参考页。
- 需要把 kit 同步到私有仓库做版本管理。
限制
- 找不到 token 源（颜色硬编码分散在组件中）时只能做部分提取，需注明“无 token 源，颜色从组件推断”。
- 网站禁止爬虫（robots.txt 或条款禁止自动采集）时，discover.mjs 会停止并返回 rc 3，不能自动添加
--i-have-permission，需用户确认有许可，或改用 B05 让用户自行保存页面。 - 来源是他人网站时，不得嵌入其图片、logo、wordmark SVG 或受版权保护内容，需用占位块注明。
- 仅同步通过验证的 kit，且只能同步到 PRIVATE 仓库；版本只增不覆盖。
- 状态依赖 JS 时可能漏测；页面很重时需要提高
--page-timeout。 - 发现达到页面预算上限且仍有新 pattern 时，需告知用户增加
--pages或收窄--include。 - 项目只有单一平台时，示例屏幕部分只包含该平台并注明原因。
- Playwright 报 JS 错误或横向溢出，修复 3 轮后仍失败则停止并报告剩余错误。
- 同步失败（网络、权限、仓库非 PRIVATE）时脚本输出“未同步，原因…”并返回 rc 0，本地 kit 仍有效。