design-system

设计系统提取器

分析现有网站、HTML 文件或截图，并将语义化设计系统整理为 DESIGN.md 文件。输出针对 design-loop 技能和通用页面生成进行了优化。

适用场景

• 基于现有网站的视觉风格启动新项目
• 记录从未正式整理成文的网站设计系统
• 运行设计循环前准备 .design/DESIGN.md
• 从客户的现有网站中提取品牌指南
• 为多页面项目创建一致性文档
• 从 Google Stitch 项目中提取设计令牌

工作流

第 1 步：确定来源

询问用户提供以下来源之一：

来源	方法
在线 URL	使用 Playwright CLI 或抓取工具浏览，截图并提取 HTML
本地 HTML 文件	直接读取文件
截图图片	进行视觉分析（有限——无法准确提取十六进制颜色值）
现有项目	扫描 site/public/ 中的 HTML 文件进行分析
Stitch 项目	使用 @google/stitch-sdk 获取屏幕 HTML 和设计主题

第 2 步：提取原始设计数据

从在线 URL 提取

1. 使用 Playwright CLI 浏览网站：

   playwright-cli -s=design open {url}
   playwright-cli -s=design screenshot --filename=.design/screenshots/source-desktop.png
   

2. 提取完整 HTML——使用抓取器 MCP，或读取页面源代码

3. 调整尺寸并截取移动端截图（375px）：

   playwright-cli -s=design resize 375 812
   playwright-cli -s=design screenshot --filename=.design/screenshots/source-mobile.png
   

4. 关闭会话：playwright-cli -s=design close

从本地 HTML 文件提取

直接读取文件，并从源代码中提取设计令牌。

仅从截图提取

对图片进行视觉分析。注意：没有 HTML 源代码时，颜色提取只能是近似值。请在输出中说明这一限制。

从 Google Stitch 项目提取

如果已安装 @google/stitch-sdk，且已设置 STITCH_API_KEY：

import { stitch } from "@google/stitch-sdk";

// List projects to find the target
const projects = await stitch.projects();

// Get project details (includes designTheme)
const project = stitch.project(projectId);
const screens = await project.screens();

// Get HTML from the main screen
const screen = screens[0]; // or find by title
const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();

Stitch 的 designTheme 对象会直接提供结构化令牌：

{
  "colorMode": "DARK",
  "font": "INTER",
  "roundness": "ROUND_EIGHT",
  "customColor": "#40baf7",
  "saturation": 3
}

将这些映射到 DESIGN.md 的各个部分：

• colorMode → 主题（浅色/深色）
• font → 字体排版中的字体系列
• roundness → 组件圆角（ROUND_EIGHT = 8px，ROUND_SIXTEEN = 16px，等等）
• customColor → 品牌主色
• saturation → 色彩鲜艳度（1-5 级）

然后还要下载并分析 HTML，以获取完整的调色板（Stitch 的主题对象仅包含主色；完整调色板位于生成的 CSS 中）。

第 3 步：分析设计令牌

从 HTML/CSS 源代码中提取以下内容：

颜色

按以下优先级查找：

1. CSS 自定义属性——:root { --primary: #hex; } 或 @theme 代码块
2. Tailwind 配置——包含 tailwind.config 的 <script> 代码块，或 <style> 中的 @theme
3. 内联样式——style="color: #hex" 或 style="background: #hex"
4. Tailwind 类——bg-blue-600、text-gray-900（映射到调色板）
5. 根据截图估算——最后手段，结果为近似值

为找到的每种颜色确定其角色：

角色	识别方法
主色	按钮、链接、激活状态、品牌元素
背景	<body> 或 <html> 的背景
表面	卡片、容器、凸起元素
主要文本	<h1>、<h2>、正文
次要文本	说明文字、元数据、弱化文本
边框	分隔线、输入框边框、卡片边框
强调色	徽章、通知、高亮内容

字体排版

提取以下内容：

令牌	查找位置
字体系列	Google Fonts <link>、@import、CSS 中的 font-family
标题字重	font-bold、font-semibold 或显式设置的 font-weight
正文字号	<body> 或根元素上的基础 font-size
行高	leading-* 类或 CSS line-height
字间距	tracking-* 类或 CSS letter-spacing

组件

识别以下模式：

• 按钮 — 形状（rounded-full、rounded-lg）、颜色、内边距、悬停状态
• 卡片 — 背景、边框、阴影、圆角、内边距
• 导航 — 粘性／静态、背景样式、当前项指示器
• 表单 — 输入框样式、焦点环、标签位置
• Hero 区块 — 布局模式、叠加效果、CTA 位置

间距与布局

• 内容最大宽度 — 查找 max-w-* 或明确的 max-width
• 区块内边距 — 区块之间常见的垂直内边距
• 网格系统 — 列数、间距值
• 留白理念 — 紧凑、均衡、宽松或极具张力

第 4 步：综合为自然语言

关键：DESIGN.md 应以有具体数值支撑的语义化自然语言描述设计。这不是 CSS 数值清单，而是一份设计师或 AI 能够阅读并据此理解和重现视觉语言的文档。

不要写	改为写
rounded-xl	“圆角柔和（12px）”
shadow-md	“以漫射阴影营造微妙的立体感”
#1E40AF	“主要操作使用深海蓝（#1E40AF）”
py-16	“区块间距宽裕，留有充足的呼吸空间”

第 5 步：编写 DESIGN.md

将文件输出到 .design/DESIGN.md（或用户指定的路径）。

遵循 design-loop 技能的 references/site-template.md 中的结构，尤其是 DESIGN.md 模板部分。主要章节包括：

1. 视觉主题与氛围 — 情绪、风格、理念
2. 调色板与用途 — 包含用途、名称、十六进制值和使用方式的表格
3. 排版 — 字体系列、字重、字号、行高
4. 组件样式 — 按钮、卡片、导航、表单
5. 布局原则 — 最大宽度、间距、网格、留白
6. 生成用设计系统说明 — 可复制粘贴到 baton 提示词中的内容块

第 6 步：验证准确性

如果可以使用浏览器自动化：

1. 使用提取出的设计系统生成一个小型测试区块（例如一张卡片、一个按钮和一个标题）
2. 将其与原始页面并排截图
3. 进行视觉比较，并调整不匹配的数值

第 7 步：向用户汇报

提供：

• 提取出的设计要素摘要（颜色数量、字体、组件模式）
• 生成的 DESIGN.md 路径
• 任何近似估算的设计要素（用 ⚠️ 标出）
• 建议手动检查的内容（截图中的颜色、含糊的排版信息）

处理多个页面

如果网站有多个风格不同的页面：

1. 首先分析首页 — 首页通常包含最完整的设计语言
2. 抽查 2-3 个内页，检查一致性
3. 在组件样式章节中记录任何页面专属覆盖项
4. 如果各页面差异很大，请询问用户应将哪个页面作为标准来源

提示

• Tailwind 网站最容易处理 — 配置块中包含所有信息
• Google Fonts 链接非常有用 — 会明确指定字体系列和字重
• CSS 自定义属性值得信赖 — 它们代表经过设计的设计要素
• 行内 Tailwind 类需要解读 — 需要将 bg-slate-900 对应到具体用途
• 截图是最后手段 — 从图像中准确提取十六进制颜色并不可靠
• 深色模式：检查 .dark 类覆盖项或 prefers-color-scheme 媒体查询

常见误区

• ❌ 只列出原始 CSS 数值，没有语义化描述
• ❌ 遗漏深色模式调色板（检查 .dark 类或媒体查询）
• ❌ 忽略组件模式（只列出颜色并不足够）
• ❌ 未包含第 6 节（可复制粘贴的生成内容块）
• ❌ 未标明截图估算颜色的不确定性