ummydev/pretty-ui

pretty-ui 是做什麼的？

AI 構建的畫面看起來千篇一律，因為沒有人做選擇。模型會用最常見的答案填補每一個空缺，結果就是一個可以屬於任何產品的頁面。

pretty-ui 按照設計師的順序解決這個問題：選擇一個方向，將其記錄下來，然後套用到每個地方並檢查結果。 選擇是由人來做的，從他們可以看到的真實選項中挑選，而不是由代理獨自決定。

執行步驟

請依序執行以下步驟，並告訴使用者你正在進行哪一步。

1. 閱讀專案

• 找出正在建構的內容：一個用來閱讀和滾動的頁面（著陸頁、行銷網站、作品集）、一個讓人操作的網頁應用程式畫面（儀表板、設定、收件匣）或一個行動應用程式。
• 找出技術棧：純 HTML、Tailwind、shadcn/ui、React、Vue、Svelte、React Native、SwiftUI、Compose 或 Flutter。請使用該技術棧進行開發，永遠不要遷移它。
• 尋找現有的視覺系統：DESIGN.md、AGENTS.md 或 CLAUDE.md 中的設計筆記、Tailwind 或 shadcn 的主題變數、品牌指南或商標。如果品牌已經有顏色和字體，請保留它們。 步驟 3 中的設計方向會在品牌內部變化佈局、字體比例、密度和強調色，而不是改變品牌本身。
• 收集真實內容：產品名稱、產品功能、目標客群、真實數據、真實截圖。使用佔位內容會讓每個設計看起來都很普通。

2. 審計（僅在 UI 已存在時執行）

閱讀 references/tells.md。對渲染 UI 的檔案執行檢查工具：

node <skill>/scripts/check.mjs <檔案或資料夾>

按嚴重程度分組，列出發現的問題給使用者，並包含檔案和行號。加入任何檢查工具無法從程式碼中看出的問題：三個完全相同的卡片、所有內容都置中、沒有清晰的視覺焦點、填充性文字。如果畫面已經設計良好，請告知使用者，並建議兩三個小幅改進，而不是重新設計。

3. 提供三個設計方向

閱讀 references/systems.md。其中列出了 24 個完整的設計系統，12 個用於網頁，12 個用於行動應用程式，每個都有公開的 DESIGN.md。

1. 選擇三個刻意有所區別的系統：例如一個淺色且具有編輯風格，一個深色且密集，一個柔和且親切。請匹配平台（網頁或應用程式）和產品所屬的領域。永遠不要提供三種看起來相似的不同版本。
2. 從其 URL 擷取每個系統的 DESIGN.md。
3. 使用相同的真實內容，為同一個關鍵畫面建立三個方向的獨立 HTML 檔案：
   • pretty-ui/directions/a-<縮寫>.html、b-<縮寫>.html、c-<縮寫>.html
   • 網頁尺寸為 1440×900，行動應用程式畫面為 390×844。使用內嵌 CSS、Google Fonts 連結，不使用外部圖片。
4. 讓它們易於比較：
   • 如果 Codex Design 的畫布工具可用（例如 create_canvas 和 add_node），將三個檔案放在同一個畫布上並排顯示，然後開啟它。
   • 否則，執行 node <skill>/scripts/compare.mjs pretty-ui/directions/*.html --out pretty-ui/directions/index.html，並告知使用者開啟該檔案。
5. 請使用者選擇一個方向，或組合部分內容（「A 的字體搭配 C 的色彩」）。如果使用者要求你決定，請選擇最適合該產品的方向，並用一句話說明原因。

當品牌已固定時，三個設計方向會使用品牌的顏色與字體，並在佈局、比例和密度上有所區別。

4. 記錄設計系統

• 將所選系統儲存為專案根目錄下的 DESIGN.md。保留其格式：包含代號的 YAML 前言，然後是概述、色彩、字體、佈局、形狀、元件以及注意事項。
• 將使用者要求的任何變更（品牌色、不同的標題字體）套用到該檔案，而非僅在程式碼中修改。
• 在 AGENTS.md（以及專案中可能存在的 CLAUDE.md）中加入一行：每個畫面均遵循 DESIGN.md：色彩、字體、間距、圓角和元件。 Codex 會自動讀取 AGENTS.md，但不會讀取 DESIGN.md。
• 對於 shadcn 或 Tailwind 專案，將代號對應到主題變數（--background、--primary、--radius 等）。每個系統頁面都連結了一個現成的 shadcn 主題：npx shadcn@latest add https://codexdesign.io/r/<縮寫>.json。

5. 逐層套用

如同設計師的紅線審查，一次一個圖層地處理整個畫面。除非使用者另有要求，否則保留功能、內容和區塊順序。

1. 代號。 將硬編碼的顏色、大小和圓角替換為系統的代號。
2. 字體。 最多使用兩種字體家族。使用系統的字體比例。確保畫面上最重要的那行文字明顯是最大的。數字使用等寬數字以對齊。
3. 間距與佈局。 使用系統中的一個間距單位及其倍數。將所有內容對齊網格或畫面邊距。將相關項目緊密分組，並在組之間留有充足間距。
4. 色彩。 中性色承擔畫面的主要視覺。主要色彩出現在使用者操作的地方，每個視圖大約一次。圖表按順序使用系統的圖表顏色。
5. 元件。 按鈕、輸入框、卡片、列表和導航應遵循系統的元件章節。使用真實圖示（Lucide、Phosphor、SF Symbols、Material Symbols），永遠不要使用表情符號作為圖示。
6. 文案。 使用產品中樸實、具體的文字。刪除填充詞彙（「無縫」、「解鎖」、「效能倍增」）。標題應說明事物的本質或功能。
7. 細節。 懸停、聚焦和按下狀態；空狀態、載入狀態和錯誤狀態；文字對比度至少為 4.5:1。
8. 動畫。 僅在需要說明事物時使用：狀態變化、畫面之間的轉場。不要對每個區塊都使用淡入效果，不要使用脈衝裝飾。

對於行動應用程式，也請閱讀 references/app.md。

6. 檢查

• 對修改過的檔案再次執行檢查工具，修正所有錯誤以及盡可能多的合理警告。
• 查看結果。如果 Playwright 或瀏覽器工具可用，請在 1440 和 390 寬度下（或應用程式的裝置尺寸）截圖，並修正看起來不對的地方：沒有視覺焦點、組之間過於擁擠、文字換行不佳、對比度不足。
• 對於重新設計，建立一個使用者可以分享的「前後對比」頁面：

node <skill>/scripts/compare.mjs before.html after.html --labels "之前,之後" --out pretty-ui/before-after.html

7. 回報

簡短地告知使用者：所選方向及原因、修改的檔案、檢查工具在前後的發現，以及任何仍需要他們決定的事項（真實照片、商標、只有他們能撰寫的文案）。

始終適用的規則

• 在決定之前先展示選項。永遠不要默默選擇一種風格。
• 保留使用者的品牌、內容和技術棧。
• 每個產品使用一個設計系統，記錄在 DESIGN.md 中，並在所有地方遵循。
• 除非使用者明確要求，否則不要使用紫色或紫羅蘭漸層、漸層文字、玻璃態面板、發光陰影、表情符號圖示、每個標題上方的藥丸形徽章，或一排排相同的圖標卡片。
• 不要用一種陳腔濫調取代另一種。奶油色搭配襯線字體和赤陶色強調色，或近黑色搭配一種螢光綠強調色，是新的預設選項；僅在產品所屬的世界呼應它們時才使用。
• 去除裝飾是工作的一半。用真實內容、為重要事項使用更大的字體，以及一個取自產品本身的令人難忘的元素來填滿空間。

檔案

• references/systems.md：24 個設計系統，附帶平台、風格和 DESIGN.md URL。
• references/tells.md：UI 看起來像 AI 生成的原因，以及應對方法。
• references/app.md：適用於 iOS、Android 和跨平台應用程式畫面的規則。
• scripts/check.mjs：用於檢查 HTML、CSS、JSX、TSX、Vue 和 Svelte 檔案中 AI 痕跡的靜態檢查工具。需要 Node 18+，無外部依賴。
• scripts/compare.mjs：產生一個 HTML 頁面，用於並排顯示多個畫面，以便選擇方向或展示前後對比。