scrollcraft

scrollcraft

滚动是每位访客都已经知道如何使用的唯一输入方式。这项技能将滚动视为一条时间线：滚轮是擦洗控制器，页面是一部上面叠加着真实文字的影片，每个部分的表现都各不相同，让访客不断向下滚动，想看看下一部分会怎样。

**你将产出：**一份访谈简报、一套页面语法、一张客户旅程地图、一条经过设计并设有一个峰值的情绪曲线、一份滚动节奏表、一个标志性动作、生成的素材、一张采用令牌驱动设计基底的真实 HTML 页面，以及一组证明页面在每个滚动位置都能正常呈现的截图。

本技能不是什么

它不是“生成一段飞越动画，再把文字叠上去”。这种做法会把同一种手法用在整个页面上，而用这种方式构建的网站一眼就能认出来：相同的黏土动画立体场景、相同的居中文字、相同的 01 / 06 计数器、相同的“滚动探索”提示。五个表现完全相同的部分，只不过是同一个部分出现了五次。

因此有以下四条规则，它们也是本技能的核心：

1. **多样性就是产品本身。**一个页面至少要采用四种手法类别，而且不能连续两次使用同一种手法。请阅读 references/devices.md。
2. **除非品牌确实采用插画风格，否则世界应当是摄影风格。**默认禁止使用柔和哑光的低多边形黏土立体场景。请阅读 references/worlds.md。
3. **不要连续串联。**不间断的镜头飞行是最昂贵、也最脆弱的设计，而且它唯一的作用就是隐藏场景之间的剪辑。改用不同的手法，就能轻松消除剪辑痕迹，因为访客并不是在观看同一部影片。只有当简报字面上要求“一段连续旅程”时，才使用串联。
4. **换一个世界，不等于换一张页面。**手法套件改变的是页面的视觉呈现。结构是另一个独立维度，必须经过刻意决策，否则每次构建都会沿用相同的骨架。最初的四次构建正是如此。请阅读 references/uniqueness.md。

步骤 0：访谈

生成任何内容之前，务必先访谈用户。 不是根据品牌名称推断出来的简报，也不是提交给用户审批的计划。要真正提出问题、得到回答并记录下来。基于假设构建的页面，最终看起来总会像上一个基于假设构建的页面。

这项技能是一个风格范围工具，而不是固定的设计风格。用户带来意图和他们拥有的素材；访谈则把这些转化为合适的页面类型：一个连续不间断的世界、彼此独立的场景、印刷风格的章节，或一个鲜活的界面。这项技能都能实现。由访谈决定选择哪一种。

保持简短。一轮问完这八个问题：

1. 用三到五个词描述氛围，再提供最多三个来自任意媒介的参考。可以是电影、专辑封面、商店、杂志或游戏。不要问“喜欢哪些网站”：一旦开始列举网站，页面就容易看起来像现有网站。
2. 用他们自己的话，按章节描述滚动浏览的旅程。 访客首先应该看到什么，接下来是什么，最后是什么。他们来决定顺序，而不是从你提供的菜单里选择。
3. 能量曲线。 哪些地方应该感觉平静，哪些地方应该感觉强烈。整页始终喧闹，就像整页始终安静一样平淡。
4. 滚动浏览时，希望用户在每个阶段有什么感受？他们应该记住的那个时刻是什么？ 能量说的是响亮程度。这里问的是情绪，两者并不总是对应：在喧闹的页面上，安静的段落可能最有冲击力。分阶段的回答会形成情绪曲线，那个时刻则是情绪峰值。在 BRIEF.md 中，两者缺一不可。参见 references/feel.md。
5. 这家网站应该做到的一件事：他们见过的其他网站都做不到。 这是标志性设计的种子。要追问真实具体的答案；“让人印象深刻”不算。
6. 他们希望偏离高端极简风多远。 提供 uniqueness.md §5 中的范围：粗野主义、极繁主义、趣味风、复古、密集、编辑风、高端极简。他们的回答决定美学风格类别，而不是你的个人品味。
7. 一个连续不间断的世界，还是彼此独立的场景？ 整个页面应该像一个连续的场所，让访客一路滚动穿行（worldflight，参见 references/worldflight.md），还是像不同场景、章节或剪辑？这是最重要的结构分岔，应该由他们决定，而不是由你之后自行选择。清楚地提供两种选项；两者都不是默认选项。
8. 他们现有的素材有哪些？ 影像、照片、产品图、品牌工具包、他们自己的短片。真实素材能让整个世界更可信，也能降低生成成本；答案决定哪些内容需要评分和编码，哪些需要生成。“什么都没有”也是完全可以的答案，这意味着整个世界都将由生成方式构建。

在规划任何章节之前，先把回答写入 <workspace>/builds/<name>/BRIEF.md，使用他们自己的原话，不要改写成营销文案。之后的所有工作都以该文件为依据。

BRIEF.md 至少必须包含：

• 八个访谈问题的回答，逐字记录。
• 情绪曲线。 每个章节一行：先写情绪，再写屏幕上是什么引发了这种情绪。在章节尚未确定之前就先写下，并随着配乐逐步成形而补充。
• 峰值。 用访客会对朋友说的话写下那个时刻，并注明它属于哪个章节。
• 完整的“告诉别人”句子。 “这就是那个……的网站”，空白处填写一种体验，而不是某个设计手法的名称。
• 任何有意设计的静默，让验证阶段能够将其与滚动故障区分开来。

references/feel.md 是以上四项内容的规范。

如果确实无法联系到用户，且整个运行过程完全自动执行，请自行编写 BRIEF.md：用品牌的口吻回答全部八个问题，在文件顶部标注 Self-authored, not interviewed，并在最终报告中说明这一点。自行编写简报只是备用方案，绝不是计划。

准备

这是环境准备，不是工作流程中的一个阶段。访谈结束后、步骤 1 开始前完成一次即可。

运行预检，不要手动检查。 它能识别那些否则会在之后表现为误导性错误的问题，最常见的是精简版 ffmpeg 将缺少滤镜报告为命令语法错误：

node <skill>/scripts/doctor.mjs

预检会报告 node、完整构建版 ffmpeg、playwright 和 Chrome、API 密钥，以及解析出的工作区。必需项检查失败时会以非零状态码退出。缺少哪些项目，就明确说明，不要默默绕过。

工作区

构建文件和指纹注册表都位于同一个目录中，而且该目录会被解析，绝不靠假定：

node <skill>/scripts/workspace.mjs --ensure     # prints it, creates it, seeds the registry

解析顺序如下，以首先命中的为准：

1. SCROLLCRAFT_HOME
2. 从当前工作目录向上查找最近的 .scrollcraft.json，内容为 { "workspace": "..." }
3. <project root>/scrollcraft，其中项目根目录是包含 .git 的最近上级目录

因此，构建文件夹的路径为 <workspace>/builds/<name>/，注册表的路径为 <workspace>/FINGERPRINTS.md。注册表初始时为空：设置这个关卡是为了避免重复，所以第一次构建时无需清除任何内容。

如果你已经把构建文件保存在其他位置，只需在项目根目录放置一个 .scrollcraft.json 并将其指向该位置，一切都会保持原样。

其他准备事项

1. KIE_AI_API_KEY，仅在生成素材时需要。使用用户自己的照片和视频片段进行构建，不需要密钥，也不会产生费用；这是一条完整可用的路径，不是备选方案。运行 node <skill>/scripts/kie.mjs probe 确认余额。一张静帧只需几分钱，一个 5s 的视频片段费用更高；包含六个段落、两个视频片段的页面只需少量费用，不会花费很多。
2. 如果有品牌资料包，请准备好（颜色、徽标、字体、现有产品照片）。如果此仓库中有品牌文件夹，生成任何内容之前都要先阅读，并遵守其中的硬性规定。品牌规范禁止虚构数字，就不要添加统计数字，即使它们看起来效果很好。

将 engine/scrollcraft.js 和 engine/scrollcraft.css 复制到构建文件夹。切勿针对单个项目修改引擎；它是实现机制。使用设计令牌为其设置主题，并编写自己的标记。

步骤 1：先确定简报和用户旅程

主题由用户决定。用开放式问题、以朴素的文字询问，绝不要编造行业多选列表：虚构的选项会对用户造成偏向，让人觉得是你在替他们决定业务方向。

步骤 0 已经涵盖风格、顺序、节奏和范围。不要重复询问。只询问那些无法合理默认的内容：

1. 这是什么？面向谁？ 用他们自己的话写一到两句话。
2. 最终你希望访客相信什么？ 用一句话说明页面旨在让访客接受的观点，而不是功能列表。如果他们给出三个观点，让他们选一个。
3. 访客接下来要做什么？ 一个操作。为它确定一个名称，并在整个页面中统一使用。
4. 你们已经有哪些素材？ 徽标、配色、摄影作品、产品照片、视频片段、品牌文档。真实素材始终胜过生成素材。
5. 艺术指导：将 references/worlds.md 中的风格方向作为真实选项提供，并说明他们也可以另选方向。

然后，先写出用户旅程：四到七个节点，每个节点都体现访客认知或感受上的变化。

1  Recognition   they see their own morning
2  Tension       the cost of it, named plainly
3  Turn          the thing that changes
4  Substance     why it holds up
5  Range         what they can choose
6  Commitment    the one action

这些节点是主干。各个版块服务于这些节点；不服务任何节点的版块都应删掉，无论画面多么好看。先向用户展示用户旅程并确认无误，再生成任何素材，因为素材成本较高，而且用户旅程决定了每一项素材。

第 2 步：语法、门槛，然后评分

按顺序做好三件事，而且前两件必须在任何段落规划之前完成。完整详情见 references/uniqueness.md。

选择一种语法。 共有八种，彼此互斥，因为每一种都禁止其他语法所要求的内容。前四次构建都用了电影式一镜到底，因此再次选择它，就意味着要在报告中说明其他七种为何不适合这次访谈。导航、主视觉和收尾都由语法决定；它们不是单独决定的。

设计标志性动作。 设计一种只属于这个网站的定制交互，在页面中编写代码实现，而不是修改工具包装置的参数。访谈问题 5 是它的种子。引擎保持不变。

运行指纹门槛检查。 阅读注册表 <workspace>/FINGERPRINTS.md（请参阅 Bootstrap 中的 工作区；运行 node <skill>/scripts/workspace.mjs 以打印路径）。计划中的构建必须在 6 个维度中至少有 4 个与每一条现有记录不同：语法、导航处理、主视觉装置、段落序列形态、收尾模式、标志性动作。要逐条比较。如果未通过，就修改计划，不要修改日志。

先写情绪曲线，再填评分表。 每个段落写一行：先写情绪，再写引发情绪的原因。先写曲线，再写段落，因为在情绪之前选定装置，就像是装置在寻找使用理由。相邻的两个段落若情绪相同，其中一个就是填充内容；趁素材还没做好，现在删掉它比之后再删更省事。在同一轮中标出情绪峰值，并让它占据页面上最大的篇幅。完整方法见 references/feel.md。

然后为每个节拍分配一种装置。认真选择，并以表格写下来：

节拍	装置	选择原因
识别	scrub	读者亲手移动镜头，是最有力的开场方式
张力	pin + 动态排版	画面保持静止，文案逐行呈现
转折	reveal	擦除效果意味着状态变化，而这正是这个节拍的作用
内涵	scrub（微距）	呈现肉眼无法以其他方式观察到的尺度与纹理
范围	pan	横向移动传达“选项”，纵向移动则传达“论点”
承诺	pin + 指针	页面停止移动，开始响应

这张表是一份电影式评分方案。它适用于一种语法，却不适用于其他七种，因此填入任何一行前，都要先阅读所选语法的适用项和禁用项列表。

构建前的检查：

• 遵守语法的禁用项。若某种语法禁止使用 pin，这里也不能用，即使它原本很合适。
• 至少使用四种不同的装置类别。更少就意味着页面只有一个点子。
• 不要连续两次使用同一种装置类别。
• 最多安排两个 scrub 段落。视频是页面上最重的元素，第三次就不再让人惊喜。
• 不要让相邻段落承载相同的情绪。如果相同，其中一个就是填充内容。
• 设定一个情绪峰值段落，并让它的篇幅明显大于其他段落。它前面的段落要比它更安静。
• 每个段落的滚动篇幅都要物有所值。整页长度为 8 到 14 个视口高度。更长并不会更有沉浸感，只会更慢。
• 段落数量和总长度不能落入此前四次构建都达到的 6 至 7 个段落、每段 13.6 至 13.8vh 这个区间。这个区间现在也是一个指纹维度。

第 3 步：生成素材

完整流程、提示词脚手架和模型说明：references/assets.md。

简要版：

node <skill>/scripts/kie.mjs still "<style preamble>\n\n<scene>" out/01-hero.png --ar 16:9 [--ref brand-can.png]
node <skill>/scripts/kie.mjs shot  "<camera move>" out/01-hero.png out/01.mp4 --dur 5
bash  <skill>/scripts/encode.sh out/01.mp4 assets/01.mp4
bash  <skill>/scripts/encode.sh out/01.mp4 assets/01-m.mp4 mobile

以下三点决定成品看起来是精致高级，还是像机器生成的：

• 所有提示词都使用同一段风格前言，逐字复用。 这是让六张独立图片看起来像同一场拍摄的关键。写好一次后，不要改写。
• 使用素材前，逐一检查。 查看 PNG。生成的成本很低，重新生成的成本更低，远低于交付糟糕的画面。
• 针对拖动进度编码，而非播放。 encode.sh 设置了密集的 GOP，因为定位时会从上一个关键帧开始读取。普通的网页视频编码播放起来很流畅，但拖动进度会卡得像泥潭。

第 4 步：构建页面

编写真正的 HTML。用真正的 <h1>、真正的 <p>、真正的链接，以及真正的阅读顺序。引擎会读取标记中的 data-sc-* 属性并驱动页面；它绝不会生成 DOM。由配置对象构建页面的运行时，正是导致所有基于它构建的网站看起来都一样的原因。

从 references/template.html 开始。设备模式见 references/devices.md；间距、字体、层次和颜色规则见 references/taste.md。在编写标记之前阅读 taste.md，而不是之后，并在不宣告检查清单的情况下完成构建。

通过覆盖设计令牌来设置主题，共六个值和两种字体：

:root {
  --sc-canvas: #0A0806;  --sc-surface: #16110E;
  --sc-ink:    #F5EBDD;  --sc-ink-soft: #A2968A;
  --sc-accent: #FF5A3D;  --sc-accent-ink: #15110F;
  --sc-font-display: "Archivo", system-ui, sans-serif;
  --sc-font-text:    "Geist", system-ui, sans-serif;
}

第 5 步：通过滚动验证页面

这不是可选项，也不能只说“应该能用”。滚动页面没有单一状态：每个位置都是不同的画面，而问题就藏在你恰好查看的两个位置之间。完整流程见 references/verify.md。

cd <build project> && npm i playwright-core     # once
node <skill>/scripts/serve.mjs --root . --port 4500 &
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/shots
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/mobile --width 390 --height 844
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/reduced --reduced-motion

测试工具会在每个章节的六个位置逐一检查，等待拖动进度的视频确实稳定下来，并报告无效滚动、未达到完全不透明度的提示元素，以及在每行文字下方最亮画面中，根据合成后的页面测得的对比度。它还会生成一张联系表。

然后完成测试工具无法做到的部分：查看 sheet.png。 它能证明片段在推进，但无法判断构图是否出色、运动是否流畅，或页面是否有意义。还要按 Tab 键检查焦点顺序。

然后进行体感检查（references/feel.md §6）。在不了解页面内容的情况下滚动浏览，为每个章节写下一个词来描述你的感受，然后再打开 BRIEF.md，将其与预期曲线进行比较。如果两者不一致，错的是页面，不是 brief。在联系表中确认峰值是视觉变化最大的部分，拥有最长的滚动区间，而且最后一屏能收束，而不是渐隐至无。

还要说明绿色测试未覆盖的内容：真实手机。 Headless Chrome 无法复现 iPhone 的视频解码器、自动播放策略、低电量模式或触控滚动；曾有一次构建连续四轮测试全绿，但主视觉片段在真实设备上却卡住不动。移动端从始至终都是首要目标，而不是最后才检查的项目：竖屏手机片段、针对触控调校的 lerp、更大的点击目标都应在创作时完成（见 assets.md 和 verify.md）。报告任何移动端缺陷时，第一轮就将 references/device-diag.html 部署到网站旁边，让设备给出答案，而不要对着无法复现故障的机器空想。完整的 iOS 片段生命周期说明见 verify.md 中的“The phone is a different machine”。

修复发现的问题，然后重新拍摄。说明你实际验证了什么，以及没有验证什么。

硬性规则

这些是发布阻碍项，不是偏好。每一项都会让页面显得像是机器生成的。

绝不	应改为
默认使用黏土微缩景观、低多边形或黏土动画风格的世界	摄影风格。参见 worlds.md
使用“滚动”提示、箭头或动画鼠标图标	什么都不加。他们正在看主视觉，知道该怎么做
使用 01 / 06 作为章节计数器	删除。这里的顺序不传递信息
每个章节标题上方都放眉题	每三个章节最多一个。标题本身就足够
在任何可见位置使用破折号	改用句号、逗号、冒号或括号
每个段落的文案都居中	变换锚点：靠前、靠后、居中、分栏
连续两次使用相同的表现手法	在步骤 2 中妥善规划整体体验
尚未采访用户就生成任何内容	执行步骤 0。编写 BRIEF.md，或注明简报为自行撰写
页面没有精心设计的高潮，或有三个相互竞争的高潮	只设一个高潮。将资源预算、高潮前的留白和最多的滚动空间都留给它。参见 feel.md §2
结尾逐渐消散、淡出，或只是变成页脚	结尾要收束并留驻。最后留下的感受，就是他们会带走的感受
感受曲线尚未确定，就开始规划段落	先定曲线，再选表现手法。参见 feel.md §1
没有一个专属的标志性设计，就发布	设计一个。换个聚光灯颜色或重新调整倾斜角度不算。参见 uniqueness.md §3
与任何已有条目相比，指纹维度中通过不足 6 项中的 4 项就发布	修改计划，而不是修改 FINGERPRINTS.md
为了实现专属效果而修改引擎	在页面中编写专属 JS，通过 --sc-p 和自己的 data-sc-* 驱动
因为上一次构建用了电影式单镜头，就再次采用	从全部八种叙事语法中选择，并说明其他七种为何落选
为修复对比度而使用全屏暗色遮罩	只在文字所在位置使用遮罩
将文字直接嵌入生成的图片	始终使用真实标记语言。这样文字可选择、可翻译且清晰锐利
在计数器中编造统计数据	只用真实数字。没有数字就不要计数器
使用 transition: all，或对宽度、高度、上边距、左边距进行动画处理	使用 transform 和 opacity；擦除效果使用 clip-path
使用渐变文字、霓虹光晕或零偏移彩色光晕阴影	用字重和字号强调；阴影应带有偏移和模糊
自动播放音频，或在任何可擦动片段中加入音频	移除音轨。encode.sh 已经会处理
未执行步骤 5 就发布	执行步骤 5

输出内容

构建文件夹，包括 BRIEF.md，然后附上一份简短报告：采用的叙事语法及其他七种落选的原因、标志性设计、与每个已有条目进行指纹门槛检查的结果、整体体验、感受曲线与高潮、感受检查差异（预期曲线与实际感受曲线，以及做出的调整）、评分表（每个节拍对应的表现手法）、生成的内容、通过截图验证的内容，以及任何无法验证的内容。说明简报是自行撰写还是通过采访完成。提供本地 URL。保持简短；页面才是交付成果。

然后将本次构建的条目追加到 <workspace>/FINGERPRINTS.md。

对技能本身的修改，以及促成这些修改的构建发现，都记录在 CHANGELOG.md 中。