admin
d9445b5888
- oil-ui-pro 升到 0.22.2：references 13→28 份（新增 16、删 imagery.md）、assets 增 cards/（22 组）与 fonts/、SKILL.md 顶层五步结构未改名。 - 升级路径：官方 `npx github:oil-oil/oil-cli update` 稳定失败（error=replace、报「检查目录权限」）。 真身为 EXDEV —— 解压在 os.tmpdir()（C 盘）、技能目录在 E 盘，Windows 上 rename 不能跨盘； CLI 的 catch 把非 CliError 原生异常一律兜底成 replaceFailed，真错误一个字不吐。 做法＝借其 prepare() 只做下载+校验，再 cp 到同盘 stage、rename 交换；官方命令复验 up_to_date。 - 回归：product-planning 按名引用的 visual-review.md／tools.md／design-direction.md／style-explorer.md 全部健在；命名闸门 2061｜0｜27。 - session-mechanism/references/pitfalls.md 新增 P0-98（含通则：更新器把原生错误兜底成指错方向的人话）。
186 lines
16 KiB
Markdown
186 lines
16 KiB
Markdown
# 存量项目
|
|
|
|
## 目录导航
|
|
|
|
- [先分清意图](#先分清意图)
|
|
- [先摸清现状](#先摸清现状)
|
|
- [优化 UI](#优化-ui)
|
|
- [改流程与加新功能](#改流程与加新功能)
|
|
- [各类改动怎样评审](#各类改动怎样评审)
|
|
- [从源头修改](#从源头修改)
|
|
- [设计规范文件](#设计规范文件)
|
|
- [验证](#验证)
|
|
|
|
在已有仓库里改界面，先分清用户要什么。优化 UI、改流程、加新功能，要改的东西和要锁住的东西正好相反：优化 UI 改的是视觉语言，流程和功能沿用；改流程和加新功能改的是做法，视觉沿用。
|
|
|
|
## 先分清意图
|
|
|
|
| 用户想要 | 常见说法 | 要改的东西 | 锁住的东西 | 多个方案差在哪 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 优化 UI | 不好看、太土、不统一、想更高级 | 层级、字体关系、色彩比例、密度、组件的样子 | 品牌资产，以及用户点名保留的部分 | 推翻现状的程度，见“优化 UI” |
|
|
| 改流程 | 难用、步骤多、找不到、老出错 | 入口、步骤、承载方式、状态的表达 | 视觉沿用现有系统 | 做法，见 [改流程与加新功能](existing-project-workflow.md) |
|
|
| 加新功能 | 加一个……、新做一页 | 新功能的做法 | 视觉沿用现有系统 | 做法，见 [改流程与加新功能](existing-project-workflow.md) |
|
|
|
|
从请求推断意图，推断不出来时问一句。一个请求同时包含几种意图时，先定流程，再定视觉：流程决定页面上有什么，视觉决定它们长什么样。流程方案选定后，视觉的几个方案都建在这个流程上；最初的基线截图留着，做最后的前后对比。
|
|
|
|
动手前在设计说明开头写一行：这次是哪种意图、优化 UI 时取哪一档、现在处在哪个阶段。后面选检查和评审规则时，以这一行为准，不套用新界面的流程。
|
|
|
|
改流程和加新功能时，现有视觉即使不够好，也照样沿用；发现的视觉问题单独列出，交给用户决定要不要另做一次优化 UI。
|
|
|
|
## 先摸清现状
|
|
|
|
只看和这次改动有关的范围，不通读整个项目：
|
|
|
|
- **设计规范文件**：先找项目根目录和 docs 里写界面视觉的 `DESIGN.md`、`design.md` 或同类文档，有就按下面“设计规范文件”一节的“读”来用。
|
|
- **新旧并存**：设计规范文件没写明时，有的页面已经换了新样式表或新组件、其他页面还是旧的，说明迁移做到一半。用 git 记录看哪套更新，跟随更新的那套，在交付说明里写明依据；拿不准时问用户。不要把旧的那套当成现有视觉语言。
|
|
- **组件和同类页面**：已有哪些组件，同类任务在别的页面是怎么做的，哪些做对了可以沿用，哪些本身就是问题。
|
|
- **项目自己的门槛**：先看仓库的检查脚本和规范，例如动效只能用哪些时长变量、文案键怎样写才能通过 i18n 检查、各页面的性能预算、组件交付要声明哪些依赖。设计实现从第一行就按这些规则写，不要做完再返工。
|
|
- **基线截图**：改动前，在目标视口截下相关页面和关键状态，包括空数据、加载、错误和长内容，存到任务目录。之后的前后对比用同样的视口、数据和状态。
|
|
|
|
优化 UI 时再看两项：
|
|
|
|
- **设计变量**：颜色、字号、间距、圆角、阴影和动效定义在哪里，页面实际用的是变量还是硬编码。
|
|
- **实际取值**：搜索相关页面和组件里的颜色、圆角、字号，统计各有多少种。常见结果是十几种灰、七种圆角、三套按钮。
|
|
|
|
## 优化 UI
|
|
|
|
### 规范体检
|
|
|
|
动手前先判断现有规范值不值得当标准。用方向卡的格式给现状写一张卡：调性、字体、色彩、密度、图标、动效。逐项标出它是品牌资产，还是偶然形成的默认值：
|
|
|
|
- **品牌资产**：标志、主色、品牌字体、专有插画，以及用户说要保留的。默认不动。
|
|
- **偶然的默认值**：组件库默认的灰阶和圆角、默认图标库、随手定的字号和间距、没人决定过的阴影。可以重新决定。
|
|
|
|
再给规范下结论：
|
|
|
|
- **规范是好的，页面没做到位。** 现有规范就是标准：整理照着它修，升级和重塑也保留它的品牌资产。
|
|
- **规范本身平庸或混乱。** 偶然的默认值都可以重新决定，目标是给这个产品建立一套更好的规范。
|
|
- **拿不准。** 把现状截图和同品类最好的两三个产品放在一起看，差距明显就按规范本身有问题处理。
|
|
|
|
结论和理由写进设计说明，后面的评审以它为准。
|
|
|
|
### 推翻程度
|
|
|
|
| 档位 | 改什么 | 留什么 |
|
|
| --- | --- | --- |
|
|
| 整理 | 把混乱的视觉值收拢成少数语义角色，统一同类组件，修层级、对齐和留白 | 品牌、结构和现有的视觉气质 |
|
|
| 升级 | 重新决定字体关系、色彩比例、密度、组件的样子和图标 | 品牌资产、页面结构和全局导航 |
|
|
| 重塑 | 按 [设计方向](design-direction.md) 重新探索，结构也可以变 | 品牌资产 |
|
|
|
|
先问一个问题：**这一页改了样子，别的页面要不要跟着改？**
|
|
|
|
- **要跟着改**：账户页、设置页、订单列表这类页面，和其他页面共用顶栏、组件和字体，只改其中一页就会和别的页面不搭。
|
|
- **不用跟着改**：落地页、活动页、单页官网这类页面，自己就能定样子，改了也不牵连别的页面。
|
|
|
|
然后按下面的顺序决定做哪几档，前一条成立就不看后一条：
|
|
|
|
1. **用户说了改多少**，按用户说的做。只说小改、别大改的，按 [整理已有页面](existing-polish.md) 做。
|
|
2. **设计规范文件里已有用户确认的规范，用户这次也没要求重新探索**，列在待迁移里的页面按规范迁移，其他页面在规范内整理，不再出三档；规范不够用时补进文件，交付时说明。之后按“给已有界面评审”看一轮，标准是这份文件。
|
|
3. **范围是整个产品，或者是一个不用跟着改的页面**，三档各出一个方案，和现状一起放进对比页，让用户直接看到改到哪一步是什么样。动手之前先按 SKILL.md 步骤 1 的“先用文字问一次”把它们写给用户，用户从文字里定得下来就只做选中的那一个。规范体检认为现有规范是好的，升级和重塑也照出，只是都保留品牌资产。
|
|
4. **范围是一个要跟着改的页面、一个组件或一处区域**，只做整理，按 [整理已有页面](existing-polish.md) 先诊断、再确认、再改：在现有的视觉语言里重排布局和层级，不换字体、色彩和组件的样子。体检认为规范本身有问题时，在交付说明里写明升级或重塑会连带改到哪些页面，问用户要不要把范围扩大。
|
|
|
|
范围是整个产品时，升级和重塑的方案要能推广出去：写明换掉的字体、颜色和组件会影响哪些页面，并拿至少一个其他页面检查新规范放上去是否成立。产品里任何地方都没有出现过的字体和颜色，只在重塑档里引入。
|
|
|
|
三档之间按推翻程度比较，不套用设计方向里的差异检验：整理和升级本来就和现状共享结构，这是档位决定的。只有重塑一档里探索多个视觉方向时，才用设计方向的差异检验。
|
|
|
|
各档要写的东西不同，不要每档都填完整的方向卡：
|
|
|
|
- **整理**：不写方向卡，按 [整理已有页面](existing-polish.md) 写诊断和确认结果；要收拢的视觉值和组件，写清各自收到哪个语义角色。
|
|
- **升级**：只写北极星、字体、色彩和记忆点四项，从这个产品的品类和内容里推出来，不是把组件库默认样式换成另一套默认样式。
|
|
- **重塑**：按设计方向走完整流程，写完整的方向卡，默认保留品牌资产，除非用户要求更换。三档并排给用户挑时，重塑只放一个代表方案；用户选了重塑，再按 SKILL.md 步骤 1 出三个方向。
|
|
|
|
选定以后，新规范先落到共享的设计变量和组件上，在一个代表性页面上做完整、确认，再逐页迁移，不一次重写所有页面。之后的评审以新规范为标准。代表性页面做完后，按下面的“设计规范文件”把选定的规范写进项目。
|
|
|
|
## 改流程与加新功能
|
|
|
|
改的是做法与结构，现有视觉系统严格沿用。先亲手走一遍并计数，再在“顺手、自动、专用”三种立场里出方案（动手之前先按 SKILL.md 步骤 1 的“先用文字问一次”把它们写给用户，用户从文字里定得下来就只做选中的那一个），放进对比页，按任务走查评审，不打视觉分。完整流程见 [改流程与加新功能](existing-project-workflow.md)。
|
|
|
|
## 各类改动怎样评审
|
|
|
|
| 改动 | 交给用户挑选之前 | 选定并做完之后 | 打分 |
|
|
| --- | --- | --- | --- |
|
|
| 整理 | 不派评审者，主 Agent 和基线做前后对比 | 润色了一整页以上时，按 [视觉评审协议](visual-review.md) 的“给已有界面评审”看一轮，标准是现有规范 | 不打分 |
|
|
| 升级 | 不派评审者 | 按“给已有界面评审”看一轮，标准是选定的新规范 | 不打分 |
|
|
| 重塑 | 不派评审者 | 按步骤 4 的评分循环，目标 9 分 | 打分 |
|
|
| 改流程、加新功能 | 主 Agent 自己走一遍；推荐一轮 [评审循环](review-loop.md) 的“评审改流程和加新功能的方案”，由用户决定 | 再走一遍，在计数表里加一行；视觉按“给已有界面评审”，润色一整页以上才做 | 不打分 |
|
|
|
|
三档放在同一个对比页里给用户挑时，挑选前都不派评审者；用户选了哪一档，之后按哪一档那一行做。改流程与加新功能的方案评审细节见 [改流程与加新功能](existing-project-workflow.md)。
|
|
|
|
## 从源头修改
|
|
|
|
改样式之前按顺序检查：
|
|
|
|
1. 项目里是否已有同样含义的组件、变量或样式；
|
|
2. 页面是不是用错了组件；
|
|
3. 父布局给的尺寸、对齐或定位是否有错；
|
|
4. 组件默认样式或状态逻辑是否有错；
|
|
5. 已有的组件变体够不够用；
|
|
6. 是否真有稳定重复的职责，需要一个新的共享实现。
|
|
|
|
前几步没查完，不新增组件、变体或样式。
|
|
|
|
- **修共享，不覆盖实例。** 不用 `!important`，不用页面专属选择器侵入组件内部，不用任意数值绕过变量。
|
|
- **变体要有稳定含义。** 新变体按用途命名，例如 `destructive`、`compact`，不按页面或视觉结果命名，例如 `orders-blue`；至少有两个使用位置，或者属于组件的公共状态。
|
|
- **先查使用位置。** 改共享组件、变量或样式前，搜出所有使用位置；每种不同的用法各抽一处验证。
|
|
- **接管后删旧的。** 新实现接管后，迁移所有使用位置，删掉旧组件、旧样式和失效的选择器。做不完时写清剩下哪些位置，不长期保留两套实现。
|
|
- **收敛视觉值。** 把十几种灰映射到正文、次要文字、边框、表面这类少数语义角色：先改变量，再批量替换，最后删掉孤立的值。
|
|
- **动效先沿用。** 先用项目已有的时长和缓动；项目没有时才按 [动效](motion.md) 确定，并收成变量。
|
|
- **展示内容先按需加载。** 文档页、组件目录这类一页里放很多真实组件的页面，首屏以下的示例和样张在滚动到附近时再加载，别让每一页都背上所有示例的脚本。项目有性能预算时，先这样压下去，剩下确实属于新功能的增量再上调基线，并写明原因。
|
|
- **不顺手改业务逻辑。** 逻辑确实造成了界面问题，例如重复请求、状态不同步，单独指出并说明改动范围。
|
|
|
|
## 设计规范文件
|
|
|
|
优化 UI 常常一次做不完：先改一个代表性页面，再分几次对话逐页迁移。下一次对话面对的是一半新、一半旧的页面，分不清哪套是标准，用户说过的喜好也丢了。所以选定的规范写进项目根目录的 `DESIGN.md`，后来的对话和不走本 Skill 的改动都能读到。
|
|
|
|
- **读**：用户确认的条目不推翻，样板页面就是视觉标准，取值以样板页面和共享变量的代码为准；Agent 推断的条目和文档没写到的部分，规范体检照常评估。没标来源的旧条目按用户确认对待。用户这次明确要求重新探索或重塑时，文档只当现状参照，不锁定方案，品牌资产照样保留。
|
|
- **什么时候写**：用户在对比页上选定、或明确说了要哪种之后，做完代表性页面再写；用户之后又给了取舍，随时补上；按规范迁移完一页，更新样板页面和待迁移。小改动、单个组件和只评审时只读不写。
|
|
- **只写确认过的方向**：方向和用户取舍只写用户确认过的；其他条目可以直接补，标 Agent 推断，交付时列出来请用户确认。还没有用户确认过的方向时，例如无人值守时自己定的，不新建这个文件，草稿放任务目录。
|
|
- **放在哪**：项目已有设计文档时，在原文件里改，不另建、不换原有结构；新写的条目照样标来源，缺品牌资产就补一节。没有才新建 `DESIGN.md`。它是项目文件，和任务目录里记过程的设计说明分开；用户明确不让往项目里写文档时，放任务目录并说明。
|
|
- **写法**：只写决定，不写取值统计和排查经过。每条写成能检查的说法：写“表格里的金额右对齐”，不写“表格更整齐”；用户的话含糊时，翻成这样的规则，标 Agent 推断。每条标“用户确认”或“Agent 推断”。篇幅控制在 100 行左右。
|
|
- **入口**：要不要在 AGENTS.md、CLAUDE.md 里加一行指向它，交付时问用户，不自己加。
|
|
|
|
骨架如下，尖括号换成实际内容。品牌资产一节必写，其他用不上的节删掉：
|
|
|
|
```markdown
|
|
# <产品名> 设计规范
|
|
|
|
更新：<日期>
|
|
|
|
## 方向
|
|
<一个具体的参照物，一两句；不写形容词>
|
|
|
|
## 品牌资产（不动）
|
|
- <标志、主色、品牌字体、专有插画>（用户确认）
|
|
|
|
## 语义角色
|
|
变量在 `<文件路径>`，这里只写每个角色用在哪，不抄取值。
|
|
- `--<变量>`：<用途和限制，例如“只用于主按钮和当前位置”>
|
|
- 字体：<标题、正文、数字各用哪个变量，字重怎么分层>
|
|
- 形状：<圆角、边框、阴影的规则>
|
|
- 动效：<时长和缓动变量>
|
|
|
|
## 可用组件
|
|
- `<组件、类名或样式文件>`：<用途>。新页面先用这些，不另画一套。
|
|
|
|
## 样板页面
|
|
- `<路径>`：已完全按本规范完成，取值和组件以它的代码为准。
|
|
|
|
## 用户取舍
|
|
- <日期>：<选了什么；喜欢和不喜欢的，各写成能检查的一条>（用户确认）
|
|
|
|
## 不要做
|
|
- <这个产品专属的禁忌>
|
|
|
|
## 待迁移
|
|
- `<路径>`：还是旧样式。全部迁完后删掉这一节。
|
|
```
|
|
|
|
## 验证
|
|
|
|
- 和基线在同一视口、同样数据和状态下做前后对比截图。
|
|
- 被改动的共享组件，在其他使用位置各看一处。
|
|
- 规范体检列出的品牌资产仍在产品里：标志可以按 [工作区骨架](direction-workspace.md) 的“顶栏放什么”挪位置或缩小，不能删掉或换掉。
|
|
- 评审按上面“各类改动怎样评审”的表。优化 UI 的标准是设计规范文件；没有文件或文件没写到的部分，按规范体检的结论：规范是好的就按现有规范，重新建立了规范就按选定的新规范。
|
|
- 改流程和加新功能，走一遍主要任务，和走查时的四个数并排对比；保存类操作要重新读取确认。
|
|
- 项目自带的检查按 SKILL.md 第 5 步的范围跑，不为一次视觉修改新建测试体系。
|