@hjmds/design-contracts 1.40.0 → 1.41.1

package/docs/usage/compositions/save-feedback.md

@@ -1,12 +1,12 @@
 # 저장 결과
 
 - 단계: 구성
-- 상태: 실험
+- 상태: 배포
 - 지원: Web · Native
 - 적용: 1.37.1
-- 검토일: 2026-10-20
+- 검토일: 2026-10-23
 - 근거: 사용자 요청으로 카드 안 저장 완료 예시(이전 3번)를 제거하고, 승인된 라이트·다크 토스트 시안으로 두 유형을 통일했다.
-- 스토리북: `실험/구성/피드백과 복구/저장 결과`
+- 스토리북: `배포/구성/피드백과 복구/저장 결과`
 
 ## 언제 쓰나
 
@@ -14,22 +14,22 @@
 
 ## 구성 요소
 
-| 유형 | 쓰는 상황 | 공개 API |
+| 컴포넌트 | 역할 | 지침 |
 | --- | --- | --- |
-| 1 · 한 줄 토스트 | 짧은 완료 확인 | Toast `description`, `tone="success"` |
-| 2 · 요약 토스트 | 저장한 대상까지 확인 | 같은 Toast의 `title` + `description` |
+| Toast(`description`, `tone="success"`) | 1 · 한 줄 토스트: 짧은 완료 확인 | [Toast](../components/toast.md) |
+| Toast(`title` + `description`) | 2 · 요약 토스트: 저장한 대상까지 확인 | [Toast](../components/toast.md) |
+| ToastProvider(Web) / ToastRegion(Native) | 앱 루트에서 표시 층·큐·타이머 소유 | [Toast](../components/toast.md) |
 
 두 유형은 별도 엔진이나 변형 prop이 아니다. 웹은 ToastProvider, Native는 ToastRegion을 앱 루트에 둔다. 카드형 저장 결과는 선택지에서 제거했다. 일반 Notice·Card·Badge의 다른 용도는 유지한다.
 
 ## 배치
 
-| 영역 | 위치·크기 |
-| --- | --- |
-| 바깥 틀 | 최대 폭 420, 최소 높이 56, 모서리 24 |
-| 화면 가장자리 | 16 + 안전 영역. 광고 footer가 있으면 상단 |
-| 내부 | 가로 16·세로 12, 첫 줄 기준 정렬, 닫기 터치 영역 44 유지 |
-| 한 줄 | 장식 아이콘 → 본문 → 닫기 |
-| 요약 | 제목 → 보조 설명, 오른쪽 닫기. 장식 아이콘은 생략; 제품 media는 유지 |
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Toast | 화면 가장자리 16 + 안전 영역. 광고 footer가 있으면 상단 | 최대 폭 420, 최소 높이 56, 모서리 24 |
+| 내부 | Toast | 첫 줄 기준 정렬 | 가로 16·세로 12, 닫기 터치 영역 44 유지 |
+| 한 줄 | Toast `description` | 장식 아이콘 → 본문 → 닫기 | — |
+| 요약 | Toast `title` + `description` | 제목 → 보조 설명, 오른쪽 닫기. 장식 아이콘은 생략; 제품 media는 유지 | — |
 
 ```text
 한 줄: [ ✓  KE123 저장했어요                  × ]
@@ -41,20 +41,42 @@
 
 ## 흐름과 상태
 
-| 상태 | 표시·행동 |
-| --- | --- |
-| 저장 중 | 기존 제출 상태, 성공 알림 없음 |
-| 성공 | 저장 응답/영속 저장 완료 후 토스트 한 장, polite 낭독 한 번 |
-| 실패 | 입력 보존, 기존 오류·재시도 |
+1. 사용자가 저장을 누르면 제품의 기존 제출 상태(버튼 pending 등)만 보여 준다. 이 단계에서는 토스트를 띄우지 않는다.
+2. 저장 응답이나 영속 저장이 끝난 뒤에만 고정 `id`로 `publish`해 토스트 한 장을 띄운다.
+3. 실패하면 토스트 대신 기존 오류·재시도 흐름을 쓰고 입력을 보존한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 토스트 없음 | — |
+| 진행 중 | 기존 제출 상태, 성공 알림 없음 | 포커스는 제출 버튼에 둔다 |
+| 성공 | 저장 응답/영속 저장 완료 후 토스트 한 장 | polite 낭독 한 번, 포커스를 옮기지 않는다 |
+| 실패 | 입력 보존, 기존 오류·재시도 | 기존 오류 안내가 낭독을 소유한다 |
 
 기본 3초이며 긴 요약은 제품에서 시간을 늘린다. 같은 성공을 카드 상태와 토스트로 중복 알리지 않는다. 이전 초안의 늦은 응답을 새 초안의 성공으로 표시하지 않는다.
 
 ## 코드 골격
 
 ```tsx
-// 영속 저장 성공 뒤; Native useToastRegion / Web useToast의 기존 publish.
-toast.publish({ id: "saved", description: savedLabel, tone: "success", closeLabel });
-toast.publish({ id: "saved", title: savedTitle, description: subjectSummary, tone: "success", closeLabel });
+// Web — ToastProvider 안에서, 영속 저장 성공 뒤에만 publish한다.
+import { useToast } from "@hjmds/react/toast";
+
+const toast = useToast();
+async function save() {
+  await persist(draft);
+  toast.publish({ id: "saved", description: savedLabel, tone: "success", closeLabel });
+  // 대상 요약형: toast.publish({ id: "saved", title: savedTitle, description: subjectSummary, tone: "success", closeLabel });
+}
+```
+
+```tsx
+// Native — ToastRegion 안에서, 같은 descriptor를 publish한다.
+import { useToastRegion } from "@hjmds/react-native/feedback";
+
+const toast = useToastRegion();
+async function save() {
+  await persist(draft);
+  toast.publish({ id: "saved", description: savedLabel, tone: "success", closeLabel });
+}
 ```
 
 실행 예제: [Web](../../../../../showcase/web/src/components/save-feedback-preview.tsx), [Native](../../../../../showcase/native/src/save-feedback-preview.tsx), [공통 문구](../../../../../showcase/shared/save-feedback.ts). 비교 예제의 durationMs: null은 제품 기본 타이머를 바꾸지 않는다.

package/docs/usage/tokens/color.md

@@ -32,6 +32,7 @@
 | `canvas` = `bg` | `#ffffff` / `#0d1116` | `--hjm-color-bg` | `theme.colors.bg` | 화면 바탕. 카드·패널(Surface·Card)도 모든 tone이 `bg`를 칠하고 층은 테두리·그림자로 나눈다 |
 | `surface.default` = `surface` | `#ffffff` / `#161b22` | `--hjm-color-surface` | `theme.colors.surface` | 바탕과 구분되는 옅은 면 |
 | `surface.sunken` = `surfaceAlt` | `#ebeef2` / `#1e232a` | `--hjm-color-surface-alt` | `theme.colors.surfaceAlt` | 한 단계 더 들어간 면(CodeBlock 바탕) |
+| `selection.background` = `surfaceSelected` | `#f0f1f3` / `#30343b` | `--hjm-color-surface-selected` | `theme.colors.surfaceSelected` | 기본 선택 배경 |
 | `surface.brand` = `surfaceAccent` | `#c9e2ff` / `#224159` | `--hjm-color-surface-accent` | `theme.colors.surfaceAccent` | 브랜드가 드러나는 옅은 면 |
 
 ### 글자
@@ -41,7 +42,7 @@
 | `content.primary` = `text` | `#191f28` / `#f3f5f7` | `--hjm-color-text` | `theme.colors.text` | 제목·강조 글자. Text `tone="primary"`(기본) |
 | `content.body` = `textBody` | `#333d4b` / `#e1e5ea` | `--hjm-color-text-body` | `theme.colors.textBody` | 긴 본문. Text `tone="body"` |
 | `content.secondary` = `textMuted` | `#4e5968` / `#cad0d8` | `--hjm-color-text-muted` | `theme.colors.textMuted` | 보조 설명. Text `tone="muted"` |
-| `content.tertiary` = `textSub` | `#65707d` / `#9ba5b0` | `--hjm-color-text-sub` | `theme.colors.textSub` | 시간·출처 같은 약한 메타 정보. Text `tone="subtle"` |
+| `content.tertiary` = `textSub` | `#646f7c` / `#9ba5b0` | `--hjm-color-text-sub` | `theme.colors.textSub` | 시간·출처 같은 약한 메타 정보. Text `tone="subtle"` |
 | `content.decorative` = `textWeak` | `#8b95a1` / `#8b96a2` | `--hjm-color-text-weak` | `theme.colors.textWeak` | 비활성·placeholder·장식 표지. Text `tone="weak"`. 읽혀야 하는 글자에는 쓰지 않는다 |
 
 ### 브랜드
@@ -86,13 +87,13 @@
 | `border.control` = `borderControl` | `#6b7684` / `#929faf` | `--hjm-color-border-control` | `theme.colors.borderControl` | 쉬고 있는 컨트롤 윤곽(Button `secondary`, 필드) |
 | `border.strong` = `textWeak` | `#8b95a1` / `#8b96a2` | `--hjm-color-text-weak` | `theme.colors.textWeak` | 강한 경계 |
 | `border.focus` | `contentBrand` | `--hjm-color-focus` | `theme.colors.contentBrand` | 포커스 링. 컴포넌트가 그린다 |
-| `interaction.hover` · `focus` · `pressed` · `selected` | `text` 0.06 · `contentBrand` 0.08 · `text` 0.1 · `primary` 0.1 | — | `resolveColorReference(…, theme.palette)` | 상태 덧칠. 제품 고유 누름 영역에만 직접 쓴다 |
+| `interaction.hover` · `focus` · `pressed` | `text` 0.06 · `contentBrand` 0.08 · `text` 0.1 | — | `resolveColorReference(…, theme.palette)` | 상태 덧칠. 제품 고유 누름 영역에만 직접 쓴다 |
 
 ### 함께 쓰는 쌍과 최소 대비
 
 `checkBrandPaletteContrast`가 검사하는 쌍이다. 이 밖의 조합(예: `contentBrand` 글자를 `surfaceAccent` 위에)은 HJM이 대비를 보장하지 않는다.
 
-- 4.5 이상: `text`·`textBody`·`textMuted`·`textSub`·`contentBrand`·`danger` on `bg`·`surface`, `onPrimary` on `primary`, `onDanger` on `dangerFill`.
+- 4.5 이상: `text`·`textBody`·`textMuted`·`textSub`·`contentBrand`·`danger` on `bg`·`surface`·`surfaceSelected`, `onPrimary` on `primary`, `onDanger` on `dangerFill`.
 - 3 이상: `primary`·`borderControl` vs `bg`·`surface`(형태), `textWeak` vs `bg`.
 
 ## 쓰는 법
@@ -162,3 +163,16 @@ import { HjmProvider } from "@hjmds/react/provider";
 표·표면의 회색 면을 줄이려는 사용자 결정으로 `surface`는 흰색 `#ffffff`,
 `surfaceAlt`는 보조 회색 `#ebeef2`를 사용한다. 페이지 바탕 `bg`는 흰색이며,
 표 본문은 `surface`, `raised` 카드는 `bg`를 소비한다. 근거는 [팔레트 결정 기록](../../theme-palette.md)을 따른다.
+
+## 기본 선택 역할
+
+`semanticColors.selection.background` → `surfaceSelected`: light `#f0f1f3`, dark `#30343b`.
+Web은 `--hjm-color-surface-selected`, Native는 `theme.colors.surfaceSelected`로 읽는다.
+선택 글자는 `semanticColors.selection.content` → `text`, 경계는 `selection.border` → `borderControl`이다.
+휠·선택 Chip·neutral SegmentedControl에 쓰며, 주요 버튼의 `primary`나 브랜드 배경의
+`surfaceAccent`를 선택 배경으로 덮어쓰지 않는다. [결정 근거](../../theme-palette.md#기본-선택-배경을-브랜드에서-분리한다-2026-10-23).
+
+기본 선택의 적용 범위와 예외는 [선택 상태 색상 기준](../../theme-palette.md#선택-상태-색상-기준-2026-10-23)을 따른다.
+
+`interaction.selected`는 이제 `surfaceSelected`를 가리킨다. 일반 선택 면에는 가능하면
+`semanticColors.selection.background`를 사용하고, hover/focus/pressed의 투명 상태 덧칠과 구분한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.40.0",
+  "version": "1.41.1",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -607,6 +607,12 @@
       "import": "./dist/reference-controls.js",
       "default": "./dist/reference-controls.js"
     },
+    "./choice-row": {
+      "types": "./dist/choice-row.d.ts",
+      "react-native": "./dist/choice-row.js",
+      "import": "./dist/choice-row.js",
+      "default": "./dist/choice-row.js"
+    },
     "./duration-field": {
       "types": "./dist/duration-field.d.ts",
       "react-native": "./dist/duration-field.js",