🚀[기능개선][UI][애니메이션] 전체 애니메이션 개선 및 통일감 확보

[Cassiiopeia]

📝 현재 문제점

• 화면 전환 시 애니메이션이 딱딱하고 부자연스러움
• 모달/다이얼로그 등장 애니메이션이 어색함
• 스켈레톤 로딩 화면의 전환이 매끄럽지 않음
• 앱 전반의 애니메이션 스타일이 통일되지 않아 일관성 부족

🛠️ 해결 방안 / 제안 기능

• 토스앱 수준의 부드러운 애니메이션 적용
• 페이지 전환 애니메이션 자연스럽게 개선 (슬라이드, 페이드 등)
• 모달/다이얼로그 등장/퇴장 애니메이션 부드럽게 개선
• 스켈레톤 로딩 → 실제 콘텐츠 전환 시 shimmer 효과 및 fade-in 적용
• 앱 전반에 걸쳐 애니메이션 커브(easing), 지속 시간(duration) 통일

⚙️ 작업 내용

• 화면 전환 애니메이션 개선
• 모달 등장/퇴장 애니메이션 개선
• 스켈레톤 로딩 전환 애니메이션 개선
• 공통 애니메이션 상수(duration, curve) 정의 및 전체 적용

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: @Cassiiopeia
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260319_#689_전체_애니메이션_개선_및_통일감_확보

커밋 메시지

전체 애니메이션 개선 및 통일감 확보 : feat : {변경 사항에 대한 설명} https://github.com/TEAM-ROMROM/RomRom-FE/issues/689

[Cassiiopeia]

전체 애니메이션 개선 및 통일감 확보 - 현황 분석 보고서

---

1부: 토스 모션 철학 & 업계 모션 디자인 시스템 기준

---

📌 토스가 말하는 인터랙션의 본질

토스 기술 블로그와 디자인 시스템(TDS) 관련 글들을 종합하면, 토스의 인터랙션 철학은 다음과 같다.

핵심 원칙: "인터랙션은 장식이 아니라 제품 설계"

• 토스 인터랙션 디자이너의 역할은 "사용자가 앱을 더 편리하게 사용하도록 화면을 개선하고, 전반적인 인터랙션 퀄리티가 높아질 수 있도록 시스템을 만드는 일"
• 처음에는 팀 내부에서도 "구현이 어렵다", "애니메이션 빼고 가자", "공수 대비 임팩트가 있나" 같은 인식이 있었음
• 토스는 이를 단순 꾸밈이 아니라 사용자 경험 개선 수단으로 정립함

토스의 5가지 모션 원칙 (블로그/컨퍼런스 종합)

#	원칙	설명
1	이해를 돕는 움직임	모션의 목적은 "예쁨"이 아니라 사용자가 상태 변화를 쉽게 인지하도록 돕는 것
2	익숙한 패턴 우선	서랍형 달력 같은 새로운 인터랙션보다 탭 형태 같은 익숙한 UI가 사용량 약 4배 증가 사례
3	플로우 단위 통일	화면 하나가 아니라 전체 사용자 동선(플로우)의 리듬을 맞추는 것이 핵심
4	시스템화	TDS(Toss Design System)로 컴포넌트, 인터랙션, 애니메이션을 통합 관리
5	강한 인터랙션은 선택적	토스뱅크카드 같은 풍부한 인터랙션은 브랜드 임팩트가 필요한 핵심 순간에만 사용

토스의 실패 사례에서 배우는 것

• 서랍형 달력 UI: 아래로 끌어내리면 열리는 인터랙션 → 실제 사용자는 존재 자체를 인지 못함
• 해결: 더 익숙한 탭 UI로 변경 → 진입 인지도 크게 개선
• 교훈: "멋진 인터랙션" < "바로 알아보는 인터페이스"

토스뱅크카드 인터랙션 사례 (강한 인터랙션의 예)

• 처음 화면에서 카드를 빠르게 회전시켜 앞뒤 색이 다름을 즉시 알림
• 잡으면 회전이 멈추고, 놓으면 돌아가는 물리적 반응
• 매우 디테일한 튜닝이지만, 이런 수준은 핵심 브랜드 경험에만 선택적으로 적용

---

📌 업계 모션 디자인 시스템 기준 (Material, Fluent, Smashing Magazine 등)

Microsoft Fluent 2 - Motion Guidelines

"Motion in Fluent 2 experiences feels fluid and real by following physical laws such as inertia, gravity, weight and velocity, making animations more believable and predictable."

• 전환(Transitions)은 UI 모션 디자인의 핵심
• 물리 법칙(관성, 중력, 무게, 속도)을 따르면 자연스럽고 예측 가능

Smashing Magazine - "Including Animation In Your Design System"

"Animation is an important design tool for both UX and brand messaging. When it's not addressed in a design system, people either do whatever they want — leading to inconsistency — or don't use it at all."

• 디자인 시스템에서 애니메이션을 다루지 않으면 제각각이거나 아예 안 쓰게 됨
• 현재 RomRom 프로젝트가 정확히 이 상태

DesignSystems.com - "5 Steps for Including Motion in Your System"

• 모션은 디자인 시스템에 완벽히 맞는 요소: 반복성, 시간 절약, UX 일관성
• 모션을 제외하면 시스템의 목적 자체가 약해짐

Nielsen Norman Group & Material Design 공통 가이드

• 최적 UI 애니메이션 시간: 100~300ms (복잡한 움직임은 최대 500ms)
• "눈에 잡힐 만큼 길되, 흐름을 방해하지 않을 만큼 짧게"

---

2부: RomRom 프로젝트 현재 상태 분석

---

📌 프로젝트 구조 개요

lib/
├── screens/              # 11개 주요 화면
│   ├── home_tab_screen.dart
│   ├── chat_tab_screen.dart
│   ├── chat_room_screen.dart
│   ├── request_management_tab_screen.dart
│   ├── register_tab_screen.dart
│   ├── my_page_tab_screen.dart
│   ├── item_detail_description_screen.dart
│   ├── splash_screen.dart
│   ├── login_screen.dart
│   ├── notification_screen.dart
│   └── onboarding/
├── widgets/              # 60개 이상 위젯
│   ├── common/           # 공통 위젯 (modal, toggle, button 등)
│   ├── skeletons/        # 로딩 스켈레톤 (3개)
│   ├── flip_card_spin.dart
│   ├── home_tab_card_hand.dart (~600줄)
│   └── ... 기타
├── utils/
│   ├── common_utils.dart  # navigateTo() 확장 메서드
│   └── item_card_scale_utils.dart
└── models/
    ├── app_colors.dart
    └── app_theme.dart

---

📌 현재 애니메이션 사용 현황

A. 사용 중인 애니메이션 위젯

위젯	사용 여부	파일 수	주요 용도
AnimatedOpacity	O 사용	소수	스크롤 시 제목 페이드 (200ms)
AnimatedScale	O 사용	1개	카드 활성/비활성 (300ms)
AnimatedContainer	O 적극 사용	다수	상태 변경 전환
AnimatedBuilder	O 적극 사용	11개	수동 애니메이션 제어
AnimatedDefaultTextStyle	O 사용	1개	탭 선택 시 텍스트 색상 (300ms)
AnimationController	O 적극 사용	11개	수동 제어
TweenAnimationBuilder	X 미사용	-	-
Hero	X 미사용	-	페이지 간 공유 요소 전환 없음
AnimatedSwitcher	X 미사용	-	상태 변경 시 교체 애니메이션 없음
AnimatedCrossFade	X 미사용	-	-

B. 커스텀 애니메이션 위젯 (이미 존재)

위젯	파일	특징
FlipCardSpin	flip_card_spin.dart	3D 카드 회전 (회전 수, duration, curve 커스터마이징)
HomeTabCardHand	home_tab_card_hand.dart	복잡한 카드 덱: 궤도 회전, 드래그, 드롭존, AI 펄스
OnboardingProgressHeader	onboarding_progress_header.dart	프로그레스 바 (500ms, easeInOut)
RomRomContextMenu	romrom_context_menu.dart	오버레이 메뉴 (250ms, easeOutCubic)
ToggleSelector	toggle_selector.dart	2개 옵션 토글 (300ms, easeInOut)
TripleToggleSwitch	triple_toggle_switch.dart	3개 탭 토글 + 텍스트 색상 전환
RangeSliderWidget	range_slider_widget.dart	범위 슬라이더 (200ms, easeOutCubic)
GlassHeaderDelegate	glass_header_delegate.dart	스크롤 시 블러 강도 변화 (0→30 sigma)

C. 외부 패키지 현황

패키지	버전	용도
animated_toggle_switch	^0.8.5	토글 애니메이션
skeletonizer	^2.1.0+1	Shimmer 로딩 스켈레톤
flutter_screenutil	^5.9.3	반응형 UI

미사용 (도입 검토 필요):

• flutter_animate — 체이닝 방식 모션 (fade/slide/scale/stagger)
• animations — Material motion (SharedAxis, FadeThrough, ContainerTransform)
• lottie — 고급 애니메이션 (선택)

---

📌 현재 Duration & Curve 분포 (불일치 현황)

Duration 사용 빈도

Duration	사용 횟수	사용 위치
300ms	20회 (최다)	toggle, completion_button, 대부분 UI 전환
200ms	12회	scrollable_header, range_slider 등
500ms	6회	onboarding progress, 로그인 전환
400ms	2회	splash_screen
250ms	1회	context_menu
800ms	1회	fadeTransition (페이지 전환)
100~150ms	소수	매우 빠른 피드백
700~1400ms	극소수	특수 애니메이션

문제: 100ms~1400ms까지 14단계 이상으로 분산. 기준 없이 각자 설정한 상태.

Curve 사용 빈도

Curve	사용 횟수	특징
easeInOut	20회 (최다)	일반적인 흐름
easeOut	6회	빠른 끝남
easeOutCubic	4회	부드러운 감속
fastOutSlowIn	1회	빠른 시작 + 느린 끝
easeInCubic	1회	느린 시작
linear	1회	일정 속도

문제: 6종류 Curve가 혼용. 같은 성격의 애니메이션인데도 다른 Curve 사용.

---

📌 페이지 전환 방식 현황

NavigationTypes (context.navigateTo)

타입	구현	전환 애니메이션	사용 화면
push	CupertinoPageRoute(iOS) / MaterialPageRoute(Android)	플랫폼 기본 슬라이드	대부분의 상세 화면
pushReplacement	동일	동일	화면 교체
pushAndRemoveUntil	동일	동일	스택 정리 후 이동
fadeTransition	PageRouteBuilder + FadeTransition	800ms fade (역방향 300ms)	스플래시→로그인, 업데이트 화면
clearStackImmediate	PageRouteBuilder (전환 없음)	전환 애니메이션 없음 (즉시 표시)	로그인 후 메인 진입

문제점:

• ❌ fadeTransition 800ms는 너무 느림 (업계 기준 300~400ms 권장)
• ❌ clearStackImmediate는 전환 없이 즉시 교체 → 딱딱함의 원인
• ❌ SlideTransition, ScaleTransition, SharedAxisTransition 등 미구현
• ❌ 탭 전환(BottomNavigation) 시 별도 전환 애니메이션 없음
• ❌ 모달/바텀시트 기본 시스템 애니메이션만 사용

---

📌 버튼/카드 터치 반응 현황

패턴 1: InkWell 기반 (가장 많음)

Material > InkWell(highlightColor: darkenBlend(), splashColor: darkenBlend().withAlpha(0.3))

• darkenBlend(): 배경색에 20% 검은색 혼합
• 사용 파일: common_modal.dart, completion_button.dart, custom_floating_button.dart 등
• 문제: ripple 효과만 존재. 눌림 스케일 반응 없음

패턴 2: GestureDetector (일부)

• 사용 파일: triple_toggle_switch.dart, range_slider_widget.dart
• 문제: 시각적 눌림 피드백 없이 onTap만 처리

패턴 3: AnimatedScale (극소수)

• 사용 파일: request_management_item_card_widget.dart (1개만)
• 비활성화 시 0.85배 축소 (300ms)
• 다른 카드/버튼에는 적용 안 됨

종합 문제:

• ❌ 공통 Pressable 위젯 없음 → 버튼마다 반응이 다름
• ❌ 대부분 InkWell ripple만 사용 → 토스 느낌과 거리 멀음
• ❌ 눌림 시 scale down → spring back 패턴 전혀 없음
• ❌ 카드 터치 시 시각적 피드백 불일치

---

📌 로딩 상태 처리 현황

Skeletonizer 사용 (3개 화면)

파일	용도
register_tab_skeleton.dart	내 물품 목록 로딩
채팅 목록 스켈레톤	채팅 리스트 로딩
등록 폼 스켈레톤	등록 화면 로딩

구현 방식:

Skeletonizer(
  enabled: true,
  effect: ShimmerEffect(baseColor: AppColors.opacity10White, highlightColor: AppColors.opacity30White),
  child: ...
)

CircularProgressIndicator 사용 (나머지)

• completion_button.dart: 버튼 내 로딩 인디케이터
• login_button.dart: 전체 화면 로딩 다이얼로그

문제점:

• ❌ 스켈레톤이 있는 화면은 3개뿐 → 나머지 화면은 로딩 시 빈 화면 또는 스피너만 표시
• ❌ 스켈레톤 → 실제 데이터 전환 시 페이드 애니메이션 없음 (즉시 교체)
• ❌ 홈 탭, 알림, 상세 화면 등에 스켈레톤 미적용

---

📌 모달/바텀시트 현황

CommonModal

• showDialog() 래퍼, 3개 팩토리: success(), error(), confirm()
• 고정 너비 312.w, InkWell 기반 버튼
• 문제: 시스템 기본 showDialog 애니메이션만 사용. 커스텀 진입 모션 없음

showModalBottomSheet

• 1개 파일에서만 사용 (register_input_form.dart)
• 문제: 시스템 기본 애니메이션만 사용

CommonSnackBar

• 다중 토스트 관리 (최대 3개 동시)
• animationController.reverse() 사용
• 상대적으로 양호

---

3부: 앱 UI 모션/전환 표준안

---

📌 우리 앱의 모션 톤앤매너

"빠르고 부드럽되 과장되지 않게, 모든 요소가 같은 리듬으로 반응하는 앱."

또는 더 쉽게:

"갑자기 뜨지 않고, 눌렀을 때 살아 있고, 화면이 끊기지 않는 앱."

---

📌 4가지 기본 원칙

원칙 1. "갑자기 나타나지 않는다"

새로운 정보, 카드, 배너, 문구는 살짝 올라오면서 자연스럽게 선명해지는 방식으로 보여준다.

• 느낌: "툭 뜨는 게 아니라 스르륵 보인다"
• 구현 감각: opacity 0→1 + y offset 816 아래에서 시작 + 180260ms + 부드러운 감속 curve

원칙 2. "누르면 바로 반응한다"

버튼, 카드, 리스트 아이템은 누르는 순간 "눌렸다"는 감각이 즉시 전달되어야 한다.

• 느낌: "딱딱한 클릭이 아니라 손에 닿는 느낌"
• 구현 감각: 누르는 순간 살짝 작아짐(0.96~0.97) → 떼면 spring back

원칙 3. "바뀔 때 연결감이 있다"

탭 변경, 필터 변경, 로딩 완료, 화면 이동은 기존 상태에서 다음 상태로 이어지는 느낌이어야 한다.

• 느낌: "화면이 교체되는 게 아니라 상태가 이어진다"
• 구현 감각: AnimatedSwitcher, FadeThrough, SharedAxis 등 전환 위젯 활용

원칙 4. "모든 움직임은 절제된다"

토스 느낌은 애니메이션이 많은 것이 아니라 짧고, 정리되어 있고, 통일되어 있는 것에 가깝다.

• 느낌: "보이게 애니메이션"보다 "느껴지게 애니메이션"
• 기준: 사용자가 "애니메이션이 많네"가 아니라 "왜인지 완성도가 높아졌다"로 느끼는 수준

---

📌 모션 토큰 정의 (Duration & Curve 통일 기준)

Duration 표준

토큰명	값	용도
instant	100ms	터치 피드백, 즉각 반응
fast	200ms	기본 UI 전환, 스크롤 반응
normal	300ms	카드/리스트 등장, 상태 변경
slow	400ms	페이지 전환, 모달 등장
emphasis	500ms	온보딩, 특수 진입

기존 800ms fadeTransition → 400ms로 단축 필요

Curve 표준

토큰명	Curve	용도
standard	easeInOut	일반적인 상태 변화
entry	easeOut	등장/진입 (빠르게 시작, 부드럽게 끝남)
decelerate	easeOutCubic	감속 (물리적 자연스러움)
spring	Spring simulation	버튼 눌림 복귀 (탄성)

---

📌 컴포넌트별 표준

1. 버튼 (모든 종류)

항목	표준
눌림 반응	scale 1.0 → 0.97 (기본 버튼) / 0.985 (카드) / 0.93~0.95 (아이콘 버튼)
복귀	spring 느낌 (직선 복귀 금지)
반응 시간	즉시 (100ms 이내 시작)
기존 ripple	유지하되 scale 반응이 primary
공통 위젯	AppPressable 하나로 통일

2. 카드 / 리스트 아이템

항목	표준
등장	fade + slide up (offset 816, 200300ms, easeOut)
리스트 stagger	아이템 간 20~40ms 시차
터치 반응	scale 0.985 + spring back
공통 위젯	AppFadeSlideIn

3. 탭 / 필터 / 카테고리 전환

항목	표준
전환 방식	Fade Through (기존 내용 사라지고 새 내용 나타남)
Duration	300ms
금지	즉시 교체, 방향 없는 전환

4. 페이지 전환

전환 유형	표준 방식	Duration
탭 간 전환 (BottomNav)	Fade Through	300ms
리스트 → 상세	Shared Axis (수평) 또는 약한 Slide	300~400ms
모달 / 바텀시트	아래에서 올라오기 + 내용 살짝 늦은 fade in	300ms
뒤로가기	들어갈 때의 반대 방향	300ms
로그인 → 메인	Fade (즉시 교체 금지)	400ms

5. 로딩 / 스켈레톤

항목	표준
모든 데이터 로딩 화면	Skeletonizer 스켈레톤 필수
shimmer 톤	기존 AppColors.opacity10White / opacity30White 유지 (통일)
스켈레톤 → 실제 데이터	fade 전환 (200~300ms)
CircularProgressIndicator	버튼 내부 로딩에만 사용. 전체 화면 로딩에는 스켈레톤

6. 모달 / 바텀시트

항목	표준
등장	아래에서 부드럽게 올라옴 + 배경 dim
내부 콘텐츠	시트보다 약간 늦게 fade in
닫힘	역방향으로 자연스럽게 내려감
bounce	과도한 bounce 금지

7. 빈 상태 / 안내 화면

항목	표준
등장	아이콘 + 문구 + CTA가 fade + slide up으로 자연스럽게 등장
느낌	"없음"이 아니라 "다음 행동을 제안하는 상태"

---

📌 통일성 금지 규칙 (절대 하면 안 되는 것)

#	금지 사항
1	화면마다 다른 페이지 전환 방식 사용
2	버튼마다 다른 눌림 반응 (어떤 건 ripple, 어떤 건 무반응, 어떤 건 scale)
3	리스트 전체가 동시에 팍 나타나는 것
4	로딩 시 빈 화면 또는 스피너만 보여주는 것 (스켈레톤 없이)
5	Duration이 500ms를 넘는 일반 UI 전환
6	너무 큰 bounce/scale (0.9 미만 축소, 1.05 초과 확대)
7	모든 요소가 동시에 움직이는 과한 연출
8	shimmer, shadow, scale이 동시에 과하게 들어가는 것

---

4부: 개선 우선순위 & 필요 작업 목록

---

📌 우선 적용 순서

1순위: 공통 모션 인프라 구축

작업	설명	체감
모션 토큰 상수 파일 생성	Duration, Curve를 앱 전역 상수로 정의	기반
AppPressable 위젯 생성	모든 버튼/카드/행 클릭의 공통 눌림 반응	★★★★★
AppFadeSlideIn 위젯 생성	모든 진입용 fade + slide up	★★★★☆

2순위: 버튼/카드 반응 통일 (가장 체감 큼)

작업	대상
모든 InkWell 버튼에 AppPressable 적용	공통 모달 버튼, 완료 버튼, 플로팅 버튼 등
모든 카드에 눌림 피드백 적용	홈 카드, 요청 관리 카드, 채팅 리스트 아이템 등

3순위: 로딩 스켈레톤 확대

작업	대상
홈 탭 스켈레톤 추가	home_tab_screen
알림 화면 스켈레톤 추가	notification_screen
상세 화면 스켈레톤 추가	item_detail_description_screen
스켈레톤 → 데이터 전환에 fade 적용	모든 스켈레톤 사용 화면

4순위: 리스트/카드 진입 애니메이션

작업	대상
리스트 아이템에 stagger 진입 적용	홈 피드, 채팅 목록, 알림 목록 등
카드 등장에 AppFadeSlideIn 적용	모든 카드형 위젯

5순위: 페이지 전환 규칙 통일

작업	대상
fadeTransition Duration 800ms → 400ms 단축	common_utils.dart
clearStackImmediate에 fade 전환 추가	common_utils.dart
탭 전환에 FadeThrough 적용	BottomNavigation
상세 진입에 SharedAxis 적용	리스트 → 상세 전환

6순위: 상태 변화 전환

작업	대상
탭/필터 변경에 AnimatedSwitcher 적용	카테고리 전환, 필터 변경
로딩→데이터, empty→content에 fade 전환	모든 상태 변화 지점

---

📌 만들어야 할 공통 위젯 4개

위젯	역할	핵심
AppPressable	모든 탭 가능 요소의 공통 눌림 반응	scale down + spring back
AppFadeSlideIn	모든 진입용 fade + slide up	opacity + offset + stagger 지원
AppPageTransition	화면 전환 규칙 통일	탭/상세/모달별 타입 구분
AppSkeleton	로딩 시 스켈레톤 통일	Skeletonizer 래퍼 + fade 전환

---

📌 기획 체크리스트 (화면 검수용)

모든 화면에 대해 아래를 검수:

• 이 화면의 버튼은 눌림 반응(AppPressable)이 있는가?
• 이 화면의 카드/리스트는 눌림 반응이 있는가?
• 이 화면에서 데이터 로딩 시 스켈레톤이 표시되는가?
• 스켈레톤에서 실제 데이터로 전환 시 fade가 있는가?
• 리스트 아이템이 stagger로 등장하는가? (동시에 팍 뜨지 않는가?)
• 이 화면으로 진입하는 전환이 규칙에 맞는가? (탭: FadeThrough / 상세: SharedAxis)
• 이 화면에서 뒤로가기 시 진입의 역방향인가?
• 탭/필터 변경 시 내용이 자연스럽게 교체되는가? (즉시 교체가 아닌가?)
• 빈 상태 화면에서 안내가 자연스럽게 등장하는가?
• 모달/바텀시트가 아래에서 부드럽게 올라오는가?

---

📌 화면별 현재 상태 & 개선 필요 사항

화면	눌림 반응	진입 모션	스켈레톤	전환 방식	상태 변화	판정
홈 탭	InkWell만	❌ 없음	❌ 없음	탭 기본	❌ 즉시 교체	개선 필요
채팅 탭	InkWell만	❌ 없음	✅ 있음	탭 기본	❌ 즉시 교체	개선 필요
채팅방	InkWell만	❌ 없음	❌ 없음	push 기본	-	개선 필요
요청 관리 탭	AnimatedScale ✅	❌ 부분적	❌ 없음	탭 기본	❌ 즉시 교체	부분 개선
등록 탭	InkWell만	❌ 없음	✅ 있음	탭 기본	❌ 즉시 교체	개선 필요
마이페이지 탭	InkWell만	❌ 없음	❌ 없음	탭 기본	❌ 즉시 교체	개선 필요
상세 화면	InkWell만	❌ 없음	❌ 없음	push 기본	-	개선 필요
스플래시	-	✅ AlignmentTween	-	fade 800ms	-	Duration 조정
로그인	InkWell만	✅ 부분적	❌ 없음	clearStackImmediate	-	전환 개선
알림	InkWell만	❌ 없음	❌ 없음	push 기본	-	개선 필요
온보딩	-	✅ 프로그레스바	-	push 기본	-	양호

---

5부: 한 줄 요약

현재 상태: Duration 14단계 분산, Curve 6종 혼용, 공통 Pressable 없음, 스켈레톤 3화면만, 페이지 전환 규칙 없음

목표: 모션 토큰 통일 → 공통 위젯 4개 생성 → 전 화면 순차 적용

토스 기준으로 핵심: "화려한 애니메이션 추가"가 아니라 "버튼 반응 / 등장 방식 / 로딩 방식 / 페이지 전환 방식을 전부 공통 규칙으로 묶는 것"

---

참고 출처:

• 토스 기술 블로그 - Design
• 토스 디자인 시스템 가이드 개선
• 디자인 시스템 다시 생각해보기
• 토스 디자이너가 제품에만 집중할 수 있는 방법
• Microsoft Fluent 2 - Motion
• Smashing Magazine - Including Animation In Your Design System
• DesignSystems.com - 5 Steps for Motion
• Flutter - Introduction to Animations

[Cassiiopeia]

@wheemin1 현재 상황 공유드립니다

[Cassiiopeia]

@suh-lab app build

[Cassiiopeia]

전체 애니메이션 개선 및 통일감 확보

이슈: #689

---

📌 작업 개요

앱 전반의 애니메이션이 Duration 14단계 분산, Curve 6종 혼용, 공통 Pressable 없음, 스켈레톤 3개 화면만 적용 등 일관성이 전혀 없던 상태를 개선. 모션 토큰 시스템 도입 → 공통 위젯 4개 신규 생성 → 전 화면 순차 적용 방식으로 토스앱 수준의 통일된 인터랙션 품질 달성.

---

🎯 구현 목표

• Duration/Curve 하드코딩 제거 → 모션 토큰으로 통일
• 공통 눌림 반응 위젯(AppPressable) 도입으로 버튼/카드 터치 피드백 통일
• 공통 등장 애니메이션 위젯(AppFadeSlideIn) 도입으로 리스트/카드 진입 stagger 통일
• 공통 스켈레톤 래퍼(AppSkeleton) 도입으로 로딩→콘텐츠 전환 fade 통일
• 페이지 전환 규칙 정립 및 모달 등장 애니메이션 개선

---

✅ 구현 내용

1. 모션 토큰 시스템 구축 (신규)

• 파일: lib/models/app_motion.dart
• 변경 내용: Duration 5단계(instant/fast/normal/slow/emphasis) + Curve 4종(standard/entry/decelerate/springOut) + stagger 기본값(staggerDelayMs: 30) 상수 정의
• 이유: 기존 100ms~1400ms 14단계 분산, 6종 Curve 혼용을 단일 파일로 관리하여 앱 전역 모션 톤앤매너 통일

토큰	값	용도
instant	100ms	터치 피드백
fast	200ms	기본 UI 전환
normal	300ms	카드/리스트 등장, 상태 변경
slow	400ms	페이지 전환, 모달 등장
emphasis	500ms	온보딩, 특수 진입
standard	easeInOut	일반 상태 변화
entry	easeOut	등장/진입
decelerate	easeOutCubic	감속
springOut	ElasticOutCurve(0.5)	버튼 눌림 복귀

---

2. 공통 위젯 4개 신규 생성

AppPressable (lib/widgets/common/app_pressable.dart)

모든 버튼/카드/리스트 아이템의 터치 반응을 통일하는 공통 래퍼 위젯.

• 누르는 순간 즉각 scale down (setState 직접 적용, 애니메이션 없음 — 토스 스타일: 즉각 반응)
• 떼는 순간 SpringSimulation 물리 기반 복귀 (damping ratio < 1.0 → underdamped, 살짝 bounce)
• scaleButton(0.97) / scaleCard(0.985) / scaleIcon(0.93) 3단계 상수 제공
• enableRipple 파라미터로 InkWell ripple 선택적 유지 가능
• Spring 파라미터: 버튼/카드 stiffness:300, damping:20 (ratio≈0.65), 아이콘 stiffness:300, damping:30 (ratio≈0.87)

버그 수정 1: enableRipple: false일 때 외부 GestureDetector(onTapDown/Up)와 내부 GestureDetector(onTap) 이중 구조로 이벤트가 소비되어 onTap이 전달 안 되는 문제 수정 → 외부 GestureDetector에 onTap 직접 연결, 내부 중복 GestureDetector 제거

버그 수정 2: register_tab_screen.dart 등록하기 FAB에서 Container(child: AppPressable(...)) 구조로 인해 노란 배경 Container는 scale되지 않고 내부 텍스트/아이콘만 scale되는 문제 수정 → AppPressable(child: Container(...)) 구조로 교체하여 버튼 전체가 scale되도록 변경

AppFadeSlideIn (lib/widgets/common/app_fade_slide_in.dart)

모든 진입 요소의 등장 방식을 통일하는 위젯.

• opacity 0→1 + Offset(0, slideOffset)→Offset.zero 슬라이드
• delay 파라미터로 리스트 stagger 지원 (기본 AppMotion.staggerDelayMs: 30ms)
• 기본: AppMotion.normal 300ms, AppMotion.entry curve

AppSkeleton (lib/widgets/common/app_skeleton.dart)

로딩 상태와 실제 콘텐츠 간 전환을 fade로 처리하는 래퍼 위젯.

• AnimatedSwitcher 기반, 스켈레톤↔콘텐츠 AppMotion.fast 200ms fade 전환
• shimmer 색상 통일: baseColor: opacity10White, highlightColor: opacity30White
• ValueKey로 switcher 키 충돌 방지

스켈레톤 위젯 1개 신규 (lib/widgets/skeletons/)

• NotificationListSkeleton: 알림 아이템(원형 아이콘 + 텍스트 2줄) 반복 구조 shimmer
• HomeTabSkeleton: 초기 구현 후 단순화 → 최종적으로 홈탭은 CircularProgressIndicator(primaryYellow)로 교체
  • 이유: 홈탭 구조가 전체 화면 카드+카드덱 레이어드 레이아웃이라 스켈레톤이 오히려 혼란스러워 단순 스피너가 더 자연스러움

---

3. 페이지 전환 규칙 개선 (lib/utils/common_utils.dart)

전환 타입	기존	개선 후
fadeTransition	800ms fade	AppMotion.slow 400ms fade
clearStackImmediate	즉시 교체 (애니메이션 없음)	AppMotion.slow 400ms fade 전환 추가
fadePush	300ms/250ms 하드코딩	AppMotion.normal/fast 토큰 적용
slideUp	미구현	신규 추가 — 아래에서 위로 슬라이드
sharedAxisHorizontal	미구현	신규 추가 — Material SharedAxisTransition 수평

animations 패키지 (^2.0.0) pubspec.yaml에 추가.

---

4. 모달 등장 애니메이션 개선 (lib/widgets/common/common_modal.dart)

기존 showDialog() → showGeneralDialog()로 교체하여 커스텀 transitionBuilder 적용.

• 등장: FadeTransition + ScaleTransition (0.92→1.0, AppMotion.decelerate curve)
• 모달 버튼: Material + InkWell → AppPressable + Container로 교체

---

5. 탭 전환 애니메이션 (lib/screens/main_screen.dart)

BottomNavigationBar 탭 전환 시 기존 즉시 교체 → AnimatedSwitcher + FadeTransition 적용.

• KeyedSubtree(key: ValueKey<int>(_currentTabIndex))로 탭별 키 부여
• AppMotion.normal 300ms, AppMotion.entry curve

---

6. 리스트 stagger 진입 애니메이션

화면	적용 위젯	stagger
chat_tab_screen.dart	채팅방 리스트 아이템	index * AppMotion.staggerDelayMs
notification_screen.dart	알림 아이템	index * AppMotion.staggerDelayMs

---

7. 스켈레톤 로딩 확대

화면	기존	개선 후
홈 탭	CircularProgressIndicator	CircularProgressIndicator (primaryYellow, strokeWidth:2)
알림 화면	CircularProgressIndicator	AppSkeleton + NotificationListSkeleton

---

8. Duration/Curve 토큰 전역 교체 (15개 파일)

기존 하드코딩된 Duration(milliseconds: N), Curves.xxx → AppMotion.* 토큰으로 일괄 교체.

파일	주요 변경
toggle_selector.dart	300ms → AppMotion.normal, easeInOut → AppMotion.standard
range_slider_widget.dart	200ms → AppMotion.fast, easeOutCubic → AppMotion.decelerate
triple_toggle_switch.dart	300ms → AppMotion.normal
glass_header_delegate.dart	200ms → AppMotion.fast
scrollable_header.dart	200ms → AppMotion.fast
common_snack_bar.dart	300ms → AppMotion.normal
request_management_item_card_widget.dart	300ms → AppMotion.normal
register_tab_screen.dart	Duration 토큰 적용
request_management_tab_screen.dart	Duration 토큰 적용
onboarding_flow_screen.dart	500ms → AppMotion.emphasis
chat_room_screen.dart	Duration 토큰 적용
splash_screen.dart	400ms → AppMotion.slow
romrom_context_menu.dart	250ms → AppMotion.fast, easeOutCubic → AppMotion.decelerate
completed_toggle_switch.dart	Duration 토큰 적용
notification_screen.dart	300ms → AppMotion.normal

---

9. AppPressable 전수 적용 — 앱 전체 인터랙티브 요소

파일	적용 요소	scale
custom_bottom_navigation_bar.dart	네비게이션 탭 아이템	scaleIcon (0.93)
my_page_tab_screen.dart	닉네임 박스, 모든 메뉴 아이템	scaleCard (0.985)
register_tab_screen.dart	등록하기 FAB, 등록된 물건 리스트 아이템	scaleButton / scaleCard (0.97/0.985)
request_management_tab_screen.dart	카드 캐러셀	scaleCard (0.985)
request_list_item_card_widget.dart	받은 요청 카드 콘텐츠 영역 (메뉴 버튼 제외)	scaleCard (0.985)
sent_request_item_card.dart	보낸 요청 카드 전체 (메뉴 버튼 Positioned 분리)	scaleCard (0.985)
login_button.dart	소셜 로그인 버튼	scaleButton (0.97)
home_feed_item_widget.dart	피드 이미지, 프로필 아바타	scaleCard / scaleIcon
home_feed_ai_sort_button.dart	AI 분석 버튼	scaleButton (0.97)
home_tab_screen.dart	알림 아이콘, 등록 버튼, 새로고침 버튼	scaleIcon / scaleButton
common_app_bar.dart	뒤로가기 아이콘	scaleIcon (0.93)
onboarding_progress_header.dart	뒤로가기 아이콘	scaleIcon (0.93)
chat_input_bar.dart	전송 버튼	scaleIcon (0.93)
notification_screen.dart	헤더 아이콘 3개 (뒤로가기/삭제/설정)	scaleIcon (0.93)
completion_button.dart	완료 버튼	scaleButton (0.97)
custom_floating_button.dart	플로팅 버튼	scaleButton (0.97)
chat_room_list_item.dart	채팅방 리스트 아이템	scaleCard (0.985)
notification_item_widget.dart	알림 아이템	scaleCard (0.985)
common_modal.dart	모달 버튼	scaleButton (0.97)

---

🔧 AppPressable 사용 기준

scaleDown 선택 기준

상수	값	적용 대상
scaleButton	0.97	버튼 (FAB, 로그인, 완료, 새로고침 등 전형적인 버튼 형태)
scaleCard	0.985	카드 / 리스트 아이템 (면적이 넓은 터치 영역)
scaleIcon	0.93	아이콘 버튼 (뒤로가기, 알림, 전송 등 소형 터치 영역)

enableRipple 선택 기준

값	적용 상황
true (기본)	밝은 배경 위 버튼처럼 ripple이 시각적으로 자연스러울 때
false	어두운 배경, 이미지 위, 카드/아이콘처럼 ripple이 어색할 때 → 대부분 이 값 사용

적용하지 않는 대상

• Toggle/Slider: ToggleSelector, RangeSliderWidget, TripleToggleSwitch 등 드래그/슬라이딩 인터랙션 위젯 — 누름 scale이 아니라 슬라이드로 상태 변경하므로 제외
• 코치마크 오버레이: 페이지 인디케이터 등 UX 상 scale 반응이 어색한 요소
• 이미지 뷰어 셀: chat_image_bubble.dart 등 갤러리 뷰어 내부 셀 — Hero 애니메이션과 충돌 가능

컨텍스트 메뉴(…) 버튼이 있는 카드의 구조

카드 내에 (…) 컨텍스트 메뉴 버튼이 있을 때, 메뉴 버튼을 누르면 카드 전체가 scale down되어서는 안 됨.

패턴	구조	사용 위젯
Row 분리	Row([Expanded(AppPressable(content)), Column(menu)])	RequestListItemCardWidget — 메뉴를 Row의 형제로 분리
Positioned 분리	AppPressable 전체 감싸기, 메뉴는 Stack > Positioned로 별도 레이어	SentRequestItemCard, register_tab_screen._buildItemTile — Positioned 위젯은 자체 GestureDetector로 이벤트를 먼저 소비

두 패턴 모두 메뉴 버튼 탭이 카드 AppPressable에 전파되지 않아 카드 scale 없이 메뉴만 동작.

---

📦 의존성 변경

# pubspec.yaml
animations: ^2.0.0  # Material SharedAxisTransition, FadeThrough 사용

---

🧪 테스트 및 검증

• dart format --line-length=120 . 통과
• flutter analyze — No issues found

---

📌 참고사항

• AppPressable에서 enableRipple: true일 때 외부 GestureDetector + 내부 InkWell 이중 구조 — scale 애니메이션과 ripple이 동시에 동작
• enableRipple: false일 때 외부 GestureDetector 단일 구조 — onTap/onLongPress를 외부 GestureDetector에서 직접 처리 (내부 중복 GestureDetector 없음)
• AppSkeleton이 이미 Skeletonizer로 감싸므로 내부 스켈레톤 위젯에서 Skeletonizer 중복 사용 금지 — Skeleton.leaf로 개별 요소만 명시
• clearStackImmediate에 fade 추가로 로그인→메인 진입 시 딱딱한 즉시 교체 해소
• Timer/async 딜레이 용도의 Duration은 모션 토큰으로 교체하지 않음 (애니메이션 duration이 아니므로)
• Spring 파라미터 튜닝 기준: damping ratio = damping / (2 × √(mass × stiffness)). 1.0 미만이면 bounce 발생. 버튼은 0.65(살짝 bounce), 아이콘은 0.87(안정적)

[github-actions]

🤖 ✅ Android APK 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	2분 12초
🔨 APK 빌드	✅ 완료	4분 15초
📤 GitHub 아티팩트 업로드	✅ 완료	5초
🔥 Firebase App Distribution	✅ 완료	20초

📦 빌드 결과

항목	값
앱 버전	1.9.105(68901)
브랜치	20260319_#689_전체_애니메이션_개선_및_통일감_확보
커밋	5a0cb12
총 소요 시간	6분 53초

🔥 Firebase App Tester 앱에서 설치 가능합니다
📦 아티팩트 다운로드
🔗 워크플로우 실행 로그

[github-actions]

🍎 ✅ iOS TestFlight 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	2분 17초
🔨 IPA 빌드	✅ 완료	6분 54초
📤 TestFlight 배포	✅ 완료	7분 48초

📦 빌드 결과

항목	값
앱 버전	1.9.105(68901)
브랜치	20260319_#689_전체_애니메이션_개선_및_통일감_확보
커밋	5a0cb12
총 소요 시간	16분 59초

📱 TestFlight에서 테스트 앱을 다운로드할 수 있습니다.
🔗 워크플로우 실행 로그