@nurihaus/web-design-system 3.7.0 → 3.8.0

package/README.md

@@ -2,10 +2,18 @@
 
 ## 설치와 사용 (4.x)
 
-`radix-ui` 는 peerDependency 다. 함께 설치한다.
+`radix-ui` 와 `motion` 은 peerDependency 다. 함께 설치한다.
 
 ```bash
-npm i @nurihaus/web-design-system radix-ui
+npm i @nurihaus/web-design-system radix-ui motion
+```
+
+`motion` 은 React 18 이상에서만 동작한다. 앱 루트에 `MotionProvider` 를 한 번 둔다. 스프링으로 움직이는 컴포넌트가 이 아래에서 동작한다.
+
+```tsx
+import { MotionProvider } from '@nurihaus/web-design-system/motion';
+
+<MotionProvider>{children}</MotionProvider>;
 ```
 
 CSS 는 JS 에 들어 있지 않다. 앱에서 한 번 가져온다.
@@ -116,6 +124,8 @@ npm run tokens   # figma.json → tokens/generated/{tokens.css, *.ts}
 
 `tokens/generated/` 를 손으로 고치지 않는다. 배경은 `docs/decisions/0001-tokens-in-ds-and-separate-css.md`.
 
+모션 토큰의 원본은 `tokens/motion.json`(값과 쓰임새)과 `tokens/motion-apply.json`(컴포넌트별 적용 매핑표)이다. 같은 `npm run tokens` 가 `tokens/generated/motion.{css,ts,md}` 를 만든다. 절차는 `docs/motion.md`, 배경은 `docs/decisions/0008-motion-system.md`.
+
 새 서비스가 다른 의미 토큰 값(버튼 색 등)을 써야 하면 `tokens/figma.json` 에 `semantic_{이름}` 세트를 추가하고 `npm run tokens` 를 돌린다. `<html data-ds-theme="{이름}">` 로 고르는 테마가 생긴다. 자세한 규칙은 `docs/tokens.md`.
 
 ## 사용 로그
@@ -138,7 +148,7 @@ export default function App({ children }) {
 <CTAButton text='리포트 받기' track='report/download' trackProps={{ format: 'csv' }} />
 ```
 
-`track` 을 받는 컴포넌트는 CTAButton · DataTable(`click`), Modal · Drawer(`open` · `close`), Tabs · DropDown · ChipGroup · Radio · Checkbox · Switch · Pagination · TextField · TextArea(`change`), BottomNav · Breadcrumb · CollapsibleMenu(`navigate`), Toast · Tooltip(`show`) 다. `value` 에는 탭 id · 칩 id · 옵션 value 처럼 개발자가 정한 id 만 들어간다. TextField · TextArea 는 포커스가 빠질 때 값이 바뀌었으면 값 없이 `change` 를 한 번 보낸다. `LogProvider` 가 없거나 `track` 을 주지 않으면 아무것도 보내지 않는다.
+`track` 을 받는 컴포넌트는 CTAButton · DataTable · Tag · MessageComposer(`click`), Modal · Drawer · MediaViewer(`open` · `close`), MediaThumbnail(`open`), Tabs · DropDown · ChipGroup · Radio · Checkbox · Switch · Pagination · TextField · TextArea(`change`), BottomNav · Breadcrumb · CollapsibleMenu(`navigate`), ListRow(링크 `navigate` · 버튼 `click`), Toast · Tooltip(`show`) 다. `value` 에는 탭 id · 칩 id · 옵션 value 처럼 개발자가 정한 id 만 들어간다. TextField · TextArea 는 포커스가 빠질 때 값이 바뀌었으면 값 없이 `change` 를 한 번 보낸다. `LogProvider` 가 없거나 `track` 을 주지 않으면 아무것도 보내지 않는다.
 
 컴포넌트 밖의 로그는 `useLog` 로 남긴다.
 
@@ -161,7 +171,8 @@ const ReportPage = () => {
 | 파일 | 내용 | 원본 |
 | --- | --- | --- |
 | `dist/ai/components.md` | 공통 규칙, 공개 컴포넌트마다 import · 사용법 · 예시 · props 표, 아직 없는 컴포넌트 목록 | 공통 규칙은 `components/common.md`, props 표는 타입, 사용법은 각 폴더 `usage.md`, 없는 목록은 `components/not-yet.md` |
-| `dist/ai/tokens.md` | CSS 변수 전체와 테마별 의미 토큰, 크기·레이어·모션 토큰 | `tokens/figma.json`, `styles/token/size.css` |
+| `dist/ai/tokens.md` | CSS 변수 전체와 테마별 의미 토큰, 크기·레이어 토큰, 모션 변수 | `tokens/figma.json`, `styles/token/size.css`, `tokens/motion.json` |
+| `dist/ai/motion.md` | 모션 토큰마다 뜻·붙는 곳·prop·reduced-motion 규칙, 컴포넌트별 적용 매핑표 | `tokens/motion.json`, `tokens/motion-apply.json` |
 
 쓰는 쪽에서는 `node_modules/@nurihaus/web-design-system/dist/ai/` 경로로 읽는다. `usage.md` 섹션이 없거나 예시가 타입 검사에 실패하면 `npm run build` 가 멈춘다.