@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/components/swipe-actions.md

@@ -0,0 +1,124 @@
+# SwipeActions
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: 별도 보조 기능(supplemental), 계약 함수 `validateActions`·`RowAction`(`components/interaction-adapters`), [optional adapters](../../optional-adapters.md)
+- 스토리북: `배포/구성/직접 조작과 모션/끌기·밀기·화면 전환`
+
+## 언제 쓰나
+
+목록 행 하나에 붙은 **삭제·보관 같은 행 단위 행동**을, Native에서는 행을 밀어 드러내고 Web에서는
+행 아래 버튼으로 바로 보여 줄 때 쓴다. 스와이프 전용 기능은 없다. 같은 행동이 항상 다른 경로로도 열린다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 행을 눌러 상세로 이동, 설정 행 | [ListRow](list-row.md), [List](list.md) |
+| 행 행동이 많거나 메뉴로 묶어야 함 | [Menu](menu.md), [ContextMenu](context-menu.md) |
+| 순서 바꾸기 | [SortableCollection](sortable-collection.md) |
+| 되돌릴 수 없는 삭제의 최종 확인 | 행동 처리 안에서 [AlertDialog](alert-dialog.md) |
+| 시트·화면 닫기 스와이프 | [Sheet](sheet.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `SwipeActions` | 보조(supplemental) | `/swipe-actions` | `/swipe-actions` |
+
+granular subpath로만 import 된다. Native는 `react-native-gesture-handler/ReanimatedSwipeable`을 import 하므로
+optional peer `react-native-gesture-handler` 2.32.0과 Reanimated(`react-native-reanimated` ^4.5.1,
+`react-native-worklets` ^0.10.1)를 앱에 설치하고 앱 루트의 GestureHandlerRootView·Reanimated 설정을 갖춰야 한다
+([optional adapters](../../optional-adapters.md)의 설치 절). Web은 추가 peer가 없다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { SwipeActions } from "@hjmds/react/swipe-actions";
+
+<SwipeActions
+  label={t("inbox.rowActions", { title: item.title })}
+  actions={[{ id: "archive", label: t("inbox.archive") }, { id: "delete", label: t("inbox.delete"), intent: "danger" }]}
+  onAction={(id) => handleRowAction(item.id, id)}
+  onError={showErrorToast}
+>
+  <InboxRow item={item} />
+</SwipeActions>
+```
+
+```tsx
+// Native — 목록 전체가 openRowId 하나를 공유한다
+import { SwipeActions } from "@hjmds/react-native/swipe-actions";
+
+<SwipeActions
+  rowId={item.id}
+  openRowId={openRowId}
+  onOpenRowChange={setOpenRowId}
+  label={t("inbox.rowActions", { title: item.title })}
+  actionsLabel={t("inbox.showActions")}
+  actions={rowActions}
+  onAction={(id) => handleRowAction(item.id, id)}
+  onError={showErrorToast}
+>
+  <InboxRow item={item} />
+</SwipeActions>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `actions` | `{ id, label, intent?: "default" \| "danger", disabled? }[]` | — (필수) | `id`는 고유, `label`이 비면 `TypeError`. `danger`는 `danger` 버튼, 나머지는 `ghost` 버튼 |
+| `busy` | `boolean` | — | 모든 행동을 막는다. 처리 중에는 두 번째 행동을 받지 않는다(`onAction`이 끝날 때까지) |
+| `onAction` | `(id: string) => void \| Promise<void>` | — (필수) | 누른 행동의 `id`. Promise를 돌려주면 끝날 때까지 다음 행동을 받지 않는다 |
+| `onError` | `(error: unknown) => void` | — (필수) | `onAction`이 던지거나 reject 하면 받는다 |
+| `rowId`(Native) | `string` | — (필수) | 데이터의 안정된 행 id |
+| `openRowId` + `onOpenRowChange`(Native) | `string \| null`, `(id: string \| null) => void` | — (필수) | 목록 전체가 공유하는 열린 행. 닫히면 `null` |
+| `actionsLabel`(Native) | `string` | — (필수) | 스와이프 대체 버튼 이름 |
+| `layoutStyle`(Web) | `HjmCompositionStyleProp` | — | 루트 `group` 배치. Native에는 없다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 목록 행 하나를 감싼다. 행 높이·여백은 `children`(보통 [ListRow](list-row.md))이 정한다. 행동 버튼은 `medium` 높이 44의 Button(`danger` 또는 `ghost`) | `react/src/swipe-actions.tsx`, `react-native/src/swipe-actions.tsx` |
+| 간격 | 행동 버튼 사이 `spacing.xs` 8, 넘치면 줄바꿈 | 같은 두 파일 |
+| 순서·정렬 | Web: 행 바로 아래에 버튼 줄이 항상 보인다. Native: 버튼은 행 오른쪽 뒤(RTL은 왼쪽)에 숨어 있다가 밀면 드러난다. 행 아래에는 `actionsLabel` ghost 버튼이 항상 있고, 누르거나 reduced motion이면 그 아래에 행동 버튼 줄이 펼쳐진다. 파괴 행동(`danger`)은 마지막에 두고, 2~3개를 넘으면 [Menu](menu.md)로 묶는다 | `react-native/src/swipe-actions.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 행동 버튼 줄은 `flexWrap: wrap`으로 줄바꿈된다 | 같은 두 파일 |
+
+```text
+Native(LTR)                              Web
+┌────────────────────┬────────────┐      ┌──────────────────────────┐
+│ 행(children) ← 밀기│[보관][삭제]│      │ 행(children)             │
+└────────────────────┴────────────┘      ├──────────────────────────┤
+[ actionsLabel ] ← 스와이프 대체 경로    │ [보관] [삭제]  항상 표시 │
+                                         └──────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 행동 label·행 label은 i18n 키로 넣는다. 어떤 행동을 두는지는 제품이 정한다.
+- Native는 `openRowId`/`onOpenRowChange`를 목록 단위 상태로 두어 한 번에 한 행만 열리게 한다.
+- `actionsLabel` 버튼은 스와이프를 쓰지 못하는 사용자의 경로다. 숨기거나 빼지 않는다.
+- 행 모양은 `children`이 소유한다. Web은 `layoutStyle`로 바깥 배치만 하고, Native는 스타일·`layoutStyle` prop이 없다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 표시 방식 | 행 아래 버튼을 항상 표시(`role="group"`) | 스와이프로 드러냄 + `actionsLabel` 버튼으로 펼침 |
+| 필수 prop | `label`·`actions`·`onAction`·`onError` | 더해 `rowId`·`openRowId`·`onOpenRowChange`·`actionsLabel` |
+| reduced motion | 해당 없음 | 스와이프를 끄고 버튼을 펼쳐 보여 줌 |
+| RTL | 해당 없음 | 행동을 왼쪽에서 드러냄 |
+| 백그라운드 전환 | 해당 없음 | 열린 행을 닫음 |
+| `layoutStyle` | 있음 | 없음 |
+
+## 함정
+
+- FlashList처럼 행 뷰를 재활용하는 목록에서도 `rowId`가 바뀌면 진행 중 표시와 펼친 메뉴가 초기화된다.
+  `rowId`는 데이터의 안정된 id로 넘긴다.

package/docs/usage/components/switch.md

@@ -0,0 +1,120 @@
+# Switch
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [제품 채택 1.4 §설정 한 행](../../product-adoption-1.4.md), `src/component-recipes.ts`(`switchRecipe`)
+- 스토리북: `배포/컴포넌트/입력/스위치`
+
+## 언제 쓰나
+
+켜고 끄는 즉시 반영되는 설정 하나에 쓴다. 알림 받기, 다크 모드, 자동 재생 같은 설정 화면의 행이
+대표적이다. 설정 화면에서는 `presentation="row"`로 **Switch 하나가 행 전체**가 된다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 폼 제출 때 함께 보내는 동의·선택 | [Checkbox](checkbox.md) |
+| 여러 항목을 함께 고름 | [CheckboxGroup](checkbox-group.md) |
+| 둘 이상 중 하나를 고름 | [SegmentedControl](segmented-control.md), [RadioGroup](radio-group.md) |
+| 버튼 모양의 켜짐/꺼짐 | [Button](button.md)의 `selected`, [ToggleGroup](toggle-group.md) |
+| 약관 동의 묶음 | [Agreement](agreement.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Switch` | 기본 | `@hjmds/react`, `/selection` | `@hjmds/react-native`, `/inputs` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Switch } from "@hjmds/react/selection";
+
+<Switch
+  presentation="row"
+  label={t("settings.push.title")}
+  description={t("settings.push.description")}
+  checked={pushEnabled}
+  onCheckedChange={setPushEnabled}
+/>
+```
+
+```tsx
+// Native
+import { Switch } from "@hjmds/react-native/inputs";
+
+<Switch
+  presentation="row"
+  label={t("settings.push.title")}
+  description={t("settings.push.description")}
+  checked={pushEnabled}
+  onCheckedChange={setPushEnabled}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `presentation` | `inline` · `row` | Web `inline`, Native `row` | 기본값이 플랫폼마다 다르다. 같은 설정 화면을 두 표면에서 맞추려면 **항상 명시**한다 |
+| `size` | `small`(44×26) · `medium`(52×32) | `medium` | — |
+| `checked`/`defaultChecked` | `boolean` | `defaultChecked` `false` | `checked`를 생략하면 비제어로 동작한다 |
+| `onCheckedChange` | `(checked: boolean) => void` | — | 다음 상태를 받는다 |
+| `labelVisibility` | `visible` · `hidden` | `visible` | `hidden`은 글자만 화면에서 숨기고 접근성 이름은 남긴다 |
+| `description` | 문구 | — | 이름과 따로 연결한다(Web `aria-describedby`, Native `accessibilityHint` 기본값) |
+| `disabled` | `boolean` | `false` | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트(행) 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle` 또는 `size`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+큰 글자(공통 large-text 기준)에서 `row`는 설명 아래로 track을 내린다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 트랙 `small` 44×26(thumb 22) · `medium` 52×32(thumb 28), 안쪽 여백 2. iOS Native는 `UISwitch` 고유 크기. 루트 최소 높이 44(`control.minTouchTarget`). 행 높이는 설명이 없으면 44, Native는 설명이 있으면 68(`rowTwoLineMinHeight`, ListRow 두 줄 행과 같다). Web은 68을 고정하지 않고 내용 높이를 따른다 | `switchRecipe.sizes`·`rowMinHeight`·`rowTwoLineMinHeight`, `styles.css` `.hjm-switch`, `react-native/src/inputs.tsx` |
+| 간격 | 이름과 트랙 사이 `spacing.sm` 12, 이름과 설명 사이 `spacing.xxs` 4. 여러 개를 쌓을 때는 [List](list.md)·[ListRow](list-row.md) 행 구분을 따르고 Switch 사이에 여백을 더하지 않는다 | `styles.css` `.hjm-switch`·`.hjm-switch__copy`, `react-native/src/inputs.tsx` |
+| 순서·정렬 | 설정 목록에서는 `presentation="row"`로 행 전체 폭을 쓰고 이름·설명이 앞(왼쪽), 트랙이 끝(오른쪽) | `styles.css` `.hjm-switch[data-presentation="row"]` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 글자 배율 ≥ 1.6(`largeTextThreshold`)이면 `row`는 이름·설명 아래로 트랙을 내린다 | `switchRecipe.stackedTextScale`, `styles.css` `.hjm-root[data-large-text="true"]` |
+
+```text
+presentation="row"                    큰 글자(≥1.6)
+┌───────────────────────────────┐      ┌───────────────────────┐
+│ 알림 받기              (●──)  │      │ 알림 받기             │
+│ 새 편지가 오면 알려요         │      │ 새 편지가 오면 알려요 │
+└───────────────────────────────┘      │ (●──)                 │
+  ↑ 이름·설명 · 간격 12 · 트랙 ↑       └───────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `label`·`description`은 i18n 키로 넣는다. 설정 항목과 문구는 제품 소유, 행 구조·색·접근성은 HJM 소유다.
+- `row`인 Switch를 다른 Pressable·button·ListRow `onPress`로 감싸지 않는다. 행 전체가 이미 하나의 switch다.
+- 기존 [ListRow](list-row.md)의 trailing control로만 둘 때는 `labelVisibility="hidden"`과 같은 `label`을 주고,
+  ListRow에는 `onPress`를 두지 않는다.
+- 배치는 `layoutStyle`로 한다. Native `style`은 쓰지 않는다. track·thumb 색은 recipe가 정하며 덮지 않는다.
+- 저장 요청 중에는 `disabled`로 막는다. 비활성 상태도 켜짐/꺼짐이 구분되게 색이 바뀐다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 요소 | `<button role="switch">` | `Pressable`(role `switch`) 안의 RN `Switch` |
+| `label`·`description` 타입 | `ReactNode` | `string` |
+| 이름 재지정 | `aria-label`/`aria-labelledby` | `accessibilityLabel`/`accessibilityHint` |
+| 꺼짐 상태 hairline | 그림(track·thumb 모두 1px inset) | 그리지 않음(RN `Switch`에 테두리 hook이 없음, `*Border` 슬롯은 Web 전용) |
+| iOS 크기 | 해당 없음 | `UISwitch` 고유 크기를 따른다(Android는 recipe 크기) |
+
+## 함정
+
+- Native는 옛 `value`/`defaultValue`/`onValueChange`를 받으면 실행 중 `TypeError`를 던진다.
+  `checked`/`defaultChecked`/`onCheckedChange`를 쓴다.
+- Native 꺼짐 상태에는 테두리가 없으므로, 어두운 카드 위에서 track이 배경과 섞이는지 실제 기기 다크 모드로 확인한다.
+  (Web은 이 hairline이 빠져 보이지 않던 일이 있었고 현재 stylesheet가 그린다.)
+- Web은 `type="button"`이 기본이라 폼 안에서도 submit을 일으키지 않는다.

package/docs/usage/components/tabs.md

@@ -0,0 +1,134 @@
+# Tabs
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Gooey navigation](../../gooey-navigation.md), `src/component-recipes.ts`(`tabsRecipe`), `src/behaviors.ts`(`tabsBehaviorDefaults`)
+- 스토리북: `배포/컴포넌트/탐색/탭`, `배포/컴포넌트/탐색/선택 표시가 이어지는 탭`
+
+## 언제 쓰나
+
+같은 화면 안에서 **서로 다른 패널 여러 개 중 하나를 보여 줄 때** 쓴다. 프로필의 "게시물/좋아요",
+설정의 "일반/알림"처럼 탭마다 패널이 따로 있고 화면 이동 없이 바뀌는 자리다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 같은 목록의 필터·보기 방식만 바꿈(패널이 하나) | [SegmentedControl](segmented-control.md) |
+| 앱의 최상위 화면 이동 | [BottomNavigation](bottom-navigation.md), [Sidebar](sidebar.md) |
+| 여러 개를 동시에 켜고 끔 | [ToggleGroup](toggle-group.md), [Chip](chip.md) |
+| 순서가 있는 단계 진행 | [Steps](steps.md) |
+| 접고 펼치는 여러 섹션 | [Accordion](accordion.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Tabs` | 기본 | `@hjmds/react`, `/navigation` | `@hjmds/react-native`, `/navigation`, `/top-bar` |
+| `TabPanel` | 동반(패널을 Tabs 밖에 둘 때) | `@hjmds/react`, `/navigation` | `@hjmds/react-native`, `/navigation`, `/top-bar` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Tabs } from "@hjmds/react/navigation";
+
+<Tabs
+  label={t("profile.tabs")}
+  value={tab}
+  onValueChange={setTab}
+  items={[
+    { id: "posts", label: t("profile.posts"), panel: <PostList /> },
+    { id: "likes", label: t("profile.likes"), panel: <LikeList /> },
+  ]}
+/>
+```
+
+```tsx
+// Native
+import { Tabs } from "@hjmds/react-native/navigation";
+
+<Tabs
+  label={t("profile.tabs")}
+  defaultValue="posts"
+  layout="fitted"
+  items={[
+    { id: "posts", label: t("profile.posts"), panel: <PostList /> },
+    { id: "likes", label: t("profile.likes"), badge: "3", badgeAccessibilityLabel: t("profile.likesNew", { count: 3 }), panel: <LikeList /> },
+  ]}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value`+`onValueChange` / `defaultValue` | 항목 `id`, `(value: string) => void`(Native는 `Value`) | 첫 활성 항목 | controlled는 둘 다 필수. 비제어에서도 `onValueChange`로 바뀐 값을 받는다 |
+| `items[]` | Web `{ id, label: ReactNode, panel?, renderLeading?, disabled? }`, Native는 더해 `badge?`·`badgeAccessibilityLabel?`·`panelAccessibilityLabel?`(`label`은 `string`) | — (필수) | — |
+| `renderLeading`(항목) | `(state: { selected, disabled, color, size }) => ReactNode` | — | `color`는 Web `"currentColor"`, Native 색 문자열 |
+| `activationMode` | `manual` · `automatic` | `manual` | `manual`은 Web에서 방향키로 포커스만 옮기고 Enter/Space로 선택 |
+| `mountPolicy` | `active` · `visited` · `always` | `active` | `active`는 선택된 패널만 mount |
+| `panelMode` | `keyed` · `dynamic` | `keyed` | `dynamic`은 `mountPolicy="active"`일 때만 허용 |
+| `size` | `medium` · `small` | `medium` | 최소 높이 48 · 44 |
+| `layout` | `content` · `fitted` | `content` | `fitted`는 폭을 나눠 채움 |
+| `overflow` | `scroll` · `clip` | `scroll` | — |
+| `orientation` | `horizontal` · `vertical` | `horizontal` | — |
+| `loop` | `boolean` | `true` | — |
+| `appearance` | `standard` · `gooey` | `standard` | `gooey`는 가로일 때만 선택 표시가 늘어나며 이동, 세로는 standard 유지 |
+| `renderPanels` | `boolean` | `true` | `false`면 패널을 그리지 않는다. 패널을 라우터·스크롤 상태와 함께 따로 둘 때 `TabPanel`에 `tabsId`(Tabs의 `id`와 같게)·`activeValue`·`value`를 넘긴다 |
+| `children`(Native) | `(selectedValue: Value) => ReactNode` | — | 항목 `panel` 대신 선택 값으로 패널을 그린다 |
+| `TabPanel` | `{ tabsId, activeValue, children, mode?: "keyed", value, mountPolicy? }` 또는 `{ mode: "dynamic" }`, Native는 `label` 필수 | — | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | Tabs·TabPanel 루트 배치. Web·Native 모두 |
+| Native `style`·`tabListStyle`, TabPanel `style` | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle` 또는 `size`·`layout`·`overflow`·`appearance`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 탭 높이 `medium` 최소 48, `small` 최소 44(`control.minTouchTarget`). 목록 아래 구분선 1(`border` 색), 선택 밑줄 2(`stroke.strong`) | `tabsRecipe.sizes`·`indicatorHeight`, `styles.css` `.hjm-tabs__tab` |
+| 간격 | 좌우 안쪽 여백 `medium` `spacing.md` 16 · `small` `spacing.sm` 12, 탭 사이 `spacing.xs` 8, 아이콘과 라벨 사이 `spacing.xs` 8. Web 패널 위아래 여백 `spacing.md` 16 | `tabsRecipe`, `styles.css` `.hjm-tabs__list`·`.hjm-tabs__leading`·`.hjm-tabs__panel` |
+| 순서·정렬 | 화면 상단(TopBar 아래)이나 섹션 머리에 가로로 놓고 패널이 바로 아래. 탭이 적고(2~4) 폭을 꽉 채워야 하면 `layout="fitted"`, 많거나 라벨 길이가 다르면 `content`. 세로(`orientation="vertical"`)는 Web에서 왼쪽 목록(최소 8rem)과 오른쪽 패널을 `spacing.md` 16 간격으로 나란히 두고 구분선이 목록 오른쪽에 선다 | `styles.css` `.hjm-tabs[data-orientation="vertical"]`, `react-native/src/navigation.tsx` |
+| 고정·스크롤 | 기본 `overflow="scroll"`로 탭 목록이 가로 스크롤한다. 목록은 스크롤 영역 안에서 고정되지 않으며 상단에 붙여야 하면 제품이 sticky 영역에 넣는다 | `tabsRecipe.overflow`, `styles.css` `.hjm-tabs__list` |
+| 좁은 폭·큰 글자 | 라벨은 줄바꿈하지 않는다(`white-space: nowrap`). 좁은 폭·큰 글자에서는 가로 스크롤로 받는다 | `styles.css` `.hjm-tabs__tab` |
+
+```text
+┌────────────────────────────────────┐
+│ TopBar                             │
+├────────────────────────────────────┤
+│ [전체] [내 글] [저장] →(스크롤)    │ ← 최소 48, 사이 8
+│  ━━━━                              │ ← 선택 밑줄 2 / 구분선 1
+├────────────────────────────────────┤
+│ 패널(Web 위아래 16)                │
+└────────────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `label`(탭 목록 이름)은 필수이고 비어 있으면 `TypeError`다. 항목 라벨과 함께 i18n 키로 넣는다.
+- `items`의 `id`는 비지 않고 겹치지 않아야 하며, 활성 항목이 하나 이상 있어야 한다(위반 시 `TypeError`).
+  Web controlled `value`가 비활성·없는 항목이면 `RangeError`다.
+- 아이콘은 `renderLeading`으로 넣고 받은 `color`·`size`를 쓴다. 색을 직접 정하지 않는다.
+- 탭을 바꿔도 화면 이동(뒤로 가기 대상)이 아니다. 주소에 남겨야 하면 제품이 controlled 값으로 동기화한다.
+- 배치는 `layoutStyle`로 한다. Web 루트 `div` 속성(`className`·`style`)과 Native의 deprecated `style`·`tabListStyle`로
+  색·높이·인디케이터를 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 항목 `label` 타입 | `ReactNode` | `string` |
+| 항목 배지 | 없음 | `badge`, `badgeAccessibilityLabel` |
+| 패널 접근 이름 | 탭 라벨로 연결(`aria-labelledby`) | 항목 `panelAccessibilityLabel`, `TabPanel`은 `label` 필수 |
+| 패널 렌더 함수 | 없음 | `children(selectedValue)` |
+| 값 타입 | `string` | 제네릭 `Value extends string` |
+| ref | `forwardRef`(`div`) | 없음 |
+| import 경로 | `/navigation` | `/navigation`, `/top-bar` |
+
+## 함정
+
+- Native `Tabs`는 예전 `options` prop을 받으면 `TypeError`("options was removed")를 던진다. `items`로 옮긴다.
+- 외부 `TabPanel`을 쓸 때 Tabs에 `id`를 주지 않으면 Web은 생성 id를 써서 `tabsId`를 맞출 수 없다.
+  `id`를 명시하고 같은 값을 `TabPanel tabsId`에 넘긴다.

package/docs/usage/components/tag.md

@@ -0,0 +1,84 @@
+# Tag
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Tag contract](../../tag.md), `src/tag.ts`(`tagRecipe`)
+- 스토리북: `배포/컴포넌트/데이터 표시/태그`
+
+## 언제 쓰나
+
+반복해서 나오는 **정적 메타데이터 한 조각**에 쓴다. `좌익수`, `A등급`, `2026 시즌`처럼 누르지도,
+고르지도, 지우지도 않는 짧은 라벨이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 누르거나 선택·해제하는 조각(필터, 지울 수 있는 태그) | [Chip](chip.md) |
+| 상태(새 글, 실패, 진행 중)를 알림 | [Badge](badge.md) |
+| 아이콘·아바타 위 숫자 | [CounterBadge](counter-badge.md) |
+| 사용자가 여러 값을 입력해 모음 | [TagsInput](tags-input.md) |
+| 경고·위험 안내 | [Notice](notice.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Tag` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Tag } from "@hjmds/react/display";
+
+<Tag tone="success">{t("player.gradeA")}</Tag>
+```
+
+```tsx
+// Native
+import { Tag } from "@hjmds/react-native/data-display";
+
+<Tag layoutStyle={{ marginTop: 4 }}>{t("player.position.leftField")}</Tag>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` | 문자열 | — (필수) | 문자열만 받는다. 비어 있으면 `TypeError` |
+| `tone` | `neutral` · `info` · `success` · `attention` · `brand` | `neutral` | `warning`·`danger`는 없다(이유는 계약 문서) |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 바깥 여백·`alignSelf` 같은 배치. Web·Native 모두 |
+| `accessibilityLabel`(Native) | `string` | 라벨 | — |
+| `style`·`labelStyle`(Native) | `StyleProp` | — | deprecated — `layoutStyle` 또는 `tone`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+모양은 radius `sm` 사각형, 최소 높이 20(큰 글자에서 늘어남), caption 크기 semibold 글자다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 최소 높이 20, 테두리 1, radius `sm` 8. 누르는 대상이 아니므로 44 터치 영역을 두지 않는다 | `tagRecipe.size`, `styles.css` `.hjm-tag`, `react-native/src/data-display.tsx` |
+| 간격 | 좌우 여백 `spacing.xxs` 4. 제목 옆이면 간격 `spacing.xs` 8, 여러 개는 가로로 `spacing.xxs` 4~`xs` 8 | `tagRecipe.size` |
+| 순서·정렬 | 제목·행 옆에 붙는 작은 메타 표시다. 제목 옆이면 제목과 세로 가운데 정렬한다 | — |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 여러 개는 줄바꿈(`wrap`)한다. 큰 글자에서는 높이가 글자에 맞춰 늘어난다(고정 높이 금지) | `tagRecipe.size.minHeight` 주석 |
+
+## 꼭 지킬 것
+
+- 라벨은 i18n 키로 넣는다. 라벨 문구와 어떤 값에 어떤 tone을 줄지는 제품 소유, 색·모양은 HJM 소유다.
+- 배치는 `layoutStyle`로만 한다. 색·radius·여백을 덮지 않는다.
+- `onClick`/`onPress`를 붙여 누르는 Tag로 만들지 않는다. 누를 수 있어야 하면 Chip을 쓴다.
+- 여러 Tag는 [Stack](stack.md) `axis="inline"`·`wrap`으로 나열한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 접근 이름 | 보이는 글자 | 기본은 라벨, `accessibilityLabel`로 바꿀 수 있음 |
+| 추가 style prop | `className`·`style`(HTML 속성) | `style`·`labelStyle`(deprecated) |
+| ref | `forwardRef`(`span`) | 없음 |
+| import 경로 | `/display` | `/data-display` |

package/docs/usage/components/tags-input.md

@@ -0,0 +1,111 @@
+# TagsInput
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [TagsInput](../../tags-input.md), `src/tags-input.ts`(`tagsInputRecipe`)
+- 스토리북: `배포/컴포넌트/입력/태그 입력`
+
+## 언제 쓰나
+
+사용자가 **자유 입력으로 여러 값을 모으는 필드**에 쓴다. 해시태그, 초대할 사람, 검색 필터처럼
+목록이 없거나, 후보가 있어도 목록 밖의 값을 만들 수 있는 경우다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 정해진 목록에서만 고름 | [Combobox](combobox.md), [Select](select.md) |
+| 고정된 몇 개 선택지를 여러 개 켬 | [CheckboxGroup](checkbox-group.md), [Chip](chip.md) |
+| 본문 중 `@사람` 언급 | [Mentions](mentions.md) |
+| 값 하나만 입력 | [Field](field.md) |
+| 정적 라벨 표시 | [Tag](tag.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TagsInput` | 기본 | `@hjmds/react`, `/tags-input` | `@hjmds/react-native`, `/tags-input` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import type { TagsInputRejectionReason } from "@hjmds/design-contracts/components/tags-input";
+import { TagsInput } from "@hjmds/react/tags-input";
+
+// 상태 → i18n 키 상수 표. 키를 템플릿 문자열로 만들지 않는다.
+const tagErrorKey: Record<TagsInputRejectionReason, string> = {
+  empty: "post.tagError.empty",
+  duplicate: "post.tagError.duplicate",
+  limit: "post.tagError.limit",
+  invalid: "post.tagError.invalid",
+};
+
+<TagsInput
+  label={t("post.tags")}
+  tags={tags}
+  onTagsChange={setTags}
+  policy={{ maxTags: 10 }}
+  onReject={(result) => setError(result.reason ? t(tagErrorKey[result.reason]) : undefined)}
+  composeRemoveLabel={(tag) => t("post.removeTag", { tag })}
+/>
+```
+
+```tsx
+// Native
+import { TagsInput } from "@hjmds/react-native/tags-input";
+
+<TagsInput
+  label={t("post.tags")}
+  tags={tags}
+  onTagsChange={setTags}
+  composeRemoveLabel={(tag) => t("post.removeTag", { tag })}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tags` + `onTagsChange` / `defaultTags` | `readonly string[]`, `(tags: readonly string[]) => void` | `defaultTags` `[]` | controlled 또는 uncontrolled. 콜백은 다음 태그 배열 전체를 받는다 |
+| `policy.allowDuplicates` | `boolean` | 막음 | 중복 허용 여부 |
+| `policy.maxTags` · `policy.isValid` | `number` · `(value: string) => boolean` | — | 거절되면 `onReject`가 결과를 받는다 |
+| `onReject` | `(result: { accepted: boolean, value: string, reason?: "empty" \| "duplicate" \| "limit" \| "invalid" }) => void` | — | 사유 문장은 제품이 `reason`으로 고른다 |
+| `onDraftChange` | `(draft: string) => void` | — | 입력 중 문자. 후보 필터링에 쓴다 |
+| `composeRemoveLabel` | `(tag: string) => string` | — (필수) | 태그 삭제 버튼 이름 |
+| `commitKeys` | `Enter` · `Comma` · `Space` · `Blur` | `["Enter"]` | Web만. Native는 Return 하나다 |
+| `suggestions` · `suggestionsLabel` | 제품이 거른 후보(`id`·`label`·`value?`·`disabled?`)와 목록 이름 | — | 거르려면 `onDraftChange`로 입력 중 문자를 받는다 |
+| `placeholder`·`description`·`disabled` | `string`·`string`·`boolean` | — | `disabled`는 라벨과 입력 틀을 `fieldRecipe.disabledOpacity`(0.6)로 흐리고 `description`은 그대로 둔다([Field](field.md)) |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 필드 전체 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 입력 틀 최소 높이 44(필드 틀과 같음), 모서리 `radius.md` 12. 입력 칸 최소 Web `8ch`, Native 80. 태그 칩 높이 28, 삭제 버튼 터치 영역 44(`control.minTouchTarget`). 후보 행 최소 높이 44(두 플랫폼, Native는 미게시(1.12.1 이후). 1.12.1 Native는 28) | `tagsInputRecipe`, `.hjm-tags-input__frame`·`__remove::after`·`__suggestion` |
+| 간격 | 라벨과 틀 사이 Web `spacing.xxs` 4, Native `spacing.xs` 8. 틀 안 태그·입력 칸 사이 `spacing.xs` 8. 이웃 필드와의 간격은 폼이 정한다 | `.hjm-tags-input`, `react-native/src/tags-input.tsx` |
+| 순서·정렬 | 라벨 → 입력 틀 → 후보 목록 → 설명. 폼 안에서 다른 [Field](field.md)와 같은 세로 줄에 두고 폭을 꽉 채운다 | `react/src/tags-input.tsx`, `react-native/src/tags-input.tsx` |
+| 고정·스크롤 | 후보 목록은 틀 바로 아래 문서 흐름에 펼쳐진다(떠 있는 층이 아니다). Web은 최대 높이 12rem에서 스크롤 | `.hjm-tags-input__suggestions` |
+| 좁은 폭·큰 글자 | 태그와 입력 칸이 넘치면 줄바꿈해 틀이 세로로 자란다. 태그 글자는 잘리지 않는다(`overflow-wrap: anywhere`) | `.hjm-tags-input__frame`·`__tag` |
+
+## 꼭 지킬 것
+
+- `label`과 `composeRemoveLabel`은 필수다. 삭제 버튼 이름은 태그 글자를 넣은 i18n 문장으로 만든다.
+- 거절 사유 문장("이미 있어요")은 제품이 `reason`으로 만든다. HJM은 판정만 한다.
+- 한국어처럼 공백이 값의 일부인 도메인에서는 `Space`를 확정 키로 켜지 않는다.
+- 후보 필터링·정렬은 제품이 한다. HJM은 받은 후보를 보여 주고 고른 값을 확정한다.
+- 배치는 `layoutStyle`로 한다(Web `className`도 받는다). Native `style`은 deprecated다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 확정 키 | `commitKeys` | Return만(`commitKeys` 없음), 포커스 이탈로 확정하지 않음 |
+| 빈 입력 Backspace | 첫 번째는 마지막 태그 선택, 두 번째에 삭제 | 해당 키 계약 없음, 태그 옆 삭제 버튼 |
+| 후보 이동 | ArrowUp/Down(끝에서 순환) | 후보를 버튼으로 누름 |
+| ref | `forwardRef`(`input`) | 없음 |
+| 스타일 prop | `className`, `layoutStyle` | `layoutStyle`(`style`은 deprecated) |