@hjmds/design-contracts 1.17.2 → 1.19.0

package/docs/usage/components/date-picker.md

@@ -91,7 +91,7 @@ import { DatePicker } from "@hjmds/react-native/date-picker";
 | `renderCellContent` | `(cell: ResolvedCalendarDateCell) => ReactNode` | — | 날짜 아래 보조 표시 |
 | Web `onNavigateBeyondGrid` | `(detail: { date, intent, overflow: "before" \| "after" }, focusDate: (date: string) => void) => void` | — | 키보드가 격자 밖으로 나갈 때 |
 | Native `safeAreaInsets` | Sheet `safeAreaInsets` | Provider 값 | — |
-| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`은 deprecated |
+| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`은 제거된 속성 |
 
 ## 배치
 
@@ -99,7 +99,7 @@ Native trigger 모서리는 `datePickerRecipe.frame.radius` 역할을 Provider
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
-| 크기 | 트리거 높이: `medium` 44 · `large` 52(`datePickerRecipe.sizes`, 두 플랫폼), 좌우 여백 16 · 20. 2026-10-06까지 렌더 값이 Web 44·56, Native 48·56이었다(1.12.1 이후 미게시). 지우기 버튼 44×44. Web 팝오버 폭 `min(22.5rem, 100vw − 2rem)`(최대 360). 날짜 셀 44, 7열 | `datePickerRecipe.sizes`, `packages/react/src/styles.css` `.hjm-date-picker*`, `packages/react-native/src/date-picker.tsx`, `src/calendar.ts` |
+| 크기 | 트리거 높이: `medium` 44 · `large` 52(`datePickerRecipe.sizes`, 두 플랫폼), 좌우 여백 16 · 20. 2026-10-06까지 렌더 값이 Web 44·56, Native 48·56이었다(1.13.0 변경). 지우기 버튼 44×44. Web 팝오버 폭 `min(22.5rem, 100vw − 2rem)`(최대 360). 날짜 셀 44, 7열 | `datePickerRecipe.sizes`, `packages/react/src/styles.css` `.hjm-date-picker*`, `packages/react-native/src/date-picker.tsx`, `src/calendar.ts` |
 | 간격 | 라벨·트리거·설명·오류 사이 Web `spacing.xs` 8, Native 6(렌더러 고정값). 트리거 가로 여백 `medium` `spacing.md` 16, `large` `spacing.lg` 20. 팝오버는 트리거 아래 `spacing.xs` 8, 안쪽 여백 `spacing.sm` 12 | 같은 파일 |
 | 순서·정렬 | 폼 안에서 다른 필드와 같은 폭으로 세로로 쌓는다. 위에서 라벨 → 트리거 → 설명 → 오류. 지우기 버튼(값이 있을 때)은 Web은 트리거 안 끝에 겹치고(트리거가 끝 여백 3rem을 비움), Native는 트리거 바깥 끝에 최소 터치 영역으로 붙는다. Web 팝오버는 시작 쪽 정렬 | `packages/react/src/styles.css`, `packages/react-native/src/date-picker.tsx` |
 | 고정·스크롤 | Web 팝오버는 필드에 붙어 층 800에 뜬다. Native 달력은 화면 아래에서 올라오는 [Sheet](sheet.md)이며 하단 안전 영역은 Provider `safeAreaInsets`를 쓴다 | 같은 파일 |
@@ -125,7 +125,7 @@ Web                                  Native
 - 모든 문구(라벨·placeholder·`clearLabel`·`closeLabel`·월 이동 라벨·셀 이름)는 i18n 키로 만든다.
   셀 이름(`composeAccessibleName`)의 어순·문법은 제품이 소유한다.
 - 달을 넘기면 제품이 새 달의 `cells`와 `monthLabel`을 다시 만들어 넘긴다. 달을 바꿔도 선택값은 바뀌지 않는다.
-- 배치는 `layoutStyle`로 한다(Web·Native). 트리거 색·높이를 덮지 않는다. Native `style`은 deprecated — `layoutStyle` 또는 `size`로 옮긴다.
+- 배치는 `layoutStyle`로 한다(Web·Native). 트리거 색·높이를 덮지 않는다. Native `style`은 제거된 속성 — `layoutStyle` 또는 `size`로 옮긴다.
 
 ## 플랫폼 차이
 
@@ -135,7 +135,7 @@ Web                                  Native
 | `description`·`error` | `ReactNode` | `string` |
 | 격자 밖 이동 알림 `onNavigateBeyondGrid` | 있음 | 없음 |
 | 하단 안전 영역 `safeAreaInsets` | 없음 | 있음(기본은 Provider 값) |
-| 배치 | `layoutStyle`(그 밖에 `className`) | `layoutStyle`(`style`은 deprecated) |
+| 배치 | `layoutStyle`(그 밖에 `className`) | `layoutStyle`(`style`은 제거된 속성) |
 
 ## 함정
 

package/docs/usage/components/description-list.md

@@ -66,7 +66,7 @@ import { DescriptionList } from "@hjmds/react-native/data-display";
 | 항목 | `{ id, label: string, value: string }` | — (필수) | 셋 다 빈 문자열이면 안 된다. 항목이 없거나 `id`가 겹치면 예외가 난다 |
 | Native `label` | `string` | — (필수) | 목록 전체의 접근성 이름 |
 | Native `availableWidth` | 양수 | 측정값 | 주면 측정보다 우선 |
-| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`·`itemStyle`은 deprecated |
+| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`·`itemStyle`은 제거된 속성 |
 
 콜백 prop은 없다.
 
@@ -86,7 +86,7 @@ import { DescriptionList } from "@hjmds/react-native/data-display";
 - 큰 글자 대응으로 화면에서 `fontScale`을 보고 `columns={1}`을 넘기지 않는다. 접힘은 resolver가 한다
   ([계약](../../description-list.md#큰-글자에서의-전환--resolver가-소유)).
 - 라벨은 i18n 키로 넣는다. Native는 목록 전체의 접근성 이름 `label`이 필수다.
-- 배치는 `layoutStyle`로만 한다(Web·Native). 색·글자 스타일을 덮지 않는다. Native `style`·`itemStyle`은 deprecated — 배치는 `layoutStyle`, 열 배치는 `descriptor.columns`로 옮긴다.
+- 배치는 `layoutStyle`로만 한다(Web·Native). 색·글자 스타일을 덮지 않는다. Native `style`·`itemStyle`은 제거된 속성 — 배치는 `layoutStyle`, 열 배치는 `descriptor.columns`로 옮긴다.
 
 ## 플랫폼 차이
 
@@ -95,7 +95,7 @@ import { DescriptionList } from "@hjmds/react-native/data-display";
 | 데이터 전달 | `items`, `columns` 평면 prop | `descriptor={{ items, columns }}` |
 | 목록 이름 | 없음(`dl`/`dt`/`dd` 의미 구조) | `label` 필수, `accessibilityRole="list"` |
 | 폭 측정 | 요소 폭 측정 | `availableWidth`가 우선, 없으면 `onLayout` 측정, 첫 프레임은 창 폭 |
-| 배치 prop | `layoutStyle`(`style`과 합친다) | `layoutStyle`(`style`·`itemStyle`은 deprecated) |
+| 배치 prop | `layoutStyle`(`style`과 합친다) | `layoutStyle`(`style`·`itemStyle`은 제거된 속성) |
 
 ## 함정
 

package/docs/usage/components/design-system-provider.md

@@ -86,9 +86,9 @@ expect(checkBrandPaletteContrast(PRODUCT_BRAND_PALETTE)).toEqual({ light: [], da
 | `reducedMotion` | `true` · `false` | `false` | — |
 | `minimumVisualTarget` | `true` · `false` | `false` | — |
 | `brandPalette` | `{ light?, dark? }` | — | 각각 `ThemeColors` 17개 key 중 필요한 것만 넘긴다(부분 병합). 상태 강조색은 덮을 수 없다. 중첩 Provider는 가장 가까운 상위의 값을 물려받는다 |
-| `designProfile` | `HjmDesignProfile` | 가장 가까운 상위 프로필 또는 없음 | 기본 프로필은1.15.0 게시. `hjmDesignPresets` 또는 `defineHjmDesignProfile` 결과만 넣는다. 후속 글자 역할·질감/구성 개선은 아직 미게시다. [프로필 계약](../../design-profile.md)의 토큰·질감·전환·구성·화면 기본값을 상속한다 |
+| `designProfile` | `HjmDesignProfile` | 가장 가까운 상위 프로필 또는 없음 | 기본 프로필·표면 질감은 1.15.0 추가. `hjmDesignPresets` 또는 `defineHjmDesignProfile` 결과만 넣는다. 글자 역할·관련 구성 개선은 1.16.0 변경. [프로필 계약](../../design-profile.md)의 토큰·질감·전환·구성·화면 기본값을 상속한다 |
 | `value` | `DesignSystemProviderValue`(`resolveDesignSystemProviderValue` 결과) | — | 테스트·스토리·임베딩용. 환경 prop·`brandPalette`·`designProfile`과 함께 쓸 수 없고(타입이 막는다), 주면 OS theme·모션 관찰과 상위 `brandPalette` 상속이 멈춘다 |
-| `surfaceEffects`(Native) | `{ renderBackdrop?, insetShadows? }` | 상위 host 또는 없음 | 미게시 실험. 실제 blur host·inset capability를 한 번 등록하며 `{}`로 하위 영역을 해제. [Surface 질감 계약](../../design-profile.md#surfacecard의-유리클레이-질감) |
+| `surfaceEffects`(Native) | `{ renderBackdrop?, insetShadows? }` | 상위 host 또는 없음 | 1.15.0 실험 API. 실제 blur host·inset capability를 한 번 등록하며 `{}`로 하위 영역을 해제. [Surface 질감 계약](../../design-profile.md#surfacecard의-유리클레이-질감) |
 | `safeAreaInsets`(Native) | `{ top?, right?, bottom?, left? }`(pt) | `{}` | 보통 `useSafeAreaInsets()` 결과. 중첩 Provider는 가장 가까운 상위 값을 물려받는다 |
 
 - 제품 상태를 바꾸는 이벤트 prop은 없다. Native의 선택형 `surfaceEffects.renderBackdrop`은 장식 host만 공급한다. 해석된 값은 Web `useHjmTheme()`, Native `useHjmNativeTheme()`로 읽는다.

package/docs/usage/components/dialog.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-07
+- 검토일: 2026-10-13
 - 근거: [Dialog](../../dialog.md), [명령형 오버레이](../../overlay-stack.md), recipe `dialogRecipe`(`src/component-recipes.ts`)
 - 스토리북: `배포/컴포넌트/오버레이/대화상자`
 
@@ -49,6 +49,7 @@ import { Dialog } from "@hjmds/react/overlays";
 <Dialog
   open={open}
   onOpenChange={(next) => setOpen(next)}
+  returnFocusRef={openButtonRef}
   title={t("album.rename.title")}
   description={t("album.rename.description")}
   closeLabel={t("common.close")}
@@ -64,6 +65,11 @@ import { Dialog } from "@hjmds/react/overlays";
 </Dialog>
 ```
 
+Web에서 바깥 버튼으로 `open`을 제어할 때는 그 버튼의 ref를 `returnFocusRef`로 연결한다.
+위 `openButtonRef`는 `useRef<HTMLButtonElement>(null)`로 만들고 여는 버튼의 `ref`에도 준다.
+macOS WebKit은 버튼 클릭이 초점을 옮기지 않을 수 있어, 열기 직전 `activeElement`만으로는
+닫힌 뒤 호출 위치를 복구할 수 없다(2026-10-13 브라우저 대조). `trigger` 슬롯을 사용하면 이 연결은 내부에서 처리한다.
+
 ```tsx
 // Native
 import { Dialog } from "@hjmds/react-native/overlays";
@@ -89,6 +95,11 @@ Native `save`는 저장 Promise를 반환한다. Dialog가 완료를 기다리
 이벤트 밖에서 시작한 요청은 외부 `busy`로 연결한다. 이전 즉시 닫힘 대응 예제가 현재 Promise 계약과 충돌해
 2026-10-06 독립 재구현 검증에서 교정했다.
 
+Native Dialog는 화면 하단에 붙은 키보드가 나타나면 그 위의 사용 가능한 영역에 가운데 정렬한다.
+입력 본문은 내부에서 스크롤하고 제목·닫기·저장 행동은 그 밖에 유지한다. 별도 KeyboardAvoidingView를
+중첩하지 않는다. iOS 입력 예제에서 저장 버튼이 키보드에 가려진 재현을 바탕으로 Sheet와 같은 좌표 계산을
+공유한다(2026-10-13). Android가 이미 줄인 모달 높이는 다시 빼지 않으며 떠 있는 키보드는 이 여백 계산에서 제외한다.
+
 ```tsx
 // Web 명령형: 앱 루트에 <OverlayStackProvider>를 두고
 import { useDialog } from "@hjmds/react/overlay-stack";
@@ -111,8 +122,8 @@ await handle.closed; // portal 제거·초점 복구 뒤. 다음 오버레이는
 | `onOpenChange` | `(open: boolean, detail: { reason }) => void` | — | Web `reason`: `"trigger"`·`"close-action"`·`"escape"`·`"outside"`. Native: `"close-action"`·`"back"`·`"outside"`. `busy`이거나 `dismissible={false}`면 닫기 요청을 보내지 않는다 |
 | `onDismissComplete`(Web) | `(detail: { reason: "close-action" \| "escape" \| "outside" \| "programmatic" }) => void` | — | 한 번 열릴 때마다 한 번, portal 제거·초점 복구 뒤. 다음 오버레이는 여기서 연다 |
 | `trigger`(Web) | `ReactElement`(버튼 요소) | — | 누르면 `reason: "trigger"`로 열린다 |
-| `primaryAction`·`secondaryAction`(Native) | `{ label, onPress: () => void \| Promise<void>, tone?, disabled?, accessibilityHint? }` | — | 동기 함수는 같은 누름에서 닫힌다. Promise를 반환하면 기다리는 동안 누른 버튼이 loading이 되고 행동·닫기·back·바깥 닫기가 모두 막히며, 성공하면 `close-action`으로 닫힌다. 던지거나 거절되면 열린 채 행동이 다시 켜지고 `onActionError`를 호출한다. 외부 `busy`도 반복 행동·닫기를 막는다. 미게시(1.12.1 이후) — 1.12.1은 Promise를 무시하고 바로 닫았다 |
-| `onActionError`(Native) | `(error: unknown) => void` | — | action 실패를 본문 오류·재시도로 연결한다. 오류를 처리하는 동안 초안을 보존한다. 없으면 개발 빌드에서 실패마다 `console.error`를 남긴다(중복 제거 없음). 미게시(1.12.1 이후) |
+| `primaryAction`·`secondaryAction`(Native) | `{ label, onPress: () => void \| Promise<void>, tone?, disabled?, accessibilityHint? }` | — | 동기 함수는 같은 누름에서 닫힌다. Promise를 반환하면 기다리는 동안 누른 버튼이 loading이 되고 행동·닫기·back·바깥 닫기가 모두 막히며, 성공하면 `close-action`으로 닫힌다. 던지거나 거절되면 열린 채 행동이 다시 켜지고 `onActionError`를 호출한다. 외부 `busy`도 반복 행동·닫기를 막는다. 1.13.0 변경 — 1.12.1은 Promise를 무시하고 바로 닫았다 |
+| `onActionError`(Native) | `(error: unknown) => void` | — | action 실패를 본문 오류·재시도로 연결한다. 오류를 처리하는 동안 초안을 보존한다. 없으면 개발 빌드에서 실패마다 `console.error`를 남긴다(중복 제거 없음). 1.13.0 변경 |
 | `children`(Native) | `ReactNode` | — | 고정된 제목 줄 아래 스크롤 본문(`ScrollView`) 안에 들어간다. `FlatList`·`SectionList`를 넣지 않는다 |
 | `contentStyle`(Native) | 배치 key만(`HjmCompositionStyleProp`) | — | 대화상자 상자의 배치. 높이는 `size`로 |
 | `useDialog()`(Web) | `(request) => { closed: Promise<void>, close(): void }` | — | request는 `open`·`defaultOpen`·`onOpenChange`·`trigger`를 뺀 DialogProps. `OverlayStackProvider` 안에서만 |

package/docs/usage/components/divider.md

@@ -54,7 +54,7 @@ import { Divider } from "@hjmds/react-native/data-display";
 | `orientation` | `horizontal` · `vertical` | `horizontal` | 가로선·세로선 |
 | `inset` | Web `none` · `start` · `both` / Native 숫자(pt, 토큰 값으로 넘긴다) | Web `none`(0) / Native 0 | Web `start`·`both`는 `spacing.md`. Native는 가로선이면 좌우, 세로선이면 위아래 여백이 된다 |
 | Web `decorative` | `boolean` | `false` | `true`면 `role="presentation"`·`aria-hidden` |
-| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`은 deprecated |
+| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`은 제거된 속성 |
 
 콜백 prop은 없다.
 
@@ -71,7 +71,7 @@ import { Divider } from "@hjmds/react-native/data-display";
 ## 꼭 지킬 것
 
 - 색·두께를 `style`/`className`으로 바꾸지 않는다. 구분선 색은 제품 테마의 `border` key로 바뀐다.
-  배치는 `layoutStyle`로 한다. Native `style`은 deprecated — `layoutStyle` 또는 `orientation`·`inset`으로 옮긴다.
+  배치는 `layoutStyle`로 한다. Native `style`은 제거된 속성 — `layoutStyle` 또는 `orientation`·`inset`으로 옮긴다.
 - Web에서 의미가 없는 장식선은 `decorative`로 표시한다(`role="presentation"`, `aria-hidden`).
   기본은 `role="separator"`다.
 

package/docs/usage/components/editor-screen.md

@@ -3,8 +3,8 @@
 - 단계: 컴포넌트
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 1.17.1
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
 - 스토리북: `배포/화면/콘텐츠/작성과 수정`, `배포/화면/계정/프로필`
 
@@ -92,7 +92,7 @@ import { TextField } from "@hjmds/react-native/inputs";
 | prop | 값 | 기본값 | 설명 |
 | --- | --- | --- | --- |
 | `dirty` | `boolean` | 필수 | `true`에서 닫기를 누르면 `discard` 확인창을 띄우고, 확인하면 `cancel.onAction`을 부른다. `false`면 바로 부른다 |
-| `submit` | `ScreenFlowAction`(`{ label, onAction(), disabled?, pending? }`) | 필수 | `pending`이면 loading·비활성. 그동안 닫기 버튼도 비활성 |
+| `submit` | `ScreenFlowAction`(`{ label, onAction(), disabled?, pending? }`) | 필수 | `pending`이면 loading·비활성. 그동안 닫기 버튼도 비활성. 본문 `state`가 `ready`가 아니면 저장 비활성 |
 | `cancel` | `ScreenFlowAction` | 필수 | `leading` 자리의 ghost 닫기 버튼 |
 | `discard` | AlertDialog confirm 요청에서 `onConfirm`을 뺀 것 + `fallbackErrorMessage: string` | 필수 | `onConfirm`은 EditorScreen이 채운다 |
 | `submitPlacement` | `"footer"` · `"header"` | `"footer"` | `header`면 저장이 상단 `actions` 자리로 가고 footer에는 `draftStatus`만 남는다 |
@@ -115,6 +115,8 @@ import { TextField } from "@hjmds/react-native/inputs";
 - 모든 문구(`label`, `discard`의 제목·설명·버튼)는 i18n 키로 넣는다. 컴포넌트는 기본 문구를 갖지 않는다.
 - `discard`는 `fallbackErrorMessage`까지 필수 타입이다. `onConfirm`은 EditorScreen이 채우므로 넘기지 않는다.
 - 확인 후 초안을 되돌리는 일은 `cancel.onAction` 안에서 제품이 한다.
+- 저장 시작 또는 `cancel.disabled`/`cancel.pending` 전환은 이미 열린 초안 버리기 확인도 종료한다. 잠금이 풀렸다고 확인창이 다시 열리지는 않는다. 2026-10-13 이전 확인창으로 저장 중 이탈 잠금을 우회할 수 있던 경로를 수정했다.
+- 최초 조회·오류·권한 제한 등 본문 대체 상태에서는 저장을 잠근다. 새 문서의 빈 초안은 `state="empty"`가 아니라 `ready`와 빈 입력으로 표현하고 제품 validation은 `submit.disabled`에 연결한다.
 - 라우터 뒤로가기·Android back·브라우저 이탈은 이 컴포넌트가 막지 않는다. 제품이 `dirty`로 guard를 건다.
 - 저장 성공 판정·오류 표시는 제품 상태(`notice`, Toast 등)로 한다.
 

package/docs/usage/components/effect-surface.md

@@ -62,7 +62,7 @@ import { EffectSurface } from "@hjmds/react-native/effect-surface";
 
 | prop | 값 | 기본값 | 설명 |
 | --- | --- | --- | --- |
-| `descriptor.layers` | `mesh` · `glow` · `grain` · `noise` · `ruled` | `["mesh"]` | 서로 다른 1~4개. ruled는 1.15.0 이후 미게시 실험 |
+| `descriptor.layers` | `mesh` · `glow` · `grain` · `noise` · `ruled` | `["mesh"]` | 서로 다른 1~4개. ruled는 1.16.0 추가 실험 |
 | `descriptor.ruledSpacing` | 유한한 8~128 host units | `24` | ruled의 1unit 선 간격. 텍스트 baseline과 독립적이며 모션 밖 정적 레이어 |
 | `descriptor.intensity` | 0~1 | `0.22` | — |
 | `descriptor.period` | 2~120초 | `12` | — |

package/docs/usage/components/empty-state.md

@@ -67,7 +67,7 @@ import { EmptyState } from "@hjmds/react-native/feedback";
 | `description` | Web `ReactNode` · Native `string` | — | — |
 | `action` | `ReactNode`(Button 하나) | — | 콜백은 Button의 `onClick`·`onPress`가 갖는다 |
 | Web `icon` · Native `illustration` | `ReactNode` | — | 장식, 접근성에서 숨김 |
-| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`·`illustrationStyle`·`titleStyle`·`descriptionStyle`·`actionStyle`은 deprecated |
+| `layoutStyle` | 배치 전용 style | — | 루트 배치. Native `style`·`illustrationStyle`·`titleStyle`·`descriptionStyle`·`actionStyle`은 제거된 속성 |
 
 EmptyState 자체에는 콜백 prop이 없다. 2026-10-07 기존 예제의 생성 버튼에 동작이 없음을 확인해
 양 기본 스토리를 예시 생성 → 검색 0건 → 검색어 지우기 → 목록 복구로 연결했다. 이 데이터는
@@ -77,7 +77,7 @@ EmptyState 자체에는 콜백 prop이 없다. 2026-10-07 기존 예제의 생
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
-| 크기 | 그림 슬롯은 `glyph.lg`(28) 정사각형이다(Native `illustration` 상자 고정 크기). 세로 여백: `compact` `spacing.xl`(24). `regular` `spacing.xxxl`(40, 두 플랫폼) | `component-recipes.ts` `emptyStateRecipe`, `styles.css` `.hjm-empty-state` |
+| 크기 | Native 그림 슬롯은 최소 `glyph.lg`(28) 폭·높이를 확보하고 큰 일러스트의 자체 크기를 존중한다. Web 그림 슬롯에는 고정 크기가 없다. 세로 여백: `compact` `spacing.xl`(24). `regular` `spacing.xxxl`(40, 두 플랫폼) | `component-recipes.ts` `emptyStateRecipe`, `styles.css` `.hjm-empty-state` |
 | 간격 | 항목 사이 간격 `spacing.xs`(8), 좌우 여백 `spacing.xl`(24) | `component-recipes.ts` `emptyStateRecipe` |
 | 순서·정렬 | 위→아래 순서는 그림 → 제목 → 설명 → 행동이고 가운데 정렬이다. 행동은 Button 하나(`tone="secondary"` 또는 `primary`)를 내용 폭만큼 둔다 | `react-native/src/feedback.tsx` `EmptyState` |
 | 고정·스크롤 | 비어 있는 목록·검색 결과 영역 **안**에 둔다. 위 TopBar·검색칸·필터는 그대로 남기고 그 아래 내용 영역만 EmptyState로 바꾼다. Native `regular`는 남은 높이를 채우고(`flexGrow: 1`) 세로 가운데에 놓는다. `align="upper"`는 위:아래 빈 공간을 1:3으로 나눠 내용이 위쪽에 온다. 화면 하단 고정 행동이 필요하면 [BottomCTA](bottom-cta.md)로 따로 둔다 | `react-native/src/feedback.tsx` `EmptyState` |
@@ -107,16 +107,16 @@ EmptyState 자체에는 콜백 prop이 없다. 2026-10-07 기존 예제의 생
 - 제목·설명·행동 문구는 i18n 키로 넣는다. "검색 0건"과 "아직 만든 것 없음"은 다른 문구로 구분한다.
 - 다음 행동이 있으면 `action`에 Button 하나를 둔다. 아이콘·일러스트는 장식이라 접근성에서 숨겨진다.
 - Native는 `title`·`description`·`accessibilityLabel` 중 하나는 있어야 한다. 모두 없으면 `TypeError`를 던진다.
-- 일러스트·아이콘 자산은 제품 소유다. 색은 recipe가 정하므로 슬롯 색을 덮지 않는다.
+- 일러스트·아이콘 자산과 자체 크기는 제품 소유다. 큰 그림은 `illustration` 노드 안에서 크기를 지정한다. EmptyState의 제목·설명 색은 recipe가 정하며 제거된 `illustrationStyle`로 프레임을 덮지 않는다.
 - 배치는 `layoutStyle`로 한다. Native 슬롯 style(`style`·`illustrationStyle`·`titleStyle`·`descriptionStyle`·`actionStyle`)은
-  deprecated(개발 모드 1회 경고, 다음 major 제거)다 — 배치는 `layoutStyle`, 외형은 `density`·`align`으로 옮긴다.
+  제거된 속성이다 — 배치는 `layoutStyle`, 외형은 `density`·`align`으로 옮긴다.
 
 ## 플랫폼 차이
 
 | 항목 | Web | Native |
 | --- | --- | --- |
-| 그림 슬롯 | `icon`(ReactNode) | `illustration`(ReactNode, 아이콘 크기 상자) |
+| 그림 슬롯 | `icon`(ReactNode) | `illustration`(ReactNode, 최소 아이콘 크기 + 콘텐츠 자체 크기) |
 | `title` | 필수, ReactNode | 선택, string |
 | `description` | ReactNode | string |
 | 정렬·알림 | 없음 | `align`, `announcement`, `accessibilityLabel`, `titleRole` |
-| 배치 | `layoutStyle`(그 밖에 `className`과 div 속성) | `layoutStyle`(슬롯 style 다섯 개는 deprecated) |
+| 배치 | `layoutStyle`(그 밖에 `className`과 div 속성) | `layoutStyle`(슬롯 style 다섯 개는 제거된 속성) |

package/docs/usage/components/field.md

@@ -30,6 +30,8 @@
 | `Field` | 기본 — 커스텀 컨트롤용 틀 | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/forms` |
 | `TextField` | 동반 — 한 줄 텍스트 입력 | `@hjmds/react`, `/forms` | `@hjmds/react-native`, `/inputs` |
 | `GestureSheetInput` | 확장 — GestureSheet 안의 키보드 추적 입력 | 없음 | `/sheet-gesture` |
+| `DateEntry` | 확장 — 날짜 조각 직접 입력([구성 지침](../compositions/date-entry.md)) | `/date-entry` | `/date-entry` |
+| `FieldGroup` | 확장 — 관련 입력의 그룹 안내·오류([구성 지침](../compositions/field-group.md)) | `/field-group` | `/field-group` |
 
 ## 최소 사용 예
 
@@ -130,7 +132,7 @@ TextField와 같은 테두리·글꼴·placeholder 색을 입힌다. 라벨·도
   않는다(TS2375). 위 예처럼 조건부 spread로 넘긴다. Web은 `ReactNode`라 `undefined`를 그대로 넘겨도 된다.
 - Web `Field`는 `controlId`가 필수이고, Native `Field`에는 `controlId`가 없다. 공용 코드에서 같은 props 객체를 넘기지 않는다.
 
-### 날짜 조각 직접 입력 (실험·미게시)
+### 날짜 조각 직접 입력 (1.14.0 추가·실험)
 
 알고 있는 날짜를 년·월·일로 직접 편집하려면 `DateEntry`를 사용한다.
 Web `@hjmds/react/date-entry`, Native `@hjmds/react-native/date-entry`의 Field 확장이다.
@@ -143,11 +145,11 @@ Web `@hjmds/react/date-entry`, Native `@hjmds/react-native/date-entry`의 Field
 
 Web TextField의 `aria-invalid={true}`는 외부 오류 ID를 `aria-describedby`로 연결하는 경우에도
 오류 테두리를 표시한다. Native TextField/TextArea의 `invalid`는 인라인 error 문구 없이 오류
-테두리를 표시하는 미게시 옵션이다. 같은 오류를 `accessibilityHint`로 연결하고 그룹 안내를
+테두리를 표시하는 옵션이다(1.14.0 추가). 같은 오류를 `accessibilityHint`로 연결하고 그룹 안내를
 별도로 보여 준다. error가 있으면 해당 문구가 hint보다 우선하고, hint가 없으면 description을 쓴다.
 2026-10-07 날짜 직접 입력의 큰 글자 오류가 세 번 반복된 관찰에 따라 이 경로를 추가했다.
 
-### 관련 입력 그룹 (실험·미게시)
+### 관련 입력 그룹 (1.14.0 추가·실험)
 
 여러 입력이 한 질문에 답하면 `FieldGroup`을 사용한다. Form의 제출 경계와 구분하며
 `@hjmds/react/field-group`, `@hjmds/react-native/field-group`에서 제공한다.

package/docs/usage/components/file-picker.md

@@ -70,7 +70,7 @@ import { FilePicker } from "@hjmds/react-native/file-picker";
 | Native `onPick` | `() => Promise<readonly FilePickerCandidate[] \| null>` | 필수 | 제품 adapter. 취소면 `null` |
 | Native `onPickError` | `(error: unknown) => void` | 필수 | `onPick`이 reject하면 이쪽으로만 온다 |
 | Web `getCandidateId` | `(file: File, index: number) => string` | `name:size:lastModified:index` | 후보 id 규칙 |
-| `disabled` | `true` · `false` | `false` | — |
+| `disabled` | `true` · `false` | `false` | 선택 완료 시에도 잠금 상태면 결과를 반영하지 않는다 |
 | `hint`, `error` | 문구 | — | 선택 사항이다 |
 
 - `FilePickerCandidate`: `{ id, name, mimeType, sizeBytes }`(`mimeType`은 플랫폼이 못 정하면 `""`).
@@ -93,6 +93,9 @@ import { FilePicker } from "@hjmds/react-native/file-picker";
   만들고 색으로만 알리지 않는다.
 - `rejected`가 있어도 `accepted`는 그대로 쓴다. 한 장이 막혔다고 전체 선택을 버리지 않는다.
 - FilePicker는 선택 목록을 쌓지 않는다. 고른 파일 목록·업로드 상태는 제품 상태와 UploadItem이 소유한다.
+- 취소(Web의 빈 선택, Native adapter의 `null`)는 기존 목록을 바꾸거나 `onSelect`를 호출하지 않는다. 같은 파일은 다시 선택할 수 있다.
+- Native 결과는 완료 시점의 `descriptor`·`existingCount`로 판정하고 현재 콜백으로 전달한다. 대기 중 다른 파일이 추가·제거되면 `existingCount`를 계속 갱신한다.
+- 파일 행 제거와 제거 후 초점 복귀는 목록을 소유한 제품이 처리한다. 제거 버튼을 FilePicker 내부에 가정하거나 선택 콜백을 목록 초기화 신호로 쓰지 않는다.
 - Native 실제 OS document/image picker 연결(`onPick`)은 제품 책임이다. 패키지는 이를 구현하거나
   기기에서 검증하지 않는다. 제품 릴리스 QA에서 확인한다.
 
@@ -106,7 +109,7 @@ import { FilePicker } from "@hjmds/react-native/file-picker";
 | 진행 중 잠금 | 없음 | `onPick` 대기 중 버튼 `busy`·비활성 |
 | `label`·`hint`·`error` 타입 | `ReactNode` | `string` |
 | 후보 id | `getCandidateId`(기본 `name:size:lastModified:index`) | adapter가 `id`를 채움 |
-| 배치 | `layoutStyle`(루트), `className`과 div 속성 | `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 recipe |
+| 배치 | `layoutStyle`(루트), `className`과 div 속성 | `layoutStyle`. `style`은 제거된 속성 — `layoutStyle` 또는 recipe |
 
 ## 함정
 
@@ -117,4 +120,4 @@ import { FilePicker } from "@hjmds/react-native/file-picker";
 
 2026-10-07 소비 감사에서 Native 선택 버튼의 모서리 12가 프로필을 우회했다. Web 버튼의 기존 `radius.md`와 같은 역할을 Native도 가까운 프로필에서 읽으며, 프로필이 없으면 기존 12를 유지한다. 선택 어댑터·비활성/진행 상태·파일 검증은 바꾸지 않는다.
 
-프로필 연결은 1.15.0 이후 미게시 변경이며, 기본 배포 계약과 실제 Native 기기 검증은 구분한다.
+프로필 연결은 1.16.0 변경이며, 기본 배포 계약과 실제 Native 기기 검증은 구분한다.

package/docs/usage/components/form.md

@@ -157,7 +157,7 @@ useEffect(() => { firstInvalidRef.current = nicknameError ? nicknameInputRef.cur
 | 실패 처리 | Promise reject를 삼킨다. 제품이 `formError`를 설정 | reject하면 `failed`로 바꾸고 Error 메시지 또는 `fallbackErrorMessage`를 alert로 표시 |
 | 첫 오류 필드로 이동 | 없음. 제품이 `onSubmit` 안에서 첫 무효 입력에 `.focus()`한다 | `firstInvalidFieldRef`: 버튼을 누른 순간 `current`를 읽는다. non-null이면 그 입력에 focus와 스크린 리더 focus를 옮기고 `onSubmit`·`onStatusChange` 없이 멈춘다(상태 그대로). ref는 `useEffect`에서 갱신하고, 순서 계산은 `resolveFirstInvalidFieldFocusTarget(fieldOrder, invalidIds)`를 쓴다 |
 | 접근성 이름 | `<form>` 속성(`aria-label` 등) | `label` 필수 |
-| 배치 | `className`, `layoutStyle`(form 속성 `style`도 받음) | `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 `density` |
+| 배치 | `className`, `layoutStyle`(form 속성 `style`도 받음) | `layoutStyle`. `style`은 제거된 속성 — `layoutStyle` 또는 `density` |
 | 밖에서 제출 | `<form>`이므로 `type="submit"` 버튼·Enter로 된다 | `ref: Ref<FormHandle>`의 `submit()`으로 같은 validation·중복 제출 방지를 실행 |
 
 ## 함정

package/docs/usage/components/heading.md

@@ -83,14 +83,14 @@ import { Heading } from "@hjmds/react-native/heading";
 | --- | --- | --- |
 | 출력 | `h1`~`h6` 요소 | `Text` + `accessibilityRole="header"` + `aria-level` |
 | 추가 prop | `HTMLAttributes`(`id`, `className`, `style` 등), ref | 없음 |
-| 배치 | `layoutStyle`. `style`도 합쳐진다(크기 변수는 덮이지 않음) | `layoutStyle`. `style`(TextStyle)은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 `level` |
+| 배치 | `layoutStyle`. `style`도 합쳐진다(크기 변수는 덮이지 않음) | `layoutStyle`. `style`(TextStyle)은 제거된 속성 — `layoutStyle` 또는 `level` |
 | 글자 배율 | `--hjm-text-scale`로 확대 | Native `Text`의 글자 배율 |
 
 ## 함정
 
 - Web `style`은 이제 버려지지 않고 합쳐진다. 다만 크기·줄 높이·굵기 변수(`--hjm-heading-*`)는 recipe가 마지막에 덮으므로
   `style`로 크기를 바꿀 수 없다. 배치는 `layoutStyle`로 준다.
-- Native `style`(deprecated)은 아직 마지막에 합쳐져 색·크기까지 바뀐다. 쓰지 말고 `layoutStyle`·`level`로 옮긴다.
+- Native `style`은 제거되었다. 배치는 `layoutStyle`, 제목 위계는 `level`로 지정한다.
 
 2026-10-07 추가: 제목은 프로필의 optional `tokens.fontFamily.display`를 사용하고 생략 시 현재 ui를 따른다.
-문서 semanticLevel·크기·굵기는 유지한다. [서체 역할](../tokens/font-roles.md), 1.15.0 이후 미게시.
+문서 semanticLevel·크기·굵기는 유지한다. [서체 역할](../tokens/font-roles.md), 1.16.0 변경.

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

@@ -80,7 +80,7 @@ import { NotificationBell } from "@hjmds/react-native/notification-bell";
 | `onPress`(NotificationBell) | `() => void` | 필수 | Web·Native 모두 `onPress`다(Web도 `onClick`이 아니다) |
 | `active`(NotificationBell) | `true` · `false` | `true` | — |
 | `disabled`(NotificationBell) | `true` · `false` | `false` | — |
-| Web `layoutStyle`(NotificationBell) | `HjmCompositionStyleProp` | — | 루트 배치. 기본 `alignSelf: "flex-start"`보다 우선하지만 `width`는 무시된다(루트는 항상 `max-content`). 떠 있는 배지가 루트의 끝 모서리에 붙어 있어 루트가 넓어지면 아이콘에서 떨어지기 때문이다. margin·`alignSelf`로 배치한다. 미게시(1.12.1 이후) |
+| Web `layoutStyle`(NotificationBell) | `HjmCompositionStyleProp` | — | 루트 배치. 기본 `alignSelf: "flex-start"`보다 우선하지만 `width`는 무시된다(루트는 항상 `max-content`). 떠 있는 배지가 루트의 끝 모서리에 붙어 있어 루트가 넓어지면 아이콘에서 떨어지기 때문이다. margin·`alignSelf`로 배치한다. 1.13.0 변경 |
 
 ## 배치
 
@@ -117,10 +117,13 @@ TopBar
 | 스피너 교체 | 없음 | `renderLoadingIndicator` |
 | 비활성이지만 포커스 유지 | `aria-disabled` | `loading` 기본 동작 |
 | NotificationBell 흔들림 정지 | 문서 숨김·reduced motion | AppState 비활성·reduced motion |
-| 배치 | `layoutStyle`(IconButton·NotificationBell, NotificationBell은 `width` 무시) | IconButton `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 `tone`·`size`·`shape`. NotificationBell은 배치 prop이 없어 감싸는 View로 배치한다 |
+| 배치 | `layoutStyle`(IconButton·NotificationBell, NotificationBell은 `width` 무시) | IconButton `layoutStyle`. `style`은 제거된 속성 — `layoutStyle` 또는 `tone`·`size`·`shape`. NotificationBell은 배치 prop이 없어 감싸는 View로 배치한다 |
 
 ## 함정
 
 - children의 색은 버튼이 칠하지 않는다. HJM Icon은 자기 `tone` 색을 쓰므로, `primary`·`danger` 버튼 안에서는
   `tone="inverse"`를 준다. 다른 아이콘 라이브러리의 컴포넌트를 직접 넣으면(Native) 색을 제품이 넘겨야 한다.
-- Native `IconButton` `style`은 deprecated지만 다음 major 전까지 recipe 뒤에 합쳐져 지름·배경까지 바뀐다. 새 코드에서 쓰지 않는다.
+- Native `IconButton`의 `style`은 제거되었다. 배치는 `layoutStyle`, 외형은 `tone`·`size`·`shape`로 지정한다.
+
+2026-10-10 사용자 요청: Button과 같은 선택 표현을 쓴다. 선택은 bg 바탕·contentBrand 아이콘으로
+표시하고 추가 선택 테두리는 없다. aria-pressed/Native selected와 키보드 focus outline은 유지한다.

package/docs/usage/components/icon.md

@@ -96,7 +96,7 @@ const renderGlyph = createLucideGlyph({ search: Search, back: ArrowLeft });
 | glyph | 내장 SVG 경로, `renderGlyph`는 선택 | `renderGlyph` 필수(내장 그림 없음) |
 | 사용자 정의 이름 | `SemanticIconName`만 | `Icon<Name>` 제네릭으로 제품 이름 허용 |
 | 출력 | `<svg>`(장식이면 `aria-hidden`) | `View` 프레임(장식이면 `accessible={false}`) |
-| 배치 | `layoutStyle` | `layoutStyle`. `style`은 deprecated(개발 모드 1회 경고, 다음 major 제거) — `layoutStyle` 또는 descriptor `size`·`tone` |
+| 배치 | `layoutStyle` | `layoutStyle`. `style`은 제거된 속성 — `layoutStyle` 또는 descriptor `size`·`tone` |
 
 ## 함정
 

package/docs/usage/components/image.md

@@ -84,10 +84,11 @@ import { ImageViewer } from "@hjmds/react-native/image-viewer";
 | ImageViewer `onClose` · `onIndexChange` | `() => void` · `(index: number) => void` | `onClose` 필수 | — |
 | ImageViewer `safeAreaInsets` | `{ top: number; bottom: number; left?: number; right?: number }` | 필수, 좌우 0 | 버튼·caption·상태 안내를 물리적 좌우 안전 영역 안에 배치. 사진은 전체 갤러리 폭 사용 |
 | ImageViewer `supportedOrientations` | RN Modal의 orientation 배열 | RN 기본값 | 제품 manifest·기기 회전 잠금 범위 안에서 허용. Modal은 fullScreen |
-| ImageViewer `renderImage` | `(props: ImageViewerImageRenderProps) => ReactNode` | RN Image | Native 전용, 미게시. `item`, 측정된 `width`·`height`, `onReady`·`onError`를 전달. 제품 이미지 host의 캐시·표시 이벤트를 연결 |
+| ImageViewer `renderImage` | `(props: ImageViewerImageRenderProps) => ReactNode` | RN Image | Native 전용, 1.14.0 추가. `item`, 측정된 `width`·`height`, `onReady`·`onError`를 전달. 제품 이미지 host의 캐시·표시 이벤트를 연결 |
 | ImageViewer `onImageStatusChange` | `({ item, status }) => void` | 없음 | `loading`·`ready`·`error`. 마운트된 각 이미지 기준이며 비선택 페이지도 포함할 수 있음 |
 
 - 실패하면 중립 배경 위에 오류 기호를 그리고, 정보 이미지의 이름은 그대로 유지한다. `fallback`은 시각만 바꾼다.
+- 같은 주소라도 Web `imageProps.srcSet`/요청 정책, Native `sourceAdapter`의 실제 source·헤더·cache 내용이 바뀌면 새 요청으로 보고 loading부터 시작한다. inline adapter 함수만 다시 만든 것은 재시도가 아니다. 같은 요청을 명시적으로 재시도하거나 adapter 구현만 교체하려면 `<Image key={attempt} ... />`처럼 요청 시도 키로 Image 전체를 다시 마운트한다. 실패한 요청의 늦은 콜백은 새 요청을 덮지 않는다.
 
 ## 배치
 
@@ -107,7 +108,7 @@ Native 이미지 프레임은 `imageRecipe.radius` 역할을 Provider의 `tokens
 - GridReveal의 `ready`는 `onLoadStatusChange`가 `loaded`일 때만 true, 오류·소스 변경·재시도 전에는 false로 돌린다.
   Native에서 화면이 가려진 채 mounted면 `active={false}`.
 - ImageViewer는 `open`으로 제어하고 닫히면 상태를 버린다. 라벨·`id`가 비거나 중복이면 `TypeError`.
-- ImageViewer는 불러오는 중(`loadingLabel`)과 실패(`errorLabel`)를 모두 알린다. 실패는 Android assertive live region, iOS는 `announceForAccessibility`다(미게시(1.12.1 이후). 1.12.1은 실패를 알리지 않았다).
+- ImageViewer는 불러오는 중(`loadingLabel`)과 실패(`errorLabel`)를 모두 알린다. 실패는 Android assertive live region, iOS는 `announceForAccessibility`다(1.13.0 변경. 1.12.1은 실패를 알리지 않았다).
 - 원격 이미지 권한·URL 수명·캐시는 제품 소유다. HJM은 메타데이터를 가져오지 않는다.
 
 ### Native ImageViewer의 제품 이미지 호스트
@@ -140,7 +141,7 @@ import { ImageViewer } from "@hjmds/react-native/image-viewer";
 회전을 허용하는 제품은 `supportedOrientations={["portrait", "landscape"]}`와 갱신되는
 safeAreaInsets 네 방향을 제공한다. 앱 manifest가 portrait 고정이면 이 prop만으로 회전이 보장되지 않는다.
 화면 크기가 바뀌면 버튼을 제외한 남은 갤러리 영역을 다시 측정해 host에 전달한다.
-아래 inspection 확장은 미게시이며, Expo 표시 확인·결과 승인 회귀와 Utilverse 채택은 별도 검증한다.
+아래 inspection 확장은 1.14.0 추가 API이며, Expo 표시 확인·결과 승인 회귀와 Utilverse 채택은 별도 검증한다.
 
 ### 결과 검사 크기 계산
 
@@ -157,7 +158,7 @@ const geometry = resolveImageInspectionGeometry(
 ); // width/height 804, panBounds x=201 y=175 (중앙에서 양방향)
 ```
 
-### Native 결과 검사 보기 (미게시)
+### Native 결과 검사 보기 (1.14.0 추가)
 
 `ImageViewer`의 선택적 `inspection`은 위 계산을 사용한다. 모든 `items`에 실제 출력의
 양수 `width`·`height`를 제공한다. 일반 Gallery의 pinch/paging과 별개로 고정 배율의 결과를

package/docs/usage/components/keyboard-dock.md

@@ -65,7 +65,7 @@ const keyboardOpen = useKeyboardState((state) => state.isVisible);
 | `enabled` | `true` · `false` | `true` | `false`면 따라 움직이지 않는다 |
 | `clearance` | 0 이상 숫자(layout point) | `0` | 키보드 위 추가 간격. 음수나 유한하지 않은 값은 `TypeError` |
 | `children` | ReactNode(필수) | — | 하단 행동. 안쪽 여백·안전 영역은 호스트가 준다 |
-| `style` | `StyleProp<ViewStyle>` | — | 감싸는 sticky view의 host 스타일. 플랫폼 host라 1.13 deprecated 대상이 아니다([이관 문서](../../migration-native-legacy-removal.md#113-deprecated-시각-style-제거는-다음-major)). 배치 값만 넣는다 |
+| `style` | `StyleProp<ViewStyle>` | — | 감싸는 sticky view의 host 스타일. 플랫폼 host라 1.13 deprecated 대상이 아니다([이관 문서](../../migration-native-legacy-removal.md#2026-10-13-잔여-시각-style-제거)). 배치 값만 넣는다 |
 
 - 이벤트·콜백 prop은 없다. 키보드 열림 여부가 필요하면 peer의 `useKeyboardState((state) => state.isVisible)`로 읽는다.
 - 내부에서 `KeyboardStickyView`에 `offset={{ closed: 0, opened: -clearance }}`를 넘긴다.

package/docs/usage/components/layout.md

@@ -113,5 +113,5 @@ Web (persistent sidebar)                         Native
 
 ## 함정
 
-- [계약 문서](../../layout.md)는 Native `skipLinkLabel`이 deprecated로 남아 있다고 적지만 1.12.1 Native `LayoutProps`에는 없다.
+- `skipLinkLabel`은 Web 전용이다. Native `LayoutProps`에는 없으므로 플랫폼 공통 props에 넣지 않는다.
 - Native persistent 사이드바는 옆으로 놓이지 않고 세로로 쌓인다. 넓은 화면 2단 배치가 필요하면 제품이 main 안에서 구성한다.

package/docs/usage/components/link.md

@@ -79,7 +79,7 @@ const renderGlyph = createLucideGlyph({ chevronEnd: ChevronRight }); // 제품
 | `renderIcon`(Native) | `(props: { name, size, color, strokeWidth }) => ReactNode` | — | semantic name → glyph 경계. 보통 `createLucideGlyph`. 크기·색은 HJM이 넘긴 값을 그대로 쓴다 |
 | `renderAnchor`(Web) | `(props: LinkRenderProps) => ReactElement` | — | 받은 props(`href`·`ref`·`className`·`data-*`·`aria-disabled`·`onClick`·`children`·병합된 `style`)를 framework Link에 그대로 넘긴다 |
 | `layoutStyle` | 배치 key만 | — | 양쪽 있음. Web은 `renderAnchor`에도 병합된 `style`로 전달된다 |
-| `style`(Native) | — | — | **deprecated**(1.13, 개발 모드 1회 경고, 다음 major 제거) — `layoutStyle`을 쓴다 |
+| `style`(Native) | — | — | 제거된 속성 — `layoutStyle`을 쓴다 |
 
 - Native는 tone·variant가 없다. 항상 brand 색 · 밑줄 · `bodyLarge` 글자 · 최소 터치 target이다.
 
@@ -118,6 +118,6 @@ const renderGlyph = createLucideGlyph({ chevronEnd: ChevronRight }); // 제품
 - Native에서 descriptor 아이콘을 주고 `renderIcon`을 빼면 개발 모드에서 한 번 경고하고 아이콘을 그리지 않는다(throw하지 않음).
   descriptor 아이콘과 `leading`/`trailing` node를 함께 주면 descriptor가 그 자리를 갖고 경고가 난다. 1.12까지는 Native가
   descriptor 아이콘을 그리지 않았다.
-- Native `style`은 deprecated다. 아직 recipe 뒤에 합쳐져 시각 값이 통과하므로 배치는 `layoutStyle`로만 준다.
+- Native `style`은 제거되었다. 배치는 `layoutStyle`로 지정하고 brand 색·밑줄·글자 크기는 `linkRecipe`를 따른다. Native에는 `tone`·`size` prop이 없다.
 - 현재 Native 스토리(`showcase/native/src/component-examples.tsx` LinkExample)는 descriptor 아이콘·`renderIcon` 예가 없고
   문구가 i18n 키가 아니다. 아이콘 경로는 위 최소 사용 예로 확인한다.

package/docs/usage/components/list-detail-screen.md

@@ -3,8 +3,8 @@
 - 단계: 컴포넌트
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 1.17.1
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
 - 스토리북: `배포/화면/콘텐츠/목록과 상세`
 
@@ -64,11 +64,11 @@ import { ListDetailScreen } from "@hjmds/react-native/screen-flows";
 | prop | 값 | 기본값 | 설명 |
 | --- | --- | --- | --- |
 | `list` | `ReactNode` | 필수 | 목록 pane 본문. 상세가 열려도 mount를 유지한다 |
-| `detail` | `{ title: string; content: ReactNode }` | 없음 | 있으면 상세 pane을 보이고 목록 pane을 숨긴다. 닫힌 상태는 prop을 빼서 표현한다(`undefined`를 넘기지 않는다) |
+| `detail` | `{ title; content; state?; stateAction?; notice? }` | 없음 | 있으면 상세 pane을 보이고 목록 pane을 숨긴다. 닫힌 상태는 prop을 빼서 표현한다(`undefined`를 넘기지 않는다) |
 | `back` | `ScreenFlowAction`(`{ label, onAction(), disabled?, pending? }`) | 필수 | 상세 pane `leading` 자리의 ghost 버튼 |
 | `refresh` | `ScreenFlowAction` | 없음 | 목록 pane `actions` 자리의 ghost 버튼. 주면 `actions`를 덮는다 |
 | `loadMore` | `ScreenFlowAction` | 없음 | 목록 pane footer의 ghost 버튼 |
-| `layoutStyle` | `HjmCompositionStyleProp` | 없음 | Web·Native 모두 목록·상세 pane을 함께 담는 **바깥 틀**에 적용한다(안쪽 목록 ScreenLayout이 아니다). 목록/상세 전환과 상관없이 같은 루트에 남는다. 미게시(1.12.1 이후) |
+| `layoutStyle` | `HjmCompositionStyleProp` | 없음 | Web·Native 모두 목록·상세 pane을 함께 담는 **바깥 틀**에 적용한다(안쪽 목록 ScreenLayout이 아니다). 목록/상세 전환과 상관없이 같은 루트에 남는다(1.13.0) |
 | 나머지 | `ScreenLayout`과 같음(`children`·`footer` 제외) | — | 목록 pane에만 적용된다(`title` 필수, `state`, `scroll` 등) |
 
 ## 배치
@@ -84,7 +84,7 @@ import { ListDetailScreen } from "@hjmds/react-native/screen-flows";
 ## 꼭 지킬 것
 
 - 라벨은 모두 i18n 키로 넣는다.
-- `state`(로딩·빈·오류·제한)는 목록 pane에만 적용된다. 상세의 로딩·오류는 `detail.content` 안에서 표시한다.
+- `state`(로딩·빈·오류·제한)는 목록 pane에만 적용된다. 상세 최초 조회·오류는 `detail.state`, 재시도는 `detail.stateAction`, 기존 상세를 유지하는 갱신 실패는 `detail.notice`로 전달한다. 미게시(1.18.0 이후)에 추가된 선택 prop이며 이전 설치 버전에서는 상세 content 안에 상태를 구성한다.
 - Web은 상세 진입 시 뒤로 버튼에 포커스를 옮기고 복귀 시 목록의 원래 요소로 돌린다. 요소가 삭제되었으면 목록 본문으로 이동한다.
   처음부터 `detail`이 있는 채로 mount되면(딥링크) 사용자 전환이 아니므로 포커스를 옮기지 않는다. 그때 포커스는 제품 router가 정한다.
 - 상세 열림 상태는 제품이 가진다. OS 뒤로가기·브라우저 뒤로가기와 `back`을 제품 router에서 함께 연결한다.
@@ -99,5 +99,5 @@ import { ListDetailScreen } from "@hjmds/react-native/screen-flows";
 ## 함정
 
 - `refresh`를 주면 ScreenLayout `actions`는 무시된다. 둘 다 필요하면 `refresh` 대신 `actions`에 직접 조합한다.
-- 상세 pane은 `title`과 `back`(leading)만 받는다. 상세 쪽 `description`·`actions`·footer 자리는 없다.
+- 상세 pane은 `title`·`state`·`stateAction`·`notice`와 `back`(leading)을 받는다. 상세 쪽 `description`·`actions`·footer 자리는 없다.
 - `loadMore`는 상태 없는 버튼이다. 끝·오류·중복 요청 방지가 필요하면 LoadMore를 쓴다.

package/docs/usage/components/list-row.md

@@ -54,6 +54,8 @@ import { Avatar, ListRow } from "@hjmds/react-native/data-display";
 <ListRow title={member.name} description={member.role}
   leading={<Avatar name={member.name} decorative />} leadingShape="circle"
   trailingText={t("member.joined", { date })} onPress={() => openMember(member.id)} />
+
+<ListRow title={t("account.delete")} tone="danger" onPress={openDeleteConfirmation} />
 ```
 
 ## 축과 기본값
@@ -62,15 +64,16 @@ import { Avatar, ListRow } from "@hjmds/react-native/data-display";
 | --- | --- | --- | --- |
 | `density` | `compact` · `comfortable` · `relaxed` · `spacious` | `comfortable` | 최소 높이는 설명 유무(한 줄·두 줄)와 함께 정해진다 |
 | `leadingShape` | `square` · `circle` | `square` | leading 프레임 크기는 recipe가 그린다 |
+| `tone` | `default` · `danger` | `default` | 탈퇴 같은 파괴적 목적지 제목은 `danger`로 강조한다. 선택·잠금·밀도와 독립적이다 |
 | `selected` | `true` · `false` | `false` | — |
 | `disabled` | `true` · `false` | `false` | — |
 | `href`(Web) | 문자열 | — | 있으면 `<a>` 행 |
 | `onClick`(Web) | `(event: MouseEvent<HTMLElement>) => void` | — | 있으면 `<button>` 행 |
 | `onPress`(Native) | `(event: GestureResponderEvent) => void` | — | 있으면 누를 수 있는 행 |
-| `loading`·`loadingLabel`(Web) | `boolean` · 현지화 문자열 | `false` · — | 같은 슬롯 모양의 자리표시 행. `loadingLabel`이 상태로 읽힌다 |
+| `loading`·`loadingLabel` | `boolean` · 현지화 문자열 | `false` · — | 같은 슬롯 모양의 자리표시 행. `loadingLabel`이 상태로 읽힌다 |
 | `trailingAction`(Native) | ReactNode | — | 행 명령 옆에 따로 그리는 별도 target(IconButton 등). 자기 `onPress`를 가진다 |
 | `layoutStyle` | 배치 key만 | — | 행 루트 배치. Native는 슬롯 배치용 `leadingStyle`·`contentStyle`·`titleRowStyle`·`trailingStyle`·`trailingActionStyle`(모두 배치 key만)도 받는다 |
-| `titleStyle`·`descriptionStyle`(Native) | — | — | **deprecated**(1.13, 개발 모드 1회 경고, 다음 major 제거) — `density`·`selected`, 글자는 listRowRecipe가 정한다 |
+| `titleStyle`·`descriptionStyle`(Native) | — | — | 제거된 속성 — 배치는 `layoutStyle`, 제목의 위험색은 `tone="danger"`, 글자는 listRowRecipe가 정한다 |
 
 - 상호작용: Web은 `href`면 `<a>`(selected는 `aria-current="page"`), `onClick`이면 `<button>`(selected는 `aria-pressed`),
   둘 다 없으면 `<div>`. Native는 `onPress`가 있으면 누를 수 있는 행이 된다.
@@ -116,7 +119,7 @@ Native 원형 leading의 `full`은 Provider token에서 읽지만 고정 원형
 | 항목 | Web | Native |
 | --- | --- | --- |
 | 제목·설명 타입 | `ReactNode` | `string` |
-| 자리표시 행 | `loading` + `loadingLabel` | — |
+| 자리표시 행 | `loading` + `loadingLabel` | `loading` + `loadingLabel` |
 | 링크 행 | `href` | 없음(`onPress`에서 router 호출) |
 | 제목 옆 메타·별도 뒤 행동·뒤 문구 | — | `titleMetadata`, `trailingAction`, `trailingText` |
 | 접근성 이름 조합 | 요소 내용 | `accessibilityLabel` 없으면 제목·`metadataLabel`·설명·`trailingLabel`을 이어 붙임 |
@@ -125,4 +128,10 @@ Native 원형 leading의 `full`은 Provider token에서 읽지만 고정 원형
 ## 함정
 
 - Web 로딩 행은 슬롯의 **존재**로 모양을 정하고 문구는 무시한다. 실제 행과 같은 슬롯을 넘겨야 높이가 맞는다.
-- Native `titleStyle`·`descriptionStyle`은 deprecated지만 아직 TextStyle 전체를 받아 색·굵기도 바뀐다. 새 코드에서 쓰지 않는다.
+- Native `titleStyle`·`descriptionStyle`은 제거되었다. 파괴적 목적지의 제목 강조에는 양 플랫폼 공통 `tone="danger"`를 사용한다. `tone`은 확인 절차나 삭제 실행을 대신하지 않는다.
+
+
+로딩 행은 실제 ListRow의 density·한 줄/두 줄 최소 높이와 padding을 그대로 사용한다. 두 줄 결과를
+예상하면 `description`을 제공한다(자리표시 중 문구 자체는 표시하지 않는다). loading 동안 행과
+trailingAction은 실행할 수 없으며 실제 슬롯 내용도 마운트하지 않는다. 여러 로딩 행 중 첫 행에만
+`loadingLabel`을 주고 나머지는 접근성 트리에서 숨긴다. 검색 화면도 임의 Skeleton 조립 대신 이 계약을 쓴다.

package/docs/usage/components/list.md

@@ -19,7 +19,7 @@
 | 화면 형태 | 쓸 것 |
 | --- | --- |
 | 수십 개 이하의 행을 한 번에 그림(설정, 계정 메뉴, 검색 결과 한 페이지) | `List` + `ListRow` |
-| 유한 카드 여러 장의 독립 입력/행동을 함께 보여주는 가로 탐색 | `CollectionRail` (미게시 실험, 아래 가로 배치 지침) |
+| 유한 카드 여러 장의 독립 입력/행동을 함께 보여주는 가로 탐색 | `CollectionRail` (1.16.0 추가·실험, 아래 가로 배치 지침) |
 | 행 한 줄의 제목·설명·앞뒤 슬롯 | [ListRow](list-row.md) |
 | 높이가 고정된 행 수백~수천 개를 창 안에서 스크롤 | [VirtualList](virtual-list.md) |
 | 이어지는 목록의 다음 페이지 요청 footer | [LoadMore](load-more.md) (List·VirtualList 아래에 둔다) |
@@ -42,6 +42,7 @@
 | --- | --- | --- | --- |
 | `List` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
 | `TaskList` | 확장 — 완료 체크 목록(optional) | `/task-list` | `/task-list` |
+| `CollectionRail` | 동반·대안 — 독립 행동을 가진 유한 가로 목록([구성 지침](../compositions/collection-detail.md)) | `/collection-rail` | `/collection-rail` |
 
 `TaskList`는 granular subpath로만 import 된다. 추가 peer는 없다. 순서 바꾸기를 합성하면 SortableCollection의 peer가 필요하다.
 
@@ -74,7 +75,7 @@ import { Text } from "@hjmds/react-native/primitives";
 | `label` | 현지화 문자열(필수) | — | 목록의 접근성 이름. 비면 `TypeError` |
 | `separator` | `indented` · `full` · `none` | `indented` | `indented`는 leading 슬롯 폭만큼 들여씀 |
 | `appearance` | `plain` · `grouped` | `plain` | `grouped`는 배경과 둥근 모서리로 한 덩어리 |
-| `layoutStyle` | 배치 key만 | — | 목록 루트 배치. Native `style`은 **deprecated**(1.13, 개발 모드 1회 경고, 다음 major 제거) — `layoutStyle`, 모양은 `appearance`·`separator` |
+| `layoutStyle` | 배치 key만 | — | 목록 루트 배치. Native `style`은 제거된 속성 — `layoutStyle`, 모양은 `appearance`·`separator` |
 | TaskList `items` | `readonly TaskItem[]` — `{ id, label, completed, description?, disabled? }` | — | `id`·`label`이 비거나 `id`가 중복되거나 `completed`가 boolean이 아니면 `TypeError` |
 | TaskList `onCompletedChange` | `(id: string, completed: boolean) => void` | — | 필수. 체크 하나마다 한 번. 목록 순서·저장은 제품이 정한다 |
 | TaskList `disabled` | `true` · `false` | `false` | 전체 체크박스를 끈다 |
@@ -110,7 +111,7 @@ Native `grouped` 프레임은 Provider의 `tokens.radius.lg`를 읽는다. plain
 
 ### CollectionRail 가로 배치
 
-새 `CollectionRail`은 미게시(1.15.0 이후) 실험 companion이다. 기존 List의 배포/호환 계약은 유지한다.
+새 `CollectionRail`은 1.16.0 추가 실험 companion이다. 기존 List의 배포/호환 계약은 유지한다.
 
 #### 언제 쓰나
 
@@ -196,7 +197,7 @@ import { CollectionRail } from "@hjmds/react/collection-rail";
 | --- | --- | --- |
 | 구조 | `role="list"` + 자식마다 `role="listitem"` | `accessibilityRole="list"` |
 | 구분선 | CSS(`data-separator`) | 행 사이 1px `View` |
-| 배치 | `layoutStyle`(+ `className`) | `layoutStyle`(`style`은 deprecated) |
+| 배치 | `layoutStyle`(+ `className`) | `layoutStyle`(`style`은 제거된 속성) |
 
 2026-10-07 Utilverse 항목 삭제 채택을 위해 `renderItemAction`을 추가했다. 체크와 삭제의 초점·누름을 분리하고 큰 글자 라벨 폭을 보존하도록 행동을 다음 줄에 둔다. `renderCollection`의 `renderItem`에도 포함된다. 삭제 저장·실패·되돌리기는 제품이 처리한다.