모션

원칙

• 변화를 설명할 때만 움직이세요. 모션은 무엇이 어디서 오고 어디로 갔는지 보여 주므로 바운스는 넣지 마세요. 반복 재생은 작업이 도는 동안의 진행 표시만 씁니다.
• 전환은 짧게 하세요. 이 시스템의 전환은 120–360ms이고, 대화상자와 토스트는 바로 닫힙니다.
• 입력을 기다리게 하지 마세요. 포커스, 상태, 결과는 바로 바뀌고 모션은 그 뒤를 따를 뿐입니다.
• 테마는 한 장면으로 바꾸세요. 화면 전체가 함께 페이드되므로 테두리나 아이콘이 뒤처지지 않습니다.
• 모션 줄이기 설정을 따르세요. prefers-reduced-motion에서는 움직임이 멈추고 모든 경로는 그대로 동작합니다(WCAG 2.3.3).

모션 토큰

밀리초를 직접 쓰지 말고 이 토큰을 쓰세요. 값은 현재 테마에서 바로 읽어 옵니다.

모션 줄이기는 컴포넌트 전환을 끄지만 이 값은 그대로 둡니다.

컴포넌트 전환

컴포넌트마다 등장 시간이 다르고, 닫을 때는 기다리게 하지 않습니다. Sheet와 Drawer는 어디로 가는지가 중요하므로 양쪽 모두 슬라이드합니다.

공유 Dialog와 Sheet를 열고, 열린 상태에서 테마를 바꿔 보세요. 초안과 포커스가 그대로 남습니다.

Toast와 Drawer는 스와이프, 시간, 일시 정지를 직접 관리하므로 타이머로 다시 만들지 마세요. 결과를 transitionend에 맞춰 알리지 마세요.

테마 전환

transitionTheme은 테마 속성과 프레임워크 상태를 한 번에 바꿉니다. View Transitions를 지원하면 새 화면이 --surf-theme-transition-duration 동안 이전 화면 위로 페이드됩니다. 지원하지 않으면 바로 적용됩니다.

• 적용된 테마:
• 모션 줄이기: 설정 없음
• View Transitions API: 사용 불가

import { flushSync } from 'react-dom'
import { transitionTheme } from '@surflane/design-tokens/theme-transition'
// @surflane/ui/all.css brings it; with per-component stylesheets, import it once.
import '@surflane/design-tokens/motion.css'

// Resolve system mode before committing the theme.
await transitionTheme(() => {
  document.documentElement.dataset.theme = resolvedTheme
  flushSync(() => setMode(nextMode))
})

사용자 동작마다 한 번만 부르고, 따로 타이머를 두지 마세요. 테마를 고르고 저장하고 복원하는 방법은 테마에서 다룹니다.

모션 줄이기

• prefers-reduced-motion에서는 대화상자, 패널, 테마가 움직임 없이 바뀝니다.
• 열기, 닫기, 포커스 복귀, 알림은 모션을 기다리지 않으므로 똑같이 동작합니다.
• 자동 스크롤처럼 5초 넘게 움직이는 모션에는 일시 정지 컨트롤을 두세요(WCAG 2.2.2). 1초에 3번 넘게 깜박이게 하지 마세요(WCAG 2.3.1).

W3C C39 — prefers-reduced-motion / Base UI — 애니메이션 수명 주기

이징 랩

지속 시간은 전체 시간이고, 이징은 그 시간에 진행을 나눕니다. 곡선의 가로축은 시간, 세로축은 진행률입니다.

linear, 모션 미리보기 켜짐

cubic-bezier(x1, y1, x2, y2)를 읽을 때는 곡선에서 시간 x를 찾고 그 점의 y를 진행률로 보세요. 기울기가 가파를수록 빠르게 바뀝니다.

이 시스템의 곡선은 오버슈트하지 않습니다. 600ms는 느린 미리보기이고 기본값이 아닙니다.

W3C CSS Easing Functions / Web Animations

관련 문서

• 인터랙션 상태 — 컨트롤이 호버, 누름, 포커스, 선택, 대기 상태를 보여 주는 방식을 정합니다.
• 테마 — 페이지나 영역에 라이트나 다크를 적용하고, 직접 테마를 만듭니다.
• 접근성 — 모든 화면이 지킬 WCAG 2.2 AA 기준을 정합니다.
• Dialog — 전체 주의가 필요한 독립 작업을 엽니다.