DESIGN.md 来自URL
输入:一个URL。可选的第二个参数:输出路径(默认 ./DESIGN.md)。
使用 Playwright MCP (mcp__plugin_playwright_playwright__*)。先通过一次 ToolSearch 调用加载浏览器工具。
运行脚本
extract.js、motion.js 和 stack.js 位于此文件旁边。运行其中一个:读取它,去掉开头的注释行,将剩下的箭头函数作为 browser_evaluate 的 function 参数传递。所有脚本均返回 JSON。stack.js 是异步的(它会获取脚本),browser_evaluate 支持异步。
流程
-
打开。
browser_navigate到 URL。browser_resize到 1440x900。如果 Cookie 横幅覆盖了内容,点击其接受/关闭按钮。如果你看到验证码或“被屏蔽”页面,停止。告知用户,不写任何内容。 -
等待介绍动画。 等待 3 秒,然后截取屏幕截图。如果英雄区域看起来空白、模糊或半透明,说明它仍在显示:再等待 2 秒并重新截取。记录显示方式(模糊进入、淡入上移、交错)用于“动效与交互”。在英雄区域完全可见之前不要运行任何操作,因为中途读取的值是错误的。 令牌。 运行
extract.js。保留结果。 -
查看。 在桌面宽度下截取屏幕截图:
- 页面顶部
- 中间:
browser_evaluate() => scrollTo(0, document.body.scrollHeight / 2),等待 800ms - 底部:相同操作,使用
scrollHeight,等待 800ms
注意在滚动时哪些内容移动、淡出或显示。
-
动效。 现在,在滚动之后运行
motion.js,以便懒加载的 3D Canvas 已经存在。 栈。 先滚动整个页面(每次约 900px,间隔 150ms;在单屏网站上使用滚轮事件),以便加载懒加载内容,然后运行stack.js。它检查页面全局变量、DOM、已加载资源、CSS 以及每个已加载脚本(内联和懒加载块)的文本,并返回:stack:按类别分类的库,每个都有证据:框架/平台(Next、Nuxt、Astro、SvelteKit、Gatsby、Remix、React、Vue、Angular、Svelte、Framer、Webflow、Wix、Squarespace、Shopify、WordPress、Lovable),UI 套件/图标(Tailwind、Radix/shadcn、Headless UI、MUI、Chakra、Mantine、Ant、Bootstrap、Sonner、Lucide、Font Awesome、Phosphor),3D(Three.js、React Three Fiber、drei、postprocessing、OGL、Babylon、PlayCanvas、A-Frame、regl、twgl、curtains.js、Spline、model-viewer、COBE、Unicorn Studio、Vanta、原始 WebGL),2D(PixiJS、p5、Paper、Konva、tsParticles、Rive、Lottie),动效(GSAP + Flip/Draggable/MorphSVG/DrawSVG/MotionPath/CustomEase、Framer Motion、anime.js、React Spring、Velocity、Popmotion、AutoAnimate、Theatre.js),滚动(ScrollTrigger、ScrollSmoother、Observer、Lenis、Locomotive、smooth-scrollbar、AOS、ScrollReveal、Rellax、CSS 滚动驱动),文字(SplitText、SplitType、Splitting、Typed、ScrambleText),滑块(Swiper、Splide、Embla、Keen、Glide、Flickity、Slick),页面过渡(Barba、Swup、Taxi、Highway、View Transitions),音频(Howler、Tone),物理(Matter、cannon-es、Rapier)。note:当 WebGL 在没有通用 3D 引擎的情况下运行时设置,表示手写 WebGL。components:手风琴、标签页、对话框、菜单、工具提示、轮播、跑马灯、表单、视频、iframe、动画 SVG、自定义光标、预加载器和主题切换的计数。shaders(GLSL 源代码)、scrollTriggers(触发/开始/结束/擦除/固定)、tweens(GSAP to/from,带有缓动、持续时间、交错)、motionProps(Framer Motion initial/animate/whileInView)、threeObjects(使用的几何体、材质、加载器、通道)、assets(模型、HDR、Rive、Spline、Lottie、视频、音频)以及scripts.failed。
如何使用:
- 最信任来自全局变量、DOM 和资源的证据。谨慎对待仅在框架运行时文件(例如 React 或 Next 内部)中找到的匹配,并对照屏幕截图确认。
- 读取着色器并用通俗语言说明其作用(弯曲、闪烁、飘动、圆角 SDF、噪声、粒子、地球)。在 3D & 媒体 和 滚动行为 中写出引擎、最多一两行关键 GLSL 代码以及滚动绑定。切勿将整个着色器复制到 DESIGN.md 中。
- 将
tweens和scrollTriggers转换为具体的动效规格(例如,“标题拆分为字母,从 blur(7px) 上升,0.7s,交错 0.017s,power2.out,当顶部到达视口 70% 时”)。 - 如果
scripts.failed很高,则跨域脚本阻止了fetch;在已知差距中列出。
-
悬停状态。 使用
browser_hover悬停主要 CTA、一个卡片和一个导航链接。每次悬停后,在该元素上运行browser_evaluate(将其作为target传递),使用(el) => { const s = getComputedStyle(el); return { bg: s.backgroundColor, color: s.color, border: s.borderColor, shadow: s.boxShadow, transform: s.transform, opacity: s.opacity }; }。与extract.js中的静态值进行比较。每个差异成为-hover组件变体。 -
移动端。
browser_resize为 390x844,滚动到顶部,等待 3 秒(介绍动画重放),截取一张屏幕截图。注意导航如何折叠以及字体大小和网格如何变化。 -
更多页面。 从主导航中选择最多 3 个内部链接(首选定价、产品/功能、文档/博客)。对于每个链接,导航,截取一张屏幕截图,并运行
extract.js。使用它们找到额外的组件(定价卡片、标签页、表格、FAQ、表单)。 -
写入 带有下面模板的输出文件。
-
整理。 运行
npx -y @google/design.md lint <path>。修复每个错误。关于响应式行为、动效与交互、3D & 媒体、迭代指南或已知差距的警告是预期的(自定义部分)。孤立令牌警告没问题。如果npx没有输出任何内容(在 Git Bash for Windows 上可能发生),将其安装到临时文件夹并直接运行:npm i --no-save @google/design.md然后node node_modules/@google/design.md/dist/index.js lint <path>。如果没有 Node 或没有网络,明确说明一次并跳过此步骤。 -
完成。
browser_close。告知用户文件路径、你发现的 3-5 个签名特征以及已知差距。
不常见的网站
- 单屏网站(
document.body.scrollHeight等于视口高度):滚动被页面接管。将鼠标移动到中心并使用滚轮事件(page.mouse.wheel)代替scrollTo,并在每次滚动几步后截取屏幕截图。 - 悬停失败因为 Canvas 覆盖了页面:通过鼠标位置悬停,然后使用
document.elementsFromPoint(x, y)读取光标下的元素,跳过CANVAS。如果计算样式没有变化,则效果是在 WebGL 或 JS 中绘制的;在已知差距中记录。 - 白色 UI 文本在浅色背景上 表示
mix-blend-mode: difference。检查getComputedStyle(el).mixBlendMode并记录颜色在屏幕上的外观(255 − 背景)以及混合模式。 - 预加载器:如果第一张屏幕截图只显示徽标或名称,则将其记录为组件,然后等待更长时间(8 秒或更长,包括移动端)。
- 引导模态框或基于对象的导航(房间、电视、桌面):将模态框捕获为组件,逐步浏览,然后打开至少一个“房间”并提取为子主题。
- 主题切换:
page.emulateMedia({ colorScheme: 'dark' })显示深色主题;读取prefers-color-scheme或[data-theme]CSS 变量。如果切换按钮超时,通过[aria-label="..."]使用{ force: true }点击,或直接从样式表中读取[data-theme="light"]规则。 - 按钮文本中重复的字母(“GGeett iinn”)表示逐字母文本滚动悬停效果:在“悬停与焦点状态”下记录。
- 模板残留(例如未使用的 shadcn 变量如
--primary: 229 84% 39%):忽略屏幕截图未显示的 CSS 变量。
如果 browser_evaluate 调用抛出错误,等待 2 秒并重试一次。如果再次失败,则继续而不使用该数据,并在已知差距中记录。
编写规则
- 每个十六进制颜色、尺寸、粗细、圆角、阴影、持续时间和缓动都来自提取的数据。切勿虚构值。如果某个值缺失,则省略并在已知差距中列出。
- 将近似重复项合并为清晰的缩放。例如,间距
7px 8px 9px变为8px。忽略使用少于 3 次的颜色,除非它们明显是强调色。 - 颜色令牌使用语义名称:
primary、on-primary、primary-hover、ink、ink-muted、ink-subtle、canvas、surface-1..n、hairline、semantic-success|warning|error。对翻转的浅色/深色部分使用inverse-*。 - 排版令牌:
display-xl/lg/md、headline、subhead、body-lg、body、body-sm、caption、button、eyebrow、mono。将像素行高转换为无单位比值(64px 在 64px 上变为1.0)。 - 在
components:中,使用令牌引用,如"{colors.primary}"和"{typography.button}"。将每个状态放在自己的键中(button-primary、button-primary-hover)。允许的属性:backgroundColor、textColor、typography、rounded、padding、size、height、width。 - 透明颜色(
#ffffff @0.08在提取输出中):对于组件backgroundColor,将其平铺到画布颜色上,得到一个不透明的十六进制颜色(通道 = 画布 + α × (颜色 − 画布)),否则整理器的对比度检查会出错。边框可以保留为 8 位十六进制颜色(#ffffff14)。 - 在散文中,引用令牌如
`{colors.primary}`(#5e6ad2),使读者同时看到名称和值。 - 基础概述、注意事项和动效描述基于屏幕截图显示的内容。具体(“发丝边框而非阴影”),不要泛泛而谈(“简洁且现代”)。
- 3D:描述场景是什么、位置、大小、引擎(来自
libraries)以及如何响应(滚动、光标、空闲循环)。切勿尝试下载模型或着色器。 - 动效值(持续时间、缓动、关键帧)仅以散文形式出现。规范中没有
motion:令牌组。
模板
examples/linear.app-DESIGN.md 是一个完整、整理后干净的输出。阅读一次以了解预期的详细程度。
---
version: alpha
name: <站点>-design-analysis
description: "<一个密集段落:画布颜色、墨水、单一强调色、显示字体及字距、卡片处理、签名主题。内联十六进制颜色。>"
colors:
primary: "#..."
on-primary: "#..."
primary-hover: "#..."
ink: "#..."
ink-muted: "#..."
canvas: "#..."
surface-1: "#..."
hairline: "#..."
typography:
display-xl:
fontFamily: <字体>
fontSize: 64px
fontWeight: 510
lineHeight: 1.0
letterSpacing: -1.4px
body:
fontFamily: <字体>
fontSize: 16px
fontWeight: 400
lineHeight: 1.5
button:
fontFamily: <字体>
fontSize: 14px
fontWeight: 510
lineHeight: 1.0
rounded:
sm: 4px
md: 8px
lg: 12px
pill: 9999px
spacing:
xxs: 4px
xs: 8px
sm: 12px
md: 16px
lg: 24px
xl: 32px
section: 96px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.on-primary}"
typography: "{typography.button}"
rounded: "{rounded.md}"
padding: 8px 14px
button-primary-hover:
backgroundColor: "{colors.primary-hover}"
feature-card:
backgroundColor: "{colors.surface-1}"
textColor: "{colors.ink}"
rounded: "{rounded.lg}"
padding: 24px
top-nav:
backgroundColor: "{colors.canvas}"
textColor: "{colors.ink}"
height: 64px
---
## 概述
<2-4 段落:氛围、密度、个性、页面节奏、使其易于识别的元素。>
**关键特征:**
- ...
## 颜色
> 来源页面:<访问的页面列表>
### 品牌与强调色
- **<描述性名称>**({colors.primary}):<角色>
### 表面
### 文本
### 语义
## 排版
### 字体系列
### 层级
| 令牌 | 大小 | 粗细 | 行高 | 字距 | 用途 |
|-------|------|--------|-------------|----------|-----|
### 原则
### 关于字体替代的说明
<如果字体是专有的,则提供开源后备字体。>
## 布局
### 间距系统
### 网格与容器
<最大宽度、列数、间距。>
### 留白哲学
## 高度与深度
| 层级 | 处理方式 | 用途 |
|-------|-----------|-----|
<来自 extract.js 的阴影,或没有阴影时如何实现层次(表面阶梯、发丝线)。>
### 装饰性深度
## 形状
### 边框圆角缩放
### 摄影与插图几何形状
## 组件
### 按钮
**`button-primary`**:<使用令牌引用的描述,包括其悬停状态>
### 卡片与容器
### 输入框与表单
### 导航
### 页脚
### <其他特定于站点的组件>
## 注意事项
### 应该做
- ...
### 不应该做
- ...
## 响应式行为
### 断点
| 名称 | 宽度 | 关键变化 |
|------|-------|-------------|
### 触摸目标
### 折叠策略
### 图像行为
## 动效与交互
### 时间与缓动
| 用途 | 属性 | 持续时间 | 缓动 |
|-----|----------|--------|-------------|
<来自 motion.js 的转场,按使用频率排序。>
### 悬停与焦点状态
<来自悬停差异:变化的内容及速度。>
### 滚动行为
<平滑滚动、吸附、粘性元素、屏幕截图中看到的滚动显示效果、库(Lenis、GSAP ScrollTrigger、AOS)。>
### 环境动效
<循环关键帧:名称、它们动画化的内容、持续时间。>
### 减少动效
<站点是否有 prefers-reduced-motion 规则?推荐的后备方案。>
## 3D & 媒体
<如果没有:"没有 3D 或视频。深度来自 <X>。" 否则,每个场景或视频一个条目:>
- **<场景名称>**:<引擎>、<位置和大小>、<展示内容>、<如何响应>。使用 <引擎/方法> 重建;静态后备:<海报图像 / 渐变>。
## 技术栈
| 层级 | 使用 | 证据 |
|-------|------|----------|
<每个 stack.js 中有命中的类别一行:框架/平台、UI 套件、3D、2D、动效、滚动、文字、滑块、页面过渡、音频。证据 = 全局变量、DOM 标记或文件。>
**签名效果的构建方式:**
- **<效果名称>**:<库 + 技术,用 1-3 句话描述,包含精确的配置值(缓动、持续时间、交错、擦除)以及关键着色器思想(如果有)。>
**重建配方:** <重现外观所需的最小库集合,例如 "Next.js + Tailwind + GSAP (ScrollTrigger, ..."。>
...
[截断以进行翻译]