preview-first 是做什麼的？
先看清楚再建構。此技能在撰寫任何應用程式程式碼之前，插入一個設計階段：開發者會在瀏覽器中看到數個完整且明顯不同的設計方向，從中挑選一個，而這個選擇將成為一份書面合約，後續每個階段都必須遵循。
這是一個設計工作室階段，而非網站產生器。此技能絕不會撰寫開發者的應用程式程式碼。它只產出一個決策和一份合約。腳本是確定性的，且使用標準函式庫 Python；判斷（閱讀摘要、為方向命名、撰寫文案）則由您負責。
何時執行、何時提議
當開發者即將啟動、重新啟動或重新設計一個網頁專案時，執行完整階段：「為 X 建立一個登陸頁面」、「啟動前端」、「我不喜歡這個看起來的樣子」、「挑選顏色和字體」，或明確的 /preview-first。
當專案已有 UI 程式碼但沒有 design/DESIGN.md 時，用一句話提議此技能：「想先看看設計方向嗎？我可以將目前的外觀與其他替代方案並排顯示。」如果接受，將現有外觀匯入為一個方向（請參閱「匯入」），以便在同等條件下進行比較。
切勿對已設定樣式的應用程式進行小型編輯時觸發（如「新增一個按鈕」、「修正內距」）。當 design/DESIGN.md 存在時，直接跳到「交棒之後」。
流程
所有腳本都位於此技能的 scripts/ 目錄下。使用 python3（或當專案使用 uv 時使用 uv run python3）來執行。以下路徑皆相對於專案根目錄。
1. 讀取專案，然後最多問四個問題
在提出任何問題之前，先讀取現有內容：package.json、Tailwind 設定、CSS 自訂屬性、LOGO SVG、現有字體、README。任何找到的東西都是約束條件，而非需要詢問的問題。
只詢問儲存庫無法回答的問題，使用平實的語言，在一則訊息中提出：
- 產品是什麼，以及它的目標對象是誰？請用一句話說明。
- 三個詞來描述它應該給人的感覺，或一個他們欣賞的網站。
- 任何固定的元素：品牌色、LOGO、字體、僅限淺色或深色模式。
- 哪一種頁面類型最重要：行銷、應用程式、內容或商店。
2. 撰寫摘要（Brief）
將答案標準化，寫入 .design-preview/brief.json：
{
"product": "Ledgerline，一款專為自由開發者設計的發票工具",
"audience": "獨立開發者和小型工作室",
"product_type": "product-type.saas",
"moods": ["精確", "冷靜", "值得信賴"],
"page_type": "marketing",
"constraints": {"brand_colors": ["#154d8c"], "fonts": [], "scheme": "both"},
"admired": ["https://linear.app"],
"words": {"name": "Ledgerline", "tagline": "與你的 git 記錄相符的發票"}
}
使用 recommend.py --list product-types 和 --list moods 將自由文字對應到節點 ID。未知的詞彙也無妨；推薦器會透過別名和代碼重疊進行回退。產品類型同樣接受自由文字。
3. 撰寫文案，然後在一分鐘內開啟預覽
先撰寫 .design-preview/copy.json；這只需要一個簡短回覆，也是讓草稿讀起來像是該產品而非範本的關鍵。使用產品自己的名詞：導覽是它的章節，功能是它做的事情，標題是用戶會重複說出的主張。
{
"headline": "501、Cricket 和 Around the Clock 的即時比分",
"subhead": "Oche 負責記分，讓玩家可以專心比賽。",
"lead": "專為酒吧聯盟的球員和在家相聚的朋友們設計。",
"cta_primary": "新遊戲", "cta_secondary": "繼續",
"nav": ["遊戲", "玩家", "統計", "設定"],
"features": [{"title": "501 和 301 附帶結標提示", "body": "每個剩餘分數都會顯示標準的結標路線。"}],
"proof": "", "meta": {"city": "里茲", "year": "2026"},
"footer": "Oche 負責記分。"
}
然後執行一個指令：
python3 <skill>/scripts/quick_start.py --brief .design-preview/brief.json --copy .design-preview/copy.json --count 5 --open
它會推薦套件、產生 directions.json、建立預覽並啟動伺服器。立即將 URL 提供給開發者。如果您跳過 --copy，草稿會使用從摘要名詞衍生的文案；絕不要將這種草稿作為完成的方向來呈現。在開發者查看的同時，修改 directions.json（名稱、理由、版面、程式），然後重新建置；頁面會重新整理到相同的 URL。
每個預覽頁面都帶有三個產生器（在工具列中），讓開發者無需返回即可獲得更多選擇：給我驚喜（一個隨機組合的方向：未使用的風格、合適的色板和配對、隨機抽取的想法、章節和程式）、變化（當前所看方向的五種變體：相同風格，其他色板、配對、想法和程式）以及，在圖庫頁面上，顯示所有風格（針對此摘要，每個風格一個方向）。每個產生器都會導向新的草稿，該草稿也帶有相同的按鈕。從終端機：
random_direction.py --directions .design-preview/directions.json --build .design-preview [--like B | --all]。
3a. 手動建立候選套件
python3 <skill>/scripts/recommend.py --brief .design-preview/brief.json --count 4
每個套件包含一個風格、色板、字體配對、元件處理方式、動畫模式、圖示集以及八到十二個設計概念（ideas：有來源的動作，例如帶有即時時間的分割導覽、標本英雄區、巨大數字、底片顆粒效果、括號按鈕、版權說明頁尾），並附有證明其合理性的圖形邊緣，以及用於交換的即時替代方案。強制多樣性：不同的風格家族，最多兩個相同色溫的色板，最多兩個相同類別類型的配對，不使用重複的色板或配對。預設三到五個套件，當開發者要求查看更多時最多可達八個。不要少於三個；如果摘要範圍很窄（僅限深色模式，僅一個品牌色），也請說明情況並仍然顯示三個。
4. 建立 directions.json
將套件轉化為 .design-preview/directions.json（結構定義在 knowledge/schema.json，files.directions）。為每個方向提供腳本無法提供的內容：
name：一個概念，而非風格（例如「Ledger」、「Greenhouse」、「Night shift」）。絕不使用「Modern」或「Clean」。rationale：一個段落，引用摘要的原文，並說明為什麼這個方向能回應這些要求。提及一個大膽的選擇以及保持低調的部分。copy：來自摘要的真實文案：標題、副標題、兩個行動呼籲、四個導覽標籤、三到六個功能（每個有標題和一句話說明）、一句誠實的證明（或留空）、一個表單標題（附欄位標籤和提交按鈕文字）、一句頁尾文字。使用句子大小寫、主動語態、產品名詞，不使用 em dash、emoji、箭頭、「無論你是 X 還是 Y」、三句式排比、lorem ipsum、虛構數字。除非一個方向的語氣確實不同，否則所有方向的文案應相同。layout（可選）：覆蓋章節變體；否則將由方向的概念以及風格的預設值來選擇。bundle.ideas（保留或編輯）：推薦器附加的概念。刪除一個不適合產品的概念，當摘要或欣賞的網站要求時，從recommend.py --list ideas中新增一個。帶有渲染鉤子的概念會改變草稿；其餘的概念則進入合約。copy.numbers和copy.stats（可選）：有來源的數據{value, label, source}；只有當這些存在時，數字英雄區和統計牆才會渲染，絕不使用虛構數字。copy.meta（可選）：{"city": "里斯本"}，用於分割導覽、版權說明頁尾和覆蓋時鐘。- 產品類型帶有一個主題套件（藝術品類型、主題元件，例如終端機、帳單、時間表、編輯器、記分板，以及該產品特有的名詞）。第一個畫面及其後的章節會使用它，因此記分板會以分數開場，商店則以產品開場。將
layout.topic設為none以移除主題元件。 overrides（可選）：{"brand_primary": "#hex", "brand_accent": "#hex"}，當摘要指定了品牌色時使用。建置器會重新計算衍生顏色，並報告任何對比度失敗。
在建置之前，對每個方向執行 references/anti-patterns.md 中的「反特徵（tell）」檢查。拒絕一個反特徵，除非摘要明確要求，並在理由中說明。
第一個畫面規則：沒有方向應以通用模板開場（置中標題、兩個按鈕、一個螢幕截圖，然後三個相同的卡片）。每個風格預設使用一種從欣賞的網站觀察到的版面原型（帶有說明的陳述段落、圍繞扁平圓盤的文字排版、產品優先的舞台、展示字體旁的物件、滿版藝術、側邊欄索引、海報式排版）以及從色板衍生的生成藝術（藍圖、等距圖形、終端機、瑞士式構圖、輪廓、半色調、軌道環、貼紙、迷你圖、單一標記）。除非摘要明確要求熟悉的外觀，否則保留這些預設值。至少要有兩個方向來自標記為 distinct 的風格；推薦器會強制執行此規則，並確保沒有兩個方向共享相同的導覽裝置、第一個畫面裝置或紋理。
5. 建置並開啟預覽
python3 <skill>/scripts/build_preview.py --directions .design-preview/directions.json
python3 <skill>/scripts/serve_preview.py --dir .design-preview --open
build_preview.py 會寫入 .design-preview/ 目錄：一個圖庫，以及每個方向的一個風格圖塊（兩個模式下的色板（含對比度等級）、字體比例、間距、圓角半徑、陰影、圖示、每個元件的所有狀態、可播放的動畫模式）、一張針對摘要頁面類型的草稿頁面，以及一個裝置視圖，該視圖會在 CSS 繪製的、最受歡迎手機、摺疊機、平板和筆電的真實視口大小框架內渲染草稿。每個頁面上的控制項可以即時切換色板、字體配對、圓角半徑、密度、動畫級別和主題。
serve_preview.py 會啟動一個分離的 localhost 伺服器，寫入 .design-preview/server.json，輸出 URL 並立即返回。為離線工作階段新增 --vendor-fonts 到建置指令；否則當網頁字體載入失敗時，圖塊會顯示一個可見的提示。
如果瀏覽器無法開啟（SSH、容器、CI 環境），請輸出 URL 和方向列表（每個方向一行），並在對話中繼續。
6. 告知開發者，然後等待
說明您建置了什麼，提供 URL，用一行文字為每個方向命名，然後停止。不要為他們挑選，不要開始撰寫程式碼，不要輪詢。開發者可能會在預覽中花費很長時間。當他們回覆時：
- 如果
.design-preview/selection.json存在，請讀取它。它包含最終選擇的方向 ID 和即時覆蓋值（色板、字體配對、圓角半徑、密度、動畫級別、主題）。 - 否則，從他們的文字中獲取選擇（「B」、「深色那個」、「A 但使用 D 的字體」），並自行撰寫
selection.json，附帶相符的覆蓋值。 - 對於變異要求（「B 但更暖一些」、「減少圓角」、「更換標題字體」），編輯
directions.json（或使用套件中的替代方案），重新建置，並將他們導回相同的 URL。伺服器持續運行；請他們重新整理頁面。 - 對於「給我看更多」，使用
--count 5或修改後的摘要再次執行recommend.py，將新的方向以新的 ID 加入，然後重新建置。
serve_preview.py --dir .design-preview --wait 1800 會阻塞直到選擇存在，僅供腳本化使用。--status 和 --stop 用於管理伺服器。
7. 匯出合約
python3 <skill>/scripts/export_design.py --selection .design-preview/selection.json \
--directions .design-preview/directions.json --project .
這會寫入 design/DESIGN.md（合約內容：識別、設計概念（附來源和建置說明）、色板（含對比度表格）、字體排印、間距和圓角半徑、陰影、版面、每個元件的所有狀態及代碼、動畫代碼和允許的模式、圖示、意象、寫作風格、無障礙最低標準、裝置檢查，以及「禁止事項」列表）、design/tokens.json（W3C 設計代碼格式）、design/tokens.css、design/tailwind.css（當檢測到 Tailwind v4 時）、CLAUDE.md 中的一列指標行，以及 .gitignore 中的 .design-preview/ 條目。重新匯出會保留「專案註記」章節，並將先前的檔案複製到 design/history/。
用一個簡短訊息確認已寫入的內容以及開發者應提交的內容（design/ 和 CLAUDE.md 中的那一行）。然後在合約下進行建置。
交棒之後
每當 design/DESIGN.md 存在時：
- 在進行任何 UI 變更之前，先讀取它。在元件中使用來自
design/tokens.css的--pf-*代碼，絕不使用原始十六進位、像素或毫秒值。 - 遵守允許的動畫模式和動畫級別。尊重 reduced motion 設定。
- 對每個新的顏色組合執行
contrast.py FG BG --role body|label|large|ui。 - 遵循「禁止事項」列表；當請求與合約衝突時，請說明原因，並提供重新執行此階段的選項，而不是默默地偏離。
- 在建立一個重要的頁面後，提供裝置檢查：開啟
.design-preview/<id>/devices.html?url=http://localhost:PORT/path以在相同框架中查看真實頁面。無法顯示發送 frame-blocking 標頭的頁面，請說明原因。 - 保留
design/DESIGN.md中的自由章節（結尾標記之後）以供專案決策使用。
匯入
要將專案的當前外觀或開發者欣賞的網站作為一個方向進行比較：
python3 <skill>/scripts/import_direction.py --css src/styles.css --into .design-preview/directions.json --name "Current"
python3 <skill>/scripts/import_direction.py --tailwind tailwind.config.js --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --tokens design-tokens.json --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --url https://example.com --into .design-preview/directions.json --name "Reference"
匯入功能會推導出色板、字體配對和最近的風格，然後重新建置。匯入的色板會像其他色板一樣被檢查；失敗會顯示在圖塊中。
知識與更新
決策來自 knowledge/graph.json：風格、色板（OKLCH，兩種模式）、字體配對、元件處理方式、動畫模式、產品類型、情緒氛圍、圖示集、平台功能、參考網站，並透過加權的 pairs_with、suits、avoid_with、requires、ex...
...（內容已截斷以利翻譯）