Communitygithub.com

EliasOulkadi/shokunin

使用 Web 動畫 API (WAAPI)、滾輪驅動動畫 (ScrollTimeline/ViewTimeline)、FLIP 技術、緩動系統與無障礙設計 (prefers-reduced-motion) 來設計 GPU 加速的動畫。當使用者要求為網頁 UI 建立動畫、轉場、滾輪效果、頁面轉換或互動式動態效果時使用。請勿用於基於畫布的動畫 (Three.js、PixiJS)、影片編輯或非網頁 (原生行動裝置) 動態設計。

shokunin 是什麼?

此技能提供了一個全面且基於原則的框架,用於在網頁 UI 中建立高性能、易於存取且具有明確溝通意圖的動畫。它不僅是程式碼範例的集合,更是一套嚴謹的決策系統,指導開發者判斷何時不該使用動畫、如何為動畫設定明確目的、選擇正確的緩動曲線與時機,以及透過 `transform` 和 `opacity` 這類僅觸發合成(composite)的屬性來維持 60fps 的流暢度。該技能支援多種平台與技術,包括純 CSS 轉場與關鍵影格動畫、Web Animations API (WAAPI)、基於 Frammer Motion 的彈簧動畫、FLIP 技術以及最新的滾輪驅動動畫 (ScrollTimeline/ViewTimeline),並提供對應的跨瀏覽器備援方案。其獨特之處在於整合了 Emil Kowalski 等頂尖設計師的實戰經驗,提供了從按鈕微回饋、工具提示、彈出視窗到手持刪除模式等常見 UI 元件的具體實作模式。此外,它強制要求使用固定的審查格式(「Before/After/Why」表格)來確保動畫程式碼的品質,並將 `prefers-reduced-motion` 無障礙支援視為必要條件,全面提升了動畫在實際產品中的實用性與專業性。

相容平台~Claude Code~Codex CLI✓Cursor✓OpenCode
npx skills add https://github.com/EliasOulkadi/shokunin/tree/HEAD/.pack/skills/motion-craft

在你喜歡的 AI 中提問

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

說明文件

Motion Craft

具有溝通意圖的動畫,而非裝飾。每一幀都必須有其存在的價值。

靈感來自 Emil Kowalski (Linear, Sonner, Vaul)、Paul Lewis (Google Chrome) 和 CSS Animation Working Group。

工作流程

動畫決策框架

在撰寫任何動畫程式碼之前,請依序回答以下四個問題。

1. 這個元素需要動畫嗎?

頻率決策理由
每天 100 次以上 (鍵盤快捷鍵、命令面板、搜尋切換)永遠不要有動畫。動畫會讓頻繁的操作感覺延遲。Raycast 沒有開啟/關閉動畫,這是最佳做法。
每天數十次 (懸停效果、列表導航)移除或大幅減少使用者在重複互動時會注意到動畫延遲
偶爾發生 (模态框、抽屜、訊息提示)使用標準動畫這是運用動畫的正確時機
罕見 / 首次 (引導、確認、慶祝)加入令人愉悅的效果這些時刻值得更長、更豐富的動畫

永遠不要為鍵盤啟動的動作加上動畫。 這些動作每天會重複數百次。

2. 動畫的目的是什麼?

每個動畫都必須清楚回答「為什麼要動?」這個問題。

目的範例有效?
空間一致性訊息提示從同一方向進入和退出?
狀態指示按鈕變形以顯示「已傳送」?
回饋按鈕在按下時縮小,確認介面接收到了使用者的操作?
防止突兀的變化元素淡入而不是突然出現?
解釋展示功能如何運作的說明動畫?
「看起來很酷」而且使用者經常看到不必要的動畫?

3. 應該使用什麼緩動曲線?

情境緩動曲線CSS
元素進入ease-out (起步快速,感覺反應靈敏)cubic-bezier(0, 0, 0.2, 1)
元素退出ease-in (起步緩慢,短暫吸引注意力後加速離開)cubic-bezier(0.4, 0, 1, 1)
螢幕上的移動 / 變形ease-in-outcubic-bezier(0.4, 0, 0.2, 1)
懸停 / 顏色變化easecubic-bezier(0.25, 0.1, 0.25, 1)
持續運動 (跑馬燈、進度條)linearcubic-bezier(0, 0, 1, 1)
UI 互動 (按鈕、工具提示、下拉選單)強 ease-outcubic-bezier(0.23, 1, 0.32, 1)

關鍵:絕對不要對 UI 進入動畫使用 ease-in。 一個使用 ease-in、持續 300ms 的下拉選單,感覺起來比使用 ease-out、同樣 300ms 的下拉選單更慢,這是因為 ease-in 延遲了初始移動——而此時正是使用者視線最集中的時刻。

4. 動畫應該多快?

元素持續時間緩動曲線
按鈕按壓回饋 (縮放)100-160mscubic-bezier(0.23, 1, 0.32, 1)
工具提示進入 / 退出125-200mscubic-bezier(0.23, 1, 0.32, 1)
下拉選單 / 選擇器 / 彈出視窗150-250mscubic-bezier(0.23, 1, 0.32, 1)
懸停變換 (縮放、浮起)200mscubic-bezier(0.23, 1, 0.32, 1)
模态框 / 對話框進入200-300mscubic-bezier(0, 0, 0.2, 1)
模态框 / 對話框退出150-200mscubic-bezier(0.4, 0, 1, 1)
抽屜 / 面板進入200-400mscubic-bezier(0.32, 0.72, 0, 1) (類似 iOS)
訊息提示進入300-400mscubic-bezier(0.23, 1, 0.32, 1)
訊息提示退出200-300mscubic-bezier(0.4, 0, 1, 1)
頁面切換300-400mscubic-bezier(0.4, 0, 0.2, 1)
滾動揭示 (淡入 + 上滑)400-800mscubic-bezier(0.16, 1, 0.3, 1)
載入閃爍效果1000-1500ms (無限循環)linear
按住刪除 (按壓)2000mslinear (刻意緩慢)
按住刪除 (放開)200mscubic-bezier(0.23, 1, 0.32, 1) (乾脆俐落)
行銷 / 解說800-3000ms可變,取決於敘事節奏

規則:UI 動畫持續時間應保持在 300ms 以下。 一個 180ms 的下拉選單感覺起來明顯比 400ms 的更加靈敏。

自訂緩動曲線

內建的 CSS ease / ease-in / ease-out 效果太弱。請使用這些更強烈的自訂變體:

:root {
  --ease-out-strong: cubic-bezier(0.23, 1, 0.32, 1);     /* UI 互動,Emil 的招牌曲線 */
  --ease-in-out-strong: cubic-bezier(0.77, 0, 0.175, 1);  /* 螢幕上的移動 */
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);          /* 類似 iOS 的抽屜 */
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);         /* 緩慢揭示,戲劇效果 */
  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);       /* 替代的強 ease-out */
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);       /* 略微過衝,謹慎使用 */
}

資料來源:easing.dev, easings.co


60fps 黃金法則

每幀 16.67ms。使用 Chrome DevTools Performance 標籤頁進行驗證。僅對 transform 和 opacity 進行動畫處理。

屬性GPU 合成?觸發項
transform (translate, scale, rotate)? 是僅合成 (Composite only)
opacity? 是僅合成 (Composite only)
filter?? 有時繪製 (Paint) + 合成 (Composite)
clip-path?? 有時繪製 (Paint) + 合成 (Composite)
width, height, top, left, margin, padding, border-width? 否佈局 (Layout) + 繪製 (Paint) + 合成 (Composite)
box-shadow? 否繪製 (Paint) + 合成 (Composite)
color, background-color? 否僅繪製 (Paint only)

審查格式 (必要)

審查 UI 動畫程式碼時,你必須使用包含 Before | After | Why 欄位的 markdown 表格。不要使用在不同行中分別列出「Before:」和「After:」的清單。

正確格式:

BeforeAfterWhy
transition: all 300mstransition: transform 200ms ease-out指定確切屬性;避免使用 all,它會觸發佈局重新計算
transform: scale(0)transform: scale(0.95); opacity: 0現實世界中沒有任何東西是從無到有的
對下拉選單使用 ease-incubic-bezier(0.23, 1, 0.32, 1)ease-in 起步緩慢——感覺遲鈍。強 ease-out 則提供即時回饋
按鈕沒有 :active 狀態在 :active 時使用 transform: scale(0.97)按鈕必須對按壓動作感到反應靈敏
在彈出視窗上使用 transform-origin: centertransform-origin: var(--radix-popover-content-transform-origin)彈出視窗應從其觸發元素處縮放。模态框則保持置中。
沒有 prefers-reduced-motion 的 transition: 300ms@media (prefers-reduced-motion: reduce) { transition-duration: 0.01ms }WCAG 2.1 要求支援減少動畫
Framer Motion 中的 animate={{ x: 100 }}animate={{ transform: "translateX(100px)" }}Framer Motion 的 x/y 不是硬體加速的。請使用 transform 字串以利用 GPU。

錯誤格式 (永遠不要這樣做):

Before: transition: all 300ms
After: transition: transform 200ms ease-out

CSS 轉場 (UI 的首選)

CSS 轉場是可中斷的——它們可以在動畫進行中重新設定目標。而關鍵影格動畫則會從零重新啟動。對於任何可能快速觸發的互動(訊息提示、切換開關、下拉選單),使用轉場可以產生更流暢的效果。

.button {
  transition: transform 160ms ease-out;
}
.button:active {
  transform: scale(0.97);
}

.tooltip {
  transition: transform 125ms ease-out, opacity 125ms ease-out;
  transform-origin: var(--transform-origin);
}

不對稱的進入 / 退出時機

進入可以較慢(使用者在決定),退出則必須快速(系統在回應):

.overlay {
  transition: clip-path 200ms ease-out;  /* 釋放:快速 */
}
.button:active .overlay {
  transition: clip-path 2s linear;       /* 按壓:緩慢而刻意 */
}

工具提示:在後續懸停時跳過延遲

.tooltip {
  transition: transform 125ms ease-out, opacity 125ms ease-out;
  transform-origin: var(--transform-origin);
}
.tooltip[data-instant] {
  transition-duration: 0ms;
}

使用 @starting-style 的進入狀態 (截至 2026 年僅 Chrome 支援,尚未成為 Baseline)

.toast {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 400ms ease-out, transform 400ms ease-out;

  @starting-style {
    opacity: 0;
    transform: translateY(100%);
  }
}

注意:@starting-style 和滾輪驅動動畫 (animation-timeline: view(), animation-timeline: scroll()) 截至 2026 年僅 Chrome 支援。對於 Firefox/Safari,請使用 JavaScript 的備援方案以實現跨瀏覽器相容性。

按住刪除模式

.overlay {
  clip-path: inset(0 100% 0 0);
  transition: clip-path 200ms ease-out;   /* 釋放:快速 */
}
.button:active .overlay {
  clip-path: inset(0 0 0 0);
  transition: clip-path 2s linear;        /* 按壓:緩慢而刻意 */
}

按鈕 - 觸覺回饋

每個可按壓的元素都需要物理反應。

.button {
  transition: transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
}
.button:active {
  transform: scale(0.97);
}

縮放比例必須細微 (0.95-0.98)。應用於所有可按壓的元素——按鈕、卡片、列表項目、標籤頁。


彈出視窗 - 原點感知

彈出視窗從其觸發元素處縮放,而非中心。模态框則保持置中。

/* Radix UI */
.popover {
  transform-origin: var(--radix-popover-content-transform-origin);
}
/* Base UI */
.popover {
  transform-origin: var(--transform-origin);
}
/* Modals (始終置中) */
.modal {
  transform-origin: center;
}

使用者是否個別注意到並不重要。總體而言,未被注意到的細節會產生疊加效應。


錯開動畫

當多個元素同時進入時,需錯開它們的出現時間。

.item {
  opacity: 0;
  transform: translateY(8px);
  animation: fadeIn 300ms ease-out forwards;
}
.item:nth-child(1) { animation-delay: 0ms; }
.item:nth-child(2) { animation-delay: 50ms; }
.item:nth-child(3) { animation-delay: 100ms; }
.item:nth-child(4) { animation-delay: 150ms; }

@keyframes fadeIn {
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

保持錯開延遲時間短暫(項目之間 30-80ms)。在錯開動畫播放時,絕不能阻止互動。


CSS 動畫 (關鍵影格)

用於預先確定、非動態的動畫。關鍵影格動畫在被打斷時會從零重新啟動——避免用於 UI。

@keyframes enter-right {
  from { opacity: 0; transform: translateX(16px); }
  to   { opacity: 1; transform: translateX(0); }
}
.enter {
  animation: enter-right 300ms ease-out forwards;
}

彈簧動畫

由於模擬真實物理效果,彈簧動畫感覺比基於持續時間的動畫更自然。它們在被打斷時能保持速度。

何時使用彈簧動畫

  • 具有動量的拖曳互動
  • 感覺「栩栩如生」的元素 (Apple Dynamic Island 風格)
  • 可在動畫進行中被打斷的手勢操作
  • 裝飾性的滑鼠追蹤互動

Apple 方法 (推薦 - 更容易理解)

{ type: "spring", duration: 0.5, bounce: 0.2 }

傳統物理模型 (更多控制)

{ type: "spring", stiffness: 100, damping: 10, mass: 1 }

保持反彈輕微 (0.1-0.3)。在大多數 UI 中避免反彈。僅在拖曳關閉和有趣的互動中使用。

基於彈簧的滑鼠互動

import { useSpring } from 'framer-motion'

const springX = useSpring(mouseX * 0.1, { stiffness: 100, damping: 10 })

沒有彈簧:感覺不自然、即時生效。有彈簧:感覺自然、具有動量。


WEB 動畫 API (WAAPI)

程式化的 CSS 動畫。硬體加速、可中斷、無需依賴庫。

const element = document.querySelector('.card')

const animation = element.animate([
  { transform: 'scale(1)', opacity: 1 },
  { transform: 'scale(0.95)', opacity: 0.7 },
], {
  duration: 200,
  easing: 'cubic-bezier(0.23, 1, 0.32, 1)',
  fill: 'both',
})

animation.pause()
animation.play()
animation.reverse()
animation.finish()
animation.finished.then(() => console.log('done'))

WAAPI 在重負載下勝過 Framer Motion——它在主執行緒之外運行。在 CSS 關鍵影格效果不足時,用於動態、可中斷的動畫。


滾輪驅動動畫

瀏覽器支援說明: 滾輪驅動動畫 (animation-timeline: view() 和 scroll()) 截至 2026 年僅 Chrome/Edge 支援,尚未成為 Baseline。對於 Firefox/Safari,請透過 IntersectionObserver 提供 JS 備援方案。

ViewTimeline (元素進入/離開視口)

@keyframes fade-up {
  from { opacity: 0; transform: translateY(20px); }
  to   { opacity: 1; transform: translateY(0); }
}
.reveal {
  animation: fade-up 600ms linear both;
  animation-timeline: view();
  animation-range: entry 0% entry 100%;
}

ScrollTimeline (頁面滾輪位置)

@keyframes shrink {
  from { height: 80px; }
  to   { height: 50px; }
}
.site-header {
  animation: shrink 300ms linear both;
  animation-timeline: scroll();
  animation-range: 0 200px;
}

滾輪連動視差 (純 JS)

const layers = document.querySelectorAll('[data-parallax]')
window.addEventListener('scroll', () => {
  const scrollY = window.scrollY
  layers.forEach(layer => {
    const speed = parseFloat(layer.dataset.parallax) || 0.3
    layer.style.transform = `translateY(${scrollY * speed}px)`
  })
})

FLIP 技術

用於佈局動畫——動畫化那些改變位置/大小的元素。

function animateLayout(element, callback) {
  const first = element.getBoundingClientRect()
  callback()
  const last = element.getBoundingClientRect()

  const dx = first.left - last.left
  const dy = first.top - last.top
  const dw = first.width / last.width
  const dh = first.height / last.height

  element.animate([
    { transform: `translate(${dx}px, ${dy}px) scale(${dw}, ${dh})` },
    { transform: 'translate(0, 0) scale(1, 1)' },
  ], {
    duration: 300,
    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
  })
}

CLIP-PATH 動畫

CSS 中最強大的動畫工具之一。硬體加速。

.overlay {
  clip-path: inset(0 100% 0 0);
  transition: clip-path 200ms ease-out;
}
.visible {
  clip-path: inset(0 0 0 0);
}

用於:按住刪除、滾輪揭示圖片、比較滑桿、標籤頁的無縫顏色過渡。


感知效能

動畫的速度直接影響

…

[為翻譯而截斷]

Individual skills in this repo

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

相關技能