@hjmds/design-contracts 1.12.0 → 1.13.0

package/docs/usage/components/spinner.md

@@ -0,0 +1,86 @@
+# Spinner
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/component-recipes.ts`(`spinnerRecipe`)
+- 스토리북: `배포/컴포넌트/상태와 알림/로딩 표시`
+
+## 언제 쓰나
+
+진행량을 모르고 도착할 내용의 모양도 정해지지 않은 **짧은 대기**를 한 자리에서 알릴 때 쓴다.
+패널 하나를 다시 불러오는 동안, 작은 영역의 결과를 기다리는 동안이 여기에 속한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 도착할 목록·카드의 모양을 알고 있음 | [Skeleton](skeleton.md) |
+| 진행량을 알거나 긴 작업(업로드·내보내기) | [Progress](progress.md) |
+| 버튼을 누른 뒤의 처리 중 | [Button](button.md)의 `loading`(같은 자리에 Spinner를 겹치지 않는다) |
+| 목록 끝에서 다음 페이지 | [LoadMore](load-more.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Spinner` | 기본 | `@hjmds/react`, `/feedback` | `@hjmds/react-native`, `/feedback` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Spinner } from "@hjmds/react/feedback";
+
+<Spinner label={t("feed.loading")} />
+```
+
+```tsx
+// Native
+import { Spinner } from "@hjmds/react-native/feedback";
+
+<Spinner label={t("feed.loading")} size="large" />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | — (필수) | 화면에는 보이지 않고 보조기기에만 읽힌다 |
+| `size`(Web) | `small` · `medium` · `large` | `medium` | — |
+| `tone`(Web) | `brand` · `neutral` · `inverse` | `brand` | — |
+| `size`(Native) | `small` · `large` | `small` | 플랫폼 `ActivityIndicator`를 테마 `contentBrand` 색으로 그린다. `tone`은 없다 |
+| `layoutStyle` | `HjmCompositionStyleProp`(margin·width·flex 계열·`alignSelf`) | — | 루트 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle` 또는 `size`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Web `small` 14 · `medium` 20(기본) · `large` 28(`glyph.xs`·`glyph.sm`·`glyph.lg`, 테두리 `stroke.strong` 2). Native는 플랫폼 `ActivityIndicator`의 `small`(기본)·`large`이고 HJM 숫자를 쓰지 않는다 | `spinnerRecipe`, `styles.css` `.hjm-spinner`·`.hjm-spinner__glyph`, `react-native/src/feedback.tsx` |
+| 간격 | — | — |
+| 순서·정렬 | 기다리는 영역의 가운데에 하나만 둔다. Web·Native 모두 루트가 가운데 정렬(`align-items`·`justify-content: center`)이므로 부모가 영역 크기를 잡아 주면 된다. 화면 전체 대기는 `large`, 카드·행 안의 대기는 `small` | `styles.css` `.hjm-spinner`, `react-native/src/feedback.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | — | — |
+
+버튼 안 대기는 Spinner를 겹치지 않고 [Button](button.md)의 `loading`을 쓴다.
+
+## 꼭 지킬 것
+
+- `label`은 i18n 키로 넣고 "무엇을" 기다리는지 적는다("불러오는 중"만 반복하지 않는다).
+- 한 영역에 Spinner는 하나다. 목록 행마다 Spinner를 두면 대신 Skeleton을 쓴다.
+- 대기가 끝나면 Spinner를 결과(내용·[EmptyState](empty-state.md)·오류)로 바꾼다.
+- 색은 Web `tone`과 테마로만 바꾼다. 어두운 배경 위에서는 `tone="inverse"`를 쓴다.
+- 배치(바깥 여백·정렬)는 `layoutStyle`로만 한다. Native `style`은 쓰지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 역할 | `role="status"`, `aria-live="polite"` | `accessibilityRole="progressbar"`, `busy: true` |
+| 크기 | 3단계 | `small`·`large` 2단계 |
+| tone | 있음 | 없음(항상 brand 색) |
+| reduced motion | 회전 멈춤(CSS) | 별도 처리 없음(`ActivityIndicator` 그대로) |
+| `style` | HTML 속성(`layoutStyle`과 합쳐지고 `layoutStyle`이 이김) | deprecated |

package/docs/usage/components/splitter.md

@@ -0,0 +1,103 @@
+# Splitter
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Splitter](../../splitter.md), `src/splitter.ts`(`splitterRecipe`)
+- 스토리북: `배포/컴포넌트/레이아웃/분할 영역 조절`
+
+## 언제 쓰나
+
+넓은 Web 화면에서 두 영역의 경계를 사용자가 드래그나 키보드로 옮겨 크기를 정할 때 쓴다.
+파일 트리/편집기 폭, 목록/상세 폭처럼 사용자가 정한 크기가 다시 방문해도 남길 바라는 레이아웃이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 개발자가 정한 고정 비율의 나란한 배치 | [Grid](grid.md), [Stack](stack.md) |
+| 옆에서 열고 닫는 보조 패널 | [SidePanel](side-panel.md), [Sidebar](sidebar.md) |
+| 패널 접기(collapse), 분리선 여러 개 | 없음(계약이 넣지 않았다) |
+| 범위 안의 값 하나 고르기 | [Slider](slider.md) |
+| Native 화면 | 없음 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Splitter` | 기본 | `@hjmds/react`, `/splitter` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Splitter } from "@hjmds/react/splitter";
+
+<Splitter
+  label={t("editor.resizeTree")}
+  min={15}
+  max={60}
+  step={5}
+  value={treeWidth}
+  onValueChange={setTreeWidth}
+  onValueChangeEnd={persistTreeWidth}
+  getValueText={(v) => t("editor.percent", { value: v })}
+  primaryPane={<FileTree />}
+  secondaryPane={<Editor />}
+/>
+```
+
+Native: 없음.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label`·`min`·`max`·`primaryPane`·`secondaryPane` | — | — (필수) | — |
+| `step` | `number` | `1` | — |
+| `axis` | `horizontal` · `vertical` | `horizontal` | `horizontal`은 패널이 좌우로 나란하고 분리선이 세로, `vertical`은 위아래 |
+| `value`/`defaultValue` | `number` | 둘 다 없으면 `min` | `primaryPane`이 값만큼, `secondaryPane`이 나머지를 차지한다 |
+| `onValueChange` | `(value: number) => void` | — | 드래그 중 매번 |
+| `onValueChangeEnd` | `(value: number) => void` | — | 드래그를 놓을 때와 값이 실제로 바뀐 키보드 step마다 한 번 |
+| `getValueText` | `(value: number) => string` | — | 분리선의 `aria-valuetext`. 없으면 숫자만 읽힌다 |
+| `disabled` | `boolean` | `false` | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치(margin·width·flex 계열·`alignSelf`) |
+| `className`, `style` | `string`, `CSSProperties` | — | 루트에 붙는다. `style`과 `layoutStyle`이 겹치면 `layoutStyle`이 이긴다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | `primaryPane`이 값만큼 고정 폭(`flex: 0 0`), `secondaryPane`이 나머지를 채운다. 분리선은 보이는 선 1(`stroke.default`, `border` 색), 잡는 영역 44(`control.minTouchTarget`) | `splitterRecipe.separator`, `styles.css` `.hjm-splitter*`, `react/src/splitter.tsx` |
+| 간격 | 패널 사이 간격은 분리선의 44 영역이 대신하므로 패널에 따로 바깥 여백을 더하지 않는다 | `styles.css` `.hjm-splitter__separator` |
+| 순서·정렬 | 넓은 Web 화면의 본문 영역을 둘로 나눈다. `horizontal`은 primary가 시작(왼쪽), `vertical`은 위 | `styles.css` `.hjm-splitter` |
+| 고정·스크롤 | 두 패널은 각자 스크롤한다(`overflow: auto`). 부모가 높이를 정해야 세로 스크롤이 생긴다. 내용이 넘칠 때만 그 패널이 Tab 정지점(`tabIndex=0`)이 되어 키보드로 스크롤할 수 있고, 넘치지 않으면 정지점이 없다 | `styles.css` `.hjm-splitter__pane`, `splitter.tsx` `useScrollableTabStop` |
+| 좁은 폭·큰 글자 | `min`은 좁은 쪽 패널 내용이 깨지지 않는 폭으로 정한다. 폭이 `breakpoint.medium`(600) 아래인 화면에서는 Splitter를 그리지 말고 [Stack](stack.md)으로 위아래로 쌓거나 한 패널만 보인다(HJM은 자동 전환하지 않는다) | `foundations.ts` `breakpoint` |
+
+```text
+axis="horizontal"(기본)
+┌──────────────┬┬──────────────────────────┐
+│ primaryPane  ││ secondaryPane            │
+│ (값만큼 고정)││ (나머지, 각자 스크롤)     │
+│              ││                          │
+└──────────────┴┴──────────────────────────┘
+               └┘ 분리선: 선 1 · 잡는 영역 44
+```
+
+## 꼭 지킬 것
+
+- 크기 저장은 `onValueChangeEnd`에서 한다. 경계값에서 더 누른 키는 end를 보내지 않는다.
+- `label`과 `getValueText`는 i18n 문구로 준다. 단위(%·px) 표현은 제품 소유다.
+- 분리선 두께·44px hit target·핸들 모양은 HJM 소유다. 배치는 `layoutStyle`로 하고 분리선을 덮지 않는다.
+- 좁은 화면(모바일 Web)에서 쓸지는 제품이 판단한다. 계약은 데스크톱 패턴으로 정의한다.
+
+## 함정
+
+- 키보드는 pane 축 방향키만 쓴다(가로면 좌/우, 세로면 위/아래). 다른 방향키와 PageUp/PageDown은 pane 콘텐츠의 것이다.
+- 패널의 Tab 정지점은 넘침에 따라 생기고 사라진다(ResizeObserver·MutationObserver로 다시 잰다). 테스트에서 패널 `tabIndex`를 고정값으로 기대하지 않는다.
+  패널에는 접근성 이름이 없다(이름 prop은 breaking 변경이라 두지 않았다, `splitter.tsx` 주석). 미게시(1.12.1 이후) 변경이며 1.12.1까지는 패널이 포커스를 받지 않았다.
+- RTL에서는 ArrowLeft가 increment다. 드래그 거리도 같은 기준으로 잰다.
+- primary pane 폭은 `value`가 아니라 `(value-min)/(max-min)` 비율로 그려진다. `value=min`이면 primary pane이 0%, `max`면 100%다.
+  예를 들어 `min=15, max=60, value=30`은 33%로 그려진다. 원하는 실제 폭 범위에 맞춰 `min`/`max`를 정하고 화면에서 확인한다.

package/docs/usage/components/stack.md

@@ -0,0 +1,93 @@
+# Stack
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Flex·Space와의 관계](../../layout-primitives.md), `src/component-recipes.ts`(`stackRecipe`)
+- 스토리북: `배포/컴포넌트/레이아웃/가로·세로 배치`
+
+## 언제 쓰나
+
+자식들을 한 방향으로 늘어놓고 사이 간격을 토큰으로 맞출 때 쓴다. 폼 필드 세로 나열, 버튼 두 개의
+가로 배치, 카드 안 제목·설명 묶음이 여기에 속한다. antd `Flex`·`Space`에 해당하는 자리도 Stack이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 2차원 열·반응형 칸 | [Grid](grid.md) |
+| 높이가 제각각인 카드 벽 | [Masonry](masonry.md) |
+| 콘텐츠 최대 폭·좌우 여백 | [Container](container.md) |
+| 배경·테두리·radius가 있는 상자 | [Surface](surface.md), [Card](card.md) |
+| 항목 사이 구분선 | Stack 안에 [Divider](divider.md) |
+| 헤더·사이드바·본문 화면 골격 | [Layout](layout.md) |
+| 제목이 있는 본문 묶음 | [Section](section.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Stack` | 기본 | `@hjmds/react`, `/layout` | `@hjmds/react-native`, `/primitives` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { Stack } from "@hjmds/react/layout";
+
+<Stack axis="inline" gap="xs" justify="end">
+  <Button tone="secondary" onClick={cancel}>{t("common.cancel")}</Button>
+  <Button onClick={save}>{t("common.save")}</Button>
+</Stack>
+```
+
+```tsx
+// Native
+import { Heading } from "@hjmds/react-native/heading";
+import { Stack, Text } from "@hjmds/react-native/primitives";
+
+<Stack gap="sm">
+  <Heading level="level4" semanticLevel={2}>{t("profile.title")}</Heading>
+  <Text tone="muted">{t("profile.description")}</Text>
+</Stack>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `axis` | `block` · `inline` | `block` | `block` 세로, `inline` 가로 |
+| `gap` | `xxs`(4) · `xs`(8) · `sm`(12) · `md`(16) · `lg`(20) · `xl`(24) · `xxl`(32) · `xxxl`(40) | `md` | spacing 토큰 |
+| `align` | `start` · `center` · `end` · `stretch` | `stretch` | — |
+| `justify` | `start` · `center` · `end` · `between` | `start` | — |
+| `wrap` | `boolean` | `false` | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | Stack 자신의 바깥 여백·폭·flex·`alignSelf` |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | — | — |
+| 간격 | 형제 사이 간격만 정한다. 화면 섹션 사이 `xl` 24(`layout.sectionGap`), 섹션 안 내용 사이 `md` 16(`layout.contentGap`, 기본), 관련 묶음(라벨과 값, 나란한 버튼) `sm` 12·`xs` 8. 이 밖의 숫자를 새로 만들지 않는다. 바깥 여백은 부모(화면 여백 `layout.pagePadding` compact 16 · regular 20 · spacious 24)가 정한다 | `stackRecipe`, `foundations.ts` `layout` |
+| 순서·정렬 | 가로로 버튼을 나열할 때 주 행동 순서는 [Button](button.md#배치)을 따른다 | — |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 가로(`axis="inline"`)로 버튼·칩을 나열해 좁은 폭에서 넘치면 `wrap`을 켠다 | `stackRecipe.defaults.wrap` |
+
+## 꼭 지킬 것
+
+- 간격은 `gap` 토큰으로만 정한다. 자식마다 margin을 붙여 간격을 만들지 않는다.
+- Stack 자체의 배치(바깥 여백·폭·flex)는 `layoutStyle`로 한다. Stack은 배경·테두리를 갖지 않으므로
+  상자가 필요하면 Surface로 감싼다.
+- 시각 순서는 DOM/자식 순서와 같게 둔다. 순서를 뒤집는 CSS로 읽기 순서를 바꾸지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `gap` 타입 | 토큰만 | 토큰 또는 숫자 |
+| 방향 | CSS 상속 | provider `environment.direction`을 `direction`으로 적용 |
+| import 경로 | `/layout` | `/primitives` |
+| ref | `forwardRef`(`div`) | 없음 |

package/docs/usage/components/statistic.md

@@ -0,0 +1,123 @@
+# Statistic
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Statistic](../../statistic.md), [optional adapters](../../optional-adapters.md), `src/component-recipes.ts`(`statisticRecipe`)
+- 스토리북: `배포/컴포넌트/데이터 표시/수치 표시`, `배포/컴포넌트/데이터 표시/움직이는 수치`
+
+## 언제 쓰나
+
+라벨이 붙은 **숫자 지표 하나**(또는 여러 개)를 보여 줄 때 쓴다. 오늘 기록 수, 승률, 잔액,
+전주 대비 증감처럼 값·단위·추세·보조 설명이 한 묶음인 자리다. 여러 지표를 나란히 두면 `StatisticGroup`을 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 항목 이름과 값이 짝인 속성 목록(숫자가 주인공이 아님) | [DescriptionList](description-list.md) |
+| 진행률·완료 비율 | [Progress](progress.md) |
+| 아이콘·탭 옆의 작은 개수 | [CounterBadge](counter-badge.md), [Badge](badge.md) |
+| 행·열이 있는 수치 표 | [DataTable](data-table.md) |
+| 기간별 활동 밀도 | [ActivityHeatmap](activity-heatmap.md) |
+| 누르면 이동하는 지표 | 바깥을 [Link](link.md)·[Button](button.md)으로 감싼다(Statistic은 interactive하지 않다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Statistic` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+| `StatisticGroup` | 동반(1~4열 묶음) | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+| `AnimatedStatistic` | 확장(값 변화 모션, optional-extension) | `/statistic-motion` | `/statistic-motion` |
+
+`AnimatedStatistic`은 granular subpath로만 import 된다. Web은 optional peer `@number-flow/react` 0.6.2를
+앱에 설치해야 한다. Native는 추가 peer 없이 HJM `ContentTransition`(RN `Animated`)으로 전체 지표를 전환한다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { StatisticGroup } from "@hjmds/react/display";
+
+<StatisticGroup
+  label={t("stats.weekly")}
+  descriptor={{
+    columns: 2,
+    items: [
+      { id: "letters", label: t("stats.letters"), value: formatNumber(sent), suffix: t("stats.unitLetters") },
+      {
+        id: "streak", label: t("stats.streak"), value: formatNumber(streak),
+        trend: { direction: "up", tone: "success", label: t("stats.trendUp") },
+      },
+    ],
+  }}
+/>
+```
+
+```tsx
+// Native
+import { Statistic } from "@hjmds/react-native/data-display";
+
+<Statistic
+  presentation="surface"
+  descriptor={{ id: "balance", label: t("wallet.balance"), value: formatCurrency(balance) }}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor` | `id`·`label`·`value`(포맷이 끝난 문자열) 필수, `prefix`·`suffix`·`hint`·`trend` 선택 | — | 빈 문자열은 `TypeError` |
+| `trend.direction` | `up` · `down` · `flat` | — | — |
+| `trend.tone` | `neutral` · `success` · `warning` · `danger` | `neutral` | 보이는 `trend.label` 필수 |
+| `density` | `comfortable` · `compact` | `comfortable` | 값 크기 `heading` · `title` |
+| `presentation` | `plain` · `surface` | `plain` | `surface`는 테두리 상자 |
+| `columns`(`StatisticGroup`) | 1~4 | 3 | 폭이 좁거나 글자가 크면 renderer가 1열까지 줄인다 |
+| `value`(`AnimatedStatistic`) | 유한한 숫자 | — (필수) | `locale` 필수, `format`(`Intl.NumberFormatOptions`) |
+| `animated`(`AnimatedStatistic`) | `boolean` | `true` | — |
+| `contextLabel` | `string` | — | 접근성 이름 앞에 붙는 맥락. `StatisticGroup`은 group `label`을 넘긴다 |
+| `composeAccessibilityLabel` | `(input: { contextLabel?, descriptor, valueText }) => string` | 기본 어순 | `descriptor`는 trend tone 기본값이 채워진 descriptor, `valueText`는 prefix·value·suffix를 이은 문자열 |
+| `renderTrendMark` | `(props: { name: "trendUp" \| "trendDown" \| "trendFlat", color, size }) => ReactNode` | 내장 표시 | 추세 아이콘을 제품 아이콘으로 바꾼다. `color`는 Web `"currentColor"`, Native trend tone 색 |
+| `renderValue`(Web) | `(value: string) => ReactNode` | — | 보이는 값만 바꾼다. 접근성 값은 descriptor 그대로 |
+| `availableWidth`(Native `StatisticGroup`) | `number` | 측정 폭 | 열 수 계산에 쓸 폭 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치. Web·Native 모두 |
+| Native `style`·`labelStyle`·`valueStyle`·`affixStyle`·`trendStyle`·`hintStyle`, 그룹 `style`·`itemStyle` | `StyleProp` | — | deprecated — `layoutStyle` 또는 `density`·`presentation`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | `presentation="surface"`의 안쪽 여백: `comfortable` `spacing.md` 16 · `compact` `spacing.sm` 12(두 플랫폼). 테두리 `stroke.default` 1, radius `md` 12 | `statisticRecipe.density`·`presentations`, `styles.css` `.hjm-statistic[data-presentation="surface"]` |
+| 글자 | 라벨 `label` 12 semibold(`compact` `caption` 11), 값 `heading` 24 heavy(`compact` `title` 18), prefix·suffix `body` 14 semibold 본문색, hint `caption`, 추세 `caption` bold(두 플랫폼). 2026-10-06까지 Web은 라벨 본문 14 medium, 값은 밀도와 관계없이 18, prefix·suffix는 흐린색이었다(1.12.1 이후 미게시) | `statisticRecipe.density`·`label`·`value`·`affix`·`hint`·`trend`, `.hjm-statistic__*` |
+| 간격 | 그룹 간격 `statisticRecipe.group.gap` = `spacing.xs` 8. 지표 안 줄 간격(라벨·값·추세) `comfortable` `spacing.xs` 8 · `compact` `spacing.xxs` 4(두 플랫폼) | `styles.css` `.hjm-statistic`·`.hjm-statistic-group`, `statisticRecipe` |
+| 순서·정렬 | 화면 위쪽 요약 영역이나 카드 안에 둔다. 지표 여러 개는 [Grid](grid.md)를 직접 짜지 말고 `StatisticGroup`으로 묶는다 | — |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 그룹 열 수 `columns`(1~4, 기본 3). Web은 폭 600 미만(`breakpoint.medium`)에서 1열. Native는 항목 폭이 120×글자 배율(`statisticRecipe.group.minItemWidth`) 아래면 열을 줄인다. 값은 줄바꿈된다(자르지 않음). 긴 통화 값이 들어갈 칸이면 열 수를 줄인다 | `styles.css` `@media (max-width: 599.98px)`, `react-native/src/data-display.tsx` |
+
+## 꼭 지킬 것
+
+- 숫자·통화·단위 포맷은 제품이 한다. HJM은 계산·포맷하지 않고 받은 `value` 문자열을 그대로 그린다.
+- 모든 문구(label·trend label·hint·group label)는 i18n 키로 넣는다. 추세는 색만으로 알리지 않는다.
+- `direction`과 `tone`은 따로 정한다. 증가가 나쁜 지표는 `up` + `danger`다([계약](../../statistic.md)).
+- 접근성 이름은 기본으로 `[contextLabel, label, 값, trend label, hint]`를 이어 만든다. 어순을 바꿔야 하면
+  `composeAccessibilityLabel`을 쓴다. `StatisticGroup`은 group `label`을 각 항목의 `contextLabel`로 넘긴다.
+- 배치는 `layoutStyle`로만 한다. Native의 deprecated `style`·`*Style`·`itemStyle`로 recipe 색·굵기를 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 값 렌더 교체 | `renderValue`(접근성 값은 descriptor 유지) | 없음 |
+| 그룹 폭 | CSS grid, 좁은 화면에서 1열 | `availableWidth` 또는 측정 폭, 최소 항목 폭 120×글자 배율로 열 수 감소 |
+| 슬롯 스타일 prop | 없음(`className`, 배치는 `layoutStyle`) | `style`·`*Style`, 그룹 `itemStyle`(모두 deprecated, 배치는 `layoutStyle`) |
+| `AnimatedStatistic` 모션 | 숫자 자리 단위 NumberFlow | 지표 전체 `rise` 전환 |
+| `renderTrendMark` color | `"currentColor"` | trend tone을 푼 색 문자열 |
+
+## 함정
+
+- Web `AnimatedStatistic`은 reduced motion, RTL, 라틴 숫자가 아닌 numbering system, `ar`·`fa`·`he`·`ur` locale,
+  `scientific`·`engineering` 표기에서는 애니메이션 없이 `Intl` 결과 문자열만 그린다.
+- `AnimatedStatistic`의 `descriptor`에는 `value`를 넣지 않는다. 값은 `value` prop의 숫자로 받는다.

package/docs/usage/components/steps.md

@@ -0,0 +1,110 @@
+# Steps
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Steps](../../steps.md), [StepPlayer](../../step-player.md), `src/steps.ts`(`stepsRecipe`)
+- 스토리북: `배포/컴포넌트/탐색/단계 탐색`, `배포/컴포넌트/상태와 알림/단계별 진행 표시`
+
+## 언제 쓰나
+
+여러 단계로 된 **선형 흐름에서 지금 어디인지** 보여 줄 때 쓴다. 온보딩(환영 → 구단 → 알림 → 완료),
+가입·주문 처리 단계가 여기에 속한다. 읽기 전용이며 단계를 눌러 이동하지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 단계 이름 없이 진행률만 | [Progress](progress.md) |
+| 시간 순 사건 기록 | [Timeline](timeline.md) |
+| 같은 수준의 화면 사이 이동 | [Tabs](tabs.md), [SegmentedControl](segmented-control.md) |
+| 페이지 번호 이동 | [Pagination](pagination.md) |
+| 화면을 가리키며 하는 기능 안내 | [Tour](tour.md) |
+| 흐름이 끝난 뒤의 결과 | [Result](result.md) (또는 `currentStepStatus: "complete"`) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Steps` | 기본 | `@hjmds/react`, `/navigation`, `/steps` | `@hjmds/react-native`, `/steps` |
+| `StepPlayer` | 확장(재생형 단계 소개, optional-extension) | `/step-player` | `/step-player` |
+
+`StepPlayer`는 granular subpath로만 import 된다. Steps·Progress·Button·Stack만 합성하므로 추가 peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Steps } from "@hjmds/react/steps";
+
+<Steps
+  descriptor={{
+    currentStepId: "team",
+    steps: [
+      { id: "welcome", label: t("onboarding.welcome") },
+      { id: "team", label: t("onboarding.team") },
+      { id: "alerts", label: t("onboarding.alerts") },
+    ],
+  }}
+  statusLabels={{
+    pending: t("steps.pending"), current: t("steps.current"),
+    complete: t("steps.complete"), error: t("steps.error"),
+  }}
+  composeAccessibleName={({ position, total, label }) => t("steps.name", { position, total, label })}
+/>
+```
+
+```tsx
+// Native — props가 같다
+import { Steps } from "@hjmds/react-native/steps";
+
+<Steps descriptor={descriptor} statusLabels={statusLabels} composeAccessibleName={composeStepName} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor.currentStepId` | 단계 `id` | — (필수) | 상태는 단계별로 넘기지 않는다. 앞은 `complete`, 커서는 지정 상태, 뒤는 `pending`이 유도된다 |
+| `descriptor.currentStepStatus` | `current` · `error` · `complete` | `current` | 커서 단계의 상태 |
+| `descriptor.steps` | 단계 배열 | — (필수) | 2개 이상, `id`는 고유하고 앞뒤 공백이 없어야 한다. 어기면 `RangeError`/`TypeError` |
+| `descriptor.steps[]` | `{ id, label, description? }` | — | — |
+| `statusLabels` | `{ pending, current, complete, error }`(모두 `string`) | — (필수) | 상태를 읽는 문구 |
+| `composeAccessibleName` | `(info: { position: number, total: number, label: string }) => string` | — (필수) | `position`은 1부터 |
+| `renderMark` | `(status: StepStatus, position: number) => ReactNode` | `✓`·`!`·번호 | 원 안 표시를 바꾼다 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+| `StepPlayer` `progress`·`playing` | `number`(0~1)·`boolean` | — (필수) | 호스트 소유 |
+| `StepPlayer` `onPlayingChange`·`onReplay` | `(playing: boolean) => void`·`() => void` | — (필수) | 재생/일시정지·다시 보기 요청 |
+| `StepPlayer` `labels` | `{ play, pause, replay, progress }` | — (필수) | — |
+
+방향·clickable·variant 축은 없다(계약에서 배제). 항상 가로 한 줄이다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 단계마다 같은 폭(`minmax(0, 1fr)`, Native `flex: 1`). 원(indicator) 24(`glyph.md`), 연결선 1(`stroke.default`), 현재·오류 단계의 원 테두리 2(`stroke.strong`) | `stepsRecipe`, `styles.css` `.hjm-steps*`, `react-native/src/steps.tsx` |
+| 간격 | 단계 사이·원과 글자 사이 `spacing.xs` 8(`stepsRecipe.gap`) | `stepsRecipe.gap` |
+| 순서·정렬 | 흐름 화면의 맨 위(TopBar 아래, 본문 위)에 가로 한 줄. 화면 아래 행동 버튼과 떨어뜨리고 탭처럼 누르게 두지 않는다 | — |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 라벨·설명은 줄바꿈된다(`overflow-wrap: anywhere`). 좁은 폭에서 라벨이 세 줄 이상이 되면 라벨을 줄이거나 [Progress](progress.md)로 바꾼다. 세로 배치 축은 없다 | `styles.css` `.hjm-steps__label` |
+
+## 꼭 지킬 것
+
+- `statusLabels` 네 개와 `composeAccessibleName`은 필수다. "3단계 중 2단계" 같은 어순은 제품이 i18n으로 조립한다.
+- 이전 단계로 가는 행동은 Steps 밖의 [Button](button.md)으로 둔다.
+- `StepPlayer`는 타이머가 없다. `progress`(0~1)·`playing`·커서를 호스트가 소유하고, `onPlayingChange`·`onReplay`에서
+  직접 상태를 바꾼다. `labels`(`play`·`pause`·`replay`·`progress`)는 비면 `TypeError`, `progress`가 범위를 벗어나면 `RangeError`다.
+- 실제 비동기 작업의 완료를 `StepPlayer` 시계로 추정하지 않는다([계약](../../step-player.md)).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 구조 | `<ol>`, 현재 단계 `aria-current="step"`, 상태 문구는 숨은 텍스트 | `accessibilityRole="summary"`, 단계마다 이름 + `accessibilityHint`에 상태 문구 |
+| 스타일 | `className`·`style`(HTML 속성), 배치는 `layoutStyle` | 배치는 `layoutStyle`(`style`은 deprecated) |
+| ref | `forwardRef`(`ol`) | 없음 |
+| import 경로 | root, `/navigation`, `/steps` | root, `/steps`(`/navigation` 없음) |

package/docs/usage/components/surface.md

@@ -0,0 +1,91 @@
+# Surface
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/base-recipes.ts`(`surfaceRecipe`·`surfaceDefaults`·`surfaceGeometry`)
+- 스토리북: `배포/컴포넌트/레이아웃/배경 영역`
+
+## 언제 쓰나
+
+배경·테두리·radius를 가진 **의미 없는 상자**가 필요할 때 쓴다. 다른 컴포넌트로 표현되지 않는
+패널, 요약 영역, 이미지를 둥근 모서리 안에 자르는 틀이 여기에 속한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 제목·본문·행동이 있는 콘텐츠 카드, 누르는 카드 | [Card](card.md) |
+| 간격만 필요하고 상자는 필요 없음 | [Stack](stack.md) |
+| 상태·경고를 알리는 상자 | [Notice](notice.md) |
+| 설정·목록 행 | [ListRow](list-row.md), [List](list.md) |
+| 화면 위에 뜨는 층 | [Sheet](sheet.md), [Dialog](dialog.md), [Popover](popover.md) |
+| 콘텐츠 최대 폭·좌우 여백 | [Container](container.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Surface` | 기본 | `@hjmds/react`, `/layout` | `@hjmds/react-native`, `/primitives` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Surface } from "@hjmds/react/layout";
+
+<Surface as="section" padding="md" aria-label={t("order.summary")}>
+  {children}
+</Surface>
+```
+
+```tsx
+// Native
+import { Surface } from "@hjmds/react-native/primitives";
+
+<Surface tone="raised" padding="md" layoutStyle={{ marginTop: 16 }}>
+  {children}
+</Surface>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tone` | `default` · `raised` · `sunken` · `accent` · `subtle` | `default` | `raised`는 그림자, `accent`는 primary 색 테두리. 모든 tone의 배경은 테마 `bg`이고 회색 채움 대신 테두리·그림자로 위계를 나타낸다 |
+| `padding` | `none` 또는 spacing 토큰(`xxs`~`xxxl`) | `none` | — |
+| `radius` | `sm` · `md` · `lg` · `xl` · `full` | `lg`(16) | — |
+| `bordered` | `boolean` | 생략 시 테두리 그림 | 모든 tone이 `borderAlways`. `bordered={false}`로만 끈다 |
+| 자식 자르기 | — | `raised` 외 자름 | `raised`를 뺀 tone은 둥근 모서리 밖으로 넘친 자식을 자른다. `raised`는 그림자가 잘리지 않게 자르지 않는다 |
+| `as`(Web) | `div` · `section` · `article` | `div` | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | Surface 자신의 바깥 여백·폭·flex·`alignSelf`. Web·Native 모두 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭은 부모를 따르고 높이는 내용이 정한다. 기본 radius `lg` 16, 테두리 1(`border` 색) | `styles.css` `.hjm-surface`, `surfaceRecipe` |
+| 간격 | 기본 `padding`이 `none`이므로 안쪽 여백을 꼭 준다. 카드 안 내용은 `md` 16, 촘촘한 묶음은 `sm` 12. 여러 Surface를 세로로 쌓을 때는 [Stack](stack.md)으로 `md` 16(같은 묶음) 또는 `xl` 24(섹션 사이) | `surfaceDefaults`, `foundations.ts` `layout` |
+| 순서·정렬 | 화면 여백 안에 놓는 카드·묶음 상자다. Surface 안에 Surface를 다시 겹치지 않고 안쪽 구분은 [Divider](divider.md)나 간격으로 한다 | — |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 긴 글자는 줄바꿈된다(`overflow-wrap: anywhere`) | `styles.css` `.hjm-surface` |
+
+## 꼭 지킬 것
+
+- 배치는 `layoutStyle`로만 한다. 배경·테두리 색·radius·그림자를 덮지 않는다.
+  색은 제품 테마 토큰이 정하고, Surface마다 브랜드 색을 하드코딩하지 않는다.
+- 안쪽 여백은 `padding` 토큰으로 정한다(기본이 `none`이라 내용이 테두리에 붙는다).
+- Surface는 role을 갖지 않는다. 영역에 이름이 필요하면 Web은 `as="section"`과 라벨을 함께 준다.
+- `raised` 안에 이미지를 넣으면 모서리가 잘리지 않는다. 모서리 자르기가 필요하면 다른 tone을 쓴다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `style` | 받음(`layoutStyle`이 이김) | 타입에서 제외 |
+| 요소 선택 | `as` | 없음(`View`) |
+| 그림자(`raised`) | CSS | `elevation: 4`와 iOS shadow |
+| ref | `forwardRef` | 없음 |
+| import 경로 | `/layout` | `/primitives` |