@hjmds/design-contracts 1.12.0 → 1.13.0

package/docs/usage/components/floating-action-button.md

@@ -0,0 +1,138 @@
+# FloatingActionButton
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [FloatingActionButton](../../floating-action-button.md), recipe `floatingActionButtonRecipe`(`src/floating-action-button.ts`)
+- 스토리북: `배포/컴포넌트/동작/플로팅 실행 버튼`
+
+## 언제 쓰나
+
+목록·피드처럼 스크롤되는 콘텐츠 위에 떠 있는 **단일 생성 행동**(새 기록 추가, 새 글 작성)에 쓴다.
+스크롤 방향에 따라 알약(라벨 보임)과 원(아이콘만)으로 접히지만 같은 버튼 인스턴스를 유지한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면의 결론이 되는 하단 고정 주 행동 | [BottomCTA](bottom-cta.md) ([판정](../../floating-action-button.md#bottomcta와-겹치지-않는다-판정)) |
+| 콘텐츠 안의 일반 행동 | [Button](button.md), [IconButton](icon-button.md) |
+| 하단 탭 가운데의 생성 버튼 | [BottomNavigation](bottom-navigation.md) 옆에 Button/IconButton 합성 |
+| 비활성·로딩 상태가 필요한 행동 | [Button](button.md) (FAB는 `disabled`·`loading`이 없다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `FloatingActionButton` | 기본 | `@hjmds/react`, `/floating-action-button` | `@hjmds/react-native`, `/floating-action-button` |
+| `useFloatingActionButtonScroll` | 보조 — 스크롤로 `layoutMode` 결정 | `/floating-action-button` | `/floating-action-button` |
+| `resolveFloatingActionButtonContentClearance` | 보조 — 첫 하단 여백 계산 | `/floating-action-button` | `/floating-action-button` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { useState } from "react";
+import { FloatingActionButton, useFloatingActionButtonScroll } from "@hjmds/react/floating-action-button";
+
+const layoutMode = useFloatingActionButtonScroll(); // window 스크롤. 컨테이너면 element, 마운트 전엔 null
+const [clearance, setClearance] = useState(0);
+
+<ul style={{ paddingBottom: clearance }}>{items}</ul>
+<FloatingActionButton
+  descriptor={{ icon: { name: "add" }, label: t("memo.new"), layoutMode }}
+  renderIcon={({ name, size, color }) => <ProductIcon name={name} size={size} color={color} />}
+  onContentClearanceChange={setClearance}
+  onClick={openComposer}
+/>
+```
+
+```tsx
+// Native
+import { useState } from "react";
+import { FlatList, View } from "react-native";
+import { FloatingActionButton, useFloatingActionButtonScroll } from "@hjmds/react-native/floating-action-button";
+
+const { layoutMode, onScroll } = useFloatingActionButtonScroll();
+const [clearance, setClearance] = useState(0);
+
+<View style={{ flex: 1 }}>
+  <FlatList data={items} renderItem={renderItem} onScroll={onScroll} contentContainerStyle={{ paddingBottom: clearance }} />
+  <FloatingActionButton
+    descriptor={{ icon: { name: "add" }, label: t("memo.new"), layoutMode }}
+    renderIcon={({ name, size, color }) => <ProductIcon name={name} size={size} color={color} />}
+    safeAreaBottomInset={insets.bottom}
+    onContentClearanceChange={setClearance}
+    onPress={openComposer}
+  />
+</View>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor.layoutMode` | `expanded` · `collapsed` | `expanded` | 직접 고르지 말고 `useFloatingActionButtonScroll` 결과를 넘긴다 |
+| `descriptor.label` | 문구(필수) | — | `collapsed`에서도 접근성 이름은 항상 전체 `label`이다 |
+| `descriptor.icon` | `{ name }` | — | `name`만 받는다(`size`·`tone`·접근성 이름은 넣을 수 없다). 아이콘은 항상 장식이다 |
+| `safeAreaBottomInset` | 0 이상 숫자 | `0` | — |
+| `renderIcon` | `(icon: { name: string; size: number; color: string; decorative: true }) => ReactNode` | 필수 | 제품 아이콘 시스템으로 그린다 |
+| `onContentClearanceChange` | `(clearance: number) => void` | 필수 | 스크롤 콘텐츠 하단 padding으로 쓴다. 큰 글자·inset이 바뀌면 다시 불린다 |
+| Web `onClick` · Native `onPress` | Button의 같은 이벤트 | — | — |
+
+- 톤·크기·모양은 `primary`·`large`·`pill`로 고정이고 prop이 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 높이·지름 52(IconButton `large`). `expanded`는 알약(아이콘 + 라벨, 라벨 좌우 여백 `spacing.lg` 20), `collapsed`는 지름 52 원이다. 최대 폭은 화면 폭 − 32(여백 양쪽)다 | `floating-action-button.ts` `floatingActionButtonRecipe`, `styles.css` `.hjm-fab` |
+| 간격 | 가장자리 여백 `spacing.md`(16). 하단 거리는 16 + 하단 안전 영역이다(Web은 `safeAreaBottomInset`과 `env(safe-area-inset-bottom)` 중 큰 값, Native는 `safeAreaBottomInset`). 스크롤 콘텐츠 하단에 `onContentClearanceChange` 값을 padding으로 둔다. 기본값은 52 + 16×2 + 하단 inset(= 84 + inset)이다 | `floating-action-button.ts` `resolveFloatingActionButtonContentClearance`, `styles.css` `.hjm-fab`, `react-native/src/floating-action-button.tsx` |
+| 순서·정렬 | 위치는 스크롤 영역의 **논리적 끝 쪽 하단 모서리**로 고정이다(RTL은 왼쪽) | `styles.css` `.hjm-fab`, `react-native/src/floating-action-button.tsx` |
+| 고정·스크롤 | Web은 `position: fixed`(z-index `layer.sticky` 100)로 창에 붙는다. Native는 positioned 부모(`flex: 1` View) 안에서 `absolute`다. [BottomNavigation](bottom-navigation.md)·도구막대 위에 띄울 때는 그 높이를 `safeAreaBottomInset`에 더한다(Native는 제품이 더한다) | `styles.css` `.hjm-fab`, `react-native/src/floating-action-button.tsx` |
+| 좁은 폭·큰 글자 | 큰 글자로 라벨이 여러 줄이 되면 clearance 값이 커진다 | `react-native/src/floating-action-button.tsx` |
+
+```text
+┌────────────────────────────┐
+│ TopBar (고정)               │
+├────────────────────────────┤
+│ 목록 (스크롤)                │
+│ ...                         │
+│ 마지막 항목                  │
+│ ← padding-bottom = clearance│
+│                ┌──────────┐ │
+│                │ + 새 기록 │ │ ← FAB expanded(52, primary pill)
+│                └──────────┘ │    끝 여백 16
+│                          16 │
+├────────────────────────────┤
+│ 안전 영역                    │
+└────────────────────────────┘
+스크롤해 내려가면 (+) 지름 52 원으로 접힌다.
+```
+
+## 꼭 지킬 것
+
+- `onContentClearanceChange`가 준 값을 스크롤 콘텐츠 하단 padding에 반드시 적용한다. 큰 글자에서
+  라벨이 여러 줄이 되면 값이 커진다. 지름만 예약하면 마지막 항목을 가린다.
+- 스크롤 콘텐츠 **뒤**의 sibling으로 둔다. 목록 항목 안에 넣지 않는다.
+- 라벨은 i18n 키로 넣는다. 아이콘 그림은 제품 아이콘 시스템이 `renderIcon`으로 그린다(HJM은 name·size·color만 준다).
+- 한 화면에 FAB는 하나만 둔다. 모서리 위치는 바꿀 수 없다(논리적 끝 쪽 하단, RTL은 왼쪽).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이벤트 | `onClick` | `onPress` |
+| 위치 | CSS(`.hjm-fab`) | positioned 부모 안 `absolute` |
+| 스크롤 hook | `useFloatingActionButtonScroll(target?)` → `layoutMode` | `useFloatingActionButtonScroll()` → `{ layoutMode, onScroll }` |
+| 여백 측정 | `ResizeObserver`·`resize` | `onLayout` |
+| 그 밖의 prop | `id`, `className`, `onFocus`, `onBlur` | `testID`, `onFocus`, `onBlur` |
+| ref | `HTMLButtonElement` | `View` |
+| 배치 prop | 없음(`layoutStyle`을 받지 않는다. 위치는 CSS가 소유) | 없음(`layoutStyle`·`style` 없음) |
+
+## 함정
+
+- 모드마다 Button과 IconButton을 바꿔 끼우면 focus와 ref를 잃는다. 이 컴포넌트 하나로 접고 편다.
+- Native `safeAreaBottomInset`은 OS 하단 inset만이다. 화면 안 도구막대 높이는 제품이 따로 더한다.

package/docs/usage/components/form.md

@@ -0,0 +1,162 @@
+# Form
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Form](../../form.md), recipe `formRecipe`(`src/form.ts`)
+- 스토리북: `배포/컴포넌트/입력/입력 양식`
+
+## 언제 쓰나
+
+여러 [Field](field.md)를 한 화면에 쌓고 한 번에 제출할 때 쓴다. Form은 필드 사이의 세로 리듬과
+**제출 세션**(중복 제출 차단, 진행 중 잠금, 폼 단위 오류 표시)만 소유한다. 값·검증·dirty 판단은
+제품(React Hook Form 등)이 소유한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 입력 하나와 즉시 반영(검색, 토글) | [SearchField](search-field.md), [Switch](switch.md) |
+| 한 번 확인하고 닫히는 위험 행동 | [AlertDialog](alert-dialog.md) |
+| 필드 하나의 라벨·도움말·오류 프레임 | [Field](field.md) |
+| 약관 동의 묶음 | [Agreement](agreement.md) |
+| 하단 고정 제출 버튼이 필요한 긴 화면 | Web: Form 안의 필드 + [BottomCTA](bottom-cta.md)(`actions`는 비운다). Native: Form은 내장 제출 버튼을 항상 그리므로 Form 없이 필드 + BottomCTA로 제품이 제출을 소유한다 |
+| Native에서 return 키로 제출해야 하는 폼(로그인·심사자 폼) | Form 없이 `TextField`(ref) + [Button](button.md)(`loading`). Native Form은 밖에서 제출을 부를 수 없다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Form` | 기본 | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/forms` |
+| `createFormSubmitSession` | 보조 — 제출 결과를 값으로 받거나 언마운트 때 정산해야 할 때 쓰는 세션 | `@hjmds/design-contracts/components/form` | 같음 |
+| `resolveFirstInvalidFieldFocusTarget` | 보조 — 필드 순서와 무효 id로 첫 오류 필드를 고른다 | `@hjmds/design-contracts/components/form` | 같음 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { useRef } from "react";
+import { Form, TextField } from "@hjmds/react/forms";
+import { Button } from "@hjmds/react/actions";
+
+const nicknameInputRef = useRef<HTMLInputElement>(null);
+
+<Form
+  aria-label={t("profile.formLabel")}
+  onSubmit={async () => {
+    setServerError(null);
+    if (nicknameError) { nicknameInputRef.current?.focus(); return; } // Web은 첫 오류 포커스를 제품이 한다
+    try { await save(values); } catch { setServerError(t("profile.saveFailed")); }
+  }}
+  formError={serverError}
+  actions={<Button type="submit">{t("profile.save")}</Button>}
+>
+  <TextField ref={nicknameInputRef} label={t("profile.nickname")} value={values.nickname}
+    onValueChange={setNickname} error={nicknameError ? t(nicknameError) : undefined} />
+</Form>
+```
+
+```tsx
+// Native
+import { useEffect, useRef } from "react";
+import type { TextInput } from "react-native";
+import { Form } from "@hjmds/react-native/forms";
+import { TextField } from "@hjmds/react-native/inputs";
+
+const nicknameInputRef = useRef<TextInput>(null);
+const firstInvalidRef = useRef<TextInput | null>(null);
+// Form은 버튼을 누른 순간 current를 읽는다. 렌더 중이 아니라 effect에서 갱신한다(첫 렌더엔 필드 ref가 null).
+useEffect(() => { firstInvalidRef.current = nicknameError ? nicknameInputRef.current : null; }, [nicknameError]);
+
+<Form
+  label={t("profile.formLabel")}
+  values={values}
+  onSubmit={save}
+  submitLabel={t("profile.save")}
+  fallbackErrorMessage={t("common.saveFailed")}
+  firstInvalidFieldRef={firstInvalidRef}
+>
+  <TextField ref={nicknameInputRef} label={t("profile.nickname")} value={values.nickname}
+    onValueChange={setNickname} {...(nicknameError ? { error: t(nicknameError) } : {})} />
+</Form>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `density` | `compact` · `comfortable` | `comfortable` | 필드 사이 간격만 바꾼다. 필드 내부 리듬은 Field의 몫이다 |
+| Web `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void \| Promise<void>` | 필수 | 기본 동작은 막혀 있다. Promise면 정산까지 busy |
+| Native `onSubmit` | `(values: Values) => void \| Promise<void>` | 필수 | 누른 순간의 `values`를 받는다. reject하면 `failed` |
+| Native `status`/`defaultStatus` | `FormSubmitStatus` = `"idle"` · `"submitting"` · `"succeeded"` · `"failed"` | `idle` | 제어·비제어 둘 다 된다 |
+| Native `onStatusChange` | `(status: FormSubmitStatus) => void` | — | 무효 제출(`firstInvalidFieldRef` non-null)에서는 불리지 않는다 |
+| Native `firstInvalidFieldRef` | `RefObject<TextInput \| null>` | — | 누른 순간 non-null이면 그 칸에 포커스하고 제출하지 않는다 |
+| Native `error` · Web `formError` | Native `string` · Web `ReactNode` | — | 폼 단위 실패 문장 |
+| `busy`(Web) | `true` · `false` | `false` | `onSubmit`이 Promise를 돌려주면 끝날 때까지 스스로 busy가 된다 |
+| `disabled`(Native) | `true` · `false` | `false` | — |
+
+- 세션(`createFormSubmitSession({ onSubmit, fallbackErrorMessage, resolveErrorMessage? })`)의 상태는
+  `getSnapshot()`이 주는 `{ status: "idle" | "submitting" | "succeeded" } | { status: "failed", message }`이고,
+  `submit(values)`는 `{ outcome: "succeeded" } | { outcome: "failed", message } | { outcome: "blocked", reason } | { outcome: "interrupted" }`를
+  돌려준다. 세션을 쓰면 Web은 `busy`·`formError`, Native는 `status`·`error`를 controlled로 넘기고 renderer 내장 상태를 함께 진실로 두지 않는다([계약](../../form.md)).
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | — | — |
+| 간격 | 필드 사이 간격: `comfortable` `spacing.lg`(20), `compact` `spacing.sm`(12). Web은 필드 묶음 아래 폼 오류와 `actions`가 각각 `spacing.sm`(12) 위 여백을 갖고, `actions` 안 버튼 간격은 `spacing.sm`(12)이다. Native는 필드·오류·내장 제출 버튼을 같은 `fieldGap`으로 세로로 쌓는다 | `form.ts` `formRecipe`, `styles.css` `.hjm-form__*`, `react-native/src/forms.tsx` `Form` |
+| 순서·정렬 | 위→아래 순서는 필드들 → 폼 오류 → 제출 행동이다. 폼 오류는 항상 행동 바로 위에 온다(`formRecipe.formError.position` `beforeActions`). Web `actions`는 줄바꿈되는 가로 줄이다. 버튼 둘이면 [Button](button.md)의 순서(보조 → 주 행동)를 따른다. Native 기본 제출 버튼은 마지막에 있으며 actions 슬롯으로 교체하거나 숨길 수 있다 | `form.ts` `formRecipe`, `styles.css` `.hjm-form__actions` |
+| 고정·스크롤 | 폼 흐름 안에 둔다. 긴 화면에서 제출을 하단에 고정하려면 Web은 Form을 스크롤 영역에 두고 `actions` 대신 [BottomCTA](bottom-cta.md)로 뺀다. Native는 `actions={null}`로 내장 버튼을 숨기고 `FormHandle.submit()`으로 같은 제출을 호출한다 | `react-native/src/forms.tsx` `Form` |
+| 좁은 폭·큰 글자 | — | — |
+
+```text
+┌──────────────────────────┐
+│ 라벨                     │
+│ [ 입력          ]        │
+│ 도움말                    │   ↕ fieldGap(comfortable lg 20 / compact sm 12)
+│ 라벨                     │
+│ [ 입력          ]        │
+│ 폼 오류(서버 거부)         │   ↕ Web sm 12
+│            [취소] [저장]  │ ← actions(Web) / 내장 제출 버튼(Native)
+└──────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- Native `FormHandle`은 `/forms`에서 import한다. `ref.current?.submit()`은 키보드 return·시트 footer에서 동일 제출 경로를 호출한다. footer를 쓰면 `actions={null}`로 내장 버튼을 숨기고, `onStatusChange`로 footer의 loading을 연결한다. 이 경로는 2026-10-06 로그인/시트 지침에서 중복 폼 구현을 피하려고 추가했다.
+
+- 필드 오류는 각 Field의 `error`에 둔다. Form의 오류(`formError`/`error`)는 서버 거부·네트워크 같은
+  폼 단위 실패에만 쓴다. 같은 문장을 두 곳에 넣지 않는다.
+- 문구는 모두 i18n 키로 넣는다. Native는 `fallbackErrorMessage`가 필수다.
+- 진행 중 표시는 Form에 맡긴다. Web은 `fieldset`을 비활성화하고 `aria-busy`를 건다. Native는 내장 제출
+  버튼이 `loading`이 된다. 별도 Spinner를 겹치지 않는다.
+- 제출 버튼은 하나다. Web은 `actions`에 `type="submit"` Button을 넣고, Native는 내장 버튼 또는 `actions` 슬롯 중 하나를 쓴다. Native Form
+  내장 버튼과 [BottomCTA](bottom-cta.md) 제출을 함께 두지 않는다.
+- Native 필드 `error`는 제출 전에(입력 변경·blur 때) 이미 보이고 있어야 한다. 무효 제출은 포커스만 옮기고
+  어떤 콜백도 부르지 않으므로, 그때 오류를 켜는 자리가 없다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 제출 버튼 | 없음(`actions` 슬롯에 제품이 넣음) | 내장(`submitLabel`); `actions`로 교체, `null`로 숨김 |
+| `onSubmit` 인자 | `FormEvent`(기본 동작은 막힘) | `values` |
+| 실패 처리 | Promise reject를 삼킨다. 제품이 `formError`를 설정 | reject하면 `failed`로 바꾸고 Error 메시지 또는 `fallbackErrorMessage`를 alert로 표시 |
+| 첫 오류 필드로 이동 | 없음. 제품이 `onSubmit` 안에서 첫 무효 입력에 `.focus()`한다 | `firstInvalidFieldRef`: 버튼을 누른 순간 `current`를 읽는다. non-null이면 그 입력에 focus와 스크린 리더 focus를 옮기고 `onSubmit`·`onStatusChange` 없이 멈춘다(상태 그대로). ref는 `useEffect`에서 갱신하고, 순서 계산은 `resolveFirstInvalidFieldFocusTarget(fieldOrder, invalidIds)`를 쓴다 |
+| 접근성 이름 | `<form>` 속성(`aria-label` 등) | `label` 필수 |
+| 배치 | `className`, `layoutStyle`(form 속성 `style`도 받음) | `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 `density` |
+| 밖에서 제출 | `<form>`이므로 `type="submit"` 버튼·Enter로 된다 | `ref: Ref<FormHandle>`의 `submit()`으로 같은 validation·중복 제출 방지를 실행 |
+
+## 함정
+
+- Native는 reject된 `Error.message`를 그대로 화면에 보인다. 서버 원문이 노출되지 않도록 제품이 번역된
+  메시지로 감싸 던지거나 메시지 없는 실패로 두어 `fallbackErrorMessage`가 쓰이게 한다.
+- Web은 reject를 삼키므로 `formError`를 설정하지 않으면 실패가 화면에 아무것도 남기지 않는다.
+- Native `firstInvalidFieldRef.current`를 렌더 중에 갱신하면 첫 렌더에는 필드 ref가 null이라 빈 값으로 바로 누르면
+  그대로 `onSubmit`이 나간다. 위 예처럼 `useEffect`에서 갱신한다.
+- Native 내장 제출 버튼은 tone이 `primary`로 고정이다. 소셜 로그인 아래 심사자 폼처럼 낮은 tone이 필요하면 Form 대신
+  `actions`에 `Button tone="secondary"`를 넣고 `ref.current?.submit()`을 호출한다.
+- Native `error`는 `string`이라 `exactOptionalPropertyTypes`에서 `undefined`를 받지 않는다. 조건부 spread로 넘긴다.

package/docs/usage/components/grid.md

@@ -0,0 +1,99 @@
+# Grid
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Responsive values와 Grid](../../responsive-grid.md), [레이아웃 primitive 판정](../../layout-primitives.md), recipe `gridRecipe`(`src/grid.ts`)
+- 스토리북: `배포/컴포넌트/레이아웃/격자`
+
+## 언제 쓰나
+
+카드·타일처럼 같은 모양의 자식을 창 크기에 따라 열 수를 바꿔 배치할 때 쓴다. 열 수는 창 너비를
+`compact`·`medium`·`expanded`·`wide` 네 class로 번역해 고르고, 자식 순서는 바꾸지 않는다(row-major).
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 행·열 의미가 있는 표(헤더, 정렬, 선택) | [DataTable](data-table.md) |
+| 높이가 제각각인 카드 벽 | [Masonry](masonry.md) |
+| 한 방향으로 쌓기·간격 | [Stack](stack.md) |
+| 페이지 폭·여백 제한 | [Container](container.md) |
+| 긴 목록 가상화 | [VirtualList](virtual-list.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Grid` | 기본 | `@hjmds/react`, `/layout` | `@hjmds/react-native`, `/primitives` |
+
+`GridReveal`은 이름이 비슷하지만 Image 계약의 확장이며 Grid와 무관하다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Grid } from "@hjmds/react/layout";
+
+<Grid columns={{ compact: 1, medium: 2, expanded: 3 }} gap={{ compact: "md" }} minColumnWidth={{ compact: 160 }}>
+  {items.map((item) => <ProductCard key={item.id} item={item} />)}
+</Grid>
+```
+
+```tsx
+// Native
+import { Grid } from "@hjmds/react-native/primitives";
+
+<Grid columns={{ compact: 2, medium: 3 }} gap={{ compact: { row: "lg", column: "sm" } }}>
+  {items.map((item) => <ProductCard key={item.id} item={item} />)}
+</Grid>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `columns` | `ResponsiveValue<number>`(필수) | — | `compact`가 필수이고 빈 class는 좁은 쪽 값을 물려받는다. 양의 정수만 받는다 |
+| `gap` | `ResponsiveValue<GridGap>`. `GridGap`은 token(`none` · `xxs`~`xxxl`) 또는 `{ row, column }` | `md`(16) | 항상 구간 객체로 준다: `{ compact: "md" }`, `{ compact: "sm", expanded: "lg" }`, `{ compact: { row: "lg", column: "sm" } }`. 맨 token `gap="md"`는 타입 오류다 |
+| `minColumnWidth` | `ResponsiveValue<number>` | — | 선택. 열이 이 폭보다 좁아지기 전에 열 수를 줄인다. 한 열은 그대로 줄어든다 |
+| `availableWidth` | 숫자 | — | 생략하면 렌더된 컨테이너를 잰다(Web `ResizeObserver`, Native `onLayout`) |
+| Native `onLayoutResolved` | `(layout: ResolvedGridLayout) => void` | — | `layout`은 `{ windowClass, flow: "row-major", requestedColumns, columns, rowGap, columnGap, columnWidth }`. 열 수가 줄었는지(`columns < requestedColumns`) 확인할 때 쓴다 |
+| Web `windowWidth` | 숫자 | `window.innerWidth`(SSR 320) | 테스트·SSR에서 창 너비를 덮는다 |
+
+- `ResponsiveValue<V>`는 `{ compact: V; medium?: V; expanded?: V; wide?: V }`다(`@hjmds/design-contracts/responsive`).
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Grid는 부모 폭을 채우고 바깥 여백을 갖지 않는다. 열 폭은 Grid가 실제로 받은 폭(`availableWidth`)으로 계산한다 | `grid.ts` `resolveGridLayout`, `styles.css` `.hjm-grid` |
+| 간격 | 기본 간격 `md`(16). 페이지 좌우 여백은 [Container](container.md)·Layout이 준다 | `grid.ts` `gridDefaults` |
+| 순서·정렬 | 자식 순서는 행 우선(row-major)이고 RTL에서는 오른쪽에서 시작한다 | `grid.ts` `gridDefaults` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 창 너비 class는 `breakpoint` 기준이다: `compact` 0 · `medium` 600 · `expanded` 960 · `wide` 1280. 열 수는 이 class로 고른다. `columns`는 `compact` 값부터 정하고 넓은 class에서 늘린다(빈 class는 좁은 쪽 값을 물려받는다). `minColumnWidth`를 주면 열이 그 폭보다 좁아지기 전에 열 수가 줄어든다. 큰 글자로 카드가 좁아질 때 이 값으로 열을 줄인다 | `responsive.ts` `resolveWindowClass`, `foundations.ts` `breakpoint` |
+
+## 꼭 지킬 것
+
+- 간격은 gap token으로만 준다. 숫자 px나 자식 margin으로 간격을 만들지 않는다.
+- class 이름 오타·알 수 없는 key·0 이하 열 수는 resolver가 던진다. 조용히 무시되지 않는다.
+- Grid는 자식의 의미를 만들지 않는다. 목록이면 자식에 제품이 목록 의미를 준다.
+- Web 배치는 `layoutStyle`로 한다(색·테두리 등 시각 key는 받지 않는다).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 구현 | CSS Grid(`repeat(n, minmax(0, 1fr))`) | `flexWrap` 행 + 자식마다 고정 폭 셀 View |
+| 창 너비 | `window.innerWidth`, `windowWidth`로 덮기(테스트·SSR) | `useWindowDimensions` |
+| SSR 첫 렌더 | 창 너비를 모르면 320으로 계산 | 해당 없음 |
+| 셀 스타일 | 없음(자식이 직접) | `itemStyle` |
+| 결과 통지 | `data-columns`·`data-state` 속성 | `onLayoutResolved(layout)` |
+| 배치 prop | `layoutStyle`, `className`, `style` | `style`(View). Grid는 layout primitive라 deprecated 대상이 아니고 `layoutStyle`은 없다 |
+| RTL | CSS가 처리 | Provider의 `environment.direction` 적용 |
+
+## 함정
+
+- Native는 자식마다 셀 View를 감싸고 폭을 기기 픽셀 단위로 내림한다. 셀 자체를 꾸밀 때는 자식이 아니라 `itemStyle`을 쓴다.
+- Web SSR에서는 320 기준 열 수로 그렸다가 하이드레이션 뒤 실제 너비로 바뀐다. 첫 화면 열 수가 중요하면 `windowWidth`를 넘긴다.

package/docs/usage/components/heading.md

@@ -0,0 +1,87 @@
+# Heading
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Heading](../../heading.md), recipe `headingRecipe`(`src/heading.ts`)
+- 스토리북: `배포/컴포넌트/글자와 아이콘/제목`
+
+## 언제 쓰나
+
+자리를 모르는 큰 제목 글자 하나가 필요할 때 쓴다. 랜딩 히어로, 결과 화면의 큰 제목,
+카드·표·빈 상태 안의 제목처럼 `Text`의 최대 크기(24px)로는 모자라거나 문서 제목 단계를
+실제로 내야 하는 자리다. 주변 여백은 갖지 않는다. 담는 블록이 정한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 화면 첫 제목(여백·eyebrow·보조 문장·보조 행동 포함) | [Top](top.md) |
+| 본문 중간 묶음의 제목 행·설명 | [Section](section.md) |
+| 본문·라벨·캡션 크기의 글자 | [Text](text.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Heading` | 기본 | `@hjmds/react`, `/heading` | `@hjmds/react-native`, `/heading` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Heading } from "@hjmds/react/heading";
+
+<Heading level="level2">{t("result.title")}</Heading>
+```
+
+```tsx
+// Native
+import { Heading } from "@hjmds/react-native/heading";
+
+<Heading level="level4" semanticLevel={3}>{t("card.title")}</Heading>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `level`(필수) | `level1` 40px · `level2` 32px · `level3` 24px · `level4` 20px · `level5` 18px | — | recipe 기본은 `level3`이지만 두 renderer 모두 prop을 필수로 받는다 |
+| `semanticLevel` | 1~6 | `level`의 숫자 | 크게 보이지만 구조상 h4인 카드 제목처럼 시각 크기와 문서 단계가 다르면 둘을 따로 적는다 |
+| `layoutStyle` | 배치 key(margin·폭·정렬 등) | — | 바깥 배치만. 크기·줄 높이·굵기·색은 받지 않는다 |
+
+- 범위 밖 값은 `TypeError`로 거부된다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 줄 높이: `level1` 48 · `level2` 40 · `level3` 32 · `level4` 28 · `level5` 26 | `foundations.ts` `heading`, `typography` |
+| 간격 | Heading은 margin이 0이다(Web `.hjm-heading`). 위아래 간격은 감싸는 Stack·Section의 `gap`이 정한다 | `styles.css` `.hjm-heading` |
+| 순서·정렬 | 한 블록에 Heading은 하나를 맨 위에 둔다 | — |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 폭은 부모를 따르고 긴 제목은 줄바꿈한다. Web은 `--hjm-text-scale`로 크기·줄 높이를 함께 키운다 | `styles.css` `.hjm-heading` |
+
+## 꼭 지킬 것
+
+- 제목 문구는 i18n 키로 넣는다. Web은 줄바꿈을 `overflow-wrap: anywhere`로 처리하므로 자르지 않는다.
+- 크기를 맞추려고 `semanticLevel`을 바꾸거나, 구조를 맞추려고 `level`을 줄이지 않는다.
+- 제목 아래 간격은 Heading에 주지 않고 감싸는 Stack·Section의 gap으로 정한다.
+- 색·크기·굵기를 덮지 않는다. 색은 테마의 `content.primary`를 따른다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 출력 | `h1`~`h6` 요소 | `Text` + `accessibilityRole="header"` + `aria-level` |
+| 추가 prop | `HTMLAttributes`(`id`, `className`, `style` 등), ref | 없음 |
+| 배치 | `layoutStyle`. `style`도 합쳐진다(크기 변수는 덮이지 않음) | `layoutStyle`. `style`(TextStyle)은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 `level` |
+| 글자 배율 | `--hjm-text-scale`로 확대 | Native `Text`의 글자 배율 |
+
+## 함정
+
+- Web `style`은 이제 버려지지 않고 합쳐진다. 다만 크기·줄 높이·굵기 변수(`--hjm-heading-*`)는 recipe가 마지막에 덮으므로
+  `style`로 크기를 바꿀 수 없다. 배치는 `layoutStyle`로 준다.
+- Native `style`(deprecated)은 아직 마지막에 합쳐져 색·크기까지 바뀐다. 쓰지 말고 `layoutStyle`·`level`로 옮긴다.

package/docs/usage/components/icon-button.md

@@ -0,0 +1,126 @@
+# IconButton
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: recipe `iconButtonRecipe`(`src/icon-button-recipe.ts`), NotificationBell 계약: [Compound controls](../../compound-controls.md#notificationbell)
+- 스토리북: `배포/컴포넌트/동작/아이콘 버튼` · `배포/컴포넌트/상태와 알림/알림 벨`
+
+## 언제 쓰나
+
+보이는 글자 없이 아이콘만으로 표시하는 행동에 쓴다. 닫기, 뒤로, 더보기, 공유, 즐겨찾기 토글처럼
+모양이 널리 통하는 행동이다. 이름은 현지화한 `label`이 접근성 이름으로 읽힌다.
+미확인 알림 수가 붙은 알림 진입점은 `NotificationBell`을 쓴다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 글자 라벨이 있는 행동 | [Button](button.md) |
+| 다른 페이지·URL로 이동 | [Link](link.md) |
+| 화면 위에 떠 있는 주 행동 | [FloatingActionButton](floating-action-button.md) |
+| 여러 아이콘 중 하나를 고름 | [ToggleGroup](toggle-group.md), [SegmentedControl](segmented-control.md) |
+| 누를 수 없는 그림 | [Icon](icon.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `IconButton` | 기본 | `@hjmds/react`, `/actions` | `@hjmds/react-native`, `/actions`, `/bottom-cta` |
+| `NotificationBell` | 확장 — 미확인 수 배지 + 증가 시 한 번 흔들림 | `/notification-bell` | `/notification-bell` |
+
+`NotificationBell`은 granular subpath로만 import 된다. 추가 peer는 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { IconButton } from "@hjmds/react/actions";
+import { Icon } from "@hjmds/react/display";
+
+<IconButton label={t("common.close")} onClick={close}>
+  <Icon name="close" />
+</IconButton>
+```
+
+```tsx
+// Native
+import { IconButton } from "@hjmds/react-native/actions";
+import { Icon } from "@hjmds/react-native/primitives";
+import { NotificationBell } from "@hjmds/react-native/notification-bell";
+// renderGlyph는 createLucideGlyph로 만든다(icon.md 참고).
+
+<IconButton label={t("common.more")} onPress={openMenu}>
+  <Icon descriptor={{ name: "more" }} renderGlyph={renderGlyph} />
+</IconButton>
+
+<NotificationBell
+  label={t("inbox.open", { count: unread })}
+  count={unread}
+  icon={<Icon descriptor={{ name: "notifications" }} renderGlyph={renderGlyph} />}
+  onPress={openInbox}
+  active={isFocused}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tone` | `ghost` · `primary` · `secondary` · `danger` | `ghost` | — |
+| `size` | `small` 36 · `medium` 44 · `large` 52 | `medium` | `small`은 터치 여백 4 추가. 아이콘 크기는 각각 `sm`·`md`·`lg` |
+| `shape` | `rounded` · `circle` | `rounded` | — |
+| `selected` | `true` · `false` | — | 주면 토글이 된다(Web `aria-pressed`, Native 접근성 state) |
+| `loading` | `true` · `false` | — | 누름을 막고 스피너로 바꾼다. Native는 기본으로 포커스를 유지한다(`disableWhileLoading`으로만 옛 동작) |
+| `loading` 중 `renderLoadingIndicator`(Native) | `(props: { color: string; size: "small" }) => ReactNode` | 기본 스피너 | 스피너를 바꿀 때만 |
+| Web `onClick` · Native `onPress` | Web `(event: MouseEvent<HTMLButtonElement>) => void` · Native `(event: GestureResponderEvent) => void` | — | Native는 `onLongPress`도 받는다 |
+| `count`(NotificationBell) | 0 이상의 정수 | — | 아니면 `RangeError` |
+| `onPress`(NotificationBell) | `() => void` | 필수 | Web·Native 모두 `onPress`다(Web도 `onClick`이 아니다) |
+| `active`(NotificationBell) | `true` · `false` | `true` | — |
+| `disabled`(NotificationBell) | `true` · `false` | `false` | — |
+| Web `layoutStyle`(NotificationBell) | `HjmCompositionStyleProp` | — | 루트 배치. 기본 `alignSelf: "flex-start"`보다 우선하지만 `width`는 무시된다(루트는 항상 `max-content`). 떠 있는 배지가 루트의 끝 모서리에 붙어 있어 루트가 넓어지면 아이콘에서 떨어지기 때문이다. margin·`alignSelf`로 배치한다. 미게시(1.12.1 이후) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 지름: `small` 36 · `medium` 44 · `large` 52. `small`은 hitSlop 4를 더해 터치 영역을 44(`control.minTouchTarget`)에 맞춘다. 아이콘 크기는 `glyph.sm` 20 · `glyph.md` 24 · `glyph.lg` 28이다 | `icon-button-recipe.ts` `iconButtonRecipe` |
+| 간격 | [TopBar](top-bar.md)가 슬롯 최소 폭 44, 슬롯 안 간격 `spacing.xs`(8), 좌우 여백 `spacing.md`(16)를 준다. NotificationBell 배지가 버튼 밖으로 넘칠 수 있으니 옆 요소와 간격을 둔다 | `component-recipes.ts` `topBarRecipe`, `styles.css` `.hjm-top-bar` |
+| 순서·정렬 | 화면 맨 위에서는 TopBar의 `leading`(뒤로·닫기)과 `actions`/`trailing`(더보기·공유·알림)에 둔다. 행 끝(목록·카드)에는 `size="small"` 또는 `medium`, `tone="ghost"`를 쓴다. NotificationBell은 IconButton 오른쪽 위 모서리(`end: 0`, `top: 0`)에 [CounterBadge](counter-badge.md) `floating`을 겹친다 | `react-native/src/notification-bell.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | — | — |
+
+```text
+TopBar
+┌─────────────────────────────────────┐
+│ [←]        화면 제목       [벨³][⋯] │  ← leading 44 / trailing 간격 xs 8, 좌우 여백 md 16
+└─────────────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `label`은 모양이 아니라 행동을 말한다("돋보기"가 아니라 "검색"). Native는 빈 `label`·빈 children을 `TypeError`로 거부한다.
+- 안의 Icon은 장식으로 둔다. 이름은 버튼이 이미 읽는다.
+- 배치는 `layoutStyle`로만 한다. 지름·radius·배경을 `style`/`className`으로 덮지 않는다.
+- NotificationBell의 `label`에 미확인 수를 포함한 현지화 문구를 넣는다. 배지와 그림은 접근성에서 숨겨진다.
+  눌러도 읽음 처리는 하지 않는다. 읽음 처리는 제품이 한다.
+- Native에서 화면이 가려진 채 mounted면 `active={false}`를 넘겨 흔들림을 멈춘다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이벤트 | `onClick` | `onPress`, `onLongPress` |
+| 기본 `type` | `"button"` | 해당 없음 |
+| 스피너 교체 | 없음 | `renderLoadingIndicator` |
+| 비활성이지만 포커스 유지 | `aria-disabled` | `loading` 기본 동작 |
+| NotificationBell 흔들림 정지 | 문서 숨김·reduced motion | AppState 비활성·reduced motion |
+| 배치 | `layoutStyle`(IconButton·NotificationBell, NotificationBell은 `width` 무시) | IconButton `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 `tone`·`size`·`shape`. NotificationBell은 배치 prop이 없어 감싸는 View로 배치한다 |
+
+## 함정
+
+- children의 색은 버튼이 칠하지 않는다. HJM Icon은 자기 `tone` 색을 쓰므로, `primary`·`danger` 버튼 안에서는
+  `tone="inverse"`를 준다. 다른 아이콘 라이브러리의 컴포넌트를 직접 넣으면(Native) 색을 제품이 넘겨야 한다.
+- Native `IconButton` `style`은 deprecated지만 다음 major 전까지 recipe 뒤에 합쳐져 지름·배경까지 바뀐다. 새 코드에서 쓰지 않는다.