URL 中的 DESIGN.md
輸入:一個 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),等待 800 毫秒 - 底部:對
scrollHeight執行相同操作,等待 800 毫秒
注意在滾動時哪些元素移動、淡出或顯示。
-
動畫。 現在執行
motion.js,因為滾動後懶加載的 3D 畫布已存在。 程式庫。 首先滾動整個頁面(以約 900 像素為一步,間隔 150 毫秒;對於單螢幕網站,請使用滾輪事件),以便懶加載區塊被載入,然後執行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,附帶 easing、duration、stagger)、motionProps(Framer Motion initial/animate/whileInView)、threeObjects(使用的幾何體、材質、載入器、通道)、assets(模型、HDR、Rive、Spline、Lottie、影片、音訊)以及scripts.failed。
如何使用它:
- 最信任來自全域變數、DOM 和資源的證據。對僅在框架執行時檔案(例如 React 或 Next 內部)中發現的匹配要謹慎處理,並根據螢幕截圖顯示的內容進行確認。
- 讀取著色器,並用簡單文字說明其作用(彎曲、閃爍、飄動、圓角 SDF、噪點、粒子、地球)。將引擎、最多一兩行關鍵 GLSL 程式碼以及滾動連接放入 3D 與媒體 和 滾動行為 中。切勿將整個著色器複製到 DESIGN.md 中。
- 將
tweens和scrollTriggers轉換為具體的動畫規格(例如,「標題被分割成字母,從模糊(7px)中升起,持續時間 0.7 秒,交錯間隔 0.017 秒,power2.out,當頂部到達視口 70% 時」)。 - 如果
scripts.failed很高,表示跨域腳本阻止了fetch;在已知限制中列出此項。
-
懸停狀態。 使用
browser_hover懸停在主要 CTA、一個卡片和一個導航連結上。每次懸停後,對該元素(作為target傳入)運行browser_evaluate:(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。使用它們來發現額外的元件(價格卡片、標籤頁、表格、常見問題、表單)。 -
寫入 使用下方範本的輸出檔案。
-
檢查。 運行
npx -y @google/design.md lint <路徑>。修復每個錯誤。關於響應式行為、動畫與互動、3D 與媒體、迭代指南或已知限制的警告是預期的(自訂章節)。孤立標記警告沒問題。如果npx沒有輸出任何內容(在 Windows 的 Git Bash 中可能發生),請將其安裝到暫存資料夾中並直接運行:npm i --no-save @google/design.md然後node node_modules/@google/design.md/dist/index.js lint <路徑>。如果沒有 Node 或沒有網路,請僅說一次並跳過此步驟。 -
完成。
browser_close。告訴使用者檔案路徑、您發現的 3-5 個特徵以及已知限制。
特殊網站
- 單螢幕網站(
document.body.scrollHeight等於視口高度):滾動被頁面接管。將滑鼠移到中間並使用滾輪事件(page.mouse.wheel)而不是scrollTo,並在每幾次滾輪步驟後擷取螢幕截圖。 - 由於畫布覆蓋頁面導致懸停失敗:透過滑鼠位置懸停,然後使用
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,將其平展到畫布顏色上,形成不透明的十六進制值(通道 = 畫布 + alpha × (顏色 − 畫布)),否則檢查工具的對比度檢查會誤判。邊框可以保持為 8 位十六進制(#ffffff14)的透明形式。 - 在敘述中,引用標記時使用
`{colors.primary}`(#5e6ad2),讓讀者同時看到名稱和數值。 - 將總覽、注意事項和動畫描述建立在螢幕截圖顯示的內容上。要具體(「使用細線邊框代替陰影」),而不是籠統(「乾淨且現代」)。
- 3D:描述場景是什麼、位於何處、大小如何、引擎(來自
libraries)以及如何反應(滾動、游標、空閒循環)。切勿嘗試下載模型或著色器。 - 動畫值(持續時間、緩動函式、關鍵影格)僅以敘述形式呈現。規範中沒有
motion:標記組。
範本
examples/linear.app-DESIGN.md 是一個已完成且通過檢查的輸出範例。閱讀一次以了解預期的詳細程度。
---
version: alpha
name: <Site>-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 句話說明,包含確切的配置值(ease、duration、stagger、scrub)以及任何關鍵的著色器概念>。
**重建配方:** <重現外觀所需的最小程式庫集合,例如「Next.js + Tailwind + GSAP (ScrollTrigger, ...)」>
## 迭代指南
### 修改顏色
- 使用以下方法取得調色板的可存取變體:<工具建議>。
- 更新後在 <url1> 和 <url2> 上測試對比度。
### 新增頁面
- 重複使用 `{typography.body}` 和 `{spacing.xl}` 標記。
### 調整動畫
- 時間重構:<動畫檔案路徑>。
- 保持會話期間的 <效果> 持續時間一致。
### 在建置時驗證
- `npx @google/design.md lint .`
## 已知限制
- ...