@hjmds/design-contracts 1.4.0 → 1.5.0

package/docs/generated/showcase-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "designSystemVersion": "1.4.0",
+  "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",
@@ -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/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.4.0",
+  "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",