impeccable

設計並迭代生產級前端介面。真實可運行的程式碼、經過深思熟慮的設計決策、卓越的工藝。

設定

在繼續之前，你必須執行以下步驟：

1. 每個工作階段執行一次 node .claude/skills/impeccable/scripts/context.mjs。如果你已經在此對話中看過它的輸出，請勿重新執行。該腳本會將專案的 PRODUCT.md（以及 DESIGN.md，如果存在）以 Markdown 區塊形式印出，或者告訴你它缺失。按照它印出的內容操作。如果它報告 NO_PRODUCT_MD，請停止並在執行任何其他操作之前遵循 reference/init.md。 如果輸出結尾有 UPDATE_AVAILABLE 指令，請遵循它（詢問使用者一次是否要更新，然後繼續）。它永遠不會阻塞當前任務。
2. 如果使用者呼叫了子命令（craft、shape、audit、polish……），你必須接著閱讀 reference/<command>.md。這是非選擇性的。參考文件定義了命令的流程；沒有它，你會跳過使用者期望的步驟。
3. 熟悉程式碼中任何現有的設計系統、慣例和元件。至少閱讀一個專案檔案（CSS / tokens / theme / 一個代表性的元件或頁面）。即使在步驟 2 中已載入子命令參考文件，這也是必需的。 不要重新發明輪子；在現有內容有效時使用它，在 UX 勝出時進行擴展。
4. 閱讀對應的 register 參考文件。這是非選擇性的；跳過它會產生通用的輸出。 如果專案是行銷、登陸頁面、活動、長篇內容或作品集（設計即產品），請閱讀 reference/brand.md。如果是應用程式 UI、管理後台、儀表板或工具（設計服務於產品），請閱讀 reference/product.md。根據以下條件選擇第一個匹配項：(1) 任務提示（"landing page" vs "dashboard"）；(2) 正在處理的表面（頁面、檔案或路由）；(3) PRODUCT.md 中的 register 欄位。
5. 如果專案是全新的（在步驟 3 中未找到現有的 CSS tokens / theme / 已提交的品牌顏色），請執行 node .claude/skills/impeccable/scripts/palette.mjs 以接收品牌種子顏色和構圖指導。這是你的主要品牌顏色的錨點。根據腳本的指示，圍繞它組合其餘的調色板（bg、surface、ink、accent、muted）。全程使用 OKLCH。僅當步驟 3 在現有 tokens 中找到了已提交的品牌顏色時才跳過此步驟；在這種情況下，保留品牌識別優先。

設計指導

產出可出貨的生產級程式碼，而非原型或起點。除非使用者要求（有疑問時請詢問），否則不要走捷徑。在達成完整實作之前不要停止（美觀、響應式、快速、精確、無錯誤、符合品牌）。你認真對待細節：每個頁面、區塊或元件都使用你可用的工具（瀏覽器截圖、電腦使用等）進行了實戰測試。Claude 能夠完成非凡的工作。不要保留。

通用規則

色彩

• 驗證對比度。 正文文字與其背景的對比度必須達到 ≥4.5:1；大字型（≥18px 或粗體 ≥14px）需要 ≥3:1。佔位符文字也需要 4.5:1，而不是預設的淺灰色。最常見的失敗：在帶色調的近白色背景上使用淺灰色正文。如果對比度接近，請將正文顏色向色階的墨水端移動；淺灰色「為了優雅」是 AI 設計難以閱讀的最大單一原因。
• 灰色文字在彩色背景上看起來褪色。使用背景色調的較深色調，或文字顏色的透明度。

排版

• 將正文行長限制在 65–75ch。
• 不要搭配相似但不相同的字型（兩個幾何無襯線字體、兩個人文無襯線字體）。在對比軸上搭配（襯線 + 無襯線、幾何 + 人文），或使用一個系列的多種字重。
• 主視覺 / 顯示標題上限：clamp() 最大值 ≤ 6rem（約 96px）。超過此值，頁面是在吼叫，而不是在設計。
• 顯示標題字距下限：≥ -0.04em。再緊的話字母會碰在一起；擁擠，而不是「設計」。
• 在 h1–h3 上使用 text-wrap: balance 以獲得均勻的行長；在長篇散文中使用 text-wrap: pretty 以減少孤行。

佈局

• 變化間距以創造節奏。
• 卡片是懶惰的答案。僅在它們確實是最佳 affordance 時使用它們。嵌套卡片永遠是錯的。
• 一維使用 Flexbox，二維使用 Grid。不要預設使用 Grid，而 flex-wrap 更簡單。
• 對於無斷點的響應式網格：repeat(auto-fit, minmax(280px, 1fr))。
• 建立語義化的 z-index 層級（dropdown → sticky → modal-backdrop → modal → toast → tooltip）。永遠不要使用像 999 或 9999 這樣的任意值。

動畫

• 動畫應該是有意圖的，而不是事後才想到。將其視為建構的一部分。
• 除非確實需要，否則不要對 CSS 佈局屬性進行動畫處理。
• 使用指數曲線進行淡出（ease-out-quart / quint / expo）。不要彈跳，不要彈性。
• 對於更高階的動畫需求，使用函式庫（例如 motion、gsap、anime.js、lenis 等）。
• 減少動畫不是可選項。每個動畫都需要一個 @media (prefers-reduced-motion: reduce) 替代方案：通常是交叉淡入淡出或即時過渡。
• 在同一個列表中交錯項目是合理的。問題在於統一的反射（每個區塊使用相同的入場動畫），而不是動畫本身；每個揭示應該適合它所揭示的內容。壓制反射絕不是交付一個完全沒有動畫的頁面的理由。
• 揭示動畫必須增強已經可見的預設狀態。不要將內容可見性限制在類別觸發的過渡上；過渡會在隱藏的標籤頁和無頭渲染器上暫停，因此揭示永遠不會觸發，區塊會以空白狀態出貨。
• 高級動畫素材不僅僅是 transform/opacity。模糊、backdrop-filter、clip-path、mask 和陰影/發光都是調色板的一部分，當它們能實質改善效果並保持流暢時。

互動

• 在 overflow: hidden 或 overflow: auto 容器內使用 position: absolute 渲染的下拉選單將被裁剪。使用原生 <dialog> / popover API、position: fixed 或 portal 來逃脫堆疊上下文。

僅限新專案（當沒有先前工作時）

色彩與主題

• 使用 OKLCH。
• 奶油色 / 沙色 / 米色背景是 2026 年飽和的 AI 預設。 整個暖中性色帶（OKLCH L 0.84-0.97, C < 0.06, hue 40-100）無論你怎麼稱呼它，看起來都是奶油色/沙色/紙張/羊皮紙。像 --paper、--cream、--sand、--bone、--flour、--linen、--parchment、--wheat、--biscuit、--ivory 這樣的代幣名稱本身就是線索。如果需求是「溫暖、傳統、家庭式海岸義大利」或「雜誌溫暖」或「編輯約束」，不要將其轉化為近白色暖色調背景；那是 AI 的做法。選擇：(a) 飽和的品牌顏色作為背景（陶土紅、牛血紅、深赭色、近黑色），(b) 色度為 0 的真正米白色（或色度朝向品牌自己的色調，而不是預設的溫暖），或 (c) 明顯屬於品牌自己的較深中間色調中性色。品牌中的「溫暖」由強調色 + 排版 + 圖像承載，而不是由背景色承載。
• 帶色調的中性色：向品牌色調方向增加 0.005–0.015 的色度。不要因為「品牌感覺那樣」而預設向暖或冷色調傾斜；那是跨專案單一文化的做法。
• 選擇主題時：深色 vs. 淺色永遠不是預設。不是因為「工具用深色看起來很酷」。不是因為「淺色比較安全」。在選擇之前，寫一句關於物理場景的句子：誰使用這個、在哪裡、在什麼環境光下、以什麼心情。如果這句話沒有強制給出答案，那就不夠具體。增加細節直到它給出答案。
• 在選擇顏色之前，先選擇一個色彩策略。在承諾軸上有四個步驟：
  • 克制：帶色調的中性色 + 一個 ≤10% 的強調色。產品預設；品牌極簡主義。
  • 投入：一個飽和色承載 30–60% 的表面。以識別為導向的頁面的品牌預設。
  • 完整調色板：3–4 個命名角色，每個都有目的地使用。品牌活動；產品資料視覺化。
  • 浸透：表面就是顏色。品牌主視覺、活動頁面。

絕對禁止

比對並拒絕。如果你即將寫出以下任何一項，請用不同的結構重寫該元素。

• 側邊條邊框。 在卡片、列表項、提示框或警告上使用大於 1px 的 border-left 或 border-right 作為彩色強調。永遠不是有意的。改用全邊框、背景色調、前導數字/圖示，或什麼都不用。
• 漸層文字。 background-clip: text 搭配漸層背景。裝飾性，從未有實際意義。使用單一純色。透過字重或大小來強調。
• 玻璃擬態作為預設。 模糊和玻璃卡片用於裝飾。罕見且有目的，否則不要用。
• 英雄指標模板。 大數字、小標籤、支援統計數據、漸層強調。SaaS 陳腔濫調。
• 相同的卡片網格。 相同大小的卡片，帶有圖示 + 標題 + 文字，無休止地重複。
• 每個區塊上方的小型大寫追蹤眉毛。 2023 時代的 kicker（帶有寬字距的小型全大寫文字，如「ABOUT」「PROCESS」「PRICING」）現在是飽和的 AI 支架；無論需求如何，它在 55-95% 的生成中出現，這正是線索的定義。一個命名的 kicker 作為有意的品牌系統是聲音；每個區塊上都有一個眉毛是 AI 語法。選擇不同的節奏。
• 作為預設支架的編號區塊標記（01 / 02 / 03）。 在每個區塊上方放置 01 · About / 02 · Process / 03 · Pricing 是眉毛比喻的更深一層：因為「登陸頁面都這樣做」而使用它，而你只是出於反射在搭建支架。數字只有在區塊確實是一個序列（一個真正的三步驟流程、一個有序的流程、一個有時間順序的時間軸）並且順序承載讀者需要的資訊時才有其價值。一個頁面上一個有意的編號序列是聲音；整個網站每個區塊上都有編號眉毛是 AI 語法。
• 文字溢出容器。 長的標題詞彙加上大的 clamp 比例加上窄的網格，導致在平板/手機上標題溢出。在每個斷點測試標題文案；如果溢出，減少 clamp 最大值或重寫文案。視口是設計的一部分。

AI 垃圾測試

如果有人可以看著這個介面並毫不懷疑地說「AI 做的」，那它就失敗了。跨 register 的失敗是上面的絕對禁止。特定 register 的失敗存在於每個參考文件中。

類別反射檢查。 在兩個層級執行；第二個會捕捉第一個遺漏的。

• 第一層： 如果有人僅從類別就能猜出主題 + 調色板，那就是第一個訓練資料反射。重新設計場景句子和色彩策略，直到答案從領域中不明顯。
• 第二層： 如果有人能從類別加反參考（「不是 SaaS 奶油色的 AI 工作流程工具 → 編輯排版」、「不是海軍藍和金色的金融科技 → 終端原生深色模式」）猜出美學家族，那就是更深一層的陷阱。第一個反射被避免了；第二個沒有。重新設計，直到兩個答案都不明顯。品牌 register 的反射拒絕美學車道列表捕捉了當前飽和的家族。

命令

命令	類別	描述	參考文件
craft [feature]	建構	規劃，然後端到端建構一個功能	reference/craft.md
shape [feature]	建構	在寫程式碼之前規劃 UX/UI	reference/shape.md
init	建構	設定專案上下文：PRODUCT.md、DESIGN.md、live 配置、下一步	reference/init.md
document	建構	從現有專案程式碼生成 DESIGN.md	reference/document.md
extract [target]	建構	將可重複使用的 tokens 和元件提取到設計系統中	reference/extract.md
critique [target]	評估	使用啟發式評分的 UX 設計審查	reference/critique.md
audit [target]	評估	技術品質檢查（無障礙、效能、響應式）	reference/audit.md
polish [target]	精煉	出貨前的最終品質檢查	reference/polish.md
bolder [target]	精煉	放大安全或平淡的設計	reference/bolder.md
quieter [target]	精煉	降低激進或過度刺激的設計	reference/quieter.md
distill [target]	精煉	剝離至本質，移除複雜性	reference/distill.md
harden [target]	精煉	生產就緒：錯誤、國際化、邊界情況	reference/harden.md
onboard [target]	精煉	設計首次使用流程、空狀態、啟用	reference/onboard.md
animate [target]	增強	加入有目的的動畫和動態	reference/animate.md
colorize [target]	增強	為單色 UI 加入策略性色彩	reference/colorize.md
typeset [target]	增強	改善排版層級和字型	reference/typeset.md
layout [target]	增強	修正間距、節奏和視覺層級	reference/layout.md
delight [target]	增強	加入個性和令人難忘的細節	reference/delight.md
overdrive [target]	增強	突破傳統限制	reference/overdrive.md
clarify [target]	修正	改善 UX 文案、標籤和錯誤訊息	reference/clarify.md
adapt [target]	修正	為不同裝置和螢幕尺寸進行調整	reference/adapt.md
optimize [target]	修正	診斷並修正 UI 效能	reference/optimize.md
live	迭代	視覺變體模式：在瀏覽器中選取元素，生成替代方案	reference/live.md

另外還有三個管理命令：pin <command>、unpin <command> 和 hooks <on|off|status|...>，詳見下方。

路由規則

1. 無參數：使用者在問「我該做什麼？」讓選單具有上下文感知能力，而不是靜態的。Setup 已經執行了 context.mjs；如果它報告了 NO_PRODUCT_MD，你已經在 init（setup）中，所以完成它並跳過此步驟。否則，執行一次 node .claude/skills/impeccable/scripts/context-signals.mjs 並讀取其 JSON，然後以 2-3 個最高價值的後續命令 作為開頭，每個命令附帶一行從訊號中提取的理由，接著是完整選單（上表，按類別分組）。永遠不要自動執行命令；推薦是使用者確認的建議。

   對訊號進行推理；沒有需要遵守的分數：

   • setup.hasDesign 為 false 而 setup.hasCode 為 true → document（捕捉視覺系統）。
   • critique.latest 為 null → 專案從未被評論過；對於一個已設定且有真實表面的專案，提供 /impeccable critique <surface> 是一個強烈的預設。
   • critique.latest 具有低 score 或非零的 p0 / p1 → polish（它將該快照讀取為其待辦事項），或者如果快照看起來過時，則重新執行 critique。
   • git.changedFiles 指向一個表面 → 將 audit 或 polish 的範圍限定在這些檔案上，並命名它們。
   • devServer.running 為 true → live 可用於瀏覽器內迭代；如果為 false，不要以 live 作為開頭。
   • 否則，完全按照 init 的「推薦起點」步驟（建構新內容 / 改善現有內容 / 視覺迭代）按意圖分組，並根據 setup.register 進行調整。

   如果 scan.targets 非空，執行一次 node .claude/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>（捆綁的檢測器針對本地檔案：無網路，無 npx）。scan.via 告訴你它們是什麼：git-changes（髒樹中的標記/樣式檔案，最相關的集合）、source-dir（例如 src、app）、html 或 root。將命中結果納入你的選擇：許多品質/對比度命中 → audit 或 polish；一個特定的垃圾家族 → 匹配的命令（漸層文字或眉毛 → quieter / typeset，平坦或灰色調色板 → colorize，等等）。這是一個真實的、當前的訊號，勝過猜測。如果 detect 出錯或樹很大且慢，跳過它並建議使用者自己執行 audit；永遠不要因為它而阻塞建議。

   保持 2-3 個精準的選擇，並附上要輸入的確切命令。選單仍然是備用方案；推薦是開場白。

2. 第一個詞匹配命令（上表或 pin / unpin / hooks）：載入其參考文件並遵循其指示。命令名稱之後的所有內容都是目標。

3. 第一個詞不匹配，但意圖明顯對應到一個命令（例如「修正間距」→ layout、「重寫這個錯誤訊息」→ clarify、「顏色感覺平淡」→ colorize）：載入該命令的參考文件並像被呼叫一樣繼續。如果兩個命令都適合，詢問一次選擇哪個。

4. 沒有明確的命令匹配：一般設計呼叫。應用 setup 步驟、通用規則和已載入的 register 參考文件，使用完整參數作為上下文。

Setup（上下文收集、register）此時已載入；子命令不會重新呼叫 /impeccable。

如果第一個詞是 craft，setup 仍然先執行，但 reference/craft.md 擁有其餘流程的所有權。如果 setup 呼叫 init 作為阻塞項，完成 init，重新整理上下文，然後恢復原始命令和目標。

teach 是 init 的已棄用別名：如果使用者輸入它，載入 reference/init.md 並像他們執行了 init 一樣繼續。

Pin / Unpin

Pin 建立一個獨立的快捷方式，使得 /<command> 直接呼叫 /impeccable <command>。Unpin 移除它。該腳本會寫入專案中存在的每個 harness 目錄。

node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>

有效的 <command> 是上表中的任何命令。簡潔地報告腳本的結果。成功時確認新的快捷方式，錯誤時逐字轉發 stderr。

Hooks

/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> 管理此專案的設計檢測器 hook。該 hook 在直接 UI 檔案編輯後自動執行檢測器，並將發現結果作為系統提醒呈現。完整流程在 reference/hooks.md 中；當使用者使用任何參數呼叫 /impeccable hooks 時載入它。