@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/compositions/reference-settings.md

@@ -0,0 +1,107 @@
+# 변경 저장과 이탈 확인
+
+- 단계: 구성
+- 상태: 배포
+- 지원: 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-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/피드백과 복구/변경 저장과 이탈 확인`
+
+## 언제 쓰나
+
+저장값과 편집 초안을 비교해 이탈 확인 흐름이 필요할 때 쓴다. Form의 상태·콜백을 제품 로직에 연결하며 새 데이터 엔진을 만들지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Form | 저장값과 편집 초안을 비교해 이탈 확인 | [공개 계약](../components/form.md) |
+| Button | 명시 행동·재시도 | [Button](../components/button.md) |
+
+## 배치
+
+```text
+부모 화면의 공개 슬롯
+└─ 입력 → 저장·되돌리기 → 이탈 확인
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Form 또는 포함 Surface | 부모 화면의 해당 슬롯 | [배치](../components/form.md#배치)에 따른다 |
+| 내용 | Form 내부 슬롯 | 입력 → 저장·되돌리기 → 이탈 확인 | spacing 토큰과 포함 컴포넌트 recipe |
+| 행동 | Button 또는 공개 콜백 | 내용과 가까운 명시 진입점 | 주 행동 하나, 보조 행동과 구분 |
+
+## 흐름과 상태
+
+1. 저장값과 편집 초안을 비교해 이탈 확인.
+2. 진행 상태와 제품의 실제 확정을 분리한다.
+3. 버리기는 마지막 저장값 복원, 계속 수정은 현재 초안 유지.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 입력 → 저장·되돌리기 → 이탈 확인 | 이름·선택 여부를 보조공학에 노출 |
+| 진행 중 | 해당 작업 pending, 입력·기존 결과 보존 | 중복 요청 차단, 로딩에 포커스를 옮기지 않음 |
+| 실패 | 버리기는 마지막 저장값 복원, 계속 수정은 현재 초안 유지 | 오류 근처 재시도, 필요할 때만 오류 읽기 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { useRef } from "react";
+import { Form, TextField } from "@hjmds/react/forms";
+import { Button } from "@hjmds/react/actions";
+
+const nicknameInputRef = useRef<HTMLInputElement>(null);
+
+<Form
+  aria-label={t("profile.formLabel")}
+  onSubmit={async () => {
+    setServerError(null);
+    if (nicknameError) { nicknameInputRef.current?.focus(); return; } // Web은 첫 오류 포커스를 제품이 한다
+    try { await save(values); } catch { setServerError(t("profile.saveFailed")); }
+  }}
+  formError={serverError}
+  actions={<Button type="submit">{t("profile.save")}</Button>}
+>
+  <TextField ref={nicknameInputRef} label={t("profile.nickname")} value={values.nickname}
+    onValueChange={setNickname} error={nicknameError ? t(nicknameError) : undefined} />
+</Form>
+```
+
+```tsx
+// Native
+import { useRef } from "react";
+import type { TextInput } from "react-native";
+import { Form } from "@hjmds/react-native/forms";
+import { TextField } from "@hjmds/react-native/inputs";
+
+const nicknameInputRef = useRef<TextInput>(null);
+
+<Form
+  label={t("profile.formLabel")}
+  values={values}
+  onSubmit={save} // 거절되면 Form이 오류를 표시한다(메시지가 없으면 fallbackErrorMessage)
+  submitLabel={t("profile.save")}
+  fallbackErrorMessage={t("profile.saveFailed")}
+  {...(nicknameError ? { firstInvalidFieldRef: nicknameInputRef } : {})} // Native는 Form이 첫 오류로 포커스를 옮긴다
+>
+  <TextField ref={nicknameInputRef} label={t("profile.nickname")} value={values.nickname}
+    onValueChange={setNickname} {...(nicknameError ? { error: t(nicknameError) } : {})} />
+</Form>
+```
+
+제품 데이터·콜백은 주입한다. 위 공개 API 지침에 Web·Native 차이를 유지한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 첫 오류 포커스 | 제품이 `onSubmit`에서 해당 입력 `ref.focus()` | `firstInvalidFieldRef`를 주면 Form이 그 입력에 포커스·보조공학 포커스를 옮기고 제출을 멈춘다 |
+| 저장 실패 표시 | 제품이 `formError`로 넘긴다 | `onSubmit`이 거절되면 Form이 오류 메시지(없으면 `fallbackErrorMessage`)를 표시한다 |
+| 제출 버튼 | `actions`에 `type="submit"` Button | `submitLabel`로 내장 버튼, `actions`로 교체 가능 |
+
+## 함정
+
+- 버리기는 마지막 저장값 복원, 계속 수정은 현재 초안 유지.
+- 포인터·제스처만으로 기능을 숨기지 않는다. 키보드·단일 탭 경로와 취소 후 복귀도 검증한다.

package/docs/usage/compositions/selection-scope.md

@@ -0,0 +1,174 @@
+# 대표 항목과 묶음 전체 선택
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [제품 상호작용 품질](../../../../../docs/INTERACTION_QUALITY.md), `showcase/web/src/patterns/SelectionScope.stories.tsx`, `showcase/native/src/SelectionScope.stories.tsx`. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/구성/상호작용 예제/대표 항목과 묶음 전체 선택`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/구성/선택과 필터/대표 항목과 묶음 전체 선택`
+
+## 언제 쓰나
+
+사진 묶음·스레드처럼 대표 항목 하나와 묶음 전체가 같은 모양으로 보일 때, 공유·삭제·이동 전에 대상 범위와 개수를 고르고 문구로 확인한 뒤 적용하게 할 때 쓴다.
+
+2026-10-02 조사에서 대표 항목과 전체 구성원을 같은 선택으로 오인할 위험을 확인했다. 길게 누르기나 작은 배지만으로 범위를 숨기는 방식은
+발견성·접근성 때문에 쓰지 않는다. 기본 범위·공유 정책·실제 전송은 제품이 정한다.
+
+같은 `상호작용 예제` 묶음: [선택 후 적용·취소](interaction-flow-apply.md) · [닫았다 열고 초안 이어쓰기](interaction-flow-draft.md) ·
+[늦은 응답보다 최신 검색 유지](interaction-flow-search.md). 상태 문구 알림은 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)을 따른다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Heading level="level3" semanticLevel={2}` | 질문형 제목 `t("share.scopeQuestion")` | [Heading](../components/heading.md) |
+| `Text` | 묶음 설명: 대표 1개 포함 전체 N개 | [Text](../components/text.md) |
+| `Button selected`(secondary) × 2 | 범위 선택: "대표만 · 1개" / "묶음 전체 · N개". 라벨에 개수를 넣는다 | [Button](../components/button.md) |
+| `Text` | 선택 범위 요약(범위 이름 + 개수) | [Text](../components/text.md) |
+| `Button`(primary) | 적용. 라벨에 개수를 넣는다 `t("share.apply", { count })`. 진행 중은 `loading` | [Button](../components/button.md) |
+| `Text` 상태 | 적용 결과·안내·실패 | [Text](../components/text.md) |
+| `Container`·`Stack` | 바깥 틀, 바깥 `gap="md"`, 범위 버튼 묶음 `gap="sm"` | [Container](../components/container.md), [Stack](../components/stack.md) |
+
+## 배치
+
+```text
+┌ 바깥 틀: 스크롤(Web 문서, Native ScrollView 위아래 spacing.md 16) ┐
+│ ← Container gutter 16(폭 600 미만)/20 · 최대 720 →                │
+│ 이 묶음에서 무엇을 공유할까요?       Heading level3(24)           │
+│ 묶음 설명(대표 1 · 전체 3)                 ↕ spacing.md 16        │
+│ ┌ 범위 선택 ───────────────────────┐                              │
+│ │ [ 대표 사진만 · 1개   ✓ ]        │ secondary, selected          │
+│ │          ↕ spacing.sm 12         │                              │
+│ │ [ 묶음 전체 · 3개       ]        │ secondary                    │
+│ └──────────────────────────────────┘       ↕ spacing.md 16        │
+│ 선택 범위: 대표 사진만 (1개)                                       │
+│ [ 1개 공유 대상으로 정하기 ]         ← 주 행동(primary), 개수 포함 │
+│ 결과·안내 (Web role=status, Native live region)                    │
+│ ░ 하단 안전 영역(화면 host 소유) ░                                 │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: `Container size="reading"` → `Stack gap="md"`. Native: `ScrollView` → `Container` → `Stack gap="md"` | 화면 본문 스크롤. 안전 영역은 화면 host(SafeArea·navigation header)가 준다. 입력이 없어 키보드 처리는 없다. 적용 버튼을 하단에 고정하면 [BottomCTA](../components/bottom-cta.md)가 하단 안전 영역을 맡는다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우는 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 최대 폭 `layout.readingMaxWidth` 720 |
+| 질문·설명 | `Heading` + `Text` | 맨 위 | 사이 `spacing.md` 16 |
+| 범위 선택 | `Button selected` × 2 | 설명 아래, 세로 묶음 | 각 `medium` 44(`control.buttonHeight`), 서로 `spacing.sm` 12 |
+| 범위 요약 | `Text` | 범위 선택 아래 | `spacing.md` 16 |
+| 주 행동 | `Button` 적용 | 요약 아래 | `medium` 44, `spacing.md` 16 |
+| 결과 | `Text` 상태 | 맨 아래 | `spacing.md` 16 |
+
+- 범위 버튼은 서로 가깝게(`spacing.sm` 12), 다른 덩어리와는 `spacing.md` 16으로 띄워 한 묶음으로 읽히게 한다.
+- 순서는 좁은 범위(대표) → 넓은 범위(전체)다. 기본 선택은 스토리에서 대표 항목이지만 제품이 정한다.
+- 범위 버튼은 `selected` 처리로 칠해져 primary로 세지 않는다. 화면의 primary는 적용 하나다([Button](../components/button.md) "한 화면 primary 하나"의 예외).
+- 적용 버튼이 화면 하단 고정이면 [BottomCTA](../components/bottom-cta.md)에 두고 라벨의 개수는 유지한다.
+
+근거: `src/component-recipes.ts`(`stackRecipe.gaps` = `spacing`, `buttonRecipe.states.selected`), `src/foundations.ts`(`control`·`layout`)
+
+## 흐름과 상태
+
+1. 화면은 묶음 설명과 기본 범위(대표)를 보여 준다.
+2. 사용자가 범위 버튼을 누르면 `selected`가 옮겨 가고, 요약과 적용 버튼 라벨의 개수가 바뀐다. 이전 결과 문구는 지운다.
+3. 적용을 누르면 그 범위의 항목 ID로 제품 작업(공유 대상 확정 등)을 실행한다. 끝날 때까지 적용 버튼은 `loading`이다.
+4. 결과 문구로 몇 개에 적용했는지 알린다. 실패하면 범위는 그대로 두고 실패 문구를 알린다. 적용을 다시 누르면 같은 범위로 재요청한다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 기본 범위 버튼 `selected`, 요약에 개수, 안내 문구 `share.chooseScope` | `selected`는 Web `aria-pressed`·Native 접근성 state로 알림 |
+| 범위 변경 | 요약·적용 라벨의 개수 갱신, 결과 문구는 안내로 돌아감 | 같음 |
+| 진행 중 | 적용 버튼 `loading`(누름 막힘·스피너), 범위 버튼 `disabled` | 포커스는 적용 버튼 유지 |
+| 성공 | 결과 문구 `t("share.applied", { count })` | 결과 알림, 포커스는 적용 버튼 유지 |
+| 실패 | 네트워크·서버 실패: 범위 유지, 결과 문구 `share.applyFailed`, 적용 버튼 다시 활성. 재요청도 실패하면 같은 문구를 다시 알린다 | 결과 알림(Web `role="status"`, Native live region + iOS 알림) |
+
+- 상태→문구 키는 상수 표로 둔다(아래 `resultKey`·`scopeKey`). 템플릿 문자열 키는 키 추출·누락 검사가 찾지 못한다.
+- 선택 범위는 제품의 안정적인 항목 ID와 권한으로 확정한다. 재시도 세대·늦은 응답 처리까지 필요하면 [저장과 재시도](action-recovery-save.md)의 세션을 합친다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { useState } from "react";
+import { Button } from "@hjmds/react/actions";
+import { Heading } from "@hjmds/react/heading";
+import { Container, Stack, Text } from "@hjmds/react/layout";
+
+const scopeKey = { cover: "share.scope.cover", group: "share.scope.group" } as const;
+const resultKey = { idle: "share.chooseScope", applied: "share.applied", failed: "share.applyFailed" } as const;
+
+const [scope, setScope] = useState<"cover" | "group">("cover");
+const [result, setResult] = useState<"idle" | "applying" | "applied" | "failed">("idle");
+const count = scope === "cover" ? 1 : group.items.length;
+const choose = (next: "cover" | "group") => { setScope(next); setResult("idle"); };
+const apply = async () => {
+  setResult("applying");
+  try { await onApply(scope); setResult("applied"); } catch { setResult("failed"); }
+};
+
+<Container size="reading">
+  <Stack gap="md">
+    <Heading level="level3" semanticLevel={2}>{t("share.scopeQuestion")}</Heading>
+    <Text as="p">{t("share.groupSummary", { total: group.items.length })}</Text>
+    <Stack gap="sm">
+      <Button tone="secondary" selected={scope === "cover"} disabled={result === "applying"} onClick={() => choose("cover")}>
+        {t("share.coverOnly", { count: 1 })}
+      </Button>
+      <Button tone="secondary" selected={scope === "group"} disabled={result === "applying"} onClick={() => choose("group")}>
+        {t("share.wholeGroup", { count: group.items.length })}
+      </Button>
+    </Stack>
+    <Text as="p">{t("share.scopeSummary", { scope: t(scopeKey[scope]), count })}</Text>
+    <Button loading={result === "applying"} onClick={() => void apply()}>{t("share.apply", { count })}</Button>
+    <Text as="p" role="status">{t(resultKey[result === "applying" ? "idle" : result], { count })}</Text>
+  </Stack>
+</Container>
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { Button } from "@hjmds/react-native/actions";
+import { Heading } from "@hjmds/react-native/heading";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+const { spacing } = useHjmNativeTheme().tokens;
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+// scope·result·count·choose·apply·scopeKey·resultKey는 Web과 같다.
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.md }}>
+  <Container size="reading" gutter={gutter}>
+    <Stack gap="md">
+      <Heading level="level3" semanticLevel={2}>{t("share.scopeQuestion")}</Heading>
+      <Text>{t("share.groupSummary", { total: group.items.length })}</Text>
+      <Stack gap="sm">
+        <Button tone="secondary" selected={scope === "cover"} disabled={result === "applying"} onPress={() => choose("cover")}>
+          {t("share.coverOnly", { count: 1 })}
+        </Button>
+        <Button tone="secondary" selected={scope === "group"} disabled={result === "applying"} onPress={() => choose("group")}>
+          {t("share.wholeGroup", { count: group.items.length })}
+        </Button>
+      </Stack>
+      <Text>{t("share.scopeSummary", { scope: t(scopeKey[scope]), count })}</Text>
+      <Button loading={result === "applying"} onPress={() => void apply()}>{t("share.apply", { count })}</Button>
+      <StatusText>{t(resultKey[result === "applying" ? "idle" : result], { count })}</StatusText>
+    </Stack>
+  </Container>
+</ScrollView>
+```
+
+`group`·`onApply`는 제품 소유다. `StatusText`는 [저장과 재시도의 공통 절](action-recovery-save.md#공통-세션과-상태-알림)의 helper(Android live region + iOS 알림)다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 바깥 틀 | 문서 스크롤 + `Container` | `ScrollView`(위아래 `spacing.md`) + `Container` |
+| 이벤트 | `onClick` | `onPress` |
+| `selected` 알림 | `aria-pressed` | 접근성 state |
+| 상태 알림 | `role="status"` | live region(Android) + iOS 알림 호출(`StatusText`) |
+
+## 함정
+
+- 구획 제목은 Heading으로 표시한다. 이전 Text heading 예제는 2026-10-06 제목 의미 구조를 맞추면서 수정했다.
+- 스토리의 "다음 적용 실패시키기"(ghost)와 350ms 지연은 실패·진행 중을 확인하는 데모 전용이다. 제품에 넣지 않는다.

package/docs/usage/compositions/stea-event-ticket.md

@@ -0,0 +1,166 @@
+# 일정과 식별 정보 티켓
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [QRCode](../../qr-code.md), `packages/react/src/qr-code.tsx`, `packages/react-native/src/qr-code.tsx`, `showcase/web/src/patterns/stea-expression-previews.tsx`(`EventTicket`), `showcase/native/src/stea-expression-previews.tsx`, `showcase/shared/stea-expressions.ts`(`ticketCopy`), `src/qr-code-recipe.ts`, `src/card.ts`
+- 스토리북: `배포/구성/정보 표시/일정과 식별 정보 티켓`
+
+## 언제 쓰나
+
+공연·예약 입장권처럼 일시·장소·좌석 정보와 함께, 현장에서 보여 줄 QR 코드와 사람이 읽을 예매 번호를 한 카드에 담을 때 쓴다.
+행동 버튼이 없는 표시용 카드다. 티켓 목록이면 이 카드를 반복하지 말고 [ListRow](../components/list-row.md)로 요약한 뒤 상세에서 이 구성을 연다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Card` | 제목(공연명)·설명("입장할 때 아래 코드를 보여 주세요") | [Card](../components/card.md) |
+| `DescriptionList` | 날짜·시간·장소·좌석 | [DescriptionList](../components/description-list.md) |
+| `QRCode` | 예매 번호를 담은 QR. `label`(필수 접근성 이름), `fallback`(필수, QR 바로 아래 항상 그려지는 대체 안내) | [QRCode](../components/qr-code.md) |
+| `Text` label muted + `Text` title strong | "예매 번호" 라벨과 번호 | [Text](../components/text.md) |
+| `Skeleton`·`Result` | 티켓을 불러오는 중·불러오기 실패(화면 상태) | [Skeleton](../components/skeleton.md), [Result](../components/result.md) |
+| `Container` | 바깥 틀의 최대 폭·좌우 여백 | [Container](../components/container.md) |
+
+## 배치
+
+```text
+┌ 바깥 틀: 스크롤(Web 문서, Native ScrollView 위아래 spacing.md 16) ┐
+│ ← Container gutter 16(폭 600 미만)/20 · 최대 720 →                │
+│ ┌ Card ────────────────────────────────────┐  body padding spacing.md 16
+│ │ 가을 밤 재즈 공연              (title)   │
+│ │ 입장할 때 아래 코드를 보여 주세요 (muted)│
+│ │ 날짜   2026년 10월 17일 토요일           │  ← DescriptionList
+│ │ 시간   저녁 7시 30분 (입장 7시부터)      │
+│ │ 장소   서울 마포구 …                     │
+│ │ 좌석   A열 12번                          │
+│ │            ↕ spacing.lg 20               │
+│ │ ┌──────────┐                             │
+│ │ │ ▓▓ QR ▓▓ │  ← size 192(기본)            │
+│ │ └──────────┘                             │
+│ │ 대체 안내 (fallback, 항상 QR 바로 아래)  │
+│ │            ↕ spacing.sm 12               │
+│ │ 예매 번호                (label muted)   │
+│ │            ↕ spacing.sm 12               │
+│ │ JZ-1017-A12-4821         (title strong)  │
+│ └──────────────────────────────────────────┘
+│ ░ 하단 안전 영역(Native 화면 host 소유) ░                          │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: `Container size="reading"`. Native: `ScrollView` → `Container` | 화면 본문, 카드는 스크롤과 함께 움직인다. 안전 영역은 화면 host(SafeArea·navigation header)가 준다. 입력이 없어 키보드 처리는 없다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우는 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 최대 폭 `layout.readingMaxWidth` 720 |
+| 틀 | `Card` | 바깥 틀 안 | body padding `spacing.md` 16(`cardRecipe`) |
+| 정보 | `DescriptionList` | Card 머리 아래 | 정보–식별 묶음 `Stack gap="lg"` 20 |
+| 식별 묶음 | `QRCode`(+fallback) → 라벨 → 번호 | 정보 아래, 시작 정렬 | 묶음 안 `Stack gap="sm"` 12, QR `size` 기본 192(모듈 수의 정수배로 내림), quiet zone 4모듈. QR–fallback 사이 간격은 컴포넌트가 주지 않는다 |
+| 로딩·실패 | `Skeleton`·`Result` | 카드 자리 | Skeleton `block` 기본 높이 `spacing.xxl` 32. Result는 자체 여백(`resultRecipe`) |
+
+- QR은 번호 **위**에 두고, 번호는 QR이 읽히지 않을 때 직원이 입력할 수 있도록 항상 같이 보인다.
+- QR 색은 `qrCodeRecipe` 고정값(전경 `#000000`, 배경 `#ffffff`)이다. 다크 테마에서도 흰 바탕으로 그려진다.
+- 행동 버튼이 없는 카드다. 실패 화면의 다시 시도 하나만 primary 행동이다.
+
+## 흐름과 상태
+
+1. 사용자가 티켓 화면을 연다. 제품이 티켓을 불러오는 동안 카드 자리에 Skeleton을 둔다.
+2. 불러오면 정보·QR·번호를 그린다. 상호작용은 없다.
+3. 현장에서 QR을 보여 준다. 스캔이 안 되면 예매 번호를 읽어 준다(Native는 번호를 길게 눌러 선택·복사할 수 있다).
+4. 불러오기가 실패하면(네트워크·서버) 카드 대신 `Result status="failure"`와 다시 시도를 둔다. 다시 시도하면 1로 돌아간다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 정보 + QR + 번호 | QR은 `label`("입장 QR 코드, 예매 번호 …")로 읽힌다 |
+| 진행 중 | 티켓을 불러오는 중(처음·다시 시도): 카드 자리에 `Skeleton`. 값이 없으면 `QRCode`를 그리지 않는다(빈 `value`는 `TypeError`) | Native Skeleton `accessibilityLabel`(`ticket.loading`) |
+| 실패 | 네트워크·서버 실패: `Result status="failure"` + 다시 시도(primary 하나). 다시 시도도 실패하면 같은 Result를 다시 보이고 문구로 실패를 알린다 | Result 제목이 읽힌다. 다시 시도 뒤 포커스는 Result 행동에 둔다 |
+| 스캔 실패(현장) | QR 아래 fallback 안내와 예매 번호로 대신한다 | fallback·번호가 텍스트로 읽힌다 |
+| 다크 테마 | Card·글자는 테마를 따르고 QR은 흰 바탕 유지 | — |
+| 큰 글자 | DescriptionList 값이 줄바꿈되고 번호가 길게 이어짐 | — |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Card, DescriptionList } from "@hjmds/react/display";
+import { Result, Skeleton } from "@hjmds/react/feedback";
+import { Container, Stack, Text } from "@hjmds/react/layout";
+import { QRCode } from "@hjmds/react/qr-code";
+
+<Container size="reading">
+  {ticketState.status === "loading" ? <Skeleton shape="block" height={320} /> :
+   ticketState.status === "failed" ? (
+    <Result status="failure" title={t("ticket.loadFailed.title")} description={t("ticket.loadFailed.body")}
+      actions={[{ label: t("ticket.retry"), onAction: reload }]} />
+  ) : (
+    <Card title={ticketState.ticket.title} description={t("ticket.showAtEntry")}>
+      <Stack gap="lg">
+        <DescriptionList aria-label={t("ticket.details")} items={ticketState.ticket.details} />
+        <Stack gap="sm">
+          {/* QRCode의 svg가 inline이라 fallback을 블록으로 감싸 아래 줄에 둔다. */}
+          <QRCode value={ticketState.ticket.booking} label={t("ticket.qrLabel", { booking: ticketState.ticket.booking })}
+            fallback={<Stack gap="xs"><Text tone="muted">{t("ticket.qrFallback")}</Text></Stack>} />
+          <Text variant="label" tone="muted">{t("ticket.bookingLabel")}</Text>
+          <Text variant="title" emphasis="strong">{ticketState.ticket.booking}</Text>
+        </Stack>
+      </Stack>
+    </Card>
+  )}
+</Container>
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { Card, DescriptionList } from "@hjmds/react-native/data-display";
+import { Result, Skeleton } from "@hjmds/react-native/feedback";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { QRCode } from "@hjmds/react-native/qr-code";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+const { spacing } = useHjmNativeTheme().tokens;
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.md }}>
+  <Container size="reading" gutter={gutter}>
+    {ticketState.status === "loading" ? <Skeleton shape="block" height={320} accessibilityLabel={t("ticket.loading")} /> :
+     ticketState.status === "failed" ? (
+      <Result status="failure" title={t("ticket.loadFailed.title")} description={t("ticket.loadFailed.body")}
+        actions={[{ label: t("ticket.retry"), onAction: reload }]} />
+    ) : (
+      <Card title={ticketState.ticket.title} description={t("ticket.showAtEntry")}>
+        <Stack gap="lg">
+          <DescriptionList label={t("ticket.details")} descriptor={{ items: ticketState.ticket.details }} />
+          <Stack gap="sm">
+            <QRCode value={ticketState.ticket.booking} label={t("ticket.qrLabel", { booking: ticketState.ticket.booking })}
+              fallback={<Text tone="muted">{t("ticket.qrFallback")}</Text>} />
+            <Text variant="label" tone="muted">{t("ticket.bookingLabel")}</Text>
+            <Text selectable variant="title" emphasis="strong">{ticketState.ticket.booking}</Text>
+          </Stack>
+        </Stack>
+      </Card>
+    )}
+  </Container>
+</ScrollView>
+```
+
+`ticketState`(`{ status: "loading" } | { status: "failed" } | { status: "ready"; ticket }`)·`reload`와 공연명·일시·장소·좌석·예매 번호는 제품 소유다. Skeleton 높이 320은 예시다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 바깥 틀 | 문서 스크롤 + `Container` | `ScrollView`(위아래 `spacing.md`) + `Container` |
+| `DescriptionList` 이름·항목 | `aria-label` + `items` | `label` + `descriptor={{ items }}` |
+| fallback 감싸기 | inline svg 옆으로 흐르지 않게 `Stack`으로 감싼다 | `Text` 그대로 |
+| 번호 선택 | 브라우저 기본 텍스트 선택 | `Text selectable` |
+| QR 배치 prop | 배치 전용 `layoutStyle`만 | 없음(감싸는 레이아웃에서 정한다) |
+| QR peer | `qrcode-generator` 2.0.4 | `qrcode-generator` 2.0.4 + `react-native-svg` 15.15.5(dev client 재빌드) |
+
+## 함정
+
+- `QRCode`는 root에서 내보내지 않는다. `/qr-code` subpath로만 import하고 optional peer를 설치한다. Native에서 peer가 없으면 기기 번들에서 실패한다.
+- `label`이 비거나 `fallback`이 없거나 `size`가 모듈당 2px(`qrCodeRecipe.minModuleSize`)보다 작으면 `TypeError`다. `value`가 비어도 `TypeError`라 불러오는 중에는 QR을 그리지 않는다.
+- `QRCode`에는 `style`·`className`이 없다. 크기는 `size`, 위치는 감싸는 레이아웃에서 정한다. Web만 배치 전용 `layoutStyle`을 받는다(`packages/react/src/qr-code.tsx`).
+- 현재 스토리는 기본·다크·큰 글자만 있고 불러오는 중·불러오기 실패 상태가 없다.

package/docs/usage/compositions/stea-flip-card.md

@@ -0,0 +1,162 @@
+# 앞면과 상세 정보 전환
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `showcase/web/src/patterns/stea-expression-previews.tsx`(`FlipInfoCard`), `showcase/native/src/stea-expression-previews.tsx`, `showcase/shared/stea-expressions.ts`(`flipCopy`), `src/content-transition.ts`, `src/card.ts`
+- 스토리북: `배포/구성/정보 표시/앞면과 상세 정보 전환`
+
+## 언제 쓰나
+
+모임·상품처럼 한 카드에 요약(앞면)과 상세 항목(뒷면)이 있고, 사용자가 버튼 하나로 두 면을 오가게 할 때 쓴다.
+3D 뒤집기 대신 같은 자리에서 `ContentTransition` `scale`로 내용을 바꾼다. 상세가 길거나 여러 묶음이면
+[Collapsible](../components/collapsible.md)·[Accordion](../components/accordion.md)으로 펼치거나 상세 화면으로 이동한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Card` | 제목("이번 주 모임")만 가진 틀 | [Card](../components/card.md) |
+| `ContentTransition` `preset="scale"` | 앞면 ↔ 뒷면 전환, `stateKey`="front"/"back" | [ContentTransition](../components/content-transition.md) |
+| 앞면 `Stack gap="xs"` + `Text` 3줄 | 이름(title strong), 요약, 메모(muted) | [Text](../components/text.md) |
+| 뒷면 `DescriptionList` | 장소·준비물·인원·진행 항목 | [DescriptionList](../components/description-list.md) |
+| `Button` `tone="secondary"` | "자세히 보기" ↔ "앞면 보기" 토글 | [Button](../components/button.md) |
+| 면 알림 | Web `VisuallyHidden role="status"`, Native `announceForAccessibility` | [VisuallyHidden](../components/visually-hidden.md) |
+| `Container` | 바깥 틀의 최대 폭·좌우 여백 | [Container](../components/container.md) |
+
+## 배치
+
+```text
+바깥 틀: 스크롤(Web 문서, Native ScrollView 위아래 spacing.md 16) + Container gutter 16/20 · 최대 720
+
+앞면                                      뒷면
+┌ Card ─────────────────────────────┐     ┌ Card ─────────────────────────────┐
+│ 이번 주 모임          (title)     │     │ 이번 주 모임                      │
+│ ┌ 면 영역 ──────────────────────┐ │     │ ┌ 면 영역 ──────────────────────┐ │
+│ │ 성수 북클럽   (title strong)  │ │     │ │ 장소    성수동 …              │ │
+│ │ 10월 9일 목요일 저녁 7시      │ │     │ │ 준비물  읽은 부분까지 …       │ │
+│ │ 이번 달 책은 … (muted)        │ │     │ │ 인원    8명 중 6명 …          │ │
+│ └───────────────────────────────┘ │     │ │ 진행    …                     │ │
+│          ↕ spacing.md 16          │     │ └───────────────────────────────┘ │
+│ [        자세히 보기         ]    │     │ [         앞면 보기          ]    │ ← secondary, 같은 자리
+└───────────────────────────────────┘     └───────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: `Container size="reading"`. Native: `ScrollView` → `Container` | 화면 본문, 카드는 스크롤과 함께 움직인다. 안전 영역은 화면 host(SafeArea·navigation header)가 준다. 입력이 없어 키보드 처리는 없다 | Native `ScrollView` 위아래 `spacing.md` 16, 좌우는 `Container` `gutter`(폭 600 미만 `compact` 16, 이상 `regular` 20). 최대 폭 `layout.readingMaxWidth` 720 |
+| 틀 | `Card` | 바깥 틀 안 | body padding `spacing.md` 16(`cardRecipe`) |
+| 면 | `ContentTransition` 안 앞면 Stack 또는 DescriptionList | Card 제목 아래 | 앞면 줄 사이 `spacing.xs` 8, 면 높이는 내용에 따름 |
+| 전환 버튼 | `Button` secondary | 면 아래, 전환되는 면 **밖**, 꽉 찬 폭(Stack 기본 stretch) | 높이 `control.buttonHeight.medium` 44, 면과 `spacing.md` 16 |
+
+- 버튼은 두 면 모두에서 같은 자리(면 아래, 면 밖)에 둔다. 면 안에 두면 면이 바뀔 때 포커스한 버튼이 사라진다.
+- 두 면의 높이가 다르면 버튼이 위아래로 움직인다. 면 높이를 고정하려면 제품 레이아웃에서 최소 높이를 준다(스토리는 고정하지 않는다).
+- 전환 버튼은 보기 전환이라 primary가 아니라 secondary다([Button](../components/button.md)).
+
+## 흐름과 상태
+
+1. 앞면(요약)으로 열린다.
+2. "자세히 보기"를 누르면 면이 `scale`(0.96 → 1, 투명도 0 → 1)로 뒷면 DescriptionList로 바뀌고 버튼 라벨이 "앞면 보기"가 된다.
+3. 다시 누르면 앞면으로 돌아온다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 앞면: 이름·요약·메모 | — |
+| 뒷면 | DescriptionList(이름 "모임 상세 정보") | 포커스는 버튼에 남는다. 바뀐 면을 Web 숨긴 status, Native announce로 알린다 |
+| 진행 중 | — (면 전환은 이미 받은 데이터로 즉시 바뀐다. 카드 데이터를 불러오는 중이면 화면이 카드 자리에 [Skeleton](../components/skeleton.md)을 둔다) | — |
+| 실패 | — (전환 자체는 실패하지 않는다. 카드 데이터 불러오기 실패는 화면이 카드 자리에 [Notice](../components/notice.md) + 다시 시도를 둔다) | — |
+| 모션 감소 | 전환 없이 즉시 바뀐다(`ContentTransition`이 처리) | 같음 |
+
+면→문구 키는 상수 표로 둔다(아래 `faceKey`). 템플릿 문자열 키는 키 추출·누락 검사가 찾지 못한다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { ContentTransition } from "@hjmds/react/content-transition";
+import { Card, DescriptionList } from "@hjmds/react/display";
+import { Container, Stack, Text, VisuallyHidden } from "@hjmds/react/layout";
+
+const faceKey = {
+  front: { status: "meetup.showingFront", toggle: "meetup.showBack" },
+  back: { status: "meetup.showingBack", toggle: "meetup.showFront" },
+} as const;
+
+<Container size="reading">
+  <Card title={t("meetup.title")}>
+    <Stack gap="md">
+      <ContentTransition stateKey={face} preset="scale">
+        {face === "back"
+          ? <DescriptionList aria-label={t("meetup.details")} items={details} />
+          : <Stack gap="xs">
+              <Text variant="title" emphasis="strong">{meetup.name}</Text>
+              <Text>{meetup.when}</Text>
+              <Text tone="muted">{meetup.note}</Text>
+            </Stack>}
+      </ContentTransition>
+      <VisuallyHidden role="status">{t(faceKey[face].status)}</VisuallyHidden>
+      <Button tone="secondary" onClick={() => setFace(face === "back" ? "front" : "back")}>
+        {t(faceKey[face].toggle)}
+      </Button>
+    </Stack>
+  </Card>
+</Container>
+```
+
+```tsx
+// Native
+import { AccessibilityInfo, ScrollView, useWindowDimensions } from "react-native";
+import { Button } from "@hjmds/react-native/actions";
+import { ContentTransition } from "@hjmds/react-native/content-transition";
+import { Card, DescriptionList } from "@hjmds/react-native/data-display";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+
+const { spacing } = useHjmNativeTheme().tokens;
+const gutter = resolveWindowClass(useWindowDimensions().width) === "compact" ? "compact" : "regular";
+const toggle = () => {
+  const next = face === "back" ? "front" : "back";
+  setFace(next);
+  // iOS는 accessibilityLiveRegion을 무시하므로 바뀐 면을 직접 알린다.
+  AccessibilityInfo.announceForAccessibility(t(faceKey[next].status));
+};
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.md }}>
+  <Container size="reading" gutter={gutter}>
+    <Card title={t("meetup.title")}>
+      <Stack gap="md">
+        <ContentTransition stateKey={face} preset="scale">
+          {face === "back"
+            ? <DescriptionList label={t("meetup.details")} descriptor={{ items: details }} />
+            : <Stack gap="xs">
+                <Text variant="title" emphasis="strong">{meetup.name}</Text>
+                <Text>{meetup.when}</Text>
+                <Text tone="muted">{meetup.note}</Text>
+              </Stack>}
+        </ContentTransition>
+        <Button tone="secondary" onPress={toggle}>{t(faceKey[face].toggle)}</Button>
+      </Stack>
+    </Card>
+  </Container>
+</ScrollView>
+```
+
+`face`(`"front" | "back"`)·`setFace`와 모임 이름·일시·책·상세 항목은 제품 소유다. Native의 `faceKey`는 Web과 같은 상수 표다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 바깥 틀 | 문서 스크롤 + `Container` | `ScrollView`(위아래 `spacing.md`) + `Container` |
+| `DescriptionList` 이름·항목 | `aria-label` + `items` | `label` + `descriptor={{ items }}` |
+| 면 변경 알림 | `VisuallyHidden role="status"` | `AccessibilityInfo.announceForAccessibility`(iOS는 live region을 무시한다) |
+
+## 함정
+
+- 3D 회전으로 뒤집지 않고 `ContentTransition`으로 면을 바꾼다. 모션 감소 처리를 ContentTransition이 맡고, 한 번에 한 면만 마운트된다.
+- 현재 스토리는 Web 면 알림을 `<span className="hjm-visually-hidden" role="status">`로 직접 그린다. 규칙은 공개 컴포넌트 [VisuallyHidden](../components/visually-hidden.md)이다.
+- 현재 스토리는 면 문구를 `faceStatus(back)` 함수로 만든다. 제품은 i18n 키 상수 표(`faceKey`)로 둔다.