@hjmds/design-contracts 1.12.1 → 1.13.0

package/docs/usage/compositions/stea-order-progress.md

@@ -0,0 +1,184 @@
+# 처리 단계와 재시도
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Steps](../../steps.md), [Timeline](../../timeline.md), `showcase/web/src/patterns/stea-composition-previews.tsx`(`OrderProgressRetry`), `showcase/native/src/stea-composition-previews.tsx`(`OrderProgressRetry`, `Frame`), `showcase/shared/stea-compositions.ts`(`orderReducer`, `orderStepsDescriptor`), `src/steps.ts`, `src/container.ts`
+- 스토리북: `배포/구성/피드백과 복구/처리 단계와 재시도`
+
+## 언제 쓰나
+
+주문·신청처럼 서버가 단계를 하나씩 확정하는 처리 과정을 보여 주고, 확정에 실패하면 같은 단계를 다시 요청하게 할 때 쓴다.
+다음 단계는 서버가 확정한 뒤에만 완료로 바뀌고, 실패는 거절된 단계에 오류 표시만 남긴다. 사용자가 직접 입력하며
+앞뒤로 오가는 마법사는 [Steps](../components/steps.md) 단독이나 `StepPlayer`를 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Card` | 제목("주문 처리 단계")·설명 틀 | [Card](../components/card.md) |
+| `Steps` | 가로 단계 표시. `currentStepStatus`: `current` · `error` · `complete` | [Steps](../components/steps.md) |
+| 진행 문구 `Text` | "서버 확인을 기다리는 중이에요." / "모든 단계가 확정됐어요." | [Text](../components/text.md) |
+| `Notice` `tone="danger"` | 실패 안내(상태는 그대로이니 다시 요청) | [Notice](../components/notice.md) |
+| `Button` primary | 다음 단계 요청 / 다시 요청. 요청 중 `loading` | [Button](../components/button.md) |
+| `Button` secondary | 전체 완료 후 "처음부터 다시" | [Button](../components/button.md) |
+| `Text` label muted + `Timeline` | "처리 기록" 제목과 확정·실패 사건 목록 | [Timeline](../components/timeline.md) |
+| `Switch` | 스토리 전용 "다음 요청을 실패로 응답". 제품에 넣지 않는다 | [Switch](../components/switch.md) |
+| `ScrollView` + `Container`(Native) | 바깥 틀. 세로 스크롤·위아래 여백, 좌우 gutter | [Container](../components/container.md), [화면 여백과 너비](../tokens/layout.md) |
+
+## 배치
+
+```text
+Native 화면(ScrollView, 위아래 spacing.lg 20) > Container gutter 16(폭 < 600) · 20(폭 ≥ 600)
+┌ Card ────────────────────────────────────────┐  body padding spacing.md 16
+│ 주문 처리 단계                    (title)    │
+│ 다음 단계는 서버가 확정한 뒤에만…  (muted)   │
+│ (✓)──(2)──(3)──(4)──(5)          ← Steps     │
+│ 접수 결제확인 상품준비 발송 도착              │
+│               ↕ spacing.lg 20                │
+│ 서버 확인을 기다리는 중이에요.  ← 진행 문구  │
+│               ↕ spacing.lg 20                │
+│ ┌ ! 서버가 이 단계를 확정하지 못했어요… ┐    │  ← 실패 때만 Notice danger
+│ └───────────────────────────────────────┘    │
+│               ↕ spacing.lg 20                │
+│ [           다시 요청               ]        │  ← 주 행동(primary)
+│               ↕ spacing.lg 20                │
+│ 처리 기록                     (label muted)  │
+│               ↕ spacing.lg 20                │
+│ ● 접수 · 주문을 받았어요.        ← Timeline  │
+│ ● 결제 확인 실패 · 단계는 바뀌지 않았어요.   │
+└──────────────────────────────────────────────┘
+  고정 영역 없음. 기록이 길어지면 화면 스크롤로 내려간다. 안전 영역은 화면 골격이 맡는다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: 제품 화면 레이아웃(문서 스크롤). Native: `ScrollView` > `Container` | 이 구성은 바깥 폭·여백을 정하지 않는다(스토리는 Card만 그린다). Native는 Card를 `ScrollView` 안 [Container](../components/container.md)에 둔다. 입력이 없어 키보드 처리는 없다. 안전 영역은 화면 골격(내비게이션 헤더·탭 바)이 맡는다 | Native ScrollView 위아래 `spacing.lg` 20, Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20(`layout.pagePadding`) |
+| 틀 | `Card` | 바깥 틀 안, 스크롤과 함께 | body padding `spacing.md` 16, 안쪽 `Stack gap="lg"` 20 |
+| 단계 | `Steps` | Card 머리 아래 맨 위 | 단계 사이 `stepsRecipe.gap` `spacing.xs` 8, 표시 원 `glyph.md` |
+| 진행 | 진행 문구 | 단계 아래 | `spacing.lg` 20 |
+| 실패 | `Notice` danger | 진행 문구 아래, 실패 때만 | `spacing.lg` 20 |
+| 행동 | `Button` primary(또는 완료 후 secondary) | Notice 아래, 꽉 찬 폭(`Stack` 기본 `align="stretch"`가 채우므로 Web `layoutStyle`·Native `fullWidth`를 따로 주지 않는다) | 높이 44, 행동 묶음 안 `Stack gap="sm"` 12 |
+| 기록 | label + `Timeline` | 맨 아래, 스크롤 | `spacing.lg` 20, 기록은 아래로 쌓인다 |
+
+- 실패 Notice는 버튼 **위**에 둔다. 사용자가 이유를 읽은 다음 "다시 요청"에 닿는다.
+- 기록이 길어지면 Card 밖 화면 스크롤로 내려간다. 단계·행동은 위에 남는다(고정은 아님).
+
+## 흐름과 상태
+
+1. 첫 단계("접수")가 확정된 채 열리고 커서는 다음 단계("결제 확인")에 있다.
+2. "다음 단계 요청"을 누르면 요청 중이 된다(버튼 `loading`, 진행 문구).
+3. 서버가 확정하면 커서가 다음 단계로 가고 기록에 success 항목이 붙는다.
+4. 서버가 거절하면 커서는 그대로, 그 단계에 `error` 표시, danger Notice, 기록에 attention 항목. 버튼 라벨이 "다시 요청"이 된다.
+5. 네트워크·서버 오류로 판정을 받지 못하면 단계 표시는 그대로 두고 Notice로 알린 뒤 "다시 요청"을 받는다.
+6. 마지막 단계까지 확정되면 `currentStepStatus="complete"`로 전체 완료를 표시하고 버튼이 secondary "처음부터 다시"로 바뀐다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | Steps `current`, 버튼 "다음 단계 요청" | — |
+| 진행 중 | 버튼 `loading`, 진행 문구 | 진행 문구가 Web `role="status"`, Native live region으로 읽힌다. 포커스는 버튼 유지 |
+| 실패 | 서버 거절: 거절된 단계 `error`(라벨 "확인 필요"), Notice danger, 버튼 "다시 요청", 기록에 attention 항목 | Notice가 알린다(Web `danger`는 `role="alert"`, Native는 `announcement="assertive"`를 줘야 발표된다) |
+| 요청 실패(네트워크·서버 오류) | 커서·단계 표시는 그대로(`current`), Notice danger에 연결 실패 문구, 버튼 "다시 요청". 서버가 판정하지 않았으므로 기록에 사건을 남기지 않는다 | 실패와 같다 |
+| 완료 | 모든 단계 complete, 진행 문구 "모든 단계가 확정됐어요.", secondary 버튼 | 진행 문구가 읽힌다 |
+
+- 요청 중 중복 요청은 상태 로직에서 무시한다. 버튼 `loading`만으로는 키보드 반복 입력을 막지 못한다.
+- 문구 키는 상태별 상수로 둔다. 상태 이름으로 키를 조립하지 않는다.
+
+| 상태 | 진행 문구 키 | Notice 키 | 버튼 키 |
+| --- | --- | --- | --- |
+| 기본 | — | — | `order.request` |
+| 진행 중 | `order.requesting` | — | `order.request`(`loading`) |
+| 실패(거절) | — | `order.failed` | `order.retry` |
+| 요청 실패 | — | `order.requestFailed` | `order.retry` |
+| 완료 | `order.done` | — | `order.restart` |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { Card, Timeline } from "@hjmds/react/display";
+import { Notice } from "@hjmds/react/feedback";
+import { Stack, Text } from "@hjmds/react/layout";
+import { Steps } from "@hjmds/react/steps";
+
+// 상태 → 문구 키
+const noticeKey = { rejected: "order.failed", requestFailed: "order.requestFailed" } as const;
+const progressKey = { requesting: "order.requesting", done: "order.done" } as const;
+
+<Card title={t("order.title")} description={t("order.description")}>
+  <Stack gap="lg">
+    <Steps descriptor={{ steps, currentStepId, currentStepStatus }} statusLabels={statusLabels}
+      composeAccessibleName={({ position, total, label }) => t("order.stepName", { position, total, label })} />
+    {/* 알림 자리를 위해 status 영역은 늘 마운트한다 */}
+    <Text role="status">{requesting ? t(progressKey.requesting) : done ? t(progressKey.done) : ""}</Text>
+    {failure ? <Notice tone="danger" title={t(noticeKey[failure])} /> : null}
+    <Stack gap="sm">
+      {done
+        ? <Button tone="secondary" onClick={restart}>{t("order.restart")}</Button>
+        : <Button loading={requesting} onClick={request}>{failure ? t("order.retry") : t("order.request")}</Button>}
+    </Stack>
+    <Text variant="label" tone="muted">{t("order.log")}</Text>
+    <Timeline items={log} composeAccessibleName={({ position, total, label }) => t("order.logName", { position, total, label })} />
+  </Stack>
+</Card>;
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Button } from "@hjmds/react-native/actions";
+import { Card, Timeline } from "@hjmds/react-native/data-display";
+import { Notice } from "@hjmds/react-native/feedback";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+import { Steps } from "@hjmds/react-native/steps";
+
+const noticeKey = { rejected: "order.failed", requestFailed: "order.requestFailed" } as const;
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container gutter={gutter}>
+    <Card title={t("order.title")} description={t("order.description")}>
+      <Stack gap="lg">
+        <Steps descriptor={{ steps, currentStepId, currentStepStatus }} statusLabels={statusLabels}
+          composeAccessibleName={({ position, total, label }) => t("order.stepName", { position, total, label })} />
+        {/* 빈 Text가 gap 하나만큼 틈을 남기므로 문구가 있을 때만 그린다. */}
+        {requesting || done ? <Text accessibilityLiveRegion="polite">{done ? t("order.done") : t("order.requesting")}</Text> : null}
+        {failure ? <Notice tone="danger" announcement="assertive" title={t(noticeKey[failure])} /> : null}
+        <Stack gap="sm">
+          {done
+            ? <Button tone="secondary" onPress={restart}>{t("order.restart")}</Button>
+            : <Button loading={requesting} onPress={request}>{failure ? t("order.retry") : t("order.request")}</Button>}
+        </Stack>
+        <Text variant="label" tone="muted">{t("order.log")}</Text>
+        <Timeline items={log} composeAccessibleName={({ position, total, label }) => t("order.logName", { position, total, label })} />
+      </Stack>
+    </Card>
+  </Container>
+</ScrollView>;
+```
+
+단계 이름·문구, 실패 스위치, 900ms 지연은 예시다. 단계 정의와 확정·거절 판단은 서버와 제품 소유다.
+상태 전이는 스토리의 `orderReducer`·`orderStepsDescriptor`를 참고한다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 진행 문구 자리 | 빈 `role="status"`를 항상 마운트(알림 자리 유지) | 문구가 있을 때만 마운트(iOS는 live region을 무시하고 빈 Text가 틈을 남김, 2026-10-02 시뮬레이터 확인) |
+| 이벤트 | `onClick` | `onPress` |
+| 바깥 틀 | 제품 화면 레이아웃(문서 스크롤) | `ScrollView` > `Container` |
+| 실패 Notice 발표 | `danger`는 늘 `role="alert"` | `announcement="assertive"`를 지정해야 발표(기본 `none`) |
+
+## 함정
+
+- 실패할 때 커서를 옮기거나 완료 표시를 먼저 그리지 않는다. 서버가 거절한 단계를 사용자가 끝난 것으로 오해한다.
+- `Timeline` 이름은 단계 이름과 다르게 짓는다("기록 N개 중 M번째"). "5단계 중"으로 읽히면 단계 수와 섞인다.
+- Steps는 세로 방향·클릭 이동을 지원하지 않는다(`src/steps.ts`). 단계 사이를 눌러 이동하는 UI를 기대하지 않는다.
+- 현재 스토리에는 네트워크·서버 오류로 요청 자체가 실패하는 경로가 없다(실패는 스위치로 만든 거절뿐이다).
+- Web은 빈 `role="status"` Text도 Stack 자식이라 gap 한 칸(`spacing.lg` 20)이 Steps 아래에 남는다.

package/docs/usage/compositions/stea-otp-verify.md

@@ -0,0 +1,215 @@
+# 인증번호 확인과 다시 입력
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [OtpField](../../otp-field.md), `showcase/web/src/patterns/stea-composition-previews.tsx`(`OtpVerifyRecover`), `showcase/native/src/stea-composition-previews.tsx`(`OtpVerifyRecover`, `Frame`), `showcase/shared/stea-compositions.ts`(`otpReducer`·`otpErrorMessage`), `src/otp-field.ts`, `src/result.ts`, `src/card.ts`, `src/container.ts`
+- 스토리북: `배포/구성/입력과 작성/인증번호 확인과 다시 입력`
+
+## 언제 쓰나
+
+문자·메일로 받은 숫자 인증번호를 입력하고 서버 확인을 기다린 뒤, 틀리면 남은 횟수를 보여 주고 다시 받게 하는 흐름에 쓴다.
+성공 화면은 서버가 번호를 확인한 뒤에만 나타나고, 입력 중에는 슬롯 위치가 움직이지 않는다.
+비밀번호·한 줄 텍스트 입력은 [PasswordField](../components/password-field.md)·[Field](../components/field.md)를 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Card` | 제목("인증번호 확인")·설명을 가진 틀 | [Card](../components/card.md) |
+| `ContentTransition` | 입력 폼 ↔ 성공 결과 전환(기본 `fade`). 입력 중엔 같은 subtree를 유지 | [ContentTransition](../components/content-transition.md) |
+| `OtpField` | `length` 6 숫자 칸. 확인 중 `busy`, 잠김 `disabled`, 틀림·요청 실패 `error` | [OtpField](../components/otp-field.md) |
+| 재전송 안내 문구 | 다시 받은 뒤 "새 인증번호를 보냈어요…", 재전송 실패 문구(muted, live) | [Text](../components/text.md) |
+| `Button` primary | 확인. 확인 중 `loading` | [Button](../components/button.md) |
+| `Button` ghost | 인증번호 다시 받기. 대기 시간 동안 `disabled`, 라벨이 남은 초를 보여 줌. 재전송 요청 중 `loading` | [Button](../components/button.md) |
+| `Result` `status="success"` | 성공 결과 + 행동 하나. Web은 `icon`을 비우면 CSS가 ✓를 그린다. Native는 기본 glyph가 없으니 `renderIcon`으로 제품 glyph를 넘긴다(비우면 빈 원) | [Result](../components/result.md) |
+| `ScrollView` + `Container`(Native) | 바깥 틀. 세로 스크롤·위아래 여백, 좌우 gutter | [Container](../components/container.md), [화면 여백과 너비](../tokens/layout.md) |
+
+## 배치
+
+```text
+Native 화면(ScrollView keyboardShouldPersistTaps="handled", 위아래 spacing.lg 20)
+┌ Container gutter 16(폭 < 600) · 20(폭 ≥ 600) ────┐
+│ ┌ Card ──────────────────────────────────┐       │  body padding spacing.md 16
+│ │ 인증번호 확인              (title)     │       │
+│ │ 문자로 받은 6자리 숫자를…  (muted)     │       │  제목–설명 spacing.xs 8
+│ │ ┌ form ──────────────────────────────┐ │       │
+│ │ │ 인증번호                           │ │       │
+│ │ │ [2][4][6][8][1][ ]   ← OtpField    │ │       │  칸 44, 칸 사이 spacing.xs 8
+│ │ │ 도움말 / 오류(남은 횟수)           │ │       │
+│ │ │          ↕ spacing.md 16           │ │       │
+│ │ │ 새 인증번호를 보냈어요 (재전송 후) │ │       │
+│ │ │          ↕ spacing.md 16           │ │       │
+│ │ │ [            확인              ]   │ │       │  ← 주 행동(primary), 위
+│ │ │          ↕ spacing.md 16           │ │       │
+│ │ │ [  8초 후 다시 받을 수 있어요  ]   │ │       │  ← 보조(ghost), 아래, 대기 중 disabled
+│ │ └────────────────────────────────────┘ │       │
+│ └────────────────────────────────────────┘       │
+└──────────────────────────────────────────────────┘
+  안전 영역·키보드: 화면 골격이 맡는다. 고정 영역 없음(행동은 본문 흐름 안)
+
+성공 후 같은 Card 안
+┌ Card ──────────────────────────────────┐
+│        (✓)                             │  Result 위아래 spacing.xxxl 40, 좌우 spacing.xl 24
+│   인증을 마쳤어요                      │
+│   서버가 번호를 확인한 뒤에만…        │  ← description
+│   [ 계속 ]                             │  ← Result 행동 하나(제품의 다음 단계)
+└────────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: 제품 화면 레이아웃(문서 스크롤). Native: `ScrollView` > `Container` | 이 구성은 바깥 폭·여백을 정하지 않는다. 스토리는 Card만 그린다. Web 단독 화면이면 [Container](../components/container.md) 같은 읽기 폭 컨테이너는 제품이 고른다. Native는 Card를 `ScrollView`(`keyboardShouldPersistTaps="handled"`) 안 `Container`에 둔다. 입력이 한 칸이라 [KeyboardFormScrollView](../components/keyboard-form-scroll-view.md)(실험, `react-native-keyboard-controller` 설치와 앱 루트 `KeyboardMotionProvider` 필요)는 기본값이 아니며, 여러 필드 폼 안에 이 구성을 넣을 때만 쓴다. 안전 영역은 화면 골격(내비게이션 헤더·탭 바)이 맡는다 | Native ScrollView 위아래 `spacing.lg` 20, Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20(`layout.pagePadding`) |
+| 틀 | `Card` | 바깥 틀 안, 스크롤과 함께 | body padding `spacing.md` 16, 제목–설명 `spacing.xs` 8 |
+| 입력 | `OtpField` medium | Card 머리 아래 맨 위 | 칸 `control.minTouchTarget` 44, 칸 사이 `spacing.xs` 8 (`large`: 52 / `spacing.sm` 12) |
+| 재전송 안내 | Text muted | 입력 아래, 재전송 후·재전송 실패 때만 | `Stack gap="md"` 16 |
+| 행동 | Button primary → ghost | 안내 아래, 세로로 꽉 찬 폭(`Stack` 기본 `align="stretch"`가 채우므로 Web `layoutStyle`·Native `fullWidth`를 따로 주지 않는다) | 높이 `control.buttonHeight.medium` 44, 사이 `spacing.md` 16 |
+| 성공 | `Result` | 폼 자리를 대신함 | 위아래 `spacing.xxxl` 40, 좌우 `spacing.xl` 24, gap `spacing.sm` 12 |
+
+- 확인이 위, 다시 받기가 아래다. 세로로 쌓은 행동은 주 행동이 위다([Button](../components/button.md) 좁은 폭 규칙과 같다). 이 구성의 primary는 확인 하나다.
+
+## 흐름과 상태
+
+1. 번호를 입력한다. 6자리가 차면 Web은 Enter·확인 버튼으로 제출하고, Native는 `onComplete`로 바로 제출한다.
+2. 확인 중: 입력은 포커스를 유지한 채 읽기 전용(`busy`), 확인 버튼은 `loading`, 다시 받기는 `disabled`.
+3. 틀리면 OtpField `error`에 "인증번호가 맞지 않아요. N번 더 시도할 수 있어요."가 나온다. 값을 고치기 시작하면 오류가 내려간다.
+4. 3번 틀리면 잠긴다(`disabled`). 대기 시간이 끝난 뒤 "인증번호 다시 받기"로만 풀린다.
+5. 다시 받으면 상태가 초기화되고(시도 횟수·대기 시간 재시작) 재전송 안내 문구가 나온다.
+6. 서버가 맞다고 응답하면 `ContentTransition`이 폼을 `Result` success로 바꾼다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 빈 칸·채운 칸(채운 칸 테두리 `content.brand`), 확인은 6자리 전 `disabled`, 다시 받기는 대기 라벨 | 첫 칸 |
+| 진행 중 | 확인 요청: 입력 읽기 전용(`busy`), 확인 `loading`, 다시 받기 `disabled` | 입력에 포커스 유지 |
+| 실패 | 확인 요청 실패(네트워크·서버): 시도 횟수를 줄이지 않고 OtpField `error`에 재시도 문구, 값 유지. 확인은 다시 누를 수 있다 | 오류는 필드 설명으로 읽힌다 |
+| 틀림 | OtpField `error`에 남은 횟수 | 오류는 필드 설명으로 읽힌다 |
+| 잠김 | OtpField `disabled` + `error`에 "시도 횟수를 모두 썼어요. 인증번호를 다시 받아 주세요." | 다시 받기만 동작 |
+| 재전송 대기 | ghost 라벨 "N초 후 다시 받을 수 있어요", `disabled` | 1초마다 라벨 갱신 |
+| 재전송 요청 중 | 다시 받기 `loading`. 두 번 보내지 않는다 | — |
+| 재전송 실패 | 대기 시간을 시작하지 않고 오류 문구(입력 아래 Text), 다시 받기는 바로 다시 누를 수 있다 | 실패 문구는 Web `role="status"`, Native live region |
+| 재전송 완료 | 안내 문구(muted) | Web: 입력으로 포커스 이동. 문구는 Web `role="status"`, Native live region |
+| 성공 | `Result` success, 행동 하나(제품의 다음 단계, 예 `otp.continue`). 스토리의 "다른 번호로 다시 해 보기"는 데모 초기화용 | Web: Result(`tabIndex={-1}`)로 포커스 이동 |
+
+- 스토리의 정답 `246810`, 대기 10초(실서비스는 보통 30~60초), 지연 900ms는 데모 값이다. 시도 횟수·대기 시간·검증은 서버와 제품 소유다.
+- 문구 키는 상태별 상수로 둔다(아래 `otpErrorKey`). 상태 이름으로 키를 조립하면 상태 표와 키가 어긋난다.
+
+| 상태 | 문구 키 | 변수 |
+| --- | --- | --- |
+| 틀림 | `otp.wrong` | `left` |
+| 잠김 | `otp.locked` | — |
+| 확인 요청 실패 | `otp.requestFailed` | — |
+| 재전송 실패 | `otp.resendFailed` | — |
+| 재전송 대기 | `otp.resendWait` | `seconds` |
+| 재전송 완료 | `otp.resent` | — |
+
+## 코드 골격
+
+```tsx
+// Web
+import { useEffect, useRef } from "react";
+import { Button } from "@hjmds/react/actions";
+import { ContentTransition } from "@hjmds/react/content-transition";
+import { Card } from "@hjmds/react/display";
+import { Result } from "@hjmds/react/feedback";
+import { OtpField } from "@hjmds/react/forms";
+import { Stack, Text } from "@hjmds/react/layout";
+
+// 상태 → 문구 키. 키를 상태 이름으로 조립하지 않는다.
+const otpErrorKey = { wrong: "otp.wrong", locked: "otp.locked", requestFailed: "otp.requestFailed" } as const;
+const error = errorKind ? t(otpErrorKey[errorKind], { left: attemptsLeft }) : undefined;
+
+const inputRef = useRef<HTMLInputElement>(null);
+const resultRef = useRef<HTMLDivElement>(null);
+// 재전송 횟수를 의존성으로 둔다. 불리언 resent는 두 번째 재전송부터 값이 같아 실행되지 않는다.
+useEffect(() => { if (resendCount > 0) inputRef.current?.focus(); }, [resendCount]);
+useEffect(() => { if (verified) resultRef.current?.focus(); }, [verified]);
+
+<Card title={t("otp.title")} description={t("otp.description")}>
+  <ContentTransition stateKey={verified ? "verified" : "form"}>
+    {verified
+      ? <Result ref={resultRef} tabIndex={-1} status="success" title={t("otp.success")}
+          description={t("otp.successBody")} actions={[{ label: t("otp.continue"), onAction: next }]} />
+      : <form onSubmit={(event) => { event.preventDefault(); submit(); }}>
+          <Stack gap="md">
+            <OtpField ref={inputRef} label={t("otp.field")} length={6} value={code}
+              onValueChange={change} busy={verifying} disabled={locked}
+              description={t("otp.hint")} {...(error ? { error } : {})} />
+            {resendFailed ? <Text role="status" tone="muted">{t("otp.resendFailed")}</Text>
+              : resendCount > 0 ? <Text role="status" tone="muted">{t("otp.resent")}</Text> : null}
+            <Button type="submit" loading={verifying} disabled={!canSubmit && !verifying}>{t("otp.submit")}</Button>
+            <Button type="button" tone="ghost" loading={resending} disabled={resendIn > 0 || verifying} onClick={resend}>
+              {resendIn > 0 ? t("otp.resendWait", { seconds: resendIn }) : t("otp.resend")}
+            </Button>
+          </Stack>
+        </form>}
+  </ContentTransition>
+</Card>;
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Button } from "@hjmds/react-native/actions";
+import { ContentTransition } from "@hjmds/react-native/content-transition";
+import { Card } from "@hjmds/react-native/data-display";
+import { Result } from "@hjmds/react-native/feedback";
+import { OtpField } from "@hjmds/react-native/inputs";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+
+const otpErrorKey = { wrong: "otp.wrong", locked: "otp.locked", requestFailed: "otp.requestFailed" } as const;
+const error = errorKind ? t(otpErrorKey[errorKind], { left: attemptsLeft }) : undefined;
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView keyboardShouldPersistTaps="handled" contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container size="reading" gutter={gutter}>
+    <Card title={t("otp.title")} description={t("otp.description")}>
+      <ContentTransition stateKey={verified ? "verified" : "form"}>
+        {verified
+          ? <Result status="success" title={t("otp.success")} description={t("otp.successBody")}
+              actions={[{ label: t("otp.continue"), onAction: next }]}
+              renderIcon={({ color }) => <CheckGlyph color={color} size={28} />} />
+          : <Stack gap="md">
+              <OtpField label={t("otp.field")} length={6} value={code} onValueChange={change}
+                onComplete={submit} busy={verifying} disabled={locked}
+                description={t("otp.hint")} {...(error ? { error } : {})} />
+              {resendFailed ? <Text accessibilityLiveRegion="polite" tone="muted">{t("otp.resendFailed")}</Text>
+                : resendCount > 0 ? <Text accessibilityLiveRegion="polite" tone="muted">{t("otp.resent")}</Text> : null}
+              <Button loading={verifying} disabled={!canSubmit && !verifying} onPress={submit}>{t("otp.submit")}</Button>
+              <Button tone="ghost" loading={resending} disabled={resendIn > 0 || verifying} onPress={resend}>
+                {resendIn > 0 ? t("otp.resendWait", { seconds: resendIn }) : t("otp.resend")}
+              </Button>
+            </Stack>}
+      </ContentTransition>
+    </Card>
+  </Container>
+</ScrollView>;
+```
+
+상태 전이는 스토리의 `otpReducer`(편집 → 확인 중 → 틀림/잠김/성공, 재전송은 대기 후 초기화)를 참고해 제품이 소유한다.
+확인 요청 실패·재전송 요청 중·실패는 스토리에 없으므로 제품이 상태를 더한다(시도 횟수를 줄이지 않는다).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 제출 | `<form onSubmit>` + `type="submit"` 버튼(Enter 제출) | `onComplete`로 6자리 도달 시 자동 제출 + 확인 버튼 |
+| 바깥 틀 | 제품 화면 레이아웃(문서 스크롤) | `ScrollView keyboardShouldPersistTaps="handled"` > `Container` |
+| 재전송 후 포커스 | 입력으로 `focus()` | 이동하지 않음(스토리) |
+| 성공 후 포커스 | `Result`(`tabIndex={-1}`)로 이동 | 이동하지 않음(스토리) |
+| 성공 아이콘 | `icon`을 비우면 CSS가 ✓ | `renderIcon`으로 제품 glyph(비우면 빈 원) |
+| 상태 문구 | `role="status"` | `accessibilityLiveRegion="polite"` |
+| busy 표현 | read-only + `aria-busy` | `editable={false}` + `accessibilityState.busy` |
+| 자동 채움 | `autoComplete="one-time-code"` | `textContentType="oneTimeCode"` |
+
+## 함정
+
+- 대기 타이머 effect 의존성에 `phase`를 넣으면 확인 요청마다 1초 타이머가 다시 시작돼 대기 시간이 줄지 않는다(2026-10-02 실측). 남은 초와 성공 여부만 의존성으로 둔다.
+- 확인 중·잠김·성공 상태에서는 입력 값을 바꾸지 않는다. 응답과 다른 번호가 화면에 남는다.
+- 성공 화면 전환은 서버 응답 뒤에만 한다. 6자리가 찼다는 이유로 미리 바꾸지 않는다.
+- 네트워크·서버 실패를 "틀림"으로 처리해 시도 횟수를 줄이지 않는다. 사용자가 맞는 번호를 넣고도 잠긴다.
+- 현재 스토리에는 확인 요청 실패·재전송 요청 중·재전송 실패 경로가 없다. 성공 행동 "다른 번호로 다시 해 보기"는 데모 초기화용이다.

package/docs/usage/compositions/stea-pixel-empty.md

@@ -0,0 +1,140 @@
+# 캐릭터와 시작 행동
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/component-recipes.ts` `emptyStateRecipe`, `packages/react/src/styles.css` `.hjm-empty-state`, `showcase/shared/stea-expressions.ts`, `showcase/{web/src/patterns,native/src}/stea-expression-previews.tsx`(`PixelEmptyState`, Native `Frame`), `src/container.ts`
+- 스토리북: `배포/구성/피드백과 복구/캐릭터와 시작 행동`
+
+## 언제 쓰나
+
+아직 만든 것이 없는 첫 빈 화면에 제품 캐릭터를 움직여 보이고 첫 행동 하나로 이끌 때 쓴다. 검색 결과 0건이나 오류처럼
+캐릭터가 어울리지 않는 빈 상태에는 쓰지 않고 기본 [EmptyState](../components/empty-state.md)만 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| EmptyState | 그림·제목·설명·행동 한 묶음 | [EmptyState](../components/empty-state.md) |
+| 제품 캐릭터(스토리: 12×12 픽셀 스프라이트) | 장식 그림, 4프레임 220ms 반복 | 제품 소유 |
+| Button `primary` | 첫 기록 남기기(시작 행동) | [Button](../components/button.md) |
+| Button `ghost` | 움직임 멈추기/다시 움직이기 | [Button](../components/button.md) |
+| Text `tone="muted"` 상태 문구 | 시작 행동 결과 | [Text](../components/text.md) |
+| `ScrollView` + `Container`(Native) | 바깥 틀. 세로 스크롤·위아래 여백, 좌우 gutter | [Container](../components/container.md), [화면 여백과 너비](../tokens/layout.md) |
+
+## 배치
+
+```text
+Native 화면(ScrollView, 위아래 spacing.lg 20) > Container gutter 16(폭 < 600) · 20(폭 ≥ 600)
+┌──────── Stack gap spacing.md 16 ─────────┐
+│ ┌──── EmptyState (가운데 정렬) ────────┐ │
+│ │            ┌────────┐                │ │
+│ │            │ 캐릭터 │ 96×96          │ │
+│ │            └────────┘   ↕ spacing.xs 8│ │
+│ │   아직 남긴 기록이 없어요  (제목)      │ │
+│ │   말랑이가 첫 기록을 기다리고 있어요.  │ │
+│ │        [ 첫 기록 남기기 ]  primary     │ │ ← 주 행동
+│ └────────────────────────────────────────┘ │
+│ [ 움직임 멈추기 ]  ghost                   │ ← 보조(멈춤 제어)
+│ 상태 문구 (muted, live)                    │
+└───────────────────────────────────────────┘
+  고정 영역 없음. 안전 영역은 화면 골격이 맡는다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: 제품 화면 레이아웃(문서 스크롤). Native: `ScrollView` > `Container` | 이 구성은 바깥 폭·여백을 정하지 않는다(Web 스토리는 Stack만 그린다). Native는 `ScrollView` 안 [Container](../components/container.md)에 둔다. 입력이 없어 키보드 처리는 없다. 안전 영역은 화면 골격(내비게이션 헤더·탭 바)이 맡는다 | Native ScrollView 위아래 `spacing.lg` 20, Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20(`layout.pagePadding`) |
+| 빈 상태 | EmptyState `density="regular"` | 본문 가운데 | 위아래 Web `spacing.xxl` 32 / Native `spacing.xxxl` 40, 좌우 `spacing.xl` 24, 슬롯 사이 `spacing.xs` 8 |
+| 캐릭터 | Web `icon` / Native `illustration` | EmptyState 맨 위 | 96×96(12칸 × `spacing.xs` 8). Native는 `illustrationStyle`로 칸을 96에 맞춘다 |
+| 시작 행동 | Button `primary` | EmptyState `action` | 높이 44, 하나만 |
+| 멈춤 제어 | Button `ghost` | EmptyState 아래, 꽉 찬 폭(`Stack` 기본 `align="stretch"`) | 묶음 사이 `spacing.md` 16 |
+| 상태 문구 | Text muted | 맨 아래. Web은 빈 `role="status"`를 늘 마운트, Native는 문구가 있을 때만 | `spacing.md` 16 |
+
+## 흐름과 상태
+
+1. 화면이 열리면 캐릭터가 220ms 간격 4프레임으로 반복한다.
+2. "첫 기록 남기기"를 누르면 제품의 작성 화면으로 간다(스토리는 상태 문구만 보인다).
+3. "움직임 멈추기"를 누르면 첫 프레임에서 멈추고 라벨이 "다시 움직이기"로 바뀐다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 캐릭터가 움직인다 | 캐릭터는 숨김, 제목·설명이 의미를 전한다 |
+| 진행 중 | 시작 행동이 화면 이동이면 없다. 서버 요청(예: 첫 항목 생성)이면 primary `loading` | 포커스는 버튼 유지 |
+| 실패 | 시작 행동이 서버 요청일 때 실패하면 상태 문구 자리에 실패 문구, primary는 다시 누를 수 있다. 빈 상태 자체를 불러오지 못한 경우는 이 구성이 아니라 오류 화면([Result](../components/result.md) failure)이다 | 상태 문구가 Web `role="status"`, Native live region으로 읽힌다 |
+| 멈춤 | 첫 프레임 정지 | 멈춤 버튼 라벨이 바뀐다 |
+| reduced motion | 타이머 없이 첫 프레임 | — |
+| 탭 숨김(Web)·앱 배경(Native) | 타이머를 걸지 않는다 | — |
+| 시작 행동 후 | 상태 문구 표시 | Web `role="status"`, Native `accessibilityLiveRegion` |
+| 다크 | 캐릭터 색을 테마에서 고른다(Native 예: 외곽 `text`, 몸 `contentBrand`, 밝은 칸 `bg`) | — |
+
+## 코드 골격
+
+```tsx
+// Web
+import { EmptyState } from "@hjmds/react/feedback";
+import { Button } from "@hjmds/react/actions";
+import { Stack, Text } from "@hjmds/react/layout";
+
+// 상태 → 문구 키
+const statusKey = { idle: undefined, started: "records.empty.started", failed: "records.empty.startFailed" } as const;
+const statusText = statusKey[startState];
+
+<Stack gap="md">
+  <EmptyState icon={<ProductMascot paused={paused} />} title={t("records.empty.title")}
+    description={t("records.empty.description")}
+    action={<Button loading={starting} onClick={startRecord}>{t("records.empty.start")}</Button>} />
+  <Button tone="ghost" onClick={() => setPaused((v) => !v)}>
+    {paused ? t("mascot.resume") : t("mascot.pause")}
+  </Button>
+  <Text role="status" tone="muted">{statusText ? t(statusText) : ""}</Text>
+</Stack>;
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { EmptyState } from "@hjmds/react-native/feedback";
+import { Button } from "@hjmds/react-native/actions";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+
+const statusKey = { idle: undefined, started: "records.empty.started", failed: "records.empty.startFailed" } as const;
+const statusText = statusKey[startState];
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container gutter={gutter}>
+    <Stack gap="md">
+      <EmptyState illustration={<ProductMascot paused={paused} />} illustrationStyle={{ width: 96, height: 96 }}
+        title={t("records.empty.title")} description={t("records.empty.description")}
+        action={<Button loading={starting} onPress={startRecord}>{t("records.empty.start")}</Button>} />
+      <Button tone="ghost" onPress={() => setPaused((v) => !v)}>
+        {paused ? t("mascot.resume") : t("mascot.pause")}
+      </Button>
+      {statusText ? <Text accessibilityLiveRegion="polite" tone="muted">{t(statusText)}</Text> : null}
+    </Stack>
+  </Container>
+</ScrollView>;
+```
+
+캐릭터 그림·프레임·색 배정, 문구는 제품 소유다. 스토리의 픽셀 박쥐와 "말랑이"는 예시다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 그림 슬롯 | `icon` | `illustration` + `illustrationStyle`(기본 칸이 아이콘 크기 `glyph.lg`라 캐릭터가 넘친다) |
+| 세로 여백 | `.hjm-empty-state` `spacing.xxl` 32 | recipe `spacing.xxxl` 40 |
+| 일시정지 감지 | `document.hidden` | `AppState` |
+| 상태 문구 자리 | 빈 `role="status"`를 늘 마운트 | 문구가 있을 때만 마운트 |
+| 바깥 틀 | 제품 화면 레이아웃(문서 스크롤) | `ScrollView` > `Container` |
+
+## 함정
+
+- 5초 넘게 반복되는 움직임에는 멈춤 제어를 둔다(WCAG 2.2.2). 스토리의 ghost 버튼이 그 자리다.
+- 캐릭터에 접근성 이름을 붙이지 않는다. EmptyState가 그림을 장식으로 숨긴다.
+- 현재 스토리의 시작 행동은 상태 문구만 바꾼다. 진행 중·실패 경로는 없다.