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. 提取元件和狀態

檢查主要的重複模式：

• 導航
• 公告欄
• Hero 區塊
• 按鈕和連結
• 卡片
• 徽章
• 表單和輸入框
• 標籤頁或膠囊
• 手風琴
• 表格
• 頁腳

對於每個重要元件，檢查相關的可見狀態：

• 默認
• 懸停
• 活動或選中
• 聚焦（如果可見）
• 禁用（如果可見）
• 滾動或黏性變體
• 打開或展開狀態
• 淺色模式和深色模式變體（如果網站支援主題切換）

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 時，包含它們。
• 在大型網站的 代理提示指南 中，至少為 hero、卡片、按鈕或導航模式包含提示就緒的範例。
• 當某些值是推斷而非觀察時，保持明確標記但仍有用的狀態。

好的範例：

• "主要操作使用涼爽的電藍色 #3B82F6"
• "陰影由三層組成：內陰影 (darker)，主要陰影 (medium) 和擴散陰影 (lighter)"
• "輸入框獲得 2px 的 --focus-ring 藍色邊框，而不是改變背景"

要避免的範例（純資料傾倒，無語義結構）：

• "顏色：藍色 (#3B82F6)，灰色 (#6B7280)，白色 (#FFFFFF)..."
• "字型大小：16px，18px，24px，32px，48px"