Communitygithub.com

Cody-W-Tucker/skills

Motion tokens、spring预设、性能规则、设备适配、无障碍强制策略以及SSR安全,用于React / Next.js,基于motion/react。基础层——所有其他运动技能都依赖于它。

skills 是什么?

这是一个面向React / Next.js项目的运动动画基础层技能,定义了整个动画系统中所有可用的值、约束和规则。核心内容包括:一个统一的 `motionTokens` 对象(涵盖持续时间、缓动函数、位移距离和缩放比例)、一个包含5个命名配置的 `springs` 预设映射、一个供所有组件使用的 `shouldAnimate()` 入口函数、基于 `useReducedMotion` 的无障碍动画默认值,以及能够消除水合警告的SSR安全初始状态。该技能强制规定了八条不可协商的规则,例如必须使用 `motion/react` 而不是 `framer-motion`、`initial` 属性必须与服务器渲染输出一致、`prefers-reduced-motion` 优先于一切、禁止动画化 `width`/`height` 等布局属性、所有token和spring配置都只能从中心化映射中引用。此外还提供了设备能力检测(例如低端设备)和运行时配置,以根据硬件和用户偏好优雅地降级动画。本技能不涵盖具体UI组件模式、拖拽手势、文本动画或第三方库——这些内容由下游技能(如 `motion-patterns` 和 `motion-advanced`)承担。

兼容平台~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)继承的值、约束和规则。在任何动画工作开始之前,请先加载此技能。

何时激活

  • 从头开始创建任何动画组件时
  • 设置 tokens、spring 预设或缓动值时
  • 实现 prefers-reduced-motion 支持时
  • 调试由动画初始状态引起的水合不匹配时
  • 评估某个动画是否应该存在时

输出

本技能产生:

  • 一个共享的 motionTokens 对象(持续时间、缓动函数、位移距离、缩放比例)
  • 一个共享的 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. 永远不要动画化布局属性。 width、height、top、left、margin、padding 禁止在 animate 中使用。仅使用 transform 和 opacity。
  5. 所有 token 值都来自 motionTokens。 禁止在组件文件中硬编码持续时间和缓动函数。
  6. 所有 spring 配置都来自 springs 映射。 禁止内联 stiffness/damping 值。
  7. 每个导入 motion/react 的文件都需要 "use client"。
  8. 永远不要在模块级别读取 window 或 navigator。 始终使用 typeof window !== "undefined" 进行保护。

决策指南

选择持续时间

Token使用时机
instant工具提示显隐、焦点环、徽章更新
fast按钮反馈、图标切换、标签切换
normal模态框打开、卡片展开、页面元素入场
slow英雄区域入场、全页面过渡
crawl刻意叙事;谨慎使用

选择 Spring

预设使用时机
snappy默认 UI — 按钮、标签、导航项
gentle卡片、模态框、面板柔和着陆
bouncy有趣时刻 — 空状态、引导页
instant工具提示、弹出框、下拉菜单
release拖拽释放 — 自然物理感受

何时完全禁用动画

当以下情况时禁用(使 shouldAnimate() 返回 false):

  • prefersReduced 为 true
  • isLowEnd 为 true 且动画非必需
  • 元素在屏幕外且永远不会进入视口
  • 动画纯粹是装饰性的,没有 UX 目的

核心概念

Token 系统

// 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 说 opacity: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 }}
/>

代码示例

端到端:tokens + springs + 无障碍 + 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、文本动画、自定义 hooks → 参见 motion-advanced
  • 纯 CSS 动画或不使用 motion/react 的 Tailwind animate-* 类
  • 第三方动画库(GSAP、anime.js 等)
  • 运动设计决策(何时动画化、强调什么)— 这是设计关注点,而非代码约束

反模式

反模式违反的规则修复方式
import { motion } from "framer-motion"规则 1使用 motion/react
在 SSR 组件上使用 initial={{ opacity: 0 }}规则 2添加挂载守卫
跳过 useReducedMotion 检查规则 3使用 useSafeMotion hook
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 — 使用在此定义的 tokens 和 springs 构建按钮、模态框、交错、页面过渡和滚动模式。不重新定义任何值。
  • motion-advanced — 使用在此定义的 tokens 和 springs 实现拖拽、SVG、文本和手势模式。在此基础上增加 useAnimate 序列和自定义 hooks。

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.

相关技能