style-extractor

样式提取器（Web 样式 + 动效）

从Web UI中提取可复用的设计系统：颜色、排版、间距、组件、状态，以及在相关时的动效（时序、关键帧、延迟链、JS 驱动的行为）。

核心原则：

• 提取视觉语言和交互规则，而不是源产品的信息架构。
• 保留可复用的内容：设计令牌、组件模式、状态变化、布局倾向、动效节奏。
• 剔除产品专属内容：业务文案、应用逻辑、导航树、功能分类、营销宣传。

输出位置（必需）

• 将所有生成的交付物保存到：%USERPROFILE%\\style-extractor\\
• 绝不要将生成的输出保存到技能文件夹（.codex/skills/...）下
• 绝不要在根输出目录中并排放置截图、CSS、JS 和 Markdown 文件

每次提取都必须创建一个专属项目文件夹：

%USERPROFILE%\style-extractor\
  <project>-<style>\
    guides\
      style-guide.md
      motion-guide.md
      evidence-manifest.md
    evidence\
      screenshots\
      assets\
      notes\

每次提取都必须提供以下交付物：

• %USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\style-guide.md
• %USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\evidence-manifest.md
• %USERPROFILE%\\style-extractor\\<project>-<style>\\evidence\\

当动效具有参考价值时，必须提供：

• %USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\motion-guide.md

子目录规则：

• guides/ 仅用于存放最终 Markdown 交付物
• evidence/screenshots/ 仅用于存放 PNG/JPG/WebP 截图
• evidence/assets/ 仅用于存放下载的 CSS/JS/SVG/字体样式表
• evidence/notes/ 仅用于存放原始转储、运行时笔记、跟踪记录或辅助文本文件
• 项目根文件夹中只能包含文件夹；不得放置散落的截图或指南文件

请使用以下参考文件：

• references/output-contract.md — 必需的输出结构和反模式
• references/style-guide-template.md — 样式指南必需的章节
• references/motion-guide-template.md — 动效附录必需的章节
• references/evidence-manifest-template.md — 证据清单必需的章节

参考资料（质量标准）

• references/9nine-visual-novel/ — 样式与动效的最佳实践参考包
• references/motherduck-design-system-reference/ — 优秀的静态样式参考包

从这些参考资料中学习：

• 文档应足够详实，能体现出真实参考手册的质感
• 保留带有代表性原始值的语义令牌表
• 保留包含具体观察值的组件状态矩阵
• 在有助于复用时，保留可复制粘贴的示例和实用的实现说明

不要盲目照搬：

• 冗长、泛泛的填充内容或重复的产品介绍
• 缺乏语义分组、只罗列原始值的内容
• 过多的产品专属品牌或信息架构细节
• 仅为增加文档篇幅、却没有提升复用价值的章节

必须通读参考资料（强制）

开始任何提取之前，请按以下顺序阅读：

1. references/output-contract.md
2. references/style-guide-template.md
3. references/motion-guide-template.md
4. references/evidence-manifest-template.md
5. references/9nine-visual-novel/guides/ 下的所有文件
6. references/motherduck-design-system-reference/guides/ 下的所有文件

参考包选择规则：

• 动效丰富、媒体内容丰富或由分区过渡驱动的源页面 → 使用 references/9nine-visual-novel/ 作为主要质量标准
• 静态结构为主的源页面 → 阅读 references/motherduck-design-system-reference/

在审阅两个参考包之前，不得开始收集证据、截图、执行脚本或起草文档。 如果最终交付物未明确说明以下内容，则视为提取未完成：

• 提取开始前已审阅两个参考包
• 当前目标所采用的主要质量标准参考包

---

工作流

阶段 0 — 输入

1. 项目名称 + 风格／变体名称
2. 来源：URL／Web 仓库／两者兼有
3. 动效评估：网站是否有明显动效？（决定是否需要阶段 1B）
4. 复用目标：Web 应用／营销网站／桌面应用／仅作设计参考
5. 选定的主要参考包：9nine／MotherDuck

收集证据前，先确定哪些来源特征应纳入可复用风格，哪些应排除。使用以下简单筛选标准：

• 保留：设计令牌、间距节奏、字体层级、信息密度、组件语言、状态处理、动效节奏
• 谨慎调整后使用：布局基元、面板结构、导航模式、内容密度
• 排除：产品文案、特定功能流程、品牌故事、应用专属信息架构、领域专属标签

阶段 0.5 — 阅读参考包（必需）

在阶段 1A 开始前完成以下所有事项：

• 阅读 references/output-contract.md
• 阅读 references/style-guide-template.md
• 阅读 references/motion-guide-template.md
• 阅读 references/evidence-manifest-template.md
• 阅读 references/9nine-visual-novel/guides/style-guide.md
• 阅读 references/9nine-visual-novel/guides/motion-guide.md
• 阅读 references/9nine-visual-novel/guides/evidence-manifest.md
• 阅读 references/motherduck-design-system-reference/guides/style-guide.md
• 阅读 references/motherduck-design-system-reference/guides/motion-guide.md
• 阅读 references/motherduck-design-system-reference/guides/evidence-manifest.md
• 选择其中一个参考包，作为当前提取任务的主要质量标准

如果未先阅读这两个参考包，提取结果无效。

阶段 1A — 静态证据收集

步骤 1 — 打开页面并截图

使用 Chrome MCP 工具：

• new_page / select_page / navigate_page
• take_screenshot（适用时使用 fullPage）

最低截图集：

1. 基准状态（整页／整区块）
2. 导航可见 + 激活状态
3. 主要 CTA：默认 + 悬停 + 按下（如果可以）
4. 表单控件：默认 + 键盘焦点可见（如果存在无效状态，也需截图）
5. 模态框／对话框打开状态（如果有）

步骤 2 — 提取计算样式

使用 evaluate_script 获取：

• CSS 变量（:root 和作用域内）
• 通过 getComputedStyle 获取颜色、字体排版、间距
• 组件状态矩阵（默认／悬停／激活／键盘焦点可见／已禁用）

步骤 3 — 获取 CSS／JS 文件内容

• 使用 list_network_requests / get_network_request 下载 CSS 文件
• 适用于离线提取 @keyframes、CSS 变量和媒体查询

需保存在 ...\\evidence\\ 中的最低静态证据：

• evidence/screenshots/ 中的截图
• evidence/assets/ 中下载的 CSS／JS 文件
• evidence/notes/ 中的笔记和选择器清单

---

阶段 1B — 动效证据收集（网站有明显动效时）

静态和动效是相互独立的路径。如果网站没有明显动画，请跳过此阶段。

按以下优先级顺序执行。每个级别都会捕获更多信息；证据充分后即可停止。

级别 1 — 提取 @keyframes（无需交互）

粘贴 scripts/transition-scanner.js，然后调用：

__seTransition.keyframes()

返回样式表中的所有 @keyframes 定义。这种方式结果确定且完整，不会受到时序问题影响。

级别 2 — CSS 过渡扫描（无需交互）

使用同一脚本，调用：

__seTransition.scan()            // scan entire page
__seTransition.scan('.my-section') // scan specific section

返回每个元素的 transition-property / duration / easing / delay，并按模式聚类。即使当前没有动画，这也能显示哪些内容可以动起来。

级别 3 — 交互差异（需要触发交互）

这能捕捉现代网站的主要模式：JS 设置内联样式 → CSS transition 插值。

粘贴 scripts/interaction-diff.js，然后：

// 1. Watch elements you care about
__seDiff.watch([
  '[class*="sectionContainer"]',
  '[class*="illustration"]',
  '[class*="navItem"]',
  'button, a[class*="cta"], a[class*="CTA"]'
])

// 2. Trigger interaction and capture diff
__seDiff.triggerAndCapture(
  () => document.querySelector('.nav-item-2').click(),
  { captureAt: 50, settleAt: 500 }
)

返回：

• diffs — 每个元素内联样式和计算样式的前后变化
• duringAnimations — 在 50ms transition 窗口内捕获的 document.getAnimations()
• afterAnimations — 动画结束后仍在运行的内容

关键洞察：document.getAnimations() 仅在 CSS transition 进行期间返回结果。捕获窗口通常小于 300ms。此脚本会自动在该窗口内捕获。

针对 3 个或更多关键交互重复此操作（切换分区、切换组件、悬停、滚动）。

级别 4 — JS 库提取

粘贴 scripts/library-detect.js，检测第三方动画库。

返回 { globals, instances, dom, fingerprints, assets }。

重点：许多现代网站会将库打包为模块，因此 window.Swiper 等可能是 undefined。此脚本还会检查：

• el.swiper — DOM 元素上的 Swiper 实例（打包后仍可用）
• [data-aos-*] — 元素上的 AOS 属性
• [data-framer-*] — Framer Motion 属性
• 资源 URL 线索（包含库名称的脚本/样式表 URL）

找到实例后，会直接提取配置（Swiper 参数、AOS 设置等）。

级别 5 — rAF 采样（不透明 JS 动效的后备方案）

如果以上级别捕获的信息不足（例如，手写的 requestAnimationFrame 循环），请使用 scripts/motion-tools.js：

__seMotion.sample('.animated-element', { durationMs: 800, include: ['transform', 'opacity'] })

每帧记录计算样式值。可用于推断时长和属性范围，但无法捕获缓动或意图。

级别 6 — 性能跟踪（可选，适用于复杂动效）

对于非常复杂的编排动画：

• performance_start_trace / performance_stop_trace
• 通过 performance_analyze_insight 分析

---

阶段 2 — 抽象与去产品化（必需）

不要将指南写成产品拆解。应将证据转化为可复用规则。

对于每项主要发现，明确分类：

• Reusable：可直接复制为令牌、组件规则、状态规则或动效原语
• Adapted：思路有用，但需要根据目标产品类型调整
• Discarded：不应复制的源产品专属结构或内容

示例：

• 云蓝色表面配色：Reusable
• 文档侧边栏 + 文章导航栏布局：Adapted
• AI 聊天应用的提示词库信息架构：Discarded
• 带视频背景的营销主视觉：根据目标而定，归为 Adapted 或 Discarded

阶段 3 — 语义令牌化（必需）

不要止步于原始值。将重复值转换为语义令牌：

1. 对重复值进行聚类（颜色/圆角/时长/缓动/阴影）
2. 映射用途（CTA/文本/边框/遮罩/激活等）
3. 按意图命名（例如 --color-accent、--motion-300、nav.switch.iconColor）
4. 将证据与令牌一并保留（原始值 + 元素/选择器/截图）

阶段 4 — 编写交付物

从参考模板开始。除非源内容明确要求，否则不要自行更改顶层结构。

交付物 A — 样式指南（必需）

遵循 references/style-guide-template.md。

此文件必须说明：

• 风格给人的感受
• 定义风格的令牌
• 组件在不同状态下的行为
• 可复用的布局倾向
• 如何在不复制产品本身的情况下重建视觉语言

交付物 B — 动效指南（动态内容时必需）

遵循 references/motion-guide-template.md。

此文件必须说明：

• 哪些内容会动
• 什么会触发动效
• 时长、延迟、缓动和关键帧
• 动效由 CSS、transition 还是 JS/库驱动
• 哪些动效原语可在其他产品中复用

交付物 C — 证据清单（必需）

遵循 references/evidence-manifest-template.md。

包含：

• 来源 URL / 仓库引用 / 捕获日期
• 截图列表
• 下载的 CSS/JS 文件或相关说明
• 使用的脚本
• 测试过的交互
• 缺口、阻碍因素和置信度说明
• 已审阅的参考包，以及提取前读取的包内文件

组件状态矩阵至少必须包含：

• 默认 / 悬停 / 激活（按下）/ 焦点可见 / 禁用
• 存在加载中 / 已选中 / 无效状态时，也要包含这些状态

---

脚本参考

脚本	命名空间	用途
scripts/transition-scanner.js	__seTransition	扫描 CSS transition 并提取 @keyframes
scripts/interaction-diff.js	__seDiff	对比前后 inline style 差异 + 即时获取 getAnimations
scripts/motion-tools.js	__seMotion	获取 getAnimations 快照 + rAF 采样
scripts/library-detect.js	（直接返回）	检测库 + 提取实例配置
scripts/extract-keyframes.py	CLI	从下载的 CSS 文件中离线提取 @keyframes

---

质量检查清单

静态

• tokens 包含使用意图（不只是列表）
• 示例可直接复制粘贴（HTML+CSS）
• 至少 5 个可直接复制粘贴的组件示例
• 明确指出可复用、经改编和舍弃的源特征
• 最终指南已剔除产品专属的 IA/文案

动效（适用于动态内容）

• 已提取样式表中的所有 @keyframes（第 1 级）
• 已记录 CSS transition 模式及其持续时间/缓动函数（第 2 级）
• 至少提供 3 个关键交互的前后差异证据（第 3 级）
• 存在 JS 库时，已检测并提取其配置（第 4 级）
• 如存在，至少记录一个“延迟链”
• 已定义动效语义 tokens（持续时间等级 + 缓动函数等级）

自检（完成指南后运行）

1. 每个颜色 token 都有用途映射吗？（不只是十六进制值列表）
2. 每个组件都有包含实际计算值的状态矩阵吗？
3. 仅凭文档就能复现动效吗？
4. 所有可直接复制粘贴的示例都是自包含的（HTML + CSS 位于同一代码块）吗？
5. 如果原产品消失，这份指南仍可作为设计参考吗？
6. 提取样式时，是否避免意外克隆源产品的信息模型？

失败条件

如果出现以下任一情况，不要认为提取已完成：

• 输出只有一个以文字为主的 Markdown 文件，没有证据清单
• tokens 只是缺少语义命名或用途映射的原始列表
• 文档描述源产品的内容多于可复用样式
• 有意义的动态网站没有动效附录
• 示例无法直接实现
• 截图和下载的资源散落在项目根目录，而非归类到子文件夹中