@hjmds/design-contracts 1.12.0 → 1.13.0

package/docs/usage/compositions/visual-foundations.md

@@ -0,0 +1,185 @@
+# 시각 효과 모음
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [EffectSurface](../../effect-surface.md), [Avatar fallback](../../avatar-fallback.md), [Icon](../../icon.md), `showcase/shared/visual-foundations.ts`, `showcase/{web/src/patterns,native/src}/visual-previews.tsx`, `src/container.ts`, `packages/react/src/composition-style.ts`
+- 스토리북: `배포/구성/비교와 검증/시각 효과 모음`
+
+## 언제 쓰나
+
+배경 질감, 의미 이름 아이콘, 사진 없는 프로필 얼굴, 문장 전환처럼 화면의 분위기를 더하는 선택 표현을 고를 때 이 모음을 본다.
+네 스토리(배경 효과·의미별 루시드 아이콘·블로바타 표정·내용 전환 효과)가 각 표현의 선택지를 나란히 비교한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| EffectSurface | `mesh`·`glow`·`grain` 배경 층 위에 내용을 둔다 | [EffectSurface](../components/effect-surface.md) |
+| Icon + `createLucideGlyph` | 의미 이름(`search`·`settings`·`notifications`·`back`)을 Lucide 그림에 연결 | [Icon](../components/icon.md) |
+| Avatar + `createBlobatarFallback` | 사진이 없을 때 seed로 정해지는 얼굴, `expression: "happy"` | [Avatar](../components/avatar.md) |
+| TextTransition | 문장이 바뀔 때 `fade`·`rise`·`slide`·`scale` 전환 | [TextTransition](../components/text-transition.md) |
+| Heading | 효과 표면 안 제목, 얼굴 묶음 제목(`level2`) | [Heading](../components/heading.md) |
+| Button | 효과 켜기(`selected`)·다음 장면 | [Button](../components/button.md) |
+| `ScrollView` + `Container`(Native) | 바깥 틀. 세로 스크롤·위아래 여백, 좌우 gutter | [Container](../components/container.md), [화면 여백과 너비](../tokens/layout.md) |
+
+비교 결과로 고르는 기준이다.
+
+| 비교 | 선택지 | 고르는 기준 |
+| --- | --- | --- |
+| 배경 효과 | `mesh` / `glow` / `grain` / 셋 모두, `active` 켬·끔 | 히어로·빈 화면 배경 하나에만. 위 글자는 일반 대비 tone으로 둔다 |
+| 의미별 아이콘 | 의미 이름 → 제품 아이콘 세트 | 컴포넌트에는 이름만 넘기고 그림은 제품이 `renderGlyph`로 연결 |
+| 블로바타 표정 | 기본 / `happy` | 사진이 없을 때만. seed는 공개 제품 식별자 |
+| 내용 전환 | `fade`(기본) / `rise` 12 / `slide` 16 / `scale` 0.96 | 같은 자리의 문장 교체는 `fade`, 단계가 넘어가면 `slide` |
+
+## 배치
+
+```text
+Native 화면(ScrollView, 위아래 spacing.lg 20) > Container gutter 16(폭 < 600) · 20(폭 ≥ 600)
+배경 효과 (Stack gap spacing.xl 24)
+[ 배경 움직임 ]  ← selected 토글
+┌──── EffectSurface (mesh) ────────────────────┐
+│ 안쪽 여백 spacing.xl 24(두 플랫폼 같음)       │
+│ mesh                (label)                   │
+│ 작은 시작, 새로운 장면.  (Heading level2) ↕ lg 20 │
+│ 설명 (body)                                   │
+│ [ 이야기 시작하기 ]  secondary                │
+└──────────────────────────────────────────────┘
+┌──── EffectSurface (glow) ─── ... ────────────┐
+┌──── EffectSurface (grain) ── ... ────────────┐
+┌──── EffectSurface (mesh+glow+grain) ─────────┐
+
+아이콘 / 얼굴 (행마다 가로, gap spacing.md 16)
+(🔍) search          (☺)(☻) 이름
+  고정 영역 없음. 안전 영역은 화면 골격이 맡는다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: 제품 화면 레이아웃(문서 스크롤) > Stack. Native: `ScrollView` > `Container` > Stack | 이 구성은 바깥 폭·여백을 정하지 않는다. Native는 `ScrollView` 안 [Container](../components/container.md)에 둔다. 입력이 없어 키보드 처리는 없다. 안전 영역은 화면 골격(내비게이션 헤더·탭 바)이 맡는다 | Native ScrollView 위아래 `spacing.lg` 20, Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20. 묶음 사이 Stack `gap="xl"` 24 |
+| 효과 표면 | EffectSurface > 안쪽 틀 > Stack `gap="lg"` | 세로로 쌓음(비교용. 실제 화면은 히어로 하나) | EffectSurface는 여백이 없다. 안쪽 틀 여백 `spacing.xl` 24(두 플랫폼 같음, [랜딩](../screens/landing.md) 히어로와 같다), 내용 사이 `spacing.lg` 20, `intensity` 0.4(예) |
+| 아이콘 행 | Icon `size="lg"` + Text | 가로(Stack `axis="inline"`) | 아이콘 `lg` 28, 사이 `spacing.md` 16 |
+| 얼굴 행 | Avatar ×2 + Text | 가로(Stack `axis="inline"`) | 두 플랫폼 48(Web `size="large"`, Native `size={48}`), 사이 `spacing.md` 16 |
+| 전환 | Text label + TextTransition | 세로 | 사이 `spacing.md` 16, 시간 `motion.normal` |
+
+## 흐름과 상태
+
+1. "배경 움직임"을 켜면 모든 EffectSurface `active`가 켜져 천천히 움직인다. 다시 누르면 멈춘다.
+2. "다음 장면"을 누르면 네 preset의 문장이 동시에 다음 문장으로 바뀐다.
+
+- 장면 문구 키는 순서 있는 상수 배열로 둔다(`sceneKeys[index]`). 번호로 키를 조립하지 않는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 효과 정지(`active` 기본 `false`) | 효과 층은 장식 |
+| 진행 중 | — (요청이 없다). 문장 전환 중에는 이전 문장이 나가고 새 문장이 들어온다 | — |
+| 실패 | — (요청이 없다). 프로필 사진이 없거나 로드에 실패하면 Avatar가 `renderFallback`(Blobatar)으로 바꾼다 | Avatar 이름이 읽힌다 |
+| 움직임 켬 | 층이 `period` 주기(기본 12초)로 움직인다 | 토글 버튼 `selected` 상태로 알린다 |
+| reduced motion | 효과·전환 모두 즉시·정지 | — |
+| 사진 없음 | Blobatar 얼굴, 같은 seed는 같은 얼굴 | 그림은 장식, Avatar 이름이 읽힌다 |
+| 다크 | 효과 색이 `primary`·`contentBrand`·`surfaceAccent` 테마 값을 따른다 | — |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Search } from "lucide-react";
+import { Button } from "@hjmds/react/actions";
+import { TextTransition } from "@hjmds/react/content-transition";
+import { Avatar, Icon } from "@hjmds/react/display";
+import { createBlobatarFallback } from "@hjmds/react/avatar-blobatar";
+import { EffectSurface } from "@hjmds/react/effect-surface";
+import { Heading } from "@hjmds/react/heading";
+import { createLucideGlyph } from "@hjmds/react/icon-lucide";
+import { Stack, Text } from "@hjmds/react/layout";
+
+const glyph = createLucideGlyph({ search: Search });
+const sceneKeys = ["intro.scene.welcome", "intro.scene.collect", "intro.scene.ready"] as const;
+
+<Stack gap="xl">
+  <EffectSurface descriptor={{ layers: ["mesh", "glow"], active, seed: "home-hero" }}>
+    {/* EffectSurface는 여백이 없다. 안쪽 틀: .hero-inner { padding: var(--hjm-space-xl) } */}
+    <div className="hero-inner">
+      <Stack gap="lg">
+        <Heading level="level2">{t("hero.title")}</Heading>
+        <Text>{t("hero.body")}</Text>
+        <Button tone="secondary" onClick={start}>{t("hero.start")}</Button>
+      </Stack>
+    </div>
+  </EffectSurface>
+  <Stack axis="inline" gap="md">
+    <Icon name="search" size="lg" renderGlyph={glyph} />
+    <Text>{t("icons.search")}</Text>
+  </Stack>
+  <Avatar name={user.name} size="large" renderFallback={createBlobatarFallback({ seed: user.publicId })} />
+  <TextTransition preset="fade" text={t(sceneKeys[index])} />
+</Stack>;
+```
+
+```tsx
+// Native
+import { ScrollView, View, useWindowDimensions } from "react-native";
+import { Search } from "lucide-react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Button } from "@hjmds/react-native/actions";
+import { TextTransition } from "@hjmds/react-native/content-transition";
+import { Avatar } from "@hjmds/react-native/data-display";
+import { createBlobatarFallback } from "@hjmds/react-native/avatar-blobatar";
+import { EffectSurface } from "@hjmds/react-native/effect-surface";
+import { Heading } from "@hjmds/react-native/heading";
+import { createLucideGlyph } from "@hjmds/react-native/icon-lucide";
+import { Container, Icon, Stack, Text } from "@hjmds/react-native/primitives";
+
+const glyph = createLucideGlyph({ search: Search });
+const sceneKeys = ["intro.scene.welcome", "intro.scene.collect", "intro.scene.ready"] as const;
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container gutter={gutter}>
+    <Stack gap="xl">
+      <EffectSurface descriptor={{ layers: ["mesh", "glow"], active, seed: "home-hero" }} visible={isFocused}>
+        {/* EffectSurface는 여백이 없다. 안쪽 틀만 View padding으로 준다 */}
+        <View style={{ padding: spacing.xl }}>
+          <Stack gap="lg">
+            <Heading level="level2">{t("hero.title")}</Heading>
+            <Text>{t("hero.body")}</Text>
+            <Button tone="secondary" onPress={start}>{t("hero.start")}</Button>
+          </Stack>
+        </View>
+      </EffectSurface>
+      <Stack axis="inline" gap="md">
+        <Icon descriptor={{ name: "search", size: "lg" }} renderGlyph={glyph} />
+        <Text>{t("icons.search")}</Text>
+      </Stack>
+      <Avatar name={user.name} accessibilityLabel={user.name} size={48}
+        renderFallback={createBlobatarFallback({ seed: user.publicId })} />
+      <TextTransition preset="fade" text={t(sceneKeys[index])} />
+    </Stack>
+  </Container>
+</ScrollView>;
+```
+
+seed·문구·아이콘 세트·얼굴 목록은 제품 소유다. `createBlobatarFallback`은 optional peer `blobatar@2.7.0`이 필요하다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 효과 표면 안쪽 틀 | `div` + CSS `padding: var(--hjm-space-xl)`(`layoutStyle`은 padding을 받지 않는다) | `View style={{ padding: spacing.xl }}` |
+| Avatar 크기 | 이름 단계 `large` 48 | 숫자 pt `48` |
+| 바깥 틀 | 제품 화면 레이아웃(문서 스크롤) | `ScrollView` > `Container` |
+| 가려짐 알림 | 없음 | EffectSurface `visible`(화면 focus) |
+| Icon 크기 지정 | `size` prop | `descriptor.size` |
+| 표정 접근성 이름 | `name`에 넣음 | `accessibilityLabel` |
+
+## 함정
+
+- 움직이는 glow 위의 작은 글자를 브랜드 색으로 두면 대비가 4.5:1 아래로 떨어진다. 일반 본문 tone을 쓴다.
+- Blobatar seed에 이름·이메일을 쓰지 않는다. 공개 제품 식별자를 쓴다.
+- EffectSurface는 화면 위쪽 히어로 하나에만 둔다. 스토리의 네 장 세로 쌓기는 비교용이다.
+- 2026-10-06 예제 검수에서 Container·Stack·Heading을 두 플랫폼에 맞췄다. 효과 안쪽 여백은 spacing.xxl(32), 얼굴은 64, 제목은 level2로 동일하다. 행은 큰 글자에서 줄바꿈한다.
+- Native EffectSurface는 AppState·reducedMotion을 반영한다. 백그라운드 중단과 내비게이션으로 가려진 화면의 중단은 다르므로, 마운트된 채 가려지는 제품 화면·목록은 `visible`을 연결한다. Storybook 정지 화면만으로 이 제품 연결을 검증했다고 보고하지 않는다.

package/docs/usage/compositions/web-additions.md

@@ -0,0 +1,146 @@
+# 웹 전용 보조 컴포넌트
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [ColorPicker](../../color-picker.md), [Watermark](../../watermark.md), [Affix](../../affix.md), `showcase/web/src/patterns/WebAdditions.stories.tsx`, `packages/react/src/affix.tsx`, `packages/react/src/styles.css`(`.hjm-color-picker`, `.hjm-watermark`, `.hjm-affix`), `src/affix.ts`, `src/color-picker.ts`
+- 스토리북: `배포/구성/비교와 검증/웹 전용 보조 컴포넌트`
+
+## 언제 쓰나
+
+Web에만 있는 보조 컴포넌트 세 개(색 고르기, 문서 워터마크, 스크롤 중 고정되는 실행 영역)를 실제 쓰임 하나씩과 함께 보여 주는 모음이다.
+스토리 셋은 서로 이어진 흐름이 아니다. 무엇을 고를지는 아래 기준으로 정한다.
+
+| 필요 | 고를 것 | 스토리 |
+| --- | --- | --- |
+| 사용자가 강조 색 같은 **사용자 데이터 색**을 고른다 | `ColorPicker` | 색상 선택 |
+| 검토용·대외비 문서임을 본문 위에 표시하되 읽기·선택·버튼은 막지 않는다 | `Watermark` | 문서 표시 |
+| 긴 스크롤 영역에서 저장 같은 실행 버튼을 위쪽에 붙여 둔다 | `Affix` | 고정 실행 영역 |
+
+Native 화면에서 같은 일이 필요하면 이 구성을 옮기지 않는다. 하단 고정 행동은 [BottomCTA](../components/bottom-cta.md)를 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `ColorPicker` | 네이티브 색 입력 + HEX 입력 + 불투명도(`alpha`) + 프리셋 견본. controlled | [ColorPicker](../components/color-picker.md) |
+| 선택값 문구 `Text` `role="status"` | 바뀐 HEX를 알림. 값은 `<bdi dir="ltr">`로 감싼다 | [Text](../components/text.md) |
+| `Watermark` | 본문 위 장식 SVG 타일. 포인터·선택을 가로채지 않는다 | [Watermark](../components/watermark.md) |
+| `Affix` | 가장 가까운 스크롤 조상 상단에 `position: sticky`로 붙는다 | [Affix](../components/affix.md) |
+| `Heading` | 워터마크 안 문서 제목 | [Heading](../components/heading.md) |
+| `Button` | 워터마크 위 저장, Affix 안 저장. 저장 중 `loading` | [Button](../components/button.md) |
+| `Notice` | 저장 실패 안내(스토리에 없음) | [Notice](../components/notice.md) |
+
+## 배치
+
+```text
+색상 선택                               문서 표시
+┌ fieldset ──────────────────────┐      ┌ Watermark ──────────────────────┐
+│ 강조 색상 (legend)             │      │ ╱HJM╱  검토 중인 문서  ╱HJM╱    │ ← 타일 240×160, -22°, 0.12
+│ [■] [ HEX  #b94627cc        ]  │      │ 본문 문단 (선택 가능)           │
+│ 불투명도 ───────●──────        │      │ [ 문서 저장 ]                   │ ← 오버레이 위에서도 눌림
+│ [ 미리보기 막대             ]  │      └─────────────────────────────────┘
+│ [■ 프리셋][■ 프리셋][■ 프리셋] │
+└────────────────────────────────┘
+선택한 색상: #b94627cc  ← live
+
+고정 실행 영역(스크롤 조상 안)
+┌ 스크롤 영역 ───────────────────┐
+│ ↑ offset spacing.xs 8          │
+│ [ 변경 저장 ] 상단 고정 중     │ ← Affix: 스크롤하면 이 줄이 위에 붙는다
+│ … 긴 본문(스크롤) …            │
+└────────────────────────────────┘
+바깥 틀: 제품 페이지(문서 스크롤, Container). 안전 영역·키보드 처리 없음
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 제품 페이지 레이아웃(문서 스크롤) | 세 스토리 모두 바깥 폭·여백을 정하지 않는다. 페이지 본문은 [Container](../components/container.md)가 정한다. Affix만 가장 가까운 스크롤 조상(문서 또는 제품의 `overflow: auto` 영역)에 붙는다. Web 전용이라 안전 영역·화면 키보드 처리는 없다 | Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20 |
+| 색 입력 줄 | `ColorPicker` 색 견본 + HEX | fieldset 첫 줄, 좁으면 줄바꿈(`flex-wrap`) | 입력 최소 높이 `colorPickerRecipe.minTargetSize` 44, 색 견본 폭 3rem, 줄 간격 0.75rem |
+| 불투명도·미리보기·프리셋 | `ColorPicker` 내부 | 색 입력 아래 순서대로 | 각 위 여백 0.75rem, 프리셋 사이 0.5rem, 프리셋 최소 높이 44 |
+| 선택값 | live 문구 | ColorPicker 바로 아래 | 제품 레이아웃 소유 |
+| 워터마크 | `Watermark` | 감싼 본문 전체를 덮는 오버레이(`inset: 0`) | `tileWidth` 240 · `tileHeight` 160 · `rotate` -22 · `opacity` 0.12(기본값), 색 `--hjm-color-text-sub` |
+| 고정 행동 | `Affix` | 스크롤 조상 상단 + `offset` | `offset` 기본 0, 띄울 때는 spacing 토큰 값(스토리 `spacing.xs` 8). 스크롤 조상보다 높으면 고정하지 않고 흐름에 남는다 |
+| 저장 실패 | `Notice` danger | 저장 버튼 위(Watermark 본문 안, Affix 아래 본문 첫머리) | 버튼과 `spacing.md` 16 |
+
+- ColorPicker 내부 간격은 CSS가 rem 값으로 직접 둔다(`padding: 1rem`, `gap: 0.75rem`·`0.5rem`). 제품에서 덮지 않는다.
+- Affix는 스크롤 조상 안에서만 붙는다. 그 조상의 높이·overflow는 제품 레이아웃이 정한다(스토리의 280px 박스는 데모 값).
+
+## 흐름과 상태
+
+1. 색상 선택: 색 견본·HEX·프리셋 중 하나로 고른다 → `onValueChange`가 소문자 `#rrggbb`(또는 `alpha`면 `#rrggbbaa`)를 준다 → 문구가 갱신된다.
+2. HEX 입력은 Enter·blur에 확정되고 Escape는 마지막 `value`로 되돌린다.
+3. 문서 표시: 워터마크 위에서 본문을 선택하고 버튼을 누른다. 워터마크는 상태가 없다.
+4. 고정 실행 영역: 스크롤하면 Affix가 상단에 붙고 `onChange(true)`, 다시 올리면 `onChange(false)`가 온다.
+5. 저장: 버튼이 `loading`이 되고, 실패하면 Notice danger가 나오며 버튼을 다시 누를 수 있다. 성공하면 Notice를 내린다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | ColorPicker는 `value` 색, 워터마크 타일, Affix는 일반 위치(`data-affixed` 없음) | — |
+| 진행 중 | 저장 버튼 `loading`(Watermark·Affix 안). ColorPicker는 요청이 없다 | 포커스는 버튼에 남는다 |
+| 실패 | 저장 실패 Notice danger, 버튼 다시 활성. Affix 고정 중이면 버튼은 그대로 위에 붙어 있다 | Notice `danger`는 `role="alert"` |
+| HEX 잘못 입력 | `labels.invalid` 문구가 오류로 보이고 외부 값은 그대로 | 오류 문구는 alert |
+| 프리셋 선택됨 | 선택한 견본 테두리가 primary 색, `aria-pressed="true"` | — |
+| `disabled` | fieldset 전체 흐림(opacity 0.5), 입력·프리셋 막힘 | 포커스 불가 |
+| Affix 고정 중 | `data-affixed="true"`, 배경 `--hjm-color-bg` | 고정돼도 버튼 상태·키보드 포커스 유지(자식 재마운트 없음) |
+| Affix 너무 큼 | `data-oversize="true"`, 고정하지 않고 일반 흐름 | — |
+
+## 코드 골격
+
+```tsx
+// Web
+import { ColorPicker } from "@hjmds/react/color-picker";
+import { Watermark } from "@hjmds/react/watermark";
+import { Affix } from "@hjmds/react/affix";
+import { Button } from "@hjmds/react/actions";
+import { Notice } from "@hjmds/react/feedback";
+import { Heading } from "@hjmds/react/heading";
+import { Stack, Text } from "@hjmds/react/layout";
+
+<Stack gap="md">
+  <ColorPicker label={t("theme.accent")} value={color} onValueChange={setColor} alpha
+    presets={productPresets}
+    labels={{ color: t("theme.color"), hex: t("theme.hex"), opacity: t("theme.opacity"), invalid: t("theme.invalidHex") }} />
+  <Text role="status">{t("theme.selected")} <bdi dir="ltr">{color}</bdi></Text>
+</Stack>;
+
+<Watermark text={[t("doc.watermark.brand"), t("doc.watermark.review")]}>
+  <Stack gap="md">
+    <Heading level="level3">{t("doc.title")}</Heading>
+    {documentBody}
+    {saveFailed ? <Notice tone="danger" title={t("doc.saveFailed")} /> : null}
+    <Button loading={saving} onClick={save}>{t("doc.save")}</Button>
+  </Stack>
+</Watermark>;
+
+<div className="scroll-region" /* 제품 소유 스크롤 조상 */>
+  <Affix offset={8 /* spacing.xs */} onChange={setPinned}>
+    <Button loading={saving} onClick={save}>{t("doc.saveChanges")}</Button>
+  </Affix>
+  {longContent}
+</div>;
+```
+
+```tsx
+// Native
+// 없음. 세 컴포넌트 모두 Native 구현이 없다.
+```
+
+스토리의 초기 색 `#b94627cc`와 프리셋 세 색은 예시 데이터다. 프리셋은 제품 소유이며 브랜드 색을 넣더라도 사용자 데이터 값으로만 다룬다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `ColorPicker` | `/color-picker` | 없음 |
+| `Watermark` | `/watermark` | 없음 |
+| `Affix` | `/affix`(root entry에 없음) | 없음. 하단 고정은 [BottomCTA](../components/bottom-cta.md) |
+
+## 함정
+
+- 세 컴포넌트 모두 root barrel에 없다. granular subpath(`@hjmds/react/color-picker` 등)로만 import한다.
+- Affix `offset`이 음수이거나 유한하지 않으면 `TypeError`를 던진다.
+- Watermark 범위(`tileWidth` ≥ 80, `tileHeight` ≥ 60, `rotate` -90~90, `opacity` 0~1, 줄 1~3개·각 120자 이하)를 벗어나면 `TypeError`다.
+- 현재 스토리의 저장은 라벨만 "저장됨"으로 바꾸는 토글이다. 진행 중·실패 경로가 없다.

package/docs/usage/compositions/web-navigation.md

@@ -0,0 +1,143 @@
+# 보관함과 페이지 이동
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Breadcrumb](../../breadcrumb.md), [Pagination](../../pagination.md), `showcase/web/src/patterns/WebNavigation.stories.tsx`, `packages/react/src/styles.css`(`.hjm-breadcrumb`, `.hjm-pagination`), `src/component-recipes.ts`(`listRowRecipe`)
+- 스토리북: `배포/구성/탐색과 이동/보관함과 페이지 이동`
+
+## 언제 쓰나
+
+Web에서 상위 보관함 → 하위 모음으로 들어가고, 그 모음의 긴 목록을 페이지 단위로 넘겨 보는 탐색에 쓴다.
+위에 경로(Breadcrumb), 가운데 목록(List), 아래 페이지 이동(Pagination)을 둔다. 무한 스크롤·더 보기가 맞으면
+[LoadMore](../components/load-more.md)를, 앱 화면 전환이면 Native 내비게이션을 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Breadcrumb` | 현재 위치까지의 경로. 마지막 항목만 현재 위치(링크 없음) | [Breadcrumb](../components/breadcrumb.md) |
+| `Section` | 모음 제목·설명("산책 기록 125개") | [Section](../components/section.md) |
+| `Link` | 상위 화면에서 하위 모음으로 들어가는 링크 | [Link](../components/link.md) |
+| 범위 문구 `Text` `role="status"` | "1–5번째 기록". 숫자 범위는 `<bdi>`로 감싼다 | [Text](../components/text.md) |
+| `List` + `ListRow` | 현재 페이지 항목 | [List](../components/list.md), [ListRow](../components/list-row.md) |
+| `Pagination` | 이전·번호·다음. `descriptor={{ currentPage, totalCount, pageSize }}` | [Pagination](../components/pagination.md) |
+| `Stack` | 바깥 `gap="lg"`, 모음 안 `gap="md"` | [Stack](../components/stack.md) |
+| `Skeleton` · `Notice` | 서버에서 페이지를 받을 때 목록 자리의 로딩·실패(스토리에 없음) | [Skeleton](../components/skeleton.md), [Notice](../components/notice.md) |
+
+## 배치
+
+```text
+페이지 본문(문서 스크롤) > Container gutter 16(폭 < 600) · 20(폭 ≥ 600)
+┌ 콘텐츠(스크롤) ────────────────────────────────┐
+│ 전체 보관함 › 산책 기록          ← Breadcrumb  │
+│              ↕ spacing.lg 20                    │
+│ ┌ 콘텐츠 영역 (tabIndex=-1, 포커스 대상) ────┐  │
+│ │ 걸었던 날을 모아봤어요   (Section 제목)    │  │
+│ │ 산책 기록 125개          (설명)            │  │
+│ │              ↕ spacing.md 16               │  │
+│ │ 1–5번째 기록             ← status          │  │
+│ │              ↕ spacing.md 16               │  │
+│ │ ┌ 1번째 산책 기록 / 설명 ───────────────┐  │  │ ListRow 두 줄 최소 68
+│ │ ├ 2번째 산책 기록 / 설명 ───────────────┤  │  │
+│ │ └ … (pageSize 5) ───────────────────────┘  │  │
+│ │              ↕ spacing.md 16               │  │
+│ │ [‹] [1] [2] [3] … [25] [›] ← Pagination    │  │ 칸 최소 44×44
+│ └────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────┘
+  고정 영역 없음. Web 전용이라 안전 영역·화면 키보드 처리는 없다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 제품 페이지 레이아웃(문서 스크롤) > [Container](../components/container.md) | 이 구성은 바깥 폭·여백을 정하지 않는다(스토리는 Stack만 그린다). 목록 화면이므로 페이지 본문은 Container `size="content"`가 정한다. 고정 영역·안전 영역·키보드 처리는 없다 | Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20 |
+| 경로 | `Breadcrumb` | 콘텐츠 맨 위, 스크롤과 함께 | 항목·구분자 사이 `spacing.xxs` 4, 좁으면 줄바꿈 |
+| 콘텐츠 머리 | `Section` 제목·설명 | 경로 아래 | 경로와 `spacing.lg` 20 |
+| 범위 | status 문구 | 머리 아래, 목록 위 | `spacing.md` 16 |
+| 목록 | `List` + `ListRow` | 범위 아래 | 두 줄 행 최소 `layout.rowHeight.twoLine` 68(comfortable), 사이 `spacing.md` 16 |
+| 로딩·실패 | `Skeleton` 행 / `Notice` danger + 다시 시도 | 목록 자리(범위 문구·Pagination은 그대로) | 목록과 같은 자리 |
+| 페이지 이동 | `Pagination` | 목록 바로 아래, 시작 정렬 | 칸 최소 `control.minTouchTarget` 44, 칸 사이 `spacing.xxs` 4, 좁으면 줄바꿈 |
+
+- Pagination은 목록 **아래**에 둔다. 위·아래 두 벌을 두지 않는다.
+- 상위 화면(보관함)은 같은 콘텐츠 영역에 Section + Link 하나만 그린다. 경로는 항목 하나(현재 위치)로 줄어든다.
+
+## 흐름과 상태
+
+1. 보관함에서 "산책 기록 125개 보기" Link를 누른다.
+2. 경로가 "전체 보관함 › 산책 기록"으로 바뀌고 포커스가 새 콘텐츠 영역으로 옮겨진다.
+3. Pagination으로 페이지를 바꾸면 목록과 범위 문구만 바뀐다. 서버에서 받으면 그동안 목록 자리에 Skeleton이 나온다.
+4. 페이지를 받지 못하면 목록 자리에 Notice와 "다시 시도"가 나오고 Pagination은 요청한 페이지에 남는다.
+5. 경로의 "전체 보관함"을 누르면 상위로 돌아가고 페이지는 1로 초기화된다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 상위(보관함): Section + Link, 경로는 현재 항목 하나 | 첫 진입에는 포커스를 옮기지 않는다 |
+| 진행 중 | 서버에서 받는 페이지면 목록 자리에 `Skeleton` 행, Pagination은 새 페이지 표시. 늦게 온 이전 페이지 응답은 버린다 | 포커스는 Pagination에 남는다 |
+| 실패 | 목록 자리에 `Notice` danger + `action` "다시 시도"(같은 페이지 재요청), 범위 문구는 비운다 | Notice `danger`는 `role="alert"` |
+| 모음 진입 | 경로 두 단계, 목록 1페이지 | 누른 링크가 사라지므로 콘텐츠 영역(`tabIndex={-1}`)에 `focus({ preventScroll: true })` |
+| 페이지 변경 | 목록 5개 교체, 범위 문구 갱신 | 포커스는 Pagination에 남고 범위 문구(`role="status"`)가 알린다 |
+| 첫·마지막 페이지 | 이전/다음 칸이 `aria-disabled`, opacity 0.5 | — |
+
+- 문구 키는 상태별 상수로 둔다(`records.range`·`records.loadFailed`·`common.retry`). 현재 페이지 이름은 `current`에 따라 두 키(`records.pageCurrent`·`records.pageGo`) 중 하나를 고른다. 범위 문구는 숫자 → 문구 순서를 코드에 고정한다(스토리와 같다). 언어마다 순서가 다르면 제품 i18n의 rich text 기능으로 `<bdi>`를 끼운다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { Breadcrumb } from "@hjmds/react/breadcrumb";
+import { Pagination } from "@hjmds/react/pagination";
+import { Button } from "@hjmds/react/actions";
+import { List, ListRow } from "@hjmds/react/display";
+import { Notice, Skeleton } from "@hjmds/react/feedback";
+import { Section, Stack, Text } from "@hjmds/react/layout";
+
+<Stack gap="lg">
+  <Breadcrumb label={t("records.path")} items={[
+    { id: "records", label: t("records.all"), destination: { kind: "internal", href: "/records" } },
+    { id: "walks", label: t("records.walks") },
+  ]} />
+  <div ref={contentRef} tabIndex={-1}>
+    <Section title={t("records.walks.title")} description={t("records.walks.count", { count: total })}>
+      <Stack gap="md">
+        <Text role="status">{status === "ready" ? <><bdi>{from}–{to}</bdi>{t("records.range")}</> : ""}</Text>
+        {status === "loading"
+          ? <Stack gap="xs"><Skeleton shape="text" /><Skeleton shape="text" width="60%" /></Stack>
+          : status === "failed"
+            ? <Notice tone="danger" title={t("records.loadFailed")}
+                action={<Button tone="secondary" size="small" onClick={retry}>{t("common.retry")}</Button>} />
+            : <List label={t("records.walks.list")}>
+                {rows.map((row) => <ListRow key={row.id} title={row.title} description={row.summary} />)}
+              </List>}
+        <Pagination label={t("records.pages")}
+          descriptor={{ currentPage: page, totalCount: total, pageSize: 5 }}
+          labels={{ previous: t("records.prev"), next: t("records.next") }}
+          composeAccessibleName={({ page, totalPages, current }) => t(current ? "records.pageCurrent" : "records.pageGo", { page, totalPages })}
+          onPageChange={setPage} />
+      </Stack>
+    </Section>
+  </div>
+</Stack>;
+```
+
+```tsx
+// Native
+// 없음. Breadcrumb·Pagination은 Web 전용이다.
+```
+
+라우팅(스토리는 데모용 hash fragment), 레코드 125개, pageSize 5는 예시다. 경로·페이지 크기·URL 동기화는 제품 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `Breadcrumb` | `/breadcrumb`, `/navigation` | 없음 |
+| `Pagination` | `/pagination`, `/navigation` | 없음. 긴 목록은 [LoadMore](../components/load-more.md) |
+
+## 함정
+
+- Breadcrumb 마지막 항목에 `destination`을 주거나, 앞 항목에서 빠뜨리면 `TypeError`다.
+- 범위 숫자를 `<bdi>`로 감싸지 않으면 RTL에서 "5–1"처럼 뒤집혀 읽힌다.
+- 탐색 후 포커스를 옮기지 않으면 누른 링크가 사라져 포커스가 `body`로 떨어진다. 첫 마운트·페이지 변경에서는 옮기지 않는다.
+- 현재 스토리는 로컬 배열을 잘라 쓰므로 로딩·실패 경로가 없다.

package/docs/usage/screens/common-chat.md

@@ -0,0 +1,127 @@
+# 채팅
+
+- 단계: 화면
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/공통 화면/채팅`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/화면/소통/채팅`
+
+## 목적
+
+ChatScreen을 사용해 채팅 흐름을 구성한다. 제품이 데이터·권한·서버 확정·문구를 공급하며, 예제의 메모리 저장을 운영 저장으로 취급하지 않는다.
+
+## 영역 구조
+
+```text
+host: 남은 높이·safe area·키보드
+└─ 헤더 → 메시지 타임라인 → 작성창
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | ChatScreen | route 본문 | [API 배치 규칙](../components/chat-screen.md#배치), host 남은 높이 |
+| 내용 | 공개 슬롯 | 헤더 → 메시지 타임라인 → 작성창 | 화면 recipe의 sectionGap·itemGap; 슬롯 안은 각 지침 토큰 |
+| 상태 | state 또는 해당 API 상태 | 본문 자리·비차단 notice | 입력 중 실패는 본문 높이와 초안을 유지 |
+
+## 버튼과 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 작업 | ChatScreen 공개 행동 슬롯 | 전송은 composer 끝; 답장은 메시지의 명시 행동과 제스처 | 같은 표면에 경쟁하는 primary 하나만 |
+| 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
+
+## 상태
+
+| 상태 | 화면 모습 | 행동 |
+| --- | --- | --- |
+| 기본 | 헤더 → 메시지 타임라인 → 작성창 | 각 공개 콜백을 제품 상태에 연결 |
+| 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
+| 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
+| 오류 | 전송 실패는 초안과 타임라인을 유지하고 notice로 안내 | 실패 원인과 재시도 경로 제공 |
+
+## 사용하는 지침
+
+| 지침 | 쓰는 곳 |
+| --- | --- |
+| [ChatScreen](../components/chat-screen.md) | 필수 props·슬롯·플랫폼 차이 |
+| [Button](../components/button.md) | 동작·로딩·보조 행동 |
+| [ScreenLayout](../components/screen-layout.md) | 화면 높이·본문 교체·스크롤 소유 |
+
+## 코드 골격
+
+```tsx
+// Web — host가 실제 남은 높이를 준다(예: height: 100dvh)
+import { ChatMessage, ChatScreen, MessageComposer } from "@hjmds/react/screens";
+
+<ChatScreen
+  title={t("chat.title")}
+  scroll="screen" // 짧은 기록. 긴 기록은 제품 가상 목록 + 기본 scroll="content"
+  state={isPending ? { kind: "loading", title: t("chat.loading") } : { kind: "ready" }}
+  composer={<MessageComposer value={draft} label={t("chat.input")} sendLabel={t("chat.send")}
+    pending={sending} onValueChange={setDraft} onSend={send} />}
+>
+  {messages.map((m) => (
+    <ChatMessage key={m.id} direction={m.direction} author={m.author} timestamp={m.timestamp}
+      {...(m.deliveryLabel ? { deliveryLabel: m.deliveryLabel } : {})}>
+      {m.text}
+    </ChatMessage>
+  ))}
+</ChatScreen>
+```
+
+```tsx
+// Native — host가 safe area·키보드를 한 번 처리한다
+import { FlatList } from "react-native";
+import { ChatMessage, ChatScreen, MessageComposer } from "@hjmds/react-native/screens";
+import { Text } from "@hjmds/react-native/primitives";
+
+<ChatScreen
+  title={t("chat.title")}
+  state={isPending ? { kind: "loading", title: t("chat.loading") } : { kind: "ready" }}
+  composer={<MessageComposer value={draft} label={t("chat.input")} sendLabel={t("chat.send")}
+    pending={sending} onValueChange={setDraft} onSend={send} />}
+>
+  {/* 기본 scroll="content": 가상 목록이 스크롤을 소유한다 */}
+  <FlatList
+    data={messages}
+    keyExtractor={(m) => m.id}
+    renderItem={({ item: m }) => (
+      <ChatMessage direction={m.direction} author={m.author} timestamp={m.timestamp}
+        {...(m.deliveryLabel ? { deliveryLabel: m.deliveryLabel } : {})}>
+        <Text>{m.text}</Text>
+      </ChatMessage>
+    )}
+  />
+</ChatScreen>
+```
+
+`ChatScreen`의 `scroll` 기본값은 `"content"`다(본문은 스크롤하지 않고 자식 목록이 스크롤을 소유한다). 메시지 목록은
+HJM이 제공하지 않으므로 제품이 고른다: Native는 `FlatList`, Web은 가변 높이 가상 목록 또는 짧은 기록의 `scroll="screen"`.
+HJM `Timeline`(이벤트 연표)과 `VirtualList`(고정 `rowHeight`)는 높이가 제각각인 메시지 목록용이 아니다.
+`deliveryLabel`은 선택 prop이라 값이 없을 때 `undefined`를 넘기지 않고 조건부 spread로 뺀다(`exactOptionalPropertyTypes`).
+콜백·데이터·지역화 함수는 제품에서 공급한다.
+
+## 큰 글자·다크·좁은 폭
+
+| 조건 | 바뀌는 것 |
+| --- | --- |
+| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
+| 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
+| 좁은 폭 | 320px부터 한 열로 읽기 순서 유지. 가상화 본문은 scroll=content, 중첩 스크롤 금지 |
+| 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 메시지 목록 | 제품 가변 높이 가상 목록 또는 짧은 기록의 `scroll="screen"` | `FlatList`(기본 `scroll="content"`) |
+| 키보드 | 브라우저가 처리, footer 가림만 확인 | host 키보드 어댑터 또는 `KeyboardAvoidingView` 하나로 감싼다(둘 다 쓰지 않음) |
+
+## 함정
+
+- 전송 실패는 초안과 타임라인을 유지하고 notice로 안내.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.
+- 긴 대화를 `scroll="screen"` + map으로 그리지 않는다. Native는 `FlatList`(기본 `scroll="content"`, 답장 원문 이동은 `scrollToIndex`), Web은 가변 높이 가상 목록이다. Web 예제의 `scroll="screen"`은 짧은 고정 기록이라서다.
+- 실패 복구 스토리(`실패와 초안 복구`)는 다음 전송 실패를 예약하는 데모 도구로 연다.