@hjmds/design-contracts 0.8.2

package/docs/consumer-release-gate.md

@@ -0,0 +1,90 @@
+# 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 단계입니다.

package/docs/content-state.md

@@ -0,0 +1,156 @@
+# ContentState scope axis
+
+**문제.** 로딩·빈 화면·오류는 화면 전체를 대신할 수도, 화면의 한 구역만 대신할 수도
+있다. 야잘알은 이 둘을 위해 이미 서로 다른 컴포넌트를 쓰고 있다 —
+`AppStateView`(화면 전체, 유일한 출구, 채움 버튼)와 `AppStateRegion`(한 구역, 선택적
+복구, ghost + 브랜드 텍스트)(`modules/app-rn/src/components/ui/AppStateView.tsx`,
+`AppStateRegion.tsx`). 이 구분은 `DESIGN_SYSTEM.md` §6 「오류 복구 행동」이 이미
+문장으로 규정해 뒀고, UI 검수(`review.md`)에서 이 축이 없어서 생긴 결함이 확산 1위
+(상태가 화면 크롬을 삼킨다, 6화면+라우트 7개)와 7위(구역 실패를 화면 전체 컴포넌트로
+그린다, 3화면)를 차지했다. 그런데 이 축은 `Result`의 `status`(success/failure/info,
+`docs/result.md`가 이미 확인)에도, `EmptyState`의 시각 recipe에도 없다 — 어느 계약도
+"이 실패가 화면 전체를 막는가, 구역만 막는가"를 모른다.
+
+## 판정 — 새 컴포넌트도 아니고 `EmptyState`/`Result`의 축도 아니다
+
+세 후보를 확인했다.
+
+1. **`EmptyState`에 붙이는 안.** 기각. `emptyStateRecipe`(`src/component-recipes.ts`)는
+   지금 icon/title/description/action의 **시각 토큰만** 있고 descriptor·validator·
+   content 상태 자체가 없다(`loading`을 표현할 수 없다 — 실제 제품은 loading을
+   `AppSkeleton`으로 완전히 다른 모양으로 그린다). scope 축은 loading에도 적용되는
+   축이라 EmptyState 하나로는 담기지 않는다.
+2. **`Result`에 붙이는 안.** 기각. `docs/result.md`가 이미 확인한 대로 Result가 푸는
+   문제(사용자 행동 뒤의 flow terminus — 결제 성공/실패)는 이 축이 관측된 화면
+   (데이터 로드 실패)과 다르다. `status`(success/failure/info)와 `scope`(screen/region)는
+   서로 다른 실물 질문이라 하나의 필드로 묶으면 Result가 갖지 않는 질문(로딩 중엔
+   무엇을 보여줄지)까지 떠안는다.
+3. **독립된 공용 축 + 작은 계약.** 채택. `docs/expansion-roadmap.md`의 「공통 상태 축」
+   표(interaction/availability/value/validation/content)에 들어갈 만큼 여러 컴포넌트가
+   참조할 개념이지만, 그 표의 다른 축과 성격이 다르다 — 그것들은 **한 인스턴스가
+   시간에 따라 오가는 상태**(hover→pressed, idle→loading)인데 `scope`는 **저작 시점에
+   한 번 정해지는 배치 결정**이다(화면을 만들 때 "이 실패가 전체냐 구역이냐"를 정하지,
+   렌더링 도중 전체와 구역을 오가지 않는다). 그래서 `content` 축의 **직교 차원**으로
+   문서에는 나란히 두되, 별도 모듈(`src/content-state.ts`)로 분리했다 — `EmptyState`가
+   나중에 loading을 포함하는 완전한 descriptor를 갖추면 이 모듈의 타입을 `import`해서
+   쓸 자리다.
+
+`content` 축과의 직교 확인: `ContentStateStatus`는 공통 축의 `loading|empty|error`만
+쓴다(`idle`·`success`는 블록 자체를 그리지 않고, `loadingMore`·`complete`는 `LoadMore`
+footer 전용이라 이 계약 밖이다 — footer는 정의상 항상 region이므로 그 축이 필요 없다).
+세 상태 모두 screen과 region 양쪽에서 실제로 관측된다(로딩 스켈레톤은 전체 화면일 수도
+`MatchDetailSectionState`처럼 구역일 수도 있다, 빈 화면도 마찬가지, 오류도 마찬가지) —
+그래서 새 축이 맞다.
+
+## 일반화한 계약
+
+```ts
+const regionError = {
+  status: "error",
+  scope: "region",
+  title: "불러오지 못했어요",
+  description: "기본 경기 정보는 그대로 볼 수 있어요.",
+  action: { label: "다시 불러오기", onAction: retry },
+} satisfies ContentStateDescriptor;
+```
+
+- `scope: "screen" | "region"`. `status: "loading" | "empty" | "error"`(공통 `content`
+  축의 부분집합).
+- `loading`은 `title`/`description`/`action`이 **없다** — `loadingLabel`만 필수다.
+  실제 컴포넌트도 로딩을 스켈레톤만으로 그린다.
+- `action`은 최대 하나다(`Result`의 primary+secondary 두 개짜리 계약과 다르다 — 이
+  문제의 실물에는 복구 행동이 항상 하나였다).
+- `resolveContentStateActionEmphasis(scope)`가 `"sole" | "optional"`을 반환한다.
+  `screen`은 콘텐츠 층의 유일한 행동이므로 강조, `region`은 선택지 중 하나이므로
+  비강조다. Button tone 이름에 직접 묶지 않았다 — HJM의 현재 `ghost` tone
+  (`src/recipes.ts`)은 `content: "textMuted"`로 해석되는데, 이 저장소의 실제 region
+  복구 버튼은 **브랜드 텍스트**다(`AppButton tone="link"`,
+  `modules/app-rn/src/features/match-detail/SectionState.tsx:30`). `ghost`가 아니라
+  브랜드 틴트 저강조 tone이 필요하다는 뜻이라, Button의 tone vocabulary가 그 tone을
+  갖추기 전까지는 제품이 로컬로 매핑한다.
+
+## HJM 기본값 — 접근성이 이 계약의 핵심이다
+
+`scope`가 실제로 강제하는 것은 버튼 두께보다 **접근성 발표 범위**다. 구역 실패를
+낭독할 때 사용자가 화면 전체가 실패했다고 오해하면 안 된다는 요구를
+`resolveContentStateAnnouncement(status, scope)`로 코드화했다.
+
+| status | scope | web role/live | native live/role | focus 이동 |
+|---|---|---|---|---|
+| loading | 무관 | status/polite | polite/progressbar | 안 함 |
+| empty | 무관 | status/polite | polite/text | **안 함** (screen이어도) |
+| error | screen | alert/assertive | assertive/alert | **함** |
+| error | region | alert/assertive | assertive/alert | **안 함** |
+
+세 가지가 이 표에서 의도적으로 대칭이 아니다.
+
+- **empty는 scope와 무관하게 focus를 옮기지 않는다.** §8.4 "빈 상태는 결핍이 아니라
+  초대다"— 화면 전체가 비어도 침묵을 깨고 끼어들 정도로 급하지 않다. `moveFocus =
+  scope === "screen"`을 모든 status에 일괄 적용하면 이 규칙을 놓친다 — 그래서
+  `resolveContentStateAnnouncement`는 `empty` 분기에서 scope를 아예 참조하지 않는다.
+  테스트가 이 함정(모든 status에 같은 공식을 재사용하는 것)을 직접 겨눈다.
+- **error만 scope로 focus 이동이 갈린다.** screen은 지킬 다른 초점이 없으니 블록으로
+  이동해도 안전하지만, region은 사용자가 화면의 다른 곳에서 하던 일이 있을 수 있어
+  강제로 끌어오면 "화면 전체가 죽었다"는 오해를 만든다 — 이게 이 계약이 푸는 핵심
+  문제다.
+- **live/role 자체(assertive/alert)는 error에서 scope와 무관하게 항상 켠다.** 발표
+  **강도**는 실패의 심각성(오류)에서 오지 화면 범위에서 오지 않는다. scope가 바꾸는
+  것은 발표가 사용자의 **초점**까지 끌고 오느냐일 뿐이다.
+
+## 이 축이 아닌 것 — 「상태가 화면 크롬을 삼킨다」와의 경계
+
+UI 검수 표에서 확산 1위(§9, 6화면+라우트 7개)와 7위(§6, 3화면)는 언뜻 같은 결함처럼
+보이지만 서로 다르다.
+
+- **7위(구역→화면 오분류)**는 `scope` **값 선택**이 틀렸다 — 구역 실패인데 `screen`
+  컴포넌트를 골라 실패하지 않은 나머지 콘텐츠까지 덮어썼다. 이 계약의 문서와
+  validator가 두 값의 의미 차이를 명확히 해 막는 종류의 실수다.
+- **1위(크롬 삼킴)**는 `scope: "screen"`을 **올바르게 골랐어도** 나는 실수다 —
+  컴포넌트를 화면 크롬(`AppScaffold`/`AppScreen`) **밖**에 두면 상단바·뒤로가기·탭
+  바까지 함께 사라진다. 이건 값의 문제가 아니라 **배치**의 문제다. 즉 `scope:
+  "screen"`의 진짜 의미는 "화면 전체"가 아니라 **"영구 크롬 안의 콘텐츠 영역
+  전체"**다 — 크롬은 어떤 scope 값도 건드리지 않는다. 이 계약은 JSX 트리를 모르므로
+  (런타임 의존성 금지) 이 불변식을 **강제할 수 없다** — 타입도 validator도 "이
+  컴포넌트가 실제로 크롬의 자손인가"를 알 방법이 없다. 그래서 이 계약은 이 요구사항을
+  **문서화된 렌더러 의무**로만 남기고, 실제 강제는 제품이 구조적 가드로 해야 한다.
+  야잘알의 `modules/app-rn/src/screen-chrome-boundary.test.ts`(JSX 조상을 정적으로
+  세는 vitest)가 정확히 이 역할이고, 참조 구현은
+  `modules/app-rn/src/features/home/HomeScreen.tsx:73-113`(`AppStateView`가
+  `AppScaffold`의 자손)이다. 이 계약을 다음에 다른 제품에 적용하는 저작자는 같은
+  구조적 가드를 그 제품 레이어에 새로 만들어야 한다 — 패키지가 대신해 줄 수 없다.
+
+**결론**: 두 결함은 같은 축(scope) 위에 있지만 방향이 다르다. 하나는 **값 선택
+오류**, 하나는 **배치 불변식 위반**이다. 이 모듈은 전자를 명세하고, 후자는 명세할 수
+없다는 사실과 그 대신 필요한 장치를 문서화한다.
+
+## 플랫폼 번역
+
+Web/RN 모두 아이콘(있으면)+제목+설명+action 세로 배치는 `EmptyState`의 시각 grammar를
+그대로 따른다 — 이 모듈은 그 grammar를 다시 정의하지 않는다. 이 모듈이 추가하는 것은:
+
+- Web: `role`/`aria-live`를 상태 블록 컨테이너 자신에만 건다. region은 그 블록이 속한
+  landmark(예: `main`)의 형제로 존재해야 하고, 별도 landmark를 새로 열지 않는다 —
+  그래야 보조기기가 "페이지의 일부가 바뀌었다"로 읽지 "새 페이지"로 읽지 않는다.
+- Native: `accessibilityLiveRegion`/`accessibilityRole`은 블록 컨테이너에, focus 이동은
+  `moveAccessibilityFocus`가 참일 때만 렌더러가 명시적으로 수행한다(예:
+  `AccessibilityInfo.setAccessibilityFocus`) — 기본값은 발표만 하고 focus는 그대로
+  둔다.
+
+## 검증 화면
+
+- `modules/app-rn/src/features/home/HomeScreen.tsx:73-113` — `AppStateView`가
+  `AppScaffold` 자손. `scope: "screen"`이 크롬 불변식을 지킨 참조 구현.
+- `modules/app-rn/src/features/match-detail/SectionState.tsx:20-56` — `status ===
+  'error'`일 때 `AppNotice announcement="assertive"` + `AppButton tone="link"`,
+  나머지는 `AppStateRegion`(`compact`) 기본 복구 tone(`link`)에 위임. `scope:
+  "region"`의 실물 — 저강조 action이 `ghost`가 아니라 브랜드 텍스트임을 실제로 보여
+  준다.
+- `modules/app-rn/src/screen-chrome-boundary.test.ts:61-74`
+  (`CHROME_ESCAPE_BASELINE`) — 크롬 불변식이 아직 안 지켜지는 파일 11개 21건의 실측
+  목록. `scope: "screen"`을 선택한 화면 중 몇이 아직 배치 불변식을 어기는지 보여주는
+  현재 상태.
+
+`planned → beta` 승격에는 이 모듈을 실제로 소비하는 renderer(예: `EmptyState`가 이
+타입을 받아들이는 시점, 또는 `AppStateView`/`AppStateRegion`이 이 계약으로 재작성되는
+시점)의 vertical slice가 필요하다. 지금은 계약만 있고 어떤 renderer도 아직 이 모듈을
+import하지 않는다.

package/docs/context-panel.md

@@ -0,0 +1,88 @@
+# ContextPanel — 새 컴포넌트를 만들지 않는다
+
+## 이게 무엇인지부터 정해야 했다
+
+`docs/expansion-roadmap.md`의 「Batch 2 — 입력과 탐색」은 `adaptive: Select, Combobox,
+ContextPanel, BottomNavigation`이라고만 적어 두었을 뿐 문제 정의가 없다. crosswalk
+(`src/component-references.ts`)에도 `ContextPanel`을 가리키는 antd source entry가
+**하나도 없다** — `TimePicker`(`targets: ["TimePicker"]`)나 `Drawer`(`targets: ["Sheet",
+"SidePanel"]`)처럼 어딘가 대응이 있는 다른 planned 항목과 다르다. 이름과 카탈로그의
+`category: "overlay"`만으로 판정해야 했다.
+
+이름("문맥 패널")과 자리(overlay, adaptive)로 가장 가능성 높은 해석은 하나다: **선택한
+대상의 상세를 본문 옆에서 보여주는 면 — Web은 사이드 영역, Native는 Sheet.** 이는 antd
+`Drawer`가 실제로 풀던 문제이기도 하다.
+
+## 판정: Drawer 분해가 이미 이 문제를 끝냈다
+
+`docs/ant-design-coverage.md`와 `src/component-references.ts:114`는 이미 `Drawer`를
+`Sheet`(adaptive)와 `SidePanel`(web)로 **decomposed** 처리해 뒀다. 그리고 방금 다른
+저작자가 완성한 `SidePanel`(`src/side-panel.ts`, `docs/side-panel.md`)을 읽어보면, 이
+컴포넌트가 이미 "ContextPanel"이 말하려던 것 그 자체다:
+
+- `modal: false` 축이 **정확히** "본문을 밀어내며 옆에서 보여주되 나머지 페이지는
+  계속 상호작용 가능한, 상세를 보여주는 비-차단 패널"이다 — 로드맵이 말하려던
+  "문맥"의 의미가 이미 여기 있다.
+- `edge: "start" | "end"`로 어느 쪽에 도킹하는지도 이미 계약돼 있다.
+
+Native에서 같은 사용자 의도("선택한 대상의 상세를 본다")를 만들 표면은 이미 `Sheet`
+(`platform: "adaptive"`, `status: "beta"`)다 — Native에는 상시 옆 패널을 놓을 화면
+폭이 없으므로 모달 Sheet로 여는 것이 Select/DatePicker가 이미 채택한 것과 같은 적응
+경로다.
+
+즉 "ContextPanel"이 하려던 일 — **Web에서는 SidePanel(필요하면 `modal:false`로
+비차단), Native에서는 Sheet** — 은 새 컴포넌트가 아니라 **이미 완결된 Drawer 분해를
+어떤 제품이 어떻게 조합해서 쓰느냐**의 문제다. 여기에 `ContextPanel`이라는 셋째 이름을
+얹으면:
+
+- `sidePanelRecipe`의 `edge`/`modal`/`content` anatomy와 거의 같은 것을 다시
+  선언하게 되고,
+- `sheetBehaviorDefaults`의 dismiss 어휘와 거의 같은 것을 Native 쪽에 다시
+  계약하게 되어,
+
+Dropdown이 Menu와 같은 실수를 반복할 뻔한 것과 같은 자리다(`docs/dropdown.md`) — 두
+컴포넌트가 같은 상태를 서로 다른 이름으로 소유하는 문제.
+
+## 대안 검토 — "선택과 결합된 패널"이라면?
+
+`ContextPanel`이 단순한 표면이 아니라 "목록에서 항목을 고르면 자동으로 열리고, 패널을
+닫으면 선택이 풀리는" **결합된 상태**를 뜻할 가능성도 검토했다. 그렇다면 SidePanel/Sheet
+어느 쪽도 갖지 않는 축(선택 key ↔ 열림 상태의 양방향 동기화)이 새로 필요할 수 있다.
+하지만 이를 요구하는 목록형 컴포넌트(`DataTable`, `Tree`)가 아직 하나도 저작되지 않았고
+(둘 다 `planned`, recipe 없음), 이 동기화가 실제로 어떤 모양이어야 하는지 뒷받침할
+vertical slice가 없다. 지금 그 축을 짐작해서 만들면 `Select`의 `open`/`selectedKey`를
+"섞지 않는다"는 이 저장소의 원칙(`docs/architecture.md`「Select와 Combobox의 적응형
+경계」)과 반대로, 검증되지 않은 결합을 먼저 만드는 것이 된다. 이 판정은 그 결합이
+필요한 실제 화면이 나오면 뒤집힐 수 있다 — 아래 참고.
+
+## 판정이 뒤집힐 조건
+
+`DataTable` 또는 `Tree`(둘 다 Batch 3 planned)가 저작되고, 그 목록의 "선택 항목 →
+상세 패널" 흐름이 여러 제품에서 반복해서 같은 동기화 코드를 다시 쓰는 것이 확인되면,
+그때는 새 표면이 아니라 **SidePanel/Sheet를 감싸는 얇은 selection-synced open-state
+헬퍼**(새 recipe 없이 behavior 레벨의 작은 함수 하나)를 여는 쪽을 권한다 — Select의
+`reconcileSelectSelection`이 표면 자체가 아니라 상태 유도 함수만 추가했던 것과 같은
+자리다.
+
+## 배선 명세 제안 (리드 적용)
+
+Dropdown(`docs/dropdown.md`)과 달리 ContextPanel은 alias로 흡수할 단일 기존 이름이
+없다(SidePanel과 Sheet 둘로 나뉘므로). 두 가지 중 리드가 고른다.
+
+**(a) 권고: catalog에서 제거.** `src/catalog.ts`의
+`{ name: "ContextPanel", category: "overlay", platform: "adaptive", status: "planned" }`
+행을 지운다. `component-definitions.ts`의 예약 ID(`ContextPanel: "context-panel"`)는
+남겨 둬도 무해하다 — `componentCatalog`에 없으면 어차피 노출되지 않는다.
+`docs/expansion-roadmap.md`의 「Batch 2」 목록에서 `ContextPanel`을 빼고, 대신 "선택
+항목 상세는 Web `SidePanel`(`modal:false` 옵션 포함) + Native `Sheet`로 이미 커버된다"는
+한 줄을 Drawer 분해 설명 옆에 남긴다.
+
+**(b) 대안: catalog row 유지 + 이 문서만 링크.** 로드맵 문구를 지금 당장 고치기보다
+Component Explorer에서 "ContextPanel"을 검색했을 때 이 문서로 안내되는 쪽이 낫다고
+판단하면 이 대안을 쓴다 — Notification이 catalog row를 유지한 채 `docs/notification.md`
+로 안내한 것과 같은 방식.
+
+이 저작자 판단은 (a)다 — Notification/Dropdown과 달리 ContextPanel은 대응할 단일
+기존 컴포넌트 이름이 없어 alias를 만들 수 없고, catalog에 recipe/behavior 없이 남아
+있는 `planned` 행 자체가 "아직 구현 안 된 진짜 계획"으로 오인될 여지가 있다 — 이미
+Drawer 분해로 완결된 문제를 다시 계획 중인 것처럼 보이게 하는 쪽이 더 나쁘다고 봤다.

package/docs/cross-platform-core-normalization.md

@@ -0,0 +1,118 @@
+# Cross-platform core normalization
+
+Text, Surface, Stack, Grid, Button, IconButton, Tag, Card의 공통 의미 축은 contracts가 소유하고 Web과
+Native renderer는 각 플랫폼 host로 번역한다. 라이브러리 비교와 채택/기각 근거는
+[library-reference-decisions.md](./library-reference-decisions.md)를 따른다.
+
+## Canonical API
+
+| Component | 공통 축 | 기본값 | 공통 anatomy |
+| --- | --- | --- | --- |
+| Text | `variant`, `tone`, `emphasis`, `children` | `body`, `primary`, `regular` | `root` |
+| Surface | `tone`, `bordered`, `padding`, `radius` | `default`, `false`, `none`, `lg` | `root` |
+| Stack | `axis`, `gap`, `align`, `justify`, `wrap` | `block`, `md`, `stretch`, `start`, `false` | `root` |
+| Grid | `columns`, `gap`, `minColumnWidth`, `children` | `gap: md`, `flow: row-major` | `root`, `item` |
+| Button | `tone`, `size`, `loading`, `disabled`, `leading`, `trailing`, `children` | `primary`, `medium`, `false`, `false` | `root`, `leading`, `label`, `trailing`, `spinner` |
+| IconButton | `label`, `tone`, `size`, `shape`, `loading`, `disabled`, `children` | `ghost`, `medium`, `rounded`, `false`, `false` | `root`, `icon`, `spinner` |
+| Tag | `tone`, `children` | `neutral` | `root`, `label` |
+| Card | `tone`, `selected`, `bordered`, `padding`, `title`, `description`, `media`, `children`, `actions` | `default`, `false`, `true`, `md` | `root`, `media`, `body`, `title`, `description`, `content`, `actions` |
+
+공통 타입과 값의 source of truth는 다음과 같다.
+
+- `base-recipes.ts`: Button/Surface tone·size·geometry와 `surfaceDefaults`
+- `component-recipes.ts`: Text/Stack axis와 defaults
+- `grid.ts`: responsive columns/gap/minimum-width descriptor와 공통 layout resolver
+- `icon-button-recipe.ts`: IconButton tone/size/shape, hit target, non-CSS color resolver
+- `tag.ts`: Tag descriptor, recipe, non-CSS presentation resolver
+- `card.ts`: Card slot anatomy와 defaults
+
+## 같은 의미, 다른 host
+
+플랫폼 host 차이를 가짜 공통 prop으로 숨기지 않는다.
+
+| Web | Native | 이유 |
+| --- | --- | --- |
+| Text `as` | Text `align` | HTML element semantics와 Native logical alignment |
+| Surface `as` | 숫자 `padding`/`radius` 허용 | HTML landmark 선택과 Native animation/layout interop |
+| Grid `windowWidth` | Grid `onLayoutResolved`, `itemStyle` | DOM 측정/SSR override와 Native item wrapper 적용 |
+| Button form props, DOM events | Pressable props, Native events | 각 플랫폼 activation 모델 |
+| Card `headingLevel` 2–4 | title에 `accessibilityRole="header"` | Native에는 HTML heading level과 동등한 host primitive가 없음 |
+
+`loading`과 `disabled`는 같은 상태가 아니다. 두 renderer 모두 loading 중 activation을
+막고 busy 상태를 보조 기술에 노출하지만, pending control의 focusability는 유지한다.
+명시적 `disabled`만 host의 disabled 상태가 된다.
+
+IconButton은 보이는 텍스트가 없으므로 현지화된 `label`과 icon `children`을 두 renderer에서
+필수로 받는다. `size`는 36/44/52 visual diameter를 선택하고 small은 Web pseudo hit area와
+Native `hitSlop=4`로 44 target을 만든다. tone 색은 renderer별 표가 아니라 공통 resolver에서
+결정한다.
+
+Surface의 `accent` border도 동일하게 해석한다. `borderAlways`가 `false`이므로
+`bordered=true`일 때만 primary 30% edge를 그리고, `subtle`은 contract가 요구하는
+edge를 항상 그린다.
+
+## 0.5 compatibility aliases
+
+0.6에서 canonical API로 옮길 수 있도록 기존 Native 호출은 당분간 동작한다.
+
+```tsx
+// before
+<Stack direction="row" />
+<Button label="저장" />
+<Tag label="신규" />
+<Surface tone="brand" />
+<Grid descriptor={{ columns: { compact: 1, medium: 2 } }} />
+<IconButton accessibilityLabel="닫기" icon={<CloseIcon />} tone="link" />
+
+// canonical
+<Stack axis="inline" />
+<Button>저장</Button>
+<Tag>신규</Tag>
+<Surface tone="accent" />
+<Grid columns={{ compact: 1, medium: 2 }} />
+<IconButton label="닫기" tone="ghost"><CloseIcon /></IconButton>
+```
+
+- Native `Stack.direction`: `row → inline`, `column → block` deprecated alias
+- Native `Button.label`, `Tag.label`: `children` deprecated alias
+- Native `Surface.sunken`, `Surface.brand`: 각각 `subtle`, `accent` deprecated alias
+- Native `Grid.descriptor`: flat `columns`/`gap`/`minColumnWidth`를 위한 deprecated alias
+- Native `IconButton.accessibilityLabel`, `icon`: `label`, `children` deprecated alias
+- Native `IconButton tone="link"`: `ghost`로 번역되는 deprecated alias
+
+호환 alias는 새 문서와 예제에서 사용하지 않는다. 제거는 major release에서만 한다.
+
+## Reference application notes
+
+상위 판단 원칙은 [library-reference-decisions.md](./library-reference-decisions.md)에만 둔다.
+이번 API에 적용한 구체적 참고점은 다음과 같다.
+
+- [MUI Grid](https://mui.com/material-ui/react-grid/)처럼 responsive columns와 spacing을
+  wrapper descriptor가 아닌 Grid의 직접 public axis로 둔다.
+- [MUI IconButton API](https://mui.com/material-ui/api/icon-button/)의 size/content 분리와
+  [React Aria Button](https://react-aria.adobe.com/Button)의 pending focus 보존을 결합하되,
+  HJM tone/shape/default는 공통 recipe가 소유한다.
+- Native host에는 [React Native accessibility](https://reactnative.dev/docs/accessibility)의
+  accessible name과 `accessibilityState.busy/disabled`를 번역한다.
+
+## Audited next migrations
+
+Tabs와 Select는 단순 alias만 추가하면 두 상태 모델이 동시에 노출되므로 이번 변경에서 억지로
+합치지 않았다.
+
+- Tabs: Web `items[{id,label,panel}]`와 Native `options[{value,label,panel?,badge?}]`를 공통
+  item key/content contract로 옮기고, `size`/`layout`/activation semantics를 동시에 맞춰야 한다.
+- Select: Web collection의 nullable `selectedKey`, sections, open-change reason과 Native의
+  string `value`/`options` modal 모델 사이에 공통 collection/selection resolver가 먼저 필요하다.
+  canonical key callback을 도입한 뒤 `value`/`onValueChange`를 호환 alias로 유지한다.
+
+## Intentional remaining differences
+
+- Web ref는 실제 DOM element이고 Native ref/event/style은 React Native host 계약을 따른다.
+- Web Button은 submit/reset/form association을 제공하고 Native Button은 제공하지 않는다.
+- Web Card는 실제 heading level을 선택할 수 있지만 Native는 header role까지만 보장한다.
+- Native는 layout animation과 계산 결과를 적용하기 위해 숫자 spacing/radius를 확장 입력으로
+  허용한다. 공통 코드에는 token 이름을 사용한다.
+
+이 차이는 parity 실패가 아니라 platform translation이다. tone, size, defaults, state,
+slot anatomy가 달라지면 parity 실패로 간주한다.

package/docs/data-table.md

@@ -0,0 +1,79 @@
+# DataTable contract
+
+**문제.** 사용자가 여러 행의 데이터를 표로 훑고, 필요하면 열 기준으로 정렬하거나
+행을 골라 배치 작업을 한다. antd `Table`은 이 배치에서 **가장 큰 표면**이다 —
+정렬·필터·페이징·선택·확장행·고정열·그룹헤더·요약행을 전부 갖는다. 이 모듈은 그
+표면을 옮기지 않는다. antd `Table` → HJM `DataTable`은 **adapted**
+관계다(`src/component-references.ts`) — decompose하지 않고 한 컴포넌트로 두되,
+문제를 HJM 의미로 다시 번역한다.
+
+**일반화한 계약 — 그리고 계약이 아닌 것.**
+
+- **계약인 것**: 열 정의(`id`·`header`·정렬 가능 여부·정렬 방향·align·width 힌트),
+  행 식별(stable `id`, `disabled?`), 행 선택, 비동기 로딩 상태, 정렬 상태의
+  toggle 규칙.
+- **계약이 아닌 것**: 실제 정렬 실행과 필터링. `Combobox`가 `filtering:
+  "local" | "external"`로 실행 방식을 나누고 검색 실행 자체는 항상 제품(로컬 배열이든
+  서버 쿼리든)에 맡기는 것과 같은 경계다(`src/combobox.ts`). `getNextDataTableSortState`는
+  버튼을 눌렀을 때 **다음 정렬 상태가 무엇이어야 하는지**만 판정하고, 실제 행을
+  재배열하는 일은 하지 않는다.
+- 행 선택은 `CollectionSelectionModel`(`src/behaviors.ts`)을 **그대로** 재사용한다 —
+  `none | single | multiple`, controlled/uncontrolled 쌍 전부 Select/Menu와 같다.
+  새 선택 타입을 만들지 않는다.
+- 로딩 상태는 `AsyncCollectionState`(`idle | loading | loadingMore | empty | error`,
+  각 상태의 message)를 **그대로** 재사용한다.
+- 반대로 **`CollectionItemDescriptor`는 재사용하지 않는다.** 그 타입의 `label`/
+  `textValue`는 "이 항목을 보이는 한 문장과 검색어로 대표할 수 있다"는 Menu/Select
+  전제인데, 표 행은 여러 열의 값으로 이루어져 하나의 대표 문장이 없다. `DataTableRowDescriptor`는
+  `id`와 `disabled?`만 가진 훨씬 좁은 타입이다 — Collection 기본 계약 중 실제로
+  행에 맞는 부분만 가져오고, 맞지 않는 부분(label/textValue/typeahead)은 그대로
+  두었다.
+- `Pagination`(다른 저작자가 이번 배치에서 계약)과 `LoadMore`(이미 beta)는 DataTable이
+  **소유하지 않고 합성**한다. `asyncState`가 `loadingMore`일 때 그 아래 어느
+  컴포넌트를 두는지는 제품 선택이다 — Native 긴 목록에 LoadMore를 쓰듯 Web 표에도
+  같은 패턴이 통한다.
+- 정렬 값은 `"ascending" | "descending"`이며 `null`이 "정렬 없음"이다 — antd의
+  `"ascend"/"descend"` 축약형을 그대로 옮기지 않고 `aria-sort`의 실제 어휘를 썼다.
+  Web renderer가 번역표 없이 그대로 속성에 꽂는다(Slider의 `valueText` pass-through와
+  같은 선택).
+- 헤더 전체 선택 상태는 새 `"none"|"some"|"all"` enum을 만들지 않고 이미 있는
+  `CheckboxState`(`boolean | "mixed"`)를 그대로 반환한다 — 헤더 체크박스가 어차피
+  check/dash로 그리는 값과 같은 타입이라 recipe가 또 번역할 일이 없다.
+- **행 확장(expandable row)은 여기서 소유하지 않는다.** antd Table의 확장행은 문제상
+  이미 beta인 `Accordion`의 disclosure 문제와 겹친다 — 확장/축소 축, 트리거,
+  `aria-expanded`를 또 계약하면 Tag가 Chip의 `selected`와 별도 `closable` 축을 만들지
+  않기로 한 것과 같은 실수가 된다(`docs/dropdown.md`가 Menu/Dropdown에서 이미 같은
+  논리를 적용했다). 확장 가능한 상세 행이 필요한 제품은 `disclosureGroup` 행동
+  계약을 행 단위로 합성한다.
+- **넣지 않은 것(불필요/미측정)**: 열 고정(고정열)과 가로 스크롤 동기화는 렌더러
+  기법이다. 열 리사이즈·드래그 재정렬·그룹 헤더(colgroup)·요약(합계) 행은 실제
+  제품 요구가 측정되지 않았다. 각각 나중에 vertical slice가 나오면 이 문서를
+  갱신하고 새 축을 연다.
+- **roving-tabindex 그리드 키보드 탐색을 만들지 않는다.** 정렬 가능한 헤더는
+  일반 버튼, 선택 셀은 일반 checkbox/radio native tab stop이다 — ARIA grid의 셀
+  단위 방향키 이동은 측정된 요구가 없고 지금 범위보다 훨씬 큰 접근성 표면이라
+  넣지 않는다.
+
+**HJM 기본값.** 정렬 헤더 버튼과 선택 셀은 `control.minTouchTarget`(44) 이상을
+유지한다. 행 hover/selected 배경은 `collectionItemContract`의 `highlightedBackground`/
+`selectedBackground`를 그대로 재사용해 Menu·Select·DataTable이 한 상호작용 색
+어휘를 공유한다 — 새 recipe가 새 hover 색을 발명하지 않는다. 기본 정렬 cycle은
+`three-state`(ascending → descending → 정렬 없음)로, 사용자가 정렬을 완전히
+해제할 수 있는 경로를 항상 남긴다.
+
+**플랫폼 번역.**
+
+- Web: `role="table"`/`"row"`/`"columnheader"`/`"cell"`. **정렬 가능한 헤더는
+  `columnheader` 안의 버튼이지, `columnheader` 자체가 인터랙티브해지는 것이
+  아니다** — Collection 기본 계약의 "interactive item 안에 또 다른 button/link
+  금지"를 뒤집어 표에 적용한 것이다(바깥 컨테이너가 아니라 안쪽 하나의 컨트롤만
+  포커스 가능해야 한다). 정렬 방향은 그 `columnheader`의 `aria-sort`로 그대로
+  나간다.
+- 선택 셀의 checkbox/radio는 CheckboxGroup 선례와 같이 각자 독립 tab stop이다 —
+  별도 roving focus를 만들지 않는다.
+- Native renderer는 이번 배치에 없다(`platform: "web"`) — `behaviorRegistry`의
+  `native` 필드는 breadcrumb·form 같은 다른 Web 전용 계약과 같은 빈 배열
+  자리표시자다.
+
+**검증 화면.** 아직 실제 제품 vertical slice가 없다 — catalog는 `planned`으로
+남고, `beta` 승격은 로드맵 gate(실제 화면 검증)를 통과한 뒤 리드가 진행한다.

package/docs/date-picker.md

@@ -0,0 +1,84 @@
+# DatePicker contract
+
+## 문제
+
+압축된 필드 하나에서 날짜 값 하나를 고른다 — 상시 표시되는 달력이 화면 공간을 쓸 수 없는
+폼/필터 자리(생년월일, 계약일, 시작일 필터)를 위한 것이다. `docs/calendar.md`가 이미
+판정했듯 이 문제의 "격자" 부분은 `Calendar`와 완전히 같은 문제이고, DatePicker가 새로
+푸는 부분은 **그 격자를 트리거+오버레이 뒤에 숨기고, 커밋 시 닫는 생명주기**뿐이다.
+
+## antd 대응
+
+`DatePicker`(data-entry) → HJM `DatePicker`, `direct`. `crosswalk`는 이미 이 이름 그대로
+연결돼 있다(`component-references.ts:76`). `RangePicker`(같은 antd 컴포넌트의 variant)는
+이 계약에 없다 — range 선택 자체를 배제했기 때문이다(아래 참고).
+
+## Calendar와의 경계
+
+`docs/calendar.md`의 판정을 그대로 따른다: 격자(월 표시, 셀, 오늘/선택/비활성, 방향키
+이동)는 `calendar.ts`가 소유하고, 이 파일은 그 위에 세 가지만 더한다.
+
+1. **필드 트리거** — `fieldFrameContract`를 그대로 재사용한다(NumberField, Select가 각자
+   독립적으로 같은 재사용을 하는 것과 같은 이유 — 프레임이 두 벌이면 하나만 바뀌는 순간
+   어긋난다).
+2. **적응형 오버레이** — `selectRecipe.adaptive`와 동일한 `{ web: "popover", native:
+   "sheet" }`. Select가 이미 검증한 패턴을 그대로 따른다(`src/behaviorRegistry.select`,
+   `docs/architecture.md`의 「Select와 Combobox의 적응형 경계」).
+3. **커밋·닫힘 생명주기** — 날짜를 고르면 `onSelectionChange`가 불리고 팝오버/시트가
+   닫힌다. Select의 `selection-requests-close-and-restores-trigger-focus` 시나리오와
+   동일한 결과를 낸다.
+
+`resolveDatePickerGrid`는 `resolveCalendarGridDescriptor`를 그대로 호출한다 — 셀의 의미,
+오늘/선택/비활성 판정, 방향키 산수 중 어느 것도 다시 정의하지 않는다. DatePicker의
+`docs/calendar.md`가 다루는 접근성 회색지대(격자 안 이동)를 다시 열지 않기 위해서다.
+
+## 공개한 상태 축
+
+| 축 | 값 |
+| --- | --- |
+| availability | enabled, disabled, readOnly, busy |
+| value | empty, selected, open |
+| validation | valid, invalid |
+
+Select의 축과 동일하되 `content`(idle/loading/loadingMore/error)는 없다 — 격자 자체가
+비동기 컬렉션이 아니라는 `docs/calendar.md`의 판정이 그대로 이어진다.
+
+### 배제한 축
+
+- **range 선택**: 측정된 수요가 없다(`docs/calendar.md` 참고). 시작~끝 날짜 구간이
+  필요해지면 `DatePickerSelection`을 넓히지 않고 별도 `DateRangePicker` 계약을 여는 쪽을
+  권한다 — 단일 날짜 소비자의 타입을 좁히지 않기 위해서다(Steps가 clickable을 얹지 않고
+  새 축을 배제한 것과 같은 판단 방식).
+- **자유 입력 텍스트 필드(Combobox 스타일)**: antd의 `DatePicker`는 텍스트 입력으로 날짜를
+  타이핑하는 것도 허용하지만, 이 계약은 트리거(버튼)로만 연다 — Combobox의 `inputValue`
+  같은 별도 편집 축을 추가하려면 날짜 문자열 파싱을 이 패키지가 갖게 되어 "제품이 포맷한
+  문자열을 받는다" 원칙과 정면으로 충돌한다. 필요해지면 별도 컴포넌트로 연다.
+- **PageUp/PageDown 월·년 단축키**: `docs/calendar.md`와 같은 이유로 배제.
+
+## HJM 기본값
+
+- 트리거는 `displayValue`(제품이 포맷한 문자열, 예: "2026년 8월 19일")를 보여주고, 없으면
+  `placeholder`를 보여준다. Statistic이 값을 절대 스스로 포맷하지 않는 것과 같은 원칙이다.
+- `clear`는 `onSelectionChange(null, "clear")`를 커밋하고 닫는다 — 별도 "빈 선택 금지"
+  설정을 두지 않았다. 대부분의 날짜 필드는 선택 사항이고(Select가 기본으로 빈 선택을
+  허용하는 것과 같다), 강제로 채워야 하는 날짜 필드는 폼 레벨 validation(`invalid` 축)이
+  이미 표현한다.
+
+## 플랫폼 번역
+
+- Web: 트리거는 `button`(`aria-haspopup="dialog"`, `aria-expanded`). 열린 표면은 실제
+  DOM 포커스가 셀 사이를 이동하는 `dialog` + `grid`다 — Select의 `activeDescendant`
+  리스트박스 패턴과 다르다(Select 팝업의 옵션은 실제 포커스를 받지 않고 트리거가 계속
+  포커스를 쥔다). 날짜 격자는 WAI-ARIA Date Picker Dialog 패턴을 따라 실제 focus가
+  gridcell 사이를 roving하므로, `datePickerBehavior.web.focus`는 `"roving"`이다. 닫히면
+  포커스는 트리거로 복원된다.
+- Native: 트리거는 버튼, 오버레이는 Sheet — Select의 Native 렌더러와 동일한 조합이다.
+- 두 플랫폼 모두 Escape/뒤로가기·바깥 탭·선택 커밋이 같은 세 가지 닫힘 경로를 낸다
+  (`dismiss: ["selection", "escape"/"back", "outside"]`).
+
+## 검증 화면
+
+first-party Web dialog·Native Sheet renderer, 환경 matrix, 기본 실행 증거는 연결되어 surface는
+`beta`다. 다만 `docs/calendar.md`가 밝힌 대로 Yajalal에는 이 문제의 살아있는 vertical
+slice가 아직 없다. 값 하나를 고르는 새 폼 필드가 실제 제품에 생기고 보조기기 증거까지
+쌓이기 전에는 `stable`로 승격하지 않는다.