sellmate-design-system-react 9.0.0-beta.79 → 9.0.0-beta.80

package/AGENTS.md

@@ -47,7 +47,7 @@
 | **내비게이션** | `STabs` `SPagination` `SStepper` |
 | **차트** | `SBarChart`(막대 그래프 — 항목끼리 크기를 견준다. `stacked` 로 항목 안의 구성까지) `SLineChart`(꺾은선 그래프 — 순서가 있는 항목의 추이를 본다. `area` 로 크기까지, `stacked` 로 구성까지) `SPieChart`(원그래프 — 한 시점의 전체를 몇 개의 몫으로 나눈다) `SDonutChart`(도넛 그래프 — 가운데가 빈 원그래프. 구멍에 글자를 두지 않는다) |
 | **표시·상태** | `STag` `SBadge` `SIcon` `SLogo`(셀메이트·서비스 로고를 아이콘처럼 — name 으로 서비스, mode 로 배경, direction 으로 가로·세로, size 는 높이다 — `"auto"` 면 부모 폭을 채운다) `SImage` `SCallout` `SContextAlert`(한 줄짜리 맥락 알림 — 오른쪽에 후속 동작 버튼) `SGuide` |
-| **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
+| **진행·로딩** | `SLinearProgress` `SCircleProgress` `SSkeleton`(처음 불러오는 동안 콘텐츠 자리를 같은 모양으로 채운다) `SLoadingContainer` `SLoadingModal` |
 | **오버레이** | `STooltip` `SPopover` `SPopup` `SDrawer` `SPortal` |
 | **모달** | `SModal.confirm()` `SModal.create()` + `SActionModal` `SConfirmModal` `SModalOutlet`(앱 루트 1회) |
 | **알림** | `SToast` `SToastContainer` |
@@ -152,7 +152,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 **`toLocaleDateString()` 은 쓰지 않는다** — 로케일에 따라 결과가 바뀌어 표기를 지킬 수 없다.
 
-**대화 화면의 시각은 예외다.** `SChatMessage` 의 `time` 처럼 말풍선에 붙는 시각은 `오후 5:52` 로 쓴다. 여기서 시각은 정렬하거나 크기를 비교하는 값이 아니라 대화의 흐름을 짚는 표시라, 자릿수를 맞춘 `17:52` 보다 말하듯 읽히는 표기가 맞다. **이 예외는 대화 말풍선에만 열린다** — 같은 화면이라도 표·상세·목록에 들어가는 일시는 그대로 `YYYY-MM-DD HH:mm` 이다.
+**대화 화면의 시각과 날짜는 예외다.** `SChatMessage` 의 `time` 처럼 말풍선에 붙는 시각은 `오후 5:52` 로, 대화 중간의 날짜 구분선은 `2026년 10월 6일 화요일` 로 쓴다. 여기서 시각·날짜는 정렬하거나 크기를 비교하는 값이 아니라 대화의 흐름을 짚는 표시라, 자릿수를 맞춘 `17:52`·`2026-10-06` 보다 말하듯 읽히는 표기가 맞다. 이 표기도 `toLocaleDateString()` 으로 만들지 않는다 — 연·월·일과 요일을 직접 이어 붙인다(§4-12). **이 예외는 대화 말풍선과 대화의 날짜 구분선에만 열린다** — 같은 화면이라도 표·상세·목록에 들어가는 일시는 그대로 `YYYY-MM-DD HH:mm` 이다.
 
 ---
 
@@ -168,7 +168,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | --- | --- | --- |
 | **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SGnbSystem`(GNB 맨 아래 판 · 전폭 상단바 오른쪽 끝) `SPage` `SPageHeader`(`SLayout` 안에서 `SPage` 앞에 둔다) |
 | **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SChatMessage` `SChatSystemMessage` `SChatInput` `SLoginCard`(유일하게 `SPage` 밖에 선다 — 로그인 화면 자체가 자기 자리다, §4-6) `SForm` `SSplitter` `SScrollArea` `SCalendarBoard` `STable` `STableBar` `SChipFilter` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `SContextAlert` `SBarChart` `SLineChart` `SPieChart` `SDonutChart` `STabs` `SStepper` `SPagination` `SDivider` |
-| **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SMeatballButton` `SDropdownButton` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SChatAttachedFile` `SChatFile` `SImage` `SLinearProgress` `SCircleProgress` |
+| **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SMeatballButton` `SDropdownButton` `SSystemActionButton` `SField` `SInput` `SSearchInput` `SNumberInput` `STextarea` `SEditor` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SRadioCard` `SRadioCardGroup` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDatePickerYearListbox` `SDatePickerMonthListbox` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SChatAttachedFile` `SChatFile` `SImage` `SLinearProgress` `SCircleProgress` `SSkeleton` |
 | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `SLogo` `STextLink` `SChip` |
 | **레이어** | 문서 흐름 **밖**에 떠서 그려진다. 어느 층에서 띄우든 레이아웃에 영향이 없다 | `SModal` `SActionModal` `SConfirmModal` `SPopup` `SDrawer` `SPopover` `STooltip` `SPortal` `SAccountListBox`(계정 행에 붙어 뜬다 — 직접 띄우지 않는다) `SLauncherListBox`(런처 버튼에 붙어 뜬다 — 직접 띄우지 않는다) `SToast` `SLoadingModal` `SLoadingContainer` `SGuide` |
 
@@ -225,6 +225,8 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 7. 하단 액션          되돌리기 왼쪽 · 실행 오른쪽 (§4-3)
 ```
 
+**`STabs`·`SStepper` 는 아래 블록 전체가 어느 관점·단계인지 말하므로 순서 목록 맨 위(페이지 제목 바로 아래, 상시 안내보다 앞)에 선다** (§4-10·§4-11).
+
 간격은 층마다 다르다 — 블록 ↔ 블록은 `gap-sd-12`, 요소 ↔ 요소는 `gap-sd-8` 이 기본이고, 같은 컴포넌트를 나열할 때는 컴포넌트별 그룹 간격이 따로 있다. 전부 §2-2 에 있다.
 
 #### 툴바(4)와 본문 표(5)는 한 블록이다 — 붙인다
@@ -376,7 +378,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 적용은 **화면 단위가 아니라 영역 단위**다. 한 화면 안에서도 칸마다 다르다.
 
-| 영역 (상담 콘솔 예) | 안쪽 여백 | 이유 |
+| 영역 (상담 콘솔 예 — 코드는 §4-12) | 안쪽 여백 | 이유 |
 | --- | --- | --- |
 | 좌측 상담 목록 | `p-sd-16` | 같은 항목 반복 |
 | 중앙 대화 | `p-sd-24` | 말풍선·버튼 묶음·시스템 메시지 혼재 |
@@ -653,6 +655,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | --- | --- | --- |
 | 화면 전체를 잠그고 기다리게 한다 | `loading.show()` — 진행률·실패 후 재시도 버튼이 필요하면 `SLoadingModal` (`SModal.loading()`) | §3-3-6 |
 | 특정 영역만 덮고 기다리게 한다 | `SLoadingContainer` | §3-3-6 |
+| 처음 불러오는 동안 올 콘텐츠의 자리를 같은 모양으로 채운다 | `SSkeleton` | §3-7-15 |
 | 진행률을 가로 막대로 보여준다 | `SLinearProgress` | §3-7-9 |
 | 진행률·대기를 원형으로 보여준다 | `SCircleProgress` | §3-7-9 |
 
@@ -739,12 +742,16 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 ```tsx
 <SActionModal modalTitle="발주 검토" button={{ label: '확정', onClick: submit }}>
-  {/* 표가 남은 높이를 먹고 자기 안에서 스크롤한다 — 헤더·합계·푸터는 늘 보인다 */}
-  <STable className="min-h-0 flex-1" columns={columns} rows={rows} />
+  {/* 본문은 flex 컨테이너가 아니다 — 세로 축을 잇는 상자를 한 겹 둔다 */}
+  <div className="flex h-full min-h-0 flex-col gap-sd-12">
+    <SContextAlert intent="warning" messages={['품절 상품 2건은 제외됩니다.']} />
+    {/* 표가 남은 높이를 먹고 자기 안에서 스크롤한다 — 위 안내·헤더·푸터는 늘 보인다 */}
+    <STable className="min-h-0 flex-1" columns={columns} rows={rows} />
+  </div>
 </SActionModal>
 ```
 
-본문(`overflow-auto` 영역)이 통째로 스크롤되면 표 헤더와 합계 줄이 위로 밀려 사라진다. `SActionModal` 의 본문은 이미 `min-h-0 flex-1` 이므로, 표에 `min-h-0 flex-1` 을 주면 세로 축이 이어져 표만 스크롤한다 (§4-2 목록 페이지와 같은 사슬이다).
+본문(`overflow-auto` 영역)이 통째로 스크롤되면 표 헤더와 합계 줄, 위의 안내까지 밀려 사라진다. **`SActionModal` 의 본문 상자는 높이는 갖지만 flex 컨테이너가 아니다** — 그래서 표에 `min-h-0 flex-1` 만 주면 아무 일도 일어나지 않고 본문이 통째로 스크롤된다. 본문 바로 아래에 `flex h-full min-h-0 flex-col` 상자를 두고 그 안에서 표에 `min-h-0 flex-1` 을 준다 (§4-2 목록 페이지와 같은 사슬이다). 표 하나뿐이어도 이 상자는 필요하다.
 
 **성격이 먼저 둘로 갈린다.**
 
@@ -1958,12 +1965,21 @@ const [selectedId, setSelectedId] = useState<string>();
   {/* 하위가 없는 항목(전체·미분류)은 SExpansionItem 이 아니라 SListItem 이다 */}
   <SListItem title="전체" selected={selectedId === 'all'} onClick={() => setSelectedId('all')} />
   <SExpansionItem title="조직">
+    {/* 펼친 항목 안에는 다음 단계 항목을 바로 넣는다 — depth 는 주지 않는다 */}
     <SListItem title="영업팀" selected={selectedId === 'sales'} onClick={() => setSelectedId('sales')} />
   </SExpansionItem>
 </SExpansionList>
 ```
 
-- `clickable` 은 리스트가 자식 `SListItem` 에 기본으로 켜 준다 — `clickable` 없이 `selected` 만 주면 표시가 안 나오는 함정(§3-7-6)을 막는 값이다.
+- **`SExpansionList` 는 루트에 하나만 둔다.** 펼친 항목의 본문이 목록(`SListItem`·`SExpansionItem` 만)이면 리스트가 그 본문을 다음 단계로 다룬다. 그래서 하위 항목에도 아래가 따라온다 — 직접 주지 않는다.
+  - `clickable` — 리스트 안의 `SListItem` 은 기본으로 켜진다. `clickable` 없이 `selected` 만 주면 표시가 안 나오는 함정(§3-7-6)을 막는 값이다. 표시 전용 항목이면 `clickable={false}` 를 준다.
+  - `depth` — 중첩에서 정해진다. 들여쓰기를 위해 `depth={2}` 를 손으로 적지 않는다.
+  - 구분선·아코디언 — 단계마다 리스트가 그리고, 같은 단계에서 하나만 열린다.
+  - 본문 여백 — 목록 본문이면 `bodyPadding` 이 꺼져 항목이 가장자리까지 찬다.
+- 직접 준 `depth`·`clickable`·`bodyPadding` 은 언제나 이 기본값보다 우선한다. 안쪽에 `SExpansionList` 를 직접 둔 코드도 그대로 동작한다 (다시 감싸지 않는다).
+- **본문에 목록이 아닌 내용이 섞이면 다음 단계로 보지 않는다.** 설명 문단·폼이 든 본문은 손대지 않으므로, 그 안의 `SListItem` 에는 위 기본값이 따라오지 않는다.
+- **리스트 밖 단독 `SExpansionItem` 은 본문을 다루지 않는다.** 선택하는 목록을 담으려면 `SExpansionList` 로 감싼다.
+
 - **하위를 가지지 않는 항목은 `SExpansionItem` 이 아니라 `SListItem`** 으로 둔다. 펼칠 것이 없는데 펼침 항목으로 만들면 화살표만 남는다.
 
 #### 3-7-8. SCard vs SSectionHeaderCard
@@ -2140,13 +2156,40 @@ const [selectedId, setSelectedId] = useState<string>();
    {/* 0 이 1 로 바뀐 뒤 도착하므로 저장 직전의 v < 1 가드는 영원히 걸리지 않는다 */}
 ```
 
+#### 3-7-15. 로딩 중 자리 — SSkeleton vs SLoadingContainer vs SCircleProgress
+
+| 판별 | 사용 |
+| --- | --- |
+| **처음 불러오는 중**이고, 올 콘텐츠의 모양(목록 행·카드·폼)을 안다 | `SSkeleton` |
+| 이미 보이는 콘텐츠를 **다시 불러오거나 저장하는 중**이라 그 영역의 입력을 막아야 한다 | `SLoadingContainer` |
+| 모양을 알 수 없는 작은 자리에서 끝나는 시점을 모른 채 기다린다 | `SCircleProgress` `indeterminate` |
+
+`SSkeleton` 은 입력을 막지 않는다 — 자리만 잡는다. 데이터가 오면 같은 자리에 실제 컴포넌트로 **바꿔 그린다**(겹쳐 두지 않는다).
+
+- **실제 레이아웃을 그대로 따라 그린다.** 폼 컨트롤 자리는 `type="input"`·`"button"`·`"checkbox"` 처럼 DS 모양을 쓴다. 해당 컴포넌트 기본 size 의 크기·모서리를 토큰으로 넣으므로 **높이·radius 를 직접 주지 않는다** — 직접 주면 데이터가 왔을 때 레이아웃이 튄다. checkbox·radio·switch 는 크기를 바꾸지 않는다.
+- **텍스트 줄은 `type="text"` 를 실제 텍스트와 같은 typo 클래스 안에 둔다.** 줄 높이를 부모 line-height 에서 받으므로 typo 밖에 두면 높이가 어긋난다. `text` 에 `height` 를 주지 않는다 — 높이가 필요하면 `rect` 다.
+- **원은 `size` 하나로 준다.** `width`·`height` 를 따로 주면 타원이 된다.
+- **넓은 영역에는 `pulse` 를 쓰지 않는다.** 블록 전체가 줄었다 커져 레이아웃이 흔들려 보인다. 기본 `wave` 를 쓰고, 한 화면에 아주 많으면 `none`.
+- **로딩 중이라는 사실은 감싸는 영역에 `aria-busy` 로 알린다.** `SSkeleton` 자체는 장식이라 보조기기에 숨겨져 있다.
+
+```tsx
+✅ <div aria-busy={loading}>
+     {loading
+       ? <div className="typo-body-md-default"><SSkeleton type="text" width="40%" /><SSkeleton type="text" /></div>
+       : <p className="typo-body-md-default">{data.summary}</p>}
+   </div>
+
+❌ <SSkeleton type="input" height={40} />   {/* 실제 SInput 과 높이가 달라 데이터가 오면 튄다 */}
+❌ <SSkeleton type="text" height={24} />    {/* text 는 세로 절반만 칠한다 — rect 를 쓴다 */}
+```
+
 ---
 
 ## 4. 페이지 레시피 — 표준 골격
 
 > 새 페이지는 반드시 아래 골격에서 시작한다. 임의 골격을 발명하지 않는다.
 >
-> **아래 레시피는 §2-0 조합 문법으로 유도된 결과다.** 여기 없는 화면(대시보드·설정·마법사 등)을 만들 때는 임의로 짜지 말고 §2-0 의 층 구조·포함 규칙·블록 순서로 직접 유도한다.
+> **아래 레시피는 §2-0 조합 문법으로 유도된 결과다.** 여기 없는 화면(일정 캘린더·권한 설정 등)을 만들 때는 임의로 짜지 말고 §2-0 의 층 구조·포함 규칙·블록 순서로 직접 유도한다.
 >
 > **레시피 코드의 `./AppShell` 은 §4-1 의 셸, `./api`·`./router` 는 앱의 데이터 계층·라우터 자리다.** 각 레시피는 Storybook `Recipes/…` 에서 실제로 띄워 볼 수 있고, 아래에 적힌 분기(칩 필터·섹션 나눔 등)의 변형 코드도 거기 있다.
 >
@@ -3232,6 +3275,1980 @@ export default function ExcelFilePopupPage() {
 
 조회만 하고 표가 없는 팝업은 이 사슬이 필요 없다 — 본문이 통째로 스크롤되어도 헤더는 고정이고 밀려날 푸터가 없다.
 
+### 4-8. 대시보드 — 요약 타일 + 차트
+
+구조: **페이지 헤더 → 조회 조건(`SKeyValueTable`) → 요약 타일 줄(`SCard`) → 차트 섹션(`SSectionHeaderCard` + 차트)**
+
+- **조회 조건도 필터다 — `SKeyValueTable` 로 만든다** (§4 핵심 원칙). 기간은 지표의 전제라 비울 수 없으므로 기간 피커에는 `clearable` 을 켜지 않는다. 나머지 조건(판매처 등)은 목록 필터와 같이 `clearable` 이다 (§3-7-4).
+- **요약 타일은 `SCard` 다.** 제목이 붙는 섹션이 아니라 흰 면 하나라서다 (§3-7-8). 이 레시피의 페이지 바탕은 흰 면이라 `bordered` 로 경계를 긋는다. 안쪽 여백은 직접 만든 컨테이너 규칙(§2-2)을 따른다.
+  - 라벨 → 메인 수치(`typo-heading-xl`) → 증감 순으로 쌓는다. 메인 수치 프리셋은 제목에 쓰지 않는다 (§2-1).
+  - 증감은 **부호와 색을 함께** 준다 — 색만으로 늘었는지 줄었는지 말하지 않는다. 색은 `text-fg-success` / `text-fg-danger` 다.
+- **타일·차트를 가로로 늘어놓는 줄은 `grid` 로 만들고, 그 `gap` 을 블록 간격(`gap-sd-12`)과 같게 둔다.** 줄 자체가 블록 스택의 한 칸이고, 줄 안의 간격이 세로 블록 간격과 같아야 격자가 한 리듬으로 읽힌다.
+- **차트는 `SSectionHeaderCard` 에 담고, 차트 이름은 카드의 `title` 이 맡는다.** 차트의 `title` 을 함께 주면 제목이 두 줄이 된다. 단위(`unit`)는 차트가 오른쪽 위에 적는다. 섹션 카드가 여럿이라 `marker` 를 켠다 (§4-5).
+- 차트 종류는 §3-0 B 로 고른다 — 날짜순 흐름은 `SLineChart`, 항목끼리 견주기는 `SBarChart`, 전체의 몫은 `SPieChart`/`SDonutChart`. **도넛의 합계는 구멍이 아니라 카드 `subtitle` 에 적는다.**
+- **차트는 "어느 쪽이 큰가" 까지만 답한다.** 정확한 값이 필요한 사용자를 위해 점·막대 클릭(`onPointClick`·`onBarClick`)을 해당 목록 화면으로 잇는다 — 대시보드 안에 같은 값의 표를 또 두지 않는다.
+- **높이 모드는 `auto` 다.** 차트 블록은 높이(`height`)가 정해져 있고 그 합이 창보다 길어질 수 있어 페이지가 스크롤하는 예외에 해당한다 — `contentHeight="auto"` 와 `scrollEndSpacing` 을 함께 켠다 (§2-2 "페이지 높이").
+
+<!-- recipe:src/recipes/SalesDashboardPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useState } from 'react';
+import {
+  SBarChart,
+  SCard,
+  SDonutChart,
+  SKeyValueTable,
+  SLineChart,
+  SSectionHeaderCard,
+  type SDateRangeValue,
+  type SKeyValueField,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { CHANNEL_OPTIONS, useSalesDashboard } from './api';
+import { useNavigate } from './router';
+
+/** 대시보드의 조회 조건도 표다 — 목록 페이지의 필터와 같은 SKeyValueTable (§4-2) */
+const filterFields: SKeyValueField[][] = [
+  [
+    // 기간은 지표의 전제라 비울 수 없다 — clearable 을 켜지 않는다 (§3-7-4)
+    { name: 'period', label: '기간', type: 'date-range-picker' },
+    {
+      name: 'channel',
+      label: '판매처',
+      type: 'select',
+      options: { options: CHANNEL_OPTIONS, valueAsPrimitive: true, clearable: true },
+    },
+  ],
+];
+
+const won = (v: number) => `${v.toLocaleString()}원`;
+
+export default function SalesDashboardPage() {
+  const navigate = useNavigate();
+  const [filter, setFilter] = useState<{ period: SDateRangeValue; channel?: string }>({
+    period: ['2026-09-01', '2026-09-14'],
+  });
+  const { summary, daily, channelShare, topProducts } = useSalesDashboard(filter);
+  const channelTotal = channelShare.reduce((sum, s) => sum + s.value, 0);
+
+  return (
+    // 블록 높이를 차트가 정하고 그 합이 창보다 길어질 수 있다 — 페이지가 스크롤하는 예외라
+    // contentHeight="auto" + scrollEndSpacing 이다 (§2-2 "페이지 높이")
+    <AppShell header={{ variant: 'bar', title: '매출 현황' }} contentHeight="auto" scrollEndSpacing>
+      <div className="flex flex-col gap-sd-12">
+        <SKeyValueTable
+          fields={filterFields}
+          values={filter}
+          onChange={({ values }) => setFilter(values as typeof filter)}
+          fieldWidth="fill"
+        />
+
+        {/* 요약 타일 — 제목이 붙는 섹션이 아니라 흰 면 하나라 SCard 다 (§3-7-8).
+            타일들은 한 줄의 블록이다 — 그리드의 gap 을 블록 간격(gap-sd-12)과 같게 두어 리듬을 잇는다.
+            페이지 바탕이 흰 면(frame)이라 카드는 bordered 로 경계를 긋는다 */}
+        <div className="grid grid-cols-4 gap-sd-12">
+          {summary.map(s => (
+            <SCard key={s.label} bordered className="flex flex-col gap-sd-4 p-sd-16">
+              <span className="typo-body-sm-default text-fg-secondary">{s.label}</span>
+              {/* 카드 안의 메인 수치는 typo-heading-xl — 제목에는 쓰지 않는다 (§2-1) */}
+              <span className="typo-heading-xl">
+                {s.value.toLocaleString()}
+                {s.unit}
+              </span>
+              {/* 증감은 숫자 앞 부호와 색으로 함께 말한다 — 색만으로 뜻을 싣지 않는다 */}
+              <span className="typo-body-sm-default text-fg-tertiary">
+                전기간 대비{' '}
+                <span className={s.change >= 0 ? 'text-fg-success' : 'text-fg-danger'}>
+                  {s.change >= 0 ? '+' : ''}
+                  {s.change.toLocaleString()}%
+                </span>
+              </span>
+            </SCard>
+          ))}
+        </div>
+
+        {/* 차트는 섹션 카드에 담는다. 차트 이름은 카드의 title 이 맡으므로 차트의 title 은 주지 않는다 —
+            둘 다 주면 제목이 두 줄이 된다. 단위(unit)는 차트가 오른쪽 위에 적는다.
+            한 페이지에 섹션 카드가 여럿이라 marker 를 켠다 (§4-5) */}
+        {/* 날짜순 흐름이라 선 — 순서가 있는 항목의 추이 (§3-0 B). 항목(날짜)이 많아 한 줄을 다 쓴다 */}
+        <SSectionHeaderCard title="일별 매출" marker>
+          <SLineChart
+            categories={daily.categories}
+            series={[{ name: '매출', data: daily.data }]}
+            unit="원"
+            area
+            showLegend={false}
+            height={280}
+            formatValue={won}
+            // 차트는 "어느 쪽이 큰가" 까지만 답한다 — 정확한 값은 그날의 주문 목록에서 본다
+            onPointClick={p => navigate(`/orders?date=${daily.dates[p.categoryIndex]}`)}
+          />
+        </SSectionHeaderCard>
+
+        <div className="grid grid-cols-2 gap-sd-12">
+          {/* 합계는 도넛 구멍이 아니라 카드 subtitle 에 적는다 (§3-0 B) */}
+          <SSectionHeaderCard title="판매처별 비중" marker subtitle={`합계 ${won(channelTotal)}`}>
+            <SDonutChart
+              data={channelShare}
+              legendPosition="bottom"
+              formatValue={won}
+              // 그림은 폭만큼의 정사각형이다 — 칸을 다 채우면 옆 카드보다 훨씬 길어지므로
+              // 화면 고유 치수로 폭을 묶는다 (§1-2)
+              className="mx-auto max-w-[280px]"
+            />
+          </SSectionHeaderCard>
+
+          {/* 항목끼리 크기를 견주므로 막대. 상품명이 길어 가로 막대로 눕힌다 */}
+          <SSectionHeaderCard title="상품별 판매량 TOP 5" marker>
+            <SBarChart
+              categories={topProducts.categories}
+              series={[{ name: '판매량', data: topProducts.data }]}
+              unit="개"
+              direction="horizontal"
+              showLegend={false}
+              height={320}
+              formatValue={v => `${v.toLocaleString()}개`}
+            />
+          </SSectionHeaderCard>
+        </div>
+      </div>
+    </AppShell>
+  );
+}
+```
+<!-- /recipe -->
+
+### 4-9. 분할 화면 — 왼쪽 목록 + 오른쪽 상세
+
+왼쪽에서 하나를 고르면 오른쪽에 그 상세가 열리는 화면이다 (카테고리·창고·코드 관리 등). 상세로 **페이지를 이동하지 않고** 목록을 보면서 연달아 고쳐야 할 때 쓴다. 목록을 훑는 것이 주목적이고 상세는 가끔 여는 화면이면 §4-2 목록 → §4-4 상세 페이지 이동이 맞다.
+
+구조: **페이지 헤더 → `SSplitter`( `Before` = 목록 카드 · `After` = 상세 카드 )**
+
+- **사이드(목록)를 `Before` 에 두고 `unit="px"` 로 폭을 고정한다.** 모델은 항상 첫 패널 크기이고, 사이드바처럼 폭이 유지돼야 하는 자리는 `px` 다. `limits` 로 목록이 읽을 수 없을 만큼 좁아지지 않게 한다 (§3-6).
+- **높이는 `contentHeight="fill"` 사슬로 넘긴다.** `SSplitter` 는 부모를 채우기만 하므로 블록 스택(`h-full min-h-0`) → `SSplitter`(`min-h-0 flex-1`) 로 남은 높이를 이어 준다 (§2-2·§3-6).
+- **두 패널은 각자 안에서 스크롤한다.** 목록 카드는 `h-full` 로 패널을 채우고 본문(마지막 자식)만 스크롤하게 한다 (§4-5 "섹션 본문이 자기 안에서 스크롤"). 끝에는 패널 자체 스크롤의 하단 여백 토큰을 둔다 (§2-2 "스크롤 영역의 하단 여백"). 상세 패널은 넘치면 패널이 스스로 스크롤한다 — `SScrollArea` 를 겹치지 않는다.
+- **패널 사이 간격** — 구분선 자리는 평소 칠해지지 않아 카드끼리 거의 붙는다. 양쪽 패널에 같은 안쪽 여백(`pr-sd-4` / `pl-sd-4`)을 주어 구분선 자리와 합친 폭이 블록 간격과 맞게 한다.
+- **목록은 §3-7-7 대로 고른다.** 계층이 있으면 `SExpansionList` + `SExpansionItem`(하위가 있는 항목) + `SListItem`(하위가 없는 항목) — 리스트는 루트에 하나다, 평평하면 `SList` + `SListItem clickable`. `STree` 는 체크박스로 여러 개를 고르는 다중 선택용이라 "하나를 골라 연다" 에 쓰지 않는다.
+- **선택은 페이지가 든다** — `selectedId` 스칼라 하나. URL 로 복원할 수 있어야 하는 값이다 (§3-7-7 "펼침 ≠ 선택").
+- **상세 폼은 고른 항목마다 새로 세운다** — 상세 컴포넌트에 `key={selectedId}` 를 준다. 그렇지 않으면 편집하던 값이 다음에 고른 항목으로 넘어간다.
+- **상세 카드의 저장·삭제는 카드 푸터다.** 화면의 일부만 확정하는 카드라 `footerSize="sm"` 이고, `footerLeft` 의 버튼도 `size="sm"` 이다 (§3-7-8). 목록 카드의 "추가" 같은 부가 액션은 헤더 `slot` 에 `size="sm"` 으로 둔다.
+
+<!-- recipe:src/recipes/CategoryManagePage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useState } from 'react';
+import {
+  SButton,
+  SExpansionItem,
+  SExpansionList,
+  SKeyValueTable,
+  SListItem,
+  SModal,
+  SSectionHeaderCard,
+  SSplitter,
+  type SKeyValueField,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { removeCategory, saveCategory, useCategory, useCategoryTree } from './api';
+import { useNavigate } from './router';
+
+const USE_OPTIONS = [
+  { label: '사용', value: 'Y' },
+  { label: '미사용', value: 'N' },
+];
+
+const detailFields: SKeyValueField[][] = [
+  [
+    { name: 'path', label: '경로', type: 'text' },
+    { name: 'code', label: '코드', type: 'text' },
+  ],
+  [
+    { name: 'name', label: '이름', type: 'input', required: true },
+    { name: 'useYn', label: '사용 여부', type: 'radio', options: { options: USE_OPTIONS } },
+  ],
+  [{ name: 'memo', label: '메모', type: 'textarea', tdColSpan: 3 }],
+];
+
+type Values = Record<string, unknown>;
+
+export default function CategoryManagePage() {
+  const navigate = useNavigate();
+  const tree = useCategoryTree();
+
+  // 선택은 앱이 든다 — 스칼라 하나라 상호배제가 구조적으로 보장되고, URL 로 복원할 수 있다.
+  // 펼침은 SExpansionList 가 관리한다 (§3-7-7 "펼침 ≠ 선택")
+  const [selectedId, setSelectedId] = useState('apparel-0');
+
+  const item = (c: { id: string; name: string; productCount: number }) => (
+    <SListItem
+      key={c.id}
+      title={c.name}
+      // 건수는 보조 텍스트로 — 숫자는 toLocaleString (§1-4)
+      supportingText={c.productCount.toLocaleString()}
+      selected={selectedId === c.id}
+      onClick={() => setSelectedId(c.id)}
+    />
+  );
+
+  return (
+    // 두 패널이 각자 안에서 스크롤해야 하므로 fill (§2-2 "페이지 높이")
+    <AppShell header={{ variant: 'bar', title: '카테고리 관리' }} contentHeight="fill">
+      {/* SSplitter 는 부모를 채우기만 한다 — 블록 스택에서 min-h-0 flex-1 로 남은 높이를 넘겨 준다 (§3-6) */}
+      <div className="flex h-full min-h-0 flex-col gap-sd-12">
+        {/* 사이드가 기준인 화면이라 사이드를 Before 에 두고 폭을 px 로 고정한다.
+            구분선 자리가 좁아 카드끼리 붙지 않게 양쪽 패널에 같은 안쪽 여백을 준다 —
+            구분선 자리와 합쳐 블록 간격(gap-sd-12)이 되게 맞춘다 */}
+        <SSplitter unit="px" defaultValue={280} limits={[240, 480]} className="min-h-0 flex-1">
+          <SSplitter.Before className="pr-sd-4">
+            {/* 목록 카드는 패널 높이를 채우고, 본문(마지막 자식)만 자기 안에서 스크롤한다 (§4-5).
+                카드 안이 목록 하나뿐이라 padding="none" 으로 가장자리까지 채운다 */}
+            <SSectionHeaderCard
+              title="카테고리"
+              marker
+              padding="none"
+              className="h-full [&>div:last-child]:min-h-0 [&>div:last-child]:flex-1 [&>div:last-child]:overflow-y-auto"
+              // 목록에 항목을 더하는 부가 액션 — 헤더 slot 의 sm 버튼 (§4-5)
+              slot={
+                <SButton
+                  size="sm"
+                  color="neutral"
+                  outline
+                  icon="add"
+                  label="추가"
+                  onClick={() => navigate('/categories/new')}
+                />
+              }
+            >
+              {/* 하위가 있는 대분류만 SExpansionItem, 전체·미분류는 SListItem (§3-7-7).
+                  리스트는 루트에 하나 — SListItem 의 clickable 은 리스트가 켜 주므로 selected 만 넘긴다.
+                  패널 자체 스크롤이라 끝에 scrollEnd 여백을 둔다 (§2-2 "스크롤 영역의 하단 여백") */}
+              <SExpansionList className="pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+                {tree.map(top =>
+                  top.children ? (
+                    <SExpansionItem
+                      key={top.id}
+                      title={top.name}
+                      supportingText={top.productCount.toLocaleString()}
+                      defaultExpanded={top.id === 'apparel'}
+                    >
+                      {/* 펼친 항목 안에는 하위 항목을 바로 넣는다 — 리스트가 다음 단계로 다뤄
+                          clickable·depth·구분선·본문 여백이 따라온다 (§3-7-7) */}
+                      {top.children.map(item)}
+                    </SExpansionItem>
+                  ) : (
+                    item(top)
+                  ),
+                )}
+              </SExpansionList>
+            </SSectionHeaderCard>
+          </SSplitter.Before>
+
+          {/* 오른쪽 패널은 넘치면 패널이 스스로 스크롤한다 — SScrollArea 를 겹치지 않는다 (§3-6) */}
+          <SSplitter.After className="pl-sd-4">
+            {/* key 로 고른 항목마다 폼을 새로 세운다 — 바꿔 고르면 편집 중이던 값이 다음 항목으로 새지 않는다 */}
+            <CategoryDetail
+              key={selectedId}
+              id={selectedId}
+              onRemoved={() => setSelectedId('all')}
+            />
+          </SSplitter.After>
+        </SSplitter>
+      </div>
+    </AppShell>
+  );
+}
+
+/** 오른쪽 패널 — 고른 카테고리 하나의 인라인 폼 */
+function CategoryDetail({ id, onRemoved }: { id: string; onRemoved: () => void }) {
+  const category = useCategory(id);
+  const [values, setValues] = useState<Values>(category ?? {});
+  if (!category) return null;
+
+  const confirmDelete = () =>
+    SModal.confirm({
+      type: 'negative',
+      modalTitle: '카테고리를 삭제할까요?',
+      topMessage: ['소속 상품은 미분류로 옮겨집니다.'],
+      mainButtonLabel: '삭제',
+    }).onOk(async () => {
+      await removeCategory(id);
+      onRemoved();
+    });
+
+  return (
+    // 화면의 일부(분할 영역)만 확정하는 카드라 footerSize="sm", 슬롯 버튼도 sm (§3-7-8)
+    <SSectionHeaderCard
+      title={category.name}
+      marker
+      padding="none"
+      footerSize="sm"
+      footerLeft={<SButton color="danger" outline size="sm" label="삭제" onClick={confirmDelete} />}
+      button={{ label: '저장', onClick: () => saveCategory(values) }}
+    >
+      {/* 표 아래에 카드 푸터가 오므로 radius="full" (§2-2) */}
+      <SKeyValueTable
+        fields={detailFields}
+        values={values}
+        onChange={({ values }) => setValues(values)}
+        bordered={false}
+        radius="full"
+      />
+    </SSectionHeaderCard>
+  );
+}
+```
+<!-- /recipe -->
+
+### 4-10. 설정 페이지 — 탭 + 섹션 + 탭 단위 저장
+
+구조: **페이지 헤더 → `STabs` → 섹션 카드들(`SSectionHeaderCard` + `SKeyValueTable`) → 하단 액션(되돌리기 · 저장)**
+
+- **탭은 보는 관점을 바꾼다** — 고르면 아래 내용이 통째로 바뀌므로 폼 값이 아니다 (§3-7-2). 블록 스택 맨 위에 선다 (§2-0).
+- **저장은 탭 단위다.** 한 번에 보이는 것만 저장한다 — 보이지 않는 탭의 편집 값까지 함께 저장되면 무엇이 바뀌는지 확인할 수 없다.
+  - 탭 본문을 컴포넌트로 빼고 `key={tab}` 로 탭마다 새로 세운다. 편집 값이 다른 탭으로 새지 않는다.
+  - **저장하지 않은 값이 있으면 탭을 옮기기 전에 `SModal.confirm` 으로 묻는다.** 그냥 옮기면 편집 값이 말없이 사라진다.
+- **저장·되돌리기는 카드 푸터가 아니라 카드 밖 하단 줄이다.** 탭 전체를 확정하는 액션이라서다 (§3-7-8). 되돌리기(`neutral outline`)는 왼쪽 끝, 저장(`primary` 채움 하나)은 오른쪽 끝 (§3-5-1·§4-3).
+- **한 탭 안에서 즉시 반영과 저장 버튼을 섞지 않는다.** 스위치만 즉시 반영되고 나머지는 저장해야 반영되면, 어떤 값이 이미 적용됐는지 읽히지 않는다. 이 레시피의 스위치도 저장 때 함께 반영된다.
+- 섹션 하나는 카드 하나이고, 카드 안이 표 하나면 `padding="none"` + 표 `bordered={false} radius="useTop"` (§2-2). 섹션이 여럿이라 `marker` 를 켠다 (§4-5).
+- **고르면 이후 처리가 통째로 달라지는 소수 결정은 `SRadioCardGroup` 으로 자기 섹션을 갖는다** — 표의 한 행으로 줄이지 않는다 (§3-7-2). 카드 목록이라 섹션 여백은 기본값이다.
+- 단위가 붙는 숫자는 `SNumberInput` 의 `inputSuffix` 로 단다 — 라벨에 괄호로 붙이거나 `addonLabel` 로 앞에 세우지 않는다.
+- 섹션이 쌓여 창보다 길어질 수 있으므로 `contentHeight="auto"` + `scrollEndSpacing` 이다 (§2-2).
+
+<!-- recipe:src/recipes/SettingsPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useState } from 'react';
+import {
+  SButton,
+  SKeyValueTable,
+  SModal,
+  SRadioCardGroup,
+  SSectionHeaderCard,
+  STabs,
+  type SKeyValueField,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { SETTINGS_TABS, saveSettings, useSettings } from './api';
+
+type Values = Record<string, unknown>;
+
+/** 탭마다 섹션 목록 — 섹션 하나가 카드 하나, 카드 안은 SKeyValueTable 하나다 */
+const SECTIONS: Record<string, { title: string; fields: SKeyValueField[][] }[]> = {
+  basic: [
+    {
+      title: '사업자 정보',
+      fields: [
+        [
+          { name: 'storeName', label: '상호', type: 'input', required: true },
+          { name: 'bizNo', label: '사업자 번호', type: 'text' },
+        ],
+        [
+          { name: 'manager', label: '담당자', type: 'input' },
+          { name: 'phone', label: '대표 번호', type: 'input' },
+        ],
+      ],
+    },
+    {
+      title: '반품지',
+      fields: [
+        [{ name: 'returnAddress', label: '주소', type: 'input', options: { width: '100%' } }],
+      ],
+    },
+  ],
+  order: [
+    {
+      title: '주문 처리',
+      fields: [
+        [
+          { name: 'autoConfirm', label: '자동 주문 확정', type: 'switch' },
+          {
+            name: 'holdHours',
+            label: '확정 보류 시간',
+            type: 'number-input',
+            options: { min: 1, max: 72, width: 'xs', inputSuffix: '시간' },
+          },
+        ],
+        [{ name: 'splitShipping', label: '부분 출고 허용', type: 'switch', tdColSpan: 3 }],
+      ],
+    },
+  ],
+  notice: [
+    {
+      title: '알림 받을 항목',
+      fields: [
+        [
+          { name: 'newOrder', label: '신규 주문', type: 'switch' },
+          { name: 'cancelRequest', label: '취소 요청', type: 'switch' },
+        ],
+        [
+          { name: 'lowStock', label: '재고 부족', type: 'switch' },
+          {
+            name: 'stockThreshold',
+            label: '재고 부족 기준',
+            type: 'number-input',
+            options: { min: 0, width: 'xs', inputSuffix: '개 이하' },
+          },
+        ],
+        [
+          {
+            name: 'channel',
+            label: '받는 곳',
+            type: 'radio',
+            tdColSpan: 3,
+            options: {
+              options: [
+                { label: '카카오 알림톡', value: 'kakao' },
+                { label: '이메일', value: 'email' },
+              ],
+            },
+          },
+        ],
+      ],
+    },
+  ],
+};
+
+// 고르면 이후 주문 처리가 통째로 달라지는 소수 결정이라 설명 줄이 붙는 SRadioCardGroup (§3-7-2)
+const ASSIGN_OPTIONS = [
+  {
+    value: 'auto',
+    label: '자동 배정',
+    subtitle: '재고가 있는 창고 중 가장 가까운 곳으로 배정합니다.',
+  },
+  {
+    value: 'priority',
+    label: '우선순위 배정',
+    subtitle: '창고 우선순위대로 재고가 있는 첫 창고에 배정합니다.',
+  },
+  { value: 'manual', label: '수동 배정', subtitle: '담당자가 주문마다 창고를 고릅니다.' },
+];
+
+export default function SettingsPage() {
+  const [tab, setTab] = useState('basic');
+  const [dirty, setDirty] = useState(false);
+
+  // 저장하지 않은 값이 있으면 탭을 옮기기 전에 묻는다 — 탭을 옮기면 그 탭의 편집 값이 사라진다
+  const changeTab = (next: string) => {
+    if (!dirty) return setTab(next);
+    SModal.confirm({
+      modalTitle: '저장하지 않은 변경 사항이 있습니다',
+      topMessage: ['다른 탭으로 옮기면 이 탭에서 바꾼 값이 사라집니다.'],
+      mainButtonLabel: '이동',
+    }).onOk(() => {
+      setDirty(false);
+      setTab(next);
+    });
+  };
+
+  return (
+    // 섹션이 쌓여 창보다 길어질 수 있어 페이지가 스크롤한다 — auto + scrollEndSpacing (§2-2)
+    <AppShell header={{ variant: 'bar', title: '환경 설정' }} contentHeight="auto" scrollEndSpacing>
+      <div className="flex flex-col gap-sd-12">
+        {/* 탭은 아래 블록 전체를 바꾸므로 페이지 제목 바로 아래, 블록 스택의 맨 위에 선다 */}
+        <STabs value={tab} tabs={SETTINGS_TABS} onValueChange={changeTab} />
+        {/* key 로 탭마다 본문을 새로 세운다 — 편집 값이 다른 탭으로 새지 않는다 */}
+        <SettingsTab key={tab} tab={tab} onDirtyChange={setDirty} />
+      </div>
+    </AppShell>
+  );
+}
+
+/** 탭 하나의 본문 — 탭 단위로 편집하고 탭 단위로 저장한다 */
+function SettingsTab({
+  tab,
+  onDirtyChange,
+}: {
+  tab: string;
+  onDirtyChange: (dirty: boolean) => void;
+}) {
+  const saved = useSettings(tab);
+  const [values, setValues] = useState<Values>(saved);
+
+  const change = (next: Values) => {
+    setValues(next);
+    onDirtyChange(true);
+  };
+  const reset = () => {
+    setValues(saved);
+    onDirtyChange(false);
+  };
+  const save = async () => {
+    await saveSettings(tab, values);
+    onDirtyChange(false);
+  };
+
+  return (
+    <>
+      {/* 주문 배정 방식은 표의 한 행이 아니라 자기 섹션을 갖는다 — 카드 목록이라 기본 여백(16) 이다 (§2-2) */}
+      {tab === 'order' && (
+        <SSectionHeaderCard title="주문 배정 방식" marker>
+          <SRadioCardGroup
+            options={ASSIGN_OPTIONS}
+            value={values.assignMode as string}
+            onValueChange={v => change({ ...values, assignMode: v })}
+          />
+        </SSectionHeaderCard>
+      )}
+
+      {/* 섹션 카드가 여럿이면 marker 를 켠다 — 한 탭 안에서 전부 같게 간다 (§4-5) */}
+      {SECTIONS[tab].map(section => (
+        <SSectionHeaderCard key={section.title} title={section.title} marker padding="none">
+          <SKeyValueTable
+            fields={section.fields}
+            values={values}
+            onChange={({ values }) => change(values)}
+            bordered={false}
+            radius="useTop"
+          />
+        </SSectionHeaderCard>
+      ))}
+
+      {/* 저장은 탭 전체를 확정하므로 카드 푸터가 아니라 카드 밖 하단 줄이다 (§3-7-8).
+          되돌리기는 왼쪽 끝, 저장은 오른쪽 끝 (§4-3) */}
+      <div className="flex items-center justify-between">
+        <SButton color="neutral" outline label="되돌리기" onClick={reset} />
+        <SButton label="저장" onClick={save} />
+      </div>
+    </>
+  );
+}
+```
+<!-- /recipe -->
+
+### 4-11. 단계형 — 스텝퍼 + 단계 본문
+
+순서대로 거쳐야 하는 작업이다. 단계를 건너뛰거나 순서를 바꿔도 되는 입력이면 단계형이 아니라 §4-3 폼(섹션 나눔)이다.
+
+**스텝퍼 방향은 작업의 모양이 정한다.**
+
+| | 가로형 | 세로형 |
+| --- | --- | --- |
+| 작업 | 한 번에 끝까지 거치는 짧은 작업 (엑셀 일괄 등록) | 단계가 많아 그룹으로 묶이고, 여러 번에 걸쳐 채우는 설정 (초기 설정·연동) |
+| 단계 수 | 3~5개 | 그 이상, `group` 으로 묶는다 |
+| 이동 | 프레임 푸터의 이전·다음만 — 가로 스텝퍼는 기본으로 눌리지 않는다 | 스텝퍼를 눌러 끝낸 단계로 돌아간다. 앞으로는 끝낸 단계 바로 다음까지만 간다 (컴포넌트가 막는다) |
+| 저장 | 마지막 실행 단계에서 한 번 | 단계마다 — 저장한 단계가 완료로 남는다 |
+| 상태 | 지난 단계 = 완료 | 단계마다 완료·오류가 따로 남는다. 완료한 단계에도 오류가 남을 수 있다 (인증 만료 등) |
+
+#### 가로형
+
+구조: **페이지 헤더(뒤로가기 = 그만두기) → 프레임 `SCard` 하나 [스텝퍼 | `SDivider` | 단계 본문] + 카드 푸터(이전 · 다음)**
+
+세로형과 같은 문법이다 — **스텝퍼와 단계 본문을 한 프레임에 담고, 단계 이동은 그 프레임의 푸터가 맡는다.** 다른 것은 스텝퍼가 위에 눕는다는 것뿐이다.
+
+- **스텝퍼는 프레임 맨 위, 가운데다.** 카드든 모달이든 같다. 지난 단계는 `completed` 로 표시한다. 가로 스텝퍼는 기본으로 눌리지 않으므로(`clickable` 기본 꺼짐) 돌아가기는 푸터의 "이전" 이 맡는다. 스텝퍼가 현재 단계 이름을 말하므로 **단계 제목을 따로 두지 않는다.**
+- **단계 이동은 카드 푸터다** — `footerLeft`(이전) · `button`(다음)으로 넘긴다(§3-7-8). 하단 줄을 카드 안에 손으로 만들거나 카드 밖에 따로 세우지 않는다. 프레임이 화면의 주 액션을 쥐므로 `footerSize` 는 기본(`md`)이고, `footerLeft` 슬롯 버튼도 `size="md"` 를 명시한다(§3-5-2).
+  - 오른쪽 버튼은 그 단계의 최상위 실행이라 `primary` 하나다(§3-5-1). 실행하는 단계에서는 라벨을 "다음" 대신 하는 일로 쓴다(`19개 등록`). 완료 단계는 다음 화면으로 가는 버튼(`상품 목록으로`)이다.
+  - 첫 단계의 이전은 비활성, 완료 단계에는 되돌릴 것이 없어 이전을 두지 않는다. 그 자리(`footerLeft`)는 위계가 낮은 실행 액션 자리가 된다(§3-5-6) — 건너뛴 행이 있으면 "오류 행 내려받기"(`neutral outline`, `icon="download"`)를 둔다. 파일을 받는 실행이라 `STextLink`(이동)가 아니라 `SButton` 이다.
+  - **화살표 아이콘은 이동 버튼에만 붙인다** — 이전은 `icon="arrowLeft"`, 다음은 `rightIcon="arrowRight"`. 실행 버튼(`19개 등록`)과 완료 단계 버튼에는 붙이지 않는다 — 화살표가 붙으면 되돌릴 수 없는 실행이 "다음 단계 보기" 처럼 가볍게 읽힌다.
+  - 단계마다 바뀌는 `button` 을 변수로 만들 때는 `SCardProps['button']`(모달이면 `SActionModalProps['button']`)로 타입을 붙인다 — 붙이지 않으면 `rightIcon` 같은 아이콘 이름이 `string` 으로 넓어져 타입 에러가 난다.
+  - **그만두기(취소)는 푸터에 두지 않는다** — 카드 푸터는 오른쪽 버튼이 하나라 취소·이전·다음을 함께 담을 수 없다. 페이지는 헤더의 `onBack` 이, 모달은 닫기(X)가 그 길이다.
+- **다음으로 가기 전에 그 단계를 검증한다.** `SForm` 으로 카드를 감싸고 다음 버튼을 `button={{ type: 'submit', … }}` 로 두면 규칙을 통과했을 때만 넘어간다 — 카드 푸터 버튼도 `SButton` props 를 그대로 받는다.
+- **단계들은 한 프레임을 공유하므로 여백은 가장 복합적인 단계에 맞춰 통일한다** (§2-2 "위자드·탭"). `SCard` 에는 `padding` prop 이 없으므로 직접 만든 영역의 규칙을 따른다 — 이 레시피는 1단계가 안내·카드 선택·표 세 종류라 스텝퍼 줄과 본문 모두 24 다. 단계마다 따로 판정하지 않는다.
+- **푸터는 고정하고 단계 본문만 스크롤한다.** 카드를 `flex h-full flex-col` 로 두고 본문을 `SScrollArea axis="vertical" overlayScrollbar` + `min-h-0 flex-1` 로 잇는다. `SCard` 는 기본이 `h-fit` 이라 이 사슬을 빠뜨리면 2단계처럼 내용이 긴 단계에서 카드가 자라 푸터가 화면 밖으로 밀린다 — 짧은 첫 단계에서는 드러나지 않아 놓치기 쉽다.
+- 검증 결과처럼 일부가 빠지는 단계는 **무엇이 빠지는지 먼저 말한다** — 표 위 `SCallout type="danger"` 에 건수와 처리 방법을 적는다.
+- **완료 단계는 결과 안내다** — 성공 아이콘(`SIcon`, `--sys-color-fg-success`) · 제목(`typo-heading-sm`) · 건수 설명(`typo-body-sm-default` + `text-fg-secondary`)을 본문 가운데에 세로로 쌓는다. 건너뛴 것이 있으면 그 건수도 다시 적는다. 프레임이 이미 카드라 **결과를 카드로 한 번 더 두르지 않는다**(§2-0). 세로 가운데에 놓으려면 본문 쌓기 상자에 `min-h-full`, 결과 블록에 `flex-1 justify-center` 를 준다 — `h-full` 은 기댈 높이가 없어 듣지 않는다.
+- **모달 안에서도 같은 구성이다.** `SActionModal` 본문 맨 위에 스텝퍼를 두고, 이전은 `footerLeft`, 다음은 `button` 으로 넘긴다 — 모달 푸터도 같은 API 다. 그만두기는 모달의 닫기(X)가 맡는다. 단계를 오가며 입력이 쌓이지만 `SActionModal` 은 기본이 바깥 클릭·ESC 로 닫히지 않으므로(§3-3-5) `persistent` 를 따로 주지 않는다.
+
+<!-- recipe:src/recipes/ProductBulkUploadPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useState } from 'react';
+import {
+  SButton,
+  SCallout,
+  SCard,
+  SDivider,
+  SForm,
+  SIcon,
+  SKeyValueTable,
+  SRadioCardGroup,
+  SScrollArea,
+  SStepper,
+  STable,
+  STag,
+  type SCardProps,
+  type SKeyValueField,
+  type STableColumn,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { commitUpload, downloadErrorRows, validateUpload, type UploadRow } from './api';
+import { useNavigate } from './router';
+
+const STEPS = [
+  { label: '파일 선택', value: 'file' },
+  { label: '검증 결과 확인', value: 'check' },
+  { label: '등록 완료', value: 'done' },
+];
+
+const MODE_OPTIONS = [
+  { value: 'create', label: '신규 등록', subtitle: '파일의 모든 행을 새 상품으로 등록합니다.' },
+  { value: 'update', label: '기존 상품 수정', subtitle: '상품코드가 같은 상품의 값을 덮어씁니다.' },
+];
+
+const fileFields: SKeyValueField[][] = [
+  [
+    {
+      name: 'file',
+      label: '엑셀 파일',
+      type: 'file-picker',
+      required: true,
+      options: {
+        accept: '.xlsx',
+        placeholder: '.xlsx 파일을 올려 주세요',
+        rules: [(v: unknown) => !!v || '파일을 선택해 주세요'],
+      },
+    },
+  ],
+];
+
+const columns: STableColumn<UploadRow>[] = [
+  // 행 번호는 엑셀의 위치를 가리키는 식별자다 → center
+  { name: 'row', label: '행', field: 'row', width: 64, align: 'center' },
+  { name: 'name', label: '상품명', field: 'name', width: 240 },
+  {
+    name: 'price',
+    label: '판매가',
+    field: 'price',
+    width: 120,
+    align: 'right',
+    format: (v: unknown) => `${Number(v).toLocaleString()}원`,
+  },
+  {
+    name: 'result',
+    label: '결과',
+    field: 'error',
+    width: 240,
+    contentType: 'control',
+    render: row =>
+      row.error ? (
+        <STag size="sm" color="red" label={row.error} />
+      ) : (
+        <STag size="sm" color="green" label="정상" />
+      ),
+  },
+];
+
+export default function ProductBulkUploadPage() {
+  const navigate = useNavigate();
+  const [step, setStep] = useState(0);
+  const [values, setValues] = useState<Record<string, unknown>>({ mode: 'create' });
+  const [rows, setRows] = useState<UploadRow[]>([]);
+  const [registered, setRegistered] = useState(0);
+
+  const errorCount = rows.filter(r => r.error).length;
+  // 지난 단계는 completed — 앞으로 건너뛰지 못하게 가로 스텝퍼는 clickable 이 기본으로 꺼져 있다
+  const items = STEPS.map((s, i) => ({ ...s, completed: i < step }));
+
+  // 1단계 → 2단계: SForm 이 규칙을 통과시킨 뒤에만 불린다
+  const validate = async () => {
+    setRows(await validateUpload(values));
+    setStep(1);
+  };
+  const commit = async () => {
+    setRegistered(await commitUpload(rows));
+    setStep(2);
+  };
+
+  // 오른쪽 버튼은 단계마다 하는 일이 다르다 — 입력 단계는 SForm 검증을 거치는 submit,
+  // 실행 단계는 라벨을 하는 일로 쓴다(`19개 등록`). 이 화면의 최상위 실행이라 primary 하나다 (§3-5-1).
+  // 화살표는 단계를 옮기는 이동 버튼(이전·다음)에만 붙인다 — 실행 버튼에 붙이면 되돌릴 수 없는 실행이
+  // "다음 단계 보기" 처럼 가볍게 읽힌다
+  const button: SCardProps['button'] =
+    step === 0
+      ? { label: '다음', rightIcon: 'arrowRight', type: 'submit' }
+      : step === 1
+        ? {
+            label: `${(rows.length - errorCount).toLocaleString()}개 등록`,
+            type: 'button',
+            disabled: rows.length === errorCount,
+            onClick: commit,
+          }
+        : { label: '상품 목록으로', type: 'button', onClick: () => navigate('/products') };
+
+  return (
+    // 그만두기는 헤더의 뒤로가기(onBack)가 맡는다 — 카드 푸터에는 이전·다음만 둔다.
+    // 푸터를 늘 보이게 하려고 fill — 단계 본문만 카드 안에서 스크롤한다 (§2-2)
+    <AppShell
+      header={{ variant: 'bar', title: '상품 일괄 등록', onBack: () => navigate('/products') }}
+      contentHeight="fill"
+    >
+      {/* 푸터의 다음 버튼(submit)이 폼 안에 들어야 하므로 SForm 이 카드를 감싼다 */}
+      <SForm formClassName="h-full" onSubmit={validate}>
+        {/* 스텝퍼와 단계 본문을 한 프레임(카드 하나)에 담는다 — 세로형(§4-11)과 같은 구성이다.
+            단계 이동은 이 프레임 안에서 닫히는 액션이라 카드 푸터다 (§3-7-8). 프레임이 화면의 주 액션을
+            쥐므로 footerSize 는 기본(md)이고, footerLeft 슬롯 버튼도 md 를 명시한다 (§3-5-2).
+            첫 단계의 이전은 비활성, 완료 단계에는 되돌릴 것이 없어 이전 대신 오류 행 내려받기를 둔다 */}
+        <SCard
+          bordered
+          className="flex h-full flex-col"
+          footerLeft={
+            step < 2 ? (
+              <SButton
+                type="button"
+                color="neutral"
+                outline
+                size="md"
+                label="이전"
+                icon="arrowLeft"
+                disabled={step === 0}
+                onClick={() => setStep(0)}
+              />
+            ) : (
+              // 완료 단계에는 되돌릴 것이 없다 — 왼쪽 끝은 위계가 낮은 실행 액션 자리다 (§3-5-6).
+              // 건너뛴 행이 있으면 고쳐서 다시 올릴 수 있게 그 행을 내려받게 한다.
+              // 파일을 받는 실행이라 링크(STextLink, 이동)가 아니라 버튼이다
+              errorCount > 0 && (
+                <SButton
+                  type="button"
+                  color="neutral"
+                  outline
+                  size="md"
+                  icon="download"
+                  label="오류 행 내려받기"
+                  onClick={() => downloadErrorRows(rows.filter(r => r.error))}
+                />
+              )
+            )
+          }
+          button={button}
+        >
+          {/* 스텝퍼가 현재 단계 이름을 말하므로 단계 제목을 따로 두지 않는다. 가로 스텝퍼는 프레임 가운데에 놓는다.
+              단계들이 한 프레임을 공유하므로 여백은 가장 복합적인 단계에 맞춰 통일한다 (§2-2) —
+              1단계가 안내 + 카드 선택 + 표로 세 종류라 프레임 전체가 24 다 */}
+          <div className="flex justify-center p-sd-24">
+            <SStepper items={items} value={STEPS[step].value} />
+          </div>
+          <SDivider />
+          {/* 단계 본문만 스크롤한다 — 직접 만든 스크롤 영역은 SScrollArea (§1-1).
+              스크롤 영역 자체를 flex 로 두지 않고 안쪽에 쌓기 상자를 둔다 — 여백·scrollEnd 여백도 안쪽에 (§2-2) */}
+          <SScrollArea axis="vertical" overlayScrollbar className="min-h-0 flex-1">
+            <div className="flex min-h-full flex-col gap-sd-12 p-sd-24 pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+              {step === 0 && (
+                <>
+                  <SCallout
+                    message={[
+                      '양식의 첫 행(머리글)은 지우지 않습니다.',
+                      '한 번에 1,000행까지 올릴 수 있습니다.',
+                    ]}
+                  />
+                  <SRadioCardGroup
+                    options={MODE_OPTIONS}
+                    value={values.mode as string}
+                    onValueChange={v => setValues({ ...values, mode: v })}
+                  />
+                  <SKeyValueTable
+                    fields={fileFields}
+                    values={values}
+                    onChange={({ values }) => setValues(values)}
+                  />
+                </>
+              )}
+
+              {step === 1 && (
+                <>
+                  {/* 오류가 있으면 무엇이 빠지는지 먼저 말한다 — 오류 행은 등록하지 않고 건너뛴다 */}
+                  {errorCount > 0 ? (
+                    <SCallout
+                      type="danger"
+                      message={[
+                        `전체 ${rows.length.toLocaleString()}행 중 ${errorCount.toLocaleString()}행에 오류가 있습니다.`,
+                        '오류 행은 등록하지 않고 건너뜁니다. 고쳐서 올리려면 이전 단계로 돌아갑니다.',
+                      ]}
+                    />
+                  ) : (
+                    <SCallout
+                      message={[`전체 ${rows.length.toLocaleString()}행을 등록할 수 있습니다.`]}
+                    />
+                  )}
+                  <STable<UploadRow> columns={columns} rows={rows} rowKey="id" />
+                </>
+              )}
+
+              {step === 2 && (
+                // 결과 안내 — 아이콘·제목·설명을 본문 가운데에 세로로 쌓는다.
+                // 프레임이 이미 카드라 카드를 한 겹 더 두르지 않는다 (§2-0 포함 규칙).
+                // 무엇이 빠졌는지도 여기서 다시 말한다 — 건너뛴 행이 있으면 건수를 적는다
+                <div className="flex flex-1 flex-col items-center justify-center gap-sd-8 py-sd-48 text-center">
+                  <SIcon name="checkFill" size={40} color="var(--sys-color-fg-success)" />
+                  <h2 className="typo-heading-sm m-0">상품 등록을 마쳤습니다</h2>
+                  <p className="typo-body-sm-default m-0 text-fg-secondary">
+                    상품 {registered.toLocaleString()}개를 등록했습니다.
+                    {errorCount > 0 && ` 오류 ${errorCount.toLocaleString()}행은 건너뛰었습니다.`}
+                  </p>
+                </div>
+              )}
+            </div>
+          </SScrollArea>
+        </SCard>
+      </SForm>
+    </AppShell>
+  );
+}
+```
+<!-- /recipe -->
+
+#### 세로형
+
+구조: **페이지 헤더 → 프레임 `SCard` 하나 [스텝퍼 열 | `SDivider vertical` | 단계 본문] + 카드 푸터(이전 · 저장하고 다음)**
+
+- **스텝퍼와 단계 본문을 한 프레임(카드 하나)에 담는다.** 둘이 한 작업으로 읽힌다. 단계가 길어 스텝퍼를 블록 스택 맨 위에 눕힐 수 없으므로 자기 열을 갖고, 열 폭은 화면 고유 치수로 고정한다(§1-2). 열 사이 경계는 항상 보이는 선이라 `SDivider vertical` 이다(§3-6).
+- **단계 저장은 프레임 안에서 닫히는 액션이라 카드 푸터다** — `SCard` 의 `footerLeft`(이전) · `button`(저장하고 다음, 마지막은 저장하고 마치기)으로 넘긴다(§3-7-8). 하단 줄을 `SDivider`·패딩으로 손으로 만들지 않는다 — 바탕·여백 토큰이 빠진다. 프레임이 화면의 주 액션을 쥐므로 `footerSize` 는 기본(`md`)이고, `footerLeft` 슬롯 버튼도 `size="md"` 를 명시한다(§3-5-2). 화살표는 가로형과 같은 규칙이다 — 이동 버튼인 이전에만 `icon="arrowLeft"` 를 붙이고, 저장을 실행하는 "저장하고 다음" 에는 붙이지 않는다.
+- **푸터는 고정하고 두 열만 각자 스크롤한다.** 카드를 `flex h-full flex-col` 로 두고 그 안의 열 그리드를 `min-h-0 flex-1` 로 이은 뒤, 열마다 `SScrollArea axis="vertical" overlayScrollbar` 를 둔다 — `div` 에 `overflow-y-auto` 를 직접 주지 않는다(§1-1). `overlayScrollbar` 는 막대를 스크롤하는 동안에만 띄워 폭을 차지하지 않으므로, 좁은 스텝퍼 열이 스크롤바만큼 깎이지 않는다. 열 전체를 푸터와 함께 스크롤시키면 단계가 길어질 때 저장 버튼이 화면 밖으로 밀린다. **스크롤 영역 자체를 `flex flex-col` 로 두지 않는다** — 자식(표)이 열 높이에 맞춰 눌려(`flex-shrink`) 넘치지 않고 잘린다. `SScrollArea` 안에 세로 쌓기 상자를 한 겹 두고, 여백과 패널 스크롤의 하단 여백(`pb-[var(--cmp-pageBody-padding-scrollEnd)]`, §2-2)은 그 안쪽 상자에 준다 — `overlayScrollbar` 에서는 `SScrollArea` 에 준 패딩이 바깥 상자에 걸려 콘텐츠가 그 여백 아래로 흘러들지 않는다.
+- **단계 본문 제목은 섹션 제목 프리셋(`typo-heading-sm`)을 직접 쓴다** — 카드 안에 카드를 겹칠 수 없어서다(§3-7-8). 곁에 그룹 이름을 `text-fg-secondary` 로 두어 스텝퍼의 그룹과 이어 읽히게 한다. 본문 영역은 직접 만든 영역이라 여백은 §2-2 판정을 따른다.
+- **저장하면 그 단계를 완료로 남기고 오류를 지운 뒤 다음 단계로 넘어간다.** 저장 버튼이 카드로 올라가므로 편집 값은 페이지가 든다 — 단계를 옮기면 편집 값을 비우고 그 단계의 저장된 값을 다시 보인다.
+- **처음 열 단계는 아직 끝내지 않은 첫 단계다.** 이미 끝낸 단계부터 다시 보여주지 않는다.
+- **스텝퍼 열이 스크롤돼도 활성 단계는 스텝퍼가 보이는 곳으로 옮긴다** — 처음 그릴 때와 단계가 바뀔 때, `showItemTooltip()` 으로 오류 단계를 짚을 때 모두 그렇다. 직접 `scrollIntoView` 를 부르지 않는다. 스텝퍼 폭도 부모보다 넓어지지 않으므로(스크롤바가 폭을 차지하는 일반 스크롤 영역에서도 가로 스크롤이 생기지 않는다), 열 폭을 스텝퍼 폭보다 넓게 잡거나 `overflow-x-hidden` 으로 가리지 않는다.
+- **완료·오류는 단계마다 앱이 든다.** 지난 단계라고 완료가 아니다 — 서버가 아는 상태를 `completed`·`error` 로 넘긴다.
+- **마치기 전에 남은 오류를 짚는다.** 확인이 필요한 단계가 남았으면 마치지 않고 `ref.showItemTooltip()` 으로 첫 오류 단계에 툴팁을 띄운다. 문구는 스텝퍼가 정한다 — 직접 만든 토스트·모달로 대신하지 않는다.
+
+<!-- recipe:src/recipes/StoreSetupPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useRef, useState } from 'react';
+import {
+  SButton,
+  SCard,
+  SDivider,
+  SKeyValueTable,
+  SScrollArea,
+  SStepper,
+  type SKeyValueField,
+  type SStepperHandle,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { SETUP_STEPS, saveSetupStep, useSetupStatus, useSetupStep } from './api';
+import { useNavigate } from './router';
+
+/** 단계마다 입력 표 하나 — 단계 이름이 본문 제목이 되므로 필드만 정한다 */
+const FIELDS: Record<string, SKeyValueField[][]> = {
+  'biz': [
+    [
+      { name: 'storeName', label: '상호', type: 'input', required: true },
+      { name: 'bizNo', label: '사업자 번호', type: 'input', required: true },
+    ],
+  ],
+  'warehouse': [
+    [
+      { name: 'warehouseName', label: '창고 이름', type: 'input', required: true },
+      { name: 'address', label: '주소', type: 'input' },
+    ],
+  ],
+  'smartstore': [
+    [
+      { name: 'sellerId', label: '판매자 ID', type: 'input', required: true },
+      { name: 'apiKey', label: 'API 키', type: 'input', required: true },
+    ],
+  ],
+  'coupang': [
+    [
+      { name: 'vendorId', label: '업체 코드', type: 'input', required: true },
+      { name: 'accessKey', label: 'Access Key', type: 'input', required: true },
+    ],
+  ],
+  // 항목이 많은 단계 — 본문 열이 창보다 길어져 그 열 안에서 스크롤한다 (푸터는 고정)
+  'order': [
+    [
+      { name: 'autoConfirm', label: '자동 주문 확정', type: 'switch' },
+      {
+        name: 'holdHours',
+        label: '확정 보류 시간',
+        type: 'number-input',
+        options: { min: 1, max: 72, width: 'xs', inputSuffix: '시간' },
+      },
+    ],
+    [
+      { name: 'splitShipping', label: '부분 출고 허용', type: 'switch' },
+      { name: 'combineShipping', label: '합포장 허용', type: 'switch' },
+    ],
+    [
+      {
+        name: 'cutoffTime',
+        label: '당일 출고 마감',
+        type: 'select',
+        options: {
+          valueAsPrimitive: true,
+          options: ['12:00', '14:00', '16:00', '18:00'].map(t => ({ label: t, value: t })),
+        },
+      },
+      {
+        name: 'courier',
+        label: '기본 택배사',
+        type: 'select',
+        options: {
+          valueAsPrimitive: true,
+          options: [
+            { label: 'CJ대한통운', value: 'cj' },
+            { label: '롯데택배', value: 'lotte' },
+            { label: '한진택배', value: 'hanjin' },
+          ],
+        },
+      },
+    ],
+    [
+      {
+        name: 'invoicePrint',
+        label: '송장 출력',
+        type: 'radio',
+        tdColSpan: 3,
+        options: {
+          options: [
+            { label: '주문 확정 시 자동', value: 'auto' },
+            { label: '담당자가 직접', value: 'manual' },
+          ],
+        },
+      },
+    ],
+    [
+      { name: 'giftWrap', label: '선물 포장 옵션', type: 'switch' },
+      {
+        name: 'giftWrapFee',
+        label: '선물 포장 비용',
+        type: 'number-input',
+        options: { min: 0, width: 'sm', inputSuffix: '원' },
+      },
+    ],
+    [
+      {
+        name: 'returnDays',
+        label: '반품 접수 기간',
+        type: 'number-input',
+        options: { min: 1, max: 30, width: 'xs', inputSuffix: '일' },
+      },
+      { name: 'exchangeAllowed', label: '교환 허용', type: 'switch' },
+    ],
+    [
+      {
+        name: 'returnFee',
+        label: '반품 배송비',
+        type: 'number-input',
+        options: { min: 0, width: 'sm', inputSuffix: '원' },
+      },
+      {
+        name: 'exchangeFee',
+        label: '교환 배송비',
+        type: 'number-input',
+        options: { min: 0, width: 'sm', inputSuffix: '원' },
+      },
+    ],
+    [
+      {
+        name: 'packingMemo',
+        label: '포장 안내',
+        type: 'textarea',
+        tdColSpan: 3,
+        options: { placeholder: '출고 담당자에게 보일 포장 안내를 적어 주세요.' },
+      },
+    ],
+    [
+      {
+        name: 'shippingMemo',
+        label: '배송 메모 기본값',
+        type: 'textarea',
+        tdColSpan: 3,
+        options: { placeholder: '송장에 인쇄할 배송 메모를 적어 주세요.' },
+      },
+    ],
+  ],
+  'notice': [[{ name: 'newOrder', label: '신규 주문 알림', type: 'switch' }]],
+  'account': [
+    [
+      { name: 'managerName', label: '담당자 이름', type: 'input', required: true },
+      { name: 'managerEmail', label: '이메일', type: 'input', required: true },
+    ],
+  ],
+  '11st': [
+    [
+      { name: 'sellerId', label: '판매자 ID', type: 'input', required: true },
+      { name: 'apiKey', label: 'API 키', type: 'input', required: true },
+    ],
+  ],
+  'gmarket': [
+    [
+      { name: 'sellerId', label: '판매자 ID', type: 'input', required: true },
+      { name: 'apiKey', label: 'API 키', type: 'input', required: true },
+    ],
+  ],
+  'own': [[{ name: 'mallUrl', label: '쇼핑몰 주소', type: 'input', options: { width: '100%' } }]],
+  'category': [[{ name: 'useMapping', label: '판매처 카테고리 매핑', type: 'switch' }]],
+  'option': [
+    [
+      {
+        name: 'defaultTemplate',
+        label: '기본 옵션 템플릿',
+        type: 'select',
+        options: {
+          valueAsPrimitive: true,
+          options: [
+            { label: '사이즈', value: 'size' },
+            { label: '색상', value: 'color' },
+            { label: '사이즈 + 색상', value: 'size-color' },
+          ],
+        },
+      },
+    ],
+  ],
+  'settlement': [
+    [
+      {
+        name: 'settleDay',
+        label: '정산일',
+        type: 'number-input',
+        options: { min: 1, max: 28, width: 'xs', inputSuffix: '일' },
+      },
+    ],
+  ],
+  'permission': [[{ name: 'approvalRequired', label: '주문 취소 승인 필요', type: 'switch' }]],
+};
+
+type Values = Record<string, unknown>;
+
+export default function StoreSetupPage() {
+  const navigate = useNavigate();
+  const status = useSetupStatus();
+  const stepperRef = useRef<SStepperHandle>(null);
+  // 처음에는 아직 끝내지 않은 첫 단계를 연다
+  const [step, setStep] = useState(
+    () => SETUP_STEPS.find(s => !status.completed.includes(s.value))?.value ?? SETUP_STEPS[0].value,
+  );
+  const [completed, setCompleted] = useState(status.completed);
+  const [errors, setErrors] = useState(status.error);
+
+  // 편집 중인 값은 저장 전까지만 산다 — 단계를 옮기면 비우고 그 단계의 저장된 값을 다시 보인다
+  const saved = useSetupStep(step);
+  const [draft, setDraft] = useState<Values | null>(null);
+  const values = draft ?? saved;
+  const goTo = (next: string) => {
+    setDraft(null);
+    setStep(next);
+  };
+
+  const index = SETUP_STEPS.findIndex(s => s.value === step);
+  const current = SETUP_STEPS[index];
+  const isLast = index === SETUP_STEPS.length - 1;
+  // 완료·오류는 단계마다 따로 남는다 — 완료한 단계에도 오류가 남을 수 있다(인증 만료 등)
+  const items = SETUP_STEPS.map(s => ({
+    ...s,
+    completed: completed.includes(s.value),
+    error: errors.includes(s.value),
+  }));
+
+  // 단계를 저장하면 완료로 남기고 다음 단계로 넘어간다. 마지막 단계에서는 남은 오류부터 짚는다
+  const save = async () => {
+    await saveSetupStep(step, values);
+    setCompleted(current => (current.includes(step) ? current : [...current, step]));
+    const restErrors = errors.filter(e => e !== step);
+    setErrors(restErrors);
+    if (!isLast) return goTo(SETUP_STEPS[index + 1].value);
+    setDraft(null);
+    // 확인이 필요한 단계가 남았으면 첫 오류 단계에 툴팁을 띄운다 — 문구는 스텝퍼가 정한다
+    if (restErrors.length) return stepperRef.current?.showItemTooltip();
+    navigate('/');
+  };
+
+  return (
+    // 스텝퍼 열과 단계 본문이 각자 안에서 스크롤해야 하므로 fill (§2-2)
+    <AppShell header={{ variant: 'bar', title: '초기 설정' }} contentHeight="fill">
+      {/* 스텝퍼와 단계 본문을 한 프레임(카드 하나)에 담는다 — 둘이 한 작업으로 읽힌다.
+          단계 저장은 이 프레임 안에서 닫히는 액션이라 카드 푸터다 (§3-7-8). 프레임이 화면의 주 액션을
+          쥐므로 footerSize 는 기본(md)이고, footerLeft 슬롯 버튼도 md 를 명시한다 (§3-5-2) */}
+      <SCard
+        bordered
+        className="flex h-full flex-col"
+        footerLeft={
+          <SButton
+            color="neutral"
+            outline
+            size="md"
+            label="이전"
+            icon="arrowLeft"
+            disabled={index === 0}
+            onClick={() => goTo(SETUP_STEPS[index - 1].value)}
+          />
+        }
+        button={{ label: isLast ? '저장하고 마치기' : '저장하고 다음', onClick: save }}
+      >
+        {/* 스텝퍼 열 | 구분선 | 단계 본문. 푸터는 고정하고 두 열만 각자 스크롤한다 — min-h-0 flex-1 로 높이를 잇는다.
+            스텝퍼 열 폭은 화면 고유 치수다 (§1-2) */}
+        <div className="grid min-h-0 flex-1 grid-cols-[240px_auto_1fr]">
+          {/* 세로형은 기본으로 눌린다 — 끝낸 단계로 돌아가 고칠 수 있고, 앞으로는 끝낸 단계 바로 다음까지만 간다 */}
+          {/* 직접 만든 스크롤 영역은 SScrollArea 다 (§1-1). overlayScrollbar 는 막대를 스크롤하는 동안에만
+              영역 위에 띄워 폭을 차지하지 않는다 — 좁은 열의 폭이 스크롤바만큼 깎이지 않는다.
+              단계가 많으면 이 열도 자기 안에서 스크롤한다 — 패널 자체 스크롤이라 끝에 scrollEnd 여백을 둔다 (§2-2).
+              overlay 모드에서는 패딩이 바깥 상자에 걸리므로 여백은 안쪽 상자에 준다 */}
+          <SScrollArea axis="vertical" overlayScrollbar className="min-h-0">
+            <div className="pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+              <SStepper ref={stepperRef} vertical items={items} value={step} onValueChange={goTo} />
+            </div>
+          </SScrollArea>
+          {/* 항상 보이는 세로 경계선 — 길이는 줄 높이를 채운다 (§3-6) */}
+          <SDivider vertical />
+          {/* 스크롤 영역(SScrollArea)과 세로 쌓기 상자를 나눈다 — 스크롤 상자를 flex 로 두면 표가 열 높이에 맞춰
+              눌려(flex-shrink) 넘치지 않고 잘린다. 패널 자체 스크롤이라 끝에 scrollEnd 여백을 둔다 (§2-2) */}
+          <SScrollArea axis="vertical" overlayScrollbar className="min-h-0">
+            {/* 자체 면을 가진 덩어리가 표 하나뿐이라 직접 만든 영역의 여백은 16 이다 (§2-2) */}
+            <div className="flex flex-col gap-sd-12 p-sd-16 pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+              {/* 프레임 안의 단계 제목 — 카드 안에 카드를 겹칠 수 없어 섹션 제목 프리셋을 직접 쓴다 (§2-1).
+                  그룹 이름을 곁에 두어 스텝퍼의 그룹과 이어 읽힌다 */}
+              <div className="flex items-center gap-sd-8">
+                <h2 className="typo-heading-sm m-0">{current.label}</h2>
+                <span className="typo-body-sm-default text-fg-secondary">{current.group}</span>
+              </div>
+              <SKeyValueTable
+                fields={FIELDS[step]}
+                values={values}
+                onChange={({ values }) => setDraft(values)}
+              />
+            </div>
+          </SScrollArea>
+        </div>
+      </SCard>
+    </AppShell>
+  );
+}
+```
+<!-- /recipe -->
+
+### 4-12. 상담 화면 — 목록 · 대화 · 템플릿 세 영역
+
+구조: **페이지 헤더 → [상담 목록 | 대화(메시지 스크롤 + 입력창) | 답변 템플릿]** — 화면을 통째로 쓰는 콘솔
+
+- **페이지 여백을 끄고 세 영역이 화면 끝까지 찬다** — `AppShell` 에 `padding="none"`. 영역은 카드가 아니라 높이를 잇는 세로 영역(`flex h-full min-h-0 flex-col`)이다. 카드로 감싸면 화면 끝에 붙은 테두리가 겹쳐 그려지고, 세 영역 중 일부만 카드면 문법이 갈린다.
+- **영역 사이 경계는 상담사가 끌어 폭을 바꾼다 — `SSplitter`** (§3-6). 패널이 둘뿐이라 `[목록 | (대화 | 템플릿)]` 으로 중첩한다. 목록은 사이드라 `unit="px"`(기본·`limits` 는 화면 고유 치수), 대화·템플릿은 크기 모델이 첫 패널(대화)이라 비율로 나눈다.
+  - **경계는 구분선 자리의 띠로 보인다.** 스플리터는 패널 사이에 구분선 자리(토큰 폭)를 비워 두고, 그 선은 끌 수 있는 자리를 알릴 때(hover·포커스)만 칠한다. 그대로 두면 빈 띠에서 머리 줄 가로선·선택 행 바탕이 끊겨 틈처럼 보인다. **`SSplitter` 바탕을 `bg-bg-neutralLight` 로 깔고 각 패널을 `bg-bg-frame` 으로 덮어** 그 띠만 옅은 면으로 남긴다 — 그 띠가 늘 보이는 영역 경계가 된다. 패널에 `border-*` 를 따로 긋거나 스플리터 구분선 색·두께를 바꾸지 않는다.
+- **세 영역의 머리 줄은 같은 높이다** — 그래야 아래 가로 구분선(`SDivider`)이 세 영역에서 한 줄로 이어진다. 높이는 화면 고유 치수로 한 곳에 두고 세 영역이 같이 쓴다. 머리 줄의 글자는 프리셋이다 — 이름·영역 제목은 `typo-heading-sm`, 문의 유형 같은 보조는 `typo-body-sm-default` + `text-fg-secondary` (§2-1). 임의 크기·굵기를 주지 않는다.
+- **상담 목록 머리 줄은 상태별 탭이다** — 보는 관점을 바꾸는 것이라 `STabs`(§3-7-2), 영역 안의 탭이라 밑줄형(`sub`), 건수는 `badge`. 목록 항목으로 탭을 흉내 내지 않는다(§1-1).
+  - **영역이 좁아져 탭이 넘치면 탭 줄만 가로로 스크롤한다** — 탭 줄을 `SScrollArea axis="horizontal" overlayScrollbar` 로 감싸고, 영역에 `min-w-0` 을 준다. 그러지 않으면 넘친 폭이 영역 전체를 밀어내 패널에 가로 스크롤이 생긴다. 목록은 스크롤하지 않고 `SListItem` 의 보조 텍스트가 말줄임된다.
+  - **스크롤 영역은 머리 줄 높이 전체로 늘린다(`self-stretch`)** — 안쪽은 `flex h-full items-center` 로 탭을 세로 가운데에 둔다. overlay 막대는 스크롤 영역 바닥에 뜨므로, 탭 높이로만 잡으면 막대가 탭 글자를 가린다.
+  - 탭을 가운데에 두려면 안쪽을 `mx-auto w-fit` 으로 감싼다 — `justify-center` 로 두면 넘칠 때 앞쪽 탭이 왼쪽 밖으로 잘려 스크롤로도 닿지 않는다. overlay 라 좌우 여백은 안쪽 상자에 준다.
+- **세 영역은 각자 안에서 스크롤한다.** `contentHeight="fill"` 에 영역 그리드를 `h-full min-h-0` 으로 잇고, 영역마다 머리 줄 아래를 `SScrollArea axis="vertical" overlayScrollbar` + `min-h-0 flex-1` 로 채운다 (§1-1). 대화 영역은 그 아래에 입력창을 고정한다.
+- **여백은 영역마다 다르다** (§2-2 상담 콘솔 예). 목록·템플릿은 같은 항목의 반복이라 목록 컴포넌트가 자기 여백을 갖고, 머리 줄도 목록 항목의 좌우 여백(`--cmp-listItem-paddingX`)에 맞춘다. 대화는 말풍선·파일·시스템 안내가 섞여 24 다 — 머리 줄·스크롤 안쪽 상자가 24 를 쓴다. 입력 영역은 `SDivider` 로 대화와 나누고, 좌우는 메시지와 끝을 맞춰 24, 위아래는 16 이다.
+- **대화는 최신이 바닥이다.** 쌓기 상자에 `min-h-full justify-end` 로 메시지가 적어도 바닥에 붙이고, 처음 열 때와 메시지가 늘 때 스크롤 영역(`SScrollArea` 의 ref)을 맨 아래로 내린다. 입력창은 스크롤 밖 바닥에 고정한다.
+- **메시지 한 건 = 한 사람이 이어 말한 묶음이다.** 같은 사람이 같은 시각에 이어 보낸 글·파일은 `SChatMessage` 하나로 묶어 `messages`·`attachments` 로 넘긴다 — 말풍선마다 컴포넌트를 따로 세우지 않는다. 파일은 `attachments` 로만 넘긴다 (`messages` 로 넘기면 칸이 두 겹이 된다).
+- **줄 사이 간격은 토큰이 정한다** — 메시지 묶음 사이는 `--cmp-chatMessage-group-message-gap`, 시스템 안내(`SChatSystemMessage`) 앞뒤는 그보다 넓은 `--cmp-chatMessage-group-system-gap`. 숫자로 적지 않는다.
+- **날짜가 바뀌는 자리에는 날짜 구분선을 끼운다** — 가로 `SDivider` 두 개 사이에 날짜(`typo-body-sm-default` + `text-fg-tertiary`). 일어난 사실이 아니라 흐름의 경계라 시스템 안내 알약(`SChatSystemMessage`)을 쓰지 않는다. **날짜는 `2026년 10월 6일 화요일`** 로 쓴다 — 말풍선 시각과 같은 대화 예외다(§1-4). `toLocaleDateString()` 은 로케일에 따라 결과가 바뀌므로 쓰지 않고 연·월·일·요일을 직접 이어 붙인다. 가로 구분선은 기본이 전체 폭이라 한 줄에 둘을 놓을 때는 `className="w-auto flex-1"` 로 남은 폭을 나눠 갖게 한다. 앞뒤 간격은 시스템 안내와 같은 토큰이다. 날짜가 다르면 같은 시각이어도 한 묶음으로 합치지 않는다.
+- 대화의 시각은 `오후 5:52` 로 쓴다 (§1-4 대화 예외). 읽음 표시는 보낸 메시지에만, 템플릿으로 보낸 글은 `variant="template"` 로 면을 나눈다.
+- **입력 중인 글은 페이지가 상담마다 든다.** 상담을 옮겨도 쓰던 글이 남고, 템플릿 패널이 그 글에 넣을 수 있다. 템플릿은 누르면 **입력창에 넣는다** — 바로 보내지 않고 상담사가 고쳐 보낸다. 보내기 전 첨부는 입력창 위에 `SChatAttachedFile` 로 쌓는다.
+- **상담 종료는 `SChatInput` 의 `footerAction` 이다** — 전송과 층이 다른 동작이라 입력창 아래 보조 슬롯(`STextLink`)에 두고, 실행 전에 `SModal.confirm` 으로 묻는다. 종료된 상담은 입력창을 `disabled` 로 잠그고 종료 링크를 뺀다.
+- 목록의 상태는 `STag` 다 — 색 점(`SBadge`)만으로 찍지 않는다 (§3-1). 템플릿 분류는 `SExpansionList` 루트 하나에 분류(`SExpansionItem`) 안 템플릿(`SListItem`)을 바로 넣는다 (§3-7-7).
+
+<!-- recipe:src/recipes/ConsultConsolePage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import {
+  SChatAttachedFile,
+  SChatFile,
+  SChatInput,
+  SChatMessage,
+  SChatSystemMessage,
+  SDivider,
+  SExpansionItem,
+  SExpansionList,
+  SList,
+  SListItem,
+  SModal,
+  SScrollArea,
+  SSplitter,
+  STabs,
+  STag,
+  STextLink,
+  STooltip,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import {
+  CONSULTS,
+  REPLY_TEMPLATES,
+  closeConsult,
+  sendChatMessage,
+  useConsultMessages,
+  type ChatEntry,
+  type Consult,
+} from './api';
+
+const STATUS_TAG: Record<Consult['status'], { color: 'orange' | 'blue' | 'grey'; label: string }> =
+  {
+    waiting: { color: 'orange', label: '대기' },
+    active: { color: 'blue', label: '상담 중' },
+    closed: { color: 'grey', label: '종료' },
+  };
+
+const TEMPLATE_BODIES = new Set(REPLY_TEMPLATES.flatMap(g => g.items.map(t => t.body)));
+
+type Message = Extract<ChatEntry, { kind: 'message' }>;
+/**
+ * 화면에 그리는 단위 — 같은 사람이 같은 날 같은 시각에 이어 말한 메시지는 SChatMessage 하나로 묶고,
+ * 날짜가 바뀌는 자리에는 날짜 구분선을 끼운다
+ */
+type Row =
+  | { kind: 'date'; id: string; date: string }
+  | { kind: 'system'; id: string; text: string }
+  | { kind: 'group'; id: string; items: Message[] };
+
+function groupEntries(entries: ChatEntry[]): Row[] {
+  const rows: Row[] = [];
+  let lastDate = '';
+  for (const entry of entries) {
+    if (entry.date !== lastDate) {
+      rows.push({ kind: 'date', id: `d-${entry.date}`, date: entry.date });
+      lastDate = entry.date;
+    }
+    const last = rows[rows.length - 1];
+    if (entry.kind === 'system') rows.push(entry);
+    else if (
+      last?.kind === 'group' &&
+      last.items[0].direction === entry.direction &&
+      last.items[0].time === entry.time
+    )
+      last.items.push(entry);
+    else rows.push({ kind: 'group', id: entry.id, items: [entry] });
+  }
+  return rows;
+}
+
+const WEEKDAYS = ['일요일', '월요일', '화요일', '수요일', '목요일', '금요일', '토요일'];
+
+/**
+ * 대화의 날짜 구분선 표기 — `2026-10-06` → `2026년 10월 6일 화요일`.
+ * 대화 흐름을 짚는 표시라 말하듯 읽히는 표기를 쓴다 (§1-4 대화 예외).
+ * toLocaleDateString 은 쓰지 않는다 — 로케일에 따라 결과가 바뀐다 (§1-4)
+ */
+function formatChatDate(date: string) {
+  const [y, m, d] = date.split('-').map(Number);
+  const weekday = WEEKDAYS[new Date(y, m - 1, d).getDay()];
+  return `${y}년 ${m}월 ${d}일 ${weekday}`;
+}
+
+/** 줄 사이 간격은 토큰이 정한다 — 시스템 안내·날짜 구분선 앞뒤는 메시지 묶음 사이보다 넓게 벌린다 */
+const gapClass = (prev: Row | undefined, row: Row) =>
+  !prev
+    ? ''
+    : prev.kind !== 'group' || row.kind !== 'group'
+      ? 'mt-[var(--cmp-chatMessage-group-system-gap)]'
+      : 'mt-[var(--cmp-chatMessage-group-message-gap)]';
+
+export default function ConsultConsolePage() {
+  const [consultId, setConsultId] = useState(CONSULTS[0].id);
+  const consult = CONSULTS.find(c => c.id === consultId)!;
+  // 입력 중인 글은 페이지가 상담마다 든다 — 상담을 옮겨도 쓰던 글이 남고, 템플릿 패널이 넣을 수 있다
+  const [drafts, setDrafts] = useState<Record<string, string>>({});
+  const draft = drafts[consultId] ?? '';
+  const setDraft = (text: string) => setDrafts(current => ({ ...current, [consultId]: text }));
+
+  return (
+    // 상담 도구는 화면을 통째로 쓰는 콘솔이다 — 페이지 여백을 끄고(padding="none") 세 영역이 화면 끝까지 찬다.
+    // 세 영역이 각자 안에서 스크롤해야 하므로 fill (§2-2)
+    <AppShell header={{ variant: 'bar', title: '상담' }} contentHeight="fill" padding="none">
+      {/* 목록 | 대화 | 템플릿 — 상담사가 경계를 끌어 영역 폭을 바꾼다(SSplitter, §3-6).
+          SSplitter 는 패널이 둘이라 [목록 | (대화 | 템플릿)] 으로 중첩한다.
+          목록은 사이드라 폭을 px 로 유지하고, 대화·템플릿은 첫 패널(대화) 기준 비율로 나눈다 */}
+      <SSplitter unit="px" defaultValue={324} limits={[240, 480]} className="bg-bg-neutralLight">
+        {/* 패널 사이에는 구분선 자리(토큰 폭)가 띠로 남는다 — 스플리터 바탕을 옅은 회색으로 깔고 패널은
+            흰 면으로 덮어, 그 띠가 영역 경계로 늘 보이게 한다. 끌 수 있다는 표시(파란 선)는 hover 때 그 위에 드러난다 */}
+        <SSplitter.Before className="bg-bg-frame">
+          <ConsultList value={consultId} onChange={setConsultId} />
+        </SSplitter.Before>
+        <SSplitter.After>
+          <SSplitter defaultValue={72} limits={[50, 85]} className="bg-bg-neutralLight">
+            <SSplitter.Before className="bg-bg-frame">
+              {/* key 로 상담마다 대화를 새로 세운다 — 첨부가 다른 상담으로 새지 않는다 */}
+              <Conversation
+                key={consultId}
+                consult={consult}
+                draft={draft}
+                onDraftChange={setDraft}
+              />
+            </SSplitter.Before>
+            <SSplitter.After className="bg-bg-frame">
+              {/* 템플릿을 누르면 입력창에 넣는다 — 바로 보내지 않고 상담사가 고쳐 보낼 수 있게 한다 */}
+              <TemplatePanel onPick={body => setDraft(draft ? `${draft}\n${body}` : body)} />
+            </SSplitter.After>
+          </SSplitter>
+        </SSplitter.After>
+      </SSplitter>
+    </AppShell>
+  );
+}
+
+/** 영역 하나 — 스플리터 패널의 높이를 이어 받아 [머리 줄 | 스크롤 영역] 으로 세로로 나눈다 */
+// min-w-0 — 안쪽이 넓어져도 영역 폭을 밀어내지 않는다 (넘치는 것은 그 자리에서 스크롤·말줄임한다)
+const PANEL = 'flex h-full min-h-0 min-w-0 flex-col';
+/**
+ * 세 영역의 머리 줄. 높이를 하나로 맞춰야 아래 가로 구분선이 세 영역에서 한 줄로 이어진다 —
+ * 화면 고유 치수라 임의 값이다 (§1-2). 좌우 여백은 영역마다 그 아래 내용의 여백을 따른다
+ */
+const PANEL_HEADER = 'flex h-[56px] shrink-0 items-center gap-sd-8';
+
+const STATUS_TABS: { label: string; value: 'all' | Consult['status'] }[] = [
+  { label: '전체', value: 'all' },
+  { label: '대기', value: 'waiting' },
+  { label: '상담 중', value: 'active' },
+  { label: '종료', value: 'closed' },
+];
+
+/** 왼쪽 — 상담 목록. 같은 항목의 반복이라 목록이 자기 여백을 갖는다 (§2-2 상담 콘솔 예) */
+function ConsultList({ value, onChange }: { value: string; onChange: (id: string) => void }) {
+  // 상태별로 나눠 보는 것은 보는 관점을 바꾸는 것이라 STabs 다 (§3-7-2) — 목록 항목으로 탭을 흉내 내지 않는다
+  const [status, setStatus] = useState<string>('all');
+  const visible = status === 'all' ? CONSULTS : CONSULTS.filter(c => c.status === status);
+  // 탭마다 건수를 배지로 단다 — 대기 건수가 눈에 띄어야 상담사가 먼저 집는다
+  const tabs = STATUS_TABS.map(t => ({
+    ...t,
+    badge: (t.value === 'all' ? CONSULTS : CONSULTS.filter(c => c.status === t.value)).length,
+  }));
+
+  return (
+    <section className={PANEL}>
+      {/* 탭은 목록 스크롤 밖에 고정. 영역 안의 탭이라 밑줄형(sub).
+          영역이 좁아져 탭이 넘치면 탭 줄만 가로로 스크롤한다 — 넘친 폭이 영역 전체를 밀어내지 않게
+          스크롤 영역에 min-w-0. 안쪽은 mx-auto w-fit — 들어가면 가운데, 넘치면 왼쪽부터 (justify-center 로
+          두면 넘칠 때 앞쪽 탭이 왼쪽 밖으로 잘려 스크롤로도 닿지 않는다). overlay 라 패딩은 안쪽에 준다 */}
+      <div className={PANEL_HEADER}>
+        {/* 스크롤 영역을 머리 줄 높이 전체로 늘리고(self-stretch) 탭은 그 안에서 세로 가운데에 둔다 —
+            overlay 막대는 스크롤 영역 바닥에 뜨므로, 탭 높이로만 잡으면 막대가 탭 글자를 가린다 */}
+        <SScrollArea axis="horizontal" overlayScrollbar className="min-w-0 flex-1 self-stretch">
+          <div className="mx-auto flex h-full w-fit items-center px-(--cmp-listItem-paddingX)">
+            <STabs sub value={status} tabs={tabs} onValueChange={setStatus} />
+          </div>
+        </SScrollArea>
+      </div>
+      <SDivider />
+      {/* 직접 만든 스크롤 영역은 SScrollArea (§1-1) — 폭을 차지하지 않도록 overlay */}
+      <SScrollArea axis="vertical" overlayScrollbar className="min-h-0 flex-1">
+        <SList className="pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+          {visible.map(c => (
+            <SListItem
+              key={c.id}
+              title={c.customer}
+              supportingText={c.lastMessage}
+              supportingTextPosition="bottom"
+              // 상태는 STag — 색 점(SBadge)만으로 찍지 않는다 (§3-1)
+              trailing={
+                <STag
+                  size="sm"
+                  color={STATUS_TAG[c.status].color}
+                  label={STATUS_TAG[c.status].label}
+                />
+              }
+              clickable
+              selected={c.id === value}
+              onClick={() => onChange(c.id)}
+            />
+          ))}
+        </SList>
+      </SScrollArea>
+    </section>
+  );
+}
+
+/** 가운데 — 대화. 말풍선·파일·시스템 안내가 섞이는 영역이라 여백이 24 다 (§2-2 상담 콘솔 예) */
+function Conversation({
+  consult,
+  draft,
+  onDraftChange,
+}: {
+  consult: Consult;
+  draft: string;
+  onDraftChange: (text: string) => void;
+}) {
+  const initial = useConsultMessages(consult.id);
+  const [entries, setEntries] = useState<ChatEntry[]>(initial);
+  const [attached, setAttached] = useState<string[]>([]);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const closed = consult.status === 'closed';
+
+  // 대화는 최신이 바닥이다 — 처음 열 때와 메시지가 늘 때 맨 아래로 내린다
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [entries]);
+
+  const send = async (text: string) => {
+    await sendChatMessage(consult.id, text);
+    const date = '2026-10-06'; // 소비 앱에서는 서버가 준 날짜를 YYYY-MM-DD 로
+    const time = '오후 5:55'; // 소비 앱에서는 서버가 준 시각을 `오후 h:mm` 으로 적는다 (§1-4 대화 예외)
+    setEntries(current => [
+      ...current,
+      ...(text
+        ? [
+            {
+              kind: 'message' as const,
+              id: `n${current.length}`,
+              direction: 'outgoing' as const,
+              date,
+              time,
+              text,
+              // 템플릿 그대로 보낸 글은 template 면으로 — 무엇으로 보냈는지를 면이 말한다
+              variant: TEMPLATE_BODIES.has(text) ? ('template' as const) : undefined,
+            },
+          ]
+        : []),
+      ...attached.map((name, i) => ({
+        kind: 'message' as const,
+        id: `f${current.length}-${i}`,
+        direction: 'outgoing' as const,
+        date,
+        time,
+        file: { name, size: 204800 },
+      })),
+    ]);
+    onDraftChange('');
+    setAttached([]);
+  };
+
+  const confirmClose = () =>
+    SModal.confirm({
+      modalTitle: '상담을 종료할까요?',
+      topMessage: ['종료하면 고객에게 종료 안내가 전송됩니다.'],
+      mainButtonLabel: '종료',
+    }).onOk(() => closeConsult(consult.id));
+
+  const rows = groupEntries(entries);
+
+  return (
+    // 대화 영역은 [머리 줄 | 대화 스크롤 | 입력창] 세로 세 칸 — 입력창은 바닥에 고정
+    <section className={PANEL}>
+      <div className={`${PANEL_HEADER} justify-between px-sd-24`}>
+        {/* 누구와의 어떤 상담인지 — 이름은 섹션 제목 프리셋, 문의 유형은 보조 설명 (§2-1) */}
+        <div className="flex min-w-0 flex-col">
+          <span className="typo-heading-sm truncate">{consult.customer}</span>
+          <span className="typo-body-sm-default truncate text-fg-secondary">{consult.topic}</span>
+        </div>
+        <STag
+          size="sm"
+          color={STATUS_TAG[consult.status].color}
+          label={STATUS_TAG[consult.status].label}
+        />
+      </div>
+      <SDivider />
+      <SScrollArea ref={scrollRef} axis="vertical" overlayScrollbar className="min-h-0 flex-1">
+        {/* 메시지가 적으면 바닥에 붙인다(justify-end) — 대화는 아래에서 위로 쌓여 읽힌다 */}
+        <div className="flex min-h-full flex-col justify-end p-sd-24 pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+          {rows.map((row, i) => (
+            <div key={row.id} className={gapClass(rows[i - 1], row)}>
+              {row.kind === 'date' ? (
+                // 날짜 구분선 — 일어난 사실이 아니라 흐름의 경계라 시스템 안내 알약이 아니다.
+                // 대화의 날짜는 `2026년 10월 6일 화요일` 로 쓴다 (§1-4 대화 예외)
+                // 가로 구분선은 기본이 전체 폭이라 둘을 한 줄에 놓으면 앞의 것이 폭을 다 차지한다 —
+                // 두 선이 남은 폭을 나눠 갖게 한다
+                <div className="flex items-center gap-sd-12">
+                  <SDivider className="w-auto flex-1" />
+                  <span className="typo-body-sm-medium shrink-0 text-fg-tertiary">
+                    {formatChatDate(row.date)}
+                  </span>
+                  <SDivider className="w-auto flex-1" />
+                </div>
+              ) : row.kind === 'system' ? (
+                // 사람이 아니라 시스템이 알리는 사실 — 상담사 배정·종료 등 (§3-0 B)
+                <SChatSystemMessage message={[row.text]} />
+              ) : (
+                <SChatMessage
+                  direction={row.items[0].direction}
+                  sender={row.items[0].direction === 'incoming' ? consult.customer : undefined}
+                  time={row.items[0].time}
+                  // 읽음 표시는 보낸 메시지에만 붙는다
+                  readStatus={
+                    row.items[0].direction === 'outgoing'
+                      ? row.items.every(m => m.read)
+                        ? 'read'
+                        : 'unread'
+                      : undefined
+                  }
+                  variant={row.items[0].variant}
+                  messages={row.items.filter(m => m.text).map(m => m.text)}
+                  // 파일은 말풍선이 아니라 attachments 로 — messages 로 넘기면 칸이 두 겹이 된다
+                  attachments={row.items
+                    .filter(m => m.file)
+                    .map(m => (
+                      <SChatFile
+                        key={m.id}
+                        name={m.file!.name}
+                        size={m.file!.size}
+                        onFileClick={() => undefined}
+                      />
+                    ))}
+                />
+              )}
+            </div>
+          ))}
+        </div>
+      </SScrollArea>
+
+      {/* 입력 영역 — 구분선으로 대화와 나눈다. 좌우는 대화 영역과 같은 24 로 메시지와 끝을 맞추고,
+          위아래는 구분선으로 떨어진 작은 영역이라 16 이다. 보내기 전 첨부는 입력창 위에 SChatAttachedFile 로 쌓는다 */}
+      <SDivider />
+      <div className="flex flex-col gap-sd-8 py-sd-16">
+        {attached.length > 0 && (
+          <div className="flex flex-row flex-wrap gap-sd-8 px-sd-24">
+            {attached.map(name => (
+              <SChatAttachedFile
+                key={name}
+                name={name}
+                onRemove={() => setAttached(current => current.filter(n => n !== name))}
+              />
+            ))}
+          </div>
+        )}
+        <SChatInput
+          value={draft}
+          disabled={closed}
+          onValueChange={onDraftChange}
+          onSend={send}
+          onAttach={() => setAttached(current => [...current, `첨부_${current.length + 1}.png`])}
+          // 상담 종료는 전송과 층이 다른 동작 — 입력창 아래 보조 액션 슬롯이다
+          footerAction={!closed && <STextLink label="상담 종료" onClick={confirmClose} />}
+        />
+      </div>
+    </section>
+  );
+}
+
+/** 오른쪽 — 답변 템플릿. 같은 아코디언의 반복이라 목록이 자기 여백을 갖는다 (§2-2 상담 콘솔 예) */
+function TemplatePanel({ onPick }: { onPick: (body: string) => void }) {
+  return (
+    <section className={PANEL}>
+      <div className={`${PANEL_HEADER} px-(--cmp-listItem-paddingX)`}>
+        <span className="typo-heading-sm">답변 템플릿</span>
+        <STooltip
+          trigger="hover"
+          icon="helpOutline"
+          message={['누르면 입력창에 넣습니다. 보내기 전에 고칠 수 있습니다.']}
+        />
+      </div>
+      <SDivider />
+      <SScrollArea axis="vertical" overlayScrollbar className="min-h-0 flex-1">
+        {/* 분류(SExpansionItem) 안에 템플릿(SListItem)을 바로 넣는다 — 리스트는 루트에 하나 (§3-7-7) */}
+        <SExpansionList className="pb-[var(--cmp-pageBody-padding-scrollEnd)]">
+          {REPLY_TEMPLATES.map((group, i) => (
+            <SExpansionItem key={group.id} title={group.name} defaultExpanded={i === 0}>
+              {group.items.map(t => (
+                <SListItem
+                  key={t.id}
+                  title={t.title}
+                  supportingText={t.body}
+                  supportingTextPosition="bottom"
+                  onClick={() => onPick(t.body)}
+                />
+              ))}
+            </SExpansionItem>
+          ))}
+        </SExpansionList>
+      </SScrollArea>
+    </section>
+  );
+}
+```
+<!-- /recipe -->
+
+### 4-13. 모달·드로어 — 목록에서 띄우는 작업
+
+목록을 떠나지 않고 한 건을 다루는 흐름이다. **무엇을 하느냐로 그릇을 고른다.**
+
+| 작업 | 그릇 | 여는 법 |
+| --- | --- | --- |
+| 목록을 보면서 한 건을 보고 고친다 | `SDrawer` — 옆에서 밀려 나온다 | 선언형 — 열린 행을 페이지가 든다 |
+| 짧은 입력으로 새로 만든다 (등록) | `SActionModal` | 명령형 — `SModal.create` (§3-3-4) |
+| 순서대로 거치는 짧은 작업 (엑셀 일괄 등록) | `SActionModal` + 가로 `SStepper` | 명령형 — `SModal.create` |
+| 입력이 길어 여러 섹션이 필요하다 | 모달이 아니라 페이지 (§4-3) | 라우트 |
+
+- **모달·드로어의 푸터 버튼은 `SForm` 밖에 그려진다.** 본문의 `SForm` 은 푸터의 `type="submit"` 을 받지 못하므로, 저장 버튼에서 **`SForm` 의 ref `validate()`** 로 검증하고 실패하면 `focusFirstInvalid()` 로 첫 필드에 보낸다. 페이지의 카드 푸터(§4-11)는 `SForm` 이 카드를 감싸므로 submit 이 닿는다 — 이 차이를 섞지 않는다.
+- **`button` 은 눌러도 닫지 않는다.** 저장이 끝난 뒤에 모달은 `modalRef.ok()`, 드로어는 닫기 상태로 닫는다. 목록 갱신은 `SModal.create(...).onOk()` 에서 한다.
+- **푸터는 `md` 고정**이고 `footerLeft` 슬롯 버튼에도 `size="md"` 를 명시한다 (§3-5-2). 등록 모달의 취소는 `footerLeft`, 드로어의 삭제(한 건의 파괴 액션)는 `footerLeft` 에 `danger outline` 이다 (§3-5-3).
+- **닫기 경로는 기본값 그대로다.** `SActionModal`·`SDrawer` 는 입력을 담으므로 바깥 클릭·ESC 로 닫히지 않는 것이 기본이다 (§3-3-5) — `persistent` 를 주지 않는다.
+- **드로어는 본문 여백을 넣지 않는다** — 모달은 여백 토큰을 스스로 넣지만, 드로어는 회색 바탕(토큰)만 깔고 여백은 담는 쪽이 준다. 직접 만든 영역 규칙(§2-2)으로 준다. 흰 표·카드가 회색 바탕 위에 놓여 경계가 읽힌다.
+- **모달 높이는 주지 않는다** (§3-3-1) — 내용이 정하고 85% 에서 멈춘다. **그때 스크롤되는 것은 본문이 아니라 표다** — 본문 바로 아래 `flex h-full min-h-0 flex-col` 상자를 두고 표에 `min-h-0 flex-1` 을 준다. 그러면 단계형 모달의 2단계처럼 표가 길어져도 스텝퍼·안내·푸터는 제자리에 있고 표가 남은 높이를 채운다. 건너뛸 행 수처럼 표에 대한 한 줄 상태는 표 바로 위 `SContextAlert` 다 (§3-2-1).
+- **모달 안 단계형은 페이지 단계형(§4-11 가로형)과 같은 구성이다** — 본문 맨 위 가운데 스텝퍼, 이전은 `footerLeft`, 다음·실행은 `button`, 그만두기는 닫기(X). 단계마다 바뀌는 `button` 은 `SActionModalProps['button']` 으로 타입을 붙인다.
+- **드로어는 행 클릭(`onRowClick`)이 아니라 이름 셀의 링크로 연다** — 상품명·주문번호처럼 그 행을 가리키는 셀을 `STextLink` 로 그린다. 행 전체 클릭은 누를 수 있다는 신호가 없고 키보드로 닿지 않는다. 별도 "상세" 버튼 열은 폭만 먹으므로 두지 않는다. 드로어는 화면을 떠나지 않고 그 위에서 고치는 자리라 그 열의 표식은 `navigable` 이 아니라 **`editable`** 이다 (§3-4).
+- 링크가 여는 함수를 받아야 하므로 컬럼은 컴포넌트 안에서 `useMemo` 로 한 번만 만든다 — 렌더마다 새 배열을 넘기면 표가 열 상태를 다시 잡는다.
+- 행마다 드로어 폼을 `key` 로 새로 세운다 — 편집 값이 다른 행으로 새지 않는다.
+
+<!-- recipe:src/recipes/ProductOverlayPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
+```tsx
+import { useMemo, useRef, useState } from 'react';
+import {
+  SActionModal,
+  SButton,
+  SContextAlert,
+  SDrawer,
+  SForm,
+  SKeyValueTable,
+  SModal,
+  SRadioCardGroup,
+  SStepper,
+  STable,
+  STableBar,
+  STag,
+  STextLink,
+  type SActionModalProps,
+  type SFormHandle,
+  type SKeyValueField,
+  type SModalCreateComponentProps,
+  type STableColumn,
+} from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import {
+  CATEGORY_OPTIONS,
+  STATUS_OPTIONS,
+  commitUpload,
+  removeProducts,
+  saveProduct,
+  useProductList,
+  validateUpload,
+  type Product,
+  type UploadRow,
+} from './api';
+
+/** 상품명 셀이 드로어를 여는 트리거라 여는 함수를 받아 컬럼을 만든다 */
+const makeColumns = (open: (row: Product) => void): STableColumn<Product>[] => [
+  { name: 'id', label: 'ID', field: 'id', width: 80, align: 'center' },
+  // 무엇을 여는지 이름이 말하는 링크로 연다 — 행 전체 클릭은 누를 수 있다는 신호가 없고 키보드로 닿지 않는다.
+  // 드로어는 화면을 떠나지 않고 그 위에서 고치는 자리라 navigable 이 아니라 editable 표식이다 (§3-4)
+  {
+    name: 'name',
+    label: '상품명',
+    field: 'name',
+    width: 240,
+    editable: true,
+    render: row => (
+      <STextLink
+        label={row.name}
+        labelClassName="text-oceanblue-75"
+        underline
+        onClick={() => open(row)}
+      />
+    ),
+  },
+  {
+    name: 'price',
+    label: '판매가',
+    field: 'price',
+    width: 120,
+    align: 'right',
+    format: v => `${Number(v).toLocaleString()}원`,
+  },
+  {
+    name: 'status',
+    label: '상태',
+    field: 'status',
+    width: 100,
+    align: 'center',
+    contentType: 'control',
+    render: row =>
+      row.status === 'selling' ? (
+        <STag size="sm" color="green" label="판매중" />
+      ) : (
+        <STag size="sm" color="grey" label="판매중지" />
+      ),
+  },
+];
+
+/** 등록 모달·상세 드로어가 같이 쓰는 입력 표 */
+const productFields: SKeyValueField[][] = [
+  [
+    {
+      name: 'name',
+      label: '상품명',
+      type: 'input',
+      required: true,
+      options: { width: '100%', rules: [(v: unknown) => !!v || '상품명을 입력해 주세요'] },
+    },
+  ],
+  [
+    {
+      name: 'category',
+      label: '카테고리',
+      type: 'select',
+      required: true,
+      options: {
+        options: CATEGORY_OPTIONS,
+        valueAsPrimitive: true,
+        rules: [(v: unknown) => !!v || '카테고리를 골라 주세요'],
+      },
+    },
+  ],
+  [
+    {
+      name: 'price',
+      label: '판매가',
+      type: 'number-input',
+      options: { min: 0, inputSuffix: '원' },
+    },
+  ],
+  [{ name: 'status', label: '상태', type: 'radio', options: { options: STATUS_OPTIONS } }],
+];
+
+type Values = Record<string, unknown>;
+
+export default function ProductOverlayPage() {
+  const [page, setPage] = useState(1);
+  const { rows, total, lastPage } = useProductList({ page, rowsPerPage: 20 });
+  // 드로어는 선언형으로 연다 — 열린 행 하나를 페이지가 든다
+  const [opened, setOpened] = useState<Product | null>(null);
+  // 컬럼은 한 번만 만든다 — 렌더마다 새 배열을 넘기면 표가 열 상태를 다시 잡는다 (setOpened 는 바뀌지 않는다)
+  const columns = useMemo(() => makeColumns(setOpened), []);
+
+  // 모달은 명령형으로 띄운다 — SActionModal 을 루트로 하는 컴포넌트를 SModal.create 에 넘긴다 (§3-3-4)
+  const openCreate = () => SModal.create({ component: ProductCreateModal }).onOk(() => setPage(1));
+  const openUpload = () => SModal.create({ component: BulkUploadModal }).onOk(() => setPage(1));
+
+  return (
+    <AppShell header={{ variant: 'bar', title: '상품 관리' }} contentHeight="fill">
+      <div className="flex h-full min-h-0 flex-col gap-sd-12">
+        {/* 툴바+표 = 한 블록 (§2-0) */}
+        <div className="flex min-h-0 flex-1 flex-col">
+          <STableBar
+            className="border-b-0"
+            total={total}
+            rightActions={
+              <div className="flex items-center gap-sd-8">
+                <SButton
+                  size="sm"
+                  color="neutral"
+                  outline
+
+                  label="엑셀 일괄 등록"
+                  onClick={openUpload}
+                />
+                {/* 이 페이지의 유일한 primary 채움 (§3-5-1) */}
+                <SButton size="sm" label="상품 등록" onClick={openCreate} />
+              </div>
+            }
+          />
+          {/* 상품명을 누르면 목록을 떠나지 않고 옆에서 상세가 밀려 나온다 */}
+          <STable<Product>
+            className="min-h-0 flex-1"
+            columns={columns}
+            rows={rows}
+            rowKey="id"
+            pagination={{ page, rowsPerPage: 20, lastPage }}
+            onPageChange={setPage}
+          />
+        </div>
+      </div>
+
+      {/* key 로 행마다 폼을 새로 세운다 — 편집 값이 다른 행으로 새지 않는다 */}
+      {opened && <ProductDrawer key={opened.id} product={opened} onClose={() => setOpened(null)} />}
+    </AppShell>
+  );
+}
+
+/**
+ * 상세 드로어 — 목록을 보면서 한 건을 고친다.
+ * 레이어라 어디서 띄워도 레이아웃에 영향이 없다 (§2-0). 닫기 경로는 X 와 푸터뿐이다 — 입력을 담으므로
+ * 바깥 클릭·ESC 로 닫히지 않는 것이 기본이고 그대로 둔다 (§3-3-5)
+ */
+function ProductDrawer({ product, onClose }: { product: Product; onClose: () => void }) {
+  const [values, setValues] = useState<Values>(product);
+  // 푸터 버튼은 SForm 밖에서 그려진다 — submit 이 폼에 닿지 않으므로 ref 로 검증한다
+  const formRef = useRef<SFormHandle>(null);
+
+  const save = async () => {
+    if (!formRef.current?.validate()) return formRef.current?.focusFirstInvalid();
+    await saveProduct(values);
+    onClose();
+  };
+  const confirmRemove = () =>
+    SModal.confirm({
+      type: 'negative',
+      modalTitle: '상품을 삭제할까요?',
+      topMessage: ['삭제된 상품은 복구할 수 없습니다.'],
+      mainButtonLabel: '삭제',
+    }).onOk(async () => {
+      await removeProducts([product.id]);
+      onClose();
+    });
+
+  return (
+    <SDrawer
+      open
+      onOpenChange={next => !next && onClose()}
+      onClose={onClose}
+      title={product.name}
+      // 푸터는 md 고정 — footerLeft 슬롯 버튼에도 md 를 명시한다 (§3-5-2).
+      // 항목 하나의 삭제라 danger outline, 왼쪽 끝 (§3-5-3·§3-5-6)
+      footerLeft={<SButton color="danger" outline size="md" label="삭제" onClick={confirmRemove} />}
+      button={{ label: '저장', onClick: save }}
+    >
+      {/* 드로어는 모달과 달리 본문 여백을 넣지 않는다 — 회색 바탕(토큰)만 깔고 여백은 담는 쪽이 준다.
+          표 하나뿐이라 직접 만든 영역의 여백은 16 이다 (§2-2). 흰 표가 회색 바탕 위에 놓여 경계가 읽힌다 */}
+      <SForm ref={formRef} formClassName="p-sd-16">
+        <SKeyValueTable
+          fields={productFields}
+          values={values}
+          onChange={({ values }) => setValues(values)}
+        />
+      </SForm>
+    </SDrawer>
+  );
+}
+
+/** 등록 모달 — 짧은 폼. 높이는 내용이 정한다 (§3-3-1) */
+function ProductCreateModal({ open, onOpenChange, onClose, modalRef }: SModalCreateComponentProps) {
+  const [values, setValues] = useState<Values>({ status: 'selling' });
+  const formRef = useRef<SFormHandle>(null);
+
+  const save = async () => {
+    if (!formRef.current?.validate()) return formRef.current?.focusFirstInvalid();
+    await saveProduct(values);
+    modalRef.ok(); // 저장이 끝난 뒤에 닫는다 — button 은 눌러도 모달을 닫지 않는다
+  };
+
+  return (
+    <SActionModal
+      open={open}
+      onOpenChange={onOpenChange}
+      onClose={onClose}
+      modalTitle="상품 등록"
+      width={640}
+      height={400}
+      footerLeft={
+        <SButton color="neutral" outline size="md" label="취소" onClick={() => modalRef.cancel()} />
+      }
+      button={{ label: '등록', onClick: save }}
+    >
+      <SForm ref={formRef}>
+        <SKeyValueTable
+          fields={productFields}
+          values={values}
+          onChange={({ values }) => setValues(values)}
+        />
+      </SForm>
+    </SActionModal>
+  );
+}
+
+const UPLOAD_STEPS = [
+  { label: '파일 선택', value: 'file' },
+  { label: '검증 결과 확인', value: 'check' },
+];
+
+const MODE_OPTIONS = [
+  { value: 'create', label: '신규 등록', subtitle: '파일의 모든 행을 새 상품으로 등록합니다.' },
+  { value: 'update', label: '기존 상품 수정', subtitle: '상품코드가 같은 상품의 값을 덮어씁니다.' },
+];
+
+const fileFields: SKeyValueField[][] = [
+  [
+    {
+      name: 'file',
+      label: '엑셀 파일',
+      type: 'file-picker',
+      required: true,
+      options: {
+        accept: '.xlsx',
+        placeholder: '파일을 업로드 해주세요.',
+        rules: [(v: unknown) => !!v || '파일을 선택해 주세요'],
+      },
+    },
+  ],
+];
+
+const resultColumns: STableColumn<UploadRow>[] = [
+  { name: 'row', label: '행', field: 'row', width: 64, align: 'center' },
+  { name: 'name', label: '상품명', field: 'name', width: 200 },
+  {
+    name: 'result',
+    label: '결과',
+    field: 'error',
+    width: 200,
+    contentType: 'control',
+    render: row =>
+      row.error ? (
+        <STag size="sm" color="red" label={row.error} />
+      ) : (
+        <STag size="sm" color="green" label="정상" />
+      ),
+  },
+];
+
+/**
+ * 모달 안 단계형 — 페이지 단계형(§4-11 가로형)과 같은 구성이다.
+ * 스텝퍼는 본문 맨 위 가운데, 이전은 footerLeft, 다음·등록은 button. 그만두기는 모달의 닫기(X)
+ */
+function BulkUploadModal({ open, onOpenChange, onClose, modalRef }: SModalCreateComponentProps) {
+  const [step, setStep] = useState(0);
+  const [values, setValues] = useState<Values>({ mode: 'create' });
+  const [rows, setRows] = useState<UploadRow[]>([]);
+  const formRef = useRef<SFormHandle>(null);
+  const valid = rows.filter(r => !r.error).length;
+
+  const next = async () => {
+    if (!formRef.current?.validate()) return formRef.current?.focusFirstInvalid();
+    setRows(await validateUpload(values));
+    setStep(1);
+  };
+  const commit = async () => {
+    await commitUpload(rows);
+    modalRef.ok();
+  };
+
+  // 단계마다 바뀌는 버튼은 타입을 붙여 둔다 — 아이콘 이름이 string 으로 넓어지지 않게 (§4-11)
+  const button: SActionModalProps['button'] =
+    step === 0
+      ? { label: '다음', rightIcon: 'arrowRight', onClick: next }
+      : { label: `${valid.toLocaleString()}개 등록`, disabled: valid === 0, onClick: commit };
+
+  return (
+    <SActionModal
+      open={open}
+      onOpenChange={onOpenChange}
+      onClose={onClose}
+      modalTitle="엑셀 일괄 등록"
+      width={720}
+      height={600}
+      footerLeft={
+        <SButton
+          color="neutral"
+          outline
+          size="md"
+          label="이전"
+          icon="arrowLeft"
+          disabled={step === 0}
+          onClick={() => setStep(0)}
+        />
+      }
+      button={button}
+    >
+      <div className="flex h-full min-h-0 flex-col gap-sd-16">
+        <div className="flex justify-center">
+          <SStepper
+            items={UPLOAD_STEPS.map((s, i) => ({ ...s, completed: i < step }))}
+            value={UPLOAD_STEPS[step].value}
+          />
+        </div>
+        {step === 0 ? (
+          <SForm ref={formRef} formClassName="flex flex-col gap-sd-12">
+            <SRadioCardGroup
+              options={MODE_OPTIONS}
+              value={values.mode as string}
+              onValueChange={v => setValues({ ...values, mode: v })}
+            />
+            <SKeyValueTable
+              fields={fileFields}
+              values={values}
+              onChange={({ values }) => setValues(values)}
+            />
+          </SForm>
+        ) : (
+          <div className="flex min-h-0 flex-1 flex-col gap-sd-12">
+            {rows.length > valid && (
+              <SContextAlert
+                icon="notificationOutline"
+                iconColor="orange_65"
+                intent="warning"
+                messages={[
+                  `${(rows.length - valid).toLocaleString()}개의 행에 오류가 있어 건너뜁니다.`,
+                ]}
+              />
+            )}
+            <STable<UploadRow>
+              className="min-h-0 flex-1"
+              columns={resultColumns}
+              rows={rows}
+              rowKey="id"
+            />
+          </div>
+        )}
+      </div>
+    </SActionModal>
+  );
+}
+```
+<!-- /recipe -->
+
 ---
 
 ## 5. 자가 점검 체크리스트
@@ -3276,7 +5293,7 @@ export default function ExcelFilePopupPage() {
 - [ ] 스크롤 위치를 저장했다 되돌린다면 **행 번호**(`getFirstVisibleRow` → `scrollToRow`)로 했는가, `scrollTop` 픽셀을 저장하지는 않았는가 (§3-4 — 가상 스크롤에서는 좌표계가 실측으로 움직여 다른 행이 나온다)
 - [ ] `editable` · `navigable` 표식을 켠 열이 **셀에서도 실제로 그렇게 동작하는가** (입력 컨트롤 · 링크가 있는가), **모달로 처리하는 열에 `navigable` 을 켜지는 않았는가** (화면을 떠나지 않으므로 `editable` 이다), 표식을 붙인 열의 폭을 함께 넓혔는가 (§3-4)
 - [ ] 금액·수량 등 양을 나타내는 숫자에 빠짐없이 `toLocaleString()` 을 썼는가 (번호·코드는 제외)
-- [ ] 날짜를 `YYYY-MM-DD` 로 표기했는가 (`toLocaleDateString()` ❌, §1-4)
+- [ ] 날짜를 `YYYY-MM-DD` 로 표기했는가 (`toLocaleDateString()` ❌, §1-4) — 대화 말풍선 시각(`오후 5:52`)과 대화의 날짜 구분선(`2026년 10월 6일 화요일`)만 예외
 - [ ] 필드 폭을 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`)으로 줬는가 — px 직접 지정 ❌ (§4-3)
 - [ ] 조회 조건으로 쓰는 셀렉트·날짜·시간 피커에 `clearable` 을 줬는가, 그 상태가 `null` 을 담을 수 있는가 (§3-7-4 — 필수 입력 필드에는 켜지 않는다)
 - [ ] 서버에서 페이지 단위로 받는 `SSelect` 에 `onReachEnd` 와 `hasMore`·`loading`·`serverSearch` 를 함께 줬는가, 늦게 온 응답을 버리는 cleanup 이 있는가 (§3-7-2 — 렌더 최적화는 DS 가 알아서 한다)