{
  "id": "motion-duration",
  "type": "foundation",
  "status": "published",
  "name": {
    "zh": "动效时长与缓动",
    "en": "Motion Duration & Easing"
  },
  "aliases": [
    "动效时长",
    "动画时长",
    "缓动曲线",
    "动画快慢",
    "动效快慢",
    "弹跳顺不顺",
    "easing",
    "duration and easing"
  ],
  "category": [
    "Motion",
    "Foundation"
  ],
  "description": {
    "zh": "动效时长是动画从开始到结束的时间，按交互类型分档：微反馈 100–150ms、标准过渡 200–300ms、强调入场 300–500ms。缓动决定加速减速的节奏，入场用 ease-out、退场用 ease-in。始终尊重 prefers-reduced-motion，把位移降级为淡入。",
    "en": "Motion duration is how long an animation runs: micro 100–150ms, standard 200–300ms, entrances 300–500ms. Ease out on entry; honour prefers-reduced-motion."
  },
  "use_when": [
    {
      "zh": "按钮、开关、卡片等元素的悬停、按下、状态切换",
      "en": "Hover, press and state changes on buttons, switches and cards"
    },
    {
      "zh": "弹层、抽屉、面板的入场与退场",
      "en": "Entrances and exits for popovers, drawers and panels"
    },
    {
      "zh": "需要统一全站动效节奏、避免每个组件各写一个时长",
      "en": "One motion rhythm for the whole product instead of per-component timing"
    }
  ],
  "avoid_when": [
    {
      "zh": "用户开启 prefers-reduced-motion（应降级为短淡入或无动画）",
      "en": "When the user enables prefers-reduced-motion — fall back to a short fade or none"
    },
    {
      "zh": "关键操作等待反馈，动画拖慢到让人觉得卡顿",
      "en": "Critical feedback slowed to the point of feeling laggy"
    },
    {
      "zh": "超过 500ms 的装饰性动画反复播放、抢占注意力",
      "en": "Decorative animations over 500ms looping and stealing attention"
    }
  ],
  "tags": [
    "motion",
    "foundation",
    "timing",
    "easing"
  ],
  "api": [
    "transition-duration",
    "transition-timing-function",
    "animation-duration",
    "cubic-bezier()",
    "prefers-reduced-motion"
  ],
  "framework_names": [
    {
      "framework": "Material Design",
      "name": "Duration & easing tokens",
      "url": "https://m3.material.io/styles/motion/overview",
      "note": {
        "zh": "分档时长与标准缓动令牌",
        "en": "Staged durations and standard easing tokens"
      }
    },
    {
      "framework": "Apple HIG",
      "name": "Motion",
      "url": "https://developer.apple.com/design/human-interface-guidelines/motion",
      "note": {
        "zh": "用动效表达层级与空间关系",
        "en": "Use motion to convey hierarchy and spatial relationships"
      }
    },
    {
      "framework": "CSS",
      "name": "transition-duration",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration",
      "note": {
        "zh": "直接控制过渡时长的属性",
        "en": "The property that controls transition length"
      }
    }
  ],
  "variants": [
    {
      "id": "micro",
      "name": {
        "zh": "微反馈",
        "en": "Micro feedback"
      },
      "note": {
        "zh": "100–150ms，点按、悬停要立刻可感知",
        "en": "100–150ms — presses and hovers must feel instant"
      }
    },
    {
      "id": "standard",
      "name": {
        "zh": "标准过渡",
        "en": "Standard"
      },
      "note": {
        "zh": "200–300ms，展开、切换、淡入淡出",
        "en": "200–300ms — expand, switch, cross-fade"
      }
    },
    {
      "id": "emphasized",
      "name": {
        "zh": "强调入场",
        "en": "Emphasised"
      },
      "note": {
        "zh": "300–500ms，页面与全屏浮层入场",
        "en": "300–500ms — page and full-screen overlay entrances"
      }
    }
  ],
  "anatomy": [
    "时长（Duration）",
    "缓动曲线（Easing curve）",
    "位移距离（Travel distance）",
    "减弱动效降级（Reduced-motion fallback）"
  ],
  "related": [
    {
      "id": "reduced-motion",
      "relation": "used_with"
    },
    {
      "id": "hover-lift",
      "relation": "used_with"
    },
    {
      "id": "page-transition",
      "relation": "used_with"
    },
    {
      "id": "press-feedback",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "motion-duration",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "Material Design — Motion",
      "url": "https://m3.material.io/styles/motion/overview"
    },
    {
      "name": "Apple HIG — Motion",
      "url": "https://developer.apple.com/design/human-interface-guidelines/motion"
    },
    {
      "name": "web.dev — Learn CSS Animations",
      "url": "https://web.dev/learn/css/animations"
    },
    {
      "name": "MDN — easing-function",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function"
    }
  ],
  "implementation": {
    "css": [
      "transition-duration: 200ms",
      "transition-timing-function: cubic-bezier(0.2, 0, 0, 1)",
      "animation-duration: 300ms",
      "@media (prefers-reduced-motion: reduce)",
      "transition-property: transform, opacity"
    ],
    "notes": {
      "zh": "时长按交互类型分档并用变量统一（--motion-fast: 120ms; --motion-base: 240ms; --motion-slow: 400ms）。入场用 ease-out 或 cubic-bezier(0.2, 0, 0, 1)，退场用 ease-in，并让退场比入场略快。只动 transform 与 opacity，避免触发 layout。媒体查询 prefers-reduced-motion: reduce 下把位移改成 opacity 淡入并压到 150ms 内，或直接 transition: none。",
      "en": "Stage durations as variables (--motion-fast: 120ms; --motion-base: 240ms; --motion-slow: 400ms) keyed to interaction type. Use ease-out or cubic-bezier(0.2, 0, 0, 1) for entrances, ease-in for exits, and make exits slightly faster than entrances. Animate transform and opacity only to avoid layout. Under prefers-reduced-motion: reduce, swap travel for an opacity fade capped at 150ms, or set transition: none."
    }
  },
  "prompts": {
    "basic": {
      "zh": "为项目定义统一的动效时长与缓动档位，让所有交互节奏一致。",
      "en": "Define one set of motion durations and easings so every interaction shares a rhythm."
    },
    "design": {
      "zh": "动效规范：微反馈 100–150ms，标准过渡 200–300ms，强调入场 300–500ms，退场比入场快约 20%；缓动入场 ease-out、退场 ease-in、标准用 cubic-bezier(0.2, 0, 0, 1)；同一元素只动 transform 与 opacity；用户开启 prefers-reduced-motion 时去掉位移，只保留 ≤150ms 的淡入。",
      "en": "Motion spec: micro feedback 100–150ms, standard transitions 200–300ms, emphasised entrances 300–500ms, exits about 20% faster than entrances; ease-out for entrances, ease-in for exits, cubic-bezier(0.2, 0, 0, 1) as the standard; animate transform and opacity only; under prefers-reduced-motion drop travel and keep only a fade of 150ms or less."
    },
    "implementation": {
      "zh": "用 CSS 变量分档：--motion-fast: 120ms; --motion-base: 240ms; --motion-slow: 400ms，缓动 --ease-standard: cubic-bezier(0.2, 0, 0, 1)。元素写 transition: transform var(--motion-base) var(--ease-standard), opacity var(--motion-base) var(--ease-standard)。用 @media (prefers-reduced-motion: reduce) 覆盖为短淡入或 transition: none。不要给所有属性加 transition: all。",
      "en": "Stage durations as CSS variables: --motion-fast: 120ms; --motion-base: 240ms; --motion-slow: 400ms, with --ease-standard: cubic-bezier(0.2, 0, 0, 1). Elements use transition: transform var(--motion-base) var(--ease-standard), opacity var(--motion-base) var(--ease-standard). Override with @media (prefers-reduced-motion: reduce) to a short fade or transition: none. Never use transition: all."
    },
    "agent": {
      "zh": "在当前项目中统一动效时长与缓动。\n先检查现有组件体系和 Design Token，优先复用当前组件。\n要求：\n- 定义快 / 标准 / 慢三档时长令牌与标准缓动曲线\n- 只动 transform 与 opacity，退场比入场略快\n- 在 prefers-reduced-motion 下把位移降级为短淡入或取消动画\n保持现有项目视觉风格。不要新增不必要依赖。\n沿用项目现有时长体系，避免逐组件各写一套。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Unify motion duration and easing in the current project.\nInspect the existing component system and design tokens first; reuse what is already there.\nRequirements:\n- Define fast / standard / slow duration tokens and a standard easing curve\n- Animate transform and opacity only; exits slightly faster than entrances\n- Under prefers-reduced-motion, demote travel to a short fade or drop animation\nKeep the project's existing visual style. Do not add unnecessary dependencies.\nReuse the existing timing system instead of per-component values.\nRun existing project checks when done and list the modified files."
    }
  }
}