sellmate-design-system-react 3.0.0 → 3.2.0

package/AGENTS.md

@@ -0,0 +1,695 @@
+# sellmate-design-system-react — 사용 규칙 (AGENTS.md)
+
+> **대상**: 이 패키지로 화면을 만드는 소비 앱의 개발자와 AI 코딩 에이전트(Claude 등).
+> 이 문서는 "무엇을 언제 쓰고, 무엇을 쓰면 안 되는지"의 단일 기준이다.
+> 개별 컴포넌트의 상세 Props/Events는 `node_modules/sellmate-design-system-react/dist/components/<이름>/README.md` 를 참조한다.
+
+## 0. 최우선 원칙 — 디자인 시스템 컴포넌트가 먼저다
+
+**화면 요소를 만들기 전에, 그 역할을 하는 컴포넌트가 이미 있는지 먼저 확인한다.**
+있으면 반드시 그것을 쓴다. 직접 만드는 것은 대응 컴포넌트가 **없다는 것을 확인한 뒤**의 최후 수단이다.
+
+```tsx
+❌ <button onClick={save}>저장</button>        ✅ <SButton label="저장" onClick={save} />
+❌ <table>…</table>                            ✅ <STable columns={columns} rows={rows} />
+❌ <div className="rounded border p-16">…</div> ✅ <SSectionHeaderCard>…</SSectionHeaderCard>
+❌ <ul><li>…</li></ul>                         ✅ <SList><SListItem title="…" /></SList>
+```
+
+"비슷하게 생긴 것을 직접 만드는 것"이 어색함의 가장 큰 원인이다. 대응 컴포넌트를 쓰면 색·간격·상태·접근성이 전부 따라온다.
+
+### 0-1. 전체 컴포넌트 인덱스
+
+무엇을 만들지 정했으면 **이 표에서 먼저 찾는다.** 상세 Props 는 `dist/components/<이름>/README.md` 참조.
+
+| 분류 | 컴포넌트 |
+| --- | --- |
+| **버튼·링크** | `SButton` `SGhostButton` `SDropdownButton` `STextLink` `SSwitch` `SToggle` |
+| **입력 (폼)** | `SForm` `SField` `SInput` `SNumberInput` `STextarea` `SSelect` `SCheckbox` `SRadio` `SRadioButton` `SChip` `SChipInput` `SBarcodeInput` `SFilePicker` |
+| **날짜·시간** | `SCalendar` `SDatePicker` `SDateRangePicker` `STimePicker` `STimeRangePicker` |
+| **표·목록** | `STable` `STableBar` `SKeyValueTable` `SList` `SListItem` `SDraggableItem` |
+| **레이아웃** | `SLayout` `SGnb` `SPage` `SSectionHeaderCard` `SCard` `SDivider` `SScrollArea` `SExpansionItem` |
+| **내비게이션** | `STabs` `SPagination` `SStepper` |
+| **표시·상태** | `STag` `SBadge` `SIcon` `SCallout` `SGuide` |
+| **진행·로딩** | `SLinearProgress` `SCircleProgress` `SLoadingContainer` `SLoadingModal` |
+| **오버레이** | `STooltip` `SPopover` `SPopup` `SPortal` |
+| **모달** | `SModal.confirm()` `SModal.create()` + `SActionModal` `SConfirmModal` |
+| **알림** | `SToast` `SToastContainer` |
+
+표에 없는 UI 를 만들어야 할 때만 `div` 로 직접 조립하고, 그때도 §1-2 · §2 의 토큰 규칙을 지킨다.
+
+### 0-2. 프로젝트 설정
+
+설정(Tailwind v4 `theme.css` import, `@source` 지정, Next.js 주의사항)은 패키지 [README.md](./README.md)를 따른다. 이 문서는 설정이 끝난 상태에서의 **화면 작성 규칙**만 다룬다.
+
+---
+
+## 1. 절대 규칙 (금지 목록)
+
+AI 에이전트는 코드를 생성하기 전에 이 목록을 반드시 지킨다.
+
+### 1-1. 생 HTML 컨트롤 금지
+
+§0 원칙의 구체적 목록이다. 아래 요소는 **어떤 경우에도** 생 HTML 로 만들지 않는다.
+
+| 금지 | 대신 사용 |
+| --- | --- |
+| `<button>` | `SButton`, `SGhostButton`, `SDropdownButton`, `STextLink` |
+| `<input type="text/password/...">` | `SInput` |
+| `<input type="number">` | `SNumberInput` |
+| `<input type="checkbox">` | `SCheckbox`, `SToggle`, `SSwitch` |
+| `<input type="radio">` | `SRadio`, `SRadioButton` |
+| `<input type="file">` | `SFilePicker` |
+| `<select>` | `SSelect` |
+| `<textarea>` | `STextarea` |
+| `<table>` | `STable`, `SKeyValueTable` |
+| `<form>` | `SForm` |
+| `<dialog>`, 직접 만든 오버레이 | `SModal.confirm(...)`, `SModal.create(...)`, `SPopup` |
+| `alert()`, `confirm()` | `SToast`, `SModal.confirm(...)` |
+| 직접 만든 탭/페이지네이션/스텝퍼 | `STabs`, `SPagination`, `SStepper` |
+| `<ul>`/`<li>` 로 만든 목록 UI | `SList` + `SListItem` (드래그 정렬은 `SDraggableItem`) |
+| 직접 만든 섹션 카드(제목 바 + 본문 박스) | `SSectionHeaderCard` + `.Header` / `.Body` |
+| `<svg>` 직접 삽입, 이모지 아이콘 | `SIcon` |
+| `<hr>` | `SDivider` |
+| `<details>` / `<summary>` | `SExpansionItem` |
+| `<progress>` | `SLinearProgress`, `SCircleProgress` |
+| `<label>` (폼 레이블) | `SField` 의 `label` prop |
+| 직접 만든 카드·패널 박스 | `SCard`, `SSectionHeaderCard` |
+| 직접 만든 스크롤 영역 | `SScrollArea` |
+
+예외: 순수 레이아웃 요소(`div`, `section`, 시맨틱 `h1~h6`, `p`, `span`, `a`)는 허용. 단 스타일은 아래 규칙을 따른다.
+
+### 1-2. 임의 값(arbitrary literal) 금지
+
+Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
+
+```text
+❌ text-[14px]  font-[600]  bg-[#eee]  gap-[13px]  p-[10px]  rounded-[5px]  text-[#333]
+✅ typo-body-sm-default  text-fg-tertiary  bg-bg-frame  gap-12  p-8  rounded-md
+✅ w-[var(--sys-size-control-md-height)]   ← 토큰을 var()로 참조하는 것은 허용
+```
+
+- 하드코딩 hex/px/rem 리터럴은 어디에도 쓰지 않는다 (인라인 `style` 포함).
+- 인라인 `style`은 런타임 계산값(동적 width 등)에만 허용한다.
+
+**단, 디자인 토큰이 없는 속성의 임의 값은 정당하다.** 화면 고유의 레이아웃 치수가 여기 해당한다.
+
+```tsx
+✅ <div className="w-[280px] max-w-[1200px] grid-cols-[200px_1fr]" />   // 앱 고유 치수
+❌ <div className="text-[13px] bg-[#eee] gap-[13px] rounded-[5px]" />   // 토큰이 있는 속성
+```
+
+규칙은 **색 · 타이포 · 간격 · 모서리** 네 계열에만 적용된다 — 이 넷은 토큰이 이미 있으므로 임의 값은 곧 디자인 시스템 우회다.
+
+### 1-3. 타이포그래피는 프리셋으로만
+
+`text-14 font-bold` 같은 조합을 즉흥으로 만들지 않는다. §2-1의 `typo-*` 프리셋 클래스를 쓴다.
+
+### 1-4. 숫자는 무조건 `toLocaleString()`
+
+**숫자를 화면에 표시할 때는 예외 없이 `toLocaleString()` 을 거쳐 세 자리마다 콤마를 넣는다.**
+금액·수량·건수·재고 무엇이든, 테이블·상세·요약 문구 어디에 놓이든 같다.
+
+```tsx
+❌ <span>{price}원</span>              ❌ {`${qty}개`}         ❌ {String(count)}
+✅ <span>{price.toLocaleString()}원</span>
+✅ format: (v: number) => `${Number(v).toLocaleString()}개`
+```
+
+콤마 없는 `39000` 은 자릿수를 세어야 읽히지만 `39,000` 은 한눈에 읽힌다. 숫자를 그대로 출력하는 코드는 미완성으로 본다.
+
+전화번호·사업자번호처럼 하이픈이 들어가는 값은 애초에 숫자가 아니라 **서식이 정해진 문자열**이므로 이 규칙의 대상이 아니다.
+
+---
+
+## 2. 조합 어휘 — 컴포넌트 "사이"를 채울 때 쓰는 것들
+
+### 2-1. 타이포그래피 프리셋
+
+역할(role) → 크기 → 굵기 순으로 조합된 클래스가 이미 준비되어 있다.
+
+| 용도 | 클래스 |
+| --- | --- |
+| 페이지/섹션 제목 | `typo-heading-lg`(18px) · `typo-heading-md`(16px) · `typo-heading-sm`(14px) · `typo-heading-xs`(12px) |
+| 본문 | `typo-body-lg-*` (16px) · `typo-body-md-*`(14px) · `typo-body-sm-*`(12px) · `typo-body-xs-default`(11px) — `*` = `default`/`medium`/`bold` |
+| 테이블 | `typo-table-header` · `typo-table-body` · `typo-table-accent` |
+| 컨트롤·필드·피드백·내비 | `typo-control-*` `typo-field-*` `typo-feedback-*` `typo-navigation-*` (컴포넌트 내부용 — 직접 쓸 일은 드묾) |
+
+**기본 선택 — 이 조합을 쓴다.** 이 서비스는 정보 밀도가 높아 본문이 12px 이다. 14px 를 본문 기본으로 쓰지 않는다.
+
+| 역할 | 클래스 | 크기 |
+| --- | --- | --- |
+| 페이지 헤더 제목 (h1) | `typo-heading-lg` | 18px |
+| 섹션 제목 | `typo-heading-sm` | 14px |
+| 본문 | `typo-body-sm-default` | 12px |
+| 보조 설명 | `typo-body-sm-default` + `text-fg-tertiary` | 12px / `grey_65` |
+
+페이지 제목만 18px 로 크게 두고 그 아래는 14 / 12 로 촘촘하게 간다. 중간 크기(16px)는 기본 골격에서 쓰지 않는다.
+
+### 2-2. 간격 (spacing)
+
+- 유틸리티 숫자 = px. 스케일: `2 4 6 8 10 12 16 19 20 22 24 28 32 36 40 48 60`
+- 형제 요소 간격은 margin 대신 부모의 `flex`/`grid` + `gap-*`으로 잡는다.
+- 시맨틱 간격 토큰 (텍스트 덩어리·요소 사이 기본 리듬):
+
+| 상황 | 값 |
+| --- | --- |
+| **페이지 콘텐츠 패딩** | **`p-20`** |
+| **섹션 ↔ 섹션** | **`gap-12`** |
+| **페이지 내 블록 ↔ 블록** (헤더·필터·툴바·테이블 사이) | **`gap-12`** |
+| 요소 ↔ 요소 (기본) | `gap-8` (`--sys-space-stack-gap-element-normal`) |
+| 제목 ↔ 설명 텍스트 | `gap-4` (`--sys-space-stack-gap-text-normal`) |
+
+정보 밀도가 높은 서비스라 블록 간격을 넓게 벌리지 않는다. `gap-16` / `gap-24` 를 페이지 골격의 기본값으로 쓰지 않는다.
+
+#### 같은 컴포넌트를 여러 개 늘어놓을 때 (그룹 간격)
+
+위 "요소 ↔ 요소 `gap-8`" 은 **서로 다른 요소** 사이의 기본값이다.
+**같은 컴포넌트를 여러 개 나열할 때는 컴포넌트마다 정해진 그룹 간격**이 따로 있다.
+
+| 컴포넌트 | 수평 배열 | 수직 배열 |
+| --- | --- | --- |
+| `SCheckbox` | **`gap-24`** | `gap-8` |
+| `SRadio` | **`gap-24`** | `gap-8` |
+| `STextLink` | **`gap-16`**(sm) / **`gap-24`**(md·lg) | `gap-4` |
+| `SGhostButton` | `gap-4` | `gap-4` |
+| `SButton` | `gap-8` (xs·sm·md) / **`gap-12`**(lg) | 〃 |
+| `STag` | `gap-8` | `gap-8` |
+| `SToggle` | `gap-8` | `gap-8` |
+| `SListItem` (bordered) | — | `gap-8` (+ 컨테이너 `p-16`) |
+
+**수평·수직이 다른 것에 주의한다** — 체크박스·라디오는 가로로 놓으면 `gap-24`, 세로로 놓으면 `gap-8` 로 3배 차이다. 가로 배열에 `gap-8` 을 쓰면 항목이 붙어 보인다.
+
+```tsx
+✅ <div className="flex gap-24">      {/* 체크박스 가로 */}
+     <SCheckbox label="전체" … /><SCheckbox label="판매중" … />
+   </div>
+✅ <div className="flex flex-col gap-8">  {/* 체크박스 세로 */}
+     <SCheckbox label="전체" … /><SCheckbox label="판매중" … />
+   </div>
+❌ <div className="flex gap-8">        {/* 가로인데 8 — 붙어 보인다 */}
+```
+
+- **라디오는 `SRadioGroup` 을 쓴다.** `direction="horizontal" | "vertical"` 만 주면 간격을 알아서 맞춘다 — 직접 `flex` 로 감싸지 않는다.
+- `SRadioButton` 그룹의 간격은 `-1px`(테두리 겹침 처리)이라 손으로 만들지 않는다.
+- 정확한 값이 필요하면 토큰을 직접 참조해도 된다: `gap-[var(--cmp-checkbox-group-gap-horizontal)]`
+
+### 2-3. 색상
+
+**시맨틱 유틸리티를 우선 사용한다** — 의미가 이름에 담긴 토큰이 이미 유틸리티로 존재한다.
+
+#### 텍스트 색은 두 단계뿐이다
+
+| 용도 | 유틸리티 | 값 |
+| --- | --- | --- |
+| **본문·제목 (기본값)** | 지정하지 않는다 — 전역 기본색이 이미 적용된다 | `grey_95` `#222222` |
+| **보조 설명 · 비활성** | **`text-fg-tertiary`** | `grey_65` `#888888` |
+
+- `theme.css` 가 `body` 에 `grey_95` 를 깔아두므로 **본문에 텍스트 색 클래스를 붙이지 않는다.** `text-fg-primary` 를 매번 쓰는 것은 불필요하다.
+- 흐리게 보여야 하는 것은 보조 설명이든 비활성이든 **전부 `text-fg-tertiary`** 다.
+- 중간 톤(`text-fg-secondary` `#555`)은 텍스트 위계에 쓰지 않는다. 두 단계로만 간다.
+
+```tsx
+✅ <p>주문이 접수되었습니다.</p>                          // 색 지정 없음 = grey_95
+✅ <p className="text-fg-tertiary">최근 30일 기준</p>      // 보조 설명
+✅ <span className="text-fg-tertiary">-</span>            // 빈 값 (§3-4)
+❌ <p className="text-fg-primary">주문이 접수되었습니다.</p>  // 불필요
+❌ <p className="text-fg-secondary">최근 30일 기준</p>      // 중간 톤 사용
+```
+
+#### 그 밖의 색
+
+| 용도 | 유틸리티 |
+| --- | --- |
+| 상태 텍스트 | `text-fg-danger` `text-fg-success` `text-fg-warning` `text-fg-accent` `text-fg-inverse` |
+| 배경 | `bg-bg-frame`(흰 콘텐츠 면) · `bg-bg-neutralLight`/`bg-bg-neutralBright`(옅은 회색 면) · `bg-bg-screen`(앱 바탕) |
+| 보더/구분선 | `border-border-default` · `border-border-strong` · `border-divider-default` |
+| 비활성 배경·보더 | `bg-disabled-bg` `border-disabled-border` |
+| 링크 | `text-link-accent` |
+
+- 시맨틱 토큰에 맞는 항목이 없을 때만 원색 스케일(`bg-blue-subtle` 등)을 쓴다.
+- 어느 쪽이든 **토큰 유틸리티만** 사용 — 리터럴 hex 금지.
+
+---
+
+## 3. 컴포넌트 선택 규칙 — "언제 뭘 쓰나"
+
+> ⚠️ 초안(개발 작성). <!-- TODO(디자인): 전체 검수·확정 --> 표시가 있는 행은 디자인 확정 전까지 초안 기준으로 사용.
+
+### 3-1. 라벨/표시류 — STag vs SBadge vs SChip
+
+| 상황 | 사용 |
+| --- | --- |
+| **상태·분류를 라벨로 표시 (기본값)** | **`STag`** — `<STag size="sm" color="..." label="판매중" />`. 목록의 상태 컬럼, 상세의 분류 태그 등 대부분이 여기 해당한다 |
+| 라벨 없이 **색 점만**으로 상태를 찍을 때 | `SBadge` — 점(dot)만 그리는 인디케이터. 텍스트가 이미 있고 앞에 점만 붙이는 좁은 경우에만 |
+| 사용자가 입력·삭제·편집하는 **토큰** | `SChip` (단독) / `SChipInput` (입력 필드 안에서) |
+
+> 상태 표시는 **`STag size="sm"` 이 기본**이다. 색 점 + 텍스트 조합(`SBadge`)을 기본으로 쓰지 않는다.
+
+### 3-2. 알림/안내류
+
+| 상황 | 사용 |
+| --- | --- |
+| 화면에 **상시 노출**되는 안내·경고 문구 | `SCallout` — `type` + `message` 배열(중첩 = 들여쓰기) |
+| 작업 결과를 **일시적으로** 알림 | `SToast` (+ 루트에 `SToastContainer`) |
+| 진행 전 **확인/취소**를 받아야 할 때 | `SModal.confirm({...}).onOk(...)` |
+| 특정 UI 요소에 대한 **온보딩·기능 안내** | `SGuide` |
+| 로딩 중 화면 잠금 | `SLoadingModal` / 영역 로딩은 `SLoadingContainer` |
+
+### 3-3. 플로팅/오버레이류
+
+| 상황 | 사용 |
+| --- | --- |
+| hover 시 **짧은 보조 설명** (상호작용 없음) | `STooltip` |
+| 클릭 시 **상호작용 가능한** 콘텐츠 (메뉴·미니 폼) | `SPopover` |
+| **팝업** (별도 창 성격의 가벼운 표시) | `SPopup` |
+| 페이지 흐름을 끊고 **작업을 완료**시키는 창 | **`SActionModal` 로 컴포넌트를 만들고 `SModal.create` 로 띄운다** (아래 참조) |
+| 확인/취소만 받는 창 | `SModal.confirm(...)` |
+| 로딩 중 화면 잠금 | `SModal.loading(...)` / `SLoadingModal` |
+
+**모달 만드는 법** — 디자인 시스템이 띄우는 모달은 `SActionModal` · `SConfirmModal` · `SLoadingModal` 3종뿐이고 `create` · `confirm` · `loading` 이 1:1로 대응한다.
+직접 오버레이를 만들지 않는다. 작업용 모달은 **`SActionModal` 을 루트로 하는 컴포넌트를 만들어 `SModal.create` 에 넘긴다.**
+
+```tsx
+// 1) SActionModal 을 루트로 하는 컴포넌트를 만든다
+//    create 가 주입하는 open / onOpenChange / onClose 를 그대로 SActionModal 에 전달해야 한다
+function OrderModal({ orderId, open, onOpenChange, onClose, modalRef }: OrderModalProps) {
+  return (
+    <SActionModal
+      open={open}
+      onOpenChange={onOpenChange}
+      onClose={onClose}
+      modalTitle="주문 상세"
+      width={720}
+      // 주 액션은 button(단수), 보조 버튼은 footerLeft — 하단 버튼 양끝 분리 규칙과 같다
+      button={{ label: '접수', onClick: () => modalRef.ok() }}
+      footerLeft={<SButton color="secondary" label="취소" onClick={() => modalRef.cancel()} />}
+    >
+      <SKeyValueTable fields={orderFields} values={order} />
+    </SActionModal>
+  );
+}
+
+// 2) SModal.create 로 띄운다
+SModal.create({ component: OrderModal, componentProps: { orderId } })
+  .onOk(() => refetch())
+  .onDismissed(() => {});
+```
+
+### 3-4. 테이블 컬럼 정렬
+
+**숫자가 들어가는 컬럼은 예외 없이 오른쪽 정렬한다** (`align: 'right'`).
+자릿수가 세로로 맞아야 값의 크기를 눈으로 비교할 수 있기 때문이다.
+
+| 컬럼 내용 | 정렬 | 예 |
+| --- | --- | --- |
+| **금액·수량·개수·비율 등 단위가 붙은 숫자** | **`'right'`** | `39,000원` · `12개` · `3건` · `15%` |
+| **숫자만 있는 값** | **`'right'`** | `1024` · `39000` |
+| 텍스트 | 생략(기본 `left`) | 상품명, 카테고리 |
+| 상태 태그·아이콘·체크박스 등 고정폭 요소 | `'center'` | `STag`, `SIcon` |
+
+```tsx
+const columns: STableColumn[] = [
+  { name: 'id', label: 'ID', field: 'id', width: '80px', align: 'right' },
+  { name: 'name', label: '상품명', field: 'name' },                       // 텍스트 → 생략
+  { name: 'qty', label: '수량', field: 'qty', width: '80px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}개` },
+  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}원` },
+  { name: 'status', label: '상태', field: 'status', width: '100px', align: 'center',
+    render: () => <STag size="sm" color="green" label="판매중" /> },
+];
+```
+
+- `format` 으로 단위를 붙이더라도 **숫자 기반이면 오른쪽 정렬**이다. 단위 때문에 문자열이 되는 것은 정렬 판단과 무관하다.
+- 숫자는 §1-4 대로 **`toLocaleString()` 이 필수**다. 세 자리 콤마 없이 출력하지 않는다.
+- `SKeyValueTable` 의 값 셀도 같은 기준을 따른다.
+
+#### 값이 없는 셀은 회색 하이픈
+
+셀을 **빈칸으로 두지 않는다.** 값이 `null` · `undefined` · 빈 문자열이면 `-` 를 `text-fg-tertiary`(`grey_65`)로 표시한다.
+빈칸은 "데이터가 없음"인지 "렌더가 깨졌는지" 구분되지 않지만, 회색 하이픈은 없다는 사실을 명시한다.
+
+```tsx
+// 재사용 헬퍼를 하나 두고 모든 컬럼에서 쓴다
+const emptyCell = <span className="text-fg-tertiary">-</span>;
+const hasValue = (v: unknown) => v !== null && v !== undefined && v !== '';
+
+const columns: STableColumn[] = [
+  { name: 'memo', label: '메모', field: 'memo',
+    render: (row: SRow) => (hasValue(row.memo) ? row.memo : emptyCell) },
+  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
+    render: (row: SRow) =>
+      hasValue(row.price) ? `${Number(row.price).toLocaleString()}원` : emptyCell },
+];
+```
+
+`0` 은 값이 있는 것이므로 하이픈으로 바꾸지 않는다 — `0원` 그대로 표시한다.
+
+### 3-5. 버튼류
+
+| 상황 | 사용 |
+| --- | --- |
+| 일반 액션 | `SButton` (`color`: `primary` / `secondary` / `neutral` / `danger`, `size`: xs~lg) |
+| **삭제 등 파괴적 액션** | **`SButton color="danger"`** 또는 **`color="danger" outline`** |
+| 텍스트만 있는 저강조 액션 | `SGhostButton` |
+| 본문 속 이동 링크 | `STextLink` |
+| 메인 액션 + 부가 메뉴 | `SDropdownButton` |
+
+한 화면의 primary 버튼 개수에 대한 제약은 없다. 다만 **삭제·초기화 등 되돌릴 수 없는 액션은 반드시 `danger`** 로 표시한다.
+
+**하단 버튼 배치 (모든 화면 공통)** — 그룹을 모아 정렬하지 않고 **양끝으로 벌린다**(`justify-between`).
+
+- **왼쪽 끝**: 취소·닫기·목록 등 되돌리는 액션
+- **오른쪽 끝**: 저장·등록·수정·삭제 등 실행 액션
+- 체크박스·안내 문구 등 **부가 요소는 오른쪽 그룹 안, 실행 버튼 바로 왼쪽**에 둔다
+
+```tsx
+<div className="flex items-center justify-between">
+  <SButton color="secondary" label="취소" />
+  <div className="flex items-center gap-8">
+    <SCheckbox label="계속 등록하기" value={keep} onValueChange={setKeep} />  {/* 부가 요소 */}
+    <SButton label="저장" />
+  </div>
+</div>
+```
+
+---
+
+## 4. 페이지 레시피 — 표준 골격
+
+> 새 페이지는 반드시 아래 골격에서 시작한다. 임의 골격을 발명하지 않는다.
+>
+> **핵심 원칙 — 표 형태의 정보는 `SKeyValueTable` 로 만든다.** 필터·등록/수정 폼·상세 정보가 모두 여기 해당한다.
+> `SField` 컨트롤을 `div` 로 직접 나열해 폼을 만들지 않는다.
+
+### 4-1. 앱 셸 (모든 페이지 공통)
+
+```tsx
+import { SLayout, SGnb, SPage, type SGnbMenuItem } from 'sellmate-design-system-react';
+
+const MENU: SGnbMenuItem[] = [
+  { label: '주문', value: 'orders', icon: 'bill' },
+  { label: '상품', value: 'products', icon: 'box', children: [{ label: '목록', value: 'product-list' }] },
+];
+
+export default function AppShell({ children }: { children: React.ReactNode }) {
+  return (
+    <SLayout type="box" header="fix">
+      {/* type/header/folded 는 SLayout 에만 준다 — SGnb 는 context 에서 읽는다 */}
+      <SGnb items={MENU} value={current} onValueChange={navigate} logo={<Logo />} />
+      <SPage background="frame" className="p-20">{children}</SPage>
+    </SLayout>
+  );
+}
+```
+
+### 4-2. 목록 페이지 (필터 + 테이블)
+
+구조: **페이지 헤더(제목 + 가이드 링크) → 필터(`SKeyValueTable`) → `STableBar` → `STable`**
+
+액션 버튼의 위치가 핵심이다:
+
+- **페이지 제목 줄에는 액션 버튼을 두지 않는다.** 가이드·매뉴얼 링크 등 부가 정보만 온다.
+- **주요 액션(등록 등)은 `STableBar` 의 `rightActions`** 에 둔다.
+- **선택 상태 액션(선택 삭제 등)은 `STableBar` 의 `actions`** 에 둔다. `actions` 슬롯은 건수 요약이 있으면 앞에 구분선(`SDivider`)을 **자동으로** 넣으므로 직접 구분선을 만들지 않는다.
+
+```tsx
+import {
+  SButton, STextLink, SKeyValueTable, STableBar, STable, STag,
+  type STableColumn, type SRow, type SKeyValueField,
+} from 'sellmate-design-system-react';
+
+/** 필터도 표다 — SKeyValueTable 로 만든다 (서비스 전용 전역 필터가 따로 있는 경우 제외) */
+const filterFields: SKeyValueField[][] = [
+  [
+    { name: 'status', label: '상태', type: 'select',
+      options: { options: STATUS_OPTIONS, emitValue: true } },
+    { name: 'keyword', label: '검색어', type: 'input',
+      options: { placeholder: '상품명 / 상품코드' } },
+  ],
+  [
+    { name: 'period', label: '등록일', type: 'date-range-picker', tdColSpan: 3 },
+  ],
+];
+
+const columns: STableColumn[] = [
+  // 숫자 컬럼은 전부 align: 'right' — §3-4
+  { name: 'id', label: 'ID', field: 'id', width: '80px', align: 'right' },
+  { name: 'name', label: '상품명', field: 'name' },
+  { name: 'stock', label: '재고', field: 'stock', width: '90px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}개` },
+  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
+    format: (v: number) => `${Number(v).toLocaleString()}원` },
+  // 상태 컬럼은 STag size="sm" — SBadge 색 점을 기본으로 쓰지 않는다
+  { name: 'status', label: '상태', field: 'status', width: '100px', align: 'center',
+    render: (row: SRow) =>
+      row.status === 'selling'
+        ? <STag size="sm" color="green" label="판매중" />
+        : <STag size="sm" color="grey" label="판매중지" /> },
+];
+
+export default function ProductListPage() {
+  const [filters, setFilters] = useState<Record<string, unknown>>({});
+  const [selected, setSelected] = useState<SRow[]>([]);
+
+  return (
+    <div className="flex flex-col gap-12">
+      {/* 페이지 헤더 — 액션 버튼 없음. 가이드/매뉴얼 링크 자리 */}
+      <div className="flex items-center justify-between">
+        <h1 className="typo-heading-lg m-0">상품 목록</h1>
+        <STextLink label="이용 가이드" rightArrow="chevron" onClick={openGuide} />
+      </div>
+
+      {/* 필터 — search 를 켜면 우측에 검색 패널이 붙는다 */}
+      <SKeyValueTable
+        fields={filterFields}
+        values={filters}
+        search
+        onChange={({ values }) => setFilters(values)}
+        onSearch={fetchList}
+      />
+
+      {/* 툴바 — 좌: 건수 + (구분선 자동) + 선택 액션 / 우: 주요 액션 */}
+      <STableBar
+        total={total}
+        selected={selected.length}
+        actions={
+          <SButton size="sm" color="secondary" label="선택 삭제"
+            disabled={!selected.length} onClick={removeSelected} />
+        }
+        rightActions={<SButton size="sm" label="상품 등록" onClick={goCreate} />}
+      />
+
+      <STable
+        columns={columns}
+        rows={rows}
+        rowKey="id"
+        selectable
+        selected={selected}
+        onSelectedChange={setSelected}
+        pagination={{ currentPage, lastPage }}
+        isLoading={isLoading}
+      />
+    </div>
+  );
+}
+```
+
+### 4-3. 폼 페이지 (등록/수정)
+
+구조: **페이지 제목 → `SForm` + `SKeyValueTable` → 하단 버튼**
+
+- 필드를 `div` 로 나열하지 않고 **`SKeyValueTable` 의 행으로 구성**한다.
+- 검증 규칙은 각 field 의 `options.rules` 로 넘긴다. `SForm` 이 하위 컨트롤을 자동 수집해 submit 시 일괄 검증하고, 실패 시 첫 실패 필드로 포커스를 옮긴다.
+- **버튼 순서: 취소·닫기가 왼쪽, 저장·등록·수정·삭제가 오른쪽.** 이 순서는 모든 화면에서 동일하다.
+
+```tsx
+import {
+  SForm, SKeyValueTable, SButton, SCheckbox,
+  type SFormHandle, type SKeyValueField, type Rule,
+} from 'sellmate-design-system-react';
+
+const required = (msg: string): Rule => v =>
+  v != null && String(v).trim() !== '' ? true : msg;
+
+const fields: SKeyValueField[][] = [
+  [
+    { name: 'name', label: '상품명', required: true, type: 'input',
+      options: { placeholder: '상품명 입력', rules: [required('상품명을 입력해 주세요.')] } },
+    { name: 'code', label: '상품코드', type: 'input', options: { placeholder: '자동 생성' } },
+  ],
+  [
+    { name: 'category', label: '카테고리', required: true, type: 'select',
+      options: { options: CATEGORY_OPTIONS, emitValue: true,
+        rules: [required('카테고리를 선택해 주세요.')] } },
+    { name: 'price', label: '판매가', type: 'number-input' },
+  ],
+  [
+    { name: 'memo', label: '메모', type: 'textarea', tdColSpan: 3,
+      helpText: ['내부 관리용 메모입니다.'] },
+  ],
+];
+
+export default function ProductCreatePage() {
+  const formRef = useRef<SFormHandle>(null);
+  const [values, setValues] = useState<Record<string, unknown>>({});
+
+  return (
+    <div className="flex flex-col gap-12">
+      <h1 className="typo-heading-lg m-0">상품 등록</h1>
+
+      <SForm ref={formRef} formClass="flex flex-col gap-12" onSubmit={save}>
+        <SKeyValueTable
+          fields={fields}
+          values={values}
+          onChange={({ values }) => setValues(values)}
+        />
+
+        {/* 하단 버튼은 양끝으로 벌린다. 부가 요소(체크박스 등)는 저장 바로 왼쪽 */}
+        <div className="flex items-center justify-between">
+          <SButton type="button" color="secondary" label="취소" onClick={goBack} />
+          <div className="flex items-center gap-8">
+            <SCheckbox label="계속 등록하기" value={keepOpen} onValueChange={v => setKeepOpen(v as boolean)} />
+            <SButton type="submit" label="저장" />
+          </div>
+        </div>
+      </SForm>
+    </div>
+  );
+}
+```
+
+### 4-4. 상세(조회) 페이지
+
+구조: **페이지 헤더(제목) → 섹션별 `SSectionHeaderCard` + `SKeyValueTable` → 하단 버튼**
+
+- 조회 값은 `type: 'text'` 행으로 표시한다. **상태·분류 태그도 별도 영역이 아니라 표의 한 행**으로 넣는다 (`render` 에 `STag`).
+- 행이 많아지면 **유형별로 섹션을 나누고, 각 섹션을 `SSectionHeaderCard` 로 감싼다.**
+  합성 컴포넌트라 `SSectionHeaderCard.Header` / `SSectionHeaderCard.Body` 를 자식으로 쓴다.
+- **수정·삭제 버튼은 하단에 둔다.** 내용이 짧아 우측 상단에 두는 변형도 있으나 기본은 하단이다.
+
+```tsx
+import {
+  SSectionHeaderCard, SKeyValueTable, SButton, STag, type SKeyValueField,
+} from 'sellmate-design-system-react';
+
+const basicFields: SKeyValueField[][] = [
+  [
+    { name: 'code', label: '상품코드', type: 'text' },
+    { name: 'createdAt', label: '등록일', type: 'text' },
+  ],
+  [
+    { name: 'category', label: '카테고리', type: 'text' },
+    // 상태 태그도 표의 한 행으로 표현한다
+    { name: 'status', label: '상태',
+      render: <STag size="sm" color="green" label="판매중" /> },
+  ],
+];
+
+const priceFields: SKeyValueField[][] = [
+  [
+    { name: 'price', label: '판매가', type: 'text' },
+    { name: 'cost', label: '원가', type: 'text' },
+  ],
+];
+
+export default function ProductDetailPage() {
+  return (
+    <div className="flex flex-col gap-12">
+      <h1 className="typo-heading-lg m-0">클래식 셔츠</h1>
+
+      <SSectionHeaderCard>
+        <SSectionHeaderCard.Header title="기본 정보" marker thickness="accent" />
+        <SSectionHeaderCard.Body>
+          <SKeyValueTable fields={basicFields} values={product} />
+        </SSectionHeaderCard.Body>
+      </SSectionHeaderCard>
+
+      <SSectionHeaderCard>
+        {/* 헤더 우측에 액션이 필요하면 slot 을 쓴다 */}
+        <SSectionHeaderCard.Header
+          title="가격 정보"
+          marker
+          helpText={['부가세 포함 금액입니다.']}
+          slot={<SButton size="sm" color="secondary" label="이력" onClick={openHistory} />}
+        />
+        <SSectionHeaderCard.Body>
+          <SKeyValueTable fields={priceFields} values={product} />
+        </SSectionHeaderCard.Body>
+      </SSectionHeaderCard>
+
+      {/* 액션은 하단 — 목록(되돌리기)은 왼쪽 끝, 실행 액션은 오른쪽 끝 */}
+      <div className="flex items-center justify-between">
+        <SButton color="secondary" label="목록" onClick={goList} />
+        <div className="flex items-center gap-8">
+          <SButton color="danger" outline label="삭제" onClick={confirmDelete} />
+          <SButton label="수정" onClick={goEdit} />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### 4-5. 섹션 카드 — SSectionHeaderCard
+
+폼 페이지에서도 입력 항목이 많으면 유형별로 `SSectionHeaderCard` 로 나눈다. 주요 옵션:
+
+| Prop (Header) | 용도 |
+| --- | --- |
+| `title` | 섹션 제목 (필수) |
+| `marker` | 제목 앞 점 표시 |
+| `required` | 제목 뒤 필수(\*) 표시 — 필수 입력 섹션에 |
+| `helpText` | 도움말 툴팁 (`string[]`) |
+| `subtitle` | 부제 |
+| `slot` | 헤더 우측 영역 (버튼 등) |
+| `thickness` | 상단 강조선 — `false`(기본) / `'default'` / `'accent'` |
+
+---
+
+## 5. 자가 점검 체크리스트
+
+페이지를 완성하면 다음을 확인한다. 하나라도 어기면 수정 후 완료를 보고한다.
+
+- [ ] 생 HTML 컨트롤(`<button>` `<input>` `<select>` `<table>` …)이 없는가
+- [ ] `text-[14px]`, `bg-[#...]` 같은 리터럴 임의 값이 없는가 (`var(--sys-*)` 참조는 허용)
+- [ ] 텍스트에 `typo-*` 프리셋을 썼는가
+- [ ] 간격이 전부 토큰 스케일 값인가 (`gap-13` ❌ → `gap-12` ✅)
+- [ ] 본문이 12px(`typo-body-sm-default`)이고 보조 설명이 `text-fg-tertiary` 인가 (14px 본문 ❌)
+- [ ] 페이지 패딩이 `p-20`, 블록·섹션 간격이 `gap-12` 인가 (`gap-16`/`gap-24` ❌)
+- [ ] 같은 컴포넌트를 나열할 때 §2-2 그룹 간격을 썼는가 (체크박스 가로 `gap-24` 등)
+- [ ] 페이지가 §4의 표준 골격에서 시작했는가
+- [ ] 필터·폼·상세 정보를 `SKeyValueTable` 로 만들었는가 (컨트롤을 `div` 로 나열하지 않았는가)
+- [ ] 섹션 구분에 `SSectionHeaderCard` 를 썼는가 (직접 만든 카드가 아니라)
+- [ ] 목록의 주요 액션이 `STableBar` 의 `rightActions` 에 있는가 (페이지 제목 줄이 아니라)
+- [ ] 상태 표시에 `STag size="sm"` 을 썼는가
+- [ ] 테이블의 숫자 컬럼(금액·수량·개수 등)이 전부 `align: 'right'` 인가
+- [ ] 화면에 표시하는 모든 숫자에 `toLocaleString()` 을 써서 세 자리 콤마를 넣었는가
+- [ ] 금액·수량 등 양을 나타내는 숫자에 `toLocaleString()` 을 썼는가 (번호·코드는 제외)
+- [ ] 하단 버튼이 양끝 분리(`justify-between`)이고, 되돌리기가 왼쪽 끝 · 실행이 오른쪽 끝인가
+- [ ] 삭제 등 파괴적 액션에 `color="danger"` 를 썼는가
+- [ ] 작업용 모달을 `SActionModal` + `SModal.create` 로 만들었는가 (직접 오버레이 ❌)
+- [ ] 상태 표시·알림·확인 다이얼로그가 §3의 선택 규칙을 따르는가
+
+---
+
+## 6. 린트로 강제되는 규칙
+
+위 규칙 중 일부는 소비 앱의 ESLint 로 검출된다 (`sellmate-design-system-react/eslint`).
+**코드를 넘기기 전에 린트를 통과시킨다.**
+
+| 규칙 | 잡히는 것 |
+| --- | --- |
+| `sellmate/no-raw-html-control` | §1-1 생 HTML 컨트롤, `alert()`/`confirm()` |
+| `sellmate/no-arbitrary-class` | §1-2 토큰 있는 속성의 임의 값 (`text-[14px]`, `bg-[#eee]`) |
+| `sellmate/no-off-scale-spacing` | §2-2 스케일 밖 간격 (`gap-13`) |
+| `sellmate/table-numeric-align` | §3-4 숫자 컬럼의 `align: 'right'` 누락 (`--fix` 지원) |
+| `sellmate/require-locale-number` | §1-4 숫자 컬럼의 `toLocaleString()` 누락 |
+| `sellmate/component-group-gap` | §2-2 컴포넌트 그룹 간격 (체크박스 가로 24 / 세로 8 등) |
+| `sellmate/require-locale-number` | §1-4 금액·수량 등의 `toLocaleString()` 누락 |
+| `sellmate/prefer-typo-preset` | §1-3 낱개 폰트 조합 (`text-14 font-bold`) |
+
+`gap-13` 처럼 스케일 밖 값은 Tailwind v4 에서 **에러 없이 조용히 무시된다**. "간격이 왜 안 먹지" 로만 보이므로 반드시 스케일 값을 쓴다.
+
+린트가 잡지 못하는 것(§3 컴포넌트 선택, §4 페이지 골격, 버튼 배치)은 §5 체크리스트로 직접 확인한다.