@chinhae/atw-cli 0.4.0 → 0.6.0

package/dist/templates/common/bundled-skills/atw-ui/references/media.md

@@ -1,45 +1,142 @@
 # 素材
 
-## 把资产作为设计起点
+图从哪来、承担什么、怎样和页面接成一体。游戏、收集和养成类产品要的角色、道具、藏品和图集，见“成套素材”。
 
-好的资产可以承担整个页面的情绪、对象识别或信息重心。先问“如果只保留一张图、一个标题和一个动作，哪张图值得占据这个位置”，再决定是否需要更多模块。不要把资产理解为布局完成后填进去的装饰。
+## 目录导航
 
-跟随设计北极星决定图像的主体、视角、尺度、光线、颜色、材质和留白。页面的字体、背景、边缘处理与运动从这张图建立呼应；也可以通过一个受控的反差突出主动作。统一是共享视觉逻辑，不是对所有图片套同一个滤镜。
+- [先定图承担什么](#先定图承担什么)
+- [复用、生成，还是交给代码](#复用生成还是交给代码)
+- [让图承担意思](#让图承担意思)
+- [写提示词](#写提示词)
+- [生成后放进页面再判断](#生成后放进页面再判断)
+- [让图和页面接成一体](#让图和页面接成一体)
+- [让一张画当舞台](#让一张画当舞台)
+- [异质素材的单色化统一](#异质素材的单色化统一)
+- [抽象技术的主视觉推导](#抽象技术的主视觉推导)
+- [成套素材：角色、道具与图集](#成套素材角色道具与图集)
+- [实时 3D](#实时-3d)
+- [生成视频的可选路径](#生成视频的可选路径)
+- [文件与说明](#文件与说明)
 
-后台和工具同样需要资产判断：对象缩略图帮助识别，内容封面支持浏览，地图或空间图帮助定位，必要的示意图解释关系。它们可以成为界面最有价值的部分；不以“这是后台”为由默认只有表格和卡片。纯数据任务确实不受益时保留清楚的数据表达，不硬塞气氛图。
+## 先定图承担什么
 
-资产要成为结构，而不是装在盒子里的插图：让它跨过版面的分界、占满首屏，或者和文字叠在一起。页面可以是一个完整的世界，而不是“一张页面配一张图”。
+素材是设计的起点，不是布局完成后填进去的装饰。先问：如果只保留一张图、一个标题和一个动作，哪张图值得占据这个位置？再决定是否需要更多模块。
 
-先把关键资产放进真实页面看一轮，再延展其他区域。资产未到位时不能把占位版的审美评审视为最终通过。
+- **分清差距来自哪里。** 是信息和构图的问题，还是确实缺一张能表达产品和品牌的图。不用更多图片、光效和动画掩盖层级问题，也不因为代码好写，就用通用渐变和几何形状顶替必要的图像。
+- **给每张图一句任务。** 它展示对象、解释关系，还是建立品牌和情绪；要让人一眼看懂什么。答不上来就先别找图，也别生成。图已经说清的，文字不再重复。
+- **后台和工具同样要判断。** 对象缩略图帮助识别，内容封面支持浏览，地图或空间图帮助定位，示意图解释关系；它们可以是界面最有价值的部分。纯数据任务确实不受益时，保留清楚的数据表达，不硬塞气氛图。
+- **图跟着北极星定，页面再和图呼应。** 主体、视角、尺度、光线、颜色、材质和留白由设计北极星决定；页面的字体、背景、边缘处理和运动从这张图建立呼应，也可以用一处受控的反差突出主动作。同组的图统一主体尺度、视角、光线和边缘质感，不是给所有图套同一个滤镜。
+- **图是结构，不是装在盒子里的插图。** 让它跨过版面的分界、占满首屏，或者和文字叠在一起，做法见“让图和页面接成一体”。
+- **先放进真实页面看一轮，再延展其他区域。** 素材没到位时，占位版的审美评审不算最终通过。
 
-没有合适的现成资产且宿主已有可用的图像生成能力时，主动制作关键素材，并给它明确的视觉任务；不要因为正在写前端代码就省略这一步。已有优秀素材时围绕它设计，不为证明使用了工具而重复生成。没有相关能力时保留清楚的素材简报与待完成项。
+## 复用、生成，还是交给代码
 
-## 先确定表达作用
+- **有合适的就复用。** 实际看过图再引用它的特征；已有好素材时围绕它设计，不为证明用了工具而重复生成。
+- **没有就做出来。** 没有合适的现成素材、宿主又能生成图片时，主动制作关键素材，不因为正在写前端代码就省掉这一步。按宿主生成工具自己的输入和编辑规则来。
+- **文字和界面交给代码。** 文字、按钮、表单、数据标签和常规布局一律由真实 HTML/CSS 排版，不让生图模型画，也不拿完整截图当可交互的成品：生图画字容易出错，改不了，也不能被选中和读屏。图片只负责物体、材质和光影。
+- **做不了就留简报。** 没有生成能力或图暂时缺着时，预留合适的容器，写一份能执行的素材简报：要表达什么、主体是什么、放在哪、宽窄屏怎样裁切、哪里承载文字、什么细节不能丢。不自动安装工具、切换收费服务，或要求用户把密钥粘进对话。
+- 要转动、有物理或随视角变化的对象见“实时 3D”；预先确定的连续变化见“生成视频的可选路径”。
 
-判断当前差距来自信息与构图，还是缺少能够表达产品和品牌的素材。不要用更多图片、光效和动画掩盖层级问题，也不要仅因代码容易编写，就用通用渐变和几何形状替代必要的图像。
+## 让图承担意思
 
-素材可以用于展示对象、解释关系、建立品牌或情绪。先确定内容、位置、尺寸比例、裁切、背景和与文字的对比，再选择现有资源、摄影、插画或生成素材。
+生成图最常见的失败不是画得不好，而是画得太满：细节越丰富越像图库照片，放进版面后没有重点，也和页面没有关系。
 
-素材简报保持可执行：要表达什么、主体是什么、放在哪、宽窄屏如何裁切、哪里承载文字、什么细节不可丢失。若画面已经表达了主题，减少重复解说；叠字区域需有稳定明暗和足够空间，不默认给整张图盖浓重渐变。
+“一张好看的使用场景”不是图的任务；“产品把一堆混乱变成了哪几个清楚的结果”才是。用对比把信息编进图里。整体统一成一种低调的材质或颜色，比如白模、单色、失焦或剪影，只让承载信息的少数几处有颜色、光或细节。所有地方都一样精细，就等于没有重点；第一版通常就是这样失败的。
 
-## 图片与可编辑界面
+选能和页面“接上”的主体：
 
-实际查看输入图片后再引用其特征。复用质量合适且有使用依据的资源；不足时才生成或重绘。保留原始文件及来源，区分复用、裁切、生成和后处理。
+- 能跨过两块色面分界的单个物件。
+- 能延伸出画面的线状物。
+- 能在上面标注的空间：模型、地图、剖面、平面图。
 
-界面文字、按钮、表单、数据标签和常规布局由可编辑元素表达，摄影、插画和特殊视觉放在明确容器中。不把完整截图作为可交互成品。
+这样的主体，之后能和页面里的线、标注和区块连成一体；一张自给自足的风景照做不到。
 
-将素材需求交给宿主可用的生成工具，遵循工具自身的输入与编辑规则。怎样让生成图承担意思、怎样写提示词、怎样把图和页面接成一体，见 [配图](imagery.md)。
+## 写提示词
 
-图像暂缺时预留合适容器并明确缺项，不自动安装工具、切换收费服务或要求用户把密钥粘进对话。替代素材不能冒充真实产品截图。
+按固定顺序写，每项一两句：
 
-同组资产统一主体尺度、视角、光线和边缘质感，避免几张各自漂亮却互不相干的图拼在一起。生成素材不冒充真实现场或产品证据。最终交付保留来源与用途，网页按实际显示尺寸处理文件体积，重要主体在桌面和手机裁切中都必须成立。
+1. **主体与表现形式**：什么东西，用什么体裁呈现（照片、插画、模型或图解），体裁从页面的方向推出。
+2. **构图与留白**：主体在画面里的位置和占比，哪一块留空给文字。按已选的首屏骨架写出主体所在的区域和占比，以及留给文字的那一块要完全干净。留白区不要有高光、反光或杂乱纹理，保证文字清晰好读。
+3. **安全距离**：主体、托台与阴影不要贴到文字边缘，留出 10% 左右的空隙，防止屏幕变窄时文字压到物体上。
+4. **背景**：直接写出页面实际使用的十六进制色值，或者要求纯透明背景。色值一致时边缘自然融进网页，不需要额外用 CSS 遮罩去修。
+5. **材质与光**：主光方向、辅光、质感。同一页的多张图用同一个光向。地面反光向留白侧自然衰减，不横扫到文字区。
+6. **排除项**：不要任何文字、标志、伪代码、界面截图或多余漂浮物；小件图标或透明图注明“不要地面投影”，外部投影交由前端 CSS `filter: drop-shadow(...)` 控制。
+
+## 生成后放进页面再判断
+
+在真实页面、真实尺寸里看，不在图片查看器里判断。单独看很好的图，放进版面后常常主体太满、朝向不对、留白在错的位置。
+
+不对就改提示词重新生成，并写清要改什么，例如“主体往右移，左边留出一半空间”“去掉地面反光，背景换成页面的色值”。不要围着一张不合适的图改版式。同一批里挑最能排版的一张，不挑细节最多的那张。
+
+## 让图和页面接成一体
+
+**背景融合。** 不透明的图，从图的四角实际取色，页面背景用同一个值；四条边都淡出到这个颜色，不加框，也不放进圆角卡片。淡出可以用 CSS 遮罩，也可以在导出时直接把边缘渐隐成页面色值。背景为纯色时，若提示词背景色与网页完全一致，边缘就能自然无缝过渡。
+
+**透明图。** 先放在最终背景上检查边缘、白边和残留的棋盘格；检查透明通道要看像素，不能看文件后缀。阴影不烘焙在图里，由页面按实际背景加投影，这样换了背景也对。
+
+**跨越结构。** 透明物件放在两个色块或两个区块的分界线上，让它同时属于两边。
+
+**图和代码接力。** 生成图负责代码做不出来的材质和光，例如金属、玻璃、模型、光影。代码负责需要精确、可编辑、会延续的部分，例如从图里延伸出去的线、路径和标注。如果图里有一段本该延续到页面的部分，就把它裁掉，改用矢量接着画。这样它能准确穿过版面，带上真实文字，并在不同宽度下重新走线。
+
+**标注。** 在图上标注用细引线加文字，不用带底色和阴影的气泡卡片。引线端点要对准图里的真实位置：图在版面里用固定的尺寸和位置，按图片像素换算坐标。窄屏上隐藏标注，或改成图下的列表，不让它们漂移到错误的位置。
+
+**窄屏裁切。** 不把整张大场景等比缩小到看不清。从原图裁出焦点区域另存一张给窄屏用，或用对象定位对准焦点。桌面和手机两种裁切，都要保住承载信息的那几处。
+
+**一张图用多次。** 结尾或其他区块可以用同一张图的局部特写，比再生成一张光线和风格对不上的图更统一。
+
+## 让一张画当舞台
+
+另一种用法正好相反：图不讲信息，只给气氛，界面保持黑白克制，全页只用一种有笔触的画当唯一的颜色来源。
+
+- **画当舞台，界面在上面演示。** 把真实界面的简化版放在画上，画从四周露出来。滚动时画固定不动，只换前面的界面内容，和“滚动叙事”接得上。
+- **大胆裁切。** 只留画的一角或一个局部，接近抽象，不和界面抢。题材不必和产品字面相关，但气质要对得上。
+- **松和紧互相衬托。** 画越松，界面越要精确、干净；两者一起出现，彼此都更好看。
+- **用得少。** 一张画贯穿全页，或者只在两三处出现，例如价格卡的顶端和页脚；不要每个区块配一张。同一页的画统一画种和笔触。
+- **演示用简化过的真实界面。** 次要内容虚化或换成骨架，只把要讲的那一处做清楚；数字对比直接用界面元素画出来，例如两条长短不同的进度条，而不是另做一张图表。
+
+## 异质素材的单色化统一
+
+引入历史画作、雕像肖像或外部摄影素材时，彩色位图容易与界面的主题色产生冲突。可以通过统一的单色处理将不同来源的素材收拢到当前方向里：
+
+- **单色映射**：将素材转为黑白高对比后，把暗部与亮部映射到页面的主色与底色。
+- **网点与点阵抖动**：对写实图片做半色调网点化或微弱的扫描线处理，消解照片的写实质感，让它能和排版、网格共处。
+
+## 抽象技术的主视觉推导
+
+缺少产品截图时，不回退到通用的彩色发光球或大渐变。从产品处理的东西里找一个有形的对象：它读写的数据长什么样，它替代的那件工具或那道工序是什么，它的用户手边有什么。表现形式满足两条：大面积色阶平稳，文字压得住；画面里的线和标尺能由 SVG/CSS 接着画。找不到有形的对象时，主视觉交给排版本身。
+
+## 成套素材：角色、道具与图集
+
+游戏、收集和养成类产品要的不是一张配图，而是一整套会被反复摆放、翻转、比较的素材。
+
+- **先写风格说明。** 画法、视角、光向、材质、比例和色板各写一句，同一批的提示词都按它写。
+- **同系列靠轮廓区分。** 统一比例和光向，用耳朵、道具、配饰这类轮廓特征区分个体，不只换颜色。缩到实际显示尺寸还要能一眼分开。
+- **多状态从同一张改出来。** 生长阶段、正反面、开壳前后、不同动作，以第一张为参考图编辑出变体，保持是同一个角色；各状态的落地点对齐到同一条基线。
+- **透明图集按轮廓切。** 格子之间留透明间距，按实际轮廓裁切，不按格子均分，否则会切掉树冠、带进邻格的残片。检查 alpha 像素，不看预览图的背景色，再放到最终背景上看边缘。
+- **贴到物体上要两面成立。** 会翻转、落下或转到侧面的素材，正面背面都要有，边缘沿轮廓闭合。受光交给场景，不在图里烘焙和场景方向相反的光影。
+
+## 实时 3D
+
+三类情况用实时 3D：用户要转动、检视的对象；堆叠、碰撞、推挤、摆动这类物理；玻璃、金属、透明塑料这类随视角变化的材质。一张生成图就能表达的，或者只为了显得高级，都不用。
+
+- 用 three.js 这类成熟引擎，需要物理时再配一个刚体库。生成的图当贴图、精灵或环境光来源，代码负责空间、运动和受力。
+- 验收看画面，不看用没用库：静帧看得出体积和透视，物体有接触阴影，关掉发光仍分得清材质；录屏里运动连续，力能传到被推的物体上。
+- 新建的小样把库下载到任务目录的 `vendor/` 并附许可证，不引用 CDN；存量项目按项目已有的依赖方式引入。以模块方式引入的页面和贴图要通过本地服务器打开；要求双击就能打开时，打包成一个普通脚本，贴图内联或放在同目录。
+- 设备像素比上限取 2；页面隐藏或滚出视口时停帧；拿不到 WebGL 时显示同一场景的静态图；减少动态效果时照常算出结果，只关镜头晃动和装饰演出。
+- 截图前确认画布真的画出了内容，见 [工具](tools.md)。
 
 ## 生成视频的可选路径
 
-需要可叠加的循环素材时，先验证首尾衔接、主体边缘和背景处理。单色背景加抠像只是候选技术；透明、反光物体可能丢失边缘或产生色溢，应在最终页面背景上检查。
+要一段能叠在页面上循环播放的素材时，先检查三样：首尾接不接得上，主体的边缘干不干净，背景处理得怎么样。在单色背景上生成再抠像，只是可以试的办法之一：透明和反光的物体抠完可能丢边，或者带上背景的颜色，要放到最终的页面背景上看。
 
-需要连续叙事时，可以用前一段的末帧衔接下一段的首帧，或使用一致的关键帧规划。按滚动或手势控制播放进度时，检查寻帧、反向播放、加载和内存占用，不默认把整段视频解码成全部大图。
+要把几段视频连成一段叙事时，可以拿前一段的最后一帧当下一段的第一帧，或者事先把各段的关键帧统一规划好。播放进度由滚动或手势控制时，要检查跳到任意一帧、倒着播、加载速度和内存占用，不要默认把整段视频解码成一张张大图。
 
 玻璃、水晶这类需要折射或透光的物体，先在最终页面的背景色上生成画面，让折射和投影烘焙进素材，再用视频抠像模型去掉背景。直接在绿幕上生成再抠像，折射会带着绿色。预渲染的折射和光照只对应生成时的背景，不应承诺会随任意页面内容产生实时物理效果。
 
-透明底的图片或视频适合放在两个区块的衔接处，跨越边界，把上下两部分连成一个画面，比放在容器里更有设计感。
+透明底的视频和图片一样，可以跨在两个区块的分界上，做法见上文的“跨越结构”。
+
+## 文件与说明
+
+- 按显示尺寸的 2 倍导出，不直接内嵌原始大图。不透明的图用 JPEG 或 WebP，透明的用 WebP 或 PNG；单张控制在几百 KB 以内。内嵌成 data URL 后体积会再大约三分之一。
+- 保留提示词、原图和处理后的版本，写清每张图的来源、用途和处理方式，分清复用、裁切、生成和后处理。
+- 生成图和替代素材不冒充真实产品截图、真实场所、真实人物或产品证据。图片是 AI 生成的，写进交付说明，不写进界面。

package/dist/templates/common/bundled-skills/atw-ui/references/motion.md

@@ -1,18 +1,24 @@
 # 动效
 
-## 先问值不值得
+## 每个界面先做三处动效
 
-加动效前先问：如果要手写一周才能做出来，还值得做吗？模型让动效变得免费，但滚动淡入、视差、跟随鼠标和装饰性循环都会增加干扰。每个动效都应承担反馈、引导、连续或品牌表达中的一项。
+完全不动的界面像一张截图：按下没有回应，切换没有来路，用户只能猜刚才发生了什么。新界面和改动了操作流程的界面，先把这三处做出来，手感写进方向卡的“动效”一栏，改流程和加新功能时写进设计说明：
+
+1. **主操作的反馈。** 按下立刻有回应，完成时交出一个结果：按钮陷下去再弹回，勾号画出来，数字滚到新值。
+2. **一处状态切换的来路。** 选中、展开、换视图、增删列表项时，让人看见东西从哪里来、到哪里去，见下文“界面过渡”。
+3. **第一次进入时的一次出场。** 主角先到，其余按阅读顺序跟上，只在首次进入时播放。
+
+这三处之外再加的动效，每个都要承担反馈、引导、连续或品牌表达中的一项；滚动淡入、视差、跟随鼠标和装饰性循环最容易变成干扰。
 
 | 目的 | 适合考虑的方式 |
 | --- | --- |
-| 按下、聚焦、展开或普通状态变化 | 原生能力或已有组件的小范围过渡 |
+| 按下、聚焦、展开或普通的状态变化 | 用浏览器原生的过渡，或已有组件自带的小过渡 |
 | 视图之间的切换、元素换位置 | 共享元素过渡，见下文“界面过渡” |
-| 拖拽、手势、空间变化与复杂编排 | 项目已有成熟动效能力 |
-| 特殊品牌画面、材质、复杂物理效果 | 图片、3D、着色器或预渲染视频，按需求取舍 |
-| 鼠标、触控或滚动控制叙事进度 | 将输入映射到明确的动画进度，处理反向和快速操作；思路见下文“滚动叙事” |
+| 拖拽、手势、位置和大小的变化、多个元素配合的动画 | 用项目里已有的成熟动效库 |
+| 特殊品牌画面、材质、复杂物理效果 | 图片、3D、着色器或预渲染视频，按需求取舍；什么时候用实时 3D 见 [素材](media.md) |
+| 用鼠标、触控或滚动控制一段叙事的进度 | 让动画的进度直接跟着输入走，往回滚和快速操作都要处理好；见 [滚动叙事](scroll-narrative.md) |
 
-代码动画适合需要精确状态控制的界面，生成视频适合预先确定的视觉变化；不能用视频替代需要动态数据与真实操作的控件。
+需要精确控制状态的界面，用代码写动画；画面怎么变早就定好的，可以用生成的视频。要显示实时数据、要让人真的去操作的控件，不能用视频代替。
 
 ## 手感
 
@@ -33,6 +39,24 @@
 
 网页可以把弹簧写成缓动曲线：按刚度和阻尼对位移做数值积分，取 20–30 个采样点写进 `linear()`，时长取位移稳定在终点 0.5% 以内的时刻。不支持的浏览器退回相近的 `cubic-bezier`。
 
+必须做的动效之外（三处基本动效，落地页类页面的区块出场和滑动驱动的叙事），每多加一个先问值不值得：如果要手写一周才能做出来，还会做吗？模型让动效变得免费，它分走的注意力并没有变少。值得的再按上表定手感，不值得的不加。
+
+## 呼应：让动作彼此接上
+
+一个动作引起的变化沿同一条路传下去，前一段的终点是下一段的起点；不要按钮、面板和数字各动各的。
+
+- **从被操作的地方出发。** 点“加入购物袋”，商品缩成一个点飞进袋子，袋子上的数字跟着跳一下；删掉一行，它朝删除按钮的方向收走，下面的行补上来。
+- **一次切换朝一个方向。** 卡片往左滑，标题、序号和底色也往左换；数字往上滚，进度也往上涨。方向一乱，就成了几段互不相干的动画。
+- **主角先动，其余被带动。** 被影响的东西晚 40–80ms 跟上，幅度更小，像被主角拉过去的。全部同时起跑、同样幅度，看起来只是一起闪了一下。
+- **形状接力。** 上一个状态里的元素变成下一个状态里的元素：按钮展开成面板，搜索图标拉长成输入框，播放键变成暂停键。用户一眼看出它们是同一个东西。
+- **动法和画面是同一种材质。** 动作的轻重、停顿和回弹从方向卡的生成引擎和控件语法推出。
+
+### 巧思从产品里找
+
+巧思是让一处动效讲出这个产品自己的事，不是加更多花样。写成一句：这个产品里的哪样东西，因为用户的哪个动作，发生了只有它才会有的变化。
+
+找不到这样的动作，就把三处基本动效做准，不硬造。一页最多一两处巧思，其余动效安静、短促。
+
 ## 界面过渡
 
 **连续。** 用户点的东西就是下一屏的主角。从列表进入详情，被点的那一项放大成详情，其他项淡出；返回时它缩回原位，页面回到原来的滚动位置。原位已经不在视口里，就先把它滚到可见，再缩回去。
@@ -51,6 +75,16 @@
 
 **到头要有反馈。** 已经是第一项或最后一项时，轻轻顶一下（往返 10–15px），而不是毫无反应。
 
+### 整页转场的稳定性取舍
+
+整页切换和组件的过渡不一样：旧页面要卸载，新页面要挂载。按稳不稳、难不难做，分三类：
+
+- **遮罩式（Curtain / Wipe）。** 用一块纯色、纹理或几何形状划过或盖住整个屏幕，趁挡住的时候卸掉旧页、挂上新页。它最简单、最稳，两个页面的结构互不相干，绝大多数页面都适合。
+- **交叠式（Overlapping）。** 新旧两页同时在屏幕上，互相错开、推挤，或者分层淡入淡出。看起来连贯，但两页的 DOM 要同时存在，层级和内存都要管好。
+- **共享元素式（Shared Element）。** 一个关键元素从旧页一直变形到新页，例如缩略图放大成详情页的主图。看起来最顺，也最容易出问题：用户快速双击、中途打断、后退，或者视口变了，都容易错位和闪烁，所以必须留好退路，出问题时直接显示到位的状态。
+
+第一次进站的加载屏（Splash），可以在等大文件加载的时候放一小段叙事或进度；站内的页面跳转，时长按下面“时长和幅度”里整页切换的取值，不让转场挡着用户看内容。
+
 ## 时长和幅度
 
 | 对象 | 时长 | 要点 |
@@ -61,37 +95,27 @@
 | 整页或视图切换 | 350–500ms | 超过 500ms 就会让人等 |
 | 首次进入时依次出现 | 每项间隔 40–80ms | 总长不超过 600ms；只在首次进入时播放，重新渲染和恢复状态时不重播 |
 
+这张表管的是界面操作。游戏和抽奖的演出时长见 [游玩](play.md)。
+
 悬停上浮 2–4px，阴影随之加深。位移超过 20px 的悬停效果会显得轻浮。
 
 ## 看不见的结果要说出来
 
 一次点击产生了看不见的副作用，例如复制到剪贴板、后台保存、发送，就用一条短暂的提示说出结果本身，例如“已复制：……”，而不是只说“成功”。确认类的时刻，例如选中或完成，可以用一次小幅弹出，只在状态第一次变化时播放，重复点击不重播。
 
-## 滚动叙事：视差与一镜到底
-
-滚动当作翻页，它只是翻页；当作摄影机的推拉，页面就能讲故事。品牌、发布和叙事页可以这样做，文档、文章、工具和后台不做；一页最多一段。记忆点先放在用户会做的动作上（点按、拖动、悬停），再考虑滚动；不要把整页做成视差秀。
-
-- **一镜到底。** 整段是一次不切换的镜头。一个主角从头走到尾，可以是产品、一根线、一个形状或一个字，每一步长成、变成或让出下一个画面：推近看到细节，拉远看到全貌，转过去看到背面，穿过去进入下一个场景。动手前先画分镜：每个镜头占多少滚动距离、画面里有什么、什么在动、文字什么时候出现。
-- **停下来再说话。** 每个镜头留一段静止，文字在静止时出现；边动边读很累。
-- **视差要有真实的前后。** 只在画面本来就有远近层次时用：前景的物体、中景、远处的背景，越近动得越多，差别要小。文字不做视差。
-- **转场也是镜头。** 一个圆从某一点扩开，带出下一节；推进一张图，穿过它到达下一节；背景色在章节之间随阅读慢慢变；一句宣言随滚动逐字亮起。每种手法一页只用一次。
-- **倒着滚也成立。** 每一帧只由滚动位置决定，往回滚自然倒放，刷新或跳到中间也立刻是对的画面。不接管用户的滚动。
-- **留出口。** 长段落前给一个跳过入口；减少动态效果时，把每个静止画面按顺序排成普通区块。
-- **代码做不出来的，交给视频。** 用户想要很强的首屏动画，而效果要靠生成视频或序列帧才做得出来，例如角色转身、产品拆解、镜头穿越场景，按 [素材](media.md) 里“生成视频的可选路径”处理；宿主没有视频生成能力时，交付明确的素材需求。CSS、SVG、着色器能完成的仍自己做。
-
 ## 体验与性能
 
-沿用项目的运动节奏和组件能力。高频操作反馈直接，不让动画延迟业务完成。
+项目里已有的动效节奏和组件能力先沿用。经常要做的操作，反馈要立刻给，不让动画拖慢事情本身。
 
 动画要能被打断。连续快速操作时，新动画从当前位置接着走，不跳回起点重播。CSS 过渡会从当前值重新出发，适合高频切换；关键帧动画会从头重播，适合一次性的出场。业务状态立即更新，不等动画结束。
 
-网页连续动画优先用变换与透明度，只声明需要变化的属性；小尺寸的指示块可以直接过渡宽高。逐帧工作要有停止和清理条件，避免频繁交错读写布局，离屏或无任务时停止播放。整页过渡期间页面通常不响应点击，所以整页过渡要短。
+网页上连续播放的动画，优先只动变换和透明度，过渡里只写会变的那几个属性；很小的指示块可以直接过渡宽高。每一帧都要执行的代码，要有停下来和清理的条件，不要一会儿读布局、一会儿写布局地来回交替；滚出屏幕或没事可做时就停。整页过渡期间页面通常点不动，所以整页过渡要短。
 
-明显位移、缩放和滚动特效，要为“减少动态效果”提供等价呈现，此时所有状态直接到位。必要信息和主要操作不能依赖自动播放、声音或动画完整结束。
+有明显位移、缩放或滚动特效的地方，要照顾开了“减少动态效果”的用户：这时所有状态直接到位，内容一样不少。必要的信息和主要的操作，不能等自动播放、声音或动画播完才出现。
 
 ## 检查动效
 
-静态截图证明不了动效。把播放速度调到 10%，可以用浏览器开发者工具的动画面板，或自动化工具里的动画倍速，在过渡进行到一半时截图。看有没有重影、跳动、元素突然出现，或者从奇怪的位置飞来。逐个检查开始、中间、结束和反向；再快速连按几次，确认不会卡在中间状态。最后开启“减少动态效果”再走一遍。只有实际测量后才报告帧率或性能改善。
+按正常速度操作一遍，再往回操作一次、快速连按几次：没有重影和跳动，元素不突然出现，不从奇怪的位置飞来，不卡在中间状态。开启“减少动态效果”后内容直接可读。必须做的之外，每个动效都要说得出它承担反馈、引导、连续或品牌表达中的哪一项，说不出的删掉。只有实际测量后才报告帧率或性能改善。
 
 ## 网页实现提示
 

package/dist/templates/common/bundled-skills/atw-ui/references/play.md

@@ -0,0 +1,18 @@
+# 游玩与强手感操控
+
+小游戏、抽奖、扭蛋、计时养成，以及旋钮、拉杆、摇杆这类强手感操控，过程本身就是产品：用户来看转轮减速、硬币被推下、娃娃差点滑落。这类界面先读本文，其余规范照常适用。
+
+## 过程即玩法
+
+- 演出可以比普通界面切换长，例如三个转轮依次停下共 2 秒左右，不按“超过 500ms 就会让人等”截短。
+- 扣了费、出了结果就先存好：刷新不丢，不重复扣，奖励只结算一次。在哪一刻存，按玩法定。
+- 演出期间写清哪些操作锁住；连按不能重复扣费。
+- 旋钮、拉杆这类手势从按下的位置开始跟手，过了生效点才算一次，没到就松手不扣。
+- 减少动态效果时，玩法照常算出结果，只是画面直接到位；不能把玩法本身停住。
+- 手感看录屏判断：减速是否连续、停下时有没有顿挫、收益从哪里飞到哪里。三帧只能说明状态。
+
+## 素材与渲染
+
+- 角色、藏品、道具、符号和材质贴图是这类界面的主角，默认用生图做，动手前先列素材清单。手写 SVG 和 CSS 只画界面图标和简单图形，拿它们画角色和道具，会落到图标包的质感。成套出图的做法见 [素材](media.md) 的“成套素材”；宿主没有生图能力时，按同一份文件交素材简报，不拿手画的图形冒充成品。
+- 乐趣来自空间和物理时，用实时 3D 渲染场景，例如堆叠、碰撞、推挤、摆动，或透明、金属材质；生成的图当贴图和精灵用，做法见 [素材](media.md) 的“实时 3D”。树木生长、天气这类自然变化，用成套生成图通常更好。
+- 素材放进场景后再看一次：受光和场景一致，有接触阴影，侧面、背面和翻落时不露出纸片的边。图生成了，不等于放进场景就可信。

package/dist/templates/common/bundled-skills/atw-ui/references/reviewer-manual.md

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

package/dist/templates/common/bundled-skills/atw-ui/references/scroll-narrative.md

@@ -0,0 +1,98 @@
+# 滚动叙事
+
+## 落地页的滚动动效
+
+落地页、品牌页、产品发布页和展览页，滚动动效和 [动效](motion.md) 的三处基本动效一起验收；文档、文章、工具和后台不做。用成熟的动效库实现，见下文“动效库”。
+
+**必须有两样**：首屏以下的区块按内容出场；至少一段滑动驱动的叙事，主角在滚动里发生明显变化。**手法按页面挑**：首屏景深、字标收进导航、一镜到底、章节转场镜头、背景随章节变色、宣言逐字亮起，从这个页面的主视觉和内容里选合适的，写进分镜并说明为什么选它。下面先说首屏景深，它是首屏有主视觉和大标题时最常用的一种。
+
+### 首屏景深（适合首屏有主视觉和大标题的页面）
+
+首屏是一个固定住的舞台，滚动直接驱动里面的层次变化，往回滚就倒放：
+
+- 首屏固定 100–200vh 的滚动距离，窄屏可缩到 80–120vh。
+- 至少两层以不同速度、不同方向变化。最常用的是主视觉和大标题反向缩放：主视觉从 1 缩到 0.8，标题从 1 放大到 1.25；或者反过来，主视觉推近、标题后退。背景层动得最慢，前景层最快。
+- 幅度要大到录屏里一眼看出来：主层缩放不少于 15%，或位移不少于 15vh。小于这个幅度，看起来就是页面在普通滚动。
+- 大标题是图形层，可以缩放和视差；正文、按钮和表单不缩放、不做视差，固定后保持可读可点。
+- 结束状态要交接给下一节：主视觉缩到下一节的位置，标题退成背景纹理，或者画面让出一条路给下一节的主角。不要固定结束后整块直接被推走。
+
+首屏是满版的品牌字标时，用下面的“字标收进导航”。首屏是其他满版文字、产品界面或纯排版时，不一定适合景深，可以把滑动驱动的叙事放在后面。
+
+### 字标收进导航（适合首屏是满版品牌字标的页面）
+
+首屏就是品牌名本身，滚动时它缩成导航栏里的标志。它用一个元素同时完成满版文字骨架和一段滑动驱动的叙事，适合品牌名短、字形有性格的工作室、品牌和作品集：
+
+- 首屏只有这一个字标，撑满版心宽度，窄屏也保持一行撑满；导航里不再放第二个标志。
+- 滑动驱动，滚过 60–100vh，字标沿一条路径缩到导航标志的位置和尺寸，往回滚放大回来。结束状态就是导航里的标志，位置和尺寸按导航实际量出，交接时不跳。
+- 缩放同一个元素的变换，不动画字号；字标用 SVG，或按容器宽度算出的字号。
+- 字标让出首屏的同时，下一节内容已经进入画面，不留一整屏空白。
+- 字标从满版缩成导航标志，是主角明显的缩放和一次交接，算一段滑动驱动的叙事；同一页不再另做首屏景深。
+- 减少动态效果时，字标留在首屏不缩放，导航从一开始就显示标志。
+
+### 区块按内容出场（必须，滑动触发）
+
+首屏以下的每个区块，滚到位置时出场一次，往回滚不重播。出场方式从这个区块的内容和材质推出来，并且符合物理直觉：有重量的落下会过冲后稳住，轻的东西有空气阻力，机械的东西咔嗒到位。
+
+| 区块内容 | 出场方式 |
+| --- | --- |
+| 卡片、实物、价格牌 | 带重量落下后稳住，过冲幅度见 [动效](motion.md) 的“手感”；后一张被前一张带出 |
+| 列表、时间线、步骤 | 沿阅读方向依次展开，连接线先画出，节点随后落位 |
+| 数字、指标 | 滚到目标值，高位先停、末位后停；不从 0 起跳的用原值起滚 |
+| 线条、图表、路径 | 沿数据或流程的方向描出，端点落定时轻微放大一下 |
+| 图片、照片 | 遮罩从画面主体的方向揭开，图片同时从 1.08 回缩到 1 |
+| 纸、布、标签 | 先快后慢，带一点旋转后摆正，像被放到桌上 |
+| 金属、机械、硬件 | 短促到位，没有软弹，可以带一次很小的回震 |
+| 大标题、口号 | 按词或按行从遮罩里升起，字距从略松收紧 |
+
+规则：
+- 每个区块的出场写进分镜。同一页最多两个区块用同一种出场。
+- 曲线用弹簧或惯性，参数从 [动效](motion.md) 的“手感”表里按材质取，不用默认的 ease。
+- 主角先到，其余被带出，间隔 40–80ms，单个区块的出场总长不超过 900ms。
+- 全页每个区块套同一个淡入上移，不算完成这一层。
+
+### 滑动驱动的叙事（必须至少一段）
+
+可以是首屏景深、字标收进导航，也可以是页面中段一段一镜到底，规则见下一节。主角必须在滚动里发生明显变化：缩放、拆解、变形、穿过或形状接力。一个小点沿着线移动、节点逐个点亮，只能算主叙事里的一个细节，不能单独当作主叙事。
+
+### 分镜
+
+动手前在方向卡的“动效”一栏写出滚动分镜：选了哪些手法、为什么，每一段占多少滚动距离、主角是谁、每个镜头画面里有什么、什么在动、往哪个方向、文字什么时候出现。先拆两个同类顶级落地页的滚动节拍作参照，写清它们每一段在动什么，再写自己的。
+
+## 视差与一镜到底
+
+- **一镜到底。** 整段是一次不切换的镜头。一个主角从头走到尾，可以是产品、一根线、一个形状或一个字，每一步长成、变成或让出下一个画面：推近看到细节，拉远看到全貌，转过去看到背面，穿过去进入下一个场景。
+- **主角从产品里找。** 主角是这个产品处理的那样东西，在滚动里走完它自己的过程。找不到只属于这个产品的主角时，退回下面的转场手法，不用通用的漂浮几何。
+- **停下来再说话。** 每个镜头留一段静止，文字在静止时出现；边动边读很累。
+- **视差要有真实的前后。** 只在画面本来就有远近层次时用：前景的物体、中景、远处的背景，越近动得越多，差别要小。正文、按钮和表单不做视差；大标题作为图形层时，按上面的首屏景深处理。
+- **转场也是镜头。** 一个圆从某一点扩开，带出下一节；推进一张图，穿过它到达下一节；背景色在章节之间随阅读慢慢变；一句宣言随滚动逐字亮起。每种手法一页只用一次。
+- **倒着滚也成立。** 每一帧只由滚动位置决定，往回滚自然倒放，刷新或跳到中间也立刻是对的画面。不接管用户的滚动。
+- **留出口。** 长段落前给一个跳过入口；减少动态效果时，把每个静止画面按顺序排成普通区块。
+- **代码做不出来的，交给视频。** 用户想要很强的首屏动画，而效果要靠生成视频或序列帧才做得出来，例如角色转身、产品拆解、镜头穿越场景，按 [素材](media.md) 里“生成视频的可选路径”处理；宿主没有视频生成能力时，交付明确的素材需求。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/dist/templates/common/bundled-skills/atw-ui/references/tools.md

@@ -0,0 +1,46 @@
+# 工具
+
+本目录自带的程序不需要读源码。这里只写什么时候用和最常用的几条命令；全部选项、动作写法和输出文件见各自的 `--help`，写错时报错会给出照抄就能用的写法。
+
+宿主有自己的浏览器工具时，查看页面、走查流程照常用。要交证据时优先用这里的截图工具：它开一个独立的临时浏览器，不碰用户自己浏览器里的数据。本机缺 Node 22，或者没有 Chrome、Chromium、Edge 时，退回宿主工具，交出同样的证据。任务或项目已经指定了截图工具时，照用它。
+
+## 截图和录屏
+
+### 什么时候截，截多少
+
+截图分两种用途，不要混在一起：
+
+- **看一眼**：改完一批，想看效果。只截当前这一屏，一条命令。把一批改动攒在一起改完再截，不是每改一处截一次；页面没有变，就不重复截。
+- **取证**：用 `--evidence` 一次取齐状态图、并排图、遮字图、2 倍图和录屏。只在两个时候做：送评审之前，交付之前。atw-prototype 的方向首屏每个方向只截一张，不取证。
+
+每一轮评审只重新取这一轮改动影响到的证据。没有动过的状态和动效，沿用上一轮的文件，交接时注明哪些是沿用的；拿不准有没有被影响到，例如改了共享样式，就重取那一项。
+
+### 常用命令
+
+```text
+node <skill>/scripts/shoot.mjs <页面地址或 HTML 文件> [选项]
+```
+
+| 要什么 | 加上 |
+| --- | --- |
+| 看一眼桌面效果 | `--size desktop`；不写时是手机 390x844 |
+| 操作几步再截 | `--steps "click .open; wait 300"` |
+| 送评审或交付前取证 | `--evidence --states idle,done --steps "send: click .send"` |
+| 落地页录一段从头滚到底 | `--record --steps "scroll 600; scroll 600; scroll 600"`，按页面长度多写几步 |
+| 截图还原：和参考图比对 | `--compare 参考.png --size <参考的逻辑尺寸>` |
+| 给用户指出问题：在元素上画框、标编号 | `--mark "1=.page-head .btn; 2=.toggle-row" --full` |
+
+在 ATW 任务里，用 `--out` 把输出写到任务目录的 `screenshots/` 下，每个页面和视口一个子目录，例如 `--out <任务目录>/screenshots/settings-desktop`：截图工具的文件名带状态，页面和视口靠目录名写明。
+
+状态靠地址参数进入，所以页面要能用 `?state=<名字>` 直接打开每个状态。其余选项、选择器和动作的写法、输出文件和 `report.json` 的结构：运行 `node <skill>/scripts/shoot.mjs --help`。拿不准写法时先加 `--dry-run` 检查，不会启动浏览器。同时开着很多任务、截图超时的时候，加 `--timeout-scale 2`。
+
+### 看结果
+
+交给评审前先自己看一眼：默认状态是不是已经加载完，遮字版有没有把图形也一起盖掉。证据有错先重截，再交给评审。汇总里提示录屏和截图不一致时，静止的终态以截图为准，再单独重录那一段核对过渡。画面是空的 WebGL 截图不能当证据。
+
+每张截图还会查一组能从页面样式里直接判断的问题，命令输出里以“默认做法提示”列出：
+
+- **要改的可读性问题**：文字对比度不达标、正文小于 13px、多行正文行高过紧、首屏里停在透明状态的内容。
+- **改掉或写出理由**：有色底上的灰字、正文行太长，以及模型默认做法：标题上方的眉标和编号标签、彩色单侧边线、渐变文字、卡片里套卡片、表情符号当图标、中文界面里的英文大写标签、标题离上文比离下文还近。保留的项，在交付说明里写出它怎样服务方向。
+
+检查会误报，例如真实的步骤编号、确实需要的标签；误报在交付说明里写一句。它只认得写法，判断不了好不好看：提示清零之后，仍要自己看截图。检查报出接口 401、404 这类和画面无关的错误时，在交付说明里记一行，不为了让检查通过去改登录、接口这类业务代码。