normalize

normalize 技能概览

normalize 是做什么的

normalize 技能用于审查某个 UI 功能，并将其重新拉回到现有设计系统的规范之内。它适合处理这样的情况：某个页面、路由或组件已经偏离了既有模式，比如间距、字体排版、token、状态设计或交互方式与产品其他部分不一致。

谁适合安装 normalize

这个 normalize 技能最适合已经具备一定设计语言基础的团队：例如已有组件库、style guide、token 体系，或在产品中已经反复出现的一致性模式。对于前端工程师、设计工程师，以及使用 AI 协助维护、需要清理界面不一致问题但又不想重做整个产品的团队成员来说，它尤其有价值。

normalize 真正解决的工作问题

用户通常并不是想要“把它做得更好看”，而是想要：

• 找出某个功能在哪些地方破坏了系统既有规范
• 区分表层视觉不一致和结构性的 UI 问题
• 产出看起来像产品原生一部分的修改
• 在应该复用现有模式时，避免凭空创造新模式

normalize 与普通通用提示词的区别

normalize 的核心差异在于：它明确是一个面向设计系统对齐的工作流，而不是一个开放式的 UI 重设计提示。这个技能会推动 agent 先收集系统上下文，再分析偏差，并在设计原则不明确时避免主观猜测。它还依赖另一个技能 /frontend-design；如果当前完全没有设计上下文，可能还需要先运行 /teach-impeccable。

normalize 的适用与不适用场景

适合使用：

• 某个功能看起来和应用其他部分“不太对劲”
• token、间距、字体排版或组件用法不一致
• 团队希望提升一致性，但不想进行大范围产品重设计
• 已经有 Design Systems 工作流，但落地执行并不均匀

不适合使用：

• 从零开始设计产品，且没有可对齐的系统
• 品牌探索或视觉方向定义类工作
• 需要先做 UX 策略再谈 UI 清理的流程
• 希望在不给仓库上下文的前提下自动修复一切的团队

如何使用 normalize 技能

normalize 的安装上下文

上游 SKILL.md 没有提供类似 package 的安装命令，因此应通过支持 GitHub-based skills 的宿主技能系统来使用它。如果你的环境采用常见的 CLI 模式，基础安装方式是：

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

不过，比安装本身更重要的是依赖准备：normalize 需要先有 /frontend-design 的上下文收集结果。如果这部分上下文尚未建立，技能会明确要求你先运行 /teach-impeccable。

首次使用 normalize 前的必备条件

在调用 normalize 之前，请确认你具备：

• 目标仓库或相关 UI 文件的访问权限
• 某种设计系统证据：tokens、文档、共享组件、style guides、截图或既有规范
• 允许查看相邻功能以进行模式比对
• 在同一技能环境中可用的 /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.”

这样提问更有效，因为它：

• 明确了范围
• 指定了可比较的参考界面
• 给出了质量判断标准
• 降低了不必要重设计的风险

推荐的 normalize 使用流程

一个实用流程是：

1. 先运行 /frontend-design，并按它的上下文收集流程执行。
2. 如果还没有可用的设计上下文，就运行 /teach-impeccable。
3. 让 normalize 先分析一个功能。
4. 在改代码之前先审阅方案。
5. 只让 agent 实施已经确认过的 normalize 工作。
6. 回头检查相邻状态和变体，避免修复只停留在 happy path。

这个顺序很重要，因为 normalize 的设计逻辑就是：先理解系统，再动手修改。

normalize 应该优先检查什么

由于这个技能本身在仓库侧提供的支持很少，因此你自己的 repo 上下文最关键。建议让 agent 优先检查：

• 共享 UI 组件
• token 定义
• design system 或 style guide 文档
• 产品中相似且较成熟的页面
• 表单、表格、modal、card 和导航模式
• 当前功能的各种状态：empty、loading、error、disabled、success

如果你只提供目标组件本身，输出质量通常会停留在“表层美化”层面。

首先要读的仓库文件

对于这个上游技能本身，优先查看：

• SKILL.md

这个文件几乎包含了目前所有可用指导，包括强制性的准备步骤，以及 normalize 在实际工作流中“先识别设计系统、再做改动”的重点。

面向 Design Systems 使用 normalize 的实用提示模板

如果你是把 normalize 用在 Design Systems 相关工作上，一定要给 agent 一组对比参考。示例：

“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 不是一个神奇的“自动做到完美”按钮。常见权衡包括：

• 如果你的系统本身就不一致，技能可能暴露出模糊地带，而不是直接帮你做出干净明确的裁决
• 强行做视觉归一化，可能会暴露更深层的 UX 问题，而这些问题不应该由它擅自发明解决方案
• 某些偏差来自真实产品需求，而不是糟糕实现
• 过度追求严格一致，可能会与局部功能的实际需求冲突

当设计系统已经足够成熟、可以被参考而不是被推测时，normalize 的输出才最值得信任。

使用 normalize 时的常见错误

尽量避免这些落地障碍：

• 跳过 /frontend-design
• 试图一次性做全应用的大扫除
• 不提供参考组件或成熟页面
• 放任 agent 自行发明 tokens 或新模式
• 把视觉归一化当作产品评审或无障碍评审的替代品

什么样的 normalize 结果算成功

一个好的 normalize 结果应该：

• 复用现有组件和 tokens
• 减少一次性样式写法
• 让功能看起来像产品原生的一部分
• 在提升一致性的同时保留功能本意
• 说明每一项修改为什么符合既有模式

如果输出主要只是改了颜色和间距，却没有模式层面的解释，那通常说明你提供的上下文还不够。

normalize 技能 FAQ

normalize 对新手友好吗？

是的，但前提是有清晰护栏。只要新手能明确指出目标功能，并提供几个质量较高的参考界面，就可以使用 normalize。真正不友好的情况是：代码库里看不出明确设计系统，或者产品模式根本没有文档化。

使用 normalize 一定需要现成的设计系统吗？

不一定非要有正式的 design system 站点，但你至少需要能证明系统中存在重复出现的标准。共享组件、tokens、稳定页面和视觉规范通常就够了。如果这些都不存在，normalize 的适配度就会明显下降。

normalize 和直接让 AI 清理 UI 有什么不同？

普通提示通常会直接跳到“开始改”。而 normalize 明确要求先找出并应用现有标准。这让它更适合做一致性工作，尤其是在较大的产品里，因为局部优化很容易在无意间进一步割裂整个系统。

什么情况下不该用 normalize？

当你需要以下工作时，不要使用 normalize：

• 全新的视觉方向
• 产品早期阶段的设计探索
• 大幅度 UX 流程发明
• 以广泛无障碍验证为首要目标
• 从零制定完整组件库策略

在这些场景下，normalize 的能力边界过窄。

normalize 能处理单个组件吗？

可以。实际上，这通常是最好的切入点。一个单独的页面区域、路由或组件，既能给技能足够的分析空间，又能让修改保持在便于评审的范围内。

normalize 只适合做视觉润色吗？

不是。原始说明提到的是 standards、tokens 和 patterns，这通常也包括组件用法、层级关系和状态处理，而不仅仅是表面样式。尽管如此，它依然不能替代深入的 UX 研究。

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

给 normalize 明确的对比目标

提升 normalize 输出质量最快的方法，就是明确告诉它在你的产品里“什么算好”。直接点名两三个参考页面或组件。这样技能就有了锚点，也能减少凭空做出的设计决策。

提供系统证据，而不只是问题功能本身

高质量输入通常包括：

• token 文件
• 共享组件路径
• design 文档
• 成熟界面的截图
• 关于目标用户或品牌语气的说明

这些信息能直接支撑该技能的核心前提：在改代码之前，先识别设计原则。

先要方案，再做实现

因为 normalize 本质上是一个“对齐型”技能，先做规划更容易建立信任。你可以要求它先输出：

• 检测到的偏差
• 根本原因
• 可复用的现有组件方案
• 设计系统不明确之处的待确认问题

这样可以在代码落地前，提前识别出那种只做“表面 polish”的输出。

把大范围清理拆成按功能划分的多次执行

如果你希望在大型产品中使用 normalize，不要一次铺太大，建议逐步推进：

1. normalize 一个路由
2. normalize 一类共享组件
3. normalize 一个相邻流程
4. 汇总前几轮暴露出的模式，并进行统一

与一次性的大范围请求相比，这种方式通常更能真正提升一致性。

留意这些常见失败模式

常见失败模式包括：

• agent 在猜测设计语言
• 过度贴合某一个参考页面
• 引入新变体，而不是复用现有变体
• 只修 happy path 的视觉，不检查状态
• 做了样式修改，却没有解释其与既有模式的对齐关系

如果你遇到这些问题，通常根源不是执行力差，而是上下文不足。

用更强的追问提示提升 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.”

这类追问能让工作持续锚定在系统一致性上，而不是滑向随意修改。

把 normalize 当作降低设计债务的工具

normalize 最有价值的使用方式，通常是反复应用在那些容易持续漂移的区域：老路由、刚上线的新功能，或被多人频繁修改过的界面。把它当作一个有针对性的设计债务治理工具，而不是一次性的美化器。

通过明确不可变约束来提升输出

要告诉技能哪些东西绝对不能动：

• 布局约束
• 业务逻辑
• 组件 API
• 无障碍要求
• 发布风险边界

这样可以帮助 normalize 把注意力集中在系统对齐上，而不是越界改写无关部分。