design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design System Extractor

设计系统提取工具

Analyse an existing website, HTML file, or screenshot and synthesise a semantic design system into a

DESIGN.md

file. The output is optimised for use with the

design-loop

skill and general page generation.

分析现有网站、HTML 文件或截图，将语义化的设计系统整合输出到

DESIGN.md

文件中。输出内容可适配

design-loop

skill 以及通用页面生成场景使用。

When to Use

适用场景

Starting a new project based on an existing site's visual language
Documenting a site's design system that was never formally written down
Preparing
```
.design/DESIGN.md
```
before running the design loop
Extracting brand guidelines from a client's existing website
Creating consistency documentation for a multi-page project
Extracting design tokens from a Google Stitch project

基于现有站点的视觉语言启动新项目
为从未正式整理过的站点设计系统编写文档
运行 design loop 前预先准备
```
.design/DESIGN.md
```
文件
从客户现有网站中提取品牌规范
为多页面项目创建一致性规范文档
从 Google Stitch 项目中提取设计令牌

Workflow

工作流程

Step 1: Identify the Source

步骤 1：确定提取源

Ask the user for one of:

Source	Method
Live URL	Browse via Playwright CLI or scraper, screenshot + extract HTML
Local HTML file	Read the file directly
Screenshot image	Analyse visually (limited — no exact hex extraction)
Existing project	Scan `site/public/` for HTML files to analyse
Stitch project	Use `@google/stitch-sdk` to fetch screen HTML + design theme

向用户索要以下任意一种来源：

来源	提取方式
在线 URL	通过 Playwright CLI 或爬虫浏览，截图 + 提取 HTML
本地 HTML 文件	直接读取文件
截图图片	视觉分析（存在限制：无法提取精确的十六进制色值）
现有项目	扫描 `site/public/` 目录下的 HTML 文件进行分析
Stitch 项目	使用 `@google/stitch-sdk` 获取页面 HTML + 设计主题

Step 2: Extract Raw Design Data

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

From a Live URL

从在线 URL 提取

Browse the site using Playwright CLI:

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

Extract the full HTML — either via scraper MCP or by reading the page source

Resize and screenshot mobile (375px):

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

Close the session:
```
playwright-cli -s=design close
```

使用 Playwright CLI 浏览站点：

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

提取完整 HTML — 通过爬虫 MCP 或读取页面源码两种方式均可

调整为移动端尺寸并截图（375px）：

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

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

From a Local HTML File

从本地 HTML 文件提取

Read the file directly and extract design tokens from the source.

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

From a Screenshot Only

仅从截图提取

Analyse the image visually. Note: colour extraction will be approximate without HTML source. Flag this limitation in the output.

对图片进行视觉分析。注意：无 HTML 源码的情况下颜色提取结果为近似值，需在输出中标记该限制。

From a Google Stitch Project

从 Google Stitch 项目提取

@google/stitch-sdk

is installed and

STITCH_API_KEY

is set:

typescript

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();

The Stitch

designTheme

object provides structured tokens directly:

json

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

Map these to DESIGN.md sections:

```
colorMode
```
→ Theme (Light/Dark)
```
font
```
→ Typography font family
```
roundness
```
→ Component border-radius (
```
ROUND_EIGHT
```
= 8px,
```
ROUND_SIXTEEN
```
= 16px, etc.)
```
customColor
```
→ Primary brand colour
```
saturation
```
→ Colour vibrancy (1-5 scale)

Then also download and analyse the HTML for the full palette (Stitch's theme object only has the primary colour — the full palette is in the generated CSS).

如果已安装

@google/stitch-sdk

并配置了

STITCH_API_KEY

：

typescript

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

// 列出所有项目以找到目标项目
const projects = await stitch.projects();

// 获取项目详情（包含 designTheme）
const project = stitch.project(projectId);
const screens = await project.screens();

// 从主页面获取 HTML
const screen = screens[0]; // 或按标题查找
const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();

Stitch 的

designTheme

对象可直接提供结构化令牌：

json

{
  "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 中）。

Step 3: Analyse Design Tokens

步骤 3：分析设计令牌

Extract these from the HTML/CSS source:

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

Colours

颜色

Look in these locations (priority order):

CSS custom properties —
```
:root { --primary: #hex; }
```
or
```
@theme
```
blocks
Tailwind config —
```
<script>
```
block with
```
tailwind.config
```
or
```
@theme
```
in
```
<style>
```

Inline styles —

style="color: #hex"

style="background: #hex"

Tailwind classes —
```
bg-blue-600
```
,
```
text-gray-900
```
(map to palette)
Computed from screenshot — last resort, approximate

For each colour found, determine its role:

Role	How to identify
Primary	Buttons, links, active states, brand elements
Background	`<body>` or `<html>` background
Surface	Cards, containers, elevated elements
Text Primary	`<h1>` , `<h2>` , main body text
Text Secondary	Captions, metadata, muted text
Border	Dividers, input borders, card borders
Accent	Badges, notifications, highlights

按优先级从以下位置查找：

CSS 自定义属性 —
```
:root { --primary: #hex; }
```
或
```
@theme
```
块
Tailwind 配置 — 包含
```
tailwind.config
```
的
```
<script>
```
块或
```
<style>
```
中的
```
@theme
```

内联样式 —

style="color: #hex"

或

style="background: #hex"

Tailwind 类名 —
```
bg-blue-600
```
,
```
text-gray-900
```
（映射到调色板）
从截图计算 — 最后手段，结果为近似值

对每个找到的颜色，确定其作用：

作用	识别方式
主色	按钮、链接、激活状态、品牌元素
背景色	`<body>` 或 `<html>` 背景
表面色	卡片、容器、上浮元素
主文本色	`<h1>` 、 `<h2>` 、正文主体文本
次文本色	说明文字、元数据、弱化文本
边框色	分割线、输入框边框、卡片边框
强调色	徽章、通知、高亮内容

Typography

排版

Extract:

Token	Where to find
Font families	Google Fonts `<link>` , `@import` , `font-family` in CSS
Heading weights	`font-bold` , `font-semibold` , or explicit `font-weight`
Body size	Base `font-size` on `<body>` or root
Line height	`leading-*` classes or `line-height` CSS
Letter spacing	`tracking-*` classes or `letter-spacing` CSS

提取以下内容：

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

Components

组件

Identify patterns for:

Buttons — shape (rounded-full, rounded-lg), colours, padding, hover states
Cards — background, border, shadow, border-radius, padding
Navigation — sticky/static, background treatment, active indicator
Forms — input style, focus ring, label positioning
Hero sections — layout pattern, overlay treatment, CTA placement

识别以下元素的样式规律：

按钮 — 形状（rounded-full、rounded-lg）、颜色、内边距、hover 状态
卡片 — 背景、边框、阴影、圆角、内边距
导航 — 粘性/静态、背景处理、激活指示器
表单 — 输入框样式、聚焦环、标签位置
Hero 区块 — 布局规律、遮罩处理、CTA 位置

Spacing & Layout

间距与布局

Max content width — look for
```
max-w-*
```
or explicit
```
max-width
```
Section padding — typical vertical padding between sections
Grid system — column count, gap values
Whitespace philosophy — tight, balanced, generous, or dramatic

内容最大宽度 — 查找
```
max-w-*
```
或显式的
```
max-width
```
区块内边距 — 区块之间的典型垂直内边距
网格系统 — 列数、间距值
留白设计理念 — 紧凑、均衡、宽松、或夸张

Step 4: Synthesise into Natural Language

步骤 4：合成为自然语言描述

Critical: The DESIGN.md should describe the design in semantic, natural language supported by exact values. This is not a CSS dump — it's a document a designer or AI can read to understand and reproduce the visual language.

Don't write	Write instead
`rounded-xl`	"Softly rounded corners (12px)"
`shadow-md`	"Subtle elevation with diffused shadow"
`#1E40AF`	"Deep Ocean Blue (#1E40AF) for primary actions"
`py-16`	"Generous section spacing with breathing room"

关键要求：DESIGN.md 应当使用语义化的自然语言搭配精确数值来描述设计，不能直接堆砌 CSS 代码，这份文档是供设计师或 AI 阅读、理解并复现视觉语言使用的。

错误写法	推荐写法
`rounded-xl`	"柔和圆角（12px）"
`shadow-md`	"带弥散阴影的 subtle 悬浮效果"
`#1E40AF`	"主操作按钮使用深海蓝（#1E40AF）"
`py-16`	"区块间距宽松，留有充足呼吸空间"

Step 5: Write DESIGN.md

步骤 5：编写 DESIGN.md

Output the file to

.design/DESIGN.md

(or user-specified path).

Follow the structure from the

design-loop

skill's

references/site-template.md

— specifically the DESIGN.md Template section. The key sections are:

Visual Theme & Atmosphere — mood, vibe, philosophy
Colour Palette & Roles — table with role, name, hex, usage
Typography — font families, weights, sizes, line heights
Component Styles — buttons, cards, nav, forms
Layout Principles — max width, spacing, grid, whitespace
Design System Notes for Generation — the copy-paste block for baton prompts

将文件输出到

.design/DESIGN.md

（或用户指定的路径）。

遵循

design-loop

skill 的

references/site-template.md

中的结构，尤其是 DESIGN.md 模板章节。核心章节包括：

视觉主题与氛围 — 风格、调性、设计理念
调色板与颜色作用 — 包含作用、名称、十六进制色值、使用场景的表格
排版规范 — 字体族、字重、字号、行高
组件样式 — 按钮、卡片、导航、表单
布局原则 — 最大宽度、间距、网格、留白
生成用设计系统说明 — 供 prompt 复制粘贴的代码块

Step 6: Verify Accuracy

步骤 6：验证准确性

If browser automation is available:

Generate a small test section (e.g. a card + button + heading) using the extracted design system
Screenshot it alongside the original
Compare visually — adjust any values that don't match

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

使用提取的设计系统生成一小块测试内容（例如卡片 + 按钮 + 标题）
将其与原始内容并列截图
视觉对比 — 调整不匹配的数值

Step 7: Report to User

步骤 7：向用户反馈

Present:

Summary of extracted tokens (colour count, fonts, component patterns)
The generated DESIGN.md location
Any tokens that were approximate (flagged with ⚠️)
Suggestions for manual review (colours from screenshots, ambiguous typography)

展示以下内容：

提取的令牌摘要（颜色数量、字体、组件规律）
生成的 DESIGN.md 的存储位置
所有近似值的令牌（用 ⚠️ 标记）
人工审核建议（截图提取的颜色、存在歧义的排版）

Handling Multiple Pages

多页面处理

If the site has multiple pages with different styles:

Analyse the homepage first — it usually has the most complete design language
Spot-check 2-3 inner pages for consistency
Note any page-specific overrides in the Component Styles section
If pages are wildly different, ask the user which page to use as the canonical source

如果站点有多个页面且样式不同：

优先分析首页 — 首页通常包含最完整的设计语言
抽查 2-3 个内页确认一致性
在组件样式章节标记所有页面专属的样式覆盖规则
如果不同页面风格差异极大，询问用户以哪个页面作为标准来源

Tips

提示

Tailwind sites are easiest — the config block has everything
Google Fonts links are gold — they specify exact families and weights
CSS custom properties are reliable — they represent intentional design tokens
Inline Tailwind classes need interpretation —
```
bg-slate-900
```
needs mapping to a role
Screenshots are last resort — accurate hex extraction from images is unreliable
Dark mode: Check for
```
.dark
```
class overrides or
```
prefers-color-scheme
```
media queries

Tailwind 站点提取难度最低 — 配置块包含所有所需信息
Google Fonts 链接价值很高 — 会明确指定精确的字体族和字重
CSS 自定义属性可靠性高 — 代表了有意设定的设计令牌
内联 Tailwind 类名需要解析 —
```
bg-slate-900
```
需要映射到对应的颜色作用
截图是最后手段 — 从图片中提取精确的十六进制色值并不可靠
暗色模式：检查
```
.dark
```
类覆盖规则或
```
prefers-color-scheme
```
媒体查询

Common Pitfalls

常见问题

❌ Listing raw CSS values without semantic description
❌ Missing the dark mode palette (check for
```
.dark
```
class or media query)
❌ Ignoring component patterns (just listing colours isn't enough)
❌ Not including Section 6 (the copy-paste generation block)
❌ Approximate colours from screenshots without flagging the uncertainty

❌ 只罗列原始 CSS 值，没有语义化描述
❌ 遗漏暗色模式调色板（需检查
```
.dark
```
类或媒体查询）
❌ 忽略组件规律（仅罗列颜色是不够的）
❌ 未包含第 6 章节（可复制的生成用代码块）
❌ 从截图提取的近似颜色未标记不确定性