@hjmds/design-contracts 1.26.1 → 1.27.0

package/docs/usage/components/target-summary.md

@@ -0,0 +1,79 @@
+# TargetSummary
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [데이터 구성 계약](../../data-workflows.md), `src/data-workflows.ts`의 `resolveTarget`, 양 renderer `src/data-workflows.tsx`
+- 스토리북: `배포/구성/정보 표시/목표 달성 요약`
+
+## 언제 쓰나
+
+실적과 목표를 받아 실적 수치, 달성 설명, 달성률 막대를 한 묶음으로 보여 준다. 달성률은 `actual / target`을 1에서
+멈춘 값이다. 목표가 0이면 비율의 분모가 없으므로 막대를 그리지 않고 100% 달성으로 꾸미지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 목표 없는 단일 수치 | [Statistic](statistic.md) |
+| 작업 진행률(업로드·단계) | [Progress](progress.md), [TransferTask](transfer-task.md) |
+| 여러 계열의 시간 추이 | [Chart](chart.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TargetSummary` | 실적·목표 달성 요약 | `@hjmds/react/data-workflows` | `@hjmds/react-native/data-workflows` |
+
+`resolveTarget`은 `@hjmds/design-contracts/data-workflows`에서 가져온다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { TargetSummary } from "@hjmds/react/data-workflows";
+
+<TargetSummary label={t("sales.monthly")} actual={actual} target={target}
+  formatActual={value => formatCurrency(value, locale)}
+  summaryLabel={s => s.ratio === null ? t("sales.noTarget") : t("sales.achieved", { percent: formatPercent(s.ratio) })} />
+```
+
+```tsx
+// Native
+import { TargetSummary } from "@hjmds/react-native/data-workflows";
+
+<TargetSummary label={t("sales.monthly")} actual={actual} target={target}
+  formatActual={value => formatCurrency(value, locale)}
+  summaryLabel={s => s.ratio === null ? t("sales.noTarget") : t("sales.achieved", { percent: formatPercent(s.ratio) })} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | string | 필수 | 수치 라벨이자 막대 이름 |
+| `actual` · `target` | number | 필수 | 유한한 0 이상 값. 아니면 `RangeError` |
+| `formatActual` | `(actual) => string` | 필수 | 실적 표시 문자열 |
+| `summaryLabel` | `(summary) => string` | 필수 | `summary`는 `{ actual, target, difference, ratio, progress }`. 목표 0이면 `ratio`·`progress`가 `null` |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | [Statistic](statistic.md) 기본(`comfortable`), [Progress](progress.md) 기본 `medium` 두께 8 | `data-workflows.tsx` |
+| 간격 | 수치와 막대 사이 `spacing.sm` 12 | `Stack gap="sm"` |
+| 순서·정렬 | 수치(라벨·값·`summaryLabel` hint) → 달성률 막대 | 양 renderer |
+| 고정·스크롤 | 없음. 카드·대시보드 격자가 정한다 | — |
+| 좁은 폭·큰 글자 | 막대는 부모 폭을 채우고 문구는 Statistic 규칙으로 줄바꿈 | Progress·Statistic 지침 |
+
+## 꼭 지킬 것
+
+- `summaryLabel`은 `ratio === null`(목표 0)을 따로 처리한다. 이 경우 막대가 없다.
+- 100%를 넘는 실적도 막대는 가득 찬 상태에서 멈춘다. 초과분은 `difference`로 문구에 적는다.
+- 숫자·통화·백분율 형식은 제품 locale로 만든다.
+
+## 관련 지침
+
+[데이터 해석과 가져오기](../compositions/data-workflows.md), [Statistic](statistic.md), [Progress](progress.md).

package/docs/usage/components/text.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-07
+- 검토일: 2026-10-17
 - 근거: `src/component-recipes.ts`(`textRecipe`), [Gravity Letters](../../gravity-letters.md)
 - 스토리북: `배포/컴포넌트/글자와 아이콘/본문 글자`, `배포/컴포넌트/시각 효과/중력 글자`
 
@@ -61,13 +61,13 @@ import { Text } from "@hjmds/react-native/primitives";
 | --- | --- | --- | --- |
 | `variant` | `caption`(11) · `label`(12) · `body`(14) · `bodyLarge`(16) · `title`(18) · `titleLarge`(20) · `heading`(24) | `body` | 화면·섹션 제목은 모양이 아니라 [Heading](heading.md)으로 쓴다 |
 | `fontRole` | `ui` · `display` · `reading` · `code` | 제목 variant는 display, 본문은 reading, caption/label은 ui | 명시값이 기본을 덮는다. [역할 지침](../tokens/font-roles.md), 1.16.0 변경 |
-| `emphasis` | `regular` · `medium`(semibold) · `strong`(bold) | 프로필이 있으면 variant 굵기, 없으면 `regular` | 명시값이 프로필과 variant보다 우선 |
+| `emphasis` | `regular` · `medium`(semibold) · `strong`(bold) | 프로필이 있으면 variant 굵기, 없으면 `regular`. `label`은 프로필과 무관하게 variant 굵기 500 | 명시값이 프로필과 variant보다 우선 |
 | `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`도 받는다 |
+| `GravityLetters` `active`·`replayKey` | `boolean`·`string \| number` | `false`·`0` | `replayKey`가 바뀌면 다시 떨어진다. Web만 `layoutStyle`도 받는다. Native만 `level`(Heading 단계)을 받는다 — Web은 바깥 Heading의 글자 모양을 물려받는다 |
 
 ## 배치
 
@@ -87,7 +87,7 @@ Native는 Text의 역할을 해당 stack에, 입력/조작 host는 제품 프로
 - 배치(여백·폭·flex)는 `layoutStyle`로만 한다. 색·크기·굵기는 `style`/`className`으로 덮지 않는다.
   (Native Text의 `style`은 layout primitive라 deprecated 경고 대상에서 빠져 있을 뿐 권장 경로가 아니다.)
 - 색으로 의미를 바꿀 때는 `tone`만 쓴다(오류 문구 `danger`, 어두운 배경 위 `inverse`).
-- `GravityLetters`는 장식이며 접근성 트리에서 숨는다. 같은 문구의 정적 Text·Heading을 바깥에 함께 둔다.
+- `GravityLetters`는 장식이며 접근성 트리에서 숨는다. 읽을 수 있는 같은 문구를 함께 두되 화면에 두 번 보이지 않게 한다: Web은 같은 Heading 안의 `VisuallyHidden`, Native는 `accessibilityRole="header"`·`accessibilityLabel`을 가진 감싸는 View.
   `glyphs`는 32개 이하, 빈 문자열·줄바꿈 없이 넘긴다(어기면 `RangeError`). `active` 기본은 `false`다.
 
 ## 플랫폼 차이
@@ -103,8 +103,14 @@ Native는 Text의 역할을 해당 stack에, 입력/조작 host는 제품 프로
 ## 함정
 
 - `emphasis`를 명시하면 `variant`의 굵기를 덮는다. `designProfile`이 있으면 생략한 `emphasis`는 해당 프로필의 `tokens.typography[variant].fontWeight`를 따른다. 프로필이 없으면 기존 기본값 `regular`를 유지하므로 `variant="title"`도 보통 굵기로 그려진다. 그 경우 굵은 제목은 `emphasis="strong"`으로 지정한다(두 renderer 동일).
+- `variant="label"`은 예외로, 프로필이 없어도 생략한 `emphasis`가 `typography.label` 굵기 500(medium)으로 그려진다. 500은 `emphasis` 단계에 없으므로(`medium`은 600) label을 400으로 그리려면 `emphasis="regular"`를 명시한다.
+  Web은 이 기본 굵기를 inline `font-weight`로 주며 `data-emphasis`는 `regular`로 남는다. Native는 `fonts="pretendard"`일 때 `Pretendard-Medium` face로 그린다.
 
 
+## 근거
+
+2026-10-17 사용자 결정: 폼 라벨·섹션 부제목이 본문 대비 약해 `label` 기본 굵기를 500으로 정했다(본문 400과 제목 600 사이). 이전에는 토큰이 600이었지만 프로필 없는 Text는 400으로 그렸다. 두 renderer는 `resolveTextDefaultWeight`(`src/component-recipes.ts`) 하나로 기본 굵기를 고른다.
+
 ## StatusText
 
 Text와 같은 표현을 유지하면서 상태 변경 알림을 연결하는 공개 companion이다.
@@ -147,7 +153,7 @@ StatusText: 결과 문자열
 
 | prop | 기본값 | 의미 |
 | --- | --- | --- |
-| `children: string` | 필수 | 제품의 지역화된 상태 문구. 빈 문자열도 허용 |
+| `children: string` | 필수 | 제품의 지역화된 상태 문구. 빈 문자열도 허용. Web은 빈 동안 live node를 유지한 채 레이아웃에서 빠져 부모 Stack gap을 만들지 않는다. Native는 비어 있으면 렌더하지 않는 조건부 결과로 둔다 |
 | `announcement` | `polite` | `none`·`polite`·`assertive`. 시각적 tone과 알림 우선순위는 독립 |
 | `announceOnMount` | `false` | Native iOS 옵션. 조건부로 새로 나타난 행동 결과를 처음에도 알림 |
 | 나머지 Text props·ref | Text와 같음 | Web role/live/atomic, Native live region은 StatusText가 소유 |

package/docs/usage/components/toggle-feedback-button.md

@@ -0,0 +1,94 @@
+# ToggleFeedbackButton
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [선택 반응 계약](../../toggle-feedback.md), `src/toggle-feedback.ts`의 `resolveToggleFeedbackProposal`·`toggleFeedbackRecipe`, 양 renderer `src/toggle-feedback.tsx`
+- 스토리북: `배포/구성/직접 조작과 모션/선택 반응 버튼`
+
+## 언제 쓰나
+
+좋아요·저장·알림 받기처럼 켜고 끄는 선택에 반응 모션과 개수를 붙인다. 누르면 예상 상태(선택·개수)를 바로 보여 주고,
+제품이 실제 API 응답으로 확정한 `state`를 다시 넘긴다. 실패하면 확정 상태로 돌아가고 오류를 알린다.
+효과는 `ripple`(종) · `ribbon`(책갈피) · `burst`(하트) 세 가지이며 선택으로 바뀌는 순간에만 재생한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 개수·모션 없는 켜기/끄기 | [Button](button.md)의 `selected`, [Switch](switch.md) |
+| 설정 값 켜기/끄기 | [Switch](switch.md) |
+| 팔로우 상태 기계 | [FollowProfileCard](follow-profile-card.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ToggleFeedbackButton` | 선택 반응 버튼 + 개수 | `@hjmds/react/toggle-feedback` | `@hjmds/react-native/toggle-feedback` |
+
+`ToggleFeedbackState`·`ToggleFeedbackEffect` 타입은 `@hjmds/design-contracts/toggle-feedback`에서 가져온다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { ToggleFeedbackButton } from "@hjmds/react/toggle-feedback";
+
+<ToggleFeedbackButton entityId={post.id} effect="burst" locale={locale}
+  state={{ selected: post.liked, count: post.likeCount }} labels={likeLabels}
+  onSelectedChange={async selected => { const next = await setLike(post.id, selected); updatePost(next); }} />
+```
+
+```tsx
+// Native
+import { ToggleFeedbackButton } from "@hjmds/react-native/toggle-feedback";
+
+<ToggleFeedbackButton entityId={post.id} effect="burst" locale={locale}
+  state={{ selected: post.liked, count: post.likeCount }} labels={likeLabels}
+  onSelectedChange={async selected => { const next = await setLike(post.id, selected); updatePost(next); }} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `entityId` | string | 필수 | 안정적인 id. 비면 던지고, 바뀌면 진행 상태를 새로 시작한다 |
+| `state` | `{ selected, count }` | 필수 | 확정 상태. `count`는 0 이상 정수, 선택인데 0이면 `RangeError` |
+| `effect` | `"ripple"` · `"ribbon"` · `"burst"` | 필수 | 아이콘 모양과 반응 모션 |
+| `locale` | string | 필수 | 개수 형식 |
+| `labels` | `{ select, selected, pending, count, error }` | 필수 | 버튼 문구·진행 중 이름·개수 라벨·실패 문구 |
+| `onSelectedChange` | `(selected) => void \| Promise<void>` | 필수 | 실제 API를 호출하고 확정 `state`를 갱신한 뒤 끝낸다 |
+| `icon` · `renderIcon` | ReactNode · `({ selected, pending }) => ReactNode` | 기본 효과 아이콘 | 제품 아이콘. `renderIcon`이 우선 |
+| `disabled` | boolean | false | 잠금 |
+| `active` | boolean | true | false면 잠그고 모션·개수 애니메이션을 끈다(화면 밖 등) |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 아이콘 24, 효과 영역 40(아이콘 둘레 −8 오프셋), 버튼은 `secondary` [Button](button.md) 기본 `medium`(높이 44) | `toggleFeedbackRecipe` `glyphSize`·`effectSize` |
+| 간격 | 버튼과 개수 사이 `spacing.md` 16, 버튼 줄과 실패 문구 사이 `spacing.sm` 12 | `Stack gap="md"`, 바깥 `gap="sm"` |
+| 순서·정렬 | [아이콘+문구 버튼] → 개수(`AnimatedStatistic` `compact`), 세로 가운데 맞춤. 실패 문구는 아래 가운데 | 양 renderer |
+| 고정·스크롤 | 없음. 카드·행 안 행동 영역에 둔다 | — |
+| 좁은 폭·큰 글자 | 버튼 줄이 `wrap`으로 줄바꿈 | `Stack axis="inline" wrap` |
+
+## 꼭 지킬 것
+
+- 개수를 타이머·클라이언트 계산으로 확정하지 않는다. 진행 중 표시만 예상값이고 확정은 API 응답 `state`다.
+- 모션은 비선택→선택 전환에서만 재생한다. 동작 줄이기, `active={false}`, 화면이 숨겨진 상태에서는 즉시 마지막 프레임으로 끝낸다.
+- 이미 선택된 상태로 처음 그려지거나 환경이 바뀌어도 모션을 다시 재생하지 않는다.
+- 문구·개수 라벨은 제품 i18n에서 만든다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 진행 중 이름 | `aria-label={labels.pending}` | `loadingLabel={labels.pending}` |
+| 모션 | `requestAnimationFrame`, `visibilitychange`로 숨김 시 종료 | `Animated.timing`, `AppState`가 active가 아니면 종료 |
+| 실패 알림 | `role="alert"` | `accessibilityRole="alert"`, `accessibilityLiveRegion="assertive"` |
+
+## 관련 지침
+
+[선택 반응 버튼](../compositions/toggle-feedback.md), [Button](button.md), [Statistic](statistic.md).

package/docs/usage/components/top-bar.md

@@ -4,13 +4,13 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-07
+- 검토일: 2026-10-17
 - 근거: [화면 제목과 마지막 행동](../../screen-chrome.md), [NavigationBar](../../navigation-bar.md), `src/component-recipes.ts`(`topBarRecipe`)
 - 스토리북: `배포/컴포넌트/탐색/상단 탐색 막대`, `배포/컴포넌트/탐색/검색·메뉴가 있는 상단 바`, `배포/컴포넌트/탐색/내비게이션 바`
 
 ## 언제 쓰나
 
-화면 맨 위에 붙는 **크롬**에 쓴다. 뒤로가기·닫기(`leading`), 짧은 화면 이름(`title`), 소수의 행동
+화면 맨 위에 붙는 **크롬**에 쓴다. 뒤로가기·닫기(`exit`), 짧은 화면 이름(`title`), 소수의 행동
 (`actions`/`trailing`)을 담는다. 스크롤과 무관한 자리이며 safe area 위쪽 여백을 처리한다.
 
 ## 쓰지 않을 때
@@ -38,12 +38,11 @@ Top과 TopBar의 구분: TopBar는 고정 크롬(이동·화면 이름·액션),
 
 ```tsx
 // Web
-import { IconButton } from "@hjmds/react/actions";
 import { TopBar } from "@hjmds/react/top-bar";
 
 <TopBar
   title={t("settings.title")}
-  leading={<IconButton label={t("common.back")} onClick={goBack}><BackIcon /></IconButton>}
+  exit={{ kind: "back", label: t("common.back"), onClick: goBack }}
 />
 ```
 
@@ -54,11 +53,7 @@ import { TopBar, TopBarAction } from "@hjmds/react-native/top-bar";
 <TopBar
   title={t("settings.title")}
   safeAreaTop={insets.top}
-  leading={
-    <TopBarAction label={t("common.back")} labelVisibility="accessibility-only" onPress={goBack}>
-      <BackIcon />
-    </TopBarAction>
-  }
+  exit={{ kind: "back", label: t("common.back"), onPress: goBack }}
   actions={<TopBarAction label={t("common.save")} onPress={save}><SaveIcon /></TopBarAction>}
 />
 ```
@@ -67,14 +62,15 @@ import { TopBar, TopBarAction } from "@hjmds/react-native/top-bar";
 
 | prop | 값 | 기본값 | 설명 |
 | --- | --- | --- | --- |
-| `centered` | `boolean` | `true` | 남은 제목 영역 안에서의 정렬이며 좌우 열을 같은 폭으로 맞추지 않는다 |
 | `safeAreaTop` | 0 이상 유한수 | 0 | Web은 `env(safe-area-inset-top)`과 큰 값을 쓴다 |
 | `headingLevel` | 1~6 | 1 | Web만. 페이지 구조에 맞춘다 |
 | `onTitleClick`(Web) | `(event: MouseEvent<HTMLButtonElement>) => void` | — | 제목을 버튼으로 만든다 |
 | `onTitlePress`(Native) | `(event: GestureResponderEvent) => void` | — | 제목을 버튼으로 만든다 |
 | `subtitle` | `string` | — | 제목 아래 보조 문맥. 제목이 필요하며 배치·색·글자 규격은 HJM이 소유(1.24.0) |
 | `titleLeading` | `ReactNode` | — | 제목 앞 작은 시각 요소 |
-| `leading` / `actions`(별칭 `trailing`) | `ReactNode` | — | 둘 중 한 이름만 쓴다 |
+| `centered` | `boolean` | `true` | 제목 가운데 정렬(기본). `false`면 왼쪽 정렬 |
+| `exit` | `{ kind: "back" \| "close"; label; onClick(Web) \| onPress(Native); disabled? }` | — | 화면 나가기를 시작 쪽 아이콘 버튼으로 고정한다(글자 없음, `label`은 보조기술 이름). `leading`과 함께 주면 `TypeError`. [ScreenLayout `exit`](screen-layout.md)과 같은 버튼. 2026-10-17 추가, 미게시 |
+| `leading` / `actions`(별칭 `trailing`) | `ReactNode` | — | `actions`·`trailing`은 둘 중 한 이름만 쓴다. 뒤로·닫기는 `leading`으로 만들지 않고 `exit`을 쓴다 |
 | `layoutStyle` | `HjmCompositionStyleProp` | — | 루트 배치. Web·Native 모두 |
 | Native `style`·`leadingStyle`·`titleStyle`·`trailingStyle` | 지원하지 않음 | — | 제거된 속성 — `layoutStyle` 또는 `centered`. 현재 공개 props에서 제거되었다 |
 | `TopBarAction` `intent` | `button` · `link` | `button` | `button`은 `onPress: (event) => void`, `link`는 `destination` + `onNavigate?: (destination: LinkDestination) => void \| Promise<void>` 또는 `renderLink` |
@@ -91,7 +87,7 @@ NavigationBar의 Native 프레임 모서리는 Provider의 `tokens.radius.xl`을
 | --- | --- | --- |
 | 크기 | 최소 높이 `control.buttonHeight.large` 52 + 위쪽 안전 영역. Web은 `max(env(safe-area-inset-top), safeAreaTop)`을 위 여백으로, Native는 `safeAreaTop`을 `paddingTop`과 `minHeight`(52 + `safeAreaTop`)에 더한다. 좌우 열 최소 폭 `control.minTouchTarget` 44, Native `TopBarAction` 최소 44×44 | `topBarRecipe.minHeight`·`sideMinWidth`·`action`, `.hjm-top-bar` |
 | 간격 | 좌우 여백 `spacing.md` 16, 슬롯 사이·슬롯 안 행동 사이 `spacing.xs` 8. `TopBarAction` 아이콘–라벨 `spacing.xxs` 4, 좌우 여백 4. 배경 `canvas` | `topBarRecipe.paddingHorizontal`·`gap`·`action` |
-| 순서·정렬 | 세 열: `leading`(뒤로·닫기) · 제목 · `actions`(끝 정렬). `centered`(기본)는 남은 제목 영역 안에서만 가운데 정렬. 행동은 1~2개만 끝 열에, 넘치면 하나만 남기고 [Menu](menu.md)로 묶는다. 주 행동(저장·완료)은 끝 열의 마지막 | `.hjm-top-bar` grid, Native `TopBar` |
+| 순서·정렬 | 세 열: `leading`(뒤로·닫기) · 제목 · `actions`(끝 정렬). `centered`(기본 `true`)는 남은 제목 영역 안에서 가운데 정렬. 왼쪽 정렬은 `centered={false}`로 고른다. 행동은 1~2개만 끝 열에, 넘치면 하나만 남기고 [Menu](menu.md)로 묶는다. 주 행동(저장·완료)은 끝 열의 마지막 | `.hjm-top-bar` grid, Native `TopBar` |
 | 고정·스크롤 | 화면 맨 위, 스크롤 영역 **밖**에 둔다. TopBar 자체는 `position: sticky`/고정을 걸지 않으므로 화면 골격이 그 아래에 스크롤 영역을 둬야 고정된다. 바로 아래 본문 첫 블록은 [Top](top.md) | `.hjm-top-bar`(position 없음) |
 | 좁은 폭·큰 글자 | 글자 배율 ≥ `largeTextThreshold` 1.6: Web은 첫 행 leading·행동, 둘째 행 제목(시작 정렬, 위아래 `spacing.xs` 8). Native는 첫 행 leading+제목, 둘째 행 행동(끝 정렬, 줄바꿈 허용) | `.hjm-top-bar[data-large-text]`, `react-native/src/navigation.tsx` `TopBar` |
 

package/docs/usage/components/transfer-task.md

@@ -0,0 +1,87 @@
+# TransferTask
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [실제 전송 계약](../../transfer-task.md), `src/transfer-task.ts`의 `resolveTransferObservation`·`isConfirmedTransferAbort`, 양 renderer `src/transfer-task.tsx`
+- 스토리북: `배포/구성/피드백과 복구/전송 진행과 취소`
+
+## 언제 쓰나
+
+업로드·다운로드·동기화처럼 실제 전송 계층이 진행량을 알려 주는 작업에 시작·취소·진행률·결과를 한 묶음으로 붙인다.
+진행률은 어댑터가 `report`로 보낸 실제 수치만 쓴다. 총량을 모르면 진행 중 표시만 하고 백분율을 만들지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 파일 고르기 | [FilePicker](file-picker.md) |
+| 진행량 없는 짧은 요청 | [Button](button.md)의 `loading` |
+| 스트림으로 받는 답 | [StreamingAnswer](streaming-answer.md) |
+| 진행 막대만 필요할 때 | [Progress](progress.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `TransferTask` | 전송 시작·취소·진행 | `@hjmds/react/transfer-task` | `@hjmds/react-native/transfer-task` |
+
+`TransferObservation`·`TransferContext` 타입은 `@hjmds/design-contracts/transfer-task`에서 가져온다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { TransferTask } from "@hjmds/react/transfer-task";
+
+<TransferTask labels={uploadLabels}
+  onTransfer={({ signal, report }) => uploadFile(file, { signal, onProgress: (completed, total) => report({ completed, total }) })}
+  formatProgress={o => o.total === null ? formatBytes(o.completed) : t("upload.progress", { done: formatBytes(o.completed), total: formatBytes(o.total) })} />
+```
+
+```tsx
+// Native
+import { TransferTask } from "@hjmds/react-native/transfer-task";
+
+<TransferTask labels={uploadLabels}
+  onTransfer={({ signal, report }) => uploadFile(file, { signal, onProgress: (completed, total) => report({ completed, total }) })}
+  formatProgress={o => o.total === null ? formatBytes(o.completed) : t("upload.progress", { done: formatBytes(o.completed), total: formatBytes(o.total) })} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `onTransfer` | `({ signal, report }) => Promise<void>` | 필수 | 실제 전송. `report({ completed, total })`, 총량을 모르면 `total: null` |
+| `labels` | `{ start, queued, transferring, cancel, cancelling, cancelled, success, error }` | 필수 | 버튼·상태 문구 |
+| `formatProgress` | `(observation) => string` | 필수 | 진행 막대 값 문구 |
+| `disabled` | boolean | false | 시작·취소를 잠근다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 버튼은 [Button](button.md) 기본 `medium`(높이 44), 막대는 [Progress](progress.md) 기본 `medium` 두께 8, 부모 폭을 채운다 | `transfer-task.tsx` |
+| 간격 | 버튼 줄·막대·상태 사이 `spacing.md` 16, 버튼 사이 `spacing.sm` 12 | `Stack gap="md"`, 버튼 줄 `gap="sm"` |
+| 순서·정렬 | [시작] [취소(진행 중만)] → 진행 막대 → 결과 문구(가운데) | 양 renderer |
+| 고정·스크롤 | 없음. 놓는 영역이 정한다 | — |
+| 좁은 폭·큰 글자 | 버튼 줄이 `wrap`으로 줄바꿈 | `Stack axis="inline" wrap` |
+
+## 꼭 지킬 것
+
+- `signal`을 전송 계층에 연결한다. 취소 요청만으로 취소 완료가 아니며, 어댑터가 `AbortError`로 거부해야 `cancelled`다.
+- `completed`는 한 작업 안에서 줄어들 수 없고 `total`을 넘을 수 없다. 어기면 `RangeError`다.
+- 총량을 나중에 알게 돼도 완료량을 꾸미지 않는다. 작업이 끝난 뒤의 `report`는 무시된다.
+- 결과 문구는 `role="status"`, 실패는 경고로 알린다. 재시도는 같은 시작 버튼이다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 결과 알림 | `role="status"` / 실패 `role="alert"` | `accessibilityLiveRegion="polite"`, 실패 `accessibilityRole="alert"` |
+
+## 관련 지침
+
+[전송 진행과 취소](../compositions/transfer-task.md), [Progress](progress.md), [FilePicker](file-picker.md).

package/docs/usage/compositions/action-recovery-optimistic.md

@@ -46,7 +46,7 @@
 │ │ 제목 Heading level3 (선택)           │ │
 │ │          ↕ spacing.md 16             │ │
 │ │ [ 북마크 추가 / 해제 (selected) ]    │ │ ← 토글, 높이 44
-│ │          ↕ spacing.md 16             │ │
+│ │          ↕ spacing.xs 8 (행동 묶음)  │ │
 │ │ [ 북마크 다시 반영 (secondary) ]     │ │ ← error일 때만
 │ │          ↕ spacing.md 16             │ │
 │ │ 상태 문구 (role=status)              │ │
@@ -56,10 +56,10 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Web 문서 스크롤 > `Container`. Native `ScrollView` > `Container` | 이 구성을 감싸는 제품 화면(대상 콘텐츠 상세 등). 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
+| 바깥 틀 | Web 문서 스크롤 > `Container size="reading"`. Native `ScrollView` > `Container size="reading"` | 이 구성을 감싸는 제품 화면(대상 콘텐츠 상세 등). 넓은 화면에서도 버튼이 읽기 폭을 넘지 않는다. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
 | 제목(선택) | `Heading level="level3"` | Stack 맨 위 | 아래 `spacing.md` 16 |
-| 토글 | `Button selected` | 대상 콘텐츠 아래, 스크롤 | `medium` 44(`control.buttonHeight`), 이웃 `spacing.md` 16. Stack 기본 `align="stretch"`로 꽉 찬 폭 |
-| 재시도 | `Button tone="secondary"` | 토글 아래, error일 때만 | `medium` 44, `spacing.md` 16. 라벨은 무엇을 다시 하는지 적는다(`t("bookmark.retry")`) |
+| 토글 | `Button selected` | 대상 콘텐츠 아래, 스크롤 | `medium` 44(`control.buttonHeight`), 위 블록과 `spacing.md` 16. 재시도와 함께 `Stack gap="xs"` 행동 묶음에 둔다. Stack 기본 `align="stretch"`로 꽉 찬 폭 |
+| 재시도 | `Button tone="secondary"` | 토글 아래, error일 때만 | `medium` 44, 토글과 `spacing.xs` 8(`actionGroupRecipe`). 라벨은 무엇을 다시 하는지 적는다(`t("bookmark.retry")`) |
 | 상태 | `Text` | 행동 아래 | `spacing.md` 16 |
 
 - 토글이 목록 행 끝에 들어가면 Button 지침대로 `size="small"`(36, `control.buttonHitSlop.small` 4로 터치 44)과 `secondary`·`ghost`를 쓴다.
@@ -116,12 +116,14 @@ function BookmarkToggle({ initial, setBookmark }: { initial: boolean; setBookmar
   };
   const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
   return (
-    <Container gutter={gutter}>
+    <Container size="reading" gutter={gutter}>
       <Stack gap="md">
-        <Button selected={state.value} disabled={state.status === "pending"} onClick={toggle}>
-          {state.value ? t("bookmark.remove") : t("bookmark.add")}
-        </Button>
-        {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("bookmark.retry")}</Button>}
+        <Stack gap="xs">
+          <Button selected={state.value} disabled={state.status === "pending"} onClick={toggle}>
+            {state.value ? t("bookmark.remove") : t("bookmark.add")}
+          </Button>
+          {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("bookmark.retry")}</Button>}
+        </Stack>
         <Text as="p" role="status">{t(bookmarkStatusKey[state.status])}</Text>
       </Stack>
     </Container>
@@ -152,12 +154,14 @@ function BookmarkToggle({ initial, setBookmark }: { initial: boolean; setBookmar
   };
   return (
     <ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
-      <Container gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
+      <Container size="reading" gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
         <Stack gap="md">
-          <Button selected={state.value} disabled={state.status === "pending"} onPress={toggle}>
-            {state.value ? t("bookmark.remove") : t("bookmark.add")}
-          </Button>
-          {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("bookmark.retry")}</Button>}
+          <Stack gap="xs">
+            <Button selected={state.value} disabled={state.status === "pending"} onPress={toggle}>
+              {state.value ? t("bookmark.remove") : t("bookmark.add")}
+            </Button>
+            {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("bookmark.retry")}</Button>}
+          </Stack>
           <StatusText>{t(bookmarkStatusKey[state.status])}</StatusText>
         </Stack>
       </Container>

package/docs/usage/compositions/action-recovery-save.md

@@ -50,7 +50,7 @@
 │ │ [ 입력                             ] │ │ TextField, 높이 44
 │ │          ↕ spacing.md 16             │ │
 │ │ [        저장 (primary)            ] │ │ ← 주 행동, 높이 44
-│ │          ↕ spacing.md 16             │ │
+│ │          ↕ spacing.xs 8 (행동 묶음)  │ │
 │ │ [ 실패한 내용 다시 저장 (secondary)] │ │ ← error일 때만
 │ │          ↕ spacing.md 16             │ │
 │ │ 상태 문구 (role=status)              │ │
@@ -66,12 +66,12 @@
 | 바깥 틀 | Web 문서 스크롤 > `Container size="reading"`. Native `ScrollView`(`keyboardShouldPersistTaps="handled"`) > `Container size="reading"` | 이 구성을 감싸는 제품 화면. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
 | 제목 | `Heading level="level3"` | Stack 맨 위, 스크롤 | 아래 `spacing.md` 16 |
 | 입력 | `TextField` | 제목 아래, 스크롤 | 높이 `control.fieldHeight` 44 |
-| 주 행동 | `Button` 저장(primary) | 입력 바로 아래, 스크롤 | `medium` 44(`control.buttonHeight`), 이웃 `spacing.md` 16. Stack 기본 `align="stretch"`로 꽉 찬 폭이 되므로 `fullWidth`·`layoutStyle`은 필요 없다 |
-| 재시도 | `Button tone="secondary"` 다시 저장 | 주 행동 아래, error일 때만 | `medium` 44, `spacing.md` 16. 라벨은 무엇을 다시 하는지 적는다(스토리 "실패한 내용 다시 저장"). 일반 "다시 시도"만 쓰지 않는다 |
+| 주 행동 | `Button` 저장(primary) | 입력 바로 아래, 스크롤 | `medium` 44(`control.buttonHeight`), 입력과 `spacing.md` 16. 재시도와 함께 `Stack gap="xs"` 행동 묶음에 둔다. Stack 기본 `align="stretch"`로 꽉 찬 폭이 되므로 `fullWidth`·`layoutStyle`은 필요 없다 |
+| 재시도 | `Button tone="secondary"` 다시 저장 | 주 행동 아래, error일 때만 | `medium` 44, 주 행동과 `spacing.xs` 8(`actionGroupRecipe`). 라벨은 무엇을 다시 하는지 적는다(스토리 "실패한 내용 다시 저장"). 일반 "다시 시도"만 쓰지 않는다 |
 | 상태 | `Text` | 행동 아래 | `spacing.md` 16 |
 | 확정 값(선택) | `Text` — `state.value` | 상태 문구 아래 | `spacing.md` 16 |
 
-- 모든 간격은 `Stack gap="md"`(`spacing.md` 16) 하나로 맞춘다. `stackRecipe.defaults.gap`도 `md`다.
+- 블록 사이 간격은 `Stack gap="md"`(`spacing.md` 16)로 맞춘다. `stackRecipe.defaults.gap`도 `md`다. 세로로 쌓인 저장·재시도 버튼만 `Stack gap="xs"`(`spacing.xs` 8) 행동 묶음으로 둔다([버튼 묶음 간격](../SELECTION.md)).
 - 스토리는 좁은 폭 기준 바깥 틀(Web `Container gutter="compact" size="reading"`, Native `ScrollView` > 같은 Container)을 그린다. 넓은 폭에서는 위 표의 첫 행대로 `regular`를 고른다.
   키보드가 입력·저장 버튼을 가리는 Native 폼은 입력이 여러 개면 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)
   (peer 필요), peer가 없으면 [KeyboardAvoiding](../components/keyboard-avoiding.md) 기준을 따른다.
@@ -132,11 +132,13 @@ function SaveNote({ save }: { save(value: string): Promise<string> }) {
       <Stack gap="md">
         <Heading level="level3" semanticLevel={2}>{t("note.title")}</Heading>
         <TextField label={t("note.body")} value={draft} onValueChange={setDraft} />
-        <Button loading={state.status === "pending"} disabled={!draft.trim()}
-          onClick={() => { const submitted = draft; void session.run(() => save(submitted), { retryable: true }); }}>
-          {t("common.save")}
-        </Button>
-        {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("save.retry")}</Button>}
+        <Stack gap="xs">
+          <Button loading={state.status === "pending"} disabled={!draft.trim()}
+            onClick={() => { const submitted = draft; void session.run(() => save(submitted), { retryable: true }); }}>
+            {t("common.save")}
+          </Button>
+          {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("save.retry")}</Button>}
+        </Stack>
         <Text as="p" role="status">{t(saveStatusKey[state.status])}</Text>
         {state.value && <Text as="p">{t("save.savedValue", { value: state.value })}</Text>}
       </Stack>
@@ -171,11 +173,13 @@ function SaveNote({ save }: { save(value: string): Promise<string> }) {
         <Stack gap="md">
           <Heading level="level3" semanticLevel={2}>{t("note.title")}</Heading>
           <TextField label={t("note.body")} value={draft} onValueChange={setDraft} />
-          <Button loading={state.status === "pending"} disabled={!draft.trim()}
-            onPress={() => { const submitted = draft; void session.run(() => save(submitted), { retryable: true }); }}>
-            {t("common.save")}
-          </Button>
-          {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("save.retry")}</Button>}
+          <Stack gap="xs">
+            <Button loading={state.status === "pending"} disabled={!draft.trim()}
+              onPress={() => { const submitted = draft; void session.run(() => save(submitted), { retryable: true }); }}>
+              {t("common.save")}
+            </Button>
+            {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("save.retry")}</Button>}
+          </Stack>
           <StatusText>{t(saveStatusKey[state.status])}</StatusText>{/* 공개 Text companion */}
           {state.value ? <Text>{t("save.savedValue", { value: state.value })}</Text> : null}
         </Stack>

package/docs/usage/compositions/action-recovery-undo.md

@@ -50,7 +50,7 @@ Toast의 `action`을 진입점으로 쓰면 토스트는 진입점만, 세션은
 │ │ 대상: 목록 / 보관함 + 항목 이름      │ │
 │ │          ↕ spacing.md 16             │ │
 │ │ [ 보관 ]  →  [ 실행 취소 ]           │ │ ← 같은 자리, loading 중 스피너
-│ │          ↕ spacing.md 16             │ │
+│ │          ↕ spacing.xs 8 (행동 묶음)  │ │
 │ │ [ 실패한 작업 다시 시도 (secondary)] │ │ ← error일 때만
 │ │          ↕ spacing.md 16             │ │
 │ │ 상태 문구 (role=status)              │ │
@@ -61,11 +61,11 @@ Toast의 `action`을 진입점으로 쓰면 토스트는 진입점만, 세션은
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Web 문서 스크롤 > `Container`. Native `ScrollView` > `Container` | 이 구성을 감싸는 제품 화면. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
+| 바깥 틀 | Web 문서 스크롤 > `Container size="reading"`. Native `ScrollView` > `Container size="reading"` | 이 구성을 감싸는 제품 화면. 넓은 화면에서도 버튼이 읽기 폭을 넘지 않는다. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다 | 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래는 `contentContainerStyle` `paddingVertical: spacing.lg` 20 |
 | 제목(선택) | `Heading level="level3"` | Stack 맨 위 | 아래 `spacing.md` 16 |
 | 대상 표시 | `Text` | 행동 위, 스크롤 | 아래 `spacing.md` 16 |
-| 행동 | `Button` 보관/실행 취소(primary) | 대상 아래, 스크롤 | `medium` 44(`control.buttonHeight`). Stack 기본 `align="stretch"`로 꽉 찬 폭 |
-| 재시도 | `Button tone="secondary"` | 행동 아래, error일 때만 | `medium` 44, `spacing.md` 16. 라벨은 무엇을 다시 하는지 적는다(스토리 "실패한 작업 다시 시도") |
+| 행동 | `Button` 보관/실행 취소(primary) | 대상 아래, 스크롤 | `medium` 44(`control.buttonHeight`). 재시도와 함께 `Stack gap="xs"` 행동 묶음에 둔다. Stack 기본 `align="stretch"`로 꽉 찬 폭 |
+| 재시도 | `Button tone="secondary"` | 행동 아래, error일 때만 | `medium` 44, 행동과 `spacing.xs` 8(`actionGroupRecipe`). 라벨은 무엇을 다시 하는지 적는다(스토리 "실패한 작업 다시 시도") |
 | 상태 | `Text` | 맨 아래 | `spacing.md` 16 |
 | 토스트(선택) | `Toast` `action` | 화면 단위 오버레이 | action 높이 `control.minTouchTarget` 44 |
 
@@ -124,13 +124,15 @@ function ArchiveItem({ id, name, api }: { id: string; name: string; api: Archive
   };
   const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
   return (
-    <Container gutter={gutter}>
+    <Container size="reading" gutter={gutter}>
       <Stack gap="md">
         <Text as="p">{state.value ? t("archive.inArchive", { name }) : t("archive.inList", { name })}</Text>
-        <Button loading={state.status === "pending"} onClick={toggle}>
-          {state.value ? t("archive.undo") : t("archive.action")}
-        </Button>
-        {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("archive.retry")}</Button>}
+        <Stack gap="xs">
+          <Button loading={state.status === "pending"} onClick={toggle}>
+            {state.value ? t("archive.undo") : t("archive.action")}
+          </Button>
+          {state.status === "error" && <Button tone="secondary" onClick={() => void session.retry()}>{t("archive.retry")}</Button>}
+        </Stack>
         <Text as="p" role="status">{t(statusKeyOf(state))}</Text>
       </Stack>
     </Container>
@@ -165,13 +167,15 @@ function ArchiveItem({ id, name, api }: { id: string; name: string; api: Archive
   };
   return (
     <ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
-      <Container gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
+      <Container size="reading" gutter={resolveWindowClass(width) === "compact" ? "compact" : "regular"}>
         <Stack gap="md">
           <Text>{state.value ? t("archive.inArchive", { name }) : t("archive.inList", { name })}</Text>
-          <Button loading={state.status === "pending"} onPress={toggle}>
-            {state.value ? t("archive.undo") : t("archive.action")}
-          </Button>
-          {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("archive.retry")}</Button>}
+          <Stack gap="xs">
+            <Button loading={state.status === "pending"} onPress={toggle}>
+              {state.value ? t("archive.undo") : t("archive.action")}
+            </Button>
+            {state.status === "error" && <Button tone="secondary" onPress={() => void session.retry()}>{t("archive.retry")}</Button>}
+          </Stack>
           <StatusText>{t(statusKeyOf(state))}</StatusText>
         </Stack>
       </Container>

package/docs/usage/compositions/activity-status.md

@@ -163,7 +163,7 @@ function ReviewHeader({ task }: { task: ReviewTask | null }) {
 - `media`는 장식이다. 마스코트에 의미가 있으면 그 뜻을 `title`·`description`에 쓴다.
 - Native effect는 `useToastRegion()`의 안정적인 `publish` 함수에 의존한다. controller 객체 전체를 의존성에 넣으면
   publish로 controller가 갱신될 때마다 effect가 다시 발행하는 반복 렌더가 생긴다(실제 예제 host에서 재현).
-- 결과 보기의 예제 안내는 Web `role="status"`, 공개 `StatusText`로 전달한다.
+- 결과 보기의 예제 안내는 Web·Native 모두 공개 `StatusText`로 전달한다(Web은 비어 있는 동안 레이아웃에서 빠져 간격을 만들지 않는다).
   Web은 패널이 실제 소유하던 초점 요소가 닫힘으로 제거됐을 때만 칩으로 돌아가고, 완료 칩 자체에 초점이 있을 때 자동 숨김이 일어나면 작업 시작 버튼으로 옮긴다.
   Enter로 결과를 선택해 초점 요소가 제거되면 복구하지만, 포인터 클릭이 버튼에 초점을 두지 않은 경우에는 새 초점을 강제하지 않는다.
   사용자가 외부 컨트롤로 이동하거나 명시적으로 해제한 초점은 유지한다. body 자체를 패널 초점 소유의 근거로 삼지 않는다. 이는 예제의 결과 안내이며 실제 결과 화면 이동은 제품 소유다.

package/docs/usage/compositions/adaptive-content.md

@@ -32,7 +32,8 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Stack | 화면의 본문 흐름 | gap md=16px, 전체 폭 |
+| 바깥 틀 | Stack. Web은 제품 화면의 `Container size="reading"` 안 | 화면의 본문 흐름 | gap md=16px, 폭은 Container를 따른다(Web 최대 `layout.readingMaxWidth` 720) |
+| 패널 제목 | `Heading level="level5"` | 패널 Surface 맨 위 | `title` 글자 크기·semibold |
 | 내용 | 해당 공개 API | 입력과 행동 사이 | 자체 recipe 크기, 줄바꿈 허용 |
 | 행동 | Button/기존 컨트롤 | 관련 항목 바로 뒤 | inline일 때 wrap, md=16px |