workbuddy_skills/oil-ui-pro/references/existing-project.md

存量项目

在已有仓库里改界面，先分清用户要什么。优化 UI、改流程、加新功能，要改的东西和要锁住的东西正好相反：优化 UI 改的是视觉语言，流程和功能沿用；改流程和加新功能改的是做法，视觉沿用。弄混了，要么在一个本来就平庸的系统上修修补补，要么三个方案只是同一条流程换了皮。

先分清意图

用户想要	常见说法	要改的东西	锁住的东西	多个方案差在哪
优化 UI	不好看、太土、不统一、想更高级	层级、字体关系、色彩比例、密度、组件的样子	品牌资产，以及用户点名保留的部分	推翻现状的程度，见“优化 UI”
改流程	难用、步骤多、找不到、老出错	入口、步骤、承载方式、状态的表达	视觉沿用现有系统	做法，见“改流程与加新功能”
加新功能	加一个……、新做一页	新功能的做法	视觉沿用现有系统	做法，见“改流程与加新功能”

从请求推断意图，推断不出来时问一句。一个请求同时包含几种意图时，先定流程，再定视觉：流程决定页面上有什么，视觉决定它们长什么样。流程方案选定后，视觉的几个方案都建在这个流程上；最初的基线截图留着，做最后的前后对比。

动手前在设计说明开头写一行：这次是哪种意图、优化 UI 时取哪一档、现在处在哪个阶段。后面选检查和评审规则时，以这一行为准，不套用新界面的流程。

改流程和加新功能时，现有视觉即使不够好，也照样沿用；发现的视觉问题单独列出，交给用户决定要不要另做一次优化 UI。

先摸清现状

只看和这次改动有关的范围，不通读整个项目：

• 组件和同类页面：已有哪些组件，同类任务在别的页面是怎么做的，哪些做对了可以沿用，哪些本身就是问题。
• 项目自己的门槛：先看仓库的检查脚本和规范，例如动效只能用哪些时长变量、文案键怎样写才能通过 i18n 检查、各页面的性能预算、组件交付要声明哪些依赖。设计实现从第一行就按这些规则写，不要做完再返工。
• 基线截图：改动前，在目标视口截下相关页面和关键状态，包括空数据、加载、错误和长内容，存到任务目录。之后的前后对比用同样的视口、数据和状态。

优化 UI 时再看两项：

• 设计变量：颜色、字号、间距、圆角、阴影和动效定义在哪里，页面实际用的是变量还是硬编码。
• 实际取值：搜索相关页面和组件里的颜色、圆角、字号，统计各有多少种。常见结果是十几种灰、七种圆角、三套按钮。

优化 UI

规范体检

动手前先判断现有规范值不值得当标准。用方向卡的格式给现状写一张卡：调性、字体、色彩、密度、图标、动效。逐项标出它是品牌资产，还是偶然形成的默认值：

• 品牌资产：标志、主色、品牌字体、专有插画，以及用户说要保留的。默认不动。
• 偶然的默认值：组件库默认的灰阶和圆角、默认图标库、随手定的字号和间距、没人决定过的阴影。可以重新决定。

再给规范下结论：

• 规范是好的，页面没做到位。 现有规范就是标准：整理照着它修，升级和重塑也保留它的品牌资产。
• 规范本身平庸或混乱。 偶然的默认值都可以重新决定，目标是给这个产品建立一套更好的规范。
• 拿不准。 把现状截图和同品类最好的两三个产品放在一起看，差距明显就按规范本身有问题处理。

结论和理由写进设计说明，后面的评审以它为准。

推翻程度

档位	改什么	留什么
整理	把混乱的视觉值收拢成少数语义角色，统一同类组件，修层级、对齐和留白	品牌、结构和现有的视觉气质
升级	重新决定字体关系、色彩比例、密度、组件的样子和图标	品牌资产、页面结构和全局导航
重塑	按 设计方向 重新探索，结构也可以变	品牌资产

先问一个问题：这一页改了样子，别的页面要不要跟着改？

• 要跟着改：账户页、设置页、订单列表这类页面，和其他页面共用顶栏、组件和字体，只改其中一页就会和别的页面不搭。
• 不用跟着改：落地页、活动页、单页官网这类页面，自己就能定样子，改了也不牵连别的页面。

然后按下面的顺序决定做哪几档，前一条成立就不看后一条：

1. 用户说了改多少，按用户说的做。
2. 范围是整个产品，或者是一个不用跟着改的页面，三档各出一个方案，和现状一起放进对比页，让用户直接看到改到哪一步是什么样。规范体检认为现有规范是好的，升级和重塑也照出，只是都保留品牌资产。
3. 范围是一个要跟着改的页面、一个组件或一处区域，只做整理：在现有的视觉语言里重排布局和层级，不换字体、色彩和组件的样子。体检认为规范本身有问题时，在交付说明里写明升级或重塑会连带改到哪些页面，问用户要不要把范围扩大。

只做整理时，也把现状和整理后的版本放进对比页，交付时问一句要不要看看升级或重塑的样子；不改完就交，让用户连原来是什么样都看不到。

范围是整个产品时，升级和重塑的方案要能推广出去：写明换掉的字体、颜色和组件会影响哪些页面，并拿至少一个其他页面检查新规范放上去是否成立。产品里任何地方都没有出现过的字体和颜色，只在重塑档里引入。

三档之间按推翻程度比较，不套用设计方向里的差异检验：整理和升级本来就和现状共享结构，这是档位决定的。只有重塑一档里探索多个视觉方向时，才用设计方向的差异检验。

各档要写的东西不同，不要每档都填完整的方向卡：

• 整理：不写方向卡。列出要收拢的视觉值和要统一的组件，写清各自收到哪个语义角色。
• 升级：只写北极星、字体、色彩和记忆点四项，从这个产品的品类和内容里推出来，不是把组件库默认样式换成另一套默认样式。
• 重塑：按设计方向走完整流程，写完整的方向卡，默认保留品牌资产，除非用户要求更换。

选定以后，新规范先落到共享的设计变量和组件上，在一个代表性页面上做完整、确认，再逐页迁移，不一次重写所有页面。之后的评审以新规范为标准。

先用，再想

改流程和加新功能都从这里开始。存量项目的问题大多不在画面上，在流程里：看截图只能看出间距和颜色，要知道该改什么，先把任务亲手走一遍。

用用户的话写任务

动手前写一句话：用户是谁，来做什么，做完想拿到什么。只用用户自己的词，不出现界面上的名词。写“把上周没回复的客户标成待跟进”，不写“在列表里筛选并批量修改状态”。后面每一屏、每一步都拿这句话衡量：它让任务前进了，还是让用户在伺候界面。

写不出这句话，先问用户，不先看界面。

先定产出物

很多功能的结果是一样东西：一份清单、一个文件、一条消息、一页摘要。结果是一样东西时，先把它写出来，再想界面：

• 谁收到它，收到后要拿它做什么。收的是人，要一眼看懂；收的是系统或程序，要能直接用。
• 里面缺了什么就用不了。按收件方的需要列，不按界面上现成有什么列。
• 用户今天凑合时亲手带走的是什么。这是产出物的下限，新功能不能比它少。
• 产品里已经有、用户却得自己翻出来的东西，系统补进去。

把最好的那一份产出物直接写成样例，放在设计说明里。例如食谱应用的“生成购物清单”，样例就是一份真的清单：按超市货架分区、合并重复的食材、标出家里常备的。样例写不出来，或者和用户凑合的办法没有区别，先回来修产出物，不开方案。

产出物定好后，各个方案都交付同一份。方案之间差的是用户为它做多少、系统替他做多少，不是谁的产出物好一点。

走一遍，边走边数

用真实或脱敏后的数据，从用户实际的入口走到能看到的结果。按 视觉评审协议 的“任务走查”记下卡住、走错、犹豫和多余的步骤，同时数四个数，写进任务目录：

• 步数：到结果要几次点击、几次页面切换。
• 决定数：界面问了用户几个问题，其中几个系统其实已经知道答案。
• 记忆负担：有几样东西要从一屏带到另一屏，靠脑子记、复制粘贴或开两个标签。
• 回头路：出错或改主意时要退回几步，丢掉什么。

记成一张表，现状、理想路径和每个方案各占一行，后面每次计数都往这张表里加：

	点击	页面切换	决定（其中系统已知）	记忆负担	回头路	寻找与阅读
现状	8	6	6（1）	3 件作品和用途	刷新后重选筛选，丢掉候选	滚动两屏才找到第三件

点击和页面切换分开记，不相加；回头路写退回几步、丢了什么；滚动找了很久、读了很多才做出的决定，即使不算点击，也记在最后一列。表格上方写一行计数口径，例如键盘操作算不算点击。现状、理想路径和每个方案都用同一个任务、同一批数据和同一套口径来数，否则数字不能互相比较。

再走一遍坏路径：输入错、名称很长、数据为空、上千行、权限不足、中途离开再回来。存量项目最常见的问题都来自真实数据。

每处犹豫归为一类：不知道从哪开始，不知道点了会怎样，不知道成功没有，不知道怎么回去。

加新功能时没有现成流程可走，就走它旁边的现有流程，再走用户今天凑合的办法：复制粘贴、导出表格、在备注里打标记。凑合的办法证明需求存在，也往往指向最自然的入口。

写理想路径

这一步不能省。假设现有界面不存在：用户从说出意图到看到结果，最少要做几个决定，每个决定需要看到什么。把它和现状的步骤并排，多出来的每一步都是结构上的机会。

找问题，得到的往往是补丁；从结果往回推，得到的才是结构上的改法。

从现象找到原因

走查记下的是现象。每条往下问为什么，直到落进下面五种原因之一，每种原因都有自己的改法方向：

原因	怎么认出来	往哪改
做决定的地方没有做决定要用的信息	要开另一页、来回切换、靠记忆	把信息搬到做决定的地方：行内、侧面板、预览
功能长在用户不会去找的地方	犹豫发生在找入口；对象没有自己的家	搬到对象上，或搬到用户出发的地方
流程的形态和任务不匹配	一步能做完的拆成向导；可撤销的还要确认；几十条要逐条打开再退回	换骨架：队列、行内编辑、批量；去掉确认，改成可撤销。骨架见 设计方向 的“产品界面”
系统知道的事让用户再做一遍	要填系统已有的值；要选只有一个合理答案的选项；要手动触发每次都做的事	预填、给默认值、自动执行并可撤销
状态看不见	做完没有变化；进行中看不出来；出了错要自己去找	把状态做成对象上的属性，在列表里就能看到

间距、颜色、文案不在表里。它们是症状或精修项，记下来放到最后，不混进原因。

三个例子：

• 现象：给上周没回复的客户标“待跟进”，每条都要点进详情、改状态、返回，列表回到顶部，再重新找下一条。原因：用户在逐条处理，骨架却是“表格加详情页”，改状态被放在了详情里。补丁：记住滚动位置。结构上的改法：筛选“未回复”后在行上直接改状态；或者左边队列、右边详情，处理完自动跳到下一条；或者全选后一步批量标记。
• 现象：新建合同有 14 个字段，填到一半去查客户编号，回来表单空了。表面原因：没有草稿。根本原因：表单在要系统已经知道的东西；入口在顶级菜单“合同”，用户却是从某个客户出发想建合同的，客户信息在入口处就丢了。补丁：加草稿，加“编号在哪里找”的提示。结构上的改法：入口移到客户详情页，客户相关字段全部带出，只剩三四个真正要判断的字段，放在侧面板里，下面的客户信息仍然看得见。
• 现象：首页是四张指标卡，用户每天进来直接点“工单”菜单。原因：首页回答“总共有多少”，用户每天要知道的是“现在该处理什么”。补丁：给指标卡加趋势箭头。结构上的改法：首页就是待处理队列的前几条，最显眼的属性是已经等了多久；指标收成一行小字。

补丁自查

每条建议写完，过一遍下面五个问题，任何一个答不上来就是补丁：

• 它是在加一个东西（提示、引导、确认、说明文字、徽章、空状态插画），还是改掉或删掉一个东西？加东西之前，先回答界面为什么让人看不明白，那个答案才是真问题。
• 把根本原因修掉以后，它还需要存在吗？
• 改完之后，步数、要记住的事、要切换的页面，至少有一样变少了吗？
• 第十次用的人会被它打扰吗？引导和确认对熟手是负担。
• 能用用户的话说出改善吗：“现在不用再……”。

补丁可以做，单独列为“今天就能改”，不冒充方案。

不知道从哪改时

用户只说“优化一下这页”，没说哪里难用，就按这页的主要任务走一遍、写理想路径，把差距最大的三处按影响排好，每处写清用户能少做什么，附截图，交给用户挑。用户挑了再继续。

改流程与加新功能

走查、理想路径和产出物样例都写完之后，才开始想方案；还没看过现有代码和页面就定下的方案，只是在三种立场的格子里填空。

视觉全部沿用：同一套设计变量、组件、图标和动效，不换字体和主色，不另做控件。多个方案之间能看出差别的只有三件事：出现在哪里，要几步，谁在做事。产出物不在其中：它在“先定产出物”里定过一次，每个方案都交付同一份最好的。产品里没有现成的控件时，例如第一次出现输入框，单独列出，从现有控件的样子推出来：圆角、描边、字号、文字颜色，以及悬停、聚焦和出错的样子，都和现有的按钮、筛选和菜单一致。不用浏览器默认样式，也不随手写一套通用表单样式。

读出产品的习惯

新功能和新流程要像这个产品原来就有的。从现有界面读出下面几项，各写一行，后面每个方案都遵守：

• 对象：导航和列表第一列里的名词，就是用户认的东西。哪些有自己的列表页，哪些只在详情里出现。新功能是哪个对象上的事；要不要引入新对象，这是大决定，写出理由。
• 动作：按钮和菜单上的词，就是用户认的动作。新功能能不能用已有的动词说出来。
• 出发方向：用户是先找到对象再做事，还是先选动作再找对象。
• 节奏：一次处理一件还是批量；马上完成还是进后台任务。
• 承载：详情开新页面还是侧面板；编辑用弹窗还是行内。
• 反馈：成功后是原地高亮、角落提示还是跳转。

这些习惯默认沿用。打破某一条时，说出来自这个任务的理由。

再看两三家同类产品：这个功能长在哪里、要几步、系统替用户做了什么、用户最后拿到什么，各写一行。能上网就真的打开看；凭记忆写的，标明是记忆。只看这一个功能，不拆整个产品。

三种立场

每个方案先选一种立场，再在立场里把流程想完整：

立场	用户做什么	适合
顺手	在原来的地方多做一件事：行内、选中后、对象的操作菜单里，不新增页面和对象	简单、依附于现有对象、做完就走
自动	系统替用户做一个他本来要自己做的判断或整理，用户只看结果、改例外、撤销	规则明确、错了能撤回、每次做法都一样
专用	给这件事一个自己的地方：新页面、新面板或新工作区，相关信息和状态摊开	高频、步骤多、要连续处理或对照

三种立场是备选，不是配额。先问每种立场在这个任务里能不能写出一个站得住的做法，写得出几个做几个；凑不出就少做一个并说明理由，不把一种立场做成两个方案，也不把一种立场硬套成一个方案。

“自动”要说得出系统替用户判断了什么。把已有数据拼在一起、换个地方显示、少点一次，都不算自动。只有现有数据真的能支撑这个判断时才选它；数据和接口做不到，就不做这个方案。

立场只决定入口、流程的形态和承载方式；对象、动作的位置、组件和反馈方式，按上一节读出的习惯沿用。

方案卡

改流程和加新功能用这张卡代替设计方向里的方向卡，每项一两行：

字段	写什么
立场	顺手、自动或专用
入口	用户在哪里、看着什么时碰到它
步骤	从意图到结果，一行一步，旁边并排现状的步骤或理想路径
修了什么	对照“从现象找到原因”的表，修的是哪一条
拿到什么	这个方案交付的产出物和“先定产出物”里的样例一致；有增减时，写明多了什么、少了什么、为什么
值得	用用户的话写一句改善：“现在不用再……”或“现在能……”。写不出来，这个方案不值得做
出错时	失败后用户在哪里，什么被保留了
赌注	押的是用户的哪种习惯或场景
放弃什么	它做不好的场景

差异检验先看一样，再比两样。先看每个方案的产出物有没有达到样例，差一截就先补，否则几个方案都只是在给一份没用的东西找入口。再比入口是否不同、步数或系统替用户做的事是否不同；两个方案这两样都一样，就是同一个方案换了皮，换一种立场重做。

放进对比页

候选直接在项目里实现，不另写一套静态页：用独立路由或查询参数切换，例如在原地址后加 ?variant=b，每个方案都用真实的组件和数据。对比页用本地地址作为候选，现状作为基线放在第一位，交付时开发服务器开着，见 风格对比页。

用户要求先看方案、选定后再动代码时，不改业务路由和组件，在任务目录里做可操作的小样，用现有的设计变量和真实数据，见 风格对比页 的 "interactive": true。

对比页里每个候选只有一个画面，选三个方案差别最大的那一刻，通常是入口或关键的一步，不选结果页，结果页在各种做法下往往长得一样。功能的结果是一样东西时，另外把产出物样例原样放进对比页的说明，让用户看到他最后拿到的是什么。traits 写立场、入口和步数，让用户在卡片上就能比较做法；字体和色板三个方案填同一组现有的值。

评审

不打视觉分，不跑评分循环。交付对比页时推荐给用户的下一步，是下面这一轮方案评审，不是 SKILL.md 步骤 4 的视觉评审和多方向横向评审。给用户之前，自己按任务那句话把每个方案走一遍，记下卡住、走错和犹豫，写进对比页的说明。用户同意后，有隔离执行者时按 视觉评审协议 的“评审改流程和加新功能的方案”评一轮。

选定并实现后，再走一遍，在同一张表里加一行，和现状并排写进交付说明。各列都没有改善时，先查是不是只改了皮，回到“从现象找到原因”；改善体现在入口更容易找到、更少出错或更容易恢复时，用卡住、走错、犹豫次数的变化说明；只减少出错、没有减少步骤和记忆负担的改动，写明它防的是哪种错，归为防错，不当作结构上的改法。视觉上只按“给已有界面评审”看一轮，润色了一整页以上才做。

计数表只量路程，不量结果。另写一行：拿到产出物的人能不能不加工直接用；不能，先修产出物，再谈步数。

各类改动怎样评审

改动	交给用户挑选之前	选定并做完之后	打分
整理	不派评审者，主 Agent 和基线做前后对比	润色了一整页以上时，按 视觉评审协议 的“给已有界面评审”看一轮，标准是现有规范	不打分
升级	不派评审者	按“给已有界面评审”看一轮，标准是选定的新规范	不打分
重塑	按 SKILL.md 步骤 4 推荐一轮视觉评审，由用户决定	按步骤 4 的评分循环，目标 9 分	打分
改流程、加新功能	主 Agent 自己走一遍；推荐一轮“评审改流程和加新功能的方案”，由用户决定	再走一遍，在计数表里加一行；视觉按“给已有界面评审”，润色一整页以上才做	不打分

三档放在同一个对比页里给用户挑时，挑选前都不派评审者；用户选了哪一档，之后按哪一档那一行做。

这时读哪些参考

改流程和加新功能时，先用这几处：设计方向 的“产品界面：先定对象和工作区骨架”，交互与状态 的“先走通用户任务”“动作层级”“按范围表达状态”和“模型在交互上的默认做法”，布局与视口 的“选择承载方式”。

视觉语言 的“细节”和“模型默认审美自查”、设计方向的差异检验、三处基本动效，留到方案选定、开始精修时再用。太早拿出来，注意力会被圆角和线框占满。例外是方案里第一次出现的东西，例如新的输入框、面板或浮层：交给用户之前就按“细节”检查一遍，用户挑方案时看的就是画面。

从源头修改

改样式之前按顺序检查：

1. 项目里是否已有同样含义的组件、变量或样式；
2. 页面是不是用错了组件；
3. 父布局给的尺寸、对齐或定位是否有错；
4. 组件默认样式或状态逻辑是否有错；
5. 已有的组件变体够不够用；
6. 是否真有稳定重复的职责，需要一个新的共享实现。

前几步没查完，不新增组件、变体或样式。

• 修共享，不覆盖实例。 不用 !important，不用页面专属选择器侵入组件内部，不用任意数值绕过变量。
• 变体要有稳定含义。 新变体按用途命名，例如 destructive、compact，不按页面或视觉结果命名，例如 orders-blue；至少有两个使用位置，或者属于组件的公共状态。
• 先查使用位置。 改共享组件、变量或样式前，搜出所有使用位置；每种不同的用法各抽一处验证。
• 接管后删旧的。 新实现接管后，迁移所有使用位置，删掉旧组件、旧样式和失效的选择器。做不完时写清剩下哪些位置，不长期保留两套实现。
• 收敛视觉值。 把十几种灰映射到正文、次要文字、边框、表面这类少数语义角色：先改变量，再批量替换，最后删掉孤立的值。
• 动效先沿用。 先用项目已有的时长和缓动；项目没有时才按 动效 确定，并收成变量。
• 展示内容先按需加载。 文档页、组件目录这类一页里放很多真实组件的页面，首屏以下的示例和样张在滚动到附近时再加载，别让每一页都背上所有示例的脚本。项目有性能预算时，先这样压下去，剩下确实属于新功能的增量再上调基线，并写明原因。
• 不顺手改业务逻辑。 逻辑确实造成了界面问题，例如重复请求、状态不同步，单独指出并说明改动范围。

验证

• 和基线在同一视口、同样数据和状态下做前后对比截图。
• 被改动的共享组件，在其他使用位置各看一处。
• 优化 UI 润色了一整页以上时，按 视觉评审协议 的“给已有界面评审”看一轮，标准是规范体检的结论：规范是好的就按现有规范，重新建立了规范就按选定的新规范。
• 改流程和加新功能，走一遍主要任务，和走查时的四个数并排对比；保存类操作要重新读取确认。
• 运行项目已有的类型检查、测试和构建；不为一次视觉修改新建测试体系。