normalize

normalize 技能總覽

normalize 的作用是什麼

normalize 技能會稽核某個 UI 功能，並把它重新對齊到既有的 design system。它特別適合用在頁面、route 或元件逐漸偏離既有模式、間距、tokens、資訊層級或互動慣例的情境。

哪些人適合使用 normalize

如果你的團隊已經有一定的設計方向，希望代理把實作拉回既有規範，那就適合用 normalize。它很適合前端團隊、design system 負責人，以及在成熟產品中工作的 product engineer；這類情境下，不一致的成本通常比重新發想新 UI 還高。

真正要解決的工作需求

大多數使用者並不是想要「畫面更漂亮」。他們真正需要的是：讓某個功能在外觀與行為上都和產品其他部分一致，同時避免再長出新的一次性樣式。normalize skill 最適合的目標是「一致性」，不是「創意發想」。

這個技能和一般提示有什麼不同

不同於泛用的「improve this UI」提示，normalize 是明確以既有標準為依據。repository 傳達得很清楚：這個技能不應該用猜的。它要求先蒐集 design context、找出偏差，並且在動手修改前先提出計畫。

最適合的使用情境

• 某個功能使用了不一致的 spacing、typography 或 color tokens
• 某個元件在視覺上可用，但和系統規範不一致
• Legacy UI 需要先整理乾淨，才能進一步做較大的重構
• 新頁面是趕著上線的，現在需要補做 design-system 對齊
• 團隊想做 normalization，但不想改動產品原本的設計意圖

哪些情況下 normalize 並不理想

如果你的團隊還沒有文件化的 patterns、沒有可重用元件，或產品／UX 方向本身都還沒定案，那 normalize for Design Systems 並不是好的第一步。這種情況下，它或許能幫你暴露出缺口，但無法安全地替你發明一套可作為權威依據的標準。

如何使用 normalize 技能

在你的 skills 環境中安裝 normalize

這個 repo 沒有在 SKILL.md 內提供安裝指令，因此多數目錄使用者通常會依照自己現有的 skill system，從 source repository path 加入。如果你的環境支援直接從 GitHub 安裝 skill，請使用 pbakaus/impeccable repository，並選擇 normalize skill。

如果你使用的指令格式類似：
npx skills add pbakaus/impeccable --skill normalize

請先和你自己的 runner 確認是否相容。重點是：這個 skill 應該位於 .agents/skills/normalize。

第一次使用前，先讀這個檔案

先從這個檔案開始：

• SKILL.md

這個 skill 在資料夾內沒有額外的 helper files、scripts 或參考文件，所以幾乎所有可用指引都集中在這一個檔案裡。這對快速上手是好事，但也代表缺少的專案背景必須由你自己補齊。

先理解它對 frontend-design 的必要依賴

最大的導入障礙其實很容易被忽略：normalize 明確寫了你必須先呼叫 /frontend-design。這個上游 skill 包含了這套 workflow 所依賴的設計原則、anti-patterns，以及蒐集 context 的流程。

它也說明，如果目前還沒有任何 design context，就必須先執行 /teach-impeccable 再往下走。實務上，normalize usage 比較像是一個串接式 workflow，不是獨立的一次性 prompt。

了解 normalize 預期的輸入內容

它宣告的參數提示是：
[feature (page, route, component...)]

好的輸入會是具體的 UI 工作單位，例如：

• checkout page
• settings/billing route
• pricing card component
• mobile nav menu

較弱的輸入則是這種過於籠統的目標：

• the whole app
• make the UI better
• fix styling everywhere

把模糊需求改寫成更強的 normalize prompt

一個弱的請求：
Normalize the dashboard

一個更強的請求：
Use normalize on the analytics dashboard route. Align it to our design system by checking token usage, spacing scale, typography hierarchy, component variants, and empty-state patterns. Preserve current functionality. Flag any places where the design system is unclear instead of guessing.

為什麼這樣效果更好：

• 明確指出功能邊界
• 先定義 normalization 的判準
• 保護既有功能不被誤動
• 告訴代理在標準不清楚時該怎麼處理

執行 normalize 前，先準備最基本的 context

若想得到高品質輸出，請提供：

• 目標功能的 path 或 route
• 你的 component library 或 design system 位置
• token 來源，例如 theme files 或 CSS variables
• 相關 UI 規範或螢幕截圖
• 任何「不能改」的商業限制
• 你要的是只出 plan，還是 plan 加 edits

少了這些 context，這個 skill 還是能看出哪裡有 drift，但無法可靠地判斷應該替換成哪一種正確 pattern。

依照 normalize 技能暗示的流程來跑

repository 內容支持以下順序：

1. 執行 /frontend-design
2. 如果 design context 不足，執行 /teach-impeccable
3. 找出 design system 文件、component patterns 與 tokens
4. 分析目前功能有哪些偏差
5. 制定 normalization plan
6. 以保守方式執行修改
7. 清理一次性 styling 與各種不一致

這個順序很重要，因為這個 skill 的核心立場就是：不要替標準亂猜。

normalize 技能應該在你的 codebase 裡檢查什麼

source 片段特別強調：

• 設計原則與整體視覺方向
• 目標受眾與 personas
• 元件模式與使用慣例
• color、type、spacing 的 design tokens
• 不一致究竟只是外觀問題，還是已影響功能
• 根本原因，例如一次性實作或缺少 tokens

這代表 normalize install 只是導入決策的一半。更關鍵的是：你的 repo 是否真的暴露了足夠多這些訊號，讓代理能照著規範做出判斷。

能提升 normalize 輸出的 prompt 寫法

同時要求診斷與行動：
Normalize the account settings page. First identify where it deviates from our system and categorize issues as token misuse, layout inconsistency, component misuse, or interaction mismatch. Then propose the minimal set of edits to align it.

要求處理不確定性：
If a pattern is not documented, stop and ask rather than inventing a new one.

要求固定輸出格式：
Return a brief audit, a change plan, then the implementation.

在真實產品中使用 normalize 技能的實務護欄

若想讓 normalize guide 用得更安全：

• 保留產品需求與文案原意
• 除非明顯違反既有 patterns，否則不要變動使用流程
• 優先用既有 primitives 取代自訂 styling
• 要求提供能減少一次性 code 的 diffs，而不只是做視覺微調
• 要求代理指出 design system 本身不一致的地方

一次有價值的 normalization，通常不只會改善 UI 一致性，也會提升後續維護性。

normalize 技能 FAQ

normalize 比一般的 UI cleanup prompt 更好嗎？

通常是，前提是你本來就有 design system。normalize 的價值不在於「prompt 寫得花俏」，而在於它強制你先蒐集標準、再依那些標準檢查 drift，並避免憑空做出設計決策。

normalize 對新手友善嗎？

算是中等。skill 本身不複雜，但新手常常缺少它所預設的前提條件：設計文件、token 來源，以及對「什麼才算 canonical」的判斷把握。如果你是初學者，建議先從單一路由或單一元件這種較小範圍開始。

沒有正式 design system，normalize 技能還能用嗎？

只能部分發揮。它還是能指出不一致之處，但只要缺少清楚的 source of truth，輸出品質就會明顯下降。這個 skill 明確反對用猜的，所以缺失的標準會變成真正的阻塞，而不是被默默當成隱含假設。

normalize 技能不擅長哪些事？

它主要不是拿來做這些事情：

• greenfield 視覺探索
• 大幅 UX 策略調整
• brand 發想
• 一次處理全 app 的大規模重構

請把它用在 alignment，而不是廣泛的產品重設計。

normalize 技能如何對應不同 frontend stack？

normalize skill 在概念上和 stack 無關，因為它聚焦的是 tokens、patterns 和 conventions。當 codebase 有可重用元件、theme primitives，以及足夠清楚的結構，能讓代理追出哪些 UI 決策才是 canonical 時，它的效果會最好。

什麼時候應該避免使用 normalize for Design Systems？

當你真正的問題是產品範圍還沒定，不是視覺不一致時，就應該避免使用。另外，如果團隊對 design system 本身都還有分歧，也不適合用；否則這個 skill 可能只是把力氣花在對齊一個仍在移動中的目標。

如何提升 normalize 技能的效果

給 normalize 更小、更明確的目標

最快看見品質提升的方法就是縮小範圍。讓 normalize 一次只處理一個 route、一個 feature，或一組相關元件。範圍越小，audit 越清楚、意外 regression 越少，alignment 判斷也會更準。

提供真正的 source of truth

不要只說「照我們的 design system 做」。請直接指向：

• component folders
• Storybook 或 docs URL
• token files
• canonical screens 的截圖
• 已核准 patterns 的實例

這能直接降低最常見的失敗模式：看似合理、其實對錯了的 alignment。

分清楚是 cosmetic drift 還是 pattern drift

好的請求會明確告訴 skill 你要的是：

• 只清理 tokens
• 對齊視覺層級
• 以核准 variants 取代元件
• 連互動行為也一起做 normalization

這個區分會大幅改變最後的計畫，也能避免過度修改。

告訴 normalize 技能哪些東西不能改

更好的 normalize usage prompt 會加上這類限制：

• 保留目前的 data flow
• 不要改動 validation logic
• 保留既有 accessibility 行為
• 維持 analytics selectors 穩定
• 避免引入新元件

這樣才能讓 normalization 聚焦在 system fit，而不是意外演變成重構。

先要求計畫，再要求改 code

既然 repository 本身就強調先規劃，那就善用這點。請要求輸出：

1. design-system findings
2. deviation audit
3. proposed normalization steps
4. 最後才是 implementation

這是最容易在早期抓出錯誤假設的方法。

明確處理缺失的標準

如果代理找不到 spacing、typography 或 component choice 的規則，請明確要求它：

• 先停下來提問
• 提出附帶 tradeoffs 的選項
• 把這個缺口標記為 design-system issue

這樣的行為，比起硬猜一個答案，更符合這個 skill 的設計意圖。

審查時看可維護性，不只看畫面截圖

最好的 normalize guide 結果，不只是畫面看起來比較一致。你還應該檢查結果是否：

• 把 hard-coded values 換成 tokens
• 移除自訂的一次性 wrappers
• 重用已核准的 primitives
• 讓系統未來更新更簡單

這正是這個 skill 能替 design systems 帶來長期價值的地方。

第一次 normalize 技能跑完後，再做一輪迭代

第一輪完成後，請補一個聚焦的 follow-up：
Re-check the implementation and list any remaining deviations from the design system, especially token usage, component variants, and spacing rhythm.

第二輪往往才會抓出那些比較細微的不一致。

用對照範例提升 normalize 輸出品質

如果你手上有 gold-standard screen，就直接講清楚：
Normalize the billing page to match the visual and structural patterns used in the account overview page.

對 normalize for Design Systems 來說，參考範例是槓桿效果最高的輸入之一。

了解 normalize 技能最常見的失敗模式

請特別留意：

• 文件不足時，代理自行發明 patterns
• 修正過頭，連 UX 原意也被改掉
• 只做到視覺對齊，卻沒清理 tokens
• 只修局部，忽略 shared components
• 做了一堆廣泛的「polish」修改，卻沒有 design-system 依據

如果你看到這些情況，就應該縮小範圍、補更多參考，並要求所有判斷都明確對應到你的系統依據。