Moddingflow/better-design

Better Design

使請求的任務清晰且可操作：使用者可以看到他們在哪裡， 在啟動操作前理解它，收到結果，並能從錯誤中恢復。 分別評估連貫性、表現力和無障礙性。不要承諾完美的使用者體驗。

1. 建立範圍與視覺基礎

• 選擇一個模式：創建、有目標的改進、審核或計劃。審核保持唯讀； 不要在計劃中實施更改。不要添加使用者未請求的功能。
• 根據請求和專案建立平台。僅在缺乏上下文時，使用 響應式網頁、語意化HTML和WCAG 2.2 AA作為初始目標。
• 在組合或更改響應式表面之前，定義實際的裝置和視口矩陣。 對於網站，包括產品支援的行動裝置、平板電腦、桌面和超寬佈局； 對於行動遊戲，包括小型和典型手機以及平板電腦。設計 約束和佈局行為必須適應這些表面，而不是僅僅縮小 桌面組合。對於瀏覽器工作，在矩陣中包含瀏覽器縮放，因為75%、 100%和150%可能暴露不同的裁剪、密度、重排和互動失敗。
• 在任何UI工作之前，尋找專案的DESIGN.md（根目錄、docs/、design/或代理 指令中指定的路徑）並完整閱讀。它是介面值的單一來源： 字體、字體比例、顏色角色、間距、圓角、元件大小、圖標和動態。 根據角色或標記名稱，從中獲取新程式碼或更改程式碼中的每個值；切勿 目測、四捨五入或引入幾乎重複的值。規則在design-md.md中。
• 在當前執行環境中或通過已確認的當前截圖檢查現有畫面， 然後檢查附近的元件、標記、樣式和專案規則。DESIGN.md的缺失 並不意味著沒有設計系統：程式碼標記本身就是系統。 保留無關的進行中的工作。
• 區分實現缺陷與重新設計請求。首先解決原因： 不明確的排序、不可預測的操作、不良的回饋、資料遺失或內容遺失。
• 按此順序做出決定：明確的任務和約束 → DESIGN.md和現有系統 → 平台慣例 → 領域任務 → 此技能的可配置基線。 功能性和適用的無障礙性要求適用於每個層級。
• 預設視覺方向。 當使用者未指定視覺樣式且專案沒有 DESIGN.md、品牌、程式碼標記或即時UI可供繼承時，以內部風格構建： 高端極簡，體現Apple精神（黑色畫布，接近白色的Geologica字體，重量500和 340，兩種灰色，一種藍色用於連結和焦點，藥丸形狀的操作，透過色調分離的表面， 真實內容作為唯一的顏色）。規則和現成的DESIGN.md預設 在house-style.md中；在編寫任何樣式之前完整閱讀。 兩種誤讀會導致代理偏離，因此請明確檢查它們（house-style.md第1節）： 產品的領域、行業、受眾或名稱不是視覺提示（「咖啡烘焙坊」、 「為開發人員設計」），且未修改的脚手架預設不是要繼承的系統（ shadcn/ui預設主題、Tailwind預設色板、create-next-app、Vite或Expo 入門套件、Bootstrap、MUI或Chakra預設）；取而代之，將內部風格映射到它們之上。 當它適用時，從參考文件house-style.html開始， 而不是空白頁面：獲取其標記、類型類別、導航、按鈕、磁貼和章節節奏（或將其移植到 框架的元件中），然後替換其內容（house-style.md第1節）。來自使用者的任何視覺提示 （顏色、情緒、主題、參考、品牌、受眾風格）都會覆蓋它：遵循 請求，並僅應用內部風格中請求未明確指定且不與其矛盾的 部分。除非被要求，否則不要將現有產品重新風格化為內部風格。遊戲保留 自己的藝術方向。
• 保留已建立的品牌、密度、遊戲風格、編輯或表現力構圖。 不要將它們替換為通用的灰色CRM系統。對於真正的衝突，選擇最小的 可訪問的調整並解釋具體的偏差。
• 僅澄清會實質性改變決策的未知事項；簡短陳述合理的假設。 此技能不會引入新的批准或HTML關卡。專案現有的原型、 批准和構建要求仍然適用。

2. 定義任務與相稱的合約

• 用簡單語言描述主要場景及其可觀察到的結果。 逐步說明：進入 → 操作 → 結果 → 錯誤/重試 → 返回/取消。
• 區分主要任務、次要操作和幫助。選擇使用者熟悉的 名稱和模式；保持跨畫面的導航和操作位置一致。
• 單一修復只需簡短記錄更改的決定和檢查。 對於新的流程，在實施前撰寫一個精簡的合約；它是一個工作工具， 而不是使用者的強制文件。
• 使用design-contract.md獲得結構、 數值預設值和例外情況。JSON範例 說明了格式；不要為了小的更改將其完整添加到專案中。
• 將合約限制為平台、目標、現有系統、方向、受影響的元件、 其操作/狀態、響應式行為和驗收證據。 計劃的檢查不是完成的檢查。

3. 在應用樣式之前設定藝術方向

負面規則只會將輸出推向下一個最常見的模板；特性來自於 過程。當創建或重新設計一個其身份是任務一部分的表面（品牌、 著陸頁、作品集、消費類應用程式、遊戲、編輯類、啟動器）時，在選擇標記之前，遵循 art-direction.md。當應用內部風格時 （第1節），色板、字體、形狀和動態標記來自其預設；仍然撰寫 概念，並讓它選擇圖像、每個章節的主導元素和一個標誌性細節 （house-style.md第10節）。否則：

• 從產品的領域、受眾和內容中推導出一個一句話概念——來自該世界的物體、 場所或工藝——而不是來自諸如「現代、乾淨、極簡」之類的形容詞。 添加三個目標品質和三個具體的反品質。
• 收集3-5個真實參考（使用者提供的優先；絕非AI生成的圖像）並注意 每個參考具體採用了什麼：節奏、密度、數字呈現、材質、光線。
• 草擬2-3個方向，這些方向在其主導裝置（排版主導、圖像主導、 結構主導）上有所不同，然後選擇一個，並給出與任務和受眾相關的理由。
• 從概念中推導出色板和字體：一個具有說明來源和色調中性的色板； 三個字體候選項和一個有理由的選擇。計劃一兩個標誌性細節； effects-library.md中的可選池包含經過測試的。
• 從相同的概念推導出動態特性：該世界中的事物如何移動（節奏、 重量、物理特性、是否有彈性），加上一個標誌性動態細節。色板、字體和動態 必須讀起來像一個聲音；請參閱motion.md。
• 在DESIGN.md、現有品牌或設計系統內，如果方向是繼承的：從DESIGN.md中獲取它，或 從即時表面中用一句話說明它，並在其內部工作。密集的工作工具通過 精確和資料排版來表達特性；如果沒有系統且沒有使用者提示，他們採用內部 風格的應用程式規模和色板，以及中性後備的密度。
• 在合約中記錄方向（direction，包括direction.motion）並計劃 distinctiveness和motion檢查。將所選方向和其標記寫入 DESIGN.md，以便後續的畫面和工作階段從相同的值構建。

4. 建立一致的決策系統

• 重用來自DESIGN.md和程式碼標記的標記和元件。對於新系統，定義 顏色、排版、間距、圓角、圖層和動態的語義角色；然後選擇 元件變體。
• 保持集合封閉，以便每個畫面都由相同的部分構建：一個或兩個字體族、 一個具有少數角色的階梯式字體比例、一個固定的間距比例、少數圓角和固定的元件 大小（例如按鈕sm/md/lg）。相同的角色，在每個畫面上相同的值。缺少的值 是一個系統決策：在相同的更改中將角色添加到DESIGN.md和程式碼標記中。
• 從模板創建DESIGN.md（從house-style預設當 內部風格適用時），在從頭創建介面時，或者當重新設計或多元件更改找不到任何 DESIGN.md時；從即時代碼標記中推導它，而不是憑空創造值，並記錄矛盾而不是默默 修復它們。不要為單一元素修復創建它，除非被要求；用一行話提供它。 在每次更改中保持DESIGN.md和程式碼標記同步，只要觸及其中任何一個。
• API表達意圖、大小、密度和狀態。保留原生屬性、表單參與、 連結和可訪問的名稱；不要要求在提交按鈕或帶有href的連結上使用onClick。
• 不要用自己獨特的十六進制、間隙、陰影和圓角來調整每個元素。當原因 是共享的時，更改共享的標記或變體。佈局數學、1px邊框、0、fr、%、calc、 aspect-ratio和允許的專案值本身不是違規。
• 根據角色和容器選擇文字大小。
• 構建幾何形狀；永遠不要憑眼睛放置。遵循layout-geometry.md 對於每個畫面、面板和遊戲選單，並測量結果（第8節）。在其原因處修復 對齊問題（樞軸、錨點、缺少佈局組、精靈填充、字體度量），永遠不要通過 微調一個元素：
  • 等間距。 同一種同級元素位於具有一個間距標記的佈局容器（flex/grid gap、 Unity佈局組、Godot盒容器、UMG盒子）中，因此它們之間的每個間隙 都是相同的。不同的間隙必須意味著一個新的組和比例上的一個清晰步驟。 接近度階梯：控制項內部 < 項目之間 < 組之間 ≤ 內邊距。
  • 共享對齊線。 一行中的項目共享它們的頂部/中心/底部（混合高度共享 中心）；一列中的項目以及設定列表中的每個標籤從一條垂直 基準線開始，控制項在第二條基準線上。使用網格或固定的標籤列，永遠不要 逐行偏移。按鈕組共享一個大小。
  • 小型控制項內的內容 通過其可見墨水（大寫字母高度、裁剪的 圖標像素）居中，而不是通過字體行框或填充的精靈矩形；不對稱的圖標獲得 一個聲明好的光學偏移，烘焙到元件中。圖標+標籤對使用一個間隙標記。
  • 呼吸空間。 沒有內容溢出或坐在其容器的邊緣上：內邊距至少 等於其包含的間隙，並為最長的本地化、懸停縮放和焦點環保留空間； 互動式UI在每個支援的寬高比下保持在安全區域內。 當內容不適合時，更改佈局，而不是邊距。
• 透過一個過程而不是黑名單來選擇排版：從概念（時代、材質、聲音、資料密度）中推導出 三個字體族候選項，然後用陳述的理由選擇。字體族 必須在其真實大小和語言下可讀，並提供所需的權重、樣式、 數字、字形覆蓋度（包括支援的字體集時的西里爾字母）和後備行為。 沒有字體族被禁止，但出於習慣選擇的字體族是一個缺陷：將一種趨勢預設 （Inter, Uni Sans）替換為另一種（Space Grotesk, DM Sans, Instrument Serif）而 沒有理由，是同樣的模板。時尚的字體絕不能使介面更難閱讀。
• 透過主導和對比構建層次結構：每個畫面或章節一個主導元素， 一個清晰的階梯式字體比例（在表現力表面上顯示3-5×正文，在密集 工具中較小的步驟），在有助於概念的地方有意識的不對稱，以及相鄰的章節 在結構上有所不同，而不是重複一個區塊模式。
• 黃金比例可以在改善構圖時告知比例、層次結構、裁剪或空白， 但它是一個視覺工具而不是強制公式。當實際任務、內容、響應式 約束、可讀性和現有系統與其衝突時，優先考慮它們。
• 不要讓一個主畫面成為不間斷的散文牆，當其內容可以透過 操作、分組或視覺錨點來理解時。將密集的解釋分解為 可掃描的章節，並在有用時將它們與有意義的控制項、圖示、 插圖、預覽、圖表或其他任務相關的圖像配對。一個儀表板或 帳戶區域，例如，應該暴露其主要章節和下一步操作，而不是 僅僅描述使用者可以配置什麼。不要添加與理解競爭或 產生虛假感知的裝飾性視覺元素。
• 使用顏色表示含義和強調；不要僅用顏色傳達狀態。 將錯誤/成功/必需/選中資訊與文字、圖示、形狀、圖案 或其他在灰階和色覺缺陷下仍然可見的非顏色提示配對。
• 在應用透明度、疊加層、漸層、圖像和每個必需的佈景主題後，驗證實際相鄰前景/背景對的對比度； 不要四捨五入接近閾值的結果。 滿足至少4.5:1的普通文字和有意義的文字圖像，以及僅3:1的大 文字（至少24 CSS px常規或18.5 CSS px粗體）。對於細小、小或異常的字體，目標更高。
• 確保用於識別活動控制項、其焦點或狀態以及有意義的圖形物件與其相鄰顏色的視覺資訊的最小對比度為3:1。 僅當邊框是使控制項可識別的要素時才需要邊框；當用它來達到該目的時， 它必須滿足相同的3:1閾值。
• 規劃所有互動狀態：預設、懸停、活動、焦點、禁用、載入和錯誤。 控制項狀態必須從背景可區分，並滿足無障礙性對比度要求。 在啟用和禁用狀態之間提供足夠的視覺差異，以便使用者 識別哪些操作可用。
• 為文字和輸入控制項支援作業系統縮放，並在應用程式層級尊重 減少動態偏好。所有動態必須能夠被停用而不遺失資訊。
• 為控制項和可聚焦元素規劃焦點指示器。永遠不要使用 outline: none 而不提供自訂焦點樣式。焦點環必須 在動態和主題中具有足夠的對比度。
• 確保所有可互動元素都可以透過鍵盤訪問，並且 焦點順序遵循一個邏輯的閱讀順序。
• 記錄所有非可見的語義、角色、狀態和 在適當的HTML、ARIA或平台無障礙性API中的即時區域更新。

5. 驗證輸出

• 總是
  • 檢查沒有文字被截斷、重疊或由內容的動態長度推出容器。
  • 檢查所有圖像都已加載且沒有斷鏈。
  • 檢查所有互動元素（按鈕、連結、輸入）具有可見的狀態（預設、懸停、焦點）並且是可點擊或可聚焦的。
  • 檢查所有動畫不被剪切、卡住或不同步。
  • 在至少一個真實裝置或可比較的視口中預覽結果。
• 測量佈局：計算兩個項目之間是否真的是相同的 間隙，以及控制項內部的內容是否居中，每個方向上的邊距是否 來自間距比例。使用像素快照、佈局檢查器網格疊加層或 螢幕尺規工具。不要假設程式碼匹配視覺意圖。
• 在至少一個與任務目標最相關的層級（導航、操作流程、 資訊架構）執行主觀使用者測試，覆蓋典型任務和邊緣 情況。記錄發現的具體問題。測試無障礙性：
  • 鍵盤導航（Tab順序、焦點可見性、Enter/Space激活、Esc關閉）。
  • 使用瀏覽器開發工具模擬的螢幕閱讀器（VoiceOver、NVDA、TalkBack）的螢幕閱讀器流程。
  • 縮放到200%或更高的佈局重排。
• 提供清晰的下一步：剩餘的待辦事項或按優先級排序的已知問題。 如果適用，給出在實施和QA期間使用的具體檢查清單。

主要行為檢查清單

• ✅ 清晰的目標：任務明確且範圍恰當。
• ✅ 設計系統：值來自DESIGN.md、程式碼標記或不矛盾的預設。
• ✅ 幾何：等間距、共享對齊線、居中內容、呼吸空間。
• ✅ 層次結構：大小、權重和對比引導眼睛。
• ✅ 狀態：所有互動元素處理預設、懸停、活動、焦點、禁用、載入和錯誤。
• ✅ 無障礙性：鍵盤導航、螢幕閱讀器、對比度（4.5:1正常，3:1大）、縮放、減少動態。
• ✅ 響應式：佈局適應目標裝置和視口。
• ✅ 無AI垃圾：沒有頁面敘述、冗餘幫助文字或不相關的描述。
• ✅ 真正的內容：使用真實的複製、圖像和資料，而不是佔位符（Lorem Ipsum）。
• ✅ 經過驗證：主觀檢查和無障礙性檢查已完成。
• ✅ 藝術方向：風格源自產品的概念（如果相關）。
• ✅ 動態：動態服務於互動、回饋和引導。
• ✅ 拖放：從一開始就預期，每個上傳都有放置區。
• ✅ 真實狀態：包括骨架載入器和載入畫面。