extract-design-md

从网站提取 DESIGN.md

给定一个可访问的 URL，生成一份 DESIGN.md — 包含 YAML 设计令牌（颜色、排版、rounded、spacing、components），以及按标准顺序排列的说明文字 — 内容应足以交给编码 Agent，让它构建与源网站风格匹配的新 UI。

核心思路（来自研究）： 令牌与网站的 CSS 自定义属性和计算样式大致一一对应，因此繁重工作只需在浏览器中低成本提取，而非依赖视觉分析。屏幕截图仅用于撰写说明文字。官方检查器是免费的质量门槛。

URL ─▶ 1 DISCOVER ─▶ 2 EXTRACT TOKENS ─▶ 3 HARVEST COMPONENTS
        ─▶ 4 CAPTURE FEEL ─▶ 5 SYNTHESIZE ─▶ 6 VALIDATE ─▶ DESIGN.md

前置条件

此技能需要调用三个外部工具 — 运行前请确保它们都可用：

• playwright-cli 位于 PATH 中 — 浏览器内提取和屏幕截图都通过它运行。使用 npm install -g @playwright/cli@latest 安装一次，然后运行 playwright-cli install --skills（需要 Node.js 18+）。检查方式：which playwright-cli。
• 可访问的 Firecrawl 实例 — 用于发现页面（firecrawl map）以及可选的文案抓取。托管 API、自托管或本地实例均可；如果 Firecrawl 无法访问，技能会改用 playwright 发现链接（页面覆盖范围较窄）。运行前请确认实例可正常响应。
• npx（Node.js）— 按需拉取官方 @google/design.md 检查器，用于质量检查。如果不可用，技能仍会写入文件，并注明“已跳过 lint”。

如果你的 Agent 对网络或文件系统访问进行了沙盒限制，请在运行前允许此技能发起的出站请求（无头浏览、Firecrawl、npx）。

令 SKILL = 此技能所在目录。选择一个稳定的 playwright 会话名称，例如 S=designmd。

标志

标志	默认值	作用
<url>	必填	入口 URL
--pages <n>	5	最多采样页面数
--pages-list <paths>	自动	固定具体页面（跳过确认提示）
--no-screenshots	截图开启	跳过观感分析阶段；说明文字将更多依赖令牌名称和文案
--theme <auto|light|dark|both>	auto	auto 自动检测；both 强制生成双主题；light/dark 固定为单一主题
--out <dir>	.design_mds/<domain>-YYYYMMDD/	输出文件夹
--no-lint	lint 开启	跳过检查器（若 npx 不可用则自动跳过）

---

阶段 1 — 发现页面

firecrawl map "<url>" > "<out>/raw/map.json"

将返回的 URL 按页面类型分类，并为每类选择最匹配的页面（始终包含首页），最多不超过 --pages（默认 5）：

• 首页（输入的 URL，始终包含）— 核心配色、字体和 Hero CTA
• 定价 / 产品 — 卡片、切换控件、表格
• 身份验证 / 登录 / 注册 / 联系方式 — 输入框、表单字段
• 博客 / 文档 / 更新日志 — 长篇正文的排版风格
• 品牌 / 关于 / 设计 — 通常会明确列出颜色和字体；价值很高

显示自动挑选的列表，并在抓取前接受添加 / 删除 / 替换操作（只需给出一个简短提示；如果指定了 --pages-list，则跳过）。没有匹配页面时跳过该类型 — 不要强行采样。如果 Firecrawl 无法使用，则改用 playwright 发现链接（由 run-code 返回 [...document.links].map(a=>a.href)）— 参见 references/edge-cases.md。

阶段 2 — 提取全局令牌（核心）

打开首页，等待页面稳定，然后运行捆绑的提取器。提取器 （scripts/extract-tokens.js）会读取经过噪声过滤的 :root 变量，对可见的主内容元素进行模式采样以获取计算样式，标记醒目的 CTA 和第一个输入框，并强制触发悬停/焦点状态——有关返回内容及原因，请参阅 references/extraction.md。

中间产物存放在 <out>/raw/ 下，让两个交付成果在文件夹根目录保持整洁——请参阅输出布局。创建一次文件夹：

S=designmd
mkdir -p "<out>/raw/tokens" "<out>/raw/components" "<out>/raw/copy" "<out>/raw/logs" "<out>/screenshots"
playwright-cli -s=$S open "<homepage-url>"
sleep 2                                              # let CSS/fonts settle (FR-ROB.1)
playwright-cli -s=$S run-code "$(cat "$SKILL/scripts/extract-tokens.js")" \
  | bash "$SKILL/scripts/slice-result.sh" > "<out>/raw/tokens/tokens.home.json"

slice-result.sh 会剥除 playwright-cli 的 Markdown 包装，让你获得干净的 JSON。 读取结果并检查 varsTotal / vars 数量是否合理。如果 vars 过少（网站并非 Tailwind 风格），请使用 varsExtra 放宽筛选条件——参阅 references/edge-cases.md（EC-FW.1 / 无设计系统）。

主题检测（决策 8）

检查 JSON 中的 themeSignal。如果网站提供浅色/深色切换——<html> 上有 .dark 类或 data-theme 属性，或者会响应 prefers-color-scheme——则该网站为双主题。当存在两种主题且 --theme 为 auto/both 时，每种主题各提取一次：切换主题、重新等待页面稳定，然后将提取器的结果输出到第二个文件（raw/tokens/tokens.home.dark.json）。切换顺序优先级如下：

1. 点击网站自带的主题切换控件，否则
2. 直接设置类/属性，例如使用 run-code 执行 document.documentElement.classList.add('dark')（或 setAttribute('data-theme','dark')），否则
3. 模拟 prefers-color-scheme。

切换后重新执行 sleep 2。如果无法可靠触发另一种主题，则只捕获已加载的主题，生成一个 DESIGN.md，并在报告中说明。即使是双主题网站，--theme light|dark 也会固定为指定主题。完整详情： references/edge-cases.md（EC-TH）。

阶段 3 — 收集组件和状态（第 2 至 N 个页面）

对于每个后续页面，不要重新导出全局变量（这些变量是共享的）——只采样该页面适合展示的组件（认证页面的输入框、定价页面的卡片/切换控件、博客页面的正文）。重复使用同一提取器；为每个页面保留其 JSON：

playwright-cli -s=$S goto "<page-2-url>"
sleep 2
playwright-cli -s=$S run-code "$(cat "$SKILL/scripts/extract-tokens.js")" \
  | bash "$SKILL/scripts/slice-result.sh" > "<out>/raw/tokens/tokens.<slug>.json"

任何针对特定页面的定制组件捕获（卡片/胶囊候选项等）放入 <out>/raw/components/；抓取的文案放入 <out>/raw/copy/；每个步骤的日志放入 <out>/raw/logs/。

提取器已在 CTA 上强制触发 hover，并在第一个输入框上强制触发 focus，然后在 states 中返回差异。综合时只保留与基础状态不同的状态（FR-ST.3）。跨页面合并：合并 CSS 变量（首页优先提供核心调色板，并标记冲突）；汇总组件，并合并样式相同的组件。

阶段 4 — 捕捉感觉（可选，默认开启）

每个采样页面截取一张视口截图（不是整页），保存到 screenshots/：

playwright-cli -s=$S screenshot --filename="<out>/screenshots/<slug>.png"

也可以使用 firecrawl scrape --only-main-content "<url>" 抓取首页和品牌页面的文案/标语，保存到 <out>/raw/copy/。截图保留在 <out>/screenshots/（它们可用于撰写正文，用户也可能会查看）。截图和文案仅用于撰写正文（概述、注意事项）—— 绝不能从中读取令牌值。--no-screenshots 会跳过此阶段。

阶段 5 — 编写 DESIGN 文件

读取合并后的 raw/tokens/*.json，并将其映射到 DESIGN.md 架构。完整架构、 token→DESIGN 映射表和规范的正文部分顺序见 references/design-md-schema.md——写入文件前请先阅读。 关键规则：

• 将主调色板中的颜色从计算得出的 rgb(...) 值解析为 hex；保留原始 CSS 变量（如 lab()/color-mix() 等）作为回退值。切勿臆造颜色。
• 根据语义角色命名颜色（--color-accent → primary/accent）；将冗长的灰色阶梯归并为具有代表性的 neutral 集合——记录整个系统，而非每个色阶。
• 在 components 中使用 {path.to.token} 引用，以保持值的 DRY 特性，并让 linter 验证这些值。必须存在 primary 颜色，否则 linter 会报错。
• 仅记录页面实际展示的组件（决策 10）——切勿臆造不存在的 card/chip。跟踪常见组件集合（button、input、card、link、chip）中哪些已找到、哪些缺失，以便写入报告。
• 仅在有实际依据时输出正文部分，并始终遵循规范顺序；绝不重复 ## 标题。

双主题输出（决策 8）

当捕获到两个主题时，输出 DESIGN.light.md + DESIGN.dark.md——每个文件都必须完整且通过 lint 验证。typography、rounded 和 spacing 共用；colors 及任何依赖颜色的 components 按主题分别设置。单主题网站只输出一个 DESIGN.md。正文可以提及存在另一个主题。

阶段 6 — 验证（质量门禁）

对每个生成的文件运行 lint：

npx -y @google/design.md lint "<out>/DESIGN.md"

• 仅自动修复结构错误：章节顺序错误、{refs} 损坏、缺少 primary/必填字段。
• 在报告中标记值级问题（超出色域的颜色、奇怪的尺寸）——绝不能为了满足 linter 而静默删除已捕获的 token（决策 12）。由用户决定如何处理标记值。
• 列出非致命警告（例如 WCAG AA 对比度），但不要因此阻塞。
• 修复后重新运行 lint；最终文件必须没有错误。如果无法使用 npx/linter，仍然写入文件，并在报告中注明“lint skipped”。

---

输出布局

两个交付文件放在文件夹根目录；所有中间文件都收纳在 raw/ 下，确保输出一目了然。

.design_mds/<domain>-YYYYMMDD/        # <domain> = host with dots→hyphens
├── DESIGN.md                         # single-theme   (or DESIGN.light.md + DESIGN.dark.md)
├── screenshots/<slug>.png            # 1 desktop-viewport PNG per page (if enabled)
└── raw/                              # intermediate artifacts (audit trail + re-runs)
    ├── tokens/tokens.<slug>.json     # raw extracted token/computed-style data per page/theme
    ├── components/                   # any bespoke per-page component captures
    ├── copy/                         # scraped page copy (if screenshots stage ran)
    ├── logs/                         # per-step playwright/firecrawl logs
    └── map.json                      # firecrawl page-discovery result

raw/tokens/*.json 始终保留（决策 9），这样无需重新抓取就能重新生成正文，且任何值都可追溯。**冲突防护：**如果今天的域名对应的文件夹已存在，请询问（覆盖 / 添加后缀 -2 / 中止）——绝不静默覆盖。

最终报告

保持简洁、诚实。说明捕获了哪些内容、找到和缺失了哪些组件、有哪些主题，以及 linter 的确切反馈。如果某个阶段效果不佳（没有设计系统、Firecrawl 故障、跳过 lint），请如实说明——不要暗示结果完全忠实于原始内容。

DESIGN.light.md + DESIGN.dark.md → .design_mds/cursor-com-20260630/

Sampled 4 pages: home, pricing, sign-in, blog
Themes: light + dark (detected via .dark on <html>)
Captured: 9 colors/theme, 6 type roles, 7 radius, full spacing
Components found: button-primary (+hover), input-field (+focus), card · missing: chip
Lint: ✓ both files clean (1 contrast warning on dark: text-muted on bg — AA borderline)
Screenshots: screenshots/ (4, desktop viewport)

先询问规则（长期有效）

每当对某项映射或模糊选择的把握低于 95%时——例如两个颜色中哪个是“primary”、网站是否确实有设计系统、如何解决当天输出冲突——请先询问并给出建议，而不是猜测。至少要在报告中指出这种模糊之处。启动的任何子 Agent 都必须依次运行，绝不并行，并且必须遵守上述 Firecrawl 和沙盒规则。

附带文件

• scripts/extract-tokens.js — 用于 run-code 的浏览器内提取器（噪声过滤、模式采样、CTA/input 检测、hover/focus）。经过验证的核心，已投入生产使用。
• scripts/slice-result.sh — 移除 playwright-cli 的 Markdown 封装，输出干净的 JSON。
• references/extraction.md — 逐字段说明提取器的返回内容，以及如何使用 varsExtra 放宽筛选条件。
• references/design-md-schema.md — DESIGN.md YAML 架构、token→DESIGN 映射表和规范的正文顺序。阶段 5 前请阅读。
• references/edge-cases.md — 无设计系统、非 Tailwind、双主题切换、合并冲突、抓取/加载失败、结果为空。