設計與 UI
讓介面看起來有意識且高級,而不是模板化的通用設計。這是應用程式建構器中最重要的品質槓桿。將其應用於 DOM/覆蓋層 UI — 頁面、瀏覽器 chrome、HUD、選單、表單。(對於 3D 遊戲的遊戲畫布,請參閱 building-games 技能;此技能管理覆蓋在其上的 DOM UI。)
閱讀 references/ 以獲取深度內容(按需載入 — 不要全部內聯):
references/refined-ui.md— 完整的產品 chrome/覆蓋層設計系統。references/typography.md— 字型比例、搭配、節奏。references/surfaces.md— 層級、邊框、陰影、分層。references/animations.md— 動態效果、緩動、過渡。references/performance.md— 保持 UI 流暢(60fps,無卡頓)。
1. 先建立設計系統(在任何樣式工作之前執行此操作)
一次定義系統,然後從中組合。絕不要隨意使用臨時值。
- CSS 中的 Token(Tailwind v4 以 CSS 為優先)。 將色板、圓角和字型放在
src/styles.css的@theme下作為 CSS 變數;並以 Tailwind 工具類的方式使用它們。只有一個真相來源。@import "tailwindcss"; @theme { --color-bg: #0b0b0f; --color-surface: #16161d; --color-fg: #e7e7ea; --color-muted: #a0a0ab; --color-primary: #14b8a6; --color-border: #26262f; --radius: 0.75rem; --font-sans: "Inter", system-ui, sans-serif; } - 使用 shadcn/ui 元件(Radix 基本元件 +
cva變體 +tailwind-merge)來建立按鈕、對話框、下拉選單、輸入框等。它們具有可訪問性且一致。將它們生成到src/components/ui中;透過 token 設定樣式,而不是使用內聯十六進位顏色。 - Tailwind v4 基本修正 — 按鈕需要指針游標。 v4 的 Preflight 讓
<button>使用cursor: default,這感覺有問題。在src/styles.css中新增一次此設定,以便按鈕/可點擊角色顯示指針:@layer base { button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; } } - 禁止臨時樣式設定: JSX 中沒有原始十六進位顏色,沒有像
text-white/bg-black這樣的字面值,沒有像p-[16px]或text-[13px]這樣的任意值。如果需要某個值,它必須變成一個 token 或一個比例階梯。
2. 量化評分標準(防止「醜」的廉價規則)
- 總共 ≤ 3–5 種顏色(一個主要色 + 中性色 + 最多一個強調色)。沒有隨機的額外色調。除非被要求,否則不要預設使用紫色。
- ≤ 2 種字型家族(通常一種)。將一個顯示/標題字型與一個正文字型配對,或只用一種。
- 行高 1.4–1.6 用於正文;大標題使用更緊湊的值。
- 當你覆蓋背景顏色時,也必須覆蓋前景/文字顏色(必須保持對比度 — 同時檢查淺色和深色模式)。
- 行動優先:先設計 ~390px 的佈局,然後再放大。沒有水平溢出;觸控目標 ≥ 44px。
- 一致的間距比例(基於 4/8 的間距系統)。充足的留白勝過資訊擁擠。
- 一個強調色,謹慎使用,僅用於主要操作 — 而不是到處使用。
3. 反 AI 樣板(讓輸出看起來像樣板的跡象 — 避免)
- 沒有漸層模糊填充,沒有巨大的英雄漸層來取代內容。
- 沒有使用表情符號作為圖示 — 使用真正的圖示集(
lucide-react)。 - 沒有手繪 SVG 插圖/地圖/圖表 — 使用真正的函式庫(
recharts用於圖表)或真正的生成圖像。 - 最終產品中沒有佔位圖像 / 灰色的 Lorem Ipsum 方塊 — 生成真正的圖像或使用真正的內容;在 canvas 圖像上設定
crossOrigin="anonymous"。 - 避免過度使用的字型外觀(僅限預設系統字型,或 Comic Sans 級別的選擇)。
- 每個元素都值得存在。 減少裝飾性噪音。建立一個系統,然後有目的地變化 — 而不是隨機變化。
- 在就地編輯應用程式時,匹配現有的 UI;不要引入第二種視覺語言。
4. 佈局與層級
- 清晰的視覺層級:每個視圖一個主要操作;大小/粗細/顏色表達重要性。詳見
references/typography.md和references/surfaces.md。 - 使用真正的佈局結構(grid/flex,容器最大寬度),而不是絕對定位的技巧。對齊到一致的網格。
- 空狀態、載入狀態和錯誤狀態是設計的一部分 — 不要發布空白/卡頓的中間狀態。
5. 動態效果(細微、有目的)
- 短暫、緩和的過渡效果(150–250ms)在懸停/按下/進入時;尊重
prefers-reduced-motion。詳見references/animations.md。 - 永遠不要以導致卡頓的方式為佈局添加動畫;優先使用 transform/opacity。
6. 遊戲覆蓋層(與 building-games 配合使用時)
遊戲畫布由 building-games 管理。此技能為 DOM 覆蓋層 設定樣式:開始/「點擊遊玩」畫面、HUD、分數、選單、暫停、行動控制。保持覆蓋層在畫布上可讀(背景、對比度),並使其遠離指標鎖定/遊戲輸入路徑。
完成檢查清單(在你宣告 UI 完成之前)
- Token 已在
@theme中定義;JSX 中沒有臨時十六進位顏色/任意值。 - ≤ 5 種顏色,≤ 2 種字型,一致的間距比例。
- 對比度維持;在設定背景的地方都已覆蓋前景色。
- 行動端(~390px)沒有溢出;觸控目標 ≥ 44px。
- 真正的圖示/圖像/圖表 — 沒有任何反樣板的跡象。
- 已處理載入/空/錯誤狀態;動態效果細微且支援減少動畫模式。
- 已在瀏覽器中渲染並目視檢查(參見 AGENTS.md 驗證),而不僅僅是 curl。