sellmate-design-system-react 3.0.0 → 3.2.0

package/dist/llms-full.txt

@@ -0,0 +1,3530 @@
+<!-- 자동 생성: npm run build (scripts/gen-llms.mjs). 직접 수정 금지. -->
+
+# sellmate-design-system-react — AI 에이전트 참조 문서
+
+사용 규칙(§1) · 토큰 어휘(§2) · 전체 컴포넌트 Props(§3) 를 한 파일에 담은 판본이다.
+
+## 1. 사용 규칙 (AGENTS.md 전문)
+
+# sellmate-design-system-react — 사용 규칙 (AGENTS.md)
+
+> **대상**: 이 패키지로 화면을 만드는 소비 앱의 개발자와 AI 코딩 에이전트(Claude 등).
+> 이 문서는 "무엇을 언제 쓰고, 무엇을 쓰면 안 되는지"의 단일 기준이다.
+> 개별 컴포넌트의 상세 Props/Events는 `node_modules/sellmate-design-system-react/dist/components/<이름>/README.md` 를 참조한다.
+
+## 0. 최우선 원칙 — 디자인 시스템 컴포넌트가 먼저다
+
+**화면 요소를 만들기 전에, 그 역할을 하는 컴포넌트가 이미 있는지 먼저 확인한다.**
+있으면 반드시 그것을 쓴다. 직접 만드는 것은 대응 컴포넌트가 **없다는 것을 확인한 뒤**의 최후 수단이다.
+
+```tsx
+❌ <button onClick={save}>저장</button>        ✅ <SButton label="저장" onClick={save} />
+❌ <table>…</table>                            ✅ <STable columns={columns} rows={rows} />
+❌ <div className="rounded border p-16">…</div> ✅ <SSectionHeaderCard>…</SSectionHeaderCard>
+❌ <ul><li>…</li></ul>                         ✅ <SList><SListItem title="…" /></SList>
+```
+
+"비슷하게 생긴 것을 직접 만드는 것"이 어색함의 가장 큰 원인이다. 대응 컴포넌트를 쓰면 색·간격·상태·접근성이 전부 따라온다.
+
+### 0-1. 전체 컴포넌트 인덱스
+
+무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props 는 `dist/components/<이름>/README.md` 참조.
+
+| 분류 | 컴포넌트 |
+| --- | --- |
+| **버튼·링크** | `SButton` `SGhostButton` `SDropdownButton` `STextLink` `SSwitch` `SToggle` |
+| **입력 (폼)** | `SForm` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioButton` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
+| **날짜·시간** | `SCalendar` `SDatePicker` `SDateRangePicker` `STimePicker` `STimeRangePicker` |
+| **표·목록** | `STable` `STableBar` `SKeyValueTable` `SList` `SListItem` `SDraggableItem` |
+| **레이아웃** | `SLayout` `SGnb` `SPage` `SSectionHeaderCard` `SCard` `SDivider` `SScrollArea` `SExpansionItem` |
+| **내비게이션** | `STabs` `SPagination` `SStepper` |
+| **표시·상태** | `STag` `SBadge` `SIcon` `SCallout` `SGuide` |
+| **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
+| **오버레이** | `STooltip` `SPopover` `SPopup` `SPortal` |
+| **모달** | `SModal.confirm()` `SModal.create()` + `SActionModal` `SConfirmModal` |
+| **알림** | `SToast` `SToastContainer` |
+
+표에 없는 UI 를 만들어야 할 때만 `div` 로 직접 조립하고, 그때도 §1-2 · §2 의 토큰 규칙을 지킨다.
+
+### 0-2. 프로젝트 설정
+
+설정(Tailwind v4 `theme.css` import, `@source` 지정, Next.js 주의사항)은 패키지 [README.md](./README.md)를 따른다. 이 문서는 설정이 끝난 상태에서의 **화면 작성 규칙**만 다룬다.
+
+---
+
+## 1. 절대 규칙 (금지 목록)
+
+AI 에이전트는 코드를 생성하기 전에 이 목록을 반드시 지킨다.
+
+### 1-1. 생 HTML 컨트롤 금지
+
+§0 원칙의 구체적 목록이다. 아래 요소는 **어떤 경우에도** 생 HTML 로 만들지 않는다.
+
+| 금지 | 대신 사용 |
+| --- | --- |
+| `<button>` | `SButton`, `SGhostButton`, `SDropdownButton`, `STextLink` |
+| `<input type="text/password/...">` | `SInput` |
+| `<input type="number">` | `SNumberInput` |
+| `<input type="checkbox">` | `SCheckbox`, `SToggle`, `SSwitch` |
+| `<input type="radio">` | `SRadio`, `SRadioButton` |
+| `<input type="file">` | `SFilePicker` |
+| `<select>` | `SSelect` |
+| `<textarea>` | `STextarea` |
+| `<table>` | `STable`, `SKeyValueTable` |
+| `<form>` | `SForm` |
+| `<dialog>`, 직접 만든 오버레이 | `SModal.confirm(...)`, `SModal.create(...)`, `SPopup` |
+| `alert()`, `confirm()` | `SToast`, `SModal.confirm(...)` |
+| 직접 만든 탭/페이지네이션/스텝퍼 | `STabs`, `SPagination`, `SStepper` |
+| `<ul>`/`<li>` 로 만든 목록 UI | `SList` + `SListItem` (드래그 정렬은 `SDraggableItem`) |
+| 직접 만든 섹션 카드(제목 바 + 본문 박스) | `SSectionHeaderCard` + `.Header` / `.Body` |
+| `<svg>` 직접 삽입, 이모지 아이콘 | `SIcon` |
+| `<hr>` | `SDivider` |
+| `<details>` / `<summary>` | `SExpansionItem` |
+| `<progress>` | `SLinearProgress`, `SCircleProgress` |
+| `<label>` (폼 레이블) | `SField` 의 `label` prop |
+| 직접 만든 카드·패널 박스 | `SCard`, `SSectionHeaderCard` |
+| 직접 만든 스크롤 영역 | `SScrollArea` |
+
+예외: 순수 레이아웃 요소(`div`, `section`, 시맨틱 `h1~h6`, `p`, `span`, `a`)는 허용. 단 스타일은 아래 규칙을 따른다.
+
+### 1-2. 임의 값(arbitrary literal) 금지
+
+Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
+
+```text
+❌ text-[14px]  font-[600]  bg-[#eee]  gap-[13px]  p-[10px]  rounded-[5px]  text-[#333]
+✅ typo-body-sm-default  text-fg-tertiary  bg-bg-frame  gap-12  p-8  rounded-md
+✅ w-[var(--sys-size-control-md-height)]   ← 토큰을 var()로 참조하는 것은 허용
+```
+
+- 하드코딩 hex/px/rem 리터럴은 어디에도 쓰지 않는다 (인라인 `style` 포함).
+- 인라인 `style`은 런타임 계산값(동적 width 등)에만 허용한다.
+
+**단, 디자인 토큰이 없는 속성의 임의 값은 정당하다.** 화면 고유의 레이아웃 치수가 여기 해당한다.
+
+```tsx
+✅ <div className="w-[280px] max-w-[1200px] grid-cols-[200px_1fr]" />   // 앱 고유 치수
+❌ <div className="text-[13px] bg-[#eee] gap-[13px] rounded-[5px]" />   // 토큰이 있는 속성
+```
+
+규칙은 **색 · 타이포 · 간격 · 모서리** 네 계열에만 적용된다 — 이 넷은 토큰이 이미 있으므로 임의 값은 곧 디자인 시스템 우회다.
+
+### 1-3. 타이포그래피는 프리셋으로만
+
+`text-14 font-bold` 같은 조합을 즉흥으로 만들지 않는다. §2-1의 `typo-*` 프리셋 클래스를 쓴다.
+
+### 1-4. 숫자는 무조건 `toLocaleString()`
+
+**숫자를 화면에 표시할 때는 예외 없이 `toLocaleString()` 을 거쳐 세 자리마다 콤마를 넣는다.**
+금액·수량·건수·재고 무엇이든, 테이블·상세·요약 문구 어디에 놓이든 같다.
+
+```tsx
+❌ <span>{price}원</span>              ❌ {`${qty}개`}         ❌ {String(count)}
+✅ <span>{price.toLocaleString()}원</span>
+✅ format: (v: number) => `${Number(v).toLocaleString()}개`
+```
+
+콤마 없는 `39000` 은 자릿수를 세어야 읽히지만 `39,000` 은 한눈에 읽힌다. 숫자를 그대로 출력하는 코드는 미완성으로 본다.
+
+전화번호·사업자번호처럼 하이픈이 들어가는 값은 애초에 숫자가 아니라 **서식이 정해진 문자열**이므로 이 규칙의 대상이 아니다.
+
+---
+
+## 2. 조합 어휘 — 컴포넌트 "사이"를 채울 때 쓰는 것들
+
+### 2-1. 타이포그래피 프리셋
+
+역할(role) → 크기 → 굵기 순으로 조합된 클래스가 이미 준비되어 있다.
+
+| 용도 | 클래스 |
+| --- | --- |
+| 페이지/섹션 제목 | `typo-heading-lg`(18px) · `typo-heading-md`(16px) · `typo-heading-sm`(14px) · `typo-heading-xs`(12px) |
+| 본문 | `typo-body-lg-*` (16px) · `typo-body-md-*`(14px) · `typo-body-sm-*`(12px) · `typo-body-xs-default`(11px) — `*` = `default`/`medium`/`bold` |
+| 테이블 | `typo-table-header` · `typo-table-body` · `typo-table-accent` |
+| 컨트롤·필드·피드백·내비 | `typo-control-*` `typo-field-*` `typo-feedback-*` `typo-navigation-*` (컴포넌트 내부용 — 직접 쓸 일은 드묾) |
+
+**기본 선택 — 이 조합을 쓴다.** 이 서비스는 정보 밀도가 높아 본문이 12px 이다. 14px 를 본문 기본으로 쓰지 않는다.
+
+| 역할 | 클래스 | 크기 |
+| --- | --- | --- |
+| 페이지 헤더 제목 (h1) | `typo-heading-lg` | 18px |
+| 섹션 제목 | `typo-heading-sm` | 14px |
+| 본문 | `typo-body-sm-default` | 12px |
+| 보조 설명 | `typo-body-sm-default` + `text-fg-tertiary` | 12px / `grey_65` |
+
+페이지 제목만 18px 로 크게 두고 그 아래는 14 / 12 로 촘촘하게 간다. 중간 크기(16px)는 기본 골격에서 쓰지 않는다.
+
+### 2-2. 간격 (spacing)
+
+- 유틸리티 숫자 = px. 스케일: `2 4 6 8 10 12 16 19 20 22 24 28 32 36 40 48 60`
+- 형제 요소 간격은 margin 대신 부모의 `flex`/`grid` + `gap-*`으로 잡는다.
+- 시맨틱 간격 토큰 (텍스트 덩어리·요소 사이 기본 리듬):
+
+| 상황 | 값 |
+| --- | --- |
+| **페이지 콘텐츠 패딩** | **`p-20`** |
+| **섹션 ↔ 섹션** | **`gap-12`** |
+| **페이지 내 블록 ↔ 블록** (헤더·필터·툴바·테이블 사이) | **`gap-12`** |
+| 요소 ↔ 요소 (기본) | `gap-8` (`--sys-space-stack-gap-element-normal`) |
+| 제목 ↔ 설명 텍스트 | `gap-4` (`--sys-space-stack-gap-text-normal`) |
+
+정보 밀도가 높은 서비스라 블록 간격을 넓게 벌리지 않는다. `gap-16` / `gap-24` 를 페이지 골격의 기본값으로 쓰지 않는다.
+
+#### 같은 컴포넌트를 여러 개 늘어놓을 때 (그룹 간격)
+
+위 "요소 ↔ 요소 `gap-8`" 은 **서로 다른 요소** 사이의 기본값이다.
+**같은 컴포넌트를 여러 개 나열할 때는 컴포넌트마다 정해진 그룹 간격**이 따로 있다.
+
+| 컴포넌트 | 수평 배열 | 수직 배열 |
+| --- | --- | --- |
+| `SCheckbox` | **`gap-24`** | `gap-8` |
+| `SRadio` | **`gap-24`** | `gap-8` |
+| `STextLink` | **`gap-16`**(sm) / **`gap-24`**(md·lg) | `gap-4` |
+| `SGhostButton` | `gap-4` | `gap-4` |
+| `SButton` | `gap-8` (xs·sm·md) / **`gap-12`**(lg) | 〃 |
+| `STag` | `gap-8` | `gap-8` |
+| `SToggle` | `gap-8` | `gap-8` |
+| `SListItem` (bordered) | — | `gap-8` (+ 컨테이너 `p-16`) |
+
+**수평·수직이 다른 것에 주의한다** — 체크박스·라디오는 가로로 놓으면 `gap-24`, 세로로 놓으면 `gap-8` 로 3배 차이다. 가로 배열에 `gap-8` 을 쓰면 항목이 붙어 보인다.
+
+```tsx
+✅ <div className="flex gap-24">      {/* 체크박스 가로 */}
+     <SCheckbox label="전체" … /><SCheckbox label="판매중" … />
+   </div>
+✅ <div className="flex flex-col gap-8">  {/* 체크박스 세로 */}
+     <SCheckbox label="전체" … /><SCheckbox label="판매중" … />
+   </div>
+❌ <div className="flex gap-8">        {/* 가로인데 8 — 붙어 보인다 */}
+```
+
+- **라디오는 `SRadioGroup` 을 쓴다.** `direction="horizontal" | "vertical"` 만 주면 간격을 알아서 맞춘다 — 직접 `flex` 로 감싸지 않는다.
+- `SRadioButton` 그룹의 간격은 `-1px`(테두리 겹침 처리)이라 손으로 만들지 않는다.
+- 정확한 값이 필요하면 토큰을 직접 참조해도 된다: `gap-[var(--cmp-checkbox-group-gap-horizontal)]`
+
+### 2-3. 색상
+
+**시맨틱 유틸리티를 우선 사용한다** — 의미가 이름에 담긴 토큰이 이미 유틸리티로 존재한다.
+
+#### 텍스트 색은 두 단계뿐이다
+
+| 용도 | 유틸리티 | 값 |
+| --- | --- | --- |
+| **본문·제목 (기본값)** | 지정하지 않는다 — 전역 기본색이 이미 적용된다 | `grey_95` `#222222` |
+| **보조 설명 · 비활성** | **`text-fg-tertiary`** | `grey_65` `#888888` |
+
+- `theme.css` 가 `body` 에 `grey_95` 를 깔아두므로 **본문에 텍스트 색 클래스를 붙이지 않는다.** `text-fg-primary` 를 매번 쓰는 것은 불필요하다.
+- 흐리게 보여야 하는 것은 보조 설명이든 비활성이든 **전부 `text-fg-tertiary`** 다.
+- 중간 톤(`text-fg-secondary` `#555`)은 텍스트 위계에 쓰지 않는다. 두 단계로만 간다.
+
+```tsx
+✅ <p>주문이 접수되었습니다.</p>                          // 색 지정 없음 = grey_95
+✅ <p className="text-fg-tertiary">최근 30일 기준</p>      // 보조 설명
+✅ <span className="text-fg-tertiary">-</span>            // 빈 값 (§3-4)
+❌ <p className="text-fg-primary">주문이 접수되었습니다.</p>  // 불필요
+❌ <p className="text-fg-secondary">최근 30일 기준</p>      // 중간 톤 사용
+```
+
+#### 그 밖의 색
+
+| 용도 | 유틸리티 |
+| --- | --- |
+| 상태 텍스트 | `text-fg-danger` `text-fg-success` `text-fg-warning` `text-fg-accent` `text-fg-inverse` |
+| 배경 | `bg-bg-frame`(흰 콘텐츠 면) · `bg-bg-neutralLight`/`bg-bg-neutralBright`(옅은 회색 면) · `bg-bg-screen`(앱 바탕) |
+| 보더/구분선 | `border-border-default` · `border-border-strong` · `border-divider-default` |
+| 비활성 배경·보더 | `bg-disabled-bg` `border-disabled-border` |
+| 링크 | `text-link-accent` |
+
+- 시맨틱 토큰에 맞는 항목이 없을 때만 원색 스케일(`bg-blue-subtle` 등)을 쓴다.
+- 어느 쪽이든 **토큰 유틸리티만** 사용 — 리터럴 hex 금지.
+
+---
+
+## 3. 컴포넌트 선택 규칙 — "언제 뭘 쓰나"
+
+> ⚠️ 초안(개발 작성). <!-- TODO(디자인): 전체 검수·확정 --> 표시가 있는 행은 디자인 확정 전까지 초안 기준으로 사용.
+
+### 3-1. 라벨/표시류 — STag vs SBadge vs SChip
+
+| 상황 | 사용 |
+| --- | --- |
+| **상태·분류를 라벨로 표시 (기본값)** | **`STag`** — `<STag size="sm" color="..." label="판매중" />`. 목록의 상태 컬럼, 상세의 분류 태그 등 대부분이 여기 해당한다 |
+| 라벨 없이 **색 점만**으로 상태를 찍을 때 | `SBadge` — 점(dot)만 그리는 인디케이터. 텍스트가 이미 있고 앞에 점만 붙이는 좁은 경우에만 |
+| 사용자가 입력·삭제·편집하는 **토큰** | `SChip` (단독) / `SChipInput` (입력 필드 안에서) |
+
+> 상태 표시는 **`STag size="sm"` 이 기본**이다. 색 점 + 텍스트 조합(`SBadge`)을 기본으로 쓰지 않는다.
+
+### 3-2. 알림/안내류
+
+| 상황 | 사용 |
+| --- | --- |
+| 화면에 **상시 노출**되는 안내·경고 문구 | `SCallout` — `type` + `message` 배열(중첩 = 들여쓰기) |
+| 작업 결과를 **일시적으로** 알림 | `SToast` (+ 루트에 `SToastContainer`) |
+| 진행 전 **확인/취소**를 받아야 할 때 | `SModal.confirm({...}).onOk(...)` |
+| 특정 UI 요소에 대한 **온보딩·기능 안내** | `SGuide` |
+| 로딩 중 화면 잠금 | `SLoadingModal` / 영역 로딩은 `SLoadingContainer` |
+
+### 3-3. 플로팅/오버레이류
+
+| 상황 | 사용 |
+| --- | --- |
+| hover 시 **짧은 보조 설명** (상호작용 없음) | `STooltip` |
+| 클릭 시 **상호작용 가능한** 콘텐츠 (메뉴·미니 폼) | `SPopover` |
+| **팝업** (별도 창 성격의 가벼운 표시) | `SPopup` |
+| 페이지 흐름을 끊고 **작업을 완료**시키는 창 | **`SActionModal` 로 컴포넌트를 만들고 `SModal.create` 로 띄운다** (아래 참조) |
+| 확인/취소만 받는 창 | `SModal.confirm(...)` |
+| 로딩 중 화면 잠금 | `SModal.loading(...)` / `SLoadingModal` |
+
+**모달 만드는 법** — 디자인 시스템이 띄우는 모달은 `SActionModal` · `SConfirmModal` · `SLoadingModal` 3종뿐이고 `create` · `confirm` · `loading` 이 1:1로 대응한다.
+직접 오버레이를 만들지 않는다. 작업용 모달은 **`SActionModal` 을 루트로 하는 컴포넌트를 만들어 `SModal.create` 에 넘긴다.**
+
+```tsx
+// 1) SActionModal 을 루트로 하는 컴포넌트를 만든다
+//    create 가 주입하는 open / onOpenChange / onClose 를 그대로 SActionModal 에 전달해야 한다
+function OrderModal({ orderId, open, onOpenChange, onClose, modalRef }: OrderModalProps) {
+  return (
+    <SActionModal
+      open={open}
+      onOpenChange={onOpenChange}
+      onClose={onClose}
+      modalTitle="주문 상세"
+      width={720}
+      // 주 액션은 button(단수), 보조 버튼은 footerLeft — 하단 버튼 양끝 분리 규칙과 같다
+      button={{ label: '접수', onClick: () => modalRef.ok() }}
+      footerLeft={<SButton color="secondary" label="취소" onClick={() => modalRef.cancel()} />}
+    >
+      <SKeyValueTable fields={orderFields} values={order} />
+    </SActionModal>
+  );
+}
+
+// 2) SModal.create 로 띄운다
+SModal.create({ component: OrderModal, componentProps: { orderId } })
+  .onOk(() => refetch())
+  .onDismissed(() => {});
+```
+
+### 3-4. 테이블 컬럼 정렬
+
+**숫자가 들어가는 컬럼은 예외 없이 오른쪽 정렬한다** (`align: 'right'`).
+자릿수가 세로로 맞아야 값의 크기를 눈으로 비교할 수 있기 때문이다.
+
+| 컬럼 내용 | 정렬 | 예 |
+| --- | --- | --- |
+| **금액·수량·개수·비율 등 단위가 붙은 숫자** | **`'right'`** | `39,000원` · `12개` · `3건` · `15%` |
+| **숫자만 있는 값** | **`'right'`** | `1024` · `39000` |
+| 텍스트 | 생략(기본 `left`) | 상품명, 카테고리 |
+| 상태 태그·아이콘·체크박스 등 고정폭 요소 | `'center'` | `STag`, `SIcon` |
+
+```tsx
+const columns: STableColumn[] = [
+  { name: 'id', label: 'ID', field: 'id', width: '80px', align: 'right' },
+  { name: 'name', label: '상품명', field: 'name' },                       // 텍스트 → 생략
+  { name: 'qty', label: '수량', field: 'qty', width: '80px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}개` },
+  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}원` },
+  { name: 'status', label: '상태', field: 'status', width: '100px', align: 'center',
+    render: () => <STag size="sm" color="green" label="판매중" /> },
+];
+```
+
+- `format` 으로 단위를 붙이더라도 **숫자 기반이면 오른쪽 정렬**이다. 단위 때문에 문자열이 되는 것은 정렬 판단과 무관하다.
+- 숫자는 §1-4 대로 **`toLocaleString()` 이 필수**다. 세 자리 콤마 없이 출력하지 않는다.
+- `SKeyValueTable` 의 값 셀도 같은 기준을 따른다.
+
+#### 값이 없는 셀은 회색 하이픈
+
+셀을 **빈칸으로 두지 않는다.** 값이 `null` · `undefined` · 빈 문자열이면 `-` 를 `text-fg-tertiary`(`grey_65`)로 표시한다.
+빈칸은 "데이터가 없음"인지 "렌더가 깨졌는지" 구분되지 않지만, 회색 하이픈은 없다는 사실을 명시한다.
+
+```tsx
+// 재사용 헬퍼를 하나 두고 모든 컬럼에서 쓴다
+const emptyCell = <span className="text-fg-tertiary">-</span>;
+const hasValue = (v: unknown) => v !== null && v !== undefined && v !== '';
+
+const columns: STableColumn[] = [
+  { name: 'memo', label: '메모', field: 'memo',
+    render: (row: SRow) => (hasValue(row.memo) ? row.memo : emptyCell) },
+  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
+    render: (row: SRow) =>
+      hasValue(row.price) ? `${Number(row.price).toLocaleString()}원` : emptyCell },
+];
+```
+
+`0` 은 값이 있는 것이므로 하이픈으로 바꾸지 않는다 — `0원` 그대로 표시한다.
+
+### 3-5. 버튼류
+
+| 상황 | 사용 |
+| --- | --- |
+| 일반 액션 | `SButton` (`color`: `primary` / `secondary` / `neutral` / `danger`, `size`: xs~lg) |
+| **삭제 등 파괴적 액션** | **`SButton color="danger"`** 또는 **`color="danger" outline`** |
+| 텍스트만 있는 저강조 액션 | `SGhostButton` |
+| 본문 속 이동 링크 | `STextLink` |
+| 메인 액션 + 부가 메뉴 | `SDropdownButton` |
+
+한 화면의 primary 버튼 개수에 대한 제약은 없다. 다만 **삭제·초기화 등 되돌릴 수 없는 액션은 반드시 `danger`** 로 표시한다.
+
+**하단 버튼 배치 (모든 화면 공통)** — 그룹을 모아 정렬하지 않고 **양끝으로 벌린다**(`justify-between`).
+
+- **왼쪽 끝**: 취소·닫기·목록 등 되돌리는 액션
+- **오른쪽 끝**: 저장·등록·수정·삭제 등 실행 액션
+- 체크박스·안내 문구 등 **부가 요소는 오른쪽 그룹 안, 실행 버튼 바로 왼쪽**에 둔다
+
+```tsx
+<div className="flex items-center justify-between">
+  <SButton color="secondary" label="취소" />
+  <div className="flex items-center gap-8">
+    <SCheckbox label="계속 등록하기" value={keep} onValueChange={setKeep} />  {/* 부가 요소 */}
+    <SButton label="저장" />
+  </div>
+</div>
+```
+
+---
+
+## 4. 페이지 레시피 — 표준 골격
+
+> 새 페이지는 반드시 아래 골격에서 시작한다. 임의 골격을 발명하지 않는다.
+>
+> **핵심 원칙 — 표 형태의 정보는 `SKeyValueTable` 로 만든다.** 필터·등록/수정 폼·상세 정보가 모두 여기 해당한다.
+> `SField` 컨트롤을 `div` 로 직접 나열해 폼을 만들지 않는다.
+
+### 4-1. 앱 셸 (모든 페이지 공통)
+
+```tsx
+import { SLayout, SGnb, SPage, type SGnbMenuItem } from 'sellmate-design-system-react';
+
+const MENU: SGnbMenuItem[] = [
+  { label: '주문', value: 'orders', icon: 'bill' },
+  { label: '상품', value: 'products', icon: 'box', children: [{ label: '목록', value: 'product-list' }] },
+];
+
+export default function AppShell({ children }: { children: React.ReactNode }) {
+  return (
+    <SLayout type="box" header="fix">
+      {/* type/header/folded 는 SLayout 에만 준다 — SGnb 는 context 에서 읽는다 */}
+      <SGnb items={MENU} value={current} onValueChange={navigate} logo={<Logo />} />
+      <SPage background="frame" className="p-20">{children}</SPage>
+    </SLayout>
+  );
+}
+```
+
+### 4-2. 목록 페이지 (필터 + 테이블)
+
+구조: **페이지 헤더(제목 + 가이드 링크) → 필터(`SKeyValueTable`) → `STableBar` → `STable`**
+
+액션 버튼의 위치가 핵심이다:
+
+- **페이지 제목 줄에는 액션 버튼을 두지 않는다.** 가이드·매뉴얼 링크 등 부가 정보만 온다.
+- **주요 액션(등록 등)은 `STableBar` 의 `rightActions`** 에 둔다.
+- **선택 상태 액션(선택 삭제 등)은 `STableBar` 의 `actions`** 에 둔다. `actions` 슬롯은 건수 요약이 있으면 앞에 구분선(`SDivider`)을 **자동으로** 넣으므로 직접 구분선을 만들지 않는다.
+
+```tsx
+import {
+  SButton, STextLink, SKeyValueTable, STableBar, STable, STag,
+  type STableColumn, type SRow, type SKeyValueField,
+} from 'sellmate-design-system-react';
+
+/** 필터도 표다 — SKeyValueTable 로 만든다 (서비스 전용 전역 필터가 따로 있는 경우 제외) */
+const filterFields: SKeyValueField[][] = [
+  [
+    { name: 'status', label: '상태', type: 'select',
+      options: { options: STATUS_OPTIONS, emitValue: true } },
+    { name: 'keyword', label: '검색어', type: 'input',
+      options: { placeholder: '상품명 / 상품코드' } },
+  ],
+  [
+    { name: 'period', label: '등록일', type: 'date-range-picker', tdColSpan: 3 },
+  ],
+];
+
+const columns: STableColumn[] = [
+  // 숫자 컬럼은 전부 align: 'right' — §3-4
+  { name: 'id', label: 'ID', field: 'id', width: '80px', align: 'right' },
+  { name: 'name', label: '상품명', field: 'name' },
+  { name: 'stock', label: '재고', field: 'stock', width: '90px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}개` },
+  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}원` },
+  // 상태 컬럼은 STag size="sm" — SBadge 색 점을 기본으로 쓰지 않는다
+  { name: 'status', label: '상태', field: 'status', width: '100px', align: 'center',
+    render: (row: SRow) =>
+      row.status === 'selling'
+        ? <STag size="sm" color="green" label="판매중" />
+        : <STag size="sm" color="grey" label="판매중지" /> },
+];
+
+export default function ProductListPage() {
+  const [filters, setFilters] = useState<Record<string, unknown>>({});
+  const [selected, setSelected] = useState<SRow[]>([]);
+
+  return (
+    <div className="flex flex-col gap-12">
+      {/* 페이지 헤더 — 액션 버튼 없음. 가이드/매뉴얼 링크 자리 */}
+      <div className="flex items-center justify-between">
+        <h1 className="typo-heading-lg m-0">상품 목록</h1>
+        <STextLink label="이용 가이드" rightArrow="chevron" onClick={openGuide} />
+      </div>
+
+      {/* 필터 — search 를 켜면 우측에 검색 패널이 붙는다 */}
+      <SKeyValueTable
+        fields={filterFields}
+        values={filters}
+        search
+        onChange={({ values }) => setFilters(values)}
+        onSearch={fetchList}
+      />
+
+      {/* 툴바 — 좌: 건수 + (구분선 자동) + 선택 액션 / 우: 주요 액션 */}
+      <STableBar
+        total={total}
+        selected={selected.length}
+        actions={
+          <SButton size="sm" color="secondary" label="선택 삭제"
+            disabled={!selected.length} onClick={removeSelected} />
+        }
+        rightActions={<SButton size="sm" label="상품 등록" onClick={goCreate} />}
+      />
+
+      <STable
+        columns={columns}
+        rows={rows}
+        rowKey="id"
+        selectable
+        selected={selected}
+        onSelectedChange={setSelected}
+        pagination={{ currentPage, lastPage }}
+        isLoading={isLoading}
+      />
+    </div>
+  );
+}
+```
+
+### 4-3. 폼 페이지 (등록/수정)
+
+구조: **페이지 제목 → `SForm` + `SKeyValueTable` → 하단 버튼**
+
+- 필드를 `div` 로 나열하지 않고 **`SKeyValueTable` 의 행으로 구성**한다.
+- 검증 규칙은 각 field 의 `options.rules` 로 넘긴다. `SForm` 이 하위 컨트롤을 자동 수집해 submit 시 일괄 검증하고, 실패 시 첫 실패 필드로 포커스를 옮긴다.
+- **버튼 순서: 취소·닫기가 왼쪽, 저장·등록·수정·삭제가 오른쪽.** 이 순서는 모든 화면에서 동일하다.
+
+```tsx
+import {
+  SForm, SKeyValueTable, SButton, SCheckbox,
+  type SFormHandle, type SKeyValueField, type Rule,
+} from 'sellmate-design-system-react';
+
+const required = (msg: string): Rule => v =>
+  v != null && String(v).trim() !== '' ? true : msg;
+
+const fields: SKeyValueField[][] = [
+  [
+    { name: 'name', label: '상품명', required: true, type: 'input',
+      options: { placeholder: '상품명 입력', rules: [required('상품명을 입력해 주세요.')] } },
+    { name: 'code', label: '상품코드', type: 'input', options: { placeholder: '자동 생성' } },
+  ],
+  [
+    { name: 'category', label: '카테고리', required: true, type: 'select',
+      options: { options: CATEGORY_OPTIONS, emitValue: true,
+        rules: [required('카테고리를 선택해 주세요.')] } },
+    { name: 'price', label: '판매가', type: 'number-input' },
+  ],
+  [
+    { name: 'memo', label: '메모', type: 'textarea', tdColSpan: 3,
+      helpText: ['내부 관리용 메모입니다.'] },
+  ],
+];
+
+export default function ProductCreatePage() {
+  const formRef = useRef<SFormHandle>(null);
+  const [values, setValues] = useState<Record<string, unknown>>({});
+
+  return (
+    <div className="flex flex-col gap-12">
+      <h1 className="typo-heading-lg m-0">상품 등록</h1>
+
+      <SForm ref={formRef} formClass="flex flex-col gap-12" onSubmit={save}>
+        <SKeyValueTable
+          fields={fields}
+          values={values}
+          onChange={({ values }) => setValues(values)}
+        />
+
+        {/* 하단 버튼은 양끝으로 벌린다. 부가 요소(체크박스 등)는 저장 바로 왼쪽 */}
+        <div className="flex items-center justify-between">
+          <SButton type="button" color="secondary" label="취소" onClick={goBack} />
+          <div className="flex items-center gap-8">
+            <SCheckbox label="계속 등록하기" value={keepOpen} onValueChange={v => setKeepOpen(v as boolean)} />
+            <SButton type="submit" label="저장" />
+          </div>
+        </div>
+      </SForm>
+    </div>
+  );
+}
+```
+
+### 4-4. 상세(조회) 페이지
+
+구조: **페이지 헤더(제목) → 섹션별 `SSectionHeaderCard` + `SKeyValueTable` → 하단 버튼**
+
+- 조회 값은 `type: 'text'` 행으로 표시한다. **상태·분류 태그도 별도 영역이 아니라 표의 한 행**으로 넣는다 (`render` 에 `STag`).
+- 행이 많아지면 **유형별로 섹션을 나누고, 각 섹션을 `SSectionHeaderCard` 로 감싼다.**
+  합성 컴포넌트라 `SSectionHeaderCard.Header` / `SSectionHeaderCard.Body` 를 자식으로 쓴다.
+- **수정·삭제 버튼은 하단에 둔다.** 내용이 짧아 우측 상단에 두는 변형도 있으나 기본은 하단이다.
+
+```tsx
+import {
+  SSectionHeaderCard, SKeyValueTable, SButton, STag, type SKeyValueField,
+} from 'sellmate-design-system-react';
+
+const basicFields: SKeyValueField[][] = [
+  [
+    { name: 'code', label: '상품코드', type: 'text' },
+    { name: 'createdAt', label: '등록일', type: 'text' },
+  ],
+  [
+    { name: 'category', label: '카테고리', type: 'text' },
+    // 상태 태그도 표의 한 행으로 표현한다
+    { name: 'status', label: '상태',
+      render: <STag size="sm" color="green" label="판매중" /> },
+  ],
+];
+
+const priceFields: SKeyValueField[][] = [
+  [
+    { name: 'price', label: '판매가', type: 'text' },
+    { name: 'cost', label: '원가', type: 'text' },
+  ],
+];
+
+export default function ProductDetailPage() {
+  return (
+    <div className="flex flex-col gap-12">
+      <h1 className="typo-heading-lg m-0">클래식 셔츠</h1>
+
+      <SSectionHeaderCard>
+        <SSectionHeaderCard.Header title="기본 정보" marker thickness="accent" />
+        <SSectionHeaderCard.Body>
+          <SKeyValueTable fields={basicFields} values={product} />
+        </SSectionHeaderCard.Body>
+      </SSectionHeaderCard>
+
+      <SSectionHeaderCard>
+        {/* 헤더 우측에 액션이 필요하면 slot 을 쓴다 */}
+        <SSectionHeaderCard.Header
+          title="가격 정보"
+          marker
+          helpText={['부가세 포함 금액입니다.']}
+          slot={<SButton size="sm" color="secondary" label="이력" onClick={openHistory} />}
+        />
+        <SSectionHeaderCard.Body>
+          <SKeyValueTable fields={priceFields} values={product} />
+        </SSectionHeaderCard.Body>
+      </SSectionHeaderCard>
+
+      {/* 액션은 하단 — 목록(되돌리기)은 왼쪽 끝, 실행 액션은 오른쪽 끝 */}
+      <div className="flex items-center justify-between">
+        <SButton color="secondary" label="목록" onClick={goList} />
+        <div className="flex items-center gap-8">
+          <SButton color="danger" outline label="삭제" onClick={confirmDelete} />
+          <SButton label="수정" onClick={goEdit} />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### 4-5. 섹션 카드 — SSectionHeaderCard
+
+폼 페이지에서도 입력 항목이 많으면 유형별로 `SSectionHeaderCard` 로 나눈다. 주요 옵션:
+
+| Prop (Header) | 용도 |
+| --- | --- |
+| `title` | 섹션 제목 (필수) |
+| `marker` | 제목 앞 점 표시 |
+| `required` | 제목 뒤 필수(\*) 표시 — 필수 입력 섹션에 |
+| `helpText` | 도움말 툴팁 (`string[]`) |
+| `subtitle` | 부제 |
+| `slot` | 헤더 우측 영역 (버튼 등) |
+| `thickness` | 상단 강조선 — `false`(기본) / `'default'` / `'accent'` |
+
+---
+
+## 5. 자가 점검 체크리스트
+
+페이지를 완성하면 다음을 확인한다. 하나라도 어기면 수정 후 완료를 보고한다.
+
+- [ ] 생 HTML 컨트롤(`<button>` `<input>` `<select>` `<table>` …)이 없는가
+- [ ] `text-[14px]`, `bg-[#...]` 같은 리터럴 임의 값이 없는가 (`var(--sys-*)` 참조는 허용)
+- [ ] 텍스트에 `typo-*` 프리셋을 썼는가
+- [ ] 간격이 전부 토큰 스케일 값인가 (`gap-13` ❌ → `gap-12` ✅)
+- [ ] 본문이 12px(`typo-body-sm-default`)이고 보조 설명이 `text-fg-tertiary` 인가 (14px 본문 ❌)
+- [ ] 페이지 패딩이 `p-20`, 블록·섹션 간격이 `gap-12` 인가 (`gap-16`/`gap-24` ❌)
+- [ ] 같은 컴포넌트를 나열할 때 §2-2 그룹 간격을 썼는가 (체크박스 가로 `gap-24` 등)
+- [ ] 페이지가 §4의 표준 골격에서 시작했는가
+- [ ] 필터·폼·상세 정보를 `SKeyValueTable` 로 만들었는가 (컨트롤을 `div` 로 나열하지 않았는가)
+- [ ] 섹션 구분에 `SSectionHeaderCard` 를 썼는가 (직접 만든 카드가 아니라)
+- [ ] 목록의 주요 액션이 `STableBar` 의 `rightActions` 에 있는가 (페이지 제목 줄이 아니라)
+- [ ] 상태 표시에 `STag size="sm"` 을 썼는가
+- [ ] 테이블의 숫자 컬럼(금액·수량·개수 등)이 전부 `align: 'right'` 인가
+- [ ] 화면에 표시하는 모든 숫자에 `toLocaleString()` 을 써서 세 자리 콤마를 넣었는가
+- [ ] 금액·수량 등 양을 나타내는 숫자에 `toLocaleString()` 을 썼는가 (번호·코드는 제외)
+- [ ] 하단 버튼이 양끝 분리(`justify-between`)이고, 되돌리기가 왼쪽 끝 · 실행이 오른쪽 끝인가
+- [ ] 삭제 등 파괴적 액션에 `color="danger"` 를 썼는가
+- [ ] 작업용 모달을 `SActionModal` + `SModal.create` 로 만들었는가 (직접 오버레이 ❌)
+- [ ] 상태 표시·알림·확인 다이얼로그가 §3의 선택 규칙을 따르는가
+
+---
+
+## 6. 린트로 강제되는 규칙
+
+위 규칙 중 일부는 소비 앱의 ESLint 로 검출된다 (`sellmate-design-system-react/eslint`).
+**코드를 넘기기 전에 린트를 통과시킨다.**
+
+| 규칙 | 잡히는 것 |
+| --- | --- |
+| `sellmate/no-raw-html-control` | §1-1 생 HTML 컨트롤, `alert()`/`confirm()` |
+| `sellmate/no-arbitrary-class` | §1-2 토큰 있는 속성의 임의 값 (`text-[14px]`, `bg-[#eee]`) |
+| `sellmate/no-off-scale-spacing` | §2-2 스케일 밖 간격 (`gap-13`) |
+| `sellmate/table-numeric-align` | §3-4 숫자 컬럼의 `align: 'right'` 누락 (`--fix` 지원) |
+| `sellmate/require-locale-number` | §1-4 숫자 컬럼의 `toLocaleString()` 누락 |
+| `sellmate/component-group-gap` | §2-2 컴포넌트 그룹 간격 (체크박스 가로 24 / 세로 8 등) |
+| `sellmate/require-locale-number` | §1-4 금액·수량 등의 `toLocaleString()` 누락 |
+| `sellmate/prefer-typo-preset` | §1-3 낱개 폰트 조합 (`text-14 font-bold`) |
+
+`gap-13` 처럼 스케일 밖 값은 Tailwind v4 에서 **에러 없이 조용히 무시된다**. "간격이 왜 안 먹지" 로만 보이므로 반드시 스케일 값을 쓴다.
+
+린트가 잡지 못하는 것(§3 컴포넌트 선택, §4 페이지 골격, 버튼 배치)은 §5 체크리스트로 직접 확인한다.
+
+
+## 2. 디자인 토큰 어휘 (theme.css 자동 추출)
+
+Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터럴 임의 값(`text-[14px]`, `bg-[#eee]`)은 금지.
+
+### 간격 (px 단위 — gap-N, p-N, m-N 등)
+2 4 6 8 10 12 16 19 20 22 24 28 32 36 40 44 48 56 60 62 80
+
+### 폰트 크기 (text-N — 단, 본문 텍스트는 아래 typo-* 프리셋 우선)
+10 11 12 13 14 16 18 20 24 28 32
+
+### radius (rounded-*)
+2 4 6 8 full control-sm control-md feedback-xs-square feedback-sm-square feedback-pill field-sm field-md navigation item-bordered
+
+### 색상 팔레트 (text-{family}-{step}, bg-…, border-…)
+- white
+- black
+- grey: 10 20 25 30 35 45 50 55 60 65 70 80 85 90 95 05 strong subtle
+- red: 15 20 30 45 60 70 75 80 85 90 95 99 strong subtle
+- orange: 10 20 35 45 55 60 65 75 85 90 95 99 strong subtle
+- yellow: 10 20 25 30 40 45 50 60 70 80 90 95 strong moderate subtle
+- olive: 10 15 20 30 45 55 65 70 80 90 95 05
+- green: 15 25 45 55 65 70 75 80 85 90 95 99 strong subtle
+- steelblue: 10 25 45 60 65 70 75 80 85 90 95 99
+- oceanblue: 15 25 50 60 65 70 75 80 85 90 95 99
+- brilliantblue: 10 20 25 40 50 60 70 75 80 85 90 95 99 05
+- bg: screen frame brand subtle accent accentLight accentBright accentFaint deep danger dangerLight warning caution progress success successLight neutralLight neutralBright tableHeader
+- fg: primary secondary tertiary quaternary brand subtleWarm subtleCool deep success dangerLight accent accentLight danger warning inverse
+- border: default strong accent accentLight danger success
+- disabled: bg text icon border
+- link: accent
+- divider: default
+- lightblue: strong subtle
+- blue: strong subtle
+- darkblue: strong subtle
+- indigo: strong subtle
+- primary: 10 20 25 40 50 60 70 75 80 85 90 95 99 05
+- danger: 15 20 30 45 60 70 75 80 85 90 95 99 strong subtle
+- success: 15 25 45 55 65 70 75 80 85 90 95 99 strong subtle
+- warning: 10 20 35 45 55 60 65 75 85 90 95 99 strong subtle
+
+### 타이포그래피 프리셋 (클래스 하나로 size/weight/line-height 적용)
+| 클래스 | size | weight | line-height |
+| --- | --- | --- | --- |
+| typo-heading-sm | 14px | 700 | 24px |
+| typo-heading-xs | 12px | 700 | 20px |
+| typo-heading-md | 16px | 700 | 26px |
+| typo-heading-lg | 18px | 700 | 30px |
+| typo-body-xs-default | 11px | 400 | 18px |
+| typo-body-sm-default | 12px | 400 | 20px |
+| typo-body-sm-medium | 12px | 500 | 20px |
+| typo-body-sm-bold | 12px | 700 | 20px |
+| typo-body-md-default | 14px | 400 | 24px |
+| typo-body-md-medium | 14px | 500 | 24px |
+| typo-body-md-bold | 14px | 700 | 24px |
+| typo-body-lg-default | 16px | 400 | 26px |
+| typo-body-lg-medium | 16px | 500 | 26px |
+| typo-body-lg-bold | 16px | 700 | 26px |
+| typo-control-xs-default | 12px | 400 | 20px |
+| typo-control-xs-medium | 12px | 500 | 20px |
+| typo-control-xs-underline | 12px | 500 | 20px |
+| typo-control-xs-bold | 12px | 700 | 20px |
+| typo-control-sm-default | 14px | 500 | 24px |
+| typo-control-sm-underline | 14px | 500 | 24px |
+| typo-control-md-default | 16px | 500 | 26px |
+| typo-control-md-underline | 16px | 500 | 26px |
+| typo-control-lg | 18px | 500 | 30px |
+| typo-feedback-xs | 11px | 500 | 18px |
+| typo-feedback-sm-regular | 12px | 400 | 20px |
+| typo-feedback-sm-medium | 12px | 500 | 20px |
+| typo-feedback-sm-bold | 12px | 700 | 20px |
+| typo-feedback-sm-underline | 12px | 500 | 20px |
+| typo-feedback-md-bold | 14px | 700 | 24px |
+| typo-feedback-md-medium | 14px | 500 | 24px |
+| typo-feedback-md-underline | 14px | 700 | 24px |
+| typo-field-xs-default | 11px | 400 | 18px |
+| typo-field-sm-default | 12px | 400 | 20px |
+| typo-field-sm-medium | 12px | 500 | 20px |
+| typo-field-sm-bold | 12px | 700 | 20px |
+| typo-field-md-default | 14px | 400 | 24px |
+| typo-field-md-medium | 14px | 500 | 24px |
+| typo-field-md-bold | 14px | 700 | 24px |
+| typo-field-lg-default | 16px | 400 | 26px |
+| typo-field-lg-medium | 16px | 500 | 26px |
+| typo-field-lg-bold | 16px | 700 | 26px |
+| typo-navigation-xs-medium | 11px | 500 | 18px |
+| typo-navigation-xs-bold | 11px | 700 | 18px |
+| typo-navigation-sm-default | 12px | 400 | 20px |
+| typo-navigation-sm-medium | 12px | 500 | 20px |
+| typo-navigation-sm-bold | 12px | 700 | 20px |
+| typo-navigation-md-bold | 13px | 700 | 22px |
+| typo-navigation-lg-medium | 14px | 500 | 24px |
+| typo-navigation-lg-bold | 14px | 700 | 24px |
+| typo-table-header | 12px | 500 | 20px |
+| typo-table-body | 12px | 400 | 20px |
+| typo-table-accent | 12px | 700 | 20px |
+
+### 시맨틱 색 토큰 (var() 참조 전용 — 예: bg-[var(--sys-color-bg-frame)])
+--sys-color-bg-accent
+--sys-color-bg-accentBright
+--sys-color-bg-accentFaint
+--sys-color-bg-accentLight
+--sys-color-bg-brand
+--sys-color-bg-caution
+--sys-color-bg-danger
+--sys-color-bg-dangerLight
+--sys-color-bg-deep
+--sys-color-bg-frame
+--sys-color-bg-neutralBright
+--sys-color-bg-neutralLight
+--sys-color-bg-progress
+--sys-color-bg-screen
+--sys-color-bg-subtle
+--sys-color-bg-success
+--sys-color-bg-successLight
+--sys-color-bg-tableHeader
+--sys-color-bg-warning
+--sys-color-blue-strong
+--sys-color-blue-subtle
+--sys-color-border-accent
+--sys-color-border-accentLight
+--sys-color-border-danger
+--sys-color-border-default
+--sys-color-border-strong
+--sys-color-border-success
+--sys-color-control-bg-inverseHover
+--sys-color-darkblue-strong
+--sys-color-darkblue-subtle
+--sys-color-disabled-bg
+--sys-color-disabled-border
+--sys-color-disabled-icon
+--sys-color-disabled-text
+--sys-color-divider-default
+--sys-color-fg-accent
+--sys-color-fg-accentLight
+--sys-color-fg-brand
+--sys-color-fg-danger
+--sys-color-fg-dangerLight
+--sys-color-fg-deep
+--sys-color-fg-inverse
+--sys-color-fg-primary
+--sys-color-fg-quaternary
+--sys-color-fg-secondary
+--sys-color-fg-subtleCool
+--sys-color-fg-subtleWarm
+--sys-color-fg-success
+--sys-color-fg-tertiary
+--sys-color-fg-warning
+--sys-color-field-bg-default
+--sys-color-field-bg-hover
+--sys-color-field-bg-readOnly
+--sys-color-field-border-danger
+--sys-color-field-border-default
+--sys-color-field-border-focus
+--sys-color-field-border-hover
+--sys-color-field-border-success
+--sys-color-field-icon-default
+--sys-color-field-text-default
+--sys-color-field-text-placeholder
+--sys-color-field-text-readOnly
+--sys-color-indigo-strong
+--sys-color-indigo-subtle
+--sys-color-lightblue-strong
+--sys-color-lightblue-subtle
+--sys-color-link-accent
+--sys-color-navigation-gnb-bg-dark
+
+## 3. 컴포넌트 카탈로그 (Props / Events / Methods)
+
+# SActionModal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SActionModal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — |  |
+| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) |
+| `modalTitle?` | `string` | `''` |  |
+| `button?` | `SActionModalButton` | — | 하단 액션 버튼 (주 액션 1개). 의도적으로 단수다 — 보조 버튼(취소·삭제 등)은 `footerLeft` 슬롯에 직접 배치한다. |
+| `footerLeft?` | `ReactNode` | — | footer 좌측 영역 (sd-action-modal 의 bottom-sub-content 슬롯). 보조 버튼이나 안내 문구를 넣는다. 버튼을 하나 더 쓰고 싶을 때 여기에 SButton 을 넣는다. |
+| `width?` | `number \| string` | — |  |
+| `height?` | `number \| string` | — |  |
+| `children?` | `ReactNode` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` |  |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SModalContainer](../SModalContainer)
+
+### Graph
+
+---
+
+# SBadge
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBadge
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SBadgeColor` | `'blue'` | 뱃지 색상 |
+
+## Dependencies
+
+### Used by
+
+ - [SList](../SList)
+
+### Graph
+
+---
+
+# SBarcodeInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SBarcodeInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| number \| null` | — |  |
+| `size?` | `SBarcodeInputSize` | `'sm'` |  |
+| `clearable?` | `boolean` | `false` |  |
+| `autoFocus?` | `boolean` | — |  |
+| `name?` | `string` | — |  |
+| `placeholder?` | `string` | `'입력해 주세요.'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `focused?` | `boolean` | — |  |
+| `hovered?` | `boolean` | — |  |
+| `prefix?` | `ReactNode` | — | 입력 앞 슬롯 |
+| `suffix?` | `ReactNode` | — | 입력 뒤 슬롯 |
+| `inputClass?` | `string` | — |  |
+| `inputStyle?` | `CSSProperties` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 값 변경 (sdUpdate) |
+| `onFocus` | `() => void` |  |
+| `onBlur` | `() => void` |  |
+
+## Dependencies
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+---
+
+# SButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SButtonColor` | `'primary'` | 색상 — sd-button preset의 색 계열 |
+| `outline?` | `boolean` | `false` | 아웃라인(테두리) 스타일. primary·neutral·danger 만 지원 (secondary 는 무시) |
+| `size?` | `SButtonSize` | `'sm'` | 크기 |
+| `icon?` | `SIconName` | — | 레이블 왼쪽 아이콘 |
+| `rightIcon?` | `SIconName` | — | 레이블 오른쪽 아이콘 |
+| `label?` | `string` | — | 버튼 텍스트 (문자열만 — 아이콘은 icon/rightIcon 사용) |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SConfirmModal](../SConfirmModal)
+ - [SDropdownButton](../SDropdownButton)
+ - [SKeyValueTable](../SKeyValueTable)
+ - [SLoadingModal](../SLoadingModal)
+ - [SPopover](../SPopover)
+ - [SPopup](../SPopup)
+ - [SToast](../SToast)
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SCalendar
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCalendar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 날짜 (YYYY-MM-DD) |
+| `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] (빈 문자열이면 제한 없음) |
+| `events?` | `SCalendarEventGroup[]` | — | 이벤트 그룹 (날짜별 점) |
+| `elevated?` | `boolean` | `false` | 카드 그림자 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
+| `onViewChange` | `(v: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
+
+## Dependencies
+
+### Used by
+
+ - [SDatePicker](../SDatePicker)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+---
+
+# SCallout
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCallout
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SCalloutType` | `'default'` | 콜아웃 타입 (색상·아이콘·타이틀 결정) |
+| `message?` | `SCalloutMessage[]` | `[]` | 표시할 메시지 목록 (배열 중첩으로 depth 표현). 각 문자열은 인라인 HTML(`<b>`, `<a>` 등)을 허용하며 sanitizeInlineHtml 로 살균 후 렌더된다. |
+| `children?` | `ReactNode` | — | message 대신 직접 본문을 넣을 때 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SCard
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCard
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `bordered?` | `boolean` | `false` | 테두리 표시 여부 |
+
+---
+
+# SCheckbox
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCheckbox
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `SCheckboxValue` | `false` | 선택 상태. boolean(단일) / 배열(그룹) / null(indeterminate) |
+| `val?` | `unknown` | — | 배열(그룹) 모드에서 이 체크박스의 값 |
+| `label?` | `string` | `''` | 라벨 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `inverse?` | `boolean` | `false` | 어두운 배경용 흰색 스타일 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: boolean \| unknown[]) => void` | 값 변경 (sdUpdate) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+ - [STable](../STable)
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SChip
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SChip
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name?` | `string` | — | 폼 연동용 name |
+| `value?` | `string` | `''` | 칩 텍스트 값 |
+| `error?` | `boolean` | — | 에러 상태 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `editable?` | `boolean` | `false` | 인라인 편집 가능 (기본값 false) |
+| `showRemove?` | `boolean` | `true` | 닫기 버튼 표시 |
+| `placeholder?` | `string` | `''` | 편집 중 placeholder |
+| `rules?` | `Rule[]` | — | 유효성 규칙 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 편집 완료 (sdUpdate) |
+| `onRemove` | `() => void` | 삭제 (sdRemove) |
+| `onFocus` | `() => void` | 편집 진입 (sdFocus) |
+| `onBlur` | `() => void` | 편집 이탈 (sdBlur) |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `focus` | `() => void` | 편집 input에 포커스합니다. |
+| `getNativeElement` | `() => HTMLElement \| null` | 네이티브 편집 엘리먼트를 반환합니다. |
+
+## Dependencies
+
+### Used by
+
+ - [SChipInput](../SChipInput)
+ - [SFilePicker](../SFilePicker)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+---
+
+# SChipInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SChipInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `values?` | `string[]` | `[]` | 칩 값 목록 |
+| `errors?` | `boolean[] \| ((value: string) => boolean)` | `[]` | 칩별 에러 (배열 또는 판별 함수) |
+| `disabledChips?` | `boolean[] \| ((value: string) => boolean)` | `[]` | 칩별 비활성 (배열 또는 판별 함수) |
+| `size?` | `SChipInputSize` | `'sm'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `placeholder?` | `string` | `'태그 입력 (Enter로 등록 / 콤마로 구분 / 띄어쓰기 불가)'` |  |
+| `name?` | `string` | — |  |
+| `rules?` | `Rule[]` | — |  |
+| `error?` | `boolean` | — |  |
+| `useReset?` | `boolean` | `false` | 입력 초기화 버튼 표시 |
+| `maxCount?` | `number` | — | 최대 칩 개수 |
+| `metaPlacement?` | `SChipInputMetaPlacement` | `'end'` | 최대 개수·초기화 meta 위치 |
+| `duplicateLabel?` | `string` | — | 중복 에러 메시지 항목명 |
+| `suggestions?` | `string[]` | `[]` | 자동완성 후보 |
+| `loadingSuggestions?` | `boolean` | `false` |  |
+| `recommendedItems?` | `string[]` | `[]` | 추천 항목 (입력값 없을 때) |
+| `loadingRecommendedItems?` | `boolean` | `false` |  |
+| `dropdownMinWidth?` | `number \| string` | `200` | 드롭다운 최소 너비 (숫자=px) |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `hint?` | `string` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(values: string[]) => void` | 값 변경 (sdUpdate) — 전체 배열 |
+| `onInput` | `(value: string) => void` | 입력 중 문자열 변경 (sdInput) |
+| `onFocus` | `() => void` |  |
+| `onBlur` | `() => void` |  |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `focus` | `() => void` | 입력 필드에 포커스를 이동합니다. |
+
+## Dependencies
+
+### Depends on
+
+- [SChip](../SChip)
+- [SField](../SField)
+- [SIcon](../SIcon)
+- [SPortal](../SPortal)
+- [STextLink](../STextLink)
+
+### Graph
+
+---
+
+# SCircleProgress
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SCircleProgress
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `number` | `0` | 진행률 (0–100) |
+| `type?` | `SCircleProgressType` | `'primary'` | 색상 테마 |
+| `indeterminate?` | `boolean` | `false` | 불확정(스피너) 모드 — value 무시 |
+| `label?` | `string` | — | 하단 레이블 |
+| `innerValue?` | `boolean` | `false` | true면 퍼센트를 원 아래가 아닌 원 가운데에 표시 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Used by
+
+ - [SLoadingContainer](../SLoadingContainer)
+ - [SLoadingModal](../SLoadingModal)
+ - [STable](../STable)
+
+### Graph
+
+---
+
+# SConfirmModal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SConfirmModal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — |  |
+| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent) |
+| `type?` | `SConfirmModalType` | `'positive'` | 타입 (아이콘·메인버튼 색 결정) |
+| `modalTitle?` | `string` | `''` |  |
+| `titleClass?` | `string` | — | 제목 엘리먼트에 추가할 클래스 (sd-confirm-modal titleClass) |
+| `topMessage?` | `string[]` | `[]` | 콘텐츠 박스 상단 메시지 목록 (각 항목이 한 줄, HTML 문자열 허용 — innerHTML 렌더링) |
+| `bottomMessage?` | `string[]` | `[]` | 콘텐츠 박스 하단 메시지 목록 (각 항목이 한 줄, HTML 문자열 허용 — innerHTML 렌더링) |
+| `tagLabel?` | `string` | — | tag 슬롯 기본 태그 레이블 (tagSlot 미지정 시) |
+| `tagShape?` | `STagShape` | `'square'` | 태그 프리셋 (shape/size/color) — sd-confirm-modal tagPreset 대응 |
+| `tagSize?` | `STagSize` | `'sm'` |  |
+| `tagColor?` | `STagColor` | `'grey'` |  |
+| `slotLabel?` | `string` | — | 콘텐츠 박스에서 태그 오른쪽에 오는 텍스트 (optionSlot 미지정 시) |
+| `tagSlot?` | `ReactNode` | — | 콘텐츠 박스 tag 위치 커스텀 콘텐츠 (미지정 시 tagLabel 기반 STag) |
+| `optionSlot?` | `ReactNode` | — | 콘텐츠 박스에서 태그 오른쪽 커스텀 콘텐츠 (미지정 시 slotLabel 텍스트) |
+| `mainButtonLabel?` | `string` | `'확인'` | 메인 버튼 |
+| `mainButtonName?` | `ConfirmModalMainButton` | — | 확인 버튼 프리셋 (없으면 type에 따라 자동 결정) |
+| `subButtonLabel?` | `string` | — | 서브(취소) 버튼 |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` |  |
+| `onOk` | `() => void` | 확인 버튼 클릭 (sdOk) |
+| `onCancel` | `() => void` |  |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) |
+
+## Dependencies
+
+### Used by
+
+ - [SModal](../SModal)
+
+### Depends on
+
+- [SButton](../SButton)
+- [SIcon](../SIcon)
+- [SModalContainer](../SModalContainer)
+- [STag](../STag)
+
+### Graph
+
+---
+
+# SDatePicker
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SDatePicker
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 날짜 (YYYY-MM-DD) |
+| `size?` | `SDatePickerSize` | `'sm'` |  |
+| `placeholder?` | `string` | `'YYYY-MM-DD'` |  |
+| `selectable?` | `[string, string]` | — | 선택 가능 범위 [시작, 종료] |
+| `disabled?` | `boolean` | `false` |  |
+| `width?` | `number \| string` | — |  |
+| `name?` | `string` | — |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(date: string) => void` | 선택 변경 (sdUpdate) |
+| `onViewChange` | `(view: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SCalendar](../SCalendar)
+- [SField](../SField)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SDateRangePicker
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SDateRangePicker
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `SDateRangeValue` | — |  |
+| `size?` | `SDateRangePickerSize` | `'sm'` |  |
+| `placeholder?` | `string` | `'YYYY-MM-DD ~ YYYY-MM-DD'` |  |
+| `selectable?` | `[string, string]` | — |  |
+| `maxRange?` | `number` | — | 최대 선택 일수 |
+| `useTimePicker?` | `boolean` | `false` | 시간(시:분) 선택 푸터 사용 여부. true이면 value는 "YYYY-MM-DD HH:mm" 형식이 되고, 캘린더 하단에 시작·종료 시간 입력이 표시된다. |
+| `disabled?` | `boolean` | `false` |  |
+| `width?` | `number \| string` | — |  |
+| `name?` | `string` | — |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(range: SDateRangeValue) => void` | 선택 변경 (sdUpdate) — [start, end] |
+| `onViewChange` | `(view: { year: number; month: number }) => void` | 보이는 연·월 변경 (sdViewChange) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SDivider
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SDivider
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `vertical?` | `boolean` | `false` | true면 수직 분할선, false면 수평 분할선 |
+
+## Dependencies
+
+### Used by
+
+ - [STableBar](../STableBar)
+
+### Graph
+
+---
+
+# SDraggableItem
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SDraggableItem
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `SDraggableItemSlot` | — | 드래그 아이템 제목 |
+| `trailing?` | `SDraggableItemSlot` | — | 타이틀 뒤에 표시할 태그/콘텐츠 |
+| `accentStripe?` | `boolean` | `false` | 아이템 왼쪽 accent stripe 표시 여부 |
+| `bordered?` | `boolean` | `false` | 외곽 테두리 사용 여부 |
+| `selected?` | `boolean` | `false` | 선택 상태 여부 |
+| `dense?` | `boolean` | `false` | 조밀한 높이 사용 여부 |
+| `disabled?` | `boolean` | `false` | 비활성 상태 여부 |
+| `dragOverlay?` | `boolean` | `true` | 드래그 시 마우스를 따라가는 overlay 표시 여부 |
+| `dragOverlayOpacity?` | `number` | `0.75` | 드래그 overlay 투명도 |
+| `dragHandleProps?` | `HTMLAttributes<HTMLDivElement>` | — | 드래그 핸들에 전달할 속성 |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onDragHandleMouseDown` | `(event: MouseEvent<HTMLDivElement>) => void` | 드래그 핸들 mouse down 이벤트 |
+
+## Dependencies
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SDropdownButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SDropdownButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color?` | `SButtonColor` | `'primary'` | 버튼 색상 |
+| `outline?` | `boolean` | `false` | 아웃라인(테두리) 스타일 |
+| `size?` | `SDropdownButtonSize` | `'sm'` | 크기 (lg 미지원) |
+| `label?` | `string` | `''` | 버튼 레이블 |
+| `items?` | `SDropdownButtonItem[]` | `[]` | 메뉴 아이템 목록 |
+| `split?` | `boolean` | `false` | split 모드 — 레이블 버튼과 토글 분리 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onItemClick` | `(value: string \| number) => void` | 메뉴 아이템 선택 (sdClick) |
+| `onLabelClick` | `() => void` | split 레이블 버튼 클릭 (sdButtonClick) |
+| `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `open` | `() => void` | 드롭다운 열기 (sdOpen) |
+| `close` | `() => void` | 드롭다운 닫기 (sdClose) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SExpansionItem
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SExpansionItem
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `ReactNode` | — |  |
+| `depth?` | `1 \| 2 \| 3` | `1` | 중첩 단계. Figma 기준 1~3단계 |
+| `leading?` | `ReactNode \| SExpansionItemRenderProp` | — | 타이틀 앞에 표시할 아이콘/콘텐츠 |
+| `trailing?` | `ReactNode` | — | 타이틀 뒤에 표시할 태그/콘텐츠 |
+| `bodyPadding?` | `boolean` | `true` | body 내부 패딩 사용 여부 |
+| `bordered?` | `boolean` | `false` | 외곽 테두리 사용 여부 |
+| `expanded?` | `boolean` | — |  |
+| `defaultExpanded?` | `boolean` | `false` |  |
+| `dense?` | `boolean` | `false` |  |
+| `disabled?` | `boolean` | `false` |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onToggle` | `(expanded: boolean, event: MouseEvent<HTMLButtonElement>) => void` |  |
+
+## Dependencies
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SField
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SField
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name?` | `string` | — | 폼 연동용 name 속성 |
+| `label?` | `string` | `''` | 레이블 텍스트 |
+| `icon?` | `SIconName` | — | 레이블 영역 아이콘명 (크기는 size 토큰 16px 고정) |
+| `iconColor?` | `SColor` | — | 레이블 영역 아이콘 색상. 미지정 시 currentColor 상속 |
+| `labelTooltip?` | `string` | `''` | 레이블 툴팁 텍스트 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 (SdTooltipProps 대응) |
+| `labelWidth?` | `number \| string` | — | 레이블/어드온 레이블 너비 (숫자=px). label·addonLabel 폭에 공통 적용 |
+| `labelHeight?` | `number \| string` | — | 레이블 박스 높이 (숫자=px). 미지정 시 size별 기본값 사용. 컨트롤 박스가 기본 필드 높이보다 큰 경우(multiline 등) 첫 행에 세로 중앙 정렬을 맞추기 위해 컨트롤 박스 높이를 넘겨받는다. |
+| `size?` | `SFieldSize` | `'sm'` | 필드 크기 |
+| `addonLabel?` | `string` | `''` | 우측 어드온 레이블 |
+| `addonAlign?` | `SFieldAddonAlign` | `'start'` | 어드온 정렬 |
+| `error?` | `boolean` | `false` | 에러 상태 |
+| `errorMessage?` | `string` | `''` | 에러 메시지 |
+| `status?` | `SFieldStatus` | — | 필드 상태 — 'error' | 'pass' | 'default'. 'pass'면 초록 테두리 |
+| `focused?` | `boolean` | `false` | 포커스 상태 (제어/반영) |
+| `hovered?` | `boolean` | `false` | 호버 상태 (제어/반영) |
+| `rules?` | `Rule[]` | — | 유효성 규칙 (검증은 컨트롤에서 수행, API 패리티) |
+| `hint?` | `string` | `''` | 하단 힌트 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `readOnly?` | `boolean` | `false` | 읽기 전용 (회색 배경) |
+| `width?` | `number \| string` | — | 컨트롤 너비 (숫자=px). 지정하면 필드가 부모 폭을 다 먹지 않고 (레이블 + width) 만큼만 차지한다. 다른 요소와 나란히 놓으려면 부모를 flex 로 두면 된다. |
+| `minWidth?` | `number \| string` | — | 컨트롤 최소 너비 (숫자=px). 하한선만 지정하며 필드는 계속 부모 폭을 채운다 |
+| `multiline?` | `boolean` | `false` | 멀티라인(textarea) — 컨트롤 높이를 고정하지 않고 min-height만 적용 |
+| `borderless?` | `boolean` | `false` | 테두리 박스 제거 (inline 컨트롤용) — border/배경/hover·focus 강조만 사라지고 label·hint·errorMessage 등 나머지 필드 구성은 그대로 동작한다. |
+| `children?` | `ReactNode` | — | 실제 컨트롤 (input/select 등) — 테두리 없이 렌더, 테두리는 SField가 제공 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onMouseEnter` | `() => void` |  |
+| `onMouseLeave` | `() => void` |  |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `focus` | `() => void` | 내부 컨트롤에 포커스하고 필드를 화면에 스크롤합니다. |
+
+## Dependencies
+
+### Used by
+
+ - [SBarcodeInput](../SBarcodeInput)
+ - [SChipInput](../SChipInput)
+ - [SDatePicker](../SDatePicker)
+ - [SDateRangePicker](../SDateRangePicker)
+ - [SFilePicker](../SFilePicker)
+ - [SInput](../SInput)
+ - [SNumberInput](../SNumberInput)
+ - [SSelect](../SSelect)
+ - [STextarea](../STextarea)
+ - [STimePicker](../STimePicker)
+ - [STimeRangePicker](../STimeRangePicker)
+
+### Depends on
+
+- [SIcon](../SIcon)
+- [STooltip](../STooltip)
+
+### Graph
+
+---
+
+# SFilePicker
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SFilePicker
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `SFilePickerValue` | `null` |  |
+| `placeholder?` | `string` | `'Click to upload'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `focused?` | `boolean` | `false` | 포커스 상태 여부 |
+| `hovered?` | `boolean` | `false` | 호버 상태 여부 |
+| `inline?` | `boolean` | `false` | 인라인 표시 — SField 테두리 박스만 사라지고 label/rules/hint 는 그대로 동작 |
+| `multiple?` | `boolean` | `false` |  |
+| `useMultipleListBox?` | `boolean` | `false` | multiple 파일 목록을 필드 아래 칩 대신, caret(▼) 클릭 시 열리는 리스트박스 카드로 표시 (바깥 클릭 시 닫힘) |
+| `accept?` | `string` | — |  |
+| `maxFileSize?` | `number \| string` | — |  |
+| `maxTotalSize?` | `number \| string` | — |  |
+| `maxFiles?` | `number \| string` | — |  |
+| `name?` | `string` | — |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `size?` | `SFieldSize` | `'sm'` |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | `'start'` |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: SFilePickerValue) => void` | 파일 변경 (sdUpdate) |
+| `onReject` | `(detail: { files: File[]; reason: SFilePickerRejectReason }) => void` | 제한 초과 거부 (sdReject) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SChip](../SChip)
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SForm
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SForm
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `formClass?` | `string` | — | form 엘리먼트에 추가할 클래스 (sd-form formClass 대응) |
+| `children?` | `ReactNode` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onSubmit` | `() => void` | 모든 필드 검증 통과 후 발생 (sd-form sdSubmit 대응) |
+| `onValidationError` | `(error: SFormValidationError) => void` | 검증 실패 시 실패한 필드 name 목록 전달 (sd-form sdValidationError 대응) |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `validate` | `() => boolean` | 등록된 모든 필드를 검증하고 통과 여부를 반환 |
+| `resetValidation` | `() => void` | 모든 필드의 검증 상태만 초기화 (값은 소비자 소유) |
+| `reset` | `() => void` | resetValidation 별칭 — sd-form sdReset 대응. 값 리셋은 소비자(value/onChange) 책임 |
+| `focusFirstInvalid` | `() => void` | 첫 번째 실패 필드로 포커스 이동 |
+
+---
+
+# SGhostButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SGhostButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `SIconName` | — | 표시할 아이콘명 (필수) |
+| `size?` | `SGhostButtonSize` | `'sm'` | 버튼 크기 |
+| `intent?` | `SGhostButtonIntent` | `'default'` | 색상 의도 |
+| `ariaLabel?` | `string` | `''` | 스크린리더용 접근성 레이블 |
+| `ariaPressed?` | `boolean` | — | 토글 버튼일 때 눌림 상태 (aria-pressed). 미지정 시 속성 자체를 내보내지 않는다. |
+| `tooltipText?` | `string` | — | 호버 시 표시할 툴팁 텍스트 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `anchorClassName?` | `string` | — | tooltip anchor wrapper 클래스. tooltipText가 있을 때 위치 조정용으로 사용합니다. |
+| `anchorStyle?` | `CSSProperties` | — | tooltip anchor wrapper 스타일. tooltipText가 있을 때 위치 조정용으로 사용합니다. |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onClick` | `(e: MouseEvent<HTMLButtonElement>) => void` | 클릭 (sdClick) |
+
+## Dependencies
+
+### Used by
+
+ - [SBarcodeInput](../SBarcodeInput)
+ - [SCalendar](../SCalendar)
+ - [SChip](../SChip)
+ - [SDateRangePicker](../SDateRangePicker)
+ - [SFilePicker](../SFilePicker)
+ - [SGnb](../SGnb)
+ - [SGuide](../SGuide)
+ - [SInput](../SInput)
+ - [SModalContainer](../SModalContainer)
+ - [SPopover](../SPopover)
+ - [SSelect](../SSelect)
+ - [STimePicker](../STimePicker)
+ - [STimeRangePicker](../STimeRangePicker)
+ - [SToast](../SToast)
+ - [STooltip](../STooltip)
+
+### Depends on
+
+- [SIcon](../SIcon)
+- [STag](../STag)
+
+### Graph
+
+---
+
+# SGnb
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SGnb
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SGnbType` | — | 메뉴 스타일: box(라운드) / belt(풀폭 행). 미지정 시 SLayout 의 type 을 따른다. |
+| `header?` | `SGnbHeader` | — | 상단바 구조: fix(GNB 폭 고정) / full(레이아웃 전폭). 미지정 시 SLayout 의 header 를 따른다. 단, useRail 이고 레일에 children 없는 아이템이 있으면 메뉴 폭이 출렁이므로 full 로 강제된다. |
+| `color?` | `SGnbColor` | `'light'` | 색상 테마: light / dark |
+| `items` | `SGnbMenuItem[]` | — | 메뉴 트리 (depth1 → depth2 → depth3). useRail 이면 첫 depth 가 레일이 되고 그 children 이 depth1 이 된다. |
+| `useRail?` | `boolean` | — | 좌측 레일 사용 여부. 켜면 items 의 첫 depth 가 아이콘+라벨 버튼의 세로 레일로 서고, 선택된 레일 아이템의 children 이 오른쪽 메뉴 패널에 깔린다. 미지정 시 SLayout 의 useRail 을 따른다. children 없는 레일 아이템이 활성이면 메뉴 패널은 렌더되지 않고 레일만 남는다. |
+| `value?` | `string` | `''` | 현재 선택된 아이템 value |
+| `folded?` | `boolean` | — | 접힘(레일) 상태. 미지정 시 SLayout 의 folded 를 따른다. |
+| `logo?` | `ReactNode` | — | 상단바 로고 영역 (slot) |
+| `railFooter?` | `ReactNode` | — | 레일 하단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고 이 슬롯은 레일 하단에 붙어 고정된다. useRail 일 때만 렌더된다. |
+| `menuFooter?` | `ReactNode` | — | 메뉴 하단 고정 슬롯. 메뉴 아이템이 많아 넘치면 메뉴 목록(ul)만 스크롤되고 이 슬롯은 메뉴 하단에 붙어 고정된다. 메뉴가 렌더될 때만(showMenu) 나타난다. |
+| `foldedFooter?` | `ReactNode` | — | 접힘(fix 레일) 하단 고정 슬롯. 접으면 본문이 빠져나가며 rail/menu footer 도 사라지므로, 48px 폴드 레일 바닥에 붙는 별도 슬롯이다. header="fix" 로 접혔을 때만 나타난다. |
+| `ariaLabel?` | `string` | `'global navigation'` | 메뉴 landmark(nav) 의 접근성 레이블. 한 화면에 nav 가 여럿일 때 구분한다. |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 선택 변경 (sdUpdate) |
+| `onRailChange` | `(value: string) => void` | 레일 선택 변경. 레일 아이템을 눌러 패널이 바뀔 때 알린다(선택 상태는 SGnb 가 자체 관리). |
+| `onFoldChange` | `(folded: boolean) => void` | 접힘 토글 (sdFoldChange) |
+| `onLauncherClick` | `() => void` | 앱런처(그리드) 버튼 클릭. 미지정 시 런처 버튼을 렌더하지 않는다. 접힘 레일(fix)에는 폴드 버튼만 남으므로 표시되지 않는다. |
+
+## Dependencies
+
+### Used by
+
+ - [SLayout](../SLayout)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+- [SLayout](../SLayout)
+- [STag](../STag)
+
+### Graph
+
+---
+
+# SGuide
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SGuide
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SGuideType` | `'tip'` | 가이드 타입 (tip: 팝업, notion: 외부 링크) |
+| `label?` | `string` | `''` | 버튼 레이블 (없으면 type 기본값) |
+| `message?` | `SGuideMessage` | `''` | 팝업 메시지 (배열이면 리스트, 중첩 배열이면 depth 표현) |
+| `url?` | `string` | `''` | notion 타입 클릭 시 이동 URL |
+| `popupTitle?` | `string` | `''` | 팝업 제목 (없으면 type 기본값) |
+| `popupWidth?` | `number` | — | 팝업 너비 (px, 기본 426) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SIcon
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SIcon
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `SIconName` | — | 아이콘명 |
+| `size?` | `number \| string` | `24` | 아이콘 크기(px 또는 CSS 길이) |
+| `color?` | `SColor` | — | 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상. 미지정 시 currentColor 상속 |
+| `rotate?` | `0 \| 90 \| 180 \| 270` | — | 회전 각도 |
+| `label?` | `string` | — | 접근성 라벨. 없으면 aria-hidden 처리 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Used by
+
+ - [SButton](../SButton)
+ - [SCallout](../SCallout)
+ - [SCheckbox](../SCheckbox)
+ - [SChipInput](../SChipInput)
+ - [SConfirmModal](../SConfirmModal)
+ - [SDatePicker](../SDatePicker)
+ - [SDateRangePicker](../SDateRangePicker)
+ - [SDraggableItem](../SDraggableItem)
+ - [SDropdownButton](../SDropdownButton)
+ - [SExpansionItem](../SExpansionItem)
+ - [SField](../SField)
+ - [SFilePicker](../SFilePicker)
+ - [SGhostButton](../SGhostButton)
+ - [SGnb](../SGnb)
+ - [SGuide](../SGuide)
+ - [SKeyValueTable](../SKeyValueTable)
+ - [SList](../SList)
+ - [SLoadingModal](../SLoadingModal)
+ - [SNumberInput](../SNumberInput)
+ - [SPagination](../SPagination)
+ - [SPopover](../SPopover)
+ - [SSectionHeaderCard](../SSectionHeaderCard)
+ - [SSelect](../SSelect)
+ - [SStepper](../SStepper)
+ - [STable](../STable)
+ - [STag](../STag)
+ - [STextLink](../STextLink)
+ - [STimePicker](../STimePicker)
+ - [STimeRangePicker](../STimeRangePicker)
+ - [SToast](../SToast)
+ - [STooltip](../STooltip)
+
+### Graph
+
+---
+
+# SInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| number` | — | 값 (제어) |
+| `type?` | `'text' \| 'password' \| 'email' \| 'number' \| 'tel' \| 'search' \| 'url'` | `'text'` | 입력 타입 |
+| `size?` | `SFieldSize` | `'sm'` | 크기 |
+| `icon?` | `SIconName` | — | 좌측 아이콘명 |
+| `iconColor?` | `SColor` | — | 좌측 아이콘 색상 |
+| `prefix?` | `ReactNode` | — | 입력 앞(좌측) 커스텀 노드 — 원본 slot="prefix" |
+| `suffix?` | `ReactNode` | — | 입력 뒤(우측) 커스텀 노드 — 원본 slot="suffix" |
+| `clearable?` | `boolean` | `false` | 지우기 버튼 |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 자동 검증 |
+| `status?` | `SFieldStatus` | — | 필드 상태 ('default' | 'pass' | 'error') |
+| `focused?` | `boolean` | — | 포커스 상태 (제어/반영) |
+| `hovered?` | `boolean` | — | 호버 상태 (제어/반영) |
+| `inputClass?` | `string` | — | 내부 input 요소 className |
+| `inputStyle?` | `CSSProperties` | — | 내부 input 요소 style |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `labelTooltip?` | `string` | — | 레이블 툴팁 텍스트 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — | 어드온 정렬 |
+| `width?` | `number \| string` | — |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 값 변경 (sdUpdate) — 문자열 전달 |
+| `onChange` | `InputHTMLAttributes<HTMLInputElement>['onChange']` | 네이티브 onChange (form-agnostic 연동용, RHF 등) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+---
+
+# SKeyValueTable
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SKeyValueTable
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields?` | `SKeyValueField[][]` | `[]` | 2차원 배열. row → [th|td] 필드들 |
+| `values?` | `Record<string, unknown>` | `{}` | field name을 key로 하는 값 객체 (`{ [name]: value }`). 지정 시 해당 field의 값으로 사용되며, field별 `options.value`보다 우선합니다. `onChange`의 `detail.values`와 함께 controlled 패턴으로 사용합니다. |
+| `search?` | `boolean` | `false` | 우측 검색 패널 |
+| `radius?` | `'default' \| 'useTop' \| 'full'` | `'default'` | border-radius 제어 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onChange` | `(detail: SKeyValueChangeDetail) => void` | 값 변경 (sdChange) |
+| `onSearch` | `() => void` | 검색 클릭 (sdSearch) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SCheckbox](../SCheckbox)
+- [SDatePicker](../SDatePicker)
+- [SDateRangePicker](../SDateRangePicker)
+- [SFilePicker](../SFilePicker)
+- [SIcon](../SIcon)
+- [SInput](../SInput)
+- [SNumberInput](../SNumberInput)
+- [SRadio](../SRadio)
+- [SSelect](../SSelect)
+- [STextarea](../STextarea)
+- [STooltip](../STooltip)
+
+### Graph
+
+---
+
+# SLayout
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLayout
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type?` | `SLayoutType` | `'box'` | 메뉴 스타일: box(라운드) / belt(풀폭 행). 자식 SGnb 가 이 값을 따른다. |
+| `header?` | `SLayoutHeader` | `'fix'` | 레이아웃 구조: fix(가로 분할) / full(풀폭 상단바). 자식 SGnb·SPage 가 이 값을 따른다. |
+| `useRail?` | `boolean` | `false` | GNB 좌측 레일 사용 여부. 자식 SGnb 가 이 값을 따르고, full 의 메뉴 열 폭도 레일만큼 넓어진다. 레일에 children 없는 아이템이 있으면 SGnb 가 header 를 full 로 강제하고, 이 레이아웃도 그에 맞춰 full 그리드로 선다. |
+| `folded?` | `boolean` | — | GNB 접힘 상태 (controlled) |
+| `defaultFolded?` | `boolean` | `false` | GNB 초기 접힘 상태 (uncontrolled) |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onFoldedChange` | `(folded: boolean) => void` | 접힘 상태 변경 |
+
+## Dependencies
+
+### Used by
+
+ - [SGnb](../SGnb)
+ - [SPage](../SPage)
+
+### Depends on
+
+- [SGnb](../SGnb)
+
+### Graph
+
+---
+
+# SLinearProgress
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLinearProgress
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `number` | `0` | 진행률 (0–100) |
+| `type?` | `SLinearProgressType` | `'primary'` | 색상 타입 |
+| `indeterminate?` | `boolean` | `false` | 진행률 없이 무한 애니메이션 |
+| `label?` | `string` | — | 하단 레이블 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+---
+
+# SList
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SList
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | `ReactNode` | — | 리스트 컨테이너 내부에 렌더링할 내용 |
+| `useGap?` | `boolean` | `false` | 리스트 아이템 사이 gap 토큰 적용 여부 |
+| `usePadding?` | `boolean` | `false` | 리스트 컨테이너 padding 토큰 적용 여부 |
+
+---
+
+# SListItem
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SListItem
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `SListItemSlot` | — | 리스트 아이템 제목 |
+| `depth?` | `1 \| 2 \| 3` | `1` | 중첩 단계. Figma 기준 1~3단계 |
+| `leading?` | `SListItemSlot` | — | 타이틀 앞에 표시할 아이콘/콘텐츠 |
+| `trailing?` | `SListItemSlot` | — | 타이틀 뒤에 표시할 태그/콘텐츠 |
+| `bordered?` | `boolean` | `false` | 외곽 테두리 사용 여부 |
+| `accentStripe?` | `boolean` | `false` | 아이템 왼쪽 accent stripe 표시 여부 |
+| `dense?` | `boolean` | `false` | 조밀한 높이 사용 여부 |
+| `disabled?` | `boolean` | `false` | 비활성 상태 여부 |
+
+---
+
+# SLoadingContainer
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLoadingContainer
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | `false` | 오버레이 표시 여부 (Stencil의 show()/hide() 명령형 API → 제어 prop으로 대체) |
+| `message?` | `string` | — | 스피너 하단 메시지 |
+| `zIndex?` | `number` | `1200` | z-index. 기본값(1200)은 토스트(1100)·모달(1000/1001) 위 — 전체 화면을 막는 최상단 블로킹 오버레이 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Depends on
+
+- [SCircleProgress](../SCircleProgress)
+
+### Graph
+
+---
+
+# SLoadingModal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SLoadingModal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — |  |
+| `persistent?` | `boolean` | — | true면 백드롭·ESC로 안 닫히고 흔들림 (sd-modal-container persistent). 로딩 중 닫힘 방지에 유용 |
+| `state?` | `LoadingModalState` | `'loading'` | 상태 (loading: 스피너, error: 경고 아이콘) |
+| `progress?` | `number` | — | 진행률 (0–100) — 지정 시 determinate 스피너 |
+| `message?` | `string \| string[]` | — | 메시지 (없으면 state 기본값) |
+| `useButton?` | `boolean` | `false` | 하단 버튼 표시 |
+| `buttonLabel?` | `string` | — | 버튼 레이블 (없으면 state 기본값) |
+| `width?` | `number \| string` | `520` |  |
+| `height?` | `number \| string` | `320` |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` |  |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 (sdClose) — error 상태에서만 노출 |
+| `onButtonClick` | `() => void` | 버튼 클릭 (sdClick) |
+
+## Dependencies
+
+### Used by
+
+ - [SModal](../SModal)
+
+### Depends on
+
+- [SButton](../SButton)
+- [SCircleProgress](../SCircleProgress)
+- [SIcon](../SIcon)
+- [SModalContainer](../SModalContainer)
+
+### Graph
+
+---
+
+# SModal
+
+> 수작성 문서 — SModal 은 컴포넌트가 아니라 **명령형 모달 서비스**라 `docs:gen`(Props/Events 표) 대상이 아니다.
+
+버튼 핸들러에서 바로 호출해 모달을 띄우는 명령형 API. 선언형 `<SConfirmModal open>` / `<SLoadingModal open>` 을 **대체하지 않고 추가로** 제공한다. (원본 디자인 시스템 `sdModal` 파리티)
+
+호출 시마다 `document.body` 에 컨테이너를 만들어 모달을 렌더하고, 닫힘 애니메이션이 끝나면 자동으로 언마운트한다. 모든 메서드는 체이닝 핸들 [`SModalRef`](#smodalref) 를 반환한다.
+
+| 메서드 | 띄우는 모달 | 용도 | 주요 콜백/제어 |
+|---|---|---|---|
+| [`SModal.confirm(options)`](#smodalconfirm) | `SConfirmModal` | 확인/취소 | `onOk` / `onCancel` / `onClose` |
+| [`SModal.loading(options?)`](#smodalloading) | `SLoadingModal` | 로딩·에러 (persistent 기본 true) | `onClick` / `update` |
+| [`SModal.create({ component })`](#smodalcreate) | `SActionModal` | 액션 모달 | `modalRef` 주입 → `ok/cancel/close/submit` |
+
+> **띄울 수 있는 모달은 `SActionModal` / `SConfirmModal` / `SLoadingModal` 세 가지뿐이고, 위 메서드가 1:1 로 대응한다.** 그 밖의 스타일로 모달을 띄우는 경로는 제공하지 않는다. `create` 는 컨테이너를 덧씌우지 않고 `component` 를 **그대로** 렌더하므로, `component` 는 루트에 `SActionModal` 을 렌더해야 한다 — 그러지 않으면 딤·카드 없이 콘텐츠만 뜨며, 개발 모드에서 `console.warn` 으로 경고한다.
+
+```ts
+import { SModal } from 'sellmate-design-system-react';
+```
+
+---
+
+## SModal.confirm
+
+아이콘 + 제목 + 메시지 + 확인/취소 버튼. `type` 에 따라 아이콘·메인 버튼 색이 결정된다.
+
+```tsx
+SModal.confirm({
+  type: 'negative',                 // 'positive' | 'negative' | 'default'
+  modalTitle: '삭제하시겠습니까?',
+  topMessage: ['이 작업은 되돌릴 수 없습니다.'],
+  mainButtonLabel: '삭제',
+  subButtonLabel: '취소',
+})
+  .onOk(() => deleteItem())
+  .onCancel(() => {});
+```
+
+**옵션 (`SConfirmOptions`)** — 선언형 `SConfirmModalProps` 에서 제어 흐름 props(`open`/`onOpenChange`/`onOk`/`onCancel`/`onClose`)를 제외한 전부. 주요 키: `type`, `modalTitle`, `topMessage`/`bottomMessage`, `mainButtonLabel`/`mainButtonName`, `subButtonLabel`, `tagSlot`/`optionSlot`, `persistent`.
+
+---
+
+## SModal.loading
+
+스피너/에러 모달. 로딩 중 임의 닫힘을 막기 위해 **`persistent` 기본값이 `true`** 다(백드롭·ESC로 안 닫힘). "띄우고 → 작업 → 결과 반영" 흐름을 `update()` / `close()` 로 제어한다.
+
+```tsx
+const ref = SModal.loading({ message: '업로드 중...' });
+try {
+  await upload();
+  ref.close();
+} catch {
+  ref.update({ state: 'error', message: '업로드 실패' })  // 표시 중 상태 갱신
+     .onClick(() => retry());                             // 「다시 시도」 버튼
+}
+```
+
+진행률:
+
+```tsx
+const ref = SModal.loading({ progress: 0, message: '파일 업로드 중...' });
+ref.update({ progress: 60 });          // 0–100
+ref.update({ progress: 100 });
+ref.close();
+```
+
+> **버튼 클릭은 자동 닫힘이 아니다.** error 상태의 버튼(기본 "다시 시도")은 `onClick` 만 발화하고 모달은 유지된다. consumer 가 `update()`(다시 로딩) / `close()` 로 후속 동작을 결정한다.
+
+**옵션 (`SLoadingOptions`)** — `state`('loading' | 'error'), `progress`(0–100), `message`(string | string[]), `useButton`, `buttonLabel`, `width`/`height`, `persistent`.
+
+---
+
+## SModal.create
+
+**`SActionModal` 을 루트로 렌더하는 컴포넌트**를 띄운다. `create` 는 컨테이너를 덧씌우지 않고 `component` 를 **그대로** 렌더하며, 표시 제어(`open` / `onOpenChange` / `onClose`)와 [`modalRef`](#smodalref) 를 주입하고 닫힘 애니메이션 종료 후 언마운트를 담당한다.
+
+컴포넌트는 주입받은 `open` / `onOpenChange` / `onClose` 를 **SActionModal 에 그대로 전달**해야 한다. 전달하지 않으면 모달이 열리지도, 닫히지도 않는다.
+
+```tsx
+import { SModal, SActionModal, type SModalCreateComponentProps } from 'sellmate-design-system-react';
+
+// componentProps 로 넘긴 값 + 주입 prop 을 함께 받는다
+interface OrderModalProps extends SModalCreateComponentProps {
+  orderId: string;
+}
+
+function OrderModal({ open, onOpenChange, onClose, modalRef, orderId }: OrderModalProps) {
+  return (
+    <SActionModal
+      open={open}
+      onOpenChange={onOpenChange}
+      onClose={onClose}
+      modalTitle="주문 처리"
+      button={{ label: '처리', onClick: () => modalRef.ok() }}
+    >
+      <p>주문번호 {orderId} 를 접수합니다.</p>
+    </SActionModal>
+  );
+}
+
+SModal.create({ component: OrderModal, componentProps: { orderId: 'ORD-001' } })
+  .onOk(() => toast('저장 완료'))
+  .onDismissed(() => cleanup());
+```
+
+**옵션 (`SCreateOptions<P>`)**
+
+| 키 | 타입 | 설명 |
+|---|---|---|
+| `component` | `ComponentType<P & SModalCreateComponentProps>` | 루트에 `SActionModal` 을 렌더하는 컴포넌트 |
+| `componentProps?` | `P` | 컴포넌트에 전달할 추가 props |
+
+**주입되는 prop (`SModalCreateComponentProps`)**
+
+| 키 | 타입 | 설명 |
+|---|---|---|
+| `open` | `boolean` | SActionModal 의 `open` 에 그대로 전달 |
+| `onOpenChange` | `(open: boolean) => void` | SActionModal 의 `onOpenChange` 에 그대로 전달 |
+| `onClose` | `() => void` | SActionModal 의 `onClose` 에 그대로 전달 |
+| `modalRef` | `SModalRef` | `ok()`/`cancel()`/`close()`/`submit()` 으로 자기 모달 제어 |
+
+### 비동기 제출 — 응답 보고 닫기
+
+SActionModal `button` 의 푸터 버튼은 클릭 시 **즉시 닫힌다**. 저장 API 응답에 따라 닫힘 여부를 정해야 하면 푸터 버튼 대신 **본문에 버튼을 두고** `modalRef` 로 닫힘 시점을 직접 제어한다.
+
+```tsx
+function OrderModal({ open, onOpenChange, onClose, modalRef, orderId }: OrderModalProps) {
+  const [error, setError] = useState('');
+  const handleSubmit = async () => {
+    try {
+      await save(orderId);
+      modalRef.ok();          // 성공 → onOk + 닫기
+    } catch {
+      setError('저장 실패');   // 실패 → 모달 유지
+    }
+  };
+  return (
+    // button 을 주지 않으면 푸터가 렌더되지 않는다
+    <SActionModal open={open} onOpenChange={onOpenChange} onClose={onClose} persistent modalTitle="주문 처리">
+      {error && <p>{error}</p>}
+      <SButton label="저장" onClick={handleSubmit} />
+      <SButton label="취소" onClick={() => modalRef.cancel()} />
+    </SActionModal>
+  );
+}
+```
+
+---
+
+## SModalRef
+
+모든 `SModal.*` 호출이 반환하고, `create` 에서는 컴포넌트 prop 으로도 주입되는 제어 핸들. 콜백 등록(체이닝)과 트리거/갱신 메서드를 함께 제공한다. 모달 종류에 따라 관련 있는 메서드만 실제로 발화한다.
+
+### 콜백 등록 (체이닝)
+
+| 메서드 | 발화 시점 |
+|---|---|
+| `onOk(fn)` | 확인 버튼(confirm) 또는 `ok()` |
+| `onCancel(fn)` | 취소 버튼(confirm) 또는 `cancel()` |
+| `onClose(fn)` | 닫기(X) 버튼 또는 `close()` |
+| `onClick(fn)` | 단일 버튼 모달(loading error)의 버튼 클릭 — **닫힘 없음** |
+| `onSubmit(fn)` | create 커스텀 모달의 `submit()` — **닫힘 없음** |
+| `onDismissed(fn)` | 사유 무관 완전히 닫혀 언마운트된 뒤(백드롭·ESC 포함) |
+
+### 트리거 / 제어
+
+| 메서드 | 동작 |
+|---|---|
+| `ok()` | `onOk` 발화 + 닫기 (저장/처리 성공) |
+| `cancel()` | `onCancel` 발화 + 닫기 (작업 취소) |
+| `close()` | `onClose` 발화 + 닫기 (중립적 닫기) |
+| `submit()` | `onSubmit` 발화 (닫힘 없음) |
+| `update(patch)` | 표시 중 옵션 갱신 (loading→error, progress 등). create 는 미지원. |
+
+모든 닫힘은 애니메이션 종료 후 `onDismissed` 로 수렴한다. 이미 닫힘이 시작된 뒤의 중복 트리거는 무시된다.
+
+---
+
+## 주의사항
+
+- **선언형과 공존**: 서비스는 추가 API다. open 상태가 앱 상태/라우트에 묶인 경우엔 선언형 `<SConfirmModal open>` / `<SLoadingModal open>` 이 더 적합하다.
+- **백드롭·ESC = 중립적 닫힘**: 특정 콜백(onClose 등) 없이 `onDismissed` 만 발화한다. 명시적 버튼·메서드만 onOk/onCancel/onClose 를 발화한다.
+- **Context 미상속**: `create` 의 커스텀 컴포넌트는 새 React 트리(createRoot)에서 렌더되어 부모의 Context Provider(Theme·Store 등)를 상속하지 않는다. 필요하면 컴포넌트 내부에서 직접 Provider 로 감싸라. (confirm/loading 은 토큰이 `:root` CSS 변수라 무관)
+- **`create` 의 `component` 는 SActionModal 을 루트로**: `create` 는 컨테이너를 덧씌우지 않으므로, 본문만 렌더하는 컴포넌트를 넘기면 딤·카드 없이 콘텐츠가 그대로 화면에 붙는다. TypeScript 는 이를 막지 못한다(`component` 타입이 아무 컴포넌트나 허용). 개발 모드에서는 마운트 직후 렌더 결과로 이를 감지해 `console.warn` 으로 경고한다 — 세 모달은 모두 Portal 로 `body` 에 렌더되므로 `create` 가 만든 host 는 비어 있어야 하는데, host 에 엘리먼트가 남아 있으면 모달이 아닌 것으로 판정한다.
+
+## Dependencies
+
+### Depends on
+
+- [SActionModal](../SActionModal)
+- [SConfirmModal](../SConfirmModal)
+- [SLoadingModal](../SLoadingModal)
+
+---
+
+# SModalContainer
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SModalContainer
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — | 표시 여부 (제어) |
+| `ariaTitle?` | `string` | `'모달'` | 접근성 제목 (스크린리더용). 시각 제목은 children이 담당 |
+| `showClose?` | `boolean` | `false` | 우측 상단 닫기 버튼 |
+| `persistent?` | `boolean` | `false` | true면 백드롭 클릭·ESC로 닫히지 않고 흔들림(shake) 애니메이션 (sd-modal-container persistent) |
+| `width?` | `number \| string` | — | 너비/높이 |
+| `height?` | `number \| string` | — |  |
+| `children?` | `ReactNode` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` | 표시 상태 변경 |
+| `onClose` | `() => void` | 닫기(X) 버튼 클릭 시 발생 (sd-modal-container 닫기 버튼 대응) |
+
+## Dependencies
+
+### Used by
+
+ - [SActionModal](../SActionModal)
+ - [SConfirmModal](../SConfirmModal)
+ - [SLoadingModal](../SLoadingModal)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+
+### Graph
+
+---
+
+# SNumberInput
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SNumberInput
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| number \| null` | — | 입력 값 |
+| `size?` | `SNumberInputSize` | `'sm'` | 크기 |
+| `min?` | `number` | `Number.NEGATIVE_INFINITY` | 최솟값 |
+| `max?` | `number` | `Number.POSITIVE_INFINITY` | 최댓값 |
+| `step?` | `number` | `1` | 스텝 단위 |
+| `useButton?` | `boolean` | `false` | 증감 버튼 표시 |
+| `useDecimal?` | `boolean` | `false` | 소수점 입력 허용 |
+| `maxDecimalLength?` | `number` | — | 소수점 이하 최대 자리수 |
+| `inputPrefix?` | `string` | `''` | 입력 앞 접두 텍스트 |
+| `inputSuffix?` | `string` | `''` | 입력 뒤 접미 텍스트 |
+| `inputClass?` | `string` | — | 네이티브 input className |
+| `inputStyle?` | `CSSProperties` | — | 네이티브 input style |
+| `autoFocus?` | `boolean` | — | 마운트 시 자동 포커스 |
+| `name?` | `string` | — | 폼 연동 name |
+| `placeholder?` | `string` | `'입력해 주세요.'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 검증 |
+| `status?` | `SFieldStatus` | — |  |
+| `focused?` | `boolean` | — |  |
+| `hovered?` | `boolean` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: number \| null) => void` | 값 변경 (sdUpdate) — number|null 전달 |
+| `onFocus` | `(e: React.FocusEvent<HTMLInputElement>) => void` | 포커스 이벤트 (sdFocus) |
+| `onBlur` | `(e: React.FocusEvent<HTMLInputElement>) => void` | 블러 이벤트 (sdBlur) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SField](../SField)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SPage
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SPage
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `background?` | `SPageBackground` | `'frame'` | 페이지 배경 표면. frame=흰 콘텐츠 면, neutral=옅은 회색 면, screen=앱 바탕. 스크롤바 처리도 여기 묶여 있다 — 셋 다 구분선+트랙 배경이고, 트랙 색만 neutral 에서 흰색이 된다. |
+
+## Dependencies
+
+### Depends on
+
+- [SLayout](../SLayout)
+
+### Graph
+
+---
+
+# SPagination
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SPagination
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currentPage?` | `number` | `1` | 현재 페이지 |
+| `lastPage?` | `number` | `1` | 마지막 페이지 |
+| `simple?` | `boolean` | `false` | 단순 모드 (현재/마지막만 표시) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onPageChange` | `(page: number) => void` | 페이지 변경 (sdPageChange) |
+
+## Dependencies
+
+### Used by
+
+ - [STable](../STable)
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SPopover
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SPopover
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open?` | `boolean` | — | 표시 여부 (제어). onOpenChange 와 함께 사용 |
+| `defaultOpen?` | `boolean` | — | 기본 표시 여부 (비제어) |
+| `placement?` | `SPopoverPlacement` | `'bottom'` | 표시 방향 |
+| `type?` | `SPopoverType` | `'default'` | 색상 타입 (default: 다크 / danger·warning·accent: 라이트 배경) |
+| `menuTitle` | `string` | — | 메뉴 제목 (필수) |
+| `titleIcon?` | `SIconName` | — | 제목 좌측 아이콘 (선택) |
+| `children?` | `ReactNode` | — | 본문 내용 |
+| `trigger?` | `ReactNode` | — | 커스텀 트리거. 없으면 아이콘 트리거 렌더 |
+| `icon?` | `SIconName` | `'helpOutline'` | 기본(아이콘) 트리거 설정 |
+| `iconSize?` | `number` | `12` |  |
+| `color?` | `SColor` | `'#01BB4B'` | 트리거 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 |
+| `leftLinkLabel?` | `string` | — | 하단 좌측 링크 레이블 (선택). 스타일은 chevron 링크로 고정 |
+| `buttonLabel` | `string` | — | 하단 우측 버튼 레이블 (필수). 색상/스타일은 type 별로 고정 |
+| `ariaLabel?` | `string` | — |  |
+| `menuClassName?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onOpenChange` | `(open: boolean) => void` | 표시 상태 변경 (sdShowChange) |
+| `onLeftLinkClick` | `() => void` | 하단 좌측 링크 클릭 |
+| `onButtonClick` | `() => void` | 하단 우측 버튼 클릭 |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+- [STextLink](../STextLink)
+
+### Graph
+
+---
+
+# SPopup
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SPopup
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `popupTitle?` | `string` | `''` | 헤더 제목 |
+| `type?` | `SPopupType` | `'default'` | 타입 (헤더 색상) |
+| `useFooter?` | `boolean` | `true` | 하단 footer 표시 여부 |
+| `submitButton?` | `SPopupSubmitButton` | — | 확인 버튼 설정 |
+| `footerLeft?` | `ReactNode` | — | footer 좌측 영역 |
+| `children?` | `ReactNode` | — | 본문 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onSubmit` | `() => void` | 확인 버튼 클릭 (sdSubmit) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+
+### Graph
+
+---
+
+# SPortal
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SPortal
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | — | 표시 여부 (제어). onClose 와 함께 사용한다. |
+| `anchorRef` | `RefObject<HTMLElement \| null>` | — | 위치 기준이 되는 앵커 엘리먼트 ref (sd-portal `parentRef` 대응). 트리거 버튼 등에 그대로 걸면 그 엘리먼트에 붙어서 뜬다. |
+| `placement?` | `SPortalPlacement` | `'bottom'` | 표시 방향 (공간이 부족하면 자동으로 반대 방향으로 전환). |
+| `align?` | `SPortalAlign` | `'start'` | 교차축 정렬 (start·center·end). |
+| `offset?` | `number` | `4` | 앵커로부터의 간격 px (sd-portal offset[1]). |
+| `alignOffset?` | `number` | `0` | 정렬축 오프셋 px (sd-portal offset[0]). |
+| `fit?` | `boolean` | `false` | 앵커 너비에 맞춰 최소 너비를 잡는다. |
+| `maxHeight?` | `number` | — | 콘텐츠 최대 높이 px. 넘치면 세로 스크롤. |
+| `autoClose?` | `boolean` | `false` | 콘텐츠 내부를 클릭하면 자동으로 닫는다. |
+| `persistent?` | `boolean` | `false` | 외부 클릭 · ESC 로 닫히지 않게 한다. |
+| `viewportPadding?` | `number` | `0` | 뷰포트 경계 여백 px (충돌 회피 패딩). |
+| `children?` | `ReactNode` | — | 본문 내용 (콘텐츠 자유). |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+| `ariaLabel?` | `string` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onClose` | `() => void` | 외부 클릭 · ESC 등으로 닫힘이 요청될 때 (sd-portal `sdClose` 대응). |
+| `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 전체 콜백 (선택). |
+| `onOpenAutoFocus` | `(event: Event) => void` | 열릴 때 포커스 이동 처리 (기본은 Radix가 콘텐츠로 포커스를 옮김). e.preventDefault()로 막을 수 있다. |
+| `onCloseAutoFocus` | `(event: Event) => void` | 닫힐 때 포커스 복귀 처리 (기본은 Radix가 앵커로 포커스를 되돌림). e.preventDefault()로 막을 수 있다. |
+| `onPointerDownOutside` | `(event: Event) => void` | 바깥 영역 pointerdown 으로 닫힘이 시작될 때 (앵커 위 클릭·persistent 는 제외). |
+
+## Dependencies
+
+### Used by
+
+ - [SChipInput](../SChipInput)
+ - [SSelect](../SSelect)
+
+### Graph
+
+---
+
+# SRadio
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SRadioGroup
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options?` | `SRadioOption[]` | `[]` | 옵션 목록 |
+| `value?` | `SRadioValue \| null` | — | 현재 선택 값 |
+| `direction?` | `'vertical' \| 'horizontal'` | `'vertical'` | 배치 방향 |
+| `disabled?` | `boolean` | `false` | 전체 비활성 |
+| `groupName?` | `string` | — | 라디오 name 속성 (form-agnostic 그룹핑) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(val: SRadioValue) => void` | 선택 변경 (sdUpdate) |
+
+### SRadio
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `val` | `SRadioValue` | — | 이 라디오의 값 |
+| `value?` | `SRadioValue \| null` | — | 그룹의 현재 선택 값 |
+| `label?` | `string` | — | 라벨 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `name?` | `string` | — | native radio name (form-agnostic 그룹핑) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(val: SRadioValue) => void` | 선택 변경 (sdUpdate) — 선택된 val 전달 |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Graph
+
+---
+
+# SRadioButton
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SRadioButton
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options?` | `SRadioButtonOption[]` | `[]` | 옵션 목록 |
+| `value?` | `string \| number \| null` | — | 현재 선택 값 |
+| `size?` | `SRadioButtonSize` | `'sm'` | 크기 |
+| `disabled?` | `boolean` | `false` | 전체 비활성 |
+| `name?` | `string` | — | input name 속성 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string \| number) => void` | 변경 (sdUpdate) |
+
+---
+
+# SScrollArea
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SScrollArea
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `axis?` | `SScrollAreaAxis` | `'both'` | 스크롤 방향. vertical=세로만, horizontal=가로만, both=양방향 |
+| `background?` | `boolean` | `false` | true면 스크롤바 트랙 배경을 채운다. 콘텐츠 영역 배경은 바뀌지 않는다. |
+| `bordered?` | `boolean` | `false` | true면 스크롤바와 콘텐츠 사이에 1px 구분선을 그린다. 컨테이너 테두리가 아니다. |
+| `maxHeight?` | `string` | — | viewport 최대 높이 (예: '400px'). 비우면 부모 크기를 따른다. |
+| `maxWidth?` | `string` | — | viewport 최대 너비 (예: '480px'). 비우면 부모 크기를 따른다. |
+
+---
+
+# SSectionHeaderCard
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSectionHeaderCardBody
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | `SSectionHeaderCardBodyChildren` | — | 바디 슬롯. 특정 컴포넌트 타입으로 제한하지 않습니다. |
+
+### SSectionHeaderCardHeader
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `ReactNode` | — | 헤더 제목 |
+| `marker?` | `boolean` | `false` | 제목 앞 점 표시 여부 |
+| `required?` | `boolean` | `false` | 제목 뒤 필수 별 표시 여부 |
+| `helpText?` | `string[]` | — | 도움말 툴팁 메시지 |
+| `subtitle?` | `ReactNode` | — | 부제 |
+| `slot?` | `ReactNode` | — | 헤더 우측 슬롯 |
+| `thickness?` | `SSectionHeaderCardThickness` | `false` | 상단 border 색상 타입. false면 표시하지 않습니다. |
+
+### SSectionHeaderCard
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | `SSectionHeaderCardChildren` | — | SSectionHeaderCard 슬롯. 특정 컴포넌트 타입으로 제한하지 않습니다. |
+
+## Dependencies
+
+### Depends on
+
+- [SBadge](../SBadge)
+- [SIcon](../SIcon)
+- [STooltip](../STooltip)
+
+### Graph
+
+---
+
+# SSelect
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSelect
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `(string \| number \| SSelectOption) \| (string \| number \| SSelectOption)[] \| null` | — | 선택 값. multi 타입이면 배열. emitValue=false(기본) 라운드트립을 위해 SSelectOption 객체도 허용 |
+| `emitValue?` | `boolean` | `false` | true면 SSelectOption 대신 원시값(string|number) 방출 |
+| `name?` | `string` | — | 폼 연동용 name 속성 |
+| `options?` | `SSelectOption[]` | `[]` | 옵션 목록 (children으로 계층 표현) |
+| `type?` | `SSelectType` | `'default'` | 타입: default | multi | default_depth | multi_depth |
+| `useSearch?` | `boolean` | `false` | 검색 입력 사용 |
+| `useSelectAll?` | `boolean` | `false` | 전체선택 옵션 사용 (multi 전용) |
+| `allSelectedLabel?` | `string` | `'전체'` | 전체선택 레이블 |
+| `placeholder?` | `string` | `'선택'` | placeholder |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `error?` | `boolean` | `false` | 에러 상태 |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — 닫힐 때 자동 검증 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
+| `dropdownHeight?` | `string` | `'260px'` | 드롭다운 최대 높이 |
+| `dropdownWidth?` | `string` | — | 드롭다운 너비 (없으면 트리거 너비) |
+| `maxDropdownWidth?` | `string` | `'640px'` | 드롭다운 최대 너비 |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — | 레이블 영역 아이콘 |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — | 레이블 툴팁 텍스트 |
+| `addonLabel?` | `string` | — | 우측 어드온 레이블 |
+| `addonAlign?` | `SFieldAddonAlign` | — | 어드온 정렬 |
+| `hint?` | `string` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: any) => void` | 값 변경 (sdUpdate). emitValue=false(기본)면 SSelectOption(들), true면 원시값 |
+| `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `focus` | `() => void` | 트리거 버튼에 포커스 (sdFocus) |
+| `open` | `() => void` | 드롭다운 열기 (sdOpen) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+ - [STable](../STable)
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+- [SPortal](../SPortal)
+
+### Graph
+
+---
+
+# SStepper
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SStepper
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `SStepperItem[]` | — | 단계 목록 |
+| `value?` | `string` | — | 현재 활성 단계 value |
+| `size?` | `SStepperSize` | `'sm'` | 크기 |
+| `ariaLabel?` | `string` | `'진행 단계'` | 접근성 레이블 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+## Dependencies
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SSwitch
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SSwitch
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `boolean` | `false` | on/off 상태 |
+| `leftLabel?` | `string` | — | 스위치 좌측 라벨 |
+| `rightLabel?` | `string` | — | 스위치 우측 라벨 |
+| `label?` | `string` | — |  |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: boolean) => void` | 변경 (sdUpdate) |
+
+---
+
+# STable
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STable
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns?` | `STableColumn[]` | `[]` |  |
+| `rows?` | `SRow[]` | `[]` |  |
+| `rowKey?` | `string` | `'id'` | 행 식별 필드 |
+| `selectable?` | `boolean` | `false` | 행 선택 체크박스 |
+| `selected?` | `SRow[]` | `[]` |  |
+| `resizable?` | `boolean` | `false` | 컬럼 너비 조절 |
+| `width?` | `string` | — |  |
+| `height?` | `string` | — |  |
+| `stickyHeader?` | `boolean` | — |  |
+| `stickyColumn?` | `STableStickyColumn` | — | 고정할 좌/우 컬럼 수 |
+| `radius?` | `'default' \| 'useTop' \| 'full'` | `'default'` | border-radius 제어 |
+| `noDataLabel?` | `string` | `'데이터가 없습니다.'` |  |
+| `noDataSlot?` | `ReactNode` | — | 데이터가 없을 때 body 영역 전체를 대체하는 슬롯. 지정하면 `noDataLabel` 대신 이 콘텐츠가 헤더 아래 영역을 채우며, 버튼 등 인터랙션도 동작한다. |
+| `isLoading?` | `boolean` | `false` |  |
+| `dense?` | `boolean` | `false` |  |
+| `noHover?` | `boolean` | `false` | true면 행에 마우스를 올려도 hover 배경(grey_05)을 표시하지 않는다 |
+| `pagination?` | `STablePagination` | — | 페이지네이션 (있으면 하단 표시) |
+| `useInternalPagination?` | `boolean` | `false` | 테이블 내부에서 페이지네이션을 직접 관리 (rows를 내부 슬라이싱) |
+| `useRowsPerPageSelect?` | `boolean` | `false` | 페이지당 행 수 셀렉트 표시 |
+| `rowsPerPageOption?` | `SSelectOption[]` | `DEFAULT_ROWS_PER_PAGE_OPTION` |  |
+| `useVirtualScroll?` | `boolean` | `false` | 가상 스크롤 |
+| `rowHeight?` | `number` | — |  |
+| `virtualBuffer?` | `number` | `5` |  |
+| `virtualEndThreshold?` | `number` | `10` |  |
+| `tableId?` | `string` | — | 테이블 식별자 (없으면 자동 생성) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onSelectedChange` | `(rows: SRow[]) => void` |  |
+| `onPageChange` | `(page: number) => void` |  |
+| `onRowsPerPageChange` | `(perPage: number) => void` |  |
+| `onVirtualUpdate` | `(range: { from: number; to: number }) => void` |  |
+| `onVirtualReachEnd` | `(info: { from: number; to: number; rowCount: number; threshold: number; }) =>…` |  |
+| `onRowClick` | `(row: SRow) => void` | 행 클릭 |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `isRowSelected` | `(row: SRow) => boolean` | 행 선택 여부 |
+| `getIsAllChecked` | `(rows: SRow[]) => boolean \| null` | 주어진 행들의 전체 선택 상태 (true/false/null=indeterminate) |
+| `getPaginationInfo` | `<union 2종>` | 내부 페이지네이션 정보 (useInternalPagination 아니면 null) |
+| `getStickyStyle` | `(colIdx: number) => CSSProperties` | 컬럼 sticky 스타일 (CSS 변수 + 고정폭) |
+| `setRowCount` | `(count: number) => void` | 가상 스크롤 총 행 수 설정 |
+| `updateRowSelect` | `(row: SRow) => void` | 단일 행 선택 토글 (sd-table updateRowSelect) — onSelectedChange 발생 |
+| `toggleSelectAll` | `(checked: boolean, rows: SRow[]) => void` | 주어진 행들 전체 선택/해제 (sd-table toggleSelectAll) — onSelectedChange 발생 |
+
+## Dependencies
+
+### Depends on
+
+- [SCheckbox](../SCheckbox)
+- [SCircleProgress](../SCircleProgress)
+- [SIcon](../SIcon)
+- [SPagination](../SPagination)
+- [SSelect](../SSelect)
+
+### Graph
+
+---
+
+# STableBar
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STableBar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `total?` | `number` | — | 전체 건수. 지정하면 "총 N 건" 을 표시한다 (천단위 구분 자동) |
+| `selected?` | `number` | — | 선택 건수. 지정하면 "N건 선택" 을 표시한다 |
+| `actions?` | `ReactNode` | — | 구분선 오른쪽 좌측 액션 영역 |
+| `rightActions?` | `ReactNode` | — | 우측 정렬 액션 영역 |
+
+## Dependencies
+
+### Depends on
+
+- [SDivider](../SDivider)
+
+### Graph
+
+---
+
+# STabs
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STabs
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | 현재 선택된 탭 value |
+| `tabs` | `STabOption[]` | — | 탭 옵션 목록 |
+| `size?` | `STabSize` | `'md'` | 탭 크기 (main 전용) |
+| `isSub?` | `boolean` | `false` | 서브 탭(밑줄형) 스타일 |
+| `vertical?` | `boolean` | `false` | 세로 배치 (sub 전용 — main 폴더형은 항상 가로) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 탭 변경 (sdUpdate) |
+
+## Dependencies
+
+### Depends on
+
+- [STag](../STag)
+
+### Graph
+
+---
+
+# STag
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STag
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `shape?` | `STagShape` | `'square'` | 모양 |
+| `size?` | `STagSize` | `'sm'` | 크기 |
+| `color?` | `STagColor` | `'grey'` | 색상 |
+| `label?` | `string` | `''` | 레이블 텍스트 |
+| `icon?` | `SIconName` | — | 아이콘명 |
+| `iconLeft?` | `boolean` | `true` | 아이콘을 레이블 왼쪽에 배치 |
+| `width?` | `string \| number` | — | 태그 너비 (숫자면 px, 문자열이면 그대로 적용). 미지정 시 콘텐츠 크기 |
+
+## Dependencies
+
+### Used by
+
+ - [SConfirmModal](../SConfirmModal)
+ - [SGhostButton](../SGhostButton)
+ - [SGnb](../SGnb)
+ - [STabs](../STabs)
+ - [STextLink](../STextLink)
+
+### Depends on
+
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# STextLink
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STextLink
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label?` | `string` | `''` | 레이블 |
+| `icon?` | `SIconName` | — | 좌측 아이콘 |
+| `iconColor?` | `SColor` | — | 좌측 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 |
+| `labelClass?` | `string` | — | 레이블 span에 추가할 클래스 |
+| `rightArrow?` | `STextLinkArrow` | `'none'` | 우측 화살표 |
+| `underline?` | `boolean` | `false` | 밑줄 여부 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `size?` | `STextLinkSize` | `'sm'` | 크기 |
+| `tooltipText?` | `string` | — | 호버 시 표시할 툴팁 텍스트 (회색 STag 스타일) |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onClick` | `() => void` |  |
+
+## Dependencies
+
+### Used by
+
+ - [SChipInput](../SChipInput)
+ - [SPopover](../SPopover)
+
+### Depends on
+
+- [SIcon](../SIcon)
+- [STag](../STag)
+
+### Graph
+
+---
+
+# STextarea
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STextarea
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string` | — | 값 (제어) |
+| `rows?` | `number` | `3` | 행 수 |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 자동 검증 |
+| `status?` | `SFieldStatus` | — | 필드 상태 ('default' | 'pass' | 'error') |
+| `focused?` | `boolean` | — | 포커스 상태 (제어/반영) |
+| `hovered?` | `boolean` | — | 호버 상태 (제어/반영) |
+| `textareaClass?` | `string` | — | 내부 textarea 요소 className |
+| `textareaStyle?` | `CSSProperties` | — | 내부 textarea 요소 style |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — | 레이블 영역 아이콘 |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — | 레이블 툴팁 텍스트 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
+| `addonLabel?` | `string` | — | 우측 어드온 레이블 |
+| `addonAlign?` | `SFieldAddonAlign` | — | 어드온 정렬 |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `number \| string` | — |  |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: string) => void` | 값 변경 (sdUpdate) |
+| `onChange` | `TextareaHTMLAttributes<HTMLTextAreaElement>['onChange']` | 네이티브 onChange (form-agnostic) |
+
+## Dependencies
+
+### Used by
+
+ - [SKeyValueTable](../SKeyValueTable)
+
+### Depends on
+
+- [SField](../SField)
+
+### Graph
+
+---
+
+# STimePicker
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STimePicker
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string \| null` | — | 선택 시간 (HH:mm) |
+| `type?` | `STimePickerType` | `'default'` | 표시 타입: default(24시간) / midday(오전·오후) |
+| `size?` | `STimePickerSize` | `'sm'` |  |
+| `placeholder?` | `string` | `'00:00'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `clearable?` | `boolean` | `false` |  |
+| `useMeridiem?` | `boolean` | — | 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. |
+| `minuteStep?` | `number` | `1` |  |
+| `width?` | `number \| string` | — |  |
+| `name?` | `string` | — |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(time: string \| null) => void` | 선택 변경 (sdUpdate) |
+| `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
+
+## Dependencies
+
+### Used by
+
+ - [STimeRangePicker](../STimeRangePicker)
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# STimeRangePicker
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STimeRangePicker
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `STimeRangeValue` | — | 선택 시간 범위 [시작, 종료] (HH:mm) |
+| `type?` | `STimeRangePickerType` | `'default'` | 표시 타입: default(24시간) / midday(오전·오후) |
+| `size?` | `STimeRangePickerSize` | `'sm'` |  |
+| `placeholder?` | `string` | `'00:00 ~ 23:59'` |  |
+| `disabled?` | `boolean` | `false` |  |
+| `clearable?` | `boolean` | `false` |  |
+| `useMeridiem?` | `boolean` | — | 오전/오후 선택 표시 여부. 지정하지 않으면 type="midday"일 때만 켜집니다. |
+| `minuteStep?` | `number` | `1` |  |
+| `rangeOrder?` | `STimeRangePickerRangeOrder` | `'strict'` | 범위 순서 정책. strict는 시작 시간이 종료 시간보다 늦어지지 않도록 보정합니다. |
+| `width?` | `number \| string` | — |  |
+| `name?` | `string` | — |  |
+| `rules?` | `Rule[]` | — |  |
+| `status?` | `SFieldStatus` | — |  |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — |  |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — |  |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — |  |
+| `addonLabel?` | `string` | — |  |
+| `addonAlign?` | `SFieldAddonAlign` | — |  |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(range: STimeRangeValue) => void` | 선택 변경 (sdUpdate) |
+| `onOpenChange` | `(open: boolean) => void` | 열림/닫힘 변경 (sdDropDownShow) |
+
+## Dependencies
+
+### Depends on
+
+- [SField](../SField)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+- [STimePicker](../STimePicker)
+
+### Graph
+
+---
+
+# SToast
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SToastContainer
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position?` | `SToastPosition` | `'bottom-center'` |  |
+| `maxVisible?` | `number` | `3` |  |
+| `defaultDuration?` | `number` | `4000` | 자동 닫힘 기본 지연(ms) |
+| `zIndex?` | `number` | `1100` | 스택 z-index. 기본값(1100)은 모달(1000/1001) 위 — 토스트는 전역 알림이라 항상 최상단 |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onShow` | `(payload: { id: string }) => void` | 토스트가 표시될 때 (sdToastShow) |
+| `onDismiss` | `(payload: { id: string }) => void` | 토스트가 제거될 때 (sdToastDismiss) |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `create` | `(options: SToastNotifyOptions) => string` |  |
+| `dismiss` | `(id: string) => void` |  |
+| `dismissAll` | `() => void` |  |
+
+### SToast
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon?` | `SIconName` | — | 좌측 아이콘 |
+| `message` | `string` | — | 메시지 |
+| `link?` | `string` | — | 우측 링크 URL |
+| `linkLabel?` | `string` | — | 링크 레이블 (없으면 URL) |
+| `buttonLabel?` | `string` | — | 우측 버튼 레이블 |
+| `useClose?` | `boolean` | `false` | 닫기 버튼 표시 |
+| `type?` | `SToastType` | `'default'` | 타입(색상/프리셋) |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onClose` | `() => void` | 닫기 (sdClose) |
+| `onButtonClick` | `(e: MouseEvent) => void` | 버튼 클릭 (sdButtonClick) |
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+
+### Graph
+
+---
+
+# SToggle
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### SToggle
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `boolean` | `false` | 선택(on/off) 상태 |
+| `label?` | `string` | `''` | 라벨 |
+| `disabled?` | `boolean` | `false` | 비활성 |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(value: boolean) => void` | 변경 (sdUpdate) |
+
+---
+
+# STooltip
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### STooltip
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `content?` | `ReactNode` | — | 툴팁 본문 (ReactNode). message 보다 우선 |
+| `message?` | `string[]` | `[]` | 툴팁 본문 줄 목록 (각 항목이 한 줄, HTML 문자열 허용 — innerHTML 렌더링) |
+| `trigger?` | `STooltipTrigger` | `'hover'` | 트리거 방식 |
+| `placement?` | `STooltipPlacement` | `'top'` | 표시 방향 |
+| `tooltipType?` | `STooltipType` | `'default'` | 배경/텍스트 색상 타입 |
+| `useClose?` | `boolean` | `false` | 우측 상단 닫기 버튼. 켜면 자동 닫힘이 비활성화되고 X(또는 hide())로만 닫힘 (hover·click 공통) |
+| `disabled?` | `boolean` | `false` | 비활성 — 트리거만 렌더하고 툴팁을 열지 않음 |
+| `children?` | `ReactNode` | — | 커스텀 트리거. 없으면 아이콘 트리거를 렌더 |
+| `icon?` | `SIconName` | `'helpOutline'` | 기본(아이콘) 트리거 설정 |
+| `iconSize?` | `number` | `12` |  |
+| `color?` | `SColor` | `'#01BB4B'` | 트리거 아이콘 색상. 팔레트 키(`grey_65`, `red_95` …) 또는 임의 CSS 색상 |
+| `ariaLabel?` | `string` | — | 접근성 레이블 |
+| `className?` | `string` | — |  |
+| `triggerClassName?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `show` | `() => void` | 툴팁을 표시합니다. |
+| `hide` | `() => void` | 툴팁을 숨깁니다. |
+
+## Dependencies
+
+### Used by
+
+ - [SField](../SField)
+ - [SKeyValueTable](../SKeyValueTable)
+ - [SList](../SList)
+
+### Depends on
+
+- [SGhostButton](../SGhostButton)
+- [SIcon](../SIcon)
+
+### Graph