AI 编程工具已经能快速生成页面，但“生成得像不像某个产品”仍然是难点。问题通常不在代码能力，而在输入信息不够：只给一句“做一个官网首页”，模型很难知道字体层级、主色、按钮圆角、阴影风格、卡片间距、交互动效应该怎么统一。
design-md-chrome 解决的就是这个问题。它是一个 Chrome 浏览器扩展，可以从当前网页中提取设计信号，再生成符合 TypeUI DESIGN.md 格式的 Markdown 文件。这个文件可以当作设计系统蓝图，交给 Google Stitch、Claude Code、Codex 等工具，让它们按照已有网站的视觉规则继续生成页面或组件。
项目地址：
https://github.com/bergside/design-md-chrome
DESIGN.md 和 SKILL.md 分别解决什么问题
这个扩展主要生成两类文件：DESIGN.md 和 SKILL.md。二者都来自同一批网页设计信号，但面向的使用方式不同。
| 文件 | 面向对象 | 主要内容 | 典型用途 |
|---|---|---|---|
| DESIGN.md | 人和 AI 工具 | 品牌背景、视觉基础、组件规则、质量检查 | 作为项目设计系统说明，指导页面和组件实现 |
| SKILL.md | AI 代理（agent） | 更偏执行步骤、规则约束和输出要求 | 给 Claude Code、Codex 这类工具作为任务技能文件 |
可以把 DESIGN.md 理解成“设计系统说明书”，把 SKILL.md 理解成“让 AI 按这套设计系统干活的执行手册”。
整体工作流
design-md-chrome 的使用路径很短：打开目标网站，点击扩展，提取页面样式，生成 Markdown，然后下载文件。
flowchart LR
A[打开目标网页] --> B[点击 Chrome 扩展]
B --> C[读取当前标签页样式]
C --> D[提取设计信号]
D --> E[生成 DESIGN.md]
D --> F[生成 SKILL.md]
E --> G[下载文件]
F --> G
G --> H[交给 AI 工具或项目仓库使用]
在 Chrome 扩展的实现模型里，类似功能通常会由页面脚本读取当前标签页中的 DOM 和计算样式，再由扩展侧把这些原始信息整理成更稳定的设计规则。原始网页里可能有成百上千个 CSS 值，真正有用的是经过归纳后的“设计信号”，例如常用字号、主色、背景色、按钮圆角、卡片阴影和动画时长。
它会提取哪些设计信号
扩展的自动提取能力覆盖了常见视觉系统中的基础要素。
| 类型 | 可能提取的信息 | 生成文档里的作用 |
|---|---|---|
| 排版 | 字体、字号、字重、行高、标题层级 | 约束标题、正文、说明文字的层次 |
| 颜色 | 主色、背景色、文本色、边框色、强调色 | 形成品牌色板和使用规则 |
| 间距 | margin、padding、gap、布局留白 | 保持页面密度和组件间距一致 |
| 圆角 | 按钮、输入框、卡片等元素的 border-radius | 判断视觉风格偏锐利还是偏柔和 |
| 阴影 | box-shadow 的层级、模糊、透明度 | 定义卡片、弹层、浮层的空间关系 |
| 动效 | duration、delay、easing、transition 属性 | 约束交互反馈和状态变化速度 |
这些信息不是简单罗列 CSS，而是为了生成可执行的设计系统规则。比如页面里出现了多个蓝色值，文档需要把它们归纳为主色、悬停色、边框色或背景辅助色；页面里有多个字号，文档需要把它们整理成标题、正文、辅助文本等层级。
扩展提供的主要操作
design-md-chrome 的功能可以拆成几个按钮或操作入口。
| 操作 | 作用 |
|---|---|
| 自动提取 | 从当前活动标签页读取样式，包括排版、颜色、间距、圆角、阴影和动效 |
| 生成 DESIGN.md | 根据提取到的设计信号生成设计系统 Markdown |
| 生成 SKILL.md | 根据同一批信号生成更适合 AI 代理使用的技能 Markdown |
| 刷新 | 对当前页面状态重新执行提取 |
| 下载 | 把生成结果保存为 DESIGN.md 或 SKILL.md |
| 解释 | 展示文件生成依据，并关联 TypeUI 参考信息 |
“刷新”很重要，因为网页不是静态图片。页面滚动、弹窗打开、主题切换、登录状态变化，都会影响当前可见元素和样式。如果想提取某个特定状态，例如打开菜单后的导航样式，应该先把页面切到目标状态，再重新运行提取。
生成的 DESIGN.md 结构
生成的 Markdown 会围绕设计系统组织，而不是围绕页面源码组织。它关注的是“如何复用这套风格”。
| 章节 | 内容作用 |
|---|---|
| 使命 | 描述这套设计系统要服务的目标 |
| 品牌 | 记录产品背景、URL、受众和界面语境 |
| 风格基础 | 列出推断出的视觉标记，例如颜色、字体、间距、圆角 |
| 可访问性 | 引入 WCAG（Web Content Accessibility Guidelines，网页内容无障碍指南）2.2 AA 相关要求 |
| 写作语气 | 约束界面文案和生成内容的表达方式 |
| 规则：要 | 明确实现时必须遵守的做法 |
| 规则：不要 | 列出反模式和禁止行为 |
| 指南编写工作流程 | 定义生成或补充设计指南时的步骤 |
| 必需的输出结构 | 约束输出文档或组件说明的格式 |
| 组件规则预期 | 要求组件说明包含状态、交互和边界情况 |
| 质量检查 | 给出可检查的一致性和质量要求 |
一个简化后的 DESIGN.md 可能长这样：
# DESIGN.md
## 使命
为产品界面建立一致、可复用、可检查的视觉规则。
## 品牌
- 产品 URL: https://example.com
- 受众: 面向需要快速完成任务的专业用户
- 界面特征: 清晰、克制、强调信息层级
## 风格基础
### 排版
- 标题使用较高字重，正文保持良好行高
- 辅助文字降低字号和颜色对比，但仍需满足可读性
### 颜色
- 主色用于关键按钮、链接和当前状态
- 中性色用于背景、边框和次级文本
### 间距
- 卡片内部留白保持一致
- 列表项之间使用稳定间距，不要随意压缩
## 规则：要
- 保持按钮、输入框、卡片圆角一致
- 为 hover、focus、disabled 状态提供明确样式
## 规则：不要
- 不要混用过多阴影层级
- 不要在同一页面使用多套字号比例
真正生成的文件会更完整，重点不是复制某个页面，而是把页面背后的视觉约束沉淀出来。
典型使用方式
安装扩展后，可以按这个流程使用：
- 打开想要分析的网站页面。
- 点击 Chrome 工具栏里的扩展图标。
- 执行自动提取，读取当前页面设计信号。
- 选择生成
DESIGN.md或SKILL.md。 - 使用解释功能检查生成依据。
- 下载 Markdown 文件。
- 把文件放进项目仓库，或直接交给 AI 编程工具作为上下文。
交给 AI 工具时，可以这样描述任务：
请严格参考 @DESIGN.md 中的设计规则，实现一个 pricing section。
要求：
- 使用文档里的颜色、圆角、阴影和间距规则
- 包含默认、hover、focus 状态
- 不要引入文档之外的新视觉风格
如果使用 SKILL.md，可以把它作为 agent 的工作规则，让工具在生成组件、重构页面、补充状态样式时遵循同一套约束。
从源码定制自己的版本
design-md-chrome 已经开源，适合根据团队规范做二次调整。定制时不需要只盯着扩展界面，更应该关注“提取规则”和“生成模板”。
flowchart TD
A[网页 DOM 和计算样式] --> B[提取规则]
B --> C[设计信号]
C --> D[归纳与过滤]
D --> E[Markdown 模板]
E --> F[DESIGN.md]
E --> G[SKILL.md]
常见定制点如下：
| 定制点 | 可以调整什么 |
|---|---|
| 提取范围 | 只分析主体区域，忽略广告、脚注、第三方组件 |
| 颜色归纳 | 合并相近颜色，指定品牌主色优先级 |
| 排版规则 | 按团队已有字号阶梯重新映射标题和正文 |
| 组件规则 | 增加按钮、表单、卡片、导航等组件的固定输出格式 |
| 可访问性检查 | 强化颜色对比度、键盘焦点、禁用态说明 |
| Markdown 模板 | 改成团队内部更熟悉的文档结构 |
| AI 执行规则 | 在 SKILL.md 中加入禁止事项和验收清单 |
比如团队已经有固定的字号阶梯：
12 / 14 / 16 / 20 / 24 / 32 / 40
那就可以在提取后把网页中的近似字号映射到这组阶梯，避免生成文档里出现大量难以维护的零散值。
开发和调试
仓库提供了本地测试命令：
node tests/run-tests.mjs
如果本地缺少依赖，可以先根据仓库中的 package.json 安装依赖，再运行测试：
npm install
node tests/run-tests.mjs
作为 Chrome 扩展开发项目，调试时通常还需要在浏览器里打开扩展管理页，开启开发者模式，然后加载未打包扩展目录。具体加载目录要以仓库实际结构为准，如果项目包含构建步骤，应先完成构建，再加载生成后的扩展目录。
使用时容易踩的坑
网页样式提取只能拿到“当前页面状态”，不能自动理解完整产品设计系统。使用生成结果时，需要把它当作高质量草稿，而不是不可修改的最终规范。
| 问题 | 影响 | 处理方式 |
|---|---|---|
| 页面状态不完整 | 没打开的弹窗、菜单、hover 状态可能不会被提取 | 切换到目标状态后刷新提取 |
| 响应式样式缺失 | 只在当前视口下读取样式，可能漏掉移动端规则 | 分别在桌面、平板、手机宽度下提取 |
| 第三方组件干扰 | 聊天插件、广告组件、嵌入小部件会污染设计信号 | 定制过滤规则，排除非主体区域 |
| 颜色过多 | 图标、插画、图片取色可能让色板变杂 | 合并相近颜色，手动标记主色和辅助色 |
| 推断不等于源码规范 | 计算样式是结果，未必代表团队真实 token | 结合已有设计 token 和代码变量校准 |
| 无障碍信息不足 | 视觉样式无法完整表达语义和键盘交互 | 在文档里补充 ARIA、focus、contrast 要求 |
最稳妥的做法是：用扩展快速生成第一版 DESIGN.md，再由工程师或设计师校准关键 token，尤其是颜色、字号、间距和组件状态。这样既能减少从零编写规范的时间，又能避免把页面里的偶然样式沉淀成长期规则。
适合和不适合的场景
| 场景 | 是否适合 | 原因 |
|---|---|---|
| 给 AI 工具补充视觉上下文 | 适合 | Markdown 规则比口头描述更稳定 |
| 快速整理竞品或参考站点的设计特征 | 适合 | 能快速得到颜色、排版、间距等线索 |
| 为旧项目补一份设计系统草稿 | 适合 | 老项目往往缺少系统化文档 |
| 完整还原一个复杂产品 | 不适合 | 扩展提取的是设计信号，不包含业务逻辑和完整交互 |
| 替代设计 token 源码 | 不适合 | 计算样式是页面结果，不一定是维护源头 |
| 自动完成所有无障碍设计 | 不适合 | WCAG 规则需要结合语义、交互和测试补充 |
design-md-chrome 的价值在于把“网页看起来是什么风格”转换成“可以被 AI 和工程流程使用的设计规则”。当 DESIGN.md 进入仓库后，页面生成、组件重构、样式审查都会多一个明确参照，AI 工具也不再只能凭一句模糊描述猜测设计方向。