# MotionKit HTML 속성 또는 JavaScript API로 제어하는 웹 인터랙션 툴킷 한국어 · [English](README.en.md) · [日本語](README.jp.md) [![npm](https://img.shields.io/npm/v/@dong-gri/motionkit.svg)](https://www.npmjs.com/package/@dong-gri/motionkit) [![license](https://img.shields.io/npm/l/@dong-gri/motionkit.svg)](LICENSE) [![jsDelivr](https://img.shields.io/jsdelivr/npm/hm/@dong-gri/motionkit.svg)](https://www.jsdelivr.com/package/npm/@dong-gri/motionkit) [라이브 데모](https://git.dongri.me/example/motionKit) · [모듈 레퍼런스](docs/module-reference.md) · [AI 프롬프트 가이드](AI-PROMPT-GUIDE.md) · [기능 계약](FEATURE_CONTRACT.md)

--- MotionKit은 34개의 인터랙션 모듈(모션·미디어·스크롤·로더·텍스트)을 `data-mk-*` 속성 하나로 붙이거나 JavaScript API로 세밀하게 제어할 수 있는 라이브러리입니다. 코어는 외부 의존성이 없으며, 미지원 브라우저나 저사양 기기에서는 효과만 비활성화되고 콘텐츠는 그대로 유지됩니다. > AI 코딩 도구(Cursor, Claude 등)로 작업한다면 [AI 프롬프트 가이드](AI-PROMPT-GUIDE.md)를 참고하세요. 모션·인터랙션을 MotionKit 모듈로 우선 적용하도록 지시하는, 그대로 붙여넣는 프롬프트가 들어 있습니다. ## 설치 ### npm ```bash npm install @dong-gri/motionkit ``` ```js import MotionKit from '@dong-gri/motionkit'; import '@dong-gri/motionkit/style.css'; MotionKit.autoInit(); ``` ### CDN (설치 없이 script 태그) ```html ``` ### CDN (ESM) ```js import MotionKit from 'https://cdn.jsdelivr.net/npm/@dong-gri/motionkit/+esm'; ``` ## 빠른 시작 HTML 속성만으로 동작합니다. ```html

문장이 흐르듯 나타납니다

98,760 Cover

스크롤 진입 시 나타납니다

``` 동일한 기능을 JavaScript API로도 쓸 수 있습니다. ```js MotionKit.counter('#total', { preset: 'pop', to: 98760, format: ',' }); MotionKit.reveal('.card', { preset: 'fade-up', stagger: 0.06 }); const lightbox = MotionKit.lightbox('.gallery img', { group: 'work', minimap: true }); ``` ## 선택적 의존성 코어는 단독으로 동작합니다. 아래 라이브러리가 페이지에 있으면 자동으로 감지해 스크롤 스크럽(GSAP + ScrollTrigger)과 스무스 스크롤(Lenis)에 활용하고, 없으면 표준 API로 폴백합니다. ```html ``` 스무스 스크롤은 기본 비활성화이며, 필요할 때만 켤 수 있습니다. ```js MotionKit.enableSmooth({ lerp: 0.08 }); MotionKit.disableSmooth(); ``` ## 모듈 | 모듈 | 활성화 속성 | 용도 | |---|---|---| | `ambientMedia` | `data-mk-ambient-media` | 미디어 주변광(Ambient Glow) | | `blurText` | `data-mk-blur-text` | 글자별 블러 리빌 | | `brushReveal` | `data-mk-brush-reveal` | 포인터 브러시 마스크 리빌 | | `cardGlow` | `data-mk-card-glow` | 포인터 스포트라이트·표면 반사·발광 외곽선 | | `counter` | `data-mk-counter` | 숫자 카운트·플립·시계·카운트다운 | | `cssScroll` | `data-mk-css-scroll` | CSS 변수·애니메이션 타임라인 스크롤 연동 | | `cursor` | `data-mk-cursor` | 커스텀 커서 11종 | | `fullpage` | `data-mk-fullpage` | 풀페이지 섹션 페이징(세로·가로·혼합축) | | `glitch` | `data-mk-glitch` | RGB 슬라이스·글리치 리빌 | | `lazy` | `data-mk-lazy` | 이미지 로딩 연출(스켈레톤·픽셀·프린트·디졸브) | | `lightbox` | `data-mk-lightbox` | 전체화면 뷰어·그룹·확대·미니맵 | | `loader` | `data-mk-loader` | 실제 진행률 연동 로더 | | `magnetic` | `data-mk-magnetic` | 포인터 자석 반응 | | `marquee` | `data-mk-marquee` | 무한 흐름 텍스트 | | `mouseParallax` | `data-mk-mouse-parallax` | 포인터·자이로 패럴럭스 | | `overflowText` | `data-mk-overflow-text` | 넘치는 텍스트 처리 8종 | | `pageReveal` | `data-mk-page-reveal` | 페이지 진입 오버레이 | | `pageTransition` | `data-mk-page-transition` | 동일 출처 페이지 전환 | | `parallax` | `data-mk-parallax` | 스크롤 패럴럭스 | | `progress` | `data-mk-progress` | 읽기 진행률 바·링 | | `reveal` | `data-mk-reveal` | 스크롤 진입 리빌 | | `ripple` | `data-mk-ripple` | 클릭 리플 | | `scrollSequence` | `data-mk-scroll-sequence` | 이미지 시퀀스 스크럽 | | `scrollVelocity` | `data-mk-scroll-velocity` | 스크롤 속도·방향 반응 | | `shuffle` | `data-mk-shuffle` | 문자 셔플 디코드 | | `slider` | `data-mk-slider` | 슬라이드·커버플로우 | | `stickyStack` | `data-mk-sticky-stack` | 스티키 스택(세로·가로·플로팅) | | `textFill` | `data-mk-text-fill` | 스크롤 텍스트 채움 | | `textReveal` | `data-mk-text-reveal` | 텍스트 리빌(한글 조합 포함) | | `textSplit` | `data-mk-text-split` | 글자·단어 분할 모션 | | `textTransition` | `data-mk-text-transition` | 텍스트 교체 전환 | | `tilt` | `data-mk-tilt` | 3D 틸트·글레어 | | `typewriter` | `data-mk-typewriter` | 타이핑 효과 | | `vibrate` | `data-mk-vibrate` | 햅틱 진동 피드백 | 각 모듈의 variant와 옵션 전체 목록은 [모듈 레퍼런스](docs/module-reference.md)와 `motionkit.features.json`을 참고하세요. ## 프레임워크 어댑터 ```jsx import { Motion } from '@dong-gri/motionkit/react'; 안녕하세요 ``` ```js import MotionKitVue from '@dong-gri/motionkit/vue'; app.use(MotionKitVue); ``` ```js import installMotionKit from '@dong-gri/motionkit/jquery'; installMotionKit(window.jQuery); $('.card').motionKit('reveal', { preset: 'fade-up' }); ``` ## 브라우저 지원 Chrome, Edge, Firefox, Safari(데스크톱·모바일)의 최신 버전을 지원합니다. `prefers-reduced-motion`을 켜면 모든 모듈이 애니메이션 없이 최종 상태로 렌더링되며, 미지원 환경에서는 효과가 정적 콘텐츠로 자동 축소됩니다. ## 빌드 ```bash npm install npm run build # dist/ 생성 npm run verify # lint · build · 테스트 · 계약 검증 ``` ## 라이선스 MIT © [dongri](https://dongri.me)