Communitygithub.com

stick-scene

建立小型手繪火柴人場景,用於登陸頁面和網站。火柴人操作一個機器或道具來展示產品功能(拉動槓桿、釘上便條、蓋章)。每個場景都是可互動的 `<stick-scene>` Canvas 元件,平時安靜待機,點擊、滑鼠懸停或滾動到畫面時播放一段簡短動作。

stick-scene 是什麼?

`stick-scene` 技能可讓開發者用 Kamran 的墨水與奶油風格,快速為產品登陸頁面加入輕量、互動式的火柴人動畫。技能自動化管理框架、道具及動態檢查,確保成品品質。支援 Claude Code 與 Cursor 等 AI 代理,亦可用於 Astro 和純靜態網站。使用者只需描述產品功能,AI 代理會提議 2-3 個物理隱喻(如槓桿、輸送帶、圖釘板),然後生成完整的 `<canvas>` 場景,包含待機循環(呼吸、四處張望、搔頭)和 5-8 秒觸發動作。內建 `frames.mjs` 和 `motion.mjs` 腳本可產生連續頁面截圖並自動檢測常見動畫瑕疵(關節跳動、手臂穿過臉部、道具遮擋主體、動作頭尾彈跳等),開發者只需檢查修正後即可嵌入。最終輸出是包含 `runtime/stick.js` 和場景 JS 檔的可部署網頁元件,支援 view、click、hover、loop、idle 五種播放模式,並內建無障礙標籤、減少動畫偏好及全域主題換色功能。

相容平台✓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,白色紙張填充,一個奶油色或強調色亮點,大量留白。任何文字使用 8.5-11px 的 Balsamiq Sans,並且只使用少許文字。
  • 人物是主角:永遠不要讓道具遮擋其頭部或活動中的手。先繪製道具,然後是人物,接著是手持或飛行的物體。
  • 一個場景一個想法。如果需要有說明文字才能解釋,表示隱喻錯了。
  • 展示結果,而不是過程:結束於某個改變狀態並停頓片刻的事物。
  • 優先使用物理物體而非繪製的動物或細節角色。第二個人物(助手)透過 ink/far 獲得單一顏色。AI 代理是機器人:使用 fig(..., { ink: '#d97757', far: '#e8b7a3', bot: { col: '#d97757', dark: '#a8553a', glow, blink, happy } }) 繪製一個圓形頭部、深色遮陽板與發光眼睛、耳螺栓、天線燈泡和胸部燈光。第二個代理使用青色(#3d7a8c,深色 #2a5866,淺色 #a9c9d1)。黑色代理也可行:深色 col 會自動獲得白色遮陽板和墨水色眼睛。工作時亮起 glow,完成時 happy,並在每個人物下方 y = 16 處放置小標籤(you、agent、claude)。
  • 代理不應立即反應。在請求到達後(在開始工作之前)保持一個節拍(一個「思考中…」的線條、一個「嗯…」的對話框、手托下巴、緩慢的天線閃爍)。
  • 不要使用其他公司的標誌。產品名稱作為道具上的純文字是可以的。

相關技能