@hjmds/design-contracts 1.12.1 → 1.13.1

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

@@ -0,0 +1,169 @@
+# 날짜 선택과 예정 목록
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `showcase/web/src/patterns/stea-composition-previews.tsx`(`ScheduleDayList`), `showcase/native/src/stea-composition-previews.tsx`(`ScheduleDayList`, `Frame`), `showcase/shared/stea-compositions.ts`(`scheduleCopy`), `src/card.ts`, `src/component-recipes.ts`(`segmentedControlRecipe`, `listRowRecipe`), `src/container.ts`
+- 스토리북: `배포/구성/선택과 필터/날짜 선택과 예정 목록`
+
+## 언제 쓰나
+
+한 주처럼 짧은 날짜 범위에서 날짜 하나를 고르면 같은 카드 안의 일정 목록이 그 날짜로 바뀌는 요약 카드에 쓴다.
+날짜가 5개 안팎이라 한 줄 SegmentedControl에 다 들어갈 때 맞다. 달력에서 아무 날짜나 고르면
+[Calendar](../components/calendar.md)·[DatePicker](../components/date-picker.md)를 쓴다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Card` | 제목("이번 주 일정")·설명을 가진 틀 | [Card](../components/card.md) |
+| `SegmentedControl` | 날짜 선택(라벨 "월 5"처럼 짧게) | [SegmentedControl](../components/segmented-control.md) |
+| `ContentTransition` | 날짜가 바뀔 때 목록 교체(기본 `fade`), `stateKey`=날짜 | [ContentTransition](../components/content-transition.md) |
+| `List` + `ListRow` | 일정 행. 제목 + "시각 · 장소" 설명 | [List](../components/list.md), [ListRow](../components/list-row.md) |
+| 빈 상태 `Text` 두 줄 | strong "이 날은 예정된 일정이 없어요." + muted 안내 | [Text](../components/text.md) |
+| `Skeleton`·`Notice` | 서버에서 받는 일정일 때 목록 자리의 로딩·실패(스토리에 없음) | [Skeleton](../components/skeleton.md), [Notice](../components/notice.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)   │
+│ ┌──────┬──────┬──────┬──────┬──────┐       │  ← SegmentedControl, 높이 44
+│ │ 월 5 │ 화 6 │ 수 7 │ 목 8 │ 금 9 │       │
+│ └──────┴──────┴──────┴──────┴──────┘       │
+│              ↕ spacing.md 16               │
+│ ┌ 주간 계획 맞추기                      ┐  │  ← ListRow 두 줄 최소 68
+│ │ 오전 10:00 · 회의실 A                 │  │
+│ ├ 디자인 검토                           ┤  │
+│ └ 오후 3:30 · 화상 회의                 ┘  │
+│   (일정 없음: 강조 문구 / 안내 문구, xs 8) │
+└────────────────────────────────────────────┘
+  고정 영역 없음. 목록이 길면 화면 스크롤로 내려간다. 안전 영역은 화면 골격이 맡는다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 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="md"` 16 |
+| 날짜 | `SegmentedControl` medium | Card 머리 아래 | 최소 높이 `control.minTouchTarget` 44, 트랙 padding·항목 사이 Native `spacing.xxs` 4 / Web CSS 2px |
+| 목록 | `List` + `ListRow` | 날짜 아래 | 두 줄 행 최소 `layout.rowHeight.twoLine` 68(comfortable), 날짜와 `spacing.md` 16 |
+| 빈 상태 | Text strong + muted | 목록 자리 | 두 줄 사이 `spacing.xs` 8 |
+| 로딩·실패 | `Skeleton` 행 / `Notice` danger + 다시 시도 | 목록 자리(날짜 선택은 그대로) | 날짜와 `spacing.md` 16 |
+
+- 날짜 선택은 목록 **위**에 둔다. 목록 높이가 바뀌어도 날짜 위치는 움직이지 않는다.
+- 큰 글자(`largeTextThreshold` 이상, Web은 `data-large-text`)에서 SegmentedControl이 세로로 쌓인다(`segmentedControlRecipe.adaptive`). 보통 폭에서는 Web 항목이 `min-inline-size: max-content`라 넘치면 가로 스크롤된다. 날짜 라벨을 짧게 유지한다.
+
+## 흐름과 상태
+
+1. 첫 날짜가 선택된 채 열린다.
+2. 다른 날짜를 누르면 `ContentTransition`이 목록을 그 날짜 일정으로 바꾼다. 서버에서 받으면 그동안 목록 자리에 Skeleton이 나온다.
+3. 일정이 없는 날짜면 목록 대신 빈 상태 두 줄이 나온다.
+4. 불러오기에 실패하면 목록 자리에 Notice와 "다시 시도"가 나온다. 다시 시도는 같은 날짜를 다시 요청한다.
+
+- 문구 키는 상태별 상수로 둔다(`schedule.empty`·`schedule.emptyHint`·`schedule.loadFailed`·`common.retry`). 행 설명은 `t("schedule.rowDescription", { time, place })`처럼 변수로 넘기고 문자열을 이어 붙이지 않는다(언어마다 순서가 다르다).
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 첫 날짜 선택, `List` 이름 "10월 5일 월요일 일정"(긴 날짜), 행 여러 개 | 포커스는 SegmentedControl에 남는다 |
+| 진행 중 | 서버에서 받는 일정이면 목록 자리에 `Skeleton` 행(`text` 두 줄). 날짜는 계속 바꿀 수 있고, 늦게 온 이전 날짜 응답은 버린다 | 포커스는 SegmentedControl에 남는다 |
+| 실패 | 목록 자리에 `Notice` danger + `action` "다시 시도"(`secondary` `small`). 날짜 선택은 유지 | Web `danger`는 `role="alert"`, Native는 `announcement="assertive"` |
+| 일정 없음 | strong + muted 문구 두 줄 | 알림 없음(스토리). 필요하면 제품이 live region을 더한다 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { ContentTransition } from "@hjmds/react/content-transition";
+import { Card, List, ListRow } from "@hjmds/react/display";
+import { Notice, Skeleton } from "@hjmds/react/feedback";
+import { Stack, Text } from "@hjmds/react/layout";
+import { SegmentedControl } from "@hjmds/react/selection";
+
+<Card title={t("schedule.title")} description={t("schedule.description")}>
+  <Stack gap="md">
+    <SegmentedControl label={t("schedule.dayLabel")} value={day} onValueChange={setDay} items={dayItems} />
+    <ContentTransition stateKey={`${day}:${status}`}>
+      {status === "loading"
+        ? <Stack gap="xs"><Skeleton shape="text" /><Skeleton shape="text" width="60%" /></Stack>
+        : status === "failed"
+          ? <Notice tone="danger" title={t("schedule.loadFailed")}
+              action={<Button tone="secondary" size="small" onClick={retry}>{t("common.retry")}</Button>} />
+          : items.length
+            ? <List label={t("schedule.listLabel", { day: longDay })}>
+                {items.map((item) => <ListRow key={item.id} title={item.title}
+                  description={t("schedule.rowDescription", { time: item.time, place: item.place })} />)}
+              </List>
+            : <Stack gap="xs">
+                <Text emphasis="strong">{t("schedule.empty")}</Text>
+                <Text tone="muted">{t("schedule.emptyHint")}</Text>
+              </Stack>}
+    </ContentTransition>
+  </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 { ContentTransition } from "@hjmds/react-native/content-transition";
+import { Card, List, ListRow } from "@hjmds/react-native/data-display";
+import { Notice, Skeleton } from "@hjmds/react-native/feedback";
+import { SegmentedControl } from "@hjmds/react-native/inputs";
+import { Container, Stack, Text } from "@hjmds/react-native/primitives";
+
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container gutter={gutter}>
+    <Card title={t("schedule.title")} description={t("schedule.description")}>
+      <Stack gap="md">
+        <SegmentedControl label={t("schedule.dayLabel")} value={day} onValueChange={setDay} items={dayItems} />
+        <ContentTransition stateKey={`${day}:${status}`}>
+          {status === "loading"
+            ? <Stack gap="xs"><Skeleton shape="text" accessibilityLabel={t("schedule.loading")} /><Skeleton shape="text" width="60%" /></Stack>
+            : status === "failed"
+              ? <Notice tone="danger" announcement="assertive" title={t("schedule.loadFailed")}
+                  action={<Button tone="secondary" size="small" onPress={retry}>{t("common.retry")}</Button>} />
+              : items.length
+                ? <List label={t("schedule.listLabel", { day: longDay })}>
+                    {items.map((item) => <ListRow key={item.id} title={item.title}
+                      description={t("schedule.rowDescription", { time: item.time, place: item.place })} />)}
+                  </List>
+                : <Stack gap="xs">
+                    <Text emphasis="strong">{t("schedule.empty")}</Text>
+                    <Text tone="muted">{t("schedule.emptyHint")}</Text>
+                  </Stack>}
+        </ContentTransition>
+      </Stack>
+    </Card>
+  </Container>
+</ScrollView>;
+```
+
+날짜 목록(10월 5~9일)과 일정 다섯 개는 예시 데이터다. 날짜 계산·시간 표기(로케일)·일정 데이터는 제품 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `SegmentedControl` import | `@hjmds/react/selection` | `@hjmds/react-native/inputs` |
+| `Card`·`List` import | `@hjmds/react/display` | `@hjmds/react-native/data-display` |
+| 큰 글자 | `data-large-text`에서 세로로 쌓음 | 기준 글자 크기 이상에서 세로로 쌓음 |
+| 트랙 padding·항목 간격 | CSS 2px | `spacing.xxs` 4 |
+| 바깥 틀 | 제품 화면 레이아웃(문서 스크롤) | `ScrollView` > `Container` |
+| 실패 Notice 발표 | `danger`는 늘 `role="alert"` | `announcement="assertive"`를 지정해야 발표(기본 `none`) |
+
+## 함정
+
+- 날짜를 빨리 바꾸면 이전 날짜 응답이 나중에 도착할 수 있다. 응답의 날짜가 현재 선택과 같을 때만 반영한다.
+- 현재 스토리는 로컬 데이터라 로딩·실패 경로가 없고, 행 설명을 `` `${time} · ${place}` ``로 이어 붙인다.

package/docs/usage/compositions/stea-stat-summary.md

@@ -0,0 +1,154 @@
+# 수치와 이전 대비 변화
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Statistic](../../statistic.md), [Progress](../../progress.md), `showcase/shared/stea-compositions.ts`, `showcase/{web/src/patterns,native/src}/stea-composition-previews.tsx`(`StatChangeSummary`, Native `Frame`), `src/container.ts`
+- 스토리북: `배포/구성/정보 표시/수치와 이전 대비 변화`
+
+## 언제 쓰나
+
+매출·주문·반품처럼 몇 개의 핵심 수치를 비교 기간과 함께 보이고, 증감의 방향과 좋고 나쁨을 색 없이도 읽히게 할 때 쓴다.
+기간을 바꾸면 수치와 목표 달성률이 같은 기간으로 함께 바뀌는 요약 카드다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| Card `title`·`description` | 요약 묶음과 제목 | [Card](../components/card.md) |
+| SegmentedControl | 비교 기간(지난주와 비교·지난달과 비교) | [SegmentedControl](../components/segmented-control.md) |
+| Statistic | 수치 하나 + `trend`(방향·tone·보이는 문구) | [Statistic](../components/statistic.md) |
+| Progress | 같은 기간의 목표 달성률 | [Progress](../components/progress.md) |
+| Stack | 세로 간격 | [Stack](../components/stack.md) |
+| Skeleton · Notice | 서버에서 받는 수치일 때 로딩·실패(스토리에 없음) | [Skeleton](../components/skeleton.md), [Notice](../components/notice.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 (padding spacing.md 16, radius lg 16) ────────────┐
+│ 판매 요약 (title)                                                   │
+│ 설명 (description)                                                  │
+│ [ 지난주와 비교 | 지난달과 비교 ]   ← SegmentedControl, 전체 폭      │
+│                 ↕ spacing.lg 20                                     │
+│ 매출  3,950,000원   ▲ 지난주보다 20% 늘었어요   (success)           │
+│                 ↕ spacing.md 16                                     │
+│ 주문  128건         ― 지난주와 같아요           (neutral)           │
+│ 반품  9건           ▲ 지난주보다 3건 늘었어요    (danger)            │
+│                 ↕ spacing.lg 20                                     │
+│ 이번 주 목표 달성률                                   76%           │
+│ ████████████████████░░░░░░                                         │
+└────────────────────────────────────────────────────────────────────┘
+  고정 영역 없음. 안전 영역은 화면 골격이 맡는다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | 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 | 바깥 틀 안, 함께 스크롤 | padding `md` 16, radius `lg` 16, 테두리 있음 |
+| 기간 선택 | SegmentedControl | 카드 본문 맨 위 | `size` `medium`, 아래 `spacing.lg` 20 |
+| 수치 목록 | Stack > Statistic ×3 | 기간 선택 아래 | 수치 사이 `spacing.md` 16, 값은 `comfortable`(`heading` 크기) |
+| 목표 | Progress | 카드 맨 아래 | 위 `spacing.lg` 20, `size` `medium` |
+| 로딩·실패 | Skeleton / Notice danger + 다시 시도 | 수치 목록 자리(기간 선택은 그대로) | 수치 목록과 같은 자리 |
+
+수치가 많아 가로로 늘어놓을 때는 [Statistic](../components/statistic.md)의 `StatisticGroup`(`columns` 기본 3, 좁은 폭·큰 글자에서 1열까지 줄어듦)을 쓴다.
+
+## 흐름과 상태
+
+1. 기간을 바꾸면 세 수치, 증감 문구, 목표 라벨("이번 주"/"이번 달")과 값이 한꺼번에 바뀐다.
+2. 증가가 나쁜 지표(반품)는 `direction: "up"`이어도 `tone: "danger"`로 둔다. 방향과 의미를 따로 준다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 선택한 기간의 수치와 증감 | `trend.label`이 보이는 문구이자 읽히는 문구다 |
+| 진행 중 | 서버에서 받는 수치면 수치 목록·목표 자리에 Skeleton(`text`). 기간 선택은 계속 바꿀 수 있고, 늦게 온 이전 기간 응답은 버린다 | 포커스는 SegmentedControl에 남는다 |
+| 실패 | 수치 목록·목표 자리에 Notice danger + `action` "다시 시도". 이전 기간 수치를 남겨 두지 않는다(기간과 수치가 어긋난다) | Web `danger`는 `role="alert"`, Native는 `announcement="assertive"` |
+| 기간 변경 | 수치·목표가 함께 바뀐다 | 포커스는 SegmentedControl에 남는다 |
+| 큰 글자 | Native SegmentedControl이 글자 배율 1.6 이상에서 세로로 쌓인다 | — |
+| 빈 값 | 스토리에 없다. 기간 안 데이터가 전혀 없으면 수치 목록 자리를 [EmptyState](../components/empty-state.md)로 바꾼다 | — |
+
+- 문구 키는 상태·기간별 상수로 둔다. 기간 이름으로 키를 조립하지 않는다.
+
+| 기간·상태 | 문구 키 |
+| --- | --- |
+| 주간 목표 | `sales.goal.week` |
+| 월간 목표 | `sales.goal.month` |
+| 실패 | `sales.loadFailed` |
+| 다시 시도 | `common.retry` |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Button } from "@hjmds/react/actions";
+import { Card, Statistic } from "@hjmds/react/display";
+import { Notice, Progress, Skeleton } from "@hjmds/react/feedback";
+import { Stack } from "@hjmds/react/layout";
+import { SegmentedControl } from "@hjmds/react/selection";
+
+// 기간 → 목표 문구 키
+const goalKey = { week: "sales.goal.week", month: "sales.goal.month" } as const;
+
+<Card title={t("sales.title")} description={t("sales.description")}>
+  <Stack gap="lg">
+    <SegmentedControl label={t("sales.period")} value={period} onValueChange={changePeriod} items={periods} />
+    {status === "loading"
+      ? <Stack gap="md"><Skeleton shape="text" /><Skeleton shape="text" /><Skeleton shape="text" width="60%" /></Stack>
+      : status === "failed"
+        ? <Notice tone="danger" title={t("sales.loadFailed")}
+            action={<Button tone="secondary" size="small" onClick={retry}>{t("common.retry")}</Button>} />
+        : <>
+            <Stack gap="md">{data.items.map((item) => <Statistic key={item.id} descriptor={item} />)}</Stack>
+            <Progress label={t(goalKey[period])} value={data.goal} valueText={formatPercent(data.goal)} />
+          </>}
+  </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, Statistic } from "@hjmds/react-native/data-display";
+import { Notice, Progress, Skeleton } from "@hjmds/react-native/feedback";
+import { SegmentedControl } from "@hjmds/react-native/inputs";
+import { Container, Stack } from "@hjmds/react-native/primitives";
+
+const goalKey = { week: "sales.goal.week", month: "sales.goal.month" } as const;
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container gutter={gutter}>
+    <Card title={t("sales.title")} description={t("sales.description")}>
+      <Stack gap="lg">
+        <SegmentedControl label={t("sales.period")} value={period} onValueChange={changePeriod} items={periods} />
+        {status === "loading"
+          ? <Stack gap="md"><Skeleton shape="text" accessibilityLabel={t("sales.loading")} /><Skeleton shape="text" /><Skeleton shape="text" width="60%" /></Stack>
+          : status === "failed"
+            ? <Notice tone="danger" announcement="assertive" title={t("sales.loadFailed")}
+                action={<Button tone="secondary" size="small" onPress={retry}>{t("common.retry")}</Button>} />
+            : <>
+                <Stack gap="md">{data.items.map((item) => <Statistic key={item.id} descriptor={item} />)}</Stack>
+                <Progress label={t(goalKey[period])} value={data.goal} valueText={formatPercent(data.goal)} />
+              </>}
+      </Stack>
+    </Card>
+  </Container>
+</ScrollView>;
+```
+
+Statistic descriptor는 `{ id, label, value(포맷 끝난 문자열), suffix, trend: { direction, tone, label } }`이다. 수치·문구·목표는 제품 데이터다.
+
+## 함정
+
+- 증감을 색만으로 전하지 않는다. `trend.label`은 필수이고 비교 기준("지난주보다")을 문구에 넣는다.
+- 목표 라벨을 기간과 따로 고정하면("월 목표") 주간 비교와 섞여 읽힌다. 기간과 함께 바꾼다.
+- 로딩·실패 자리를 Fragment로 바꿔 넣으면 수치 목록과 Progress가 바깥 `Stack gap="lg"`의 직계 자식으로 남는다. 둘을 한 `Stack`으로 묶으면 사이가 `spacing.lg` 20에서 바뀐다.
+- `onValueChange`는 `string`을 넘긴다. 기간 타입으로 좁힐 때 허용 값인지 확인하고 바꾼다(스토리는 `as StatPeriod`로 단언한다).
+- 현재 스토리는 로컬 데이터라 로딩·실패 경로가 없고, 목표 값 문구를 `` `${goal}%` ``로 이어 붙인다. 퍼센트 표기는 로케일 포맷(`formatPercent`)으로 만든다.

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

@@ -0,0 +1,174 @@
+# 시간 선택
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `showcase/web/src/patterns/TimeSelection.stories.tsx`, `showcase/native/src/TimeSelection.stories.tsx`, `showcase/native/src/pattern-status.tsx`, `showcase/shared/time-example.ts`, `src/foundations.ts`(`control`, `spacing`), `src/component-recipes.ts`(`stackRecipe`, `sectionRecipe`), `src/container.ts`
+- 스토리북: `배포/구성/선택과 필터/시간 선택`
+
+## 언제 쓰나
+
+알림 시각·마감 시각처럼 하루 안의 시각 하나를 시·분 두 Select로 나눠 고르게 할 때 쓴다. 둘 다 고른 뒤에만
+확정 버튼이 열리고, 확정하면 같은 흐름 아래에 성공 Notice가 붙는다. 날짜까지 함께 고르면
+[DatePicker](../components/date-picker.md)를, 길이(시·분·초)를 고르면 `DurationField`([NumberField](../components/number-field.md) 지침)를 먼저 검토한다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `Section` | 제목과 한 줄 설명(양쪽 모두 Section) | [Section](../components/section.md) |
+| `Stack` `gap="md"` | 세로 흐름 전체 | [Stack](../components/stack.md) |
+| `Select` × 2 | 시(0~23), 분(0~59). 항목은 `{ id, label, textValue }` | [Select](../components/select.md) |
+| 상태 문구 `Text` | "선택한 시각 HH:MM" 또는 "시와 분을 모두 선택해 주세요". Web `role="status"`, Native live region(iOS는 announce 보완) | [Text](../components/text.md) |
+| `Button` `tone="primary"` | 선택 완료. 둘 다 고르기 전엔 `disabled`, 저장 중 `loading` | [Button](../components/button.md) |
+| `Button` `tone="ghost"` | 다시 고르기(두 값과 결과를 비움) | [Button](../components/button.md) |
+| `Notice` `tone="success"` / `"danger"` | 확정 결과 / 저장 실패. 결과가 나기 전엔 마운트하지 않는다 | [Notice](../components/notice.md) |
+| `ScrollView` + `Container`(Native) | 바깥 틀. 세로 스크롤·위아래 여백, 좌우 gutter | [Container](../components/container.md), [화면 여백과 너비](../tokens/layout.md) |
+
+## 배치
+
+```text
+Native 화면(ScrollView, 위아래 spacing.lg 20) > Container gutter 16(폭 < 600) · 20(폭 ≥ 600)
+┌ Section(스크롤과 함께 흐름) ───────────┐
+│ 제목 (Section title)                   │
+│ 설명 (muted)                           │  제목–설명 spacing.xxs 4
+│            ↕ spacing.xs 8              │  머리–내용(sectionRecipe.gap)
+│ 시                                     │
+│ [ 시 선택                        ▾ ]   │  필드 높이 44
+│            ↕ spacing.md 16             │
+│ 분                                     │
+│ [ 분 선택                        ▾ ]   │
+│            ↕ spacing.md 16             │
+│ 선택한 시각 09:30        ← 상태 문구   │
+│            ↕ spacing.md 16             │
+│ [            선택 완료             ]   │  ← 주 행동(primary), 꽉 찬 폭
+│            ↕ spacing.md 16             │
+│ [            다시 고르기           ]   │  ← 보조 행동(ghost)
+│            ↕ spacing.md 16             │
+│ ┌ ✓ 시간을 정했어요 · 09:30 ────────┐  │  ← 확정 후에만
+│ └────────────────────────────────────┘  │
+└────────────────────────────────────────┘
+  고정 영역 없음. 안전 영역은 화면 골격이 맡는다
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Web: 제품 화면 레이아웃(문서 스크롤). Native: `ScrollView` > `Container` | 이 구성은 바깥 폭·여백을 정하지 않는다(Web 스토리는 Section만 그린다). Native는 `ScrollView` 안 [Container](../components/container.md)에 둔다. Select는 키보드 대신 목록 표면(Web popover, Native modal sheet)을 열어 키보드 처리는 없다. 안전 영역은 화면 골격(내비게이션 헤더·탭 바)이 맡는다 | Native ScrollView 위아래 `spacing.lg` 20, Container gutter 폭 600 미만 `compact` 16 · 이상 `regular` 20(`layout.pagePadding`) |
+| 머리 | Section 제목·설명 | 흐름 맨 위, 스크롤과 함께 | 제목–설명 `spacing.xxs` 4, 머리–내용 `spacing.xs` 8 |
+| 입력 | Select 시 → 분 | 머리 아래, 시가 먼저 | 필드 `control.fieldHeight` 44, 사이 `spacing.md` 16 |
+| 상태 | 상태 문구 | 입력 바로 아래 | 위 `spacing.md` 16 |
+| 행동 | Button primary → ghost | 상태 아래, 세로로 쌓음. Stack 기본 `align="stretch"`라 꽉 찬 폭 | 높이 `control.buttonHeight.medium` 44, 사이 `spacing.md` 16 |
+| 결과 | Notice success / danger | 행동 아래 | 위 `spacing.md` 16 |
+
+- 주 행동이 위, 되돌리기(ghost)가 아래다. 가로로 놓아야 하면 [Button 배치](../components/button.md#배치)의 보조 → 주 순서를 따른다.
+- 이 구성에는 고정 영역이 없다. 긴 화면 하단에 확정을 고정해야 하면 "선택 완료"를 [BottomCTA](../components/bottom-cta.md)로 옮긴다.
+
+## 흐름과 상태
+
+1. 시 Select를 연다(Web은 트리거에 붙은 listbox popover, Native는 modal sheet) → 시를 고른다.
+2. 분 Select를 같은 방식으로 고른다. 어느 값을 바꿔도 이전 확정 결과를 지운다.
+3. 두 값이 모두 있으면 상태 문구가 시각으로 바뀌고 "선택 완료"가 활성화된다.
+4. "선택 완료" → (서버에 저장하면 버튼 `loading`) → success Notice가 붙는다. "다시 고르기" → 두 Select와 Notice를 비운다.
+5. 저장이 실패하면 danger Notice가 붙고 고른 값은 그대로 남아 "선택 완료"를 다시 누를 수 있다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 두 Select에 placeholder, 상태 문구 "시와 분을 모두 선택해 주세요", 선택 완료 `disabled` | 상태 문구가 live region |
+| 하나만 고름 | 초기와 같은 상태 문구, 선택 완료 `disabled` | — |
+| 둘 다 고름 | 상태 문구에 "선택한 시각 HH:MM", 선택 완료 활성 | 상태 문구 변경을 알린다(Native iOS는 announce 보완) |
+| 진행 중 | 서버에 저장하는 제품이면 선택 완료 `loading`, 두 Select `busy`(포커스 순서 유지, 조작 막음), 다시 고르기 `disabled` | 포커스는 버튼에 남는다 |
+| 실패 | 행동 아래 Notice danger(값 유지), 선택 완료 다시 활성 | Web `danger`는 `role="alert"`, Native는 `announcement="assertive"` |
+| 확정 | 행동 아래 Notice success | Web Notice는 `role="status"`로 알린다. Native는 `announcement="polite"`를 줘야 알린다. 포커스는 버튼에 남는다 |
+
+- Select는 선택 해제가 기본 허용이라 `onSelectionChange`에 `null`이 올 수 있다. 값은 `string | null`로 둔다.
+- 값은 `"HH"`·`"MM"` 문자열 키다. 시간대·예약 계산은 제품 소유다.
+- 문구 키는 상태별 상수로 둔다. 상태 이름으로 키를 조립하지 않는다.
+
+| 상태 | 상태 문구 키 | Notice 키 |
+| --- | --- | --- |
+| 기본·하나만 고름 | `reminder.time.incomplete` | — |
+| 둘 다 고름 | `reminder.time.selected`(`value`) | — |
+| 실패 | 둘 다 고름과 같다 | `reminder.time.saveFailed` |
+| 확정 | 둘 다 고름과 같다 | `reminder.time.saved` |
+
+## 코드 골격
+
+```tsx
+// Web
+import { Select } from "@hjmds/react/forms";
+import { Button } from "@hjmds/react/actions";
+import { Section, Stack, Text } from "@hjmds/react/layout";
+import { Notice } from "@hjmds/react/feedback";
+
+<Section title={t("reminder.time.title")} description={t("reminder.time.description")}>
+  <Stack gap="md">
+    <Select label={t("reminder.time.hour")} placeholder={t("reminder.time.hourPlaceholder")}
+      emptySelectionLabel={t("reminder.time.hourClear")} busy={saving}
+      items={hourOptions} selectedKey={hour} onSelectionChange={changeHour} />
+    <Select label={t("reminder.time.minute")} placeholder={t("reminder.time.minutePlaceholder")}
+      emptySelectionLabel={t("reminder.time.minuteClear")} busy={saving}
+      items={minuteOptions} selectedKey={minute} onSelectionChange={changeMinute} />
+    <Text role="status">{value ? t("reminder.time.selected", { value }) : t("reminder.time.incomplete")}</Text>
+    <Button disabled={!value} loading={saving} onClick={confirm}>{t("reminder.time.confirm")}</Button>
+    <Button tone="ghost" disabled={saving} onClick={reset}>{t("reminder.time.reset")}</Button>
+    {result === "saved" && value ? <Notice tone="success" title={t("reminder.time.saved")} description={value} /> : null}
+    {result === "failed" ? <Notice tone="danger" title={t("reminder.time.saveFailed")} /> : null}
+  </Stack>
+</Section>;
+```
+
+```tsx
+// Native
+import { ScrollView, useWindowDimensions } from "react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
+import { Select } from "@hjmds/react-native/forms";
+import { Button } from "@hjmds/react-native/actions";
+import { Container, Section, Stack, Text } from "@hjmds/react-native/primitives";
+import { Notice } from "@hjmds/react-native/feedback";
+
+const { width } = useWindowDimensions();
+const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
+
+<ScrollView contentContainerStyle={{ paddingVertical: spacing.lg }}>
+  <Container gutter={gutter}>
+    <Section title={t("reminder.time.title")} description={t("reminder.time.description")}>
+      <Stack gap="md">
+        <Select label={t("reminder.time.hour")} placeholder={t("reminder.time.hourPlaceholder")}
+          dismissLabel={t("reminder.time.hourClose")} busy={saving}
+          items={hourOptions} selectedKey={hour} onSelectionChange={changeHour} />
+        <Select label={t("reminder.time.minute")} placeholder={t("reminder.time.minutePlaceholder")}
+          dismissLabel={t("reminder.time.minuteClose")} busy={saving}
+          items={minuteOptions} selectedKey={minute} onSelectionChange={changeMinute} />
+        {/* iOS는 live region을 무시하므로 문구가 바뀔 때 AccessibilityInfo.announceForAccessibility로 보완한다 */}
+        <Text accessibilityLiveRegion="polite">{value ? t("reminder.time.selected", { value }) : t("reminder.time.incomplete")}</Text>
+        <Button disabled={!value} loading={saving} onPress={confirm}>{t("reminder.time.confirm")}</Button>
+        <Button tone="ghost" disabled={saving} onPress={reset}>{t("reminder.time.reset")}</Button>
+        {result === "saved" && value ? <Notice tone="success" announcement="polite" title={t("reminder.time.saved")} description={value} /> : null}
+        {result === "failed" ? <Notice tone="danger" announcement="assertive" title={t("reminder.time.saveFailed")} /> : null}
+      </Stack>
+    </Section>
+  </Container>
+</ScrollView>;
+```
+
+`hourOptions`·`minuteOptions`(항목 라벨 "9시"·"30분")와 문구는 제품 소유이며 라벨도 i18n으로 만든다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 목록 표면 | 트리거에 붙은 listbox popover | modal sheet |
+| 필수 문구 | `emptySelectionLabel`(선택 해제 항목) | `dismissLabel`(시트 닫기) |
+| 상태 문구 낭독 | `role="status"` | `accessibilityLiveRegion`(Android), iOS는 `announceForAccessibility`로 보완(스토리 `PatternStatus`) |
+| 테마·글자 스토리 | 기본·어두운 테마·큰 글자(textScale 2) | 기본·어두운 테마·큰 글자(textScale 2) |
+| 확정 Notice 발표 | 늘 live region | `announcement`를 지정해야 발표(기본 `none`) |
+| 바깥 틀 | 제품 화면 레이아웃(문서 스크롤) | `ScrollView` > `Container` |
+
+## 함정
+
+- 값을 바꾸면 이전 확정 결과(`result`)를 지운다. 남겨 두면 새로 고른 시각과 다른 확정 Notice가 보인다.
+- 스토리의 확정은 로컬 상태만 바꾼다. 서버 저장의 진행·실패·재시도 검증을 대신하지 않는다.
+- 2026-10-06 검수에서 예제도 Container·Section·Text와 Native 확정 Notice의 `announcement="polite"`를 사용하도록 맞췄다. 제목 의미와 iOS 알림을 개별 View/Text 스타일로 다시 만들지 않는다.

package/docs/usage/compositions/toast-layout.md

@@ -0,0 +1,128 @@
+# 토스트 배치 비교
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Toast](../../toast.md), `showcase/web/src/components/ToastLayout.stories.tsx`, `src/component-recipes.ts`(`toastRecipe`), `src/toast.ts`, `packages/react/src/styles.css`(`.hjm-toast-viewport`, `.hjm-toast`), `packages/react/src/toast.tsx`
+- 스토리북: `배포/구성/비교와 검증/토스트 배치 비교`
+
+## 언제 쓰나
+
+Toast 카드 한 장의 내부 배치(톤 배지·제목·설명·닫기·실행 버튼)와 화면 위 위치를 좁은 폭·큰 글자·긴 문구·톤별로 확인하는 비교 스토리다.
+소비자는 이 결과로 "문구를 얼마나 길게 둘지, 실행 버튼을 둘지, 어떤 tone을 쓸지"를 고른다.
+
+| 스토리 | 비교하는 것 | 소비자가 고를 기준 |
+| --- | --- | --- |
+| 간결한 배치 | mobile1 viewport에서 설명 한 줄 카드 | 기본 알림은 `description` 한 줄로 끝낸다 |
+| 리퀴드 효과 대체 표시 | `presentation: "liquid"` descriptor를 Web이 표준 카드로 그림 | 공유 descriptor에 `liquid`를 넣어도 Web은 표준 카드 + 실행 버튼을 유지한다 |
+| 긴 문구와 실행 버튼 | 좁은 폭 + textScale 2 + 혼합 언어 긴 문구 + `dismissOnAction: false` | 긴 문구는 줄바꿈되고 잘리지 않는다. 실행 후에도 남아야 하는 행동(다시 시도)은 `dismissOnAction: false` |
+| 상태별 비교 | neutral·success·info·warning·danger 다섯 장, 실행 버튼 유무 | tone은 결과의 의미로 고른다. 실행 버튼은 그 알림이 아니어도 할 수 있는 행동일 때만 둔다 |
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| `ToastProvider` + `useToast` | 앱 루트에 하나. viewport·큐·타이머 | [Toast](../components/toast.md) |
+| `Toast` | controlled 카드 한 장(스토리가 직접 그림) | [Toast](../components/toast.md) |
+| descriptor `action` | 끝 정렬 알약 버튼 하나 | [Toast](../components/toast.md) |
+
+## 배치
+
+```text
+화면(좁은 폭, placement="bottom" 기본)
+┌──────────────────────────────────────┐
+│                                      │
+│          (콘텐츠, 스크롤)            │
+│                                      │
+│ ┌ Toast ───────────────────────────┐ │ ← 좌우 max(spacing.md 16, 안전 영역)
+│ │ (●) 연결을 확인해 주세요     [×] │ │    배지 32 · 제목 굵게 · 닫기 44×44
+│ │     Your changes remain …        │ │    설명(보조 색)
+│ │                  [ 다시 시도 ]   │ │ ← 실행 버튼: 둘째 줄, 끝 정렬, 높이 44
+│ └──────────────────────────────────┘ │
+│   ↕ max(spacing.md 16, 하단 안전 영역) + bottomOffset
+└──────────────────────────────────────┘
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | `ToastProvider` viewport(앱 루트 하나) | 화면 콘텐츠·스크롤 위에 `position: fixed`로 떠 있다. 콘텐츠 스크롤과 무관하고 콘텐츠 여백을 바꾸지 않는다. 안전 영역은 viewport가 `env(safe-area-inset-*)`로 직접 피한다. 하단 고정 바는 `bottomOffset`으로 피한다. 모바일 Web 화면 키보드는 따로 피하지 않는다 | 가장자리 `max(spacing.md 16, safe-area)`, `layer.toast` 1000, viewport는 포인터를 통과시킨다(`pointer-events: none`, 카드만 받음) |
+| viewport | `ToastProvider` | 화면 고정(`position: fixed`), 기본 하단 가운데. `top`·`top-start`·`top-end`·`bottom-start`·`bottom-end` 선택 | 가장자리 `max(spacing.md 16, safe-area)`, 최대 폭 `min(420, 100vw - 32)`, 카드 사이 `spacing.sm` 12. 하단이면 새 카드가 아래부터 쌓인다 |
+| 카드 | `Toast` | viewport 안 | 최소 높이 3.5rem, padding 위아래 `spacing.sm` 12·시작 `spacing.md` 16·끝 `spacing.xs` 8, 열 간격 `spacing.sm` 12, radius `lg` 16 |
+| 배지 | tone 아이콘 | 첫 줄 시작 | 지름 `toastRecipe.icon.badgeDiameter` 32 |
+| 문구 | 제목 + 설명 | 첫 줄 가운데, 남은 폭 전부 | 제목–설명 `spacing.xxs` 4, `word-break: keep-all`, 잘림 없음 |
+| 닫기 | IconButton | 첫 줄 끝 | `control.minTouchTarget` 44 × 44 |
+| 실행 | 알약 버튼 | 둘째 줄, 문구 열부터 끝까지, 끝 정렬 | 최소 높이 44, 좌우 `spacing.md` 16, 줄 간격 `spacing.xs` 8 |
+
+- 하단에 고정 바(BottomNavigation·BottomCTA)가 있으면 `bottomOffset`으로 그 높이만큼 띄운다.
+- 한 번에 보이는 카드는 `maxVisible` 1(기본)이다. 상태별 비교 스토리의 다섯 장 겹침은 비교용이며 실제 화면 모습이 아니다.
+
+## 흐름과 상태
+
+1. 행동 결과가 나오면 `useToast().publish(descriptor)`를 부른다. 문구 키는 결과별 상수로 둔다(아래 `toastCopy`).
+2. 카드가 viewport에 나타나고 기본 3000ms 뒤 닫힌다(포인터·포커스가 올라가 있으면 멈춘다).
+3. 실행 버튼을 누르면 `onAction` 후 기본으로 닫힌다(`dismissOnAction: false`면 남는다). 닫기 버튼은 즉시 닫는다.
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 결과 한 줄(`description`), tone은 결과 의미, 3000ms 뒤 자동 닫힘 | 낭독은 `priority`가 정한다 |
+| 진행 중 | 오래 걸리는 작업의 진행은 같은 `id`로 다시 `publish`해 카드 하나를 갱신한다(새 카드를 쌓지 않는다). 진행률 자체는 화면의 [Progress](../components/progress.md)가 맡는다 | 같은 카드가 갱신된다 |
+| 실패 | `tone: "danger"` + 실행 버튼 "다시 시도"(`dismissOnAction: false`면 다시 시도 후에도 남는다). 실패를 Toast로만 알리면 사라진 뒤 다시 찾을 수 없으므로, 되돌릴 수 없는 실패는 화면 안 [Notice](../components/notice.md)·Result로 남긴다 | `priority`로 낭독 긴급도를 정한다 |
+| neutral | 회색 배지 + 알림 아이콘 | 낭독은 `priority`가 정하고 tone과 무관 |
+| success·info·warning | 각 feedback 배지 색 + 아이콘 | 같음 |
+| danger | danger 배지 + 경고 아이콘, 흔히 "다시 시도" 실행 | 같음 |
+| 실행 버튼 있음 | 둘째 줄 알약 버튼, `durationMs` 기본은 수동 닫기까지 유지 | 포커스가 카드에 있으면 타이머 정지 |
+| 큰 글자·긴 문구 | 문구가 여러 줄로 늘고 카드가 길어진다. 버튼 라벨도 줄바꿈 | — |
+| 닫히는 중 | 투명해지며 `spacing.xs` 8만큼 내려감. 모션 감소면 이동 없음 | — |
+
+## 코드 골격
+
+```tsx
+// Web
+import { ToastProvider, useToast } from "@hjmds/react/toast";
+
+// 앱 루트에 한 번
+<ToastProvider label={t("common.notifications")} bottomOffset={dockHeight}>{children}</ToastProvider>;
+
+// 결과 → 문구 키. 결과 이름으로 키를 조립하지 않는다.
+const toastCopy = {
+  saving: { title: "sync.savingTitle", description: "sync.savingBody" },
+  failed: { title: "sync.offlineTitle", description: "sync.offlineBody" },
+} as const;
+
+// 화면에서
+const toast = useToast();
+toast.publish({
+  id: "sync",
+  tone: "danger",
+  title: t(toastCopy.failed.title),
+  description: t(toastCopy.failed.description),
+  closeLabel: t("common.closeNotification"),
+  action: { label: t("sync.retry"), onAction: retry, dismissOnAction: false },
+});
+```
+
+```tsx
+// Native
+// 이 스토리는 Web 전용이다. Native 배치는 ToastRegion(`@hjmds/react-native/feedback`)을 쓰고
+// safeAreaInsets·keyboardOffset을 제품이 넘긴다. 자세한 것은 Toast 컴포넌트 지침을 본다.
+```
+
+스토리의 문구(번뚝 타이머 등)는 예시다. 문구·id·action은 제품 소유, 카드 모양·큐·타이머는 HJM 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 큐·영역 | `ToastProvider`·`useToast` | `ToastRegion`·`useToastRegion` |
+| 하단 고정 바 회피 | `bottomOffset` | `keyboardOffset` |
+| 안전 영역 | `env(safe-area-inset-*)` | `safeAreaInsets` prop(기본 `{}`) |
+| `presentation: "liquid"` | 표준 카드로 대체 | `/toast-liquid`의 `createLiquidToastPresentation`을 등록하면 리퀴드 표현 |
+
+## 함정
+
+- `durationMs`를 3000보다 짧게 줘도 3000으로 올라간다.
+- 카드 색·배지·radius를 `className`으로 덮지 않는다. 톤 색은 `toastRecipe.tones`가 정한다.
+- 화면마다 Provider를 새로 만들지 않는다. 같은 진행을 갱신할 때는 같은 `id`로 다시 `publish`한다.
+- 현재 스토리는 `Toast` 카드만 직접 그리고 viewport(`ToastProvider`)를 띄우지 않는다. 화면 위 위치·안전 영역·`bottomOffset`은 스토리로 확인되지 않고 위 표의 값은 `.hjm-toast-viewport` CSS에서 확인했다.