@hjmds/design-contracts 1.10.0 → 1.12.0

package/docs/avatar-fallback.md

@@ -0,0 +1,74 @@
+# Avatar fallback and Blobatar
+
+Reviewed: 2026-10-01. Implemented locally; package publication and consumer adoption are separate.
+
+`Avatar` remains the sole canonical component. Both renderers accept
+`renderFallback({ size, decorative: true })`. The factory is called only while a
+photo is absent or has failed. Returning null/undefined preserves the existing
+Web `fallback` or Native initials. Existing consumers are unchanged.
+
+The Avatar owns the accessible name; custom fallback content is decorative and
+must not contain interactive controls. Native hides fallback descendants from
+accessibility. Photo source changes retry loading rather than retaining an old
+failure. Web continues forwarding the image error callback.
+
+## Optional adapter
+
+Import `createBlobatarFallback` from `@hjmds/react/avatar-blobatar` or
+`@hjmds/react-native/avatar-blobatar`. Neither root imports the adapter.
+Install `blobatar@2.7.0` and the matching `@blobatar/react@2.7.0` or
+`@blobatar/react-native@2.7.0`; Native additionally uses the existing supported
+`react-native-svg` peer. The static entry needs no Reanimated or Worklets import.
+
+```tsx
+const renderFallback = useMemo(
+  () => createBlobatarFallback({ seed: account.publicAvatarId, expression: 'idle' }),
+  [account.publicAvatarId],
+);
+// Web: <Avatar name={displayName} src={photo} renderFallback={renderFallback} />
+// Native: <Avatar name={displayName} source={photo} accessibilityLabel={displayName}
+//                 renderFallback={renderFallback} />
+```
+
+Only `idle` and `happy` static expressions are currently exposed. There is no
+`motion` option in this first implementation. Use the same public product seed on
+both platforms; names, emails, credentials and inferred emotions are not seeds.
+Normalization is explicitly disabled to preserve case-sensitive account identity.
+Generation is local (Web data URI, Native SVG paths). No avatar server is called.
+Pinned upstream versions prevent an incidental generator upgrade from changing
+existing faces. React adapters retain upstream generation rather than approximating
+its artwork with a second generator. MIT notices remain in the upstream packages.
+
+`패턴/프로필 편집` in both showcases demonstrates choosing a face,
+editing a display name, toggling notifications, applying and reverting local
+changes. Copy is keyed in the shared showcase fixture; it is not embedded in the
+renderer. This is a composition example, not an account API or new canonical screen.
+The original [integration plan](../../../docs/plans/visual-and-motion-integration-2026-10-01.md)
+tracks later animation, theme and marketing work.
+
+## Optional motion and expressions (2026-10-01)
+
+`/avatar-blobatar-motion` on each renderer exports `createAnimatedBlobatarFallback`.
+It accepts a stable public `seed`, `expression` (idle, happy, sad, surprised, wink,
+sleepy or thinking), `active` (default false), and `visible` (default true). Pass its
+result into the existing Avatar `renderFallback`. Avatar still owns naming and image
+fallback; the animated artwork remains decorative.
+
+The Web entry imports Blobatar's motion stylesheet and observes intersection/document
+visibility. Native uses the upstream optional AnimatedBlobatar entry, requiring the
+host's compatible Reanimated/Worklets, and observes AppState. Native hosts must pass
+route/list visibility explicitly. Native switches to the static upstream renderer when
+inactive, hidden, reduced or backgrounded: upstream 2.7.0 keeps its frame callback
+running with `animate=false`, as confirmed by device-host CPU sampling. Seed and
+expression are preserved, while the idle clock restarts when re-enabled.
+Both honor HJM reduced motion and never enable
+idle animation without `active`. Static `/avatar-blobatar` remains available without
+motion imports. The pinned Blobatar 2.7.0 generation and original license remain.
+
+컴포넌트/데이터 표시/Animated Blobatar provides Default, Dark and LargeText in both
+showcases, with explicit pose and motion controls. Native gating tests mock the
+upstream rendering boundary; the subsequent [Native integration audit](../../../docs/evidence/native-visual-integration-2026-10-01/README.md)
+adds installed iPhone 17 / iOS 27 simulator captures and active/stopped CPU samples
+from the real upstream runtime. The inactive frame-loop correction is backed by
+those samples. This does not establish physical-device GPU timing, battery use,
+or exhaustive geometry and screen-reader behavior.

package/docs/bottom-navigation.md

@@ -35,7 +35,7 @@ const descriptor = {
 
 시각·플랫폼 선택은 별도 `BottomNavigationConfiguration`으로 전달합니다.
 
-- `presentation`: `bar | floating`
+- `presentation`: `bar | floating | capsule`
 - `distribution`: `equal | center-gap`
 - `density`: `compact | regular`
 - `direction`: `ltr | rtl`
@@ -126,3 +126,18 @@ distribution을 선택하고 outer Dock frame에서 기존 Button/IconButton 기
 합성합니다. 이 action은 tab role, selected state, badge, `selectedKey`, destination count를
 가질 수 없습니다. Web은 button, RN은 button role과 activate action을 사용하며 제품 router나
 modal API를 직접 호출합니다.
+
+## Capsule presentation (2026-10-01)
+
+`configuration={{ presentation: "capsule" }}`는 둥근 route 표면과 선택된 항목의 가로형
+icon/label을 제공합니다. `primaryAction`은 컬렉션 밖의 별도 원형 행동으로 배치됩니다.
+`center-gap`과 함께 지정하면 오류입니다. 생성 행동이 route로 오인되거나 중앙에서 이름을
+가리는 것을 방지하기 위한 선택입니다.
+
+기본 크기에서 비선택 항목의 시각 label은 접히지만 전체 접근성 이름/배지/route intent는
+그대로 유지됩니다. 큰 글씨(1.5 이상) 또는 5–6개 목적지는 모든 이름을 세로 배치해 표시합니다.
+기존 bar/floating 및 router 소유 selectedKey는 바뀌지 않습니다.
+[사용자 레퍼런스 두 번째 이미지](https://www.instagram.com/p/Ddb8lXmjnV9/?img_index=2)의
+선택 캡슐과 분리된 추가 행동을 참고했으며, 원본 소스는 복제하지 않았습니다.
+
+Storybook: **컴포넌트 → 탐색 → 캡슐 네비게이션**, Default/Dark/LargeText.

package/docs/breadcrumb.md

@@ -74,7 +74,7 @@ Web에서는:
 경로도 유지합니다. 필수 props는 `label`, `items`이고 `ref`는 nav 요소를 가리킵니다.
 
 2026-09-16 사용자의 React/RN 라이브러리 확장 요청으로, 제품 채택 대기와 라이브러리 beta
-제공을 분리했습니다. `Patterns/WebNavigation`은 조상 링크로 보관함을 열고 다시 기록 목록으로
+제공을 분리했습니다. `갤러리/웹 탐색`은 조상 링크로 보관함을 열고 다시 기록 목록으로
 돌아오는 작동 예제입니다. 제품 채택이나 stable 증거로 계산하지 않습니다.
 
 [WAI Breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)의 landmark·조상 링크·

package/docs/calendar.md

@@ -15,7 +15,7 @@
 
 과거 Yajalal 조사에서는 월 격자가 날짜 레일로 바뀌어 살아 있는 Calendar 소비 화면이 없었다.
 이번 구현의 근거는 React/RN 컴포넌트를 채우라는 명시 요청이며, 검증 화면은 Showcase의
-`Patterns/Calendar` 기록 탐색이다. 이를 Yajalal 채택으로 기록하지 않는다.
+`컴포넌트/입력/Calendar` 기록 탐색이다. 이를 Yajalal 채택으로 기록하지 않는다.
 
 ## 경계
 

package/docs/cascader.md

@@ -110,7 +110,7 @@ collection + tri-state 판정 모듈)으로 확정됐고, Tree renderer가 들
   않으므로 막아 둔 자리를 여는 새 축이 필요 없다.
 
 그래서 catalog의 Cascader 행은 `prerequisite`에서 `composed`(Popover·Tree)로 옮겼고,
-작동 예제는 Showcase `Patterns/Tree`의 Cascader 화면이다. "만들지 않는다"는 판정 자체는
+작동 예제는 Showcase `컴포넌트/데이터 표시/Tree`의 Cascader 화면이다. "만들지 않는다"는 판정 자체는
 그대로다 — 바뀐 것은 흡수하는 쪽이 컴포넌트가 아니라 조합이라는 점뿐이다.
 
 

package/docs/code-block.md

@@ -0,0 +1,32 @@
+# Code block
+
+Reviewed: 2026-10-01. Optional `/code-block` entries in both renderers expose
+`CodeBlock`. This is a source preview, not an editor or executable HTML renderer.
+The visual integration request required syntax presentation without another input
+or clipboard engine, so source validation belongs to contracts and actions are slots.
+
+Pass `code`, a localized `label`, optional `language`, `wrap` and `tokens`.
+Tokens have `{text, tone?}` where tone is plain, keyword, string, comment or number.
+Their text must concatenate to the original code exactly, including whitespace;
+invalid output throws. Use a product-selected highlighter to generate tokens.
+No parser, remote highlighting service, raw HTML or execution is included. The
+semantic palette supplies readable token colors; string/plain may share a color.
+
+Long lines scroll horizontally by default. `wrap` opts into wrapping. On Web the
+preformatted source is keyboard-focusable and selectable; on Native it uses a
+selectable Text inside the existing horizontal ScrollView. The Native accessible
+name includes the original source as well as its label, so naming does not hide code.
+
+`copyAction` accepts an existing product control. Web can pass HJM ClipboardButton
+with `value={code}`, localized idle/copied labels and a visible `onCopyError` response.
+Native can use system text selection directly or supply the product's clipboard
+button. No Expo clipboard peer is pulled into the generic renderer. The Native
+showcase demonstrates actual system selection; it does not fake a copied state.
+
+Both showcases register `컴포넌트/데이터 표시/Code Block`. Contract tests reject altered
+highlight text; browser tests check literal script text, focus and wrapping; Native
+host tests check selectable content and scroll/wrap composition. The
+[Native flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md) verifies
+200% controlled text scaling and actual iOS simulator long-press Copy, with exact
+source/clipboard equality. Header and source use the common text-scale helper;
+token spans inherit once. Android clipboard and physical-device verification remain separate.

package/docs/command-palette.md

@@ -134,4 +134,4 @@ Native는 `unsupported`다. 전역 단축키는 제품 소유다.
 - **전역 단축키는 제품 소유다.** 이 renderer는 여는 키를 정하지 않는다.
 - 로컬 검증: `test/command-palette.browser.test.tsx` 5개(이름·초점·배경 inert, 활성 행과
   disabled 건너뜀·재필터, 실행 시 강제 종료와 사유, 종료 후 후속 명령 순서, Escape·바깥
-  pointer 종료)와 `Patterns/CommandPalette`.
+  pointer 종료)와 `컴포넌트/탐색/Command Palette`.

package/docs/compound-controls.md

@@ -0,0 +1,83 @@
+# Compound controls
+
+Reviewed: 2026-10-01. Web and React Native expose identical optional entry names:
+`/duration-field`, `/inline-confirm`, `/reaction-picker`, `/notification-bell`.
+These are compositions of existing canonical controls, not replacements for them.
+The 2026-10-01 visual integration request calls for reusable interactions as well as
+page examples; keeping the existing controls preserves their disabled, focus and
+loading behavior instead of introducing another control implementation.
+
+## DurationField
+
+Use for bounded elapsed time (integer seconds), not clock time or calendar dates.
+Pass `value`, `onValueChange`, required `max`, optional `min` (default 0), and
+`labels: {label, hours, minutes, seconds, increment(unit), decrement(unit)}`.
+All labels are localized by the product. Three existing NumberFields edit the
+hours/minutes/seconds representation. The shared `/duration-field` contract
+validates safe integers and clamps the *combined* duration to the configured range.
+Native field columns wrap according to the text scale so enlarged numeric values stay visible.
+Hours are disabled when the maximum is below one hour. `disabled` disables all
+inputs. Values outside the range throw rather than silently changing product state.
+
+## InlineConfirm
+
+Use for a local explicit confirmation when an overlay would interrupt the context.
+Pass `label`, `prompt`, `confirmLabel`, `cancelLabel`, `pendingLabel`,
+`successLabel`, `errorLabel`, and `onConfirm(): void | Promise<void>`.
+The existing AlertDialog session owns async deduplication, pending and retry.
+No action runs on the initial trigger. Pending disables both actions; rejection
+shows the supplied safe error text and permits retry. Web initially focuses cancel,
+Escape cancels, and cancellation restores trigger focus. Native exposes the
+controls and live error text through its host accessibility APIs.
+Native keeps the localized status text available to assistive technology. iOS
+receives one explicit announcement per prompt/pending/error/success transition;
+errors interrupt queued speech, other updates queue politely. Repeated rendering,
+completion's internal closing phase and background updates do not repeat the prompt.
+Android retains its live-region/alert semantics. Native bridge calls are lifecycle-tested;
+this is not a claim that VoiceOver audio was manually heard.
+
+Success remains visible. Remount with a new entity key to reset the interaction;
+the session captures the action and labels when opened. The product owns operation
+cancellation, authorization, persistence and server-side idempotency.
+
+## ReactionPicker
+
+Pass a nonempty list of `{id, emoji, label, count?, disabled?}`, controlled
+`value: string | null`, `onValueChange`, and the group `label`.
+The shared `/reactions` contract rejects duplicate IDs, invalid counts and unknown
+selected IDs. Selecting the current reaction clears it; selecting another replaces
+it. Existing Buttons own selection and disabled semantics. Counts are product data
+and never increment implicitly. Include counts in localized option labels when
+needed for screen readers; visible emoji/count artwork is decorative. Native passes
+one composed text label to Button so emoji and count use its Text wrapper; sibling
+raw strings bypass that wrapper and fail to render on a real device.
+
+## NotificationBell
+
+Pass `label`, nonnegative integer `count`, `icon`, `onPress`, and optionally
+`disabled` or `active`. Supply the localized unread information in `label` and a
+semantic Icon/Lucide glyph as `icon`. Existing IconButton and CounterBadge own the
+control and count presentation. Artwork and badge are hidden from accessibility
+so the button is announced once.
+A count increase triggers one 400ms pulse; mounting or decreasing does not ring.
+Reduced motion, inactive presentation and background document/AppState suppress
+motion. Native hosts should set `active={false}` for offscreen items. Pressing does
+not mark notifications read automatically; that operation belongs to the product.
+
+## Evidence and examples
+
+Both showcases register `컴포넌트/입력/Duration Field`,
+`컴포넌트/동작/Inline Confirm`, `컴포넌트/동작/Reaction Picker` and
+`컴포넌트/피드백/Notification Bell`, each with Default, Dark and LargeText.
+`갤러리/복합 입력` provides the comparison examples. Web browser and Native
+host-action tests exercise clamp, confirmation/retry/deduplication, controlled
+reactions and motion suspension. Native host tests are not device-render evidence;
+actual iPhone 17 / iOS 27 simulator LargeText cancel/error/retry/success/reset flows
+are recorded in the [component flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md).
+Remaining device coverage stays tracked in the
+[implementation ledger](../../../docs/plans/visual-integration-progress.md).
+
+The same [Native flow audit](../../../docs/evidence/component-flows-2026-10-01/README.md)
+also verifies LargeText duration unit increments/decrements and total seconds, reaction
+selection/replacement/clearing, and local bell read/add state. These are actual simulator
+actions, distinct from backend notification delivery and physical-device screen-reader QA.

package/docs/confirm-popover.md

@@ -99,7 +99,7 @@ Component Explorer에서 이 문서로 연결한다.
 
 ## 2026-09-16 작동 예제
 
-React/RN 확장 요청에 따라 `Patterns/Popover/ReversibleConfirmation`을 제공한다.
+React/RN 확장 요청에 따라 `컴포넌트/오버레이/Popover/ReversibleConfirmation`을 제공한다.
 `@hjmds/react/popover`의 children 함수에서 `close()`와 HJM Button을 조합한다.
 취소 버튼을 초기 초점으로 지정하고, 보관 후 사라지는 트리거 대신 보관 취소 버튼에
 초점을 보낸다. 보관 취소는 실제 로컬 상태를 복원한다. 외부 서버 요청이나 배포 증거는 아니다.

package/docs/consumer-policy.md

@@ -1,13 +1,13 @@
 # HJM 소비 앱 정책
 
 상태: **Normative**
-정책 버전: **1.4.0**
+정책 버전: **2.0.0**
+검토일: 2026-10-02 · 전체 소비 이관에 따른 deprecated API 제거
 적용 대상: 신규 HJM Web·React Native 앱과 기존 앱의 새 화면
 
-이 정책 원문은 다음 package patch release부터
-`@hjmds/design-contracts/consumer-policy.md` export에 포함됩니다. 아직 그 export를 포함하지
-않는 `0.9.0` 소비자는 HJM-APP-STANDARD의 versioned profile과 catalog snapshot을 정책
-근거로 사용하고, 존재하지 않는 `v0.9.0` 정책 URL을 만들어 내면 안 됩니다.
+이 원문은 `@hjmds/design-contracts/consumer-policy.md`에서 제공한다. 소비 앱은 설치한
+패키지 버전의 정책과 HJM-APP-STANDARD release snapshot을 함께 확인한다. 이 checkout의
+1.11 소스 갱신을 아직 설치하지 않은 앱에 자동 적용된 것으로 판단하지 않는다.
 
 이 문서는 "HJM답게 보인다"를 특정 화면 복제로 정의하지 않습니다. 모든 제품이 공유해야
 하는 것은 정보 위계, semantic role, 상태 피드백, 접근성 품질과 플랫폼별 행동입니다.
@@ -93,23 +93,15 @@ foundation이 모두 stable이 됐으므로, 중앙 app profile의 다음 개정
 
 ### 3.1 React Native legacy style compatibility boundary
 
-`@hjmds/react-native` 0.9.x의 공개 타입에는 `style`, `labelStyle`, `inputStyle`,
-`containerStyle`과 여러 slot `*Style`처럼 전체 React Native style을 받는 호환 API가 남아
-있습니다. 이 타입 범위와 caller-last 렌더 순서는 기존 소비자를 위한 집행 공백이지, 앞 절의
-금지 속성을 제품이 덮어써도 된다는 허가가 아닙니다.
-
-- 신규 앱과 기존 앱의 새 화면은 legacy raw style prop을 새로 사용하면 안 됩니다(MUST NOT).
-  컴포넌트가 `layoutStyle`을 제공하면 배치에는 그것만 사용하고, 제공하지 않으면 바깥
-  composition wrapper를 사용하거나 HJM에 semantic axis를 먼저 추가해야 합니다(MUST).
-- `HjmCompositionStyle` / `layoutStyle`은 margin, width, flex 계열과 `alignSelf`만 노출하며
-  color, typography, padding, gap, border, radius, height, opacity, transform과 interaction
-  state key를 타입에서 제외합니다. 허용된 margin 값도 HJM spacing token 또는 검토된 제품
-  adapter에서 와야 합니다(MUST).
-- 기존 화면의 legacy prop은 migration 기간에만 유지할 수 있습니다(MAY). controlled visual
-  key가 남아 있으면 정책 항목, 소유자, 대체 semantic API와 제거 train을 ADR에 기록해야
-  하며, 신규 사용으로 복사해서는 안 됩니다(MUST NOT).
-- 0.9 호환 train에서는 등록 style ID와 배열을 런타임에서 필터링하거나 조용히 삭제하지
-  않습니다. 그러한 즉시 변경은 기존 앱의 레이아웃을 예측 불가능하게 깨뜨리기 때문입니다.
+2026-10-02 전체 소비 버전업 결정에 따라 deprecated 공개 스타일 통로는 1.11에서 제거합니다.
+정확한 제거 속성과 대체 API는 [1.11 이관표](migration-native-legacy-removal.md)를 따릅니다.
+1.x 설치본의 caller-last 호환 동작은 역사적 동작이며 현재 소스에 유지되지 않습니다.
+
+- 배치에는 `layoutStyle`을 쓰고, 제공하지 않는 컴포넌트는 외부 composition wrapper를 씁니다.
+- `HjmCompositionStyle` / `layoutStyle`은 margin, width, flex 계열과 `alignSelf`만 제공합니다. color,
+  typography, padding, gap, border, radius, height, opacity, transform은 recipe/semantic API 소유입니다.
+- 내부 조합의 스타일은 비공개 renderer에 두며 앱에서 해당 내부 파일을 import하지 않습니다.
+- 정식 플랫폼 host·제품 소유 슬롯·이미지 renderer 스타일을 deprecated 별칭과 혼동하지 않습니다.
 
 소비 앱의 legacy prop이 실제로 무엇을 덮어쓰고 있었는지 확인한 뒤, 배치가 아닌 값은
 semantic axis로 옮겼습니다. 아래는 그 축과 대체 대상입니다.
@@ -165,7 +157,7 @@ legacy raw style surface는 다음 조건이 모두 충족된 뒤 공지된 brea
 “1.0.0 이전 제거” 기한은 실제 release/API와 어긋나므로 폐기합니다. 이미 게시한 1.x의 타입과
 런타임을 minor에서 삭제하는 대신, 위 네 조건과 소비 앱별 이관 목록을 충족한 다음 major에서
 제거합니다. 1.4는 semantic API와 이관 경로를 추가하는 train이며, 기존 prop을 새 화면에 쓰는
-것은 계속 금지합니다. 제거 예정 major는 소비 이관 완료 후 Changeset에서 확정합니다.
+것은 계속 금지합니다. 2026-10-02 사용자의 전체 이관 결정으로 제거 train을 1.11로 확정했습니다.
 
 권장 구조는 다음과 같습니다. 실제 폴더명은 stack 관습에 맞춰도 역할은 유지합니다.
 
@@ -240,3 +232,18 @@ package로 승격하지 않습니다.
 ## Optional presentation adapters
 
 The [optional adapter contract](optional-adapters.md) lists platform-specific entries and exact peer requirements. These extensions do not promote the canonical component or establish consumer/device compatibility. Native adapters require separately verified development clients; base imports retain their existing dependency contract.
+
+
+## 상호작용 채택과 성능 기록
+
+2026-10-02 사용자가 참고 인터랙션 수준의 제품 품질을 요청한 데 따른 구체 적용 기준이다.
+기존 상태 피드백·접근성 책임을 제품의 입력 → 반응 → 확정 → 복구 흐름까지 연결한다.
+
+- 제품은 설치된 HJM 버전의 API와 Storybook 배포/실험 상태를 확인하고 해당 범위에서 재사용한다.
+  새 동작이 필요한 경우 기존 Button·Sheet·Toast를 합성하며 같은 상태를 두 계층에서 관리하지 않는다.
+- 성공은 서버 또는 제품의 실제 확정 뒤에 표시한다. 연속 입력·실패·역순 응답·중간 이탈에서도
+  초안과 복구 경로를 보존한다. 웹·앱 입력 방식이 달라도 같은 사용자 의도를 유지한다.
+- 성능에 영향을 주는 제스처·전환·대량 렌더링 변경은 제품 조건의 변경 전후를 측정한다.
+  기기·OS·빌드·데이터·측정 방법과 미검증 범위를 기록하고 데모의 성공을 실기기 성능으로 쓰지 않는다.
+- 구체 예제·목표·기록 양식은 [상호작용 적용·품질 기준](../../../docs/INTERACTION_QUALITY.md)을 따른다.
+  이 소스 문서의 변경이 아직 게시되지 않은 API를 소비 앱에 설치하거나 자동 적용하지는 않는다.

package/docs/cross-platform-core-normalization.md

@@ -1,5 +1,7 @@
 # Cross-platform core normalization
 
+검토일: 2026-10-02 · 2.0 source contract
+
 Text, Surface, Stack, Grid, Button, IconButton, Tag, Card의 공통 의미 축은 contracts가 소유하고 Web과
 Native renderer는 각 플랫폼 host로 번역한다. 라이브러리 비교와 채택/기각 근거는
 [library-reference-decisions.md](./library-reference-decisions.md)를 따른다.
@@ -41,6 +43,10 @@ Native renderer는 각 플랫폼 host로 번역한다. 라이브러리 비교와
 `loading`과 `disabled`는 같은 상태가 아니다. 두 renderer 모두 loading 중 activation을
 막고 busy 상태를 보조 기술에 노출하지만, pending control의 focusability는 유지한다.
 명시적 `disabled`만 host의 disabled 상태가 된다.
+2026-10-02 사용자 요청에 따라 Button은 로딩 중 기존 글자·양쪽 장식을 시각적으로 숨기고
+버튼 중앙에 스피너 하나만 표시한다. 내용은 레이아웃에 남겨 폭을 유지하며 접근성 이름과
+busy 상태도 유지한다. 글자 옆에 스피너를 추가하는 이전 표현은 시각적 중복과 폭 변화를
+만들어 버렸다.
 
 IconButton은 보이는 텍스트가 없으므로 현지화된 `label`과 icon `children`을 두 renderer에서
 필수로 받는다. `size`는 36/44/52 visual diameter를 선택하고 small은 Web pseudo hit area와
@@ -53,7 +59,8 @@ edge를 항상 그린다.
 
 ## 0.5 compatibility aliases
 
-0.6에서 canonical API로 옮길 수 있도록 기존 Native 호출은 당분간 동작한다.
+아래는 0.6 이관 당시의 before/canonical 비교다. 현재 지원 여부는 각 API 타입을 따른다.
+아래 before API는 모두 [2.0 이관](./migration-native-legacy-removal.md)에서 제거했다.
 
 ```tsx
 // before
@@ -73,30 +80,25 @@ edge를 항상 그린다.
 <IconButton label="닫기" tone="ghost"><CloseIcon /></IconButton>
 ```
 
-- Native `Stack.direction`: `row → inline`, `column → block` deprecated alias
-- Native `Button.label`, `Tag.label`: `children` deprecated alias
-- Native `Surface.sunken`, `Surface.brand`: 각각 `subtle`, `accent` deprecated alias
-- Native `Grid.descriptor`: flat `columns`/`gap`/`minColumnWidth`를 위한 deprecated alias
-- Native `IconButton.accessibilityLabel`, `icon`: `label`, `children` deprecated alias
-- Native `IconButton tone="link"`: `ghost`로 번역되는 deprecated alias
-
-호환 alias는 새 문서와 예제에서 사용하지 않는다. 제거는 major release에서만 한다.
+Native `Surface.sunken`은 공통 recipe에 독립적으로 정의된 tone이며 deprecated alias가 아니다.
+`brand`만 제거하고 `accent`로 이관한다. 1.x의 호환 별칭 지원 설명은 현재 2.0 소스에 적용하지 않는다.
 
 ## Collection and state vocabulary
 
-공통 제품 코드에서 같은 역할은 같은 이름을 사용한다. Web을 기준으로 Native의 비파괴 호환
-bridge를 추가했으며, 새 코드는 canonical 열만 사용한다.
+공통 제품 코드에서 같은 역할은 같은 이름을 사용한다. 1.x에서 제공했던 Native bridge를
+2.0에서 제거했으므로 아래 canonical API만 사용한다.
 
-| Component | Canonical Web/Native API | Deprecated Native alias |
-| --- | --- | --- |
-| Switch | `checked`, `defaultChecked`, `onCheckedChange` | `value`, `defaultValue`, `onValueChange` |
-| RadioGroup | `items: RadioGroupItem[]` | `options: RadioOption[]` |
-| SegmentedControl | `items: SegmentedControlItem[]` | `options: SegmentedControlOption[]` |
-| Tabs | `items: TabItem[]`, item key `id` | `options: TabOption[]`, item key `value` |
-| Select | `source`/`items`/`sections`, `selectedKey`, `defaultSelectedKey`, `onSelectionChange` | `options`, `value`, `defaultValue`, `onValueChange` |
-
-한 인스턴스에서 canonical과 deprecated channel을 함께 전달하면 타입과 runtime 모두 실패한다.
-이 규칙은 TypeScript를 우회하는 JavaScript 소비자에게도 결정적인 상태 모델을 보장한다.
+| Component | Canonical Web/Native API |
+| --- | --- |
+| Switch | `checked`, `defaultChecked`, `onCheckedChange` |
+| RadioGroup | `items: RadioGroupItem[]` |
+| SegmentedControl | `items: SegmentedControlItem[]` |
+| Tabs | `items: TabItem[]`, item key `id` |
+| Select | `source`/`items`/`sections`, `selectedKey`, `defaultSelectedKey`, `onSelectionChange` |
+| Menu | 항목 key `id`, 실행 `onAction`, 선택 `selection.onSelectionChange` |
+
+Web Menu의 선택 prop 배치는 Web Menu 타입을 따른다. 두 플랫폼 모두 실행과 선택 변경을
+구분하며 item-local `onSelect` 또는 Native `onSelect` 호환 콜백은 사용하지 않는다.
 
 ## Reference application notes
 

package/docs/data-table.md

@@ -84,10 +84,13 @@ async 상태와 narrow long-copy 회귀로 확인하고, 소비 제품의 데이
 `@hjmds/react/data-table`의 `DataTable`이 이 계약을 실행한다. Web renderer는 전용 keyboard·
 selection·320px long-copy proof를 통과해 2026-09-29 stable로 승격한다. Native는 `unsupported`다.
 
-- **기존 `Table`과 겹치지 않는다.** `@hjmds/react`의 `Table`(advanced-display)은 열·행을
-  그려 주는 표시용이고 선택·tri-state·async 상태·정렬 상태 순환이 없다. DataTable은 그
-  상호작용 계약을 실행하는 쪽이다. 단순 표는 계속 `Table`을 쓴다 — 같은 화면에 둘을 겹쳐
-  쓰지 않는다.
+- **기존 `Table`과 정렬 기능은 공유한다.** 2026-10-01 중복 조사에서 Table도 정렬 버튼과
+  ascending/descending 순환을 제공하는데 표시 전용으로 설명했던 불일치를 확인했다.
+  Table은 generic row·caption·emptyState와 두 방향 정렬을 제공하고, DataTable은
+  ID 기반 row/column·선택·tri-state·async 상태 및 정렬 해제를 포함하는 세 상태 순환을 제공한다.
+  정렬 전환은 같은 계약 함수, header button은 같은 내부 renderer를 소비한다.
+  caption과 단순 generic row 표는 Table, 행 선택·loading/error와 정렬 해제가 필요한 표는
+  DataTable을 선택한다. API를 합치면 caption·emptyState·row 모델 호환성을 잃으므로 두 API를 유지한다.
 - **정렬 버튼은 header 안에 있다.** `th` 자체를 버튼으로 만들지 않고, 방향은
   `aria-sort`에 그대로 흘린다. 다음 상태는 `getNextDataTableSortState`가 정하고 실제 정렬은
   제품이 한다.
@@ -103,4 +106,4 @@ selection·320px long-copy proof를 통과해 2026-09-29 stable로 승격한다.
 - 로컬 검증: `test/data-table.browser.test.tsx` 5개(header 안 정렬 버튼과 aria-sort 3단계,
   tri-state 선택과 disabled 제외, 단일 선택 radio 의미, 셀당 컨트롤 하나와 기본 tab 순서,
   async 상태 발표와 footer 조합), `test/data-table.keyboard.browser.test.tsx` 1개(실제 Tab·Enter·Space
-  입력), 그리고 `Patterns/CommandPalette`의 표 화면.
+  입력), 그리고 `컴포넌트/탐색/Command Palette`의 표 화면.

package/docs/dialog.md

@@ -37,3 +37,5 @@ a narrow viewport. React Native renderer tests cover modal role/name/state,
 action labels and close requests, back/outside dismissal, busy guards, and long
 title/description copy. These tests exercise renderer contracts; device and
 screen-reader behavior remains a separate consumer validation concern.
+
+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/effect-surface.md

@@ -0,0 +1,50 @@
+# Composable decorative surfaces
+
+2026-10-01. Optional Web/Native presentation, independent implementation inspired
+by layered shader composition. No Shaders.com engine, presets or source is shipped.
+
+Import `EffectSurface` from the renderer `/effect-surface` entry. The shared
+`/effect-surface` contract accepts unique `layers` (`mesh`, `glow`, `grain`), a
+stable `seed`, `intensity` from 0 to 1, a cycle `period` from 2 to 120 seconds,
+`active` (false by default), and three semantic color references. Web uses local
+SVG/WAAPI; Native requires the existing optional SVG peer and core Animated.
+No WebGPU context, network request or new native animation runtime is required.
+
+```tsx
+<EffectSurface descriptor={{ layers: ['mesh', 'grain'], seed: 'welcome', active: true }}>
+  <WelcomeContent />
+</EffectSurface>
+```
+
+Web accepts `className`; Native accepts container `style` and host `visible`.
+Native screen/list owners must pass `visible={false}` when hidden or outside the
+visible list window. Web observes intersection and document visibility. Both
+honor the HJM provider's reduced-motion setting; Native also handles AppState.
+The static seeded geometry and the base theme background stay visible when motion
+stops. Effects never duplicate content, take focus, intercept touches or add an
+accessible name. The content itself stays in normal layout.
+
+Noise uses a seeded repeating small-dot tile rather than large spots. Geometry
+is shared, while host rasterization and transform details can differ. This is
+atmospheric parity, not a pixel-identical renderer promise. Motion is opt-in and
+slow by default to avoid adding continuous work to ordinary content screens.
+Use `active` only while an effect matters; avoid many simultaneously moving rows.
+
+The component does not automatically guarantee text contrast across arbitrary
+brand colors/intensities. Verify the actual composition or put important text
+and controls on an opaque HJM Surface. The fallback background is the current
+provider background, not an independently selected palette.
+
+`갤러리/시각 효과` demonstrates layers separately and together.
+This optional surface is supplemental presentation; it does not add another
+canonical Surface or replace ThinkingOrb's actual-work state semantics.
+
+
+Host failure fallback (2026-10-02): if Web animation creation is rejected, the SVG
+stays static and no visibility event repeatedly retries it. Native SVG/Animated
+render errors remove only the decoration until the surface remounts; product
+children keep their state and remain interactive on the base theme background.
+A failed Native foreground animation start keeps the static decoration and stops
+retrying for that effect lifecycle. Descriptor validation stays outside this
+fallback so invalid caller input is still reported. This implements integration
+plan §5's requirement that decorative failures must not remove product content.

package/docs/floating-action-button.md

@@ -109,7 +109,7 @@ FAB는 collection 항목이 아니다. 스크롤 콘텐츠 **뒤**에 오는 고
 
 ## 검증 화면
 
-2026-09-16: React/RN `Patterns/Floating action button`에 스크롤 목록 → 기록 작성
+2026-09-16: React/RN `패턴/빠른 메모 작성`에 스크롤 목록 → 기록 작성
 Dialog → 새 기록 추가 흐름을 구현했다. Flutter 앱은 이번 이관 범위에서 제외한다.
 
 ## React / React Native 공개 API

package/docs/folder-preview.md

@@ -0,0 +1,26 @@
+# Folder preview
+
+Reviewed: 2026-10-01. Both renderers expose FolderPreview through `/folder-preview`.
+It is an optional Collapsible composition for collections with a decorative cover,
+not a new navigation or overlay controller. Pass localized `label`, controlled
+`open`, `onOpenChange`, up to three useful `previews`, actual `children`, and optional
+`disabled`. Further preview nodes are intentionally not rendered.
+
+Previews are decorative snapshots, not interactive controls. Their wrapper is inert
+on Web and hides descendants from Native accessibility/touch. Use existing Asset or
+Image components in slots when artwork is needed, and repeat meaningful item names
+and actions in expanded children. The label should describe the collection/count.
+The existing Collapsible owns expanded state and unmounts closed content.
+
+The bounded 260×160 artwork uses overlapping cards that fan out when opened. Web
+transitions transforms and respects reduced motion. Native uses the existing
+ContentTransition around the artwork, inheriting its reduced-motion/AppState rules.
+Labels and real content remain fluid; the illustration is not their sizing model.
+
+Both showcases register 컴포넌트/데이터 표시/Folder Preview with Default, Dark and
+LargeText. Tests cover controlled expansion and decorative accessibility boundaries.
+[Native and Web LargeText flow evidence](../../../docs/evidence/component-flows-2026-10-01/README.md)
+verifies opening/closing and readable expanded content. The examples use document line
+artwork in decorative slots: enlarged text there previously overlapped inside the fixed
+illustration. Actual item names remain in the fluid content below. Physical-device and
+manually heard screen-reader verification remain separate.

package/docs/generated/component-maturity.md

@@ -1,6 +1,6 @@
 # Component maturity and evidence manifest
 
-> Generated from `@hjmds/design-contracts` 1.10.0. Do not edit this file directly; run `pnpm contracts:sync`.
+> Generated from `@hjmds/design-contracts` 1.12.0. Do not edit this file directly; run `pnpm contracts:sync`.
 
 This document is the human-readable projection of the same catalog and Showcase manifest consumed by product CI.
 

package/docs/generated/renderer-evidence.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "designSystemVersion": "1.10.0",
+  "designSystemVersion": "1.12.0",
   "source": "packages/design-contracts/docs/generated/showcase-manifest.json",
   "surfaces": {
     "web": {
       "packageName": "@hjmds/react",
-      "packageVersion": "1.10.0",
+      "packageVersion": "1.12.0",
       "activeComponents": 103,
       "claimedComponents": 103,
       "completeScenarioComponents": 103,
@@ -5642,7 +5642,7 @@
     },
     "native": {
       "packageName": "@hjmds/react-native",
-      "packageVersion": "1.10.0",
+      "packageVersion": "1.12.0",
       "activeComponents": 83,
       "claimedComponents": 83,
       "completeScenarioComponents": 83,

package/docs/generated/renderer-evidence.md

@@ -1,6 +1,6 @@
 # Renderer evidence coverage
 
-> Generated for HJM 1.10.0. Do not edit directly; run `pnpm evidence:sync`.
+> Generated for HJM 1.12.0. Do not edit directly; run `pnpm evidence:sync`.
 
 This projection joins the canonical surface maturity manifest with first-party renderer claims. Missing scenarios are explicit beta promotion debt; stable surfaces are blocked by CI until none remain.
 

package/docs/generated/showcase-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "designSystemVersion": "1.10.0",
+  "designSystemVersion": "1.12.0",
   "packageName": "@hjmds/design-contracts",
   "components": [
     {