@nurihaus/web-design-system 3.0.0 → 3.0.3

package/dist/ai/components.md

@@ -0,0 +1,742 @@
+<!-- scripts/build-ai-docs.mjs 가 만든다. props 표는 타입에서, 설명은 각 컴포넌트 폴더의 usage.md 에서 온다. -->
+
+# @nurihaus/web-design-system 컴포넌트
+
+화면을 만들 때 아래 컴포넌트가 있으면 직접 만들지 말고 이것을 쓴다. 색·간격·글자는 같은 폴더의 `tokens.md` 변수만 쓴다.
+
+## CSS 가져오기
+
+앱에서 한 번만 가져온다. 둘 중 하나를 고른다.
+
+```ts
+import '@nurihaus/web-design-system/styles.css';      // 토큰 + 글꼴 스택 + 리셋 + 컴포넌트. 글꼴 파일은 앱이 불러온다
+
+import '@nurihaus/web-design-system/tokens.css';      // .nuri-theme 글꼴 스택 없이 쓸 때
+import '@nurihaus/web-design-system/reset.css';
+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` 로 바꾼다.
+
+**커스텀은 `className` 과 `style` 로 한다.** 모든 컴포넌트가 둘을 받아 루트 요소에 붙인다(TextField 는 입력 상자, DataTable 은 `<table>`). variant 가 정한 색을 className 으로 덮으려면 `.cta-button.variant-primary` 보다 구체적인 선택자가 필요하다. 색·간격·글자 값은 `tokens.md` 의 변수만 쓴다.
+
+**상태는 prop 으로 넘긴다.** `disabled`, `loading`, `isError`, `open`, `checked` 처럼 컴포넌트가 받는 상태 prop 을 쓰고, 클래스를 직접 붙여 상태를 흉내 내지 않는다. 값이 있는 컴포넌트는 `value`/`onValueChange`(제어) 또는 `defaultValue`(비제어) 둘 중 하나로 쓴다.
+
+**Tooltip 이 여러 개면 `TooltipProvider` 로 감싼다.** 앱 루트에 한 번 두면 된다. 조건이 맞을 때만 띄우려면 `open` 을 제어하지 말고 `disabled` 를 쓴다.
+
+**없는 것은 지어내지 않는다.** 이 문서 끝의 "아직 없는 것" 표에 있는 컴포넌트는 없다. 없는 prop · variant · 토큰 이름도 만들지 않는다. 틀린 variant 나 size 값은 타입 오류가 난다.
+
+## 목록
+
+- [Avatar](#avatar)
+- [CTAButton](#ctabutton)
+- [OptionBadge](#optionbadge)
+- [IconTextBadge](#icontextbadge)
+- [IconTextOptionBadge](#icontextoptionbadge)
+- [DataTable](#datatable)
+- [TextField](#textfield)
+- [Radio](#radio)
+- [Checkbox](#checkbox)
+- [DropDown](#dropdown)
+- [CollapsibleMenu](#collapsiblemenu)
+- [Text](#text)
+- [Tooltip](#tooltip)
+- [TooltipProvider](#tooltipprovider)
+- [Tabs](#tabs)
+- [ModalWithDoubleButton](#modalwithdoublebutton)
+- [Spinner](#spinner)
+- [InlineLoading](#inlineloading)
+- [OverlayLoading](#overlayloading)
+
+## Avatar
+
+```ts
+import { Avatar } from '@nurihaus/web-design-system/avatar';   // 이 컴포넌트만 싣는다 (권장)
+import { Avatar } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 사용자 프로필 이미지를 원형으로 보여줄 때 쓴다. `src`가 없거나 이미지를 불러오지 못하면 기본 아바타 아이콘이 나오고, `badgeOption`에 넣은 요소는 오른쪽 아래에 겹쳐 표시된다.
+
+**쓰지 않는다.** 프로필이 아닌 일반 이미지나 사각형 썸네일에는 쓰지 않는다. 아이콘과 이름을 한 줄로 묶은 라벨이 필요하면 IconTextBadge를 쓴다.
+
+```tsx
+<Avatar size="m" src="https://placehold.co/80x80" alt="프로필 이미지" />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `size` | `'s' \| 'm' \| 'l' \| 'xl'` | 예 | `'m'` |
+| `badgeOption` | `ReactNode` |  |  |
+| `src` | `string` |  |  |
+| `alt` | `string` |  |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## CTAButton
+
+```ts
+import { CTAButton } from '@nurihaus/web-design-system/cta-button';   // 이 컴포넌트만 싣는다 (권장)
+import { CTAButton } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 저장, 확인, 다음 단계처럼 사용자가 실행하는 동작 버튼에 쓴다. `variant`로 강조 단계를 고르고, `loading`이 true면 `text` 대신 Spinner가 표시된다.
+
+**쓰지 않는다.** 확인과 취소 두 버튼을 가진 대화상자는 버튼을 직접 배치하지 말고 ModalWithDoubleButton을 쓴다. 화면 안의 패널 전환은 Tabs, 사이드 메뉴 항목은 CollapsibleMenu를 쓴다.
+
+```tsx
+<CTAButton variant="primary" size="m" text="저장" onClick={() => {}} />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'m'` |
+| `text` | `ReactNode` | 예 |  |
+| `variant` | `'neutral' \| 'primary' \| 'outlined' \| 'secondary' \| 'ghost' \| 'confirm'` |  | `'primary'` |
+| `leftIcon` | `ReactNode` |  |  |
+| `rightIcon` | `ReactNode` |  |  |
+| `loading` | `boolean` |  |  |
+
+이 밖에 React·HTML 기본 속성 276개를 받는다.
+
+## OptionBadge
+
+```ts
+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`을 주면 마우스를 올렸을 때 설명이 뜬다.
+
+**쓰지 않는다.** 아이콘이 함께 필요하면 IconTextBadge를, 아이콘과 텍스트 오른쪽에 수치 같은 부가 값까지 붙여야 하면 IconTextOptionBadge를 쓴다. 클릭 동작이 필요한 요소에는 CTAButton을 쓴다.
+
+```tsx
+<OptionBadge option="진행 중" variant="primary" size="s" width="fit-content" />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'outlined'` |  | `'neutral'` |
+| `width` | `string \| number` |  | `'100%'` |
+| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'xl'` |
+| `option` | `ReactNode` | 예 |  |
+| `style` | `CSSProperties` |  |  |
+| `tooltip` | `{ content: ReactNode; position?: 'bottom' \| 'left' \| 'right' \| 'top' \| undefined; delayDuration?: number \| undefined; }` |  |  |
+| `asChild` | `boolean` |  |  |
+| `className` | `string` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## IconTextBadge
+
+```ts
+import { IconTextBadge } from '@nurihaus/web-design-system/icon-text-badge';   // 이 컴포넌트만 싣는다 (권장)
+import { IconTextBadge } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 아이콘과 텍스트를 한 줄로 묶어 보여줄 때 쓴다. SNS 채널처럼 아이콘으로 구분되는 값에 맞고, `tooltip`을 주면 마우스를 올렸을 때 설명이 뜬다.
+
+**쓰지 않는다.** 아이콘 없이 텍스트만 있으면 OptionBadge를 쓴다. 오른쪽에 부가 값을 붙여야 하면 IconTextOptionBadge를 쓴다.
+
+```tsx
+<IconTextBadge
+  icon={<img src="https://placehold.co/18x18" alt="" />}
+  text="Instagram"
+  size="s"
+  width="fit-content"
+  tooltip={{ content: '연결된 채널', position: 'top' }}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'outlined'` |  | `'neutral'` |
+| `width` | `string \| number` |  | `'100%'` |
+| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'xl'` |
+| `icon` | `ReactNode` | 예 |  |
+| `text` | `ReactNode` | 예 |  |
+| `style` | `CSSProperties` |  |  |
+| `tooltip` | `{ content: ReactNode; position?: 'bottom' \| 'left' \| 'right' \| 'top' \| undefined; delayDuration?: number \| undefined; }` |  |  |
+| `asChild` | `boolean` |  |  |
+| `className` | `string` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## IconTextOptionBadge
+
+```ts
+import { IconTextOptionBadge } from '@nurihaus/web-design-system/icon-text-option-badge';   // 이 컴포넌트만 싣는다 (권장)
+import { IconTextOptionBadge } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 왼쪽에 아이콘과 텍스트, 오른쪽에 부가 값(`option`)을 함께 보여줄 때 쓴다. 채널 이름과 팔로워 수를 한 배지에 담는 경우가 이에 해당한다.
+
+**쓰지 않는다.** 이 배지는 `tooltip`을 받지 않으므로 툴팁이 필요하면 IconTextBadge를 쓴다. 부가 값이 없으면 IconTextBadge나 OptionBadge를 쓴다.
+
+```tsx
+<IconTextOptionBadge
+  icon={<img src="https://placehold.co/18x18" alt="" />}
+  text="Instagram"
+  option="2.4K"
+  size="s"
+  width="fit-content"
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `variant` | `'neutral' \| 'primary' \| 'danger' \| 'outlined'` |  | `'neutral'` |
+| `width` | `string \| number` |  | `'100%'` |
+| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'xl'` |
+| `icon` | `ReactNode` | 예 |  |
+| `text` | `ReactNode` | 예 |  |
+| `option` | `ReactNode` | 예 |  |
+| `style` | `CSSProperties` |  |  |
+| `className` | `string` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## DataTable
+
+```ts
+import { DataTable } from '@nurihaus/web-design-system/data-table';   // 이 컴포넌트만 싣는다 (권장)
+import { DataTable } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 여러 레코드를 열 단위로 나열하는 목록 화면에 쓴다. 이름과 달리 `rows`는 헤더 열 정의(`id`, 헤더 내용)이고 `columns`는 데이터 행 배열이며, 각 데이터 행은 `rows`의 모든 `id`를 키로 가진다. 열 너비는 셀 내용의 너비를 따르므로 같은 열의 헤더와 셀 내용에 같은 너비를 준다.
+
+**쓰지 않는다.** 정렬, 페이지네이션, 행 선택, 빈 상태 표시는 내장되어 있지 않으므로 데이터를 바깥에서 가공해 넘기고 빈 목록은 따로 그린다. 헤더는 위에 고정되고 `fixedRowsIndex`로 왼쪽 열을 고정할 수 있지만, 그 외의 표 동작이 필요하면 직접 만든다.
+
+```tsx
+<DataTable
+  rows={[
+    { id: 'name', value: <div style={{ width: '160px' }}>이름</div> },
+    { id: 'status', value: <div style={{ width: '120px' }}>상태</div> },
+  ] as const}
+  columns={[
+    {
+      name: { value: <div style={{ width: '160px' }}>홍길동</div> },
+      status: { value: <div style={{ width: '120px' }}>대기</div>, onClickCell: () => {} },
+    },
+  ]}
+  fixedRowsIndex={1}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `rows` | `T` | 예 |  |
+| `columns` | `ColumnsType<T>` | 예 |  |
+| `fixedRowsIndex` | `number` |  | `0` |
+| `headerHeight` | `number` |  | `85` |
+| `rowHeight` | `number` |  | `60` |
+| `cellHeight` | `number` |  |  |
+| `className` | `string` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## TextField
+
+```ts
+import { TextField } from '@nurihaus/web-design-system/text-field';   // 이 컴포넌트만 싣는다 (권장)
+import { TextField } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 한 줄 텍스트를 입력받을 때 쓴다. 위 라벨(`title`), 아래 안내 문구(`helperText`), 좌우 아이콘을 함께 붙일 수 있고, `isError`가 true면 `helperText`가 오류 스타일로 바뀐다.
+
+**쓰지 않는다.** 여러 줄 입력은 지원하지 않는다(`<input>`만 렌더한다). 정해진 값 중에서 고르는 입력은 DropDown이나 Radio를 쓴다.
+
+```tsx
+<TextField
+  size="s"
+  width="320px"
+  name="title"
+  title="제목"
+  placeholder="제목을 입력하세요"
+  helperText="50자 이내로 입력하세요"
+  onChange={() => {}}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |
+| `size` | `'s' \| 'm'` | 예 | `'s'` |
+| `title` | `ReactNode` |  |  |
+| `name` | `string` | 예 |  |
+| `value` | `string` |  |  |
+| `defaultValue` | `string` |  |  |
+| `leftIcon` | `ReactNode` |  |  |
+| `rightIcon` | `ReactNode` |  |  |
+| `width` | `string \| number` | 예 | `'100%'` |
+| `helperText` | `ReactNode` |  |  |
+| `isError` | `boolean` |  |  |
+
+이 밖에 React·HTML 기본 속성 289개를 받는다.
+
+## Radio
+
+```ts
+import { Radio } from '@nurihaus/web-design-system/radio';   // 이 컴포넌트만 싣는다 (권장)
+import { Radio } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 몇 개의 선택지를 모두 펼쳐 보여주고 그중 하나만 고르게 할 때 쓴다. 선택 상태는 항상 부모가 가지므로 `onChange`에서 받은 id로 `selected`를 갱신해야 선택이 바뀐다.
+
+**쓰지 않는다.** 여러 개를 동시에 고르면 Checkbox를 쓴다. 선택지가 많아 모두 펼치기 어려우면 DropDown을 쓴다.
+
+```tsx
+<Radio
+  options={[
+    { id: 'all', label: '전체' },
+    { id: 'active', label: '활성' },
+    { id: 'inactive', label: '비활성', disabled: true },
+  ]}
+  selected="all"
+  onChange={() => {}}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `options` | `{ id: string; label: ReactNode; disabled?: boolean \| undefined; }[]` | 예 |  |
+| `selected` | `string \| null` |  |  |
+| `onChange` | `((id: string \| null) => void)` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## Checkbox
+
+```ts
+import { Checkbox } from '@nurihaus/web-design-system/check-box';   // 이 컴포넌트만 싣는다 (권장)
+import { Checkbox } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 동의 여부처럼 켜고 끄는 값 하나를 받거나, 목록의 항목을 각각 독립적으로 선택할 때 쓴다. `onChange`는 바뀐 체크 상태(boolean)를 받는다.
+
+**쓰지 않는다.** 여러 선택지 중 하나만 골라야 하면 Radio를, 목록에서 값 하나를 고르면 DropDown을 쓴다.
+
+```tsx
+<Checkbox id="agree-terms" label="약관에 동의합니다" checked={false} onChange={() => {}} />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | 예 |  |
+| `size` | `'s' \| 'm' \| 'l'` |  | `'m'` |
+| `className` | `string` |  |  |
+| `onClick` | `((checked: boolean) => void)` |  |  |
+| `checked` | `boolean` |  |  |
+| `onChange` | `((checked: boolean) => void)` |  |  |
+| `id` | `string` | 예 |  |
+| `disabled` | `boolean` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## DropDown
+
+```ts
+import { DropDown } from '@nurihaus/web-design-system/drop-down';   // 이 컴포넌트만 싣는다 (권장)
+import { DropDown } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 펼쳐지는 목록에서 값 하나를 고를 때 쓴다. 보통 `options`를 넘기고, 목록 영역을 직접 그려야 하면 `renderOption`을 쓰되 이때는 항목 선택 처리와 닫기(`close`)를 직접 해야 한다.
+
+**쓰지 않는다.** 여러 값을 동시에 고르는 다중 선택은 지원하지 않는다. 선택지가 적어 모두 펼쳐 보여주는 편이 나으면 Radio를, 페이지 이동 메뉴는 CollapsibleMenu를 쓴다.
+
+```tsx
+<DropDown
+  size="s"
+  width="240px"
+  placeholder="상태 선택"
+  options={[
+    { label: '전체', value: 'all' },
+    { label: '활성', value: 'active' },
+    { label: '비활성', value: 'inactive' },
+  ]}
+  value="all"
+  onValueChange={() => {}}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `size` | `'s' \| 'm'` |  | `'s'` |
+| `defaultValue` | `string` |  |  |
+| `value` | `string` |  |  |
+| `onValueChange` | `((value: string) => void)` |  |  |
+| `renderValue` | `((value?: string \| undefined) => ReactNode)` |  |  |
+| `options` | `{ label: ReactNode; value: string; disabled?: boolean \| undefined; }[]` |  |  |
+| `renderOption` | `((props: { isOpen: boolean; close: () => void; }) => ReactNode)` |  |  |
+| `placeholder` | `ReactNode` |  |  |
+| `disabled` | `boolean` |  |  |
+| `defaultOpen` | `boolean` |  |  |
+| `open` | `boolean` |  |  |
+| `onOpenChange` | `((open: boolean) => void)` |  |  |
+| `leftIcon` | `ReactNode` |  |  |
+| `rightIcon` | `ReactNode` |  |  |
+| `width` | `string \| number` |  | `'fit-content'` |
+| `side` | `'bottom' \| 'left' \| 'right' \| 'top'` |  |  |
+| `align` | `'center' \| 'start' \| 'end'` |  |  |
+| `position` | `'popper' \| 'item-aligned'` |  |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## CollapsibleMenu
+
+```ts
+import { CollapsibleMenu } from '@nurihaus/web-design-system/collapsible-menu';   // 이 컴포넌트만 싣는다 (권장)
+import { CollapsibleMenu } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 사이드바 같은 세로 내비게이션 메뉴에 쓴다. `children`이 있는 항목은 펼치고 접는 그룹이 되고, 없는 항목은 `href`가 있으면 링크, 없으면 버튼으로 렌더되며, `activeKey` 항목과 그 상위 그룹이 강조된다. 링크는 기본으로 `<a>`다. 라우터의 링크로 바꾸려면 `linkComponent`에 넘긴다. 받는 props는 `href`·`className`·`children`·`onClick`·`aria-current`·`aria-disabled`이고, 그대로 링크에 전달하면 된다.
+
+**쓰지 않는다.** 같은 화면 안에서 패널을 바꾸는 용도는 Tabs를 쓴다. 본문 콘텐츠를 접고 펼치는 아코디언 용도로는 쓰지 않는다(`<nav>`로 렌더된다). 값을 고르는 폼 입력은 DropDown을 쓴다.
+
+Next.js 에서는 `next/link` 의 `Link` 를 그대로 넘긴다.
+
+```ts
+import Link from 'next/link';
+
+// <CollapsibleMenu linkComponent={Link} items={…} />
+```
+
+```tsx
+<CollapsibleMenu
+  activeKey="user.search"
+  onActiveKeyChange={() => {}}
+  linkComponent={(props) => <a {...props} />}
+  items={[
+    { key: 'dashboard', item: <span>대시보드</span>, href: '/dashboard' },
+    {
+      key: 'users',
+      item: <span>사용자</span>,
+      defaultOpen: true,
+      children: [
+        { key: 'user.search', item: <span>사용자 검색</span> },
+        { key: 'user.list', item: <span>사용자 목록</span> },
+      ],
+    },
+  ]}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `size` | `'s' \| 'm'` |  | `'s'` |
+| `items` | `CollapsibleMenuItem[]` | 예 |  |
+| `activeKey` | `string` |  |  |
+| `onActiveKeyChange` | `((key: string) => void)` |  |  |
+| `indent` | `number` |  | `12` |
+| `chevron` | `ReactNode` |  |  |
+| `width` | `string \| number` |  | `'240px'` |
+| `linkComponent` | `ComponentType<CollapsibleMenuLinkProps>` |  |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## Text
+
+```ts
+import { Text } from '@nurihaus/web-design-system/text';   // 이 컴포넌트만 싣는다 (권장)
+import { Text } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 제목, 본문, 설명처럼 화면에 글자를 표시할 때 쓴다. `size`와 `weight`로 타이포그래피 토큰을, `color`로 색상 토큰을 적용하고, `as`로 태그를 고른다(기본값 `p`).
+
+**쓰지 않는다.** 클릭 가능한 텍스트에는 쓰지 않는다. `onClick`, `id` 같은 HTML 속성은 타입상 받지만 요소에 전달되지 않고 `className`과 `style`만 전달된다. 버튼 문구는 CTAButton의 `text`에 문자열로 넘긴다.
+
+```tsx
+<Text as="h2" text="캠페인 목록" size="xl" weight="bold" color="grey-scale-900" />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `text` | `ReactNode` | 예 |  |
+| `size` | `'base' \| 'xl' \| 'xsm' \| 'sm' \| 'lg' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl'` | 예 |  |
+| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold' \| 'extrabold'` | 예 |  |
+| `color` | `'transparent' \| 'purple-50' \| 'purple-100' \| 'purple-200' \| 'purple-300' \| 'purple-400' \| 'purple-500' \| 'purple-600' \| 'purple-700' \| 'purple-800' \| 'purple-900' \| 'grey-scale-50' \| 'grey-scale-100' \| 'grey-scale-200' \| 'grey-scale-300' \| 'grey-scale-400' \| 'grey-scale-500' \| 'grey-scale-600' \| 'grey-scale-700' \| 'grey-scale-800' \| 'grey-scale-900' \| 'accent-red-50' \| 'accent-red-100' \| 'accent-red-200' \| 'accent-red-300' \| 'accent-red-400' \| 'accent-red-500' \| 'accent-red-600' \| 'accent-red-700' \| 'accent-red-800' \| 'accent-red-900' \| 'accent-pink-50' \| 'accent-pink-100' \| 'accent-pink-200' \| 'accent-pink-300' \| 'accent-pink-400' \| 'accent-pink-500' \| 'accent-pink-600' \| 'accent-pink-700' \| 'accent-pink-800' \| 'accent-pink-900' \| 'accent-magenta-50' \| 'accent-magenta-100' \| 'accent-magenta-200' \| 'accent-magenta-300' \| 'accent-magenta-400' \| 'accent-magenta-500' \| 'accent-magenta-600' \| 'accent-magenta-700' \| 'accent-magenta-800' \| 'accent-magenta-900' \| 'accent-blue-50' \| 'accent-blue-100' \| 'accent-blue-200' \| 'accent-blue-300' \| 'accent-blue-400' \| 'accent-blue-500' \| 'accent-blue-600' \| 'accent-blue-700' \| 'accent-blue-800' \| 'accent-blue-900' \| 'accent-mint-50' \| 'accent-mint-100' \| 'accent-mint-200' \| 'accent-mint-300' \| 'accent-mint-400' \| 'accent-mint-500' \| 'accent-mint-600' \| 'accent-mint-700' \| 'accent-mint-800' \| 'accent-mint-900' \| 'accent-green-50' \| 'accent-green-100' \| 'accent-green-200' \| 'accent-green-300' \| 'accent-green-400' \| 'accent-green-500' \| 'accent-green-600' \| 'accent-green-700' \| 'accent-green-800' \| 'accent-green-900' \| 'accent-yellow-50' \| 'accent-yellow-100' \| 'accent-yellow-200' \| 'accent-yellow-300' \| 'accent-yellow-400' \| 'accent-yellow-500' \| 'accent-yellow-600' \| 'accent-yellow-700' \| 'accent-yellow-800' \| 'accent-yellow-900' \| 'accent-orange-50' \| 'accent-orange-100' \| 'accent-orange-200' \| 'accent-orange-300' \| 'accent-orange-400' \| 'accent-orange-500' \| 'accent-orange-600' \| 'accent-orange-700' \| 'accent-orange-800' \| 'accent-orange-900' \| 'black' \| 'white'` |  |  |
+| `textDecoration` | `TextDecoration<string \| number>` |  |  |
+| `textAlign` | `TextAlign` |  |  |
+| `wordBreak` | `WordBreak` |  |  |
+| `whiteSpace` | `WhiteSpace` |  |  |
+| `as` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'p' \| 'span' \| 'strong'` |  |  |
+
+이 밖에 React·HTML 기본 속성 265개를 받는다.
+
+## Tooltip
+
+```ts
+import { Tooltip } from '@nurihaus/web-design-system/tooltip';   // 이 컴포넌트만 싣는다 (권장)
+import { Tooltip } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 아이콘이나 짧은 라벨에 마우스를 올렸을 때 짧은 설명을 띄울 때 쓴다. `trigger`에는 DOM 요소 하나(예: `<span>`)를 넘기고 `direction`으로 뜨는 방향을 고른다. 조건이 맞을 때만 띄우려면 `open`을 제어하지 말고 `disabled`를 쓴다(예: 사이드바가 접혔을 때만 `disabled={!collapsed}`). `disabled`이면 `trigger`만 그려 툴팁이 열린 채 남지 않는다.
+
+**쓰지 않는다.** 툴팁 안에 링크나 버튼처럼 클릭할 내용을 넣지 않는다. 툴팁 위로 마우스를 옮기면 닫힌다. 배지에 설명을 붙일 때는 OptionBadge, IconTextBadge의 `tooltip` prop을 쓴다.
+
+```tsx
+<Tooltip trigger={<span>도움말</span>} content="최근 30일 기준입니다." direction="top" disabled={false} />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `trigger` | `ReactNode` | 예 |  |
+| `content` | `ReactNode` | 예 |  |
+| `direction` | `'bottom' \| 'left' \| 'right' \| 'top'` |  | `'bottom'` |
+| `disabled` | `boolean` |  | `false` |
+| `defaultOpen` | `boolean` |  |  |
+| `open` | `boolean` |  |  |
+| `onOpenChange` | `((open: boolean) => void)` |  |  |
+| `delayDuration` | `number` |  |  |
+| `disableHoverableContent` | `boolean` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## TooltipProvider
+
+```ts
+import { TooltipProvider } from '@nurihaus/web-design-system/tooltip';   // 이 컴포넌트만 싣는다 (권장)
+import { TooltipProvider } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 툴팁이 여러 개 모인 영역(사이드바, 툴바)을 감싼다. 하나를 보고 옆으로 옮기면 `skipDelayDuration` 동안은 지연 없이 바로 뜬다. 앱 루트에 한 번 두어도 된다. 안에 있는 Tooltip과 배지 툴팁은 이 Provider를 같이 쓴다. `delayDuration` 기본값은 100ms다.
+
+**쓰지 않는다.** 툴팁이 하나뿐이면 감싸지 않는다. Tooltip은 Provider 없이도 동작한다.
+
+```tsx
+<TooltipProvider skipDelayDuration={300}>
+  <Tooltip trigger={<span>대시보드</span>} content="대시보드" direction="right" />
+  <Tooltip trigger={<span>사용자</span>} content="사용자" direction="right" />
+</TooltipProvider>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | 예 |  |
+| `delayDuration` | `number` |  | `100` |
+| `skipDelayDuration` | `number` |  |  |
+| `disableHoverableContent` | `boolean` |  |  |
+
+## Tabs
+
+```ts
+import { Tabs } from '@nurihaus/web-design-system/tabs';   // 이 컴포넌트만 싣는다 (권장)
+import { Tabs } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 같은 화면 안에서 여러 패널 중 하나를 골라 보여줄 때 쓴다. `items`의 각 항목이 탭 라벨과 패널 내용을 함께 가지며, `defaultValue`나 `value`를 주지 않으면 처음에 어떤 탭도 선택되지 않는다.
+
+**쓰지 않는다.** 다른 페이지로 이동하는 내비게이션은 CollapsibleMenu를 쓴다. 폼에서 값 하나를 고르는 입력은 Radio를 쓴다.
+
+```tsx
+<Tabs
+  variant="underline"
+  defaultValue="info"
+  items={[
+    { id: 'info', label: '기본 정보', content: <div>기본 정보 패널</div> },
+    { id: 'history', label: '변경 이력', content: <div>변경 이력 패널</div> },
+  ]}
+/>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `items` | `TabsItem[]` | 예 |  |
+| `variant` | `'underline' \| 'filled'` |  | `'underline'` |
+| `value` | `TabsValue` |  |  |
+| `defaultValue` | `TabsValue` |  |  |
+| `onValueChange` | `((id: TabsValue) => void)` |  |  |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## ModalWithDoubleButton
+
+```ts
+import { ModalWithDoubleButton } from '@nurihaus/web-design-system/modal-with-double-button';   // 이 컴포넌트만 싣는다 (권장)
+import { ModalWithDoubleButton } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 삭제 확인처럼 제목, 설명, 버튼 두 개로 된 확인 대화상자에 쓴다. `ModalWithDoubleButton.Row`는 버튼을 가로로, `ModalWithDoubleButton.Column`은 세로로 배치하며, `left`와 `right`는 CTAButton props를 그대로 받는다.
+
+**쓰지 않는다.** `open` prop이 없고 렌더되는 동안 항상 보이므로, 표시 여부는 부모가 조건부 렌더링으로 정하고 버튼 `onClick`에서 언마운트한다. `showCloseIcon`의 X 아이콘은 클릭해도 동작이 없으므로 닫기 수단으로 쓰지 않는다. 버튼이 하나이거나 세 개 이상인 모달은 이 라이브러리에 없다.
+
+```tsx
+<ModalWithDoubleButton.Row
+  title="항목을 삭제할까요?"
+  subTitle="삭제하면 되돌릴 수 없습니다."
+  left={{ text: '취소', onClick: () => {} }}
+  right={{ text: '삭제', variant: 'primary', onClick: () => {} }}
+/>
+```
+
+### ModalWithDoubleButton.Row props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `title` | `string` |  |  |
+| `subTitle` | `ReactNode` |  |  |
+| `titleIcon` | `ReactNode` |  |  |
+| `content` | `ReactNode` |  |  |
+| `showCloseIcon` | `boolean` |  |  |
+| `showTitleLine` | `boolean` |  |  |
+| `left` | `CTAButtonProps` | 예 |  |
+| `right` | `CTAButtonProps` | 예 |  |
+| `size` | `'s' \| 'm' \| 'l'` |  | `'m'` |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+### ModalWithDoubleButton.Column props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `title` | `string` |  |  |
+| `subTitle` | `ReactNode` |  |  |
+| `titleIcon` | `ReactNode` |  |  |
+| `content` | `ReactNode` |  |  |
+| `showCloseIcon` | `boolean` |  |  |
+| `showTitleLine` | `boolean` |  |  |
+| `left` | `CTAButtonProps` | 예 |  |
+| `right` | `CTAButtonProps` | 예 |  |
+| `size` | `'s' \| 'm' \| 'l'` |  | `'m'` |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## Spinner
+
+```ts
+import { Spinner } from '@nurihaus/web-design-system/loading';   // 이 컴포넌트만 싣는다 (권장)
+import { Spinner } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 20px 고정 크기의 회전 표시만 필요할 때 쓴다. 작은 영역이나 다른 요소 옆에 붙인다. 링 색은 CSS `color` 를 따르고 기본은 `grey-scale-200` 이다. 색 prop 은 없다. 다른 색은 `className` 이나 `style` 로 `color` 를 준다(감싸는 요소의 color 는 물려받지 않는다).
+
+**쓰지 않는다.** 버튼 로딩은 CTAButton의 `loading`을 쓴다(내부에서 Spinner를 그린다). 크기나 가로 정렬을 정해야 하면 InlineLoading을, 화면 전체를 막아야 하면 OverlayLoading을 쓴다.
+
+```tsx
+<Spinner style={{ color: 'var(--color-grey-scale-400)' }} />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## InlineLoading
+
+```ts
+import { InlineLoading } from '@nurihaus/web-design-system/loading';   // 이 컴포넌트만 싣는다 (권장)
+import { InlineLoading } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 목록이나 카드 영역 안에서 데이터를 불러오는 동안 그 자리에 표시할 때 쓴다. `size`(px)로 크기를, `justifyContent`로 가로 정렬을 정한다. 링 색은 Spinner 와 같이 `className`·`style` 의 `color` 로 바꾼다.
+
+**쓰지 않는다.** 로딩 중 다른 조작을 막아야 하면 OverlayLoading을 쓴다. 버튼 안 로딩은 CTAButton의 `loading`을 쓴다.
+
+```tsx
+<InlineLoading size={24} justifyContent="center" />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `size` | `number` | 예 |  |
+| `justifyContent` | `'center' \| 'flex-start' \| 'flex-end' \| 'space-between'` |  | `'flex-start'` |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## OverlayLoading
+
+```ts
+import { OverlayLoading } from '@nurihaus/web-design-system/loading';   // 이 컴포넌트만 싣는다 (권장)
+import { OverlayLoading } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 저장이나 업로드처럼 끝날 때까지 화면 전체 조작을 막아야 할 때 쓴다. 화면 전체를 반투명 배경으로 덮고 가운데에 스피너와 `message`를 표시하며, `open`이 false면 아무것도 렌더하지 않는다. 스피너 색은 `className` 을 주고 `.my-overlay .base-spinner { color: … }` 처럼 바꾼다.
+
+**쓰지 않는다.** 화면 일부만 로딩 중이면 InlineLoading을, 버튼 하나만 로딩 중이면 CTAButton의 `loading`을 쓴다.
+
+```tsx
+<OverlayLoading open={true} message="저장 중입니다" />
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `open` | `boolean` |  | `true` |
+| `message` | `string` |  |  |
+| `backdropOpacity` | `number` |  | `0.6` |
+| `zIndex` | `number` |  | `1200` |
+| `className` | `string` |  |  |
+| `style` | `CSSProperties` |  |  |
+
+이 밖에 React·HTML 기본 속성 2개를 받는다.
+
+## 아직 없는 것
+
+아래는 디자인 시스템에 없다. 비슷한 이름의 컴포넌트를 지어내 import 하지 않는다.
+
+| 필요한 것 | 지금 있는 것 |
+| --- | --- |
+| 페이지네이션 | 없음 |
+| 토스트·스낵바 | 없음 |
+| 스위치(토글) | 없음. 켜고 끄는 값은 Checkbox |
+| 여러 줄 입력(textarea) | 없음. TextField 는 한 줄 `<input>` 이다 |
+| 날짜 선택 | 없음 |
+| 드로어·사이드 패널 | 없음 |
+| 스켈레톤 | 없음. 불러오는 중에는 InlineLoading |
+| 브레드크럼 | 없음 |
+| 아이콘 세트 | 없음. 패키지 안 아이콘은 컴포넌트 내부용이라 내보내지 않는다 |
+| 확인용이 아닌 일반 모달 | 없음. 버튼 두 개짜리 확인 모달 ModalWithDoubleButton 만 있다 |
+
+없는 것이 필요하면 쓰는 쪽 저장소에서 `tokens.md` 의 변수로 만든다. 그리고 디자인 시스템에 추가할 후보라고 알린다.