@hjmds/design-contracts 1.10.0 → 1.11.0

package/docs/rating.md

@@ -65,7 +65,7 @@
 
 ## 2026-09-16: React/RN 작동 조합
 
-명시 요청에 따라 `Patterns/Rating`에 정수/0.5점 입력과 읽기 전용 평균 표시를 추가했다.
+명시 요청에 따라 `컴포넌트/입력/Rating`에 정수/0.5점 입력과 읽기 전용 평균 표시를 추가했다.
 입력은 기존 Slider, 현재값과 평균 표시는 Statistic이며 별 모양 variant를 새로 만든 것은 아니다.
 
 - [Web 예제](../../../showcase/web/src/patterns/Rating.stories.tsx): `@hjmds/react/slider`,

package/docs/react-native-completion.md

@@ -113,9 +113,9 @@ Context 배선/정적 토큰 사용은 예제로 설명하며 BorderBeam은 모
   경로를 유지했다. Anchor는 문서·별도 스크롤 영역, section focus, reduced motion, fragment
   history와 동적 본문 관찰을 구현했다. Web 전용이며 Native wrapper를 추가하지 않았다.
   [Breadcrumb](./breadcrumb.md), [Pagination](./pagination.md), [Anchor](./anchor.md).
-- Patterns/WebNavigation은 125개 기록의 페이지별 목록 교체와 보관함 왕복을 제공한다.
+- 갤러리/웹 탐색은 125개 기록의 페이지별 목록 교체와 보관함 왕복을 제공한다.
   경로 변경 후 사라진 링크 대신 새 본문으로 focus를 옮기며 초기 mount에서는 focus를 뺏지 않는다.
-  Patterns/Anchor는 세 부분의 실제 읽기 가이드에서 목차·스크롤·focus를 연결한다.
+  컴포넌트/탐색/Anchor는 세 부분의 실제 읽기 가이드에서 목차·스크롤·focus를 연결한다.
 - 탐색 묶음 `pnpm ci:check` exit 0: contracts 733, Web SSR 139 + browser 140,
   Native 268 = 패키지 테스트 1,280개. Showcase Web 19 / Native 1과 타입·문서·evidence·
   번들·정적 Storybook(Web 71 / contract-only 23 / unsupported 0)이 통과했다.
@@ -131,7 +131,7 @@ Context 배선/정적 토큰 사용은 예제로 설명하며 BorderBeam은 모
   바깥 pointer/Tab이 향한 곳을 그대로 두고, 자식 popover가 감싸는 Dialog보다 Escape를 먼저 받는다.
   [API와 근거](./popover.md). ConfirmPopover는 새 renderer가 아니라 Popover의 확인/취소 조합으로
   제공하고 파괴적 동작은 AlertDialog에 남긴다. [조합 근거](./confirm-popover.md).
-- Patterns/Popover는 필터 적용과 되돌릴 수 있는 보관 두 화면을 제공한다. 보관하면 트리거가
+- 컴포넌트/오버레이/Popover는 필터 적용과 되돌릴 수 있는 보관 두 화면을 제공한다. 보관하면 트리거가
   사라지므로 제품이 초점을 보관 취소 버튼으로 옮기고, 초기 mount에서는 초점을 뺏지 않는다.
 - 묶음 종료 시 두 예산이 실측에서 걸려 근거와 함께 올렸다. contracts 루트 barrel은
   111.8 -> 112.3 kB gzip인데 모듈별로 재면 catalog.js +522 B(Popover·ConfirmPopover maturity
@@ -160,7 +160,7 @@ Context 배선/정적 토큰 사용은 예제로 설명하며 BorderBeam은 모
 - 브라우저(chromium) 검증 6개: 도킹·초점 가둠·스크롤 락과 flush 모서리, RTL `start` 미러링과
   wide 560px, 비모달의 살아 있는 페이지·내부 Escape만 dismiss, 사유별 단일 보고와 busy 중
   outside 차단, controlled owner의 busy 종료와 1회 완료, 320px·2배 글자에서 가로 넘침 없음.
-  `Patterns/SidePanel`은 기록 편집(모달)과 도움말(비모달) 두 화면을 제공한다.
+  `컴포넌트/오버레이/Side Panel`은 기록 편집(모달)과 도움말(비모달) 두 화면을 제공한다.
 - 예산은 실측으로 넷을 조정했다. `./side-panel` 45.9 kB raw / 11.0 kB gzip(6 modules),
   `./overlays`는 modal.js 분리로 6→7 modules(81.2/16.7 kB, 의존성 추가 아님),
   루트는 36→38 modules(322.3/66.3 kB, 바이트 한도 그대로), `./styles.css`는 도킹·크기·footer

package/docs/screen-chrome.md

@@ -43,7 +43,7 @@ LTR/RTL, light/dark에서 hit target, 글자 범위, overflow, 제목 분리와
 검증한다. ref/heading/link, busy 중 중복 실행 방지와 폭/focus 보존, sticky footer 위
 마지막 본문 행동의 도달 가능성도 검사한다. 기본 SSR renderer fixture를 추가한다.
 
-`Patterns/Notification settings`는 Web/RN에서 동일 문구·선택·저장 상태를 합성한다.
+`패턴/알림 설정`는 Web/RN에서 동일 문구·선택·저장 상태를 합성한다.
 행 제목과 스위치 문구가 중복되면 `labelVisibility="hidden"`을 사용한다. `label`은
 계속 필수이며 Web의 visually-hidden 텍스트와 Native의 accessibilityLabel로 남는다.
 Web List의 indented 구분선은 행 margin이 아닌 별도 선으로 그린다. 320px 조합에서

package/docs/scroll-progress.md

@@ -0,0 +1,29 @@
+# Scroll progress
+
+Reviewed: 2026-10-01. Both renderers expose `ScrollProgress` through `/scroll-progress`.
+This extension composes canonical Progress; it does not introduce another range,
+accessibility or drawing implementation. Use plain Progress for task completion.
+
+Pass `label`, `metrics: {offset, contentSize, viewportSize}` and normal Progress
+presentation options. Metrics are logical forward distances in one consistent unit.
+The shared resolver clamps bounce/overscroll into 0–1. An unmeasured viewport returns
+0; content fitting a measured viewport returns 1. Negative sizes and nonfinite
+numbers throw. Horizontal RTL hosts must normalize platform-specific offsets.
+
+On Web use `const metrics = useScrollMetrics(host)` with the actual vertical
+scrolling HTMLElement stored by a callback ref. No implicit window listener is
+installed. Scroll events are batched per animation frame; ResizeObserver and DOM
+changes update the content extent. The hook disconnects when the host changes.
+
+On Native feed `onScroll` contentOffset.y, `onContentSizeChange` height, and
+`onLayout` viewport height from the product's ScrollView. Keep the product's
+existing callbacks and gesture handling. The renderer adds no scroll responder.
+Both showcases contain `컴포넌트/피드백/Scroll Progress` with working scroll
+content. Updates are continuous range values, not repeated live announcements.
+
+Regression checks cover overscroll, unknown/fitting dimensions, actual browser
+scroll/content resize and Native canonical Progress values. The [Native integration audit](../../../docs/evidence/native-visual-integration-2026-10-01/README.md)
+records Default/Dark/LargeText initial-view captures on the existing iPhone 17 / iOS 27
+simulator. The subsequent [component flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md)
+verifies real LargeText swipes from 0% to 100% and back to 87%, with captures and
+accessibility snapshots. VoiceOver speech and physical-device performance remain unverified.

package/docs/sheet.md

@@ -61,3 +61,5 @@ focus/dismiss와 텍스트 배치 회귀를 직접 확인하도록 위 테스트
 
 참조: [React Native Keyboard](https://reactnative.dev/docs/keyboard),
 [ScrollView](https://reactnative.dev/docs/scrollview).
+
+Native accessibility follow-up (2026-10-01): at 200% text scale, the close glyph was clipped inside the fixed IconButton frame. Dialog and Sheet now render that decorative glyph at a fixed icon size, matching Toast; title/body text still scales and the named close action and touch target are preserved. `sheet-viewport.test.tsx` checks both renderers and close callbacks.

package/docs/sidebar.md

@@ -31,3 +31,9 @@
 
 **Web 전용.** 폰은 BottomNavigation을 쓰고, 네이티브 태블릿의 split view는 navigator의
 문제다.
+
+## 선택형 Web 표현 — 2026-10-01
+
+`appearance`는 standard(기본), bounce, hook, proximity를 지원한다. bounce는 새로 선택한 항목의 아이콘에 한 번만 적용하고, hook은 선택 항목의 시작 쪽 곡선 경계를 강조한다. proximity는 마우스/펜의 세로 거리에 따라 아이콘만 최대 18% 확대한다. 링크 경계와 키보드 순서는 변하지 않는다. 터치는 근접 효과를 만들지 않는다. HJM provider의 모션 줄이기에서 동적 표현을 끄며, provider 없이도 기본 정적 탐색은 가능하다.
+
+독립적으로 구현한 제한된 표현이다. 원본 사이트의 모션 엔진을 복제하지 않았다. Web 전용이라는 기존 지원 범위를 유지하며 Native에서 새 사이드바를 만들지 않는다. Storybook `컴포넌트/탐색/Sidebar Motion`의 Default/Dark/LargeText에서 네 가지 표현과 접기를 비교한다. 기존 앱 셸 예제는 컴포넌트/탐색/Sidebar에 남는다.

package/docs/splitter.md

@@ -69,7 +69,7 @@ Native `unsupported`다. 제품 채택과 실제 보조기기 실측은 승격
   인자 평가까지 통째로 건너뛰어 키보드 조절이 조용히 죽는다. commit을 먼저 하고 알린다.
 - 로컬 검증: `test/splitter.browser.test.tsx` 6개(separator 의미·수직 방향과 44px hit
   target, 방향키 step과 Home/End 경계, 드래그 스냅과 드래그당 1회 end, RTL 드래그·키보드,
-  disabled, 실제 Tab focus와 focused keyboard resize)와 `Patterns/Splitter`.
+  disabled, 실제 Tab focus와 focused keyboard resize)와 `컴포넌트/레이아웃/Splitter`.
 
 **검증 범위.** Web Chromium renderer matrix가 긴 pane 콘텐츠·환경·접근성 증거를 제공한다.
 제품 vertical slice, screen reader 실측, 모든 OS 조합은 보증하지 않으며 소비 앱 릴리스 QA에서 확인한다.

package/docs/step-player.md

@@ -0,0 +1,16 @@
+# StepPlayer
+
+검토일: 2026-10-01.
+
+`@hjmds/react/step-player`, `@hjmds/react-native/step-player`는 기존 Steps, Progress, Button을 합성한다. 별도 단계 상태 머신이나 재생 엔진을 두지 않는다. 사용자가 요청한 단계형 소개와 미디어는 서로 다른 시계를 사용하므로 호스트가 현재 위치와 재생 상태를 소유한다.
+
+- `descriptor`, `statusLabels`, `composeAccessibleName`: 기존 Steps 계약 그대로.
+- `progress`: 전체 재생 진행률 0~1. `playing`: 실제 호스트 재생 여부.
+- `onPlayingChange`: 재생/일시정지 요청. 콜백 호출 자체로 내부 상태를 바꾸지 않는다.
+- `onReplay`: 호스트가 현재 단계와 진행률을 초기화하고 재생 정책을 결정한다.
+- `labels`: 번역된 play/pause/replay/progress 문구. `disabled`는 두 동작을 비활성화한다.
+- `children`: 현재 단계의 실제 콘텐츠. 모션은 기존 ContentTransition 등으로 합성한다.
+
+완료 시 마지막 단계와 progress=1을 전달하고 재생 여부를 false로 바꾼다. 실제 비동기 작업의 완료를 타이머로 추정하는 용도가 아니다. 재생 종료/탐색 이탈/백그라운드 정지는 호스트 책임이다. 모션 줄이기는 콘텐츠 전환을 줄이며 사용자가 요청한 재생 자체를 막지 않는다.
+
+양쪽 Storybook `컴포넌트/피드백/Step Player`에 Default/Dark/LargeText를 제공한다. 예제만 사용자가 시작하는 6초 소개 시계를 가지며, 브라우저 숨김 또는 Native AppState 비활성에서 정지한다. 실제 서비스의 작업 진행이나 저장 완료를 주장하지 않는다.

package/docs/task-list.md

@@ -0,0 +1,32 @@
+# Task list
+
+Reviewed: 2026-10-01. Web and Native expose TaskList through `/task-list`.
+TaskList composes existing List and Checkbox rather than creating another selection
+or gesture engine. Each controlled item has unique `id`, localized `label`, boolean
+`completed`, optional `description` and `disabled`. Invalid identity/completion data
+throws. Pass a localized list `label` and `onCompletedChange(id, completed)`; the
+product accepts the requested change and owns saving, errors and rollback.
+
+`emptyContent` is product-localized content when there are no tasks. `disabled`
+disables every checkbox. Checking a task never reorders or removes it automatically.
+
+For reordering, supply `renderCollection({items, renderItem})` and compose the
+existing optional SortableCollection. Pass its localized labels and accept its
+`orderedIds` in product state. Map its SortableItem back to the TaskItem by ID before
+calling `renderItem`. The host propagates any global disabled/active state to that
+collection; TaskList continues to control checkbox disabled state. This slot keeps
+DND peers out of the plain TaskList import graph, while the existing adapter owns
+keyboard/drag/cancellation/accessibility behavior.
+
+Both showcases register 컴포넌트/입력/Task List with Default, Dark and LargeText
+and working controlled completion/reordering. Web tests exercise actual checkbox
+interaction; Native tests check controlled intent and disabled props. Device drag,
+focus and screen-reader verification remain pending.
+
+## Native enlarged selection marks
+
+The 2026-10-01 [device flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md)
+found that 200% text scaling enlarged Checkbox's decorative mark beyond its fixed box.
+Native Checkbox now keeps the checked/mixed artwork at the recipe typography size
+while its label and description continue scaling. TaskList inherits this correction
+through Checkbox; it does not provide a second selection indicator.

package/docs/theme-studio.md

@@ -0,0 +1,13 @@
+# Theme studio
+
+검토일: 2026-10-01.
+
+`@hjmds/design-contracts/theme-studio`는 기존 provider의 brandPalette와 색 대비 계산을 재사용하는 작업 도구다. 새로운 테마 엔진이나 자동 색상 생성기는 아니다.
+
+- `applyStudioColor`는 light/dark별 primary, onPrimary, contentBrand 역할에 여섯 자리 HEX를 적용하며 기존 입력 객체를 변경하지 않는다.
+- `studioReport`는 HJM 기본 팔레트에 override를 합친 뒤 기존 paletteContrastRules의 각 색상 쌍에 정확한 ratio·minimum·pass를 반환한다. 표시할 때만 소수점을 줄이고 통과 판정은 원래 값으로 한다.
+- `exportStudioPalette`는 실제 설정을 `{brandPalette: ...}` JSON으로 직렬화한다. 소비 제품 기본값이나 중앙 토큰을 수정하지 않는다.
+
+Web/Native Storybook `디자인 기초/테마 편집`에서 Default/Dark/LargeText 예제를 제공한다. 양쪽 테마를 동시에 비교하고 버튼·입력·disabled·오류, Lucide 의미 아이콘, 안내·성공·주의 알림을 확인할 수 있다. 기록 데이터는 Web DataTable, Native List로 비교한다. Native에 없는 DataTable을 새로 흉내 내지 않고 기존 읽기 순서와 의미를 유지한다. Web은 JSON 파일 다운로드, Native는 OS 공유와 선택 가능한 코드 표시를 제공한다. 공개 API에는 번역 문구를 넣지 않으며 라벨과 오류 안내는 showcase가 소유한다.
+
+색상 쌍 통과는 전체 접근성 인증이 아니다. 웹 버튼의 hover/focus는 실제 상호작용으로 확인하며, 실제 제품 배경과 보조기기 사용성은 별도 확인해야 한다. 서체 비교·라이선스 입력은 별도 후속 구현이다.

package/docs/thinking-orb.md

@@ -1,6 +1,6 @@
 # ThinkingOrb — AI 작업 상태
 
-검토일: 2026-09-29. 원본: [Thinking Orbs](https://github.com/Jakubantalik/thinking-orbs/tree/de85557ca220332586d070d8788c0e1d6e877a0d), MIT.
+검토일: 2026-10-01. 원본: [Thinking Orbs](https://github.com/Jakubantalik/thinking-orbs/tree/de85557ca220332586d070d8788c0e1d6e877a0d), MIT.
 
 ## 결정과 범위
 
@@ -22,6 +22,7 @@
 
 - `state`: working, searching, solving, listening, connecting, weaving, composing, breathing, shaping.
   실제 상태를 앱에서 전달한다. listening은 음성 크기에 반응하는 오디오 시각화가 아니다.
+- `appearance`: 기본 `state`는 상태별 원본 기하를 유지한다. `fluid`는 물결치는 점 고리, `matrix`는 원형 점 격자로 독립 구현한 표현이다. 실제 진행률이나 음성 신호를 나타내지 않으며 기존 정지·가시성·모션 줄이기 규칙을 공유한다.
 - `size`: 20 또는 64. 원본의 점 수·반지름 튜닝을 유지하며 임의 CSS 확대는 지원하지 않는다.
 - `label`: 필수. 앱에서 번역한 현재 작업 설명. 완료·오류 때는 별도 결과 UI로 교체한다.
 - `speed`: 기본 1, 유한수 0 초과 4 이하. 무제한 속도는 읽기 어려운 모션을 만들므로 제한한다.
@@ -30,7 +31,7 @@
   AppState만으로는 여전히 mounted인 숨긴 화면을 알아낼 수 없기 때문이다.
 
 HJM provider의 `text` 색을 깊이에 따른 opacity와 조합한다. 원본의 고정 grayscale 팔레트는
-브랜드 테마와 배경에서 어긋날 수 있어 사용하지 않는다. 기하 좌표는 원본과 동일하다.
+브랜드 테마와 배경에서 어긋날 수 있어 사용하지 않는다. `appearance="state"`의 기하 좌표는 원본과 동일하다.
 모션 줄이기에서는 elapsed 0.6초 프레임만 그린다. 긴 JS 정체 후 이동은 최대 64ms로 제한해
 순간적인 모션 점프를 줄인다. 상태 전환은 새 모양으로 즉시 바뀌며 morph 전환은 제공하지 않는다.
 웹은 role=status와 숨긴 텍스트, Native는 접근 가능한 progressbar host를 사용한다.
@@ -122,3 +123,9 @@ Storybook registry 누락을 수정해 해당 검사를 다시 통과했다. Evi
 workspace/evidence/docs/governance, 양쪽 showcase 검사, Web Storybook build 및
 112 canonical story inventory, 중앙 library-policy 정적 검사, `git diff --check` 통과.
 게시·소비 앱 갱신은 실행하지 않았다.
+
+## Storybook 탐색
+
+Web/Native 모두 `컴포넌트/피드백/ThinkingOrb`에서 Default, Dark, LargeText를 제공한다.
+Fluid와 Matrix는 같은 컴포넌트의 표현 예제이며 새 상태 엔진이나 진행률 계약을 추가하지 않는다.
+2026-10-01 추가 표현의 Native 실제 화면 확인은 아직 미완료다.

package/docs/time-picker.md

@@ -95,7 +95,7 @@ catalog의 `{ name: "TimePicker", category: "input", platform: "adaptive", statu
 
 ## 2026-09-16: React/RN 작동 조합
 
-명시 요청에 따라 위 합성 경로를 양쪽 Showcase의 `Patterns/Time selection`에 구현했다.
+명시 요청에 따라 위 합성 경로를 양쪽 Showcase의 `패턴/시간 선택`에 구현했다.
 시 00–23와 분 00–59의 독립 Select, 두 값이 있어야 가능한 확정, 초기화, 변경 시 확정 결과 해제를
 포함한다. 새 TimePicker renderer를 선언하지 않고 기존 공개 `Select`를 그대로 조합한다.
 

package/docs/toast.md

@@ -10,8 +10,7 @@ Toast는 사용자가 응답해야만 진행되는 modal UI가 아니라, 무시
 필수 선택·삭제 확인·시간 안에 응답해야 하는 작업은 `AlertDialog`를 사용합니다.
 
 HJM은 Radix Primitives에서 provider/viewport anatomy, visible timer pause, focus·Escape·swipe
-수명주기를 참고하고 React Aria/Spectrum에서 bounded queue, stable id close handle, 5초 최소
-timeout과 actionable persistent 기본값을 참고했습니다. 외부 component나 prop 이름은 공개하지
+수명주기를 참고하고 React Aria/Spectrum에서 bounded queue, stable id close handle과 actionable persistent 기본값을 참고했습니다. 외부 component나 prop 이름은 공개하지
 않고 다음 세 계층으로 번역했습니다.
 
 ```text
@@ -44,7 +43,9 @@ const result = store.publish({
   `announcement`를 제공합니다.
 - action은 무시해도 안전해야 합니다. label 자체로 동작이 명확하지 않으면
   `accessibilityLabel`에 완전한 이름을 제공합니다.
-- action이 있는 Toast는 기본 persistent입니다. 제품이 명시한 `durationMs`도 5000ms보다
+- 기본 알림과 리퀴드 알림은 모두 표시 후 3초에 자동 닫힘을 시작합니다. 리퀴드는 진입 연출 동안 타이머를 멈춥니다.
+  2026-10-02 사용자 요청으로 기존 5초 기본값·최솟값을 3초로 변경했습니다.
+- action이 있는 Toast는 기본 persistent입니다. 제품이 명시한 `durationMs`도 3000ms보다
   짧아질 수 없으며, `null`은 명시적 persistent입니다.
 
 `publish` 결과에는 stable id와 `visible | queued` 위치가 포함됩니다. 호출자는 반환된 함수
@@ -74,9 +75,9 @@ duration을 갖습니다. `closing` id는 exit가 끝날 때까지 새 publish
 자기 monotonic clock으로 `advanceTime(elapsedMs)`를 호출합니다.
 
 ```text
-queued(waiting, 5000) ─ show ─→ visible(running, 5000)
+queued(waiting, 3000) ─ show ─→ visible(running, 3000)
                                   ├─ pointer/focus/window/gesture → paused
-                                  └─ elapsed=5000 → closing(timeout)
+                                  └─ elapsed=3000 → closing(timeout)
                                                         └─ exit complete → closed
 ```
 
@@ -113,7 +114,7 @@ so a window-width breakpoint left doubled text and action labels compressed
 even in a wide window. A 1280px window/420px card regression covers that case.
 
 Proof: `packages/react/test/toast-layout.browser.test.tsx`; review fixture:
-Storybook `Patterns/Toast layout`. The fixture covers long Korean/English copy,
+Storybook `패턴/토스트 배치`. The fixture covers long Korean/English copy,
 doubled text, dark theme and RTL. Automated browser checks are separate from
 real assistive-technology and consumer-release evidence; Toast remains beta.
 
@@ -132,7 +133,7 @@ Toast의 `●` 글리프가 뜻 없는 회색 점으로 보였고, 글자 글리
 - 여러 줄·큰 글자에서도 badge는 제목 옆 위쪽에 붙고, 한국어는 `word-break: keep-all`로 단어 중간에서
   끊지 않습니다(Web).
 
-Review fixture: Storybook `Patterns/Toast layout` → `Tone gallery`(light/dark).
+Review fixture: Storybook `패턴/토스트 배치` → `Tone gallery`(light/dark).
 
 Web renderer:
 

package/docs/tour.md

@@ -154,7 +154,7 @@ renderer이며 Native는 계속 `unsupported`다. Web renderer 증거는 stable
   다음 단계에 맞춘 anchor 하이라이트, 배경 inert와 바깥 pointer 무시, 첫 단계 이전은
   no-op·마지막 다음은 complete, Escape·건너뛰기 탈출, unmount의 1회 interrupted,
   controlled owner 종료와 320px 배치, 긴 번역 copy 내부 스크롤·키보드 건너뛰기·호출자
-  focus 복귀)와 `Patterns/Tour`.
+  focus 복귀)와 `컴포넌트/오버레이/Tour`.
 
 ## 검증 화면
 

package/docs/tree-select.md

@@ -114,12 +114,12 @@ antd `TreeSelect`의 `checkStrictly`(부모/자식을 독립적으로 체크할
 - 표면: `@hjmds/react/popover`의 `Popover`(트리거 + 팝업 + 확정 버튼)
 - collection: `@hjmds/react/tree`의 `Tree`(깊이 발표·화살표·확장)
 - 집계: 이 모듈의 `resolveTreeCheckedStates`/`toggleTreeCheckedSelection`
-- 예제: Showcase `Patterns/Tree`의 TreeSelect 화면
+- 예제: Showcase `컴포넌트/데이터 표시/Tree`의 TreeSelect 화면
 
 **Cascader도 같은 자리에서 끝난다.** catalog는 Cascader를 "TreeSelect에 path value와
 중간 단계 commit 축이 필요하다"는 prerequisite로 묶어 뒀는데, Tree renderer의 resolve
 결과가 이미 `parentId` 사슬을 들고 있어 경로는 파생이고, 중간 단계 확정은 그 노드를 그대로
 고르는 것이다. 새 축을 계약에 추가할 이유가 없어 prerequisite를 풀고 `composed`로 옮겼다
-(`Patterns/Tree`의 Cascader 화면). antd의 열(column) 방식 화면은 베끼지 않는다 — HJM의
+(`컴포넌트/데이터 표시/Tree`의 Cascader 화면). antd의 열(column) 방식 화면은 베끼지 않는다 — HJM의
 계층 탐색 어휘를 그대로 쓰는 쪽이 같은 문제를 이미 푼다.
 

package/docs/voice-note.md

@@ -0,0 +1,19 @@
+# VoiceNote
+
+검토일: 2026-10-01.
+
+Web `@hjmds/react/voice-note`, Native `@hjmds/react-native/voice-note`.
+공통 `@hjmds/design-contracts/voice-note`의 descriptor는 제목, 실제 재생 상태, 초 단위 위치·길이를 받는다.
+
+기존 Asset의 장식 이미지 슬롯, Slider의 키보드/접근성 조정, Button의 비활성/로딩 상태를 합성한다. 독립 오디오 엔진을 추가하지 않는다. 녹음 권한, 파일 다운로드, 오디오 세션, 재생 종료와 백그라운드 처리는 제품 플레이어의 책임이다.
+
+- 상태는 paused/playing/loading/error. duration=null은 메타데이터 미확인, 0은 확인된 빈 녹음이다. 두 경우 탐색·재생을 막는다.
+- position은 실제 플레이어 위치이며 duration을 넘어가면 끝으로 제한한다. 음수·무한수는 거절한다.
+- onPlayingChange는 재생/정지 요청, onSeek는 Slider 변경 요청이다. 제품은 요청을 실제 엔진에 적용하고 새 descriptor를 전달한다. 내부 타이머로 재생을 꾸미지 않는다.
+- 오류 시 labels.error와 선택형 onRetry를 제공한다. 로딩·오류·disabled에서 재생과 탐색을 막는다.
+- labels와 formatTime은 제품 번역을 받는다. Native의 이전/다음 접근성 동작 문구도 labels에 포함된다.
+- artwork는 제목 옆 장식용 슬롯이다. 실제 파일 정보나 필수 텍스트를 이 슬롯에만 두지 않는다.
+
+양쪽 Storybook 컴포넌트/데이터 표시/Voice Note에 Default/Dark/LargeText와 로딩·오류 전환 버튼이 있다. 스토리는 상태 조작 예제라고 명시하며 실제 소리를 재생하지 않는다. 패키지 검사는 플레이어 연결 계약을 검증하며 실제 오디오·권한·OS 백그라운드 지원의 증거가 아니다.
+
+[Native 후속 검증](../../../docs/evidence/component-flows-2026-10-01/README.md)에서 iPhone 17 / iOS 27 시뮬레이터의 큰 글씨 재생·정지 상태 전환, 로딩 중 비활성, 오류 후 재시도를 실제 조작했다. 캡처는 UI 상태 연결을 증명하며 실제 음성 재생 검증은 아니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -570,6 +570,96 @@
       "react-native": "./dist/interaction-adapters.js",
       "import": "./dist/interaction-adapters.js",
       "default": "./dist/interaction-adapters.js"
+    },
+    "./avatar-fallback": {
+      "types": "./dist/avatar-fallback.d.ts",
+      "react-native": "./dist/avatar-fallback.js",
+      "import": "./dist/avatar-fallback.js",
+      "default": "./dist/avatar-fallback.js"
+    },
+    "./effect-surface": {
+      "types": "./dist/effect-surface.d.ts",
+      "react-native": "./dist/effect-surface.js",
+      "import": "./dist/effect-surface.js",
+      "default": "./dist/effect-surface.js"
+    },
+    "./content-transition": {
+      "types": "./dist/content-transition.d.ts",
+      "react-native": "./dist/content-transition.js",
+      "import": "./dist/content-transition.js",
+      "default": "./dist/content-transition.js"
+    },
+    "./duration-field": {
+      "types": "./dist/duration-field.d.ts",
+      "react-native": "./dist/duration-field.js",
+      "import": "./dist/duration-field.js",
+      "default": "./dist/duration-field.js"
+    },
+    "./reactions": {
+      "types": "./dist/reactions.d.ts",
+      "react-native": "./dist/reactions.js",
+      "import": "./dist/reactions.js",
+      "default": "./dist/reactions.js"
+    },
+    "./scroll-progress": {
+      "types": "./dist/scroll-progress.d.ts",
+      "react-native": "./dist/scroll-progress.js",
+      "import": "./dist/scroll-progress.js",
+      "default": "./dist/scroll-progress.js"
+    },
+    "./code-block": {
+      "types": "./dist/code-block.d.ts",
+      "react-native": "./dist/code-block.js",
+      "import": "./dist/code-block.js",
+      "default": "./dist/code-block.js"
+    },
+    "./activity-heatmap": {
+      "types": "./dist/activity-heatmap.d.ts",
+      "react-native": "./dist/activity-heatmap.js",
+      "import": "./dist/activity-heatmap.js",
+      "default": "./dist/activity-heatmap.js"
+    },
+    "./task-list": {
+      "types": "./dist/task-list.d.ts",
+      "react-native": "./dist/task-list.js",
+      "import": "./dist/task-list.js",
+      "default": "./dist/task-list.js"
+    },
+    "./voice-note": {
+      "types": "./dist/voice-note.d.ts",
+      "react-native": "./dist/voice-note.js",
+      "import": "./dist/voice-note.js",
+      "default": "./dist/voice-note.js"
+    },
+    "./theme-studio": {
+      "types": "./dist/theme-studio.d.ts",
+      "react-native": "./dist/theme-studio.js",
+      "import": "./dist/theme-studio.js",
+      "default": "./dist/theme-studio.js"
+    },
+    "./grid-reveal": {
+      "types": "./dist/grid-reveal.d.ts",
+      "react-native": "./dist/grid-reveal.js",
+      "import": "./dist/grid-reveal.js",
+      "default": "./dist/grid-reveal.js"
+    },
+    "./gravity-letters": {
+      "types": "./dist/gravity-letters.d.ts",
+      "react-native": "./dist/gravity-letters.js",
+      "import": "./dist/gravity-letters.js",
+      "default": "./dist/gravity-letters.js"
+    },
+    "./gooey-navigation": {
+      "types": "./dist/gooey-navigation.d.ts",
+      "react-native": "./dist/gooey-navigation.js",
+      "import": "./dist/gooey-navigation.js",
+      "default": "./dist/gooey-navigation.js"
+    },
+    "./action-session": {
+      "types": "./dist/action-session.d.ts",
+      "react-native": "./dist/action-session.js",
+      "import": "./dist/action-session.js",
+      "default": "./dist/action-session.js"
     }
   },
   "files": [