将真实网站的视觉语言转化为可被 AI 代理直接消费的设计系统文档——这就是 web-to-design-md 的核心使命。它不满足于传统的截图存档或静态 HTML 抓取，而是深入运行中的网页，提取计算样式、CSS 变量、交互状态和内容语调，生成一份结构完整的 DESIGN.md 和配套的 HTML 预览看板。对于需要在不同代理工作流中复现同一套设计语言的团队来说，这比任何截图工具都更接近”可执行的设计系统”。

该仓库本身被打包为一个可安装的 AI Skill，直接通过 GitHub 地址分发给支持 Skill 机制的 AI 编程应用（如 Codex、WorkBuddy 等），安装后即可用自然语言驱动整个提取流程。项目诞生于 2026 年 4 月，虽然只有一次初始化提交，但其设计理念和工程规范已相当成熟——它本质上是一份”写给 AI 看的网页设计取证指南”。

📌 项目概览 & 统计数据

✨ 核心功能

• 🧬 浏览器优先的证据提取：以 agent-browser 为核心运行环境，通过 eval 命令实时采集渲染后的 DOM 结构、计算样式、CSS 变量和可读取的样式表规则，而非依赖静态源码抓取。这意味着懒加载内容、粘性 UI、交互触发的样式变化都不会被遗漏。

• 🎨 深度设计系统合成：不只输出十六进制色值和字体大小，而是将颜色映射到功能角色（主色、交互色、中性色阶），将排版整理为可复用的层级体系，将间距、圆角、阴影转化为通俗的设计语言。最终产出的 DESIGN.md 本身就可以作为提示上下文直接喂给其他 AI 代理。

• 🖼️ HTML 预览看板生成：从 DESIGN.md 自动生成配套的 HTML 预览文件，在左侧展示配色板、排版、间距、按钮、卡片等视觉规则，右侧保留原始 markdown 供检查。预览本身也使用提取出的设计 token 渲染，确保”预览即系统”。

• 🌓 浅色/深色主题双模式支持：当网站支持主题切换时，自动在浏览器中触发切换并分别提取两套模式的 token 差异，在最终的文档和预览中都完整呈现。

• 🔄 交互状态全面捕获：不仅记录静态外观，还探测悬停、激活、聚焦、禁用、粘性、展开等关键状态的变化，并记录动效的速度感受和触发机制（点击/滚动/时间驱动）。

• 📝 品牌语调提取：除视觉层面外，还会采集标题风格、CTA 文案、句子密度、产品定位方式等文本层面的品牌语调，确保后续代理生成的内容在”说话方式”上也保持一致。

🗂️ 模块/架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14

.
├── SKILL.md                           # 技能定义主文件（核心）
├── agents/
│   └── openai.yaml                    # 代理配置文件
├── assets/
│   ├── DESIGN.template.md             # design.md 输出模板
│   └── design-preview-shell.template.html  # HTML 预览外壳模板
├── references/
│   ├── browser-tooling-bootstrap.md   # 浏览器工具引导指南
│   └── website-reading-checklist.md   # 网站阅读检查清单
└── scripts/
    ├── check-browser-tooling.mjs      # 浏览器工具可用性检测
    ├── extract-browser-evidence.mjs   # 浏览器端证据批量提取
    └── render-design-preview.mjs      # 从 markdown 渲染 HTML 预览

整个仓库围绕”一个 SKILL.md + 配套脚本/模板”的极简架构构建。SKILL.md 是灵魂文件，定义了完整的工作流、提取步骤、输出规范、质量门槛和边缘情况处理；scripts/ 下的三个 Node.js 脚本分别负责环境检测、证据提取和预览渲染；assets/ 提供了固定的输出模板，保证每次运行产出的文档结构一致；references/ 存放辅助指南，供代理在边缘情况下查阅。

🛠️ 技术架构

架构上采取了”浏览器即运行时”的设计哲学。agent-browser 不仅负责打开页面，更是整个提取管道的执行环境——JS 代码通过 eval 注入页面上下文，直接读取渲染后的 DOM、getComputedStyle() 结果和 CSS 自定义属性，避免了传统静态爬取方案中大量被遗漏的动态内容。提取到的证据经过 SKILL.md 中详细定义的”合成规则”转化为设计语言，最终注入到固定模板中输出。

🚀 部署/安装方式

通过 Skill 安装器安装

1
2
3

# Codex 风格安装器
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo Paidax01/web-to-design-md --path .

直接提供 GitHub URL

如果你的 AI 编程应用支持直接通过 GitHub URL 安装 Skill，只需提供仓库地址：

1

https://github.com/Paidax01/web-to-design-md

安装后重启 AI 编程应用，Skill 即被自动发现。

手动安装

将仓库文件夹复制到本地 Skills 目录即可：

1

git clone https://github.com/Paidax01/web-to-design-md.git ~/.your-app/skills/web-to-design-md

💻 本地开发

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 1. 克隆仓库
git clone https://github.com/Paidax01/web-to-design-md.git
cd web-to-design-md

# 2. 检查浏览器工具可用性
node scripts/check-browser-tooling.mjs

# 3. 如果 agent-browser 缺失，安装它
# 具体安装方式参考 scripts/check-browser-tooling.mjs 输出的建议

# 4. 验证安装
agent-browser --help

# 5. 使用 Skill 提取网站
# 在你的 AI 编程应用中执行：
# "用 web-to-design-md 技能提取 https://example.com 的设计系统"

核心脚本说明：

• scripts/check-browser-tooling.mjs：检测 node/npm 和 agent-browser 是否可用，给出安装建议
• scripts/extract-browser-evidence.mjs：通过 agent-browser 批量提取 DOM 和样式证据（仅在用户明确要求生成 JSON 产物时使用）
• scripts/render-design-preview.mjs：从 DESIGN.md 渲染 HTML 预览看板

💡 项目亮点总结

1. 浏览器优先、证据优先的设计哲学：不依赖静态 HTML 爬取，所有设计信息从运行中的页面实时采集，懒加载、动态渲染、交互状态无一遗漏。这种”现场取证”的方式比任何基于源码的方案都更接近用户真实体验。

2. 堪比设计规则手册的输出质量：产出的 DESIGN.md 不是色值表单，而是包含颜色功能角色、排版层级、间距节奏、组件状态行为、品牌语调的完整设计系统。其他 AI 代理可以直接将其作为提示上下文，无需额外解释。

3. 极度固执但专业的工作流：SKILL.md 约定了严格的工具优先级（agent-browser → 拒绝静默降级）、提取顺序（打开→等待→滚动→采集→状态探测）和质量门槛（9 项自检问题）。这种不妥协的设计让输出质量有高度保障。

4. 自包含的安装体验：仓库本身就是一个完整的可安装 Skill，用户无需手动配置任何依赖。内置的引导脚本自动检测并安装缺失的浏览器工具，将环境设置成本降到最低。

5. 预览即系统的可视化校验：HTML 预览不是简单的 markdown 渲染，而是使用提取到的设计 token 构建的精美看板，让用户无需重新打开原网站就能验证提取结果——形成”原网站→设计文档→预览看板”的完整闭环。

🔗 参考资料

• web-to-design-md 仓库
• agent-browser（由该项目依赖和引导安装）
• SKILL.md 完整规范
• DESIGN.md 输出模板
• 网站阅读检查清单