Sampo：UI 設計、動態與 3D
一條路徑，處理任何與畫面外觀或動態相關的工作：網頁、應用程式畫面、元件、動畫、3D 場景，或單純的「讓它更好看」。它會導向至 UI 操作手冊（以下路徑相對於此技能；可使用 sampo playbooks show ui/NAME 印出相同檔案）以及用於衡量結果的 sampo 動詞。目標是打造一個擁有觀點的 UI，絕非通用卡片組：以下每個步驟若不是做出決定，就是證明一個決定。若為終端機 UI 或 Claude Code 模組，請改為使用 ../playbooks/references/ui/terminal-ui.md。
請在專注的任務中工作（每個步驟都會編輯檔案）。每個步驟只閱讀它指定的操作手冊。
1. 方向：決定它應該帶給人的感受
- 儲存庫中已有一個（包含
## Direction區段的DESIGN.md、品牌指南、已上線的設計系統）：以此為準。閱讀它並前往步驟 2，除非使用者要求全新的外觀。 - 沒有方向，或使用者想要選擇外觀或樣式：載入：技能 sampo:directions（從一句話產生六張單頁卡片，並將選擇結果儲存為附帶大膽程度的
DESIGN.md）。 - 展示真實範例而非描述：
sampo page looks會建立一個展示畫廊，每個外觀卡片都有一個實際範例；sampo looks會根據使用者過去保留和還原的記錄，對二十個外觀進行評分，因此請從其頂部推薦。 - 立場、品味詞彙、方向庫以及「應避免的預設值」：請參閱
../playbooks/references/ui/design-direction.md。
2. Token：字型、顏色、間距
../playbooks/references/ui/type-and-colour.md：字級與配對、OKLCH 調色盤角色、深色模式視為獨立處理階段。- 現有 CSS：
sampo design extract SRC會從其自訂屬性中提取 Token 表格，並寫入 DESIGN.md 的## Tokens區段（使用--out -則改為印出）。從無到有：sampo design palette SEED --out tokens.css會從一個顏色產生淺色與深色調色盤（使用--format css|dtcg|tailwind）；它會輸出到標準輸出，因此請使用>重新導向。從 Figma 或 DTCG.json檔案獲取 Token：sampo design tokens tokens.json --to md --out DESIGN.md。硬編碼的值：sampo design infer SRC會建議 Token。 - 品牌資產：
sampo design tokens DESIGN.md --to brand --out public/會寫入 favicon.svg 和 card.svg。 - Token 偏移：
sampo design xray PAGE --out xray.png會將每個元素標記為綠色（Token 顏色）或紅色。 - 在開始建構之前先驗證：
sampo design contrast TOKENS會檢查角色配對（在深色模式下，正文文字對比度需達 7:1）。
3. 建構：版面與行為
- 從嚴格的範本開始：先執行
sampo new list，然後執行sampo new web DIR（頁面）或sampo new scene DIR（3D 場景）；sampo new check PATH可確保其保持嚴謹。 ../playbooks/references/ui/composition.md：韻律、網格、單一光源產生的深度、主視覺、狀態圖集。../playbooks/references/ui/interaction.md：回饋截止時間、鍵盤操作流程、表單錯誤、360 像素觸控規則。- 圖表：
../playbooks/references/ui/data-viz.md。故事頁面：../playbooks/references/ui/scrollytelling.md。 - 程式碼側的卡片：
sampo lib show NAME（操作手冊中會指出哪些名稱）。
4. 動態：經過設計，而非隨意點綴
../playbooks/references/ui/motion.md：時間 Token、狀態到動態的對照表、分鏡腳本、減少動畫偏好設定視為獨立路徑。- 撰寫 Motion Score（儲存庫根目錄下的
motion.toml），然後執行sampo motion check（檢查遺漏的縮減形式、未知的緩動函數、DESIGN.md 缺少的 Token）以及sampo motion compile --to css|waapi|three|lab --out FILE來輸出程式碼。 - 遊戲與趣味性 UI：
../playbooks/references/ui/game-feel.md。音效：../playbooks/references/ui/sound-design.md。
5. 3D：絕不破壞頁面的場景
../playbooks/references/ui/scene-3d.md：構圖、光源與材質、幀數預算、生存契約（無 WebGL、減少動畫、遺失上下文）、黑畫面故障排除。- 將場景描述為資料（攝影機、光源、材質、網格、動畫）一次，儲存在
scene.json中，然後執行sampo scene compile scene.json --to three --out scene.js（一個 three.js 模組）或--to component（一個元件）。 - 無依賴項：單一檔案的 WebGL2 範本
../playbooks/references/ui/templates/scene.html（使用sampo new scene）。 - 燈光配置與 PBR 預設：
sampo lib show light-and-material；用於單一表面的著色器紋理，絕非整個方向：sampo lib list --area looks，然後是sampo lib show shader-NAME；函式庫：sampo lib show three-js、sampo lib show react-three-fiber。
6. 檢查：透過觀察來驗證
sampo design lint SRC：通用設計問題與工藝瑕疵；請修正每一項，或說明為何保留。其最後一行會列出 DESIGN.md 中未被任何檔案使用的 Token：請將它們加入程式碼中，或從 Token 表格中刪除。sampo design check：DESIGN.md 中選擇啟用的閘門（## Gates，格式為- brief: advisory|blocking）：在程式碼中找到的 Knobs 顏色、字型系列與持續時間；- a11y: …：Token 對比配對、減少動畫路徑、無快速閃爍、圖片 alt 屬性以及可見的焦點樣式；- debt: advisory 40：每個檔案中未使用 Token 的顏色、持續時間與圓角半徑，需在預算範圍內。- 任何顏色變更後，再次執行
sampo design contrast TOKENS；任何動態變更後，再次執行sampo motion check。 sampo critique URL：頁面實際使用的樣式與 DESIGN.md Token 的比對結果（未命名、近似重複、一次性樣式）；使用--why SELECTOR可查看是哪條規則勝出。--bingo會對九個模板化外觀的特徵進行評分（若全數符合則結束程式碼為 1）；--marks shot.png會將在螢幕截圖上繪製的鉛筆紅筆標記，轉換為每個標記元素對應的 FIX 擷取（--note會說明每個標記的要求）；--brief [ID]會檢查簡報中引用的詞句是否出現在頁面上。../playbooks/references/ui/visual-qa.md：sampo smoke會拍攝幀數矩陣（360/768/1440 解析度、淺色與深色模式、減少動畫）；請閱讀 PNG 檔案並進行觀察。前後對比：sampo img diff A.png B.png --out diff.png。- 元件的各種狀態（預設、懸停、錯誤、空白、載入中）：
sampo stories CHART會將每個狀態拍攝為一個矩陣頁面。sampo shot和sampo stories接受--profile tv|eink|car|wrist參數（該裝置的尺寸與縮放比例）以及--reduced-motion參數（prefers-reduced-motion: reduce，用於海報與靜態狀態）。 - 將每個項目記錄為任務步驟的證據；UI 變更不能僅憑通過的測試就視為完成。
7. 品味
使用者可以保留或還原某個外觀：使用 sampo looks keep LOOK 或 sampo looks revert LOOK，以便下一次的排序能從中學習。