@hjmds/design-contracts 1.12.0 → 1.13.0

package/docs/usage/components/asset.md

@@ -0,0 +1,126 @@
+# Asset
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Asset contract](../../asset.md), [VoiceNote](../../voice-note.md), recipe `assetRecipe`(`src/asset.ts`)
+- 스토리북: `배포/컴포넌트/데이터 표시/이미지·영상 표시` · `배포/컴포넌트/데이터 표시/음성 메모`
+
+## 언제 쓰나
+
+아이콘·이미지·Lottie·비디오를 같은 크기·모서리 규칙의 액자에 넣을 때 쓴다. 종류가 다른 그림이
+한 줄에 섞여 나오는 자리(캐릭터 그림, 첨부 썸네일 줄)가 대표적이다. 재생기는 제품이 슬롯으로 넣는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 사람·계정 얼굴 | [Avatar](avatar.md) |
+| 비율이 정해진 큰 이미지·영상 | [AspectRatio](aspect-ratio.md), [Image](image.md) |
+| 버튼·행 안의 단일 아이콘 | [Icon](icon.md) |
+| 업로드 진행 중인 첨부 | [UploadItem](upload-item.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Asset` | 기본(액자) | `@hjmds/react`, `/asset` | `@hjmds/react-native`, `/asset` |
+| `AssetGroup` | 동반(겹쳐 쌓는 묶음) | `@hjmds/react`, `/asset` | `@hjmds/react-native`, `/asset` |
+| `VoiceNote` | 확장(음성 메모 재생 UI, optional-extension) | `/voice-note`만 | `/voice-note`만 |
+
+`VoiceNote`는 root에서 export되지 않는다. Asset·Slider·Button·Stack·Surface·Text만 합성하며
+optional peer를 요구하지 않는다(소스 import 확인).
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Asset } from "@hjmds/react/asset";
+
+<Asset descriptor={{ kind: "lottie", size: "large", accessibilityLabel: t("pet.fox") }}>
+  {({ animate }) => <FoxLottie autoplay={animate} />}
+</Asset>
+```
+
+```tsx
+// Native
+import { Image } from "react-native";
+import { Asset, AssetGroup } from "@hjmds/react-native/asset";
+
+<AssetGroup label={t("letter.carriers")} size="small">
+  {carriers.map((c) => (
+    <Asset key={c.id} descriptor={{ kind: "image", size: "small", shape: "circle", decorative: true }}>
+      <Image source={c.art} style={{ width: 32, height: 32 }} />
+    </Asset>
+  ))}
+</AssetGroup>
+```
+
+```tsx
+// Native
+// VoiceNote. Web(`@hjmds/react/voice-note`)도 같은 props에 `layoutStyle`만 더 받는다.
+import { VoiceNote } from "@hjmds/react-native/voice-note";
+
+<VoiceNote
+  descriptor={{ title: note.title, state: player.state, duration: player.duration, position: player.position }}
+  labels={{ play: t("voice.play"), pause: t("voice.pause"), seek: t("voice.seek"), loading: t("voice.loading"),
+    error: t("voice.error"), retry: t("voice.retry"), backward: t("voice.backward"), forward: t("voice.forward") }}
+  formatTime={formatSeconds}
+  onPlayingChange={(playing) => (playing ? player.play() : player.pause())}
+  onSeek={player.seekTo}
+  onRetry={player.reload}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor` | `{ kind, size?, shape?, decorative?, accessibilityLabel? }`(`AssetDescriptor`) | 필수 | 이름 또는 `decorative: true` 둘 중 하나만 |
+| `descriptor.kind` | `icon` · `image` · `lottie` · `video` | 필수 | — |
+| `descriptor.size` | `small`(32) · `medium`(48) · `large`(72) · `xlarge`(120) | `medium` | — |
+| `descriptor.shape` | `square` · `rounded` · `circle` | `rounded` | — |
+| `children` | `ReactNode` 또는 `(state: { animate: boolean }) => ReactNode` | 필수 | `animate`는 `lottie`·`video`이고 reduced motion이 아닐 때만 `true`다 |
+| `accessory` | `ReactNode` | — | 액자 바깥 모서리에 붙는 작은 표식(재생 아이콘, 상태 점) |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | Asset·AssetGroup 바깥 배치 전용 |
+| Native `style`(Asset·AssetGroup) | — | — | deprecated — `layoutStyle` 또는 descriptor `size`/`shape`(개발 모드 1회 경고, 다음 major 제거) |
+| `AssetGroup` `label` · `size` | `string` · `AssetSize` | `label` 필수 · `size` `medium` | 겹침은 크기의 30%로 Avatar와 같다 |
+| `VoiceNote` `descriptor` | `{ title, state: "paused" \| "playing" \| "loading" \| "error", duration: number \| null, position: number, disabled? }` | 필수 | `duration: null`(메타데이터 미확인)과 `0`이면 재생·탐색이 막힌다 |
+| `VoiceNote` `labels` | `{ play, pause, seek, loading, error, retry, backward, forward }`(모두 `string`) | 필수 | i18n 문구 |
+| `VoiceNote` `formatTime` | `(seconds: number) => string` | 필수 | 경과/전체 시간 문구와 Slider 접근성 값 |
+| `VoiceNote` `onPlayingChange` · `onSeek` · `onRetry` | `(playing: boolean) => void` · `(seconds: number) => void` · `() => void` | 앞의 둘 필수 | 플레이어 제어는 제품 소유 |
+| `VoiceNote` `artwork` | `ReactNode` | — | 장식 원형 Asset으로 그린다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 정사각 액자. 한 변 `small` 32 · `medium` 48 · `large` 72 · `xlarge` 120. 모서리 `square` 0 · `rounded` `radius.md` 12 · `circle` `radius.full`. 터치 대상이 아니므로 누를 수 있게 하려면 감싸는 버튼·행이 최소 44를 확보한다 | `assetRecipe.sizes`·`shapes`, `.hjm-asset__frame` |
+| 간격 | `accessory`는 액자 끝·아래 모서리 바깥으로 `spacing.xxs` 4 띄워 붙으므로 옆 요소와 `spacing.xs` 8 이상 띄운다. `AssetGroup` 겹침은 크기의 30%(48이면 −14) | `assetRecipe.accessory`·`overlapRatio`, `react/src/asset.tsx` |
+| 순서·정렬 | 늘어나지 않는 인라인 요소(Web `inline-flex`, `flex: 0 0 auto`). 행 안에서는 시작 쪽에 둔다. 한 줄에 종류가 다른 그림을 섞을 때 모두 같은 `size`·`shape`를 준다 | `.hjm-asset`, `assetBehavior.scenarios` |
+| 고정·스크롤 | 고정 영역이 없다 | — |
+| 좁은 폭·큰 글자 | 액자 크기는 그대로이고 옆 문구가 줄바꿈된다 | `assetRecipe.sizes`(고정 수치) |
+
+## 꼭 지킬 것
+
+- 뜻이 있는 그림은 `accessibilityLabel`을, 장식은 `decorative: true`만 준다. 이름 없는 비장식과
+  둘 다 준 경우 모두 렌더 중 `TypeError`가 난다.
+- reduced motion에서는 숨기지 말고 `animate`로 재생을 멈춘다. 판단을 제품에서 다시 만들지 않는다.
+- Lottie·비디오·오디오 엔진, 그림 자산은 제품 소유다. HJM은 액자·크기·겹침·표식 위치만 소유한다.
+- `VoiceNote`의 재생 위치는 실제 플레이어 값을 넘긴다. 내부 타이머로 진행을 꾸미지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 배치 prop | `layoutStyle`(+`className`) | `layoutStyle`(`style`은 deprecated). `VoiceNote`는 Native에 `layoutStyle` 없음 |
+| 매체 크기 | CSS가 자식을 액자 안으로 줄인다(`max-*: 100%`) | 가운데 정렬만 한다. 자식 크기를 직접 준다 |
+| `AssetGroup` 겹침 | CSS로 `.hjm-asset` 형제에 적용 | `children`이 배열일 때만 각 자식을 감싸 적용 |
+| `VoiceNote` 앞뒤 이동 문구 | `labels.backward/forward`를 받지만 쓰지 않는다 | Slider 접근성 동작 문구로 쓴다 |
+
+## 함정
+
+- `AssetGroup`의 `size`는 겹침 폭만 정한다. 안의 각 `Asset` descriptor에 같은 `size`를 직접 준다.
+- Native `AssetGroup`에 Fragment 하나나 단일 자식을 넘기면 겹치지 않는다. `map` 결과 배열을 넘긴다.

package/docs/usage/components/auth-provider-button.md

@@ -0,0 +1,116 @@
+# AuthProviderButton
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [AuthProviderButton](../../provider-button.md), recipe `authProviderButtonRecipe`(`src/provider-button.ts`), 포트폴리오 상위 기준 루트 `docs/LOGIN_SCREEN_STANDARD.md`(LS-02·LS-05·LS-09)
+- 스토리북: `배포/컴포넌트/동작/소셜 로그인 버튼`
+
+## 언제 쓰나
+
+Google·Kakao·Naver·Apple 소셜 로그인 버튼에 쓴다. 지원 제공자는 이 네 개뿐이며
+(`AuthProviderId`), 다른 값은 렌더 시 `TypeError`가 난다. 로그인 화면에서는
+[AuthScreenLayout](auth-screen-layout.md)의 `main` 슬롯에 세로로 쌓는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 제공자가 아닌 일반 행동, 개발 로그인·QA 슬롯 버튼 | [Button](button.md) (`tone="secondary"`, LS-05) |
+| 로그인 화면 전체 배치 | [AuthScreenLayout](auth-screen-layout.md) |
+| 로그인 진행 표시 | AuthScreenLayout의 `pendingLabel` (버튼별 `busy` 아님) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `AuthProviderButton` | 기본 | `@hjmds/react`, `/provider-button` | `@hjmds/react-native`, `/provider-button` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { AuthProviderButton } from "@hjmds/react/provider-button";
+
+<AuthProviderButton
+  descriptor={{ provider: "kakao", label: t("auth.provider.kakao") }}
+  logo={<ProviderLogo provider="kakao" />} // 제품 컴포넌트
+  onClick={() => start("kakao")}
+/>
+```
+
+```tsx
+// Native
+import { AuthProviderButton } from "@hjmds/react-native/provider-button";
+
+<AuthProviderButton
+  descriptor={{ provider: "apple", label: t("auth.provider.apple") }}
+  logo={<ProviderLogo provider="apple" />} // 제품 컴포넌트
+  onPress={() => start("apple")}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `descriptor.provider` | `google` · `kakao` · `naver` · `apple` | 필수 | 색은 `authProviderPalettes`가 정하고 테마는 제공자가 규정한 light/dark 변형 중 하나를 고를 뿐이다. 다크에서 Google·Apple은 변형이 바뀌고 Kakao·Naver는 같다 |
+| `descriptor.label` | 문자열 | 필수 | 공백만 있으면 `TypeError` |
+| `descriptor.busy` · `disabled` | `boolean` | `false` | — |
+| `logo` | `ReactNode` | 필수 | 제품이 공급하는 제공자 로고 |
+| Web `onClick` · Native `onPress` | `(event: MouseEvent<HTMLButtonElement>) => void` · `() => void` | Native 필수 | 로그인 시작 |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | 바깥 배치 전용 |
+| Native `style` | — | — | deprecated — `layoutStyle`(외형은 `authProviderButtonRecipe` 소유, 개발 모드 1회 경고, 다음 major 제거) |
+| — | — | HJM 소유 | 크기: 높이 `buttonRecipe` medium(Native는 최소 터치 타깃과 큰 쪽), radius `md`, 로고 상자 20, 테두리 1(테두리를 규정한 변형만), 포커스 링은 fill 바깥(offset 2) |
+| Web `type` | HTML button type | `"button"` | — |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭을 꽉 채운다(Web `inline-size: 100%`). 최소 높이 44(`buttonRecipe` medium과 `control.minTouchTarget` 중 큰 쪽), 모서리 `radius.md` 12, 로고 20×20, 라벨 `typography.body` 14/20(제공자 가이드가 라벨·색 표현을 소유한다. 네이버 녹색 대비는 [제공자 색 예외](../../provider-button.md#제공자-색과-글자-대비)) | `authProviderButtonRecipe`, `.hjm-auth-provider-button` |
+| 간격 | 좌우 여백 `spacing.md` 16, 로고↔이름 `spacing.sm` 12. 버튼 사이는 스토리 기준 `Stack gap="sm"`(12) | `authProviderButtonRecipe`, `showcase/web/src/patterns/Agreement.stories.tsx`(`AuthScreenLayoutPreview`) |
+| 순서·정렬 | [AuthScreenLayout](auth-screen-layout.md) `main` 슬롯에 세로로 쌓는다. 안쪽은 [로고]+[제공자 이름]이 가운데 정렬. 순서는 제품이 정하고, 일반 Button(개발 로그인 등)은 제공자 사이가 아니라 목록 아래에 `tone="secondary"`로 둔다 | `.hjm-auth-provider-button`(`justify-content: center`) |
+| 고정·스크롤 | 고정되지 않는다. 진행 중에는 버튼 목록을 그대로 두고 카드 가운데에 로딩 하나만 보인다(`pendingLabel`). 버튼 자리·크기는 바뀌지 않는다 | `react/src/auth-screen.tsx`, `react-native/src/auth-screen.tsx` |
+| 좁은 폭·큰 글자 | 이름이 줄바꿈되고 버튼 높이가 늘어난다. 자르지 않는다 | `.hjm-auth-provider-button__label`(`overflow-wrap: anywhere`) |
+
+```text
+main 카드(mainCard)
+┌──────────────────────────┐
+│ [   (G) Google        ]  │
+│ [   (K) 카카오        ]  │  ← 간격 spacing.sm 12
+│ [   (N) 네이버        ]  │
+│ [   ()  Apple         ]  │  ← iOS 필수
+└──────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `label`에는 제공자 이름만 넣는다(`카카오`, `네이버`, `Google`, `Apple`). "Google로 계속하기" 같은 문장을
+  만들지 않는다. 문구는 제품 i18n 카탈로그가 소유하며 renderer가 만들거나 자르지 않는다.
+- `logo`는 제품이 공급한다. HJM에는 제공자 로고가 없고 넣지도 않는다(공개 MIT 배포라 상표를 담을 수 없다).
+  로고 원본은 포트폴리오 루트 `assets/auth-providers/`이고 `node scripts/sync-auth-provider-logos.mjs --write`로
+  앱 checkout에 투사한 복사본만 쓴다. 앱에서 따로 내려받지 않는다. 비율을 유지하고 정사각으로 늘리지 않는다.
+- 배치는 `layoutStyle`로만 한다. 제공자 색을 `className`·`style`로 다시 칠하지 않는다. 제품 테마·브랜드 색은 이 버튼에 닿지 않는다.
+- 로그인 화면의 진행 상태는 AuthScreenLayout `mainCard` + `pendingLabel`로 표시한다. 버튼마다 `busy`를 켜지
+  않고, 진행 중에 버튼 목록을 제거하거나 바꾸지 않는다. `busy`는 단독 버튼 호환용이며 카드 진행 상태와 함께 쓰지 않는다.
+- 제공자 목록과 순서는 제품(서버 `GET /auth/providers` 등)이 정한다. 설정되지 않은 제공자는 그리지 않는다.
+  iOS 앱에서는 Apple이 필수다(LS-02). 웹·Android·iOS의 제공자 집합은 같게 둔다(iOS에 Apple 추가만 허용).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이벤트 | `onClick` 등 `<button>` 속성(선택) | `onPress`(필수) |
+| 비활성 | `descriptor.disabled`(`disabled` 속성은 받지 않음) | `descriptor.disabled` |
+| 배치 입력 | `layoutStyle`(+`className`, `style` 없음) | `layoutStyle`(`style`은 deprecated) |
+| 접근성 이름 | `aria-label={label}` | `accessibilityLabel={label}` |
+| `testID`·ref | ref 전달 | 둘 다 없음 |
+
+## 함정
+
+- `busy`이면 로고와 라벨은 자리를 유지한 채 숨고 가운데 스피너 하나만 보인다. 버튼 폭은 줄지 않는다.
+  `disabled`는 불투명도 0.5로 흐려지지만 `busy`는 흐려지지 않는다(두 renderer 같음).
+- descriptor 검증은 렌더마다 실행된다. 빈 번역 키 결과(빈 문자열)가 그대로 들어가면 화면이 아니라 렌더가 실패한다.

package/docs/usage/components/auth-screen-layout.md

@@ -0,0 +1,129 @@
+# AuthScreenLayout
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [로그인 화면 골격](../../auth-screen.md), [1.4 제품 채택 가이드](../../product-adoption-1.4.md), recipe `authScreenRecipe`(`src/auth-screen.ts`), 포트폴리오 상위 기준 루트 `docs/LOGIN_SCREEN_STANDARD.md`(LS)
+- 스토리북: `배포/컴포넌트/레이아웃/로그인 화면`
+
+## 언제 쓰나
+
+로그인·가입 진입 화면의 배치에 쓴다. 위 영역(`hero` + `main`)은 남는 세로 공간에서 가운데 정렬되고,
+`footer`(동의 고지·정책 링크)는 바닥에 붙는다. 내용이 화면보다 길면 스크롤로 바뀐다.
+이 컴포넌트는 배치만 소유하며 슬롯 안의 내용은 그리지 않는다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 제공자 버튼 하나하나 | [AuthProviderButton](auth-provider-button.md) (`main` 슬롯에 넣는다) |
+| 동의 체크 항목 | [Agreement](agreement.md) (`footer`나 가입 단계에 넣는다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `AuthScreenLayout` | 기본 | `@hjmds/react`, `/auth-screen` | `@hjmds/react-native`, `/auth-screen` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { AuthScreenLayout } from "@hjmds/react/auth-screen";
+
+<AuthScreenLayout
+  mainCard
+  {...(pending ? { pendingLabel: t("auth.pending") } : {})}
+  hero={<ProductHero />}            // 제품 마크·제목·설명
+  main={<ProviderButtons />}        // pending이어도 같은 목록
+  footer={<ConsentAndPolicyLinks />}
+/>
+```
+
+```tsx
+// Native
+import { AuthScreenLayout } from "@hjmds/react-native/auth-screen";
+
+<AuthScreenLayout
+  mainCard
+  {...(pending ? { pendingLabel: t("auth.pending") } : {})}
+  hero={<ProductHero />}
+  main={<ProviderButtons />}
+  footer={<ConsentAndPolicyLinks />}
+  testID="login-screen"
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `hero` · `main` | `ReactNode` | 필수 | 제품 마크·제목·설명 / 제공자 버튼 목록(진행 중에도 같은 목록) |
+| `footer` | `ReactNode` | — | 동의 고지·정책 링크 |
+| `density` | `regular` · `compact` | `regular` | 제품이 화면 높이를 보고 고른다. 간격·padding만 바뀐다 |
+| `hasFooter` | `boolean` | `true` | `false`이거나 `footer`가 없으면 아래 영역을 그리지 않는다 |
+| `mainCard` | `boolean` | `false` | 기존 제품 카드와 중첩 방지. 새 조합은 켠다. 카드 배경은 테마 `bg`, radius `lg`, padding `md` |
+| `pendingLabel` | 문자열 | — | 주면 진행 상태다. 공백만 있으면 `TypeError`. 제거하면 원래 상태로 돌아온다 |
+| Web `as` | `main` · `section` | `main` | 최대 폭은 416이다 |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | 바깥 배치 전용(Web·Native 모두) |
+| Native `testID` | `string` | — | 뿌리 `ScrollView` 식별 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 화면 전체(Web `min-block-size: 100dvh`, Native `ScrollView flex: 1`). 위 블록과 footer는 최대 폭 416, 마크 72(`markSize`, `radius.lg`), 정책 링크 최소 44(`footerMinTouchTarget`), mainCard 모서리 `radius.lg` 16 | `authScreenRecipe`, `.hjm-auth-screen*` |
+| 간격 | `regular` / `compact`: 바깥 좌우 `layout.pagePadding.regular` 20 / `.compact` 16, 바깥 위아래 `spacing.xxxl` 40 / `spacing.lg` 20, hero 안 `spacing.md` 16 / `spacing.xs` 8, hero↔main `spacing.xl` 24 / `spacing.md` 16, 위 블록↔footer 최소 `spacing.xl` 24 / `spacing.md` 16. mainCard 안쪽 `spacing.md` 16 | `authScreenRecipe.densities`·`mainCard` |
+| 순서·정렬 | 위→아래 hero(가운데 정렬 문구) → main(폭 꽉 채움) → footer(동의 고지·정책 링크). 위 블록은 남는 세로 공간에서 가운데, footer는 바닥에 붙는다. 진행 중 로딩은 main 카드 가운데에 겹친다 | `.hjm-auth-screen__block`(`justify-content: center`), `.hjm-auth-screen__pending` |
+| 고정·스크롤 | 고정 영역이 없다. 넘치면 화면 전체가 스크롤한다. 안전 영역은 Native `contentInsetAdjustmentBehavior="automatic"`과 키보드 inset 자동 조정이 처리하고, Web은 safe-area inset을 더하지 않는다 | `react-native/src/auth-screen.tsx`, `.hjm-auth-screen` |
+| 좁은 폭·큰 글자 | 키 작은 화면·큰 글자에서는 `compact`를 고른다. 그래도 넘치면 스크롤되며 footer는 맨 아래로 밀린다 | `authScreenRecipe.densities` |
+
+```text
+┌──────────────────────────┐
+│     (바깥 위 여백 40)     │
+│        [마크 72]          │  ← hero(가운데)
+│     어떤 계정으로…        │
+│        설명 한 줄         │
+│      ↕ spacing.xl 24      │
+│ ┌──────────────────────┐ │
+│ │ [ Google ]           │ │  ← main(mainCard), 최대 폭 416
+│ │ [ 카카오 ]  …        │ │
+│ └──────────────────────┘ │
+│     (남는 공간)          │
+│ 계속하면 동의 · 정책 링크 │  ← footer(바닥)
+│     (바깥 아래 여백 40)   │
+└──────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 로그인 진행 중에는 `pendingLabel` 하나로 표시한다. `main`의 버튼 목록은 그대로 두고(조건부 제거·교체 금지)
+  카드 크기를 유지한 채 중앙 로딩 하나만 보인다. 버튼별 `busy`를 함께 켜지 않는다.
+- `pendingLabel`은 스크린리더 안내로만 쓰인다. 로딩 아래에 보이는 문구를 따로 두지 않는다.
+  완료·취소·실패 시 prop을 제거한다. 취소는 실패 문장 없이 버튼만 복구한다(LS-09).
+- `pendingLabel`은 기존 카드에서 전환하는 상태다. 제공자 목록 최초 조회의 로딩을 대신하지 않는다.
+- 슬롯 내용은 전부 제품 소유다: 마크 자산, 모든 문구(i18n 키), 제공자 목록과 순서, 정책 링크 목적지,
+  심사자 폼 노출 조건. 제공자 로고를 HJM에 넣지 않는다([AuthProviderButton](auth-provider-button.md)).
+- iOS 앱의 제공자 목록에는 Apple이 있어야 한다(LS-02). 심사자 이메일 폼은 서버 env와 `review=1` 두 조건이
+  모두 맞을 때만 제품이 `main` 카드 안에 그린다(LS-07).
+- `hasFooter: false`는 필수 동의 고지·정책 링크를 생략해도 된다는 뜻이 아니다.
+- 외부 배치는 `layoutStyle`(정렬·flex·margin·폭 키만 허용)로 한다. Native에는 `style` prop이 없고, Web `style`로 배치하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 뿌리 요소 | `<main>` 또는 `as="section"`, ref 전달 | `ScrollView` |
+| 배치·식별 | `layoutStyle`, `className`, HTML 속성 | `layoutStyle`, `testID` |
+| 진행 중 숨김 | `inert` + `aria-hidden` + `visibility: hidden`, 로딩은 `role="status"` | 터치·접근성 제외 + 불투명도 0, 로딩은 `progressbar` + live region |
+| 키보드 | 브라우저 기본 | 키보드 inset 자동 조정, 탭 유지(`handled`), iOS `interactive`·Android `on-drag` 내리기 |
+
+## 함정
+
+- Native는 자체로 키보드 스크롤 여백을 준다. 부모가 다시 keyboard avoidance를 하면 여백이 중복될 수 있으니
+  심사자 폼처럼 입력칸이 있는 화면은 소비 화면에서 확인한다.
+- 앱 셸이 이미 `<main>`을 가진 Web 화면에서 기본값을 쓰면 main landmark가 중첩된다. `as="section"`을 쓴다.
+- 기존 제품 카드 wrapper 안에서 `mainCard`를 켜면 카드가 이중이 된다. wrapper를 걷어내고 `mainCard`로 옮긴다.
+- 현재 Web `style`은 recipe 크기 변수(`--hjm-auth-screen-*`) 뒤에 펼쳐져 최대 폭·간격 변수를 덮을 수 있다. 배치는 `layoutStyle`로만 준다.

package/docs/usage/components/avatar.md

@@ -0,0 +1,114 @@
+# Avatar
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Avatar fallback and Blobatar](../../avatar-fallback.md), recipe `avatarRecipe`(`src/component-recipes.ts`)
+- 스토리북: `배포/컴포넌트/데이터 표시/아바타` · `배포/컴포넌트/데이터 표시/블로바타 캐릭터` · `배포/컴포넌트/데이터 표시/움직이는 블로바타 캐릭터`
+
+## 언제 쓰나
+
+사람·계정을 사진 또는 이니셜로 나타낼 때 쓴다. 사진이 없거나 로드에 실패하면 자동으로 대체 표시로
+바뀌고, 사진 주소가 바뀌면 다시 시도한다. Web은 여러 명을 겹쳐 보이는 `AvatarGroup`이 있다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 사람이 아닌 그림·캐릭터·Lottie | [Asset](asset.md) |
+| 비율이 있는 큰 사진 | [Image](image.md), [AspectRatio](aspect-ratio.md) |
+| 이름 옆 숫자·상태 표시 | [CounterBadge](counter-badge.md), [Badge](badge.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Avatar` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+| `AvatarGroup` | 동반(겹친 묶음) | `@hjmds/react`, `/display` | 없음 |
+| `createBlobatarFallback` | 확장(선택 대체 그림, 정적) | `/avatar-blobatar` | `/avatar-blobatar` |
+| `createAnimatedBlobatarFallback` | 확장(선택 대체 그림, 움직임) | `/avatar-blobatar-motion` | `/avatar-blobatar-motion` |
+
+Blobatar 어댑터는 root에서 export되지 않는다. optional peer `blobatar@2.7.0`과
+`@blobatar/react@2.7.0`(Web) 또는 `@blobatar/react-native@2.7.0`(Native)을 앱에 설치해야 하고,
+Native는 `react-native-svg`도 필요하다. motion Native entry는 `@blobatar/react-native/animated`를 써서
+호환 Reanimated·Worklets가 추가로 필요하다([계약](../../avatar-fallback.md)). 설치하지 않은 채 import하면
+tsc·테스트는 통과해도 기기 Metro에서 깨질 수 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Avatar, AvatarGroup } from "@hjmds/react/display";
+
+// 사진이 없으면 src를 빼야 한다(exactOptionalPropertyTypes에서 undefined를 넘기면 타입 오류).
+const profile = (
+  <Avatar name={user.displayName} {...(user.photoUrl ? { src: user.photoUrl } : {})} size="large" />
+);
+
+const roomMembers = (
+  <AvatarGroup label={t("room.members", { count: members.length })} size="small"
+    overflow={hidden > 0 ? t("room.moreMembers", { count: hidden }) : null}>
+    {visible.map((m) => <Avatar key={m.id} name={m.displayName} src={m.photoUrl} size="small" />)}
+  </AvatarGroup>
+);
+```
+
+```tsx
+// Native
+import { Avatar } from "@hjmds/react-native/data-display";
+
+<Avatar name={user.displayName} {...(user.photoUrl ? { source: { uri: user.photoUrl } } : {})}
+  accessibilityLabel={user.displayName} size={48} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `name` | `string` | 필수 | 이니셜과 기본 접근성 이름의 원천. 공백뿐이면 `TypeError` |
+| Web `src` · Native `source` | `string` · `ImageSourcePropType` | — | 사진이 없으면 prop을 뺀다. 주소(Native는 source 내용)가 바뀌면 실패 상태를 지우고 다시 시도한다 |
+| Web `size` | `small`(32) · `medium`(40) · `large`(48) · `xlarge`(64) | `medium` | — |
+| Web `shape` | `circle` · `rounded` | `circle` | — |
+| Native `size` | 숫자(pt) | 44 | 24 미만이면 `RangeError`. 모양은 항상 원이다 |
+| `renderFallback` | `(context: { size: number; decorative: true }) => ReactNode` | — | 사진이 없거나 실패했을 때만 불린다. `size`는 px/pt 값. null·undefined를 돌려주면 기본 대체 표시(Web `fallback`→이니셜, Native 이니셜)를 쓴다 |
+| Web `alt` | `string` | `name` | `""`이면 보조기기에서 숨긴다 |
+| Web `imageProps` | `img` 속성(`alt`·`src` 제외) | — | `onError`는 `(event: SyntheticEvent<HTMLImageElement>) => void`이며 대체 표시로 바꾼 뒤 불린다 |
+| Native `accessibilityLabel` · `decorative` | `{ accessibilityLabel: string }` 또는 `{ decorative: true }` | — | 둘 중 하나가 타입으로 강제된다 |
+| Native `initials` | `string` | 이름에서 계산 | 앞뒤 공백을 지우고 최대 3자, 대문자 |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | 배치 전용. Native `style`·`imageStyle`은 deprecated — layoutStyle 또는 `size`/`renderFallback` |
+| `AvatarGroup`(Web) `label` · `size` · `overflow` | `string` · Avatar 크기 · `ReactNode` | `label` 필수 · `size` `medium` | 빈 `label`은 `TypeError`. `overflow`는 제품이 만든 "+3" 같은 문구이며 `aria-hidden`이다(남은 인원은 `label`에 담는다). 겹침은 크기의 30%다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Web `small` 32 · `medium` 40 · `large` 48 · `xlarge` 64, Native 숫자(기본 44). 목록 행에는 Web `medium`/Native 기본, 프로필 머리에는 `xlarge`. Avatar 자체는 터치 대상이 아니므로 누르는 프로필은 감싸는 행·버튼이 최소 44를 확보한다 | `.hjm-avatar[data-size]`, `react-native/src/data-display.tsx` |
+| 간격 | 자체 바깥 여백이 없다. `AvatarGroup`은 크기의 30%만큼 겹치고 각 아바타에 `bg` 색 2px 테두리를 둘러 경계를 만든다 | `.hjm-avatar-group` |
+| 순서·정렬 | 행·카드·댓글 머리의 시작 쪽에 두고 이름·본문이 끝 쪽으로 이어진다. `AvatarGroup`의 넘친 수 표시는 맨 끝에 온다 | `.hjm-avatar-group__overflow` |
+| 고정·스크롤 | 고정 영역이 없다 | — |
+| 좁은 폭·큰 글자 | 아바타 크기는 그대로이고 옆 문구가 줄바꿈된다. 이니셜 글자는 Web `small`에서 label, `xlarge`에서 title 크기다 | `.hjm-avatar[data-size="small"]`·`[data-size="xlarge"]` |
+
+## 꼭 지킬 것
+
+- `name`은 빈 문자열이면 `TypeError`다. 접근성 이름은 Avatar가 소유하고, 대체 그림은 장식으로만 그린다(버튼 등 상호작용 금지).
+- Blobatar `seed`에는 공개 제품 식별자를 쓴다. 이름·이메일·자격증명은 seed로 쓰지 않는다.
+- 사진·표시 이름·남은 인원 문구는 제품 소유다. `overflow`는 i18n 키로 만든다. `overflow`는 보조기기에서 숨겨지므로 전체 인원은 `label` 문구에 넣는다.
+- 배치는 `layoutStyle`로만 한다. Native `style`·`imageStyle`은 deprecated(개발 모드 1회 경고, 다음 major 제거)다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 사진 | `src`(문자열), `imageProps`로 `img` 속성·`onError` 전달 | `source`(`ImageSourcePropType`). `imageStyle`은 deprecated — layoutStyle 또는 `size` |
+| 접근성 이름 | `alt`(기본 `name`), `alt=""`이면 숨김 | `accessibilityLabel` 필수, 또는 `decorative` |
+| 대체 표시 | `fallback` 노드 또는 이니셜 | `initials`(최대 3자) 또는 이니셜 |
+| 크기·모양 축 | 4단 이름 · `circle`/`rounded` | 숫자 · 원만 |
+| 묶음 | `AvatarGroup` | 없음 |
+
+## 함정
+
+- `src`/`source`에 `undefined`를 직접 넘기면 `exactOptionalPropertyTypes`에서 타입 오류다. 사진이 없으면 prop을 빼거나 spread로 조건부로 넣는다.
+- Web `AvatarGroup`은 이제 `style`을 버리지 않고 `layoutStyle`과 합친다. 겹침 변수(`--hjm-avatar-overlap`)는 마지막에 덮이므로 `style`로 겹침을 바꿀 수 없다.
+- 이니셜은 두 플랫폼 모두 `resolveAvatarInitials`(`@hjmds/design-contracts/avatar-fallback`)로 첫 단어와 마지막 단어의 첫 글자(code point)다. 1.12.1까지 Web은 앞 두 단어를 써서 "Kim Min Jun"이 Web "KM", Native "KJ"였다(미게시 변경). 1.12.1에서 일치가 필요하면 Native `initials`·Web `fallback`으로 같은 값을 준다.

package/docs/usage/components/badge.md

@@ -0,0 +1,84 @@
+# Badge
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: recipe `badgeRecipe`(`src/component-recipes.ts`)
+- 스토리북: `배포/컴포넌트/데이터 표시/배지`
+
+## 언제 쓰나
+
+항목의 상태나 분류를 짧은 글자 하나로 붙일 때 쓴다. "진행 중", "완료", "시즌 3"처럼 누를 수 없는 표시다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 읽지 않은 수·알림 점 | [CounterBadge](counter-badge.md) |
+| 사용자가 붙인 키워드·카테고리 | [Tag](tag.md) |
+| 누르거나 고르는 필터 | [Chip](chip.md) |
+| 문장으로 설명해야 하는 상태 | [Notice](notice.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Badge` | 기본 | `@hjmds/react`, `/display` | `@hjmds/react-native`, `/data-display` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Badge } from "@hjmds/react/display";
+
+<Badge tone="success" size="small">{t("order.status.done")}</Badge>
+```
+
+```tsx
+// Native
+import { Badge } from "@hjmds/react-native/data-display";
+
+<Badge tone="success" size="small" label={t("order.status.done")} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tone` | `neutral` · `strong` · `brand` · `info` · `success` · `warning` · `attention` · `danger` | `neutral` | `brand`는 판이 중립색이고 글자만 브랜드색이다. 브랜드 틴트는 "선택됨"을 뜻하므로 정적 표시에 쓰지 않는다. `strong`은 `neutral`보다 한 단계 강한 잉크 판이며 승패처럼 한눈에 갈려야 하는 사실에 쓴다 |
+| `variant` | `filled` · `outline` | `filled` | — |
+| `size` | `small` · `medium` | `medium` | — |
+| `leading` | `ReactNode` | — | 라벨 앞 아이콘 자리이며 보조기기에서 숨겨진다 |
+| Web `children` · Native `label` | `ReactNode` · `string \| number`(필수) | — | 표시 라벨 |
+| Native `accessibilityLabel` | `string` | `String(label)` | 숫자 라벨에 단위를 붙여 읽힐 때 쓴다 |
+| `layoutStyle` | margin·width·flex·`alignSelf` | — | 배치 전용. Native `style`·`labelStyle`은 deprecated — layoutStyle 또는 tone/토큰 |
+
+콜백이 없다. 누를 수 없는 표시다.
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 내용 폭만 차지한다. 최소 높이 `medium` 24 · `small` 20, 모서리 `radius.full`. 누를 수 없는 표시라 44 터치 영역이 필요 없다(누르게 하려면 [Chip](chip.md)) | `badgeRecipe.sizes`, `.hjm-badge` |
+| 간격 | 좌우 여백 `medium` `spacing.xs` 8 · `small` `spacing.xxs` 4, 아이콘↔라벨 `spacing.xxs` 4. 여러 개를 나란히 둘 때는 `spacing.xxs` 4~`spacing.xs` 8 | `badgeRecipe.sizes` |
+| 순서·정렬 | 제목·행 이름 옆(끝 쪽) 또는 카드 머리 위에 인라인으로 붙인다. 한 행에 2~3개를 넘기지 않는다 | `.hjm-badge`(`inline-flex`) |
+| 고정·스크롤 | 고정 영역이 없다 | — |
+| 좁은 폭·큰 글자 | 라벨이 줄바꿈된다(`overflow-wrap: anywhere`). 말줄임하지 않는다 | `.hjm-badge` |
+
+## 꼭 지킬 것
+
+- 라벨은 i18n 키로 넣고 짧게 둔다. 상태 뜻을 색에만 싣지 않는다(글자가 뜻을 말해야 한다).
+- 색은 `tone`으로만 고른다. 브랜드 색을 `style`·`className`·`labelStyle`로 덮지 않는다.
+- 배치는 Web·Native 모두 `layoutStyle`로만 한다. Native `style`·`labelStyle`은 deprecated(개발 모드 1회 경고, 다음 major 제거)다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 라벨 | `children` | `label`(문자열·숫자, 필수) |
+| 접근성 이름 | 라벨 텍스트 | `accessibilityLabel`(기본 `String(label)`) |
+| 배치 | `layoutStyle` | `layoutStyle`(`style`은 deprecated) |
+| 라벨 스타일 훅 | 없음 | `labelStyle` deprecated — tone/토큰 |
+| 기본 폭 | inline | `alignSelf: "flex-start"` |