前端样式提取器 是做什么的?
目标
从源前端产出一份有证据支持的、框架中立的可移植设计系统包 v1.0.0。输出是供 frontend-style-adapter 使用的交接契约,不是复制的源代码,也不是逐像素克隆。
在编写捆绑包前先阅读 references/CONTRACT.md。在检查过程中阅读 references/INSPECTION_CHECKLIST.md。不要凭空编造样式值,也不要把推断出的模式当作观察事实。
输入
- 来源:仓库根目录/工作区、选定的目录,或一个可访问的已渲染网站。
- 可选:特定页面/组件、主题、断点、设计保真度、输出路径。
- 默认值:来源 = 当前仓库;范围 = 代表性共享 UI + 仓库中可发现的路由/页面;输出 = 源仓库内的
design-system/portable/(除非用户要求其他位置)。 - 一个不含可访问源 CSS 或计算后样式的公共 URL 属于仅视觉来源。除非能通过工具测量,否则将精确的像素/颜色/间距标记为推断值。如果环境无法打开网站,则解释此限制,而不是捏造分析。
工作流
- 了解情况,不修改源码。 检查 git 状态、项目结构、包清单、框架与样式栈、路由/页面结构、全局样式、主题提供者、组件库和设计令牌。遵守
AGENTS.md和仓库说明。绝不读取.env、密钥或不相关数据。 - 运行可选的启发式库存(仅使用标准库,而非权威 CSS 解析器):
python3 <skill-root>/scripts/style_inventory.py <source-root> --out <temporary-path>/style-inventory.json尽可能使用仓库外的临时路径。阅读摘要;直接在代码/渲染 UI 中验证重要声明。 - 采样代表性 UI: 全局外壳、导航、标题/文本、按钮、字段/表单、卡片、表格、模态框、提示框、加载/空/错误状态;检查桌面和移动端、悬停/聚焦/禁用状态、浅色/暗色主题(如果支持)。同时采样常见和不常见的路由。记录检查过的表面与跳过的表面。
- 解析规则层次结构: 显式令牌/配置 → 共享组件 → 重复页面模式 → 一次性例外。不要将单个页面的布局误认为全局规则。保留有意义的语义令牌和别名(例如
var(--brand-primary)),仅在验证后才说明实际解析值。 - 记录来源: 每个令牌和每条结构规则都需要
origin、confidence和具体的evidence。优先使用文件路径+行号/符号、计算样式观察结果或截图/视口引用。每个未经支持的推断都必须标注为“推断”。说明所有限制、未检查的页面、依赖/资产许可的不确定性。 - 编写捆绑包 到指定输出路径。必需文件:
manifest.json、tokens.json、rules.json、README.md、typography.md、layout-rules.md、component-rules.md、interaction-rules.md、responsive-rules.md。可选的assets.md用于图标/图片/字体的考虑。参见references/CONTRACT.md和assets/example-bundle/了解格式;将所有示例内容替换为源特有的观察结果。使用可移植的语言(组件契约和设计意图),而非仅使用特定框架的实现作为描述。 - 验证:
python3 <skill-root>/scripts/validate_bundle.py <bundle-path>。修复所有错误。手动检查未知/低置信度项。如果尚未执行浏览器/截图比较,不要声称已测试视觉保真度。 - 报告: 源与检查的表面、框架/样式方法、输出路径、令牌/规则数量、覆盖率/不确定性、验证器结果,以及交接用法:使用设计系统路径调用
frontend-style-adapter。
硬约束
- 提取设计语言,而非业务逻辑、文案、专有资产或实现内部细节。
- 不得修改应用源码、安装包、重写配置或自动提交。允许创建请求的捆绑包。
- 除非用户明确授权且权利清晰,否则不得将徽标、字体二进制文件、许可图片/图标复制到捆绑包中;应描述其外观、原始引用和许可注意事项。
- 不得传输
.env、凭据、用户数据、实时 API 响应或密钥。 - 保留单独的浅色/暗色主题和响应式规则(如果存在),不要平铺为单一样式。
- 确切的实现细节应放在
evidence/备注中;需求应保持跨框架可移植。 - 清晰优先于数量:高价值的已文档化模式胜过数百个无证据的令牌。
- 如果没有可运行的 UI/浏览器,请在清单中报告
visualVerification: "not_performed"。
完成条件
捆绑包通过验证;每个导出的项都可追溯;全局规则与例外分开;可访问性/响应状态已处理;报告列出了已知的差距。