dsh-super-code 0.3.10 → 0.4.0

package/builtin/skills/oil-ui/references/media.md

@@ -0,0 +1,158 @@
+# 素材
+
+图从哪来、承担什么、怎样和页面接成一体。游戏、收集和养成类产品要的角色、道具、藏品和图集，见“成套素材”。
+
+## 目录导航
+
+- [先定图承担什么](#先定图承担什么)
+- [复用、生成，还是交给代码](#复用生成还是交给代码)
+- [让图承担意思](#让图承担意思)
+- [写提示词](#写提示词)
+- [生成后放进页面再判断](#生成后放进页面再判断)
+- [让图和页面接成一体](#让图和页面接成一体)
+- [让一张画当舞台](#让一张画当舞台)
+- [异质素材的单色化统一](#异质素材的单色化统一)
+- [抽象技术的主视觉推导](#抽象技术的主视觉推导)
+- [成套素材：角色、道具与图集](#成套素材角色道具与图集)
+- [真实贴图与科学、工程素材](#真实贴图与科学工程素材)
+- [实时 3D](#实时-3d)
+- [生成视频的可选路径](#生成视频的可选路径)
+- [文件与说明](#文件与说明)
+
+## 先定图承担什么
+
+素材是设计的起点，不是布局完成后填进去的装饰。先问：如果只保留一张图、一个标题和一个动作，哪张图值得占据这个位置？再决定是否需要更多模块。
+
+- **分清差距来自哪里。** 是信息和构图的问题，还是确实缺一张能表达产品和品牌的图。不用更多图片、光效和动画掩盖层级问题，也不因为代码好写，就用通用渐变和几何形状顶替必要的图像。概念或容器结构不成立时，否决当前方案，先改方向和骨架；不用继续生图补救。
+- **给每张图一句任务。** 它展示对象、解释关系，还是建立品牌和情绪；要让人一眼看懂什么。答不上来就先别找图，也别生成。图已经说清的，文字不再重复。
+- **后台和工具同样要判断。** 对象缩略图帮助识别，内容封面支持浏览，地图或空间图帮助定位，示意图解释关系；它们可以是界面最有价值的部分。纯数据任务确实不受益时，保留清楚的数据表达，不硬塞气氛图。
+- **图跟着北极星定，页面再和图呼应。** 主体、视角、尺度、光线、颜色、材质和留白由设计北极星决定；页面的字体、背景、边缘处理和运动从这张图建立呼应，也可以用一处受控的反差突出主动作。同组的图统一主体尺度、视角、光线和边缘质感，不是给所有图套同一个滤镜。
+- **图是结构，不是装在盒子里的插图。** 让它跨过版面的分界、占满首屏，或者和文字叠在一起，做法见“让图和页面接成一体”。
+- **先放进真实页面看一轮，再延展其他区域。** 素材没到位时，占位版的审美评审不算最终通过。
+
+## 复用、生成，还是交给代码
+
+- **有合适的就复用。** 实际看过图再引用它的特征；已有好素材时围绕它设计，不为证明用了工具而重复生成。
+- **自然主体先准备真实位图。** 植物、食物、人物、空间和自然材质担任主视觉时，默认先制作定制位图，或复用已经实际看过、符合方向的素材。简单矢量只用于图标、数据和结构可控的图形；需要自然观感的主视觉，不能用单薄线条图标冒充成品。
+- **没有就做出来。** 没有合适的现成素材时，主动制作关键素材，不因为正在写前端代码就省掉这一步。生成素材按这个来源顺序：宿主能生图就用宿主的。宿主不能生图且本任务已明确授权使用 oiloil 积分时，先运行 `node <skill>/scripts/oiloil-image.mjs balance` 检查登录状态；未登录或登录失效时，明确告诉用户需要登录，给出 `npx github:oil-oil/oil-cli login` 和 [账户页](https://ui.oiloil.org/account/?tab=images)，说明浏览器授权完成后继续当前任务。只提示一次，不反复催促，也不反复发送生图请求。登录后用 [oiloil 生图脚本](../scripts/oiloil-image.mjs)（先运行 `node <skill>/scripts/oiloil-image.mjs --help`；并发不超过 2 个进程，`--prompt` 参数用单引号包裹以防 `$` 符号被 Shell 展开，基于参考图改图时传 `--ref <参考图>`）。任务没有明确授权时不使用积分，只在需要图的方向上友好提示一次，任务照常继续。已登录不等于授权消费。按所用工具自己的输入和编辑规则来。除了主产品本身，还可以把产品所处的地域环境、原材料肌理和工序细节一起做进这套画面里，让页面有完整的上下文，不只放几张孤立的棚拍白底图。需要真实材质、设计器物、历史摄影、工程测绘图、古地图、科学版画或航空航天实拍素材时，用 `curate-media.mjs` 从 Poly Haven、Wikimedia Commons、各大博物馆开放馆藏（含日本国立博物馆与国会图书馆）、LOC、Wellcome 和 NASA 检索到本地 `assets/`。授权不允许放进页面的条目也能派上用场：下载到不上线的目录，给生图当参考图，取它的题材、年代、构图和材质线索，不让生成结果复刻原图。编号拉取、贴图直链、联系表和视频 poster 的命令见 [工具](tools.md#检索和下载真实素材)；下载自动生成 `SOURCES.md`，据此保留条目许可与署名。
+- **需要随操作实时变形的实物，用多层次矢量或实时渲染配合静态图。** 遇到选配器、规格切换、剖面拆解这类必须随用户点击立刻改变比例、部件或色泽的区域，如果只放一张不会变的静态照片，操作和画面就会脱节。把静态图像留给氛围、地域和材质特写；需要实时联动的主体用内联 SVG（画足外轮廓受光体积、结构连接件和表面肌理三层细节，不画成单薄的纯色图标）或 Canvas/3D 绘制，让每一次切换都在画面上立即兑现。
+- **位图和代码分工。** 位图负责自然形态、材质和光影；代码负责交互与可访问界面。文字、按钮、表单、数据标签和常规布局一律由真实 HTML/CSS 排版，不让生图模型画，也不拿完整截图当可交互的成品：生图画字容易出错，改不了，也不能被选中和读屏。
+- **离线只限制运行时。** 页面运行时不得请求外部素材；制作阶段仍可按授权使用 image-gen 生成，再把成品打包到本地 `assets/`。不把离线交付当成跳过定制素材的理由。
+- **没有生成能力时才用替代。** 没有符合方向的现成素材，且确认本任务没有可用生成能力后，才选用许可和实际显示质量都合格的临时替代素材或多层次矢量，并附素材简报，写清需要补做的主体、视角、材质、光向、留白和尺寸。不自动安装工具、切换收费服务，或要求用户把密钥粘进对话。
+- 要转动、有物理或随视角变化的对象见“实时 3D”；预先确定的连续变化见“生成视频的可选路径”。
+
+## 让图承担意思
+
+生成图最常见的失败不是画得不好，而是画得太满：细节越丰富越像图库照片，放进版面后没有重点，也和页面没有关系。
+
+跟产品无关的“好看场景”放进版面只会抢戏；处处都画满细节，就等于没有重点。画实物或真实场景时，把主体的质感和光影做足，背景和放字的地方留干净；画抽象功能或前后变化时，可以把大面压成单色、白模或失焦，只让关键的那几处亮出颜色、光或细节。
+
+选能和页面“接上”的主体：
+
+- 能跨过两块色面分界的单个物件。
+- 能延伸出画面的线状物。
+- 能在上面标注的空间：模型、地图、剖面、平面图。
+
+这样的主体，之后能和页面里的线、标注和区块连成一体；一张自给自足的风景照做不到。
+
+## 写提示词
+
+按固定顺序写，每项一两句：
+
+1. **主体与表现形式**：什么东西，用什么体裁呈现（照片、插画、模型或图解），体裁从页面的方向推出。
+2. **构图与留白**：主体在画面里的位置和占比，哪一块留空给文字。按已选的首屏骨架写出主体所在的区域和占比，以及留给文字的那一块要完全干净。留白区不要有高光、反光或杂乱纹理，保证文字清晰好读。
+3. **安全距离**：主体、托台与阴影不要贴到文字边缘，留出 10% 左右的空隙，防止屏幕变窄时文字压到物体上。
+4. **背景**：直接写出页面实际使用的十六进制色值，或者要求纯透明背景。色值一致时边缘自然融进网页，不需要额外用 CSS 遮罩去修。
+5. **材质与光**：主光方向、辅光、质感。同一页的多张图用同一个光向。地面反光向留白侧自然衰减，不横扫到文字区。
+6. **排除项**：不要任何文字、标志、伪代码、界面截图或多余漂浮物；小件图标或透明图注明“不要地面投影”，外部投影交由前端 CSS `filter: drop-shadow(...)` 控制。
+
+## 生成后放进页面再判断
+
+在真实页面、真实尺寸里看，不在图片查看器里判断。单独看很好的图，放进版面后常常主体太满、朝向不对、留白在错的位置。
+
+不对就改提示词重新生成，并写清要改什么，例如“主体往右移，左边留出一半空间”“去掉地面反光，背景换成页面的色值”。不要围着一张不合适的图改版式。每轮只生成少量有明确差异的候选，按预先写定的主体、构图和材质筛选，不反复随机抽卡。同一批里挑最能排版的一张，不挑细节最多的那张。
+
+**A/B 共用素材。** 各版本使用同一批原图和同等质量的导出，只改被测变量；不拿定制位图对低质量替代图，以免把素材差距误判为方案差距。
+
+## 让图和页面接成一体
+
+**背景融合。** 要融进背景的主视觉和大图，不加框，也不关进圆角卡片：从图的四角实际取色，页面背景用同一个值，或者用 CSS 遮罩、导出渐隐把四条边淡出到背景色。纯色背景时，提示词里的底色和网页一致，边缘就能自然接上。
+
+**透明图。** 先放在最终背景上检查边缘、白边和残留的棋盘格；检查透明通道要看像素，不能看文件后缀。阴影不烘焙在图里，由页面按实际背景加投影，这样换了背景也对。
+
+**跨越结构。** 透明物件放在两个色块或两个区块的分界线上，让它同时属于两边。
+
+**图和代码接力。** 生成图负责代码做不出来的材质和光，例如金属、玻璃、模型、光影。代码负责需要精确、可编辑、会延续的部分，例如从图里延伸出去的线、路径和标注。如果图里有一段本该延续到页面的部分，就把它裁掉，改用矢量接着画。这样它能准确穿过版面，带上真实文字，并在不同宽度下重新走线。
+
+**标注。** 在图上标注用细引线加文字，不用带底色和阴影的气泡卡片。引线端点要对准图里的真实位置：图在版面里用固定的尺寸和位置，按图片像素换算坐标。窄屏上隐藏标注，或改成图下的列表，不让它们漂移到错误的位置。
+
+**窄屏裁切。** 不把整张大场景等比缩小到看不清。从原图裁出焦点区域另存一张给窄屏用，或用对象定位对准焦点。桌面和手机两种裁切，都要保住承载信息的那几处。
+
+**一张图用多次。** 结尾或其他区块可以用同一张图的局部特写，比再生成一张光线和风格对不上的图更统一。
+
+## 让一张画当舞台
+
+另一种用法正好相反：图不讲信息，只给气氛，界面保持黑白克制，全页只用一种有笔触的画当唯一的颜色来源。
+
+- **画当舞台，界面在上面演示。** 把真实界面的简化版放在画上，画从四周露出来。滚动时画固定不动，只换前面的界面内容，和“滚动叙事”接得上。
+- **大胆裁切。** 只留画的一角或一个局部，接近抽象，不和界面抢。题材不必和产品字面相关，但气质要对得上。
+- **松和紧互相衬托。** 画越松，界面越要精确、干净；两者一起出现，彼此都更好看。
+- **用得少。** 一张画贯穿全页，或者只在两三处出现，例如价格卡的顶端和页脚；不要每个区块配一张。同一页的画统一画种和笔触。
+- **演示用简化过的真实界面。** 次要内容虚化或换成骨架，只把要讲的那一处做清楚；数字对比直接用界面元素画出来，例如两条长短不同的进度条，而不是另做一张图表。
+
+## 异质素材的单色化统一
+
+引入历史画作、雕像肖像或外部摄影素材时，彩色位图容易与界面的主题色产生冲突。可以通过统一的单色处理将不同来源的素材收拢到当前方向里：
+
+- **单色映射**：将素材转为黑白高对比后，把暗部与亮部映射到页面的主色与底色。
+- **网点与点阵抖动**：对写实图片做半色调网点化或微弱的扫描线处理，消解照片的写实质感，让它能和排版、网格共处。
+
+## 抽象技术的主视觉推导
+
+缺少产品截图时，不回退到通用的彩色发光球或大渐变。从产品处理的东西里找一个有形的对象：它读写的数据长什么样，它替代的那件工具或那道工序是什么，它的用户手边有什么。表现形式满足两条：大面积色阶平稳，文字压得住；画面里的线和标尺能由 SVG/CSS 接着画。找不到有形的对象时，主视觉交给排版本身。
+
+## 成套素材：角色、道具与图集
+
+游戏、收集和养成类产品要的不是一张配图，而是一整套会被反复摆放、翻转、比较的素材。
+
+- **先写风格说明。** 画法、视角、光向、材质、比例和色板各写一句，同一批的提示词都按它写。
+- **同系列靠轮廓区分。** 统一比例和光向，用耳朵、道具、配饰这类轮廓特征区分个体，不只换颜色。缩到实际显示尺寸还要能一眼分开。
+- **状态序列从同一素材改出来。** 生长阶段、正反面、开壳前后和不同动作，都以第一张为参考图编辑变体，保持同一个角色，不逐状态独立生成；各状态的落地点对齐到同一条基线。
+- **透明图集按轮廓切。** 格子之间留透明间距，按实际轮廓裁切，不按格子均分，否则会切掉树冠、带进邻格的残片。检查 alpha 像素，不看预览图的背景色，再放到最终背景上看边缘。
+- **贴到物体上要两面成立。** 会翻转、落下或转到侧面的素材，正面背面都要有，边缘沿轮廓闭合。受光交给场景，不在图里烘焙和场景方向相反的光影。
+
+## 真实贴图与科学、工程素材
+
+读 `--sheet` 生成的联系表 PNG 挑选，`imageUrl` 用来下载；`look` 里的四边色、纸底和干净区域，直接对应下文的背景融合、正片叠底和压字位置。Poly Haven 的 `textureMaps.diffuse.url` 才是表面颜色贴图，`roughness` 和 `normal` 分别供实时材质的粗糙度与法线使用；渲染球和模型预览图不适合重复铺贴。
+
+- 用 Diffuse JPG 做 CSS `background-repeat: repeat` 或 SVG `<pattern>`，在最终尺寸下检查四边接缝和重复频率。部分素材只沿一个轴重复；不要只看缩略图就认定双轴无缝。
+- Three.js 的颜色贴图用 sRGB，粗糙度与法线用线性数据；本工具选择 OpenGL 法线，按模型 UV 和实际光照检查方向。重复材质设置两个轴的 RepeatWrapping；模型 glTF 依赖清单中的 UV 贴图用于该模型，不能当作无缝材质。
+- 测绘结果只选 LOC hh 的图纸资源，照片、调查说明与图纸分开看。地图与版画的 IIIF 原图尺寸、下载尺寸可能不同，以下载输出的宽高判断能否承载页面放大和标注。
+- NASA 视频检索排除标题或关键词明确标为动画、仿真或可视化的项，仍要看片确认是否符合实拍要求。首帧 poster 是静态回退；背景播放、循环与裁切先在真实页面里检查。
+- 许可证跟素材记录走。Poly Haven 输出 CC0 与信源署名，Wellcome 保留条目许可；LOC 不推定所有条目无版权限制。Met、AIC、Cleveland 和 Rijksmuseum 只取公有领域或 CC0 条目；Japan Search 只取 CC0、公有领域、CC BY 和 CC BY-SA，ColBase 的图要按其要求署“出典：ColBase”；Commons 按每个文件自己的许可，BY-SA 改色或合成后要以同样许可共享。V&A 的公开 API 可访问高清图，但公开访问不等于取得首页、商业用途或高清发布授权，所以标为 `reference`。NASA 使用条件保留第三方署名与限制。官方条款随 `SOURCES.md` 一并保留，需要展示署名时放到页脚或项目的素材说明。
+
+## 实时 3D
+
+三类情况用实时 3D：用户要转动、检视的对象；堆叠、碰撞、推挤、摆动这类物理；玻璃、金属、透明塑料这类随视角变化的材质。一张生成图就能表达的，或者只为了显得高级，都不用。
+
+- 用 three.js 这类成熟引擎，需要物理时再配一个刚体库。生成的图当贴图、精灵或环境光来源，代码负责空间、运动和受力。
+- 验收看画面，不看用没用库：静帧看得出体积、透视、接触阴影和材质区分；序列图看动作关系，直接操作看运动是否连续、力能否传到被推的物体上。录屏条件按 [工具](tools.md)，序列图不能证明正常速度下的手感。
+- 新建的小样把库下载到任务目录的 `vendor/` 并附许可证，不引用 CDN；存量项目按项目已有的依赖方式引入。以模块方式引入的页面和贴图要通过本地服务器打开；要求双击就能打开时，打包成一个普通脚本，贴图内联或放在同目录。
+- 设备像素比上限取 2；页面隐藏或滚出视口时停帧；拿不到 WebGL 时显示同一场景的静态图；减少动态效果时照常算出结果，只关镜头晃动和装饰演出。
+- 截图前确认画布真的画出了内容，见 [工具](tools.md)。
+
+## 生成视频的可选路径
+
+要一段能叠在页面上循环播放的素材时，先检查三样：首尾接不接得上，主体的边缘干不干净，背景处理得怎么样。在单色背景上生成再抠像，只是可以试的办法之一：透明和反光的物体抠完可能丢边，或者带上背景的颜色，要放到最终的页面背景上看。
+
+要把几段视频连成一段叙事时，可以拿前一段的最后一帧当下一段的第一帧，或者事先把各段的关键帧统一规划好。播放进度由滚动或手势控制时，要检查跳到任意一帧、倒着播、加载速度和内存占用，不要默认把整段视频解码成一张张大图。
+
+玻璃、水晶这类需要折射或透光的物体，先在最终页面的背景色上生成画面，让折射和投影烘焙进素材，再用视频抠像模型去掉背景。直接在绿幕上生成再抠像，折射会带着绿色。预渲染的折射和光照只对应生成时的背景，不应承诺会随任意页面内容产生实时物理效果。
+
+透明底的视频和图片一样，可以跨在两个区块的分界上，做法见上文的“跨越结构”。
+
+## 文件与说明
+
+- 生成、下载或用户给的图，放进页面前按显示尺寸的 2 倍导出，不直接内嵌原始大图。不透明的图用 JPEG 或 WebP，透明的用 WebP 或 PNG；单张控制在几百 KB 以内。内嵌成 data URL 后体积会再大约三分之一。压缩、缩放、多尺寸 `srcset`、比例裁切和透明裁边用 `node <skill>/scripts/prep-image.mjs` 一次批量完成，用法看 `--help`。
+- 保留原图和处理后的版本；生成图记录提示词，以及工具明确提供的模型和实际成本（费用或积分）；未提供的项标为“未提供”，不估算。所有素材记录来源、用途和处理方式，分清复用、裁切、生成和后处理。
+- 生成图和替代素材不冒充真实产品截图、真实场所、真实人物或产品证据。

package/builtin/skills/oil-ui/references/motion.md

@@ -0,0 +1,123 @@
+# 动效
+
+## 每个界面先做三处动效
+
+完全不动的界面像一张截图：按下没有回应，切换没有来路，用户只能猜刚才发生了什么。新界面和改动了操作流程的界面，先把这三处做出来：
+
+1. **主操作的反馈。** 按下立刻有回应，完成时交出一个结果：按钮陷下去再弹回，勾号画出来，数字滚到新值。
+2. **一处状态切换的来路。** 选中、展开、换视图、增删列表项时，让人看见东西从哪里来、到哪里去，见下文“界面过渡”。
+3. **第一次进入时的一次出场。** 主角先到，其余按阅读顺序跟上，只在首次进入时播放。
+
+这三处之外再加的动效，每个都要承担反馈、引导、连续或品牌表达中的一项；滚动淡入、视差、跟随鼠标和装饰性循环最容易变成干扰。
+
+| 目的 | 适合考虑的方式 |
+| --- | --- |
+| 按下、聚焦、展开或普通的状态变化 | 用浏览器原生的过渡，或已有组件自带的小过渡 |
+| 视图之间的切换、元素换位置 | 共享元素过渡，见下文“界面过渡” |
+| 拖拽、手势、位置和大小的变化、多个元素配合的动画 | 用项目里已有的成熟动效库 |
+| 特殊品牌画面、材质、复杂物理效果 | 图片、3D、着色器或预渲染视频，按需求取舍；什么时候用实时 3D 见 [素材](media.md) |
+| 用鼠标、触控或滚动控制一段叙事的进度 | 让动画的进度直接跟着输入走，往回滚和快速操作都要处理好；见 [滚动叙事](scroll-narrative.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），而不是毫无反应。
+
+### 整页转场的稳定性取舍
+
+整页切换和组件的过渡不一样：旧页面要卸载，新页面要挂载。按稳不稳、难不难做，分三类：
+
+- **遮罩式（Curtain / Wipe）。** 用一块纯色、纹理或几何形状划过或盖住整个屏幕，趁挡住的时候卸掉旧页、挂上新页。它最简单、最稳，两个页面的结构互不相干，绝大多数页面都适合。
+- **交叠式（Overlapping）。** 新旧两页同时在屏幕上，互相错开、推挤，或者分层淡入淡出。看起来连贯，但两页的 DOM 要同时存在，层级和内存都要管好。
+- **共享元素式（Shared Element）。** 一个关键元素从旧页一直变形到新页，例如缩略图放大成详情页的主图。看起来最顺，也最容易出问题：用户快速双击、中途打断、后退，或者视口变了，都容易错位和闪烁，所以必须留好退路，出问题时直接显示到位的状态。
+
+第一次进站的加载屏（Splash），可以在等大文件加载的时候放一小段叙事或进度；站内的页面跳转，时长按下面“时长和幅度”里整页切换的取值，不让转场挡着用户看内容。
+
+## 时长和幅度
+
+| 对象 | 时长 | 要点 |
+| --- | --- | --- |
+| 按下、开关、选中指示 | 150–300ms | 按下缩到 0.96–0.98，按下时立即生效（约 80ms），松开再弹回 |
+| 下拉、气泡、提示 | 180–250ms | 从触发点方向展开，缩放从 0.96 左右开始，不从 0 开始 |
+| 面板、抽屉、侧栏 | 250–400ms | 按移动距离取值，越远越长 |
+| 整页或视图切换 | 350–500ms | 超过 500ms 就会让人等 |
+| 首次进入时依次出现 | 每项间隔 40–80ms | 总长不超过 600ms；只在首次进入时播放，重新渲染和恢复状态时不重播 |
+
+这张表管的是界面操作。游戏和抽奖的演出时长见 [游玩](play.md)。
+
+悬停上浮 2–4px，阴影随之加深。位移超过 20px 的悬停效果会显得轻浮。
+
+## 看不见的结果要说出来
+
+一次点击产生了看不见的副作用，例如复制到剪贴板、后台保存、发送，就用一条短暂的提示说出结果本身，例如“已复制：……”，而不是只说“成功”。确认类的时刻，例如选中或完成，可以用一次小幅弹出，只在状态第一次变化时播放，重复点击不重播。
+
+## 体验与性能
+
+项目里已有的动效节奏和组件能力先沿用。经常要做的操作，反馈要立刻给，不让动画拖慢事情本身。
+
+动画要能被打断。连续快速操作时，新动画从当前位置接着走，不跳回起点重播。CSS 过渡会从当前值重新出发，适合高频切换；关键帧动画会从头重播，适合一次性的出场。业务状态立即更新，不等动画结束。
+
+网页上连续播放的动画，优先只动变换和透明度，过渡里只写会变的那几个属性；很小的指示块可以直接过渡宽高。每一帧都要执行的代码，要有停下来和清理的条件，不要一会儿读布局、一会儿写布局地来回交替；滚出屏幕或没事可做时就停。整页过渡期间页面通常点不动，所以整页过渡要短。
+
+有明显位移、缩放或滚动特效的地方，要照顾开了“减少动态效果”的用户：这时所有状态直接到位，内容一样不少。必要的信息和主要的操作，不能等自动播放、声音或动画播完才出现。
+
+## 检查动效
+
+按正常速度操作一遍，再往回操作一次、快速连按几次：没有重影和跳动，元素不突然出现，不从奇怪的位置飞来，不卡在中间状态。开启“减少动态效果”后内容直接可读。只有实际测量后才报告帧率或性能改善。
+
+## 网页实现提示
+
+- 浏览器原生的视图过渡适合做“同一对象从一处变到另一处”：给前后两个状态里代表同一对象的元素起同一个过渡名，名字在同一时刻必须唯一。
+- 只变形状的过渡里，隐藏旧快照、直接显示新状态，就不会出现重影。
+- 过渡伪元素后面只能跟少数伪类，例如 `:only-child`；写成 `:not(...)` 会让整条规则失效。需要按场景区分规则时，在根元素上加一个属性来切换。
+- 内嵌页面和图片在过渡里会被截成快照；目的地没加载完就开始过渡，会以空白结束。

package/builtin/skills/oil-ui/references/play.md

@@ -0,0 +1,29 @@
+# 游玩与强手感操控
+
+小游戏、抽奖、扭蛋、计时养成，以及旋钮、拉杆、摇杆这类强手感操控，过程本身就是产品：用户来看转轮减速、硬币被推下、娃娃差点滑落。这类界面先读本文，其余规范照常适用。
+
+## 先盘点特有对象与状态
+
+先填对象与状态表，再选参考、出概念或画灰度结构。只列页面、按钮和通用资源不算完成：
+
+| 特有对象 | 用户怎样辨认 | 主动作怎样改变它 | 必须有的状态 | 状态的可见反馈 | 素材与渲染成本 |
+| --- | --- | --- | --- | --- | --- |
+
+对象覆盖用户在这个玩法里真正操控、生成、消耗和结算的东西；状态按核心循环列出开始、可操作、输入或演出、锁定、结算、失败与恢复，玩法没有的状态删掉，实际存在的特有状态补上。每个对象和状态都要能在画面里辨认，不能用同一张静态图配不同文字充数。
+
+再写一条 `主动作 → 特有对象变化 → 可见反馈 → 下一次操作或结算` 的核心循环，标出每屏唯一主角和唯一主动作。写清主视口的输入方式和反馈位置；触摸与指针的操作确有差异时再分别写，不重复两套相同说明。对象或状态缺项、核心循环走不通、输入或反馈无法执行时，退回盘点，不进入素材制作和灰度结构。
+
+## 过程即玩法
+
+- 演出可以比普通界面切换长，例如三个转轮依次停下共 2 秒左右，不按“超过 500ms 就会让人等”截短。
+- 扣了费、出了结果就先存好：刷新不丢，不重复扣，奖励只结算一次。在哪一刻存，按玩法定。
+- 演出期间写清哪些操作锁住；连按不能重复扣费。
+- 旋钮、拉杆这类手势从按下的位置开始跟手，过了生效点才算一次，没到就松手不扣。
+- 减少动态效果时，玩法照常算出结果，只是画面直接到位；不能把玩法本身停住。
+- 状态与变化用序列图看；正常速度下的手感通过直接操作判断：减速是否连续、停下时有没有顿挫、收益从哪里飞到哪里。录屏只按 [工具](tools.md) 的条件取用，不能仅凭序列图宣称手感已验证。
+
+## 素材与渲染
+
+- 对象与状态表完成后，把需要制作的项转成素材清单。角色、藏品、道具、符号和材质贴图是这类界面的主角，默认用生图做。手写 SVG 和 CSS 只画界面图标和简单图形，拿它们画角色和道具，会落到图标包的质感。成套出图的做法见 [素材](media.md) 的“成套素材”，素材来源也按同一份文件的顺序选择；都无法生成时，按该文件交素材简报，不拿手画的图形冒充成品。
+- 乐趣来自空间和物理时，用实时 3D 渲染场景，例如堆叠、碰撞、推挤、摆动，或透明、金属材质；生成的图当贴图和精灵用，做法见 [素材](media.md) 的“实时 3D”。树木生长、天气这类自然变化，用成套生成图通常更好。
+- 素材放进场景后再看一次：受光和场景一致，有接触阴影，侧面、背面和翻落时不露出纸片的边。图生成了，不等于放进场景就可信。

package/builtin/skills/oil-ui/references/reviewer-manual.md

@@ -0,0 +1,73 @@
+# 视觉与交互评审手册 (子 Agent 专用)
+
+本手册给独立评审者读。评审者没有参与制作，根据主 Agent 交来的当前画面证据、可操作页面和约束评审；分数按第 1 节的锚点给，拿不准时取低一档。
+
+只提供评审，不修改文件，不启动其他评审者。分清看得见的缺陷和个人的风格偏好；没有明显问题就直说，不为了凑数提修改。没看到、没法验证的内容要写明；只有静态截图时，不能声称动效或操作流程已经通过。
+
+## 1. 全新界面与改版评审（打分制）
+
+**评审视角**：拉高标准，以“该体裁里最顶尖的团队会怎么做”为标尺。
+
+**验收否决（先于打分与发布判断）**：以下任一成立，把对应项列为第一条问题，最后一行在总分旁写“不可发布”；总分不得超过 7，已触发更低分锚点时按更低档。功能通过、状态齐全、证据齐全都不能抵消，必须修复后重看实际画面。
+
+- 真实文字在目标视口、实际字体和 100% 阅读尺寸下不可读；
+- 主视觉仍像等待替换的占位素材；
+- 把产品名换成无关产品，首屏仍原样成立：说服型页面检查主视觉或核心构图，工具、后台与工作区检查核心业务关系与异常焦点；沿用高效品类基线不算换皮。精准还原任务不适用此项，以给定参考图为准；
+- 三秒后说不清当前画面的主角，或找不到完成当前任务的主动作。
+
+0. **三秒测试与候选查重（先于一切细节和流程）**：把首屏缩到 480px 宽（手机截图缩到 180px 宽）看三秒，再看遮字版三秒，写下两句话：它像哪一年的哪一类产品；第一眼看到的是什么。像若干年前的通用产品、组件库默认样式或素材库配图的，直接写出来，总分不超过 7 分；属于上面否决项的，再标“不可发布”。工具、后台与工作区沿用侧栏、紧凑工具条、趋势面板或表格/队列等高效品类基线不扣分，三秒测试看表面层次是否干净透气，以及核心业务关系与异常焦点是否一眼可辨。能用截图工具时，用它出缩略图和遮字图。
+
+   同批给出三个完整方向候选（不含选定方向的版式变体）时，再并排遮住产品名，核对核心图形、控件语法和主动作的视觉呈现；三项相同就直接判为同构换皮，退回重做，不能用配色、字体、材质或装饰差异凑成三个方向。这里比较的是视觉呈现，不是候选本应共享的产品任务与内容。
+1. **品类与标杆检验**：一句话指出这属于什么品类（如 B 端后台、展览落地页），该品类里标杆产品在首屏怎么做。指出现有画面违背共识的地方，判断是有意的创新，还是套用了模型的默认模板。能找到时，拿一两张同品类顶尖产品的实际画面并排比，说清素材、材质和场景完成度差在哪里。
+2. **动效检查（看动没动，不查证据齐不齐）**：默认看带时间的序列图或打开页面直接操作；序列图只用于判断状态与变化，不据此评价正常速度下的手感。只有确实要判断正常速度下的手感、且你能播放视频时，才按 [工具](tools.md) 使用录屏。证据不足且能打开页面时，只补看对应操作。只判断该动的地方动了没有：
+   - 主操作有没有反馈，一处状态切换看不看得出来路，首次进入有没有出场。
+   - 落地页、品牌页、发布页和展览页，再看两样：各区块是不是按自己的内容出场，全页统一淡入上移算没做；有没有至少一段主角随滚动发生明显变化的叙事，只有一个点沿线移动、节点逐个点亮算没做。
+   - 小游戏、抽奖、计时养成这类产品，三处基本动效只是底线，再按 [游玩](play.md) 核对“过程即玩法”和“素材与渲染”。
+   - 确实没做的写进问题。做了的，动得好不好放到“提升”的动效一项里评，不在这里展开。
+   - 不为逐帧找瑕疵追加取证。证据不一致时只补看对应操作；正常速度下的手感以实际操作或符合上述条件的录屏为依据，缺少这类观察就写“正常速度手感未核对”。只有静态截图、页面也打不开时，写一句“没看到动效”，不猜。
+3. **提升：精致度、设计感、动效**：缺陷清零的页面常常只是及格。这三项逐项看，有看得见的差距才写，每条写位置、现在的水平、做到什么样算到位；某一项确实没有，写“没有”和依据。提升是把已有的东西做得更好，不是再加东西。第一条是“重做”时不写提升。
+   - **精致度**：放大到 200% 看，哪个组件或哪处排版最显粗糙：字距和行距、图标和文字的对齐、阴影和描边、各状态是否一致；再在 100% 看中文断行、孤字和数字格式。顺着整页从上往下数所有标题和正文块的左边缘 X 起点：有秩序的版面整页共享 2–3 条垂直锚线，如果左起点散成五六处，直接指出哪几块没对齐。
+   - **设计感**：主角在 480px 缩略图里看不看得见、占多大；哪一处最接近品类最好水平，还差什么；哪一处仍是组件库默认的样子。把每一屏的构图概括成一个词（如 `分栏`、`大字列表`、`错落画报`、`选配台`、`满版图`）：同一个词连续出现两次或全页出现三次，按模板复读指出。同时检查整页节奏与收尾：如果每一屏都被塞进带底色或边框的卡片盒子里（缺少直接排在开放画布上的留白呼吸与高低错落），或者首屏很有风格、下面却退回成每个区块上下画一条通栏细横线、结尾只放几个默认输入框，直接指出。点题真交互（能亲手操作的选配、试算或实时状态装置）必须真实可操作。
+   - **动效**：按上面的证据边界判断，不只看有没有。哪一处动得机械：匀速、各动各的、全页一律淡入上移、和操作接不上；哪一处最值得做出手感，让人想再操作一次或往回再滚一遍。手感用“动作 + 实物参照”写，不写形容词。
+4. **精简与瑕疵**：
+   - 填缝文字：为了把版面两端配平而塞进去的小字，例如听起来有诗意却不指向任何对象、动作或数据的短句，或写在界面上的设计说明。逐条点名，要求删掉。
+   - 明确列出其他可以直接删掉的无用文字（如“示例”、“待核实”、“系统界面”、“仅供示意”）。
+   - 除了文字，还要列出该删或该并的面板、数据和装饰：每一屏只有一个主角，多出来的点名。删完以后主角没有变大变强、画面只是变空的，或者具体业务信息被笼统套话替代的，同样算问题。
+
+核对构图、字体、素材和交互是不是都在呼应设计北极星。工具、后台与内容浏览页面，说明首屏对象数量、第一排内容的位置和主动作与当前对象的距离，并和同类优秀产品比较密度；同时检查画面是否清爽透气，点开对象后的详情是否讲清了前因后果而非重复表格字段。
+
+参考作品是方向与质量基线，不要求照抄；精准还原任务以给定参考图为准。若有同类优秀作品截图，可与当前画面一起按完成度排序并说明差距。借用的媒介只是风格来源，不为了“更像”而增加无用部件。
+
+**输出要求**：
+
+- 开头先列一份紧凑的速查清单（每行一条：`[问题 1 / 提升 1] 位置或选择器：现象 → 修完要达到的可验收结果`），方便主 Agent 逐条勾销、不漏改；清单下面再写详细分析。
+- 先写问题，再写提升。问题只写会阻断任务、读不清或明显是模型默认做法的，按影响从大到小排序，最多 5 条；提升最多 5 条，精致度、设计感、动效三项都要表态。每条写位置、观察证据、影响、修完要达到的结果和怎样验收。改法只写目标，不替制作方定构图，不规定要放多少对象、多少数据，也不建议用加功能、加数据量来换真实感；更小的问题合成一句放在最后。主 Agent 会按这个顺序修改，下一轮也会拿这份清单逐条核对，所以每条要写到修完能看出来的程度。
+- 首屏骨架仍是模型默认模板，或主视觉远低于同品类水准，分数因此落在 6 分及以下时，第一条写“重做：……”，点名要重做的区块和原因，不再给这些区块列修补建议。在被否定的骨架上修补，只会把它修得更像样。
+- 倒数第二行写“保留：……”，点名一两处修改时不能磨掉的做法，通常是这个方向最有辨识度的地方。
+- 最后给出 1–10 分的总分。
+
+分数按下面的锚点给，先看任务，再看视觉：会丢数据、走不通、骗用户“已成功”的问题，比任何视觉问题都优先扣分。任务全部走通也不等于 8 分，主视觉同样要过门槛。
+
+| 分数 | 门槛 |
+| --- | --- |
+| 10 | 挑不出可观察的缺陷，至少一处是这个品类里没见过的好做法 |
+| 9 | 主流程、异常状态、细节都成立，提升只剩小处；至少一处达到品类最好水平 |
+| 8 | 方向鲜明，主流程走得通，没有阻断和数据丢失；页面有主视觉或关键素材的，达到同品类一线产品的完成度；缩到 480px 仍认得出作品特征（工具与后台为清爽的表面秩序与清晰的业务重心）；有若干中等问题 |
+| 7 | 方向成立，但有一处会让用户丢数据、走错、卡住的问题，或首屏结构仍带明显的模型默认做法，或主视觉停在手画矢量、平面假透视、用文字代替造型的水平，或三秒测试里像某一年的某类通用产品 |
+| 5–6 | 能看出方向，但骨架是模型默认模板，或主流程有多处卡住 |
+| 1–4 | 主任务走不通，或画面有重叠、裁切、看不清这类基本错误 |
+
+分数写在锚点上，给出“离下一档还差什么”，从精致度、设计感和动效里写，不写“再补一种状态”。
+
+评分必须附具体差距，不同模型的数值不直接比较，用户判断优先。不猜不存在的文件与行号。
+
+## 2. 存量已有界面润色评审（只对齐规范，不打分）
+
+**评审视角**：不要想象你理想的风格，而是严格遵循该产品现有的设计规范（色板、间距）。
+
+主 Agent 提供成文规范或从现有设计变量、共享组件与同类页面整理的现状规范，以及不能改动的品牌、字体、主色、组件库和导航。没有一致的现状时，以多数做法为准，少数做法记为待统一；规范本身有问题时单独列出，交给用户决定。
+
+1. **偏离规范检查**：逐条指出当前画面哪里用了规范以外的颜色/字号/圆角，或者明明有现有组件却自己手搓了一个。
+2. **布局与结构**：在规范范围内，指出最影响完成度的三处问题（层级、对齐、留白、减法）。
+3. **动效检查**：看这次改动涉及的动效到不到位、有没有把原来的动效改坏；用户明确要求或整页升级时，再按第 1 节的“动效检查”核对整页。
+4. **输出要求**：只提供客观修正建议，列出可删减的文字。**不打分**。不建议更换整体品牌色或字体。

package/builtin/skills/oil-ui/references/scroll-narrative.md

@@ -0,0 +1,97 @@
+# 滚动叙事
+
+## 落地页的滚动动效
+
+落地页、品牌页、产品发布页和展览页，滚动动效和 [动效](motion.md) 的三处基本动效一起验收；文档、文章、工具和后台不做。用成熟的动效库实现，见下文“动效库”。
+
+**必须有两样**：首屏以下的区块按内容出场；至少一段滑动驱动的叙事，让主角在滚动里发生明显变化。**手法按页面挑**：首屏景深、字标收进导航、一镜到底、章节转场镜头、背景随章节变色、宣言逐字亮起，从页面的主视觉和内容里挑最合适的一种，写进分镜并说明理由，不要每页都默认锁住首屏做缩放。
+
+### 首屏景深（适合首屏有明确前后景层次的页面）
+
+首屏是一个固定住的舞台，滚动直接驱动里面的层次变化，往回滚就倒放：
+
+- 首屏固定 100–200vh 的滚动距离，窄屏可缩到 80–120vh。
+- 至少两层以不同速度或方向变化，例如前景推近、背景慢移，或者主视觉和大标题拉开尺度差；背景层动得最慢，前景层最快。
+- 幅度要大到实际滚动时一眼看出来：主层缩放不少于 15%，或位移不少于 15vh。小于这个幅度，看起来就是页面在普通滚动。
+- 大标题是图形层，可以缩放和视差；正文、按钮和表单不缩放、不做视差，固定后保持可读可点。
+- 结束状态要交接给下一节：主视觉缩到下一节的位置，标题退成背景纹理，或者画面让出一条路给下一节的主角。不要固定结束后整块直接被推走。
+
+首屏是满版的品牌字标时，用下面的“字标收进导航”。首屏是其他满版文字、产品界面或纯排版时，不一定适合景深，可以把滑动驱动的叙事放在后面。
+
+### 字标收进导航（适合首屏是满版品牌字标的页面）
+
+首屏就是品牌名本身，滚动时它缩成导航栏里的标志。它用一个元素同时完成满版文字骨架和一段滑动驱动的叙事，适合品牌名短、字形有性格的工作室、品牌和作品集：
+
+- 首屏只有这一个字标，撑满版心宽度，窄屏也保持一行撑满；导航里不再放第二个标志。
+- 滑动驱动，滚过 60–100vh，字标沿一条路径缩到导航标志的位置和尺寸，往回滚放大回来。结束状态就是导航里的标志，位置和尺寸按导航实际量出，交接时不跳。
+- 缩放同一个元素的变换，不动画字号；字标用 SVG，或按容器宽度算出的字号。
+- 字标让出首屏的同时，下一节内容已经进入画面，不留一整屏空白。
+- 字标从满版缩成导航标志，是主角明显的缩放和一次交接，算一段滑动驱动的叙事；同一页不再另做首屏景深。
+- 减少动态效果时，字标留在首屏不缩放，导航从一开始就显示标志。
+
+### 区块按内容出场（必须，滑动触发）
+
+首屏以下的每个区块，滚到位置时出场一次，往回滚不重播。出场方式从这个区块的内容和材质推出来，并且符合物理直觉：有重量的落下会过冲后稳住，轻的东西有空气阻力，机械的东西咔嗒到位。
+
+| 区块内容 | 出场方式 |
+| --- | --- |
+| 卡片、实物、价格牌 | 带重量落下后稳住，过冲幅度见 [动效](motion.md) 的“手感”；后一张被前一张带出 |
+| 列表、时间线、步骤 | 沿阅读方向依次展开，连接线先画出，节点随后落位 |
+| 数字、指标 | 滚到目标值，高位先停、末位后停；不从 0 起跳的用原值起滚 |
+| 线条、图表、路径 | 沿数据或流程的方向描出，端点落定时轻微放大一下 |
+| 图片、照片 | 遮罩从画面主体的方向揭开，图片同时从 1.08 回缩到 1 |
+| 纸、布、标签 | 先快后慢，带一点旋转后摆正，像被放到桌上 |
+| 金属、机械、硬件 | 短促到位，没有软弹，可以带一次很小的回震 |
+| 大标题、口号 | 按词或按行从遮罩里升起，字距从略松收紧 |
+
+规则：
+- 每个区块的出场写进分镜：重点区块按内容单独设计出场，普通区块保持统一克制的节奏，不要全页从头到尾套同一个淡入上移。
+- 曲线用弹簧或惯性，参数从 [动效](motion.md) 的“手感”表里按材质取，不用默认的 ease。
+- 主角先到，其余被带出，间隔 40–80ms，单个区块的出场总长不超过 900ms。
+
+### 滑动驱动的叙事（必须至少一段）
+
+可以是首屏景深、字标收进导航，也可以是页面中段一段一镜到底，规则见下一节。主角必须在滚动里发生明显变化：缩放、拆解、变形、穿过或形状接力。一个小点沿着线移动、节点逐个点亮，只能算主叙事里的一个细节，不能单独当作主叙事。
+
+### 分镜
+
+动手前在方向卡的“动效”一栏写出滚动分镜：选了哪些手法、为什么，每一段占多少滚动距离、主角是谁、每个镜头画面里有什么、什么在动、往哪个方向、文字什么时候出现。先拆两个同类顶级落地页的滚动节拍作参照，写清它们每一段在动什么，再写自己的。
+
+## 视差与一镜到底
+
+- **一镜到底。** 整段是一次不切换的镜头。一个主角从头走到尾，可以是产品、一根线、一个形状或一个字，每一步长成、变成或让出下一个画面：推近看到细节，拉远看到全貌，转过去看到背面，穿过去进入下一个场景。
+- **主角从产品里找。** 主角是这个产品处理的那样东西，在滚动里走完它自己的过程。找不到只属于这个产品的主角时，退回下面的转场手法，不用通用的漂浮几何。
+- **停下来再说话。** 每个镜头留一段静止，文字在静止时出现；边动边读很累。
+- **视差要有真实的前后。** 只在画面本来就有远近层次时用：前景的物体、中景、远处的背景，越近动得越多，差别要小。正文、按钮和表单不做视差；大标题作为图形层时，按上面的首屏景深处理。
+- **转场也是镜头。** 一个圆从某一点扩开，带出下一节；推进一张图，穿过它到达下一节；背景色在章节之间随阅读慢慢变；一句宣言随滚动逐字亮起。每种手法一页只用一次。
+- **倒着滚也成立。** 每一帧只由滚动位置决定，往回滚自然倒放，刷新或跳到中间也立刻是对的画面。不接管用户的滚动。
+- **留出口。** 长段落前给一个跳过入口；减少动态效果时，把每个静止画面按顺序排成普通区块。
+- **代码做不出来的，交给视频。** 用户想要很强的首屏动画，而效果要靠生成视频或序列帧才做得出来，例如角色转身、产品拆解、镜头穿越场景，可以告诉用户用 [oil-motion](https://github.com/oil-oil/oil-motion) 来做。CSS、SVG、着色器能完成的仍自己做；同一次对话只提一次。
+
+## 滚动交互的两种模式
+
+滚动带来的变化分两种模式：
+
+- **滑动驱动（Scroll-Driven）。** 动画进程与滚动距离严格 1:1 映射（Scrub）。用户停下则动画停下，往回滚则倒放。首屏景深、一镜到底、3D 视角变换和模型解构只用滑动驱动；除首屏景深外，一镜到底一页最多一段。
+- **滑动触发（Scroll-Triggered）。** 元素滚入视口阈值时，触发一段按自身时长播放的独立动画（如卡片进场、数字上涨）。它什么时候播完由代码决定，不跟着滚动条走。
+  - **默认单向一次性（Once）。** 触发后样式固定，用户向上回滚不重播、不复位，不在阅读中途让内容反复飞入或闪烁。
+  - **离开重置（Reset on Leave）。** 只有强节奏的纯展示页才允许在完全移出视口后重置，不在视口临界点反复触发。
+
+## 平滑滚动与全屏分段
+
+- **平滑滚动只管滚起来顺不顺，不算动效。** 用 Lenis 这类库，是为了消掉鼠标滚轮一格一格的跳动，让滑动驱动的动画和视差走得均匀。后台、仪表盘、表单和长文档不开全局平滑滚动，保持原生滚动的即时响应。
+- **慎用全屏分段滚动（Snap Scroll）。** 隐藏滚动条、单次滑动切换整屏的做法只适合特定的全屏展厅与作品封面，常规业务和长文本不用。
+
+## 动效库
+
+落地页的滚动动效必须用成熟的动效库，不手写滚动监听和逐帧计算：
+
+- **没有框架的页面**：GSAP，滚动用 ScrollTrigger（`scrub` 做滑动驱动，`once` 做滑动触发，`pin` 固定舞台），大标题拆字用 SplitText，元素换位置用 Flip。平滑滚动用 Lenis，并接进 GSAP 的时钟：`lenis.on('scroll', ScrollTrigger.update)`、`gsap.ticker.add((t) => lenis.raf(t * 1000))`、`gsap.ticker.lagSmoothing(0)`。GSAP 和它的插件都可以免费使用。
+- **React、Vue 等项目**：沿用项目已有的动效库（Motion、GSAP 等）；没有时加 GSAP，不另外手写一套。
+- **需要离线打开的作品**：把库文件按固定版本放进作品目录，从本地引用，不依赖 CDN。
+- **减少动态效果**：用 `gsap.matchMedia()` 分开两套：减少时不固定、不缩放，所有区块直接到位，主叙事排成按顺序的静止画面。
+- 只动变换、透明度和滤镜。固定舞台的外层高度就是这段的滚动距离；离屏的动画由库自动暂停。窄屏可以缩短距离、降低幅度，但选定的手法都要保留。
+
+## 检查
+
+从头滚到底，再滚回去，各看一遍：往回滚是否倒放、跳到中段刷新画面是否正确、文字是否在静止时出现、窄屏选定的手法是否都在、开启“减少动态效果”后是否所有内容直接可读。

package/builtin/skills/oil-ui/references/style-explorer.md

@@ -0,0 +1,48 @@
+# 风格对比页
+
+把几个候选放在同一页里并排比较，由用户挑选。用户可以并排或单张查看、按实际尺寸看、选定并复制方向。对比页的外壳只负责比较和挑选，不带风格倾向，也不作为候选的参考。
+
+几个候选的核心内容、主要动作和目标用户保持一致，变的是构图、信息怎么组织、字体的气质、色彩关系、疏密和用图的方式。放几个候选，看用户要几个、真正有差别的有几个；不复制整个产品来凑数。
+
+## 准备输入
+
+一轮只生成一个对比页。候选能跑就用真实页面：单独写的 HTML 小样直接嵌入，项目里的方案用本机地址，拿不到可运行的页面时才用截图。每个方案一个画面：存量项目选入口或差别最大的那一步，整站方案只放代表页。
+
+把候选 HTML 放进一个目录后传目录，也可以直接传几个 HTML 文件。显示名取 `<title>`，没有标题时取文件名。同目录有 `manifest.json` 时会读取它补充方向信息；没有 manifest 也能生成。
+
+最小的 `manifest.json`：
+
+```json
+{
+  "candidates": [
+    {"source": "a.html"},
+    {"source": "b.html"}
+  ]
+}
+```
+
+| 特殊情况 | 在 manifest 里加 |
+| --- | --- |
+| 固定画布的界面 | 顶层或候选里加 `"nativeViewport": "宽x高"` |
+| 自己写的可操作小样 | 候选加 `"interactive": true` |
+| 需要启动服务才能看的页面 | 候选加 `"kind": "url"` 和本机 `url`；顶层可加 `serve` 启动说明 |
+| 改动已有页面 | 把现状也放进来，并加 `"baseline": true` |
+| 只有截图 | 候选加 `"kind": "image"`，`source` 指向截图 |
+
+HTML 和图片候选只需填写 `source`；本机地址候选按上表填写 `url`。候选来自方向卡时，每个候选再填 `name`、`concept`（北极星那一句）、`typography`、`palette`（色值数组）和 `traits`，对比页把它们和画面一起展示，用户靠这些挑选；省略的项不显示。其他字段写法见生成器的 `--help`。
+
+## 生成和打开
+
+```text
+python3 <skill>/scripts/build_explorer.py <候选目录>
+```
+
+也可以传多个 HTML 文件，或传 `manifest.json`。没有 `python3` 命令时换成 `python` 或 `py -3`。对比页默认生成在输入旁边，文件名是 `style-explorer.html`。修改候选后，要加 `--force` 重新生成，否则打开的还是旧画面。生成器会把要改的地方一次列出来。运行不了生成器时，把候选留给用户直接看，说明对比页还没有组装，不临时另写一套工具。
+
+有本机地址候选时，交付时让开发服务器开着。用户之后说“打开对比页”：读 manifest 里的 `serve`，在 `cwd` 里后台运行 `command`，等 `url` 能访问了再打开对比页。
+
+## 记录选择
+
+用户点“选择”会复制一句话，例如“<轮次>：选 03 <方向名>”。用户粘贴它或直接说出选择后，按轮次和编号对照当前 manifest，确认是这一轮的，把选择和备注更新到设计说明，再回到生成这个对比页的流程接着做。对比页不会写回任何文件，也不会自动给 Agent 发消息。
+
+交付前对候选目录跑一次 `node <skill>/scripts/shoot.mjs <manifest 所在目录> --size desktop --thumb --out shots/explore`（一次出齐各候选缩略图与并排总览图 `sheet.png`）核对候选：每张画面和 manifest 里写的页面、状态、视口一致，中文字体真实渲染出来了。判断文字大小和细节时用单张查看的“实际尺寸 100%”，适应窗口的缩小图不能当作可读性通过。对比页本身的功能由 Skill 自带的测试保证，任务里不验证、不读模板源码。

package/builtin/skills/oil-ui/references/task-explore.md

@@ -0,0 +1,28 @@
+# 显式探索与比较
+
+上级入口：[Skill 主流程](../SKILL.md)。只有用户明确要求比较设计方向、改动档位或版式时才进入本流程。它叠加在新建、重设计或存量任务上，不替代各任务的产品事实、锁定范围、制作和验收规则。领域模块只提供方法，不自行增加候选数量或重启选择流程。
+
+数量先服从用户；用户没有指定数量时才默认三个。比较改动档位时保留现状基线；比较版式时保持选定方向的字体、色彩和控件语法，只改变骨架、主视觉摆法和页面结构。内部概念、草图和素材候选的数量不随对外方向数量减少。
+
+## 先用文字收敛
+
+先沿主入口确定基础任务与适用的领域规则；按它要求的方案产物形成所需数量的对外方向。基础路径要求通用方向流程时，才按 [设计方向](design-direction.md) 完成产品事实、删减、概念、主视口灰度和过关检验。每个方向都必须适配且可落地，不靠极端颜色或构图制造差异，也不拿陪跑方案凑数。骨架按需读 [说服型骨架](direction-persuasion.md)。
+
+先用三四行写清每个方向的感觉、首屏、核心动作、字体、色彩和主视觉，附上推荐及理由，再问用户：按其中一个直接做，还是把这些方向做成首屏放在一起比。发给用户后这一轮结束。用户从文字里选定，或者已经说清想要什么，就只做选中的一个，不做对比页；用户要看实际画面，才制作多个首屏。
+
+只交付设计说明时止于方向卡，并说明未渲染。用户已经给定参考图、品牌规范或明确风格时，所有方向都留在这个风格里，只在骨架、主视觉和页面结构上拉开。
+
+## 用户要看实际画面
+
+按 [风格对比页](style-explorer.md) 把各方向首屏放在一起。每个方向一个 HTML 文件、一个视口、只做首屏和主状态，不提前铺成多个完整页面；不写交互、响应式和动效，不取证，不派画面评审。宿主支持并行制作时按方向分工，不让多个执行者同时修改同一份共享样式。
+
+- 各方向共用同一份产品事实和示例数据，只写一次；结构、样式、标题、副标题和主视觉各写各的，不用同一模板换几组样式凑数。
+- 主视觉靠图的方向按 [素材](media.md) 生成一张，至多重新生成一次；页面已有专项候选流程时按专项，不重复增加生成批次。其余图位先用从页面取色的色块占着。
+- 对候选目录统一截图，一次出齐缩略图与并排总览 `sheet.png`，主 Agent 亲自看过，只修重叠、裁切和明显粗糙后交付。
+- 附上推荐理由，请用户选定方向并说出具体喜欢和不喜欢哪里，然后结束这一轮。
+
+用户说了“你定”“直接做”，或者无人值守时，不问并自主选定，但仍只在明确探索时制作这些候选。把截图缩到 480px 宽并排看一次，写下选择理由，再只深化选中的一个。
+
+## 比较版式
+
+先用文字写出两三种骨架的差别；能从文字选定就只做一个，要看实际画面再做成首屏，连同选中的方向放进对比页。用户只回复选哪个，就并入意见直接做完整页面；想拼合两个方向时，先做出拼合后的首屏给用户确认。

package/builtin/skills/oil-ui/references/task-review.md

@@ -0,0 +1,8 @@
+# 只读评审
+
+上级入口：[Skill 主流程](../SKILL.md)。用户只要评审时，本流程只交付证据、诊断和建议，不修改产品文件，不生成新方向，也不进入制作后的修正循环。
+
+1. 写清评审对象、用户目标、设备与已知约束；只读取相关页面、截图和材料，不通读整个项目。比较已有方案时保持它们现有的内容和范围，不先补齐成自己的设计。
+2. 能运行或看图时取得真实证据；不能时明确限制，不把推测写成实际视觉或交互结论。按 [视觉评审派发协议](visual-review.md) 选择适合现有界面或候选方案的评审方式，评审标准由评审者读取，主 Agent 只交接材料。
+3. 有隔离且能看图的执行者时，派没有制作历史的评审者；没有则由主 Agent 自检，并在结果中写明“未独立评审”。需要验证主要流程时，按 [轻量 UX 走查派发](ux-review.md) 取得任务走查证据；纯视觉评审不额外走查。
+4. 报告按影响排序，写清位置、观察、依据和建议；比较方案时分别说明适配与代价，再给选择建议。交付报告后停止，不修正、不实现建议，也不顺便扩展任务范围。