Web Design Extractor

---
name: web-design-extractor
description: 从公开网站或已获授权的网站 URL、一个或多个网页截图中提取有证据支撑、可直接用于实现的 `design.md`。适用于需要为复刻、设计系统文档或 UI 实现简报逆向分析网站的视觉系统、布局、组件、响应式行为、内容层级或交互状态的场景。
---

# 网站设计提取器

基于可见证据制作忠实的设计规格。必须区分已观察的事实与视觉推断；不得声称掌握输入资料未能证明的源 CSS、行为或资源。

## 选择证据路径

**先探环境，再选路线——按能用的最强的来，别一上来就退源码。**

```text
① 用户项目里已有 playwright   → 用它（代码最少，也不让人白装一个浏览器）
② 机器上有 Chrome / Edge      → 用 scripts/browser-extract.mjs（零依赖，Node ≥ 22）
③ 都没有                      → 退源码路线，并强制标注「转录边界」
```

具体怎么做、产物怎么读、有哪些坑，见 [references/browser-route.md](references/browser-route.md)。

**两条路线是叠加关系，不是二选一**：源码给「这个站定义了哪些令牌、叫什么名字」，
浏览器给「哪些真的在用、用成了什么样」。能同时走就走两条。

按输入形态选：

- **仅 URL（有浏览器）**：跑 `scripts/browser-extract.mjs`，拿计算样式、四档视口实测和截图。
  这样拿到的值是 `[OBSERVED: URL]`，可以直接当复刻约束用。
- **仅 URL（没有浏览器）**：退源码路线，见下面的降级路径。这样拿到的值是 `[INFERRED]`。
- **仅截图**：按原始尺寸分析图片。测量值、布局规则和未展示状态均应视为推断，除非图片能够直接证明。
- **URL 加截图**：以用户说明视口下的截图为视觉事实基准。使用 URL 验证结构和计算样式；发现差异时明确标注，不可静默合并。
- **多张截图**：将其作为不同视口或状态样本进行对比。只有样本显示断点变化时，才能认定布局具备响应式行为。
- **没有浏览器控制能力时（降级路径）**：只能拿到服务端返回的 HTML 和其中写明的 CSS，
  拿不到渲染后的计算样式、断点行为和截图。**这时不能假装走了上面几条路径**，必须：

  1. 在 `design.md` 开头写一节「**证据边界**」，逐项列清**有什么**（HTML 结构、声明的 CSS 变量、
     内联样式、字面写死的值）和**没有什么**（计算样式、断点行为、截图、字体文件、交互态）。
     注意：**这一节两种路线都要填**，正常运行时也要写清「本次覆盖了什么 / 没覆盖什么」，
     无缺口就写「无」——浏览器路线一样会只覆盖首屏、不采交互态；
  2. 字面写出来的令牌值记 `[OBSERVED: URL]`；**「哪个令牌用在哪个元素上」一律记 `[INFERRED]`**——
     源码里两处都写着 `#fff`，不代表它们用的是同一个东西；
  3. 断点、悬停、焦点、空态、错误态一律 `[UNKNOWN]`，不要用「常见做法」补一个上去；
  4. 在交付说明里说明这是降级运行，并给出补全证据的具体办法（补一张截图；或换到有浏览器
     控制能力的环境重跑一次）。

  降级不是问题，**把降级说成完整运行才是问题**。

用户未提供 URL 或图片时，要求其提供。仅当目标视口会实质影响结果时，才询问视口信息。

## 收集证据

### 来自 URL

1. 打开用户提供的准确 URL。默认只处理公开可访问的内容。
   需要登录、私有或付费墙后的页面能不能做，**是用户的合规判断，不是本 Skill 的判断**——
   用户要求分析就分析，做完在「证据」一节注明这部分内容来自用户提供的访问权限。
2. 记录最终 URL、页面标题、视口、采集时间与可见页面状态；在有助于保留视觉证据时截取页面截图。
3. 按视觉顺序识别页面区域：全局外壳、导航、首屏、主要区块、重复内容模式、行动号召、表单与页脚。
4. 读取具有代表性的可见元素及其计算样式。优先记录字体、字号、字重、行高、文字/背景/边框颜色、间距、圆角、阴影、网格或弹性布局，以及过渡或动画属性。
5. 统计并分类重复出现的可见组件，如按钮、链接、输入框、卡片、列表、表格和导航。检查少量代表项，不要抓取整个页面。
6. 只记录已观察到的交互或状态。悬停、焦点、加载、空态、错误、展开或移动端状态未出现时，标为未知，不得虚构。

### 来自截图

1. 记录文件名、原始像素尺寸，以及用户提供的视口或设备信息。
2. 先按对齐、重复、对比、留白和内容层级将图片划分为区域，再命名组件。
3. 推断比例化排版层级、间距节奏、列结构、颜色角色、圆角、阴影、图像处理和断点；每项推断都要明确标注。
4. 仅提取解释层级或组件结构所需的可见文字；模糊的 OCR 文字不得作为权威文案呈现。
5. 不得仅从像素推断 HTML 语义、DOM 结构、精确字体文件、精确 CSS 值或未展示的交互。

## 编写规格

起草前阅读 [references/design-md-template.md](references/design-md-template.md)。将完成的结果写入用户指定目录中的 `design.md`；未指定位置时写入当前项目，且不得覆盖已有 `design.md`，应改为 `design-extracted.md`。

写作前查找 `docs/product/` 中与当前项目、当前端（`c-end/` 或 `admin/`）对应的产品体验基线。基线存在时，在 `design.md` 中增加“产品基线映射”：列出可复用的导航、Token、组件或页面模式，并标记外部证据与已确认基线的冲突。外部网站或截图只能作为参考，不得静默覆盖当前产品的品牌、领域术语、信息架构或核心交互模式。

产品基线不存在时，只记录当前提取结果；不要仅凭一次外部参考建立完整的产品级规范。若用户正在定义首版产品体验，建议先使用 `product-experience-foundation`。

全文使用以下证据标签：

- `[OBSERVED: URL]`：渲染后的 DOM、计算样式或直接可见的页面事实。
- `[OBSERVED: SCREENSHOT]`：由提供截图直接支持的可见细节。
- `[INFERRED]`：合理的重建设计决定。
- `[UNKNOWN]`：输入资料未能建立的实质性实现细节。

只有 URL 检查能够确认时才使用精确数值。来自截图的数值应使用相对描述或明确的近似值。分别说明品牌意图、视觉令牌、页面架构、组件、行为、无障碍观察结果和重建规则。不可妥协的复刻要求使用“必须”，建议使用“应当”。

## 交付前验证

- 包含来源、采集日期、视口和证据类型。
- 每一项非显然结论均标为已观察、推断或未知。
- 每个重复组件都有清晰的结构、变体、可见状态，以及证据支持时的响应式行为。
- 区分实际观察到的无障碍事实与推荐要求；不得仅凭视觉检查声称符合 WCAG。
- 检查排版、颜色、间距、圆角、阴影和动效规则之间没有相互矛盾。
- 只写用户给到的内容。用户没提供的私有数据、隐藏内容或访问不到的资源，不要猜、不要补——
  用户提供了就照写，并在「证据」一节注明来源。
- 基线存在时，确认已记录“产品基线映射”和所有实质冲突。
- 「**证据边界**」一节已填——**两种路线都要填**，无缺口写「无」。
- 若发生过重定向，最终 URL 与地区 / 语言影响已写进「证据」表，没有把港币版当成美版来描述。
- 写完扫一遍中文乱码：`grep -rnI $'\xef\xbf\xbd' <design.md 所在目录>`

交付时简要说明输出文件、所用证据与最重要的剩余未知项。