Paidax01/web-to-design-md

网站到 DESIGN.md

概述

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

目标不是克隆网站。目标是深入检查它，以便另一个代理可以重新创建相同的设计语言、内容风格和交互感觉，而无需查看原始网站。

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 抓取。一个真实的网站通常将重要行为隐藏在 hydration、滚动状态、悬停状态或响应式布局变化之后。
• 将 agent-browser eval 视为主要提取层。主要证据应来自 DOM 结构、渲染后的 HTML、计算样式、CSS 变量、可读的样式表规则以及在浏览器运行时内收集的交互状态。
• 不要将截图作为默认证据来源。当 agent-browser eval 或等效的页面评估路径可用时，使用 DOM、计算样式、CSS 变量、可读的样式表规则和提取的文本作为主要证据。
• 仅将截图作为可选的最后手段交叉检查，当 DOM 证据不足或用户明确要求进行视觉验证时使用。
• 不要静默回退到 Playwright 或 Chrome CLI。如果 agent-browser 不可用，明确检测到这一点并帮助用户安装或暴露它。
• 将静态源文件视为支持性证据，而非主要事实来源。
• 将技术细节转化为设计语言。不要盲目转储 CSS；将其合成为代理实际可用的内容。
• 区分观察到的事实和推断。如果某物是判断或可能的规则，而非直接观察到的值，请明确标记。
• 将 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，请独立检查每个 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 中明确记录 主题模式
2. 当材料不同时，分别记录浅色模式和深色模式令牌
3. 在配套 HTML 预览中显示可见的浅色/深色主题摘要块

文档通常应包含以下部分：

1. 视觉主题与氛围
2. 调色板与角色
3. 排版规则
4. 组件样式
5. 布局原则
6. 深度与层次
7. 注意事项
8. 响应式行为
9. 代理提示指南

仅当它们带来真正价值时添加可选附录：

• 交互模式
• 内容与消息传递模式
• 观察到的页面
• 证据说明

在这些部分中，当网站支持时，优先使用更丰富的 Stitch 风格子部分：

• 关键特征
• 主要色、交互色、中性色阶、表面与叠加、阴影与深度
• 字体系列、层次结构、原则
• 按钮、卡片与容器、输入与表单、导航、图像处理、特色组件
• 间距系统、网格与容器、留白哲学、圆角比例
• 断点、触摸目标、折叠策略
• 快速颜色参考、示例组件提示、迭代指南

如果网站暴露了足够多的证据来使文档更精确，则不要将文档停留在高层摘要的水平。

HTML 预览契约

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

预览应：

• 使用最终的 DESIGN.md 作为其事实来源，而不是单独手动维护的摘要
• 使用固定的预览外壳模板，而不是每次运行时新发明的 HTML 框架
• 在左侧展示最有用的视觉规则，例如概述、调色板、排版、间距、圆角、按钮、卡片、深度和响应式说明
• 保持 markdown 源代码在专用窗格中可见，以便用户可以快速检查或复制原始文档
• 感觉像一个精致的设计板，而不是一个普通的 markdown 渲染
• 在可能的情况下使用提取的设计令牌，以便预览本身反映记录的系统

当可用时，使用 assets/design-preview-shell.template.html 作为默认外壳。将该模板视为稳定基础设施，仅将记录的令牌和内容填充到其中，除非用户明确要求新的布局方向。

当用户提供布局的视觉参考时，紧密跟随它，使 HTML 在视觉上属于同一系列，同时仍从 markdown 数据生成。

合成规则

编写最终文件时：

• 优先使用语义名称而非原始令牌标签。
• 当颜色精度重要时包含精确的十六进制值。
• 将圆角、间距、阴影和字阶转化为另一个代理可以立即使用的简单语言。
• 保持文档有观点且可用；避免巨大的数据转储。
• 解释功能角色，而不仅仅是外观。
• 将重复出现的模式组合成系统。
• 保留细微差别。如果网站混合了两种视觉模式，请描述两者以及每种模式出现的时间。
• 优先使用可观察到的精确数字细节：精确的十六进制值、字体大小、行高、字间距、圆角值、间距单位和多层阴影公式。
• 当一个模式对网站身份至关重要时，添加简短的理念或理由，例如“阴影即边框”或“压缩即身份”。
• 包含组件特定的实现提示，以帮助其他代理在未看到源网站的情况下构建匹配的 UI。
• 在大型网站的 代理提示指南 中至少包含英雄、卡片、按钮或导航模式的提示就绪示例。
• 当某些值是推断而非观察时，保持明确标记但仍然有用。

好：

• “主要操作使用冷酷的电蓝色 #3B82F6

...（内容截断用于翻译）