distill-design

/distill-design — 从网站提炼 DESIGN.md

将线上网站转化为 DESIGN.md：一份纯文本设计系统规范（YAML token frontmatter + 11 个散文式章节），任何 AI Agent 都可以读取它来生成 符合品牌风格的 UI。概念和格式遵循 VoltAgent/awesome-design-md。

参数： 一个网站 URL（$ARGUMENTS）。如果未提供，则向用户询问。

产出内容： 默认情况下，仅生成 DESIGN.md。可视化的 preview.html 和真实感的 demo.html 都是可选的——仅在用户要求时生成（参见下文两个“按需生成”章节）。

先阅读这些内容

• reference/format-spec.md — 确切的 frontmatter schema 和 11 个章节的正文。
• reference/extraction-guide.md — 如何从线上站点测量 token。
• reference/template.md — 你要填写的 DESIGN.md 骨架。
• reference/preview-template.html — 规范化的、数据驱动的 preview.html。 原样复制它，仅注入 token JSON（参见“生成 token 预览”）。
• reference/demo-guide.md — 如何构建真实感的 demo（仅在要求时）。 （这些文件与本 SKILL.md 放在一起，因此请将它们作为同级文件读取。） preview.html 外壳对每个品牌都是相同的——使用上述模板，绝不要 手写它。对于定制的 demo.html，源仓库 （ake77-code/distill-design）中的示例文件夹 examples/stripe、 examples/linear、examples/spotify 可作为参考。

输出写入位置

默认情况下，写入当前项目（而不是此 skill 自己的文件夹）：

• 单个规范 → ./DESIGN.md（项目根目录）。可选的 preview.html / demo.html 仅在要求时与它放在一起。
• 多个规范 → 按品牌使用 distill-design/<brand>/ 文件夹。
• 始终遵循用户给出的显式路径。

工作流

1. 确定目标范围

确认 URL。确定除首页外值得检查的几种页面类型： 营销页、定价页、文档，以及可访问的应用/仪表盘（如可达）。品牌通常会翻转 极性（浅色营销页 → 深色应用）——计划同时捕获两者。

2. 检查与测量

优先采用测量值而非猜测。驱动真实的无头浏览器并读取 getComputedStyle —— 按以下严格顺序尝试，在第一个可行的方法处停止 （完整片段见 extraction-guide.md）：

1. Playwright（首选） —— 通过 Bash 编写 Chromium 脚本；如果缺失，用 npx -y playwright install chromium（或 bunx playwright install chromium）安装， 然后用 page.$eval(sel, …) 读取精确的十六进制色值、字体栈、圆角、内边距、 阴影。也进行截图。（全程中 npx 和 bunx 可互换使用。）
2. Puppeteer（后备） —— 如果 Playwright 不可用，通过 require("puppeteer") 采用相同 方法；用 npx -y puppeteer browsers install chrome（或 bunx 等价命令）安装。
3. Browser MCP（Chrome / Preview） —— 仅当已连接其中之一时。
4. WebFetch / fetch（最后手段） —— 仅文本，无像素值。仅当无法运行任何 浏览器时使用；结合品牌知识，并在 Colors 注释和 ## Known Gaps 中将输出标注为 受启发的诠释。

扫描 hero、正文文本、按钮、卡片、导航、输入框和页脚。提取颜色 → 角色、 字体比例、圆角比例、间距基准单位、高度、各组件规格和 状态，以及 2–3 个标志性母题。

3. 映射为 token —— 深入挖掘

最常见的失败是文件过于单薄。真实品牌拥有大量 token；要匹配这种 深度（目标值见 format-spec.md）：

• 颜色 ~18–30+，按角色命名，保持 FLAT。在 colors: 内承载 极性：用 *-on-dark 文本变体和 surface-dark-* 色块；按 名称中的近似不透明度对弱化墨色分级（ink-muted-64）。只在 ~2% 以内且同角色的 十六进制值才去重。
• 排版 ~12–20 个语义角色（hero-display、lead、tagline、 body-strong、dense-link、caption-strong、button-large、fine-print、 micro-legal、nav-link），每个都要有字重、行高、以 px 为单位的 letterSpacing， 以及仅在真实存在时的 fontFeature。捕捉罕见的字重（300 / 600-vs-700）。
• rounded 要有 none:0 + full；spacing 要包含实测的异常值（17px）和 一个 section 步长。使用实测值，而不是理想化的 4/8/12。
• 组件 ~15–30+，每个都是 {group.token} 组合（允许字面的 padding/height/ size）。变体是 SEPARATE 键（-active、-focus、-selected、-2）。 绝不要记录 hover。
• 为任何专有字体选择一个开源替代品。

4. 编写 DESIGN.md

将 reference/template.md 填充到输出路径（默认 ./DESIGN.md —— 见 “输出写入位置”）。遵循 11 节结构以及随附示例的散文语气。name: 为 <Brand>-design-analysis。frontmatter 的 description 是最重要的字段 —— 一行 一段密集的散文（普通标量，不是 > 块），生动到闭着眼都能想象出该网站。

5. 自检 DESIGN.md

• Frontmatter 是有效的 YAML；如不确定，快速解析一下（见下方验证）。
• 正文中的每个 {group.token} 都能解析到已定义的 frontmatter 键。
• 所有 11 节都存在且非空（Overview → Known Gaps），包括 必需的 ## Known Gaps。
• 达到深度目标（~18+ 颜色、~12+ 字体角色、~15+ 组件）。description 是 内联的。没有 -hover 组件键（简短的散文式 hover 可以）。letterSpacing 以 px 为单位。
• 颜色按角色命名并已去重；专有字体有替代品。

6. 提供可视化（始终以此结尾）

DESIGN.md 是交付物。不要自动生成 preview.html 或 demo.html。 在回复结尾提醒用户可以选择任一，例如：

已生成 DESIGN.md。需要的话我还能基于它生成: ① preview.html —— 设计系统可视化(色板 / 字阶 / 组件,带顶部导航与明暗切换); ② demo.html —— 像真实网站的 Web 落地页或移动端界面。 两者都按需生成,要哪个告诉我。

（匹配用户的语言。）仅在用户要求时生成 preview.html → 遵循下方 “生成 token 预览”。仅在用户要求时生成 demo.html → 遵循下方 “生成真实演示”。

生成 token 预览 preview.html（按请求）

不要手写各品牌的 HTML/CSS。 预览外壳对每个 网站都是相同的 —— 只有注入的数据会变化。该技能提供一个规范的、数据驱动的 模板：reference/preview-template.html —— 一个精致的设计系统展示页： 一个粘性导航（品牌字标 + 一个链接到 github.com/ake77-code/distill-design 的 distill-design GitHub 徽标 + 各节锚点 + 明暗切换 + 一个 CTA）， 一个双栏 hero（Design System Analysis of <displayName> + 描述 + 一个 设备模型卡片），然后是编号各节 （“01 — Color Palette”、“02 — Typography Scale”、“03 — Components”、“04 — Spacing & Radius”、“05 — Elevation & Depth”、“06 — Responsive Behavior”），渲染分组后的色板 卡片、字体阶梯、组件画廊、间距/圆角块，以及断点 表格。没有页脚。零依赖（系统字体，无 CDN）。

要生成某品牌的 preview.html：

1. 逐字复制 reference/preview-template.html 到 <output>/preview.html。
2. 仅替换 <script type="application/json" id="design-data"> 内的 JSON， 换成该品牌的 token（从 DESIGN.md 推导而来）。其他什么都不要改 —— 外壳、 CSS 和渲染器在各品牌间保持逐字节一致。 注入的 JSON schema（参见模板中该块上方的注释）：

• meta：{ name, displayName, description, source, nativeTheme: "light"|"dark", navCta, heroCtas, sections? }。name 是真实品牌；hero 区显示 "Design System Analysis of displayName" —— 将 displayName 设为真实品牌名 （例如 "Apple"、"Stripe"、"Figma"）。不要虚构产品名 —— 使用 该 URL 所属的实际品牌。description 是 frontmatter 的 description 原文；source 是线上 URL；nativeTheme 是 品牌的极性（Linear 等为 dark）。可选的 navCta（导航按钮文案，例如 "Buy" / "Get started"）和 heroCtas ["Learn more","Buy"] 用于设置品牌的 CTA 文案。可选的 heroArt 选择与标志性母题匹配的 hero 视觉： device（默认产品 mock）、mesh（渐变网格填充 —— 类似 Stripe 的品牌），或 glow（暗色辉光 —— 类似 Linear 的品牌）。可选的 sections = { colors:{heading,intro}, typography:{...}, components:{...} } 为每个 section 提供品牌语气的 heading/intro（例如 "One blue. Three near-blacks."），从匹配的 DESIGN.md 正文章节中提取；省略则使用默认值。
• colors：扁平调色板，以 role→hex 表示（支持 rgba 字符串）。每个 role 渲染为一个 色板，自动分组（Brand & Accent / Surface / Text / Hairlines & Borders / Semantic）。
• colorRoles（可选，推荐）：{ role: "one-line description" } —— 来自 DESIGN.md Colors 章节的每色使用说明；显示为色板的第 3 行， 使卡片与参考深度一致。colorNames（可选）：{ role: "Friendly Name" } → 渲染为 "role (Friendly Name)"。
• colorsDark：可选的相反极性覆盖值（否则 dark 将被合成生成）。
• typography：role→{ fontFamily, fontSize, fontWeight, lineHeight, letterSpacing }。
• rounded、spacing：token→value 映射。
• components：role→{ backgroundColor, textColor, typography, rounded, padding, border, height, size }；值可以使用 {group.token} 引用（由渲染器解析），以便每个 图库示例都以真实组件样式渲染。
• responsive（可选）：{ breakpoints:[{name,width,changes}], touchTargets, collapsing, imageBehavior }，来自 DESIGN.md 的 Responsive Behavior 章节 —— 驱动 "06 — Responsive Behavior"。省略整个键即可隐藏该 section。

模板已提供导航、hero、编号 section、色板分组、 字体阶梯、组件图库、间距/圆角/高度层级块、响应式断点表格，以及 light/dark 切换（localStorage）。导航字标显示品牌名 （不是第三方品牌）；GitHub chip 显示 distill-design 并指向 github.com/ake77-code/distill-design。 注入数据后，验证它能否独立打开（file://），并在视觉上呈现为 使用品牌色彩的精致设计系统分析页面。若需像素级参考， awesome-design-md 项目会在 getdesign.md/design-md/<brand>/preview.html 渲染每个品牌。

按需生成一个逼真的演示 demo.html

目标：一个零外部依赖的单一 .html 文件（所有 CSS/JS 内联， 无 CDN，无网络请求——仅使用 system/-apple-system 字体栈），读起来 像真实的产品，而不是一个 token 目录。它不同于 preview.html： preview.html 记录该系统；而演示则使用它来交付一个可信的页面。

阅读 reference/demo-guide.md 获取完整配方。简而言之：

1. 如果不明确就询问形态：Web（响应式落地页）还是 Mobile （手机框内的应用屏）。默认 Web。
2. 从 token 构建一个真实页面——从 DESIGN.md 中直接提取每一种颜色、字体、圆角、间距、 阴影和组件：
   • Web：粘性导航 → hero（标题 + 副标题 + 主/次 CTA）→ 社会证明 徽标 → 三栏功能卡片 → 定价层级 → 用户评价 → CTA 横幅 → 页脚。
   • Mobile：手机框（状态栏、刘海）包裹真实应用屏——顶栏、 内容列表/信息流/卡片，以及底部标签栏或正在播放/粘性 CTA。
3. 让它感觉真实——可信的文案和产品名称、品牌的标志性 母题（例如渐变网格、发光细线、绿色播放按钮）、通过内联 SVG/CSS 渐变实现的逼真图像（绝不外链外部图片）， 以及在小型内联 <script> 中得体的悬停/滚动微交互。
4. 保存到规范文件旁边，命名为 demo.html（或 demo-mobile.html）。
5. 验证它能独立打开（双击 / file://），没有控制台错误，并且 在视觉上以品牌的语言类似真实网站。

验证

# YAML frontmatter parses (frontmatter is between the first two '---' lines)
python3 - "$f" <<'PY'
import sys, yaml
t = open(sys.argv[1]).read().split('---', 2)
yaml.safe_load(t[1]); print("frontmatter OK")
PY

然后在规范文件中 grep 两个最常见的疏漏——两者都必须返回空：

grep -nE '^\s+[a-z0-9-]*-hover:' "$f"   # no hover-STATE component keys (prose ok)
grep -c '^## ' "$f"                     # must be 11 (Overview … Known Gaps)

如果你生成了 preview.html 或 demo.html，请在浏览器中打开它——或者 用浏览器 MCP 截图——并确认它以品牌的语言渲染。

备注

• 文件夹名称保持小写、URL 安全（stripe、together.ai）。
• name: 为 <Brand>-design-analysis。当值是被解读的（仅 WebFetch， 无实测 CSS）而非官方认可时，请在 Colors 源页面 说明和 ## Known Gaps 部分中说明这一点——不要捏造精确度。
• 每个文件夹一个品牌；将状态变体记为单独的组件键；绝不使用 hover。