website-to-design-md

网站转 DESIGN.md

概述

使用此技能将真实网站转化为可复用的 design.md 或 DESIGN.md 文档，以及配套的 HTML 预览。

目标不是克隆网站，而是深入检查网站，让另一个 Agent 无需查看原网站，也能复现相同的设计语言、内容语气和交互体验。

HTML 预览是一个实用的审阅界面。它应将 Markdown 转换为一目了然的设计板，让用户无需重新打开网站，就能检查配色、排版、间距、组件特征以及原始 Markdown 源码。

通用浏览器规则

此技能应始终优先使用 agent-browser。

• 将 agent-browser open、agent-browser wait，尤其是 agent-browser eval，作为主要的提取工作流。
• 不要一开始就检查用户使用的是哪款应用或平台。
• 不要根据用户使用的是 Codex、Trae、Claude、Cursor 还是其他宿主来分支处理逻辑。
• 不要一开始就检查当前项目文件夹是否包含 Playwright、Chrome CLI 或本地浏览器包。
• 如果无法使用 agent-browser，请帮助用户安装它，或将其添加到 PATH，然后继续使用相同的工作流。
• 除非用户明确要求使用单独的备用方案，否则不要悄悄切换到 Playwright、Chrome CLI 或以截图为主的提取方式。

工作方式

优先使用浏览器，并以证据为依据。

• 优先使用 agent-browser，而不是直接获取原始 HTML。实时网站的重要行为可能隐藏在水合、滚动状态、悬停状态或响应式布局变化之后。
• 将 agent-browser eval 作为主要提取层。主要证据应来自浏览器运行时中收集的 DOM 结构、渲染后的 HTML、计算样式、CSS 变量、可读的样式表规则以及交互状态。
• 不要默认使用截图作为证据来源。当可以使用 agent-browser eval 或等效的页面求值方式时，应优先使用 DOM、计算样式、CSS 变量、可读的样式表规则和提取的文本作为主要证据。
• 仅在 DOM 证据不足，或用户明确要求进行视觉验证时，才将截图作为可选的最后核对手段。
• 不要悄悄退回到 Playwright 或 Chrome CLI。如果无法使用 agent-browser，请明确检测并帮助用户安装它或将其添加到可执行路径。
• 将静态源文件视为辅助证据，而非主要事实来源。
• 将技术细节转化为设计语言。不要不加整理地倾倒 CSS；应将其综合成 Agent 能够实际使用的内容。
• 区分观察到的事实与推断。如果某项判断或规则只是推测，而非直接观察到的值，请明确标注。
• 除非用户明确选择不需要，否则应将 HTML 预览视为默认交付内容的一部分，而非可选附加项。

预检

1. 将目标规范化为一个或多个 URL。
2. 检查是否已能使用 agent-browser。
3. 如果缺少 agent-browser，请使用 scripts/check-browser-tooling.mjs，然后帮助用户安装 agent-browser 或将其添加到可执行路径。
4. 不要将检查当前文件夹中的 Playwright、Chrome CLI 或本地浏览器可执行文件作为主要处理方式。
5. 除非用户明确要求使用备用方案，否则不要悄悄退回到 Playwright 或 Chrome CLI。
6. 默认将 Markdown 输出文件命名为 DESIGN.md。
7. 默认将配套预览文件命名为相同的基本文件名加上 -preview.html，例如 DESIGN-preview.html 或 design-preview.html。
8. 如果用户明确要求使用 design.md、自定义文件名或自定义文件夹，请严格遵照，并将 HTML 预览放在同一文件夹中，除非用户要求不这样做。
9. 如果提供了多个 URL，请分别检查；只有当这些页面的视觉语言明显一致时，才综合为一套共享设计系统。

浏览器工具引导设置

将浏览器工具设置视为技能的一部分，而不是单独交给用户的任务。

检测

按以下顺序检查：

• agent-browser 是否已可调用
• 如果不可用，是否可以立即安装或使其可用

随附的检查脚本会报告：

• node 和 npm 是否可用
• agent-browser 是否可调用
• 下一步应使用哪种工具
• 是否建议安装

默认安装方式

如果 agent-browser 不可用，请协助用户安装它或将其添加到 PATH，并在使用该技能前通过 agent-browser --help 验证。

安装行为

• 说明安装是为了让技能能够稳定使用 agent-browser。
• 如果首次安装因网络或沙盒限制而失败，请申请所需的批准并重试。
• 如果安装成功，请在同一轮中直接继续分析网站。
• 如果安装失败，请明确告知用户缺少什么，并停止操作，不要悄悄改用其他提取工具。
• 不要仅仅因为缺少工具就悄悄降级为静态 HTML 抓取。

必需的提取步骤

需要进一步了解检查内容时，请使用 references/website-reading-checklist.md 中的检查清单。

1. 确定页面范围

• 确定页面用途。
• 确定页面属于营销、产品、仪表板、文档、电商、编辑内容还是混合类型。
• 从上到下识别重要的可见版块。
• 记录受限或无法访问的区域，不要凭空编造。

2. 获取基线信息

• 先检查桌面端页面。
• 如果平板和移动端的布局有显著变化，也要进行检查。
• 撰写任何内容前，缓慢滚动浏览整个页面，避免遗漏延迟动画、粘性 UI 或渐进式展开内容。
• 页面处于活动状态时，获取浏览器端代码证据：渲染后的 HTML、关键节点的 outerHTML、根 CSS 变量、可读的样式表规则，以及代表性组件的计算样式。
• 优先直接调用 agent-browser eval，或使用由 agent-browser 驱动的封装脚本，而不是切换到其他浏览器技术栈。
• 仅当用户明确需要通过 shell 生成 JSON 文件，同时仍使用 agent-browser 时，才使用 scripts/extract-browser-evidence.mjs。
• 默认步骤中不要为了截取屏幕截图而暂停。使用页面求值直接从运行中的页面提取结构和样式。

2.1 首选的求值工作流

当 agent-browser eval 或等效的浏览器求值方式可用时，请按以下顺序操作：

1. 打开页面
2. 等待页面加载和 hydration 完成
3. 滚动页面以触发延迟加载内容和粘性状态变化
4. 提取代表性节点的渲染后 HTML
5. 提取标题、按钮、卡片、导航和版块容器的计算样式
6. 提取根 CSS 变量和可读的样式表规则
7. 提取可见文本片段和 CTA 文案
8. 通过 DOM 或计算样式变化探查悬停、激活、粘性或展开状态

不要用屏幕截图代替步骤 4 至 8。

3. 提取设计系统

提取可复用的规则，而不只是页面特有的表层样式：

• 颜色及其用途
• 网站支持的浅色和深色主题变体
• 字体层级
• 间距节奏和网格行为
• 圆角样式
• 边框处理方式
• 阴影和表面层次
• 图像风格
• 图标风格
• 动效和过渡风格
• 内容密度和留白理念
• 可观察到的样式表和 CSS 变量约定
• 能说明重复组件实际结构的 DOM 模式

4. 提取组件和状态

检查主要的重复模式：

• 导航
• 公告栏
• 主视觉区块
• 按钮和链接
• 卡片
• 徽标
• 表单和输入框
• 选项卡或胶囊按钮
• 折叠面板
• 表格
• 页脚

对于每个重要组件，检查值得关注的可见状态：

• 默认
• 悬停
• 激活或选中
• 可见时的聚焦状态
• 可见时的禁用状态
• 滚动或粘性变体
• 打开或展开状态
• 网站支持切换主题时的浅色模式和深色模式变体

5. 提取交互行为

不要只关注静态视觉效果。

记录：

• 滚动时会发生什么变化
• 悬停时会发生什么变化
• 点击时会发生什么变化
• 用户在浅色模式和深色模式之间切换时会发生什么变化
• 哪些元素会通过动画进入视野
• 轮播、选项卡或粘性侧边栏是由点击、滚动还是时间驱动的
• 动效感觉有多快，风格是微妙、利落、电影感、活泼还是克制
• 在浏览器中可观察到交互过程中发生变化的 CSS 或 DOM 状态

6. 提取内容和品牌语气

把握影响设计的语气：

• 标题风格
• CTA 措辞
• 句子密度
• 产品定位
• 信任信号
• 功能命名模式
• 文案是偏技术、活泼、高端、直接、学术还是对话式

这很重要，因为好的 DESIGN.md 应同时指导视觉风格和呈现方式。

6.1 主题模式检查

如果网站支持外观切换：

• 直接在浏览器中触发浅色和深色模式切换
• 提取两种模式下的 DOM 和计算样式证据
• 记录哪些设计变量会反转，哪些强调色保持不变
• 说明两种模式下图像、阴影、边框、卡片和代码块的样式处理是否有变化
• 在最终的 Markdown 和 HTML 预览中呈现这两种模式

输出要求

使用 assets/DESIGN.template.md 中的结构撰写最终文档。

完成 Markdown 文档后，尽可能使用 scripts/render-design-preview.mjs 生成配套的 HTML 预览。

如果可以使用浏览器工具，撰写前应优先进行 DOM 和样式提取。证据顺序如下：

1. 渲染后的 HTML 和关键节点结构
2. 计算样式和 CSS 变量
3. 交互状态差异
4. 仅当用户明确要求或 DOM 证据不明确时，才可选用截图进行交叉验证

如果页面支持浅色和深色主题，输出要求还包括：

1. 在 DESIGN.md 中明确记录 Theme Modes
2. 当两种模式差异显著时，分别记录浅色模式和深色模式的设计变量
3. 在配套的 HTML 预览中呈现可见的浅色／深色主题摘要区块

文档通常应包含以下章节：

1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide

仅在能带来实际价值时添加可选附录：

• Interaction Patterns
• Content & Messaging Patterns
• Observed Pages
• Evidence Notes

如果网站提供了足够的信息，优先在这些章节中采用更丰富的 Stitch 风格小节：

• Key Characteristics
• Primary、Interactive、Neutral Scale、Surface & Overlay、Shadows & Depth
• Font Family、Hierarchy、Principles
• Buttons、Cards & Containers、Inputs & Forms、Navigation、Image Treatment、Distinctive Components
• Spacing System、Grid & Container、Whitespace Philosophy、Border Radius Scale
• Breakpoints、Touch Targets、Collapsing Strategy
• Quick Color Reference、Example Component Prompts、Iteration Guide

如果网站提供了足够的证据，不要只停留在高层概述。

HTML 预览规范

默认在 Markdown 文件旁生成一个 HTML 文件。

预览应：

• 以最终的 DESIGN.md 为事实来源，而不是使用单独手工维护的摘要
• 使用固定的预览外壳模板，而不是每次运行都新造一个 HTML 框架
• 在左侧呈现最有用的视觉规则，例如概览、配色、排版、间距、圆角、按钮、卡片、层次和响应式说明
• 在专用窗格中显示 Markdown 源文件，方便用户快速检查或复制原始文档
• 呈现为精致的设计看板，而不是普通的 Markdown 渲染
• 在切实可行时使用提取出的设计令牌，让预览本身体现文档所描述的设计系统

如果 assets/design-preview-shell.template.html 可用，请将其用作默认外壳。将该模板视为稳定的基础设施，除非用户明确要求采用新的布局方向，否则只需填入文档中指定的令牌和内容。

当用户提供布局的视觉参考时，应尽可能贴近地遵循，使生成的 HTML 明显属于同一风格，同时仍基于 Markdown 数据生成。

综合规则

编写最终文件时：

• 优先使用语义化名称，而非原始令牌标签。
• 当颜色精度很重要时，包含精确的十六进制值。
• 将圆角、间距、阴影和字体比例转化为浅显易懂的描述，方便其他 Agent 立即使用。
• 保持文档有明确主张且实用；避免倾倒大量数据。
• 说明功能作用，而不只是外观。
• 将重复出现的模式归纳为系统。
• 保留细微差异。如果网站融合了两种视觉模式，应说明两者及其各自的使用场景。
• 当细节可观察时，优先提供精确数值：十六进制颜色值、字号、行高、字间距、圆角值、间距单位和多层阴影公式。
• 当某种模式是网站身份的重要组成部分时，补充简短的理念或缘由，例如“阴影即边框”或“紧凑感即身份”。
• 当组件特定的实现提示能帮助其他 Agent 在不查看源网站的情况下构建匹配的 UI 时，应将其纳入。
• 对于内容较丰富的网站，Agent Prompt Guide 至少应包含适用于主视觉区、卡片、按钮或导航模式的可直接用于提示词的示例。

在某些值是推断得出的而非直接观察到的情况下，应明确标注，但仍确保其有参考价值。

良好示例：

• “主要操作使用冷调电光蓝 #3B82F6，搭配深炭灰色表面。”
• “卡片更具编辑感，而非应用感：柔和边框、宽裕的内边距，以及极浅的阴影分隔。”

不佳示例：

• “按钮背景是 rgb(59, 130, 246)。”
• “有一些间距和一些圆角。”

质量标准

最终的 DESIGN.md 应能直接作为其他 Agent 的提示词上下文，无需额外解释。

完成前，请检查：

• 仅凭这份文档，其他 Agent 能否复现网站的氛围？
• 是否将主要颜色与具体功能关联起来？
• 字体层级是否足够具体，可供复用？
• 是否对主要组件提供了足够详细的状态说明？
• 是否记录了会实质影响构图的响应式变化？
• 是否捕捉到了文案语气，而不只是 UI 外观？
• 是否避免编造隐藏页面或不可见状态？
• 其他 Agent 是否能据此掌握足够的间距比例、圆角比例和阴影行为，从而构建风格匹配的组件库？
• 其他 Agent 是否至少能获得 2 到 4 个可直接用于提示词的示例，用于重建标志性的版块或组件？

如果任何一项的答案是否定的，请在定稿前重新检查网站。

细节阈值

目标是编写一份更接近设计规则手册、而非灵感板的文档。

对于内容丰富的营销网站或经过精心打磨的产品网站，请包含：

• 在 Visual Theme & Atmosphere 中至少加入一段内容详实的文字
• 包含多组颜色，而不只是一个平铺的设计令牌表
• 提供完整的字体层级表，尽可能标注字号、字重、行高和字间距
• 明确说明按钮、卡片、导航以及至少一种独特设计模式的行为
• 如果阴影、边框、间距或圆角属于设计标识，请提供达到实现级别的说明
• 在最后一节中提供可直接用于提示词的示例和迭代规则

如果输出比你实际观察到的信息还简短，请在完成前补充内容。

默认交付模式

除非用户另有要求：

1. 使用 agent-browser 和 agent-browser eval 检查线上网站。
2. 在当前工作区中综合编写一份精心打磨的 DESIGN.md 文件。
3. 根据 Markdown 生成一个同级 HTML 预览文件，通常使用 scripts/render-design-preview.mjs。
4. 如果不得不改用 Shell 作为后备方案或安装工具，请在最终回复中简要说明。
5. 默认保持目标文件夹整洁。除非用户明确要求，否则不要在交付文件旁留下单独的 notes、note.md、research.md、evidence.md 或证据 JSON 文件。
6. 如果需要中间证据文件，优先使用系统临时路径。使用 scripts/extract-browser-evidence.mjs 时，除非用户希望保留该产物，否则省略输出路径。
7. 在最终回复中指出最显著的设计特征、生成的文件名以及任何证据缺口。

边缘情况

多个页面

如果用户提供了同一产品的多个 URL：

• 首先找出共通的设计规则
• 分别记录各页面特有的差异
• 避免在每个页面上重复描述相同的设计系统

身份验证墙或访问受限

如果网站的某些部分无法访问：

• 仅记录你实际检查到的内容
• 明确指出无法查看的部分
• 不要臆造隐藏的组件或流程

高度动态的应用

如果网站是复杂应用而非营销页面：

• 重点关注导航模型、信息密度、表格或面板模式、筛选器、表单、空状态以及状态变化行为
• 将仪表盘或应用框架的逻辑纳入布局原则
• 如果特定工作流会影响视觉系统，请附上简洁的交互说明

缺少工具

如果会话开始时没有可用的浏览器自动化工具：

• 先检查实际环境，不要凭空猜测
• 首先确认 agent-browser 是否已可用
• 不要一开始就在项目文件夹中检查浏览器依赖
• 如果缺少该工具，请协助用户安装它或将其加入 PATH
• 使用真实的 agent-browser --help 或同等冒烟测试验证工具是否可用
• 告知用户，工具配置是为了完成提取任务
• 除非用户明确要求使用后备方案，否则不要悄悄改用 Playwright 或 Chrome CLI

实用思路

如果文字显得过于直白，请采用以下思路：

“编写一套设计系统说明，让优秀的设计工程 Agent 在构建同一产品风格的新页面之前能够据此开展工作。”