normalize

normalize 技能概覽

normalize 是做什麼的

normalize 技能會稽核一個 UI 功能，並把它重新拉回既有 design system 的一致軌道。它適合用在某個頁面、route 或 component 已經偏離既有模式的情境，例如 spacing、typography、tokens、state 處理或互動設計逐漸走樣時。

哪些人適合安裝 normalize

這個 normalize 技能最適合已經有某種設計語言基礎的團隊：像是 component library、style guide、token set，或產品內反覆出現的互動模式。對 frontend engineer、design engineer，以及需要在不重做整個產品前提下，清理介面不一致問題的 AI 協作維護者尤其有幫助。

normalize 真正解決的工作需求

使用者通常不是想要「把這頁做得更漂亮」，而是想要：

• 找出功能哪些地方違反了系統既有慣例
• 區分外觀不一致與結構性 UI 問題
• 產出看起來像產品原生的一致性調整
• 在應該沿用既有模式時，避免憑空發明新 pattern

為什麼 normalize 不同於一般提示詞

normalize 最大的差異在於，它明確是一套design-system 對齊工作流，不是開放式的 UI redesign 提示詞。這個技能會引導 agent 先蒐集系統脈絡、分析偏差，再在設計原則不清楚時避免亂猜。它也依賴另一個技能 /frontend-design；如果目前還沒有任何設計脈絡，可能要先跑 /teach-impeccable。

最適合與不適合使用 normalize 的情境

最適合：

• 某個功能看起來和 app 其他部分相比「就是不太對」
• tokens、spacing、typography 或 component 用法不一致
• 團隊想提升一致性，但不想大規模重做產品
• 已經有 Design Systems 工作流，但落地執行不平均

不適合：

• 從零開始的產品設計，沒有可對照的系統
• 品牌探索或視覺方向發想工作
• 在做 UI 清理前，還需要先定 UX 策略的流程
• 期待不提供 repo 脈絡也能自動修好的團隊

如何使用 normalize 技能

normalize 的安裝脈絡

上游 SKILL.md 沒有提供像套件那樣的 install command，所以要透過支援 GitHub-based skills 的宿主技能系統來使用。如果你的環境採用常見 CLI 模式，基礎安裝方式如下：

npx skills add https://github.com/pbakaus/impeccable --skill normalize

但比起安裝本身，更重要的是相依設定：normalize 需要先有 /frontend-design 的 context gathering，如果這個脈絡還沒建立，技能會指示你先執行 /teach-impeccable。

第一次使用 normalize 前的必要前置條件

在呼叫 normalize 之前，請先確認你具備：

• 目標 repository 或相關 UI 檔案的存取權
• 某種 design system 證據：tokens、文件、shared components、style guides、screenshots 或既有慣例
• 可以檢查相鄰功能做 pattern matching 的權限
• 同一個技能環境中可用的 /frontend-design

少了這些脈絡，normalize 就只能猜；而原始指引也明確表示，設計原則不清楚時不應該靠猜測處理。

normalize 期待的輸入格式

參數提示是：

[feature (page, route, component...)]

實務上，最有效的輸入會明確指出一個具體介面，並說清楚要從哪裡看。例子如下：

• normalize settings billing page
• normalize /dashboard/reports route
• normalize AccountMenu component and related dropdown states

比起「整個 app 都幫我調整」，這個技能更適合處理範圍明確、邊界清楚的功能。

如何提出高品質的 normalize 請求

一個比較弱的請求：

• 「Normalize the UI.」

一個更強的請求：

• 「Normalize the /checkout flow to match our existing design system. Focus on spacing, form field hierarchy, button treatments, error states, and component reuse. Compare against our account settings pages and shared form components before changing anything.」

這樣寫的好處是：

• 有明確 scope
• 有指定對照介面
• 有清楚品質標準
• 能降低不必要 redesign 的機率

建議的 normalize 使用流程

一個實用流程如下：

1. 先執行 /frontend-design，依照它的 context-gathering 流程蒐集脈絡。
2. 如果還沒有可用的設計脈絡，再執行 /teach-impeccable。
3. 請 normalize 分析單一功能。
4. 在改 code 前先檢查它提出的 plan。
5. 只讓 agent 實作已經同意的 normalization 範圍。
6. 再回頭檢查相鄰 states 與 variants，避免修正只停留在 happy path。

這個順序很重要，因為 normalize 的核心就是先理解系統，再進行修改。

normalize 應該先檢查什麼

這個技能本身在 repository 層面的支援很精簡，所以你自己的 repo 脈絡才是關鍵。建議要求 agent 優先檢查：

• shared UI components
• token definitions
• design system 或 style guide 文件
• 產品內成熟、可對照的頁面
• form、table、modal、card 與 navigation patterns
• 目前功能的各種狀態：empty、loading、error、disabled、success

如果你只提供目標 component，輸出通常只會停留在表面美化，難以真正做到系統對齊。

優先閱讀的 repository 檔案

針對上游技能本身，請先從這個檔案開始：

• SKILL.md

這份檔案幾乎包含了所有可取得的指引，包括必要的準備步驟，以及 normalize 在修改前要先找出 design system 的工作流重點。

normalize 用於 Design Systems 時的實用提示詞模式

如果你是把 normalize 用在 Design Systems 工作，請務必提供一組對照基準。範例如下：

“Use normalize on the TeamMembers page. First study our design system tokens, the shared table component, and the settings pages. Identify where this page diverges in spacing, typography, action placement, row density, empty states, and status badges. Propose a concise plan, then update the implementation to reuse existing patterns instead of introducing new ones.”

這比單純要求「做得一致一點」更有效，因為它點出了可觀察、可驗證的維度。

使用 normalize 時要預期的限制與取捨

normalize 不是一個神奇的「一鍵變完美」按鈕。常見取捨包括：

• 如果你的系統本身就不一致，技能可能只會把模糊地帶攤開，而不一定能乾淨地做出結論
• 強力做視覺 normalization，可能會暴露出更深層的 UX 問題，而這不是它應該自行發明解法的範圍
• 有些 drift 是產品需求造成的，不一定是實作品質差
• 嚴格一致性有時會和局部功能需求衝突

當系統已經成熟到可以被參照，而不是只能靠推測時，這個技能的可信度最高。

使用 normalize 時最常見的錯誤

請避免以下這些導入阻礙：

• 跳過 /frontend-design
• 一次要求整個 app 做大範圍清理
• 沒有提供任何參考 component 或成熟頁面
• 放任 agent 自行發明 tokens 或 patterns
• 把視覺 normalization 當成產品審查或無障礙審查的替代品

什麼樣的 normalize 結果算成功

好的 normalize 結果應該要：

• 重用既有 components 與 tokens
• 減少一次性、局部特製的 styling
• 讓功能看起來像產品原生的一部分
• 在保留功能意圖的前提下提升一致性
• 清楚說明每個變更為何符合既有 patterns

如果輸出大多只是改顏色與間距，卻沒有 pattern 層級的推理，通常代表你提供的 context 不夠。

normalize 技能 FAQ

normalize 對新手友善嗎？

算友善，但前提是要有明確護欄。新手只要能指出目標功能，再提供幾個品質好的參考介面，就可以使用 normalize。若 codebase 裡沒有明顯的 design system，或產品 patterns 沒有文件化，對新手就會比較不友善。

使用 normalize 一定要有既有 design system 嗎？

不一定要有正式的 design system 網站，但至少要有重複出現的標準證據。shared components、tokens、穩定頁面與視覺慣例通常就足夠。如果這些都不存在，normalize 的適配性就會很弱。

normalize 和直接叫 AI 幫忙整理 UI 有什麼差別？

一般 prompt 常常會直接跳到修改階段；normalize 則明確要求先找出並套用既有標準。這讓它特別適合做一致性工作，尤其在大型產品中，局部優化如果沒有系統脈絡，反而可能讓整體更碎裂。

什麼情況下不該使用 normalize？

當你需要的是以下工作時，就不適合用 normalize：

• 全新的視覺方向
• 產品早期的設計探索
• 大幅度的 UX flow 發明與重構
• 以完整無障礙驗證為主要任務
• 從零建立完整 component library 策略

在這些情況下，normalize 的定位會太窄。

normalize 可以只處理單一 component 嗎？

可以。事實上，這通常是最好的起點。單一頁面區塊、route 或 component，通常能讓技能有足夠的範圍做出合理判斷，同時又讓變更保持可審查。

normalize 只適合做視覺 polish 嗎？

不是。原始說明提到的是 standards、tokens 與 patterns，通常也涵蓋 component 用法、資訊階層與 state handling，不只是表層 styling。不過，它仍然不能取代深入的 UX 研究。

如何改進 normalize 技能的使用效果

幫 normalize 指定對照目標

要最快提升 normalize 的輸出品質，最有效的方法就是明確告訴它你們產品裡什麼叫做「好」。請直接點名兩到三個參考頁面或 components，讓技能有錨點，減少自行腦補設計決策的空間。

提供系統證據，而不只是壞掉的功能

高品質輸入通常包含：

• token files
• shared component paths
• design documentation
• 成熟介面的 screenshots
• 關於受眾或品牌語氣的註記

這些資訊能直接支援技能的核心要求：在修改 code 之前，先找出設計原則。

先要求 plan，再進入實作

因為 normalize 是以對齊既有系統為核心，所以先規劃再動手，可信度會高很多。你可以要求它先列出：

• 偵測到的偏差
• 根本原因
• 可重用的既有 components
• 系統不明確時仍待確認的問題

這樣可以在改動落進 code 之前，就先攔下那種只有 polish、沒有對齊邏輯的輸出。

把大範圍清理拆成以功能為單位的多次處理

如果你想把 normalize 用在大型產品，建議採取漸進式做法：

1. normalize 一個 route
2. normalize 一個 shared component family
3. normalize 一個相鄰 flow
4. 根據前幾輪暴露出的 patterns 再做整併

這樣通常比一次下大範圍要求，更能做出真正一致的結果。

留意這些 normalize 失敗模式

常見失敗模式包括：

• agent 在猜設計語言
• 過度貼合某一個參考頁面
• 明明可以重用既有模式，卻引入新的 variants
• 只修 happy-path 的視覺，忽略其他 states
• 改了樣式，卻說不出它和既有 pattern 的對齊理由

如果你看到這些問題，通常癥結是脈絡不足，而不只是執行品質差。

用後續提示詞強化 normalize 結果

第一輪輸出後，你可以用這類提示詞進一步改善 normalize：

• “Revise this to use only existing button and form patterns.”
• “Re-check empty, loading, and validation states against our settings pages.”
• “List any new patterns you introduced and replace them with existing system equivalents.”
• “Separate must-fix inconsistencies from optional polish.”

這些 follow-up 能讓工作持續緊扣系統一致性，而不是往自由發揮的方向偏掉。

把 normalize 當成降低 design debt 的工具

normalize 最有價值的用法，是反覆套用在那些容易 drift 的區域：舊 route、剛上線不久的功能，或很多 contributor 都碰過的介面。把它視為精準處理 design debt 的工具，而不是一次性的美化器。

透過明確非協商條件來提升 normalize 輸出

請直接告訴技能哪些部分必須保持穩定：

• layout constraints
• business logic
• component APIs
• accessibility requirements
• release-risk limits

這能幫助 normalize 聚焦在 system alignment，而不會過度延伸到無關的重寫工作。