@hjmds/design-contracts 1.10.0 → 1.12.0

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.12.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": [