Communitygithub.com

Asymmetric-al/core

從零開始建構動畫,依序做出決定以確認感覺是否正確——是否該有動畫、目的為何、使用哪種工具、哪些屬性、曲線與持續時間、如何中斷、如何退出。並產出實作程式碼。

core 是什麼?

這是一個專門用於實作 Web 動畫的 AI 技能,從設計工程與動畫合約出發,遵循嚴謹的動畫建構序列。它不會審查現有程式碼或尋找動畫機會,而是專注於將動畫需求轉化為高品質、可通過嚴格審查的實作。支援的觸發情境包括建構或重寫網頁動畫、轉場或微互動,但不適用於 React Native、程式碼審查或單純的動畫評論。其核心工作流程要求先載入相關設計與動畫技能文件,重用現有動畫令牌與 UI 元件,並保持減少動畫的全局設定。技能內建七大建構步驟:判斷是否該有動畫、命名目的、選擇最便宜的工具、挑選屬性、設定曲線與持續時間或彈簧、處理中斷與退出、以及確保減少動畫與指標閘控。同時提供詳盡的「永不發佈」清單,幫助開發者避開常見錯誤。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Asymmetric-al/core/tree/HEAD/.agents/skills/animate

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

建構動畫

此儲存庫 (Asymmetric-al/core)

在 Core 的設計工程與操作動畫合約之後,使用此技能來實作網頁動畫。在上游更新後,先調和此覆蓋層再執行 bun run skills:sync。

觸發條件

  • 建構或重寫網頁動畫、轉場或微互動。
  • 請勿用於 Expo/React Native (animate-expo)、程式碼審查 (improve-animations) 或嚴格的純動畫評論 (review-animations)。

工作流程

  1. 首先載入 docs/ai/skills/emil-design-engineering/SKILL.md 和 docs/ai/skills/anim/SKILL.md。
  2. 重用現有的 Core 動畫令牌和 Base UI 基本元件。請勿分支持續時間、緩動曲線或引入 Radix API。
  3. 在 packages/ui/styles/globals.css 中,將減少動畫保持在全局基線。
  4. 如果任務需要 toast、抽屜、選單或下拉選單,請重用 @asym/ui / Base UI。除非使用者明確詢問要使用哪個函式庫,否則請不要呼叫 pick-ui-library。

檢查清單

  • 動畫有其目的,並儘可能使用 transform/opacity。
  • Core 令牌、Base UI 和 anim 優先於說明性的上游值。
  • 偏好使用共享工具和 @asym/lib/motion-presets,而非新的時間字面值。

這是一個建構技能。它只做一件事:將動畫需求轉化為能夠通過嚴格審查的實作。它不會審查程式碼(那是 improve-animations)、評論差異(那是 review-animations)、尋找可以加入動畫的地方(那是 find-animation-opportunities),或用於 React Native(那是 animate-expo)。

操作姿態

你是一位資深設計工程師,正在親自建構動畫。標準是 Emil Kowalski 的動畫哲學——與 review-animations 所執行的標準相同。撰寫程式碼時,要使其能一次性通過該審查。

兩種失敗模式,第一種更糟:

  1. 對不該有動畫的事物加入動畫。 下方的閘門有時會產生零行程式碼。這是成功,而非逃避。
  2. 使用錯誤的要素為正確的事物加入動畫——在進場動畫中使用 ease-in、scale(0)、在 toast 上使用關鍵幀、或是讓下拉選單感覺遲緩的持續時間。

切勿將動畫選項呈現為選單。做出決定,用一句話說明理由,然後撰寫程式碼。

嚴格規則

  1. 依序執行序列。 步驟 1 和 2 是所有事情的閘門。在知道是否要加入動畫之前,不要急著選擇曲線。
  2. 不使用近似值。 每個曲線、持續時間和彈簧配置都來自下方的表格。切勿因為 cubic-bezier(0.4, 0, 0.2, 1) 看起來很熟悉就擅自使用。
  3. 擴展程式碼庫的令牌,而非分支它們。 如果 --ease-out-soft 或持續時間令牌已存在於 packages/ui/styles/globals.css 中,請使用它。加入平行系統是種缺陷。
  4. 減少動畫和懸停閘控會隨動畫一起交付,而不是事後才補上。
  5. 使用最便宜的可行工具。 不要為了淡入效果而安裝動畫函式庫。

建構序列

1. 這個動畫應該存在嗎?

頻率決定
每天 100+ 次(鍵盤快捷鍵、指令面板切換)永遠不要加入動畫。 在此停止。
每天數十次(懸停效果、列表導航)僅限幾乎不可察覺——快速且細微,否則不要
偶爾(模態視窗、抽屜、toast)標準動畫
罕見 / 首次(新手引導、成功、慶祝)愉悅預算在此

鍵盤啟動的操作是取消資格,而非判斷問題。 Raycast 沒有開啟/關閉動畫——這對於每天開啟數百次的東西來說是正確的。

如果請求未通過此閘門,請直接說明,並且不要撰寫動畫。提供非動畫的替代方案(即時狀態變更、靜態提示)作為替代。

2. 目的是什麼?

在繼續之前,用以下詞彙之一來命名:

  • 反饋 — 確認介面已接收到使用者的操作
  • 空間一致性 — 顯示某物從何處來或到何處去
  • 狀態指示 — 使狀態變更易於理解
  • 防止突兀的變化 — 銜接原本會瞬間跳轉的內容
  • 說明 — 展示某物如何運作(僅限行銷/新手引導)
  • 愉悅 — 僅允許在「罕見/首次」層級

無法命名?就不要建構。「它看起來很酷」對於一個經常見到的元素來說,是停止的理由。

也要檢查功能:使用者正在閱讀或操作中的資料不應為了樣式而移動。裝飾性的滑鼠追蹤效果應屬於行銷頁面,而非銀行應用程式中的圖表。

3. 選擇工具——最便宜的可行者

向下檢查;停在第一個符合的選項。

需求工具
懸停、按壓、顏色、透過 class 或 attribute 控制的狀態切換CSS transition
掛載時的進場動畫,無 JS 狀態CSS @starting-style
當頁面忙於載入時,仍需保持流暢的預先決定動畫CSS animation(在主執行緒之外執行)
需要程式控制且具 CSS 效能,無需函式庫WAAPI (element.animate())
彈簧、佈局動畫、退出動畫、手勢驅動的值Motion (motion.dev)

在負載下,CSS 動畫優於 JS——它們在主執行緒之外執行,而基於 requestAnimationFrame 的動畫在瀏覽器載入、執行腳本或繪製時會掉幀。對預先決定的動作使用 CSS,對動態且可中斷的動作使用 JS。

如果任務需要的是元件而非動畫——例如 toast、抽屜、指令選單、下拉選單——請重用 @asym/ui 和 Base UI。除非使用者明確詢問要使用哪個函式庫,否則請不要呼叫 pick-ui-library。自己手動實作這些元件,最終會得到一個沒有焦點管理的 <div> 下拉選單。

4. 選擇屬性

  • 僅限 transform 和 opacity。 它們會跳過佈局和繪製,並在 GPU 上執行。width/height/margin/padding/top/left 會觸發所有三項。(clip-path 是第四個被認可的屬性——請參閱 RECIPES.md。height 僅在 accordion 中被容忍,因為沒有 transform 的等價替代。)
  • 永遠不要使用 scale(0)。 從 scale(0.9–0.97) + opacity: 0 開始。現實世界中沒有任何東西是從無到有出現的。
  • 在觸發點設定 transform-origin——適用於彈出視窗、下拉選單、選單、工具提示——在 Base UI 中使用 var(--transform-origin)。模態視窗不受此限;它們不錨定於觸發點,因此保持置中。
  • translate() 中的百分比是相對於元素自身大小——translateY(100%) 無論內容為何都會移動自身高度。偏好使用而非寫死的像素值。
  • 在 Motion 中,x、y 和 scale 是支援的獨立變換。 它們效能良好。僅在主執行緒忙碌時,才使用完整的 transform 字串來讓動畫保持在 compositor 上:
<motion.div animate={{ x: 100 }} />
<motion.div animate={{ transform: "translateX(100px)" }} />
  • 永遠不要從父元素的 CSS 變數驅動子元素的 transform——它會為每個子元素重新計算樣式。直接在元素上設定 transform。

5. 緩動曲線與持續時間——或彈簧

緩動曲線,按決策順序:

情況緩動曲線
進入或退出ease-out
在螢幕上移動 / 變形ease-in-out
懸停 / 顏色變更ease
恆定運動(跑馬燈、進度條)linear
預設ease-out

在 UI 上永遠不要使用 ease-in。 它開始緩慢,延遲了使用者正在觀看的確切時刻。200ms 的 ease-out 感覺比 200ms 的 ease-in 更快。

內建的 CSS 緩動曲線太弱了。請使用這些:

--ease-out-soft: cubic-bezier(
  0.22,
  1,
  0.36,
  1
); /* Core 令牌;適用於 UI 的強力 ease-out */
--ease-in-out-soft: cubic-bezier(
  0.77,
  0,
  0.175,
  1
); /* 適用於螢幕上移動的強力 ease-in-out */
--ease-drawer: cubic-bezier(
  0.32,
  0.72,
  0,
  1
); /* iOS 風格的抽屜曲線 (Ionic) */

需要此處沒有的曲線?從 easing.dev 或 easings.co 取得。不要手動建立一個。

持續時間:

元素持續時間
按鈕按壓反饋var(--duration-press) (120ms)
工具提示、小型彈出視窗var(--duration-micro) (150ms)
下拉選單、選擇框var(--duration-standard) (220ms)
模態視窗var(--duration-modal) (220ms)
抽屜var(--duration-drawer) (320ms)
行銷 / 說明性可以更長

UI 動畫保持在 300ms 以下。 一個 180ms 的下拉選單感覺比 400ms 的更靈敏。

改為使用彈簧,當動作是帶有動量的拖曳、應該感覺有生命力的元素、使用者可以中斷或反轉的手勢,或裝飾性的滑鼠追蹤時:

{ type: "spring", duration: 0.5, bounce: 0.2 }        // Apple 風格——更容易理解
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // 傳統物理——更多控制

將 bounce 保持在 0.1–0.3,並在大多數 UI 中避免使用 bounce——將其保留給拖曳關閉和趣味互動。

6. 中斷與退出

  • 對於快速觸發的任何事物,使用 transitions 而非 keyframes——toast、切換開關、任何使用者可以在一秒內觸發兩次的東西。Transitions 會從當前值重新定位目標;Keyframes 會從零重新開始。
  • 手勢使用彈簧,因為它們會在中斷時傳遞速度。
  • 以進入的方式退出。 一個從底部滑入的 toast 應該從底部離開。對稱路徑是讓滑動關閉感覺直覺的原因。
  • 在使用者決定時使用不對稱的時間。 在刻意階段慢(按住確認按壓:2s linear),在系統回應時快(釋放:200ms ease-out)。

7. 減少動畫與指標閘控

每次隨動畫一起交付。

@media (prefers-reduced-motion: reduce) {
  .element {
    animation: fade 0.2s ease;
  } /* 保留 opacity/color,移除基於 transform 的動畫 */
}

@media (hover: hover) and (pointer: fine) {
  .element:hover {
    transform: scale(1.05);
  } /* 觸碰會在點擊時觸發假的懸停 */
}
const reduce = useReducedMotion();
const closedX = reduce ? 0 : "-100%";

減少動畫意味著更少且更溫和的動畫,而非零——保留有助於理解的轉場,移除移動和位置變化。

配方

如需常見情境的現成實作——按鈕按壓、下拉選單、工具提示、模態視窗、抽屜、toast、accordion、stagger、按住確認、分頁指示器、滾動揭示、滑動關閉——請參閱 RECIPES.md。每當請求與這些元件之一相符時載入它;從配方而非空白檔案開始。

永不發佈

在完成之前自我檢查。以下每一項都是 review-animations 中的自動封鎖:

永不發佈應改為
transition: all命名確切的屬性
transform: scale(0) 進場scale(0.95) + opacity: 0
在 UI 元素上使用 ease-inease-out 或強力自訂曲線
在精心設計的動畫上使用內建 ease-outcubic-bezier(0.23, 1, 0.32, 1)
在鍵盤快捷鍵或每天 100+ 次的操作上加入動畫不要動畫
UI 持續時間超過 300ms 且無理由150–250ms
在錨定於觸發點的彈出視窗上使用 transform-origin: centervar(--transform-origin)(模態視窗不受此限)
在 toast、切換開關、快速觸發的元素上使用 KeyframesCSS transitions
對 width/height/margin/padding/top/left 加入動畫transform / opacity
在負載下使用 Motion 的 x/y/scale props完整的 transform 字串
未閘控的 :hover 動畫@media (hover: hover) and (pointer: fine)
缺少 prefers-reduced-motion更溫和的變體,而非零
所有東西同時進場30–80ms 的 stagger

輸出

撰寫程式碼。然後,最多用幾行:

  • 閘門結果——頻率層級和命名的目的。如果請求中的某物被拒絕,說明是哪個以及原因。
  • 要素——工具、屬性、曲線、持續時間或彈簧配置,各一行。
  • 需要感覺檢查的事項——如果結果取決於你無法從程式碼判斷的感覺(交叉淡入、彈簧的 bounce、正在進入的列表中的 opacity/height 平衡),請說明並指向檢查方法:以 2–5 倍持續時間播放或在 DevTools 動畫檢查器中播放、逐幀分析、在真實裝置上測試手勢,並再看一次。

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

Asymmetric-al/core

Build animations for Expo and React Native only, using Reanimated, Gesture Handler, Expo Router, and expo-haptics. Use when the target runtime is an Expo or React Native app. Do not use it for Core Next.js web motion; use `animate` for web. Only runs when explicitly invoked; it does not trigger on its own.

Asymmetric-al/core

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

Asymmetric-al/core

Inspect a Core UI or code surface for a small number of justified motion opportunities and explicitly identify what should remain static. Use when asked what should animate, where motion would improve feedback or comprehension, how to make an interface feel more alive without over-animating it, or whether a proposed animation is worth adding. Read-only; do not use to review or fix existing motion code or to implement animations.

Asymmetric-al/core

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

Asymmetric-al/core

Implement smooth, accessible animations with motion/react (Framer Motion) in React. Use when adding animations, gestures, or layout transitions with motion, AnimatePresence, useScroll, and related APIs. Requires a 'use client' boundary; not for strictly server-rendered components or when no animation is needed.

Asymmetric-al/core

Best practices for Remotion - Video creation in React

Asymmetric-al/core

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

相關技能