Communitygithub.com

design-md:任意網址生成實測 DESIGN.md

用真實瀏覽器開啟任意網站,寫出 Google design.md 格式的 DESIGN.md:實測配色、字體、間距、懸停狀態、動效時長、3D 與技術棧,讓程式 Agent 做出風格一致的介面。

design-md:任意網址生成實測 DESIGN.md 是什麼?

在地商家架站配方第 1 步(先把風格定下來),來自 Ibad-10/design-md(2026-10-07 發布,附完整 linear.app 範例)。給它一個網址,它驅動 Playwright MCP:等開場動畫播完,執行 extract.js 取設計權杖,截取頁首/頁中/頁尾,執行 motion.js 與 stack.js(框架、UI 套件、GSAP/ScrollTrigger 動畫參數、著色器、Lenis、輪播),比對主按鈕、卡片與導覽連結的懸停差異,檢查 390px 行動版,再抽查最多 3 個內頁,最後寫出 YAML 權杖加概覽、配色、字體、版面、元件、該做與不該做、響應式、動效與互動、3D 與媒體、技術棧和已知缺口,並以 @google/design.md 檢查。每個數值都來自線上頁面,不捏造。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Ibad-10/design-md/tree/HEAD/skills/design-md

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 支援此操作。

流程

  1. 開啟。 browser_navigate 到該 URL。browser_resize 調整為 1440x900。如果 Cookie 橫幅遮蓋了內容,點擊其接受/關閉按鈕。如果您看到驗證碼或「被封鎖」頁面,請停止。告訴使用者,不要寫入任何內容。

  2. 等待進場動畫。 等待 3 秒,然後擷取螢幕截圖。如果英雄區域看起來空白、模糊或半透明,則表示仍在顯示中:再等待 2 秒並再次擷取。記錄其顯示效果(模糊淡入、向上淡入、交錯漸顯)作為動畫與互動。在英雄區域完全可見之前不要執行任何操作,因為在動畫中讀取的值是錯誤的。 代碼。 執行 extract.js。保留結果。

  3. 查看。 在桌面寬度下擷取螢幕截圖:

    • 頁面頂部
    • 中間:browser_evaluate () => scrollTo(0, document.body.scrollHeight / 2),等待 800 毫秒
    • 底部:對 scrollHeight 執行相同操作,等待 800 毫秒

    注意在滾動時哪些元素移動、淡出或顯示。

  4. 動畫。 現在執行 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;在已知限制中列出此項。
  5. 懸停狀態。 使用 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 元件變體。

  6. 行動版。 browser_resize 調整為 390x844,滾動到頂部,等待 3 秒(進場動畫重播),擷取一張螢幕截圖。注意導航如何摺疊,以及字體比例和網格如何變化。

  7. 更多頁面。 從主導航中,選擇最多 3 個內部連結(偏好價格、產品/功能、文檔/部落格)。對於每個連結,導航到該頁面,擷取一張螢幕截圖並執行 extract.js。使用它們來發現額外的元件(價格卡片、標籤頁、表格、常見問題、表單)。

  8. 寫入 使用下方範本的輸出檔案。

  9. 檢查。 運行 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 或沒有網路,請僅說一次並跳過此步驟。

  10. 完成。 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 .`

## 已知限制

- ...

相關技能