Skip to content
Back to search

motion-web

SkillWorks with Claude CodeGitHub

"Design and build motion-first creative websites — page design (structure, type scale, palette, spacing) plus interaction choreography: scroll animation, Framer Motion, GSAP, and light 3D via Three.js/R3F. Use for animated landing pages, creative portfolios, product showcases, WebGL-lite scenes, and motion audits. Also use when tuning interaction handfeel (手感差/太生硬/不跟手), replicating motion from a video or URL reference (复刻), building 3D depth from flat image assets (伪3D/抠图), diagnosing dead scroll-timeline stretches, mixing scene audio, auditing discoverability (点不开/没人会发现), building headless verification probes, or fixing a page that moves well but looks generated (不好看/像AI做的/没设计感). Equally for building a whole site from nothing (从0到1做个网页/落地页/官网/作品集): stack choice, sections and copy, components (导航/hero/表单/卡片/定价表), and production polish (favicon/OG/404/空状态/暗色模式). Not for dashboards, admin UI, or full 3D scene generation."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/feitangyuan--motion-web/badge.svg)](/listings/feitangyuan--motion-web)

HTML

<a href="/listings/feitangyuan--motion-web"><img src="/api/listings/feitangyuan--motion-web/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As Claude Code Skill

git clone https://github.com/feitangyuan/motion-web.git ~/.claude/skills/motion-web

As Codex / Antigravity Skill

git clone https://github.com/feitangyuan/motion-web.git ~/.agents/skills/motion-web

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 625 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: motion-web
  3. description: "Design and build motion-first creative websites — page design (structure, type scale, palette, spacing) plus interaction choreography: scroll animation, Framer Motion, GSAP, and light 3D via Three.js/R3F. Use for animated landing pages, creative portfolios, product showcases, WebGL-lite scenes, and motion audits. Also use when tuning interaction handfeel (手感差/太生硬/不跟手), replicating motion from a video or URL reference (复刻), building 3D depth from flat image assets (伪3D/抠图), diagnosing dead scroll-timeline stretches, mixing scene audio, auditing discoverability (点不开/没人会发现), building headless verification probes, or fixing a page that moves well but looks generated (不好看/像AI做的/没设计感). Equally for building a whole site from nothing (从0到1做个网页/落地页/官网/作品集): stack choice, sections and copy, components (导航/hero/表单/卡片/定价表), and production polish (favicon/OG/404/空状态/暗色模式). Not for dashboards, admin UI, or full 3D scene generation."
  4. ---
  5. # motion-web
  6. Motion-first creative web. The skill handles all phases: reference → concept → spec → build → audit.
  7. **This skill builds whole web pages.** Motion is what makes them good; it is not the whole job. A
  8. request with no motion in it at all — "做个落地页", "帮我把这个官网做出来" — is still this skill, and the
  9. deliverable is a finished site: stack, tokens, sections, copy, components, states, meta, deploy.
  10. **Priority order — 1 and 2 are co-equal:**
  11. 1. Motion concept and interaction choreography
  12. 2. **Page design** — structure, type scale, palette, spacing rhythm, the thing it looks like before anything moves
  13. 3. **The page as a built artifact** — sections and their copy, the component vocabulary, the token layer,
  14. the states off the happy path (`page-blueprints.md`, `components.md`, `project-setup.md`, `production-polish.md`)
  15. 4. Light 3D or canvas only when it strengthens the page
  16. 5. Performance, accessibility, reduced-motion fallbacks
  17. **A great mechanic on a default-looking page is a failed page.** Motion is the *advantage*, not the
  18. excuse. The most common failure of this skill is shipping one clever interaction glued onto a layout
  19. nobody designed — if the page would embarrass you with the motion switched off, it is not done, and
  20. no amount of spring tuning fixes it. Design is not step 2 in time; it is a second thing that must also
  21. be true at the end. → `references/page-design.md`, `references/design-slop.md`
  22. This *is* a design-and-build skill for one class of site: creative and marketing web — landing pages,
  23. product pages, portfolios, studio sites, campaigns, editorial, light docs. It builds them end to end.
  24. It is **not** a dashboard / admin / data-dense app-UI skill, and not a full 3D-scene generator
  25. (those route to `3d-scene-studio`). A creative page containing app-shaped fragments — a pricing table, a
  26. sign-in, a console screenshot — is in scope; a logged-in product interface is not.
  27. ---
  28. ## Agentic Intent Detection (CRITICAL — Read This First)
  29. **The user will often say very little. Detect their intent from minimal input and act autonomously.**
  30. ### Signal → Intent Map
  31. | What the user sends | Detected intent | What to do |
  32. |---|---|---|
  33. | "做个网页" / "做个落地页/官网/作品集" with a topic, no reference | `full-build` | **The whole site, not a mechanic.** [page-blueprints.md](./references/page-blueprints.md) → [project-setup.md](./references/project-setup.md) → [page-design.md](./references/page-design.md) → build → [components.md](./references/components.md) → [production-polish.md](./references/production-polish.md) |
  34. | "这页要放什么" / "该有哪些 section" / "信息架构" / "文案怎么写" | `blueprint` | [page-blueprints.md](./references/page-blueprints.md) — pick a spine, write real copy, mark every invented fact |
  35. | "导航" / "按钮" / "表单" / "卡片" / "footer" / "FAQ" / "定价表" / "弹窗" / "组件" | `component` | [components.md](./references/components.md) — the dialect table first, then the state matrix. A component without its states is not done |
  36. | "用什么技术栈" / "Astro 还是 Next" / "怎么起项目" / "design token" / "字体" / "部署" | `setup` | [project-setup.md](./references/project-setup.md) — page ladder ≠ motion ladder; start at rung 0 and climb |
  37. | "像 demo 不像成品" / "OG 预览是空的" / "没有 favicon" / "404" / "空状态" / "暗色模式" / "表单没校验" | `polish` | [production-polish.md](./references/production-polish.md) — all of it is checkable; run §9 rather than estimating |
  38. | A bare URL (no other text) | `url-drop` | Open it and deconstruct it (Replicate Mode steps 1–2), then ask: rebuild this, or use it as the reference for something of theirs? |
  39. | A URL + "做个网页" or "参考这个" | `replicate → build` | Deconstruct the URL first (Replicate Mode), then propose a motion concept for the user's own content |
  40. | 参考 + "复刻出来并收录成 case" / "存进 skill" / "做成案例" | `case-authoring` | [cases/AUTHORING.md](./cases/AUTHORING.md) — Phase 0 gate first: strip the images out of the reference; if nothing survives, settle the assets **before** building, not after |
  41. | A URL + "复刻" / "做一个类似的" / "参考这个做" | `replicate` | **Deconstruct → map to patterns → build immediately.** |
  42. | A URL to a paper/article/blog | `doc-drop` | Read it, name the techniques with extractable values, build from one if asked (Document / Article Drop below) |
  43. | A vague brief ("做个很酷的网页" / "做个 portfolio") | `freeform-build` | Orchestrate via [composition-guide.md](./references/composition-guide.md) → choose style+arc independently |
  44. | A topic only ("做一个关于 AI 的落地页") | `spec → build` | Orchestrate via [composition-guide.md](./references/composition-guide.md) → propose visual direction, build immediately |
  45. | A detailed brief with references | `spec → build` | Write MOTION_SPEC.md → get approval → build |
  46. | "审查" / "有什么问题" / "gap" | `audit` | Inspect existing work for motion/perf/accessibility gaps — **including the still frame**, per [design-slop.md](./references/design-slop.md) |
  47. | "不好看" / "太丑" / "像 AI 做的" / "没设计感" / "普通" | `design-audit` | Screenshot with motion **off** and run the gates in [design-slop.md](./references/design-slop.md). Do not tune springs — the complaint is about the still frame |
  48. | "版式" / "排版" / "字太小" / "留白" / "结构" / "section 都长一样" | `design` | [page-design.md](./references/page-design.md) — macrostructure, type scale, spacing rhythm, measured against current award winners |
  49. | "加上…" on existing page | `incremental-build` | Extend current implementation with new motion |
  50. | A **video** reference (Pinterest/Dribbble/X clip) | `video-ref` | **STOP — run the Video Reference Protocol below before writing any code** |
  51. | "手感差" / "太生硬" / "不跟手" / "四平八稳" on existing motion | `handfeel-tune` | Audit against [handfeel.md](./references/handfeel.md) — springs, velocity coupling, secondary motion |
  52. | "跟手但总差一点" / "一抖一抖" / 手感随帧率变 on anything that **follows** (camera, cursor, rail, tooltip) | `handfeel-tune` | Not §1's spring — [handfeel.md](./references/handfeel.md) §7: `1-exp(-k·dt)`, the `speed/k` lead term, and never correcting after the filter |
  53. | "能不能不用 GSAP" / 只是个入场或视差 / 想要更轻 | `build` | Check rung **1.5** first — native `animation-timeline` / `animation-trigger` / `sibling-index()` → [build-mode.md](./references/build-mode.md) ladder + [pattern-recipes.md](./references/pattern-recipes.md) #16. Firefox gets the static end-state |
  54. | 素材是一个**真实存在的地方**(实拍/扫描),要走进去 | `build` | Rung **5.5** — 3D Gaussian splats before models → [build-mode.md](./references/build-mode.md) ladder |
  55. | 卡片/图片要**弯折**、旗帜、翻页、把截图钉进立体面、"skew 不够用" | `warp` | Corner-pin homography → [pattern-recipes.md](./references/pattern-recipes.md) #17. **Guard every quad and clamp edge tilt to `asin(h/w)`** — an unguarded quad paints a screen-sized block with no error |
  56. | "点不开" / "只有一个能点" / "没人会发现" / "看不到" on existing motion | `affordance-audit` | **Do not touch hit-test code first.** Audit against [affordance.md](./references/affordance.md) — the mechanism is usually fine; the invitation is missing or expired |
  57. | A pile of **image assets** + "做成一个 3D 场景" / "要有纵深" / "camera 要能走进去" | `image-plane-3d` | **Do not reach for models.** Build the scene from flat planes in a real perspective camera → [image-plane-3d.md](./references/image-plane-3d.md) (ladder rung 5) |
  58. | "有拼接感" / "没融进去" / "像贴上去的" on a rendered scene | `image-plane-3d` | Measure before touching art: mean `R−B` and luminance per asset batch, contact shadows present → [image-plane-3d.md](./references/image-plane-3d.md) §6–7 |
  59. | "这个该用什么画" / "DOM 还是 canvas" / 页面只会输出 div 和系统字体 / 参考明显不是 DOM 能做的 | `render-layer` | **先定层再定机制** → [render-layer.md](./references/render-layer.md) §1。层是一个声明,写进 case README,由 `verify_case.py --layer` 核对 |
  60. | 手绘 / 墨线 / 描边风的 3D,"像画出来的不像渲出来的",boil / 抖线 / 纸纹 | `ink-render` | [render-layer.md](./references/render-layer.md) §3 — 深度不连续描边(法线折痕关掉)、静态 warp 与动态 boil 分离、boil 时钟 11Hz 对 60fps 渲染 |
  61. | Raw plates / renders that still need cutting out, "抠图", "素材怎么进场景", "图糊了" | `asset-pipeline` | Key against the image's **own** background, crop to the alpha bbox, script the metadata, print the per-element resolution budget → [image-asset-pipeline.md](./references/image-asset-pipeline.md) |
  62. | Any headless check; a number disagrees with what you see; "怎么验" | `verify` | Build the probe surface first — pinnable clocks, `__seek`, `__hold`, state exits — then measure → [verification-harness.md](./references/verification-harness.md) |
  63. | "这一段什么都没发生" / "节奏不好" / "一堆字一下就出来了" on a scroll timeline | `timeline-audit` | Lay every track against one scroll axis; dead beats are coinciding plateaus, not one slow layer → [timeline-orchestration.md](./references/timeline-orchestration.md) |
  64. | Long scroll scene with many assets; "卡", "加载慢", "内存爆了", hundreds of plates | `scene-streaming` | Activate by screen window, slice big uploads, yield inside the scan, dispose completely → [scene-streaming.md](./references/scene-streaming.md) |
  65. | Anything with sound — BGM, ambience, interaction SFX, "音效太少", "氛围音听不清但也别吵" | `scene-audio` | Three buses (bgm / hand / world), per-act curves, discrete events over a louder bed → [scene-audio.md](./references/scene-audio.md) |
  66. **Never ask the user what mode to use.** Detect it. Proceed. Only stop if the brief is truly ambiguous between two very different outputs (e.g., spec vs. immediately building).
  67. ---
  68. ## Video Reference Protocol (硬规则 — 不许猜)
  69. **Trigger: the reference is a video you cannot actually watch** — Pinterest pin, Dribbble shot, X clip, 站外短链. A title or text description is NOT motion information.
  70. 0. **Read the thread before you conclude there is no live page.** The author almost always posts the
  71. URL in a reply, and the replies also tell you whether the piece is even a web page. Measured
  72. 2026-09-02: a previous session declared seven video references URL-less and spent its Phase 1 on
  73. frame measurement; **all seven had live sites, posted by the authors themselves**, and three of
  74. four clips in one post turned out to be Jitter / Figma Motion / Rive renders with no web
  75. implementation at all (`cases/AUTHORING.md` Phase 1). `safe-x tweet <url> --json`, then resolve
  76. every `t.co` link in the replies.
  77. 1. **Never build motion from a guess.** If all you extracted is a title/description, you know the *topic*, not the *motion*. Building anyway burns a full iteration — this is a documented failure mode (2026-07-06, seafood hero: guessed "orbit", actual was a rising diagonal; two rebuilds).
  78. 2. **Ask for 2–3 keyframes immediately.** One sentence: "这个视频我打不开,截 2-3 帧关键画面(入场/中间/离场)发我"。
  79. 3. **State the trajectory as explicit geometry before coding**, and get confirmation:
  80. - Anchor points: where the element enters / crests / exits (corners, thirds)
  81. - Attitude: rotation follows path tangent / stays constant / lags behind
  82. - Secondary reactions: what else moves (background shapes, lines, text) and how
  83. - Example: "右下入场 → 中心 → 左上离场的上升对角线,鱼头恒定朝左上" — wrong guesses die here, not in code
  84. 4. Only then map to pattern-recipes / handfeel.md and build.
  85. A single screenshot follows the same rule: one frame gives pose, not trajectory. If the *path* matters, ask for more frames.
  86. ---
  87. ## Replicate Mode (复刻模式)
  88. When the user sends a URL with "复刻" / "做一个类似的" / "能不能做这种效果" — deconstruct it, then build. There is no storage step; the deliverable is the page.
  89. ### Replicate Execution Path
  90. 1. **Open the page and read it as three layers**, with whatever browser tooling is available (Claude
  91. Preview, `browser-use`, Playwright): the **stack** (library, easing, keyframes, CSS variables — the
  92. bundle names them), the **scroll choreography** (which element is pinned over which band, rails and
  93. their px distance, parallax rates, scrubbed properties, entrance points — sample ~9 scroll positions
  94. and diff `getBoundingClientRect` plus computed styles between them), and the **WebGL layer** (program
  95. count, draw calls, custom uniform names; wrap `getContext` before page scripts run if you need the
  96. shader sources). Two scripts cover the measurable halves: `scripts/measure_structure.py <url>` for
  97. the static page (sections, nav, buttons, token scales, media, meta, mobile overflow) and
  98. `scripts/measure_churn.py <url>` for how much of the page actually moves under a real wheel.
  99. **The URL must be the work itself**, never a gallery listing (`awwwards.com/sites/<slug>`): a
  100. listing page hands you the gallery's own chrome, and six different winners come back with the same
  101. library, the same keyframes and the same font.
  102. 2. **Deconstruct** — state what you found, and quote the numbers rather than impressions:
  103. - "GSAP 3.12 + ScrollTrigger + Lenis;`.home-animate__wrapper` 在 0.25–0.50 被 pin 住,
  104. 期间 `.icon` 横移 +1545px,出场是 0.25/0.38/0.62 三段 stagger"
  105. - "背景是原生 WebGL2,14 个 program、944 draw calls,uniform 里有 bloomStrength/blurTexture1-5
  106. 和 cloudCoverage/cloudDensity —— 是 UnrealBloom + 体积云"
  107. **Never report "用了 WebGL" off a context alone** — an unsized 300×150 context with no linked
  108. program is Modernizr-style capability detection, not a scene. Count linked programs and draw calls.
  109. 3. **Map to pattern-recipes** — find the closest recipe in `references/pattern-recipes.md`
  110. 4. **Fill the gap** — what the reference uses that we don't have in recipes, write from scratch based on extracted values
  111. 5. **Build immediately** — scaffold the page, run it, verify visually
  112. 6. **Report** — "复刻了 [site] 的核心动效,用了 [X] 实现 [Y],和原版差异是 [Z]"
  113. ### Replicate ≠ Copy
  114. - **Do**: Recreate the interaction pattern, motion character, timing feel
  115. - **Don't**: Copy proprietary brand colors, exact copy text, identifiable product UI
  116. - **Do**: Adapt the technique to the user's own content and palette
  117. - Note in the report what was adapted vs. what was faithful to the original
  118. ---
  119. ## Freeform Build Mode (When User Gives Zero Direction)
  120. When the user says "做个网页" / "随便做" / "自己想一个主题" or gives a simple vague topic (e.g. "做一个AI agent平台落地页"), this is an invitation to be creative.
  121. **Do NOT default to a generic template, do NOT use rigid 1-to-1 routing mapping, and do NOT ask clarification questions.**
  122. ### Freeform Action Path (Runtime Creative Loop — 创造发生在执行中,不在文档里)
  123. The user should NEVER need to supply a reference. But novelty also does NOT come
  124. from reading these docs — docs are constraints and physics, not answers.
  125. Novelty comes from **fresh inputs sampled at runtime + a build-test-kill loop
  126. where you are your own critic**. Execute:
  127. 1. **Sample the present** (runtime input, not memory): open this month's
  128. Awwwards SOTD / Godly / SiteInspire listings and look at 3–5 of the winning
  129. pages themselves — the work, never the gallery page. You're not copying;
  130. you're locating the current frontier so you can land past it. 2 minutes.
  131. Look at **structure and type scale**, not only the effect — that is the half
  132. that decides whether the page reads as current (`page-design.md` §1).
  133. 2. **Invent 3 candidate mechanics** from the topic's own physics via the
  134. generative operators (composition-guide §5). Kill any candidate that
  135. resembles the graveyard OR anything you just saw in step 1.
  136. 3. **Sketch before committing**: build the signature interaction as a minimal
  137. single-file prototype (one div, one rAF loop, fake content, <15 min).
  138. Not the page — just the mechanic.
  139. 4. **Test it on yourself**: run it and drive it with the currently available
  140. browser tooling — Claude Preview (`preview_start` → `preview_eval`/`preview_click` →
  141. `preview_screenshot`) first, `browser-use` as fallback — mouse sweeps, wheel
  142. flicks, screenshots at extremes, then look at the evidence. Ask:
  143. 会不会玩 10 秒就腻? 截两帧给人看,能不能猜出交互规则? If it fails — mutate the
  144. operator or pick the next candidate. Do not ask the user to be your eyes.
  145. 5. **Design the page — as a separate act, before the mechanic goes into it.**
  146. Not "pick a palette and start coding". Three outputs, in order:
  147. (a) the **blueprint and the real copy** → `references/page-blueprints.md` — which
  148. sections exist and what they actually say; (b) the **macrostructure, type scale
  149. and spacing rhythm** → `references/page-design.md`, with concrete values in
  150. `data/visual-bank.json`; (c) the **token layer and scales** →
  151. `references/project-setup.md` §2–§5. The mechanic then gets placed *into* a page
  152. that already works, which is the opposite order from the one that produces
  153. 「一个破动效贴在没设计的页面上」.
  154. 6. **Build it**, components and their state matrices from `references/components.md`,
  155. springs from `references/motion-tokens.md`, full-page linkage per handfeel.md.
  156. 7. **Design gate — run this before you show anything.** Screenshot the page with
  157. **all motion disabled** (`prefers-reduced-motion`, or comment out the mechanic)
  158. and judge that still frame on its own:
  159. - Would this still frame place on Awwwards with zero animation? If the honest
  160. answer is "no, it's a centred headline and three cards", the design is not done.
  161. - Run the slop gates in `references/design-slop.md`. Any hit = revise, not ship.
  162. - Only then ask the motion questions: 会不会玩 10 秒就腻? 截两帧能不能猜出交互规则?
  163. A page that passes step 4 and fails this one is the documented failure mode this
  164. loop exists to prevent — step 4 only ever tested the mechanic.
  165. 8. **Finish it**: `references/production-polish.md` — head, OG, favicon, 404, the
  166. states off the happy path, and the ten manual checks in §9. A page that stops
  167. before this is a demo, not a deliverable.
  168. 9. **Bury the mechanic**: append one line to the graveyard (composition-guide)
  169. so it can never be reused — the loop stays forced-fresh.
  170. Pitch to the user only if two surviving candidates are genuinely different
  171. directions; otherwise just build the best one and explain the metaphor after.
  172. ---
  173. ## Document / Article Drop
  174. If the user drops a paper, article or design blog: read it, name the 2–3 techniques in it that carry
  175. extractable values (library, easing, timing, a shader idea, a layout rule), and ask one question —
  176. build from one of them now, or keep going with the brief? If they say build, the most distinctive
  177. pattern becomes the page's primary motion concept and goes through the same Build Order as everything
  178. else. Nothing is stored; a technique that mattered goes into `pattern-recipes.md` after it has shipped.
  179. ---
  180. ## Modes (for explicit user direction)
  181. - `spec`: turn a brief + references into a buildable `MOTION_SPEC.md`
  182. - `build`: implement an approved motion-first web experience
  183. - `audit`: inspect an existing motion-heavy page or implementation for gaps
  184. - `design-audit`: the complaint is about how it *looks*, not how it moves — judge the still frame first
  185. - `replicate`: deconstruct a reference page in numbers, then rebuild the pattern on the user's content
  186. - `freeform-build`: user gives no direction → make creative choices independently
  187. - `full-build`: build a whole site 0→1 — blueprint + copy, stack + tokens, design, components, motion, polish
  188. - `blueprint`: decide what sections a page needs and write their copy
  189. - `component`: design/build a specific component with its full state matrix
  190. - `setup`: pick the page stack, scaffold the project, lay the token/type/font layer
  191. - `polish`: the finishing pass — meta, OG, 404, off-happy-path states, dark mode, pre-ship checks
  192. ---
  193. ## Build Order (Always Follow This)
  194. 0. **Pick the page stack** → `references/project-setup.md` §1 — one HTML file / Vite / Astro / Next. This is a
  195. *different ladder* from the motion one; do not let either pick the other. Start at rung 0.
  196. 0.5 Pick the motion stack rung → `references/build-mode.md` **Tech Stack Decision Ladder** — lowest rung that reaches the goal; never default to R3F because the reference "looks 3D", and never default to *models* because the scene needs depth (rung 5 builds the whole scene out of images)
  197. 1. **Pick the blueprint and write the copy** → `references/page-blueprints.md` — which sections exist, in
  198. what order, and the real words in them. Layout is a response to real text; placeholder copy means the
  199. page has not been designed. Then pick arc type → `references/choreography-arc.md`
  200. 2. **Design the page** → `references/page-design.md` — macrostructure, type scale, palette, spacing
  201. rhythm. Concrete values in `data/visual-bank.json`. This is a real step with its own output, not a
  202. line item: decide what the page looks like **with the motion switched off**, and be willing to
  203. defend that still frame on its own
  204. 2.5 **Lay the token layer and the scales** → `references/project-setup.md` §2–§5 — three-level tokens,
  205. fluid type scale with a real jump, space scale, fonts with metric overrides, `@layer` order. Doing this
  206. after components exist means editing every component.
  207. 3. Pick motion tokens → `references/motion-tokens.md` (duration, easing, spring)
  208. 3.5 **Build the component vocabulary** → `references/components.md` — pick the dialect (creative vs product,
  209. the two are measurably different systems), then give every interactive component its full state matrix.
  210. A missing `:focus-visible`, error or empty state is the most common "像 demo" cause.
  211. 4. Check pattern library → `references/pattern-recipes.md` for reusable implementations
  212. 5. **If the scene is built from image assets, run the asset pipeline before the runtime** → `references/image-asset-pipeline.md`. Cutouts, scripted metadata, per-element resolution budget. No amount of shader work fixes an asset that was keyed against the wrong background or is being enlarged 0.83×. Decide the **topology** at the same time (camera moves vs world moves → `image-plane-3d.md` §12) and, if it is long, the **streaming policy** → `references/scene-streaming.md`
  213. 6. Implement per → `references/build-mode.md`, **building the probe surface as you go** → `references/verification-harness.md` §1 (retrofitting `__seek` / `__hold` / pinnable clocks costs more than building them)
  214. 7. For a multi-track scroll timeline, lay the tracks out horizontally → `references/timeline-orchestration.md`; if the page has sound → `references/scene-audio.md`
  215. 8. For anything interactive that isn't an obvious button: mark the invitation per → `references/affordance.md`
  216. 9. **Run the design gate before the motion gate** → `references/design-slop.md`. Screenshot with all
  217. motion disabled and judge that frame first; a page that only works while moving has not been designed
  218. 10. **Finish it** → `references/production-polish.md` — head/OG/favicon, 404, the states off the happy path,
  219. dark-mode decision, and the ten manual checks in §9. Skipping this is what makes a good page read as a demo
  220. 11. Verify desktop + mobile + reduced-motion + **the affordance checklist and its numeric oracles**
  221. **Mandatory pre-flight — not optional, not a suggestion:** before writing a single line of GSAP, Framer Motion, or Three.js/R3F code, open the matching framework section in `references/build-mode.md` (Framework-Specific Rules) and the `Failure Patterns to Avoid` table. Do this even if you're confident you remember the pattern — the table exists specifically because remembered patterns silently regress (e.g. GSAP `.from()` without `gsap.context()`/`.revert()` under React StrictMode). Skipping this step and reinventing a fix that's already documented there is a process failure, not a stylistic choice.
  222. ---
  223. ## Load Only What You Need
  224. | Mode | Read these references |
  225. |---|---|
  226. | `spec` | motion-spec.md + baseline-ui.md + choreography-arc.md |
  227. | **every build, without exception** | **page-design.md + design-slop.md** — the still frame is half the deliverable |
  228. | a brief in a case's class, or you need its mechanism | the case's `README.md` first (it has the 可以照搬/不许照搬 split), then its `index.html` |
  229. | **every 0→1 site build** | **page-blueprints.md + project-setup.md + components.md + production-polish.md** — sections & copy, stack & tokens, component states, the finish |
  230. | `full-build` / "做个网页" with no reference | page-blueprints.md + project-setup.md + page-design.md + design-slop.md + composition-guide.md + components.md + production-polish.md |
  231. | `blueprint` / "该有哪些 section" / 信息架构 / 文案 | page-blueprints.md + page-design.md §1 |
  232. | `component` / 导航 / 表单 / 卡片 / footer / 弹窗 | components.md + baseline-ui.md + (affordance.md if it isn't an obvious button) |
  233. | `setup` / 技术栈 / token / 字体 / 部署 | project-setup.md (+ build-mode.md ladder for the *motion* stack) |
  234. | `polish` / 像 demo / OG / favicon / 404 / 空状态 / 暗色模式 | production-polish.md + baseline-ui.md |
  235. | `build` | build-mode.md + motion-tokens.md + pattern-recipes.md + (light-3d.md if canvas/WebGL) |
  236. | `image-plane-3d` / scene built from image assets / "有拼接感" | image-asset-pipeline.md + image-plane-3d.md + light-3d.md + verification-harness.md + (scene-streaming.md if it's long; affordance.md if anything in the scene is clickable) |
  237. | `scene-streaming` / 长滚动大场景 / 卡 / 加载慢 | scene-streaming.md + image-asset-pipeline.md §6, §9 |
  238. | `asset-pipeline` / 抠图 / 素材元数据 / 图糊了 | image-asset-pipeline.md (+ image-plane-3d.md §2 for how the runtime consumes it) |
  239. | `verify` / building any oracle / a metric disagrees with the eye | verification-harness.md + affordance.md §9 |
  240. | `timeline-audit` / scroll-driven多拍编排 / "这一段什么都没发生" | timeline-orchestration.md + choreography-arc.md |
  241. | `scene-audio` / BGM / 环境音 / 交互音效 | scene-audio.md + verification-harness.md §3 |
  242. | `freeform-build` | page-design.md + design-slop.md + composition-guide.md + choreography-arc.md + visual-bank.json + motion-tokens.md + pattern-recipes.md |
  243. | `audit` | build-mode.md + motion-tokens.md |
  244. | `handfeel-tune` / "不跟手" complaints | handfeel.md + motion-tokens.md |
  245. | `affordance-audit` / "点不开" / "发现不了" complaints | affordance.md + handfeel.md |
  246. | `video-ref` | (protocol above) then handfeel.md + pattern-recipes.md |
  247. | `replicate` / `url-drop` | pattern-recipes.md + handfeel.md + page-design.md + design-slop.md |
  248. | portfolio/personal site | page-blueprints.md (the portfolio blueprint) + components.md |
  249. ---
  250. ## Core Rules
  251. - Motion is the main design material, not the final polish layer.
  252. - **Anything that follows something else is not a spring problem.** Cameras, cursors, rails and tooltips
  253. must arrive and stop. Steady-state lag behind a moving target is `speed / k` — arithmetic, not a tuning
  254. failure — and a correction written after the filter gets undone next frame (`handfeel.md` §7).
  255. - **「飘」 is a stillness ratio, not an easing curve.** Easing changes how fast the source is read; it never
  256. changes how often a new state appears. Measure the fraction of near-identical adjacent frames before
  257. touching a curve (`timeline-orchestration.md` §11).
  258. - **Climb the ladder from rung 1.5, not rung 4.** A reveal, a parallax band, a stagger and a scroll-spy nav
  259. are now native CSS; author the finished state first and put the timeline behind `@supports`, because
  260. Firefox implements none of it (`build-mode.md` ladder, `pattern-recipes.md` #16).
  261. - **Buildable ≠ findable.** An interaction is not done when it works; it is done when a first-time visitor
  262. discovers it without being told. Every interactive element that isn't an obvious button owes an answer to
  263. the three questions in `references/affordance.md` §1.
  264. - **The test has to encode the user's complaint, not your model of it.** If the user says "I can't open it"
  265. and your check says "it opens", you are measuring a different thing — go find their question first.
  266. - **Decide what number would prove it, then print that number.** Screenshots are expensive and settle
  267. nothing. Coverage sweep, handoff size error, safe-area containment, window-vs-dwell — all one headless
  268. run (`references/affordance.md` §9).
  269. - **A general quality score is worse than no test.** Every oracle must encode one stated complaint; the
  270. aesthetic verdict stays with a human looking at the thing (`verification-harness.md` §0).
  271. - **Assets before runtime.** In an image-built scene the metadata is a build artifact, never a hand-edit —
  272. if you are nudging a `baseline` to make something sit right, the bug is upstream (`image-asset-pipeline.md`).
  273. - **A dead beat is several layers' flat sections landing together**, not one slow layer. Read a scroll
  274. schedule horizontally (`timeline-orchestration.md` §1).
  275. - **The deliverable is a page, not a mechanic.** A brief with no motion in it is still this skill, and the
  276. job is a finished site — sections with real copy, a component vocabulary with its states, a token layer,
  277. meta and a 404. Handing back one beautiful interaction and a template around it is the failure this
  278. skill's whole design half exists to prevent.
  279. - **The two component dialects are measurably different systems.** Creative pages: median **1** distinct
  280. radius, **0** shadowed elements, 37 % uppercase buttons, no nav CTA, a 2-column footer. Product pages:
  281. median **8** radii, ~18 shadowed elements, 1 % uppercase, 2 nav CTAs, a 5-column 35-link footer
  282. (n=32, `components.md` §1). Pick one and be consistent — building a creative page out of product
  283. components *is* the "像 AI 做的" complaint.
  284. - **A component without its states is not built.** hover / `:focus-visible` / active / disabled / loading /
  285. error / empty / success. The missing state is almost always the one the user notices
  286. (`components.md` §2).
  287. - **Copy before layout.** Layout is a response to real text length; a page laid out around placeholder
  288. copy has to be redone. If the user supplied no facts, write the draft and mark every invented slot
  289. `[…]` — never invent proof (`page-blueprints.md` §4, `design-slop.md` A8).
  290. - **Award-winning is not well-built.** In the same 32-site run, 2 of 18 award sites had horizontal
  291. overflow at 390px, 5 had no `<h1>`, and only 37 % of their images reserved a box. Copy their design
  292. language; do not copy their hygiene (`production-polish.md`).
  293. - **A projective transform has a legality condition, and violating it fails silently.** Corner-pin
  294. (`matrix3d`) only behaves while the destination quad stays convex — past that the homography flips
  295. through infinity and paints a screen-sized block with no console error. Guard the quad *and* clamp
  296. edge tilt to `asin(h/w)`; the guard alone is a visible snap (`pattern-recipes.md` #17).
  297. - **From `cases/`: take the mechanism, never the skin.** The source ships in full because re-deriving a
  298. solver is waste — but palette, type values, grid, section order and copy belong to that case. A page
  299. that is a case with the logo swapped is the failure mode, not the shortcut.
  300. - **A probe that bypasses the event handlers tests a path nobody takes.** One case passed
  301. every probe-driven check — landing error 0.0000°, all slots reachable, both ends clamped — while
  302. being completely dead to a real scroll wheel. Every oracle must drive at least one **real** gesture,
  303. and `verify_case.py` now does this on every page.
  304. - **Placeholder geometry passes every oracle and still looks like nothing.** Grey gradient rectangles
  305. standing in for photographs clear the type-ratio, dead-beat and state-matrix checks and still read
  306. as a technique diagram. No metric detects it and none should be invented — decide whether the
  307. artwork exists **before** the build, not after (`cases/AUTHORING.md` Phase 0).
  308. - **An oracle that pins its input and settles has not tested the page anyone uses.** Every assertion
  309. in `--strings` originally ran against a frozen clock; unpinned, a drifting endpoint or a body that
  310. never stops sloshing is invisible to all of them. Whatever your mechanic is driven by, add a pass
  311. that lets it run free. (And when a live readout looks alarming, check the loop is running first —
  312. a hidden browser tab suspends `requestAnimationFrame`, and a frozen sim reports plausible,
  313. completely wrong numbers: `cases/string-clock` 踩过的坑 #7.)
  314. - **An inline style declaration outranks every rule in the stylesheet, including `:hover`.** A stack order written as `el.style.zIndex` silently kills `.thing:hover{z-index:…}` — the hover still *looks* live because its colour change comes from the same rule that did win, so the promotion is dead and nothing reports it. Ship per-element state as a custom property
  315. (`el.style.setProperty('--z', n)`) and let the rules read it.
  316. - **Never build from a summary of a reference you could open yourself.** A previous session compressed a video into one sentence for a hand-off; building from that sentence produced a resizable window the reference does not have, an eased entrance it does not have, and a scrolling marquee that measures 0 px of movement per frame. The clip was on disk the whole time. A contact sheet gives pose; only the frames give **trajectory, cadence and stillness**
  317. .
  318. - **An oracle threshold comes from a measurement or from a design requirement you can state — never from taste.** A "no clumping" band of nearest-neighbour CV [0.08, 0.40] looked principled and the reference itself scored 0.507: it places at random and lets cards overlap hard. The real contract was elsewhere — **z-order is arrival order, so the newest card is never buried** — and that one is worth asserting.
  319. - **Decide what the page is *drawn with* before you decide what it does.** Seven cases shipped as DOM + CSS on the system font stack while every reference was something else; nothing in the skill ever asked the question, so every brief resolved to divs by default. The layer is a declaration in the case README, and `verify_case.py --layer` checks it (`references/render-layer.md` §1, `cases/ink-crowd`).
  320. - **Some numbers only exist in the source.** The 11 Hz boil clock that decides whether a frame reads as drawn is invisible to frame-differencing: sub-pixel displacement under camera motion, 95 % of frames differ, autocorrelation flat. Measuring pixels would have produced a confident wrong answer. Fetch the bundle and read it (`cases/ink-crowd` §1).
  321. - **"Take the feel, not the layout" means taking the motion first.** A build that lifted a reference's palette and grain and shipped a static page passed every gate in the floor: the page looked right and did nothing. Characterise the reference's motion in numbers before touching the design — per-layer velocity and how much of the time anything is moving — and assert liveness with no input.
  322. - **Whole-frame correlation cannot measure a multi-layer scene.** Layers moving at different rates, some in opposition, cancel to a median shift of zero. Track one colour or feature mask per layer instead.
  323. - **Check a tiled texture's period against every repeating dimension near it.** A 128 px noise tile over an 11-band strip on a 1440 px canvas (130.9 px per band) beats into vertical streaks — the one artefact film grain never has. Writing noise into the pixels avoids the whole class.
  324. - **A pointer that aims into a 3D scene must intersect the plane the *content* sits on, not the ground.** Figures are 1.75 units tall; a ray aimed at a body and intersected with `y = 0` lands far behind it, and near the horizon it runs away entirely. The symptom is not "slightly off" — it is a mechanic that works in one screen band and is completely deaf everywhere else, while its own counter still reports activity (`cases/ink-crowd` §4, `verify_case.py --follow`).
  325. - **Two answers to "pin a screen", and they exclude each other.** Hijack the wheel and translate a rail: you can compute any progress you like, and `position:sticky` will never fire because the ancestor is transformed, so every pinned child must be parked by hand. Leave scroll alone and stack `sticky; top:0; height:100vh` screens: pinning is free, and progress has to be read back out of the document as `(scrollY - offsetTop) / innerHeight`. Pick before laying anything out; retrofitting either onto the other is a rewrite (`cases/wheel-rail` §2, `cases/press-stack` §2).
  326. - **A sticky stack of one-viewport screens has no dwell at all.** Each screen is fully visible at exactly one scroll position, so every animation inside it plays in the half already being covered, and scrolling reads as dead. `margin-bottom: 100vh` on each screen buys a viewport of dwell without changing its box. Then progress splits: content uses `(scrollY - top) / vh` while the screen is whole, and only exit effects use `(scrollY - top - vh) / vh` (`cases/press-stack` §2).
  327. - **Read the layout in the oracle; never assume it.** `--stack` hardcoded "one screen per viewport" and reported 1 of 8 pinned the moment the layout gained a dwell — a green-to-red flip caused entirely by the check, not the page. Section positions come from the probe (`cases/press-stack` §3).
  328. - **A sticky stack eats the bottom of the screen first.** The next screen rides up from below, so anything anchored with `margin-top:auto` is the first thing covered. A headline, a giant numeral and a section rule all disappeared on the first build for this one reason. Content belongs in the upper two thirds (`cases/press-stack` §2).
  329. - **Album covers are drawable; people are not.** Sleeves are a colour field, two shapes and a line of type; a record is concentric grooves plus two narrow specular arcs — a wide wash across the disc reads as a gold plate. Both are better generated than faked with a grey rectangle. A portrait or a hand is neither: leave the slot out and redesign around it rather than stacking primitives into a figure (`cases/press-stack` §4).
  330. - **Density is a device, and the underlay is where it comes from.** A page can carry every motion mechanism the reference has and still read thin: 184 elements against the reference's 584. The gap was not more copy — it was the technical-drawing underlay the reference puts beneath everything: a hairline grid, act rules, range markers. Twenty elements, each of which draws itself and tracks the pointer, and the same screens stop looking like a wireframe of the reference (`cases/wheel-rail` §3).
  331. - **A reference clip on disk outranks the live site.** Built from headless screenshots of `blink.trade`, this case reproduced the palette, the type and the scroll device and still got "the fuzzy round thing never changes". The clip showed the signature element is a radar sweep — a hand turning over a dotted ring, trailing a soft wedge that closes and clears in 0.92 s. A still frame cannot represent the one thing that made the page. **If a clip exists, watch it before building, even when the live site is reachable** (`cases/wheel-rail` §2b — and this is the second time it cost a rebuild).
  332. - **Input-driven and ambient are not alternatives.** The correction "interaction motion means motion the mouse produces" is about what is *missing*, never a licence to strip the ambient layer. The reference runs both: wheel and pointer drive the layout and every reveal, and the sweep turns regardless. Assert both — churn under real input, and liveness with no input at all (`verify_case.py --rail`).
  333. - **A rail that translates is not choreography.** A hijacked wheel moving a rail while every child element holds still is a scrollbar in costume — and it passed four `--rail` assertions before anyone looked at it. Measure how many elements actually change under real wheel input: the reference moves 64 %, the rejected build moved 13 %. Assert the churn, and assert that some elements are caught *mid*-transition, or a page that snaps between states satisfies the count and still reads as a slideshow (`cases/wheel-rail` §3).
  334. - **Split the text or the page has nothing to animate.** The reference wraps every word in an inline-block span — 296 of them — at `translateY(8px)` / `opacity 0` with `transition-duration: 0s`, i.e. written per frame rather than handed to CSS. That single decision is most of the 64 %. Writing the values yourself is also what makes the reveal scrub backwards when the wheel reverses (`cases/wheel-rail` §2).
  335. - **A scroll-mapped reveal on something already on screen resolves to "finished" on frame 1.** The hero diagram's draw-on never once played, because its section's `top` is 0 at rest so the progress clamps to 1 immediately. Anything visible at rest needs its own load clock; only what starts below the fold can be mapped to scroll (`cases/wheel-rail` §2).
  336. - **Interaction motion means motion the mouse produces.** Wheel and pointer, nothing else. A page that drifts, breathes and dissolves on its own clock while the mouse sits still is a screensaver, and it will satisfy a "add motion" brief while failing the actual request. Ask which input drives it before building (`cases/wheel-rail` §0).
  337. - **A probe that reads back what the code wrote cannot tell you what the screen shows.** An oracle asserting a hard cut read `el.style.opacity` — the inline value the loop sets — and reported a perfect flipbook for a copy with `transition: opacity 250ms` added, because a transition interpolates *between* inline values and the inline read jumps straight to the target. `getComputedStyle` catches it at 19 of 60 samples mid-transition. This is the probe-only lesson one layer down: the first version tests intent, not rendering (`cases/toy-flipbook` §5 #2).
  338. - **A low-probability effect needs a driver that clears its threshold, or the assertion was never run.** A desk-toy kick fires only above `|v| > 2.2` and then wins a 6 % roll; a pointer sweep peaks at exactly 2.2, so the leg reported 0/5 and could not distinguish a broken mechanism from a test that never triggered. Drive it with something that overshoots, and **print the peak and fail if it never cleared the threshold** — a leg that did not run must say so rather than pass or fail silently (`cases/toy-flipbook` §5 #3).
  339. - **A comment can promise what the code has never once done.** `s.v = s.v < -30 ? -s.v * 0.35 : 0` sat under a comment reading "bounce, then rest" in shipped code; `s.v` is positive while falling, so the branch never ran and every toy stopped dead on contact. It looked fine — you only miss a bounce if you know it was meant to be there. Assert the *consequence* (the squash) rather than the movement, and the dead branch surfaces immediately (`cases/toy-flipbook` §5 #1).
  340. - **`file://` refuses a CSS mask and allows an `<img>`, so a page can be half-lit and look almost right.** `mask-image: url(img/x.webp)` is a CORS fetch from origin `null`; the photograph loads, the lighting silently does not, and three console lines are the only evidence. Inline the mask as a `data:` URI and leave the display image external — a mask carries alpha only, so 320 px and flat RGB is ~4 KB against 75 KB for the photo it clips.
  341. - **An oracle's baseline must be measured still, never waited out — a fixed settle time let a copy with the pointer force set to ZERO pass every assertion.** `verify_case.py` fires one real wheel in its own smoke test; on a page that turns a wheel into a decaying impulse, a hard-coded 2.6 s settle landed *inside* the 2.7 s decay, so the page was still drifting on its own and every later displacement was credited to the pointer. Poll the probe until motion is under threshold, and fail if it never settles. A settle time that is long enough today stops being long enough the moment someone adds an entrance (`cases/char-curtain` §5 #1).
  342. - **A ratio dominated by structure cannot test the force that produced it.** An anisotropic pointer push (x at full, y at 0.35) looked testable as "is horizontal displacement much larger than vertical" — 7.9× on the real case. A copy with the bias set to 1.0 measured **8.8×**, higher, because the vertical links absorb y motion by sliding nodes along the string. Assert the structural claim the code actually makes instead: poking one column must leave a distant column alone (`cases/char-curtain` §5 #2).
  343. - **A rate limit computed once per frame is not a rate limit.** The budget was read before a loop over nine emitters and passed in as a flag, so all nine could fire on the same frame: a stated cap of 4 measured 6 and allowed 9. Re-read the budget inside the loop *and* guard again at the moment of the push. The overshoot is invisible by eye, which is why only an oracle finds it (`cases/lyre-crows` §5 #1).
  344. - **An assertion can match a string the page is structurally unable to produce.** A check for the full replacement sentence failed against a perfectly working page, because the tail holds a fixed node count and anything longer is truncated. Assert that state *changed* — against a snapshot taken before the interaction — rather than that it changed into one exact value (`cases/lyre-crows` §5 #2).
  345. - **A pure-canvas page is invisible to the floor's input check, and that is a finding about the page, not the check.** The change signature is scrollY plus computed styles plus `innerText`; canvas pixels are in none of them. A demo that is one `<canvas>` can be full of motion and still fail "a real wheel event changed nothing" — and a visitor who has not moved yet, or anyone using a screen reader, gets exactly as little as the checker does. A small live readout in the DOM fixes both at once (`cases/char-curtain` §5 #3).
  346. - **One flaky fetch in a hundred runs is enough to make a whole suite untrustworthy, and a CDN font is the usual culprit.** Two cases kept a Google Fonts `<link>` because substituting a lookalike face would have changed the design rather than ported it — sound reasoning, wrong conclusion. A full-suite run went red once on `console/page errors`; twelve deliberate re-runs were clean. An intermittent failure nobody can reproduce is worse than a consistent one, because the first thing anyone does with it is stop trusting the suite. Keep the real faces and remove the network instead: fetch the OFL originals, subset each to the characters its own page renders (65.8 → 40.9 KB for a variable serif), inline them.
  347. - **Prove an oracle by breaking the case.** `--rail`'s hijack assertion passed a copy with `preventDefault()` deleted, because `overflow:hidden` already pinned `scrollY`. The check was vacuous and would have stayed vacuous forever. Run every new oracle against a deliberately broken copy of its own case before filing it (`cases/wheel-rail` §3).
  348. - **`position:sticky` does not fire inside a transformed ancestor.** Any pinned element inside a hijacked rail has to be parked by hand against the rail offset. This is not a bug to debug — it is the spec (`cases/wheel-rail` §2).
  349. - **A post-process pass ships with a debug channel or it is undebuggable.** "The heads render as black blobs" sent me into the capsule mesh; one look at the raw colour buffer showed shadows above the figures, i.e. an inverted camera basis. Expose raw colour / linear depth / edge magnitude from the first frame you write (`cases/ink-crowd` §4).
  350. - **Stillness is a spec.** 444 of 504 frames of that reference have zero changed pixels; its whole motion budget is *when things appear*. If a page's character is staccato, the assertion is `document.getAnimations()` empty and rects bit-identical between events — not an easing curve.
  351. - **A stylesheet that fails to parse does not error — it recovers, and recovery eats the next block.**
  352. One `*/` written inside a banner comment closed it early and the parser consumed the following
  353. `:root{}` as that garbage rule's body: 23 tokens undefined, `background: var(--ground)` invalid at
  354. computed-value time, the whole `font:` shorthand dropped to Times 16px — and the page passed every
  355. check in `verify_case.py` (`cases/string-clock`, 踩过的坑 #1). Never write `*/` inside a comment;
  356. the floor now fails on any referenced-but-undefined custom property and on a transparent body.
  357. - **A colour is not an `<image>`, so it takes the whole declaration down with it.**
  358. `background-image: <gradient>, #eae3d3` is invalid and drops in full — the ground simply never
  359. paints, with nothing logged. Colours belong in `background-color`, layered under the gradient.
  360. - **A scripted edit that matches nothing reports success.** Two `str.replace` calls in one session
  361. silently changed no bytes because the pattern had drifted from the file. Assert the file actually
  362. changed after every scripted edit, or the next check is measuring the old page.
  363. - **A percentage inside a transform resolves against the element's own box, never the container.**
  364. `translateY(-40%)` on a 64px numeral is 26px, not 40% of the dial — and a token used as *both* a
  365. width and a transform argument (`--dial: min(74vh, 100%, 760px)`) resolves differently in the two
  366. places, so it can be correct at one breakpoint and wrong at another from one declaration.
  367. - **A discrete control is driven by committing a state, not by an impulse.** A wheel notch on a
  368. detented dial means "next slot", not "add velocity": a mouse reports `deltaY` 120 and a trackpad
  369. 600+, and a spring pulling back the whole time makes the actual travel unpredictable. And never
  370. `preventDefault()` a wheel unconditionally — hand it back at the control's ends or the page cannot
  371. scroll.
  372. - Do not let motion hide weak hierarchy, unreadable text, or missing content.
  373. - **The still frame is half the deliverable.** Screenshot with motion disabled and be willing to defend
  374. that frame on its own. "不好看 / 像 AI 做的" is almost never a motion-tuning problem — going to the
  375. springs first is the documented wrong move (`design-slop.md`).
  376. - **Design the page before the mechanic goes into it.** Macrostructure, type scale and palette are an
  377. act with their own output, not a clause inside the build step. Placing a mechanic into a page that
  378. already works is the opposite order from decorating a template, and it is the order that works.
  379. - Extract real motion values when possible: trigger, duration, easing, stagger, transform, media, library, reduced-motion behavior.
  380. - Treat X posts, videos, and screenshots as topic information only until the real page is inspected (Video Reference Protocol).
  381. - Light 3D belongs here only when it is part of a web page: hero scenes, product staging, shader planes, scroll cameras, spatial cards, or WebGL-lite atmosphere.
  382. - **A shader is required only when the picture has to change at runtime.** If the viewer only moves
  383. *through* the picture, a whole scene can be unlit `MeshBasicMaterial` planes — SBS *The Boat* ships
  384. zero `ShaderMaterial`, zero custom blending, zero `renderOrder` across 117 app modules
  385. (`image-plane-3d.md` §14). Decide which one you are building before writing the first material.
  386. - **Depth does not require geometry.** A `PerspectiveCamera` doesn't care whether the thing at `(x,y,z)` is a
  387. mesh or a textured plane — it foreshortens, occludes, sorts and projects either way. Before proposing models,
  388. ask what actually has to *rotate*; if the answer is "nothing, the camera just moves", the whole scene can be
  389. flat images (`references/image-plane-3d.md`). What separates it from collage is measurement, not art.
  390. - Full 3D scenes, game-like environments, generated models, physics-heavy scenes, and material/light pipelines → route to `3d-scene-studio` — after ruling out rung 5.
  391. - Use `MOTION_SPEC.md` as the build contract for complex builds. Skip it for quick freeform builds.
  392. - Implementation is not done until desktop, mobile, reduced-motion, performance, and build/type-check are verified.
  393. - **R3F & DOM Sync**: If WebGL canvas is in background (`pointer-events: none`), `state.pointer` dies. Use global `window.addEventListener('pointermove')` for NDC coordinates.
  394. - **Parallax vs Unproject**: If tracking DOM elements to WebGL meshes, `Vector3.unproject(camera)` will conflict with a moving Parallax camera. Unproject using a separate static dummy camera.
  395. - **Scroll Morphing**: Do not use CSS `clip-path` on Canvas. Keep Canvas `100vw/100vh`, track transparent DOM placeholders via `getBoundingClientRect()`, and lerp mesh position/scale. Use Shader SDFs for rounded corners instead of real geometry.
  396. ---
  397. ## Data
  398. - `data/visual-bank.json` — the static-first visual design library: 7 palette archetypes, 5 typography
  399. systems, 5 layout grids, each with concrete values (`clamp()` scales, letter-spacing, grid CSS).
  400. `page-design.md` and `design-slop.md` A4 point here. Pick one archetype and commit; do not blend two.
  401. - The measured numbers quoted in `components.md` §1, `page-blueprints.md`, `production-polish.md` and
  402. `page-design.md` §2 come from a 2026-08 headless run over 32 sites (18 award-winning creative, 14
  403. product-marketing) with `scripts/measure_structure.py` at 1440×900 and 390×844. The summaries live in
  404. those files; the per-site records are not part of this release. Re-run the script on a fresh set of
  405. URLs when you need a current baseline.
  406. ---
  407. ## Cases
  408. `cases/` ships **working, verified source** — unlike a technical-breakdown-only library, the whole page
  409. is there and it runs. That makes one rule load-bearing:
  410. > **机制层照搬,皮层一律不许照搬。**
  411. > The **mechanism** — solvers, math, guards, probe surfaces, the `@supports` authoring order — is
  412. > engineering, not an aesthetic signature. Lift it verbatim; re-deriving a homography by hand is waste.
  413. > The **skin** — palette, type values, grid, section order, copy, the invented brand — is the case's
  414. > own identity. Reusing it produces a page that is recognisably this case wearing a different logo,
  415. > which is the exact template behaviour the rest of this skill exists to prevent.
  416. Each case's `index.html` marks the boundary in a comment banner, and its `README.md` has the split as
  417. two explicit lists (可以照搬 / 不许照搬) plus the reasoning behind every skin decision — **that**
  418. reasoning is what transfers, not the values.
  419. | Case | Teaches | Stack |
  420. |---|---|---|
  421. | `cases/string-clock/` | **soft body, exact endpoint** — clock hands as slack elastic strings pinned at both ends, a stiff tip spring so the readout stays true while the stroke lies, `Rods` shipped as the degenerate case, and the dialect finding (product controls on a creative canvas) | single HTML file, rAF |
  422. | `cases/ink-crowd/` | **the ink render layer** — hand-written WebGL2 (no framework, no CDN): 620 instanced capsules into an MRT + depth target, then a fullscreen pass that draws the line from **depth discontinuity only** (interior creases off). Two noises, one static per figure and one on an **11 Hz boil clock** against a 60 fps render. Shadow disc and void are the same primitive. Binary palette, inlined variable font | single HTML file, WebGL2, rAF |
  423. | `cases/press-stack/` | **the sticky stack** — the opposite answer to `wheel-rail`: native scroll left alone, nine screens each `position:sticky;top:0;height:100vh` so the next rides over the last. Progress is read back out of the document (`(scrollY - offsetTop) / innerHeight`), not accumulated. Type wipe lights words `0.22 → 1` in reading order. Every sleeve and record is **drawn on a canvas**, no bitmaps | single HTML file, DOM + Canvas 2D, rAF |
  424. | `cases/wheel-rail/` | **input-driven choreography** — nothing plays on a timer. `wheel` is hijacked `{passive:false}` and eased into a translated rail (`window.scrollY` stays 0); the pointer drives three planes at a 7× depth ratio; labelled nodes are pinned to their curves by `getPointAtLength`; act 4's curve field is parked by hand because `position:sticky` cannot fire inside a transformed ancestor | single HTML file, DOM + inline SVG, rAF |
  425. | `cases/toy-flipbook/` | **rotation in depth without a renderer** — four curated pre-rendered yaw frames, hard-cut by `Math.round` of a spring with no transition anywhere, on a **held 11 Hz jitter clock** against a 60 fps render. One normalised driver feeds every layer its own gain, including opposite signs on the two lines of a single headline | single HTML file, rAF |
  426. | `cases/char-curtain/` | **a cloth that is a set of strings, not a mesh** — 576 glyphs on 24 Verlet columns with **zero horizontal links**, which is the only reason a pointer parts it instead of denting it. Sprung anchors rather than pinned ones, bouncing by reflecting `oldX`, and speed mapped to colour *and* alpha so a still frame shows where the ripple is | single HTML file, Canvas 2D, rAF |
  427. | `cases/lyre-crows/` | **a causal ecology instead of a timeline** — strum a string, a word is released, a steering crow hunts it down and **rewrites its own tail with what it caught**. Rate limiting at the source and unconditional decay on the product are what keep the loop from becoming noise; steering clamps the *force*, not the velocity, which is what gives a turn a radius | single HTML file, Canvas 2D, rAF |
  428. Every case passes the same acceptance floor and prints it in its README: no console errors, zero
  429. horizontal overflow at 320/375/414/768/1440, one `<h1>`, `lang` set, display ÷ body ≥ 4×, ≥ 3 distinct
  430. section shapes, **no referenced custom property left undefined**, a body that paints its own ground,
  431. and **nothing stuck hidden under reduced-motion**. The single-screen hero (`toy-flipbook`) runs with
  432. `--min-shapes 1`, which is an exemption for a hero demo and **not** for anything that is
  433. actually a page. Each case adds a domain oracle. `--beats` and `--detent` are kept without a
  434. case: both need the page to expose their probe contract, so they are patterns to build
  435. against, not checks you can point at an arbitrary page:
  436. | Flag | Asserts | Used by |
  437. |---|---|---|
  438. | `--beats` | sweeps the scroll axis, normalises each track by its own range, and reports the **longest run where no track moved** — the operational definition of a dead beat | no case — needs `__probe.seek/tracks` |
  439. | `--detent` | released at 36 positions, a snapping control lands ≤ 0.02° off a slot, settles, reaches every slot, and clamps at both ends | no case — needs the detent probe |
  440. | `--strings` | two assertions that **pull against each other**: every hand's tip is ≤ 1.5° off the true angle, *and* every hand still sags ≥ 1.12× its chord — plus a **real-pointer** fling at 12/60/240 px per step that may not stretch past 3.2× or leave the box, and a **free-running** pass with the clock unpinned | string-clock |
  441. | `--stack` | the sticky contract: every screen must pin at `top: 0` **while `window.scrollY` keeps advancing** (the inverse of `--rail`, which requires it to stay at 0), ≥3 distinct grounds, and a type wipe that both **shows a gradient** at some moment and **never drops below 0.12** — a page that lights everything at once passes the second test, a page that fades from zero passes the first, and only the reference's device passes both. Also fails any element that pulls a bitmap | press-stack |
  442. | `--rail` | **element churn, idle liveness, plus** the wheel hijack: with the mouse completely still for 1.5 s at least 2 elements must still be changing, because a page whose every motion waits for input is a still image until someone touches it. Then: across a real eight-burst wheel run at least 35 % of elements must change `transform`, `opacity` or `stroke-dashoffset`, and at least 4 must be caught **part-way** through a transition. The first assertion catches a rail that translates while every child holds still; the second catches states that snap. Also, as before, the wheel is hijacked and the pointer carries depth: a real wheel must move a rail while `window.scrollY` stays 0 **and the wheel event is cancelled** (`overflow:hidden` pins `scrollY` on its own but still overscrolls), the rail must be measurably behind target one frame later and settled a second later, and a corner-to-corner pointer sweep must move the far plane at least 1.5× the near one | wheel-rail |
  443. | `--layer <dom\|svg\|canvas2d\|webgl>` | asserts the render layer the README declares, by probing live canvas contexts and inline SVG shape counts rather than trusting the prose — a case claiming `webgl` while shipping divs fails. Implies the **web-font gate**: 0 `@font-face` and no font preload is a fail, because the system stack is the generated-page tell no other gate catches (`--draws-own-type` for a page that draws its own letterforms) | ink-crowd |
  444. | `--follow` | pointer-led motion: aims at five points across the canvas — including bare ground — and requires the crowd **centroid to close on the aim from every one of them**. A follow counter that ticks is not evidence anything walked; a mechanic that works in one band and is deaf everywhere else passes every other check | ink-crowd |
  445. | `--flipbook` | two assertions that **pull against each other**: across a 60-sample real pointer sweep every frame is either fully lit or fully off (a crossfade fails this) *and* the sweep visits every frame in order without skipping (a control that snaps to the end pose fails this). Plus: the jitter re-rolls between 4 and 25 Hz, and a wheel spin past the kick threshold both lifts desk toys off the table and squashes them on landing — **the leg prints its peak drive and fails if it never cleared the threshold**, so an untriggered test cannot pass silently | toy-flipbook |
  446. | `--curtain` | two assertions that **pull against each other**: a real pointer sweep must move the median column ≥ 6px sideways, *and* poking one column must leave the far side of the cloth moving < 20 % as much. A dead cloth fails the first; a sheet with horizontal links passes the first and fails the second. Plus: no link deviates > 35 % from rest length, and every anchor returns within 2px of its peg. **The baseline is polled until the cloth is measurably still rather than waited out** — see the lesson above | char-curtain |
  447. | `--lyre` | two assertions that **pull against each other**: fourteen real strum sweeps must release words, *and* the count aloft must never exceed the page's stated cap while being abused. A decorative instrument passes the cap; an unlimited emitter floods (the broken copy reached 440). Plus: with prey aloft a crow must enter a hunting state and close ≥ 30 % of its gap, and a counted capture must **change that crow's tail** and leave the caught word in it | lyre-crows |
  448. A new case is not a case until `verify_case.py` passes on it.
  449. **Building one — read [cases/AUTHORING.md](./cases/AUTHORING.md) first.** It is the procedure for
  450. 参考 → 复刻 → 收录: the intake gate (does the reference survive having its images stripped?), the
  451. measurement scripts, the four classification decisions, the build rules, the oracle, and what a
  452. README owes — 设计系统 + 动效系统 + 判据 + 可照搬/不许照搬 + 踩过的坑.
  453. **Read a case when**: the user's brief is in its class, you need the mechanism, or you want a worked
  454. example of a doc's rules actually applied. **Do not** open one to "start from" — start from
  455. `page-blueprints.md` and pull the mechanism in.
  456. ---
  457. ## Reference Files
  458. | File | Contains |
  459. |---|---|
  460. | `references/choreography-arc.md` | 5 page-level arc types with motion tokens |
  461. | `references/motion-tokens.md` | **Duration scale, easing dictionary, spring config cheatsheet, stagger patterns, transform budget** |
  462. | `references/pattern-recipes.md` | **ready-to-use motion pattern implementations (Vanilla + Framer + GSAP)** — count them, don't trust a number written here. Includes #17 corner-pin warp (真形变,不是 skew) and #18 the Verlet card chain built on it |
  463. | `references/affordance.md` | **能点 ≠ 看得出能点:the invitation audit, window-vs-dwell, painted-bbox marks, down-records/up-decides, numeric oracles, the invisible handoff** |
  464. | `references/handfeel.md` | **Interaction handfeel: underdamped springs, velocity tilt, wheel momentum guard, jelly wobble, fake lighting on flat images — plus §7 the *following* half (frame-rate-independent `exp(-k·dt)`, the `speed/k` steady-state lag and its lead term, why a correction after the filter hunts, acceleration-driven critical damping) and §8 screen shake** |
  465. | `references/build-mode.md` | Implementation rules, performance rules, verification checklist |
  466. | `references/page-design.md` | **动效页怎么设计:macrostructure 选择、给动效让位的版式、测量自当前获奖站的字号阶梯与配色规模、滚动叙事的分段、移动端降级** |
  467. | `references/design-slop.md` | **动效页专属的 AI 味闸门:关掉动效看静帧、默认 hero、三栏特性卡、紫色渐变、装饰代替设计、统一 hover 抬升、全页 fade-up、首屏烧光预算** |
  468. | `references/page-blueprints.md` | **这页到底放什么:the section vocabulary, 7 blueprints (product / portfolio / studio / campaign / editorial / index / docs), ordering logic, what each section owes in real copy, information architecture, and the measured section-count & shape-variety numbers** |
  469. | `references/components.md` | **组件级 craft:the two measurably different component dialects (creative vs product — radius, shadow, uppercase, nav CTA, footer scale), the state matrix every component owes, and nav / hero / button / tag / card / media / form / accordion / dialog / index / proof / footer** |
  470. | `references/project-setup.md` | **工程 0→1:the page stack ladder (one HTML file → Vite → Astro → Next), the three-level token layer + Tailwind v4 `@theme`, fluid type & space scales with the clamp() formula, font loading with metric overrides, `@layer` order, file layout, images, budget & deploy** |
  471. | `references/production-polish.md` | **从能跑到成品:the full head block, OG images, 404, the states off the happy path, dark mode without a flash, the small "finished" details, machine-readable structure, analytics, and ten manual pre-ship checks** |
  472. | `references/baseline-ui.md` | Accessibility and usability floor (focus, touch targets, hover-free mobile) — the *floor*, not the design |
  473. | `references/motion-spec.md` | MOTION_SPEC.md template and entry field definitions |
  474. | `references/composition-guide.md` | **How to orchestrate custom designs and motion without rigid templates** |
  475. | `references/shaders-spec.md` | **WebGL GLSL shaders, simplex noise, rendering optimization — and §6 the silent failures: int-vs-float literals killing a program, missing tonemapping/colorspace includes, `DepthTexture` filtering, distance falloff for high-frequency detail, spatially-coherent instanced wind** |
  476. | `references/tactile-texture.md` | **SVG viscous filters, CSS Houdini, OffscreenCanvas, and canvas grain patterns** |
  477. | `references/image-asset-pipeline.md` | **图片资产怎么造出来:keying against the image's own background, the `coverage` gate, bbox crop, line-art alpha, scripted `cx/baseline`, the crown anchor nobody records, per-element resolution budget, texture density vs serving distance, provenance** |
  478. | `references/scene-streaming.md` | **大场景怎么装得下:screen-window activation, cooperative scanning, throttled DOM mutation, full disposal, sliced texture upload, audio streamed by audibility** |
  479. | `references/verification-harness.md` | **判据台架:the probe contract (`__seek`/`__hold`/pinnable clocks/state exits), on-off differencing, why teleport and screen-diff lie, determinism as a precondition, sampling rate, the ruler's resolution floor — and why a composite quality score is worse than no test** |
  480. | `references/timeline-orchestration.md` | **多轨滚动时间轴:read the schedule horizontally, one easing layer, weight by what the eye reads, one window one event, velocity-zero keyframes, the apparatus outliving its content, the money frame, threshold-map histograms** |
  481. | `references/scene-audio.md` | **场景声音:three buses (bgm/hand/world), per-act LUFS curves, ducking, discrete events over a louder bed, why a continuous quantity reads as ambience, the REST oracle, filters eating 20 dB** |
  482. | `references/image-plane-3d.md` | **图片资产做出真纵深:flat cutouts as planes in a real perspective camera — asset metadata contract, long lens, silhouette interlock, hand-sorted transparency, analytic contact shadows, the colour-temperature cure for 「拼接感」** |
  483. | `references/light-3d.md` | Three.js/R3F/canvas integration rules + DOM-over-a-moving-scene |
  484. ---
  485. ## Scripts
  486. ```bash
  487. # ── MEASURE STRUCTURE (the static-page half: sections, components, tokens, polish) ─
  488. # Answers "how is it built as a page": sections, nav, buttons, token scales, forms, media, meta, mobile overflow.
  489. python3 scripts/measure_structure.py https://example.com
  490. python3 scripts/measure_structure.py --urls-file urls.txt --out data/structure-bank.json
  491. # Skips URLs already present in the out file, so a killed run resumes.
  492. # ── DECONSTRUCT A VIDEO REFERENCE (no URL to open) ────────────────────────────
  493. # measure_structure needs a loadable page. A clip has none.
  494. python3 scripts/measure_frames.py sheet ref.mp4 # contact sheet — ALWAYS look first
  495. python3 scripts/measure_frames.py palette ref.mp4 -t 8 # ground %, accents, mid-grey scale
  496. python3 scripts/measure_frames.py bands ref.mp4 -t 8 # control heights/widths off the pixels
  497. python3 scripts/measure_frames.py trace ref.mp4 --color red # arc/chord per frame
  498. python3 scripts/measure_frames.py grounds ref.mp4 # section changes + which way the new screen arrives
  499. python3 scripts/measure_frames.py wipe ref.mp4 --from 7.9 --to 10.1 --dark
  500. # ^ the schedule of a per-word reveal, and the one number a still frame cannot give
  501. # you: whether unlit type is hidden (0.00) or merely dimmed (side-b: 0.22).
  502. # ── VERIFY A CASE / ANY BUILT PAGE ────────────────────────────────────────────
  503. # The acceptance floor every case's README claims. Re-runnable, so the claim can't rot.
  504. python3 scripts/verify_case.py cases/string-clock/index.html --strings # exact tip, sagging body
  505. python3 scripts/verify_case.py cases/ink-crowd/index.html --layer webgl --follow # declared layer + pointer-led crowd
  506. python3 scripts/verify_case.py cases/wheel-rail/index.html --rail # hijacked wheel + depth + churn
  507. python3 scripts/verify_case.py cases/press-stack/index.html --stack # sticky dwell + type wipe + drawn art
  508. python3 scripts/verify_case.py cases/toy-flipbook/index.html --min-shapes 1 --flipbook # hard cut AND continuous scrub
  509. python3 scripts/verify_case.py cases/char-curtain/index.html --min-shapes 1 --curtain # parts AND stays independent
  510. python3 scripts/verify_case.py cases/lyre-crows/index.html --min-shapes 1 --lyre # releases AND stays limited
  511. python3 scripts/verify_case.py http://localhost:5173 # works on a dev server too
  512. # ── DOES ANYTHING ACTUALLY MOVE? ──────────────────────────────────────────────
  513. # The check that caught what every oracle above missed twice: a page with all the
  514. # right mechanisms that reads as dead. Drives a REAL wheel; scrollTo teleports
  515. # past the arriving-and-leaving window where the motion lives.
  516. python3 scripts/measure_churn.py https://a-reference.com # characterise it first
  517. python3 scripts/measure_churn.py cases/foo/index.html --against https://a-reference.com
  518. # ── SHIP REAL TYPE, NOT THE SYSTEM STACK ──────────────────────────────────────
  519. # 0 @font-face is the loudest generated-page tell (render-layer.md §2).
  520. python3 scripts/subset_fonts.py list
  521. python3 scripts/subset_fonts.py pack --out /tmp/faces.css \
  522. Grot=Inter-Variable Ital=InstrumentSerif-Italic Mono=IBMPlexMono-Regular
  523. ```
  524. **Self-check** (run after editing `scripts/` or any case, or when the user asks to 体检 this skill):
  525. ```bash
  526. cd ~/.claude/skills/motion-web
  527. python3 -c "import json;json.load(open('data/visual-bank.json'))" && echo "json OK"
  528. python3 -m py_compile scripts/*.py && echo "syntax OK"
  529. # then the seven verify_case.py lines above — every one must print VERDICT: PASS
  530. ```
  531. **zsh does not split variables.** `flags="--layer webgl"; verify "$f" $flags` passes the whole string
  532. as one argument and argparse reports `unrecognized arguments`. Write the flags out, or use `${=flags}`.
  533. ---
  534. ## Output Contracts
  535. **For spec work**: output a concise `MOTION_SPEC.md` from the template in `references/motion-spec.md`.
  536. **For freeform build**: skip the spec. Build immediately. After completion, tell the user:
  537. - The concept name and why you chose it
  538. - The arc type and how it shapes the page rhythm
  539. - The 3 most important motion decisions made
  540. - What to verify (reduced-motion, mobile, FPS)
  541. **For a `full-build`**: report the blueprint chosen and why, the page stack rung, the component dialect
  542. (creative vs product), the motion concept, **every factual slot you had to invent, listed explicitly**, and
  543. the results of `production-polish.md` §9 — which checks passed and which you could not run.
  544. **For any build**: verify locally before reporting done. Run build/type-check if applicable. Report what changed, what was verified, and any remaining risk.
README.md · README · 206 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # motion-web
  2. > **Build motion-first, high-touch creative websites on vanilla Three.js / Canvas 2D / WebGL / CSS. A Claude Agent Skill with real-world physics, token discipline, and automated headless verification.**
  3. > **动效即材质:面向 Agent 与前端工程师的高手感交互动效体系。内置 7 大完整案例、物理阻尼求解器、排版规范与自动化 Headless 验证判据。**
  4. [![License: CC BY-NC 4.0](https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey.svg)](LICENSE)
  5. [![Type](https://img.shields.io/badge/Type-Agent%20Skill-333.svg)](SKILL.md)
  6. [![Cases](https://img.shields.io/badge/Cases-7%2F7%20PASS-brightgreen.svg)](cases/)
  7. [![Platform](https://img.shields.io/badge/Platform-Vanilla%20JS%20%7C%20Canvas%20%7C%20WebGL2-orange.svg)](cases/)
  8. **▶ From the same author: [onetake](https://github.com/feitangyuan/onetake), launch films and feature demos made with a coding agent, in one continuous take → [onetakemotion.com](https://onetakemotion.com)**\
  9. **▶ 同一作者:[onetake](https://github.com/feitangyuan/onetake),用 coding agent 做一镜到底的产品发布片和功能演示 → [onetakemotion.com](https://onetakemotion.com)**
  10. ---
  11. [English](#english) | [中文说明](#chinese)
  12. ---
  13. <a name="english"></a>
  14. ## English
  15. `motion-web` is a code-first, motion-driven creative web engineering skill. It treats **motion as the core material of the interface** rather than after-the-fact decoration.
  16. Every case and blueprint enforces real physical laws (spring-damper systems, anisotropic forces, stepped jitter, causal ecosystems) and zero placeholder code. All cases come with automated Playwright headless verification oracles (`verify_case.py`) to mathematically prevent AI slop, synthetic drifts, and dead interactions.
  17. ### 🎬 Promo Reel
  18. ![motion-web 15s promo](assets/hero.gif)
  19. > 🎥 Full 60fps stereo audio version: [`assets/motion-web-15s.mp4`](assets/motion-web-15s.mp4)
  20. ---
  21. ### 🌟 Seven Interactive Cases (All 100% Runnable & Verified)
  22. All cases are single-file HTML pages that run standalone without build tools or external CDN dependencies. Every case passes strict assertions in `verify_case.py`.
  23. <table>
  24. <tr>
  25. <td width="50%" align="center">
  26. <b>01 · string-clock (DROOP!)</b><br/>
  27. <img src="assets/cases/string-clock.gif" width="100%" /><br/>
  28. <sub>Softbody clock hands with absolute endpoint accuracy</sub><br/>
  29. <a href="cases/string-clock/index.html">▶ Live Page</a> | <a href="cases/string-clock/README.md">📖 Breakdown</a>
  30. </td>
  31. <td width="50%" align="center">
  32. <b>02 · ink-crowd (Drawn, Not Rendered)</b><br/>
  33. <img src="assets/cases/ink-crowd.gif" width="100%" /><br/>
  34. <sub>Procedural WebGL2 ink crowd, depth-discontinuity contours</sub><br/>
  35. <a href="cases/ink-crowd/index.html">▶ Live Page</a> | <a href="cases/ink-crowd/README.md">📖 Breakdown</a>
  36. </td>
  37. </tr>
  38. <tr>
  39. <td width="50%" align="center">
  40. <b>03 · press-stack (Lathe)</b><br/>
  41. <img src="assets/cases/press-stack.gif" width="100%" /><br/>
  42. <sub>Sticky stacked vinyls, spring overshoot, zero bitmaps</sub><br/>
  43. <a href="cases/press-stack/index.html">▶ Live Page</a> | <a href="cases/press-stack/README.md">📖 Breakdown</a>
  44. </td>
  45. <td width="50%" align="center">
  46. <b>04 · wheel-rail (Equal Length)</b><br/>
  47. <img src="assets/cases/wheel-rail.gif" width="100%" /><br/>
  48. <sub>Wheel-driven curved rail, 3 depth planes, 7× parallax</sub><br/>
  49. <a href="cases/wheel-rail/index.html">▶ Live Page</a> | <a href="cases/wheel-rail/README.md">📖 Breakdown</a>
  50. </td>
  51. </tr>
  52. <tr>
  53. <td width="50%" align="center">
  54. <b>05 · toy-flipbook (TOYBOX)</b><br/>
  55. <img src="assets/cases/toy-flipbook.gif" width="100%" /><br/>
  56. <sub>Hard-cut yaw frames via spring round + 11Hz stepped jitter</sub><br/>
  57. <a href="cases/toy-flipbook/index.html">▶ Live Page</a> | <a href="cases/toy-flipbook/README.md">📖 Breakdown</a>
  58. </td>
  59. <td width="50%" align="center">
  60. <b>06 · char-curtain (Curtain)</b><br/>
  61. <img src="assets/cases/char-curtain.gif" width="100%" /><br/>
  62. <sub>Cloth as independent Verlet ropes, anisotropic pointer push</sub><br/>
  63. <a href="cases/char-curtain/index.html">▶ Live Page</a> | <a href="cases/char-curtain/README.md">📖 Breakdown</a>
  64. </td>
  65. </tr>
  66. <tr>
  67. <td colspan="2" align="center">
  68. <b>07 · lyre-crows (The Lyre & the Ink Crows)</b><br/>
  69. <img src="assets/cases/lyre-crows.gif" width="60%" /><br/>
  70. <sub>Causal ecosystem: plucked strings release words, ink crows pursue and rewrite tails</sub><br/>
  71. <a href="cases/lyre-crows/index.html">▶ Live Page</a> | <a href="cases/lyre-crows/README.md">📖 Breakdown</a>
  72. </td>
  73. </tr>
  74. </table>
  75. ---
  76. ### 📦 Installation
  77. #### As Claude Code Skill
  78. ```bash
  79. git clone https://github.com/feitangyuan/motion-web.git ~/.claude/skills/motion-web
  80. ```
  81. #### As Codex / Antigravity Skill
  82. ```bash
  83. git clone https://github.com/feitangyuan/motion-web.git ~/.agents/skills/motion-web
  84. ```
  85. ---
  86. ### 🧪 Automated Verification
  87. Verify all 7 cases with Playwright headless oracles:
  88. ```bash
  89. # Verify all cases
  90. python3 scripts/verify_case.py cases/string-clock/index.html --strings
  91. python3 scripts/verify_case.py cases/ink-crowd/index.html --layer webgl --follow
  92. python3 scripts/verify_case.py cases/press-stack/index.html --stack
  93. python3 scripts/verify_case.py cases/wheel-rail/index.html --rail
  94. python3 scripts/verify_case.py cases/toy-flipbook/index.html --min-shapes 1 --flipbook
  95. python3 scripts/verify_case.py cases/char-curtain/index.html --min-shapes 1 --curtain
  96. python3 scripts/verify_case.py cases/lyre-crows/index.html --min-shapes 1 --lyre
  97. ```
  98. Launch the local interactive gallery:
  99. ```bash
  100. python3 -m http.server 8899 -d cases/
  101. # Open http://localhost:8899
  102. ```
  103. ---
  104. <a name="chinese"></a>
  105. ## 中文说明
  106. `motion-web` 是一个面向 Agent 与前端开发者的动效与创意网页工程体系。它坚持**动效即材质(Motion is the Material)**,拒绝浮于表面的装饰性动画,通过真实的物理模拟、严苛的排版与设计系统约束,交付兼具审美手感与生产级代码质量的创意交互页面。
  107. ### 核心设计原则
  108. 1. **拒绝 AI 塑料感(Anti-AI-Slop)**:
  109. - 严禁任何无意义的 `opacity: 0 -> 1` 或线性匀速缓动;
  110. - 采用真实的二阶弹簧阻尼系统(Spring-damper)、各向异性推力与定格阶梯抖动(Stepped Jitter);
  111. - 每一个动作都有阻尼、有动量、有过冲回弹。
  112. 2. **机械级验收地板(Automated Verification Floor)**:
  113. - 每个案例均配备专属的无头 Chromium 探针(Oracle),自动模拟真实指针扫掠、滚轮事件与惯性衰减;
  114. - 只有通过数学断言(位移比、形变误差、回弹锚点、状态收敛)的代码才允许交付。
  115. 3. **零外部网络依赖(Self-Contained)**:
  116. - 案例与模板均采用子集化内联字体与原生 WebGL2 / Canvas 2D 绘制,断网状态下完整可运行。
  117. ---
  118. ### 7 大实测案例一览
  119. | 案例 | 机制核心 | 技术栈 | 验收判据 |
  120. |---|---|---|---|
  121. | [`string-clock`](cases/string-clock/) | **软体绳索但端点精确**:松弛弹性绳指针,尖端硬弹簧确保读数绝对准确,笔画在撒谎而时间没有。 | Canvas 2D + rAF | `--strings` |
  122. | [`ink-crowd`](cases/ink-crowd/) | **墨线手绘渲染层**:620 个胶囊体实例进 MRT 几何与深度缓冲,全屏 Pass 仅从深度不连续处勾勒墨线。 | WebGL2 (MRT, G-Buffer) | `--layer webgl --follow` |
  123. | [`press-stack`](cases/press-stack/) | **粘性叠层**:九屏各自 sticky top:0,后屏滚动骑压前屏;Canvas 纯矢量手绘唱片封套。 | DOM + Canvas 2D | `--stack` |
  124. | [`wheel-rail`](cases/wheel-rail/) | **输入驱动的轨道编排**:拦截 wheel 缓动平移轨道,三层视差平面(景深比 7×),沿 SVG 曲线钉住标签。 | DOM + Inline SVG | `--rail` |
  125. | [`toy-flipbook`](cases/toy-flipbook/) | **零 DCC 深度旋转**:4 张预渲染 Yaw 角度帧,弹簧位移通过 Math.round 硬切,11Hz 阶梯抖动。 | Canvas 2D / DOM + rAF | `--min-shapes 1 --flipbook` |
  126. | [`char-curtain`](cases/char-curtain/) | **绳排非网布**:576 个字符悬挂在 24 条独立 Verlet 绳上,列间零水平约束,指针掠过如撩开帘幕。 | Canvas 2D + Verlet | `--min-shapes 1 --curtain` |
  127. | [`lyre-crows`](cases/lyre-crows/) | **因果生态闭环**:拨弦抖出词句,墨鸦转向猎食并改写自身尾迹;转向钳制加速度保留转弯半径。 | Canvas 2D + Steering | `--min-shapes 1 --lyre` |
  128. ---
  129. ### 目录结构
  130. ```
  131. motion-web/
  132. ├── SKILL.md # Agent 核心执行规范与工作流定义
  133. ├── LICENSE # CC BY-NC 4.0 许可证(非商用)
  134. ├── README.md # 规范与展示文档
  135. │
  136. ├── cases/ # 7 大完整、可运行、可验证的交互案例
  137. │ ├── index.html # 案例画廊入口
  138. │ ├── AUTHORING.md # 案例开发与判据编写规范
  139. │ ├── string-clock/ # 软体弹性绳索时钟
  140. │ ├── ink-crowd/ # 原生 WebGL2 墨线群集
  141. │ ├── press-stack/ # 粘性叠层唱片封面
  142. │ ├── wheel-rail/ # 滚轮驱动视差轨道
  143. │ ├── toy-flipbook/ # 硬切翻页与阶梯抖动
  144. │ ├── char-curtain/ # 独立 Verlet 绳排门帘
  145. │ └── lyre-crows/ # 因果生态文字猎鸟
  146. │
  147. ├── references/ # 深入规范:物理阻尼、排版尺度、组件方言、生产级打磨
  148. │ ├── physics.md # 弹簧阻尼模型与数学求解
  149. │ ├── components.md # 组件方言与实测基线
  150. │ ├── page-design.md # 字号梯次与版面比例
  151. │ ├── page-blueprints.md # 页面架构与叙事蓝图
  152. │ └── production-polish.md # 生产级细节自检清单
  153. │
  154. ├── scripts/ # 自动化无头测量与验收工具链
  155. │ ├── verify_case.py # 案例 Headless Oracle 验收脚本
  156. │ ├── measure_structure.py # 页面静态结构与 Token 提取
  157. │ ├── measure_churn.py # 交互变化率与过渡状态测量
  158. │ ├── measure_frames.py # 逐帧逆向测量工具
  159. │ └── subset_fonts.py # 字体按需子集化内联工具
  160. │
  161. └── assets/ # 演示动图、缩略图与宣传视频
  162. ├── hero.gif
  163. ├── motion-web-15s.mp4
  164. └── cases/ # 各案例交互演示动图与快照
  165. ```
  166. ---
  167. ### License
  168. 本项目采用 [CC BY-NC 4.0](LICENSE)(知识共享署名-非商业性使用 4.0 国际)许可证。个人学习、学术研究与非商业展示可免费使用;禁止任何未经授权的商业集成、平台内置或营利性分发。如需商业授权或企业合作,请联系作者。项目内嵌入的第三方开源字体子集保留原各自开源许可(SIL Open Font License)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.