@hjmds/design-contracts 1.8.0 → 1.10.0

package/dist/watermark.d.ts

@@ -0,0 +1,15 @@
+export declare const watermarkRecipe: {
+    readonly tileWidth: 240;
+    readonly tileHeight: 160;
+    readonly rotate: -22;
+    readonly opacity: 0.12;
+    readonly foreground: "textSub";
+};
+export declare function resolveWatermark(text: string | readonly string[], width?: number, height?: number, rotate?: number, opacity?: number): {
+    lines: string[];
+    width: number;
+    height: number;
+    rotate: number;
+    opacity: number;
+};
+//# sourceMappingURL=watermark.d.ts.map

package/dist/watermark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watermark.d.ts","sourceRoot":"","sources":["../src/watermark.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;CAAkG,CAAC;AAC/H,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAAE,KAAK,GAAgC,MAAM,EAAE,MAAM,GAAiC,MAAM,EAAE,MAAM,GAA6B,MAAM,EAAE,OAAO,GAA8B,MAAM;;;;;;EAMpP"}

package/dist/watermark.js

@@ -0,0 +1,11 @@
+export const watermarkRecipe = { tileWidth: 240, tileHeight: 160, rotate: -22, opacity: 0.12, foreground: "textSub" };
+export function resolveWatermark(text, width = watermarkRecipe.tileWidth, height = watermarkRecipe.tileHeight, rotate = watermarkRecipe.rotate, opacity = watermarkRecipe.opacity) {
+    const lines = typeof text === "string" ? [text] : [...text];
+    // Bounded tiles prevent accidental invisible/huge overlays; this is decorative labeling, not tamper protection.
+    if (!lines.length || lines.length > 3 || lines.some(line => !line.trim() || line.length > 120))
+        throw new TypeError("Watermark needs one to three nonempty lines of at most 120 characters");
+    if (![width, height, rotate, opacity].every(Number.isFinite) || width < 80 || height < 60 || Math.abs(rotate) > 90 || opacity < 0 || opacity > 1)
+        throw new TypeError("Invalid Watermark geometry");
+    return { lines, width, height, rotate, opacity };
+}
+//# sourceMappingURL=watermark.js.map

package/dist/watermark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watermark.js","sourceRoot":"","sources":["../src/watermark.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAW,CAAC;AAC/H,MAAM,UAAU,gBAAgB,CAAC,IAAgC,EAAE,QAAQ,eAAe,CAAC,SAAmB,EAAE,SAAS,eAAe,CAAC,UAAoB,EAAE,SAAS,eAAe,CAAC,MAAgB,EAAE,UAAU,eAAe,CAAC,OAAiB;IACnP,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5D,gHAAgH;IAChH,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,uEAAuE,CAAC,CAAC;IAC7L,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,GAAG,EAAE,IAAI,MAAM,GAAG,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACpM,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACnD,CAAC","sourcesContent":["export const watermarkRecipe = { tileWidth: 240, tileHeight: 160, rotate: -22, opacity: 0.12, foreground: \"textSub\" } as const;\nexport function resolveWatermark(text: string | readonly string[], width = watermarkRecipe.tileWidth as number, height = watermarkRecipe.tileHeight as number, rotate = watermarkRecipe.rotate as number, opacity = watermarkRecipe.opacity as number) {\n  const lines = typeof text === \"string\" ? [text] : [...text];\n  // Bounded tiles prevent accidental invisible/huge overlays; this is decorative labeling, not tamper protection.\n  if (!lines.length || lines.length > 3 || lines.some(line => !line.trim() || line.length > 120)) throw new TypeError(\"Watermark needs one to three nonempty lines of at most 120 characters\");\n  if (![width, height, rotate, opacity].every(Number.isFinite) || width < 80 || height < 60 || Math.abs(rotate) > 90 || opacity < 0 || opacity > 1) throw new TypeError(\"Invalid Watermark geometry\");\n  return { lines, width, height, rotate, opacity };\n}\n"]}

package/docs/affix.md

@@ -1,63 +1,27 @@
-# Affix — 계약을 만들지 않는다
-
-## 문제로 제기된 것
-
-Ant Design `Affix`는 스크롤이 특정 지점을 지나면 임의 요소를 화면에 고정합니다. 검토
-관찰은 두 가지였습니다 — `TopBar`가 이미 있고(`src/layout.ts:9`, RN `native`, beta), Web
-CSS `position: sticky`가 대부분을 푼다면, 이것이 컴포넌트인지 아니면 레이아웃 기법인지
-확인하라는 것과, `docs/expansion-roadmap.md`의 `Stack` 판정("반복되는 내부 flex를 감싸는
-것만으로 제품 의미나 접근성 계약이 생기지 않는다")이 그대로 적용될 가능성이 높다는
-것이었습니다.
-
-## 판정: 만들지 않는다
-
-### 1. 관찰된 모든 실사용은 이미 다른 컴포넌트나 CSS 한 줄이 소유한다
-
-- **BurnTok** 웹 헤더(`apps/web/src/app/page.tsx:118`, `messages/page.tsx:27`,
-  `u/[id]/ProfileClient.tsx:80`, `c/[id]/StoryClient.tsx:287`,
-  `notifications/page.tsx:44`)는 모두 `<header className="sticky top-0 ...">`로 상단바를
-  고정합니다. 이는 정확히 `TopBar`의 자리이고, `position: sticky` 한 줄로 끝나는
-  문제입니다 — 스크롤 진행률 계산, 고정 해제 조건 분기, 별도 controlled 상태 없이 CSS가
-  전부 해결합니다.
-- **Yajalal RN**에도 이미 `TopBar` 구현(`modules/app-rn/src/components/ui/AppTopBar.tsx`)이
-  있습니다. Native는애초에 헤더가 화면 최상단에 고정 마운트되는 것이 기본값이라
-  "스크롤 임계값을 지나면 고정"이라는 Affix 특유의 조건 자체가 성립하지 않습니다.
-- 그 외 "고정" 관련 코드는 각 컴포넌트가 이미 소유한 문제입니다: `StatTable`의 첫 열
-  고정(`stickyFirstColumn`, `stat-table-contract.ts:23`)은 표 내부 anatomy이고,
-  `BottomCTA`의 하단 고정 영역(`AppBottomCTA.tsx:39` "Safe-area-aware sticky action
-  area")은 이미 별도 컴포넌트로 계약돼 있습니다. 둘 다 "임의 요소를 고정하는 범용
-  wrapper"를 필요로 하지 않습니다.
-
-### 2. 임의 콘텐츠를 고정하는 범용 요구 자체가 관측되지 않는다
-
-antd `Affix`의 핵심 사용법 — 헤더도 테이블도 아닌 **임의 콘텐츠**(플로팅 목차, 사이드
-액션 카드 등)를 스크롤 중간에 고정 — 는 두 제품 어디에도 없습니다. 있는 모든 "고정"
-사례는 위처럼 헤더(TopBar) 아니면 특정 컴포넌트 내부 anatomy(StatTable, BottomCTA)로
-이미 이름이 있습니다.
-
-### 3. 계약할 상태 축이 없다
-
-Affix가 컴포넌트가 되려면 "Web과 Native가 각자 다른 기법으로 같은 결과를 낸다"는 공유
-semantic이 있어야 합니다(`docs/architecture.md`의 `adaptive` 정의). 그런데 Web은 CSS
-`position: sticky`(레이아웃 엔진이 처리, JS 상태 없음), Native는 애초에 스크롤에 따라
-고정/해제되는 개념 자체가 드뭅니다(헤더는 기본 고정, 그 외에는 `stickyHeaderIndices`처럼
-리스트 컴포넌트가 소유). 이는 `docs/virtual-list.md`가 항목 높이 추정을 판정한 것과 같은
-모양입니다 — 이름도 단위도 의미도 대응하지 않는 렌더러 힌트일 뿐, 공유할 사용자 의미가
-없습니다.
-
-`Stack`의 판정과 같은 자리입니다: 반복되는 CSS 속성 하나를 감싸는 것만으로 제품 의미나
-접근성 계약이 생기지 않습니다.
-
-## 만들지 않은 것
-
-`src/affix.ts`, `test/affix.test.ts`는 없습니다. `componentCatalog`의
-`{ name: "Affix", category: "utility", platform: "web", status: "planned" }` 행과
-crosswalk의 `Affix → Affix` direct 관계(`src/component-references.ts:125`)는 건드리지
-않습니다.
-
-## 뒤집힐 조건
-
-1. 헤더도 테이블도 CTA도 아닌 **임의 콘텐츠**를 스크롤 중간 지점부터 고정해야 하는 실제
-   화면(예: 긴 폼 옆의 플로팅 요약 카드)이 두 제품 중 하나에 나타난다.
-2. 그 화면에서 CSS `position: sticky`만으로 부족한 요구(예: 여러 sticky 요소의 겹침
-   순서 조정, 고정 해제 시점의 접근성 발표)가 측정된다.
+# Affix — Web 상단 고정
+
+2026-09-30: 사용자의 구현 요청으로 기존 수요 대기 결정을 대체한다. `position: fixed`로 복제/이동하면
+초점과 폼 상태를 잃거나 폭을 다시 측정해야 하므로 CSS sticky로 원래 DOM과 문서 흐름을 유지한다.
+JS는 고정 상태 관측과 화면보다 큰 콘텐츠의 해제에만 사용한다.
+
+`@hjmds/react/affix`의 `Affix`는 `children`, `offset`(기본 0, 유한한 비음수 CSS px),
+`disabled`, `onChange(affixed)`를 받는다. 가장 가까운 스크롤 조상의 상단에서 offset만큼 떨어져
+고정된다. 부모의 끝에서 해제된다. 부모에 스크롤할 공간이 있어야 하며, 부모의 overflow 설정은
+CSS sticky의 기준을 바꾼다. 부모 자체가 콘텐츠와 같은 높이면 고정 구간이 없다.
+
+- `onChange`는 최초 상태와 이후 상태 전환에 호출한다. 렌더링마다 호출하지 않는다.
+- 스크롤·리사이즈는 animation frame으로 모아 측정하고 unmount 시 observer/listener/frame을 해제한다.
+- 콘텐츠가 스크롤 영역 높이에서 offset을 뺀 값보다 크면 일반 흐름으로 돌려 가려진 영역이 없게 한다.
+- disabled/offset 변경에도 자식을 재마운트하지 않아 입력값·초점이 유지된다.
+- 상단 고정만 지원하며 bottom 고정·portal·다중 sticky 영역 자동 충돌 조정은 제공하지 않는다.
+- 별도 role이나 live announcement를 강제하지 않는다. 자식 의미·접근성 이름은 제품이 소유한다.
+
+```tsx
+<Affix offset={16} onChange={setPinned}>
+  <Button onClick={save}>{t('form.save')}</Button>
+</Affix>
+```
+
+계약: [affix.ts](../src/affix.ts). UI: [renderer](../../react/src/affix.tsx).
+사용 예제: [Web additions](../../../showcase/web/src/patterns/WebAdditions.stories.tsx).
+검증: [브라우저 스크롤·초점 회귀](../../react/test/web-additions.browser.test.tsx).

package/docs/ant-design-coverage.md

@@ -67,11 +67,9 @@ catalog 행 처리도 여기서 갈립니다. **흡수됨**은 행을 지우고
 남깁니다 — 남겨 두면 "아직 만들 계획"으로 잘못 읽힙니다. **검증할 화면이 없음**은 행을
 그대로 둡니다. 계약은 유효하고 언젠가 채워질 자리이기 때문입니다. **거절됨**은 행을 지울 수 없습니다 — crosswalk의 `targets`가 가리키고 있고 흡수할 다른 이름이 없기 때문입니다. 대신 `ComponentCatalogEntry.declinedReason`에 사유를 적습니다.
 
-**흡수됨은 다시 두 갈래입니다.** 흡수한 대상이 **정확히 하나**면(`Notification`→Toast,
-`Dropdown`→Menu, `Flex`·`Space`→Stack) 행을 지우고 그 하나에 `aliases`로 이름을 남깁니다.
-대상이 **둘 이상의 조합**이면(`TimePicker`→Select 둘, `Rating`→Slider/Statistic,
-`ConfirmPopover`→Popover/AlertDialog) alias를 걸 단일 이름이 없으므로 **행을 그대로 둡니다.**
-이 저장소는 이 답을 세 번 반복해서 냈고, 우연이 아니라 규칙입니다.
+2026-09-30 사용자의 조합·중복 제외 요청에 따라, 구현된 조합도 독립 catalog 행에서 제거합니다.
+단일 대상 alias나 여러 primitive를 가리키는 crosswalk로 범위를 추적하고 작동 예제는 유지합니다.
+조합의 이름을 Planned로 예약하는 대안은 이미 해결된 기능을 미구현 수에 포함하므로 폐기합니다.
 
 **흡수 대기**는 행과 crosswalk를 **둘 다 건드리지 않습니다.** 흡수를 지금 적용하면 아직 만들지
 않은 해결책을 완료로 표시하게 됩니다 — `planned`이 거짓말하던 문제와 방향만 반대인 같은 문제입니다.
@@ -88,18 +86,16 @@ evidence registry로 판단합니다.
 - partial maturity: decomposed target 중 일부만 stable 또는 beta
 - planned only: 모든 target이 planned
 
-2026-09-18 SidePanel·Splitter·Tour·Tree·TransferList·Mentions·CommandPalette·DataTable renderer까지 추가한 뒤 status 기반 분포는
-**fully mature 62 / partial maturity 0 /
-planned only 8**입니다. decomposed Drawer의 두 갈래(Sheet·SidePanel)가 모두 구현되면서
-partial maturity가 비었습니다 — 0은 "부분 구현이 없다"는 뜻이고 planned only 20은 그대로입니다. 따라서 73/73 tracking은 73개 구현 완료를 의미하지 않습니다.
-홈과 Component Explorer는 이 수치를 분리해 표시합니다. 이 숫자는 source inventory 수가
-아니라 HJM target의 maturity에서 계산하므로 catalog status가 바뀌면 함께 갱신합니다.
+2026-09-30 조합 항목을 실제 primitive로 연결한 status 기반 분포는
+**fully mature 70 / partial maturity 0 /
+planned only 0**입니다. 이는 참조표 대상의 성숙도이며 원본 라이브러리 API 전체의 동등성을
+보증하지 않습니다. ColorPicker·Watermark·Affix에도 Web renderer가 추가되어 Planned가 없습니다.
 
 ## lifecycle
 
 Ant Design 6.6.1은 기존 `List`를 deprecated로 표시하고 `Listy`를 successor로 추가했습니다.
 reference inventory는 `List.lifecycle = deprecated`, `Listy.lifecycle = new`로 보존하지만 HJM
-`List`를 자동으로 deprecated 처리하지 않습니다. HJM은 기존 비가상 `List`와 planned
+`List`를 자동으로 deprecated 처리하지 않습니다. HJM은 기존 비가상 `List`와 구현된
 `VirtualList`를 서로 다른 사용 문제로 유지합니다.
 
 ## 업데이트 규칙

package/docs/cascader.md

@@ -1,5 +1,10 @@
 # Cascader — 별도 컴포넌트를 만들지 않는다
 
+> 2026-09-30 정리: 구현된 조합을 미구현으로 집계하지 않도록 독립 Planned 행과 catalog ID를 제거했다.
+> 기존 조합 예제와 공개 helper는 유지하며, 참조표는 실제 구성 컴포넌트로 연결한다.
+> 아래 날짜별 설계 기록의 행 유지 지시는 당시 판단이며 이 결정으로 대체한다.
+
+
 ## 문제로 제기된 것
 
 계층 데이터에서 경로 하나를 고른다(시/도 → 구 → 동). Ant Design `Cascader`와 `direct`

package/docs/catalog-decision-status.md

@@ -1,5 +1,10 @@
 # Catalog이 "만들지 않기로 확정함"을 표현하지 못하는 문제 — 설계 제안
 
+> 2026-09-30 후속 결정: 구현된 조합 5개는 독립 Planned 행에서 제거하고 참조표를
+> 실제 primitive로 연결했다. 아래의 다중 대상 조합 행 유지 판단은 과거 기록이다.
+> 현재 원칙과 집계는 [참조 범위](ant-design-coverage.md)를 따른다.
+
+
 ## 문제
 
 `ComponentStatus`는 `"stable" | "beta" | "planned" | "deprecated"` 넷뿐이다(`src/catalog.ts`).

package/docs/color-picker.md

@@ -1,72 +1,30 @@
-# ColorPicker — 지금은 만들지 않는다
-
-## 문제로 제기된 것
-
-임의의 색을 고른다(hex/RGB/HSB 입력, 팔레트, 최근 사용 색). Ant Design `ColorPicker`와
-`direct` crosswalk를 따른다. catalog에는 이미 `{ name: "ColorPicker", category: "input",
-platform: "web", status: "planned" }` 자리가 예약돼 있다.
-
-## 판정: 실사용처 근거 없이 만들지 않는다
-
-먼저 가정하지 말라는 지시대로 두 제품에 색을 고르는 화면이 있는지 확인했다.
-
-- **Yajalal RN**(`modules/app-rn/src`): `grep -rli "colorpicker\|color picker\|color-picker"`가
-  0건이다. 코드베이스 전체에 색을 고르는 화면이 없다.
-- **BurnTok Web**: 이 머신에 저장소가 없어 코드로 직접 확인할 수 없었다. 로드맵
-  (`docs/expansion-roadmap.md`)의 제품 적용 순서·완료 슬라이스 기록 어디에도 색 선택
-  화면이 등장하지 않는다 — 언급되는 색 관련 작업은 전부 "제품이 이미 고정한 semantic
-  color를 렌더러가 어떻게 적용하는가"(Toast tone mark, Statistic trend mark, 구단 색
-  adapter)이고, "사용자가 임의의 색을 고르는" 문제는 한 번도 나오지 않는다.
-
-측정된 vertical slice가 없다는 뜻이다. `docs/expansion-roadmap.md`의 maturity gate는
-"실제 제품 vertical slice 없이 승격하지 않는다"고 정하고 있고, 이 원칙은 계약을 쓸지
-말지에도 그대로 적용된다 — `docs/notification.md`·`docs/dropdown.md`·
-`docs/virtual-list.md`가 이미 "측정된 요구가 없으면 만들지 않는다"로 판정한 것과 같은
-근거다.
-
-## 이 판정을 더 무겁게 만드는 이유
-
-ColorPicker는 만들면 가벼운 계약이 아니다. 로드맵의 상태 축 표 어디에도 없는 완전히
-새로운 세 갈래 문제를 한 번에 열어야 한다.
-
-1. **색 공간 표현.** hex/RGB/HSB/alpha 중 무엇을 공개 API로 삼을지, 변환 규칙을 어디
-   소유할지부터 새로 정해야 한다 — 이 저장소의 어떤 기존 컴포넌트도 색 값 자체를
-   입력 데이터로 다루지 않는다(`semanticColors`/`ColorReference`는 전부 제품이 아니라
-   시스템이 미리 고정한 토큰이다).
-2. **대비·접근성.** 사용자가 고른 색이 텍스트/배경 대비 4.5:1을 만족하는지, 선택 UI
-   자체의 포커스 인디케이터가 색상 스와치 배경과 충분한 대비를 유지하는지를 계약이
-   보장해야 한다 — Statistic의 trend, UploadItem의 상태처럼 이 저장소는 "색으로만
-   말하지 않는다"를 지켜왔는데, ColorPicker는 그 규칙과 정반대로 색 자체가 선택 결과인
-   컴포넌트라 이 원칙을 어떻게 지킬지부터 새로 설계해야 한다(스와치에 값 텍스트를
-   병기하는 것 정도는 쉽지만, 색맹 사용자를 위한 팔레트 순서·명도 대비 규칙은 가볍지
-   않다).
-3. **입력 방식.** 팔레트 탭, 텍스트 hex 입력, 슬라이더(hue/saturation/brightness) 최소
-   셋을 하나의 컴포넌트가 조율해야 하고, 셋 사이의 값 동기화(hex 입력 중 오타 상태를
-   팔레트에 어떻게 반영하는지)는 NumberField/Slider보다 훨씬 큰 상태 기계다.
-
-수요 없이 이 세 갈래를 먼저 짜면 다음 사람이 "실제로 무엇을 위해 이렇게 무거운가"를
-또 물어야 하는 계약이 된다. 반대로 실사용처가 나오면, 그 화면이 실제로 필요한 것은
-이 셋 중 일부뿐일 가능성이 높다(예: 구단 색 하나를 브랜드 팔레트에서만 고르는 화면이면
-색 공간 변환도 hex 입력도 필요 없다) — 지금 전체를 설계하면 그 실제 요구보다 큰 계약이
-된다.
-
-## 만들지 않은 것
-
-`src/color-picker.ts`, `test/color-picker.test.ts`는 없다. catalog의
-`{ name: "ColorPicker", category: "input", platform: "web", status: "planned" }` row와
-`antDesignReferenceComponents`의 `ColorPicker → ColorPicker` crosswalk(`relationship:
-"direct"`)는 건드리지 않는다 — 이름 자리를 지우는 것이 아니라, 지금 채울 계약이 없다는
-것이다.
-
-## 뒤집힐 조건
-
-다음 중 하나가 실제로 측정되면 이 판정을 다시 연다.
-
-1. BurnTok 또는 Yajalal에 사용자가 임의의 색을 고르는 실제 화면 요구가 나온다(예: 커스텀
-   테마, 사용자 지정 하이라이트 색).
-2. 요구가 팔레트에서 미리 정의된 색 중 하나만 고르는 좁은 범위로 확인되면, ColorPicker
-   전체가 아니라 `Chip` 또는 `RadioGroup`의 시각 변형으로 더 가볍게 흡수될 수 있는지부터
-   먼저 검토한다 — hex 입력·색 공간 변환이 필요 없는 한 별도 컴포넌트를 열 이유가
-   약해진다.
-3. 요구가 hex/RGB 자유 입력까지 포함하면, 이 문서의 세 갈래(색 공간/대비/입력 방식)를
-   실제 화면의 좁은 요구에 맞춰 하나씩만 계약하고 나머지는 열지 않는다.
+# ColorPicker — Web sRGB 색상 입력
+
+2026-09-30: 사용자가 남은 세 후보의 개발을 명시적으로 요청하여 기존 수요 대기 결정을 대체했다.
+React Native와 Flutter 구현은 포함하지 않는다. 계약은 HEX sRGB를 저장값으로 선택했다.
+HSV/RGB 입력기를 동시에 만드는 대신 브라우저 색상 선택기와 HEX 입력을 연결해 값 표현을 하나로 유지한다.
+
+`@hjmds/react/color-picker`의 `ColorPicker`는 controlled `value`와 `onValueChange`를 받는다.
+`label`과 `labels.color`, `labels.hex`, `labels.opacity`, `labels.invalid`는 제품에서 번역하여 전달한다.
+`alpha`가 false면 `#rrggbb`, true면 `#rrggbbaa`를 내보낸다. 3·4자리 축약 HEX도 입력할 수 있다. alpha가 켜진 상태에서 3·6자리 HEX를 입력하면 색만 바꾸고 현재 투명도를 유지한다(네이티브 색상 입력과 같다).
+alpha를 끈 상태에서 불투명하지 않은 값을 전달하면 투명도를 조용히 버리지 않고 거부한다.
+
+- HEX는 Enter/blur에 확정한다. 잘못된 입력은 오류를 보여주고 외부 값은 유지한다.
+  Escape는 마지막 controlled 값으로 복구하며 Enter가 상위 폼을 제출하지 않게 한다.
+- 브라우저 색상 선택기는 RGB를 선택하고 기존 alpha를 보존한다. 정확한 선택기 모양은 OS 소유다.
+- 불투명도 range는 0–100%이며 키보드 화살표/Home/End를 지원한다. 8비트 alpha로 반올림한다.
+- `presets`는 HEX 배열이며 색상값을 읽을 수 있는 버튼이다. 중복값은 정규화 후 제거한다.
+- `disabled`는 fieldset을 통해 모든 입력과 팔레트를 비활성화한다.
+- 제어부는 HJM canvas·border·focus 토큰을 사용한다. 견본의 사용자 색상은 콘텐츠 데이터다.
+  선택색을 제품의 본문/배경으로 사용할 때의 대비는 제품이 확인한다.
+
+```tsx
+<ColorPicker label={t('color.title')} labels={{
+  color: t('color.choose'), hex: t('color.hex'), opacity: t('color.opacity'), invalid: t('color.invalid'),
+}} value={color} onValueChange={setColor} alpha presets={['#b94627ff', '#338844ff']} />
+```
+
+계약: [color-picker.ts](../src/color-picker.ts). UI: [renderer](../../react/src/color-picker.tsx).
+사용 예제: [Web additions](../../../showcase/web/src/patterns/WebAdditions.stories.tsx).
+검증: [계약 회귀](../test/web-additions.test.ts), [브라우저 동작](../../react/test/web-additions.browser.test.tsx),
+[환경 행렬](../../react/test/scenario-matrix.browser.test.tsx). 브라우저/OS 색상 팝업 자체의 내부 UI는 HJM 검증 대상이 아니다.

package/docs/confirm-popover.md

@@ -1,5 +1,10 @@
 # ConfirmPopover — Popover 위의 확인 조합
 
+> 2026-09-30 정리: 구현된 조합을 미구현으로 집계하지 않도록 독립 Planned 행과 catalog ID를 제거했다.
+> 기존 조합 예제와 공개 helper는 유지하며, 참조표는 실제 구성 컴포넌트로 연결한다.
+> 아래 날짜별 설계 기록의 행 유지 지시는 당시 판단이며 이 결정으로 대체한다.
+
+
 ## 문제로 제기된 것
 
 Ant Design `Popconfirm`은 "삭제하시겠습니까?" 같은 확인을 Modal보다 가벼운

package/docs/generated/component-maturity.md

@@ -1,12 +1,12 @@
 # Component maturity and evidence manifest
 
-> Generated from `@hjmds/design-contracts` 1.8.0. Do not edit this file directly; run `pnpm contracts:sync`.
+> Generated from `@hjmds/design-contracts` 1.10.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.
 
-- Contract: stable 100 · planned 8
-- Web renderer: stable 100 · planned 8
-- Native renderer: stable 83 · planned 3 · unsupported 22
+- Contract: stable 103
+- Web renderer: stable 103
+- Native renderer: stable 83 · unsupported 20
 
 | Component | Canonical story ID | Contract | Web | Native | Documentation | Required evidence |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -52,16 +52,12 @@ This document is the human-readable projection of the same catalog and Showcase
 | Combobox | `input/combobox` | stable | stable | stable | generated only | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | DatePicker | `input/date-picker` | stable | stable | stable | [authored](../date-picker.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | DateRangePicker | `input/date-range-picker` | stable | stable | stable | generated only | contract: contract; web: default, dark, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, large-text, rtl, reduced-motion, accessibility, native-actions |
-| TimePicker | `input/time-picker` | planned | planned | planned | [authored](../time-picker.md) | contract: contract |
-| ColorPicker | `input/color-picker` | planned | planned | unsupported | [authored](../color-picker.md) | contract: contract |
+| ColorPicker | `input/color-picker` | stable | stable | unsupported | [authored](../color-picker.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard |
 | FilePicker | `input/file-picker` | stable | stable | stable | [authored](../file-picker.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
-| Cascader | `input/cascader` | planned | planned | planned | [authored](../cascader.md) | contract: contract |
 | Form | `input/form` | stable | stable | stable | [authored](../form.md) | contract: contract; web: default, dark, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, large-text, rtl, reduced-motion, accessibility, native-actions |
 | Agreement | `input/agreement` | stable | stable | stable | [authored](../agreement.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | Mentions | `input/mentions` | stable | stable | stable | [authored](../mentions.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
-| Rating | `input/rating` | planned | planned | planned | [authored](../rating.md) | contract: contract |
 | TransferList | `input/transfer-list` | stable | stable | stable | [authored](../transfer-list.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
-| TreeSelect | `input/tree-select` | planned | planned | unsupported | [authored](../tree-select.md) | contract: contract |
 | UploadItem | `data-display/upload-item` | stable | stable | stable | [authored](../upload-item.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | Tabs | `navigation/tabs` | stable | stable | stable | generated only | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | TopBar | `navigation/top-bar` | stable | stable | stable | generated only | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility |
@@ -105,16 +101,15 @@ This document is the human-readable projection of the same catalog and Showcase
 | Result | `feedback/result` | stable | stable | stable | [authored](../result.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility |
 | BottomInfo | `feedback/bottom-info` | stable | stable | stable | [authored](../bottom-info.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility |
 | Toast | `feedback/toast` | stable | stable | stable | [authored](../toast.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
-| Watermark | `feedback/watermark` | planned | planned | unsupported | [authored](../watermark.md) | contract: contract |
+| Watermark | `feedback/watermark` | stable | stable | unsupported | [authored](../watermark.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility |
 | Dialog | `overlay/dialog` | stable | stable | stable | [authored](../dialog.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | AlertDialog | `overlay/alert-dialog` | stable | stable | stable | generated only | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | Sheet | `overlay/sheet` | stable | stable | stable | [authored](../sheet.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, native-actions |
 | SidePanel | `overlay/side-panel` | stable | stable | unsupported | [authored](../side-panel.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard |
 | Popover | `overlay/popover` | stable | stable | unsupported | [authored](../popover.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard |
-| ConfirmPopover | `overlay/confirm-popover` | planned | planned | unsupported | [authored](../confirm-popover.md) | contract: contract |
 | Tooltip | `overlay/tooltip` | stable | stable | unsupported | [authored](../tooltip.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard |
 | CommandPalette | `overlay/command-palette` | stable | stable | unsupported | [authored](../command-palette.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard |
-| Affix | `utility/affix` | planned | planned | unsupported | [authored](../affix.md) | contract: contract |
+| Affix | `utility/affix` | stable | stable | unsupported | [authored](../affix.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility |
 | DesignSystemProvider | `provider/design-system-provider` | stable | stable | stable | [authored](../design-system-provider.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility; native: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility |
 | SkipNav | `utility/skip-nav` | stable | stable | unsupported | [authored](../skip-nav.md) | contract: contract; web: default, dark, long-copy, large-text, rtl, reduced-motion, accessibility, keyboard |
 | VisuallyHidden | `utility/visually-hidden` | stable | stable | unsupported | [authored](../visually-hidden.md) | contract: contract; web: default, dark, large-text, rtl, reduced-motion, accessibility |

package/docs/generated/renderer-evidence.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "designSystemVersion": "1.8.0",
+  "designSystemVersion": "1.10.0",
   "source": "packages/design-contracts/docs/generated/showcase-manifest.json",
   "surfaces": {
     "web": {
       "packageName": "@hjmds/react",
-      "packageVersion": "1.8.0",
-      "activeComponents": 100,
-      "claimedComponents": 100,
-      "completeScenarioComponents": 100,
+      "packageVersion": "1.10.0",
+      "activeComponents": 103,
+      "claimedComponents": 103,
+      "completeScenarioComponents": 103,
       "components": [
         {
           "componentId": "text",
@@ -2306,6 +2306,65 @@
           ],
           "missingScenarios": []
         },
+        {
+          "componentId": "color-picker",
+          "name": "ColorPicker",
+          "status": "stable",
+          "claimed": true,
+          "subpath": "./color-picker",
+          "exportNames": [
+            "ColorPicker"
+          ],
+          "proofs": [
+            {
+              "scenarios": [
+                "default"
+              ],
+              "file": "test/default-render.ssr.test.tsx",
+              "caseId": "color-picker"
+            },
+            {
+              "scenarios": [
+                "accessibility",
+                "dark",
+                "large-text",
+                "rtl",
+                "reduced-motion",
+                "long-copy"
+              ],
+              "file": "test/scenario-matrix.browser.test.tsx",
+              "caseId": "color-picker"
+            },
+            {
+              "scenarios": [
+                "keyboard"
+              ],
+              "file": "test/web-additions.browser.test.tsx",
+              "caseId": "color-picker"
+            }
+          ],
+          "requiredScenarios": [
+            "default",
+            "dark",
+            "long-copy",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "accessibility",
+            "keyboard"
+          ],
+          "claimedScenarios": [
+            "default",
+            "accessibility",
+            "dark",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "long-copy",
+            "keyboard"
+          ],
+          "missingScenarios": []
+        },
         {
           "componentId": "file-picker",
           "name": "FilePicker",
@@ -4909,6 +4968,56 @@
           ],
           "missingScenarios": []
         },
+        {
+          "componentId": "watermark",
+          "name": "Watermark",
+          "status": "stable",
+          "claimed": true,
+          "subpath": "./watermark",
+          "exportNames": [
+            "Watermark"
+          ],
+          "proofs": [
+            {
+              "scenarios": [
+                "default"
+              ],
+              "file": "test/default-render.ssr.test.tsx",
+              "caseId": "watermark"
+            },
+            {
+              "scenarios": [
+                "accessibility",
+                "dark",
+                "large-text",
+                "rtl",
+                "reduced-motion",
+                "long-copy"
+              ],
+              "file": "test/scenario-matrix.browser.test.tsx",
+              "caseId": "watermark"
+            }
+          ],
+          "requiredScenarios": [
+            "default",
+            "dark",
+            "long-copy",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "accessibility"
+          ],
+          "claimedScenarios": [
+            "default",
+            "accessibility",
+            "dark",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "long-copy"
+          ],
+          "missingScenarios": []
+        },
         {
           "componentId": "dialog",
           "name": "Dialog",
@@ -5322,6 +5431,56 @@
           ],
           "missingScenarios": []
         },
+        {
+          "componentId": "affix",
+          "name": "Affix",
+          "status": "stable",
+          "claimed": true,
+          "subpath": "./affix",
+          "exportNames": [
+            "Affix"
+          ],
+          "proofs": [
+            {
+              "scenarios": [
+                "default"
+              ],
+              "file": "test/default-render.ssr.test.tsx",
+              "caseId": "affix"
+            },
+            {
+              "scenarios": [
+                "accessibility",
+                "dark",
+                "large-text",
+                "rtl",
+                "reduced-motion",
+                "long-copy"
+              ],
+              "file": "test/scenario-matrix.browser.test.tsx",
+              "caseId": "affix"
+            }
+          ],
+          "requiredScenarios": [
+            "default",
+            "dark",
+            "long-copy",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "accessibility"
+          ],
+          "claimedScenarios": [
+            "default",
+            "accessibility",
+            "dark",
+            "large-text",
+            "rtl",
+            "reduced-motion",
+            "long-copy"
+          ],
+          "missingScenarios": []
+        },
         {
           "componentId": "design-system-provider",
           "name": "DesignSystemProvider",
@@ -5483,7 +5642,7 @@
     },
     "native": {
       "packageName": "@hjmds/react-native",
-      "packageVersion": "1.8.0",
+      "packageVersion": "1.10.0",
       "activeComponents": 83,
       "claimedComponents": 83,
       "completeScenarioComponents": 83,