@nurihaus/web-design-system 3.7.0 → 3.9.0

package/dist/ai/components.md

@@ -22,7 +22,7 @@ import '@nurihaus/web-design-system/components.css';
 
 **size 는 전역 이름이다.** `xs · s · m · l · xl` 다섯 개뿐이고, 컴포넌트는 그중 지원하는 것만 받는다(props 표 참고). 같은 글자는 한 줄에 나란히 놓이는 컨트롤(CTAButton · DropDown · TextField)에서 같은 높이다. px 는 `tokens.md` 의 `--control-height-*` 같은 변수에 있고, 컴포넌트에 숫자로 높이를 주지 않는다.
 
-**색은 variant 가 정한다.** CTAButton · OptionBadge · IconTextBadge · IconTextOptionBadge 는 `variant` 로 글자·배경·테두리 색이 묶여서 정해진다. 색 prop 은 없다. 색을 받는 컴포넌트는 Text(`color`, 토큰 이름만) 하나다. Spinner · InlineLoading · OverlayLoading 은 CSS `color` 를 따라가므로 `className` 이나 `style` 의 `color` 로 바꾼다.
+**색은 variant 가 정한다.** CTAButton · IconButton · OptionBadge · IconTextBadge · IconTextOptionBadge 는 `variant` 로 글자·배경·테두리 색이 묶여서 정해진다. 색 prop 은 없다. 색을 받는 컴포넌트는 Text(`color`, 토큰 이름만) 하나다. Spinner · InlineLoading · OverlayLoading 은 CSS `color` 를 따라가므로 `className` 이나 `style` 의 `color` 로 바꾼다.
 
 **커스텀은 `className` 과 `style` 로 한다.** 모든 컴포넌트가 둘을 받아 루트 요소에 붙인다(TextField 는 입력 상자, DataTable 은 `<table>`). variant 가 정한 색을 className 으로 덮으려면 `.cta-button.variant-primary` 보다 구체적인 선택자가 필요하다. 색·간격·글자 값은 `tokens.md` 의 변수만 쓴다.
 
@@ -34,7 +34,7 @@ import '@nurihaus/web-design-system/components.css';
 
 | 컴포넌트 | 보내는 때 | action | value |
 | --- | --- | --- | --- |
-| CTAButton | 누를 때 | `click` | 없음 |
+| CTAButton · IconButton | 누를 때 | `click` | 없음 |
 | DataTable | `onClickRow` 가 있는 헤더 칸을 누를 때 | `click` | 그 칸의 `id` |
 | Modal · Drawer | 열고 닫을 때 | `open` · `close` | 없음 |
 | Tabs · DropDown · ChipGroup · Radio | 고를 때 | `change` | 탭 id · 옵션 value · 칩 id · 선택지 id |
@@ -45,10 +45,15 @@ import '@nurihaus/web-design-system/components.css';
 | Breadcrumb | 현재 위치가 아닌 링크를 누를 때 | `navigate` | 항목 `id` |
 | CollapsibleMenu | 링크·버튼 항목을 고를 때. 그룹 여닫기는 보내지 않는다 | `navigate` | 항목 `key` |
 | Toast · Tooltip | 뜰 때 | `show` | 없음 |
+| ListRow | 링크 행·`onClick` 행을 누를 때. 보기만 하는 행은 보내지 않는다 | `navigate`(링크) · `click`(버튼) | 없음 |
+| Tag | 지우기 버튼을 누를 때 | `click` | 없음 |
+| MessageComposer | 보내기가 실제로 될 때. 막힌 보내기는 보내지 않는다 | `click` | 없음 |
+| MediaThumbnail | 눌러서 보기를 열 때 | `open` | 없음 |
+| MediaViewer | 열고 닫을 때 | `open` · `close` | 없음 |
 
 `value` 에는 개발자가 정한 id 만 들어가고 사용자가 입력한 글자는 들어가지 않는다. TextField · TextArea 가 값을 싣지 않는 것도 그래서다. 더 붙일 값은 `trackProps` 로 준다. `LogProvider` 가 없거나 `track` 이 없으면 아무것도 보내지 않는다. 컴포넌트 밖의 로그(화면 진입 등)는 `useLog` 를 쓴다.
 
-Avatar · OptionBadge · IconTextBadge · IconTextOptionBadge · Skeleton · Text · Icon · StepProgress · Spinner · InlineLoading · OverlayLoading 은 상호작용 핸들러가 없어 `track` 을 받지 않는다. ModalWithDoubleButton 은 `left` · `right` 가 CTAButton props 라 거기에 `track` 을 준다.
+Avatar · OptionBadge · IconTextBadge · IconTextOptionBadge · Skeleton · Text · Icon · StepProgress · Spinner · InlineLoading · OverlayLoading · ListGroup · DescriptionList · EmptyState · MessageThread · Message · MessageEvent · BottomBar 는 상호작용 핸들러가 없어 `track` 을 받지 않는다. Card 도 받지 않는다 — 누르는 카드는 asChild 로 넘긴 링크·버튼이 로그를 맡는다. ModalWithDoubleButton 은 `left` · `right` 가 CTAButton props 라 거기에 `track` 을 준다. Notice 는 `action` 에 `track` 을 주면 그 버튼(CTAButton)이 보낸다. EmptyState 의 버튼은 넘긴 CTAButton 에 준다.
 
 **없는 것은 지어내지 않는다.** 이 문서 끝의 "아직 없는 것" 표에 있는 컴포넌트는 없다. 없는 prop · variant · 토큰 이름도 만들지 않는다. 틀린 variant 나 size 값은 타입 오류가 난다.
 
@@ -56,6 +61,7 @@ Avatar · OptionBadge · IconTextBadge · IconTextOptionBadge · Skeleton · Tex
 
 - [Avatar](#avatar)
 - [CTAButton](#ctabutton)
+- [IconButton](#iconbutton)
 - [Callout](#callout)
 - [OptionBadge](#optionbadge)
 - [IconTextBadge](#icontextbadge)
@@ -87,7 +93,22 @@ Avatar · OptionBadge · IconTextBadge · IconTextOptionBadge · Skeleton · Tex
 - [BottomNav](#bottomnav)
 - [StepProgress](#stepprogress)
 - [ChipGroup](#chipgroup)
+- [Card](#card)
+- [ListGroup](#listgroup)
+- [ListRow](#listrow)
+- [DescriptionList](#descriptionlist)
+- [Notice](#notice)
+- [EmptyState](#emptystate)
+- [Tag](#tag)
+- [MessageThread](#messagethread)
+- [Message](#message)
+- [MessageEvent](#messageevent)
+- [MessageComposer](#messagecomposer)
+- [BottomBar](#bottombar)
+- [MediaThumbnail](#mediathumbnail)
+- [MediaViewer](#mediaviewer)
 - [LogProvider](#logprovider)
+- [MotionProvider](#motionprovider)
 
 ## Avatar
 
@@ -104,6 +125,8 @@ import { Avatar } from '@nurihaus/web-design-system';             // 루트. 첫
 <Avatar size="m" src="https://placehold.co/80x80" alt="프로필 이미지" />
 ```
 
+**모션.** 없음. onClick 을 받지 않는 표시용 이미지다. 누를 수 있게 하려면 쓰는 쪽이 버튼으로 감싸고 그 버튼이 press 를 받는다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -124,7 +147,7 @@ import { CTAButton } from '@nurihaus/web-design-system/cta-button';   // 이 컴
 import { CTAButton } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
 ```
 
-**언제 쓴다.** 저장, 확인, 다음 단계처럼 사용자가 실행하는 동작 버튼에 쓴다. `variant`로 강조 단계를 고르고, `loading`이 true면 `text` 대신 Spinner가 표시된다. Google·Apple·Facebook 로그인 버튼은 `variant="social"`(흰 바탕·검정 글자, 공급자 가이드)에 공급자 로고를 `leftIcon`으로 준다. `callout`을 주면 버튼 오른쪽 위 모서리에 말풍선(Callout)을 끼운다(예: "최근 사용") — 버튼 글자는 움직이지 않고 자리는 DS 가 잡는다. 말풍선 글자도 버튼 안이라 버튼의 접근 가능한 이름에 이어진다(스크린 리더도 "최근 사용"을 듣는다).
+**언제 쓴다.** 저장, 확인, 다음 단계처럼 사용자가 실행하는 동작 버튼에 쓴다. `variant`로 강조 단계를 고르고, `loading`이 true면 `text` 대신 Spinner가 표시된다. Google·Apple·Facebook 로그인 버튼은 `variant="social"`(흰 바탕·검정 글자, 공급자 가이드)에 공급자 로고를 `leftIcon`으로 준다. `callout`을 주면 버튼 오른쪽 위 모서리에 말풍선(Callout)을 끼운다(예: "최근 사용") — 버튼 글자는 움직이지 않고 자리는 DS 가 잡는다. 말풍선 글자도 버튼 안이라 버튼의 접근 가능한 이름에 이어진다(스크린 리더도 "최근 사용"을 듣는다). 다른 화면으로 옮겨 가는 버튼은 `asChild` 를 주고 링크 요소(`<a>`·라우터 Link) 하나를 children 으로 준다 — 그 링크가 버튼 모양이 되고 글자·아이콘은 링크 안에 들어간다. 링크에는 `loading` 을 쓰지 않는다.
 
 **쓰지 않는다.** 확인과 취소 두 버튼을 가진 대화상자는 버튼을 직접 배치하지 말고 ModalWithDoubleButton을 쓴다. 화면 안의 패널 전환은 Tabs, 사이드 메뉴 항목은 CollapsibleMenu를 쓴다.
 
@@ -138,16 +161,23 @@ import { CTAButton } from '@nurihaus/web-design-system';             // 루트.
     leftIcon={<img src="/icons/google.svg" alt="" />}
     callout="최근 사용"
   />
+  <CTAButton asChild variant="primary" size="l" text="홈으로">
+    <a href="/" />
+  </CTAButton>
 </>
 ```
 
+**모션.** press · reject · appear(opt) · busy(`loading`). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
+| `asChild` | `boolean` |  |  |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'m'` |
 | `track` | `string` |  |  |
 | `text` | `ReactNode` | 예 |  |
+| `children` | `ReactNode` |  |  |
 | `variant` | `'neutral' \| 'primary' \| 'outlined' \| 'secondary' \| 'ghost' \| 'confirm' \| 'social'` |  | `'primary'` |
 | `leftIcon` | `ReactNode` |  |  |
 | `rightIcon` | `ReactNode` |  |  |
@@ -155,7 +185,44 @@ import { CTAButton } from '@nurihaus/web-design-system';             // 루트.
 | `loading` | `boolean` |  |  |
 | `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
-이 밖에 React·HTML 기본 속성 276개를 받는다.
+이 밖에 React·HTML 기본 속성 275개를 받는다.
+
+## IconButton
+
+```ts
+import { IconButton } from '@nurihaus/web-design-system/icon-button';   // 이 컴포넌트만 싣는다 (권장)
+import { IconButton } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 글자 없이 아이콘 하나로 뜻이 통하는 버튼에 쓴다(뒤로, 알림, 첨부, 떠 있는 추가 버튼). `icon` 은 Icon 이름, `label` 은 버튼의 이름(aria-label)이라 꼭 준다. `variant` 는 `ghost`(기본, 바탕 없이 회색 아이콘, 누르는 동안 회색 원)·`secondary`(연보라)·`primary`(진보라). `size` 는 `s`(36)·`m`(44, 기본)·`l`(56)이고 보이는 크기가 작아도 누르는 자리는 44 이상이다. 다른 화면으로 옮겨 가는 버튼은 `asChild` 를 주고 링크 요소 하나를 children 으로 준다 — 그 링크가 버튼 모양이 되고 아이콘은 링크 안에 들어간다. 떠 있는 버튼의 자리·그림자는 쓰는 쪽이 `className` 으로 준다(`--shadow-floating`). `className`·`style` 은 버튼(또는 링크)에 붙는다.
+
+**쓰지 않는다.** 글자가 있는 버튼은 CTAButton 을 쓴다. 칩의 지우기는 Tag 의 `onRemove`, 대화 보내기는 MessageComposer 를 쓴다.
+
+```tsx
+<>
+  <IconButton icon="caret-left" label="뒤로" onClick={() => {}} />
+  <IconButton asChild icon="plus" label="새로 만들기" variant="primary" size="l">
+    <a href="/new" />
+  </IconButton>
+</>
+```
+
+**모션.** press. 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  |  |
+| `size` | `'s' \| 'm' \| 'l'` |  | `defaultSize` |
+| `label` | `string` | 예 |  |
+| `track` | `string` |  |  |
+| `children` | `ReactNode` |  |  |
+| `variant` | `'primary' \| 'secondary' \| 'ghost'` |  | `'ghost'` |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
+| `icon` | `'link' \| 'circle' \| 'image' \| 'warning' \| 'x' \| 'house' \| 'megaphone-simple' \| 'chats-circle' \| 'user-circle' \| 'bell' \| 'caret-left' \| 'magnifying-glass' \| 'dots-three' \| 'gear-six' \| 'chat-circle' \| 'paper-plane-tilt' \| 'plus' \| 'camera' \| 'video-camera' \| 'play' \| 'upload-simple' \| 'calendar-blank' \| 'clock' \| 'map-pin' \| 'truck' \| 'ticket' \| 'qr-code' \| 'sparkle' \| 'gift' \| 'wallet' \| 'bank' \| 'credit-card' \| 'check-circle' \| 'check' \| 'info' \| 'question' \| 'lock' \| 'pencil-simple' \| 'trash' \| 'copy' \| 'share-network' \| 'eye' \| 'sliders-horizontal' \| 'heart' \| 'star' \| 'globe' \| 'sign-out' \| 'caret-right' \| 'arrow-right' \| 'instagram-logo' \| 'tiktok-logo' \| 'youtube-logo'` | 예 |  |
+
+이 밖에 React·HTML 기본 속성 275개를 받는다.
 
 ## Callout
 
@@ -176,6 +243,8 @@ import { Callout } from '@nurihaus/web-design-system';             // 루트.
 </>
 ```
 
+**모션.** enter · attention. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -192,7 +261,7 @@ import { OptionBadge } from '@nurihaus/web-design-system/option-badge';   // 이
 import { OptionBadge } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
 ```
 
-**언제 쓴다.** 상태값이나 분류처럼 짧은 값 하나(`option`)를 라벨로 보여줄 때 쓴다. `variant`로 색을 고른다(`neutral`·`primary`·`danger`·`outlined`). 색 prop 은 없다. `tooltip`을 주면 마우스를 올렸을 때 설명이 뜬다. 대상에 붙어 늘 떠 있는 말풍선은 Callout 을 쓴다.
+**언제 쓴다.** 상태값이나 분류처럼 짧은 값 하나(`option`)를 라벨로 보여줄 때 쓴다. `variant`로 색을 고른다(`neutral`·`primary`·`danger`·`success`·`warning`·`outlined`). 색 prop 은 없다. `tooltip`을 주면 마우스를 올렸을 때 설명이 뜬다. 대상에 붙어 늘 떠 있는 말풍선은 Callout 을 쓴다.
 
 **쓰지 않는다.** 아이콘이 함께 필요하면 IconTextBadge를, 아이콘과 텍스트 오른쪽에 수치 같은 부가 값까지 붙여야 하면 IconTextOptionBadge를 쓴다. 클릭 동작이 필요한 요소에는 CTAButton을 쓴다.
 
@@ -200,11 +269,13 @@ import { OptionBadge } from '@nurihaus/web-design-system';             // 루트
 <OptionBadge option="진행 중" variant="primary" size="s" width="fit-content" />
 ```
 
+**모션.** attention(opt). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
-| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'outlined'` |  | `'neutral'` |
+| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'success' \| 'warning' \| 'outlined'` |  | `'neutral'` |
 | `width` | `string \| number` |  | `'100%'` |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'xl'` |
 | `option` | `ReactNode` | 예 |  |
@@ -236,11 +307,13 @@ import { IconTextBadge } from '@nurihaus/web-design-system';             // 루
 />
 ```
 
+**모션.** attention(opt). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
-| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'outlined'` |  | `'neutral'` |
+| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'success' \| 'warning' \| 'outlined'` |  | `'neutral'` |
 | `width` | `string \| number` |  | `'100%'` |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'xl'` |
 | `icon` | `ReactNode` | 예 |  |
@@ -273,11 +346,13 @@ import { IconTextOptionBadge } from '@nurihaus/web-design-system';             /
 />
 ```
 
+**모션.** attention(opt). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
-| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'outlined'` |  | `'neutral'` |
+| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'success' \| 'warning' \| 'outlined'` |  | `'neutral'` |
 | `width` | `string \| number` |  | `'100%'` |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'xl'` |
 | `icon` | `ReactNode` | 예 |  |
@@ -317,6 +392,8 @@ import { DataTable } from '@nurihaus/web-design-system';             // 루트.
 />
 ```
 
+**모션.** press · attention(opt). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -358,6 +435,8 @@ import { TextField } from '@nurihaus/web-design-system';             // 루트.
 />
 ```
 
+**모션.** 없음. 텍스트 입력은 press 의 avoid 대상이다. 글자가 바뀌는 것은 선택이 아니라 confirm 도 아니다..
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -387,9 +466,11 @@ import { Radio } from '@nurihaus/web-design-system';             // 루트. 첫
 
 **언제 쓴다.** 몇 개의 선택지를 모두 펼쳐 보여주고 그중 하나만 고르게 할 때 쓴다. 선택 상태는 항상 부모가 가지므로 `onChange`에서 받은 id로 `selected`를 갱신해야 선택이 바뀐다.
 
+`variant="chip"`이면 선택지를 칩으로 가로로 늘어놓는다. 폼 안에서 짧은 선택지 몇 개를 고를 때 쓴다. 처음에는 아무것도 고르지 않은 채로 둘 수 있다. `label`은 선택지 묶음의 `aria-label`이 된다.
+
 `track`을 주면 선택지를 누를 때 `change`와 그 선택지 `id`를 `value`에 담아 사용 로그로 보낸다.
 
-**쓰지 않는다.** 여러 개를 동시에 고르면 Checkbox를 쓴다. 선택지가 많아 모두 펼치기 어려우면 DropDown을 쓴다.
+**쓰지 않는다.** 여러 개를 동시에 고르면 Checkbox를 쓴다. 선택지가 많아 모두 펼치기 어려우면 DropDown을 쓴다. 목록을 거르는 필터 칩은 ChipGroup을 쓴다(늘 하나가 골라져 있다).
 
 ```tsx
 <Radio
@@ -403,10 +484,14 @@ import { Radio } from '@nurihaus/web-design-system';             // 루트. 첫
 />
 ```
 
+**모션.** press · confirm. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
+| `variant` | `'default' \| 'chip'` |  | `'default'` |
+| `label` | `string` |  |  |
 | `options` | `{ id: string; label: ReactNode; disabled?: boolean \| undefined; }[]` | 예 |  |
 | `selected` | `string \| null` |  |  |
 | `onChange` | `((id: string \| null) => void)` |  |  |
@@ -432,6 +517,8 @@ import { Checkbox } from '@nurihaus/web-design-system';             // 루트.
 <Checkbox id="agree-terms" label="약관에 동의합니다" checked={false} onChange={() => {}} />
 ```
 
+**모션.** press · confirm. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -466,6 +553,8 @@ import { Switch } from '@nurihaus/web-design-system';             // 루트. 첫
 <Switch id="push-alarm" label="푸시 알림 받기" checked={true} onChange={() => {}} />
 ```
 
+**모션.** press · confirm. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -500,6 +589,8 @@ import { TextArea } from '@nurihaus/web-design-system';             // 루트.
 <TextArea name="memo" title="메모" placeholder="내용을 입력하세요" rows={4} />
 ```
 
+**모션.** 없음. 텍스트 입력은 press 의 avoid 대상이다. 글자가 바뀌는 것은 선택이 아니라 confirm 도 아니다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -534,6 +625,8 @@ import { Toast } from '@nurihaus/web-design-system';             // 루트. 첫
 <Toast open title="저장했습니다" description="변경 사항이 반영됐습니다." variant="success" onOpenChange={() => {}} />
 ```
 
+**모션.** enter · exit. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -543,7 +636,7 @@ import { Toast } from '@nurihaus/web-design-system';             // 루트. 첫
 | `title` | `ReactNode` | 예 |  |
 | `track` | `string` |  |  |
 | `onPause` | `(() => void)` |  |  |
-| `variant` | `'secondary' \| 'default' \| 'success' \| 'warning' \| 'error'` |  | `'default'` |
+| `variant` | `'success' \| 'warning' \| 'secondary' \| 'default' \| 'error'` |  | `'default'` |
 | `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 | `onResume` | `(() => void)` |  |  |
 | `open` | `boolean` |  |  |
@@ -573,6 +666,8 @@ import { ToastProvider } from '@nurihaus/web-design-system';             // 루
 </ToastProvider>
 ```
 
+**모션.** 없음. 토스트 자리(viewport)만 그린다. 모션은 각 Toast 가 받는다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -599,6 +694,8 @@ import { Pagination } from '@nurihaus/web-design-system';             // 루트.
 <Pagination totalPages={10} page={3} onPageChange={() => {}} />
 ```
 
+**모션.** press. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -638,6 +735,8 @@ import { Modal } from '@nurihaus/web-design-system';             // 루트. 첫
 </Modal>
 ```
 
+**모션.** enter · exit. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -676,6 +775,8 @@ import { Drawer } from '@nurihaus/web-design-system';             // 루트. 첫
 </Drawer>
 ```
 
+**모션.** enter · exit. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -713,6 +814,8 @@ import { Skeleton } from '@nurihaus/web-design-system';             // 루트.
 <Skeleton shape="text" lines={3} />
 ```
 
+**모션.** busy(`animated`). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -748,6 +851,8 @@ import { Breadcrumb } from '@nurihaus/web-design-system';             // 루트.
 />
 ```
 
+**모션.** press. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -790,6 +895,8 @@ import { DropDown } from '@nurihaus/web-design-system';             // 루트.
 />
 ```
 
+**모션.** press · enter · exit · expand. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -860,6 +967,8 @@ import Link from 'next/link';
 />
 ```
 
+**모션.** press · expand. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -894,6 +1003,8 @@ import { Text } from '@nurihaus/web-design-system';             // 루트. 첫
 <Text as="h2" text="캠페인 목록" size="xl" weight="bold" color="grey-scale-900" />
 ```
 
+**모션.** 없음. 글자만 그린다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -927,6 +1038,8 @@ import { Tooltip } from '@nurihaus/web-design-system';             // 루트.
 <Tooltip trigger={<span>도움말</span>} content="최근 30일 기준입니다." direction="top" disabled={false} />
 ```
 
+**모션.** enter · exit. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -963,6 +1076,8 @@ import { TooltipProvider } from '@nurihaus/web-design-system';             //
 </TooltipProvider>
 ```
 
+**모션.** 없음. DOM 을 그리지 않는다. 지연 시간만 나눠 준다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -994,6 +1109,8 @@ import { Tabs } from '@nurihaus/web-design-system';             // 루트. 첫
 />
 ```
 
+**모션.** press · progress. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1045,6 +1162,8 @@ import { ModalWithDoubleButton } from '@nurihaus/web-design-system';
 />
 ```
 
+**모션.** enter · exit. 토큰 값과 규칙은 `motion.md`.
+
 ### ModalWithDoubleButton.Row props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1096,6 +1215,8 @@ import { Spinner } from '@nurihaus/web-design-system';             // 루트.
 <Spinner style={{ color: 'var(--color-grey-scale-400)' }} />
 ```
 
+**모션.** busy. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1120,6 +1241,8 @@ import { InlineLoading } from '@nurihaus/web-design-system';             // 루
 <InlineLoading size={24} justifyContent="center" />
 ```
 
+**모션.** busy. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1146,6 +1269,8 @@ import { OverlayLoading } from '@nurihaus/web-design-system';             // 루
 <OverlayLoading open={true} message="저장 중입니다" />
 ```
 
+**모션.** busy · enter · exit. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1186,13 +1311,15 @@ import { Icon } from '@nurihaus/web-design-system';             // 루트. 첫
 <Icon name="x" size="m" label="닫기" />
 ```
 
+**모션.** 없음. 장식 그림이다. 모션은 감싸는 컴포넌트가 정한다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'l'` |
 | `label` | `string` |  |  |
-| `name` | `'link' \| 'image' \| 'x' \| 'warning' \| 'house' \| 'megaphone-simple' \| 'chats-circle' \| 'user-circle' \| 'bell' \| 'caret-left' \| 'magnifying-glass' \| 'dots-three' \| 'gear-six' \| 'chat-circle' \| 'paper-plane-tilt' \| 'plus' \| 'camera' \| 'video-camera' \| 'play' \| 'upload-simple' \| 'calendar-blank' \| 'clock' \| 'map-pin' \| 'truck' \| 'ticket' \| 'qr-code' \| 'sparkle' \| 'gift' \| 'wallet' \| 'bank' \| 'credit-card' \| 'check-circle' \| 'check' \| 'info' \| 'question' \| 'lock' \| 'pencil-simple' \| 'trash' \| 'copy' \| 'share-network' \| 'eye' \| 'sliders-horizontal' \| 'heart' \| 'star' \| 'globe' \| 'sign-out' \| 'caret-right' \| 'arrow-right' \| 'instagram-logo' \| 'tiktok-logo' \| 'youtube-logo'` | 예 |  |
+| `name` | `'link' \| 'circle' \| 'image' \| 'warning' \| 'x' \| 'house' \| 'megaphone-simple' \| 'chats-circle' \| 'user-circle' \| 'bell' \| 'caret-left' \| 'magnifying-glass' \| 'dots-three' \| 'gear-six' \| 'chat-circle' \| 'paper-plane-tilt' \| 'plus' \| 'camera' \| 'video-camera' \| 'play' \| 'upload-simple' \| 'calendar-blank' \| 'clock' \| 'map-pin' \| 'truck' \| 'ticket' \| 'qr-code' \| 'sparkle' \| 'gift' \| 'wallet' \| 'bank' \| 'credit-card' \| 'check-circle' \| 'check' \| 'info' \| 'question' \| 'lock' \| 'pencil-simple' \| 'trash' \| 'copy' \| 'share-network' \| 'eye' \| 'sliders-horizontal' \| 'heart' \| 'star' \| 'globe' \| 'sign-out' \| 'caret-right' \| 'arrow-right' \| 'instagram-logo' \| 'tiktok-logo' \| 'youtube-logo'` | 예 |  |
 | `weight` | `'fill' \| 'regular'` |  |  |
 
 이 밖에 React·HTML 기본 속성 474개를 받는다.
@@ -1235,6 +1362,8 @@ import Link from 'next/link';
 />
 ```
 
+**모션.** press · progress · appear(opt) · dismiss-on-scroll(opt). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1270,6 +1399,8 @@ import { StepProgress } from '@nurihaus/web-design-system';             // 루
 />
 ```
 
+**모션.** progress · reveal(opt). 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1308,6 +1439,8 @@ import { ChipGroup } from '@nurihaus/web-design-system';             // 루트.
 />
 ```
 
+**모션.** press · confirm. 토큰 값과 규칙은 `motion.md`.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1324,6 +1457,490 @@ import { ChipGroup } from '@nurihaus/web-design-system';             // 루트.
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
+## Card
+
+```ts
+import { Card } from '@nurihaus/web-design-system/card';   // 이 컴포넌트만 싣는다 (권장)
+import { Card } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 목록이나 홈에서 내용 한 묶음을 흰 면(`variant="default"`) 또는 연보라 면(`variant="tinted"`)에 담을 때 쓴다. 안은 세로로 쌓이고 사이 간격은 정해져 있다. 누르면 다른 화면으로 가는 카드는 `asChild` 를 주고 링크 요소(`<a>`·라우터 Link) 하나를 children 으로 준다 — 그 링크가 카드가 되고 내용은 링크의 children 으로 쓴다. 링크·버튼 카드만 누를 때 살짝 줄어든다. `className`·`style` 은 루트(asChild 면 그 링크)에 붙는다.
+
+**쓰지 않는다.** 설정·메뉴처럼 줄지어 놓이는 항목은 ListGroup 과 ListRow 를 쓴다. 이름과 값을 나란히 보여 주는 요약은 DescriptionList 를 쓴다.
+
+```tsx
+<>
+  <Card>
+    <strong>여름 신제품 리뷰</strong>
+    <span>마감 3일 남음</span>
+  </Card>
+  <Card asChild variant="tinted">
+    <a href="/campaigns/1">
+      <strong>여름 신제품 리뷰</strong>
+      <span>마감 3일 남음</span>
+    </a>
+  </Card>
+</>
+```
+
+**모션.** press · attention(opt). 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  |  |
+| `variant` | `'default' \| 'tinted'` |  | `'default'` |
+
+이 밖에 React·HTML 기본 속성 266개를 받는다.
+
+## ListGroup
+
+```ts
+import { ListGroup } from '@nurihaus/web-design-system/list-group';   // 이 컴포넌트만 싣는다 (권장)
+import { ListGroup } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 설정·계정 메뉴처럼 ListRow 여러 줄을 흰 면 하나에 묶을 때 쓴다. 줄 사이에는 구분선이 자동으로 들어간다. `label` 을 주면 면 위에 작은 제목이 붙고 스크린 리더는 그 제목을 그룹 이름으로 읽는다. `className`·`style` 은 제목과 면을 감싼 루트에 붙는다.
+
+**쓰지 않는다.** 내용이 자유로운 한 묶음은 Card 를 쓴다. 이름과 값만 나란히 보여 주는 요약은 DescriptionList 를 쓴다.
+
+```tsx
+<ListGroup label="계정">
+  <ListRow label="내 정보" onClick={() => {}} />
+  <ListRow label="연결된 계정" trailing="2개" asChild>
+    <a href="/accounts" />
+  </ListRow>
+</ListGroup>
+```
+
+**모션.** 없음. 면과 제목만 그린다. 눌림은 각 ListRow 가 받는다.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` |  |  |
+
+이 밖에 React·HTML 기본 속성 266개를 받는다.
+
+## ListRow
+
+```ts
+import { ListRow } from '@nurihaus/web-design-system/list-row';   // 이 컴포넌트만 싣는다 (권장)
+import { ListRow } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** ListGroup 안의 한 줄에 쓴다. `label` 이 이름, `description` 이 아래 보조 글, `leading` 이 왼쪽(Icon size m 이나 Avatar), `trailing` 이 오른쪽(값 글자, OptionBadge, Switch)이다. 다른 화면으로 가는 줄은 `asChild` 를 주고 링크 요소(`<a>`·라우터 Link) 하나를 children 으로 준다 — 그 링크가 줄이 되고 내용은 링크 안에 들어간다. 그 자리에서 동작하는 줄은 `onClick` 을 주면 button 이 된다. 누르는 줄은 오른쪽 끝에 화살표가 기본으로 붙고 `chevron={false}` 로 숨긴다. 누르면 배경이 잠깐 어두워진다. `className`·`style` 은 줄(button·링크) 자체에 붙는다.
+
+**쓰지 않는다.** `trailing` 에 Switch 같은 버튼을 둔 줄에는 `onClick`·`asChild` 를 주지 않는다 — 버튼 안에 버튼이 들어간다. 줄을 ListGroup 밖에 홀로 두지 않는다. 사용 로그는 넘기는 링크·핸들러에서 남긴다.
+
+```tsx
+<ListGroup>
+  <ListRow
+    leading={<Icon name="user-circle" size="m" />}
+    label="내 정보"
+    description="이름 · 연락처"
+    onClick={() => {}}
+  />
+  <ListRow label="등급" trailing={<OptionBadge option="골드" variant="primary" size="s" />} />
+  <ListRow label="알림 받기" trailing={<Switch id="push" aria-label="알림 받기" />} />
+</ListGroup>
+```
+
+**모션.** press · attention(opt). 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  |  |
+| `label` | `ReactNode` | 예 |  |
+| `track` | `string` |  |  |
+| `children` | `ReactNode` |  |  |
+| `onClick` | `MouseEventHandler<HTMLElement>` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
+| `description` | `ReactNode` |  |  |
+| `chevron` | `boolean` |  |  |
+| `leading` | `ReactNode` |  |  |
+| `trailing` | `ReactNode` |  |  |
+
+이 밖에 React·HTML 기본 속성 264개를 받는다.
+
+## DescriptionList
+
+```ts
+import { DescriptionList } from '@nurihaus/web-design-system/description-list';   // 이 컴포넌트만 싣는다 (권장)
+import { DescriptionList } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 금액 내역·신청 정보처럼 이름과 값을 줄마다 나란히 보여 주는 요약에 쓴다. 이름은 왼쪽 회색, 값은 오른쪽 진한 글자다. 합계 줄은 `total: true` 를 주면 위에 구분선이 생기고 값이 크고 굵어진다. 마지막 항목에 둔다. `className`·`style` 은 `<dl>` 에 붙는다.
+
+**쓰지 않는다.** 줄을 눌러 다른 화면으로 가야 하면 ListGroup 과 ListRow 를 쓴다. 열이 여러 개인 표는 DataTable 을 쓴다.
+
+```tsx
+<DescriptionList
+  items={[
+    { id: 'fee', label: '원고료', value: '300,000원' },
+    { id: 'tax', label: '원천징수 (3.3%)', value: '-9,900원' },
+    { id: 'total', label: '실 지급액', value: '290,100원', total: true },
+  ]}
+/>
+```
+
+**모션.** 없음. 이름–값 글자만 그린다. 누르는 표면이 아니다.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `items` | `DescriptionListItem[]` | 예 |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## Notice
+
+```ts
+import { Notice } from '@nurihaus/web-design-system/notice';   // 이 컴포넌트만 싣는다 (권장)
+import { Notice } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 카드·바텀시트·폼 안에 머무르며 상태나 주의를 알릴 때 쓴다(예: "검토 중입니다", "저장하지 못했습니다"). `variant`(`neutral` 기본·`success`·`warning`·`danger`)가 바탕색·글자색과 앞 아이콘(정보·체크·경고·경고)을 정한다. `danger` 는 `role="alert"` 라 화면 낭독기가 바로 읽는다. 다른 variant 에 role 이 필요하면 쓰는 쪽이 `role` 을 준다(그 값이 앞선다). `title` 은 본문 위 굵은 한 줄, `children` 이 본문이다. `action`(`{ label, onClick, loading?, track? }`)을 주면 본문 아래 작은 버튼(CTAButton xs·neutral)이 하나 붙는다. `loading` 이면 버튼이 Spinner 로 바뀌고 처리 중에는 `onClick` 을 다시 부르지 않는다. 조건에 따라 나타나는 안내만 `motion`(`weak`·`strong`)을 준다 — 나타날 때 흐려졌다 선명해진다. 사라질 때는 움직이지 않는다. `className`·`style` 은 루트(`div`)에 붙는다.
+
+**쓰지 않는다.** 행동 결과를 잠깐 알리고 스스로 사라져야 하면 Toast 를 쓴다. 입력칸 하나의 오류는 TextField 의 helper text 를 쓴다. 목록이 비었거나 화면 전체를 채우는 안내는 EmptyState 를 쓴다.
+
+```tsx
+<Notice variant="danger" title="저장하지 못했습니다" action={{ label: '다시 시도', onClick: () => {} }}>
+  네트워크 연결을 확인해 주세요.
+</Notice>
+```
+
+**모션.** enter(opt, `motion`). 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` |  |  |
+| `children` | `ReactNode` | 예 |  |
+| `variant` | `'neutral' \| 'danger' \| 'success' \| 'warning'` |  | `'neutral'` |
+| `motion` | `'strong' \| 'weak'` |  |  |
+| `action` | `NoticeAction` |  |  |
+
+이 밖에 React·HTML 기본 속성 264개를 받는다.
+
+## EmptyState
+
+```ts
+import { EmptyState } from '@nurihaus/web-design-system/empty-state';   // 이 컴포넌트만 싣는다 (권장)
+import { EmptyState } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 목록이 비었을 때, 불러오지 못해 다시 시도를 권할 때, 찾을 수 없거나 준비 중인 화면에 쓴다. 가운데에 아이콘 원·제목·설명·버튼을 세로로 쌓는다. `icon` 은 Icon 이름, `title` 은 필수, `description` 은 한두 줄 보충 설명이다. `action` 에는 버튼(보통 CTAButton)을 넘긴다. `variant`(`default` 기본·`neutral`)는 아이콘 원 색만 바꾼다. 기본은 연보라, 오류·준비 중처럼 힘을 뺄 때는 `neutral`(회색)이다. 제목은 제목 단계를 정하지 않으려고 `p` 로 그린다. 화면 제목이 필요하면 쓰는 쪽이 따로 둔다. `className`·`style` 은 루트(`div`)에 붙는다.
+
+**쓰지 않는다.** 카드 안에서 상태를 짧게 알리는 안내는 Notice 를 쓴다. 불러오는 중에는 Skeleton 이나 로딩 컴포넌트를 쓴다.
+
+```tsx
+<EmptyState
+  icon="warning"
+  variant="neutral"
+  title="불러오지 못했어요"
+  description="잠시 뒤 다시 시도해 주세요."
+  action={<CTAButton size="s" variant="secondary" text="다시 시도" />}
+/>
+```
+
+**모션.** 없음. 누를 곳이 없는 표시용 화면이다. 버튼은 쓰는 쪽이 넘긴 CTAButton 이 press 를 받는다.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | 예 |  |
+| `variant` | `'neutral' \| 'default'` |  | `'default'` |
+| `icon` | `'link' \| 'circle' \| 'image' \| 'warning' \| 'x' \| 'house' \| 'megaphone-simple' \| 'chats-circle' \| 'user-circle' \| 'bell' \| 'caret-left' \| 'magnifying-glass' \| 'dots-three' \| 'gear-six' \| 'chat-circle' \| 'paper-plane-tilt' \| 'plus' \| 'camera' \| 'video-camera' \| 'play' \| 'upload-simple' \| 'calendar-blank' \| 'clock' \| 'map-pin' \| 'truck' \| 'ticket' \| 'qr-code' \| 'sparkle' \| 'gift' \| 'wallet' \| 'bank' \| 'credit-card' \| 'check-circle' \| 'check' \| 'info' \| 'question' \| 'lock' \| 'pencil-simple' \| 'trash' \| 'copy' \| 'share-network' \| 'eye' \| 'sliders-horizontal' \| 'heart' \| 'star' \| 'globe' \| 'sign-out' \| 'caret-right' \| 'arrow-right' \| 'instagram-logo' \| 'tiktok-logo' \| 'youtube-logo'` | 예 |  |
+| `description` | `ReactNode` |  |  |
+| `action` | `ReactNode` |  |  |
+
+이 밖에 React·HTML 기본 속성 264개를 받는다.
+
+## Tag
+
+```ts
+import { Tag } from '@nurihaus/web-design-system/tag';   // 이 컴포넌트만 싣는다 (권장)
+import { Tag } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 고른 값을 보여 주고 하나씩 지울 수 있게 할 때 쓴다(예: 여러 개 고른 나라). `text` 가 글자다. `onRemove` 를 주면 오른쪽에 X 버튼이 붙고, 누르면 `onRemove` 가 불린다. 이때 `removeLabel`(X 버튼을 읽어 줄 이름, 예: "대한민국 지우기")도 꼭 준다 — 앱 언어로 쓰는 쪽이 정한다. `onRemove` 가 없으면 지울 수 없는 표시용 태그다. `track` 을 주면 X 를 누를 때 `click` 을 보낸다. `className`·`style` 은 루트(`span`)에 붙는다. 여러 개를 늘어놓을 때 줄 바꿈·간격은 쓰는 쪽 컨테이너가 정한다.
+
+**쓰지 않는다.** 목록을 걸러 낼 선택지는 ChipGroup 을 쓴다. 상태값·분류 라벨은 OptionBadge 를 쓴다.
+
+```tsx
+<>
+  <Tag text="대한민국" onRemove={() => {}} removeLabel="대한민국 지우기" />
+  <Tag text="일본" />
+</>
+```
+
+**모션.** press. 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `track` | `string` |  |  |
+| `text` | `ReactNode` | 예 |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
+| `onRemove` | `(() => void)` |  |  |
+| `removeLabel` | `string` |  |  |
+
+이 밖에 React·HTML 기본 속성 265개를 받는다.
+
+## MessageThread
+
+```ts
+import { MessageThread } from '@nurihaus/web-design-system/message-thread';   // 이 컴포넌트만 싣는다 (권장)
+import { MessageThread } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 1:1 대화·문의 답변처럼 말풍선이 쌓이는 대화 목록에 쓴다. `<ol>` 이고 children 은 Message · MessageEvent 다. 항목 사이 간격만 정한다. 스크롤과 새 메시지로 내려가기는 쓰는 쪽이 정한다. `className`·`style`·`ref` 는 `<ol>` 에 붙는다.
+
+**쓰지 않는다.** 댓글처럼 말풍선이 아닌 목록에는 쓰지 않는다.
+
+```tsx
+<MessageThread>
+  <MessageEvent>10월 22일</MessageEvent>
+  <Message name="담당자" time="오후 2:10">안녕하세요!</Message>
+  <Message side="end" time="오후 2:12">네, 확인했어요.</Message>
+</MessageThread>
+```
+
+**모션.** 없음. 목록 틀이다. 등장 모션은 항목(Message)이 가진다.
+
+### props
+
+이 컴포넌트가 따로 정의한 prop 은 없다.
+
+이 밖에 React·HTML 기본 속성 269개를 받는다.
+
+## Message
+
+```ts
+import { Message } from '@nurihaus/web-design-system/message';   // 이 컴포넌트만 싣는다 (권장)
+import { Message } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** MessageThread 안의 말풍선 하나다. `side="end"` 는 내가 보낸 메시지(오른쪽, 보라), 기본 `start` 는 상대 메시지(왼쪽, 회색)다. 글은 children 이고 줄바꿈을 그대로 보인다. `name` 은 말풍선 위 이름, `time` 은 옆 시각(`<time>`, 기계용 값은 `dateTime`)이다. 언제 보일지(연속 메시지에서 숨기기 등)는 쓰는 쪽이 정한다. `media` 는 글 뒤 말풍선 안에 들어가는 썸네일이다. 글 없이 `media` 만 주면 안쪽 여백이 줄어든다. `motion`(`weak`·`strong`)을 주면 나타날 때 아래에서 올라온다 — 방금 보내거나 받은 메시지에만 준다. 처음 그리는 대화에는 주지 않는다. `className`·`style`·`ref` 는 `<li>` 에 붙는다.
+
+**쓰지 않는다.** 날짜·상태 안내 줄은 MessageEvent 를 쓴다.
+
+```tsx
+<MessageThread>
+  <Message side="end" time="오후 2:12" dateTime="2026-10-22T14:12" motion="weak">
+    방금 보낸 메시지
+  </Message>
+</MessageThread>
+```
+
+**모션.** enter(opt, `motion`). 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `time` | `ReactNode` |  |  |
+| `name` | `ReactNode` |  |  |
+| `motion` | `'strong' \| 'weak'` |  |  |
+| `side` | `'end' \| 'start'` |  | `'start'` |
+| `media` | `ReactNode` |  |  |
+| `dateTime` | `string` |  |  |
+
+이 밖에 React·HTML 기본 속성 267개를 받는다.
+
+## MessageEvent
+
+```ts
+import { MessageEvent } from '@nurihaus/web-design-system/message-event';   // 이 컴포넌트만 싣는다 (권장)
+import { MessageEvent } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** MessageThread 안 가운데에 놓는 날짜·상태 줄이다(예: "10월 22일", "캠페인이 확정됐어요"). 움직이지 않는다. `className`·`style`·`ref` 는 `<li>` 에 붙는다.
+
+**쓰지 않는다.** 누군가 보낸 말은 Message 를 쓴다. 화면 위에 잠깐 뜨는 알림은 Toast 를 쓴다.
+
+```tsx
+<MessageThread>
+  <MessageEvent>캠페인이 확정됐어요</MessageEvent>
+</MessageThread>
+```
+
+**모션.** 없음. 대화 가운데 날짜·상태 줄. 움직이지 않는다.
+
+### props
+
+이 컴포넌트가 따로 정의한 prop 은 없다.
+
+이 밖에 React·HTML 기본 속성 267개를 받는다.
+
+## MessageComposer
+
+```ts
+import { MessageComposer } from '@nurihaus/web-design-system/message-composer';   // 이 컴포넌트만 싣는다 (권장)
+import { MessageComposer } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 대화 화면 아래의 메시지 입력 줄이다. 입력 칸은 글자만큼 늘어나다가(다섯 줄쯤) 그 뒤로는 칸 안에서 스크롤한다. Enter 는 줄바꿈이고 보내기는 오른쪽 버튼으로만 한다. 값은 `value`·`defaultValue`·`onValueChange(value)` 로 다룬다. 보낼 수 있으면 버튼을 눌렀을 때 `onSend(value)` 가 불린다. **값을 스스로 비우지 않는다** — 보내기에 성공하면 쓰는 쪽이 `value` 를 비운다. 보낼 수 있는지는 기본으로 값이 공백만이 아닐 때다. 첨부만 보내는 화면은 `canSend` 를 직접 준다. 보낼 수 없거나 `disabled` 면 버튼이 회색(`aria-disabled`)이고 눌러도 보내지 않고 흔들린다. `loading` 동안은 Spinner 를 돌리고 보내지 않는다. `label`·`sendLabel` 은 입력 칸·보내기 버튼의 이름(aria-label)이다. `autoFocus` 는 사용자가 방금 입력을 연 화면(예: 다시 문의하기를 고른 뒤)에서만 준다. `maxLength` 는 입력 칸 최대 글자 수다. `leading` 은 입력 칸 왼쪽(첨부 아이콘 버튼), `attachments` 는 입력 줄 위(첨부 썸네일) 자리다. `track` 을 주면 실제로 보낼 때 `click` 을 한 번 보낸다(입력한 글은 싣지 않는다). `className`·`style`·`ref` 는 루트 `<div>` 에 붙는다. 화면 아래에 붙이려면 BottomBar 안에 둔다.
+
+**쓰지 않는다.** 폼의 여러 줄 입력은 TextArea, 한 줄 입력은 TextField 를 쓴다.
+
+```tsx
+<BottomBar>
+  <MessageComposer
+    label="메시지"
+    sendLabel="보내기"
+    placeholder="메시지를 입력하세요"
+    onSend={() => {}}
+  />
+</BottomBar>
+```
+
+**모션.** press · reject · busy(`loading`). 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `value` | `string` |  |  |
+| `defaultValue` | `string` |  |  |
+| `onValueChange` | `((value: string) => void)` |  |  |
+| `onSend` | `(value: string) => void` | 예 |  |
+| `canSend` | `boolean` |  |  |
+| `loading` | `boolean` |  |  |
+| `placeholder` | `string` |  |  |
+| `label` | `string` | 예 |  |
+| `sendLabel` | `string` | 예 |  |
+| `leading` | `ReactNode` |  |  |
+| `attachments` | `ReactNode` |  |  |
+| `disabled` | `boolean` |  |  |
+| `autoFocus` | `boolean` |  |  |
+| `maxLength` | `number` |  |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## BottomBar
+
+```ts
+import { BottomBar } from '@nurihaus/web-design-system/bottom-bar';   // 이 컴포넌트만 싣는다 (권장)
+import { BottomBar } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 화면 아래에 붙어 그 화면의 주 행동(CTAButton 하나나 둘)이나 입력 줄(MessageComposer)을 담는 바다. `position: sticky; bottom: 0` 이라 스크롤하는 조상의 마지막 자식으로 둔다. 바로 아래 자식들이 폭을 똑같이 나눠 갖는다. 기기 홈 막대(안전 영역)만큼 아래를 더 비운다. 스크롤해도 숨지 않는다. `className`·`style`·`ref` 는 루트 `<div>` 에 붙는다.
+
+**쓰지 않는다.** 화면을 오가는 주 메뉴는 BottomNav 를 쓴다.
+
+```tsx
+<BottomBar>
+  <CTAButton variant="ghost" size="l" text="거절" />
+  <CTAButton variant="primary" size="l" text="수락" />
+</BottomBar>
+```
+
+**모션.** 없음. 주 행동·입력을 담는 고정 바라 스크롤로 숨기지 않는다.
+
+### props
+
+이 컴포넌트가 따로 정의한 prop 은 없다.
+
+이 밖에 React·HTML 기본 속성 266개를 받는다.
+
+## MediaThumbnail
+
+```ts
+import { MediaThumbnail } from '@nurihaus/web-design-system/media-thumbnail';   // 이 컴포넌트만 싣는다 (권장)
+import { MediaThumbnail } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 사진·영상을 작은 썸네일로 보여 주고 누르면 화면 안에서 크게 볼 때 쓴다. 앱 웹뷰에서 원본 주소로 이동하면 앱을 벗어나므로 링크 대신 쓴다. `type`(`image`·`video`, 기본 `image`), `size`(`s` 64·`m` 96 정사각형, `l` 폭을 채우되 240 까지 4:3 — 말풍선 안). 올리는 중이면 `loading`, 실패하면 `invalid` 를 준다. 둘 다 누르면 열리지 않는다. `onRemove`·`removeLabel` 을 주면 오른쪽 위에 지우기 버튼이 생긴다. `closeLabel` 은 뷰어 닫기 버튼 이름이라 필수다. 영상처럼 `alt` 가 없으면 `viewLabel` 이 버튼 이름이 된다. `className`·`style` 은 감싸는 div 에 붙는다.
+
+**쓰지 않는다.** 누를 일 없는 사람 사진은 Avatar 를 쓴다. 썸네일 없이 버튼 하나로 크게 보이려면 MediaViewer 의 `trigger` 를 쓴다.
+
+```tsx
+<MediaThumbnail
+  src="https://example.com/photo.jpg"
+  alt="제품 사진"
+  closeLabel="닫기"
+  size="m"
+  onRemove={() => {}}
+  removeLabel="삭제"
+/>
+```
+
+**모션.** press · busy(`loading`). 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `size` | `'s' \| 'm' \| 'l'` |  | `'m'` |
+| `viewLabel` | `string` |  |  |
+| `loading` | `boolean` |  |  |
+| `invalid` | `boolean` |  |  |
+| `onRemove` | `(() => void)` |  |  |
+| `removeLabel` | `string` |  |  |
+| `src` | `string` | 예 |  |
+| `type` | `'video' \| 'image'` |  | `'image'` |
+| `alt` | `string` |  |  |
+| `closeLabel` | `string` | 예 |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## MediaViewer
+
+```ts
+import { MediaViewer } from '@nurihaus/web-design-system/media-viewer';   // 이 컴포넌트만 싣는다 (권장)
+import { MediaViewer } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 사진·영상 하나를 화면 전체에 띄워 볼 때 쓴다. 검은 바탕 위에 비율을 지켜 가운데 놓고, 영상은 열린 동안만 재생한다(닫으면 멈춘다). `trigger` 에 넘긴 요소를 누르면 열리고, `open`·`defaultOpen`·`onOpenChange` 로 제어한다. `closeLabel` 은 오른쪽 위 닫기 버튼 이름이라 필수다. 접근성 이름은 `title`, 없으면 `alt` 다(화면에는 안 보인다). Escape·닫기 버튼으로 닫힌다. `className`·`style` 은 화면 전체를 덮는 dialog 에 붙는다.
+
+**쓰지 않는다.** 썸네일을 누르면 여는 경우는 MediaThumbnail 이 뷰어를 같이 그린다. 사진 여러 장을 넘겨 보는 갤러리는 아직 없다.
+
+```tsx
+<MediaViewer open src="https://example.com/photo.jpg" alt="제품 사진" closeLabel="닫기" onOpenChange={() => {}} />
+```
+
+**모션.** enter · exit. 토큰 값과 규칙은 `motion.md`.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `trigger` | `ReactElement<any, string \| JSXElementConstructor<any>>` |  |  |
+| `title` | `string` |  |  |
+| `open` | `boolean` |  |  |
+| `defaultOpen` | `boolean` |  |  |
+| `onOpenChange` | `((open: boolean) => void)` |  |  |
+| `src` | `string` | 예 |  |
+| `type` | `'video' \| 'image'` |  | `'image'` |
+| `alt` | `string` |  |  |
+| `closeLabel` | `string` | 예 |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
 ## LogProvider
 
 ```ts
@@ -1344,6 +1961,8 @@ LogProvider 가 없거나 `track` 을 주지 않으면 아무것도 보내지
 </LogProvider>
 ```
 
+**모션.** 없음. DOM 을 그리지 않는다.
+
 ### props
 
 | prop | 타입 | 필수 | 기본값 |
@@ -1351,6 +1970,33 @@ LogProvider 가 없거나 `track` 을 주지 않으면 아무것도 보내지
 | `onEvent` | `(event: LogEvent) => void` | 예 |  |
 | `children` | `ReactNode` |  |  |
 
+## MotionProvider
+
+```ts
+import { MotionProvider } from '@nurihaus/web-design-system/motion';   // 이 컴포넌트만 싣는다 (권장)
+import { MotionProvider } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 앱 루트에 한 번 둔다. 구현층이 `motion` 인 모션 토큰(스프링·presence, `motion.md`)을 쓰는 컴포넌트가 이 아래에서 움직인다. 안에서 motion 컴포넌트를 직접 쓸 때는 `m.div` 처럼 `motion/react` 의 `m` 을 쓴다. `motion.div` 를 쓰면 개발 빌드에서 오류가 난다. `reducedMotion` 기본값 `'user'` 는 OS 의 동작 줄이기 설정을 따른다.
+`motion` 은 peerDependency 이고 React 18 이상에서만 동작한다. CSS 로 움직이는 모션은 이 Provider 없이도 같은 설정을 따른다.
+
+**쓰지 않는다.** 화면마다 겹쳐 두지 않는다. 겹쳐도 동작은 같지만 안쪽 `reducedMotion` 이 바깥 것을 가린다. 모션을 끄려고 Provider 를 빼지 않는다. `reducedMotion="always"` 를 준다.
+
+```tsx
+<MotionProvider>
+  <CTAButton text="저장" />
+</MotionProvider>
+```
+
+**모션.** 없음. DOM 을 그리지 않는다. 다른 컴포넌트의 motion 층이 이 아래에서 돈다.
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `reducedMotion` | `'user' \| 'always' \| 'never'` |  | `'user'` |
+| `children` | `ReactNode` |  |  |
+
 ## 아직 없는 것
 
 아래는 디자인 시스템에 없다. 비슷한 이름의 컴포넌트를 지어내 import 하지 않는다.