@hjmds/design-contracts 1.26.0 → 1.27.0

package/docs/generated/showcase-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "designSystemVersion": "1.26.0",
+  "designSystemVersion": "1.27.0",
   "packageName": "@hjmds/design-contracts",
   "components": [
     {
@@ -1583,6 +1583,54 @@
         "authored": null
       }
     },
+    {
+      "id": "image-choice-group",
+      "storyId": "input/image-choice-group",
+      "name": "ImageChoiceGroup",
+      "category": "input",
+      "platform": "shared",
+      "contractStatus": "beta",
+      "surfaces": {
+        "web": "beta",
+        "native": "beta"
+      },
+      "requirements": [
+        {
+          "surface": "contract",
+          "scenarios": [
+            "contract"
+          ]
+        },
+        {
+          "surface": "web",
+          "scenarios": [
+            "default",
+            "dark",
+            "long-copy",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "accessibility"
+          ]
+        },
+        {
+          "surface": "native",
+          "scenarios": [
+            "default",
+            "dark",
+            "long-copy",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "accessibility"
+          ]
+        }
+      ],
+      "documentation": {
+        "generated": "docs/generated/component-maturity.md",
+        "authored": null
+      }
+    },
     {
       "id": "segmented-control",
       "storyId": "input/segmented-control",

package/docs/gravity-letters.md

@@ -5,8 +5,13 @@ Reviewed: 2026-10-01
 Optional `@hjmds/react/gravity-letters` and `@hjmds/react-native/gravity-letters`
 provide an independently authored promotional drop/rebound accent. This is not a
 replacement for Text or ContentTransition: the whole effect is decorative and
-hidden from accessibility APIs. Keep the meaningful static heading outside it.
-The Web presentation inherits typography; Native uses canonical heading Text.
+hidden from accessibility APIs. Keep the meaningful heading text outside it; it
+need not be a second visible copy. Web puts `VisuallyHidden` text in the same
+Heading; Native wraps the letters in an accessible `header` view labelled with
+the text (Native has no VisuallyHidden). The Web presentation inherits
+typography; Native takes an optional `level` and draws the glyphs with that
+`headingRecipe` level, because RN text styles do not cross the per-glyph
+Animated views (without `level` it keeps canonical heading Text).
 
 Pass `glyphs` as host-segmented graphemes/words (at most 32 nonempty single-line
 strings). Never split emoji or complex scripts with UTF-16 `split("")`. Spaces

package/docs/masonry.md

@@ -1,8 +1,10 @@
 # Masonry
 
 2026-09-29: 사용자가 미구현 기능 완성을 요청해 높이가 다른 카드를 배치하는 Web/Native
-렌더러를 추가했다. `width`, `columns`, `gap`, `getItemHeight(item, itemWidth)`를 명시한다.
-컨테이너 측정과 콘텐츠 높이는 소비 화면이 소유한다. 임의 높이 콘텐츠를 추정해 겹치게
+렌더러를 추가했다. `getItemHeight(item, itemWidth)`를 명시하고 `width`·`columns`·`gap`은 선택이다.
+콘텐츠 높이는 소비 화면이 소유한다. 2026-10-17 구성 리뷰에서 데스크톱 1200px에서도 고정 2열이라 카드가
+약 580px로 늘어난 것을 확인해, `width`를 생략하면 Masonry가 자리 폭을 측정하고 `columns`를 생략하면
+`masonryRecipe.minItemWidth`(160)로 열 수를 계산하게 했다. 항목 틀은 세로 flex 상자라 카드가 `flex: 1`로 채운다. 임의 높이 콘텐츠를 추정해 겹치게
 만드는 대신 확정한 높이로 가장 짧은 열에 순서대로 배치한다. DOM/Native 읽기 순서는
 입력 순서 그대로이며 RTL은 위치만 반전한다. 긴 문구·큰 글자를 사용할 때 높이도 함께
 재계산해야 한다. 빈 목록은 `empty`로 표현하고 중복 키·잘못된 크기는 거부한다.

package/docs/screen-patterns.md

@@ -1,6 +1,6 @@
 # 반복 화면 조합
 
-검토일: 2026-10-15 · 상태: Storybook 배포(2026-10-06 사용자 승인) · 패키지 적용 범위는 개별 API 사용 지침 참조
+검토일: 2026-10-17 · 상태: Storybook 배포(2026-10-06 사용자 승인) · 패키지 적용 범위는 개별 API 사용 지침 참조
 
 사용자가 로그인·설정·알림·채팅 화면을 미리 일반화해 개발 생산성을 높이도록 요청했다.
 기존 AuthScreenLayout, Section, ListRow, TopBar, Layout, EmptyState, action-session,
@@ -400,7 +400,10 @@ CommentThreadScreen의 optional threadHeader는 첫 댓글 앞의 스크롤 콘
 [댓글 화면](usage/components/comment-thread-screen.md#배치)을 따른다.
 
 
-### 화면별 독립 복구와 첫 행동 (미게시, 1.18.0 이후)
+### 화면별 독립 복구와 첫 행동
+
+API별 제공 기준과 개발 중 추가분은 [사용 지침](usage/README.md)과 설치된 공개 타입에서 확인한다.
+이 절의 설계 시점을 현재 미게시 상태로 해석하지 않는다.
 
 2026-10-13 계층 점검에서 빈 채팅의 첫 입력이 사라지고 상세 조회 실패를 제품이 다시 조립해야 하는
 누락을 확인했다. 기존 화면 API를 다음과 같이 보강한다.

package/docs/showcase.md

@@ -76,12 +76,12 @@ CI에서 별도로 빌드·번들 검증하며, HJM 카탈로그의 story identi
 
 - `pnpm contracts:sync`: `docs/generated/component-maturity.md`와
   `docs/generated/showcase-manifest.json` 갱신
-- `pnpm contracts:check`: 생성 파일이 source와 다르면 CI 실패
+- `pnpm contracts:check`: 생성 파일과 source의 차이를 보고하는 선택적 로컬 검사
 - `pnpm evidence:sync`: first-party renderer claim과 required scenario를 결합한
   `renderer-evidence.json`/`.md` 및 명시적 beta debt 갱신
-- `pnpm evidence:check`: renderer projection이 source와 다르면 CI 실패
+- `pnpm evidence:check`: renderer projection과 source의 차이를 보고하는 선택적 로컬 검사
 - renderer의 `test/executed-scenarios.json`은 proof file, `all-cases`와 실행할 scenario/environment를
-  선언한다. 실제 test가 이 registry를 import해 case를 실행하며 package test 실패가 CI로 전파된다.
+  선언한다. 실제 test가 이 registry를 import해 case를 실행하며 선택한 package test의 실패로 보고한다.
 - `workspace:check`는 claim의 component/case/proof와 registry의 scenario를 결합한다.
   non-default scenario도 이 registry와 실행되는 proof에 연결되어야 한다. registry 자체는
   독립적인 실행 성공 영수증이 아니며 해당 source의 테스트 결과와 함께 읽는다.
@@ -89,13 +89,11 @@ CI에서 별도로 빌드·번들 검증하며, HJM 카탈로그의 story identi
 - 제품 Storybook verifier: 설치한 `@hjmds/design-contracts/showcase`를 기준으로 실제 채택한
   story와 scenario를 검증한다. 전체 inventory gate는 full-coverage 구현에만 적용한다.
 - 제품 evidence artifact: 검증한 story ID·실제로 실행한 scenario·소비 버전/source를 기록한다.
-- `pnpm governance:check`: canonical `ci:check`/`release:check` 연결, renderer test/생성 drift 검사,
-  registry 연결과 release verification step의 실패 전파·publish/tag 이전 순서를 검증한다.
 
-현재 canonical tag는 **내부 package·Showcase 검사**를 기준으로 생성한다. 외부 소비 제품을
-`repository_dispatch`하고 release SHA·consumer SHA·run/artifact를 결합해 기다리는 gate는
-구현되어 있지 않다. 제품 CI/기기 QA는 별도 범위다. 현재 실행 계약과 향후 외부 gate 설계는
-[릴리스 검증 계약](../../../docs/RELEASE_GOVERNANCE.md)을 따른다.
+현재 npm workflow는 빌드·게시 뒤 같은 commit에 canonical tag를 만든다. tag 자체는
+package·Showcase 테스트나 외부 소비 제품의 검증 성공 증거가 아니다. 폐기된 workflow를
+요구하던 `governance:check`는 2026-10-17 감사에서 제거했다. 로컬 검사·게시·소비 제품의
+확인 범위는 [릴리스 검증 계약](../../../docs/RELEASE_GOVERNANCE.md)을 따른다.
 
 `compareShowcaseStoryIds`와 `assertShowcaseStoryIds`는 모든 Stable/Beta 컴포넌트를 제공하는
 first-party/full-coverage Storybook의 inventory gate입니다. 부분 채택 소비 앱이나 개별 화면은

package/docs/stable-promotion.md

@@ -1,11 +1,23 @@
 # Stable 승격 기준
 
-검토일: 2026-09-29. 이 문서가 성숙도 승격 조건의 원문입니다.
+검토일: 2026-10-17. 이 문서가 성숙도 승격 조건의 원문입니다.
 
 `stable`은 공개 API와 동작을 SemVer로 지원한다는 약속입니다. 변경을 영구히 금지하거나
 모든 제품·OS에서 검증을 마쳤다는 뜻은 아닙니다. `beta`는 API·동작 또는 renderer 검증에
 구체적인 미완료 항목이 있다는 뜻입니다. 채택 제품 수나 사용 기간으로 구분하지 않습니다.
 
+## 카탈로그 등록과 공개 API 분류
+
+2026-10-17 확인에서 기존 동결의 해제 조건에 열거된 핵심 8개가 모두 Web·Native stable이었다.
+동결은 종료하고 당시 목록·예외는 [역사 기록](catalog-freeze.json)으로 보존한다.
+
+- 독립된 의미·상태·접근성 계약은 canonical catalog에 등록한다. 기존 API와 같은 의미이면 기존 계약을 확장한다.
+- 동반·대체 API, optional extension, supplemental은 공개 API 대응표에서 기존 계약과의 관계를 설명한다.
+  카탈로그 동결을 피하려고 supplemental로 분류하지 않는다. 기존 공개 이름은 호환성을 보존하며 재분류를 검토한다.
+- canonical의 플랫폼 지원·안정성은 catalog가 소유한다. 나머지는 개별 계약에 지원 플랫폼, 필요한 peer,
+  검증 범위·미완료 항목을 명시한다. 기본 API나 Storybook 분류에서 stable을 추정하지 않는다.
+- 등록 자체가 승격은 아니다. 새 stable 주장은 아래 기준으로 판정한다. 공개 API 대응표·사용 지침은 같은 변경에서 갱신한다.
+
 ## 컴포넌트 승격에 필요한 것
 
 1. 공개 타입·기본값·지원 동작이 문서와 일치하고, 알려진 계약 공백이 없어야 합니다.

package/docs/usage/README.md

@@ -4,9 +4,9 @@
 
 단계는 Storybook과 같은 `토큰 → 컴포넌트 → 구성 → 화면`이다. 화면을 만들 때는 화면 지침의 영역 구조와
 버튼 위치에서 시작해 구성·컴포넌트 지침으로 내려가고, 값은 토큰 지침에서 고른다.
-[선택 기준](SELECTION.md)으로 그대로 사용·공개 슬롯 확장·제품 전용 구성을 고른다. 설치 버전의 지침을 본다: `node_modules/@hjmds/design-contracts/docs/usage/`.
+[선택 기준](SELECTION.md)으로 그대로 사용·공개 슬롯 확장·공통 API 보완·제품 고유 기능 연결을 고른다. 설치 버전의 지침을 본다: `node_modules/@hjmds/design-contracts/docs/usage/`.
 제공 기준은 확인한 기본 API 버전이며 최초 출시 버전이 아니다. 구성·화면은 각 API 지침의 제공 버전을 확인한다.
-API 안정성은 1.25.0의 생성 manifest에서 읽은 정규(canonical) API 기준이다. 동반·선택형 확장은 개별 계약을 확인한다.
+API 안정성은 1.26.1의 생성 manifest에서 읽은 정규(canonical) API 기준이다. 동반·선택형 확장은 개별 계약을 확인한다.
 Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품 반영을 의미하지 않는다.
 `분류`는 Storybook 제목 `<배포|실험>/<단계>/<분류>/<항목>`의 셋째 마디이고, 토큰·구성·화면은 Storybook 메뉴와 같은 순서다.
 
@@ -33,7 +33,8 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | 지침 | 분류 | 언제 쓰나 | 제공 기준 | 지원 | API 안정성 | Storybook |
 | --- | --- | --- | --- | --- | --- | --- |
 | [Accordion](components/accordion.md) | 데이터 표시 | 서로 관계가 있는 여러 접힘 항목을 한 그룹으로 보일 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
-| [ActivityChip](components/activity-chip.md) | 상태와 알림 | 백그라운드에서 돌고 있는 작업 하나(검수·업로드·동기화)의 상태를 헤더의 빈 자리에 짧게 보여 주고, 누르면 그 작업의 진행 패널(Toast 패널)을 여닫을 때 쓴다. | 미게시(1.17.2 이후) | Web · Native | 개별 API 계약 참조 | 배포 |
+| [AccountSwitcher](components/account-switcher.md) | 구성/탐색과 이동 | 확인된 현재 계정을 보여 주고 메뉴에서 다른 계정을 골라 실제 세션 전환을 요청할 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [ActivityChip](components/activity-chip.md) | 상태와 알림 | 백그라운드에서 돌고 있는 작업 하나(검수·업로드·동기화)의 상태를 헤더의 빈 자리에 짧게 보여 주고, 누르면 그 작업의 진행 패널(Toast 패널)을 여닫을 때 쓴다. | 1.26.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [ActivityHeatmap](components/activity-heatmap.md) | 데이터 표시 | 최대 1년(366일) 범위의 일별 활동량을 한눈에 보여 주는 읽기 전용 개요에 쓴다. | 1.12.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Affix](components/affix.md) | 기반 기능 | Web에서 스크롤하는 동안 요약·필터·저장 버튼 같은 작은 영역을 가장 가까운 스크롤 조상의 상단에 붙여 두고, 부모가 끝나면 함께 풀리게 할 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [Agreement](components/agreement.md) | 입력 | 가입·결제·서비스 시작 앞의 약관 동의 묶음에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
@@ -45,6 +46,7 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [AuthScreenLayout](components/auth-screen-layout.md) | 레이아웃 | 로그인·가입 진입 화면의 배치에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Avatar](components/avatar.md) | 데이터 표시 | 사람·계정을 사진 또는 이니셜로 나타낼 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Badge](components/badge.md) | 데이터 표시 | 항목의 상태나 분류를 짧은 글자 하나로 붙일 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [BezierEditor](components/bezier-editor.md) | 구성/직접 조작과 모션 | CSS `cubic-bezier` 이징 네 좌표를 슬라이더로 편집하고 곡선과 움직임 미리 보기를 함께 보여 줄 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [BottomCTA](components/bottom-cta.md) | 동작 | 화면의 결론 행동(저장·다음·결제·가입)을 본문 아래 하단 영역에 둘 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [BottomInfo](components/bottom-info.md) | 상태와 알림 | 주 행동 아래에 늘 붙어 있는 작은 조건 문장에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [BottomNavigation](components/bottom-navigation.md) | 탐색 | 앱의 안정된 최상위 route(홈·검색·메시지·내 정보) 2~6개 사이를 이동하는 하단 막대에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
@@ -61,16 +63,20 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [CheckboxGroup](components/checkbox-group.md) | 입력 | 한 질문에 대한 여러 선택지 중 0개 이상을 고르게 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Chip](components/chip.md) | 입력 | 누를 수 있는 작은 pill이다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [CodeBlock](components/code-block.md) | 데이터 표시 | 코드·명령·설정 조각을 읽기 전용으로 보여 주고 사용자가 선택·복사하게 할 때 쓴다. | 1.12.1 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [CohortRetentionTable](components/cohort-retention-table.md) | 구성/정보 표시 | 가입 시점(코호트)별로 기간마다 남은 인원 비율을 직사각형 표와 heat 색으로 비교할 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Collapsible](components/collapsible.md) | 데이터 표시 | 이웃 없이 혼자 접었다 펴는 한 덩어리에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [ColorPicker](components/color-picker.md) | 입력 | 사용자가 콘텐츠 색(라벨 색, 태그 색, 테마 편집기의 사용자 값 등)을 sRGB HEX로 고르는 폼 입력에 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [Combobox](components/combobox.md) | 입력 | 주어진 목록에서 하나를 고르는데 목록이 길어 입력으로 좁혀야 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [CommandPalette](components/command-palette.md) | 오버레이 | ⌘K 스타일로 앱 전체의 **행동**을 검색해 실행하는 모달에 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
+| [CommentThreadRow](components/comment-thread-row.md) | — | 가상화 목록(FlatList·가상 스크롤러)처럼 제품이 댓글 목록을 직접 그려야 할 때 댓글 한 행을 그린다. | 1.23.0 | Web · Native | 개별 API 계약 참조 | 실험 |
 | [CommentThreadScreen](components/comment-thread-screen.md) | 화면/소통 | 게시물·콘텐츠 아래의 댓글 화면 한 장에 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [CompositionLayout](components/composition-layout.md) | 화면/설정 | 카드·패널·화면 본문 안의 콘텐츠 묶음에 제목·배지·행동·안내·본문·하단 영역이 필요할 때 쓴다. | 1.23.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Container](components/container.md) | 레이아웃 | 화면 본문의 최대 폭과 좌우(논리 방향) 여백을 맞출 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [ContentTransition](components/content-transition.md) | 시각 효과 | 같은 자리의 내용이 상태에 따라 바뀔 때(필터 결과 패널, 단계별 본문) 새 내용이 짧게 나타나도록 감싼다. | 1.12.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [ContextMenu](components/context-menu.md) | 탐색 | Web에서 제품이 소유한 영역(카드·목록 행·캔버스)의 우클릭·길게 누르기·Shift+F10에 명령 목록을 띄울 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native unsupported | 배포 |
-| [ConversationRow](components/conversation-row.md) | — | 대화 목록에서 상대, 마지막 메시지, 상대 시각, 안 읽음 점을 표시한다. | 1.24.0 | Web · Native | 개별 API 계약 참조 | 실험 |
+| [ConversationRow](components/conversation-row.md) | 화면/소통 | 대화 목록에서 상대, 마지막 메시지, 상대 시각, 안 읽음 점을 표시한다. | 1.24.0 | Web · Native | 개별 API 계약 참조 | 실험 |
+| [ConversionFunnel](components/conversion-funnel.md) | 구성/정보 표시 | 순차 단계(열기 → 작성 → 저장 등)의 인원을 가로 막대로 보여 주고, 단계를 골라 전체 대비·직전 대비 전환율과 이탈 수를 문구로 읽을 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [CorrelationMatrix](components/correlation-matrix.md) | 구성/정보 표시 | 여러 지표 사이의 상관계수(-1~1)를 정사각 대칭 표와 양·음 두 방향 heat 색으로 보여 줄 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [CounterBadge](components/counter-badge.md) | 데이터 표시 | 읽지 않은 알림·메시지·장바구니 수처럼 **셀 수 있는 개수**를 아이콘·행 옆에 작게 보일 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [DataTable](components/data-table.md) | 데이터 표시 | 여러 행의 데이터를 열로 맞춰 훑고, 열 기준으로 정렬하거나 행을 골라 일괄 작업할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native beta | 배포 |
 | [DatePicker](components/date-picker.md) | 입력 | 폼·필터 자리에서 날짜 **하나**를 고를 때 쓴다(생년월일, 방문일, 시작일 필터). 평소에는 필드 트리거만 보이고, 누르면 Web은 필드에 붙은 팝오버, Native는 Sheet 안에 같은 달력 격자를 연다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
@@ -82,17 +88,26 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [EditorScreen](components/editor-screen.md) | 화면/콘텐츠 | 글쓰기·프로필 수정처럼 한 화면 전체가 편집 흐름일 때 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [EffectSurface](components/effect-surface.md) | 시각 효과 | 환영·온보딩·빈 히어로처럼 분위기를 주는 배경이 필요할 때 내용 뒤에 장식 레이어(mesh·glow·grain)를 깐다. | 1.12.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [EmptyState](components/empty-state.md) | 상태와 알림 | 목록이 비었거나 검색 결과가 0건이라 **아직 없음**을 알릴 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [EventAttendanceCard](components/event-attendance-card.md) | 구성/선택과 필터 | 행사·모임 카드에서 일정, 참석자 수, 참석자 목록을 보여 주고 참석 응답(참석·미정·불참 등)과 캘린더 추가를 실제 요청으로 처리할 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [ExpandableSearch](components/expandable-search.md) | 구성/선택과 필터 | 평소에는 검색 열기 버튼 하나만 두고, 누르면 그 자리에서 검색 입력·제안·최근 검색·결과를 펼칠 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Field](components/field.md) | 입력 | 라벨·도움말·오류를 가진 입력 칸에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [FilePicker](components/file-picker.md) | 입력 | 사용자가 업로드할 로컬 파일을 고르게 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [FilterRecovery](components/filter-recovery.md) | 구성/피드백과 복구 | 검색·필터 결과가 비었을 때 실제로 결과가 생기는 필터 완화 제안을 보여 주고, 사용자가 고른 하나를 명시적으로 적용할 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [FloatingActionButton](components/floating-action-button.md) | 동작 | 목록·피드처럼 스크롤되는 콘텐츠 위에 떠 있는 **단일 생성 행동**(새 기록 추가, 새 글 작성)에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [FollowProfileCard](components/follow-profile-card.md) | 구성/정보 표시 | 프로필 카드에서 팔로우·팔로잉 전환과 팔로워 수를 실제 mutation 결과와 함께 보여 줄 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Form](components/form.md) | 입력 | 여러 Field를 한 화면에 쌓고 한 번에 제출할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Grid](components/grid.md) | 레이아웃 | 카드·타일처럼 같은 모양의 자식을 창 크기에 따라 열 수를 바꿔 배치할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Heading](components/heading.md) | 글자와 아이콘 | 자리를 모르는 큰 제목 글자 하나가 필요할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [HistogramExplorer](components/histogram-explorer.md) | 구성/정보 표시 | 실제 관측값 배열의 분포를 동폭 구간 막대로 보여 주고, 사용자가 구간 수를 바꿔 볼 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Icon](components/icon.md) | 글자와 아이콘 | HJM semantic 이름(`search`, `back`, `chevronEnd`, `notifications` 등 43개)으로 고르는 그림 기호에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [IconButton](components/icon-button.md) | 동작 | 보이는 글자 없이 아이콘만으로 표시하는 행동에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
-| [IconTile](components/icon-tile.md) | — | 프로필·런처 격자의 아이콘 위/제목 아래 항목에 쓴다. | 미게시(1.25.0 이후) | Web · Native | 개별 API 계약 참조 | 실험 |
+| [IconTile](components/icon-tile.md) | — | 프로필·런처 격자의 아이콘 위/제목 아래 항목에 쓴다. | 1.26.0 | Web · Native | 개별 API 계약 참조 | 실험 |
 | [Image](components/image.md) | 데이터 표시 | 원본 크기를 아는 사진·차트 이미지를 로드 전에 자리를 잡아 두고, 실패해도 의미를 잃지 않게 보여 줄 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [ImageChoiceGroup](components/image-choice-group.md) | 화면/계정 | 아바타 얼굴, 프로필 사진, 모음에 넣을 사진처럼 **그림을 보고 고르는** 단일·다중 선택에 쓴다. | 미게시(1.26.1 이후) | Web · Native | Web beta / Native beta | 배포 |
 | [ImageComparison](components/image-comparison.md) | 데이터 표시 | 같은 좌표와 비율의 두 이미지를 겹쳐 변화량을 비교할 때 쓴다. | 1.14.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [ImportFieldMapping](components/import-field-mapping.md) | 구성/입력과 작성 | CSV 등 원본 열을 제품의 대상 필드에 연결하고, 검증을 통과한 연결만 가져오기로 넘길 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [InlineEdit](components/inline-edit.md) | 구성/입력과 작성 | 목록·상세의 제목처럼 이미 확정된 짧은 값 하나를 그 자리에서 명시적으로 편집·저장·취소할 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [KeyboardAvoidanceContext](components/keyboard-avoidance-context.md) | — | 제품이 직접 만든 키보드 대응 영역 안에서 HJM `ScreenLayout`·`Sheet`가 여백을 두 번 주지 않게 할 때 쓴다. | 미게시(1.26.1 이후) | Native | 개별 API 계약 참조 | 실험 |
 | [KeyboardAvoiding](components/keyboard-avoiding.md) | — | 추가 native peer 없이 하단 행동(BottomCTA, 채팅 입력창)이 소프트웨어 키보드에 가려지지 않게 할 때 쓴다. | 1.12.1 | Native | 개별 API 계약 참조 | 배포 |
 | [KeyboardDock](components/keyboard-dock.md) | 구성/직접 조작과 모션 | `react-native-keyboard-controller`를 설치한 앱에서 화면 하단에 고정된 행동(BottomCTA, 채팅 입력창)이 키보드와 함께 위아래로 움직이게 할 때 쓴다(Native 전용, 별도 보조 기능. API 성숙도는 실험적 어댑터). 내부는 `KeyboardStickyView`이며, 여백을 바꾸는 대신 키보드 움직임을 따라 translate 한다. | 1.12.1 | Native | 개별 API 계약 참조 | 배포 |
 | [KeyboardFormScrollView](components/keyboard-form-scroll-view.md) | 구성/직접 조작과 모션 | 입력 필드가 여러 개인 세로 스크롤 폼(가입, 프로필 수정, 주소 입력)에서 포커스된 필드가 키보드에 가려지지 않게 스크롤해 줄 때 쓴다(Native 전용, 별도 보조 기능. API 성숙도는 실험적 어댑터). 내부는 `react-native-keyboard-controller`의 `KeyboardAwareScrollView`이고, `keyboardShouldPersistTaps="handled"`로 고정돼 키보드가 열린 채 버튼을 눌러도 탭이 전달된다. | 1.12.1 | Native | 개별 API 계약 참조 | 배포 |
@@ -105,6 +120,7 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [LoadMore](components/load-more.md) | 탐색 | 이미 그린 항목을 그대로 둔 채 목록 끝에서 다음 페이지를 요청하는 footer에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Masonry](components/masonry.md) | 레이아웃 | 높이가 서로 다른 카드(사진 피드, 핀보드, 갤러리)를 여러 열에 빈틈없이 쌓을 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [MediaSelectionScreen](components/media-selection-screen.md) | 화면/콘텐츠 | 고른 사진·영상을 큰 썸네일 격자로 보여 주고, 각 항목의 업로드 상태·재시도·취소·순서 이동·삭제와 "추가"·"완료" 행동을 한 화면에 묶을 때 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [MediaTransport](components/media-transport.md) | 구성/직접 조작과 모션 | 제품의 실제 오디오·영상 엔진에 재생·일시 정지·유한 길이 탐색 제어를 붙일 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Mentions](components/mentions.md) | 입력 | 여러 줄 입력 중 `@`(사람)·`#`(해시태그) 같은 트리거를 치면 후보를 띄우고, 고른 후보를 트리거부터 커서까지 자리에 넣고 공백 하나를 붙이는 입력에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Menu](components/menu.md) | 탐색 | 트리거 버튼을 누르면 뜨는 **항목 목록**에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Menubar](components/menubar.md) | 탐색 | 데스크톱 Web 앱 상단에 항상 같은 자리에 있는 가로 메뉴 막대(파일·편집·보기)에 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
@@ -113,24 +129,29 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [Notice](components/notice.md) | 상태와 알림 | 화면 흐름 안 **제자리에 남아 있는** 상태 알림에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [NotificationInboxScreen](components/notification-inbox-screen.md) | 화면/소통 | 알림함 화면 전체 틀에 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [NotificationItem](components/notification-item.md) | 구성/정보 표시 | 알림함의 알림 한 행에 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
-| [NotificationRow](components/notification-row.md) | — | 알림 목록에서 아바타, 유형 배지, 미리보기, 시간, 읽지 않음 표시, 선택적 썸네일을 나란히 배치한다. |  | Web · Native | 개별 API 계약 참조 | 후보 |
+| [NotificationRow](components/notification-row.md) | — | 알림 목록에서 아바타, 유형 배지, 미리보기, 시간, 읽지 않음 표시, 선택적 썸네일을 나란히 배치한다. | 1.26.0 | Web · Native | 개별 API 계약 참조 | 실험 |
 | [NumberField](components/number-field.md) | 입력 | 범위가 정해진 **정확한 수 하나**를 입력받을 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [OnboardingScreen](components/onboarding-screen.md) | 화면/소개 | 첫 실행 소개·초기 설정처럼 **몇 단계를 차례로 넘기는 화면**에 쓴다. | 1.14.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [OtpField](components/otp-field.md) | 입력 | 문자·메일로 받은 **숫자 인증번호**를 칸 모양으로 입력받을 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [OverviewScreen](components/overview-screen.md) | 레이아웃 | 같은 데이터와 기능을 유지하면서 테마별 행·카드·격자와 도구 배치를 선택하는 목록 화면에 쓴다. | 1.15.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Pagination](components/pagination.md) | 탐색 | 총 개수(또는 총 페이지 수)가 정해진 결과 집합에서 사용자가 **임의의 페이지로 바로 이동**해야 할 때 Web·Native에서 쓴다. | 1.12.1 | Web · Native | Web stable / Native beta | 배포 |
 | [PasswordField](components/password-field.md) | 입력 | 비밀번호를 입력받고, 필요할 때만 값을 눈으로 확인하게 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [PasswordRulesField](components/password-rules-field.md) | 구성/입력과 작성 | 새 비밀번호 입력 아래에 제품이 정한 규칙의 충족 개수와 규칙별 상태를 함께 보여 줄 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [PermissionScreen](components/permission-screen.md) | 화면/소개 | 카메라·위치·알림 같은 권한이 **왜 필요한지 설명하고 다음 행동을 고르게 하는** 화면에 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [PhotoSourceSheet](components/photo-source-sheet.md) | 구성/선택과 필터 | 사진 버튼 하나에서 **앨범에서 고르기 / 촬영하기**를 고르게 할 때 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Popover](components/popover.md) | 오버레이 | 트리거에 붙어 뜨는 비모달 표면 안에 **포커스를 받는 임의 콘텐츠**를 둘 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
+| [PricingChoice](components/pricing-choice.md) | 구성/선택과 필터 | 요금제·결제 주기 중 하나를 고르고, 선택한 실제 가격과 혜택을 확인한 뒤 [계속]으로 제품 결제 흐름을 시작할 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [ProfileScreen](components/profile-screen.md) | 화면/계정 | 내 프로필(또는 계정) 화면 틀에 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
-| [ProfileSummary](components/profile-summary.md) | — | 프로필의 아바타·이름·배지·통계 수치·행동을 구성한다. |  | Web · Native | 개별 API 계약 참조 | 후보 |
+| [ProfileSummary](components/profile-summary.md) | — | 프로필의 아바타·이름·배지·통계 수치·행동을 구성한다. | 1.26.0 | Web · Native | 개별 API 계약 참조 | 실험 |
 | [Progress](components/progress.md) | 상태와 알림 | 작업이 얼마나 진행됐는지 보여 줄 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [ProgressiveBlur](components/progressive-blur.md) | 시각 효과 | 스크롤 영역의 바깥에 더 내용이 있음을 알리거나 장식 이미지 가장자리를 흐릴 때 쓴다. | 1.14.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [QRCode](components/qr-code.md) | 데이터 표시 | 문자열(초대 링크, 연결 코드, 결제·체크인 URL)을 다른 기기의 카메라로 스캔하게 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Radio](components/radio.md) | 입력 | 라디오 한 개를 제품이 직접 배치해야 할 때만 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [RadioGroup](components/radio-group.md) | 입력 | 한 화면에 펼쳐 둔 선택지 중 정확히 하나를 고를 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Rating](components/rating.md) | 입력 | 정수 점수를 선택하거나 계산된 소수 평균을 읽기 전용으로 보여 줄 때 쓴다. | 1.14.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [RepeatableFieldGroup](components/repeatable-field-group.md) | 구성/입력과 작성 | 참여자 이름·연락처처럼 같은 입력 행을 사용자가 추가·삭제하는 묶음에 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [ReplyComposer](components/reply-composer.md) | 구성/입력과 작성 | 답장 대상(실제 메시지 id·저자·발췌)을 가진 작성창에서 실제 전송 Promise를 기다리고, 실패하면 초안을 보존해 다시 보낼 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
+| [ReplyMessage](components/reply-message.md) | 구성/입력과 작성 | 대화 타임라인의 메시지에 실제 메시지 id를 묶은 답장 동작을 붙일 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Result](components/result.md) | 상태와 알림 | 사용자 행동 뒤 흐름이 **끝난** 화면에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [SavedItemsScreen](components/saved-items-screen.md) | 화면/콘텐츠 | 저장한 이미지·게시물을 컬렉션 표지 → 사진 격자 → 상세 순서로 탐색할 때 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [ScreenLayout](components/screen-layout.md) | 화면/화면 틀과 도구 | 한 라우트 화면의 뼈대가 필요할 때 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
@@ -139,10 +160,12 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [Section](components/section.md) | 레이아웃 | 화면 안의 내용 묶음에 제목·설명·머리 행동(“모두 보기”, “편집”)을 붙일 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [SegmentedControl](components/segmented-control.md) | 입력 | 2~4개의 짧은 보기 중 **항상 하나가 선택된** 전환에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Select](components/select.md) | 입력 | 폼 한 칸에서 여러 선택지 중 하나를 고르게 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [SelectionActionBar](components/selection-action-bar.md) | 구성/선택과 필터 | 목록에서 여러 항목을 고른 뒤 보관·삭제 같은 같은 행동을 한 번에 실행하고, 방금 확정된 작업만 되돌릴 때 쓴다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [SettingsScreen](components/settings-screen.md) | 화면/설정 | 앱의 설정 화면 전체에 쓴다. | 1.17.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [SharedTransitionElement](components/shared-transition-element.md) | 구성/직접 조작과 모션 | 목록의 카드(사진·썸네일)를 눌러 상세 화면으로 갈 때, 같은 요소가 두 화면 사이에서 확대·축소되어 이어지는 공유 요소 전환에 쓴다. | 1.12.1 | Native | 개별 API 계약 참조 | 배포 |
 | [SharedTransitionScreen](components/shared-transition-screen.md) | 구성/직접 조작과 모션 | `createHjmTransitionStack()`으로 만든 stack에서 공유 요소 전환을 쓸 때, **각 라우트 본문**을 감싼다. | 1.12.1 | Native | 개별 API 계약 참조 | 배포 |
 | [Sheet](components/sheet.md) | 오버레이 | 현재 화면 위에 모달로 띄우는 보조 작업 패널에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [ShortcutRecorder](components/shortcut-recorder.md) | 구성/직접 조작과 모션 | Web 앱에서 사용자가 수정키+키 조합을 눌러 기록하고, 확인 뒤 실제 단축키로 등록하게 할 때 쓴다. | 1.21.0 | Web | 개별 API 계약 참조 | 배포 |
 | [Sidebar](components/sidebar.md) | 탐색 | 데스크톱 Web의 세로 내비게이션에 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [SidePanel](components/side-panel.md) | 오버레이 | Web 화면 가장자리(시작·끝)에 도킹되어 밀려 나오는 보조 패널에 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [Skeleton](components/skeleton.md) | 상태와 알림 | 데이터가 오기 전, 곧 채워질 콘텐츠의 **모양을 미리 보여 줄 때** 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
@@ -150,16 +173,20 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [Slider](components/slider.md) | 입력 | 범위 안에서 값 하나를 대략적으로, 연속 조작으로 고를 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [SortableCollection](components/sortable-collection.md) | 입력 | 작은 목록의 순서를 사용자가 바꾸고, 그 순서를 제품이 저장할 때 쓴다(즐겨찾기 순서, 할 일 순서 등). 드래그와 함께 각 행에 "앞으로/뒤로" 버튼과 키보드·접근성 action이 항상 붙는다. | 1.12.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Spinner](components/spinner.md) | 상태와 알림 | 진행량을 모르고 도착할 내용의 모양도 정해지지 않은 **짧은 대기**를 한 자리에서 알릴 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [SplitAction](components/split-action.md) | 구성/입력과 작성 | 실행 버튼 하나와 실행 방식 선택 메뉴를 나란히 둔다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Splitter](components/splitter.md) | 레이아웃 | 넓은 Web 화면에서 두 영역의 경계를 사용자가 드래그나 키보드로 옮겨 크기를 정할 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [Stack](components/stack.md) | 레이아웃 | 자식들을 한 방향으로 늘어놓고 사이 간격을 토큰으로 맞출 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Statistic](components/statistic.md) | 데이터 표시 | 라벨이 붙은 **숫자 지표 하나**(또는 여러 개)를 보여 줄 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Steps](components/steps.md) | 탐색 | 여러 단계로 된 **선형 흐름에서 지금 어디인지** 보여 줄 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [StreamingAnswer](components/streaming-answer.md) | 구성/피드백과 복구 | AI 응답처럼 제공자가 조각(`delta`)으로 보내는 답을 받는 대로 표시하고, 생성·다시 생성·중지를 한 묶음으로 제공한다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Surface](components/surface.md) | 레이아웃 | 배경·테두리·radius를 가진 **의미 없는 상자**가 필요할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [SwipeActions](components/swipe-actions.md) | 구성/직접 조작과 모션 | 목록 행 하나에 붙은 **삭제·보관 같은 행 단위 행동**을, Native에서는 행을 밀어 드러내고 Web에서는 행 아래 버튼으로 바로 보여 줄 때 쓴다. | 1.12.1 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Switch](components/switch.md) | 입력 | 켜고 끄는 즉시 반영되는 설정 하나에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [TableColumnSettings](components/table-column-settings.md) | 구성/선택과 필터 | 표의 열마다 보이기 체크박스와 앞으로·뒤로 이동 버튼을 제공해 열 표시와 순서를 바꾼다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Tabs](components/tabs.md) | 탐색 | 같은 화면 안에서 **서로 다른 패널 여러 개 중 하나를 보여 줄 때** 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Tag](components/tag.md) | 데이터 표시 | 반복해서 나오는 **정적 메타데이터 한 조각**에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [TagsInput](components/tags-input.md) | 입력 | 사용자가 **자유 입력으로 여러 값을 모으는 필드**에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [TargetSummary](components/target-summary.md) | 구성/정보 표시 | 실적과 목표를 받아 실적 수치, 달성 설명, 달성률 막대를 한 묶음으로 보여 준다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Text](components/text.md) | 글자와 아이콘 | 화면의 모든 일반 글자에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [TextArea](components/text-area.md) | 입력 | 여러 줄 자유 글을 받는 입력에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [TextFormat](components/text-format.md) | 글자와 아이콘 | 도움말·개발자 안내·약관 본문 안에서 단축키(`⌘S`), 짧은 코드 조각(`pnpm add …`), 인용문을 표시할 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
@@ -167,12 +194,14 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [ThinkingOrb](components/thinking-orb.md) | 상태와 알림 | AI 에이전트가 실제로 검색·생성·듣기 같은 작업을 하는 동안 그 단계를 보여 줄 때만 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Timeline](components/timeline.md) | 데이터 표시 | 이미 일어난 일을 시간 순서대로 보여 줄 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Toast](components/toast.md) | 상태와 알림 | 방금 한 행동의 결과처럼 **무시해도 안전한 짧은 알림**에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [ToggleFeedbackButton](components/toggle-feedback-button.md) | 구성/직접 조작과 모션 | 좋아요·저장·알림 받기처럼 켜고 끄는 선택에 반응 모션과 개수를 붙인다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [ToggleGroup](components/toggle-group.md) | 입력 | 여러 개를 동시에 켜고 끄는 짧은 버튼 묶음에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Tooltip](components/tooltip.md) | 오버레이 | Web에서 이미 이름과 focus를 가진 컨트롤(대개 IconButton)에 **짧은 보충 설명 한 문장**을 붙일 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [Top](components/top.md) | 레이아웃 | 화면 **본문의 첫 블록**에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [TopBar](components/top-bar.md) | 탐색 | 화면 맨 위에 붙는 **크롬**에 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [Tour](components/tour.md) | 오버레이 | 새 화면·새 기능을 처음 만난 사용자에게 화면의 여러 요소를 순서대로 짚어 설명할 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [TransferList](components/transfer-list.md) | 입력 | 한 항목 집합을 두 목록으로 나누고 사용자가 항목을 오가게 할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
+| [TransferTask](components/transfer-task.md) | 구성/피드백과 복구 | 업로드·다운로드·동기화처럼 실제 전송 계층이 진행량을 알려 주는 작업에 시작·취소·진행률·결과를 한 묶음으로 붙인다. | 1.21.0 | Web · Native | 개별 API 계약 참조 | 배포 |
 | [Tree](components/tree.md) | 데이터 표시 | 깊이가 정해지지 않은 계층 데이터를 펼치고 접으며 탐색하고, 그 안에서 하나 또는 여럿을 고를 때 쓴다. | 1.12.1 | Web | Web stable / Native unsupported | 배포 |
 | [UploadItem](components/upload-item.md) | 데이터 표시 | 사용자가 고른 파일 **한 개**의 업로드 상태(대기·전송 중·완료·실패)를 한 행으로 보여 줄 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
 | [VirtualList](components/virtual-list.md) | 데이터 표시 | 행 높이가 **모두 같은** 긴 목록(수백~수천 행)을 정해진 높이 안에서 스크롤할 때 쓴다. | 1.12.1 | Web · Native | Web stable / Native stable | 배포 |
@@ -206,9 +235,9 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [사진 촬영과 앨범 선택](compositions/photo-source.md) | 선택과 필터 | 명시적으로 선택 후 플랫폼 picker 실행 흐름이 필요할 때 쓴다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
 | [선택 후 적용·취소](compositions/interaction-flow-apply.md) | 선택과 필터 | 표시 방식·정렬·필터처럼 시트에서 여러 번 바꿔 본 뒤 적용을 눌러야 화면에 반영되고, 취소하거나 닫으면 기존 선택을 유지해야 할 때 쓴다. | 1.12.1 | Web · Native | 구성 API별 | 배포 |
 | [시간 선택](compositions/time-selection.md) | 선택과 필터 | 알림 시각·마감 시각처럼 하루 안의 시각 하나를 시·분 두 Select로 나눠 고르게 할 때 쓴다. | 1.12.1 | Web · Native | 구성 API별 | 배포 |
-| [펼치는 검색과 실제 메시지 답장](compositions/communication.md) | 선택과 필터 | 상단 검색 버튼에서 검색 영역을 펼치거나 채팅의 실제 메시지를 선택해 답장을 전송할 때 쓴다. | 1.21.0 | Web · Native | 구성 API별 | 배포 |
+| [펼치는 검색과 실제 메시지 답장](compositions/communication.md) | 선택과 필터 | 검색 아이콘 버튼에서 검색 영역을 펼치거나 채팅의 실제 메시지를 선택해 답장을 전송할 때 쓴다. | 1.21.0 | Web · Native | 구성 API별 | 배포 |
 | [보관함과 페이지 이동](compositions/web-navigation.md) | 탐색과 이동 | Web에서 상위 보관함 → 하위 모음으로 들어가고, 그 모음의 긴 목록을 페이지 단위로 넘겨 보는 탐색에 쓴다. | 1.12.1 | Web | 구성 API별 | 배포 |
-| [펼침과 메뉴](compositions/disclosure.md) | 탐색과 이동 | Web에서 내용을 숨겼다 펼치거나(Collapsible), 대상에 붙은 작업 메뉴를 우클릭·키보드로 열거나(ContextMenu), 데스크톱 앱처럼 상단 메뉴 막대를 두는(Menubar) 세 방식을 각각 보여 주는 모음이다. | 1.12.1 | Web | 구성 API별 | 배포 |
+| [펼침과 메뉴](compositions/disclosure.md) | 탐색과 이동 | 내용을 숨겼다 펼치거나(Collapsible), Web에서 대상에 붙은 작업 메뉴를 우클릭·키보드로 열거나(ContextMenu), 데스크톱 앱처럼 상단 메뉴 막대를 두는(Menubar) 세 방식을 각각 보여 주는 모음이다. | 1.12.1 | Web · Native | 구성 API별 | 배포 |
 | [대화 메시지](compositions/common-message.md) | 정보 표시 | 말풍선 하나하나에 반응·답장·원문 이동·전송 실패 후 다시 보내기를 붙일 때 쓴다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
 | [명령 기록 표시](compositions/command-records.md) | 정보 표시 | 명령 원문과 출력 기록을 선택·읽기·복사할 때 쓴다. | 1.16.0 | Web · Native | 구성 API별 | 배포 |
 | [문서와 파일](compositions/document-resource.md) | 정보 표시 | 이름·형식·크기와 미리보기·내보내기·별도 메뉴를 함께 제공하는 문서에 쓴다. | 1.14.0 | Web · Native | 구성 API별 | 배포 |
@@ -251,7 +280,7 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [웹 전용 보조 컴포넌트](compositions/web-additions.md) | 비교와 검증 | Web에만 있는 보조 컴포넌트 세 개(색 고르기, 문서 워터마크, 스크롤 중 고정되는 실행 영역)를 실제 쓰임 하나씩과 함께 보여 주는 모음이다. | 1.12.1 | Web | 구성 API별 | 배포 |
 | [종이 줄무늬 비교](compositions/paper-surface.md) | 비교와 검증 | 같은 입력·기록에서 종이 preset의 grain+ruled 상속과 앱이 지정한 평면/줄무늬 표현을 비교한다. | 1.16.0 | Web · Native | 구성 API별 | 배포 |
 | [테마 조합](compositions/design-profile-comparison.md) | 비교와 검증 | 같은 기능에 10가지 표현을 적용하고, 앱 소유 테마 설정을 넣었을 때 네 단계의 전파와 상태 유지를 검토할 때 쓴다. | 1.16.0 | Web · Native | 구성 API별 | 배포 |
-| [토스트 배치 비교](compositions/toast-layout.md) | 비교와 검증 | Toast 카드 한 장의 내부 배치(톤 배지·제목·설명·닫기·실행 버튼)와 화면 위 위치를 좁은 폭·큰 글자·긴 문구·톤별로 확인하는 비교 스토리다. | 1.12.1 | Web | 구성 API별 | 배포 |
+| [토스트 배치 비교](compositions/toast-layout.md) | 비교와 검증 | Toast 카드 한 장의 내부 배치(톤 배지·제목·설명·닫기·실행 버튼)와 화면 위 위치를 좁은 폭·큰 글자·긴 문구·톤별로 확인하는 비교 스토리다. | 1.12.1 | Web · Native | 구성 API별 | 배포 |
 | [환경 조합 검증](compositions/environment-matrix.md) | 비교와 검증 | 제품 화면이 테마·쓰기 방향·글자 크기·모션 설정이 달라져도 같은 의미를 유지하는지 확인할 때, 어떤 환경 조합과 검증 항목을 골라 볼지 정하는 기준표로 쓴다. | 1.12.1 | Web | 구성 API별 | 배포 |
 
 ## 화면
@@ -273,6 +302,7 @@ Storybook 배포/실험은 예제 분류이며 npm 게시·기기 검증·제품
 | [사진 선택과 업로드](screens/flow-media.md) | 콘텐츠 | MediaSelectionScreen을 사용해 사진 선택과 업로드 흐름을 구성한다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
 | [작성과 수정](screens/flow-editor.md) | 콘텐츠 | EditorScreen을 사용해 작성과 수정 흐름을 구성한다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
 | [저장한 항목](screens/common-saved.md) | 콘텐츠 | SavedItemsScreen을 사용해 저장한 항목 흐름을 구성한다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
+| [대화 목록](screens/common-conversation-list.md) | 소통 | DM·채팅방 목록에서 상대·마지막 메시지·시각·읽지 않음을 훑고, 행을 눌러 대화로 들어가며, 길게 눌러 행 단위 동작(읽지 않음 표시·알림 해제·차단·삭제)을 고른다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 실험 |
 | [댓글](screens/common-comments.md) | 소통 | CommentThreadScreen을 사용해 댓글 흐름을 구성한다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
 | [신고와 차단](screens/flow-moderation.md) | 소통 | ModerationScreen을 사용해 신고와 차단 흐름을 구성한다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |
 | [알림함](screens/common-inbox.md) | 소통 | NotificationInboxScreen을 사용해 알림함 흐름을 구성한다. | 구성 API 지침 참조 | Web · Native | 구성 API별 | 배포 |

package/docs/usage/SELECTION.md

@@ -1,10 +1,9 @@
 # 화면과 구성 선택
 
-검토일: 2026-10-15
+검토일: 2026-10-17
 
-2026-10-15 사용자 요청: 메시지·댓글에서 같은 HJM 부품을 사용해도 앱이 기본 배치와 상태 표시를
-다시 조립하면서 UI가 달라졌다. 이 선택 기준은 모든 화면·구성에 적용한다. **공통 구조는 HJM이
-완성해서 제공하고, 앱은 데이터·문구·브랜드·권한·추가 기능을 연결한다.**
+이 선택 기준은 모든 화면·구성에 적용한다. **공통 구조는 HJM이 완성해서 제공하고, 앱은
+데이터·문구·브랜드·권한·추가 기능을 연결한다.** 도입 계기는 [근거](#근거)에 있다.
 
 ## 선택 기준
 
@@ -29,6 +28,27 @@
 제품에서 동일한 기본 구조를 다시 만드는 허용 경로로 해석하지 않는다. 배지는 의미·값을 앱이
 결정하고 위치·간격·넘침 표현은 해당 HJM 구성과 Badge 계약을 따른다.
 
+## 조립 규칙(필수)
+
+예제·제품 화면 모두 아래 표의 컴포넌트를 쓴다. 버튼·글자로 대체 조립하지 않는다.
+
+| 의도 | 쓸 것 | 쓰지 않을 것 |
+| --- | --- | --- |
+| 하나 고르기(주제·정렬·탭) | `Chip`(`selectionMode="single"`), `SegmentedControl`, `RadioGroup`, `ToggleGroup` | `selected`를 준 `Button` 나열 |
+| 여러 개 고르기 | `Chip`(`selectionMode="multiple"`), `CheckboxGroup` | 버튼 토글 |
+| 켜고 끄기 설정 | `Switch`(제목·설명 포함), 설정 목록은 `ListRow` + `Switch` | "○○ 켜짐/꺼짐" 글자 버튼 |
+| 주 행동 | 화면 지침의 "버튼과 행동 위치"대로 하나의 primary, 하단 고정이면 `BottomCTA`/`footer` | 같은 표면에 경쟁하는 primary 여럿, 폭이 제각각인 버튼 줄 |
+| 보조 행동 | 주 행동 아래 같은 폭 secondary, 또는 헤더 `actions` | 본문 중간에 흩어진 버튼, 나가기를 보조 행동으로 두기 |
+| 상태·결과 안내 | `Notice`, `Badge`, `ListRow` 설명 | 가운데 정렬 일반 글자 |
+| 예제 전용 도구(실패 예약 등) | "미리보기 도구" 캡션 아래 `Button size="small" tone="ghost"`로 분리 | 제품 행동과 같은 모양·폭 |
+| 헤더 제목·추가 기능 | 제목은 기본 가운데(`ScreenLayout`·`TopBar`, 왼쪽 정렬은 선택), 추가 기능은 `actions`에 아이콘 버튼 1~2개로 오른쪽 위(`ScreenFlowAction.icon`, 넘치면 Menu) | 왼쪽 정렬 제목, 헤더의 글자 버튼(가운데 제목을 밀어냄), 본문에 흩어진 도구 버튼 |
+| 도구성 행동(새로고침·추가·편집·삭제·공유·검색·필터·더보기) | `IconButton` + 아이콘, 글자는 `label`(보조기술 이름). HJM 화면은 아이콘 슬롯(`ScreenFlowAction.icon` 등) | 헤더·행·도구 막대의 글자 버튼 |
+| 화면 나가기(뒤로·닫기·설정 나가기) | `ScreenLayout`(과 이를 쓰는 화면)의 `exit` — 헤더 시작 쪽 아이콘 버튼, 글자 없음 | 본문·하단의 "나가기" 글자 버튼, 화면마다 다른 화살표 |
+| 버튼 묶음 간격 | 세로로 쌓으면 `gap="xs"`(8), 가로로 나란하면 `gap="sm"`(12) — `actionGroupRecipe` | 세로 버튼 사이 12 이상 |
+| 간격 | `Stack`·`ScreenLayout`·recipe 간격 | 임의 `margin`·빈 `View` |
+
+리뷰 기준: 위 "쓰지 않을 것" 패턴이 보이면 예제 조립 문제인지 컴포넌트 recipe 문제인지 먼저 가리고, 원인 쪽(예제 또는 HJM 컴포넌트)을 고친다.
+
 ## 구현과 확인
 
 - 화면 → 구성 → 컴포넌트 → 토큰 순으로 찾고 기존 공개 API와 양 renderer를 먼저 확인한다.
@@ -54,3 +74,9 @@
 
 구성·화면은 여러 API를 사용하므로 별도 라이브러리 버전을 복제하지 않고 각 API 지침을 참조한다.
 설치 버전보다 새 문서의 prop은 설치된 타입과 export에서 다시 확인한다.
+
+## 근거
+
+- 선택 기준·소유권: 2026-10-15 사용자 요청 — 메시지·댓글에서 같은 HJM 부품을 쓰면서도 앱마다 기본 배치와 상태 표시를 다시 조립해 UI가 달라졌다.
+- 도구성 행동 아이콘 버튼: 2026-10-17 사용자 지시 — '나의 기록' 헤더의 새로고침·새 기록 글자 버튼.
+- 조립 규칙(필수): 2026-10-16 사용자 지적("UI가 구리다") — `배포/구성/피드백과 복구/변경 저장과 이탈 확인` 예제가 선택을 버튼으로, 켜고 끄기를 글자 버튼으로 흉내 내 선택 상태가 테두리 없는 글자로만 보이고 버튼 폭이 제각각이었다.

package/docs/usage/STANDARD.md

@@ -1,6 +1,6 @@
 # 사용 지침 규격
 
-검토일: 2026-10-13 · 선택적 형식 감사: `pnpm usage:check`(`scripts/check-usage-docs.mjs`)
+검토일: 2026-10-17 · 선택적 형식 감사: `pnpm usage:check`(`scripts/check-usage-docs.mjs`)
 
 2026-10-06 사용자 요청: 지침은 단계마다 같은 규격으로 나와야 한다. 그래야 에이전트가 어느 지침을 열어도
 같은 자리에서 같은 정보(위치·크기·간격·순서·상태)를 찾고, 빠진 정보를 검사기가 잡는다. 자유 형식이던
@@ -10,7 +10,9 @@
 ## 1. 공통
 
 화면·구성은 [소유권](SELECTION.md#소유권)에 맞춰 HJM 공개 구현과 앱의 데이터/확장 입력을 구분한다.
-기본 배치·상태·배지·상호작용을 제품이 재조립하도록 안내하지 않는다. 실행 예제만 있는 조합은
+기본 배치·상태·배지·상호작용을 제품이 재조립하도록 안내하지 않는다. 의도별 행동 위치는
+[선택 기준](SELECTION.md#조립-규칙필수), 정확한 값·기본값은 contracts recipe와 공개 타입이 소유한다.
+개별 지침은 해당 정본을 참조하고 다른 순서·숫자를 별도 규칙으로 만들지 않는다. 실행 예제만 있는 조합은
 공개 구현 여부를 명시하고, 예제를 앱에 복사하는 대신 기존 HJM API를 보완한다.
 
 
@@ -51,6 +53,9 @@
 - 코드 예는 `strict` + `exactOptionalPropertyTypes`로 실제 공개 타입을 확인한다. `usage:check`는 문서 형식 검사이며 타입 검사 결과가 아니다.
 - 같은 예제를 문서와 Storybook에 복사하지 않는다. 실행되는 TSX 원본을 참조할 수 있으며 플랫폼마다
   `<!-- usage-example: Web 상대/경로.tsx -->` 또는 `Native` 표시와 읽을 수 있는 링크를 함께 둔다.
+  읽을 수 있는 링크는 npm에 포함되지 않는 `showcase/` 상대 경로 대신 확인한 commit SHA의 저장소 URL을 쓴다.
+  설치 후 예제 링크가 끊긴 2026-10-17 점검에 따른 규칙이다. 예제를 바꿀 때 링크의 SHA도 함께 갱신하고,
+  해당 SHA의 예제와 설치 버전의 공개 타입을 구분한다. 로컬 marker는 작성 시 원본 존재 확인용이다.
   검사기는 참조 파일의 존재만 확인한다. 변경한 원본은 해당 Showcase 타입 검사 또는 파일 지정 타입 검사로 확인한다.
   2026-10-13 설정 화면의 중복 코드 골격을 실제 Web/Native preview 참조로 교체했다. 제품은 예제를 읽고 공개 API를 사용하며 showcase를 import하지 않는다.
 - 배치도는 ```text 블록 ASCII. 위→아래, 주 행동·보조 행동·고정 영역·스크롤 영역·안전 영역을 표시한다.
@@ -59,6 +64,10 @@
 - 링크: 같은 단계 `name.md`, 다른 단계 `../<폴더>/name.md`, 계약 문서 `../../<doc>.md`.
 - 문체: 한국어 평서체(-다).
 
+- 규칙과 근거를 나눈다. 본문(꼭 지킬 것·배치·상태 등)에는 규칙만 쓰고, 규칙이 생긴 계기(날짜·실측·사고·사용자 지시)는
+  문서 끝 `## 근거` 절에 "규칙 이름: 날짜 계기" 한 줄로 남긴다. 근거를 지우지 않는다(포트폴리오 "결정에는 근거를 남긴다").
+  호환 버전·측정 결과처럼 사용에 필요한 날짜는 본문에 둔다.
+
 ## 2. 단계별 절과 표
 
 ### 토큰 (`tokens/`)