Ahmed8881/ahmed-ui-craft

Ahmed UI Craft

語言模型傾向於網路上的統計平均值：Inter 字體、紫色漸層、三個相同的圓角卡片、每個功能都配上一個表情符號。這種輸出一眼就能看出是模板，也向用戶表明沒有任何決策被真正做出。這個技能強制要求做出決策、將其記錄為標記（tokens），並在交付任何東西之前進行檢查。

請依序遵循以下工作流程。每個步驟的存在都是有原因的，跳過它們正是產生通用 UI 的起因。

步驟 0 - 在設計前先閱讀專案

在憑空發明之前先觀察。請依序檢查：

1. 框架：package.json (next, react, vue, svelte, astro)，或純 .html。
2. 樣式：tailwind.config.* 或 @import "tailwindcss" / @theme (Tailwind v4)， *.module.css、styled-components 或純 CSS。
3. 現有標記：搜尋 --color-、--space-、@theme、theme.extend。
4. 元件庫：components/ui/ + components.json (shadcn/ui)、 @mui/material、Radix、Headless UI、Vuetify。

原因：一個漂亮的元件如果忽略專案現有的標記和元件庫，就是一種倒退，而非改進。如果專案已經有設計系統，請在其內部運作：擴展其標記、重新設定其基本元件的樣式（對於 shadcn/ui，請編輯 globals.css 和元件檔案中的 CSS 變數，不要包裝它們）。只有在沒有系統可供擴展時，才引入 assets/tokens.css。

如果沒有任何現有設定，預設為：語意 HTML + 來自 assets/tokens.css 的 CSS 自訂屬性，如果專案中使用 Tailwind，則將其映射到 Tailwind 中。

步驟 1 - 設計思考（在任何程式碼之前）

在腦中或回覆中寫下四行簡短的文字：

• 目的：這個畫面要完成什麼工作？（例如：「說服團隊負責人開始試用」）
• 受眾：誰在看？用什麼裝置？在什麼情境下？（例如：「運維工程師，桌機，快速瀏覽」）
• 調性：三個形容詞。（例如：「精確、冷靜、密集」）
• 差異化亮點：使用者關閉分頁後會記住的一件事。

差異化亮點必須具體且可見，不能是「乾淨現代」這種空泛描述。 好的範例：「價格用巨大的壓縮數字顯示，從頭延伸到尾」； 「每張卡片都有一條極細的分隔線和一個等寬索引數字，像規格表一樣」； 「主標題以斜體襯線字體搭配米色紙張紋理背景」。

原因：如果你無法說出差異化亮點，輸出就會是平均值，因為當沒有特定方向拉動模型時，模型就會產出平均值。

如果使用者提供了品牌標誌、截圖或現有網站，調性應從中衍生。不要將新的方向強加於已建立的品牌之上。

步驟 2 - 致力於一個美學方向

選擇一個方向，並將其應用於所有地方：字體、顏色、圓角、陰影、動畫、圖像以及文案節奏。混合的方向會讓人感覺優柔寡斷。

方向	字體	顏色	形狀與深度	動畫
編輯風格	襯線顯示字體，人文主義正文	紙張米白、墨水黑、一個強烈強調色	極細分隔線、接近零圓角、無陰影	緩慢淡入淡出，滾動時無動畫
粗獷風格	厚重無襯線或等寬字體，巨大尺寸	純黑/白 + 一個亮色	0 圓角、粗邊框、硬偏移陰影	即時、乾脆
柔和 / 有機風格	圓角或軟軟的襯線顯示字體	暖色調中性色、柔和大地色強調色	僅容器使用大圓角、擴散陰影	彈簧般、輕柔
工業 / 科技風格	壓縮或無襯線 + 等寬字體	深中性色、信號強調色（琥珀、萊姆、青）	小圓角、1px 邊框、可見的網格線	快速、接近線性
奢華風格	高對比襯線字體，寬字距大寫	接近黑色、奶油色、金屬色或深寶石色強調色	寬敞留白、細邊框	緩慢、長時間緩動
趣味風格	厚實顯示字體，友善無襯線字體	兩種刻意衝突的飽和顏色	貼紙形狀、偏移陰影	彈性過衝

每一行在 assets/directions/ 中都有一個現成的預設（字體、經過對比度檢查的淺色和深色色板、圓角、陰影、動畫），以及 references/directions.md 中的簽名動作列表。在 tokens.css 之後載入預設，使用其至少兩個簽名動作，並將其色相向品牌色偏移。瑞士極簡風格是第七個預設。

選擇規則：

• 從步驟 1 推導出來，而不是出於習慣。給 SRE 的儀表板不應該是「奢華風格」。
• 在你的回覆中命名它（「方向：工業 / 科技風格」），以便用戶可以及早修正方向。
• 如果用戶要求平淡的東西（「簡單、乾淨」），仍然要選擇：「瑞士極簡風格」是一個方向（嚴格的網格、一種無襯線字體、黑色 + 一種顏色、零裝飾）。

步驟 3 - 先定義標記

在寫任何一個元件之前，為以下項目定義標記：顏色、字體、間距、圓角、陰影、動畫、z-index。從 assets/tokens.css 開始：保留名稱，替換其值。

起始值（Fraunces + Instrument Sans，紙張感中性色，朱紅色強調色）是一個佔位符，不是一種風格。在撰寫元件之前，至少更改字體配對（從 references/typography.md 中選擇，與你的方向匹配）、強調色相以及中性色所傾向的色相。原因：在測試中，未更改的起始標記使一個登入頁面和一個不相關產品的定價頁面看起來一模一樣。這是一個新的預設，而這個技能存在的目的正是為了解決這個問題。只有當方向真的是溫暖的編輯風格並搭配紅橙色強調色時，才保留它們。

生成一個新的、可存取的色板最快的方法：生成它，然後將其貼到第二區塊的顏色標記上。

node scripts/palette.mjs --hue 250 --accent 130 --dark-first   # 石板色系中性色，萊姆色強調色

--hue 調整中性色的色相（使用品牌色相），--accent 是強調色的色相。每個文字/背景配對在輸出前都已解決為符合 WCAG AA 標準（在淺色和深色模式下）。

對於以深色優先的方向（監控儀表板、開發者工具、奢華夜間主題），設定 :root { color-scheme: dark; }，使深色成為預設，淺色為可選。

原因：標記使方向可強制執行。元件中硬編碼的 #6366f1 或 13px 是一個孤立做出的決策，而二十個這樣的決策會導致 UI 偏離。有了標記，深色模式、主題化以及後續的重新設計都只需更改一個檔案。

規則：

• 兩層結構：原始色票（--ink-900、--clay-500）和語意標記（--color-text、--color-accent、--color-surface）。元件只使用語意標記。
• 元件中沒有魔術數字。每個顏色、大小、間距、圓角、陰影、動畫持續時間和 z-index 都來自標記。例外：0、1px 極細分隔線、100% 和 1fr。
• 深色模式：每個語意顏色都是 light-dark(淺色值, 深色值)，這樣兩個主題都存在於一個宣告中，元件永遠不需要更改。請參閱 references/color-and-theming.md。

Tailwind：讓標記成為主題，這樣 bg-surface、text-text-muted、font-display 和 rounded-md 都存在，而 bg-indigo-500 不存在。

• v4：assets/tokens.css 中的第二個區塊已經使用了 Tailwind 的名稱空間（--color-*、--font-*、--text-*、--radius-*、--shadow-*、--ease-*）。將該區塊的 :root 更改為 @theme，並在其第一行加入 --color-*: initial; 以捨棄預設色板。保留區塊 3（color-scheme）作為純 CSS。工具類根據主題解析 light-dark()，因為它們引用 var(--color-*)。 不要寫 @theme inline { --color-x: var(--color-x) }；一個引用自身名稱的變數是一個循環，會解析為空值。
• v3：在 tailwind.config 中，將 theme.colors（不是 extend）設定為 { surface: "var(--color-surface)", ... }，並以相同方式擴展 fontFamily、borderRadius、boxShadow。

步驟 4 - 行動裝置優先，包含所有狀態

為 360px 的視口編寫基礎樣式，然後加入 min-width 媒體查詢或容器查詢。原因：增加空間比減少空間容易，而且大多數版面問題（水平滾動、表格被壓碎）只在較小寬度下出現。

每個互動元素都應包含其所有狀態。缺少狀態是 UI 感覺未完成的最常見原因。

狀態	必須顯示的內容
default	靜止設計
hover	微妙變化（顏色或陰影），僅在 @media (hover: hover) 下
focus-visible	清晰可見的環，永遠不要移除
active	按壓回饋（顏色變深，或 translateY(1px)）
disabled	較低對比度 + cursor: not-allowed，以及真正的 disabled 屬性
loading	旋轉器或骨架，aria-busy="true"，寬度不跳動
error	欄位附近的錯誤訊息文字，不僅僅是紅色邊框
empty	真實的訊息和下一個動作，永遠不要留空白框

優先使用語意 HTML：<button> 用於動作、<a href> 用於導航、每個輸入框都使用 <label for>、<dialog> 用於模態框、<table> 用於表格資料、地標（<header> <nav> <main> <footer>）。僅在 HTML 沒有原生等效元素時才加入 ARIA。原因：原生元素自帶鍵盤行為和螢幕閱讀器語意，無需額外費用；ARIA 是一個你隨後必須實現的承諾。

撰寫真實的文案。佔位符文字（「Lorem ipsum」、「功能 1」、「王小明」）會隱藏版面問題，並使結果看起來像一個模板。使用與步驟 1 目的相符的具體、合理的內容。

步驟 5 - 在交付前進行審計

執行 scripts/audit.md：bash scripts/audit.sh <變更的檔案>（模式檢查加標記對比度檢查），然後，如果 Playwright 可用或用戶同意安裝，執行 node scripts/browser-check.mjs <頁面> 並查看其儲存的螢幕截圖。修正失敗的項目。註解中寫的比例只是聲明，不是測量值；請實際計算它們。不要在還有已知失敗的情況下報告工作已完成；如果有無法修復的問題（例如，一個品牌顏色無法通過對比度檢查），請明確說明。

多代理模式（當子代理工具可用時）

主代理始終自己執行步驟 0-4：思考與建置需要相同的上下文，分割它們會失去步驟 0 發現的內容。僅在兩個時間點使用子代理：

1. 方向提案（僅限步驟 2，開放式簡報）。如果沒有品牌、螢幕截圖或現有設計系統，請平行啟動 2-3 個子代理。給予每個子代理步驟 1 的內容，並為每個子代理分配表格中一個不同的方向。指示每個子代理先閱讀其在 references/directions.md 和 references/typography.md 中的章節，並告訴每個子代理其他代理的方向，以便它們避免。每個子代理僅回傳：方向、字體配對、強調色 + 中性色色相、差異化亮點、兩個簽名動作。拒絕一個重用另一個代理的字體配對、強調色相或差異化亮點，或保留 tokens.css 起始值的提案。選擇一個（或向用戶顯示選項），然後獨立繼續。 原因：一個代理會收斂到平均值；強制不同的起點則不會。 當品牌已設定方向時，跳過此步驟。

2. 獨立審查（步驟 5，始終針對新頁面或畫面）。在你自己的審計通過後，啟動一個未參與撰寫程式碼的、全新的子代理。給予它變更的檔案、步驟 1 的內容以及所選的方向，並要求它：閱讀 references/anti-patterns.md、執行 scripts/audit.sh，並列出 UI 看起來普通、缺少狀態或違反方向的每個地方。它將每個發現分為阻塞 / 主要 / 次要等級，並且不進行編輯。修正所有阻塞和主要問題，重新執行 scripts/audit.sh，並在回覆中列出未修正的次要問題。進行一輪審查，不循環。 原因：建置者根據其意圖來評斷結果，而不是根據螢幕上實際顯示的內容。

沒有子代理工具：自己按順序進行兩輪審查。對於審查，請重新閱讀檔案，彷彿是其他人寫的。

品質規則（及其原因）

字體排印

• 不要將 Inter、Roboto、Arial、Helvetica 或 system-ui 作為顯示文字使用。 也要避免較新的 AI 預設字體：Poppins、Montserrat、Space Grotesk、DM Sans。 原因：這些是每個生成頁面都使用的字體，因此它們會發出「生成」的信號。
• 將一個顯示字體與一個在結構上形成對比的正文字體配對（襯線 + 無襯線， 壓縮 + 寬體，無襯線 + 等寬）。最多兩個字體家族，可選加一個等寬字體。
• 使用帶有流體尺寸（clamp()）的模數尺度，並使最大的標題 遠大於正文文字。膽怯的層級（32px 對 16px）看起來未完成。
• 正文文字：最小 16px，行高 1.5-1.7，行長 60-75ch。密集的儀表板 可對元資料和表格儲存格使用 12-14px，但絕不用於段落或輸入框。

顏色

• 一種主導色承載品牌；一種尖銳的強調色保留給 主要動作和關鍵資料。中性色完成大部分工作。大約 60/30/10 的比例。 原因：均勻分布的五色色板沒有焦點，因此沒有任何東西被認為是重要的。
• 將你的中性色傾向於品牌色相，而不是使用純灰色。
• 沒有紫色到藍色或紫色在白色上的漸層，除非品牌真的是紫色。
• 文字對比度至少 4.5:1（24px+ 或 18.66px+ 粗體文字，以及 UI 元件邊界和焦點環，至少 3:1）。

版面與形狀

• 避免相同的三或四卡片網格。變化大小和強調：一個特色 項目跨越兩列，一個列表旁邊有一個大視覺元素，一個不對稱分割。
• 圓角遵循方向，並且在每個層級保持一致。不要對所有東西都使用 rounded-2xl；小控制項使用小圓角或無圓角。
• 在 320px 寬度下無水平滾動。在 flex/grid 子元素上使用 min-width: 0，對長字串使用 overflow-wrap: anywhere，並為寬表格使用滾動容器。
• 觸控目標至少 44x44px（內距也算）。

圖示與圖片

• 不要使用表情符號作為圖示。使用一套圖示集（Lucide、Phosphor、Heroicons、Tabler）並保持統一的線條寬度， 或使用內聯 SVG。原因：表情符號在不同作業系統上渲染不同，無法用標記著色， 並且會被螢幕閱讀器朗讀（「火箭」）。
• 裝飾性圖示設定 aria-hidden="true"；僅圖示的按鈕設定一個 aria-label。

動畫

• 僅對 transform 和 opacity 進行動畫（謹慎使用 filter）。原因：其他屬性 會在每一幀觸發版面或繪製，並在低階手機上造成卡頓。
• 持續時間來自標記：UI 回饋 120-200ms，進入元素 250-400ms。
• 尊重 prefers-reduced-motion：移除移動效果，保持淡入淡出簡短或立即。

可存取性

• 所有表單輸入必須有相關聯的 <label>。
• 使用 <fieldset> 和 <legend> 對相關表單控制項進行分組。
• 為圖像提供描述性替代文字。
• 確保所有功能都可以透過鍵盤存取。
• 使用 aria-live 區域進行動態內容更新，但只在必要時使用。

程式碼品質

• 不要使用 !important。使用適當的 CSS 特異性。
• 使用一致的命名慣例（BEM、CSS Modules 作用域、Tailwind 工具類）。
• 沒有未使用的 CSS。
• 沒有控制檯錯誤或警告。
• 撰寫包含所有邊緣情況（空值、載入、錯誤）的測試。