@hjmds/design-contracts 0.8.2

package/docs/description-list.md

@@ -0,0 +1,75 @@
+# DescriptionList contract
+
+**문제.** 라벨-값 쌍의 묶음 — FA 등급 규정, 선수 프로필, 계약 조건 — 을 일관된 위계와
+반응형 열 배치로 보여줍니다. 야잘알의 FA 등급 시트와 통산 화면이 지금 각자의 자체
+구현으로 이 문제를 풀고 있습니다.
+
+**일반화한 계약.** Statistic과 같은 원칙입니다 — 값은 제품이 이미 포맷한 문자열이고,
+HJM은 stable `id`, `label`, `value`의 반복되는 읽기 순서만 소유합니다.
+
+```ts
+const gradeSheet = {
+  items: [
+    { id: "grade", label: "FA 등급", value: "A등급" },
+    { id: "years", label: "규정 출장 시즌", value: "6시즌" },
+  ],
+} satisfies DescriptionListDescriptor;
+```
+
+- 각 쌍은 독립된 접근성 노드입니다. Statistic 그룹과 같은 원칙으로, renderer는 여러
+  쌍을 하나의 축약된 노드로 합치지 않습니다.
+- `columns`는 1 또는 2만 허용합니다(Statistic의 1–4보다 좁습니다 — 라벨-값 쌍은 통계
+  카드보다 한 줄이 길어 3–4열에서 값이 쉽게 잘립니다).
+
+**HJM 기본값.** 기본 `columns`는 2.
+
+## 큰 글자에서의 전환 — resolver가 소유
+
+이번 검수에서 야잘알 소비 코드가 §5 「큰 글자에서의 전환」 규칙을 다섯 번 어겼습니다.
+매번 화면이 `fontScale >= 1.6`이면 `columns={1}`을 넘기는 식으로 직접 막았고, 그 완화를
+빠뜨린 화면은 조용히 깨졌습니다. 야잘알 `src/components/ui/statistic-renderer-contract.ts`의
+`resolveStatisticColumnCount`가 이미 같은 문제를 "화면이 배율을 판정하지 않고, 최소 칸
+폭을 배율만큼 키워서 좁은 폭과 큰 글자를 같은 계산으로 흡수한다"는 형태로 풀었습니다.
+
+DescriptionList는 이 형태를 **코어 계약 안으로** 가져와 `resolveDescriptionListColumnCount`로
+공개합니다 — Statistic처럼 소비 앱이 각자 재구현하지 않고, 이 패키지가 폭·배율 판정을
+소유합니다.
+
+```ts
+resolveDescriptionListColumnCount(availableWidth, requestedColumns, textScale);
+```
+
+- `availableWidth`가 유효하지 않으면(0 이하, NaN) `requestedColumns`를 그대로 돌려줍니다 —
+  renderer가 아직 레이아웃을 측정하지 못한 첫 프레임을 위한 안전한 폴백입니다.
+- `textScale`은 `DesignSystemProvider`의 연속값을 그대로 받으며 최소 1로 clamp합니다.
+  배율이 1보다 작다고 칸을 더 좁히지 않습니다(§5가
+  막은 방향).
+- 같은 `availableWidth`에서 `textScale`이 커지면 `minItemWidth`가 함께 커지므로 2열이
+  자연히 1열로 줄어듭니다 — 화면마다 반복해야 했던 임계값 분기가 사라집니다.
+
+## Statistic과의 경계
+
+DescriptionList는 Statistic의 "제품이 포맷한 문자열, 독립 접근성 노드" 원칙을 그대로
+따르지만 같은 컴포넌트는 아닙니다. Statistic은 숫자 중심 지표(값이 tabular, 짧고,
+trend를 가질 수 있음)이고 DescriptionList는 임의 길이 텍스트 값의 라벨-값 쌍입니다.
+그래서 `value`에 `trend`가 없고, `columns` 상한이 2로 더 좁으며, `resolveDescriptionListColumnCount`의
+`minItemWidth`(160)는 Statistic의 `minItemWidth`(120)와 다른 값입니다 — 통계 카드보다
+라벨-값 한 줄이 넓게 필요하기 때문입니다.
+
+## 플랫폼 번역
+
+Web/Native 모두 `resolveDescriptionListColumnCount`가 돌려준 열 수로 CSS grid 또는
+flex wrap 레이아웃을 만듭니다. 실제 측정된 컨테이너 폭과 시스템 폰트 배율은 renderer가
+공급하고, 이 계약은 그 두 입력을 받아 열 수만 결정합니다.
+
+## 현재 검증과 남은 증거
+
+first-party Web/RN renderer가 공통 descriptor와
+`resolveDescriptionListColumnCount`를 직접 소비하므로 contract와 두 surface를 `beta`로
+승격했다. Web은 `<dl>/<dt>/<dd>` 구조와 측정 폭 기반 열 전환을, Native는 독립된 라벨-값
+접근성 노드와 window/text-scale 기반 flex 열 전환을 기본 실행 test로 검증한다.
+
+이전 판정이 후보로 든 야잘알 화면은 여전히 승격의 제품 근거로 세지 않는다. 해당 화면은
+단일 열 `List`/`ListRow` 조합이며 DescriptionList의 1/2열 문제와 다르기 때문이다. 실제 소비
+앱에서 이 renderer를 쓰는 1/2열 화면과 200% 글자 크기 실기기 증거는 stable 승격 전까지
+명시적인 debt로 남는다.

package/docs/design-system-provider.md

@@ -0,0 +1,139 @@
+# DesignSystemProvider contract
+
+## 문제
+
+antd `ConfigProvider`는 테마·방향(RTL)·글자 배율·locale 같은 전역 설정을 React Context로
+아래 모든 컴포넌트에 내려준다. 이 패키지는 React도 RN도 import하지 않으므로 "Context로
+내려준다"는 부분(그 자체가 antd `ConfigProvider`의 본체)은 애초에 이 저장소의 물건이 될
+수 없다. 그래서 먼저 물어야 했다: **런타임(Context 전파)을 걷어내고 나면 계약할 것이
+남는가?**
+
+**남는다 — 다만 "provider 컴포넌트"가 아니라 "환경 값의 타입 + 기본값 + 병합 규칙 +
+해석된 색 팔레트"다.**
+`showcaseEnvironmentMatrix`(`src/showcase.ts`)가 이미 theme/direction/textScale/motion
+네 축을 정확히 열거하고 있다는 것이 그 증거였다 — 다만 그건 Showcase 문서 도구가 쓰는
+**닫힌 5개 fixture 시나리오**(`id: "default"|"dark"|"large-text"|"rtl"|"reduced-motion"`)
+이지, 실제 제품이 런타임에 구독할 **열린 값 타입**이 아니다. 이 계약이 그 열린 버전이다.
+
+## 이미 있는 것과 겹치지 않는지 먼저 확인했다
+
+- **theme 축은 이미 완결돼 있다.** `colors.ts`가 이미 `ThemePreference =
+  "system"|"light"|"dark"`, `ResolvedTheme`, `isThemePreference()`를 갖고 있다. 이
+  모듈은 그것을 **재선언하지 않고 그대로 import**한다 — "이미 있는 것과 겹치면 만들지
+  마라"는 지시를 theme 축에는 그대로 적용해 아무것도 새로 만들지 않았다.
+- **direction 축은 겹치는 게 아니라 흩어져 있었다.** `"ltr" | "rtl"`가
+  `BottomNavigationDirection`, `TabsDirection`, `SelectionDirection`, `IconDirection`,
+  `ShowcaseDirection`, 그리고 `calendar.ts`의 인라인 파라미터까지 **최소 6곳에서 각자 다시
+  선언**돼 있었다. 공개 이름은 호환성을 위해 유지하되 모두
+  `DesignSystemDirection`의 type alias로 이관했다. 따라서 기존 import는 깨지지 않고,
+  허용 값의 단일 출처만 Provider 계약으로 모였다.
+- **textScale은 이름도 모양도 이미 두 갈래였다.** `description-list.ts`는 `fontScale`
+  (연속값, `Math.max(fontScale, 1)`로 자체 clamp), `showcase.ts`는 `textScale`(닫힌
+  `1|1.5|2`)을 각자 쓰고 있었다. `DesignSystemTextScale = number`(연속값)를 상류
+  신호로 열었고 DescriptionList의 세 번째 인수와 Showcase fixture 변환 함수가 이 타입을
+  사용한다. Showcase의 닫힌 union과 기존 `motion` 필드는 fixture API 호환을 위해 유지한다.
+- **reducedMotion은 "선호"와 "전략"이 이미 분리돼 있었다.** `foundations.ts`의
+  `ReducedMotionBehavior`("instant"/"opacity"/"static")는 컴포넌트가 Reduce Motion일
+  **때 무엇을 하는지**(전략)이고, `carousel.ts`의 `inputs: ["reducedMotion", ...]`는 그
+  현재 **선호값**(boolean) 하나를 이미 컴포넌트 입력으로 받고 있었다. 이 모듈은 그
+  boolean 선호값의 단일 출처를 계약할 뿐, 각 컴포넌트의 전략(motionPreset)을 대체하지
+  않는다 — 둘은 계속 분리된 채로 둔다.
+
+## 일반화한 계약
+
+- `DesignSystemEnvironmentInput`은 네 필드 모두 **선택**이다 — 렌더러가 아직 일부
+  신호만 알고 있을 수 있기 때문이다(RN의 `AccessibilityInfo.isReduceMotionEnabled()`는
+  비동기라 첫 렌더에는 값이 없을 수 있다).
+- `resolveDesignSystemEnvironment(input, options)`의 우선순위는 축마다
+  **명시 input → 해석된 parent → renderer의 system signal → HJM default**다. 기존 호출의
+  필수 `systemTheme`은 그대로이며 `systemDirection`, `systemTextScale`,
+  `systemReducedMotion`, `parent`만 선택적으로 추가됐다. `theme: "system"`을 명시하면
+  parent보다 현재 `systemTheme`을 우선한다.
+- `resolveDesignSystemProviderValue()`는 이 환경과 `THEMES`, `ACCENTS`, `accentFill`을 묶어
+  `{ environment, palette }`를 반환한다. renderer는 `palette`를
+  `resolveColorReference()`에 그대로 전달한다.
+- `validateDesignSystemProviderValue()`는 renderer에 직접 주입되는 완전한 제품 palette도
+  같은 런타임 경계에서 검사한다. 모든 semantic theme/accent role과 alpha 합성 가능한
+  6자리 hex 값이 필요하며, 일부 token만 덮는 partial override는 허용하지 않는다. 제품
+  palette의 대비 fixture와 승인 책임은 그 완전한 palette를 제공하는 제품 adapter가 가진다.
+- `validateDesignSystemEnvironmentInput()`은 선택형 input을 검사하고,
+  `validateResolvedDesignSystemEnvironment()`는 parent 전용 invariant를 검사한다. 후자는
+  `theme: "system"`, 누락된 축, 잘못된 direction, 0 이하/non-finite textScale, boolean이
+  아닌 reducedMotion을 모두 거부한다. 이미 resolved라는 타입 이름을 런타임에서도 지킨다.
+- **OS 조회 자체는 하지 않는다.** `Appearance`, `AccessibilityInfo`, `I18nManager`,
+  `PixelRatio`, `matchMedia`는 renderer 몫이고 코어는 계속 React/RN/DOM 의존성이 없다.
+
+## HJM 기본값
+
+`designSystemEnvironmentDefaults`: `theme: "system"`, `direction: "ltr"`,
+`textScale: 1`, `reducedMotion: false` — 기존 호출의 fallback과 호환되는 값이다. 실제
+renderer는 이 fallback을 OS 감지 결과로 오해하면 안 되고, root에서 반드시
+`systemReducedMotion`을 공급해야 한다. RN의 비동기 신호를 아직 모르는 첫 프레임에는 adapter가
+애니메이션을 시작하지 않는 정책을 별도로 적용한다.
+
+## 플랫폼 번역
+
+이 모듈 자체는 플랫폼을 분기하지 않는다 — 같은 Provider value를 Web과 Native가
+구독한다. 다른 것은 **system signal을 어떻게 얻고, 값을 어떻게 전파하고, palette를
+어떤 style API로 번역하는가**뿐이다:
+
+- Web: `matchMedia`(색 구성표·prefers-reduced-motion), CSS `dir` 속성(direction),
+  `document.documentElement`의 root font-size 배율. 전파는 React Context.
+- Native: `Appearance`/`useColorScheme()`, `AccessibilityInfo`, `PixelRatio.getFontScale()`
+  또는 `useWindowDimensions().fontScale`, `I18nManager.isRTL`. 전파는 RN Context 또는
+  동등한 상태 저장소.
+
+catalog의 `platform: "shared"`가 맞다. 오버레이(Web popup vs Native Sheet)처럼 표면을
+바꾸는 컴포넌트가 아니라, 같은 값 타입을 두 플랫폼이 각자의 OS API로 채워 넣기 때문이다.
+
+중첩 Provider는 `parent.environment`를 options에 넘긴다. 일부 축만 명시하면 나머지는
+parent에서 상속하고, root Provider는 system signal로 채운다. 이 규칙 덕분에 각 React/RN
+adapter가 자체 병합 로직을 다시 만들 필요가 없다. `parent`에는 반드시
+`resolveDesignSystemEnvironment()` 또는 `resolveDesignSystemProviderValue().environment`의
+결과를 넘긴다. `theme: "system"`인 input 객체를 타입 단언으로 parent에 넣어도 resolver가
+다시 해석하지 않고 즉시 실패한다.
+
+## 공개한 축 / 배제한 축
+
+| 축 | 상태 |
+| --- | --- |
+| `theme`(system/light/dark) | 공개 — `colors.ts` 재사용 |
+| `direction`(ltr/rtl) | 공개 — 새로 정식화 |
+| `textScale`(연속값) | 공개 |
+| `reducedMotion`(boolean 선호) | 공개 |
+| `locale`(언어 코드) | **배제** — RTL 여부는 `direction`으로 이미 표현되고, 숫자·날짜·복수형
+  포맷은 "제품이 포맷한 문자열을 받는다" 원칙상 이 패키지가 몰라도 된다. locale 자체가
+  필요한 제품은 그 값을 직접 들고 있다가 필요한 곳(예: `Intl.DateTimeFormat`)에 쓴다. |
+| React/RN Context, `<Provider>` 컴포넌트, `useDesignSystem()` 훅 | **배제** — 이 패키지는
+  런타임 의존성을 갖지 않는다. 각 제품의 renderer가 이 값 타입을 자신의 Context에 담아
+  전파한다. |
+| `size`(antd ConfigProvider의 컴포넌트 전역 사이즈 프리셋) | **배제** — 측정된 요구가
+  없고, 있다 해도 그건 각 recipe의 `sizes`(예: `selectRecipe.sizes`)가 이미 컴포넌트별로
+  갖고 있는 축이라 전역 오버라이드를 얹으면 두 곳이 같은 축을 다시 소유하게 된다. |
+| 임의 theme/component token override | **partial override는 배제** — HJM light/dark는 대비
+  테스트를 함께 통과하는 고정 계약이다. 별도 브랜드 제품은 모든 semantic role을 가진
+  완전한 `DesignSystemProviderValue`만 renderer의 `value` 경계로 주입하며, 런타임 shape 검사와
+  제품별 전체 대비 fixture를 함께 둔다. |
+
+## 제품 adapter 증거
+
+Showcase fixture만으로 성숙도를 올리지 않는다. 현재는 다음 실제 제품 경계가
+`resolveDesignSystemProviderValue()`의 `environment + palette`를 Context에 저장하고 renderer에
+내려준다.
+
+| 제품 표면 | 실제 adapter 증거 | 검증 경계 |
+| --- | --- | --- |
+| BurnTok Web | `../BurnTok/apps/web/src/components/ThemeProvider.tsx` | `matchMedia`, root `dir`, 저장된 theme preference를 resolver에 넣고 Context가 `providerValue`, `environment`, `palette`를 공개한다. OS 축은 system option으로 전달하므로 nested `parentEnvironment`가 omitted axis보다 먼저 적용된다. `palette.theme.bg`는 브라우저 theme color에 실제 적용된다. `ThemeProvider.test.tsx`가 이 경계를 검증한다. |
+| BurnTok RN | `../BurnTok/apps/mobile/src/components/ThemeProvider.tsx` | `useColorScheme`, `I18nManager`, `useWindowDimensions().fontScale`, `AccessibilityInfo`의 신호를 system option으로 해석하고 `parentEnvironment` 상속 및 명시 fixture를 지원하며 `palette.theme`을 Native style renderer의 `colors`로 제공한다. |
+| Yajalal RN | `../yajalal/modules/app-rn/src/lib/theme/provider-adapter.ts`, `ThemeProvider.tsx` | HJM resolver로 환경 우선순위와 `parentEnvironment`의 omitted axis 상속을 해석하고 `validateResolvedDesignSystemEnvironment()`로 검증한 뒤, 기존 제품 팔레트만 검토된 adapter로 바꾼다. `ThemeProvider.test.ts`가 해석된 환경과 팔레트를 검증한다. |
+
+Showcase의 `DesignSystemProvider` Web reference는 이 증거를 대신하는 가상 UI가 아니다.
+동일한 provider value의 theme, direction, textScale, reducedMotion과 해석된 palette를
+직접 표시하는 비시각 adapter presentation이다.
+
+## 현재 성숙도
+
+catalog 상태는 `beta`다. Web과 RN, 두 제품에서 값 해석·Context 전파·palette 소비,
+중첩 Provider의 omitted axis 상속 경계까지 확인됐다. 다만 이 상속 adapter가 포함된
+추가 제품 릴리스 증거는 아직 없으므로 roadmap은 다음 승격 조건을
+`evidence-needed`로 기록하고 `stable`을 과장하지 않는다.

package/docs/dropdown.md

@@ -0,0 +1,78 @@
+# Dropdown — 별도 컴포넌트를 만들지 않는다
+
+## 판정
+
+Ant Design에서 `Dropdown`은 "트리거에 붙는 오버레이"이고 그 안의 항목 목록은 별도
+컴포넌트 `Menu`가 채운다. 두 컴포넌트가 나뉜 이유는 Ant Design의 Dropdown이 임의
+콘텐츠(`dropdownRender`)도 담을 수 있는 범용 오버레이 셸이기 때문이다.
+
+HJM에는 이 분리가 없다. `menuRecipe`(`src/component-recipes.ts:628`)의 anatomy는 이미
+`trigger, content, viewport, section, sectionLabel, item, ...`이고, `behaviorRegistry.menu`
+(`src/behaviors.ts:815`)는 `open`/`defaultOpen`/`onOpenChange`/`selection`/`asyncState`를
+직접 controlled 축으로 가진다. 즉 HJM의 `Menu`는 이미 **트리거 + 떠 있는 표면 + 항목
+목록**을 한 컴포넌트가 끝까지 소유한다. `expansion-roadmap.md`도 Menu를 "Web anchored
+surface와 RN Sheet가 같은 결과를 만드는 adaptive 슬라이스"로 이미 beta 검증했다고
+기록한다.
+
+그래서 Ant Design 기준 "Dropdown"이 실제로 풀던 문제 — 트리거를 누르면 뜨는 action
+목록 — 는 HJM에서 이미 `Menu` 하나로 완결된 문제다. 여기에 이름만 다른 `Dropdown`을
+새로 만들면:
+
+- `menuRecipe`와 거의 같은 `trigger`/`content`/`viewport` anatomy를 다시 선언하게 되고,
+- `behaviorRegistry.menu`와 거의 같은 `open`/`dismiss`/`selection` 축을 다시 계약하게
+  되어, 두 컴포넌트가 같은 상태를 서로 다른 이름으로 소유하는 정확히 그 실수(Tag가
+  `docs/tag.md`에서 Chip의 `selected`와 별도 `closable` 축을 만들지 않기로 한 것과 같은
+  종류의 실수)를 반복한다.
+
+## 임의 콘텐츠 오버레이는 이미 다른 곳에 있다
+
+**셋 중 2번 선택지 검토.** "Menu는 항목 collection만 다루고 Dropdown은 임의 콘텐츠를
+담는 표면"이라는 분리가 가능한지 검토했다. 그런데 "트리거에 붙어 임의 콘텐츠를 보여
+주는 Web 오버레이"는 이미 catalog에 `Popover`(`category: overlay`, `platform: web`,
+`status: planned`)로 자리를 예약해 두었다. Ant Design의 crosswalk도 `Popover`를
+`category: "data-display"`, `relationship: "direct"`로 이미 별도 target에 연결해 두었다
+(`src/component-references.ts:102`). 즉 "임의 콘텐츠 담는 트리거 오버레이"라는 문제는
+HJM 안에서 이미 `Popover`의 이름표를 달고 대기 중이다.
+
+여기서 `Dropdown`을 "임의 콘텐츠"용으로 다시 정의하면 `Popover`와 완전히 같은 문제를
+두 이름으로 계약하게 된다. 브리프가 명시한 대로 Popover와 Dropdown을 동시에 만들지
+않기로 하고, 두 planned 항목 중 실제 제품에서 먼저 요구가 나오는 쪽만 계약한다. 지금은
+어느 쪽도 vertical slice 근거가 없으므로 **아무것도 만들지 않는다.**
+
+## 결론
+
+1. Menu가 이미 트리거+표면+항목 목록의 문제를 완결한다 — antd Dropdown의 압도적 다수
+   사용법("Dropdown + Menu" 조합)이 정확히 이 문제다.
+2. Dropdown이 항목 목록이 아닌 임의 콘텐츠를 위한 것이라는 대안은 이미 `Popover`가
+   점유한 문제와 구분되지 않는다.
+3. 측정된 제품 수요 없이 겹치는 두 표면을 만들지 않는 것이 이 저장소의 원칙이다
+   (`docs/authoring-brief.md`: "없는 컴포넌트를 만드는 것보다 안 만드는 이유를 남기는
+   것이 이 저장소에 더 값지다").
+
+`src/dropdown.ts`, `test/dropdown.test.ts`는 만들지 않는다. `antDesignReferenceComponents`의
+`Dropdown → Dropdown` crosswalk(`relationship: "direct"`)도 바꿀 필요가 없다 — target
+`ComponentId`는 유지하되, catalog의 실제 구현 결정만 아래로 옮긴다.
+
+## 배선 명세 제안 (리드 적용)
+
+두 가지 중 하나를 리드가 고른다. 이 저작자의 권고는 (a)다.
+
+**(a) 권고: Menu의 alias로 흡수.**
+
+```ts
+{ name: "Menu", category: "navigation", platform: "adaptive", status: "beta",
+  recipe: "menuRecipe", behavior: "menu", aliases: ["Dropdown"] }
+```
+
+기존 `{ name: "Dropdown", ... status: "planned" }` catalog row는 제거한다. Ant Design
+crosswalk의 `Dropdown` source entry는 그대로 두되(같은 `Menu` target을 이미 가리키고
+있어 변경이 필요 없다), Component Explorer의 "Dropdown" 검색은 `aliases`를 통해 Menu로
+안내된다.
+
+**(b) 대안: planned 유지 + 이유만 기록.** catalog row를 건드리지 않고 이 문서만 링크한다.
+alias 흡수가 Component Explorer 표시 방식과 충돌하거나 추후 Menu가 collection 전용으로
+좁아질 계획이 있다면 이 대안을 쓴다.
+
+이 저작자 판단으로는 (a)가 맞다 — `aliases`는 이미 `FloatingActionButton: aliases:
+["FloatButton", "FAB"]`처럼 "다른 생태계 이름으로 찾아와도 같은 HJM 컴포넌트로
+안내한다"는 정확히 이 용도로 쓰이고 있다.

package/docs/expansion-roadmap.md

@@ -0,0 +1,285 @@
+# HJM Design System Expansion Roadmap
+
+## 무엇을 흡수하는가
+
+HJM은 외부 라이브러리의 외형이나 public prop 이름을 복사하지 않습니다. 각 시스템에서
+잘 검증된 문제 분해 방식만 가져와 HJM의 문장인 **“조용한 화면 위에 중요한 순간만
+선명하게”**에 맞게 다시 설계합니다.
+
+| 참고 시스템 | 흡수할 것 | 그대로 가져오지 않을 것 |
+| --- | --- | --- |
+| Ant Design | 넓은 컴포넌트 범위, Form/Field 역할 분리, async 상태 | 시각 스타일, variant 이름, runtime dependency |
+| Radix Primitives | compound anatomy, focus·dismiss·keyboard acceptance table | DOM primitive를 RN까지 강제하는 구조 |
+| React Aria | stable key 기반 collection, selection mode, 국제화·키보드 모델 | React hook과 DOM 구현 |
+| Material | 상태 축 조합, adaptive layout, non-text contrast | Material shape·motion·component appearance |
+| TDS | 모바일 정보 위계, 작은 핵심 세트, ListRow 중심 조합 | 전용 자산·폰트·컴포넌트·이름의 복제 |
+| Polaris | component lifecycle, page/pattern catalog | Shopify 도메인 어휘 |
+| Tamagui | typed variant, Web popup/Native sheet의 adaptive intent | 스타일 엔진과 package dependency |
+
+공식 참고 링크는 `docs/identity.md`의 참고 원칙에 고정합니다. 새 라이브러리를 참고할 때도
+`문제 → 일반화한 계약 → HJM 기본값 → 플랫폼 번역 → 검증 화면`을 기록해야 합니다.
+
+### 「검증 화면」에 후보를 적을 때
+
+**구체적인 화면·컴포넌트 이름은 실제 코드에서 확인한 뒤에만 적습니다.** 확인하지 않았으면
+`아직 없음`이 정확한 값이고, 그것만 적는 것이 정직한 문서입니다.
+
+이 규칙이 필요한 이유는 **게이트가 여기를 못 보기 때문**입니다. `pnpm typecheck && pnpm test`는
+이 저장소 안만 검사합니다. 그래서 "만들지 않는다" 판정은 근거가 저장소 안(다른 모듈의 계약)에
+있어 어긋나면 테스트가 잡지만, 「검증 화면」은 근거가 **저장소 밖**(제품 코드)에 있어 같은
+실수라도 걸리는 그물이 없습니다. 실제로 네 문서가 존재하지 않는 화면을 후보로 적어 두었고,
+승격을 실측하기 전까지 아무도 몰랐습니다(`docs/consistency-audit.md` 3차).
+
+그래서 후보를 적을 때는 **`파일:줄` 형태로 인용합니다.** 인용이 그 자체로 증명은 아니지만,
+적는 사람이 파일을 열게 하고 읽는 사람이 반증할 수 있게 합니다. 인용할 수 없으면 그것은
+후보가 아니라 짐작이고, 짐작은 적지 않습니다.
+
+Ant Design의 현재 전체 범위는 [`ant-design-coverage.md`](./ant-design-coverage.md)와
+`antDesignReferenceComponents`에 6.6.1 core 73개로 고정합니다. 73/73은 scope tracking이며
+renderer 완료를 뜻하지 않습니다. 홈과 Showcase는 Web reference, contract-only, Native-only
+증거를 표시하고, reference crosswalk의 fully mature, partial maturity, planned-only 수치와
+분리합니다.
+
+## 확장 구조
+
+```text
+Foundations ───────────────┐
+Semantic color references ├─ Component fragments ─ Visual recipes ─┐
+                           │                                         ├─ Web renderer
+Behavior contracts ────────┤                                         ├─ RN renderer
+Collection contracts ──────┘                                         └─ Product adapter
+```
+
+- `component-contracts.ts`: focus, field frame, floating surface, collection item처럼 여러
+  recipe가 공유하는 내부 문법
+- `component-recipes.ts`: anatomy, size, tone, visual state
+- `behaviors.ts`: controlled state 이름, 유효한 state axis, Web keyboard/focus, RN
+  accessibilityState, 공통 acceptance scenario
+- `catalog.ts`: 구현 범위, 플랫폼 분류, maturity와 recipe/behavior 연결
+
+시각 recipe만으로 구현 완료를 주장하지 않습니다. Menu, Tabs, Dialog처럼 행동이 중요한
+컴포넌트는 behavior scenario까지 renderer 테스트가 통과해야 합니다.
+
+## 공통 상태 축
+
+| 축 | 값 |
+| --- | --- |
+| interaction | idle, hover, focusVisible, pressed, dragged |
+| availability | enabled, disabled, readOnly, busy |
+| value | empty, filled, checked, mixed, selected, open, expanded |
+| validation | valid, invalid |
+| content | idle, loading, loadingMore, empty, error |
+
+컴포넌트는 필요한 축만 공개합니다. 예를 들어 Link는 disabled를 지원하지 않고, AlertDialog는
+outside dismiss를 지원하지 않습니다. 반드시 별도 fixture로 검증할 조합은
+`selected + focusVisible`, `invalid + focusVisible`, `busy + focusVisible`,
+`open + selected item`입니다.
+
+## Collection 기본 계약
+
+Menu, Select, Combobox, DataTable, Tree가 서로 다른 데이터 모델을 만들지 않도록 다음을
+공유합니다.
+
+- stable string `id`
+- 보이는 `label`과 typeahead/검색용 `textValue`
+- 선택적 `description`, `disabled`; 위험 `tone`과 `shortcut`은 Menu descriptor에만 추가
+- section의 보이는 label 또는 accessibility label
+- `none | single | multiple` selection mode
+- `idle | loading | loadingMore | empty | error` async state
+- interactive item 안에 또 다른 button/link 금지
+
+제품 객체를 recipe에 직접 넘기지 않습니다. 제품 adapter가 목적에 맞는 descriptor로 변환하며
+도메인 ID를 유지하고, semantic tone은 그 의미를 지원하는 컴포넌트에만 전달합니다.
+
+## 공개 배치
+
+### 현재 실제 앱에서 검증 중
+
+- Button, Field, Surface
+- IconButton, Badge, CounterBadge
+- SegmentedControl, Tabs, SearchField
+- Checkbox, CheckboxGroup, RadioGroup
+- List, ListRow, Divider, Section
+- Notice, EmptyState, Skeleton
+- Sheet, Dialog, Toast, BottomCTA, TopBar
+- Select, Combobox
+
+### Batch 1 — 기반과 행동 검증 (beta 적용 중)
+
+- shared: Icon, Stack, Checkbox/CheckboxGroup/RadioGroup, Accordion
+- adaptive: Link, Menu, AlertDialog
+- web: Tooltip
+
+Accordion은 disclosure behavior의 첫 shared 세로 슬라이스, Menu는 Web anchored surface와 RN
+Sheet가 같은 결과를 만드는 adaptive 슬라이스, AlertDialog는 focus/back/async confirm을
+검증하는 overlay 슬라이스로 사용합니다.
+
+Tooltip은 현지화된 plain text 보충 설명만 허용하는 Web 전용 overlay입니다. focus는 즉시,
+pointer는 지연 후 열고 trigger/content hover·pointer corridor·Escape·skip delay·한 번에 하나만
+열림을 provider가 조정합니다. portal/flip/shift/RTL/visual viewport는 제품 Web renderer의
+비공개 AnchoredOverlay에 두고 interactive Popover로 확장하지 않습니다. 상세는
+`docs/tooltip.md`에 둡니다.
+
+BurnTok 알림 버튼 vertical slice에서 실제 anchor clone, 기존 `aria-describedby`, focus와
+pointer 수명주기, controlled close 거부, sibling FIFO, detached anchor, portal RTL과 viewport
+collision을 검증했습니다. Tooltip surface는 interaction을 추가하지 않고 plain copy만
+제공하며 Reduce Motion exit도 같은 완료 경계를 지나므로 Tooltip을 Web beta로 승격합니다.
+
+Icon은 외부 package component를 화면에서 직접 고르는 방식 대신 HJM semantic name을 제품
+adapter가 tree-shakeable glyph로 번역합니다. 기본은 decorative이며 정보 icon만 현지화된
+접근성 이름을 요구하고, 논리 방향 icon만 RTL에서 mirror합니다. 상세는 `docs/icon.md`에 둡니다.
+
+Link는 Button callback이 아니라 필수 `href`가 있는 목적지입니다. Web은 실제 anchor/Next Link로
+modifier click·context menu·새 탭을 보존하고, Native는 internal Expo Router Link와 external
+Linking adapter로 적응합니다. disabled·visited application state·download는 공통 API에 넣지
+않습니다. BurnTok 메시지 목록의 고정 conversation-row adapter에서 Web anchor와 Native
+`Link asChild`, unread 접근성 이름, modifier/context navigation, pressed feedback을
+검증했으므로 Link를 adaptive beta로 승격합니다.
+Stack은 반복되는 내부 flex를 감싸는 것만으로 제품 의미나 접근성 계약이 생기지 않으므로 실제
+paired layout 요구가 나타날 때까지 planned recipe 이상으로 공개하지 않습니다.
+
+BurnTok Web/RN과 Yajalal RN의 Toast tone mark, Yajalal Statistic trend mark에서 같은 semantic
+registry·tone·size·stroke·RTL 계약을 실제 renderer로 검증했습니다. 제품 전용 야구 icon은
+별도 adapter에 남기고 raw color·숫자 size·stroke override가 공용 API로 새지 않게 했으므로
+Icon을 beta로 승격합니다.
+
+AlertDialog는 `idle → busy → error/closing → closed` session을 공통 기반으로 삼습니다.
+confirm side effect와 결과 정산을 별도 once guard로 나누지 않고 한 session이 소유하며,
+outside dismiss는 영구 금지합니다. Web의 exit 완료와 Native Modal dismissal 이후에만 결과를
+정산하므로 중첩 확인도 동시에 두 개가 열리지 않습니다.
+
+Sheet는 beta 단계에서 `SheetOpenState`, concrete dismiss reason, `SheetDismissPolicy`와
+`canDismissSheet`를 공통 계약으로 고정합니다. 기본값은 close/outside/Escape·back 허용,
+busy dismiss와 swipe 금지입니다. controlled owner의 programmatic close는 항상 허용하고,
+후속 overlay는 exit/onDismiss가 끝난 뒤 엽니다. drag handle은 swipe gesture capability와
+명시적 policy가 모두 켜진 renderer에서만 보여 동작하지 않는 affordance를 만들지 않습니다.
+visual recipe는 border/shadow, 콘텐츠 typography rhythm, Web max-width, safe-area, Reduce Motion만
+담고 dismiss behavior는 포함하지 않습니다.
+
+Toast는 root provider의 bounded FIFO와 stable-id update를 공통화합니다. queued 항목에는 timer를
+시작하지 않고 visible 동안 pointer/focus/window/gesture pause를 합성하며, action과 dismiss는
+한 revision에서 정확히 한 번만 처리합니다. 외형 tone과 announcement priority를 분리하고 모든
+tone을 고유 icon mark와 함께 표시합니다. 상세 계약은 `docs/toast.md`에 둡니다.
+
+선택 입력은 단일 mode prop으로 합치지 않습니다. Checkbox, CheckboxGroup, RadioGroup이
+시각 recipe만 공유하고, Checkbox는 각 native tab stop, RadioGroup은 roving focus를 갖습니다.
+그룹 값은 stable string id와 `ReadonlySet` 또는 nullable single key만 사용합니다.
+
+### Batch 2 — 입력과 탐색 (beta 적용 중)
+
+- shared: Steps, Statistic, Slider, NumberField, LoadMore
+- adaptive: Select, Combobox, BottomNavigation
+  - `ContextPanel`은 이 목록에서 뺐다. 선택 대상의 상세를 옆에 보여 주는 문제는
+    `Drawer`를 분해할 때 이미 **Web `SidePanel`(+`modal: false`) / Native `Sheet`**로
+    답이 나와 있었다. 로드맵이 컴포넌트 이름을 먼저 적어 두고 문제 정의를 나중으로
+    미루면 이런 중복이 생긴다 — 근거는 `docs/context-panel.md`.
+- web: Pagination, Breadcrumb
+
+Statistic은 제품이 포맷한 문자열을 받아 label/value/hint/trend 위계만 통일합니다. trend 방향과
+semantic tone은 독립이고 arrow/minus와 visible copy를 함께 사용합니다. 그룹은 각 값을 하나의
+축약된 접근성 노드로 합치지 않습니다.
+
+Yajalal의 선수·FA 기록 vertical slice에서 기존 StatGrid 호환 adapter와 새 Statistic renderer를
+함께 검증했습니다. 좁은 폭에서는 1열까지 reflow하고 큰 글자에서도 값을 줄 수로 자르지 않으며,
+각 통계의 label/value/hint/trend를 독립된 접근성 이름으로 유지하므로 Statistic을 beta로
+승격합니다.
+
+Select/Combobox는 Menu의 collection contract를 공유하지만 role과 dismiss behavior는 별도입니다.
+Web은 listbox popup, Native는 Sheet를 사용합니다. Native 긴 목록에는 페이지 번호보다
+LoadMore/infinite loading을 사용합니다.
+
+LoadMore는 `ready | loading | error | complete` footer state와 stable `requestKey`만 공유합니다.
+Web IntersectionObserver와 Native onEndReached는 플랫폼 renderer가 소유하고, 공통 controller는
+요청 하나만 통과시켜 반복 viewport event와 retry 중복을 막습니다. automatic mode도 접근 가능한
+manual fallback을 유지합니다.
+
+BurnTok 홈 피드 vertical slice에서 Web IntersectionObserver와 항상 보이는 manual fallback,
+Native FlatList onEndReached와 footer fallback을 같은 controller에 연결했습니다. 두 renderer 모두
+탭과 다음 offset으로 requestKey를 만들고 실제 페이지 요청 Promise가 끝날 때까지 중복 호출을
+차단하며 loading/error/complete 접근성 상태를 검증했으므로 LoadMore를 beta로 승격합니다.
+
+BottomNavigation은 route source-of-truth를 복제하지 않고 `selectedKey`를 input으로만 받습니다.
+Web renderer는 실제 link와 `aria-current`, Native renderer는 navigator의 preventable tabPress와
+long press를 보존합니다. 숫자 badge는 visual subtree를 접근성에서 숨기고 item root에 합성된
+이름을 한 번만 전달합니다. BurnTok 중앙 생성 action은 `center-gap`에 놓이는 sibling primary
+action이며 destination collection에는 들어가지 않습니다. BurnTok Web/RN과 Yajalal RN 실제
+navigation에 적용해 route state·disabled/reselect·긴 글자·safe area·RTL 계약을 검증했으므로
+BottomNavigation을 beta로 승격합니다.
+
+선행 타입은 Select의 nullable stable key와 Combobox의 `selectedKey`/`inputValue` 분리를
+고정합니다. local filtering과 server-driven external filtering도 구분해 선택 상태와 비동기
+검색 상태가 서로 덮어쓰지 않게 합니다. 실제 제품 흐름에서 확인된 stable key, stale result,
+committed item snapshot만 공개하고 임의 값 생성이나 option 내부 action은 아직 추가하지 않습니다.
+
+`validateCollection`, `flattenCollectionItems`, `resolveCollectionItem`,
+`reconcileSelectSelection`은 먼저 공개합니다. item ID는 section 전체에서 유일하고 보이는
+label·typeahead용 textValue·section accessible name은 비어 있을 수 없습니다. Select의 open
+state도 selection state와 별도 controlled/uncontrolled 축으로 유지합니다.
+
+### vertical slice가 없는 계약 — 채택 전 확인할 것
+
+surface별 `planned → beta` gate는 public renderer export와 package CI가 실행하는 canonical
+`default` proof를 요구합니다. 실제 제품 vertical slice는 별도의 adoption evidence이며,
+없다면 beta의 환경 debt와 함께 공개되고 stable 승격을 막습니다. 제품 채택을 검토하는
+과정에서 **전제가 이미 바뀌어 있던 사례**도 나왔습니다.
+
+`Calendar`·`DatePicker`를 위임할 때 "야잘알 일정 찾기가 월 달력 격자를 자체 구현 중"이라는
+전제를 줬는데, 저작자가 소스를 직접 확인해 그 전제가 **커밋 `0f4887c`(「일정 탐색기 월
+그리드를 날짜 레일로 교체」)에서 이미 깨졌다**는 것을 찾아냈다. `buildCalendarCells`는
+남아 있지만 렌더되지 않고 월 범위 쿼리의 내부 계산일 뿐이며, 화면은 월 헤더 + 7일
+날짜 레일이다. 앱 전체에 값 하나를 고르는 압축 트리거 UI도 없다.
+
+이후 DatePicker에는 first-party Web·Native renderer와 canonical 환경 증거가 추가되어
+`beta`로 승격됐다. 다만 위 실측은 여전히 유효하다. **제품 adoption evidence는 없고**,
+Yajalal의 날짜 레일을 DatePicker 채택으로 세지 않는다. 따라서 `stable` 승격 근거는 없다.
+
+**교훈**: 위임할 때 준 실사용처 전제를 저작자가 **확인하게** 해야 한다. 리드의 기억은
+커밋 하나로 낡는다.
+
+### Batch 3 — 복합 데이터와 파일
+
+- beta: Timeline, UploadItem, DatePicker, FilePicker
+- planned: TimePicker
+- web: DataTable, Tree, ColorPicker, CommandPalette, SidePanel, Popover
+
+FilePicker는 파일 선택 의도만 소유합니다. 업로드 요청·재시도·서버 상태는 제품이 소유하고,
+공유 UI에는 UploadItem의 progress/success/error/cancel 표현만 둡니다.
+
+## 제품 적용 순서
+
+### BurnTok
+
+1. SearchField, CounterBadge, ShareSheet/ListRow
+2. messages/notifications metadata row와 unread state
+3. Sheet의 시각 recipe 연결 — 기존 focus trap·scroll lock은 보존
+4. action Menu를 공유/피드에서 검증
+5. Dialog와 AlertDialog를 분리
+
+### Yajalal
+
+1. SearchField, BottomCTA, Notice, CounterBadge
+2. Chip을 action/radio/checkbox로 의미 분리
+3. List/ListRow/Section/Skeleton을 공용 recipe에 연결
+4. Accordion을 기록 상세에서 검증
+5. Menu/Select를 선수·시즌 선택 흐름에 적용
+
+제품 전용 `ai` accent, `built`, `live`, `win`, 구단 색은 adapter에 남고 recipe에는
+`info`, `success`, `attention`, `brand` 같은 공용 의미만 들어갑니다. 반면
+`SemanticIconName`의 `ai`는 특정 모델이나 제품 색을 뜻하지 않는 일반 “AI 기능”
+아이콘 역할이므로 공용 registry에 둡니다.
+
+## maturity gate
+
+- surface `planned → beta`: public renderer export + package CI의 canonical default proof
+- `beta → stable(shared)`: Web/RN renderer, 공통 scenario parity, Web keyboard,
+  iOS VoiceOver, Android TalkBack, Reduce Motion + consumer adoption evidence
+- `beta → stable(adaptive)`: 픽셀 parity 대신 같은 action/result/announcement, dismiss/back
+  scenario 통과
+- Web/Native 전용: 해당 플랫폼의 keyboard 또는 screen reader evidence
+
+모든 단계에서 light/dark, 200% text 또는 큰 글자, RTL 가능한 API, 필수 텍스트 4.5:1,
+경계·focus·indicator 3:1, 44-unit target을 확인합니다.
+
+Sheet stable 승격에는 위 gate와 함께 모든 dismiss reason의 단일 callback, busy 차단,
+Web focus/scroll lock, Native safe-area/back, Reduce Motion exit 완료, Sheet 종료 뒤 후속 surface
+순서, opt-in swipe gesture의 실제 기기 검증이 필요합니다.

package/docs/file-picker.md

@@ -0,0 +1,59 @@
+# FilePicker contract
+
+**문제.** 사용자가 업로드할 로컬 파일을 고른다 — 어떤 형식을 받는지, 몇 개까지
+고를 수 있는지, 그리고 무엇을 골랐는지. 업로드 요청·재시도·서버 응답은 이 계약
+밖이다. `docs/expansion-roadmap.md`의 Batch 3 절이 이미 그 경계를 그어 뒀다:
+FilePicker는 파일 선택 의도만 소유하고, 진행·성공·실패 표현은 [[upload-item]]이
+따로 소유한다. antd `Upload`는 이 둘로 decompose된다
+(`src/component-references.ts`의 crosswalk).
+
+**일반화한 계약.**
+
+- `mode`(`single` 기본값 또는 `multiple`), `accept?`(MIME 패턴 또는 확장자 목록),
+  `maxSizeBytes?`, `maxCount?`(multiple 전용)만 공개한다. `maxCount`를 single
+  모드에 주면 조용히 무시하지 않고 던진다 — 두 축이 같은 것을 다르게 두 번
+  말하게 두지 않는다.
+- 고른 결과는 `{ accepted, rejected }`로 함께 돌아온다. `rejected`의 각 항목은
+  `reason`(`unsupported-type`, `too-large`, `count-exceeded` 중 하나)과 그 판정에 쓴
+  한계값을 함께 들고 있어 제품이 왜 막혔는지 다시 계산하지 않고 문장을 만든다.
+  나머지 accepted 파일은 그대로 선택된 채로 남는다 — identity.md의 "무엇이
+  깨졌는지 + 무엇이 무사한지"를 한 결과 값 안에서 만족한다.
+- 크기·형식 거부는 **선택 시점**의 판정이다. 브라우저 `accept` 속성이나 네이티브
+  피커의 필터는 참고 힌트일 뿐 강제가 아니므로(사용자가 "모든 파일"을 고르면
+  통과한다), `resolveFilePickerSelection`이 실제 선택 결과를 다시 검증한다.
+- `mode: "single"`은 별도 분기가 아니라 `maxCount = 1`인 일반 규칙의 특수
+  경우로 처리한다 — Web dropzone에 파일 여러 개를 한 번에 끌어다 놓아도(단일
+  모드라도 드롭 이벤트 자체는 여러 파일을 줄 수 있다) 첫 파일만 accepted, 나머지는
+  `count-exceeded`로 떨어진다.
+- `existingCount`는 FilePicker가 소유하지 않는 입력이다(Select의 `selectedItem`과
+  같은 자리). 여러 번 나눠 고르는 제품 흐름에서 이미 고른 개수를 넘겨주면
+  `maxCount`가 누적 기준으로 판단된다 — FilePicker는 선택 목록 자체를 쌓아두지
+  않는다.
+- 넣지 않은 것: 파일 내용 읽기/미리보기, 업로드 진행·재시도·서버 상태(→
+  [[upload-item]]과 제품), 디렉터리 업로드, 자동 정렬. antd `Upload`의 넓은 표면 중
+  "무엇을 고를 것인가"만 가져온다.
+
+**HJM 기본값.** `mode` 기본값은 `single`(더 좁고 안전한 쪽). trigger 버튼은
+`control.minTouchTarget`(44) 이상을 유지하고, dropzone은 `radius.lg`의 점선
+테두리로 표현하며 hover/drag 시 `border.focus` 색과 `interaction.focus`
+배경으로 강조한다 — 이 강조는 장식이 아니라 "여기 놓으면 된다"는 신호다.
+
+**플랫폼 번역.**
+
+- Web: `<input type="file">` 또는 동등 위젯이 `role="button"`으로 trigger를
+  드러낸다. 드래그 앤 드롭은 **Web 전용 보강**이며 항상 버튼 trigger와 함께
+  있어야 한다 — `validateFilePickerTriggers`가 이 조합을 강제한다. Native가
+  dropzone trigger를 요청하면 던진다.
+- Native: 시스템 document/이미지 피커가 유일한 진입점이다. 결과가 도착하는
+  경로는 다르지만(Web `change` 이벤트 vs Native picker 콜백), 같은
+  `FilePickerCandidate` 배열로 들어와 같은 `resolveFilePickerSelection`을 통과하므로
+  accept/size/count 판정은 두 플랫폼에서 동일하다 — 로드맵의 adaptive gate가
+  요구하는 "같은 결과를 내는 다른 경로"다.
+- 열림/닫힘 축을 공개하지 않는다. 플랫폼 피커 시트는 OS가 소유하는 일시적
+  chrome이라 Sheet/Select처럼 `open` controlled state를 모델링하지 않는다.
+- 거부 발표는 색에 의존하지 않는다 — `reason`과 한계값으로 제품이 만든 문장을
+  live 영역/에러 카피로 보여준다.
+
+**검증 화면.** first-party Web input/dropzone과 Native picker-adapter renderer, 선택 판정
+상호작용 테스트는 연결되어 surface는 `beta`다. 실제 제품 vertical slice와 플랫폼 picker
+실기기 증거는 아직 없으므로 `stable` 승격 gate는 닫혀 있다.