建構動畫
此儲存庫 (Asymmetric-al/core)
在 Core 的設計工程與操作動畫合約之後,使用此技能來實作網頁動畫。在上游更新後,先調和此覆蓋層再執行 bun run skills:sync。
觸發條件
- 建構或重寫網頁動畫、轉場或微互動。
- 請勿用於 Expo/React Native (
animate-expo)、程式碼審查 (improve-animations) 或嚴格的純動畫評論 (review-animations)。
工作流程
- 首先載入
docs/ai/skills/emil-design-engineering/SKILL.md和docs/ai/skills/anim/SKILL.md。 - 重用現有的 Core 動畫令牌和 Base UI 基本元件。請勿分支持續時間、緩動曲線或引入 Radix API。
- 在
packages/ui/styles/globals.css中,將減少動畫保持在全局基線。 - 如果任務需要 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 所執行的標準相同。撰寫程式碼時,要使其能一次性通過該審查。
兩種失敗模式,第一種更糟:
- 對不該有動畫的事物加入動畫。 下方的閘門有時會產生零行程式碼。這是成功,而非逃避。
- 使用錯誤的要素為正確的事物加入動畫——在進場動畫中使用
ease-in、scale(0)、在 toast 上使用關鍵幀、或是讓下拉選單感覺遲緩的持續時間。
切勿將動畫選項呈現為選單。做出決定,用一句話說明理由,然後撰寫程式碼。
嚴格規則
- 依序執行序列。 步驟 1 和 2 是所有事情的閘門。在知道是否要加入動畫之前,不要急著選擇曲線。
- 不使用近似值。 每個曲線、持續時間和彈簧配置都來自下方的表格。切勿因為
cubic-bezier(0.4, 0, 0.2, 1)看起來很熟悉就擅自使用。 - 擴展程式碼庫的令牌,而非分支它們。 如果
--ease-out-soft或持續時間令牌已存在於packages/ui/styles/globals.css中,請使用它。加入平行系統是種缺陷。 - 減少動畫和懸停閘控會隨動畫一起交付,而不是事後才補上。
- 使用最便宜的可行工具。 不要為了淡入效果而安裝動畫函式庫。
建構序列
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-in | ease-out 或強力自訂曲線 |
在精心設計的動畫上使用內建 ease-out | cubic-bezier(0.23, 1, 0.32, 1) |
| 在鍵盤快捷鍵或每天 100+ 次的操作上加入動畫 | 不要動畫 |
| UI 持續時間超過 300ms 且無理由 | 150–250ms |
在錨定於觸發點的彈出視窗上使用 transform-origin: center | var(--transform-origin)(模態視窗不受此限) |
| 在 toast、切換開關、快速觸發的元素上使用 Keyframes | CSS 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 動畫檢查器中播放、逐幀分析、在真實裝置上測試手勢,並再看一次。