@hjmds/design-contracts 1.3.5 → 1.5.0

package/docs/generated/showcase-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "designSystemVersion": "1.3.5",
+  "designSystemVersion": "1.5.0",
   "packageName": "@hjmds/design-contracts",
   "components": [
     {
@@ -9,10 +9,10 @@
       "name": "Text",
       "category": "foundation",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -144,10 +144,10 @@
       "name": "Icon",
       "category": "foundation",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -161,7 +161,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -173,7 +172,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -257,7 +255,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -269,7 +266,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -336,10 +332,10 @@
       "name": "Stack",
       "category": "layout",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -384,10 +380,10 @@
       "name": "Container",
       "category": "layout",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -743,10 +739,10 @@
       "name": "IconButton",
       "category": "action",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -760,7 +756,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -772,7 +767,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -3137,10 +3131,10 @@
       "name": "Badge",
       "category": "data-display",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -3233,10 +3227,10 @@
       "name": "Card",
       "category": "data-display",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -3895,10 +3889,10 @@
       "name": "Tag",
       "category": "data-display",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -4028,10 +4022,10 @@
       "name": "Notice",
       "category": "feedback",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -4076,10 +4070,10 @@
       "name": "Progress",
       "category": "feedback",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -4124,10 +4118,10 @@
       "name": "Spinner",
       "category": "feedback",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -4141,7 +4135,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -4153,7 +4146,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -4172,10 +4164,10 @@
       "name": "Skeleton",
       "category": "feedback",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {
@@ -4189,7 +4181,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -4201,7 +4192,6 @@
           "scenarios": [
             "default",
             "dark",
-            "long-copy",
             "large-text",
             "rtl",
             "reduced-motion",
@@ -4543,7 +4533,7 @@
       ],
       "documentation": {
         "generated": "docs/generated/component-maturity.md",
-        "authored": null
+        "authored": "docs/sheet.md"
       }
     },
     {
@@ -4796,10 +4786,10 @@
       "name": "DesignSystemProvider",
       "category": "provider",
       "platform": "shared",
-      "contractStatus": "beta",
+      "contractStatus": "stable",
       "surfaces": {
-        "web": "beta",
-        "native": "beta"
+        "web": "stable",
+        "native": "stable"
       },
       "requirements": [
         {

package/docs/product-adoption-1.4.md

@@ -0,0 +1,48 @@
+# 1.4 제품 채택 가이드
+
+2026-09-23 소비 감사에서 기존 HJM 대신 같은 설정·로그인·Sheet를 제품마다 조립하는 사례를
+확인했다. 새 도메인 컴포넌트를 추가하는 대신 실제 우회를 없앨 수 있는 API와 조합을 보완한다.
+
+## 로그인
+
+`AuthScreenLayout`의 hero/main/footer를 제품의 기존 내용으로 채운다. 로고, 제공자 목록,
+심사자 폼 노출 조건, 동의와 정책 링크는 제품 소유다. 제공자 로고를 HJM 패키지로 옮기지 않는다.
+Native의 외부 배치는 `layoutStyle`, UI 식별은 `testID`를 사용한다. 키보드가 열린 입력 폼에서도
+버튼 터치를 받으며 iOS의 키보드 스크롤 여백을 제공한다. 긴 내용은 축소하지 않고 스크롤한다.
+부모도 keyboard avoidance를 한다면 같은 clearance를 중복 적용하지 않도록 소비 화면에서 검증한다.
+Web의 상위 앱 셸에 이미 main landmark가 있으면 `as="section"`을 사용한다. 이 옵션은
+다에리 WebShell의 main 안에 로그인 레이아웃을 채택할 때 중첩 main을 피하기 위해 추가했다.
+
+## 설정 한 행
+
+`Switch presentation="row"`에 label/description/checked/onCheckedChange를 전달하면 행 전체가
+한 개의 switch다. 다른 Pressable이나 button으로 감싸지 않는다. 표시 이름과 설명은 접근성에서도
+분리하고, Web의 기존 aria-describedby가 있으면 설명을 함께 연결한다. 공통 large-text 기준(160%)에서는
+설명 아래로 track을 내려 좁은 텍스트 열을 만들지 않는다. DOM의 순서 차이는 키보드 tab stop을
+추가하지 않는다.
+
+Web의 기본은 기존 inline, Native의 기본은 기존 row다. 제품 간 같은 설정 화면은 presentation을
+명시한다. 기존 ListRow의 trailing control만 필요한 경우 `labelVisibility="hidden"`을 유지할 수 있다.
+그 경우 ListRow에는 별도 onPress를 두지 않는다.
+
+## 상태 화면
+
+상태를 하나의 error boolean으로 뭉치지 않는다. 아래 조합은 제품 adapter에 두며 데이터 조회나
+재시도 로직을 HJM에 넣지 않는다.
+
+| 상태 | 조합 | 제품 책임 |
+| --- | --- | --- |
+| 최초 로딩 | Skeleton + 기다리는 대상 설명 | 실제 화면 높이/형태, 중복 announcement 방지 |
+| 빈 결과 | EmptyState + 다음 행동 | 검색 0건과 데이터 미생성을 구분 |
+| 구역 실패 | Notice + 재시도 | 다른 정상 구역은 유지 |
+| 이전 데이터 있음 | 기존 콘텐츠 + Notice | stale 배지, 새로고침, 중복 재시도 방지 |
+| 전체 흐름 종료 | Result | 다음 목적지와 결과 문구 |
+
+## 호환성과 채택 검증
+
+세 패키지의 exact version, dependency/lock/contract/catalog를 함께 갱신한다. 기존 beta의
+status를 자동으로 stable로 바꾸지 않는다. 실제 쓰는 beta는 소비 ADR/evidence에 연결한다.
+Native raw style API는 아직 호환 지원이며 [소비 정책](consumer-policy.md)의 다음 major 절차를 따른다.
+
+Sheet 이관은 [입력 화면 계약](sheet.md)을 따른다. 각 제품은 typecheck/build/관련 동작 테스트와
+실제 화면 검증을 구별해 기록한다. 패키지 테스트 통과가 소비자·배포·기기 완료를 뜻하지 않는다.

package/docs/sheet.md

@@ -0,0 +1,50 @@
+# Sheet 입력 화면과 가용 영역
+
+## 문제와 결정
+
+2026-09-23 소비 조사에서 BurnTok 모바일 `AppSheet.tsx:93`은 제목을 수직 정렬하기 위해
+ReactNode를 `as unknown as string`으로 전달했다. Web도 `.hjm-sheet__header`를 덮어썼다.
+같은 어댑터가 키보드 높이, top inset, 본문 maxHeight를 별도로 보정하고 있었다.
+
+1.4는 제목·닫기 컨트롤을 헤더 중앙에 정렬한다. 제목은 여전히 문자열이다. 임의의 제목 slot을
+추가하면 접근성 이름과 표시가 서로 어긋날 수 있어 기본 renderer 정렬을 고치는 쪽을 택했다.
+
+Native Sheet는 `keyboardAvoidance`와 `scrollable`을 제공한다. 둘 다 기본 false다.
+이미 키보드를 처리하거나 FlatList를 넣는 소비자를 minor에서 이중 처리하지 않기 위한 선택이다.
+입력 폼은 두 옵션을 함께 켜고 제품의 키보드 listener·강제 maxHeight·중첩 ScrollView를 제거한다.
+
+## 계약과 플랫폼 번역
+
+- 제목/닫기와 footer는 스크롤 본문 바깥에 둔다. body만 줄어들고 스크롤한다.
+- top safe area는 화면의 가용 높이를 제한한다. bottom sheet 내부에 노치 높이를 더하지 않는다.
+- Native modal의 실제 onLayout 높이를 사용한다. Android adjustResize가 이미 줄인 높이에
+  키보드 높이를 한 번 더 빼지 않는다.
+- 열린 키보드 위에 Sheet가 나타나도 `Keyboard.metrics()`로 현재 상태를 읽는다.
+- iOS frame change, Android didShow/didHide를 구독하고 종료 시 해제한다.
+- 화면 폭보다 좁은 floating keyboard에는 화면 전체를 밀어 올리지 않는다.
+- docked keyboard가 있으면 home indicator inset을 키보드 위에 중복 추가하지 않는다.
+- Web은 기존 scroll body·viewport CSS·focus trap을 유지하며 헤더 정렬을 함께 고친다.
+- busy, close reason, Modal dismiss completion, focus return 계약은 유지한다.
+
+```tsx
+<Sheet open={open} title="설정" closeLabel="닫기"
+  keyboardAvoidance scrollable safeAreaInsets={insets}
+  onOpenChange={setOpen} footer={<Button onPress={save}>저장</Button>}>
+  <TextField label="이름" value={name} onValueChange={setName} />
+</Sheet>
+```
+
+`scrollable` 본문 안에 가상화 목록을 중첩하지 않는다. 목록 자체가 스크롤 소유자인 경우
+`scrollable={false}`로 두고 목록의 flex/keyboard 연결을 제품 adapter에서 담당한다.
+
+## 증거와 남은 확인
+
+- `packages/react-native/test/sheet-viewport.test.tsx`: 키보드 사전 표시, frame 변경, resize,
+  floating keyboard, listener 해제, footer/body 경계, safe area와 title 이름.
+- `packages/react-native/test/modal-lifecycle-fallback.test.tsx`: 종료/후속 surface/focus 회귀.
+- `packages/react/test/sheet-layout.browser.test.tsx`: 320px의 제목/닫기 기하와 100/200% 글자.
+- 위 Native proof는 host mock이다. 소비 앱 Device Hub 및 Android의 실제 키보드 동작은
+  별도로 기록하며 mock 통과를 기기 증거로 삼지 않는다.
+
+참조: [React Native Keyboard](https://reactnative.dev/docs/keyboard),
+[ScrollView](https://reactnative.dev/docs/scrollview).

package/docs/stable-core.md

@@ -1,4 +1,21 @@
-# Stable Core 0.8
+# Stable Core
+
+## 1.5.0 승격
+
+다음 13개를 stable로 올렸습니다: `Text`, `Icon`, `Stack`, `Container`, `DesignSystemProvider`,
+`IconButton`, `Badge`, `Card`, `Tag`, `Notice`, `Progress`, `Spinner`, `Skeleton`.
+
+- 근거: 1.5.0에서 renderer 시나리오 증거를 이름뿐인 검사에서 실제 검사로 바꿨습니다
+  (Web `test/scenario-matrix.browser.test.tsx`, Native `test/scenario-matrix.test.tsx`). 두 renderer에서
+  요구 시나리오가 모두 통과하고 세 제품 이상이 쓰는 컴포넌트만 올렸습니다.
+- 이 전환으로 Web의 "모든 시나리오 증거 완비"는 33개에서 16개로 줄었다가 승격 대상 보강 뒤
+  24개가 됐습니다. 줄어든 것은 이전 수치가 과대 표시였기 때문입니다.
+- 아이콘·로딩 표시·구분선처럼 보이는 글자 슬롯이 없는 컴포넌트는 long-copy 요구에서 뺐습니다
+  (`showcase.ts`의 `textlessComponentNames`).
+- keyboard·platform-parity를 요구하는 컴포넌트(Checkbox, Switch, Dialog, Sheet 등)는 그 증거가
+  아직 없어 beta로 남습니다. 생성된 evidence 문서의 "Missing required scenarios"가 남은 일입니다.
+
+## 0.8 첫 stable slice
 
 첫 renderer stable slice는 `Surface`, `Button`, `Field`, `TextArea`다. 이 네 컴포넌트는
 계약이 이미 stable이고 Web/RN renderer가 같은 public intent를 실행한다.

package/docs/tag.md

@@ -47,11 +47,10 @@ recipe가 안정화되면 그쪽에 위임하고, 이 계약에는 넣지 않습
 
 ## 현재 maturity와 남은 증거
 
-Tag contract와 Web/Native surface는 모두 **beta**입니다. 두 first-party renderer의 canonical
-default render proof가 `tagRecipe`의 정적 text/background anatomy를 실행하고, generated
-manifest와 evidence registry가 이 상태를 함께 검증합니다.
-
-beta는 전체 환경 인증을 뜻하지 않습니다. dark, RTL, 200% text/Dynamic Type, screen reader와
-실제 device screenshot은 아직 scenario별 실행 proof가 없으며 generated evidence의 debt로
-남습니다. 야잘알의 기존 `AppBadge` 사용처를 canonical Tag renderer로 마이그레이션하고 이
-환경 증거까지 연결한 뒤 stable 승격을 검토합니다.
+Tag contract와 Web/Native surface는 모두 **stable**입니다(1.5.0). 두 first-party renderer의
+scenario matrix가 dark(라이트 전용 색 누수 없음), 2배 글자, RTL, 모션 줄이기, 접근 이름,
+긴 문구 줄바꿈을 실제 계산 스타일로 검사하고 모두 통과했습니다. Web은 실제 브라우저에서
+배치까지, Native는 test renderer의 style 값까지 봅니다.
+
+stable은 전체 환경 인증을 뜻하지 않습니다. screen reader 실사용과 실제 device screenshot은
+제품 기기 QA의 범위입니다.

package/docs/theme-palette.md

@@ -50,3 +50,15 @@ contracts·tree-select까지 연쇄로 초과).
   형태로 보이는지(3:1). 기존 AA 검사가 못 잡던 축이다.
 - `keeps neutral surfaces and text in one low-saturation family per theme` — 중성 역할의
   채도 상한 30%. 강조 역할(`primary`·`contentBrand`·`danger`·`surfaceAccent`)은 제외한다.
+
+## 라이트 `textSub`를 AA로 올렸다 (2026-09-26)
+
+브랜드 팔레트 대비 검사([brand-boundary.md](./brand-boundary.md))를 만들면서 기본 팔레트에 같은 기준을 돌렸더니
+라이트 `textSub` `#6b7684`가 `surface`(`#f2f4f6`) 위에서 **4.19:1**로 본문 AA(4.5)에 못 미쳤다. `textSub`는
+`Text tone="subtle"`의 실제 글자색이라 장식 등급으로 볼 수 없다. 같은 색상·채도에서 명도만 내린 `#65707d`
+(`surface` 4.57:1, `bg` 5.04:1)로 바꿨다. 텍스트 램프 순서(`textMuted` > `textSub` > `textWeak`)는 유지된다.
+모펀은 같은 이유로 이미 `textSub`를 `#626E7D`로 보정해 쓰고 있었다.
+
+`borderControl`은 `#6b7684`를 그대로 둔다. 비텍스트 기준(3:1)이고 `surface` 위 4.19:1로 충분하다.
+
+**버린 대안:** 검사에서 `textSub`를 본문 기준에서 빼기. 실제 글자에 쓰이는 색을 기준에서 빼면 검사가 존재 이유를 잃는다.

package/docs/theming.md

@@ -2,8 +2,9 @@
 
 HJM은 `theme`(light/dark/system) 같은 **환경**과, 그 환경이 해석된 **값**을 분리해서
 받는다. 제품 브랜드색은 값 쪽에 넣는다. 이 문서는 새 제품이 처음 부딪히는 그 경로만
-설명한다. 팔레트를 어떻게 고를지는 [theme-palette.md](./theme-palette.md), 색의 의미
-구분은 [identity.md](./identity.md)에 있다.
+설명한다. **무엇을 어디까지 바꿀 수 있는지와 대비 검사 규칙은 [brand-boundary.md](./brand-boundary.md)가
+단일 원본이다.** 팔레트를 어떻게 고를지는 [theme-palette.md](./theme-palette.md), 색의 의미 구분은
+[identity.md](./identity.md)에 있다.
 
 ## 두 가지 사용 방식
 
@@ -52,29 +53,23 @@ function ProductProvider({ preference, systemDark, children }) {
 }
 ```
 
-React Native는 `HjmNativeProvider`가 같은 `value`를 받는다. 실제 사용 예는 BurnTok의
-`apps/web/src/components/ThemeProvider.tsx`다 — 경계선 색 두 개만 주입하고 나머지는
-기본값을 쓴다.
+React Native는 `HjmNativeProvider`가 같은 `value`를 받는다. `value`를 넘기면 Provider가 OS 설정 관찰을
+멈추므로, 위 예시처럼 system theme 등의 신호를 제품이 구독해 resolver에 넣는다. 실제 사용 예는 BurnTok의
+`apps/web/src/components/ThemeProvider.tsx`(경계선 두 key)와 `apps/mobile/src/components/ThemeProvider.tsx`
+(경계선 두 key + 표면 두 key)다.
+
+팔레트를 바꾸면 제품 테스트에서 대비 검사를 돌린다.
+
+```ts
+import { checkBrandPaletteContrast } from "@hjmds/design-contracts/palette-contrast";
+
+expect(checkBrandPaletteContrast(PRODUCT_BRAND_PALETTE)).toEqual({ light: [], dark: [] });
+```
 
 ## 덮어도 되는 것과 아닌 것
 
-| key | 덮기 | 이유 |
-| --- | --- | --- |
-| `primary` / `onPrimary` / `contentBrand` | 권장 | 브랜드의 자리다. 주 행동과 현재 위치를 이 색이 말한다 |
-| `borderControl` / `focus` | 선택 | 브랜드 채도가 높으면 포커스 대비를 맞추기 위해 함께 조정한다 |
-| `border` / `borderControl` | 선택 | 제품 경계선 밀도가 다를 때. BurnTok이 이 둘만 주입한다 |
-| `bg` / `surface` / `text*` 중성 계열 | 신중히 | 대비 검증이 붙어 있다. 바꾸면 라이트·다크 양쪽에서 4.5:1을 다시 확인한다 |
-| `danger` / `success` / `warning` / `info` | 비권장 | 상태색을 브랜드색으로 바꾸면 "오류"와 "브랜드"가 같은 색이 된다 |
-| 컴포넌트별 색 | 불가 | recipe가 semantic key만 읽는다. 컴포넌트 하나만 다른 색이 되면 그것은 제품 예외지 테마가 아니다 |
-
-## 하지 말아야 할 세 가지
-
-1. **CSS로 `.hjm-*` 클래스를 덮거나 `--hjm-color-*`를 인라인 style로 재정의하지 않는다.** 그 순간 업그레이드마다 깨진다. 필요한 것이
-   semantic key로 표현되지 않으면 그것은 계약 공백이고, 우회가 아니라 이슈로 올린다.
-2. **recipe 값을 읽어 인라인 스타일로 다시 싣지 않는다.** 렌더러가 이미 그 값을
-   칠한다. 제품이 다시 실으면 두 벌이 생기고 한쪽만 갱신된다.
-3. **제공자 브랜드색을 팔레트에 넣지 않는다.** 소셜 로그인 색은 테마가 아니라 남의
-   자산이다 — [AuthProviderButton](./provider-button.md)이 그 자리를 갖는다.
+규칙은 [brand-boundary.md](./brand-boundary.md)에 있다. 요약하면 `brandPalette`의 17개 semantic key만 바꿀 수 있고,
+상태 강조색과 컴포넌트별 색은 바꿀 수 없으며, `.hjm-*`·`--hjm-*` CSS 재정의는 지원하는 경로가 아니다.
 
 ## 어댑터를 두는 이유
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.3.5",
+  "version": "1.5.0",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -46,6 +46,12 @@
       "import": "./dist/color-references.js",
       "default": "./dist/color-references.js"
     },
+    "./palette-contrast": {
+      "types": "./dist/palette-contrast.d.ts",
+      "react-native": "./dist/palette-contrast.js",
+      "import": "./dist/palette-contrast.js",
+      "default": "./dist/palette-contrast.js"
+    },
     "./responsive": {
       "types": "./dist/responsive.d.ts",
       "react-native": "./dist/responsive.js",