Communitygithub.com

flutter-motion-ui

빌드된 애니메이션과 상태를 함께 설계하는 고급스러운 Flutter UI를 만듭니다. 페이지 전환, Hero/공유 요소 애니메이션, 리퀴드-글래스 네비게이션 바, 계단식 등장 애니메이션, 바텀 시트 확인, 슬라이드 투 컨펌, OTP 및 다단계 인증 플로우, 변형 버튼(로딩→성공), 롤링 숫자, 리스트 애니메이션, 실시간 추적 화면, 테마 전환 등을 포함합니다.

flutter-motion-ui란 무엇인가요?

이 스킬은 Flutter 애플리케이션에서 부드럽고 일관된 애니메이션과 상태 관리를 동시에 제공하는 방법을 설명합니다. 핵심 아이디어는 '상태가 모션을 구동한다'는 것입니다. 즉, 상태 변화가 UI 애니메이션을 자동으로 트리거하도록 설계하여 `AnimationController.forward()`와 같은 수동 호출이 필요 없게 합니다. 이를 위해 sealed class로 화면 상태를 명시적으로 모델링하고, `AnimatedSwitcher`, `AnimatedContainer`와 같은 암시적 애니메이션 위젯을 사용하여 상태 전환을 자연스럽게 처리합니다. 이 스킬은 Riverpod, Bloc, Provider 등 다양한 상태 관리 라이브러리와 호환되며, `lib/core/motion/`에 포함된 위젯 키트(Entrance, GlassNavBar, MorphButton, SlideToConfirm, RollingText 등)를 제공합니다. 또한, 일관된 디자인 토큰(색상, 간격, 반경, 타이포그래피, 모션 속도)을 테마에 저장하여 UI 일관성을 유지하고, 리듀스드 모션, 접근성, 성능 최적화(지연 리스트, 범위 제한 빌드)에 대한 모범 사례를 제시합니다. 스킬은 22개의 레퍼런스 앱(지갑, 배달, 라이드셰어링, 피트니스 등)의 프레임별 분석을 기반으로 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Ismail554/flutter-motion-ui-skill/tree/HEAD/flutter-motion-ui

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Flutter Motion UI

이 스킬은 Flutter 화면을 하나의 일관되고 완성된 제품처럼 느껴지게 만듭니다: 모든 요소가 의도를 가지고 도착하고, 모든 탭이 응답하며, 모든 상태 변화가 시각적으로 드러나고, 데이터가 화면 간에 일관성을 유지합니다.

22개의 레퍼런스 앱(지갑, 배달, 라이드셰어링, 피트니스, 인증/OTP, 알람, 체크아웃, 예약, 기기 페어링)의 프레임별 분석에서 추출되었습니다. references/video-analysis.md에는 각 앱이 하는 일과 어떤 레시피로 재현하는지 나열되어 있습니다.

핵심 아이디어: 상태가 모션을 구동한다

레퍼런스에서 '부드러운' 순간은 거의 모두 동일한 메커니즘입니다: 상태가 변경되고, UI가 이전 값에서 새 값으로 애니메이션되었습니다. 아무도 버튼 핸들러에서 controller.forward()를 호출하지 않았습니다. 따라서 작업은 항상 다음과 같습니다:

  1. 화면의 상태를 명시적으로 모델링합니다(다섯 개의 boolean이 아닌 sealed class).
  2. 해당 상태로 switch를 사용하여 렌더링합니다.
  3. 변경되는 부분을 암시적 애니메이션(AnimatedSwitcher, AnimatedContainer, TweenAnimationBuilder 또는 키트 위젯)으로 감싸서 두 상태 간의 차이가 스스로 애니메이션되도록 합니다.

이렇게 하면 애니메이션과 상태 관리는 더 이상 두 가지 문제가 아닙니다. 중단된 애니메이션, 더블 탭, '로딩 스피너 옆에 성공 체크' 버그는 불가능한 상태를 표현할 수 없기 때문에 사라집니다.

명시적인 AnimationController는 손가락 제스처, 루핑 앰비언스(펄스, 스캐너), 그리고 안무된 다중 파트 시퀀스의 세 가지 경우에만 사용됩니다.

워크플로우

1. 코드를 작성하기 전에 프로젝트를 읽으십시오

  • pubspec.yaml: Flutter/Dart SDK, 이미 사용 중인 상태 라이브러리(riverpod / bloc / provider / getx / 없음), 라우터(go_router / auto_route / Navigator), 기존 애니메이션 패키지.
  • 기존 테마, 색상, 간격, 공유 위젯. 기존 것을 확장하십시오; 두 번째 디자인 시스템이나 두 번째 상태 라이브러리를 도입하지 마십시오. 프로젝트의 폴더 구조와 명명 규칙을 따르십시오. 기존 앱에서는 요청받지 않은 파일에 대한 변경 사항을 기능에 필요한 만큼만 최소화하고(Hero 래퍼, 패딩 인셋), 관련 없는 lint나 스타일 수정은 요청하지 않는 한 그대로 두고, 다시 작성한 모든 기존 파일을 요약에 나열하여 diff에 놀라움이 없도록 하십시오.
  • 새 프로젝트이거나 규칙이 없는 경우, 이 스킬의 기본값(Riverpod Notifier, 확장 기능이 있는 Material 3 테마, lib/core/ + lib/features/<name>/)을 사용하십시오.

2. 모션 키트를 한 번 설치하십시오

작업에 필요한 키트 파일을 프로젝트의 공유 UI 폴더(기본값 lib/core/motion/)에 복사하십시오: 항상 motion.dart, 그리고 실제로 사용할 위젯만, 배럴 파일을 일치하도록 정리하십시오. 세 개를 사용하는 화면에 열 개의 파일을 모두 복사하면 아무도 호출하지 않는 코드가 남습니다. 키트는 의존성이 없는 순수 Flutter이며, 분석기-클린 및 위젯-테스트되었습니다. 프로젝트에 이미 동등한 항목(자체 지속 시간 파일, 자체 네비게이션 바)이 있는 경우, 중복하지 않고 그들의 것을 적용하십시오.

파일제공하는 것
motion.dartMotion.fast/base/slow/page/hero, 곡선, 스프링, 리듀스드-모션 헬퍼—지속 시간이 있는 유일한 장소; Haptics.tap/selection/success/error—햅틱이 실행되는 유일한 장소
entrance.dartEntrance(계단식 페이드/슬라이드/블러인), StateSwitcher(상태에 대한 애니메이션 switch)
page_routes.dartAppRoute, AppPageTransitions.theme(), showAppSheet, heroFadeShuttle
glass_nav_bar.dartGlassNavBar 플로팅 리퀴드-글래스 필, 슬라이딩 렌즈 표시기
morph_button.dartPressable, MorphButton(idle→spinner→success), AsyncMorphButton
slide_to_confirm.dartSlideToConfirm 햅틱 및 상태가 있는 드래그-투-커밋
rolling_number.dartCountUpText, RollingText(주행 거리계 숫자)
otp_boxes.dartOtpBoxes, Shake
animated_items.dartAnimatedItems<T>—일반 불변 리스트에서 삽입/제거를 애니메이션하는 리스트

assets/examples/send_money_flow.dart는 완전히 작업된 플로우(리스트 → 키패드 → 슬라이드 → 전송 → 성공 → 뒤로, 새 행이 애니메이션으로 들어옴)입니다. 다중 상태 플로우를 구축할 때 읽으십시오; 이것이 모방할 패턴입니다. 그 옆에 있는 send_money_flow_test.dart는 그러한 플로우를 테스트하는 방법(전체 경로, 작은 화면 오버플로우, 리듀스드 모션)을 보여줍니다.

assets/project_setup/analysis_options.yaml은 키트가 통과하는 엄격한 lint 세트입니다. 이를 프로젝트의 분석기 구성에 병합하도록 제안하십시오; 팀이 이미 선택한 규칙을 덮어쓰지 마십시오.

3. 화면을 상태와 순간으로 설계한 다음 빌드하십시오

화면 코딩을 시작하기 전에 (머리 속이나 짧은 주석으로) 다음을 작성하십시오:

  • 상태: 이 화면이 가질 수 있는 서로 다른 상태는 무엇인가요? (예: Editing → Submitting → Done | Failed)
  • 공유 데이터: 이 화면이 다른 화면도 표시하는 것은 무엇인가요? 그 데이터는 하나의 소유자를 얻습니다.
  • 순간: 입장, 기본 작업, 각 상태 변경, 그리고 퇴장. 각각은 아래 표에서 하나의 의도적인 모션을 얻습니다. 다른 모든 것은 정지 상태를 유지합니다.

그런 다음 이 순서로 빌드하십시오: 토큰/테마 → 정적 레이아웃 → 상태 계층 → 상태 변경 애니메이션 → 입장 계단식 → 네비게이션 전환 → 햅틱 → 리듀스드-모션 및 작은 화면 확인.

4. 확인

건드린 파일에 대해 dart format을 실행하고 flutter analyze가 깨끗해질 때까지 실행하십시오. 장치/에뮬레이터를 사용할 수 있는 경우 앱을 실행하고 실제로 플로우를 살펴보십시오; 그렇지 않으면 상태를 탐색하는 짧은 위젯 테스트(예제 테스트의 모양 참조)를 작성하고 실행하십시오. 그런 다음 references/consistency-checklist.md를 살펴보십시오.

어떤 모션이 어떤 순간에

순간사용타이밍
화면이 처음 나타날 때상위 3~7개 블록에 Entrance(index: n), 위에서 아래로slow, 55ms 간격
관련 없는 화면으로 푸시(스플래시→홈, 인증→앱)AppTransition.fadeThroughpage
동일한 플로우의 다음 단계(전화→OTP→비밀번호)AppTransition.sharedAxisX + 애니메이션 단계 표시기page
리스트 항목 → 세부 정보이미지/카드에 Hero + 나머지 세부 정보가 그 후에 페이드인hero
확인 / 선택 / 평가 / 선택showAppSheet, 내부 콘텐츠가 계단식으로 나타남page
진행 중인 요청status가 있는 MorphButton 또는 SlideToConfirm단계당 base
값 변경(가격, ETA, 잔액)RollingText(개별) / CountUpText(크기)base / long
항목 추가 / 제거AnimatedItemsbase
화면 상태 변경(로딩→콘텐츠→에러)StateSwitcherbase
선택(칩, 카드, 탭, 별)AnimatedContainer 색상/테두리 + 작은 AnimatedScalefast
모든 탭Pressable 스케일 + 가벼운 햅틱instant
유효성 검사 실패Shake + 빨간 테두리 + 메시지; 입력 유지slow
성공Motion.overshoot로 체크 팝, successHold 유지, 그런 다음 진행—

감각을 유지하는 경험 법칙:

  • 입장은 한 번 재생됩니다. 지연 리스트에서 다시 보기 위해 스크롤된 행은 다시 빌드되어 다시 애니메이션됩니다; 첫 번째 나타날 때만 애니메이션되도록 Entrance(enabled: …)를 전달하십시오.
  • 네비게이션당 하나의 쇼피스. Hero 또는 블러 스루 또는 큰 계단식 — 셋 다가 아닙니다.
  • 느리게 들어가고, 빠르게 나갑니다. 나가기는 Motion.exit로 들어가기 지속 시간의 약 60~80%로 실행됩니다.
  • 관련된 것은 함께 움직이고, 관련 없는 것은 계단식으로 움직입니다.
  • 변환과 불투명도를 애니메이션하고, 긴 리스트에서 레이아웃 애니메이션을 피하십시오. 블러는 비용이 많이 듭니다 — 몇 개의 Hero 요소에만 사용하고, 리스트 행당 절대 사용하지 마십시오.
  • 장식을 위해 입력을 차단하지 마십시오. 입장은 탭 가능성을 지연시켜서는 안 됩니다; 실제 작업(네트워크)만 컨트롤을 비활성화합니다.
  • 리듀스드 모션을 존중하십시오: 키트는 이미 Motion.of(context, …)를 통해 지속 시간을 축소합니다; 작성하는 모든 컨트롤러에서 동일하게 하십시오.

상태 관리 필수 사항

Riverpod / Bloc / ChangeNotifier 동등 항목이 있는 전체 가이드: references/state.md. 절충할 수 없는 사항:

  • 플로우 상태는 sealed class입니다; UI는 철저한 switch입니다. 각 상태에 필요한 데이터를 그 안에 넣으십시오.
  • 공유 데이터당 하나의 소유자. 리스트 화면과 세부 정보/플로우 화면은 동일한 프로바이더를 읽습니다; 플로우는 여기에 씁니다. Navigator.pop을 통해 결과를 다시 전달하고 로컬 복사본을 패치하지 마십시오 — 그렇게 하면 화면이 동기화에서 벗어납니다.
  • 실패 시 사용자 입력을 유지하십시오. 실패한 제출은 필드가 그대로 있고 오류가 추가된 편집 상태로 돌아갑니다.
  • build가 아닌 리스너에서의 부작용. 네비게이션, 스낵바, 햅틱은 상태 전환에 반응합니다(ref.listen, BlocListener).
  • 애니메이션 상태는 위젯에 남고, 비즈니스 상태는 절대 그렇지 않습니다. 컨트롤러는 Submitting을 알지만 AnimationController에 대해서는 모릅니다.
  • 라이브 데이터는 상태로 매핑된 스트림입니다(ETA, 드라이버 위치, 주문 상태). 위젯이 틱 사이를 보간하여 업데이트가 초당 한 번 도착하더라도 모션이 연속적입니다.
  • await 후 상태를 건드리기 전에 비동기 갭(ref.mounted / isClosed / mounted)을 보호하십시오.

UI 일관성

일관성은 설계된 앱과 멋진 화면의 더미를 구분합니다. 토큰을 테마에 넣고 위젯에 하드코딩하지 마십시오:

  • 색상: ColorScheme + 브랜드 추가 요소(성공, 글래스 틴트, 그라데이션)에 대한 ThemeExtension. 위젯은 Theme.of(context)를 읽습니다; 이것은 또한 애니메이션 라이트/다크 전환을 무료로 만듭니다.
  • 간격: 4pt 스케일(4, 8, 12, 16, 20, 24, 32). 전체 앱에 대해 하나의 가로 페이지 패딩.
  • 반경: 세 가지 값(예: 12 작은 / 20 카드 / 28 시트) + 필. 동일한 카드 = 모든 곳에서 동일한 반경.
  • 타이포그래피: TextTheme 역할만; 변경되는 숫자에는 표 형식 그림.
  • 모션: Motion.*만.
  • 컴포넌트: 하나의 기본 버튼, 하나의 시트 스타일, 하나의 입력 스타일, 하나의 네비게이션 바. 두 번째 변형이 나타나면 매개변수가 있는 공유 위젯으로 승격하십시오.

세부 정보 및 감사 목록: references/consistency-checklist.md.

코드 품질 기준

애니메이션 UI는 느슨한 코드의 비용을 배가시킵니다: 초당 120번 실행되는 빌드 메서드, 화면보다 오래 사는 컨트롤러, 한 전화기에만 맞는 레이아웃. 모든 파일을 키트가 충족하는 동일한 기준으로 유지하십시오. references/flutter-best-practices.md에는 전체 지침이 있습니다; 가장 자주 잘못되는 점:

  • _buildX() 헬퍼 메서드가 아닌 작은 위젯 클래스, const 생성자 포함 — 재빌드가 변경된 것만 건드리도록.
  • 생성된 모든 것은 폐기됩니다: 애니메이션/텍스트/스크롤/페이지 컨트롤러, CurvedAnimation, 포커스 노드, 타이머, 구독.
  • 모든 비동기 갭을 보호하십시오(context.mounted / ref.mounted / isClosed)이고 Future를 절대 조용히 버리지 마십시오(await 또는 unawaited).
  • 안정적인 키: 동적 리스트와 AnimatedSwitcher 자식에서 ValueKey(item.id); 인덱스 키를 사용하지 말고, build에서 생성된 키를 사용하지 마십시오.
  • 오버플로우 대신 스크롤하는 레이아웃: 키패드, 폼 또는 피커가 있는 모든 화면은 320×480 뷰포트, 열린 키보드 및 1.3× 텍스트에서 살아남아야 합니다.
  • 모든 화면은 좁은 + 큰 텍스트에서 살아남습니다, 요청받은 플로우뿐만 아니라: 320 너비에 1.6× 텍스트에서 제목과 금액을 보유한 Row, 숫자와 레이블이 있는 카드, 또는 리스트 타일은 텍스트가 Expanded/Flexible에 maxLines 및 overflow와 함께 있지 않으면 옆으로 오버플로우됩니다. tester.platformDispatcher.textScaleFactorTestValue = 1.6을 사용하여 320×568에서 앱의 첫 번째 화면(및 각 탭)을 펌핑하고 예외가 없을 것으로 예상하는 하나의 테스트를 포함하십시오.
  • 불운한 제스처를 테스트하십시오: 일찍 놓인 드래그, 로딩 중 두 번째 탭, 요청 중 뒤로 버튼. 이러한 경로는 시작-끝 테스트가 절대 건드리지 않는 충돌을 보유합니다.
  • 기능 코드에 리터럴이 없습니다: 색상, 반경, 간격, 지속 시간, 햅틱은 모두 테마/토큰/Motion/Haptics에서 옵니다; 사용자 대면 문자열은 프로젝트의 현지화 설정을 따릅니다.
  • 지연 리스트 및 범위 제한 재빌드: 스크롤 가능한 항목에 대한 빌더, 틱 값에 대한 select, child로 전달된 정적 서브트리.
  • 구성에 의해 접근 가능: 사용자 정의 컨트롤에 대한 의미론, 제스처 전용 작업에 대한 대안, 리듀스드 모션 존중. Semantics(label: …, excludeSemantics: true) 래퍼는 자식의 탭 작업도 제거합니다 — onTap도 Semantics에 전달하십시오.
  • 중요한 곳에서 테스트: 단위 테스트로서의 컨트롤러 상태 전환; 결과를 주장하는 플로우당 하나의 위젯 테스트, 애니메이션 내부가 아닙니다.

참조 파일 — 작업과 일치하는 파일을 읽으십시오

  • references/motion-system.md — 토큰 설명, 안무, 키트에 없는 효과(스플래시 시퀀스, 블러 포커스인, 진행 링, 스캐너 라인, 색상/테마 인터폴레이션, 스크롤 링크된 헤더)에 대한 레시피.
  • references/navigation-transitions.md — 페이지 전환, 제대로 된 Hero, 컨테이너 변환, 바텀 시트, 다단계 플로우, go_router 통합.
  • references/glass-nav-bar.md — 리퀴드-글래스 바가 구축되는 방법, 튜닝, 성능, 쉘/탭 상태, 알려진 함정.
  • references/state.md — Riverpod, Bloc 및 ChangeNotifier에서의 플로우 상태, 공유 상태, 비동기/낙관적 패턴, 라이브 스트림.
  • references/components.md — 레시피: 단계 진행, 선택 가능한 카드/칩, 반응형 레이블이 있는 별 평가, 페이지를 다시 틴트하는 카드 캐러셀, 휠 피커, 스켈레톤, 실시간 추적 시트 + 경로 마커, 지속적인 미니 상태 표시줄.
  • references/video-analysis.md — 22개의 분석된 녹화: 화면에서 일어나는 일과 재구축 방법.
  • references/flutter-best-practices.md — 프로젝트 구조, 위젯 구성, 라이프사이클, 비동기 안전, Dart 3 습관, 견고한 레이아웃, 성능, 테마, l10n/접근성, 오류 상태, 테스트, 도구. 새 프로젝트 구조를 만들거나 기존 코드를 검토/리팩토링할 때 읽으십시오.
  • references/consistency-checklist.md — 토큰, 전달 전 QA, 성능 및 접근성 검사.

출력 기대 사항

  • 프로젝트 구조 내에서 완전하고 실행 가능한 파일을 제공하십시오 — '나머지 코드...'가 있는 조각이 아닙니다.
  • 프로젝트의 기존 패키지를 사용하십시오. 새 패키지는 분명히 자리를 잡을 때만 제안하고, 그 이유를 말하십시오.
  • Flutter API는 빠르게 움직입니다. 설치된 SDK가 확신하는 것보다 최신인 경우, 추측하기보다는 시그니처를 확인하십시오(flutter analyze가 가장 빠른 오라클입니다).
  • 완료 시, 어떤 순간이 애니메이션되었고 어떤 상태 모양이 사용되었는지 간략하게 사용자에게 알리십시오.

관련 스킬