web-to-design-md 项目深度解析

一、项目概述

web-to-design-md 是一个将活网站深度分析并生成 DESIGN.md 设计系统文档的技能。其核心理念是：不是克隆网站，而是通过深度检查，让另一个 Agent 能够在不需要查看原始网站的情况下复现相同的设计语言、内容调性和交互感受。

核心输出物

二、核心设计理念

2.1 浏览器优先（Browser-First）

原则：优先使用 agent-browser 进行数据提取，而不是静态 HTML 抓取。

agent-browser open → agent-browser wait → agent-browser eval

理由：

• 活网站的重要行为隐藏在 hydration、滚动状态、hover 状态或响应式布局变化中
• 静态 HTML 无法获取运行时的交互状态
• agent-browser eval 可以直接访问 DOM 结构、computed styles、CSS variables、stylesheet rules

2.2 证据驱动（Evidence-Driven）

核心原则：区分「观察事实」与「推断结论」。

2.3 翻译而非搬运

原则：不要盲目转储 CSS，而是将其翻译成 Agent 可以直接使用的设计语言。

Bad: "Button background is rgb(59, 130, 246)."

Good: "Primary actions use a cool electric blue #3B82F6 on dark charcoal surfaces."

2.4 质量门槛

最终的 DESIGN.md 应该能够作为另一个 Agent 的 Prompt 上下文，无需额外解释。

三、SKILL.md 结构化流程设计分析

3.1 文档结构

SKILL.md
├── Overview（概述）
├── Universal Browser Rule（通用浏览器规则）
├── Working Style（工作方式）
├── Preflight（预检）
├── Browser Tooling Bootstrap（浏览器工具引导）
├── Required Extraction Passes（必需提取步骤）
│   ├── 1. Scope the Page
│   ├── 2. Capture the Baseline
│   ├── 3. Extract the Design System
│   ├── 4. Extract Components and States
│   ├── 5. Extract Interaction Behavior
│   ├── 6. Extract Content and Brand Voice
│   └── 6.1 Theme Mode Sweep
├── Output Contract（输出契约）
├── HTML Preview Contract（HTML预览契约）
├── Synthesis Rules（合成规则）
├── Quality Bar（质量门槛）
├── Detail Threshold（细节阈值）
├── Default Deliverable Pattern（默认交付模式）
├── Edge Cases（边缘情况处理）
└── Handy Framing（心智模型）

3.2 流程设计亮点

1. Preflight 阶段

• 规范化 URL
• 检查 agent-browser 可用性
• 预设默认输出文件名（DESIGN.md + *-preview.html）
• 处理多页面场景

2. Required Extraction Passes（7个阶段）

每个阶段都有明确的输入、处理逻辑和输出要求。

3. Output Contract（输出契约）

明确定义：

• 必须包含的 9 个主要章节
• 可选的附录章节
• Stitch-style 子章节命名规范

4. Quality Bar（质量门槛）

提供 10 个检查问题，确保输出质量。

5. Edge Cases（边缘情况）

• 多页面处理
• 认证墙或部分访问
• 高度动态应用
• 工具缺失

3.3 关键设计模式

心智模型：

"Write the design system that a strong design-engineering agent would want before building a fresh page in the same product language."

四、技术架构

4.1 核心文件结构

web-to-design-md/
├── SKILL.md                           # 核心执行指南
├── assets/
│   ├── DESIGN.template.md            # 输出模板
│   └── design-preview-shell.template.html  # HTML预览模板
├── references/
│   ├── website-reading-checklist.md # 网站分析检查清单
│   └── browser-tooling-bootstrap.md # 工具引导
└── scripts/
    ├── check-browser-tooling.mjs    # 工具检测脚本
    ├── extract-browser-evidence.mjs # 证据提取脚本
    └── render-design-preview.mjs     # HTML渲染脚本

4.2 工具依赖

4.3 证据提取流程

// 推荐的 eval 顺序
1. open page
2. wait for load and hydration
3. scroll once to trigger lazy and sticky states
4. extract root CSS variables
5. extract readable stylesheet rules
6. extract representative rendered HTML
7. extract computed styles for key elements
8. extract visible text and CTA content
9. extract hover, sticky, or expanded state changes through DOM or style diffs

五、9维设计系统输出结构

5.1 必需章节

5.2 可选附录

• Interaction Patterns - 交互模式
• Content & Messaging Patterns - 内容与消息模式
• Observed Pages - 观察的页面
• Evidence Notes - 证据笔记

5.3 子章节示例

六、创新点分析

6.1 文档即代码

将设计系统文档作为可执行的规范，而不是静态的参考手册。

6.2 双向验证

• 从网站提取证据 → 生成文档
• 文档 → 生成 HTML 预览
• 预览作为验证表面

6.3 工具自举（Tooling Bootstrap）

将工具检测和安装流程内置到技能中，而不是依赖外部环境。

6.4 渐进式质量门

• Detail Threshold：定义「足够好」的标准
• Quality Bar：10 个检查问题
• Richness Check：9 个自检问题

6.5 证据命名空间

明确区分 Observed vs Inferred，避免混淆事实和推断。

七、适用场景

八、SKILL.md 编写规范借鉴

8.1 结构化章节命名

[主标题]（英文大写）
├── [副标题]
│   ├── [子项1]
│   └── [子项2]
└── [子项3]

8.2 原则定义模式

## [原则名称]

### 行为描述
[具体行为]

### 禁止行为
[明确禁止的模式]

### 例外情况
[明确的例外]

8.3 输出契约模式

## Output Contract

产出：[具体文件]

必须包含：[清单]

可选包含：[清单]

格式规范：[具体要求]

8.4 质量门槛模式

## Quality Bar

在完成前检查：
- [ ] 问题1
- [ ] 问题2
- [ ] 问题3

如果任何答案为"否"，在最终确定前重新检查。

8.5 边缘情况模式

## Edge Cases

### 情况1
- 识别方法：
- 处理方式：

### 情况2
- 识别方法：
- 处理方式：

九、总结

web-to-design-md 是一个高度结构化的设计系统文档生成技能。其核心价值在于：

1. 证据驱动：从活网站提取真实数据，而非推测
2. Agent 可读：输出可直接作为 AI Agent 的设计上下文
3. 结构严谨：9维设计系统 + 严格的质量门
4. 工具自举：内置工具检测和引导
5. 双向验证：文档 → 预览 → 验证