sellmate-design-system-react 7.1.0 → 8.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/AGENTS.md +412 -18
  2. package/README.md +16 -1
  3. package/dist/components/SDraggableItem/README.md +1 -0
  4. package/dist/components/SDraggableItem/SDraggableItem.d.ts +3 -0
  5. package/dist/components/SDrawer/README.md +5 -4
  6. package/dist/components/SDrawer/SDrawer.d.ts +16 -5
  7. package/dist/components/SExpansionItem/README.md +1 -0
  8. package/dist/components/SExpansionItem/SExpansionItem.d.ts +3 -0
  9. package/dist/components/SGnb/README.md +7 -0
  10. package/dist/components/SGnb/SGnb.d.ts +27 -0
  11. package/dist/components/SGnb/gnb.config.d.ts +13 -0
  12. package/dist/components/SIcon/SIcon.d.ts +1 -1
  13. package/dist/components/SIcon/icons.gen.d.ts +8 -3
  14. package/dist/components/SLayout/SLayout.d.ts +6 -0
  15. package/dist/components/SListItem/README.md +1 -0
  16. package/dist/components/SListItem/SListItem.d.ts +3 -0
  17. package/dist/components/SModal/README.md +41 -6
  18. package/dist/components/SModal/SModalOutlet.d.ts +18 -0
  19. package/dist/components/SModal/index.d.ts +1 -0
  20. package/dist/components/SSplitter/README.md +27 -0
  21. package/dist/components/SSplitter/SSplitter.d.ts +32 -0
  22. package/dist/components/SSplitter/index.d.ts +2 -0
  23. package/dist/components/SSplitter/splitter.config.d.ts +15 -0
  24. package/dist/components/STooltip/README.md +2 -0
  25. package/dist/index.cjs +1034 -221
  26. package/dist/index.cjs.map +1 -1
  27. package/dist/index.d.ts +1 -0
  28. package/dist/index.js +1033 -223
  29. package/dist/index.js.map +1 -1
  30. package/dist/lib/autofill.d.ts +29 -0
  31. package/dist/lib/is-dev.d.ts +2 -0
  32. package/dist/lib/modal-outlet.d.ts +53 -0
  33. package/dist/llms-full.txt +502 -28
  34. package/dist/llms.txt +418 -20
  35. package/dist/styles.css +154 -17
  36. package/dist/theme.css +40 -10
  37. package/eslint/scale.gen.mjs +1 -1
  38. package/package.json +2 -1
package/dist/llms.txt CHANGED
@@ -31,22 +31,26 @@
31
31
 
32
32
  무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props 는 `dist/components/<이름>/README.md` 참조.
33
33
 
34
+ **이 표에서 어느 것을 골라야 할지 모르겠으면 §3-0 "의도 → 컴포넌트 라우팅" 으로 간다.** 하려는 일을 문장으로 찾으면 답이 하나 나온다 — 여기 인덱스는 "무엇이 있는지", §3-0 은 "언제 그걸 쓰는지" 를 담당한다.
35
+
34
36
  | 분류 | 컴포넌트 |
35
37
  | --- | --- |
36
38
  | **버튼·링크** | `SButton` `SGhostButton` `SDropdownButton` `STextLink` `SSwitch` `SToggle` |
37
- | **입력 (폼)** | `SForm` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioButton` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
39
+ | **입력 (폼)** | `SForm` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
38
40
  | **날짜·시간** | `SCalendar` `SDatePicker` `SDateRangePicker` `STimePicker` `STimeRangePicker` |
39
- | **표·목록** | `STable` `STableBar` `SKeyValueTable` `SList` `SListItem` `SDraggableItem` |
40
- | **레이아웃** | `SLayout` `SGnb` `SPage` `SSectionHeaderCard` `SCard` `SDivider` `SScrollArea` `SExpansionItem` |
41
+ | **표·목록** | `STable` `STableBar` `SKeyValueTable` `SList` `SListItem` `SExpansionList` `SDraggableList` `SDraggableItem` `STree` |
42
+ | **레이아웃** | `SLayout` `SGnb` `SPage` `SSectionHeaderCard` `SCard` `SDivider` `SSplitter` `SScrollArea` `SExpansionItem` |
41
43
  | **내비게이션** | `STabs` `SPagination` `SStepper` |
42
44
  | **표시·상태** | `STag` `SBadge` `SIcon` `SCallout` `SGuide` |
43
45
  | **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
44
- | **오버레이** | `STooltip` `SPopover` `SPopup` `SPortal` |
45
- | **모달** | `SModal.confirm()` `SModal.create()` + `SActionModal` `SConfirmModal` |
46
+ | **오버레이** | `STooltip` `SPopover` `SPopup` `SDrawer` `SPortal` |
47
+ | **모달** | `SModal.confirm()` `SModal.create()` + `SActionModal` `SConfirmModal` `SModalOutlet`(앱 루트 1회) |
46
48
  | **알림** | `SToast` `SToastContainer` |
47
49
 
48
50
  표에 없는 UI 를 만들어야 할 때만 `div` 로 직접 조립하고, 그때도 §1-2 · §2 의 토큰 규칙을 지킨다.
49
51
 
52
+ **이 표는 패키지가 실제로 export 하는 컴포넌트와 일치해야 한다** — `npm run check:routing` 이 강제한다. 표에 없는 컴포넌트는 소비 앱 입장에서 존재하지 않는 것과 같다.
53
+
50
54
  ### 0-2. 프로젝트 설정
51
55
 
52
56
  설정(Tailwind v4 `theme.css` import, `@source` 지정, Next.js 주의사항)은 패키지 [README.md](./README.md)를 따른다. 이 문서는 설정이 끝난 상태에서의 **화면 작성 규칙**만 다룬다.
@@ -131,7 +135,76 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
131
135
 
132
136
  ---
133
137
 
134
- ## 2. 조합 어휘컴포넌트 "사이"를 채울 때 쓰는 것들
138
+ ## 2. 조합 규칙화면을 어떻게 쌓는가
139
+
140
+ §3 이 "무엇을 쓸지" 라면 여기는 **"고른 것들을 어떻게 붙일지"** 다. 층 구조(§2-0)가 먼저고, 타이포·간격·색(§2-1~2-3)은 그 층에 붙는 값이다.
141
+
142
+ ### 2-0. 화면의 층 구조 — 무엇을 어디에 놓는가
143
+
144
+ **모든 화면은 다섯 층으로 쌓인다. 컴포넌트는 저마다 놓이는 층이 정해져 있고, 층이 다르면 붙이는 방법도 다르다.** 조합이 어색해지는 원인은 대개 층을 건너뛴 것이다 — 요소를 페이지에 바로 놓거나, 인라인 요소를 블록처럼 세우거나, 카드 안에 카드를 겹치는 식이다.
145
+
146
+ | 층 | 무엇인가 | 컴포넌트 |
147
+ | --- | --- | --- |
148
+ | **셸** | 앱 전체 뼈대. 페이지가 바뀌어도 남는다 | `SLayout` `SGnb` `SPage` |
149
+ | **블록** | `SPage` 의 직계 자식. 페이지를 세로로 쌓는 단위 | `SSectionHeaderCard` `SCard` `SForm` `SSplitter` `SScrollArea` `STable` `STableBar` `SKeyValueTable` `SList` `SExpansionList` `SDraggableList` `STree` `SCallout` `STabs` `SStepper` `SPagination` `SDivider` |
150
+ | **요소** | 블록 **안에** 놓이는 컨트롤. 혼자 페이지에 서지 않는다 | `SButton` `SGhostButton` `SDropdownButton` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioGroup` `SRadioButton` `SSwitch` `SToggle` `SChipInput` `SBarcodeInput` `SFilePicker` `SDatePicker` `SDateRangePicker` `STimePicker` `STimeRangePicker` `SCalendar` `SListItem` `SExpansionItem` `SDraggableItem` `SLinearProgress` `SCircleProgress` |
151
+ | **인라인** | 텍스트 흐름·셀·라벨 안에 섞인다. 혼자 블록이 되지 않는다 | `STag` `SBadge` `SIcon` `STextLink` `SChip` |
152
+ | **레이어** | 문서 흐름 **밖**에 떠서 그려진다. 어느 층에서 띄우든 레이아웃에 영향이 없다 | `SModal` `SActionModal` `SConfirmModal` `SPopup` `SDrawer` `SPopover` `STooltip` `SPortal` `SToast` `SLoadingModal` `SLoadingContainer` `SGuide` |
153
+
154
+ 여기에 화면을 차지하지 않는 **부트스트랩** 이 따로 있다 — `SModalOutlet` `SToastContainer` 는 앱 진입점에 한 번만 렌더한다 (§4-1).
155
+
156
+ > 이 표는 §0-1 인덱스 전체를 덮는다 (`npm run check:routing` 이 강제). **컴포넌트를 골랐으면 그것이 어느 층인지 먼저 확인하고, 아래 포함 규칙에 맞는 자리에 놓는다.**
157
+
158
+ #### 블록은 두 종류다
159
+
160
+ 같은 블록층이어도 **안에 다른 것을 담느냐** 로 갈린다. 이걸 구분해야 포함 규칙이 선다.
161
+
162
+ - **담는 블록** — `SSectionHeaderCard` `SCard` `SForm` `SSplitter` `SScrollArea`. 안이 비어 있고 다른 블록·요소를 받는다.
163
+ - **그리는 블록** — 나머지 전부. 자기가 내용을 그리므로 안에 무엇을 넣을지 고민할 일이 없다 (`STable` 의 셀처럼 지정된 슬롯 제외).
164
+
165
+ #### 포함 규칙 — 무엇 안에 무엇이 올 수 있나
166
+
167
+ | 담는 것 | 올 수 있는 것 | 오면 안 되는 것 |
168
+ | --- | --- | --- |
169
+ | `SPage` | **블록만** | **요소를 직접** — 버튼 하나도 블록에 담아 놓는다 |
170
+ | `SSectionHeaderCard.Body` | 그리는 블록 · 요소 | `SSectionHeaderCard` · `SCard` (카드 겹침, §3-7-8) |
171
+ | `SCard` | 그리는 블록 · 요소 | `SCard` · `SSectionHeaderCard` |
172
+ | `SForm` | 블록 (보통 `SKeyValueTable` + 하단 액션) | — |
173
+ | `SSplitter.Before` / `.After` | 블록 | — |
174
+ | `SScrollArea` | 블록 | — |
175
+ | `STable` 셀 (`render`) | 인라인 · 요소 | 블록 — 표 안에 표·카드를 넣지 않는다 |
176
+ | `SKeyValueTable` 값 셀 | 인라인 · 요소 | 블록 |
177
+ | `SListItem` | 인라인 | 블록 · 요소 |
178
+
179
+ - **블록을 `div` 로 감싸지 않는다.** 감싸면 페이지 스택에서 빠져나가 `gap-sd-12` 리듬이 끊긴다. 여러 블록을 묶어야 하면 그건 섹션이므로 `SSectionHeaderCard` 다.
180
+ - **요소를 페이지에 직접 놓지 않는다.** 하단 액션 버튼들처럼 블록이 없는 자리는 `div` 로 한 줄을 만들어 그 `div` 가 블록이 된다 (§4-3·§4-4).
181
+ - **레이어는 어디서 띄워도 된다.** `body` 로 portal 되므로 셸 안에 넣을 필요가 없고, 넣어도 레이아웃이 바뀌지 않는다 (§4-1).
182
+
183
+ #### 블록을 쌓는 방법과 순서
184
+
185
+ **`SPage` 는 자식을 자동으로 쌓지 않는다.** 페이지가 직접 세로 스택을 만든다 — 이게 모든 §4 레시피가 `flex flex-col gap-sd-12` 로 시작하는 이유다.
186
+
187
+ ```tsx
188
+ <SPage background="frame">
189
+ <div className="flex flex-col gap-sd-12"> {/* 블록 스택 — 페이지가 만든다 */}
190
+ …블록들…
191
+ </div>
192
+ </SPage>
193
+ ```
194
+
195
+ 블록 순서는 화면 종류와 무관하게 같다. **필요한 것만 남기되 순서를 바꾸지 않는다.**
196
+
197
+ ```text
198
+ 1. 페이지 제목 (+ 가이드·매뉴얼 링크. 액션 버튼은 오지 않는다 §4-2)
199
+ 2. 상시 안내 SCallout
200
+ 3. 필터 SKeyValueTable
201
+ 4. 툴바 STableBar (건수 요약 + 액션)
202
+ 5. 본문 STable · 섹션 카드들 · SList …
203
+ 6. 페이지네이션 SPagination (STable 이 pagination prop 으로 직접 그린다)
204
+ 7. 하단 액션 되돌리기 왼쪽 · 실행 오른쪽 (§4-3)
205
+ ```
206
+
207
+ 간격은 층마다 다르다 — 블록 ↔ 블록은 `gap-sd-12`, 요소 ↔ 요소는 `gap-sd-8` 이 기본이고, 같은 컴포넌트를 나열할 때는 컴포넌트별 그룹 간격이 따로 있다. 전부 §2-2 에 있다.
135
208
 
136
209
  ### 2-1. 타이포그래피 프리셋
137
210
 
@@ -146,15 +219,22 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
146
219
 
147
220
  **기본 선택 — 이 조합을 쓴다.** 이 서비스는 정보 밀도가 높아 본문이 12px 이다. 14px 를 본문 기본으로 쓰지 않는다.
148
221
 
149
- | 역할 | 클래스 | 크기 |
150
- | --- | --- | --- |
151
- | 페이지 헤더 제목 (h1) | `typo-heading-lg` | 18px |
152
- | 섹션 제목 | `typo-heading-sm` | 14px |
153
- | 본문 | `typo-body-sm-default` | 12px |
154
- | 보조 설명 | `typo-body-sm-default` + `text-fg-tertiary` | 12px / `grey_65` |
222
+ **제목 위계는 §2-0 층을 따라간다** — 층이 한 단 내려가면 제목도 한 단 내려간다. 층을 건너뛰지 않듯 제목도 건너뛰지 않는다.
223
+
224
+ | (§2-0) | 역할 | 클래스 | 크기 |
225
+ | --- | --- | --- | --- |
226
+ | | 페이지 제목 (h1) | `typo-heading-lg` | 18px |
227
+ | 블록 | 섹션 제목 | `typo-heading-sm` | 14px |
228
+ | 블록 내부 | 하위 제목 (섹션 안을 더 나눌 때) | `typo-heading-xs` | 12px |
229
+ | — | 본문 | `typo-body-sm-default` | 12px |
230
+ | — | 보조 설명 | `typo-body-sm-default` + `text-fg-tertiary` | 12px / `grey_65` |
155
231
 
156
232
  페이지 제목만 18px 로 크게 두고 그 아래는 14 / 12 로 촘촘하게 간다. 중간 크기(16px)는 기본 골격에서 쓰지 않는다.
157
233
 
234
+ - **섹션 제목의 타이포를 직접 주지 않는다.** `SSectionHeaderCard.Header` 가 `title` 에 이미 넣는다 — 그 위에 `typo-heading-sm` 을 또 씌우지 않는다. 직접 쓰는 경우는 섹션 카드 없이 제목만 세울 때뿐이다.
235
+ - **하위 제목이 필요하면 먼저 섹션을 나눌 수 없는지 본다.** 한 섹션 안에서 제목이 두 단으로 갈린다는 것은 대개 섹션이 둘이라는 뜻이다 (§3-7-8).
236
+ - 본문 안에서 한 단어를 강조할 때는 `typo-body-sm-medium` 을 쓴다. `typo-body-sm-bold` 는 제목 성격의 짧은 라벨에만 쓴다. <!-- TODO(디자인): 강조 굵기 기준 확정 -->
237
+
158
238
  **보조 설명의 색** — 기본은 `text-fg-tertiary`(`grey_65`) 다. 보조 설명 안에서 위계가 한 단계 더 필요할 때만 `text-fg-secondary`(`grey_80`) → `text-fg-tertiary`(`grey_65`) 순으로 내려 쓴다 (§2-3).
159
239
 
160
240
  ### 2-2. 간격 (spacing)
@@ -166,14 +246,14 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
166
246
  - 형제 요소 간격은 margin 대신 부모의 `flex`/`grid` + `gap-sd-*`으로 잡는다.
167
247
  - 시맨틱 간격 토큰 (텍스트 덩어리·요소 사이 기본 리듬):
168
248
 
169
- 화면은 세 층이다. **여백(padding)과 간격(gap)은 서로 다른 축이고, 규칙도 다르다.**
249
+ **여백(padding)과 간격(gap)은 서로 다른 축이고, 규칙도 다르다.** 어느 쪽이든 값은 §2-0 의 층이 정한다.
170
250
 
171
251
  ```text
172
- 페이지 프레임 SPage 가 여백을 넣는다. 직접 주지 않는다
173
- └ 블록 페이지 직계 자식 (헤더·필터·툴바·테이블·섹션 카드)
174
- 블록 블록 간격은 gap-sd-12
175
- └ 섹션·패널 블록 중 "안에 콘텐츠를 담는 컨테이너"인 것
252
+ (SPage) 여백을 SPage 가 넣는다. 직접 주지 않는다
253
+ └ 블록 블록 블록 간격은 gap-sd-12
254
+ └ 담는 블록 "안에 콘텐츠를 담는" 블록 (SSectionHeaderCard·SCard 등, §2-0)
176
255
  여기에만 안쪽 여백 선택지가 있다 (아래 "섹션·패널 안쪽 여백")
256
+ └ 요소 요소 ↔ 요소 간격은 gap-sd-8 이 기본
177
257
  ```
178
258
 
179
259
  | 상황 | 값 |
@@ -322,6 +402,124 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
322
402
 
323
403
  > ⚠️ 초안(개발 작성). <!-- TODO(디자인): 전체 검수·확정 --> 표시가 있는 행은 디자인 확정 전까지 초안 기준으로 사용.
324
404
 
405
+ ### 3-0. 의도 → 컴포넌트 라우팅 (여기서 시작한다)
406
+
407
+ **§3 의 입구는 이 표다.** 아래 §3-1 부터는 계열별로 정리돼 있어서 "내가 만들 게 어느 계열인지"를 이미 알아야 펼 수 있다. 그런데 실제 출발점은 계열이 아니라 **하려는 일**이다. 그 문장을 여기서 찾으면 답이 하나 나온다.
408
+
409
+ - **읽는 법**: 왼쪽에서 하려는 일을 찾고 → 가운데 컴포넌트를 쓴다. 오른쪽에 § 참조가 있으면 그 자리는 답이 갈리므로 **반드시 그 절을 읽고 고른다.** 참조가 없으면 더 볼 것 없이 그대로 쓴다.
410
+ - 이 표는 §0-1 인덱스 전체를 덮는다 (`npm run check:routing` 이 강제). **여기에 해당하는 일이 없으면 대응 컴포넌트가 없는 것이므로** §1-1 의 예외 규칙(순수 레이아웃 요소)으로 간다.
411
+
412
+ #### A. 값을 입력받는다
413
+
414
+ | 하려는 일 | 컴포넌트 | 갈림 |
415
+ | --- | --- | --- |
416
+ | 한 줄 텍스트를 받는다 | `SInput` | §3-7-1 |
417
+ | 여러 줄 텍스트를 받는다 | `STextarea` | §3-7-1 |
418
+ | 숫자(수량·금액)를 받는다 | `SNumberInput` | |
419
+ | 바코드를 스캔해 받는다 | `SBarcodeInput` | |
420
+ | 목록에서 하나 고르게 한다 | `SSelect` | §3-7-2 |
421
+ | 선택지를 항상 펼쳐 두고 하나 고르게 한다 | `SRadioGroup` | §3-7-2 |
422
+ | 버튼 모양으로 모드를 하나 고르게 한다 | `SRadioButton` | §3-7-2 |
423
+ | 라디오 하나를 표 셀 등에 직접 배치한다 | `SRadio` | §3-7-2 |
424
+ | 여러 개를 고르게 한다 / 동의를 받는다 | `SCheckbox` | §3-7-3 |
425
+ | 켜는 즉시 반영되는 설정을 준다 | `SSwitch` | §3-7-3 |
426
+ | 목록을 좁히는 필터를 켜고 끄게 한다 | `SToggle` | §3-7-3 |
427
+ | 자유 입력값을 여러 개 쌓게 한다 | `SChipInput` | §3-1 |
428
+ | 입력된 값 하나를 지우거나 고치게 한다 | `SChip` | §3-1 |
429
+ | 파일을 받는다 | `SFilePicker` | |
430
+ | 날짜 하나를 받는다 | `SDatePicker` | §3-7-4 |
431
+ | 날짜 기간을 받는다 | `SDateRangePicker` | §3-7-4 |
432
+ | 시각 하나를 받는다 | `STimePicker` | |
433
+ | 시각 범위를 받는다 | `STimeRangePicker` | |
434
+ | 달력 자체를 화면에 펼쳐 보여준다 | `SCalendar` | §3-7-4 |
435
+ | 컨트롤에 라벨·필수·에러를 붙인다 | `SField` | §3-7-5 |
436
+ | 입력 여러 개를 묶어 한 번에 검증한다 | `SForm` | §4-3 |
437
+ | 폼·필터를 표 형태로 배치한다 | `SKeyValueTable` | §4 |
438
+
439
+ #### B. 정보를 읽게 보여준다
440
+
441
+ | 하려는 일 | 컴포넌트 | 갈림 |
442
+ | --- | --- | --- |
443
+ | 여러 건을 여러 열로 보여주고 열끼리 비교하게 한다 | `STable` | §3-7-6 |
444
+ | 항목 하나의 속성들을 `라벨: 값` 으로 보여준다 | `SKeyValueTable` | §4-4 |
445
+ | 한 줄로 읽히는 항목을 세로로 나열한다 | `SList` + `SListItem` | §3-7-6 |
446
+ | 나열한 항목을 펼쳐 하위 내용을 보여준다 | `SExpansionList` + `SExpansionItem` | §3-7-7 |
447
+ | 부모-자식 계층을 들여쓰기로 보여준다 | `STree` | §3-7-7 |
448
+ | 사용자가 순서를 드래그로 바꾸게 한다 | `SDraggableList` + `SDraggableItem` | §3-7-6 |
449
+ | 표 위에 건수 요약과 액션을 얹는다 | `STableBar` | §4-2 |
450
+ | 상태·분류를 라벨로 찍는다 | `STag` | §3-1 |
451
+ | 색 점만으로 상태를 찍는다 | `SBadge` | §3-1 |
452
+ | 아이콘을 넣는다 | `SIcon` | |
453
+ | 문장 안에서 다른 화면으로 보낸다 | `STextLink` | §3-5-6 |
454
+
455
+ #### C. 동작을 실행시킨다
456
+
457
+ | 하려는 일 | 컴포넌트 | 갈림 |
458
+ | --- | --- | --- |
459
+ | 라벨이 있는 일반 액션을 준다 | `SButton` | §3-5 |
460
+ | 아이콘 하나로 뜻이 통하는 부가 조작을 준다 | `SGhostButton` | §3-5-5 |
461
+ | 한 버튼에 여러 선택지를 매단다 | `SDropdownButton` | §3-5-4 |
462
+
463
+ #### D. 화면을 담고 나눈다
464
+
465
+ | 하려는 일 | 컴포넌트 | 갈림 |
466
+ | --- | --- | --- |
467
+ | 앱 셸(상단바 + 내비 + 본문)을 세운다 | `SLayout` | §4-1 |
468
+ | 좌측 내비게이션을 만든다 | `SGnb` | §4-1 |
469
+ | 페이지 본문을 담는다 (패딩·스크롤) | `SPage` | §4-1 |
470
+ | 제목 있는 섹션으로 묶는다 | `SSectionHeaderCard` | §3-7-8 |
471
+ | 제목 없이 흰 면으로만 묶는다 | `SCard` | §3-7-8 |
472
+ | 가로선으로 끊는다 | `SDivider` | §3-6 |
473
+ | 사용자가 영역 크기를 조절하게 한다 | `SSplitter` | §3-6 |
474
+ | 특정 영역 안에서만 스크롤시킨다 | `SScrollArea` | |
475
+
476
+ #### E. 다른 곳으로 이동시킨다
477
+
478
+ | 하려는 일 | 컴포넌트 | 갈림 |
479
+ | --- | --- | --- |
480
+ | 같은 화면에서 보는 관점을 바꾼다 | `STabs` | §3-7-2 |
481
+ | 긴 목록을 페이지로 끊는다 | `SPagination` | §4-2 |
482
+ | 여러 단계의 진행 위치를 보여준다 | `SStepper` | |
483
+
484
+ #### F. 흐름을 끊고 띄운다
485
+
486
+ > 이 그룹은 **전부 §3-3-1 판별 순서를 먼저 밟는다.** 아래는 그 결과를 되짚는 표다.
487
+
488
+ | 하려는 일 | 컴포넌트 | 갈림 |
489
+ | --- | --- | --- |
490
+ | 실행 여부만 확정받는다 | `SModal.confirm()` | §3-3-1 |
491
+ | 모달 안에서 작성·선택하게 한다 | `SActionModal` + `SModal.create()` | §3-3-1 |
492
+ | 띄우는 것 자체가 하나의 화면이다 | `SPopup` | §3-3-1 |
493
+ | 화면 옆에서 밀려 나오는 작업 패널을 연다 | `SDrawer` | §3-3-5 |
494
+ | 확인 다이얼로그를 화면에 직접 배치한다 | `SConfirmModal` | §3-3-4 |
495
+ | 클릭하면 상호작용 가능한 작은 콘텐츠를 띄운다 | `SPopover` | §3-3 |
496
+ | hover 하면 짧은 설명을 띄운다 | `STooltip` | §3-3 |
497
+ | 임의 요소에 붙는 저수준 레이어가 필요하다 | `SPortal` | §3-7-10 |
498
+
499
+ #### G. 알리고 안내한다
500
+
501
+ | 하려는 일 | 컴포넌트 | 갈림 |
502
+ | --- | --- | --- |
503
+ | 화면에 상시 노출되는 안내·경고를 둔다 | `SCallout` | §3-2 |
504
+ | 작업 결과를 일시적으로 알린다 | `SToast` | §3-2 |
505
+ | 기능 온보딩·도움말을 붙인다 | `SGuide` | §3-2 |
506
+
507
+ #### H. 기다리게 한다
508
+
509
+ | 하려는 일 | 컴포넌트 | 갈림 |
510
+ | --- | --- | --- |
511
+ | 화면 전체를 잠그고 기다리게 한다 | `SLoadingModal` (또는 `SModal.loading()`) | §3-2 |
512
+ | 특정 영역만 덮고 기다리게 한다 | `SLoadingContainer` | §3-2 |
513
+ | 진행률을 가로 막대로 보여준다 | `SLinearProgress` | §3-7-9 |
514
+ | 진행률·대기를 원형으로 보여준다 | `SCircleProgress` | §3-7-9 |
515
+
516
+ #### I. 앱을 켤 때 한 번만 (§4-1)
517
+
518
+ | 하려는 일 | 컴포넌트 | 갈림 |
519
+ | --- | --- | --- |
520
+ | `SModal.*` 로 띄운 모달이 그려질 자리를 만든다 | `SModalOutlet` | §4-1 |
521
+ | `SToast` 가 그려질 자리를 만든다 | `SToastContainer` | §4-1 |
522
+
325
523
  ### 3-1. 라벨/표시류 — STag vs SBadge vs SChip
326
524
 
327
525
  | 상황 | 사용 |
@@ -461,7 +659,7 @@ function OrderModal({ orderId, open, onOpenChange, onClose, modalRef }: OrderMod
461
659
  width={720}
462
660
  // 주 액션은 button(단수), 보조 버튼은 footerLeft — 하단 버튼 양끝 분리 규칙과 같다
463
661
  button={{ label: '접수', onClick: () => modalRef.ok() }}
464
- footerLeft={<SButton color="neutral" outline label="취소" onClick={() => modalRef.cancel()} />}
662
+ footerLeft={<SButton color="neutral" outline size="md" label="취소" onClick={() => modalRef.cancel()} />}
465
663
  >
466
664
  <SKeyValueTable fields={orderFields} values={order} />
467
665
  </SActionModal>
@@ -474,6 +672,10 @@ SModal.create({ component: OrderModal, componentProps: { orderId } })
474
672
  .onDismissed(() => {});
475
673
  ```
476
674
 
675
+ **하단 버튼을 본문(children)에 직접 두지 않는다.** 주 액션은 `button`, 보조 버튼은 `footerLeft` 로 넘긴다 — 푸터 배경·여백·양끝 분리가 컴포넌트 규칙대로 잡히는 자리다. `button` 은 클릭해도 **모달을 닫지 않으므로**(`onClick` 만 발화) 저장 API 응답을 보고 `modalRef.ok()` 로 닫으면 되고, 그 때문에 본문에 버튼을 따로 둘 이유가 없다. `footerLeft` 는 슬롯이라 `SButton` 을 직접 배치하며 `size="md"` 를 명시한다(§3-5-2).
676
+
677
+ **모달 안에서도 앱의 훅을 그냥 쓴다 — 단, 앱 루트에 `SModalOutlet` 이 있어야 한다 (§4-1).** outlet 이 있으면 명령형 모달이 앱 렌더 트리의 자식으로 그려지므로 `useQuery`·`useNavigate`·`useTheme` 같은 Context 기반 훅이 페이지에서와 똑같이 동작한다. **모달 컴포넌트를 Provider 로 다시 감싸지 않는다.** outlet 없이 띄우면 모달이 별도 React 루트로 떠서 Provider 가 하나도 닿지 않고, `No QueryClient set` 처럼 모달을 여는 순간에만 터진다.
678
+
477
679
  #### 3-3-5. 닫기 경로 — `persistent` 기본값은 컴포넌트마다 다르다
478
680
 
479
681
  **입력을 담는 모달은 백드롭 클릭·ESC 로 닫히지 않는 것이 기본**이다. 닫기 시도는 흔들림(shake)으로만 반응한다. 작성 중인 내용을 실수로 잃지 않게 하기 위한 것이다. 반면 `SConfirmModal` 은 잃을 입력이 없으므로 **백드롭·ESC 로 닫히는 것이 기본**이다.
@@ -724,12 +926,156 @@ const columns: STableColumn[] = [
724
926
  </div>
725
927
  ```
726
928
 
929
+ ### 3-6. 영역 나누기 — SDivider vs SSplitter
930
+
931
+ | 상황 | 사용 |
932
+ | --- | --- |
933
+ | 두 영역 사이에 **선만** 그을 때 | `SDivider` — 위치·두께가 고정된 구분선이다 |
934
+ | 사용자가 **경계를 끌어 넓이를 바꿀 수 있어야** 할 때 | `SSplitter` — 두 패널을 감싸고 경계 위치를 소유한다 |
935
+
936
+ `SSplitter` 의 구분선은 평소 자리만 잡고 칠해지지 않다가, 경계에 커서를 올리거나 포커스를 주면 그때 드러난다 — 조절 가능한 자리라는 신호다. **항상 보이는 선이 필요하면 `SDivider` 를 쓴다.** 선 색·두께·주변 여백은 토큰이 정하므로 직접 주지 않는다.
937
+
938
+ ```tsx
939
+ <SSplitter defaultValue={30} limits={[20, 60]}>
940
+ <SSplitter.Before>내비게이션</SSplitter.Before>
941
+ <SSplitter.After>본문</SSplitter.After>
942
+ </SSplitter>
943
+ ```
944
+
945
+ - 자식은 `SSplitter.Before` 와 `SSplitter.After` **둘뿐**이고, 루트의 직접 자식이어야 한다.
946
+ - 크기 단위는 `unit` 이 정한다. 기본 `'%'` 는 창이 바뀌어도 비율을 유지하고, `'px'` 는 폭을 유지한다. **사이드바처럼 폭이 고정돼야 하는 자리는 `'px'`**, 화면을 비율로 나누는 자리는 기본값 그대로 둔다.
947
+ - 본문이 읽을 수 없을 만큼 좁아지지 않도록 `limits={[최소, 최대]}` 를 준다. 생략하면 `'%'` 는 `[10, 90]`, `'px'` 는 `[50, Infinity]`.
948
+ - 각 패널은 넘치는 만큼 **스스로 스크롤한다.** 패널 안에 `SScrollArea` 를 겹쳐 넣지 않는다.
949
+ - 모델은 항상 **첫 패널**(`SSplitter.Before`) 크기다. 사이드가 기준인 화면이면 사이드를 `Before` 에 둔다.
950
+ - 앱 셸의 GNB 폭은 `SGnb` 가 소유한다. `SLayout`/`SGnb` 를 `SSplitter` 로 감싸지 않는다 — **GNB 폭을 끌 수 있게 하려면 `SGnb` 에 `resizable` 을 준다**(§4-1).
951
+
952
+ **Quasar `q-splitter` 에서 옮겨올 때** — `unit` · `limits` · `emitImmediately` 는 이름과 뜻이 같고, 나머지는 아래처럼 바뀐다. `emitImmediately` 를 주지 않으면 **드래그를 놓는 순간 한 번만** `onValueChange` 가 온다.
953
+
954
+ | q-splitter | SSplitter |
955
+ | --- | --- |
956
+ | `horizontal` (상/하 분할) | **`vertical`** — 이 저장소는 `STabs`·`SStepper` 와 같이 "세로 **배치**" 로 읽는다 |
957
+ | `v-model` | `value` + `onValueChange` (또는 `defaultValue`) |
958
+ | `disable` | `disabled` |
959
+ | `before` / `after` 슬롯 | `SSplitter.Before` / `SSplitter.After` |
960
+ | `before-class` / `after-class` | 각 슬롯에 `className` 을 직접 |
961
+ | `separator-class` / `separator-style` | `dividerClassName` / `dividerStyle` |
962
+ | `reverse` · `dark` | 없음 — 모델은 항상 첫 패널 크기다 |
963
+
964
+ ### 3-7. 나머지 판별 — 입력·목록·컨테이너
965
+
966
+ > §3-0 라우팅에서 이 절을 가리키는 자리들이다. <!-- TODO(디자인): 전체 검수·확정 -->
967
+
968
+ #### 3-7-1. SInput vs STextarea
969
+
970
+ **줄 수가 아니라 값의 성격으로 고른다.** 값의 길이를 미리 알 수 있으면 `SInput`, 없으면 `STextarea` 다.
971
+
972
+ | 값 | 사용 |
973
+ | --- | --- |
974
+ | 이름·코드·전화번호·URL 처럼 형식이 정해진 값 | `SInput` |
975
+ | 메모·사유·설명처럼 길이가 예측되지 않는 문장 | `STextarea` |
976
+
977
+ 값이 길어질 수 있는데 `SInput` 을 쓰면 사용자가 자기가 쓴 것을 다시 읽지 못한다 — 한 줄 안에서 좌우로 스크롤해야 하기 때문이다. 반대로 짧은 값에 `STextarea` 를 쓰면 빈 공간이 남아 입력량을 잘못 기대하게 한다.
978
+
979
+ #### 3-7-2. 하나를 고르게 하는 다섯 — SSelect vs SRadioGroup vs SRadioButton vs STabs vs SRadio
980
+
981
+ **먼저 "고르면 무엇이 바뀌는가"를 본다.**
982
+
983
+ 1. **화면의 내용이 통째로 바뀐다** → `STabs`. 값을 고르는 게 아니라 보는 관점을 바꾸는 것이다. 폼 값이 아니다.
984
+ 2. 그 밖에는 폼 값이므로 **선택지 수와 노출 여부**로 고른다.
985
+
986
+ | 선택지 | 사용 |
987
+ | --- | --- |
988
+ | 6개 이상, 또는 서버에서 오는 동적 목록 | `SSelect` |
989
+ | 2~5개 고정 + 선택지를 항상 보여야 함 | `SRadioGroup` |
990
+ | 2~4개 + 짧은 라벨의 배타적 모드 전환 (세그먼트) | `SRadioButton` |
991
+
992
+ - **`SRadio` 를 직접 나열하지 않는다.** 그룹 간격은 `SRadioGroup` 이 맞춘다 (§2-2). `SRadio` 단독은 `SRadioGroup` 이 만들 수 없는 배치 — 표 셀 안에 행마다 하나씩 놓는 경우 — 에만 쓴다.
993
+ - `SRadioButton` 은 `options` 를 통째로 받는 세그먼트 컨트롤이라 `SRadio` 를 여러 개 넣는 게 아니다.
994
+
995
+ #### 3-7-3. 켜고 끄는 셋 — SCheckbox vs SSwitch vs SToggle
996
+
997
+ 셋 다 on/off 지만 **값이 언제 반영되는지**가 다르다. 이걸 틀리면 사용자가 저장 버튼을 찾다가 못 찾거나, 눌렀는데 반영이 안 돼 다시 누른다.
998
+
999
+ | 판별 | 사용 |
1000
+ | --- | --- |
1001
+ | **폼 값으로 제출된다** (저장 버튼을 눌러야 반영) | `SCheckbox` |
1002
+ | **누르는 즉시 반영된다** (저장 버튼 없음) | `SSwitch` |
1003
+ | **목록을 좁히는 필터** (여러 개를 나란히 켜고 끔) | `SToggle` |
1004
+
1005
+ - `SCheckbox` 만 다중 선택(배열)과 `indeterminate`(부분 선택)를 갖는다. 전체 선택 체크박스는 반드시 `SCheckbox` 다.
1006
+ - 약관 동의처럼 **제출 시점에 값이 필요한 것은 항상 `SCheckbox`** 다 — 모양이 스위치에 가까워 보여도 그렇다.
1007
+ - `SToggle` 은 알약형 버튼이라 여러 개를 가로로 늘어놓는 필터 자리에 맞는다. 설정 화면의 on/off 한 줄에는 쓰지 않는다.
1008
+
1009
+ #### 3-7-4. 날짜 셋 — SDatePicker vs SDateRangePicker vs SCalendar
1010
+
1011
+ | 판별 | 사용 |
1012
+ | --- | --- |
1013
+ | 날짜 **하나**를 값으로 받는다 | `SDatePicker` |
1014
+ | **시작~종료** 를 값으로 받는다 | `SDateRangePicker` |
1015
+ | 달력 격자 **자체가 화면 콘텐츠** 다 (일정·이벤트 보기) | `SCalendar` |
1016
+
1017
+ - **기간을 `SDatePicker` 두 개로 만들지 않는다.** 시작이 종료보다 뒤인 입력을 막는 검증과 한쪽만 고른 중간 상태 처리가 `SDateRangePicker` 안에 이미 있다. 두 개로 쪼개면 그게 전부 앱 몫이 된다.
1018
+ - `SDatePicker`·`SDateRangePicker` 는 내부적으로 `SCalendar` 를 팝오버로 띄운다. 값을 받는 자리에 `SCalendar` 를 직접 쓰지 않는다.
1019
+
1020
+ #### 3-7-5. SField 를 직접 쓰는 경우
1021
+
1022
+ **거의 없다.** `SInput`·`SNumberInput`·`STextarea`·`SSelect`·날짜/시간 피커는 이미 내부에서 `SField` 를 쓰고 있어서 `label`·`required`·에러 표시를 자기 prop 으로 받는다. 그 위에 `SField` 를 한 겹 더 감싸면 라벨이 두 번 나온다.
1023
+
1024
+ 직접 쓰는 경우는 하나뿐이다 — **디자인 시스템에 없는 컨트롤**에 다른 필드와 똑같은 라벨·필수·에러 모양을 붙일 때.
1025
+
1026
+ #### 3-7-6. 여러 건을 나열하는 셋 — STable vs SList vs SDraggableList
1027
+
1028
+ | 판별 | 사용 |
1029
+ | --- | --- |
1030
+ | 열이 둘 이상이고 **열끼리 값을 비교**한다 (정렬·합계·자릿수 맞춤) | `STable` |
1031
+ | 한 항목이 **한 줄로 읽힌다** (제목 + 보조 텍스트) | `SList` + `SListItem` |
1032
+ | **순서 자체가 데이터**라 사용자가 끌어서 바꾼다 | `SDraggableList` + `SDraggableItem` |
1033
+
1034
+ - **항목 하나의 속성을 나열하는 것은 목록이 아니다.** `라벨: 값` 이 세로로 쌓이는 것은 `SKeyValueTable` 이다 (§4-4).
1035
+ - `SList` 는 레이아웃만 담당한다. 펼침·단일 선택 동작이 필요하면 `SExpansionList` 다 (§3-7-7).
1036
+
1037
+ #### 3-7-7. 펼치는 셋 — SExpansionItem vs SExpansionList vs STree
1038
+
1039
+ | 판별 | 사용 |
1040
+ | --- | --- |
1041
+ | 항목들이 **서로 독립적으로** 여닫힌다 (여러 개 동시에 열려도 됨) | `SExpansionItem` 단독 |
1042
+ | **한 번에 하나만** 열려야 한다 (아코디언) | `SExpansionList` + `SExpansionItem` |
1043
+ | **부모-자식 계층 자체**를 보여줘야 한다 (2단 이상, 연결선) | `STree` |
1044
+
1045
+ `SExpansionList` 는 depth 별 단일 확장·선택을 관리하는 wrapper 다. 직접 `useState` 로 "열린 항목 하나"를 들고 있지 않는다.
1046
+
1047
+ #### 3-7-8. SCard vs SSectionHeaderCard
1048
+
1049
+ | 판별 | 사용 |
1050
+ | --- | --- |
1051
+ | **제목이 붙는 섹션** 이다 | `SSectionHeaderCard` |
1052
+ | 제목 없이 **흰 면만** 필요하다 (요약 타일, 빈 상태 박스) | `SCard` |
1053
+
1054
+ - 페이지 골격에서 콘텐츠를 묶는 섹션은 **사실상 전부 `SSectionHeaderCard`** 다 (§4-4·§4-5). 제목·필수 표시·도움말·헤더 우측 액션이 전부 여기 붙는다.
1055
+ - **카드 안에 카드를 겹치지 않는다.** 섹션 안을 더 나눠야 하면 `SDivider` 로 끊거나(§3-6) 섹션을 둘로 분리한다.
1056
+ - 안쪽 여백은 `SSectionHeaderCard.Body` 의 `padding` prop 으로 준다 — `p-sd-*` 를 직접 주지 않는다 (§2-2).
1057
+
1058
+ #### 3-7-9. SLinearProgress vs SCircleProgress
1059
+
1060
+ | 판별 | 사용 |
1061
+ | --- | --- |
1062
+ | 진행률(%)이 있고 가로로 길게 놓을 자리가 있다 | `SLinearProgress` |
1063
+ | 자리가 좁다, 또는 **끝나는 시점을 모른다**(대기) | `SCircleProgress` |
1064
+
1065
+ `SCircleProgress` 는 `indeterminate` 로 두면 스피너가 된다. **다만 화면이나 영역을 막아야 하는 상황이면 progress 가 아니라 `SLoadingModal`·`SLoadingContainer` 다** (§3-2) — 진행 표시와 입력 차단은 다른 일이고, 막지 않으면 사용자가 로딩 중에 또 누른다.
1066
+
1067
+ #### 3-7-10. SPortal — 직접 쓸 일이 거의 없다
1068
+
1069
+ `STooltip`·`SPopover`·`SSelect`·날짜 피커가 내부에서 쓰는 저수준 레이어다. 앵커에 붙여 띄우는 동작이 필요하면 **먼저 §3-3 에서 대응 컴포넌트를 찾는다.** `SPortal` 을 직접 쓰는 것은 그 넷 중 어느 것도 아닌 새로운 부착형 레이어를 만들 때뿐이고, 그때도 모달 안에서 열릴 수 있다면 소속 컨테이너를 맞춰야 한다.
1070
+
727
1071
  ---
728
1072
 
729
1073
  ## 4. 페이지 레시피 — 표준 골격
730
1074
 
731
1075
  > 새 페이지는 반드시 아래 골격에서 시작한다. 임의 골격을 발명하지 않는다.
732
1076
  >
1077
+ > **아래 레시피는 §2-0 조합 문법으로 유도된 결과다.** 여기 없는 화면(대시보드·설정·마법사 등)을 만들 때는 임의로 짜지 말고 §2-0 의 층 구조·포함 규칙·블록 순서로 직접 유도한다.
1078
+ >
733
1079
  > **핵심 원칙 — 표 형태의 정보는 `SKeyValueTable` 로 만든다.** 필터·등록/수정 폼·상세 정보가 모두 여기 해당한다.
734
1080
  > `SField` 컨트롤을 `div` 로 직접 나열해 폼을 만들지 않는다.
735
1081
 
@@ -759,6 +1105,30 @@ export default function AppShell({
759
1105
  }
760
1106
  ```
761
1107
 
1108
+ **GNB 폭을 사용자가 조절하게 하려면 `SGnb` 에 `resizable` 을 준다.** 메뉴 오른쪽 경계가 조절선이 되고, 레일 폭은 고정된 채 메뉴 컬럼만 늘고 준다. 범위는 컴포넌트가 정하므로 숫자를 직접 주지 않는다.
1109
+
1110
+ ```tsx
1111
+ {/* 폭을 기억해야 하면 menuWidth 를 앱이 쥐고 onMenuWidthChange 로 되받아 저장한다.
1112
+ 초기값만 정하면 되면 defaultMenuWidth 하나로 끝난다. */}
1113
+ <SGnb items={MENU} value={current} onValueChange={navigate} resizable defaultMenuWidth={240} />
1114
+ ```
1115
+
1116
+ `onMenuWidthChange` 는 **드래그를 놓는 순간**(또는 방향키 조작) 한 번만 온다 — 저장 로직을 그대로 붙여도 프레임마다 쓰이지 않는다. 접혀 있거나 레일 리프가 활성이라 깔 메뉴가 없으면 조절선은 나오지 않는다.
1117
+
1118
+ **앱 부트스트랩에는 `<SModalOutlet />` 을 한 번 렌더한다 — Provider 안쪽에 둔다.**
1119
+
1120
+ ```tsx
1121
+ import { SModalOutlet } from 'sellmate-design-system-react';
1122
+
1123
+ // 앱 진입점 (main.tsx / App.tsx) — 앱 전체에 하나. 위치는 Provider 안쪽이기만 하면 된다
1124
+ <QueryClientProvider client={queryClient}>
1125
+ <RouterProvider router={router} />
1126
+ <SModalOutlet />
1127
+ </QueryClientProvider>;
1128
+ ```
1129
+
1130
+ `SModal.confirm/loading/create` 로 띄운 모달이 그려지는 자리다. outlet 이 앱 트리 안에 있어야 모달이 앱의 Context(QueryClient·Router·Theme 등)를 상속한다 — outlet 이 없으면 모달은 뜨지만 별도 React 루트라 Provider 가 닿지 않는다(§3-3-4). 모달은 언제나 `body` 로 portal 되므로 outlet 을 어디에 두든 레이아웃에는 영향이 없고, **셸 안에 넣을 필요도 없다.** 토스트를 쓴다면 `SToastContainer` 도 같은 자리에 둔다.
1131
+
762
1132
  **최소 너비는 `SLayout` 이 보장한다 — 앱이 `min-w-*` 를 직접 주지 않는다.** 창이 최소 너비(`SLAYOUT_MIN_WIDTH`, GNB 포함한 전체 기준)보다 좁아지면 GNB·상단바는 제자리에 남고 **`SPage` 안에만 가로 스크롤이 생긴다.** 문서(브라우저 창)에는 가로 스크롤이 생기지 않는다. 그래서 셸을 감싸는 요소에 `min-width` 나 `overflow-x` 를 걸지 않는다 — 걸면 창 전체가 스크롤되어 GNB 가 화면 밖으로 밀린다.
763
1133
 
764
1134
  **셸의 `SPage` 는 모든 페이지가 공유하므로, 스크롤 끝 여백을 끄려면 페이지가 셸에 알려야 한다.** 위처럼 프레임 컴포넌트가 `scrollEndSpacing` 을 받아 그대로 넘기고, 페이지네이션이 있는 목록 페이지만 `false` 를 준다 (§4-2). 나머지 페이지는 넘기지 않으면 기본값(켬)이 적용된다.
@@ -792,6 +1162,22 @@ export default function AppShell({
792
1162
  </SLayout>
793
1163
  ```
794
1164
 
1165
+ **메뉴 목록과 함께 스크롤되면 안 되는 것은 `SGnb` 의 위아래 고정 슬롯에 둔다.** 레일과 메뉴에 각각 위(`railTop`·`menuTop`)와 아래(`railFooter`·`menuFooter`) 슬롯이 있다. 아이템이 많아 넘치면 **목록만 스크롤되고 이 슬롯들은 제자리에 남는다** — 메뉴 검색, 워크스페이스 전환, 계정 행처럼 항상 보여야 하는 것이 여기 온다. 레일 슬롯은 `useRail` 일 때만, 메뉴 슬롯은 깔 메뉴가 있을 때만 렌더된다.
1166
+
1167
+ **접으면 레일·메뉴가 통째로 빠져나가면서 그 슬롯들도 함께 사라진다.** 접힌 상태에서도 남겨야 할 것은 `foldedTop`·`foldedFooter` 로 따로 준다 — `header="fix"` 로 접혔을 때만 나타나며, 폭이 좁은 폴드 레일이므로 아이콘 버튼 하나 정도로 줄인다.
1168
+
1169
+ ```tsx
1170
+ {/* 접히면 menuTop·menuFooter 가 함께 빠지므로, 폴드 레일에 남길 것만 foldedTop 으로 따로 준다 */}
1171
+ <SGnb
1172
+ items={MENU} value={current} onValueChange={navigate} useRail
1173
+ menuTop={<SInput value={keyword} onValueChange={setKeyword} placeholder="메뉴 검색" />}
1174
+ menuFooter={<AccountRow />}
1175
+ foldedTop={<SGhostButton icon="search" size="sm" ariaLabel="메뉴 검색" onClick={openSearch} />}
1176
+ />
1177
+ ```
1178
+
1179
+ 슬롯 안쪽 여백은 **슬롯 내용이 직접 갖는다** — 컴포넌트는 자리만 잡는다(폴드 슬롯만 좁은 폭에 맞춰 가운데 정렬한다). 메뉴 폭은 `resizable` 로 바뀔 수 있으므로 슬롯 내용은 고정 폭 대신 `w-full` 로 따라가게 둔다.
1180
+
795
1181
  ### 4-2. 목록 페이지 (필터 + 테이블)
796
1182
 
797
1183
  구조: **페이지 헤더(제목 + 가이드 링크) → 필터(`SKeyValueTable`) → `STableBar` → `STable`**
@@ -1078,6 +1464,14 @@ export default function ProductDetailPage() {
1078
1464
  - [ ] `SGhostButton` 의 `intent` 가 조작 성격과 맞는가 (되돌릴 수 없는 삭제만 `danger`, 진입·추가는 `action`, 나머지는 `default`)
1079
1465
  - [ ] 창을 띄울 때 §3-3-1 판별 순서를 따랐는가 (그 자체가 화면 → `SPopup` / 실행 여부만 확정 → `SModal.confirm` / 모달 안에서 작성 → `SActionModal`)
1080
1466
  - [ ] 작업용 모달을 `SActionModal` + `SModal.create` 로 만들었는가 (직접 오버레이 ❌)
1467
+ - [ ] 모달·드로어의 하단 버튼을 본문이 아니라 `button` · `footerLeft` prop 으로 넘겼는가 (§3-3-4)
1468
+ - [ ] 앱 부트스트랩의 Provider 안쪽에 `<SModalOutlet />` 이 한 번 렌더되어 있는가 (§4-1 — 없으면 모달 안에서 앱 훅이 죽는다), 그 대신으로 모달 컴포넌트를 Provider 로 다시 감싸지 않았는가
1469
+ - [ ] 고른 컴포넌트를 §2-0 의 제 층에 놓았는가 (요소를 `SPage` 에 직접 놓지 않았는가, 블록을 `div` 로 감싸지 않았는가)
1470
+ - [ ] §2-0 포함 규칙을 지켰는가 (카드 안 카드 ❌, 표 셀 안 블록 ❌)
1471
+ - [ ] 블록 순서가 §2-0 순서와 맞는가 (제목 → 안내 → 필터 → 툴바 → 본문 → 페이지네이션 → 하단 액션)
1472
+ - [ ] 제목 위계가 층을 따라갔는가 (18 → 14 → 12, 건너뛰기 ❌), 섹션 제목 타이포를 `SSectionHeaderCard` 위에 덧씌우지 않았는가
1473
+ - [ ] 화면 요소마다 §3-0 라우팅에서 컴포넌트를 골랐는가 (직접 만들거나 비슷한 것으로 대체하지 않았는가)
1474
+ - [ ] §3-0 의 "갈림" 열이 가리킨 판별 절을 읽고 골랐는가 (§3-7-2 선택 컨트롤, §3-7-3 켜고 끄기 등)
1081
1475
  - [ ] 상태 표시·알림·확인 다이얼로그가 §3의 선택 규칙을 따르는가
1082
1476
 
1083
1477
  ---
@@ -1205,6 +1599,10 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
1205
1599
  | typo-table-header | 12px | 500 | 20px |
1206
1600
  | typo-table-body | 12px | 400 | 20px |
1207
1601
  | typo-table-accent | 12px | 700 | 20px |
1602
+ | typo-item-sm-default | 12px | 500 | 20px |
1603
+ | typo-item-sm-selected | 12px | 700 | 20px |
1604
+ | typo-item-md-default | 14px | 500 | 24px |
1605
+ | typo-item-md-selected | 14px | 700 | 24px |
1208
1606
 
1209
1607
  ### 시맨틱 색 토큰 (var() 참조 전용 — 예: bg-[var(--sys-color-bg-frame)])
1210
1608
  --sys-color-bg-accent
@@ -1278,7 +1676,7 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
1278
1676
  --sys-color-link-accent
1279
1677
  --sys-color-navigation-gnb-bg-dark
1280
1678
 
1281
- ## 3. 컴포넌트 인덱스 (62종)
1679
+ ## 3. 컴포넌트 인덱스 (63종)
1282
1680
 
1283
1681
  **Props 는 이 문서에 없다.** 쓸 컴포넌트를 정했으면 그 컴포넌트의 README 를 읽는다.
1284
1682
 
@@ -1287,4 +1685,4 @@ Tailwind 유틸리티는 아래 스케일에 있는 값만 사용한다. 리터
1287
1685
  예) SButton 을 쓴다면 `dist/components/SButton/README.md`.
1288
1686
  prop 을 추측해서 쓰지 말고 반드시 README 로 확인한다 (분류별 용도는 §1 의 "전체 컴포넌트 인덱스" 참조).
1289
1687
 
1290
- SActionModal · SBadge · SBarcodeInput · SButton · SCalendar · SCallout · SCard · SCheckbox · SChip · SChipInput · SCircleProgress · SConfirmModal · SDatePicker · SDateRangePicker · SDivider · SDraggableItem · SDraggableList · SDrawer · SDropdownButton · SExpansionItem · SExpansionList · SField · SFilePicker · SForm · SGhostButton · SGnb · SGuide · SIcon · SInput · SKeyValueTable · SLayout · SLinearProgress · SList · SListItem · SLoadingContainer · SLoadingModal · SModal · SNumberInput · SPage · SPagination · SPopover · SPopup · SPortal · SRadio · SRadioButton · SScrollArea · SSectionHeaderCard · SSelect · SStepper · SSwitch · STable · STableBar · STabs · STag · STextLink · STextarea · STimePicker · STimeRangePicker · SToast · SToggle · STooltip · STree
1688
+ SActionModal · SBadge · SBarcodeInput · SButton · SCalendar · SCallout · SCard · SCheckbox · SChip · SChipInput · SCircleProgress · SConfirmModal · SDatePicker · SDateRangePicker · SDivider · SDraggableItem · SDraggableList · SDrawer · SDropdownButton · SExpansionItem · SExpansionList · SField · SFilePicker · SForm · SGhostButton · SGnb · SGuide · SIcon · SInput · SKeyValueTable · SLayout · SLinearProgress · SList · SListItem · SLoadingContainer · SLoadingModal · SModal · SNumberInput · SPage · SPagination · SPopover · SPopup · SPortal · SRadio · SRadioButton · SScrollArea · SSectionHeaderCard · SSelect · SSplitter · SStepper · SSwitch · STable · STableBar · STabs · STag · STextLink · STextarea · STimePicker · STimeRangePicker · SToast · SToggle · STooltip · STree