@hjmds/design-contracts 1.26.1 → 1.27.0

package/docs/usage/compositions/environment-matrix.md

@@ -27,7 +27,7 @@
 | `getShowcaseEnvironmentInput` | 프리셋을 Provider 입력(`theme`·`direction`·`textScale`·`reducedMotion`)으로 변환 | [DesignSystemProvider](../components/design-system-provider.md) |
 | `HjmProvider`(Web)·`HjmNativeProvider`(Native) | 제품에서 환경 축을 실제로 바꾸는 곳 | [DesignSystemProvider](../components/design-system-provider.md) |
 
-모두 `@hjmds/design-contracts/showcase`에서 import한다. 스토리의 `hjm-page`·`hjm-showcase-grid`·`hjm-showcase-card` 클래스는 showcase 전용 스타일이다.
+모두 `@hjmds/design-contracts/showcase`에서 import한다. 스토리 페이지는 `Container size="content"` > Heading·Text > `Grid`(1·2·3열) > `Card`·`Badge`로 조립한다. 프리셋 이름 Badge는 같은 id의 `showcaseScenarios` 이름을 쓴다.
 
 ## 배치
 
@@ -39,16 +39,16 @@
 │ └───────────────────────────────────────────────────────┘ │
 └───────────────────────────────────────────────────────────┘
 
-스토리 페이지(참고, showcase 전용 스타일)
+스토리 페이지(참고)
 ┌──────────────────────────────────────────────────────────┐
-│ Patterns / Evidence matrix / 안내                        │
-│ ┌ Environment presets (카드 격자) ─────────────────────┐ │
-│ │ [default] [dark] [large-text] [rtl] [reduced-motion] │ │
+│ 환경 조합 검증 / 안내                                     │
+│ ┌ 환경 조합 (Card 격자) ───────────────────────────────┐ │
+│ │ [기본] [어두운 테마] [200% 글자] [오른쪽→왼쪽] [동작 줄이기] │ │
 │ └──────────────────────────────────────────────────────┘ │
-│ ┌ Story requirements (카드 격자) ──────────────────────┐ │
-│ │ [Contract] [Default] [Dark] [Long copy] [200% text]  │ │
-│ │ [RTL] [Reduced motion] [Accessibility] [Keyboard]    │ │
-│ │ [Native actions] [Web / Native parity]               │ │
+│ ┌ 스토리 확인 항목 (Card 격자) ────────────────────────┐ │
+│ │ [계약] [기본] [어두운 테마] [긴 문구] [200% 글자]    │ │
+│ │ [오른쪽→왼쪽] [동작 줄이기] [접근성] [키보드]        │ │
+│ │ [앱 동작] [웹·앱 동등성]                             │ │
 │ └──────────────────────────────────────────────────────┘ │
 └──────────────────────────────────────────────────────────┘
   상단 Storybook toolbar: light/dark · LTR/RTL · 100/150/200% · full/reduced
@@ -57,8 +57,8 @@
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
 | 바깥 틀 | `HjmProvider`(Web)·`HjmNativeProvider`(Native) | 검증할 제품 화면의 맨 바깥. 화면의 스크롤·`Container`·안전 영역은 바꾸지 않는다 | 환경 입력만 바꾼다. 여백·크기는 제품 화면 값 그대로. Native는 `safeAreaInsets`도 실제 기기 값으로 넘긴다 |
-| 환경 프리셋 | `showcaseEnvironmentMatrix` 카드 5개 | 스토리 첫 섹션 | showcase 전용 격자(제품 기준 아님) |
-| 검증 항목 | `showcaseScenarios` 카드 11개 | 스토리 둘째 섹션 | showcase 전용 격자 |
+| 환경 프리셋 | `showcaseEnvironmentMatrix` Card 5개(Badge 이름·조합·동작) | 스토리 첫 섹션 | Grid compact 1·medium 2·expanded 3열, gap `spacing.md` 16 |
+| 검증 항목 | `showcaseScenarios` Card 11개 | 스토리 둘째 섹션 | 같은 Grid |
 | 환경 전환 | Storybook toolbar | 페이지 밖 상단 | — |
 
 ### 비교하는 다섯 환경
@@ -135,7 +135,11 @@ const preset = showcaseEnvironmentMatrix.find((env) => env.id === "rtl")!;
 
 ## 함정
 
-- 현재 스토리는 HJM 컴포넌트 대신 `hjm-page`·`hjm-showcase-card` 같은 showcase 전용 클래스의 HTML(`h1`·`article`)과 영어 제목을 쓴다. 제품 검증 화면을 만들 때 이 마크업을 따라 하지 않는다(제목은 [Heading](../components/heading.md), 문구는 i18n 키).
+- 제품 검증 화면의 제목은 [Heading](../components/heading.md), 문구는 i18n 키로 둔다. showcase 계약의 한국어 이름·설명을 제품 문구로 가져오지 않는다.
 - `getShowcaseEnvironmentInput`의 결과는 펼쳐서(`{...input}`) 넘긴다. 필드를 하나씩 꺼내 넘기면 optional 타입 때문에
   `exactOptionalPropertyTypes`에서 TS2375가 난다(Web·Native 같다).
 - 검증용 Provider로 화면을 감쌀 때 바깥 틀(스크롤·Container·안전 영역)을 따로 바꾸면 실제 화면과 다른 것을 검증하게 된다.
+
+## 근거
+
+- 2026-10-17 구성 리뷰: 스토리 문구 대부분이 영어였고 raw HTML과 showcase 전용 클래스로 조립돼 있어 계약 문구를 한국어로 바꾸고 HJM 공개 컴포넌트로 다시 조립했다.

package/docs/usage/compositions/expo-interactions.md

@@ -5,7 +5,7 @@
 - 지원: Native
 - 적용: 1.12.1
 - 검토일: 2026-10-15
-- 근거: `showcase/native/src/ExpoInteractions.stories.tsx`, `src/content-transition.ts`, `src/foundations.ts`(`spacing`, `layout`), `packages/react-native/src/content-transition.tsx`, `packages/react-native/src/internal/recipe-button.tsx`(`selected`)
+- 근거: `showcase/native/src/ExpoInteractions.stories.tsx`, `src/content-transition.ts`, `src/foundations.ts`(`spacing`, `layout`), `packages/react-native/src/content-transition.tsx`, `packages/react-native/src/inputs.tsx`(`Switch`)
 - 스토리북: `배포/구성/피드백과 복구/중단해도 남는 현재 상태`
 
 공통 구조·배치·상태·배지의 소유권은 [화면과 구성 선택](../SELECTION.md#소유권)을 따른다. 앱은 데이터·문구·브랜드·추가 기능을 공개 슬롯과 콜백으로 연결한다. 아래 코드 골격을 앱별 기본 구조 복제의 근거로 사용하지 않는다. 전용 구성 API가 없는 콘텐츠 묶음은 [CompositionLayout](../components/composition-layout.md)의 제목·배지·행동·본문·상태·footer 슬롯을 사용한다.
@@ -22,7 +22,7 @@
 | --- | --- | --- |
 | `ScrollView` · `Container` | 바깥 틀. HJM 화면 골격이 소유한다 | [Container](../components/container.md), [화면 여백](../tokens/layout.md) |
 | `Heading level="level5"`, `Text` | 영역 제목(18)과 설명 | [Heading](../components/heading.md), [Text](../components/text.md) |
-| `Button tone="secondary" selected` | 동작 줄이기 같은 켜고 끄는 설정(토글 버튼) | [Button](../components/button.md) |
+| `Switch presentation="row"` | 동작 줄이기 같은 켜고 끄는 설정 | [Switch](../components/switch.md) |
 | `Button` `primary`·`secondary`·`ghost` | 다음 상태 · 처음으로 · 내용 닫기/열기 | [Button](../components/button.md) |
 | `Stack` | 영역 세로 쌓기 `gap="md"`, 행동 묶음 `gap="sm"` | [Stack](../components/stack.md) |
 | `ContentTransition` | `stateKey`가 바뀔 때 새 내용을 `preset="rise"`로 들인다 | [ContentTransition](../components/content-transition.md) |
@@ -37,7 +37,7 @@
 │ ┌ Stack gap="md" 16 ─────────────────────────────┐ │
 │ │ 제목 (Heading level5)                          │ │
 │ │ 설명 (Text)                                    │ │
-│ │ [ 동작 줄이기 ]  ← secondary + selected 토글    │ │
+│ │ 동작 줄이기                    [  ○] ← Switch row│ │
 │ │ ┌ 행동 묶음 Stack gap="sm" 12 ───────────────┐ │ │
 │ │ │ [ 다음 상태 ]   primary   ← 주 행동이 맨 위 │ │ │
 │ │ │ [ 처음으로 ]    secondary ← 보조 행동       │ │ │
@@ -54,13 +54,13 @@
 | --- | --- | --- | --- |
 | 바깥 틀 | `ScrollView` > `Container size="reading"` | 화면 전체, 스크롤. 상단 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md))가 맡는다. 입력이 없어 키보드 처리는 없다 | 위아래 `contentContainerStyle` `paddingVertical: spacing.lg` 20. 좌우 `Container gutter`: 폭 600 미만 `compact` 16, 이상 `regular` 20([화면 여백](../tokens/layout.md)) |
 | 머리 | `Heading` + `Text` | Stack 맨 위 | 사이 `spacing.md` 16 |
-| 설정 토글 | `Button tone="secondary" selected` | 머리 아래 | 높이 `medium` 44(`control.buttonHeight`). Stack 기본 `align="stretch"`로 꽉 찬 폭 |
+| 설정 토글 | `Switch presentation="row"` | 머리 아래 | 꽉 찬 폭 행, track `medium` 52×32. 큰 글자에서는 track이 라벨 아래로 내려간다 |
 | 행동 묶음 | `Stack gap="sm"` + Button ×3 세로 | 토글 아래, 주 행동이 위 | 버튼 사이 `spacing.sm` 12, 각 높이 44 |
 | 바뀌는 내용 | `ContentTransition` | 행동 묶음 아래, 함께 스크롤 | `rise` 세로 12 이동, 시간 `motion.normal`, 곡선 `easing.enter`. 래퍼 자체 크기·여백 없음 |
 
 - 한 영역(구획 하나) 안이므로 요소 사이는 `layout.contentGap`(`Stack gap="md"` 16)이다([화면 여백](../tokens/layout.md)).
-- 한 화면의 primary는 "다음 상태" 하나다. 토글은 `tone="secondary"`로 두고 켜졌을 때만 `selected` 표시(배경 `bg`, 글자·테두리 `contentBrand`)가 된다.
-  `selected={false}`인 버튼은 tone 색으로 칠해지므로 tone을 비우면 꺼진 토글이 primary 채움이 된다([Button](../components/button.md) 꼭 지킬 것의 예외 규칙).
+- 한 화면의 primary는 "다음 상태" 하나다. 켜고 끄는 설정은 [선택 조립 규칙](../SELECTION.md#조립-규칙필수)대로 `Switch`로 두고 `selected` Button으로 흉내 내지 않는다.
+  2026-10-16 사용자 지적으로 글자 버튼 토글은 켜짐/꺼짐이 테두리 없는 글자로만 구분돼 설정으로 읽히지 않았다.
 
 ## 흐름과 상태
 
@@ -98,6 +98,7 @@ import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
 import { Button } from "@hjmds/react-native/actions";
 import { ContentTransition } from "@hjmds/react-native/content-transition";
 import { Heading } from "@hjmds/react-native/heading";
+import { Switch } from "@hjmds/react-native/inputs";
 import { Container, Stack, Text } from "@hjmds/react-native/primitives";
 
 const flowStateKey = ["flow.state.ready", "flow.state.review", "flow.state.done"] as const;
@@ -113,7 +114,7 @@ function FlowStatus() {
         <Stack gap="md">
           <Heading level="level5" semanticLevel={2}>{t("flow.title")}</Heading>
           <Text>{t("flow.description")}</Text>
-          <Button tone="secondary" selected={reduced} onPress={() => setReduced((value) => !value)}>{t("flow.reduceMotion")}</Button>
+          <Switch presentation="row" label={t("flow.reduceMotion")} checked={reduced} onCheckedChange={setReduced} />
           <Stack gap="sm">
             <Button onPress={() => setIndex((value) => (value + 1) % flowStateKey.length)}>{t("flow.next")}</Button>
             <Button tone="secondary" onPress={() => setIndex(0)}>{t("flow.reset")}</Button>
@@ -149,4 +150,4 @@ function FlowStatus() {
 - 다음 상태 계산을 전환 완료 콜백에 묶으면 빠른 연속 누름과 중간 닫기에서 상태가 어긋난다.
 - ContentTransition은 움직이는 동안 래퍼 밖으로 세로 12만큼 밀려 나온다. 바로 아래 요소와 붙이지 않는다.
 - 예제는 `Container gutter="compact"`와 `Stack gap="md"`로 바깥 틀을 공유하고 행동 묶음은 `Stack gap="sm"`으로 둔다. Native 위아래 여백은 `spacing.md` 16이다.
-- 제목은 Heading, 동작 줄이기 토글은 secondary, 작업 결과는 iOS 알림도 처리하는 예제 helper를 쓴다. 제품은 같은 계약을 자체 상태 알림에 연결한다.
+- 제목은 Heading, 동작 줄이기는 Switch, 작업 결과는 iOS 알림도 처리하는 예제 helper를 쓴다. 제품은 같은 계약을 자체 상태 알림에 연결한다.

package/docs/usage/compositions/family-drawer.md

@@ -20,7 +20,7 @@
 | 컴포넌트 | 역할 | 지침 |
 | --- | --- | --- |
 | `Container` · `ScrollView` | 시작 화면의 바깥 틀. HJM 화면 골격이 소유한다 | [Container](../components/container.md), [화면 여백](../tokens/layout.md) |
-| `Heading level="level2"`, `Text` | 시작 화면의 제목·설명 | [Heading](../components/heading.md), [Text](../components/text.md) |
+| `Heading level="level3"`, `Text` | 시작 화면의 제목·설명. 화면 제목은 semibold `level3`이며 bold 표시 역할 `level1`·`level2`는 쓰지 않는다 | [Heading](../components/heading.md), [Text](../components/text.md) |
 | `Button` primary | 시트를 여는 트리거(시작 화면의 주 행동) | [Button](../components/button.md) |
 | `Sheet` | 하단 시트. 제목·닫기·`footer`, 안전 영역·스크롤·`busy` | [Sheet](../components/sheet.md) |
 | `Steps` | 현재 단계와 전체 단계 수, 실패하면 현재 단계 `error` | [Steps](../components/steps.md) |
@@ -37,7 +37,7 @@
 ┌ Web 문서 스크롤 · Native ScrollView ┐    ┌──────────── backdrop ─────────────┐
 │ ←gutter 16|20→ Container            │    │╭──────────────────────────────────╮│
 │ ┌ Stack gap="xl" 24 ──────────────┐ │    ││ 함께하는 공간              [닫기] ││ ← 머리 고정, 최소 44
-│ │ 공간 제목 (Heading level2)      │ │    ││──────────────────────────────────││
+│ │ 공간 제목 (Heading level3)      │ │    ││──────────────────────────────────││
 │ │ 설명 (Text)                     │ │    ││ ① 초대 ─ ② 설정 ─ ③ 확인         ││ ← Steps
 │ │ [ 공간 설정하기 ] primary       │ │    ││          ↕ spacing.xl 24         ││   본문(스크롤)
 │ │ 설정을 마쳤어요. (상태 문구)    │ │    ││ (실패 시 Notice danger)          ││
@@ -111,7 +111,7 @@ const isLast = step === stepIds.length - 1;
 
 <Container size="reading" gutter={gutter}>
   <Stack gap="xl">
-    <Heading level="level2">{t("space.title")}</Heading>
+    <Heading level="level3">{t("space.title")}</Heading>
     <Text as="p">{t("space.description")}</Text>
     <Button onClick={openSetup}>{t("space.setup.open")}</Button>
     {saved ? <Text as="p" role="status">{t("space.setup.saved")}</Text> : null}
@@ -155,7 +155,7 @@ import { Steps } from "@hjmds/react-native/steps";
 <ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
   <Container size="reading" gutter={gutter}>
     <Stack gap="xl">
-      <Heading level="level2">{t("space.title")}</Heading>
+      <Heading level="level3">{t("space.title")}</Heading>
       <Text>{t("space.description")}</Text>
       <Button onPress={openSetup}>{t("space.setup.open")}</Button>
       {saved ? <StatusText announceOnMount>{t("space.setup.saved")}</StatusText> : null}
@@ -200,9 +200,13 @@ import { Steps } from "@hjmds/react-native/steps";
 - 저장을 시트 닫힘 사유와 묶지 않는다. 닫기·바깥·back 닫힘은 취소다.
 - 중단 후 다시 열면 진행 중이던 단계로 이어간다. 성공 뒤 새 작업을 시작할 때만 0으로 되돌린다. 영속 초안이 필요한 제품은 별도 저장소 정책을 연결한다.
 - 저장 중 `busy`를 빼면 사용자가 시트를 닫아 저장 결과를 볼 곳이 사라진다.
-- 현재 스토리는 시작 화면에 바깥 틀(Container·ScrollView)이 없고 Storybook 프레임이 감싼다. 제품은 위 바깥 틀 행을 따른다.
+- 스토리는 시작 화면을 `Container size="reading"`으로 감싼다. Native 제품은 그 바깥에 위 바깥 틀 행의 `ScrollView`를 둔다.
 - 스토리는 데모 비동기 저장의 진행 중·실패·재시도를 포함한다. 실제 서버 저장은 제품이 연결한다.
 
 ## 실행 예제의 복구 경계
 
 2026-10-13 Web·Native 스토리는 `createActionSession` 기반 데모 저장을 연결한다. 마지막 단계 저장 중에는 이동·닫기를 잠그고, 실패하면 `Steps.currentStepStatus="error"`와 Notice를 표시한 채 현재 단계를 유지한다. 같은 주 버튼이 다시 저장을 수행한다. 중간에 닫았다 열면 현재 단계로 이어지고, 성공 뒤 다시 시작할 때만 첫 단계로 초기화한다. footer는 기본 Sheet 배치를 따르는 직접 자식이다. Web은 이전 → 주 행동, Native는 주 행동 → 이전이며 Native에서 가로 Stack으로 재정의하지 않는다. 실제 서버 저장·영속 초안·제품별 단계 입력은 포함하지 않는다.
+
+## 근거
+
+- 2026-10-17 구성 리뷰: 시작 화면 제목이 heavy 800 `level2`로 화면 제목 규칙(semibold)보다 무거웠고, 데스크톱에서 버튼과 문구가 1280 폭 전체로 늘어났다. 그래서 제목을 `level3`으로 낮추고 스토리에 읽기 폭 Container를 적용했다.

package/docs/usage/compositions/field-group.md

@@ -41,13 +41,13 @@ CheckboxGroup/RadioGroup, 날짜 조각이면 DateEntry를 먼저 사용한다.
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
 | 바깥 틀 | Web fieldset / Native View | 기존 폼 안 | 테두리 없음, Web 최소 폭 0 |
-| 그룹 이름 | Web legend / Native Text label | 맨 위 | Web 아래 spacing.sm 12, Native 그룹 간격 spacing.sm 12 |
-| 입력 묶음 | renderField | descriptor.fields 순서 | `layout="stack"`은 세로, `layout="inline"`은 줄바꿈 가능한 행. 간격 spacing.md 16 |
+| 그룹 이름 | Web legend / Native Text, `fieldGroupRecipe.heading`(bodyLarge·semibold, 각 칸 label보다 크게) | 맨 위 | Web 아래 spacing.sm 12, Native 그룹 간격 spacing.sm 12 |
+| 입력 묶음 | renderField | descriptor.fields 순서 | `layout="stack"`은 세로, `layout="inline"`은 모든 칸이 한 줄에 들어갈 때만 한 행, 아니면 모두 세로. 간격 spacing.md 16 |
 | 개별 도움말 | FieldGroup | 해당 입력 바로 아래 | Native 간격 spacing.xs 8, 글자 크기는 Text 기본 |
 
 ### 배치 축
 
-`layout`은 `stack`(기본) 또는 `inline`이다. `inline`은 날짜·소요 시간처럼 짧은 값들이 하나의 질문을 이루는 입력에 쓴다. Web은 최소 10ch의 자동 줄바꿈 grid, Native는 공통 recipe의 최소 너비를 가진 wrapping row다. 좁은 영역에서는 순서를 유지하며 다음 줄로 이동한다. `layoutStyle`은 바깥 배치만, Web `className`은 그룹 host에 적용된다.
+`layout`은 `stack`(기본) 또는 `inline`이다. `inline`은 날짜·소요 시간처럼 짧은 값들이 하나의 질문을 이루는 입력에 쓴다. 두 renderer 모두 `fieldGroupRecipe.inline`의 `minWidth`(글자 배율 비례)로 모든 칸이 들어가는지 보고, 들어가면 한 행에 칸마다 최대 `maxWidth`까지, 아니면 모든 칸을 세로로 쌓는다(`wrap: "all-or-none"`). 2+1처럼 일부만 줄바꿈하지 않는다. `layoutStyle`은 바깥 배치만, Web `className`은 그룹 host에 적용된다.
 
 2026-10-13 DateEntry와 DurationField가 같은 그룹 제목·입력 행을 직접 만들고 있어 `fieldGroupRecipe`를 `@hjmds/design-contracts/field-group`에 모았다. 두 컴포넌트는 FieldGroup의 descriptor·renderField·guardChange를 재사용한다. 날짜 파싱과 시간 단위 변환은 각각의 기존 계약에 남는다.
 
@@ -110,3 +110,7 @@ controlProps는 TextField에 바로 연결되는 형태이며 Checkbox/Select
 
 - 실제 스크린리더·Native 기기·제품 팔레트 검증은 아직 남았다. 자동 검사 통과를 승격 근거로 단독 사용하지 않는다.
 - 국가·주소·연락처의 필드 순서와 autocomplete는 제품별로 정한다. 예제의 한국 주소 순서를 공통 규칙으로 복사하지 않는다.
+
+## 근거
+
+- 2026-10-17 구성 리뷰: DurationField 칸이 데스크톱에서 약 400px로 늘어나 짧은 값이 넓은 칸 가운데 떠 있었고, 402pt에서는 시·분 / 초로 끊겼다. 그룹 이름은 regular라 굵은 칸 이름보다 약했다. 그래서 칸 최대 폭, 전부-또는-세로 줄바꿈, 그룹 제목 typography를 recipe에 두었다.

package/docs/usage/compositions/interaction-adapters.md

@@ -27,7 +27,7 @@ Web·Native stable, Native `screen-transition`은 experimental이다. 각 어댑
 | `CarouselMotion` | 카드 넘기기. 이전/다음 버튼, 반복·자동 재생 없음 | [Carousel](../components/carousel.md) |
 | `Celebration` | 제품이 확인한 성공 뒤 입자 효과(장식) | [Celebration](../components/celebration.md) |
 | `createHjmTransitionStack`·`SharedTransitionElement`·`SharedTransitionScreen`·`useSharedTransitionOptions` | Native 전용: 목록 카드 → 상세 화면 확대 전환 | [SharedTransitionScreen](../components/shared-transition-screen.md), [SharedTransitionElement](../components/shared-transition-element.md) |
-| `Button`·`Text` | 상태 변경 트리거, 결과 문구 | [Button](../components/button.md), [Text](../components/text.md) |
+| `Button`·`StatusText`·`Section`·`Surface` | 상태 변경 트리거, 결과 문구, 구획 제목, 카드 틀 | [Button](../components/button.md), [StatusText](../components/text.md), [Section](../components/section.md), [Surface](../components/surface.md) |
 
 ## 배치
 
@@ -59,14 +59,14 @@ Native(전체 화면 host)                    Web(문서 흐름)
 | 구획 제목 | [Section](../components/section.md) `title` | 각 어댑터 묶음 위 | 제목과 본문 사이 `spacing.xs` 8(`sectionRecipe`) |
 | 순서 목록 | `SortableCollection` | 본문, 스크롤 | Native 행 padding·간격 `spacing.xs` 8, 손잡이 줄 최소 높이 44. Web 손잡이 44×44, 행 위아래 `spacing.xs` 8 |
 | 행 작업 | `SwipeActions` + [ListRow](../components/list-row.md) | 목록 행 | 행 높이·여백은 `ListRow`(한 줄 56), 작업 버튼 높이 44·간격 `spacing.xs` 8 |
-| 결과 문구 | `Text`(Web `role="status"`, Native `accessibilityLiveRegion`) | 작업·축하 바로 아래 | 구획 안 간격은 Section이 정한다 |
+| 결과 문구 | `StatusText`(Web `role="status"`, Native live region + iOS 알림) | 작업·축하 바로 아래 | 구획 안 간격은 Section이 정한다 |
 | 내용 전환 | `ContentTransition`·`TextTransition` | 바뀌는 내용 자리 | 크기 변화 없음(전환은 투명도·짧은 이동만) |
-| 카드 | `CarouselMotion` | 본문 | Native는 `onLayout`으로 잰 폭 × 제품이 정한 높이, Web은 부모 폭 |
+| 카드 | `CarouselMotion` | 본문 | Native는 `onLayout`으로 잰 폭 × 제품이 정한 높이, Web은 부모 폭. 이전·다음은 슬라이드 아래 끝 정렬 아이콘 버튼(`spacing.sm` 간격) |
 | 축하 | `Celebration` | Native: 스크롤 **밖** 화면 오버레이(host의 형제), Web: 자체 canvas | 입자 32/64개, 1.6/2.4초(`celebrationRecipe`) |
 
 - Native `Celebration`을 스크롤 내용 안에 두면 화면 밖에서 시작해 보이지 않는다(기기 QA 확인). 항상 화면 host의 형제로 둔다.
 - `SwipeActions`는 Web에서 버튼을 바로 보이고, Native에서 스와이프·상시 "작업 보기" 버튼·동작 줄이기 모두 같은 버튼을 드러낸다. 목록 전체가 `openRowId` 하나를 공유한다.
-- 카드 높이·색·이미지는 제품 소유다. 카드 안 제목은 [Heading](../components/heading.md)으로 둔다.
+- 카드 높이·색·이미지는 제품 소유다. 예제 카드는 `Surface padding="lg"` 안 가운데 정렬 `Stack`의 [Heading](../components/heading.md) `level4`이고, Native 높이는 첫 카드의 실제 높이를 잰 값이다.
 
 근거: `packages/react-native/src/sortable.tsx`, `packages/react/src/sortable.tsx`, `packages/react-native/src/swipe-actions.tsx`, `src/interaction-adapters.ts`(`celebrationRecipe`), `src/foundations.ts`(`layout`)
 
@@ -94,6 +94,7 @@ Native(전체 화면 host)                    Web(문서 흐름)
 ```tsx
 // Web
 import { Container, Section, Stack, Text } from "@hjmds/react/layout";
+import { StatusText } from "@hjmds/react/status-text";
 import { ListRow } from "@hjmds/react/display";
 import { Heading } from "@hjmds/react/heading";
 import { SortableCollection } from "@hjmds/react/sortable";
@@ -108,14 +109,14 @@ const recordKey = { start: "record.start", ready: "record.ready" } as const;
   <Stack gap="xl">
     <Section title={t("fav.title")}>
       <SortableCollection items={items} label={t("fav.label")} labels={sortLabels} disabled={savingOrder}
-        renderItem={(item) => <strong>{item.label}</strong>} onCommit={(intent) => void commitOrder(intent.orderedIds)} />
+        renderItem={(item) => <Text emphasis="medium">{item.label}</Text>} onCommit={(intent) => void commitOrder(intent.orderedIds)} />
     </Section>
     <Section title={t("note.title")}>
       <SwipeActions label={t("note.actions")} actions={[{ id: "archive", label: t("note.archive") }]} busy={busy}
         onAction={runAction} onError={() => setNoteStatus("failed")}>
         <ListRow title={note.title} />
       </SwipeActions>
-      <Text as="p" role="status">{t(noteStatusKey[noteStatus])}</Text>
+      <StatusText>{t(noteStatusKey[noteStatus])}</StatusText>
     </Section>
     <ContentTransition stateKey={record}>
       <Heading level="level4" semanticLevel={3}>{t(recordKey[record])}</Heading>
@@ -131,6 +132,7 @@ import { ScrollView, View, useWindowDimensions } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { Container, Section, Stack, Text } from "@hjmds/react-native/primitives";
+import { StatusText } from "@hjmds/react-native/status-text";
 import { ListRow } from "@hjmds/react-native/data-display";
 import { useHjmNativeTheme } from "@hjmds/react-native/provider";
 import { SortableCollection } from "@hjmds/react-native/sortable";
@@ -149,7 +151,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
       <Stack gap="xl">
         <Section title={t("fav.title")}>
           <SortableCollection items={items} label={t("fav.label")} labels={sortLabels} disabled={savingOrder}
-            renderItem={() => null} onCommit={(intent) => void commitOrder(intent.orderedIds)} />
+            renderItem={(item) => <Text emphasis="medium">{item.label}</Text>} onCommit={(intent) => void commitOrder(intent.orderedIds)} />
         </Section>
         <Section title={t("note.title")}>
           <SwipeActions rowId={note.id} label={note.title} actionsLabel={t("note.showActions")}
@@ -157,7 +159,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
             actions={[{ id: "archive", label: t("note.archive") }]} onAction={runAction} onError={() => setNoteStatus("failed")}>
             <ListRow title={note.title} />
           </SwipeActions>
-          <Text accessibilityLiveRegion="polite">{t(noteStatusKey[noteStatus])}</Text>
+          <StatusText>{t(noteStatusKey[noteStatus])}</StatusText>
         </Section>
         <View onLayout={(e) => setCardWidth(e.nativeEvent.layout.width)}>
           <CarouselMotion width={cardWidth} height={cardHeight} slides={slides} currentKey={slideKey} onCurrentKeyChange={setSlideKey}
@@ -185,7 +187,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 
 ## 함정
 
-- Native `SortableCollection`은 손잡이 줄에 `item.label`을 이미 그린다. `renderItem`은 `() => null`로 두거나 보조 정보만 그린다.
+- `SortableCollection` 손잡이는 항목 이름을 보조 기술에만 알린다. 보이는 이름은 두 플랫폼 모두 `renderItem`이 그린다.
 - Native 화면 전환은 현재 포트폴리오 Expo 앱(expo-router, React Navigation 미사용)에서 바로 쓸 수 없다. exports patch를 제품 패키지 관리자에 등록해야 한다.
 - 어댑터 peer 없이 subpath를 import하면 자동 대체 없이 기기 Metro 번들이 실패한다.
 - 예제는 Heading·Container·Stack·ListRow를 사용한다. 플랫폼별 드래그/스와이프 host는 유지하고 동일한 배치 역할을 재사용한다.

package/docs/usage/compositions/interaction-flow-apply.md

@@ -29,7 +29,7 @@
 | `Text` 상태 | 현재 적용된 값 `t("display.current", { value })` | [Text](../components/text.md) |
 | `Button` 트리거 | 시트를 연다. 열 때 임시 선택을 적용 값으로 초기화. 화면의 primary 하나 | [Button](../components/button.md) |
 | `Sheet` | 선택 영역. `title`·`closeLabel` 필수, `returnFocusRef`로 트리거에 포커스 복귀 | [Sheet](../components/sheet.md) |
-| `Button selected`(secondary) × N | 선택지. 임시 선택(draft)만 바꾼다 | [Button](../components/button.md) |
+| `RadioGroup` | 선택지. 임시 선택(draft)만 바꾼다 | [RadioGroup](../components/radio-group.md) |
 | `Button` 적용 / `Button` 취소(secondary) | 시트 `footer`. 적용만 확정 값을 바꾼다 | [Button](../components/button.md) |
 
 ## 배치
@@ -47,9 +47,9 @@
 ┌ Sheet ───────────────────────────────┐
 │ 표시 방식 선택                   [×] │ ← header 고정, 닫기 = 취소와 같음
 ├──────────────────────────────────────┤
-│ [ 간결하게   ✓ ]  (selected)         │ ↑ body 스크롤
-│ [ 자세하게     ]                     │ │ 선택지 간격 spacing.md 16
-│ [ 크게 보기    ]                     │ │
+│ (●) 간결하게                         │ ↑ body 스크롤
+│ ( ) 자세하게                         │ │ RadioGroup card, 행 56
+│ ( ) 크게 보기                        │ │
 │ 안내: 적용해야 바뀐다                │ ↓
 ├──────────────────────────────────────┤
 │ Web:    [선택 취소] [선택 적용]       │ ← footer 고정, 오른쪽 정렬, gap 12
@@ -65,21 +65,21 @@
 | 현재 값 | `Text` | 제목 아래, 트리거 위 | `spacing.md` 16 |
 | 트리거 | `Button`(primary) | 현재 값 아래 | `medium` 44(`control.buttonHeight`) |
 | 시트 머리 | `Sheet` header | 시트 위 고정 | Native 최소 높이 `control.minTouchTarget` 44, 제목–닫기 `spacing.sm` 12; Web 여백 `spacing.lg` 20, 제목–닫기 `spacing.md` 16 |
-| 선택지 | `Button selected` × N | 시트 body, 스크롤 | 높이 44, 간격 `spacing.md` 16. 본문 안 선택지 묶음은 `Stack gap="md"`로 명시한다. 설치한 버전의 Sheet body gap과 중첩 여부를 확인하며 checkout 상태를 npm 게시 증거로 삼지 않는다 |
+| 선택지 | `RadioGroup`(`presentation="card"`, `accessibilityLabel` = 시트 제목) | 시트 body, 스크롤 | 행 최소 높이 56(`layout.rowHeight.singleLine`), 항목 사이 `spacing.xs` 8(`selectionGroupRecipe`). 안내 문구와는 `Stack gap="md"` 16. 설치한 버전의 Sheet body gap과 중첩 여부를 확인하며 checkout 상태를 npm 게시 증거로 삼지 않는다 |
 | 행동 | `Button` 적용·취소 | 시트 footer, 스크롤 밖 고정 | 간격 `spacing.sm` 12(`sheetRecipe.footer.gap`), Native 위 여백 `spacing.sm` 12 |
 | 시트 틀 | `Sheet` | 하단, 모달 | Web 최대 폭 640(`sheetRecipe.web.maxWidth`)·최대 높이 90%, Native 가로 여백 `spacing.lg` 20·최대 높이 90%(`maxHeightRatio` 0.9), 하단 안전 영역 추가 |
 
 - footer 순서는 [Sheet](../components/sheet.md) 배치 규칙을 따른다. Web footer는 오른쪽 정렬 가로 줄 **[취소][적용]**(보조 → 주 행동), Native footer는 세로 열이라
   **적용(primary) 먼저, 취소(secondary) 아래**다. 두 renderer의 footer가 이미 `gap` 12를 주므로 버튼을 `Stack`으로 다시 감싸지 않는다.
-- primary 개수: 화면에서는 트리거 하나, 시트 안에서는 적용 하나를 센다. 선택지는 `selected`를 준 secondary라 세지 않는다([Button](../components/button.md) 꼭 지킬 것).
-- 선택지가 단일 선택이면 Button 묶음 대신 [RadioGroup](../components/radio-group.md)도 쓸 수 있다. 의미(임시 선택 → 적용)는 같다.
+- primary 개수: 화면에서는 트리거 하나, 시트 안에서는 적용 하나를 센다. 선택지는 RadioGroup이라 버튼으로 세지 않는다.
+- 선택지를 `selected` Button 나열로 만들지 않는다. 2026-10-16 사용자 지적으로 선택 버튼 줄이 테두리 없는 글자처럼 보였다. 하나 고르기는 [선택 조립 규칙](../SELECTION.md#조립-규칙필수)대로 RadioGroup(선택지가 짧은 2~4개면 SegmentedControl)을 쓴다. 의미(임시 선택 → 적용)는 같다.
 
 근거: `src/component-recipes.ts`(`sheetRecipe`), `packages/react/src/styles.css`(`.hjm-sheet__footer`, `.hjm-sheet__body`), `packages/react-native/src/overlays.tsx`(Sheet footer `View`), `src/foundations.ts`(`layout`, `heading`)
 
 ## 흐름과 상태
 
 1. 트리거를 누르면 임시 선택을 현재 적용 값으로 초기화하고 시트를 연다.
-2. 선택지를 누르면 임시 선택만 바뀐다(`selected` 표시). 화면 본문의 현재 값은 그대로다.
+2. 선택지를 누르면 임시 선택만 바뀐다(라디오 선택 표시). 화면 본문의 현재 값은 그대로다.
 3. 적용을 누르면 확정 값을 임시 선택으로 바꾸고 시트를 닫는다.
 4. 취소·닫기(×)·바깥 누름·Escape·Android back은 확정 값을 바꾸지 않고 닫는다.
 5. 닫히면 포커스가 트리거로 돌아온다.
@@ -105,6 +105,7 @@ import { Button } from "@hjmds/react/actions";
 import { Heading } from "@hjmds/react/heading";
 import { Container, Stack, Text } from "@hjmds/react/layout";
 import { Sheet } from "@hjmds/react/overlays";
+import { RadioGroup } from "@hjmds/react/selection";
 
 const displayKey = { compact: "display.compact", detailed: "display.detailed", large: "display.large" } as const;
 type DisplayId = keyof typeof displayKey;
@@ -128,10 +129,10 @@ const trigger = useRef<HTMLButtonElement>(null);
       <Button tone="secondary" onClick={() => setOpen(false)}>{t("display.cancel")}</Button>
       <Button onClick={() => { setApplied(draft); setOpen(false); }}>{t("display.apply")}</Button>
     </>}>
-    <Stack gap="md">{/* 선택지 묶음 내부 간격 */}
-      {options.map((id) => (
-        <Button key={id} tone="secondary" selected={draft === id} onClick={() => setDraft(id)}>{t(displayKey[id])}</Button>
-      ))}
+    <Stack gap="md">
+      <RadioGroup accessibilityLabel={t("display.choose")} presentation="card"
+        items={options.map((id) => ({ value: id, label: t(displayKey[id]) }))}
+        value={draft} onValueChange={(next) => setDraft(next as DisplayId)} />
       <Text>{t("display.applyHint")}</Text>
     </Stack>
   </Sheet>
@@ -145,6 +146,7 @@ import { useRef, useState } from "react";
 import { ScrollView, View, useWindowDimensions } from "react-native";
 import { Button } from "@hjmds/react-native/actions";
 import { Heading } from "@hjmds/react-native/heading";
+import { RadioGroup } from "@hjmds/react-native/inputs";
 import { Sheet } from "@hjmds/react-native/overlays";
 import { Container, Stack } from "@hjmds/react-native/primitives";
 import { useHjmNativeTheme } from "@hjmds/react-native/provider";
@@ -172,9 +174,9 @@ const trigger = useRef<View>(null);
     <Button onPress={() => { setApplied(draft); setOpen(false); }}>{t("display.apply")}</Button>
     <Button tone="secondary" onPress={() => setOpen(false)}>{t("display.cancel")}</Button>
   </>}>
-  {options.map((id) => (
-    <Button key={id} tone="secondary" selected={draft === id} onPress={() => setDraft(id)}>{t(displayKey[id])}</Button>
-  ))}
+  <RadioGroup<DisplayId> accessibilityLabel={t("display.choose")} presentation="card"
+    items={options.map((id) => ({ value: id, label: t(displayKey[id]) }))}
+    value={draft} onValueChange={(next) => next && setDraft(next)} />
 </Sheet>
 ```
 

package/docs/usage/compositions/interaction-flow-search.md

@@ -31,8 +31,8 @@
 | `Button` 검색 / `Button` 다시 검색(secondary) | 검색 실행(primary 하나), 실패했을 때만 보이는 재시도 | [Button](../components/button.md) |
 | `Text` | 진행·결과·실패 문구 | [Text](../components/text.md) |
 
-스토리의 "느린 응답으로 검색"(900ms)·"빠른 응답으로 검색"(150ms) 두 버튼은 역순 응답을 재현하는 데모다. 제품은 검색 버튼 하나(또는 입력 중 검색)로 둔다.
-`다음 검색 실패시키기`는 실패 경로를 여는 데모 도구다. 스토리는 기본·어두운 테마, `검색 중`, `실패와 다시 검색`, 제품 팔레트 두 가지(`보라 테마`, `초록 테마 · 어둡게`)다.
+스토리는 검색 버튼 하나(기본 150ms)를 두고, 역순 응답은 미리보기 도구 `다음 검색 느리게`(900ms)로 재현한다. 제품은 검색 버튼 하나(또는 입력 중 검색)로 둔다.
+`다음 검색 실패시키기`도 실패 경로를 여는 미리보기 도구다. 스토리는 기본·어두운 테마, `검색 중`, `실패와 다시 검색`, 제품 팔레트 두 가지(`보라 테마`, `초록 테마 · 어둡게`)다.
 2026-10-06 같은 SearchField 진행 상태와 팔레트를 보이던 `입력과 작성/검색 입력`을 이 항목으로 합쳤다([옛 링크](../../../../../docs/STORYBOOK_NAVIGATION.md#실험-정리와-합친-항목-2026-10-06)).
 검색 입력 칸·결과 목록이 필요한 화면이면 [SearchField](../components/search-field.md)·[List](../components/list.md)에 같은 세대 규칙을 연결한다.
 
@@ -42,7 +42,7 @@
 ┌ 화면 ────────────────────────────────┐
 │ Native ScrollView 위아래 16          │
 │ (keyboardShouldPersistTaps=handled)  │
-│ └ Container gutter 16/20             │
+│ └ Container reading, gutter 16/20    │
 │   Heading 제목                       │
 │          ↕ spacing.md 16             │
 │   검색어                             │
@@ -57,7 +57,7 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Native: `ScrollView keyboardShouldPersistTaps="handled"` → `Container` → `Stack gap="xl"`. Web: `Container` → `Stack gap="xl"` | 화면 본문. 안전 영역은 화면 셸이 준다. 키보드가 열린 채 검색 버튼을 누를 수 있게 Native 스크롤은 탭을 통과시킨다. 입력이 화면 아래쪽에 있으면 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)를 쓴다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 구획 사이 `layout.sectionGap` 24 |
+| 바깥 틀 | Native: `ScrollView keyboardShouldPersistTaps="handled"` → `Container size="reading"` → `Stack gap="xl"`. Web: `Container size="reading"` → `Stack gap="xl"` | 화면 본문. 안전 영역은 화면 셸이 준다. 키보드가 열린 채 검색 버튼을 누를 수 있게 Native 스크롤은 탭을 통과시킨다. 입력이 화면 아래쪽에 있으면 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)를 쓴다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 구획 사이 `layout.sectionGap` 24 |
 | 제목 | `Heading level="level3"` | 묶음 맨 위 | 24/32(`heading.level3`) |
 | 입력 | `SearchField` | 제목 아래 | 높이 `control.fieldHeight` 44, `layout.contentGap` 16 |
 | 주 행동 | `Button` 검색 | 입력 아래 | `medium` 44(`control.buttonHeight`), `spacing.md` 16 |
@@ -109,7 +109,7 @@ const search = () => {
 const message = state.status === "pending" || state.status === "error" ? t(searchStatusKey[state.status])
   : state.value ? renderResult(state.value) : t(searchStatusKey.idle);
 
-<Container gutter={gutter}>
+<Container size="reading" gutter={gutter}>
   <Stack gap="xl">
     <Stack gap="md">
       <Heading level="level3" semanticLevel={2}>{t("search.title")}</Heading>
@@ -138,7 +138,7 @@ const { spacing } = useHjmNativeTheme().tokens;
 const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
 
 <ScrollView keyboardShouldPersistTaps="handled" contentContainerStyle={{ paddingVertical: spacing.md }}>
-  <Container gutter={gutter}>
+  <Container size="reading" gutter={gutter}>
     <Stack gap="xl">
       <Stack gap="md">
         <Heading level="level3" semanticLevel={2}>{t("search.title")}</Heading>
@@ -162,7 +162,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 | --- | --- | --- |
 | 입력 이벤트 | `onValueChange`(문자열 값). DOM 이벤트가 필요할 때만 `onChange`(둘 다 호출된다) | `onValueChange` |
 | 상태 알림 | `role="status"` | live region(Android) + iOS 알림 호출 |
-| 바깥 틀 | `Container` | `ScrollView`(세로 여백, `keyboardShouldPersistTaps="handled"`) 안 `Container` |
+| 바깥 틀 | `Container size="reading"` | `ScrollView`(세로 여백, `keyboardShouldPersistTaps="handled"`) 안 `Container size="reading"` |
 | 검색 중 표시 | SearchField `loading` | SearchField `busy` + `busyLabel`(필수) |
 
 ## 함정
@@ -174,3 +174,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 - 실패와 결과 없음은 다른 상태다. 실패는 `다시 검색`(`session.retry()`), 결과 없음은 검색어를 바꾸는 경로를 준다.
 
 2026-10-13 실패 예약은 다음 요청이 **시작할 때** 그 요청에 귀속한다. 이미 진행 중인 응답이 이후에 켠 예약을 소비하지 않으며, 오래된 실패도 최신 성공을 덮지 않는다. 재시도는 기존 계약대로 실패한 제출 검색어를 다시 요청하고 작성 중인 검색어는 보존한다. 재시도 버튼이 사라질 때 입력 ref로 초점을 돌린다. unmount에서는 로컬 데모 지연 타이머를 정리하고 분리된 작업을 종료하지만 실제 네트워크 취소를 구현한 것은 아니다.
+
+## 근거
+
+- 2026-10-17 구성 리뷰: 데모 지연 버튼 두 개("느린/빠른 응답으로 검색")가 secondary 제품 행동처럼 보였고 primary 검색이 없었으며, 데스크톱에서 입력과 버튼이 1280 폭 전체로 늘어났다. 그래서 primary 검색 하나와 미리보기 도구 토글로 바꾸고 읽기 폭 Container를 적용했다.

package/docs/usage/compositions/live-list.md

@@ -26,18 +26,20 @@ Magic UI Animated List의 소개 페이지 순차 노출에서 새 항목의 등
 | ContentTransition | 새 항목 등장과 바깥 높이 전환 | [내용 전환](../components/content-transition.md) |
 | TextField | 제품이 항목 id별로 보존하는 메모 | [필드](../components/field.md) |
 | Button · Text | 명시적 데이터 변경과 변경 결과 | [버튼](../components/button.md), [글자](../components/text.md) |
+| EmptyState | 기록이 없을 때 목록 자리 가운데 안내 | [빈 상태](../components/empty-state.md) |
+| 미리보기 도구(Showcase `PreviewTools`) | 움직임 멈추기 같은 예제 전용 조작. 제품 행동과 분리한 `small` ghost 버튼([선택 조립 규칙](../SELECTION.md#조립-규칙필수)) | — |
 
 ## 배치
 
 ```text
 [안내]
-[기록 추가] [3개 함께 추가]
-[순서 뒤집기] [첫 기록 삭제]
-[움직임 멈추기]
+[기록 추가] [3개 함께 추가] [순서 뒤집기] [첫 기록 삭제]   ← 한 inline 묶음, 좁으면 감김
+미리보기 도구
+[움직임 멈추기]   ← small ghost, 예제 전용
 [변경 결과]
 ┌ 기록 목록 ────────────┐
 │ 제목·설명              │
-│ 메모 입력              │
+│  메모 입력 (행 글자 시작선에 맞춤) │
 ├───────────────────────┤
 │ 다음 기록·메모         │
 └───────────────────────┘
@@ -45,9 +47,11 @@ Magic UI Animated List의 소개 페이지 순차 노출에서 새 항목의 등
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Web: Stack, Native: KeyboardAvoiding → ScrollView → Stack | 위에서 아래. Native canvas는 자체 스크롤이 없으므로 명시적 host 사용 | gap lg=20px, Native keyboardShouldPersistTaps="handled"·하단 spacing.md |
-| 변경 행동 | inline Stack · Button | 목록 위, 좁으면 감김 | 기본 Stack/Button recipe |
-| 데이터 | List | 변경 결과 아래 | separator full, 공통 ListRow/TextField 크기 |
+| 바깥 틀 | Web: `Container size="reading"` → Stack, Native: KeyboardAvoiding → ScrollView → Stack | 위에서 아래. Native canvas는 자체 스크롤이 없으므로 명시적 host 사용 | gap lg=20px, Native keyboardShouldPersistTaps="handled"·하단 spacing.md |
+| 변경 행동 | inline Stack 하나 · Button | 목록 위, 좁으면 감김 | `gap="sm"` 12. 주 행동은 "기록 추가" primary 하나, 나머지는 secondary |
+| 예제 도구 | 미리보기 도구 캡션 + Button `size="small"` `tone="ghost"` | 변경 행동 아래 | 캡션과 버튼 사이 `spacing.xs` 8. 제품에는 복사하지 않는다 |
+| 데이터 | List | 변경 결과 아래 | separator full, 공통 ListRow/TextField 크기. 메모 TextField는 `layoutStyle` 좌우 margin `listRowRecipe.density.comfortable.paddingHorizontal`(8)로 행 글자 시작선에 맞춘다 |
+| 빈 상태 | EmptyState | 목록 자리 가운데 | EmptyState 기본 |
 | 등장 | ContentTransition | 각 stable id 항목 | rise=12px, motion.normal, easing.enter |
 | 높이 | ContentTransition animateHeight | 목록 바깥 | 같은 stateKey를 유지하며 실제 측정 높이만 전환 |
 
@@ -66,7 +70,7 @@ Magic UI Animated List의 소개 페이지 순차 노출에서 새 항목의 등
 | 진행 중 | 새 행만 짧게 등장 | 기존 입력 노드와 초안 유지 |
 | 실패 | 서버 실패가 있는 제품은 기존 목록·초안을 보존하고 오류를 별도 표시 | 이 로컬 예제에는 네트워크 요청 없음 |
 | 삭제 | 해당 행 즉시 제거 | Web pointer 삭제는 먼저 삭제 버튼으로 초점을 옮긴다. 마지막 행은 삭제 버튼도 비활성되므로 추가 버튼으로 이동 |
-| 비어 있음 | 기록 없음과 추가 안내 | 추가 버튼 유지 |
+| 비어 있음 | EmptyState(제목·설명)가 목록 자리 가운데 | 추가 버튼 유지 |
 | 모션 감소·정지 | 같은 데이터, 공간 전환 없음 | 의미·입력 순서 동일 |
 
 ## 코드 골격

package/docs/usage/compositions/navigation-bar-collection.md

@@ -22,8 +22,9 @@
 | --- | --- | --- |
 | BottomNavigation | 목적지 2~6개, 선택 상태, 배지 | [BottomNavigation](../components/bottom-navigation.md) |
 | IconButton `tone="primary" size="large" shape="circle"` | `primaryAction`: 목적지가 아닌 행동 | [IconButton](../components/icon-button.md) |
-| HjmProvider / HjmNativeProvider `brandPalette` | 막대 범위의 제품 색(스토리 색은 예시) | [DesignSystemProvider](../components/design-system-provider.md) |
-| Button `secondary` `selected` | 스토리에서 참고 표현을 고르는 선택기(제품에는 필요 없음) | [Button](../components/button.md) |
+| HjmProvider / HjmNativeProvider `brandPalette` | 막대 범위의 제품 색(스토리 색은 예시). `accent`는 흰 글자를 올리는 채움색, `soft`는 옅은 표면색이다. Web 갤러리는 `host="contents"`로 Provider 자체는 칠하지 않고 Card가 표면을 칠한다 | [DesignSystemProvider](../components/design-system-provider.md) |
+| Card `title`·`description` | 스토리에서 참고 막대 하나를 묶는 갤러리 틀(제품에는 필요 없음). 제목 단계는 페이지 Heading `level3` → 동작 묶음 Heading `level4` → Card 제목 순서로 내려간다 | [Card](../components/card.md) |
+| SegmentedControl | 스토리에서 참고 표현을 고르는 단일 선택기(제품에는 필요 없음). `selected` Button 나열로 만들지 않는다([선택 조립 규칙](../SELECTION.md#조립-규칙필수)) | [SegmentedControl](../components/segmented-control.md) |
 
 ## 배치
 
@@ -142,7 +143,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 `route`·`items`·`routes`·`Link`·`renderGlyph`·`PlusGlyph`·`barRef`/`barHeight`(막대 높이 측정)·`navigation`은 제품 소유다.
 탭 navigator를 쓰면 `View` 대신 navigator의 `tabBar`에 `BottomNavigation`을 넘기고 본문은 각 탭 화면이 그린다.
 
-스토리의 참고 색(`accent`·`soft`), 아이콘 세트, 막대를 감싼 테두리 카드와 `padding-inline: 0`(320 폭 갤러리용) 덮어쓰기는
+스토리의 참고 색(`accent`·`soft`), 아이콘 세트, 막대를 감싼 갤러리 Card와 읽기 폭(`Container size="reading"`) 틀은
 제품에 가져오지 않는다. 제품 색은 앱 루트 Provider의 `brandPalette`로 준다.
 
 ## 플랫폼 차이
@@ -165,3 +166,7 @@ const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "
 2026-10-13 예제는 사각 선택 표현을 공개 tile 축으로 이관하고 내부 radius·padding CSS와 Native deprecated 스타일을 제거했다. Web 갤러리의 `style.position="relative"`는 fixed 막대를 문서 흐름에서 비교하기 위한 showcase 전용 배치다. 제품 하단 탐색에는 복사하지 않으며 `layoutStyle`은 position을 지원하지 않는다.
 
 비교 예제는 목적지 이름과 현재 선택만 바꾸는 메모리 데모다. 주 행동은 작성 화면을 열지 않고 실행 횟수를 올린다. Web 링크는 인스턴스별 fragment를 사용해 현재 선택과 브라우저 뒤로·앞으로 이동을 동기화하고 다른 막대의 주소는 무시한다. 표현 preset을 바꾸면 해당 막대의 초기 선택과 실행 횟수로 새로 시작한다. 실제 router·작성 화면·저장 API는 제품이 연결한다.
+
+## 근거
+
+- 2026-10-17 구성 리뷰: 프로젝트 참고 색이 `accent`/`soft`를 뒤집어 선택 타일이 흰 바탕에 흰 글자로 보였다. Web만 파일 내 CSS 테두리 틀을 써서 플랫폼 구조가 달랐고, 세 단계 제목이 같은 크기였으며, 데스크톱에서 선택 컨트롤이 1280 폭 전체로 늘어났다. 그래서 공개 Card와 읽기 폭 Container로 바꾸고 제목 단계를 나눴다.

package/docs/usage/compositions/optional-motion.md

@@ -44,10 +44,10 @@
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | 제품 화면의 `Container`(좌우 여백·최대 폭) 안에 `Stack gap="md"` | 본문 흐름 안. 스크롤·안전 영역은 화면(문서 스크롤)이 소유하고, 텍스트 입력이 없어 키보드 처리는 없다 | 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 요소 사이 `layout.contentGap` 16. 다른 구획과는 `layout.sectionGap` 24 |
+| 바깥 틀 | 제품 화면의 `Container size="reading"`(좌우 여백·Web 최대 폭 720) 안에 `Stack gap="md"` | 본문 흐름 안. 스크롤·안전 영역은 화면(문서 스크롤)이 소유하고, 텍스트 입력이 없어 키보드 처리는 없다 | 좌우 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 요소 사이 `layout.contentGap` 16. 다른 구획과는 `layout.sectionGap` 24 |
 | 지표 | AnimatedStatistic | 맨 위 | 값은 Statistic `comfortable`(`heading` 크기) |
 | 값 갱신 | Button `secondary` | 지표 아래 | 높이 `medium` 44. 화면의 primary는 제품 주 행동에 남긴다 |
-| 작업 메뉴 | MorphingMenu | 값 갱신 아래 | 트리거에서 펼쳐짐 |
+| 작업 메뉴 | MorphingMenu | 값 갱신 아래 | 닫힌 트리거는 secondary Button과 같은 틀(라벨 + 끝의 `chevronDown`, 높이 44, 폭은 라벨 기준)이고 동작 줄이기·RTL의 `Menu` 트리거와 같은 모양이다. 트리거에서 펼쳐짐(열린 폭 240) |
 | 결과 문구 | `Text as="p" role="status"` | 맨 아래 | — |
 
 ## 흐름과 상태