Communitygithub.com

運動基礎(Motion Foundations)

為 React / Next.js 使用 motion/react 定義動畫令牌、彈簧預設、效能規則、裝置適應、無障礙支援與 SSR 安全。所有其他運動技能皆依賴此基礎層。

運動基礎(Motion Foundations) 是什麼?

此技能為整個動畫系統的基礎層,定義所有值、約束與規則,供下游技能(如 motion-patterns、motion-advanced)繼承。支援 React 與 Next.js 專案,使用 motion/react 套件。核心產出包括共享的 motionTokens 物件(duration、easing、distance、scale)、5 個命名彈簧預設的 springs 對應表、以及一個 shouldAnimate() 閘門函數,用於控制何時允許動畫。此外,透過 useReducedMotion 鉤子與 CSS 媒體查詢實現無障礙動畫預設,並確保 SSR 初始狀態不產生水合警告,因為 initial 屬性必須與伺服器渲染結果完全一致。此技能強調動畫必須有明確目的(引導注意力、溝通狀態、保持空間連續性),同時遵循八條強制規則,例如只能使用 motion/react、禁止動畫佈局屬性、所有令牌值必須來自 motionTokens 等。它也提供決策指南,協助開發者選擇適當的持續時間與彈簧預設,並辨識應完全停用動畫的情境。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cody-W-Tucker/skills/tree/HEAD/skills/motion-foundations

在你喜歡的 AI 中提問

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

說明文件

運動基礎

動畫系統的基礎層。定義所有值、約束與規則,供下游技能 (motion-patterns、motion-advanced) 繼承。在開始任何動畫工作之前,請先載入此技能。

啟用時機

  • 從頭開始建立任何動畫元件
  • 設定令牌、彈簧預設或緩動值
  • 實作 prefers-reduced-motion 支援
  • 偵錯動畫初始狀態造成的水合不匹配
  • 評估某個動畫是否應該存在

產出

此技能產生:

  • 一個共享的 motionTokens 物件(duration、easing、distance、scale)
  • 一個共享的 springs 預設對應表(5 個命名的設定)
  • 一個 shouldAnimate() 閘門,供所有元件使用
  • 透過 useReducedMotion 達到無障礙合規的動畫預設
  • 零水合警告的 SSR 安全初始狀態

原則

動畫必須達成下列至少一項,否則應被移除:

  • 引導注意力
  • 溝通狀態
  • 保持空間連續性

回應速度永遠重於流暢度。一個造成輸入延遲的 60 fps 動畫,比完全沒有動畫更糟糕。

規則

這些是不可協商的。它們適用於系統中的每一個元件。

  1. 僅使用 motion/react。 絕不從 framer-motion 導入。絕不在同一個元件樹中混用兩者。
  2. initial 必須與伺服器輸出相符。 如果伺服器渲染 opacity: 1,initial 屬性也必須是 opacity: 1。沒有例外。
  3. 減少動畫覆蓋一切。 當 useReducedMotion() 傳回 true 或 prefersReduced 為 true 時,所有變形都會被停用。只有不透明度淡入淡出且持續時間 ≤ 0.2s 才是唯一允許的替代方案。
  4. 絕不動畫化佈局屬性。 禁止在 animate 中使用 width、height、top、left、margin、padding。僅可使用 transform 和 opacity。
  5. 所有令牌值皆來自 motionTokens。 禁止在元件檔案中寫死持續時間和緩動。
  6. 所有彈簧設定皆來自 springs 對應表。 禁止內聯使用 stiffness/damping 值。
  7. 每個從 motion/react 導入的檔案都必須加上 "use client"。
  8. 絕不在模組層級讀取 window 或 navigator。 務必使用 typeof window !== "undefined" 保護。

決策指南

選擇持續時間

令牌使用時機
instant提示框顯示/隱藏、焦點環、徽章更新
fast按鈕反饋、圖示切換、晶片切換
normal模態框開啟、卡片展開、頁面元素進入
slow英雄區進入、全頁面轉場
crawl刻意說故事;請節制使用

選擇彈簧

預設使用時機
snappy預設 UI — 按鈕、晶片、導覽項目
gentle卡片、模態框、面板輕柔落定
bouncy俏皮時刻 — 空狀態、入門引導
instant提示框、彈出視窗、下拉選單
release拖曳釋放 — 自然的物理感

何時完全停用動畫

在以下情況停用(讓 shouldAnimate() 傳回 false):

  • prefersReduced 為 true
  • isLowEnd 為 true 且動畫非必要
  • 元素在畫面外且永遠不會進入可視區域
  • 動畫純粹是裝飾性的,沒有 UX 目的

核心概念

令牌系統

// lib/motion-tokens.ts
export const motionTokens = {
  duration: {
    instant: 0.08,
    fast:    0.18,
    normal:  0.35,
    slow:    0.6,
    crawl:   1.0,
  },
  easing: {
    smooth: [0.22, 1, 0.36, 1],
    sharp:  [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    linear: [0, 0, 1, 1],
  },
  distance: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 48,
  },
  scale: {
    subtle: 0.98,
    press:  0.95,
    pop:    1.04,
  },
}

export const springs = {
  snappy:  { type: "spring", stiffness: 300, damping: 30 },
  gentle:  { type: "spring", stiffness: 120, damping: 14 },
  bouncy:  { type: "spring", stiffness: 400, damping: 10 },
  instant: { type: "spring", stiffness: 600, damping: 35 },
  release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}

執行時期旗標

// lib/motion-config.ts
export const motionConfig = {
  isLowEnd() {
    return (
      typeof navigator !== "undefined" &&
      navigator.hardwareConcurrency <= 4
    )
  },

  prefersReduced() {
    return (
      typeof window !== "undefined" &&
      window.matchMedia("(prefers-reduced-motion: reduce)").matches
    )
  },

  shouldAnimate({ essential = false } = {}) {
    if (this.prefersReduced()) return false
    if (!essential && this.isLowEnd()) return false
    return true
  },

  duration() {
    return this.isLowEnd() || this.prefersReduced()
      ? motionTokens.duration.instant
      : motionTokens.duration.normal
  },
}

無障礙

優先級順序(從高到低):

  1. prefers-reduced-motion: reduce — 停用所有變形,將不透明度過渡限制在 ≤ 0.2s
  2. 低階裝置偵測 — 縮短持續時間,移除非必要動畫
  3. 設計偏好 — 其他所有情況

動畫必須優雅降級。不能以導致佈局偏移或混淆方向的方式突然消失。

// hooks/use-reduced-motion.tsx
"use client"
import { useReducedMotion } from "motion/react"

export function useSafeMotion(fullY: number = 16) {
  const reduce = useReducedMotion()
  return {
    initial: { opacity: 0, y: reduce ? 0 : fullY },
    animate: { opacity: 1, y: 0 },
    exit:    { opacity: 0, y: reduce ? 0 : -fullY },
  }
}
/* globals.css */
@media (prefers-reduced-motion: reduce) {
  .motion-safe-transition  { transition: opacity 0.15s; }
  .motion-reduce-transform { transform: none !important; }
}
<!-- Tailwind -->
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>

SSR / 水合安全

規則:initial 必須始終與伺服器渲染的結果相符。

// 錯誤 — 伺服器渲染 opacity:1 但 initial 為 0 → 水合不匹配
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// 正確 — 使用 AnimatePresence 或延遲到客戶端掛載
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])

<motion.div
  initial={{ opacity: mounted ? 0 : 1 }}
  animate={{ opacity: 1 }}
/>

程式碼範例

端對端:令牌 + 彈簧 + 無障礙 + SSR 保護

// components/fade-in-card.tsx
"use client"

import { useState, useEffect } from "react"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
import { motionConfig } from "@/lib/motion-config"

interface FadeInCardProps {
  children: React.ReactNode
  delay?: number
}

export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {
  // SSR 保護 — initial 必須與伺服器輸出相符 (opacity: 1)
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])

  // 無障礙 — 當偏好減少動畫時停用變形
  const safeMotion = useSafeMotion(motionTokens.distance.md)

  // 裝置閘門 — 在低階硬體上跳過動畫
  if (!motionConfig.shouldAnimate() || !mounted) {
    return <div>{children}</div>
  }

  return (
    <motion.div
      initial={safeMotion.initial}
      animate={safeMotion.animate}
      exit={safeMotion.exit}
      transition={{
        ...springs.gentle,
        delay,
      }}
      whileHover={{ scale: motionTokens.scale.pop }}
      whileTap={{ scale: motionTokens.scale.press }}
    >
      {children}
    </motion.div>
  )
}

約束 / 非目標

此技能不涵蓋:

  • UI 元件模式(按鈕、模態框、階梯式)→ 請參閱 motion-patterns
  • 拖曳、手勢、SVG、文字動畫、自訂鉤子 → 請參閱 motion-advanced
  • 純 CSS 動畫或未使用 motion/react 的 Tailwind animate-* 類別
  • 第三方動畫函式庫(GSAP、anime.js 等)
  • 動畫設計決策(何時動畫、強調什麼)— 這是設計問題,非程式碼約束

反模式

反模式違反規則修正方法
import { motion } from "framer-motion"規則 1使用 motion/react
initial={{ opacity: 0 }} 在 SSR 元件上規則 2加入掛載保護
跳過 useReducedMotion 檢查規則 3使用 useSafeMotion 鉤子
animate={{ width: "100%" }}規則 4改用 scaleX 變形
內聯 transition={{ duration: 0.4 }}規則 5使用 motionTokens.duration.normal
內聯 { stiffness: 300, damping: 30 }規則 6使用 springs.snappy
缺少 "use client" 指令規則 7在檔案頂部加入
在模組層級使用 navigator.hardwareConcurrency規則 8包裹在 typeof navigator !== "undefined" 中

相關技能

  • motion-patterns — 使用此處定義的令牌和彈簧來建構按鈕、模態框、階梯式、頁面轉場和捲動模式。不會重新定義任何值。
  • motion-advanced — 使用此處定義的令牌和彈簧來處理拖曳、SVG、文字和手勢模式。在此基礎上加入 useAnimate 序列和自訂鉤子。

Individual skills in this repo

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

Cody-W-Tucker/skills

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says landing page, post-click experience, landing page audit, conversion rate, or landing page optimization.

Cody-W-Tucker/skills

TikTok Ads deep analysis covering creative quality, tracking, bidding, campaign structure, and TikTok Shop. Evaluates 28 checks with emphasis on creative-first strategy, safe zone compliance, and Smart+ campaigns. Use when user says TikTok Ads, TikTok marketing, TikTok Shop, Spark Ads, Smart+, or TikTok campaign.

Cody-W-Tucker/skills

YouTube Ads specific analysis covering campaign types, creative quality, audience targeting, and measurement. Evaluates video ad performance across skippable, non-skippable, bumper, Shorts, Demand Gen, and Connected TV formats. Covers VAC→Demand Gen migration, Shorts creative requirements, and CTV shoppable ads. Use when user says YouTube Ads, video ads, pre-roll, bumper ads, YouTube campaign, Shorts ads, or CTV ads.

Cody-W-Tucker/skills

Craft the story that makes investors say \"I want in.\" Master the narrative structure that Reid Hoffman, Sequoia, and top founders use to raise capital. Use when: **Preparing to fundraise** to develop your story before the deck; **Investor meetings** to structure conversations that convert; **Pitch practice** to refine your narrative arc; **Cold outreach** to write compelling investor emails; **Pivoting** to reframe your story after a change

Cody-W-Tucker/skills

Identify the best GTM motions and tools across 7 motion types: Inbound, Outbound, Paid Digital, Community, Partners, ABM, and PLG. Use when selecting marketing channels, choosing between inbound and outbound strategy, or planning cross-channel campaigns.

Cody-W-Tucker/skills

Produce a print-grade single-page kami (紙 / 纸) document — warm parchment canvas, ink-blue accent, serif at one weight, no italic, no cool grays. The output reads like a professional white paper or studio one-pager, not an app UI. Multilingual by design (EN · zh-CN · ja). One self-contained HTML file, zero dependencies.

Cody-W-Tucker/skills

Optimize landing pages for maximum conversions using proven frameworks from Unbounce and Oli Gardner—apply the \"one goal, one message, one action\" principle with data-driven design, copy, and CTA best practices. Use when: **Create a new landing page** for a campaign; **Optimize an existing landing page** that isn't converting; **Review landing page design** before launch; **Improve form conversion rates** on lead gen pages; **A/B test landing page elements** systematically

Cody-W-Tucker/skills

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

Cody-W-Tucker/skills

A single-frame motion-design composition with looping CSS animations — rotating type ring, animated globe, ticking timer, parallax labels. Renders as a hero video poster you can hand straight to HyperFrames or any keyframe-based exporter. Use when the brief asks for "motion design", "animated hero", "loop", "video poster", "title card", or pairs Open Claude Design with HyperFrames for a kinetic export.

Cody-W-Tucker/skills

Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs.

Cody-W-Tucker/skills

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

Cody-W-Tucker/skills

Produce a single-file slide deck in the Atelier Zero visual language (warm-paper background, italic-serif emphasis spans, coral terminating dots, surreal collage plates) — Open Design's brand deck recipe. The deck uses **horizontal magazine-style swipe pagination** (←/→, wheel, swipe), a per-slide chrome strip with brand mark and slide counter, an ESC overview grid, a coral progress bar, and inherits the canonical stylesheet + 16-slot image library from the sister `open-design-landing` skill.

Cody-W-Tucker/skills

Produce a world-class single-page editorial landing site in the Atelier Zero visual language (Monocle / Apartamento / Études editorial collage) — the same aesthetic Open Design uses for its own marketing surface. The agent fills a typed `inputs.json` from a brand brief, optionally generates 16 collage assets via gpt-image-2, then runs a pure-function composer that emits a self-contained HTML file; a separate path can mirror the Astro marketing site in `apps/landing-page/`. Drop-in scroll-reveal motion and a Headroom-style sticky nav are wired automatically.

Cody-W-Tucker/skills

Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D, animations, audio, captions, charts, transitions, and more.

Cody-W-Tucker/skills

Single-page SaaS landing with hero, features, social proof, pricing, and CTA. Respects the active DESIGN.md color/typography/layout tokens. Trigger keywords: "saas landing", "marketing page", "product landing".

Cody-W-Tucker/skills

Single-page SaaS landing with hero, features, social proof, pricing, and CTA. Respects the active DESIGN.md color/typography/layout tokens. Trigger keywords: "saas landing", "marketing page", "product landing".

Cody-W-Tucker/skills

Master April Dunford's 8-step sales narrative from \"Sales Pitch\" (2023). Transform your positioning into a compelling story that wins enterprise deals. Use when: Structuring B2B sales presentations and demos; Creating pitch decks for complex products; Training sales teams on narrative-driven selling; Converting positioning strategy into sales conversations; Winning against entrenched competitors

Cody-W-Tucker/skills

Swiss-style user-research narrative template in warm-paper editorial aesthetics. Use when users ask for a premium research deck or story-first live artifact with minimalist typography, high-clarity layout, subtle motion, donut breakdowns, and keyboard/click navigation across slides in a single HTML file.

Cody-W-Tucker/skills

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

Cody-W-Tucker/skills

Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.

相關技能