@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/components/text-area.md

@@ -0,0 +1,112 @@
+# TextArea
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/base-recipes.ts`(`fieldRecipe`)
+- 스토리북: `배포/컴포넌트/입력/여러 줄 입력`
+
+## 언제 쓰나
+
+여러 줄 자유 글을 받는 입력에 쓴다. 자기소개, 후기, 문의 본문처럼 줄바꿈이 값의 일부인 경우다.
+라벨·설명·오류 문구 틀은 [Field](field.md)와 같다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 한 줄 값(이름, 이메일) | [Field](field.md)의 `TextField` |
+| `@사람` 언급이 있는 본문 | [Mentions](mentions.md) |
+| 비밀번호·숫자·인증 코드 | [PasswordField](password-field.md), [NumberField](number-field.md), [OTPField](otp-field.md) |
+| 검색어 | [SearchField](search-field.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TextArea` | 기본 | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/inputs` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { TextArea } from "@hjmds/react/forms";
+
+<TextArea
+  label={t("review.body")}
+  description={t("review.bodyHint")}
+  error={bodyError ? t(bodyError) : undefined}
+  value={body}
+  onChange={(event) => setBody(event.currentTarget.value)}
+  minVisibleLines={3}
+  maxVisibleLines={8}
+/>
+```
+
+```tsx
+// Native
+import { TextArea } from "@hjmds/react-native/inputs";
+
+<TextArea
+  label={t("review.body")}
+  value={body}
+  onValueChange={setBody}
+  maxVisibleLines={8}
+  layoutStyle={{ marginTop: 16 }}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `surface` · `inset` | `surface` | — |
+| `shape` | `medium` · `large` · `full` | `medium` | — |
+| `align` | `start` · `center` | `start` | — |
+| `value`/`defaultValue` | `string` | — | — |
+| `onChange`(Web) | `(event: ChangeEvent<HTMLTextAreaElement>) => void` | — | DOM 이벤트. 값은 `event.currentTarget.value` |
+| `onValueChange`(Native) | `(value: string) => void` | — | 다음 문자열 |
+| `minVisibleLines` · `maxVisibleLines` | 줄 수 | 최소 높이 80, 상한 없음 | 높이는 줄 수로만 정한다. 최소 높이는 `max(80, 줄 수 × typography.body 줄 높이 20 + spacing.sm 12 × 2)`라 `minVisibleLines`가 1·2여도 80(`fieldRecipe.multilineMinHeight`) 아래로 내려가지 않고 3부터 커진다(3줄 84). Web·Native 같다 |
+| `leadingAction` | `ReactNode` | — | 틀 안 글자 앞 행동 버튼. 자라는 글자의 세로 가운데에 맞추고 흐린 affix 색을 쓰지 않는다. 미게시(1.12.1 이후) |
+| `trailing` | `ReactNode` | — | 틀 안 글자 뒤 슬롯 |
+| `description` · `error` · `required` · `disabled` | Web `ReactNode`, Native `string` · `boolean` | — | Field와 같은 틀로 그려지고 보조기기 설명에 연결된다 |
+| `busy`(Native) | `boolean` | `false` | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 필드 전체(라벨·틀·설명) 배치. Web·Native 모두 |
+
+`leading`(흐린 장식 affix)은 TextArea에 없다(TextField 전용). 행동은 `leadingAction`·`trailing`에 두고, 글자 수 같은 보조 표시는 `description`으로 둔다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 최소 높이 80(`fieldRecipe.multilineMinHeight`)에서 시작해 입력에 따라 자란다. 좌우 안쪽 여백 `spacing.md` 16, 모서리 기본 `radius.md` 12 | `fieldRecipe`, `.hjm-field__control--multiline` |
+| 간격 | 라벨과 틀 사이 `spacing.xs` 8. 이웃 필드와의 간격은 폼이 정하고 TextArea는 바깥 여백이 없다(필요하면 `layoutStyle`로 준다) | `fieldRecipe.label.gap`, `.hjm-field` |
+| 순서·정렬 | 라벨 → 입력 틀 → 설명/오류. 폼의 세로 줄에서 폭을 꽉 채운다 | `react-native/src/inputs.tsx`(`TextArea`) |
+| 고정·스크롤 | `maxVisibleLines`에 닿으면 틀 안에서 스크롤한다. Web은 사용자가 세로로만 크기를 바꿀 수 있다(`resize: vertical`) | `.hjm-field__control--multiline textarea` |
+| 좁은 폭·큰 글자 | 큰 글자에서는 줄 높이가 커져 `minVisibleLines`·`maxVisibleLines`의 실제 높이도 커진다. 픽셀 높이로 고정하지 않는다 | `.hjm-field__control--multiline textarea` |
+
+## 꼭 지킬 것
+
+- `label` 또는 접근 이름(Web `aria-label`, Native `accessibilityLabel`)이 반드시 있어야 한다. 둘 다 없으면 `TypeError`.
+- 라벨·설명·오류·placeholder는 i18n 키로 넣는다. placeholder를 라벨 대신 쓰지 않는다.
+- 높이를 `style`의 `minHeight`/`maxHeight`로 바꾸지 않는다. `minVisibleLines`/`maxVisibleLines`를 쓴다.
+- 한 줄 높이(44)에서 시작해 자라는 입력이 필요하면 TextArea가 아니라 [MessageComposer](message-composer.md)를 쓴다. 한 줄 시작은 composer 내부 전용이며 공개 `minVisibleLines`로는 80 아래로 내려가지 않는다. 2026-10-06 리뷰에서 하한을 44로 낮춘 미게시 변경이 기존 `minVisibleLines={2}` 필드를 80에서 64로 줄여 되돌렸다.
+- 오류는 `error`로 넘긴다. 테두리 색을 직접 바꾸지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 값 변경 | DOM `onChange`(`onValueChange` 없음) | `onValueChange(value)` |
+| 배치 | `layoutStyle`(필드 전체), 바깥 틀 class는 `fieldClassName` | `layoutStyle`(필드 전체) |
+| `style` | `textarea`에 전달 | 타입에서 제외 |
+| 진행 표시 | 없음 | `busy` |
+| 라벨·문구 타입 | `ReactNode` | `string` |
+| import 경로 | `/forms` | `/inputs` |
+
+## 함정
+
+- 현재 Web `TextField`의 `onValueChange` 주석은 "Web TextArea와 같은 콜백"이라고 적지만 Web `TextAreaProps`에는
+  `onValueChange`가 없다(`react/src/forms.tsx`). 공유 폼 코드는 Web TextArea만 `onChange`로 분기한다.

package/docs/usage/components/text-format.md

@@ -0,0 +1,75 @@
+# TextFormat
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [TextFormat](../../text-formats.md), `src/text-formats.ts`(`textFormatRecipe`)
+- 스토리북: `배포/컴포넌트/글자와 아이콘/글자 서식`
+
+## 언제 쓰나
+
+도움말·개발자 안내·약관 본문 안에서 단축키(`⌘S`), 짧은 코드 조각(`pnpm add …`), 인용문을
+표시할 때 쓴다. `kind`마다 `<kbd>`·`<code>`·`<blockquote>`라는 다른 HTML 요소를 그려
+보조기기가 그 의미대로 읽게 한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 여러 줄 코드, 복사 버튼이 붙은 코드 | [CodeBlock](code-block.md) |
+| 단순히 글자 크기·굵기만 다름 | [Text](text.md) |
+| Native 화면 | 없음. RN에는 대응 의미 요소가 없어 renderer를 두지 않는다([계약](../../text-formats.md)) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TextFormat` | 기본 | `@hjmds/react`, `/text-formats` | — |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Text } from "@hjmds/react/layout";
+import { TextFormat } from "@hjmds/react/text-formats";
+
+<>
+  <Text>
+    {t("help.saveShortcut.prefix")}{" "}
+    <TextFormat kind="kbd">{t("help.saveShortcut.key")}</TextFormat>
+  </Text>
+  <TextFormat kind="code">pnpm add @hjmds/react</TextFormat>
+</>
+```
+
+Native: 없음.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `kind`(필수) | `kbd` → `<kbd>` · `code` → `<code>` · `quote` → `<blockquote>` | 없음 | 목록 밖 값은 실행 중 `TypeError` |
+| `children` | `ReactNode` | — (필수) | — |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 배치(주로 `quote` 블록의 바깥 여백·폭) |
+| 나머지 | `HTMLAttributes<HTMLElement>` | — | 해당 HTML 요소로 전달되고 ref도 그 요소로 간다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | `kbd`·`code` 안쪽 좌우 여백 `spacing.xxs` 4, 모서리 `radius.sm` 8. `quote` 시작 쪽 2px 세로 선과 안쪽 여백 `spacing.md` 16 | `.hjm-text-format[data-kind]` |
+| 간격 | 바깥 여백이 없다(`margin: 0`). `quote` 앞뒤 문단과의 간격은 부모가 준다 | `.hjm-text-format` |
+| 순서·정렬 | `kbd`·`code`는 문장 안에 인라인으로, `quote`는 블록으로 놓는다 | `.hjm-text-format` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 긴 코드 조각은 줄바꿈된다(`overflow-wrap: anywhere`). 줄바꿈 없이 가로 스크롤이 필요하면 [CodeBlock](code-block.md) | `.hjm-text-format` |
+
+## 꼭 지킬 것
+
+- 키 이름(⌘ / Ctrl 등)은 제품 문구다. 플랫폼별로 다르게 부르므로 i18n 키로 넣고 HJM이 정하지 않는다.
+- `quote`는 블록 요소(`<blockquote>`)를 만든다. 문단 안 인라인 강조용으로 쓰지 않는다.
+- 배치는 `layoutStyle`로 한다. `className`은 붙일 수 있지만(`hjm-text-format`에 합쳐진다) 글꼴·색·테두리를 덮지 않는다.
+  배치 외 시각 override는 [소비 정책](../../consumer-policy.md) 위반이다.
+- 모양은 `@hjmds/react/styles.css`의 `.hjm-text-format` 규칙이 그린다. stylesheet를 불러오지
+  않은 화면에서는 의미 요소만 남고 HJM 모양은 없다.

package/docs/usage/components/text-transition.md

@@ -0,0 +1,104 @@
+# TextTransition
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/content-transition.ts`(`resolveContentTransition`). 독립 계약 문서 없음(supplemental)
+- 스토리북: `배포/컴포넌트/시각 효과/내용 전환`, `배포/구성/직접 조작과 모션/끌기·밀기·화면 전환`
+
+## 언제 쓰나
+
+같은 자리의 짧은 문자열이 바뀔 때(상태 문구, 버튼 옆 안내, 단계 이름) 바뀐 순간을 짧은
+등장 모션으로 알린다. 글자 단위로 쪼개지 않고 문자열 전체를 한 번에 바꿔, 줄바꿈·선택·
+스크린리더 낭독이 한 값으로 유지된다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 문자열이 아니라 패널·영역 전체가 바뀜 | `ContentTransition`(같은 subpath, 아래 표) — [ContentTransition](content-transition.md) |
+| 숫자 값이 바뀌는 통계 | [Statistic](statistic.md) |
+| 읽어 줘야 하는 결과 알림 | [Toast](toast.md), [Notice](notice.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TextTransition` | 기본(문자열 전환) | `/content-transition` | `/content-transition` |
+| `ContentTransition` | 동반(하위 트리 전환, TextTransition의 기반) | `/content-transition` | `/content-transition` |
+
+root에서는 내보내지 않는다. granular subpath로만 가져온다.
+
+| renderer | 필요한 peer(`peerDependenciesMeta` optional) |
+| --- | --- |
+| Web | `framer-motion` 13.4.4 (subpath가 직접 import 한다) |
+| Native | 없음. RN `Animated`만 쓴다 |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { TextTransition } from "@hjmds/react/content-transition";
+
+// 상태 → i18n 키 상수 표. 키를 템플릿 문자열로 만들지 않는다.
+const uploadStatusKey = {
+  uploading: "upload.status.uploading",
+  processing: "upload.status.processing",
+  done: "upload.status.done",
+} as const;
+
+<TextTransition text={t(uploadStatusKey[phase])} preset="rise" />
+```
+
+```tsx
+// Native
+import { TextTransition } from "@hjmds/react-native/content-transition";
+
+const uploadStatusKey = {
+  uploading: "upload.status.uploading",
+  processing: "upload.status.processing",
+  done: "upload.status.done",
+} as const;
+
+<TextTransition text={t(uploadStatusKey[phase])} preset="rise" />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `text`(필수) | 문자열 | — | 바뀔 때마다 전환한다. 같은 문자열이면 아무것도 하지 않는다 |
+| `preset` | `fade` · `rise`(아래 12에서) · `slide`(가로 16, RTL이면 반대) · `scale`(0.96에서) | `fade` | — |
+| `motion` | `system` · `none` | `system` | `system`이어도 provider의 reduced motion이면 즉시 바뀐다 |
+| `layoutStyle`(Web) | `HjmCompositionStyleProp` | — | 바깥 `<div>` 배치. Native에는 없다 |
+| `ContentTransition` `stateKey`·`children` | `string`·`ReactNode` | — (필수) | `stateKey`가 바뀔 때 하위 트리를 전환한다 |
+| `ContentTransition` `focusTarget`(Web) | `RefObject<HTMLElement \| null>` | — | 전환 전 포커스가 바뀌는 하위 트리 안에 있었으면 전환 뒤 이 요소로 포커스를 옮긴다 |
+
+첫 렌더에는 모션이 없다. 길이는 `motion.normal`, 곡선은 `easing.enter`(foundations).
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 바깥 여백·크기 prop이 없다. 높이는 새 문자열에 맞춰 즉시 바뀐다(높이 보간 없음). 자리를 고정하려면 부모에 최소 높이를 준다 | `react/src/content-transition.tsx`, `react-native/src/content-transition.tsx` |
+| 간격 | 위치와 이웃 간격은 감싸는 [Stack](stack.md) 등의 `gap`으로 준다 | — |
+| 순서·정렬 | 블록 요소다(Web `<div>` 두 겹, Native `Animated.View`). 문장 중간에 인라인으로 끼우지 않고 한 줄(또는 한 덩어리)로 둔다 | `react/src/content-transition.tsx`, `react-native/src/content-transition.tsx` |
+| 고정·스크롤 | 이동량은 `rise` 세로 12, `slide` 가로 16이다. 부모가 `overflow: hidden`이면 시작 위치가 잘려 보일 수 있다 | `design-contracts/src/content-transition.ts` |
+| 좁은 폭·큰 글자 | 좁은 폭에서 문구 길이 차이로 줄 수가 바뀌면 아래 요소가 튄다(크기 행 참고) | `react/src/content-transition.tsx` |
+
+## 꼭 지킬 것
+
+- 문자열은 i18n 키로 만든 최종 문구를 넘긴다. 글자 수 변화를 노린 연출용으로 쓰지 않는다.
+- 글자 모양 prop은 없다. 글자 모양은 감싸는 쪽이 정한다(아래 플랫폼 차이). Web은 `layoutStyle`로 배치만 하고, Native는 배치 prop이 없어 감싸는 쪽이 배치한다.
+- Web에서 이 subpath를 쓰려면 앱에 `framer-motion`을 설치한다. 없으면 import 시점에 실패한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 글자 렌더 | `<div>` 안의 맨 텍스트(부모 글꼴 상속) | HJM `Text`로 감싼다 |
+| 전환 방식 | `stateKey`로 키를 바꿔 새 노드를 마운트 | 같은 노드의 opacity·transform 보간 |
+| 백그라운드 | 해당 없음 | 앱이 active가 아니면 전환 없이 즉시 표시 |
+| `layoutStyle` | 있음 | 없음 |

package/docs/usage/components/text.md

@@ -0,0 +1,101 @@
+# Text
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/component-recipes.ts`(`textRecipe`), [Gravity Letters](../../gravity-letters.md)
+- 스토리북: `배포/컴포넌트/글자와 아이콘/본문 글자`, `배포/컴포넌트/시각 효과/중력 글자`
+
+## 언제 쓰나
+
+화면의 모든 일반 글자에 쓴다. 본문·보조 설명·캡션·라벨·카드 안의 작은 제목(24px 이하)이 여기에
+속한다. 제품 CSS로 폰트 크기·굵기·색을 직접 쓰는 대신 `variant`·`emphasis`·`tone`으로 고른다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 문서 제목 단계(`h1`~)가 필요하거나 24px보다 큰 제목 | [Heading](heading.md) |
+| 화면 첫 자리의 제목 블록(보조 문장·행동 포함) | [Top](top.md) |
+| 본문 묶음의 헤더 행 | [Section](section.md) |
+| 숫자 지표와 그 라벨 | [Statistic](statistic.md) |
+| 다른 화면·URL로 가는 글자 | [Link](link.md) |
+| 숫자·날짜·코드 같은 형식 글자 | [TextFormat](text-format.md) |
+| 화면에는 숨기고 보조기기에만 읽힐 글자(Web) | [VisuallyHidden](visually-hidden.md) |
+
+Text와 Heading의 경계: Text의 `variant="heading"`(24px)은 **모양만** 제목이고 제목 role이 없다.
+보조기기의 제목 탐색에 잡혀야 하거나 더 큰 크기가 필요하면 Heading을 쓴다. Heading은 여백을 갖지 않는다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Text` | 기본 | `@hjmds/react`, `/layout` | `@hjmds/react-native`, `/primitives` |
+| `GravityLetters` | 확장(홍보용 글자 낙하 장식, optional-extension) | `/gravity-letters` | `/gravity-letters` |
+
+`GravityLetters`는 granular subpath로만 import 된다. 추가 peer 의존성은 없다(Web은 WAAPI, Native는 RN `Animated`).
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Text } from "@hjmds/react/layout";
+
+<Text as="p" variant="body" tone="muted">{t("profile.bioHint")}</Text>
+```
+
+```tsx
+// Native
+import { Text } from "@hjmds/react-native/primitives";
+
+<Text variant="body" tone="muted" numberOfLines={2}>{t("profile.bioHint")}</Text>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `caption`(11) · `label`(12) · `body`(14) · `bodyLarge`(16) · `title`(18) · `titleLarge`(20) · `heading`(24) | `body` | 화면·섹션 제목은 모양이 아니라 [Heading](heading.md)으로 쓴다 |
+| `emphasis` | `regular` · `medium`(semibold) · `strong`(bold) | `regular` | — |
+| `tone` | `primary` · `body` · `muted` · `subtle` · `weak` · `brand` · `danger` · `inverse` | `primary` | — |
+| `as` | `span` · `p` · `div` · `strong` · `small` | `span` | Web만. 문단은 `as="p"` |
+| `align` | `TextStyle["textAlign"]` | 쓰기 방향의 시작 쪽 | Native만 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 배치. Web·Native 모두 |
+| `GravityLetters` `glyphs` | `readonly string[]`(1~32개) | — (필수) | — |
+| `GravityLetters` `active`·`replayKey` | `boolean`·`string \| number` | `false`·`0` | `replayKey`가 바뀌면 다시 떨어진다. Web만 `layoutStyle`도 받는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭은 부모를 따른다. 긴 읽기 글은 부모 폭을 `layout.readingMaxWidth` 720 이하로 둔다 | `foundations.ts`(`layout`) |
+| 간격 | 바깥 여백이 없다(Web `margin: 0`). 문단 사이·라벨과 값 사이 간격은 부모 [Stack](stack.md)의 `gap`이나 `layoutStyle`로 준다. 본문 문단 묶음은 보통 `spacing.xs` 8~`spacing.sm` 12, 섹션 사이는 `layout.sectionGap`(`spacing.xl` 24) | `.hjm-text`, `foundations.ts`(`layout`, `spacing`) |
+| 순서·정렬 | Web은 부모가 정하고, Native는 `align`(생략 시 쓰기 방향의 시작 쪽)으로 정한다 | `react-native/src/primitives.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 줄이 늘어나 높이가 자란다. 자르려면 Native `numberOfLines`를 쓰고, 핵심 문구는 자르지 않는다 | `.hjm-text`(`overflow-wrap: anywhere`) |
+
+## 꼭 지킬 것
+
+- 글자는 i18n 키로 넣는다. 제품 이름·도메인 문구는 제품 소유, 크기·색 체계는 HJM 소유다.
+- 배치(여백·폭·flex)는 `layoutStyle`로만 한다. 색·크기·굵기는 `style`/`className`으로 덮지 않는다.
+  (Native Text의 `style`은 layout primitive라 deprecated 경고 대상에서 빠져 있을 뿐 권장 경로가 아니다.)
+- 색으로 의미를 바꿀 때는 `tone`만 쓴다(오류 문구 `danger`, 어두운 배경 위 `inverse`).
+- `GravityLetters`는 장식이며 접근성 트리에서 숨는다. 같은 문구의 정적 Text·Heading을 바깥에 함께 둔다.
+  `glyphs`는 32개 이하, 빈 문자열·줄바꿈 없이 넘긴다(어기면 `RangeError`). `active` 기본은 `false`다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 요소 선택 | `as` | 없음(항상 RN `Text`) |
+| 정렬 | 없음(배치는 부모) | `align`(생략 시 방향에 맞춘 논리 정렬) |
+| 글자 크기 조정 | 브라우저 | provider `textScaling`이 `allowFontScaling`을 정함 |
+| 긴 단어 줄바꿈 | `overflow-wrap: anywhere` | RN 기본 |
+| import 경로 | `/layout` | `/primitives` |
+
+## 함정
+
+- `emphasis`가 `variant`의 굵기를 덮는다. `variant="title"`도 기본 `emphasis="regular"`면 보통 굵기로
+  그려진다. 굵은 제목이 필요하면 `emphasis="strong"`을 명시한다(두 renderer 동일).

package/docs/usage/components/thinking-orb.md

@@ -0,0 +1,105 @@
+# ThinkingOrb
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [ThinkingOrb](../../thinking-orb.md), `src/thinking-orb-recipe.ts`(`thinkingOrbRecipe`)
+- 스토리북: `배포/컴포넌트/상태와 알림/생각 중 표시`
+
+## 언제 쓰나
+
+AI 에이전트가 실제로 검색·생성·듣기 같은 작업을 하는 동안 그 단계를 보여 줄 때만 쓴다.
+상태(`state`)는 앱이 실제 작업 단계에서 넘긴다. orb가 진행률을 흉내 내지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 일반 로딩·대기 | [Spinner](spinner.md) |
+| 진행률을 아는 작업 | [Progress](progress.md) |
+| 콘텐츠 자리 표시 | [Skeleton](skeleton.md) |
+| 완료·오류 결과 | [Result](result.md), [Toast](toast.md) — orb를 결과 UI로 교체한다 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ThinkingOrb` | 기본(root에서는 내보내지 않는다) | `/thinking-orb` | `/thinking-orb` |
+
+granular subpath로만 가져온다. Native subpath는 optional native peer를 직접 import 한다.
+
+| renderer | 필요한 peer(`peerDependenciesMeta` optional) |
+| --- | --- |
+| Web | 없음(Canvas 2D) |
+| Native | `@shopify/react-native-skia` ^2.6.2, `react-native-reanimated` ^4.5.1와 그 전제 `react-native-worklets` ^0.10.1. 모두 native 모듈이라 설치 후 dev client를 다시 빌드한다 |
+
+계약 문서가 검증 대상으로 적은 조합은 Expo 57 / RN 0.86.2다. 기본 패키지의 `react-native >=0.81`
+범위가 이 subpath의 지원을 보장하지 않는다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ThinkingOrb } from "@hjmds/react/thinking-orb";
+
+<ThinkingOrb state="searching" label={t("agent.searching")} />
+```
+
+```tsx
+// Native
+import { ThinkingOrb } from "@hjmds/react-native/thinking-orb";
+
+<ThinkingOrb state="searching" size={20} label={t("agent.searching")} active={isFocused} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `state` | `working` · `searching` · `solving` · `listening` · `connecting` · `weaving` · `composing` · `breathing` · `shaping` | `working` | `listening`은 음성 크기 시각화가 아니다 |
+| `appearance` | `state`(상태별 기하) · `fluid` · `matrix` | `state` | — |
+| `size` | `64` · `20` | `64` | 다른 값은 `RangeError` |
+| `label`(필수) | 번역된 현재 작업 설명 | — | 비거나 공백이면 `TypeError` |
+| `speed` | 0 초과 4 이하 | `1` | — |
+| `paused` | `boolean` | `false` | — |
+| `active` | `boolean` | `true` | — |
+| `layoutStyle`(Web) | `HjmCompositionStyleProp` | — | 바깥 요소 배치. `style`과 겹치면 `layoutStyle`이 이긴다 |
+| `style` | Web `CSSProperties`, Native `StyleProp<ViewStyle>` | — | Native는 `layoutStyle`이 없어 `style`이 배치 통로다(optional motion host frame이라 deprecated 대상에서 빠졌다). 배치 key만 넣는다 |
+
+색은 provider의 `text` 색을 깊이별 opacity로 쓴다. 색 prop은 없다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 정사각형 고정 크기 `size` 20 또는 64. 안쪽·바깥 여백이 없다. 누를 수 없는 표시라 터치 영역 요구가 없다 | `thinkingOrbRecipe`(`sizes: [20, 64]`) |
+| 간격 | 문구와 나란히 둘 때 간격은 감싸는 [Stack](stack.md)의 `gap`(예: `spacing.xs` 8)으로 준다 | — |
+| 순서·정렬 | 20은 작업 문구 한 줄과 나란히, 64는 영역 가운데 단독으로 둔다. Web 바깥 요소는 `inline-flex`라 글줄 안에도 놓인다. 버튼 안 로딩 표시로 쓰지 않는다(버튼은 `loading`). 작업이 끝나면 같은 자리를 결과 UI로 바꾸고 orb와 결과를 함께 두지 않는다 | `react/src/thinking-orb.tsx` |
+| 고정·스크롤 | — | — |
+| 좁은 폭·큰 글자 | 큰 글자 설정에도 크기가 변하지 않는다 | `react/src/thinking-orb.tsx`, `react-native/src/thinking-orb.tsx` |
+
+## 꼭 지킬 것
+
+- Native에서는 탭·내비게이션·가상 목록에서 화면이 가려지면 `active={false}`를 넘긴다.
+  mounted 상태로 숨은 화면은 AppState로 알 수 없어 계속 그린다.
+- orb가 live region(Web `role="status"`, Native progressbar + `accessibilityLiveRegion`)이다.
+  같은 문구를 옆에 또 보여 줄 때 그 문구에 live region을 중복으로 두지 않는다.
+- 크기는 `size`로만 바꾼다. CSS·transform으로 확대하지 않는다.
+- 배치는 Web `layoutStyle`, Native `style`로 하고 배치 key(margin·`alignSelf` 등)만 넣는다. Web `className`·`style`로 크기·색을 바꾸지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그리기 | Canvas 2D, 보이지 않으면(IntersectionObserver·문서 숨김) 정지 | Skia Picture, 백그라운드·`active=false`면 정지 |
+| 모션 줄이기 | provider `reducedMotion` | provider 값 또는 OS 설정. OS 값을 읽기 전에는 정지 프레임으로 시작 |
+| 접근성 | `role="status"` + 숨긴 텍스트 | `accessibilityRole="progressbar"`, `busy: true` |
+| 추가 prop | `className`, `layoutStyle` | `testID`(`layoutStyle` 없음) |
+
+## 함정
+
+- 2026-10 소비 앱에서 이 subpath를 쓰면서 Skia·Reanimated 같은 optional native peer를
+  설치하지 않아 tsc·테스트는 통과했는데 기기 Metro에서 크래시가 났다. 타입 검사는 peer 설치를
+  증명하지 않는다. Native 채택 전에 위 peer를 앱 `package.json`에 넣고 설치 앱에서 실제로 그려지는지 확인한다.

package/docs/usage/components/timeline.md

@@ -0,0 +1,105 @@
+# Timeline
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Timeline](../../timeline.md), `src/timeline.ts`(`timelineRecipe`)
+- 스토리북: `배포/컴포넌트/데이터 표시/타임라인`
+
+## 언제 쓰나
+
+이미 일어난 일을 시간 순서대로 보여 줄 때 쓴다. 경기 플레이 기록, 이적·변경 이력, 주문 처리
+기록처럼 "무슨 일이 언제 있었나"를 위→아래 한 방향으로 나열한다. 현재 위치(커서)는 없다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 흐름에서 지금 어디에 있는지(현재 단계) | [Steps](steps.md) |
+| 항목을 눌러 이동·선택 | [List](list.md), [ListRow](list-row.md) |
+| 항목이 하나도 없음 | Timeline을 마운트하지 않고 [EmptyState](empty-state.md) |
+| 과거 기록을 더 불러옴 | Timeline 아래에 [LoadMore](load-more.md)를 합성 |
+| 항목별 짧은 배지 | 새 필드 없음. 제품 화면에서 [Tag](tag.md)로 조합 |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Timeline` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+
+항목 타입 `TimelineItemDescriptor`는 `@hjmds/design-contracts/components/timeline`에 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Timeline } from "@hjmds/react/display";
+
+// 상태 → i18n 키 상수 표. 키를 템플릿 문자열로 만들지 않는다.
+const playEventKey = {
+  hit: "pbp.event.hit",
+  out: "pbp.event.out",
+  run: "pbp.event.run",
+} as const;
+
+<Timeline
+  items={plays.map((play) => ({
+    id: play.id,
+    label: t(playEventKey[play.kind]),
+    timestamp: formatInning(play.inning), // 제품이 포맷한 문자열
+    tone: play.scored ? "success" : "neutral",
+  }))}
+  composeAccessibleName={({ position, total, label }) =>
+    t("pbp.itemA11y", { position, total, label })}
+/>
+```
+
+```tsx
+// Native
+import { Timeline } from "@hjmds/react-native/data-display";
+
+<Timeline
+  items={items}
+  composeAccessibleName={({ position, total, label }) =>
+    t("pbp.itemA11y", { position, total, label })}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items`(필수) | `id`·`label` 필수, `timestamp`·`description`·`tone` 선택 | — | 배열 순서가 곧 표시 순서 |
+| `items[].tone` | `neutral` · `info` · `success` · `attention` | `neutral` | `warning`·`danger`는 없다 |
+| `composeAccessibleName`(필수) | `(info: { position: number, total: number, label: string }) => string` | — | position은 1부터 |
+| `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치. Web·Native 모두 |
+| `style`(Native) | `StyleProp<ViewStyle>` | — | deprecated — `layoutStyle`. 개발 모드에서 한 번 경고하고 다음 major에서 제거된다 |
+| 나머지 | Web `<ol>` 속성, Native `ViewProps`(`style` 제외) | — | — |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 각 항목은 [레일 16][본문] 두 열. 레일은 지름 10의 dot과 다음 항목까지 이어지는 1px connector. 항목은 누를 수 없어 터치 영역 요구가 없고 행 안에 버튼을 넣지 않는다 | `timelineRecipe`, `.hjm-timeline__item`·`__dot`·`__connector` |
+| 간격 | 항목 사이 `spacing.md` 16, 레일과 본문 열 간격 `spacing.sm` 12, 본문 줄 간격 `spacing.xxs` 4 | `timelineRecipe.gap`, `.hjm-timeline*` |
+| 순서·정렬 | 본문은 label·timestamp 줄 → description. Web은 label과 timestamp를 한 줄 양 끝에 둔다 | `.hjm-timeline__heading` |
+| 고정·스크롤 | 본문 스크롤 영역 안의 한 섹션으로 폭을 꽉 채운다. 더 불러오기는 Timeline 아래에 [LoadMore](load-more.md) | — |
+| 좁은 폭·큰 글자 | Web은 좁으면 timestamp가 다음 줄로 내려간다(`flex-wrap`). 큰 글자에서도 글을 자르지 않는다 | `.hjm-timeline__heading`·`__label` |
+
+## 꼭 지킬 것
+
+- `timestamp`·`description`은 제품이 날짜·이닝을 이미 포맷한 문자열이다. Timeline은 시간 계산을 하지 않는다.
+- 빈 배열, 중복 `id`, 앞뒤 공백이 있는 `id`, 빈 문자열 필드, 목록 밖 tone은 실행 중 오류를 던진다.
+- 접근 이름의 어순은 언어마다 다르므로 `composeAccessibleName`은 i18n 키로 만든다.
+- 제품 고유 색(구단 색 등)은 adapter에서 네 tone 중 하나로 먼저 매핑한다. dot 색을 직접 칠하지 않는다.
+- 배치는 `layoutStyle`로 한다. Web `className`/`style`과 Native의 deprecated `style`로 dot·connector·글자 색을 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 구조 | `<ol>` / `<li>`, dot·connector `aria-hidden` | `View` 행, rail·본문은 접근성 트리에서 숨김 |
+| 항목 접근 이름 | `<li aria-label={accessibleName}>` | `accessibleName, timestamp, description`을 이어 붙인 `accessibilityLabel` |
+| ref | `HTMLOListElement`로 전달 | 없음(함수 컴포넌트) |