@hjmds/design-contracts 0.8.2 → 0.9.1

package/docs/identity.md

@@ -50,7 +50,9 @@ HJM은 장식으로 브랜드를 증명하지 않습니다. 정보와 행동의
 
 - 깨끗한 white canvas와 깊은 navy dark canvas가 기본입니다.
 - HJM blue는 행동과 현재 상태를 드러내는 서명입니다.
-- 그라디언트는 브랜드 마크, hero, 특별한 CTA에만 제한합니다.
+- 공통 `brandGradient`는 HJM 조직 surface와 fallback에만 사용합니다. 제품 hero와 특별한
+  CTA의 브랜드 표현은 제품 어댑터가 소유하며, 모든 앱이 같은 그라디언트를 자동으로
+  복제하지 않습니다.
 - `text`, `textBody`, `textMuted`는 필수 정보에 사용할 수 있습니다.
 - `textSub`, `textWeak`는 장식적·중복적인 정보에만 사용하며 필수 문장에는 쓰지 않습니다.
 - 제품 상태는 먼저 `info / success / warning / attention`에 매핑하고, 제품 이름은 공용
@@ -103,7 +105,8 @@ HJM은 장식으로 브랜드를 증명하지 않습니다. 정보와 행동의
 | product palette | KBO 구단 색상, 코드 미리보기 색상 |
 
 제품 매핑은 앱 또는 제품 어댑터에 남깁니다. HJM 코어에 제품명, 저장 키, 도메인 상태를
-추가하지 않습니다.
+추가하지 않습니다. 공통 HJM 결을 유지하면서 제품을 구별하는 구체적인 경계와 검증 항목은
+[`consumer-policy.md`](./consumer-policy.md)의 "제품 정체성 경계"를 따릅니다.
 
 ## 참고 원칙
 

package/docs/library-gap-analysis.md

@@ -0,0 +1,65 @@
+# 외부 디자인 시스템 gap 분석 — 2026-08-31
+
+## 조사 범위
+
+HJM 0.8.2의 기존 91개 catalog 항목과 아래 공식 component inventory를 대조했다.
+
+- [Radix Primitives](https://www.radix-ui.com/primitives/docs/components)
+- [React Aria](https://react-spectrum.adobe.com/react-aria/getting-started.html)
+- [Chakra UI](https://chakra-ui.com/docs/components/concepts/overview)
+- [Material UI](https://mui.com/material-ui/all-components/)
+- [Mantine](https://mantine.dev/core/package/)
+- [Carbon](https://carbondesignsystem.com/components/overview/components/)
+- [Tamagui](https://tamagui.dev/ui/intro/1.0.0)
+
+빈 이름을 그대로 복사하지 않고 다음 기준으로 평가했다.
+
+1. HJM의 기존 컴포넌트 조합으로 의미가 이미 완결되는가
+2. Web/RN에서 같은 사용자 문제로 번역되는가
+3. 제품 고유 콘텐츠·포맷·navigation을 침범하지 않는가
+4. 접근성 또는 layout 오류를 중앙에서 줄이는가
+5. 작은 public surface로 장기간 유지 가능한가
+
+## 채택
+
+### Container
+
+MUI와 Mantine은 centered max-width + gutter를 독립 layout primitive로 제공하고 Chakra도
+같은 역할을 core inventory에 둔다. HJM에는 `Layout.main`의 암묵적 max-width만 있어
+온보딩·설정·상세 페이지가 shell 없이 같은 폭을 재사용할 수 없었다.
+
+HJM은 임의 px prop을 열지 않고 `reading | content | full`과 token gutter만 공개한다.
+Web은 logical inline margin/padding, Native는 centered `View`와 maxWidth로 번역한다.
+
+### AspectRatio
+
+Radix, Chakra, Mantine, Carbon에서 반복되는 media geometry primitive다. 이미지·동영상·지도
+자체를 소유하지 않고 레이아웃 이동을 막는 비율만 소유하므로 HJM 경계와 잘 맞는다.
+
+HJM은 `square | portrait | landscape | wide`와 양의 custom ratio를 허용한다. crop,
+`object-fit`, alt text, playback은 자식 또는 제품이 소유한다.
+
+### VisuallyHidden
+
+Chakra는 독립 component로, React Aria는 전용 accessibility package로 제공한다. 아이콘이나
+압축된 상태에 추가 문맥을 제공할 때 매번 잘못된 clip CSS를 복제하는 문제를 줄인다.
+
+Web에서만 제공한다. Native는 invisible text node가 읽기 순서를 왜곡할 수 있으므로 host
+control의 `accessibilityLabel`/`accessibilityHint`가 canonical 번역이다.
+
+## 이번에 채택하지 않음
+
+- `Kbd`, `Code`, `Blockquote`: 제품·문서 콘텐츠 표현이며 HJM의 상호작용 계약이 없다.
+- `ScrollArea`: Web custom scrollbar와 Native `ScrollView`는 같은 public 의미가 아니고,
+  기본 host scrolling을 감싸는 것만으로는 결함이 줄지 않는다.
+- `Toolbar`, `Menubar`, `ContextMenu`: desktop keyboard model과 실제 제품 vertical slice가
+  먼저 필요하다.
+- `Heading`: `Section`과 semantic heading level, `Text` typography가 이미 책임을 나눠 가진다.
+- `ProgressCircle`: 새 컴포넌트보다 기존 `Progress`의 presentation axis인지 먼저 검증해야 한다.
+- `Popover`, `DataTable`, `SidePanel`, `CommandPalette`: 계약은 이미 준비되어 있다. 제품
+  vertical slice가 확인되면 planned → beta로 올리며 별도 새 catalog 항목은 만들지 않는다.
+
+## 후속 검토
+
+분기마다 외부 inventory 전체를 다시 복사하지 않는다. 실제 제품에서 두 번 이상 반복된
+문제를 먼저 기록하고, 이 문서의 기준으로 기존 조합과 새 primitive를 비교한다.

package/docs/migration-0.6.md

@@ -1,5 +1,9 @@
 # v0.6 migration
 
+> **역사 문서:** 아래 Git-path 명령은 v0.6 당시의 일회성 전환 기록이며 신규 설치 예제가
+> 아닙니다. 현재 소비 앱은 [`../README.md`](../README.md)의 npm registry 설치 규칙에 따라
+> contracts와 renderer를 같은 정확한 SemVer로 설치합니다.
+
 v0.6은 renderer가 없는 계약 패키지의 역할을 이름에서 분명히 하고, Web/RN 앱이 필요한
 graph만 가져가도록 package boundary를 나누는 breaking release입니다. package name은
 `@hjm/design-system`에서 `@hjmds/design-contracts`로 변경됩니다. 이전 이름 alias나 호환

package/docs/migration-0.9.1.md

@@ -0,0 +1,15 @@
+# 0.9.1 contrast correction
+
+The patch improves boundaries visible in dark product screens and the secondary action outlines in both themes. Upgrade contracts and the Web or Native renderer to the same exact version. No required theme keys or component props are added.
+
+| Role | Previous | Updated | Contrast on neutral surfaces |
+| --- | --- | --- | --- |
+| Dark `border` | `#1e293b` | `#64748b` | 3.07–3.95:1 on `surfaceAlt`, `surface`, `bg` |
+| Dark `textWeak` | `#64748b` | `#8292a9` | 4.62–5.94:1 on the same surfaces; weaker than `textSub` |
+| Secondary Button / IconButton border | `border` | `textSub` | 3.75:1 light / 5.71:1 dark against its `surfaceAlt` fill |
+
+`semanticColors.action.neutral.border` exposes the existing `textSub` theme key for neutral action recipes. Native renderers already resolve these recipes; Web CSS uses the same role. Field idle, focus, invalid, placeholder and hint colors are unchanged.
+
+After upgrading, remove product overrides whose only purpose was restoring these defaults. Keep product-owned treatment for special backgrounds and emphasis. In particular, choose `tone="secondary"` when an icon action needs a visible circular or rounded boundary: the default `ghost` tone remains transparent and has no visible outline.
+
+The reported ratios describe opaque enabled colors on the three named neutral surfaces. They do not establish contrast for tinted surfaces, photos, opacity overlays, disabled states or custom palettes. Light `textWeak` remains decorative; light `textSub` is not sufficient for small text on every neutral surface, so meaningful small light-mode copy should use `textMuted` or stronger. Recheck both themes, focus/invalid states and consumer style overrides in the actual product after updating.

package/docs/stable-core.md

@@ -0,0 +1,26 @@
+# Stable Core 0.8
+
+첫 renderer stable slice는 `Surface`, `Button`, `Field`, `TextArea`다. 이 네 컴포넌트는
+계약이 이미 stable이고 Web/RN renderer가 같은 public intent를 실행한다.
+
+## 승격 증거
+
+- 두 surface의 default·dark·long copy·large text·RTL·reduced motion·accessibility matrix
+- `Field` Web label activation, native Tab stop, invalid description linkage
+- Native `Field` host control의 focus/setText action과 accessible name/hint
+- package granular export와 bundle graph boundary
+- canonical Web/Native Showcase renderer
+
+`Surface`, `Button`, `TextArea`는 추가 keyboard model을 발명하지 않고 host semantics를
+그대로 사용한다. `Field`만 공통 behavior가 있으므로 dedicated keyboard/host-action proof를
+연결한다.
+
+## stable이 보장하지 않는 것
+
+- 제품의 폼 validation 정책이나 서버 오류 번역
+- arbitrary style override 또는 모든 브랜드 palette
+- 모든 OS·브라우저 조합의 영구 호환
+- 제품이 전달한 copy, URL, file의 신뢰성
+
+새 회귀가 발견되면 stable 표면을 조용히 beta로 낮추지 않는다. patch에서 회귀를 고치거나,
+API 변경이 필요하면 Changeset과 migration을 함께 제공한다.

package/docs/visually-hidden.md

@@ -0,0 +1,20 @@
+# VisuallyHidden contract
+
+## 문제
+
+화면에 보이는 아이콘·압축 상태만으로 부족한 문맥을 접근성 트리에 추가할 때 표준 clip
+CSS가 제품마다 복제되고 쉽게 깨진다.
+
+## 계약
+
+자식 copy를 1px geometry로 시각적으로 숨기되 DOM과 accessibility tree에는 유지한다.
+focusable control을 숨기는 용도가 아니며 input, link, button 자체를 자식으로 넣지 않는다.
+
+## 플랫폼 경계
+
+Web 전용이다. Native는 host control의 `accessibilityLabel`과 `accessibilityHint`를 사용한다.
+별도의 보이지 않는 `Text`를 mount하면 읽기 순서와 중복 announcement가 달라질 수 있다.
+
+## 검증 화면
+
+Web Showcase에서 아이콘 action의 추가 문맥과 DOM 잔존을 검증한다.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jim1286/hjm-design-system.git",
@@ -111,12 +112,21 @@
     "./renderer-evidence.json": {
       "default": "./docs/generated/renderer-evidence.json"
     },
+    "./consumer-policy.md": {
+      "default": "./docs/consumer-policy.md"
+    },
     "./components/alert-dialog": {
       "types": "./dist/alert-dialog.d.ts",
       "react-native": "./dist/alert-dialog.js",
       "import": "./dist/alert-dialog.js",
       "default": "./dist/alert-dialog.js"
     },
+    "./components/aspect-ratio": {
+      "types": "./dist/aspect-ratio.d.ts",
+      "react-native": "./dist/aspect-ratio.js",
+      "import": "./dist/aspect-ratio.js",
+      "default": "./dist/aspect-ratio.js"
+    },
     "./components/bottom-navigation": {
       "types": "./dist/bottom-navigation.d.ts",
       "react-native": "./dist/bottom-navigation.js",
@@ -165,6 +175,12 @@
       "import": "./dist/content-state.js",
       "default": "./dist/content-state.js"
     },
+    "./components/container": {
+      "types": "./dist/container.d.ts",
+      "react-native": "./dist/container.js",
+      "import": "./dist/container.js",
+      "default": "./dist/container.js"
+    },
     "./components/data-table": {
       "types": "./dist/data-table.d.ts",
       "react-native": "./dist/data-table.js",
@@ -369,6 +385,12 @@
       "import": "./dist/upload-item.js",
       "default": "./dist/upload-item.js"
     },
+    "./components/visually-hidden": {
+      "types": "./dist/visually-hidden.d.ts",
+      "react-native": "./dist/visually-hidden.js",
+      "import": "./dist/visually-hidden.js",
+      "default": "./dist/visually-hidden.js"
+    },
     "./showcase": {
       "types": "./dist/showcase.d.ts",
       "react-native": "./dist/showcase.js",
@@ -379,7 +401,8 @@
   "files": [
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"

package/docs/consumer-release-gate.md

@@ -1,90 +0,0 @@
-# Consumer release gate
-
-HJM의 canonical `v<version>` tag는 private consumer인 BurnTok Web, BurnTok Native,
-Yajalal Native의 Storybook inventory가 같은 canonical release commit의 generated manifest와 맞는 경우에만
-생성됩니다. canonical repository는 public이고 두 consumer는 private이므로, public caller가
-private reusable workflow를 직접 호출할 수 없습니다. 자동 gate는 canonical에만 보관한 단일
-fine-grained token으로 두 consumer에 `repository_dispatch`를 보내고 결과 evidence를 검증합니다.
-
-릴리스 target의 식별자는 repository 하나가 아니라 **`repository + surface` tuple**입니다.
-현재 matrix는 `burntok-web`, `burntok-native`, `yajalal-native` 세 개입니다. Yajalal에는 현재
-적용 범위인 Web 앱/renderer evidence가 없으므로 `yajalal-web`을 만들어 성공을 가장하지 않습니다.
-
-| target | repository / branch | surface | artifact prefix | evidence binding |
-| --- | --- | --- | --- | --- |
-| `burntok-web` | `jim1286/BurnTok` / `main` | `web` | `hjm-consumer-evidence-burntok-` | `hjm-evidence.json`의 `canonicalRelease` |
-| `burntok-native` | `jim1286/BurnTok` / `main` | `native` | `hjm-consumer-evidence-burntok-native-` | `native-storybook.json` + `dispatch.json`의 `releaseCandidate` |
-| `yajalal-native` | `jim1286/yajalal` / `main` | `native` | `hjm-consumer-evidence-yajalal-` | `native-storybook.json` + `dispatch.json`의 `releaseCandidate` |
-
-두 consumer workflow의 `run-name`은 기존
-`HJM <version> · <correlation_id>`를 유지합니다. canonical이 correlation ID 끝에 target ID를
-붙이므로 run-name/concurrency를 별도로 늘리지 않아도 surface run이 서로 구분됩니다. workflow는
-`github.event.client_payload.surface`를 읽고 허용된 surface만 실행해야 합니다. Native
-`dispatch.json`과 `inventory.releaseCandidate`에는 payload의 `surface`를 그대로 기록합니다.
-
-## 실행 순서
-
-1. authored Changeset을 포함한 source commit을 검증한 뒤 로컬에서 `pnpm release:version`을
-   실행합니다. 생성된 fixed-package version, changelog, dist, generated docs를 하나의 release
-   commit으로 `main`에 push합니다.
-2. `main` push마다 `Release Packages` workflow가 실행되고, `release-candidate` step이 package
-   version을 유일한 trigger로 씁니다. 현재 `v<version>` tag가 이미 있거나 authored Changeset이
-   남아 있으면 `should-release=false`로 두어 나머지 step을 모두 건너뜁니다. tag가 없고 남은
-   Changeset도 없는 push에서만 릴리스를 진행합니다. 이때 `pnpm release:commit:check HEAD^`가
-   push된 commit이 `pnpm release:version` 생성물과 정확히 같은 shape인지(소비된 Changeset,
-   허용된 path, 세 manifest의 lockstep bump, authored bump type과 일치하는 version, 동기화된
-   source version 상수) 먼저 검증하고, 그 다음 package, renderer, Storybook, committed artifact를
-   검증합니다. 실패한 release를 다시 시도할 때는 같은 gate를 그대로 통과하는 `workflow_dispatch`
-   수동 실행을 씁니다.
-3. `scripts/check-consumer-release.mjs`는 설정된 default branch 이름을 확인하고, 두 repository의
-   현재 HEAD를 full SHA로 각각 한 번 캡처한 뒤 그 SHA의 workflow invariant를 검사합니다.
-   BurnTok Web/Native tuple은 같은 캡처 SHA를 공유합니다.
-4. script는 `{ repository, release_sha, version, correlation_id, consumer_ref, surface }` payload로
-   세 `hjm-release-candidate` event를 보냅니다. 같은 repository의 동시 run이 섞이지 않도록
-   공통 correlation ID에 target ID(`burntok-web` 등)를 붙인 고유 correlation ID를 사용합니다.
-   consumer workflow는 `surface`를 검증하고 해당 surface job/evidence만 실행하며, 자체 checkout을
-   `consumer_ref`에, public canonical checkout을 `release_sha`에 고정하고 실제 HEAD를 다시
-   비교합니다.
-5. canonical은 workflow 파일, event, evaluated run name, 생성 시각, 캡처한 consumer
-   `head_sha`가 모두 일치하는 단 하나의 run만 추적합니다. 캡처 뒤 default branch가 이동해
-   다른 SHA에서 실행된 run이나 과거 성공 run은 재사용하지 않고 즉시 실패합니다.
-6. 세 run이 모두 `success`여야 하며, 각 run에서 다음 고유 artifact가 정확히 하나 생성되어야
-   합니다.
-   - `hjm-consumer-evidence-burntok-<burntok-web-correlation-id>`
-   - `hjm-consumer-evidence-burntok-native-<burntok-native-correlation-id>`
-   - `hjm-consumer-evidence-yajalal-<yajalal-native-correlation-id>`
-7. canonical은 artifact ZIP을 다운로드해 evidence JSON, generated manifest, Native dispatch
-   record 안의 repository, surface, canonical release SHA, consumer SHA, version, correlation ID를
-   다시 exact-join합니다. evidence의 `source.id`도 target ID와 같아야 하고 `source.surface` 및
-   inventory projection도 target surface와 같아야 합니다. artifact가 비었거나 만료됐거나 내부
-   값이 다르면 실패합니다.
-8. 위 검증이 모두 끝난 뒤에만 같은 job의 tag step이 실행되어 현재 HEAD에 `v<version>`을
-   생성합니다. token 누락, dispatch 실패, timeout, cancelled/failure run, artifact 누락 또는
-   payload 불일치는 모두 tag 생성을 막습니다.
-
-## Secret과 최소 권한
-
-canonical `hjm-design-system` repository에 Actions secret 하나만 둡니다.
-
-- 이름: `HJM_CONSUMER_SYNC_TOKEN`
-- 종류: fine-grained personal access token 또는 동등한 GitHub App token
-- repository access: `jim1286/BurnTok`, `jim1286/yajalal`만 선택
-- repository permissions:
-  - `Contents: Read and write` — `repository_dispatch` 생성
-  - `Actions: Read-only` — workflow run과 evidence artifact 조회·다운로드
-
-consumer repository에는 `HJM_CANONICAL_READ_TOKEN`이 필요하지 않습니다. canonical은 public이라
-consumer의 기본 `GITHUB_TOKEN`으로 full SHA를 읽을 수 있고, consumer 자체 private checkout은
-각 consumer run의 기본 token으로 수행합니다. broad classic PAT를 복제하거나 소비 앱에 canonical
-token을 저장하지 않습니다.
-
-## 이 gate가 증명하는 것과 증명하지 않는 것
-
-이 gate는 canonical release SHA의 active ID가 실제 exported CSF story에 빠짐없이 연결되고,
-BurnTok Web에서는 built Storybook index에, BurnTok Native와 Yajalal Native에서는 generated
-Native registration과 Storybook CSF index 해석 결과에 결합됐음을 surface별로 증명합니다.
-known planned ID는 문서 registration으로만 남고 active evidence에는 포함되지 않습니다.
-
-inventory 일치만으로 dark/RTL/large-text/accessibility scenario가 실행됐다고 주장하지 않습니다.
-tag 생성과 publish가 끝난 뒤 consumer dependency를 그 version range로 올리고 각 앱의 CI/device gate를
-통과시키는 작업도 별도 adoption 단계입니다.