Communitygithub.com

stick-scene

为落地页和网站创建小型手绘火柴人场景,火柴人操作机器或道具来展示产品功能(拉杆、钉便签、盖章等)。每个场景是一个可交互的 Canvas 微件 `<stick-scene>`,安静待机,在点击、悬停或滚动进入视口时播放一个简短动作。

stick-scene 是什么?

**stick-scene** 是一个为开发者设计的 AI 智能体技能,用于用 Kamran 的墨水黄油风格创建手绘火柴人动画微件。每个场景是一个无依赖的 `<stick-scene>` 自定义元素,内部包含一个 `<canvas>`,火柴人会待机(呼吸、张望、挠下巴)并在触发时播放 5-8 秒的动作,然后恢复待机状态。该技能支持 Claude Code、Cursor 等 AI 编码代理,已在大约 90 个真实场景中得到验证(参见 kamranahmed.info/story)。核心工作流包括:理解产品、构思 2-3 个物理隐喻(如杠杆、图章、传送带)、从模板编写场景、使用联系表检查关键帧、通过运动检测脚本排查关节扭曲或穿模等故障,最后嵌入 HTML。场景元素支持多种触发方式(view、click、hover、loop、idle)及无障碍 label,并遵循严格样式规范:墨水使用 #141414,白色填充,一个黄油色或强调色高亮,Balsamiq Sans 字体 8.5-11px,人物永远不被道具遮挡,每个场景只表达一个核心想法。AI 智能体(机器人)有专用的绘制 API,包含圆形头部、深色面罩、发光眼睛、天线和胸部灯光,并能通过颜色区分不同代理。该技能极大地简化了使用手绘动画展示产品功能的开发过程。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nilbuild/stick-scene/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Stick scene

一个火柴人,采用 Kamran 的墨水黄油风格,完成一项工作来展示产品的功能。场景会待机(呼吸、张望、挠下巴),在触发时播放一个 5-8 秒的动作,然后恢复待机状态。它是一个位于 <stick-scene> 元素内部的 <canvas>,无任何依赖。

此处所有内容均在 kamranahmed.info/story 上的约 90 个场景中得到验证。请从这些模式出发,不要发明新的绘画风格。

文件

  • runtime/stick.js:完整运行时。包含骨架(人物、姿势、缓动、画笔)、道具套件、舞台和 <stick-scene> 元素。将其原样复制到项目的静态文件夹中。
  • templates/scene.js:新场景的起点。
  • templates/preview.html + scripts/frames.mjs:将场景在特定时刻冻结,渲染成一张联系表,并报告错误。
  • scripts/motion.mjs:以 60 fps 步进场景,报告静止帧可能隐藏的问题:关节突变、手臂穿过脸部、道具覆盖头部、肘部反向弯曲或向后突出、挤压变形、脚步滑动、手部落空、动作开始或结束时的跳跃。
  • references/craft.md:API 速查表、姿势库、时间配方、道具配方、隐喻目录以及已经犯过的错误。编写场景前请先阅读。
  • examples/:真实场景。diffity-review.js(评论 → 智能体修复 → 批准,两个人物、一块板子和一张桌子)是最清晰的完整示例。scenes-p3.js 和 scenes-p4.js 包含约 30 个场景;craft.md 中的隐喻目录说明了每个场景的用途。

工作流程

  1. 理解产品。 每项一行:用户做什么,他们得到什么。如果存在,请阅读着陆页或 README。
  2. 提出 2-3 个隐喻 并让用户选择,除非他们让你直接开始。每行一个想法:道具、动作、效果。好的隐喻是物理的(杠杆、图章、传送带、图钉板、帧导轨、板条箱堆),一眼就能看懂而不需要标题,并最终以可见的结果结束(勾号、图章、某物升起或亮起)。参见 craft.md 中的目录。
  3. 从 templates/scene.js 编写场景。 首先在固定的世界坐标中布局道具,然后是待机动作,最后是动作时间线,持续 T 秒。为 label 提供一个简单的句子,供屏幕阅读器使用。
  4. 使用联系表检查。 在宣告完成之前,查看每一张联系表:
    # 一次,在临时目录中:  npm i [email protected]
    NODE_PATH=<scratch>/node_modules node <skill-dir>/scripts/frames.mjs \
      --scene <id> --src path/to/scene.js \
      --frames "idle:0,idle:2.5,s:0.8,s:1.6,s:2.4,s:3.2,s:4.0,s:5.0" --fw 400 --out /tmp/<id>.png
    
    <skill-dir> 是此 SKILL.md 所在的文件夹。然后查看 PNG。idle:<sec> 冻结待机循环,s:<sec> 冻结动作中的某个时刻,u:<0..1> 冻结动作的某个进度分数。添加 @<n> 来渲染第 n 次播放(s:2.4@1),这样随 S.n 变化的场景就能检查所有变体。修复并重新渲染,直到:没有内容被边缘裁剪,没有道具遮挡脸部或正在解释的事物,每个节拍本身都能被理解,文字位于其框内且上下留有余地,手部位于所持物品的前方,所持物品与身体接触的位置符合现实(麦克风在嘴边,手柄在掌心),箭头是手绘的 V 形,而不是实心三角形,最后一帧与待机状态匹配(循环回去时没有跳跃)。通常需要两到三轮。 然后检查联系表无法展示的运动:
    NODE_PATH=<scratch>/node_modules node <skill-dir>/scripts/motion.mjs --scene <id> --src path/to/scene.js
    
    修复每一个 jump(通过混合姿势而不是切换姿势来解决)、arm-through-face、head-covered(道具、备注或气泡覆盖脸部)、bent-back-elbow、elbow-out-back(断翼式手臂保持超过片刻)、squash、start-pop 和 end-pop,直到它输出 "motion is clean"。在行走动作的最开始或结束时出现短暂的 skate 是可以的。
  5. 嵌入它。 将 runtime/stick.js 和场景文件复制到网站的静态文件夹中,并添加:
    <stick-scene scene="<id>" play="view" style="height:230px; max-width:560px"></stick-scene>
    <script src="/scenes/stick.js" defer></script>
    <script src="/scenes/<id>.js" defer></script>
    
    在 Astro 中使用 <script is:inline ... defer>。stick.js 必须在文档顺序中位于每个场景脚本之前(延迟脚本按顺序执行,场景在加载时读取 window.RIG)。在包含多个场景的着陆页上,将每个场景放入一个框架中,使其不会漂浮在裸露的地面线上:一个圆角卡片,带有 1px 边框、白色背景、微弱的点状网格(radial-gradient(#e6e6e6 1px, transparent 1.2px),间距 14px),并保持地板带(不要 no-floor);地面线随后像小舞台一样从一边延伸到另一边。为页面上的每个场景提供相同的框架和完整的内容宽度。然后在无头浏览器中加载真实页面,将元素滚动到视口内,等待约 3 秒,并截取桌面和手机宽度的截图。

元素属性

  • scene:注册为 SCENES['<id>'] 的 id。
  • play:view(半可见时播放一次,然后点击播放;着陆页的最佳默认值)、click、hover(鼠标悬停时循环播放,触摸时点击)、loop(始终运行,谨慎使用)、idle(从不播放)。
  • no-floor:移除地面线下的浅灰色带。在纯白页面上使用。no-ground:也移除地面线。
  • zoom:在框内放大或缩小绘图(默认 1)。
  • label 或 aria-label:场景展示的内容。默认为场景的 label。
  • no-font:不从 Google Fonts 加载 Balsamiq Sans(当网站已经自行托管它或不得调用 Google 时)。
  • 使用 CSS 设置大小。绘图适应高度(230px 是原生尺寸)和场景世界单位中的 width,居中对齐。
  • 减少运动模式显示一静止帧,从不播放。视口外的场景不绘制。
  • STICK.theme({ butter: '#…', greenInk: '#…' }) 可切换整个页面的调色板颜色。当只有一个场景需要不同颜色时,优先在场景中使用本地颜色常量(如 diffity-review.js 中的 GitHub 添加/删除绿色)。

样式规则

  • 墨水色 #141414,白色纸张填充,一个黄油色或强调色高亮,大量留白。对于文字,使用 Balsamiq Sans 8.5-11px,并且只使用少量文字。
  • 人物是主角:永远不要让道具遮挡其头部或活动手部。先绘制道具,然后是人物,然后是手持或飞行的物体。
  • 每个场景只表达一个想法。如果需要标题来解释,说明隐喻选错了。
  • 展示结果,而不是过程:以某种状态已改变并持续一拍的动作结束。
  • 相较于绘制的动物或详细角色,优先使用物理对象。第二个角色(助手)通过 ink/far 获得单一颜色。AI 智能体是一个机器人:fig(..., { ink: '#d97757', far: '#e8b7a3', bot: { col: '#d97757', dark: '#a8553a', glow, blink, happy } }) 绘制一个带有深色面罩和发光眼睛的圆形头部、耳螺栓、天线灯泡和胸部灯光。第二个智能体使用青色(#3d7a8c,深色 #2a5866,远色 #a9c9d1)。黑色智能体也有效:深色 col 会自动获取白色面罩和墨水色眼睛。工作时发出微光 glow,完成时 happy,并在每个角色下方放置一个小标签(you、agent、claude),位置 y = 16。
  • 智能体不应立即做出反应。在请求到达后保持一拍(一个 thinking… 行、一个 hmm… 气泡、一只手托着下巴、缓慢的天线闪烁)再开始工作。
  • 不要使用其他公司的标志。产品名称以纯文本形式放在道具上是可以的。

相关技能