补入 oil-ui-pro（上一提交按授权清空时移出，本轮按用户要求加回）

oil-ui-pro/references/component.md

@@ -0,0 +1,77 @@
+# 组件
+
+用户要把一个组件做到极致时，力气全部集中在这一个对象上：它放大看也经得起，用起来有手感，放进任何产品都认得出。页面上的方法照常有效，但流程不同：方向少做，深度多做。把组件当成一个小页面，三个方向平均用力、各做一遍完整验收，结果往往是三个能用却都不出彩的组件。
+
+本文的例子来自不同品类，只示意要具体到什么程度，不是模板。主视觉、母题、尺和状态的样子，每次都从当前产品里推出来；做出来和某个例子很像时，先问这是不是来自这个产品。
+
+## 先写它回答的那个问题
+
+用一句话写下用户看这个组件时最想知道或最想做的一件事，用用户的话写。例如行李追踪组件是“我的箱子到哪了”，不是“显示物流状态”。这句话决定谁是主角。
+
+再写组件的构成，每项一两行：
+
+- **主角**：用户最怕错过、会随时间变化的那个量，例如还要等多久、还剩多少。它在组件里最大、最先被看到。
+- **陪衬**：判断主角需要的其他信息，越少越好。
+- **主操作**：只有一个。写清它的手感：拖、按、长按还是滑；拖动时会不会吸附到常用值。
+- **状态**：列全。还没开始、进行中、暂停、计划中、完成、出错、极端值（0、满、超长名称），以及加载中。每个状态都要有画面，不能只做默认状态。状态的变化要落在主视觉上，例如洗碗机组件里，洗完时水汽散去、门缝亮起，故障时出问题的那根管道断开变红；只换标题文字和一个小圆点，等于主视觉没有参与。每个状态写明改主视觉的哪一层、改成什么样，三层见下一节。
+- **容器**：它会出现在哪些尺寸里，例如整页卡片、小组件、通知栏。没要求时只做一种。
+
+## 先定主视觉，再画组件
+
+组件也需要一个视觉主角，不能只靠文字、数字和进度条撑起来。按顺序找：
+
+1. **实物**：组件背后有实物时，用它的写实渲染或产品照片，例如耳机、行李箱、相机、一盆植物。透明底，角度和光线按组件的版式定。组件的主色从实物里取：外壳、配件或内容里最认得出的那种颜色。实物只有银灰黑白时，可以把颜色交给一个会亮的部位，例如耳机的状态灯、相机的录制点，并让它随状态变化。生成提示词里写明这个颜色和这个部位。组件本体里，主视觉要么完整放下，要么明确设计成出血到组件边缘，不能被容器随意切掉一角；跨出边界的效果只用在作品图里。
+2. **数据画成的量**：没有实物时，把主角画成看得见的量，例如一格代表一分钟的网格、填满的长度、范围圈。见 [设计方向](design-direction.md) 的“让人记住的一刻”。
+
+需要的图先按 [配图](imagery.md) 生成或选好，再围绕它排版。组件的颜色从这张图里取两三种：主色是图里最有辨识度的颜色，其余靠黑白灰。先定色板再去配图，图和界面会像两样东西。
+
+主视觉分三层，生成图之前先分好：
+
+- **照片层**：实物本身。状态需要实物变化时，例如耳机戴上和收进盒子、箱子合上和打开，用同一张图改提示词生成几个变体，角度、光向和大小完全一致；代码只切换图片。提示词写法见 [配图](imagery.md)。
+- **画在上面的层**：用代码画的线、量和标注，贴在实物对应的部位：降噪强度画成从耳罩向外扩散的声波，温度标在出问题的那个零件旁，剩余量沿容器的液面走。它随数据实时变，是状态变化的主要落点。
+- **背景层**：组件底色和实物身后的光。例如等待中光线变暗，出错时光熄掉，完成时亮起。这是状态的意思，不是装饰。
+
+一个量只画一条尺。主视觉上表示主角的那条线、那圈格子，就是主操作的控件：目标直接拖在它上面，当前值和目标在同一条尺上，拖动时实物随之变化。主视觉下面再放一个滑块或一排刻度，就是把同一件事画了两遍，删掉其中一条。常用值做成尺上的刻度和吸附点，标上名字，例如降噪强度上的“通勤”“专注”；不另做一排快捷按钮。
+
+同一个信息在组件里只出现一次。做完默认状态后列一张表：每个数字一行，写它出现在哪几处；文字、图形、控件上显示的值都算。出现两次以上，删到只剩最有力的那一处。目标值写在标题里、显示在滑块旁、又是快捷按钮的名字，就是三次。
+
+所有状态并排后做一次遮字测试：把文字和数字全部遮掉或模糊，再看这张图。还分得出哪个在进行、哪个出错、哪个已完成，主视觉才算参与了状态；分不出来，回到三层里改画在上面的层和背景层，不靠加文字解决。
+
+再定一个母题：一种从产品里来的图形，例如刻度、波形、点阵、等高线，从主视觉一路用到进度、加载、按钮按下和空状态。一个组件里只用一种母题。母题同时决定控件的形状：圆滚滚的毛绒玩具推出胶囊形的按钮和柱子，海报和硬照推出直角的按钮和图片，刻度推出细线和等宽数字。写下主按钮、次要开关和底部那行小字各自怎样带上母题；带不上的，先问能不能删。下半部分退回组件库默认的按钮和开关，整个组件就只有上半部分是设计。
+
+大数字是组件的脸。给它选一款有性格的数字字体，用等宽数字，不用系统默认字体；标签用另一款安静的字。两款够了。
+
+## 方向少做，深度多做
+
+1. **先出两三张草图。** 只做默认状态的静态画面，不写交互、不取证。草图之间在主视觉、母题和主操作的手感上不同，不是同一个布局换颜色。放进 [风格对比页](style-explorer.md) 给用户挑；用户让你自己决定时，选最有辨识度、又最能回答那个问题的一张，写下理由。
+2. **选定后只深化这一个。** 把所有状态做完，主操作做出完整的手感，再按下面的轮次打磨。其他草图不再深化。
+
+## 把一处做到极致
+
+组件的记忆点通常在主操作发生的那一刻。逐项想清楚，写进设计说明：
+
+- **跟手**：拖动时，被拖的东西和手指之间没有延迟；跟着变化的数字、颜色、主视觉同步变化，不等松手。
+- **阻尼和吸附**：经过常用值（例如 80%、100%）时有一次轻微的停顿，松手后吸附过去；拖过头会被拉回来。
+- **结果当场发生**：调了目标，主视觉跟着变，例如声波随降噪强度收拢或扩散，而不是只改一个数字。
+- **数字的变化**：数字滚动到新值，不是跳过去；等宽数字，单位比数字小一级、基线对齐。
+- **状态之间的过渡**：从发生变化的地方出发，例如开始时从实物上发生变化的那个部位出发，完成时最后一格亮起。
+
+动效的时长和曲线见 [动效](motion.md)。只在主操作和关键状态切换上用力，其余保持安静。
+
+## 打磨轮次
+
+截图、状态并排图、遮字图和录屏用 [工具](tools.md) 里的截图工具一次出齐。派评审之前自己先看一遍证据：默认状态已经加载完，遮字图保留了图形，慢放帧里没有上一个状态的残影，200% 图截的是组件而不是整页。证据有错先重截，不算一轮。
+
+深化后的组件按轮次打磨：截图、评审、修改。每轮给评审者这些东西：组件 200% 放大的截图；所有状态并排的图两份，一份原样，一份遮掉全部文字和数字；主操作 5 秒左右的录屏。评审任务：
+
+> 评审这一个组件，不评审页面。先说出用户第一眼看到的主角是什么，是不是那句“它回答的问题”里的答案。再拿这个品类里最有名的两三个产品做对照，说出这个组件和它们不同在哪；遮住名字后认不出是谁家的，就直接指出来。数一遍同一个信息在组件里出现了几次，出现两次以上的指出来。看所有状态并排的那张图：状态之间除了文字，主视觉有没有变化。然后按“这个品类里最好的组件”的标准，指出放大以后最露怯的三处细节：对齐、标签和图形压在一起、数字排版、阴影和描边、状态之间不一致。再说主操作的手感：跟手吗，有没有吸附和阻尼，结果有没有当场发生在主视觉上。最后回答：有没有一个瞬间值得截图分享；没有的话，最有希望的是哪一处，怎么做。每条写清位置、观察和调整方向。按 10 分制打分；以下任一成立，总分不高于 7：遮字后分不出各个状态；同一个数字出现三次以上；主操作的控件不在主视觉上，而是另画了一条尺；遮住名字后说不出它和品类里常见产品的区别。只提供评审，不修改文件。
+
+目标 9 分，默认最多三轮；分数连续两轮没有提升时停止。每轮只改评审指出的问题和主操作的手感，不换方向。
+
+## 交付
+
+- **组件本体**：能运行、能操作，所有状态可以切换查看，例如用一排状态按钮或键盘切换，切换控件放在组件外面。
+- **作品图**：组件放大两倍，放在从主视觉取色的背景上；背景从主视觉取色，选和组件形成清楚对比的那一档。实物另放一份在组件外面，比组件里的大三到五倍，压住组件的一条边或一个角，再被画布边缘切掉一部分；一张图里放一两个，不围一圈。可以再出一张：把组件的一处局部推近，画面旋转十到十五度，只看母题和细节。这些只用来展示，界面本身不需要这样。
+- **一段录屏**：主操作从开始到结果出现，5 到 8 秒。
+
+验收证据只给选定的那一个：所有状态各一张截图、200% 截图、主操作录屏。草图阶段不取证。组件不做独立的任务走查，也不按 SKILL.md 步骤 4 另做评审；把时间留给打磨。

oil-ui-pro/references/design-direction.md

@@ -0,0 +1,248 @@
+# 设计方向
+
+模型不被推一把时，会给出让所有人都能接受的平均答案。“做得独特一点”“随机一点”推不动它，它只会换几处装饰。这里的方法都是在给模型一个具体的推力：先认清品类、看清同类最好的产品怎么做，再定调性、用生成引擎起方向，最后用可检验的规则逼出真正的差异。方向的目标是“这个品类里最好的团队会这样做，而且做出了这个产品自己的样子”；只是“和模型的默认不一样”还不够。高级感来自一套语言的完整和细节，不来自题材少见。
+
+本文件以方法为主，偶尔给的例子只示意要具体到什么程度，不是风格清单。方向里的题材、材质、场景、字体和配色，每次都从当前产品的内容、受众和使用场合里推出；想到的方向如果和常见的“网红风格”撞上，要能说出来自这个产品的理由，否则重选。
+
+## 认品类，拆标杆
+
+动手前先认清这是什么品类的产品，再看这个品类里做得最好的产品是怎么做的。这一步给出地板：用户已经习惯的结构，以及一线产品的完成度。后面的调性和生成引擎，是在这块地板之上找这个产品自己的东西。
+
+按三步做，每一步都写下来：
+
+1. **说出品类和标杆。** 这是什么品类的产品，例如“语言学习 App”“组件库官网”“项目管理工具”“作品画廊”。这个品类里风格最鲜明的两三家是谁。选风格最鲜明的，不一定是最有名的。
+2. **拆开其中一家。** 拆成 6–10 条看得见的要素，每条写两件事：它是什么样，它为什么这样做。按这几层去拆：控件的形状和手感、字体、颜色、图标和插画、状态与反馈、动效、文案语气、首屏放了什么。要拆到能照着做的程度。例如一款学习 App 是“按钮厚实，按下去会陷下去，答对时有夸张的弹跳”，理由是答题是核心动作，要给利用零碎时间的普通人手感上的回报；一款开发工具是“深色、行距紧、每种状态一个统一的图标、快捷键印在菜单上”，理由是工程师一天要在里面待好几个小时。拆出来只有“干净、留白、一种强调色”，说明没拆到位，换一家重拆。
+3. **决定留什么、换什么。** 拿本产品的受众、内容和使用场合逐条对照：理由同样成立的留下，理由不成立的换掉，换掉的部分由后面的生成引擎给出替代。结果写进方向卡的“标杆与取舍”。
+
+拆的时候分清三样东西：
+
+- **基线**：用户已经期待的结构，例如画廊里作品先行、筛选在顶部，商店里购物车在右上角。沿用它，用户不用重新学。
+- **套路**：这个品类人人都在用的默认版式。一轮方向里至少一个要打破它，见“差异检验”。
+- **撞脸**：字体、配色、主视觉和图标都和某个标杆一样，只换了名字。任何方向都不允许。
+
+检验方法：把一个按钮、一行列表、一个空状态或一次反馈单独拿出来，放进别的产品里，还能认出它属于这个产品。识别不一定靠形状和颜色，也可以靠密度、字体和动效的节奏；黑白方向同样能做到。
+
+## 先定调性，再求差异
+
+从产品的题材、受众、品牌语气和使用场合推出调性。用五个刻度描述，每个刻度都写出依据：
+
+| 刻度 | 两端 | 在画面上看什么 |
+| --- | --- | --- |
+| 能量 | 安静 ↔ 喧闹 | 饱和度、对比、元素是否碰撞 |
+| 完成度 | 粗粝 ↔ 精致 | 边缘处理、颗粒与噪点、对齐是否严格 |
+| 密度 | 疏 ↔ 密 | 留白尺度、叠层、网格纪律 |
+| 分量 | 轻 ↔ 重 | 字重、色块面积、阴影硬度 |
+| 严肃度 | 活泼 ↔ 庄重 | 圆角、插画语言、动效幅度 |
+
+例如“地下现场演出社区 → 喧闹、粗粝、密”，“冥想陪伴 → 安静、精致、疏”。两种都完全成立，失败的是没有依据的默认：
+
+- 证据指向喧闹粗粝，交付的却是米色卡片、柔和阴影和大留白。这是最常见的失败，设计被磨回了模型默认的“安静高级”。
+- 反过来，为了显得有趣，给一个本该安静的产品硬加颗粒、撕纸边和粗边框。
+
+证据已经锁定调性时，所有候选都留在这个调性里，在构图、色彩身份和主视觉上拉开差异。不要为了“平衡”放进一个安静极简的保底方案。只有证据确实模糊时，才让候选分布在不同调性上。
+
+### 模糊词必须翻译
+
+“高级、精致、克制、史诗、有文学感、简洁”不能当作设计理由。用户或你自己说出这类词时，先翻译成可观察的决定：
+
+| 模糊词 | 翻译成什么 |
+| --- | --- |
+| 高级 | 先说清是哪一种高级，再决定字体的对比、分隔的方式、间距的尺度和色相的数量。只说高级什么也没决定 |
+| 精致 | 公差：字距怎么调、对齐到几像素的网格、阴影最多几级、色相最多几种 |
+| 克制 | 饱和度预算，例如强调色不超过画面 10%；动效幅度上限；色相数量上限 |
+| 史诗 | 尺度：展示字多大、主图占多少面积、明暗对比多强 |
+| 文学感 | 字族的性格、行长、行高和配色，各取什么值 |
+| 粗糙 | 用哪些手段，各用到什么程度，例如错位多少像素、旋转多少度 |
+| 简洁 | 密度档位，以及删掉什么、为什么删。简洁是结果，不是指令 |
+
+翻译不出可观察决定的词，从理由里删掉。
+
+## 用生成引擎起方向
+
+每个方向都从一个具体的引擎出发，而不是从形容词出发。不同方向最好用不同的引擎：
+
+- **材质 × 环境**：一种材质放在一个具体的环境里，比如“湿陶土 × 午后的工作室”。由材质推出光照、深度、边缘的处理和动效的阻尼。
+- **一个具体场景**：一个有时间、地点和光线的场景，比如“凌晨两点的便利店”。由场景里的光线、声音、材料和节奏推出色彩、质感和动效速度。适合情绪型工具。
+- **角色原型**：给产品一个性格，比如“一丝不苟的档案管理员”，让性格决定字体、色彩和动作。
+- **一场设计运动或文化语法**：选一个和产品的题材、受众或地域有真实联系的设计运动或视觉传统，借用它的语法，而不是贴它的图案。
+- **其他领域的整套表现形式**：把另一个领域的媒介或器物的表达方式借过来，比如把行程做成一张登机牌。只借它最有辨识度的一两个手法，页面本身仍是原来的体裁；不把那个媒介的部件一件件搬来，那会变成道具堆砌。
+- **有意打破常规**：激进的非对称版式、不和谐的配色与字体、让人不安的留白，但整体仍然好看、功能完整。
+
+感受词从这个品牌出发，而不是从行业出发。“美味、温暖、有食欲”会把每个食品应用都推向橙色；“深夜治愈、独处、温柔”才属于某一个品牌。行业惯用色可以用，前提是理由来自这个品牌；如果理由只是“这个行业都这么用”，就换掉。
+
+写方向卡之前，先在心里把方向想厚：用起来是什么感觉，让人联想到什么表面和物件，页面怎样流转，在讨好哪一类人。卡片是从这些思考里提炼出来的。跳过这一步，卡片只剩三十个字的空壳，后面做出的页面也会是平的。
+
+随机种子也是一种引擎：让脚本生成一串随机字符，从中联想配色、布局和字体，种子不进入界面。它适合陷入重复时破局，但不如上面几种引擎可解释。
+
+## 先定首屏骨架，再写文案
+
+**先回答一个问题：用户来首屏是看什么、做什么？**
+
+- **来看内容、挑东西或处理对象的页面**，例如画廊、商店、信息流、文档、作品集、工具和后台：首屏就是第一排内容本身。导航、标题和筛选合起来不超过一两行，第一排内容要完整出现在首屏。不放首屏口号，也不放解释这个页面是干什么的段落。下面的骨架表不用于这类页面；它们按“产品界面”一节定工作区骨架。
+- **来听一句话、看一张画、被说服的页面**，例如落地页、品牌页、产品发布页、展览页：才从下面的骨架表里选。
+- **两种都有时**，例如商店首页顶上有一块活动横幅，以用户最常来做的事为准：横幅可以留，但不能把第一排商品推出首屏。
+
+以下是说服型页面的方法。
+
+模型最顽固的习惯是左右分栏：一边大标题，另一边说明、按钮或一张图。换字体、换配色、换材质都改变不了它，因为它在写文案之前就定下来了：先想好标题、一段说明、一个按钮，把它们摆好，自然就是左右两栏。所以骨架要在写任何文案之前决定。
+
+每个方向先从下表选一个首屏骨架，再用 3–5 个方框画出首屏线框：每块是什么、占首屏多大面积、阅读从哪里开始。
+
+| 骨架 | 首屏长什么样 |
+| --- | --- |
+| 满版图像压字 | 一张图占满首屏，标题和动作压在图的安全区里 |
+| 居中单一物件 | 一个物件或一句话居中，四周是大面积空白 |
+| 画面即界面 | 首屏就是产品界面或一件实物本身，标题、导航和按钮都长在它上面 |
+| 满版文字 | 文字本身就是画面，字大到占满首屏、跨过边缘或被裁切 |
+| 通栏上下堆叠 | 通栏大标题横跨整个宽度，下面紧接内容 |
+| 网格拼贴 | 多块内容同时出现，按网格或拼贴排列，没有单一主角 |
+| 纵排或斜向 | 文字竖排、斜切或旋转，打破从左到右的阅读 |
+| 左右分栏 | 文字一侧，画面一侧。这是模型的默认，一轮最多一个方向使用，并写出为什么非它不可。另一侧必须是跨越结构的图像、色块或图形装置，不能是装在卡片里的产品界面 |
+
+规则：
+- 同一轮的方向，骨架互不相同。
+- 左右分栏最多出现一次。所谓“大标题九栏、说明三栏”同样算左右分栏。
+- 骨架定好之后再写文案。文案去适应骨架，不让骨架去适应“标题 + 说明 + 按钮”的组合。
+
+构图的大胆程度和调性无关。安静精致的产品，一样可以把一句话放在空白首屏正中，或让纵排标题贯穿整屏，或让界面本身占满首屏。调性决定音量，骨架决定结构；不要因为调性偏安静，就退回左右分栏。
+
+每一轮至少有一个方向让你自己觉得有点冒险：放在同类产品里会显得格格不入，但仍然好看，功能完整。模型只有被明确要求时才会这样做。如果你心里想的是“这不可能行得通”，通常说明方向是对的，做出来往往比预想好。
+
+最常见的模板核心不是左右分栏本身，而是“左边标题和两个按钮，右边一张装在圆角卡片里的产品界面”。那张卡片几乎总是该删的：要么让产品界面本身占满首屏，要么换成一张跨越版面结构的图、一个色块或一个图形装置。
+
+## 产品界面：先定对象和工作区骨架
+
+后台、工具、App，以及画廊、商店、信息流、文档站这类让人浏览和挑选内容的页面，都没有首屏海报，决定结构的是用户每天面对的对象、对它最常做的动作，以及多久用一次。模型的默认是“左侧栏 + 顶部四张指标卡 + 一张图表 + 一张表格”，不管产品是什么，因为这样不需要理解业务。跳出它的办法和落地页一样：画界面之前先定骨架。
+
+先写三行：
+
+- **核心对象**：用户每天处理的是什么，例如工单、合同、镜头、病床；一眼认出它靠哪两三个属性，例如缩略图、状态、金额、截止时间。再问一句：用户在这个对象上最怕错过什么？通常是一个会随时间变化的量，例如已经等了多久、离截止还剩多少、欠了多少。把它做成对象上最显眼的属性，而不是藏在详情里。
+- **主动词**：对它最常做的动作是逐条处理、比较、创作、安排、定位、推进还是监控。
+- **频率**：每天用几小时的专业用户，还是每月来一次的普通人。它决定密度。
+
+再按主动词选工作区骨架：
+
+| 主动词 | 骨架 | 长什么样 |
+| --- | --- | --- |
+| 逐条处理 | 队列 / 收件箱 | 左边队列，右边当前这一条的全部信息和处理动作；处理完自动跳到下一条，键盘可以一路按到底 |
+| 比较与筛选 | 表格 | 行是对象，列是比较依据；筛选、排序和批量操作长在表头与选择状态上，不另开页面 |
+| 创作与编辑 | 画布 / 文档 | 内容占满，工具贴着内容出现，面板按需展开 |
+| 沿时间安排 | 时间线 / 日历 | 横轴是时间，对象是时间上的块，拖动即改期 |
+| 在空间中定位 | 地图 / 平面图 / 座位图 | 对象画在真实位置上，列表只做辅助 |
+| 推进流程 | 看板 / 流水线 | 列是阶段，对象在列之间移动 |
+| 监控 | 仪表 | 只在真的需要持续盯着时使用；每个数字写出正常范围，以及出问题后该做什么 |
+| 对话后产出 | 对话 + 产物 | 对话收窄在一侧，产物占主区域并能直接编辑 |
+| 浏览与挑选 | 画廊 / 货架 / 信息流 | 内容铺满首屏，缩略图的比例就是版式；筛选和排序贴着内容顶部，占一行；点开时在原地展开或用浮层，关上回到原来的位置 |
+
+首页先回答“我现在该处理什么”，而不是“总共有多少”。大多数产品的主动词不是监控，首页就不该是指标卡仪表盘。
+
+**对象的样子就是产品界面的主视觉。** 先设计一个对象在列表行、卡片或画布上的样子：最重要的属性放在哪，状态怎样一眼看出，长名字怎么收，空值怎么显示，选中和处理中长什么样。一个设计好的列表行，比十张指标卡更能体现方向。
+
+**密度按频率定。** 每天用几小时的专业工具，行高 32–40px、正文 13–14px、一屏看到 20 行以上都正常，操作以键盘为先；偶尔来一次的消费产品，点击区域 44px 以上，一屏只要求一个决定。不要给专业工具套消费级的大留白，也不要把一次性的流程塞满控件。密度要在截图上数出来：一屏能看到几个对象，主动作离当前对象有多远。高频工具一屏少于 10 个对象时，先查行高、页面头部和说明文字占了多少高度。
+
+**产品界面的大胆放在哪。** 放在工作区结构、对象的样子和状态的表达上，例如时间在画面里怎样流动、超时怎样一眼跳出来。页面标题和品牌区保持小：一行，和区域标题同级或略大。在高频工具和内容页里放超大页面标题、通栏口号，或者用一整块深色卡片装“下一步”动作，都是把落地页的手法搬错了地方，占掉的是每天要看几百次的工作区。
+
+多个方向时，工作区骨架、对象的样子、导航方式（侧栏、顶栏、命令面板、在空间里跳转）、密度四项，任意两个方向至多一项相同。这四项是在通用差异检验之外再比，不是替代：产品界面同样需要各自的色彩身份和字体性格，不能三个方向都是系统黑体加一种强调色，只换了布局。方向卡里的“首屏骨架”一栏，产品界面填工作区骨架和对象的样子。
+
+## 方向卡
+
+每个方向写一张方向卡，每项都填具体选择，不填形容词：
+
+| 字段 | 要写到的程度 |
+| --- | --- |
+| 北极星 | 一句能指导取舍的体验意图：用起来像在什么地方、做什么事 |
+| 调性 | 五个刻度的取值及依据 |
+| 标杆与取舍 | 品类是什么，拆的是哪一家；沿用了哪几条、换掉了哪几条，各自为什么 |
+| 生成引擎 | 用了哪一种，具体是什么，来自这个产品的什么证据 |
+| 首屏骨架 | 先写用户来首屏看什么。内容页写首屏能看到几个对象、页头占几行；说服型页面写从骨架表里选的哪一种，附 3–5 个方框的首屏线框：每块是什么、占多大面积、阅读从哪里开始 |
+| 页面结构 | 首屏以下怎么组织，例如单列沉浸滚动，或导航、内容、详情三栏 |
+| 各区块的形式 | 首屏以下每个主要区块（产品实样、功能、价格、隐私、结尾等）在这个方向里长成什么东西。形式从生成引擎推出，不是同一个模块换颜色 |
+| 字体 | 具体字族、字重和尺度关系：展示、正文、数字各用什么，相差多大 |
+| 色彩 | 用到的十六进制色值及用途，说清这个方向的色彩身份；黑白灰加一种强调色也是完整的答案 |
+| 主视觉 | 哪张图或哪个图形承担情绪与识别，来自复用、生成还是排版本身 |
+| 图标 | 用哪一套、什么描边粗细和端点，或者不用图标、改用字符和编号 |
+| 控件语法 | 按钮、输入、选中、标签、状态和动效共用的一套形状和手感，用一句话写清，例如圆角多大、描边多粗、按下时怎样变化 |
+| 动效 | 手感用“动作 + 实物”写，例如“咔嗒：拨动开关”；三处基本动效各怎么动、怎样彼此呼应；有没有一处从产品里找到的巧思。见 [动效](motion.md) |
+| 结构性突破 | 改变首屏结构的那一处偏离常规，以及它怎样放大北极星。手写批注、质感按钮、划线这类局部细节不算 |
+| 记忆点 | 集中发力的一两处：在哪个时刻或位置，用什么材质、动作或画法，见“让人记住的一刻” |
+| 放弃什么 | 这个方向主动不要的常见做法 |
+
+北极星、字体、色板和特征直接写进对比页 manifest，与画面一同展示。
+
+## 差异检验
+
+方向卡写完、做小样之前，逐条检验：
+
+- **比线框，不比描述**：把各方向的首屏线框并排放在一起比。方向的描述可以各不相同，线框却可能都是“左边大标题，右边小块”。线框相似就是同一骨架，重选骨架。
+- **四项至多一项相同**：首屏骨架、字体、色彩、主视觉四项里，任意两个方向至多一项相同；否则就是同一方向的变体，换一个生成引擎重写其中一个。
+- **不按明暗分方向**：头号失败是“一个亮、一个暗、一个暖”。每个方向要有自己的色彩身份：不同的色相家族、不同的材质感，或者干脆是黑白。明暗是色彩身份的结果，不是区分方向的依据。
+- **黑白也是一种色彩身份**：黑白灰加一种强调色，甚至完全不用彩色，也是完整的色彩身份，这时颜色交给内容：产品截图、用户的照片、一张画。它和多色方案同样算拉开了差异。颜色选常见的还是少见的都可以，理由要来自这个产品。
+- **结构也要不同**：不同方向可以有不同的页面组织。三个方向页面结构完全相同、只是颜色和质感不同，就还没有拉开差异。候选只需共享核心内容和主要任务。
+- **至少一个走到极端**：至少一个方向在各项上都取明确的一端，不做折中；折中的取值最多出现在一个方向里。
+- **至少一个打破品类套路**：在同一调性内，至少一个方向不用这个品类的默认版式。常见套路如下：
+  打破套路不等于抛弃基线：画廊仍然让作品先行，只是作品的排列、筛选和点开后的样子可以与众不同。
+  - 后台：左侧栏、顶栏加卡片网格。
+  - 电商：大横幅、商品网格加页脚。
+  - 社交：底部标签栏、信息流加悬浮按钮。
+  - 落地页：主视觉、特性、用户评价，最后一个行动按钮。
+  - 聊天：左侧联系人，右侧消息。
+- **不撞脸**：把每个方向和它拆过的标杆并排看。字体、配色、主视觉和图标都一样，只换了名字，就是撞脸，重做。沿用基线不算撞脸，例如画廊让作品先行。
+- **盲看**：遮住名字和说明只看画面，仍能说出每个方向带给人的不同感受。
+
+小样做出来后再比一次实际画面：在对比页并排看首屏，眯起眼睛只看明暗块面。块面的分布如果相似，比如都是左边一大块、右边一小块，即使字体和颜色都不同，也回到骨架表重做，不靠换装饰补救。首屏之后，再按区块逐一比较整页，规则见“方向贯穿整页”。
+
+## 方向贯穿整页
+
+方向不只属于首屏。首屏以下的每个区块，都要用这个方向自己的语言重新设计：同一份内容，在不同方向里应该是不同的东西，形式从各自的生成引擎推出。模型最容易在首屏用尽力气，到了第二屏就回到通用的卡片、分栏和居中结尾，三个方向的下半页变得一模一样。
+
+规则：
+- **候选共享内容，不共享实现。** 同一份示例数据可以共用；为这个方向写的区块结构、样式和代码不共用。不要为了省事，把某个区块写成共用模块再给各方向换颜色，那等于亲手制造趋同。产品本身的组件不在此列：设计组件库官网或已有产品时，各方向照常使用同一套真实组件，差异体现在它们被怎样编排、呈现和讲述上。
+- **同一条修改意见，要翻译成每个方向自己的做法。** 评审常常对所有方向提出同一条建议，比如“展示产品真正交付的东西”。这条意见在每个方向里的落地形式都不同，不能用同一种实现套到所有方向上。
+- **区块的顺序和取舍也属于方向。** 各方向都按“首屏、对象介绍、三步流程、一句结尾”排下来，就算每块都换了样子，仍是同一张页面。由各自的引擎决定先讲什么、合并什么、删什么：有的方向把流程并进对象介绍，有的方向整页只讲一个对象。产品界面也一样，同一段内容、同一道题按同样的顺序出现，就是换了皮的同一个界面。
+- **外壳也是区块。** 导航、行动按钮、结尾区的句式和页脚最容易被忽略，常常三个方向共用同一套，只换颜色。它们同样要从生成引擎推出自己的形式。
+- **逐区块比较，而不是只比首屏。** 把各方向的整页截图并排，按区块一一对照：产品实样对产品实样，结尾对结尾。任何一个区块在两个方向里看起来是同一个东西，就回到那个方向的生成引擎重做这个区块。
+
+## 北极星与呼应
+
+北极星选定后，转成少量相互支持的关系：摄影的空旷与标题的留白呼应；窄字形与纵向画面呼应；低饱和环境色与唯一的行动色形成反差。每个方向明确主角、陪衬、重复的节奏和一处结构性突破。
+
+突破要改变结构，例如首屏的骨架、比例或阅读顺序，而不是多加一个装饰；它应增强主题或引导关键动作。精修时不要把有辨识度的选择修平。新增元素不能强化同一意图时，优先省略。大胆的方案也必须可读、可用。
+
+## 让人记住的一刻
+
+模型做的页面常常处处及格，却没有一处让人记住。惊艳很少来自整页都用力，而是来自一处做到极致：通常是一个组件的一次动作，结果、材质、光影、手感和节奏都做到位。每个方向选一两处集中发力，其余保持安静。
+
+去哪里找：
+
+- **用户会做的动作。** 点按、拖动、切换、提交，比滚动更容易成为记忆点。
+- **关键时刻。** 付款成功、第一次完成任务、升级、删除、上传、等结果。这些时刻情绪最强，一个小动画的回报最高。
+- **边角页面。** 404、空状态、加载、页脚。没人期待，风险又低，最容易出彩。
+- **AI 在工作的时候。** 把过程按顺序展开：步骤一个个亮起，日志一行行流进来，做完的一步收起，正在做的一步展开。白底黑字照样成立，不需要材质和发光。
+
+怎么想：
+
+- **让结果当场发生。** 状态切换不只换一个图标，而是让被影响的东西当场变化：打开深色模式，整页像拉下遮光帘一样暗下去；拖动时间，画面的天色跟着走。用户看到的是结果，不是控件在表演。
+- **把数字画成看得见的量。** 百分比、时长、余额，先问能不能画成一个量：点亮的格子、填满的长度、一格代表一天的网格。数字只是标签，量才是画面。
+- **给抽象的状态一种材质。** 先问“这个状态如果是一个实物，会是什么”，答案从产品所在的领域里找。
+- **借物件的动作交付结果，物件从用户手上找。** 选这个领域的用户本来就拿在手上的东西：旅行产品用登机牌成立，作品集用登机牌只是借梗。票据、打印机、卡带、老游戏机这类复古实物在灵感站上已经泛滥，用之前先问：这个产品自己的实物是什么。
+- **给控件物理和性格。** 拖动有弹性和重量，按下有光影变化，拉过头会不情愿地弹回来。
+- **画法要说得出来源。** 点阵、字符画、像素、粒子、写实材质这类画法，只有能说出它来自产品做的事时才选：把数据渲染成点阵的研究工具用点阵，长在终端里的工具用字符画。说不出来源就不选；选了就从主视觉一路用到加载、图标和空状态。做法见 [点缀与特效](ornament.md)。
+- **一张画面垫底时，界面要退后。** 有情绪的摄影或绘画铺满，界面缩到只剩一行导航和一句话，排版严格；底图虚化或压暗，保证文字可读。
+
+## 参考怎样转为设计决定
+
+先说明参考用途：借鉴视觉关系、建立质量基线，还是精准还原。实际看过图片再描述它的视觉。借鉴时提取关系，例如“标题占主要视觉重量，图像提供情绪，辅助信息压低对比”，再用当前内容重新组织；不要照搬参考的业务模块、标识和文案。隐喻要转译成界面决策，不做成妨碍操作的仿真外壳。
+
+参考里没有的东西也是决定。参考的首屏没有标题区和说明段，就不要替它补上；参考没有用的装饰，也不要加回去。
+
+## 小样、选择与品味
+
+先用几句话比较设计意向，再给有希望的方向做代表性小样，不一开始就做多套完整产品。单个页面的小样通常是首屏加最能体现方向的一两个区块；用户明确要完整页面时照做，评审深度仍按探索阶段。方案数量按任务定，窄小的任务不强求多方案。
+
+挑能暴露方向优缺点的代表性页面：含复杂表单的产品不能只做封面，长页面的小样要包含关键内容结构。
+
+介绍产品的页面，必须让用户看到产品真正交付的东西：一张生成好的报表、一份导出的合同、一段处理后的真实数据，而不是只用文字承诺“能做什么”。这个实样往往比功能列表更有说服力，也最容易成为页面的第二个主角。需要实际比较多个小样，或由 Agent 自行选定方向时，先使用 [风格对比页](style-explorer.md) 生成对比页留档，再选定方向。
+
+比较任务适配、辨识度、内容承载、可读性和实现代价，主 Agent 给出推荐依据，由用户选定。选定后请用户用具体的话补充品味：想要什么感受，不要什么、为什么不要，哪些地方要保留。用户只说“再高级一点”时，用上面的翻译表追问，或拿两张小样让用户比较。
+
+把选定方向和品味写进设计说明，作为后续判断基线。评审提出新风格时，先判断它是否解决原目标；只有当前方向确实不适配，或用户改变目标时，才重新探索。

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

@@ -0,0 +1,286 @@
+# 存量项目
+
+在已有仓库里改界面，先分清用户要什么。优化 UI、改流程、加新功能，要改的东西和要锁住的东西正好相反：优化 UI 改的是视觉语言，流程和功能沿用；改流程和加新功能改的是做法，视觉沿用。弄混了，要么在一个本来就平庸的系统上修修补补，要么三个方案只是同一条流程换了皮。
+
+## 先分清意图
+
+| 用户想要 | 常见说法 | 要改的东西 | 锁住的东西 | 多个方案差在哪 |
+| --- | --- | --- | --- | --- |
+| 优化 UI | 不好看、太土、不统一、想更高级 | 层级、字体关系、色彩比例、密度、组件的样子 | 品牌资产，以及用户点名保留的部分 | 推翻现状的程度，见“优化 UI” |
+| 改流程 | 难用、步骤多、找不到、老出错 | 入口、步骤、承载方式、状态的表达 | 视觉沿用现有系统 | 做法，见“改流程与加新功能” |
+| 加新功能 | 加一个……、新做一页 | 新功能的做法 | 视觉沿用现有系统 | 做法，见“改流程与加新功能” |
+
+从请求推断意图，推断不出来时问一句。一个请求同时包含几种意图时，先定流程，再定视觉：流程决定页面上有什么，视觉决定它们长什么样。流程方案选定后，视觉的几个方案都建在这个流程上；最初的基线截图留着，做最后的前后对比。
+
+动手前在设计说明开头写一行：这次是哪种意图、优化 UI 时取哪一档、现在处在哪个阶段。后面选检查和评审规则时，以这一行为准，不套用新界面的流程。
+
+改流程和加新功能时，现有视觉即使不够好，也照样沿用；发现的视觉问题单独列出，交给用户决定要不要另做一次优化 UI。
+
+## 先摸清现状
+
+只看和这次改动有关的范围，不通读整个项目：
+
+- **组件和同类页面**：已有哪些组件，同类任务在别的页面是怎么做的，哪些做对了可以沿用，哪些本身就是问题。
+- **项目自己的门槛**：先看仓库的检查脚本和规范，例如动效只能用哪些时长变量、文案键怎样写才能通过 i18n 检查、各页面的性能预算、组件交付要声明哪些依赖。设计实现从第一行就按这些规则写，不要做完再返工。
+- **基线截图**：改动前，在目标视口截下相关页面和关键状态，包括空数据、加载、错误和长内容，存到任务目录。之后的前后对比用同样的视口、数据和状态。
+
+优化 UI 时再看两项：
+
+- **设计变量**：颜色、字号、间距、圆角、阴影和动效定义在哪里，页面实际用的是变量还是硬编码。
+- **实际取值**：搜索相关页面和组件里的颜色、圆角、字号，统计各有多少种。常见结果是十几种灰、七种圆角、三套按钮。
+
+## 优化 UI
+
+### 规范体检
+
+动手前先判断现有规范值不值得当标准。用方向卡的格式给现状写一张卡：调性、字体、色彩、密度、图标、动效。逐项标出它是品牌资产，还是偶然形成的默认值：
+
+- **品牌资产**：标志、主色、品牌字体、专有插画，以及用户说要保留的。默认不动。
+- **偶然的默认值**：组件库默认的灰阶和圆角、默认图标库、随手定的字号和间距、没人决定过的阴影。可以重新决定。
+
+再给规范下结论：
+
+- **规范是好的，页面没做到位。** 现有规范就是标准：整理照着它修，升级和重塑也保留它的品牌资产。
+- **规范本身平庸或混乱。** 偶然的默认值都可以重新决定，目标是给这个产品建立一套更好的规范。
+- **拿不准。** 把现状截图和同品类最好的两三个产品放在一起看，差距明显就按规范本身有问题处理。
+
+结论和理由写进设计说明，后面的评审以它为准。
+
+### 推翻程度
+
+| 档位 | 改什么 | 留什么 |
+| --- | --- | --- |
+| 整理 | 把混乱的视觉值收拢成少数语义角色，统一同类组件，修层级、对齐和留白 | 品牌、结构和现有的视觉气质 |
+| 升级 | 重新决定字体关系、色彩比例、密度、组件的样子和图标 | 品牌资产、页面结构和全局导航 |
+| 重塑 | 按 [设计方向](design-direction.md) 重新探索，结构也可以变 | 品牌资产 |
+
+先问一个问题：**这一页改了样子，别的页面要不要跟着改？**
+
+- **要跟着改**：账户页、设置页、订单列表这类页面，和其他页面共用顶栏、组件和字体，只改其中一页就会和别的页面不搭。
+- **不用跟着改**：落地页、活动页、单页官网这类页面，自己就能定样子，改了也不牵连别的页面。
+
+然后按下面的顺序决定做哪几档，前一条成立就不看后一条：
+
+1. **用户说了改多少**，按用户说的做。
+2. **范围是整个产品，或者是一个不用跟着改的页面**，三档各出一个方案，和现状一起放进对比页，让用户直接看到改到哪一步是什么样。规范体检认为现有规范是好的，升级和重塑也照出，只是都保留品牌资产。
+3. **范围是一个要跟着改的页面、一个组件或一处区域**，只做整理：在现有的视觉语言里重排布局和层级，不换字体、色彩和组件的样子。体检认为规范本身有问题时，在交付说明里写明升级或重塑会连带改到哪些页面，问用户要不要把范围扩大。
+
+只做整理时，也把现状和整理后的版本放进对比页，交付时问一句要不要看看升级或重塑的样子；不改完就交，让用户连原来是什么样都看不到。
+
+范围是整个产品时，升级和重塑的方案要能推广出去：写明换掉的字体、颜色和组件会影响哪些页面，并拿至少一个其他页面检查新规范放上去是否成立。产品里任何地方都没有出现过的字体和颜色，只在重塑档里引入。
+
+三档之间按推翻程度比较，不套用设计方向里的差异检验：整理和升级本来就和现状共享结构，这是档位决定的。只有重塑一档里探索多个视觉方向时，才用设计方向的差异检验。
+
+各档要写的东西不同，不要每档都填完整的方向卡：
+
+- **整理**：不写方向卡。列出要收拢的视觉值和要统一的组件，写清各自收到哪个语义角色。
+- **升级**：只写北极星、字体、色彩和记忆点四项，从这个产品的品类和内容里推出来，不是把组件库默认样式换成另一套默认样式。
+- **重塑**：按设计方向走完整流程，写完整的方向卡，默认保留品牌资产，除非用户要求更换。
+
+选定以后，新规范先落到共享的设计变量和组件上，在一个代表性页面上做完整、确认，再逐页迁移，不一次重写所有页面。之后的评审以新规范为标准。
+
+## 先用，再想
+
+改流程和加新功能都从这里开始。存量项目的问题大多不在画面上，在流程里：看截图只能看出间距和颜色，要知道该改什么，先把任务亲手走一遍。
+
+### 用用户的话写任务
+
+动手前写一句话：用户是谁，来做什么，做完想拿到什么。只用用户自己的词，不出现界面上的名词。写“把上周没回复的客户标成待跟进”，不写“在列表里筛选并批量修改状态”。后面每一屏、每一步都拿这句话衡量：它让任务前进了，还是让用户在伺候界面。
+
+写不出这句话，先问用户，不先看界面。
+
+### 先定产出物
+
+很多功能的结果是一样东西：一份清单、一个文件、一条消息、一页摘要。结果是一样东西时，先把它写出来，再想界面：
+
+- 谁收到它，收到后要拿它做什么。收的是人，要一眼看懂；收的是系统或程序，要能直接用。
+- 里面缺了什么就用不了。按收件方的需要列，不按界面上现成有什么列。
+- 用户今天凑合时亲手带走的是什么。这是产出物的下限，新功能不能比它少。
+- 产品里已经有、用户却得自己翻出来的东西，系统补进去。
+
+把最好的那一份产出物直接写成样例，放在设计说明里。例如食谱应用的“生成购物清单”，样例就是一份真的清单：按超市货架分区、合并重复的食材、标出家里常备的。样例写不出来，或者和用户凑合的办法没有区别，先回来修产出物，不开方案。
+
+产出物定好后，各个方案都交付同一份。方案之间差的是用户为它做多少、系统替他做多少，不是谁的产出物好一点。
+
+### 走一遍，边走边数
+
+用真实或脱敏后的数据，从用户实际的入口走到能看到的结果。按 [视觉评审协议](visual-review.md) 的“任务走查”记下卡住、走错、犹豫和多余的步骤，同时数四个数，写进任务目录：
+
+- **步数**：到结果要几次点击、几次页面切换。
+- **决定数**：界面问了用户几个问题，其中几个系统其实已经知道答案。
+- **记忆负担**：有几样东西要从一屏带到另一屏，靠脑子记、复制粘贴或开两个标签。
+- **回头路**：出错或改主意时要退回几步，丢掉什么。
+
+记成一张表，现状、理想路径和每个方案各占一行，后面每次计数都往这张表里加：
+
+| | 点击 | 页面切换 | 决定（其中系统已知） | 记忆负担 | 回头路 | 寻找与阅读 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 现状 | 8 | 6 | 6（1） | 3 件作品和用途 | 刷新后重选筛选，丢掉候选 | 滚动两屏才找到第三件 |
+
+点击和页面切换分开记，不相加；回头路写退回几步、丢了什么；滚动找了很久、读了很多才做出的决定，即使不算点击，也记在最后一列。表格上方写一行计数口径，例如键盘操作算不算点击。现状、理想路径和每个方案都用同一个任务、同一批数据和同一套口径来数，否则数字不能互相比较。
+
+再走一遍坏路径：输入错、名称很长、数据为空、上千行、权限不足、中途离开再回来。存量项目最常见的问题都来自真实数据。
+
+每处犹豫归为一类：不知道从哪开始，不知道点了会怎样，不知道成功没有，不知道怎么回去。
+
+加新功能时没有现成流程可走，就走它旁边的现有流程，再走用户今天凑合的办法：复制粘贴、导出表格、在备注里打标记。凑合的办法证明需求存在，也往往指向最自然的入口。
+
+### 写理想路径
+
+这一步不能省。假设现有界面不存在：用户从说出意图到看到结果，最少要做几个决定，每个决定需要看到什么。把它和现状的步骤并排，多出来的每一步都是结构上的机会。
+
+找问题，得到的往往是补丁；从结果往回推，得到的才是结构上的改法。
+
+### 从现象找到原因
+
+走查记下的是现象。每条往下问为什么，直到落进下面五种原因之一，每种原因都有自己的改法方向：
+
+| 原因 | 怎么认出来 | 往哪改 |
+| --- | --- | --- |
+| 做决定的地方没有做决定要用的信息 | 要开另一页、来回切换、靠记忆 | 把信息搬到做决定的地方：行内、侧面板、预览 |
+| 功能长在用户不会去找的地方 | 犹豫发生在找入口；对象没有自己的家 | 搬到对象上，或搬到用户出发的地方 |
+| 流程的形态和任务不匹配 | 一步能做完的拆成向导；可撤销的还要确认；几十条要逐条打开再退回 | 换骨架：队列、行内编辑、批量；去掉确认，改成可撤销。骨架见 [设计方向](design-direction.md) 的“产品界面” |
+| 系统知道的事让用户再做一遍 | 要填系统已有的值；要选只有一个合理答案的选项；要手动触发每次都做的事 | 预填、给默认值、自动执行并可撤销 |
+| 状态看不见 | 做完没有变化；进行中看不出来；出了错要自己去找 | 把状态做成对象上的属性，在列表里就能看到 |
+
+间距、颜色、文案不在表里。它们是症状或精修项，记下来放到最后，不混进原因。
+
+三个例子：
+
+- **现象**：给上周没回复的客户标“待跟进”，每条都要点进详情、改状态、返回，列表回到顶部，再重新找下一条。**原因**：用户在逐条处理，骨架却是“表格加详情页”，改状态被放在了详情里。**补丁**：记住滚动位置。**结构上的改法**：筛选“未回复”后在行上直接改状态；或者左边队列、右边详情，处理完自动跳到下一条；或者全选后一步批量标记。
+- **现象**：新建合同有 14 个字段，填到一半去查客户编号，回来表单空了。**表面原因**：没有草稿。**根本原因**：表单在要系统已经知道的东西；入口在顶级菜单“合同”，用户却是从某个客户出发想建合同的，客户信息在入口处就丢了。**补丁**：加草稿，加“编号在哪里找”的提示。**结构上的改法**：入口移到客户详情页，客户相关字段全部带出，只剩三四个真正要判断的字段，放在侧面板里，下面的客户信息仍然看得见。
+- **现象**：首页是四张指标卡，用户每天进来直接点“工单”菜单。**原因**：首页回答“总共有多少”，用户每天要知道的是“现在该处理什么”。**补丁**：给指标卡加趋势箭头。**结构上的改法**：首页就是待处理队列的前几条，最显眼的属性是已经等了多久；指标收成一行小字。
+
+### 补丁自查
+
+每条建议写完，过一遍下面五个问题，任何一个答不上来就是补丁：
+
+- 它是在加一个东西（提示、引导、确认、说明文字、徽章、空状态插画），还是改掉或删掉一个东西？加东西之前，先回答界面为什么让人看不明白，那个答案才是真问题。
+- 把根本原因修掉以后，它还需要存在吗？
+- 改完之后，步数、要记住的事、要切换的页面，至少有一样变少了吗？
+- 第十次用的人会被它打扰吗？引导和确认对熟手是负担。
+- 能用用户的话说出改善吗：“现在不用再……”。
+
+补丁可以做，单独列为“今天就能改”，不冒充方案。
+
+### 不知道从哪改时
+
+用户只说“优化一下这页”，没说哪里难用，就按这页的主要任务走一遍、写理想路径，把差距最大的三处按影响排好，每处写清用户能少做什么，附截图，交给用户挑。用户挑了再继续。
+
+## 改流程与加新功能
+
+走查、理想路径和产出物样例都写完之后，才开始想方案；还没看过现有代码和页面就定下的方案，只是在三种立场的格子里填空。
+
+视觉全部沿用：同一套设计变量、组件、图标和动效，不换字体和主色，不另做控件。多个方案之间能看出差别的只有三件事：出现在哪里，要几步，谁在做事。产出物不在其中：它在“先定产出物”里定过一次，每个方案都交付同一份最好的。产品里没有现成的控件时，例如第一次出现输入框，单独列出，从现有控件的样子推出来：圆角、描边、字号、文字颜色，以及悬停、聚焦和出错的样子，都和现有的按钮、筛选和菜单一致。不用浏览器默认样式，也不随手写一套通用表单样式。
+
+### 读出产品的习惯
+
+新功能和新流程要像这个产品原来就有的。从现有界面读出下面几项，各写一行，后面每个方案都遵守：
+
+- **对象**：导航和列表第一列里的名词，就是用户认的东西。哪些有自己的列表页，哪些只在详情里出现。新功能是哪个对象上的事；要不要引入新对象，这是大决定，写出理由。
+- **动作**：按钮和菜单上的词，就是用户认的动作。新功能能不能用已有的动词说出来。
+- **出发方向**：用户是先找到对象再做事，还是先选动作再找对象。
+- **节奏**：一次处理一件还是批量；马上完成还是进后台任务。
+- **承载**：详情开新页面还是侧面板；编辑用弹窗还是行内。
+- **反馈**：成功后是原地高亮、角落提示还是跳转。
+
+这些习惯默认沿用。打破某一条时，说出来自这个任务的理由。
+
+再看两三家同类产品：这个功能长在哪里、要几步、系统替用户做了什么、用户最后拿到什么，各写一行。能上网就真的打开看；凭记忆写的，标明是记忆。只看这一个功能，不拆整个产品。
+
+### 三种立场
+
+每个方案先选一种立场，再在立场里把流程想完整：
+
+| 立场 | 用户做什么 | 适合 |
+| --- | --- | --- |
+| 顺手 | 在原来的地方多做一件事：行内、选中后、对象的操作菜单里，不新增页面和对象 | 简单、依附于现有对象、做完就走 |
+| 自动 | 系统替用户做一个他本来要自己做的判断或整理，用户只看结果、改例外、撤销 | 规则明确、错了能撤回、每次做法都一样 |
+| 专用 | 给这件事一个自己的地方：新页面、新面板或新工作区，相关信息和状态摊开 | 高频、步骤多、要连续处理或对照 |
+
+三种立场是备选，不是配额。先问每种立场在这个任务里能不能写出一个站得住的做法，写得出几个做几个；凑不出就少做一个并说明理由，不把一种立场做成两个方案，也不把一种立场硬套成一个方案。
+
+“自动”要说得出系统替用户判断了什么。把已有数据拼在一起、换个地方显示、少点一次，都不算自动。只有现有数据真的能支撑这个判断时才选它；数据和接口做不到，就不做这个方案。
+
+立场只决定入口、流程的形态和承载方式；对象、动作的位置、组件和反馈方式，按上一节读出的习惯沿用。
+
+### 方案卡
+
+改流程和加新功能用这张卡代替设计方向里的方向卡，每项一两行：
+
+| 字段 | 写什么 |
+| --- | --- |
+| 立场 | 顺手、自动或专用 |
+| 入口 | 用户在哪里、看着什么时碰到它 |
+| 步骤 | 从意图到结果，一行一步，旁边并排现状的步骤或理想路径 |
+| 修了什么 | 对照“从现象找到原因”的表，修的是哪一条 |
+| 拿到什么 | 这个方案交付的产出物和“先定产出物”里的样例一致；有增减时，写明多了什么、少了什么、为什么 |
+| 值得 | 用用户的话写一句改善：“现在不用再……”或“现在能……”。写不出来，这个方案不值得做 |
+| 出错时 | 失败后用户在哪里，什么被保留了 |
+| 赌注 | 押的是用户的哪种习惯或场景 |
+| 放弃什么 | 它做不好的场景 |
+
+差异检验先看一样，再比两样。先看每个方案的产出物有没有达到样例，差一截就先补，否则几个方案都只是在给一份没用的东西找入口。再比入口是否不同、步数或系统替用户做的事是否不同；两个方案这两样都一样，就是同一个方案换了皮，换一种立场重做。
+
+### 放进对比页
+
+候选直接在项目里实现，不另写一套静态页：用独立路由或查询参数切换，例如在原地址后加 `?variant=b`，每个方案都用真实的组件和数据。对比页用本地地址作为候选，现状作为基线放在第一位，交付时开发服务器开着，见 [风格对比页](style-explorer.md)。
+
+用户要求先看方案、选定后再动代码时，不改业务路由和组件，在任务目录里做可操作的小样，用现有的设计变量和真实数据，见 [风格对比页](style-explorer.md) 的 `"interactive": true`。
+
+对比页里每个候选只有一个画面，选三个方案差别最大的那一刻，通常是入口或关键的一步，不选结果页，结果页在各种做法下往往长得一样。功能的结果是一样东西时，另外把产出物样例原样放进对比页的说明，让用户看到他最后拿到的是什么。`traits` 写立场、入口和步数，让用户在卡片上就能比较做法；字体和色板三个方案填同一组现有的值。
+
+### 评审
+
+不打视觉分，不跑评分循环。交付对比页时推荐给用户的下一步，是下面这一轮方案评审，不是 SKILL.md 步骤 4 的视觉评审和多方向横向评审。给用户之前，自己按任务那句话把每个方案走一遍，记下卡住、走错和犹豫，写进对比页的说明。用户同意后，有隔离执行者时按 [视觉评审协议](visual-review.md) 的“评审改流程和加新功能的方案”评一轮。
+
+选定并实现后，再走一遍，在同一张表里加一行，和现状并排写进交付说明。各列都没有改善时，先查是不是只改了皮，回到“从现象找到原因”；改善体现在入口更容易找到、更少出错或更容易恢复时，用卡住、走错、犹豫次数的变化说明；只减少出错、没有减少步骤和记忆负担的改动，写明它防的是哪种错，归为防错，不当作结构上的改法。视觉上只按“给已有界面评审”看一轮，润色了一整页以上才做。
+
+计数表只量路程，不量结果。另写一行：拿到产出物的人能不能不加工直接用；不能，先修产出物，再谈步数。
+
+## 各类改动怎样评审
+
+| 改动 | 交给用户挑选之前 | 选定并做完之后 | 打分 |
+| --- | --- | --- | --- |
+| 整理 | 不派评审者，主 Agent 和基线做前后对比 | 润色了一整页以上时，按 [视觉评审协议](visual-review.md) 的“给已有界面评审”看一轮，标准是现有规范 | 不打分 |
+| 升级 | 不派评审者 | 按“给已有界面评审”看一轮，标准是选定的新规范 | 不打分 |
+| 重塑 | 按 SKILL.md 步骤 4 推荐一轮视觉评审，由用户决定 | 按步骤 4 的评分循环，目标 9 分 | 打分 |
+| 改流程、加新功能 | 主 Agent 自己走一遍；推荐一轮“评审改流程和加新功能的方案”，由用户决定 | 再走一遍，在计数表里加一行；视觉按“给已有界面评审”，润色一整页以上才做 | 不打分 |
+
+三档放在同一个对比页里给用户挑时，挑选前都不派评审者；用户选了哪一档，之后按哪一档那一行做。
+
+## 这时读哪些参考
+
+改流程和加新功能时，先用这几处：[设计方向](design-direction.md) 的“产品界面：先定对象和工作区骨架”，[交互与状态](interaction-and-state.md) 的“先走通用户任务”“动作层级”“按范围表达状态”和“模型在交互上的默认做法”，[布局与视口](layout-and-viewport.md) 的“选择承载方式”。
+
+[视觉语言](visual-language.md) 的“细节”和“模型默认审美自查”、设计方向的差异检验、三处基本动效，留到方案选定、开始精修时再用。太早拿出来，注意力会被圆角和线框占满。例外是方案里第一次出现的东西，例如新的输入框、面板或浮层：交给用户之前就按“细节”检查一遍，用户挑方案时看的就是画面。
+
+## 从源头修改
+
+改样式之前按顺序检查：
+
+1. 项目里是否已有同样含义的组件、变量或样式；
+2. 页面是不是用错了组件；
+3. 父布局给的尺寸、对齐或定位是否有错；
+4. 组件默认样式或状态逻辑是否有错；
+5. 已有的组件变体够不够用；
+6. 是否真有稳定重复的职责，需要一个新的共享实现。
+
+前几步没查完，不新增组件、变体或样式。
+
+- **修共享，不覆盖实例。** 不用 `!important`，不用页面专属选择器侵入组件内部，不用任意数值绕过变量。
+- **变体要有稳定含义。** 新变体按用途命名，例如 `destructive`、`compact`，不按页面或视觉结果命名，例如 `orders-blue`；至少有两个使用位置，或者属于组件的公共状态。
+- **先查使用位置。** 改共享组件、变量或样式前，搜出所有使用位置；每种不同的用法各抽一处验证。
+- **接管后删旧的。** 新实现接管后，迁移所有使用位置，删掉旧组件、旧样式和失效的选择器。做不完时写清剩下哪些位置，不长期保留两套实现。
+- **收敛视觉值。** 把十几种灰映射到正文、次要文字、边框、表面这类少数语义角色：先改变量，再批量替换，最后删掉孤立的值。
+- **动效先沿用。** 先用项目已有的时长和缓动；项目没有时才按 [动效](motion.md) 确定，并收成变量。
+- **展示内容先按需加载。** 文档页、组件目录这类一页里放很多真实组件的页面，首屏以下的示例和样张在滚动到附近时再加载，别让每一页都背上所有示例的脚本。项目有性能预算时，先这样压下去，剩下确实属于新功能的增量再上调基线，并写明原因。
+- **不顺手改业务逻辑。** 逻辑确实造成了界面问题，例如重复请求、状态不同步，单独指出并说明改动范围。
+
+## 验证
+
+- 和基线在同一视口、同样数据和状态下做前后对比截图。
+- 被改动的共享组件，在其他使用位置各看一处。
+- 优化 UI 润色了一整页以上时，按 [视觉评审协议](visual-review.md) 的“给已有界面评审”看一轮，标准是规范体检的结论：规范是好的就按现有规范，重新建立了规范就按选定的新规范。
+- 改流程和加新功能，走一遍主要任务，和走查时的四个数并排对比；保存类操作要重新读取确认。
+- 运行项目已有的类型检查、测试和构建；不为一次视觉修改新建测试体系。

oil-ui-pro/references/imagery.md

@@ -0,0 +1,69 @@
+# 配图
+
+生成图最常见的失败不是画得不好，而是画得太满：细节越丰富越像图库照片，放进版面后没有重点，也和页面没有关系。好的配图要先承担意思，再承担气氛，最后和页面接成一个整体。
+
+## 先让图承担意思
+
+生成之前先写一句：这张图要让人一眼看懂什么？答不上来就先别生成。“一张好看的使用场景”不是答案；“产品把一堆混乱变成了哪几个清楚的结果”才是。
+
+用对比把信息编进图里。整体统一成一种低调的材质或颜色，比如白模、单色、失焦或剪影，只让承载信息的少数几处有颜色、光或细节。例如白色仓库模型里只有出了异常的两排货架亮成橙色，灰度地图上只有正在配送的路线是彩色。所有地方都一样精细，就等于没有重点；第一版通常就是这样失败的。
+
+选能和页面“接上”的主体：
+
+- 能跨过两块色面分界的单个物件。
+- 能延伸出画面的线：线缆、轨道、河流、胶片、纸带。
+- 能在上面标注的空间：模型、地图、剖面、平面图。
+
+这样的主体，之后能和页面里的线、标注和区块连成一体；一张自给自足的风景照做不到。
+
+## 写提示词
+
+按固定顺序写，每项一两句：
+
+1. **主体与表现形式**：什么东西，用什么体裁呈现（照片、插画、模型或图解），体裁从页面的方向推出。
+2. **视角与镜头**：机位的高度和角度；焦段和景深。
+3. **构图**：主体在画面里的位置和占比，四周留多少边距，哪一块留空给文字。要整件物体完整入画，就写明“完整地放在画面内，四周留出宽松边距”，否则常被裁掉一角，之后没法排版。
+4. **背景**：写出页面实际使用的十六进制色值，或者要求透明背景。
+5. **材质与光**：主光方向、辅光、质感。同一页的多张图用同一个光向。
+6. **重点**：用什么对比让哪几处成为焦点，其余部分怎样退后。
+7. **排除**：不要文字、标志、界面、屏幕内容；透明物件写明“地面不要阴影”。
+
+文字、界面和数据一律不让生图模型画：会画错，改不了，也不能被选中、翻译和读屏。它们放在页面上，用真实元素压在图上，或用引线连到图上。
+
+## 生成后放进页面再判断
+
+在真实页面、真实尺寸里看，不在图片查看器里判断。单独看很好的图，放进版面后常常主体太满、朝向不对、留白在错的位置。
+
+不对就改提示词重新生成，并写清要改什么，例如“除了三处重点，其余全部改成白色”“把整个模型收进画面”。不要围着一张不合适的图改版式。同一批里挑最能排版的一张，不挑细节最多的那张。
+
+## 让图和页面接成一体
+
+**背景融合。** 不透明的图，从图的四角实际取色，页面背景用同一个值；四条边都淡出到这个颜色，不加框，也不放进圆角卡片。只淡出一侧时，其余三边在宽屏上会露出矩形接缝。淡出可以用 CSS 遮罩，也可以在导出时直接把边缘渐隐成页面色值，后者不增加样式，适合样式体积受限的页面。生成图的底色常常不均匀，靠边缘会偏色，要在实际显示尺寸下检查接缝。
+
+**透明图。** 先放在最终背景上检查边缘、白边和残留的棋盘格；检查透明通道要看像素，不能看文件后缀。阴影不烘焙在图里，由页面按实际背景加投影，这样换了背景也对。
+
+**跨越结构。** 透明物件放在两个色块或两个区块的分界线上，让它同时属于两边。
+
+**图和代码接力。** 生成图负责代码做不出来的材质和光，例如金属、玻璃、模型、光影。代码负责需要精确、可编辑、会延续的部分，例如从图里延伸出去的线、路径和标注。如果图里有一段本该延续到页面的部分，就把它裁掉，改用矢量接着画。这样它能准确穿过版面，带上真实文字，并在不同宽度下重新走线。
+
+**标注。** 在图上标注用细引线加文字，不用带底色和阴影的气泡卡片。引线端点要对准图里的真实位置：图在版面里用固定的尺寸和位置，按图片像素换算坐标。窄屏上隐藏标注，或改成图下的列表，不让它们漂移到错误的位置。
+
+**窄屏裁切。** 不把整张大场景等比缩小到看不清。从原图裁出焦点区域另存一张给窄屏用，或用对象定位对准焦点。桌面和手机两种裁切，都要保住承载信息的那几处。
+
+**一张图用多次。** 结尾或其他区块可以用同一张图的局部特写，比再生成一张光线和风格对不上的图更统一。
+
+## 让一张画当舞台
+
+另一种用法正好相反：图不讲信息，只给气氛，界面保持黑白克制，全页只用一种有笔触的画当唯一的颜色来源，例如油画、水粉、水彩或版画。
+
+- **画当舞台，界面在上面演示。** 把真实界面的简化版放在画上，画从四周露出来。滚动时画固定不动，只换前面的界面内容，和“滚动叙事”接得上。
+- **大胆裁切。** 只留画的一角或一个局部，接近抽象，不和界面抢。题材不必和产品字面相关，但气质要对得上：快、静、暖或者松弛。
+- **松和紧互相衬托。** 画越松，界面越要精确、干净；两者一起出现，彼此都更好看。
+- **用得少。** 一张画贯穿全页，或者只在两三处出现，例如价格卡的顶端和页脚；不要每个区块配一张。同一页的画统一画种和笔触。
+- **演示用简化过的真实界面。** 次要内容虚化或换成骨架，只把要讲的那一处做清楚；数字对比直接用界面元素画出来，例如两条长短不同的进度条，而不是另做一张图表。
+
+## 文件与说明
+
+- 按显示尺寸的 2 倍导出，不直接内嵌原始大图。不透明的图用 JPEG 或 WebP，透明的用 WebP 或 PNG；单张控制在几百 KB 以内。内嵌成 data URL 后体积会再大约三分之一。
+- 保留提示词、原图和处理后的版本，写清每张图的用途和处理方式。
+- 生成图不冒充真实产品、真实场所或真实人物。虚构产品的小样，在页脚注明图片由 AI 生成。

oil-ui-pro/references/interaction-and-state.md

@@ -0,0 +1,111 @@
+# 交互与状态
+
+## 先走通用户任务
+
+用一条主要路径说明：从哪里进入、识别哪个对象、作出什么决定、执行哪个动作、看到什么结果。只展开当前范围相关的分支，不为一个小表单设计整个产品流程。
+
+浏览、比较、选择和编辑是不同任务。列表用适合比较的身份、数据或预览；只读详情不默认铺满禁用输入框；用户明确进入编辑后再显示需要的控件。需要连续批量配置的工作表可以持续编辑，但必须有一致的对象与保存语义。
+
+同一对象与动作沿用统一名称。品牌表达可以改变外观，不随意改变返回、关闭、保存、删除等熟悉动作的含义。
+
+## 对象身份
+
+一个对象靠四样东西认出来，按顺序取，够区分就停：
+
+1. **视觉身份**：缩略图、头像、封面、Logo 或媒体帧。同一对象在各处用同一裁切和比例；加载失败时用稳定的兜底图，并保留名称。
+2. **主名称**：用户平时称呼和搜索用的名字。
+3. **区分字段**：同名或相似对象之间最能区分的一个字段。
+4. **影响判断的状态**：只在它会改变选择或操作时显示。
+
+数据库 ID、看不懂的长文件名、所有对象都一样的类型标签、装饰图标、截断后彼此相同的文字，都不能充当身份。
+
+选择器首先是对象识别器，不是字符串下拉框。选项显示图片、名称和必要的区分字段；收起后仍显示足够的身份，用户不用重新打开就能确认选了谁；搜索覆盖名称和区分字段；已选对象不在当前分页或筛选结果里时，仍然显示。
+
+把这四样做成一个共享的对象身份组件，列表、表格第一列、选择器、已选结果和详情标题都用它。
+
+## 列表、表格与详情
+
+列表只回答三件事：有哪些对象，它们在决策上有什么不同，该打开哪一个。每项只放身份、一个影响判断的状态、比较所需的最少字段、整项点击和“更多”。完整分析、证据、关联对象、编辑和历史放进详情。
+
+- **表格还是卡片**：要横向比较同一字段（数值、状态、日期、价格）用表格；主要靠图片和内容挑选用卡片或列表；每项主体是长文或完整媒体时不压进表格行。同一类对象在整个产品里只保留一种主要形态，只有用户确实有两种任务时才提供视图切换。
+- **每一列都要有答案**：它帮助比较、表达状态、需要直接修改，还是可执行操作？答不上来就删，不把详情字段逐列搬进表格。用来识别对象的那一列放在最前，横向滚动时固定；单位写在表头，不在每个单元格里重复。
+- **一个单元格只做一件事**：识别、比较、状态、编辑或操作中的一种。不在单元格里拼“预览 + 状态 + 数量 + 按钮”的迷你卡片；状态只在固定的一列表达一次；行级动作放固定的操作列，不在内容下面再排一行按钮。
+- **批量**：只有真的存在批量动作时才显示多选框。筛选变化后不静默操作看不见的已选项：要么清除隐藏的选择，要么写明数量和范围。
+- **点击**：卡片主体和“查看”按钮不做同一件事；整张卡可点时，卡内的独立控件不触发外层点击。编辑完成后回到原行，原行显示最新状态。
+
+## 动作层级
+
+| 层级 | 用途 | 呈现 |
+| --- | --- | --- |
+| 主操作 | 完成这个区域的主要任务 | 一个高强调按钮，写成“动作 + 对象”，例如“发送报价” |
+| 次级操作 | 高频但不是主要任务 | 低强调文字按钮 |
+| 管理操作 | 重命名、复制、重新处理、可撤销的删除 | 收进“更多”，菜单项写文字 |
+| 危险操作 | 不可恢复或损失大 | 在菜单里用分隔线隔开，并确认 |
+
+可撤销的操作直接执行并提供撤销，不再确认；不可撤销的操作确认时写出对象和后果，按钮写动作，例如“删除 3 个文件”，不写“确定”。同一区域出现两个高强调按钮，就重新判断主任务。“处理”“管理”“继续”这类词说不出结果，换成动作加对象。次级操作可以在悬停、聚焦或选中该项后出现，但要预留位置、不挤动内容，触屏上要有等价入口。
+
+每个可见动作都要有真实结果：数据变化、明确范围的预览、可观察的任务状态、导航，或者复制、下载这类本地结果。没有写入能力就不显示写操作，不用长期禁用的按钮占位；当前状态不允许的菜单项直接隐藏，不留无法解释的灰色图标。
+
+帮助文案只解释界面推断不出的规则、限制和风险；先修正标题、默认值或结构，不用长说明弥补流程混乱。使用原生或已有可靠控件，保持标签、焦点、键盘操作与可访问名称；校验和重要状态不只用颜色或悬停提示表达。
+
+## 表单与提交
+
+只收集当前任务必需且无法可靠带入的信息。系统已知的值合理预填，需要用户判断的值保留可编辑性；数据属于其他对象时说明来源，不能悄悄改写源对象。
+
+相关字段形成清楚的提交边界。一次用户意图只提交一次，处理中防止重复操作；结果即时生效时不再增加无意义的保存。
+
+只有字段依赖、错误代价或任务长度确实需要时，才增加步骤、预览、草稿或额外确认。行内编辑适合简单独立字段；复杂关联编辑进入能容纳完整任务的表面。
+
+校验在能够修正的位置显示原因和修正方式。提交失败保留输入、当前对象和位置；返回上一步或从源数据编辑返回时维持流程连续性。
+
+## 按范围表达状态
+
+| 情况 | 界面要表达的内容 |
+| --- | --- |
+| 首次加载，尚无内容 | 在最终内容区域提供适量占位或进度，保持结构稳定 |
+| 刷新或筛选，已有内容 | 保留可用内容并标示正在更新，不把旧结果误当成新查询完成 |
+| 集合确实为空 | 说明原因，并给适合当前任务的开始动作 |
+| 搜索或筛选无结果 | 保留查询条件，提供调整或清除条件的方式 |
+| 局部提交 | 在触发位置表达处理中，保持按钮尺寸，防止重复提交 |
+| 后台长任务 | 给对象明确的排队、处理中、完成或失败状态及必要进度 |
+| 加载或提交失败 | 在相应范围解释原因和恢复动作，不要求用户重新寻找对象 |
+
+同一范围不同时表达互相矛盾的状态。局部请求不清空整页，进度不重复堆叠，等待结果不伪装成空集合。
+
+占位布局应接近实际内容，不制造额外滚动。已有数据刷新时保持结果、数量与查询条件的对应关系；快速连续操作后只呈现当前意图对应的结果。
+
+## 模型在交互上的默认做法
+
+这些做法单看都说得过去，所以模型会不假思索地用。出现时换成右边的做法：
+
+| 默认做法 | 换成 |
+| --- | --- |
+| 首页开头四张指标卡，数字没有比较基准，也引不出动作 | 首页回答“现在该处理什么”，见设计方向的“产品界面” |
+| 可撤销的操作也弹确认框 | 直接执行并提供撤销；只有不可撤销的操作才确认，见“动作层级” |
+| 所有反馈都用角落里的浮动提示，包括错误 | 反馈出现在触发的位置；错误留在原处直到解决。浮动提示只用于离开视线的结果，例如已复制、已发送 |
+| 一加载就整页转圈 | 保留已有内容，只在变化的区域标示更新，见“按范围表达状态”和下文数字 |
+| 空状态只有一张插图和“暂无数据” | 说明为什么空、下一步做什么，给一个能直接开始的动作；能导入或预填示例就提供 |
+| 字段一字排开，用占位文字当标签，提交后才一起报错 | 标签常驻在输入框上方，按任务分组；离开字段时校验，提交出错时聚焦到第一个错误并说明怎么改；少数可选字段标“选填”，不给满屏必填项加星号 |
+| 按钮禁用，却不说为什么；每行末尾一排图标按钮；必要按钮只在悬停时出现 | 按“动作层级”重排：主操作一个，管理操作进“更多”，触屏和键盘都能到达 |
+| 详情和设置默认用弹窗 | 按任务选择弹窗、侧面板或完整页面，见布局与视口的“选择承载方式” |
+| 表格所有列等宽、居中 | 按“列表、表格与详情”删掉答不出用途的列；对齐方式见视觉语言的“细节” |
+| 按回车才搜索，无结果时只写“无结果” | 输入即筛选（请求较重时防抖 150–300ms）；无结果时保留查询，给出放宽条件或清除的入口 |
+| 一两个字段也拆成多步向导 | 只有步骤之间确实依赖时才分步；否则一页完成，并能看到全部范围 |
+| 保存后跳回列表，看不出刚改的是哪一条 | 回到原位置，把刚改动的对象高亮 1–2 秒 |
+
+## 有数字的底线
+
+- **响应**：100ms 内给出按下反馈。300ms 内能完成的操作不显示加载，避免一闪而过；超过 1 秒显示骨架或进度；超过 10 秒显示进度，并允许离开后回来查看。加载指示一旦出现，至少停留 400–500ms。
+- **对比度**：正文与背景至少 4.5:1；大字（约 24px 以上，或 19px 以上的粗体）、图标和控件边界至少 3:1。
+- **点击区域**：触屏至少 44×44pt（Android 48dp），相邻目标之间留 8px；桌面指针目标至少 24×24px。
+- **文字**：手机上的输入框文字不小于 16px，否则 iOS 聚焦时会自动放大页面。正文字号和行高见 [视觉语言](visual-language.md) 的“可读性是交付门槛”；阅读型正文每行中文 25–40 字、英文 45–75 个字符。
+- **提示停留**：普通提示 4–6 秒，带撤销的 5–10 秒；鼠标悬停在提示上时暂停计时。重要错误不用会自动消失的提示。
+- **键盘**：Esc 关闭浮层，并把焦点还给打开它的元素；Enter 提交单行表单；弹窗打开时焦点落在第一个输入或主按钮上，Tab 不跑到弹窗外面。
+
+## 确认与完成
+
+需要等待结果的操作有可观察的生命周期。提交后保留对象与反馈；同步完成后再呈现成功，失败时保留恢复入口。
+
+可以关闭表面的后台任务，应已转为可持续观察的任务状态。关闭窗口不是取消请求；没有真实取消能力时，不把关闭或取消描述成已撤回操作。
+
+关键保存从界面重新读取或重新进入验证。模拟原型可以演示状态，但交付时明确模拟边界，不声称真实数据已写入。

oil-ui-pro/references/layout-and-viewport.md

@@ -0,0 +1,60 @@
+# 布局与视口
+
+## 先定空间责任
+
+明确首屏重点、内容的伸缩方式、滚动区域与主要操作的位置。任务型界面减少无意义滚动；叙事型页面允许有意的长度与节奏。不能为了单屏把文字和控件缩小到难以使用。
+
+区分全幅背景、限宽正文、弹性区域和固定规格控件。布局由内容、父容器、比例与上下限共同决定，不把整张设计图按比例缩成网页。
+
+宽屏可并列需要同时参考的信息，窄屏按任务顺序重排。是否分栏取决于内容关系，不默认所有页面都是左文右图。
+
+## 内容与伸缩
+
+- 文字与可变数据采用内容驱动尺寸。固定规格用于图标、点击区域、媒体比例或稳定几何，不用于让当前截图刚好装下。
+- 让长名称和宽内容能够合理收缩、换行或局部滚动。网页中的 Flex/Grid 子项必要时设置收缩边界，不用全页裁切掩盖溢出。
+- 图像明确尺寸、裁切与主体安全区；异步内容预留合适空间，避免加载后挤走操作。
+- 把真实组件或页面放进固定大小的缩略窗口（组件目录、模板墙、样张）时，按内容的自然尺寸缩放进窗口，不要居中后让上下两头一起被裁掉。先保证宽度放得下；太高的内容缩到还能读的比例后顶端对齐，底部渐隐。随容器伸缩的组件在缩略窗口里没有自然宽度，会被挤成一列竖排字，要按真实使用时的宽度渲染再缩放。
+- 响应式验证覆盖项目支持的代表性宽度，断点由内容失效的位置决定。不同视口允许重排，不强求像素比例一致。
+
+## 滚动由谁负责
+
+每个表面只有一个主滚动区：应用外壳固定时，主内容区滚动；弹窗只有正文滚动；表格只在自身容器里横向滚动。确实需要分别浏览的面板才有自己的滚动，并且要有明确的尺寸和任务边界。
+
+- Flex 和 Grid 的子项要允许收缩（最小宽高设为 0），否则长内容会撑破父容器，出现整页横向滚动。
+- 不让页面、内容区和弹窗同时滚动；不为溢出随手加 `overflow: auto`；不做没有独立任务边界的多层嵌套滚动。
+
+## 选择承载方式
+
+| 任务 | 承载 | 要点 |
+| --- | --- | --- |
+| 短而自包含：确认、简短表单、预览加配置 | 弹窗 | 宽度随内容：确认用窄的，表单用中等，预览加配置用宽的或双栏 |
+| 需要保持底层列表、表格或画布可见 | 侧面板 | 从当前对象出发的查看或编辑；关闭后回到原对象 |
+| 多步骤、复杂创作、大量媒体，或需要两个以上主滚动区 | 完整页面 | 任务本身就是目的地，不是某页的附属动作 |
+
+不在弹窗上再叠弹窗，需要第二层完整任务时升级为侧面板或页面。沿用项目已有的表面组件，不为一次需求另建一套。
+
+弹窗固定分三段：
+
+- **标题栏**固定在顶部：标题、必要的对象身份和关闭入口。
+- **正文**占剩余空间，是唯一的滚动区。
+- **操作栏**固定在底部，跨满弹窗宽度：主操作在右，取消紧挨着它，危险确认单独隔开；计数或校验摘要放在左侧。
+
+弹窗高度用“内容上限 + 动态视口高度”约束，不用固定高度。纯阅读的弹窗只留关闭入口。关闭或返回后，回到原来的位置和对象。
+
+## 菜单与浮层
+
+浮层贴着触发器出现，空间不足时翻转或平移，保留视口安全边距。它要渲染在能脱离裁切的层上，不被表格、弹窗或滚动容器截掉；页面滚动、容器滚动和窗口缩放后重新定位；触发器消失时关闭。长名称按对象身份的规则截断，不撑大浮层；内容超出下拉能清楚承载的范围时，改用弹窗或完整页面。单选选完即关，多选在点“完成”或点击外部时关闭。关闭后不留下遮罩、滚动锁或看不见的点击层。
+
+## 精准还原
+
+先记录参考图的逻辑视口或已知像素尺寸、完整范围和固定区域。图像像素不等于逻辑视口；无法确定时说明假设。
+
+测量主区域比例、共享对齐线、文字尺度、图片裁切与间距关系。先对齐整体几何与字体，再处理边框、阴影和细节；不因还原任务重新探索风格。
+
+用与参考相当的视口和内容检查差异。参考没有展示的窄屏与状态根据内容约束补充，并区分“参考还原”与“合理延展”。
+
+## 验证重点
+
+实际检查长内容、空内容和当前改动相关状态。移动端注意视口变化、输入面板与安全边距，主操作不能被键盘或固定区域遮挡。
+
+检查页面是否意外横向溢出、滚动是否发生在预期区域、焦点与菜单是否可见，以及缩放或重排后阅读和操作顺序是否仍然清楚。

oil-ui-pro/references/media.md

@@ -0,0 +1,45 @@
+# 素材
+
+## 把资产作为设计起点
+
+好的资产可以承担整个页面的情绪、对象识别或信息重心。先问“如果只保留一张图、一个标题和一个动作，哪张图值得占据这个位置”，再决定是否需要更多模块。不要把资产理解为布局完成后填进去的装饰。
+
+跟随设计北极星决定图像的主体、视角、尺度、光线、颜色、材质和留白。页面的字体、背景、边缘处理与运动从这张图建立呼应；也可以通过一个受控的反差突出主动作。统一是共享视觉逻辑，不是对所有图片套同一个滤镜。
+
+后台和工具同样需要资产判断：对象缩略图帮助识别，内容封面支持浏览，地图或空间图帮助定位，必要的示意图解释关系。它们可以成为界面最有价值的部分；不以“这是后台”为由默认只有表格和卡片。纯数据任务确实不受益时保留清楚的数据表达，不硬塞气氛图。
+
+资产要成为结构，而不是装在盒子里的插图：让它跨过版面的分界、占满首屏，或者和文字叠在一起。页面可以是一个完整的世界，而不是“一张页面配一张图”。
+
+先把关键资产放进真实页面看一轮，再延展其他区域。资产未到位时不能把占位版的审美评审视为最终通过。
+
+没有合适的现成资产且宿主已有可用的图像生成能力时，主动制作关键素材，并给它明确的视觉任务；不要因为正在写前端代码就省略这一步。已有优秀素材时围绕它设计，不为证明使用了工具而重复生成。没有相关能力时保留清楚的素材简报与待完成项。
+
+## 先确定表达作用
+
+判断当前差距来自信息与构图，还是缺少能够表达产品和品牌的素材。不要用更多图片、光效和动画掩盖层级问题，也不要仅因代码容易编写，就用通用渐变和几何形状替代必要的图像。
+
+素材可以用于展示对象、解释关系、建立品牌或情绪。先确定内容、位置、尺寸比例、裁切、背景和与文字的对比，再选择现有资源、摄影、插画或生成素材。
+
+素材简报保持可执行：要表达什么、主体是什么、放在哪、宽窄屏如何裁切、哪里承载文字、什么细节不可丢失。若画面已经表达了主题，减少重复解说；叠字区域需有稳定明暗和足够空间，不默认给整张图盖浓重渐变。
+
+## 图片与可编辑界面
+
+实际查看输入图片后再引用其特征。复用质量合适且有使用依据的资源；不足时才生成或重绘。保留原始文件及来源，区分复用、裁切、生成和后处理。
+
+界面文字、按钮、表单、数据标签和常规布局由可编辑元素表达，摄影、插画和特殊视觉放在明确容器中。不把完整截图作为可交互成品。
+
+将素材需求交给宿主可用的生成工具，遵循工具自身的输入与编辑规则。怎样让生成图承担意思、怎样写提示词、怎样把图和页面接成一体，见 [配图](imagery.md)。
+
+图像暂缺时预留合适容器并明确缺项，不自动安装工具、切换收费服务或要求用户把密钥粘进对话。替代素材不能冒充真实产品截图。
+
+同组资产统一主体尺度、视角、光线和边缘质感，避免几张各自漂亮却互不相干的图拼在一起。生成素材不冒充真实现场或产品证据。最终交付保留来源与用途，网页按实际显示尺寸处理文件体积，重要主体在桌面和手机裁切中都必须成立。
+
+## 生成视频的可选路径
+
+需要可叠加的循环素材时，先验证首尾衔接、主体边缘和背景处理。单色背景加抠像只是候选技术；透明、反光物体可能丢失边缘或产生色溢，应在最终页面背景上检查。
+
+需要连续叙事时，可以用前一段的末帧衔接下一段的首帧，或使用一致的关键帧规划。按滚动或手势控制播放进度时，检查寻帧、反向播放、加载和内存占用，不默认把整段视频解码成全部大图。
+
+玻璃、水晶这类需要折射或透光的物体，先在最终页面的背景色上生成画面，让折射和投影烘焙进素材，再用视频抠像模型去掉背景。直接在绿幕上生成再抠像，折射会带着绿色。预渲染的折射和光照只对应生成时的背景，不应承诺会随任意页面内容产生实时物理效果。
+
+透明底的图片或视频适合放在两个区块的衔接处，跨越边界，把上下两部分连成一个画面，比放在容器里更有设计感。

oil-ui-pro/references/motion.md

@@ -0,0 +1,128 @@
+# 动效
+
+## 每个界面先做三处动效
+
+完全不动的界面像一张截图：按下没有回应，切换没有来路，用户只能猜刚才发生了什么。新界面和改动了操作流程的界面，先把这三处做出来，手感写进方向卡的“动效”一栏：
+
+1. **主操作的反馈。** 按下立刻有回应，完成时交出一个结果：按钮陷下去再弹回，勾号画出来，数字滚到新值。
+2. **一处状态切换的来路。** 选中、展开、换视图、增删列表项时，让人看见东西从哪里来、到哪里去，见下文“界面过渡”。
+3. **第一次进入时的一次出场。** 主角先到，其余按阅读顺序跟上，只在首次进入时播放。
+
+这三处之外再加动效，先问：如果要手写一周才能做出来，还值得做吗？模型让动效变得免费，但滚动淡入、视差、跟随鼠标和装饰性循环最容易变成干扰。每个动效都要承担反馈、引导、连续或品牌表达中的一项。
+
+| 目的 | 适合考虑的方式 |
+| --- | --- |
+| 按下、聚焦、展开或普通状态变化 | 原生能力或已有组件的小范围过渡 |
+| 视图之间的切换、元素换位置 | 共享元素过渡，见下文“界面过渡” |
+| 拖拽、手势、空间变化与复杂编排 | 项目已有成熟动效能力 |
+| 特殊品牌画面、材质、复杂物理效果 | 图片、3D、着色器或预渲染视频，按需求取舍；着色器能做的效果见 [点缀与特效](ornament.md) |
+| 鼠标、触控或滚动控制叙事进度 | 将输入映射到明确的动画进度，处理反向和快速操作；思路见下文“滚动叙事” |
+
+代码动画适合需要精确状态控制的界面，生成视频适合预先确定的视觉变化；不能用视频替代需要动态数据与真实操作的控件。
+
+## 手感
+
+动效的手感从方向的材质和调性推出，用“动作 + 实物”来命名和选参数（弹簧刚度 / 阻尼）：
+
+| 动作 | 实物参照 | 刚度 / 阻尼 | 适合 |
+| --- | --- | --- | --- |
+| 咔嗒 | 磁铁吸合、卡扣、拨动开关 | 350–400 / 10–15 | 按钮、开关、下拉展开 |
+| 滑入 | 气压闭门器、抽屉阻尼 | 250–300 / 20–25 | 底部面板、抽屉、折叠 |
+| 流淌 | 倒蜂蜜、雾气弥散 | 150–200 / 30–40 | 页面转场、主视觉出现 |
+| 砸落 | 锤击、重物落桌 | 400–500 / 5–10 | 确认选择、完成反馈 |
+| 回弹 | 橡皮球、蹦床 | 300 / 8 | 庆祝提示、儿童与游戏 |
+| 漂浮 | 氦气球、飘絮 | 100 / 25 | 冥想、梦幻场景、空闲循环 |
+
+重的材质（石、金属、陶）偏咔嗒和砸落，轻的材质（纸、布、雾）偏漂浮和流淌；高频操作用短促的动作，少见的品牌时刻才用绵长的。喧闹粗粝的方向可以用硬切、80–150ms 的线性跳变和抽帧，作为有意的品牌表达；被禁止的只是没有考虑过的默认缓动。
+
+过冲幅度跟着面积走。整页、面板这类大面积的东西，过冲不超过 1–2%，否则整块画面会晃；徽章、勾选标记这类小东西可以过冲 10–20%，显得有弹性。表里阻尼偏低的参数只用在小物件上。
+
+网页可以把弹簧写成缓动曲线：按刚度和阻尼对位移做数值积分，取 20–30 个采样点写进 `linear()`，时长取位移稳定在终点 0.5% 以内的时刻。不支持的浏览器退回相近的 `cubic-bezier`。
+
+## 呼应：让动作彼此接上
+
+生硬的动效各动各的：按钮自己闪一下，面板自己滑出来，数字直接换掉。好的动效像一句话：一个动作引起的变化沿同一条路传下去，前一段的终点是下一段的起点。
+
+- **从被操作的地方出发。** 点“加入购物袋”，商品缩成一个点飞进袋子，袋子上的数字跟着跳一下；删掉一行，它朝删除按钮的方向收走，下面的行补上来。
+- **一次切换朝一个方向。** 卡片往左滑，标题、序号和底色也往左换；数字往上滚，进度也往上涨。方向一乱，就成了几段互不相干的动画。
+- **主角先动，其余被带动。** 被影响的东西晚 40–80ms 跟上，幅度更小，像被主角拉过去的。全部同时起跑、同样幅度，看起来只是一起闪了一下。
+- **形状接力。** 上一个状态里的元素变成下一个状态里的元素：按钮展开成面板，搜索图标拉长成输入框，播放键变成暂停键。用户一眼看出它们是同一个东西。
+- **动法和画面是同一种材质。** 纸面的方向，切换轻、有一点停顿；硬件的方向，开关有咔嗒到位的感觉；液体和玻璃的方向，用流淌和折射。
+
+### 巧思从产品里找
+
+巧思是让一处动效讲出这个产品自己的事，不是加更多花样。从内容里找一个只有它才有的动作：
+
+- 天气应用切到雨天，雨点落在卡片上；雨停以后，卡片上的水痕慢慢干掉。
+- 记账应用记下一笔支出，预算条少掉的那一截落进这笔账里。
+- 音乐播放器换歌，新封面的颜色从唱片中心漫到整个背景。
+- 完成待办时，勾号用和品牌标志相同的笔画画出来。
+
+找不到这样的动作，就把三处基本动效做准，不硬造。一页最多一两处巧思，其余动效安静、短促。
+
+## 界面过渡
+
+**连续。** 用户点的东西就是下一屏的主角。从列表进入详情，被点的那一项放大成详情，其他项淡出；返回时它缩回原位，页面回到原来的滚动位置。原位已经不在视口里，就先把它滚到可见，再缩回去。
+
+**方向一致。** 下一项从右边进，上一项从左边进；打开和关闭互为逆过程；侧面板从它所在的那一侧滑入滑出。方向随意的动画比没有动画更让人迷惑。
+
+**只变形状时不做交叉淡化。** 切换视口、筛选、展开说明、缩放，这类变化里内容还是同一个东西，只是尺寸和位置变了。让外框直接变形，内容立即显示新状态。交叉淡化会让新旧两张缩放不同的画面叠在一起，出现重影。只有内容本身换了，才淡入淡出。
+
+**离开、加入、留下分开处理。** 被移除的淡出，新加入的淡入，留下的滑到新位置。三者用同一种淡化，列表就会整片闪烁。
+
+**选中指示用一块会移动的滑块。** 分段控件、标签页、列表当前项，都用同一块底板滑到新位置，而不是旧的熄灭、新的点亮。选项宽度不同时，宽度一起过渡。首次显示、窗口缩放和字体加载完成后直接放到位，不要从 0 宽度长出来。
+
+**先准备好目的地。** 目的地要加载的内容，例如图片或内嵌页面，先加载或预先渲染好，否则动画会停在一块白屏上。需要来回切换的视图预先渲染并留在页面里，切换时只移动，不重新加载。内容加载完成后再淡入，不先闪一下白底。
+
+**离开比进入快。** 退出时长约为进入的 60–70%，用加速曲线；进入用减速曲线或弹簧。
+
+**到头要有反馈。** 已经是第一项或最后一项时，轻轻顶一下（往返 10–15px），而不是毫无反应。
+
+## 时长和幅度
+
+| 对象 | 时长 | 要点 |
+| --- | --- | --- |
+| 按下、开关、选中指示 | 150–300ms | 按下缩到 0.96–0.98，按下时立即生效（约 80ms），松开再弹回 |
+| 下拉、气泡、提示 | 180–250ms | 从触发点方向展开，缩放从 0.96 左右开始，不从 0 开始 |
+| 面板、抽屉、侧栏 | 250–400ms | 按移动距离取值，越远越长 |
+| 整页或视图切换 | 350–500ms | 超过 500ms 就会让人等 |
+| 首次进入时依次出现 | 每项间隔 40–80ms | 总长不超过 600ms；只在首次进入时播放，重新渲染和恢复状态时不重播 |
+
+悬停上浮 2–4px，阴影随之加深。位移超过 20px 的悬停效果会显得轻浮。
+
+## 看不见的结果要说出来
+
+一次点击产生了看不见的副作用，例如复制到剪贴板、后台保存、发送，就用一条短暂的提示说出结果本身，例如“已复制：……”，而不是只说“成功”。确认类的时刻，例如选中或完成，可以用一次小幅弹出，只在状态第一次变化时播放，重复点击不重播。
+
+## 滚动叙事：视差与一镜到底
+
+滚动当作翻页，它只是翻页；当作摄影机的推拉，页面就能讲故事。品牌、发布和叙事页可以这样做，文档、文章、工具和后台不做；一页最多一段。记忆点先放在用户会做的动作上（点按、拖动、悬停），再考虑滚动；不要把整页做成视差秀。
+
+- **一镜到底。** 整段是一次不切换的镜头。一个主角从头走到尾，可以是产品、一根线、一个形状或一个字，每一步长成、变成或让出下一个画面：推近看到细节，拉远看到全貌，转过去看到背面，穿过去进入下一个场景。动手前先画分镜：每个镜头占多少滚动距离、画面里有什么、什么在动、文字什么时候出现。
+- **停下来再说话。** 每个镜头留一段静止，文字在静止时出现；边动边读很累。
+- **视差要有真实的前后。** 只在画面本来就有远近层次时用：前景的物体、中景、远处的背景，越近动得越多，差别要小。文字不做视差。
+- **转场也是镜头。** 一个圆从某一点扩开，带出下一节；推进一张图，穿过它到达下一节；背景色在章节之间随阅读慢慢变；一句宣言随滚动逐字亮起。每种手法一页只用一次。
+- **倒着滚也成立。** 每一帧只由滚动位置决定，往回滚自然倒放，刷新或跳到中间也立刻是对的画面。不接管用户的滚动。
+- **留出口。** 长段落前给一个跳过入口；减少动态效果时，把每个静止画面按顺序排成普通区块。
+- **代码做不出来的，交给视频。** 用户想要很强的首屏动画，而效果要靠生成视频或序列帧才做得出来，例如角色转身、产品拆解、镜头穿越场景，可以告诉用户用 [oil-motion](https://github.com/oil-oil/oil-motion) 来做。CSS、SVG、着色器能完成的仍自己做；同一次对话只提一次。
+
+## 体验与性能
+
+沿用项目的运动节奏和组件能力。高频操作反馈直接，不让动画延迟业务完成。
+
+动画要能被打断。连续快速操作时，新动画从当前位置接着走，不跳回起点重播。CSS 过渡会从当前值重新出发，适合高频切换；关键帧动画会从头重播，适合一次性的出场。业务状态立即更新，不等动画结束。
+
+网页连续动画优先用变换与透明度，只声明需要变化的属性；小尺寸的指示块可以直接过渡宽高。逐帧工作要有停止和清理条件，避免频繁交错读写布局，离屏或无任务时停止播放。整页过渡期间页面通常不响应点击，所以整页过渡要短。
+
+明显位移、缩放和滚动特效，要为“减少动态效果”提供等价呈现，此时所有状态直接到位。必要信息和主要操作不能依赖自动播放、声音或动画完整结束。
+
+## 检查动效
+
+静态截图证明不了动效。三处基本动效和动效记忆点都要留证据：一段 3–5 秒录屏，或开始、中间、结束三帧，并写明触发它的动作。把播放速度调到 10%，可以用浏览器开发者工具的动画面板，或自动化工具里的动画倍速，在过渡进行到一半时截图。看有没有重影、跳动、元素突然出现，或者从奇怪的位置飞来。逐个检查开始、中间、结束和反向；再快速连按几次，确认不会卡在中间状态。最后开启“减少动态效果”再走一遍。只有实际测量后才报告帧率或性能改善。
+
+## 网页实现提示
+
+- 浏览器原生的视图过渡适合做“同一对象从一处变到另一处”：给前后两个状态里代表同一对象的元素起同一个过渡名，名字在同一时刻必须唯一。
+- 只变形状的过渡里，隐藏旧快照、直接显示新状态，就不会出现重影。
+- 过渡伪元素后面只能跟少数伪类，例如 `:only-child`；写成 `:not(...)` 会让整条规则失效。需要按场景区分规则时，在根元素上加一个属性来切换。
+- 内嵌页面和图片在过渡里会被截成快照；目的地没加载完就开始过渡，会以空白结束。

oil-ui-pro/references/ornament.md

@@ -0,0 +1,82 @@
+# 点缀与特效：SVG 和着色器
+
+这里讲用代码画出来的视觉效果：小到一条手绘下划线、一层颗粒，大到首屏整片流动的渐变、扫过按钮的一道流光、由点阵组成的主视觉。它们能让方向从“配色对了”变成“有生命”；做得粗糙时，就是又一层模型默认的装饰。
+
+## 先问要不要
+
+- **从生成引擎里来。** 效果要能说出属于这个方向的理由：方向的关键词是“信号”，点阵和扫描线才成立；是“流体”，流动渐变才成立。删掉它，方向会少一点自己的东西；删掉后没有区别，就不加。
+- **一个主效果，几处回响。** 一页选一个主效果，其余地方只用它的颜色、形状或节奏小声呼应，比如首屏是流动渐变，按钮的流光就用同一组颜色。几种特效各自为政，页面就成了效果展示。
+- **不碰内容。** 效果不压在正文、数据和控件上，也不画得像按钮；在它上面的文字，按最差的一帧检查对比度。
+- **用代码画。** SVG 和着色器体积小，跟着主题色走，放大也清楚。摄影和复杂插画才用图片，见 [素材](media.md)。
+- **质感先来自材质。** 顶尖的产品界面很少用流光、渐变团和着色器，让人记住的多是写实的材质、准确的结果和手感。特效是给少数方向的，不是提升质感的默认手段。
+- **产品界面收着用。** 后台和工具的工作区不放持续运动的效果；登录、空状态、完成反馈和品牌页可以放开。
+
+## SVG 能做的几类
+
+| 效果 | 做法 | 要注意 |
+| --- | --- | --- |
+| 颗粒质感 | `feTurbulence type="fractalNoise"` 生成噪声，`feColorMatrix` 把它染成页面的颜色并控制透明度，写成 data URI 平铺成 `background-image`。细颗粒 `baseFrequency` 约 0.8–0.9、透明度 0.05–0.08；再叠一层约 0.004 的大块起伏，表面就不是均匀色块 | 加 `stitchTiles="stitch"` 避免拼缝。做成固定尺寸的平铺图，不把 `filter` 挂在整页或滚动容器上，否则每次重绘都要重算。只在方向本身有实物材质时加，不当作提升质感的通用补丁 |
+| 手绘框、粗糙边缘、大号数字的毛边 | `feTurbulence` 接 `feDisplacementMap`，`scale` 约 1.5–3。同类图形各换一个 `seed`，不要一模一样 | 正文不加；`scale` 太大像坏了。滤镜区域默认只向外留 10%，位移、光晕和投影会被裁掉，给 `filter` 设足够的 `x`、`y`、`width`、`height` |
+| 沿弧线或环形排字 | `<textPath>` 配 `startOffset="50%"` 和 `text-anchor="middle"` 居中 | 字放在弧的外侧；放在内侧，字距被挤压，字形会相撞。手机换一套 `viewBox` 重新取景，不只是等比缩小 |
+| 下划线、轨迹、连接两处内容的引线 | `path` 加 `stroke-linecap="round"`；缩放时线宽不变用 `vector-effect="non-scaling-stroke"`；描线动画设 `pathLength="1"` 和 `stroke-dasharray="1"`，让 `stroke-dashoffset` 从 1 走到 0 | 引线两端要真的指向内容。让光点沿线流动：用一段短虚线加长间隔，动画 `stroke-dashoffset`，再叠一份模糊的副本当光晕 |
+
+颜色统一用 `currentColor` 或设计变量，让效果跟着主题和深色模式变。
+
+## 着色器能做什么
+
+| 效果 | 核心做法 |
+| --- | --- |
+| 流动渐变 | 3–5 个颜色点沿各自的慢速轨迹移动，按距离混合；要更像液体，用噪声扭曲坐标再取噪声（domain warping），纹路会像大理石或油彩那样流 |
+| 极光和光带 | 在一个方向上拉长的噪声，叠加在深色底上，边缘用渐变遮罩收掉 |
+| 虹彩和镭射 | 用余弦调色板 `a + b·cos(2π(c·t + d))` 按角度或指针位置取色，四组参数就能调出整条连续的色带 |
+| 流光 | 一条两边柔化的亮带，按 20°–30° 斜角扫过形状，只在形状内部可见 |
+| 点阵和半调 | 把画面切成网格，每格按下面的亮度画一个圆点；动起来可以是波纹、指针附近的隆起，或者从点阵慢慢显出一张图 |
+| 像素和抖动 | 用 Bayer 矩阵做有序抖动，把颜色压成少数几种，得到一位色屏幕和早期游戏的质感 |
+| 跟随指针 | 指针附近的亮斑、扭曲或点阵隆起；指针位置先做惯性平滑，再传给着色器 |
+
+不少效果不需要 WebGL：边框上转圈的流光，用 `@property` 注册一个角度变量，驱动 `conic-gradient`，再用 `mask` 只露出边框；文字上的流光，用 `background-clip: text` 配移动的渐变；跟随指针的卡片光斑，把指针坐标写进 CSS 变量，驱动 `radial-gradient`。只有连续变化的噪声、逐像素计算或大量点阵时，才用着色器。
+
+## 做得高级的关键
+
+**渐变**
+
+- **在 OKLab 或 OKLCH 里混色。** 在 sRGB 里混两种对比色，中间会经过发灰发脏的一段；在 OKLab 里混，中间段仍然饱满。CSS 可以写 `linear-gradient(in oklch, …)`，着色器里先转到 OKLab 再插值。
+- **加抖动消色带。** 大面积平滑渐变在 8 位显示上会出现一圈圈色带，暗部最明显。输出前叠一层正负半个色阶的噪声，色带就消失了；把噪声加大到 3–8%，就是颗粒渐变的质感。
+- **配色从品牌来。** 紫蓝色的柔光团是最典型的模型默认。从设计变量里取两三个色相，挑一组不常见的搭配，再加结构：光带、点阵、颗粒，而不是再加一团光。
+- **光晕不要糊成白块。** 几层光叠加后会超过 1，直接截断会变成一片死白。用 `1 - exp(-x)` 这类曲线把亮部压回来，高光才有层次。
+
+**流光**
+
+- **亮带要窄、边要软。** 宽度约为元素的 15–25%，两侧用 `smoothstep` 柔化。
+- **扫过要快，间隔要长。** 单次 600–900ms、缓入缓出；在悬停、出现时播放，或每隔 4 秒以上扫一次。一刻不停地扫，就显得廉价。
+- **用提亮的混合方式。** `screen` 或 `plus-lighter` 让流光提亮底色，而不是刷上一层白。浅色底上几乎看不见流光，所以它更适合深色、饱和色或金属质感的表面。
+- **只在一个地方扫。** 通常是主按钮或一张主卡片。每张卡都在闪，就没有重点。
+
+**点阵**
+
+- **圆点面积跟明暗走。** 半径按亮度的平方根变化，面积才和明暗成正比，画面读起来才像原图。
+- **边缘要抗锯齿。** 用 `fwidth` 和 `smoothstep` 在一个像素的宽度内过渡（WebGL2 直接可用）。硬边的点动起来会闪烁、爬行。
+- **防摩尔纹。** 网格尺寸取设备像素的整数倍，或把网格旋转 15°、45°；彩色半调的每个通道用不同角度。
+- **没亮的点也画出来。** 屏幕式的点阵，熄灭的点保留很淡的一层，亮的点加一圈柔光，才像真的屏幕。
+- **格子大小决定读法。** 每格 6–12 CSS 像素读起来是质感，16 像素以上读起来是图形。
+
+**动起来**
+
+- **速度跟角色走。** 背景的循环慢到十秒以上，读正文时注意不到；交互反馈要在 150–300ms 内响应。
+- **指针要有惯性。** 每帧让当前位置向目标靠近一小步（例如 `current += (target - current) * 0.1`），效果才像有重量，不会一抖一抖地跟着鼠标。
+- **可以跟滚动绑定。** 把滚动进度作为参数传进去，让效果随阅读推进变化，比独立循环更有叙事感。
+
+## 成本与兜底
+
+- **分辨率按效果选。** 模糊的颜色场按 1 倍或一半分辨率渲染，再用 CSS 放大；点阵、像素和细线要按实际设备像素渲染，否则会糊。
+- **不引入 3D 引擎。** 只画一个全屏四边形时，直接写 WebGL 或用几 KB 的小工具库，不为它加载 three.js 这类完整引擎。
+- **看不见就停。** 滚出视口时用 `IntersectionObserver` 暂停，标签页隐藏时停掉 `requestAnimationFrame`；`prefers-reduced-motion` 时只画一帧静止画面。
+- **先写兜底。** 拿不到 WebGL、上下文丢失（`webglcontextlost`）或设备太弱时，显示同样配色的 CSS 渐变或静态图，页面照常可读。
+
+## 验收
+
+- 截几个不同时刻的画面，不只看第一帧；效果上的文字按最差的一帧检查对比度。
+- 100% 和 200% 下看点阵、颗粒和边缘；缩略图里看不出颗粒是正常的。
+- 浅色、深色和减少动效三种设置各看一次，再看一次兜底画面。
+- 在目标手机上看滚动是否掉帧、机身是否发热。
+- 装饰性 SVG 和画布加 `aria-hidden="true"`；承担意思的效果，例如由点阵拼出的标题，另给读屏能读到的真实文字。

oil-ui-pro/references/style-explorer.md

@@ -0,0 +1,82 @@
+# 风格对比页
+
+把几个候选放在同一页里并排比较，由用户挑选。用户可以并排或单张查看、切换桌面和手机、按实际尺寸看、筛选、选定并写备注。对比页的外壳只负责比较和挑选，不带风格倾向，也不作为候选的参考。
+
+先保持核心内容、主要动作和目标用户一致，再改变构图、信息组织、字体气质、色彩关系、密度与图像语言。数量按请求和有效差异决定，不复制整个产品来凑方案，也不把内置外壳的风格套给候选。
+
+对比页是视觉探索工具。HTML 小样默认不执行脚本和提交，标记为可操作的小样和本机地址候选除外（见“准备输入”）；需要真实数据、登录或后端的交互验收，仍在项目里进行。
+
+## 准备输入
+
+一轮只生成一个对比页，候选能跑就用真实页面：单独写的 HTML 小样直接嵌入，项目里的方案用本地地址。只有拿不到可运行的页面时才用截图。每个方案一个画面：存量项目选入口或差别最大的那一步，整站方案只放代表页，其他页面写进说明。手机版只在手机是主要设备时另出，不手写汇总页。
+
+在任务目录放置 `manifest.json` 和候选文件。HTML 候选为带 `head` 的文档，CSS 写在页面里。图片、字体和视频用相对路径引用任务目录里的文件，例如 `img/hero.jpg`，生成器会把它们内嵌进对比页；不要自己把图片转成 base64 写进候选，文件会变得很大、难以修改。不引用网络资源和任务目录以外的文件，链接只使用本页锚点。可以保留代码供独立打开，但比较页不执行其脚本。
+
+候选必须在不运行脚本时也能显示设计内容。依赖脚本生成界面的页面，先取得静态 HTML 或实际截图；不能把只有空挂载节点的应用入口交给对比页。
+
+候选内部不使用 iframe、object 或 embed 等嵌套文档；先将需要的内容转为静态页面或截图。另存的现有页面常带 `srcset` 或 `<picture><source>` 响应式图片，生成器会拒绝：改成一张用相对路径引用的 `<img>`，或直接用截图作为图片候选。
+
+图片候选支持 PNG、JPEG、WebP。实际查看图片并记录它代表的页面与状态，避免拿不同任务或不同状态的图比较风格。源文件必须位于 manifest 同目录或子目录。
+
+manifest 使用固定字段，结构如下。尖括号内是占位说明，全部换成本轮方向卡里的实际内容；不要沿用占位文字作为风格：
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "<项目名称>",
+  "brief": "<所有候选共同表达的内容与主要任务>",
+  "round": "<轮次，例如 01>",
+  "candidates": [
+    {
+      "id": "<小写唯一标识>",
+      "name": "<方向名称>",
+      "concept": "<北极星：一句能指导取舍的体验意图>",
+      "typography": "<实际使用的字族、字重与尺度关系>",
+      "palette": ["<十六进制色值>", "<十六进制色值>", "<十六进制色值>"],
+      "traits": ["<可观察特征>", "<可观察特征>"],
+      "kind": "html",
+      "source": "<候选文件的相对路径>"
+    }
+  ]
+}
+```
+
+自己写的可运行小样（单个 HTML、脚本内联），在 manifest 里给候选加 `"interactive": true`。单张查看时就能直接操作，对比页仍是可离线移动的单个文件，不需要服务器；卡片左下角标注“可操作”。这类候选只能运行内联脚本，不能联网或加载外部文件；浏览器存储换成页面关闭即清空的内存版本；`alert`、`confirm` 这类系统弹窗不会出现，需要确认时用页面内的对话框。
+
+已有仓库里要运行起来的应用（例如 React、Vue 项目），把 `kind` 设为 `url`，用 `url` 字段代替 `source`，指向本机开发服务器上的页面，例如 `http://localhost:5173/orders?variant=b`。这类候选在对比页里实时运行，脚本和表单照常工作，切换手机视口时应用会真实重排；卡片左下角标注“本地运行”。地址只能是 localhost、127.0.0.1 或 ::1；页面空白时，确认开发服务器已启动，且没有用响应头禁止被嵌入。这类候选要靠开发服务器才能看，所以：
+
+- 在 manifest 顶层写下启动方式，就是你刚才自己用过的那条命令：`"serve": {"command": "pnpm dev", "cwd": "<项目的绝对路径>", "url": "http://localhost:3456"}`。
+- 交付时让开发服务器开着，用户打开对比页看到的就是真实页面。
+- 服务没在运行时，对比页会提示用户在对话里说“打开对比页”，并附上这条命令。
+
+不默认另存截图版。用户要长期留档或发给别人时，再用 [工具](tools.md) 里的截图工具另截一份。
+
+给当前版本加 `"baseline": true`，它会排在第一位，编号显示为“现状”，其余方向从 01 开始编号。每轮最多一个基线。改动存量页面时，都把现状放进来，让每个方向都和它对照。
+
+`id` 使用唯一的小写字母、数字、连字符或下划线。`typography` 描述实际使用的文字关系，`palette` 使用十六进制颜色，`traits` 简述可观察差异。图片候选将 `kind` 改为 `image`、`source` 指向对应图像。
+
+## 生成和打开
+
+确认 Python 不低于 3.10，将脚本与输入输出参数解析为绝对路径后运行 [生成器](../scripts/build_explorer.py)：
+
+```text
+<python> <skill>/scripts/build_explorer.py <任务目录>/manifest.json --output <任务目录>/style-explorer.html
+```
+
+macOS/Linux 通常使用 `python3`，Windows 通常使用 `py -3`；执行前确认实际解释器。没有生成器运行能力时保留输入与候选供直接查看，说明尚未组装对比页，不临时重写另一套工具。
+
+默认拒绝覆盖。确实要更新已有本轮对比页时显式加 `--force`，或使用新的输出文件名。输入错误时保留旧产物；生成器不覆盖源候选，也不允许把运行产物写入 Skill 目录。
+
+用浏览器打开返回的本地 HTML。HTML 小样和截图已经内嵌，单个文件移到哪里都能看；本地地址候选要开发服务器开着。模板原文件只有空状态，不是用户最终对比页。
+
+用户之后说“打开对比页”时：读对比页旁边的 manifest 里的 `serve`，在 `cwd` 里后台运行 `command`，等 `url` 能访问了，再用浏览器打开对比页。端口被占用时先确认占着它的是不是同一个项目。
+
+## 查看与记录选择
+
+默认使用相同逻辑视口展示 HTML 候选：桌面 1280×900，手机 390×844。卡片等比缩放以便同屏比较；判断文字大小与细节时进入单张查看，使用“实际尺寸 100%”检查真实排版；适应窗口仍可能缩小，不能据此宣称可读性通过。切换手机视口后确认真实重排，而非仅看缩小后的桌面。
+
+点“选择”时会复制一句简短的文字，例如“<轮次>：选 03 <方向名>”，有备注时再附一行。用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到项目设计说明，继续实现。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
+
+## 检查实际结果
+
+核对候选：每张画面和 manifest 里写的页面、状态、视口一致，中文字体真实渲染出来了。对比页本身的并排、单张、筛选、复制和离线打开由 Skill 自带的回归测试保证，任务里不验证、不读模板源码，也不在用户自己的浏览器里清除任何存储。

oil-ui-pro/references/tools.md

@@ -0,0 +1,55 @@
+# 工具
+
+本目录自带的程序按下面的写法调用，不需要读源码；加 `--help` 打印同样的说明。
+
+宿主有自己的浏览器工具时，查看页面、走查流程照常用。要交出下面这几样标准证据时，优先用这里的截图工具：它开一个独立的临时浏览器，不碰用户自己浏览器里的数据。本机缺 Node 22，或者没有 Chrome、Chromium、Edge 时，退回宿主工具，交出同样的几样东西。不为截图另写 Playwright 或浏览器协议脚本。
+
+## 截图和录屏
+
+```text
+node <skill>/scripts/shoot.mjs <页面地址或 HTML 文件> [选项]
+```
+
+本地文件会用一个只监听本机的临时服务器打开。地址里带 `?` 或 `&` 时加引号，例如 `"http://127.0.0.1:3000/?state=done"`；更省事的是用 `--states`。同名文件会直接覆盖，不需要额外参数。
+
+| 要什么 | 加上 |
+| --- | --- |
+| 每个状态各一张，再拼成并排图 | `--states idle,running,done,error --sheet` |
+| 同时要遮掉全部文字的版本 | 再加 `--mask` |
+| 200% 截图 | `--zoom 2` |
+| 手机和桌面各一套 | `--size 390x844,1280x900`（默认只有 390x844） |
+| 整页长图 | `--full` |
+| 截图前先操作几步 | `--steps "click .open; wait 300"` |
+| 主操作录屏，外加开始、中间、结束三帧 | `--record --steps "drag .handle 0 -80; wait 400; click .start" --hold 1500` |
+
+`--steps` 里的动作用分号隔开：`click 选择器`、`hover 选择器`、`drag 选择器 横向位移 纵向位移`、`type 选择器 文字`、`key 按键`、`scroll 纵向位移`、`wait 毫秒`。
+
+结果写进 `--out` 指定的目录，默认是 `./shots`：每个状态一张 `<状态>.png`，遮字版是 `<状态>-masked.png`，并排图是 `sheet.png` 和 `sheet-masked.png`，录屏是 `record.mp4` 和 `motion-start/mid/end.jpg`。每张图都会检查控制台错误、横向溢出和没加载出来的图片，命令最后一行给出结论，明细在 `report.json`。录屏需要本机装了 ffmpeg，没有时只留三帧。
+
+检查报出接口 401、404 这类和画面无关的错误时（例如访客状态下的登录接口），在交付说明里记一行就行，不为了让检查通过去改登录、接口这类业务代码。
+
+截图前先自己看一眼结果：默认状态是不是已经加载完，遮字版有没有把图形也一起盖掉。证据有错先重截，再交给评审。
+
+## 写可操作的小样
+
+小样要能用地址参数直接打开每个状态，例如 `?state=done`，截图工具和评审都靠它。一个组件或一个页面只写一个文件，不要每个状态复制一份。
+
+颜色、字号、间距、圆角先定成十来个 CSS 变量，后面一律引用变量；同一个组件的样式用原生 CSS 嵌套写在一起。不引入 Tailwind 或 Sass 这类需要构建的工具。
+
+状态和交互用 Alpine.js 写在 HTML 属性上，不手写一长段切换显示的脚本：
+
+1. 复制到任务目录：`cp <skill>/assets/vendor/alpine.min.js <任务目录>/vendor/`
+2. 页面里引用：`<script defer src="vendor/alpine.min.js"></script>`
+3. 状态集中放在一个 `x-data` 里，初始状态读地址参数：
+
+```html
+<main x-data="{ state: new URLSearchParams(location.search).get('state') || 'idle', amount: 40 }">
+  <p x-show="state === 'done'">做好了</p>
+  <input type="range" min="20" max="80" x-model.number="amount">
+  <button @click="state = 'running'">开始</button>
+</main>
+```
+
+放进对比页时，在 manifest 里给这个候选加 `"interactive": true`。生成器会把任务目录里引用到的 CSS 和 JS 文件内联进对比页，不用手动合并。
+
+存量项目里照用项目自己的技术栈，不引入 Alpine.js。

oil-ui-pro/references/visual-language.md

@@ -0,0 +1,202 @@
+# 视觉语言
+
+## 从整体到局部
+
+先查看信息焦点、构图和内容密度，再调整空间、排版、色彩与细节。前一层已经解决问题时，不为显得精修而继续添加样式。
+
+使用项目有效的视觉变量、组件和参考关系。没有标准时只定义当前需要的文字、颜色与间距角色；不凭空生成完整设计系统。
+
+每次修改能说明：哪个可见元素、哪种关系存在问题、调整什么、期待改善什么。源码检查可以证明样式不一致，不能单独证明画面更好。
+
+## 焦点与空间
+
+- 每个任务区域有可辨认的主信息或主动作，辅助信息通过尺度、字重、对比或位置退后；不用多种强强调同时争夺注意力。
+- 同类关系保持同类间距，组内更紧、组间更松。先用对齐与留白建立结构，再判断是否需要容器或分隔线。
+- 留白承担分组、焦点或节奏。工具界面不为追求空旷牺牲必要信息，品牌页面也不强制塞满首屏。
+- 非对称、越界图形或大尺度文字可以表达选定方向，但需要稳定的局部对齐和清楚阅读顺序；不把有意的非对称自动当成错误。
+- 父布局负责区域排列，组件负责自身内部空间。同一距离不要同时由多层样式重复增加。
+- 先把内容直接放在画布上，通过对齐、字号和留白组织。容器只在确有分组、选择、背景对比或操作边界时出现；不要把页面、模块、条目和条目说明逐层套成卡片。
+- 分隔线和边框不要重复。每条线只做一件事：同一处分隔不叠双线、单线再加一个框；留白已经分开的地方不再补线；不要每个层级都画一遍线。线的粗细对应层级，例如粗线分版面、细线分栏，全页一致。线本身是风格的一部分时照样保留，只删重复的那些。
+
+## 字体与内容
+
+- 按标题、正文、辅助信息、标签和数据建立文字角色。角色稳定，层级有足够区别；实际内容长度决定换行和空间。
+- 检查目标语言的字形、字重与回退字体。英文样例好看不能证明中文排版成立；中英混排检查基线与视觉重量。
+- 正文行长与行高服务阅读；密集表格按扫描与比较安排，不套用文章排版。需要纵向比较的数字可使用等宽数字。
+- 重要名称和说明不靠固定高度裁切。确需截断时保留完整内容的可访问入口，避免相近名称截断后无法区分。
+- 先写具体产品内容再调布局。按钮说明动作结果；价值表达使用真实用途，不用空泛口号、虚构背书或无意义英文填版。
+
+### 可读性是交付门槛
+
+字号与行高在真实视口、实际字体和 100% 阅读尺寸下判断，缩略图只能用来判断构图。阅读型页面的中文正文通常从 16–18px 起步，产品界面正文 14–16px，每天长时间使用的高密度工具可以到 13–14px（见设计方向里的密度）；正文无单位行高 1.6–1.75；操作文字通常 14–16px。它们是起点，不是跨产品的死规定。不要靠 9–12px 的说明、低对比细字或压缩行高营造“精致”。信息太多先删冗余、调层级或重排。
+
+多行中文标题通常先用 1.2–1.35 的行高，按真实字形检查。不要照搬英文大写海报的极紧行高，不把标题高度固定为单行，不用负外边距挤压后续内容。展示字确需更紧时，必须看过每个支持视口的实际换行并确认字形不碰撞。
+
+中文断行要主动控制：`text-wrap: pretty` 或 `balance` 只能减少孤字，不能消除。数字和单位（38 秒、47 分钟）、“不会”这类不可拆的词用不换行包起来；首屏说明、页边批注这类短段落按语义手动断句。行末只剩一两个字，或者词被拆到两行，都算缺陷。
+
+验收时看长标题、两到三行正文、中英混排、数字单位与字体回退；在窄屏和放大阅读后检查行间、上下区块及按钮内部。文字重叠、截断关键信息或被相邻区域压住属于未完成。先修行高、内容驱动高度和容器伸缩，再考虑减小字号。
+
+### 示例数据要像真的
+
+示例数据会暴露模板感，即使视觉层已经很好。要避开：整数指标（1,000 位用户、+10%）、张三李四和示例公司、每条都是“2 小时前”、写着“标题”“描述”的占位字、页面上反复出现的“了解更多”“立即开始”。真实数据是不整齐的：1,238 位用户、+1.83%，时间有“刚刚”“昨天 16:12”“3 月 14 日”；名字有长有短，顺带验证长名字的排版。按钮说出具体动作，例如“保存草稿”“周二发送”。一页上有很多演示（组件目录、模板库、功能展示）时，让它们共用一个具体的虚构场景：同一个产品、同一批人、同一组文件和数字，演示之间互相呼应，比各自编一条“示例标题”可信得多；不要把库名、技术栈当成演示内容。
+
+## 色彩与表面
+
+颜色按文字、背景、动作、选中与状态等含义使用。品牌色与语义状态可以共存，但不能只靠颜色区别重要状态。
+
+边框、阴影、材质和渐变要与方向一致，并帮助分层、表达氛围或建立品牌识别。不要把紫色、圆角、渐变列为一律禁用；问题在于无意义重复、主次混乱和不适合任务。
+
+避免每张普通卡片都使用不同的强调色、重边框与重阴影。相同层级保持一致重量；内部嵌套轮廓与外部容器协调。
+
+配色做两个自检：去掉所有发光和模糊后，配色是否还成立；能否说出一个用类似配色的成功产品或出版物。表面层级可以用色温和色相的偏移来区分，不只靠明暗。选完配色再问一句：这组颜色是从这个产品的内容、用户或品牌里推出来的，还是一组放在哪个产品上都不出错的安全色？是后者，就回到产品重新找。
+
+质感按调性的完成度取用，不混用：
+- 精致一端：表面的高光、层次柔和的阴影、细微的冷暖交叉色、细线分隔。
+- 粗粝一端：手工和印刷留下的痕迹，从这个方向的生成引擎里找，不套一组固定的道具。
+
+核对文字、控件边界、焦点和选中态在实际背景上的可辨认性，尤其是图像、透明和动态背景。遵循项目已有的可访问性目标；基础阅读与操作不能依赖猜测。
+
+## 模型默认审美自查
+
+先做一个总测试：把画面给人看，说“这是 AI 做的”，对方会不会马上相信？好的界面应该让人问“这是怎么做出来的”，而不是“这是哪个 AI 做的”。
+
+没有明确风格依据时，模型容易生成下列默认做法。它们都不是禁令，但每出现一项，都要能说出它怎样服务当前北极星；说不出就换成方向卡里的具体选择：
+
+- 无来由的渐变、柔光、玻璃拟态和发光描边。
+- 配色说不出来自这个产品的理由，只是因为它“不会出错”“显得高级”或者“这个行业都这么用”。判断不看是哪种颜色，任何颜色都可以用，只看理由是否来自这个产品。
+- 中文界面从头到尾只用思源黑体或系统黑体，标题没有自己的字体性格。
+- 在页面里画假的浏览器窗口、红黄绿三个圆点、写着 9:41 的手机状态栏或整台手机外壳。浏览器和设备本身已经提供这些，产品本身是浏览器或设备模拟器时除外。
+- 所有内容都装进同样圆角、同样阴影的卡片，卡片里再套卡片。
+- 首屏固定为左右分栏：左边大标题，右边说明、按钮或一张图；下方接三列图标特性卡。换了字体和颜色，这个骨架也常常原样保留。
+- 用表情符号或随手找的图标给每个标题做装饰；最典型的是 2px 描边的通用图标放进浅色底圆角方块，每个标题配一个。
+- 工具、后台，以及画廊、商店、信息流这类内容页，顶部放超大标题、口号或解释这个页面的段落，把第一排内容推出首屏；用一整块深色圆角卡片装“下一步”动作；每一列、每个区块下面一行解释它是干什么的。
+- 用单侧色条标重点：引文、提示、答题反馈、当前项、紧急卡片，左边或右边加一条 2–4px 的彩色边线。这是最常见的模型默认之一，“它在表达状态”不能当理由。状态用元素本身表达：状态词加颜色或图标、整块底色、字重、位置和顺序。单侧的线只用来分隔结构，例如侧栏和主区之间、表格的列之间，并且用中性色。
+- 用星星、闪光、魔法棒、机器人表示 AI 功能。图标应表达实际动作或结果，例如摘要、翻译、转写。
+- 全页只用一种无衬线字体，标题与正文尺度相差不大，标题没有自己的性格。
+- 每个区块都有英文眉标、胶囊徽章和一句空泛口号，例如“一站式”“赋能”“开启全新体验”。中文产品用英文做字标、表头和分区名（WORKSPACE、CONTENT OBJECT、FIELD NOTES）也属于这一类。
+- 界面上写满制作说明：“示例”“待核实”“概念图”“示意图”“按钮未接入”，或者“仅保存在此浏览器”这类解释实现方式的话，挂在字段旁、图片角落或页脚。这些是写给委托人的话，放进交付说明。
+- 所有间距相同，页面没有松紧节奏，也没有一处视觉重心。
+- 随意给文字上色、加高亮，或者到处加描述性小字和标签，留出没有用途的空白区域。
+- 首屏之后接一排三栏功能格：编号或图标、小标题、两行说明，内容和首屏重复。首屏再有辨识度，到这里也会退回模板。
+- 界面完全不动，或只有悬停变色；有动效时各动各的：每个区块套同一个淡入上移，按钮、面板和数字之间没有关系。
+- 自己画的下拉、开关、滚动条，比平台原生组件更难用。
+- 文案抽象，用晦涩的比喻代替具体说明。方向的比喻也会渗进功能：按钮叫“检查采样”，导航画成一圈轨道。比喻只管视觉气质，功能名、按钮和导航用产品本身的说法。
+
+要求精简时给出具体操作，例如“改成以图片为中心的网格，去掉渐变、发光和多余容器”。只说“像苹果一样极简”几乎不起作用。
+
+检查时截图整页，逐项对照。出现三项以上，通常说明方向还停在默认模板，应回到方向卡重新确定主构图和主视觉，而不是逐个替换装饰。
+
+## 控件与图标
+
+同一界面维持一致的图标语言、光学大小与文字对齐。通用图标优先使用成熟资源；特殊品牌插图单独制作，不为每个标题机械添加图标。
+
+可点击元素需要可识别的入口及相应反馈。默认、按下、聚焦、选中、禁用与处理中表达不同含义；鼠标悬停不能替代触屏与键盘入口。反馈变化保持点击区域与邻近布局稳定。
+
+控件是一套语法：圆角、描边、字重、阴影、按下时的位移、选中的表达和状态图标，在按钮、输入、标签、开关和空状态之间用同一套逻辑。方向不只贯穿整页，也贯穿每个控件。按钮和输入框还停在组件库的默认样子，换了主色也认不出是哪个产品，就说明控件还没有进入方向。
+
+陌生图标配可见文字；纯图标按钮仍需可访问名称。箭头符号有含义：↗ 表示打开新页面或外部链接，提交、检查这类原地动作不用它。静态标签和装饰不要伪装成按钮，行内按钮不要误触外层卡片动作。
+
+### 图标库也会趋同
+
+模型的默认是 Lucide 或 Heroicons：24px、2px 描边、圆头端点。库本身没有问题，问题是每个方向都用同一套、同一种摆法。图标和字体一样是方向的一部分，在方向卡里写明用哪一套、什么粗细和端点，或者干脆不用。
+
+| 方向的气质 | 可以考虑 | 特点 |
+| --- | --- | --- |
+| 精致、编辑、奢侈 | Phosphor 的 Thin 或 Light，Iconoir | 细描边，配细字重的衬线或无衬线 |
+| 工业、仪器、企业工具 | Carbon，Material Symbols 的 Sharp，Radix Icons | 直角端点、网格严格；Radix 专为 15px 的紧凑界面设计 |
+| 友好、圆润、消费 | Phosphor 的 Fill 或 Duotone，MingCute | 圆角端点，实心或双色 |
+| 中文产品，需要大量业务图标 | IconPark，Remix Icon | 覆盖面广；IconPark 能调描边粗细、端点和主题 |
+| 需要连续调粗细和填充 | Material Symbols | 可变字体，填充、字重、光学尺寸都能连续调节 |
+| 像素、游戏、复古 | Pixelarticons | 像素网格 |
+| 品牌标志 | Simple Icons | 各品牌标志的矢量形状 |
+
+用 Iconify 可以按名称取到上面大多数库的单个 SVG。
+
+- **一个产品只用一套。** 需要补缺时，挑描边、端点和圆角一致的，统一成相同的画布尺寸和描边宽度。
+- **粗细跟字重走。** 图标描边接近同尺寸正文的笔画粗细：细字配 1–1.5px，粗黑体配 2px 以上或实心。图标尺寸约为字号的 1–1.25 倍，按视觉中心和文字对齐，不按外框。
+- **能不用就不用。** 编辑类方向常用字符本身：→ ↗ ※ §、编号、缩写。只在能加快识别的地方用图标。
+- **品牌时刻手绘。** 核心动作、空状态这类少数位置，可以用方向自己的线条语言画专属 SVG；通用动作仍用库。
+- **小样内联。** 自包含小样只内联用到的 SVG，不引用图标字体或 CDN。存量项目沿用已有的库，换库属于改版。
+- **核对许可。** 多数是 MIT、Apache 或 ISC；SF Symbols 只能用在 Apple 平台的界面里，不能用于网页；需要署名的库按要求署名。
+
+## 细节
+
+好效果常常体现在模型不会主动做的小事上。它们单看都很小，加在一起就是“做出来的”和“生成出来的”之间的差别。结构和主视觉定下来以后，逐项过一遍；单个细节单独修，不为修一个细节改动整体结构。
+
+粗粝一端的方向同样讲究细节，只是讲究的方式不同：套印错位、毛边和颗粒要有意为之、方向和幅度一致，不能和随手没对齐混在一起；用代码画这些质感的做法见 [点缀与特效](ornament.md)。下面的形状与表面偏向精致一端，粗粝方向按自己的质感取舍；文字、对齐、状态和资源两端都适用。
+
+**形状与表面**
+
+- 嵌套圆角要同心：内层圆角约等于外层圆角减去两者之间的内边距，内层不大于外层。
+- 阴影用两层叠成：一层贴近、较实的接触阴影，一层远而淡的环境阴影。阴影颜色带一点背景的色相，不用纯黑；同一层级的阴影保持一致。
+- 高分屏上的细分隔线用 0.5px 或半透明色；边框和阴影不同时给重的。
+- 压在图像上的文字，靠图像本身的安静区域和局部遮罩保证对比，不给整张图盖浓重渐变。
+
+**文字**
+
+- 中文正文字距保持 0。展示字号可以收紧，字越大越可以收，但要看实际字形不碰撞；全大写的英文小标签加 5–10% 字距。
+- 中文用全角标点，引号用“”。行首不出现句号、逗号和右引号，行尾不出现左引号和左括号，可以用 `line-break: strict`；浏览器支持时用 `text-spacing-trim` 做标点挤压。
+- 中文和英文、数字之间的间距全页一致：支持时用 `text-autospace`，否则统一手写空格，不要一处有一处没有。
+- 数字用等宽数字；单位比数字小一级或更淡；金额、时间、百分比的格式全页统一，例如 1,238、+1.83%、16:12。
+- 标题按语义断行，不留孤字，见上文“可读性是交付门槛”。
+
+**对齐**
+
+- 图标和文字按视觉中心对齐，不按外框；圆形、三角形图标需要光学微调。
+- 大号标题的字形自带左侧空隙，要微调 1–3px，让它看起来和下方正文左对齐。
+- 数字列右对齐，小数位对齐。
+- 按钮文字在按钮里视觉居中；中文字形偏上或偏下时微调。
+
+**状态**
+
+- 每个可点元素都有悬停、按下、焦点、禁用和处理中状态；状态变化不改变尺寸、不挤动旁边内容，处理中的按钮保持原宽度。
+- 焦点环、文字选中色、输入光标、复选框和单选框的强调色跟随方向，不留浏览器默认的蓝色。
+- 深色或有色背景上的滚动条调成协调的颜色；可滚动区域的边缘用淡出提示还有内容。
+- 空、加载、错误状态和默认状态一样用心，不是事后补的一行灰字。
+
+**资源**
+
+- 位图按显示尺寸的 2 倍准备，图标用矢量。
+- 图片加载前先占好比例，不让布局跳动。
+- 网页标题、标签页图标和分享图与方向一致。
+
+在 100% 和 200% 缩放下各看一遍关键区域（无法用浏览器缩放时，用宽高减半、像素比为 2 的视口截图代替）；把局部截图放大，检查对齐、边缘和标点。
+
+## 克制：大胆在结构，克制在细节
+
+大胆和克制作用在不同层面，并不冲突。结构上大胆：首屏骨架、主视觉和一处结构性突破可以走得很远。细节上克制：其余元素安静下来，让主角成立。一页只有一个主角，可以是一张图、一句巨大的标题或一个图形装置；其余的字号、颜色、容器和动效都为它退后。满屏都在出招，和满屏米色卡片一样，都是没有取舍。
+
+克制要落成预算，和调性里“克制”的翻译一致：
+
+- 一页的字号 4–6 级，字重 2–3 种，字族不超过 2–3 个（展示、正文，可选等宽）。级数少，级差要大。
+- 强调色约占画面 10% 以内，只用在主动作、选中和需要立刻识别的状态上。
+- 划线、倾斜、跨界、手写批注这类特别处理，一页一处，放在最能放大北极星的位置。
+- 先做准三处基本动效，让它们彼此呼应；装饰性的动效一页最多一两处，见 [动效](motion.md)。
+
+预算是起点。方向明确需要更多时，例如拼贴或喧闹的调性，写出理由即可。
+
+克制不等于极简。用户选定强烈风格后，减法应让风格更集中，不把它变成通用白底模板。减法删的是装饰和重复，不删帮助判断的信息：工具与决策界面里，对象名称、比较依据、当前选择和下一步动作是主角，删掉它们界面不会更高级，只会失去用途。删减后检查用户是否还能确定当前对象、理解代价、发现主动作和判断结果；不能用更少的文字代替更清楚的结构。
+
+### 删元素
+
+逐项判断元素是否帮助识别、判断、操作、反馈，或对选定品牌与情绪有明确贡献。贡献说不清时尝试移除，对照前后效果。优先删重复标题、无语义徽章、多余容器和竞争性装饰。一张合适的图、几句必要文字和一个动作就能承载页面时，让它们成立；不为“完整”追加卖点卡片、数据徽章和重复的行动按钮。
+
+### 删文字
+
+模型爱加字：每个区块都是“眉标 + 标题 + 副标题”三件套，内容页顶部还要加一段解释这个页面是干什么的，每个字段下面一行提示，“点击下方按钮开始”这种描述界面的话，“新”徽章、脚注，以及解释图片内容的图注。
+
+- **逐句问**：删掉后，用户是否仍知道眼前是什么、能做什么？画面、位置或交互已经表达了的，就删。
+- **用展示代替描述**：能放产品真正交付的东西，例如一份真实的结果或一段真实数据，就不写一段话去形容它。
+- **一个区块只讲一件事**：一句标题，最多一段说明。需要第三层文字时，通常说明这个区块该拆开或删掉。
+- **叙事页面的字数预算**：首屏标题约 15 字以内，说明约 40 字以内，按钮 2–6 字，空状态一句话加一个动作。产品界面不按字数砍，按“逐句问”删重复和解释。
+- **做完后删一轮**：逐区块尝试删掉 30–50% 的文字，只把删了会影响理解的放回来。
+- **不先加字再调淡**：不先添一堆小字，再用降低对比来补救。设计理由、源文件名、组件术语和装饰性英文留在说明或按需展开处。
+- **必须留下的**：错误原因、单位、选择范围、陌生动作的标签、风险和后果。
+
+### 编辑剩下的文字
+
+文案需要一次主动编辑：用用户会说的话重写空泛口号，保留具体对象、动作和结果；可以继承用户原有的表达。不要把第一轮生成的文案当作不可改变的内容，也不要为了补满版式编造信息。
+
+模型写的中文常带翻译腔，交付前逐句改掉：用分号把两件事串成一句；“交代当前情况”“带读者回到”“保持内容明确”这类书面套话；标题写成字段名，例如“受控勾选”“禁用等级”。改成一句只讲一件事的短句，标题用人会说的短语，例如“生成中锁定”“回到最新”。
+
+模型写的文案往往是整页最弱的部分。标题、主张和按钮这类关键文案，优先用用户提供的原话，或交给用户亲自改写；交付时标出哪些仍是模型写的占位文案。

oil-ui-pro/references/visual-review.md

@@ -0,0 +1,154 @@
+# 视觉评审协议
+
+## 评审者的独立性
+
+选择能实际看图的隔离执行者，不固定供应商、模型价格或参数规模。遵循用户的模型偏好和预算，不假定更贵必然更懂设计。
+
+首次评审与后续独立复查均使用新上下文。只传当前版本的必要证据，不继承制作对话，也不将旧评审粘进去。主 Agent 保留历史，用于判断建议是否反复和修改是否有效。
+
+没有隔离看图能力时，主 Agent 可以直接检查当前画面，但不能称为独立评审。不能看图时只给结构或源码诊断，不根据文件名猜测画面。
+
+## 交接内容
+
+| 提供 | 不提供 |
+| --- | --- |
+| 用户任务、受众、交付范围和目标设备 | 制作者的论证、已经投入的时间 |
+| 已确定的方向、品牌与不可改变约束 | 源码、实现细节与技术借口 |
+| 当前版本截图，注明页面、状态与逻辑视口 | 旧版本截图、旧评分和旧评审结论 |
+| 已实际查看的必要参考与其用途 | 预设问题清单、希望评审者赞同的答案 |
+| 需要评估的可见状态或过程证据；三处基本动效（主操作反馈、一处状态切换、首次出场）和动效记忆点，各一段 3–5 秒录屏或开始、中间、结束三帧，并写明触发它的动作 | “必须给到某个分数”等通过暗示 |
+
+有记忆点时，评审单独回答：这一刻是否让人记住，动作和结果能否一眼对上。有动效证据时，再回答：各处动效是不是同一种手感，是否从被操作的地方出发、朝同一个方向、彼此接得上；指出各动各的、生硬或多余的地方。只有静态截图时，评审记录写明记忆点和动效没有评审。
+
+新评审者需要理解任务约束，不能只凭一张图自由改题。参考图用于说明方向或质量基线，精准还原任务除外，不作为要求照抄的目标。
+
+截图文件必须能被评审者访问。交接前确认文件属于当前版本；长页同时提供整体与必要局部，细节图不能替代整体构图。交互只能依据提供的状态与过程证据判断，单张截图不能证明提交或键盘行为正确。
+
+## 可直接使用的评审任务
+
+> 根据提供的用户任务、设计方向、约束和当前画面评审设计。先用一两句话说出这个画面想成为什么体裁和风格；再说出它属于什么品类，举出这个品类里两三个风格最鲜明的产品，说出它们在首屏和控件上通常怎么做。画面违背这些共识的地方，判断是有意的偏离，还是没认出品类；同时看画面是不是某个标杆的复制，遮住名字还能不能认出是另一家。再设想这一体裁里顶尖的设计团队会怎样完成同一任务，可以举一两类真实可参照的作品；然后指出当前画面与那个标准之间差距最大的一到三处。先看主构图、阅读顺序、主视觉和内容与操作的关系，再看排版、空间、色彩和细节。留意过度、夸张或一看就是模型生成的做法并扣分，例如首屏左边大标题、右边说明或图片的默认分栏，无来由的渐变与发光，处处圆角卡片，表情符号图标、随意给文字上色、空泛或晦涩的比喻式文案。画面里多个元素同时争当主角、处处都在用力，也算问题；反过来，处处及格却没有一处让人记住，也指出来，并说出最值得集中发力的位置。留意重复的线框：同一处分隔叠了好几条线，留白已经分开的地方又加线，或者每个层级都画一遍线，让画面发碎。承担风格和结构的线不算问题。单侧的彩色边线（引文、提示、反馈、当前项左边的一条色条）也算问题。画面上的制作说明，例如“示例”“待核实”“示意图”“未接入”，也列进可以直接删掉的文字。体裁指产品本身，例如展览落地页；借用的其他媒介只是风格来源，不按“像不像那个媒介”评判，也不为了更像而建议补上更多部件。如果是工具、后台，或画廊、商店、信息流这类让人浏览挑选的页面，再说出一屏能看到几个对象、第一排内容离顶部多远、主动作离当前对象有多远，并和这一体裁里最好的产品比较密度。另外单独列出两类小问题：可以直接删掉的文字，以及对齐、圆角、阴影、标点、状态这类看得出的细节瑕疵；表格和列表要放大看，各列的行线和基线是否对齐。每处问题写清位置、观察、影响和可执行的调整方向，必要时给伪代码或属性关系，不写含糊的散文。敢下判断，给出有主见的建议，不退回安全、容易的做法。区分可观察缺陷与风格偏好；没有明显问题时直接说明，不为凑数提出修改。最后按 10 分制打分，表示当前画面离顶尖水准还有多远。只提供评审，不修改文件，不启动其他评审者。未看到或无法验证的内容明确说明。
+
+如果有同类的优秀作品截图，更好的做法是把它们和当前画面放在一起，例如四张专业作品加一张当前截图，请评审者按完成度和品味排序并说明差距。有视觉基线的比较比“想象顶尖团队”更稳定。这些作品是基线和情绪板，不是要照抄的目标。
+
+用“顶尖团队会怎么做”作为参照，是为了拉高标准、让建议有方向，不是要求照抄某个作品。评审只给方向和具体修改点，不自己重做页面；让评审者直接重做通常时间和成本都会翻倍。
+
+主 Agent 在任务后附实际材料。没有真实材料时不能原样发送模板并让评审者自行想象。
+
+评审同时核对设计北极星是否在构图、字体、素材和交互中形成呼应，突破是否增强主题，以及是否用冗余文字和层层容器掩盖薄弱的主视觉。阅读尺寸下的文字碰撞、过小正文和错误裁切应直接指出；不要仅凭整体缩略图判定可读性通过。
+
+## 给已有界面评审
+
+在已有项目里润色界面时，评审的标准是这个产品自己的设计规范，不是评审者心里的理想风格。规范管“用什么”：哪些颜色、字号、间距、组件；[视觉语言](visual-language.md) 里关于层级、对齐、留白、文字和减法的判断管“怎么用得好”，照常使用。
+
+什么时候用，由 SKILL.md 步骤 4 决定：润色一整页或多页之后，或者用户要求评审现有界面、没有要求重新设计时。单个元素的小改动不评审；用户要求改版或重新探索时，用上面的正常评审。
+
+### 先确定规范
+
+1. **有成文规范时以它为准。** 设计文档、设计变量（颜色、字号、间距、圆角、阴影）、组件库文档或组件目录。
+2. **没有成文规范时，从现有实现里读出来。** 看设计变量文件和主题配置、共享组件和它们的变体、同类页面的做法，整理一份简短的现状规范：字体和字号层级、每种颜色的用途、间距和圆角、按钮与表单等关键组件的样子、用哪套图标。实现里本来就不一致的，比如三种按钮，以多数用法为准，少数用法记为待统一。
+3. **规范本身有问题时说出来。** 不在评审里悄悄绕开，单独列出，交给用户决定。
+
+优化 UI 时做过规范体检、重新建立了规范的，以选定的新规范为准，见 [存量项目](existing-project.md) 的“规范体检”。
+
+### 交给评审者
+
+- 当前版本的截图，注明页面、状态和逻辑视口。
+- 规范：有成文规范时给相关文件或摘录；没有时给整理好的现状规范，再附两三张用了同样组件的其他页面截图，作为一致性的参照。
+- 不能动的清单：品牌、字体、主色、组件库、全局导航，以及用户指定保留的部分。
+- 用户任务和受众。
+
+和正常评审一样，不给源码、制作过程和旧版截图。
+
+### 评审任务
+
+> 根据提供的设计规范、不能改动的清单、用户任务和当前画面，评审这个已有界面。先读规范，再看画面。第一部分，逐条列出画面偏离规范的地方：用了规范以外的颜色、字号、间距或圆角，同类组件长得不一样，没用已有组件而是另做了一个。第二部分，在规范范围内指出最影响完成度的三处问题，依据是层级、对齐、留白、文字、状态和减法这些设计判断。每条建议都要能用现有的设计变量和组件做到；确实需要新增变量或组件时，单独列出并说明理由。不建议更换品牌色、字体、组件库或整体布局。另外列出可以直接删掉的文字，以及对不齐、间距不一这类细节瑕疵。每处写清位置、观察和调整方向。只提供评审，不修改文件，不打分，不启动其他评审者。未看到或无法验证的内容明确说明。
+
+### 处理结果
+
+- 只做一轮。改完由主 Agent 和基线做前后对比，不为分数复查。
+- 偏离规范的问题优先改，改在共享的设计变量和组件上，不在单个页面上覆盖。
+- 需要扩展规范或违背规范的建议，不直接采纳，连同理由交给用户决定。
+
+## 首稿通常怎样被改好
+
+首稿即使方向不同，也常常共用同一套模板骨架。交付对比页时推荐一轮独立评审，由用户决定是否执行；执行时它是把方向拉开的主要手段，不能因为方向卡已经不同就跳过某个方向。叙事页面（落地页、品牌页、活动页）最常见、也最有效的几类改法：
+
+- 删掉装在卡片里的产品界面小组件，把位置让给主视觉。
+- 把一个元素放大到结构级别，其余元素为它退后。
+- 用一个主视觉撑起画面。它从方向的生成引擎里来，不套现成的装置。
+- 砍掉重复的标签和并列的按钮，只留一个主动作。
+- 让图像参与版面结构，而不是装在盒子里。
+
+这些改法不要搬到产品界面上。工具、后台和 App 常见的有效改法是：
+
+- 删掉解释界面的文字：列说明、区块副标题、“卡片顶边对应……”这类说明、和状态标签重复的提示框。
+- 压缩页面头部，把高度还给工作区；页面标题缩成一行。
+- 把用户最怕错过的属性放大，例如等待时长、超时、欠费，让它在整页里最先被看到。
+- 提高密度，直到一屏能看到足够多的对象用于比较。
+- 同一个状态只表达一次，删掉重复的徽章、色块和提示。
+
+画廊、商店、信息流这类浏览内容的页面，常见的有效改法是：
+
+- 删掉顶部的口号和解释页面用途的段落。
+- 把第一排内容提到首屏，让内容本身成为主角。
+- 把标题、导航和筛选合进顶部一到两行。
+- 让缩略图的比例和排列成为版式本身，不再给每张卡片加多余的边框和说明。
+
+## 反馈格式
+
+先用短段落说明当前画面如何表达任务与方向。随后按影响列问题，每项包含：
+
+- 位置：页面、区域、状态或元素。
+- 观察与证据：实际看到了什么；不能只说“普通”“不高级”。
+- 影响：妨碍了识别、任务完成、视觉焦点或选定方向中的哪一项。
+- 建议：可执行的调整，必要时提供布局示意或属性关系；不猜不存在的文件与行号。
+- 验证：修改后应检查什么，并指出是否只是主观偏好。
+
+10 分制评分用来驱动循环：主 Agent 以 9 分为完成目标，但不向评审者透露这个目标。分数必须附带具体差距，只有数字的评审不算有效。同一评审模型的前后分数可以比较；不同模型的数值不直接比较，也不把分数当作审美事实。分数高但用户不喜欢时，以用户判断为准。
+
+## 多个方向时加一次横向评审
+
+逐个评审只能看出每个方向自身的问题，看不出方向之间的趋同。多个方向都修改完后，再派一个新的评审者，同时看所有方向的整页截图，只回答一个问题：哪些区块在不同方向里本质上是同一个东西（结构、组件或版式相同，只是换了颜色和字体）？逐条列出区块和涉及的方向。被点名的区块，按各自方向的生成引擎重做。
+
+## 任务走查：让评审者真的去用
+
+视觉评审看的是截图，看不出流程问题：入口找不到、出错后回不去、第二次用还是一样慢。新界面或改动了操作流程时，在视觉评审之外，再派一个新的执行者做任务走查。它必须能操作真实页面，例如浏览器自动化或可点击的原型，不看代码和制作过程。没有这种能力时，由主 Agent 按同样的方法自己走一遍，并标明不是独立走查。
+
+交给它：
+
+- 3–5 个真实任务，用用户的话写，不提界面上的按钮名称。写“把上周没回复的三个客户标成待跟进”，不写“点击筛选按钮，选择未回复”。每个任务写清怎样算完成。
+- 目标设备、入口地址和需要的测试数据。
+- 故障场景怎么触发：提交失败、断网、空数据、慢响应。
+
+它要做的：
+
+- 每个任务从入口开始，记录每一步看到了什么、为什么选这里。需要猜的地方记为“犹豫”，点错又退回的记为“走错”，走不下去的记为“卡住”。
+- 每个任务再做一次“第二次使用”：有没有更短的路径，能不能只用键盘完成。
+- 至少在一个任务里制造失败，看输入是否保留、能否原地恢复。
+- 在窄屏上把最主要的任务再走一遍。
+
+输出按严重程度排序：卡住、走错、犹豫、多余的步骤。每条附截图和步骤编号，写清当时预期什么、实际发生了什么。不打审美分，也不提视觉建议。
+
+所有核心任务都能在没有提示的情况下完成，并且每处犹豫都有对应的修改或保留理由，走查才算通过。任务走查和视觉评分是两条线：一边分数高，不能抵消另一边的问题。
+
+## 评审改流程和加新功能的方案
+
+存量项目里改流程和加新功能的方案，比的是做法，不打分，也不问顶尖团队会怎样设计画面。交给评审者：用户的话写成的任务、每个方案的方案卡、各自差别最大的那一帧或本地地址、现状基线。不给制作过程。
+
+> 根据提供的任务、方案卡和画面，评审这几个存量项目里的方案。先说出这几个方案是不是真的不同的做法：入口和步数都相同、只是画面不同的，指出是哪几个。再对每个方案，按任务从入口走到结果，指出哪一步还在让用户伺候界面，而不是在做决定：找入口、重复填写系统已知的值、为了确认而确认、来回切换页面。然后列出方案里属于补丁的部分：加提示、加引导、加确认、加说明，却没有让步骤、要记住的事或要切换的页面变少。最后指出每个方案最可能失败的场景。每条写清位置、观察和调整方向。只提供评审，不修改文件，不打分，不启动其他评审者。未看到或无法验证的内容明确说明。
+
+能操作真实页面时，另按上面的“任务走查”走一遍，选定前后各一次，比较步数和卡住、走错、犹豫的次数。
+
+## 主 Agent 如何处理反馈
+
+先处理任务阻碍、内容错误与明显视觉层级问题，再处理有依据的精修。将接受的反馈映射到实际实现；用户指定的风格不能被评审者随意替换。
+
+评审单独列出的“可以直接删掉的文字”默认照删；只有删了会影响理解时才保留，并在记录里写一句理由。
+
+多个评审对不同方向给出同一条建议时，分别在每个方向里找它自己的落地形式，不用一种实现套到所有方向上。
+
+建议违反用户约束、仅表达另一种偏好或缺乏证据时，可以不采纳并保留简短理由。为了更像借用的媒介而增加部件、线框或装饰的建议，先对照北极星判断，通常不采纳。一次完成相关改动后集中取证；不每改一个细节就重新派发。
+
+记录版本、已接受改动、未解决问题与检查结果。保持相当的视口、内容和状态进行前后比较；后续独立评审只看当前版本，前后收益由主 Agent 检查，重大主观取舍由用户判断。
+
+出现持续换风格、互相推翻或细节调整无可见收益时停止美学循环，保留最符合任务与方向的版本。停止不能掩盖仍然存在的功能缺陷或未经验证的部分。