@hjmds/design-contracts 1.18.0 → 1.19.0

package/docs/usage/screens/discovery-gallery.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-06
+- 검토일: 2026-10-13
 - 근거: `showcase/web/src/patterns/DiscoveryGallery.stories.tsx`, `showcase/native/src/DiscoveryGallery.stories.tsx`, `showcase/shared/discovery-gallery.ts`, `src/base-recipes.ts`(`buttonRecipe.states.selected`), `src/grid.ts`
 - 스토리북: `배포/화면/검색/작품 탐색`
 
@@ -28,7 +28,7 @@
 │   작품 검색 (보이는 라벨)                                    │
 │   [🔍 모바일, 작업 공간 ...........  (x)]                  │  SearchField 최소 44
 │              ↕ spacing.xl 24                               │
-│ ② [전체] [웹사이트] [모바일] [대시보드]                       │  ghost, 선택된 것만 selected
+│ ② [전체] [웹사이트] [모바일] [대시보드]                       │  SegmentedControl pills, 단일 선택
 │ ③ [정렬: 인기순] [저장한 작품 2]                             │  secondary(정렬) · ghost+selected(저장만 보기)
 │ ④ "N개의 작품"  (상태 알림)                                 │
 │ (오류면 여기 Notice danger + [다시 시도])                    │
@@ -76,9 +76,9 @@
 | 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
 | --- | --- | --- | --- |
 | 검색 | SearchField `onValueChange` | ① 맨 아래 | 1. 입력 즉시 거른다 |
-| 카테고리 | Button `ghost`, 선택된 것만 `selected` | ② | 카테고리 수, "전체"가 맨 앞 |
+| 카테고리 | SegmentedControl `presentation="pills"` | ② | 카테고리 수, "전체"가 맨 앞 |
 | 정렬 전환 | Button `secondary`, 라벨에 현재 값(`t("gallery.sort", { value: t(sortKey[sort]) })`) | ③ 첫 자리 | 1. 누를 때마다 인기순 ↔ 최신순 |
-| 저장한 작품만 | SegmentedControl `presentation="pills"`, 라벨에 개수 | ③ 정렬 뒤 | 1 |
+| 저장한 작품만 | Button `ghost` + `selected`, 라벨에 개수 | ③ 정렬 뒤 | 1 |
 | 상세 보기 | Button `ghost` | 카드 맨 아래 버튼 줄 첫 자리 | 카드마다 1. `aria-label`/`accessibilityLabel`에 작품 제목 포함 |
 | 카드 저장 | Button `secondary` + `selected`(토글) | 카드 버튼 줄 둘째 자리 | 카드마다 1. 라벨 "저장" ↔ "저장됨", 접근성 이름에 제목과 저장/저장 취소 |
 | 시트 저장(시트의 주 행동) | Button 기본 primary + `selected` | ⑦ Sheet `footer`(Native 꽉 찬 폭, Web 끝 정렬) | 1. 라벨 "컬렉션에 저장" ↔ "저장 취소". 시트를 닫지 않는 토글이다 |
@@ -87,7 +87,7 @@
 | 파괴 행동 | — | — | 없음(저장 취소는 같은 버튼의 토글) |
 
 primary는 화면에서 빈 결과 복구 하나, 시트 안에서 저장 하나다. 시트 안 행동은 그 표면 안에서 세고, `selected`를 준 버튼은
-tone과 관계없이 선택 모양(배경 `bg`, 글자·테두리 `contentBrand`)으로 칠해져 세지 않는다([Button](../components/button.md) "꼭 지킬 것").
+tone과 관계없이 선택 모양(배경 `bg`, 글자 `contentBrand`, 별도 선택 테두리 없음)으로 칠해져 세지 않는다([Button](../components/button.md) "꼭 지킬 것").
 카드 안 버튼은 [보기][저장] 순서로 시작 정렬, `wrap`이다. 카드 전체를 누름 대상으로 만들지 않는다 — 카드 안에 버튼이 둘이라
 겹친 누름 대상이 된다.
 
@@ -96,9 +96,9 @@ tone과 관계없이 선택 모양(배경 `bg`, 글자·테두리 `contentBrand`
 | 상태 | 화면 모습 | 행동 |
 | --- | --- | --- |
 | 기본 | "전체"·인기순, 전체 카드, 결과 수 | 검색·필터·정렬·저장·보기 |
-| 로딩 | 스토리에 없음. ①~③은 그대로, ⑤ 자리에 같은 Grid로 카드 3개 모양의 [Skeleton](../components/skeleton.md)(AspectRatio 1.6 안 `shape="block"` `height="100%"` + 제목 `shape="text"` 60%). 로딩 사실은 영역 단위로 한 번(Web Grid `aria-busy`·`aria-label`, Native 첫 Skeleton `accessibilityLabel`). 검색 중이면 SearchField Web `loading` · Native `busy` + `busyLabel` | 검색·필터는 그대로 |
-| 빈 | ⑤ 자리에 EmptyState(`t("gallery.empty.title")`, 설명) | [필터 초기화] |
-| 오류 | 스토리에 없음. ①~③은 남기고 ④ 아래 [Notice](../components/notice.md) `tone="danger"`(Native `announcement="assertive"` — 기본 `none`). 문구는 원인별 키(`errorKey`: 네트워크 `gallery.error.network`, 서버 `gallery.error.server`). 이전 결과가 있으면 ⑤를 유지하고, 결과가 없으면 EmptyState를 그리지 않는다(빈 결과와 실패를 섞지 않는다). 다시 시도가 또 실패하면 같은 Notice를 같은 자리에 두고 버튼 `loading`만 푼다 | Notice `action` 다시 시도 1개 |
+| 로딩 | 동기 스토리에 없음. 제품 최초 조회는 ScreenLayout 본문 중앙 spinner, 재조회는 기존 결과와 검색·필터를 유지한다 | 같은 요청 중복 실행 방지 |
+| 빈 | 성공 응답 0건일 때만 ScreenLayout 본문 중앙 빈 상태(`t("gallery.empty.title")`, 설명) | [필터 초기화] |
+| 오류 | 스토리에 없음. ①~③은 남기고 ④ 아래 [Notice](../components/notice.md) `tone="danger"`(Native `announcement="assertive"` — 기본 `none`). 문구는 원인별 키(`errorKey`: 네트워크 `gallery.error.network`, 서버 `gallery.error.server`). 이전 결과가 있으면 ⑤를 유지하고, 첫 조회 실패면 ScreenLayout 중앙 오류와 재시도를 사용하고 EmptyState를 그리지 않는다(빈 결과와 실패를 섞지 않는다). 다시 시도가 또 실패하면 같은 Notice를 같은 자리에 두고 버튼 `loading`만 푼다 | Notice `action` 다시 시도 1개 |
 | 저장 토글 | 카드 버튼이 `selected`로 바뀌고 ③ 저장 개수가 늘어난다. 저장만 보기 중 저장 취소하면 카드가 사라지고 결과 수가 읽힌다 | — |
 | 상세 열림 | 시트가 올라오고 같은 그림을 크게 보인다. 시트에서 저장하면 카드 상태도 같이 바뀐다 | 저장·닫기 |
 
@@ -115,7 +115,7 @@ tone과 관계없이 선택 모양(배경 `bg`, 글자·테두리 `contentBrand`
 | [Grid](../components/grid.md) | ⑤ 카드 격자 |
 | [AspectRatio](../components/aspect-ratio.md) · [Image](../components/image.md) | 제품의 실제 썸네일, 로딩 Skeleton 틀 |
 | [EmptyState](../components/empty-state.md) | 결과 없음 |
-| [Skeleton](../components/skeleton.md) | 로딩 |
+| [Skeleton](../components/skeleton.md) | 로딩 | 동기 스토리에 없음. 제품 최초 조회는 ScreenLayout 본문 중앙 spinner, 재조회는 기존 결과와 검색·필터를 유지한다 | 같은 요청 중복 실행 방지 |
 | [Notice](../components/notice.md) | 오류 |
 | [Sheet](../components/sheet.md) | ⑦ 상세 |
 | [화면 여백과 너비](../tokens/layout.md) | gutter·최대 폭·breakpoint |
@@ -123,155 +123,61 @@ tone과 관계없이 선택 모양(배경 `bg`, 글자·테두리 `contentBrand`
 
 ## 코드 골격
 
-카테고리·작품·썸네일·문구는 제품 소유다. `Thumbnail`은 제품 컴포넌트 자리다(AspectRatio 1.6 + Image). 상태마다 다른 문구는
-상태→키 상수 표로 고른다. 아래 두 예는 설치 버전 타입으로 검사했다(`query`·`results`·`selected` 등 상태 값과 핸들러는 제품이 둔다).
+동기 검색·카테고리·독립 저장 토글·상세 Sheet의 실행 원본은
+`showcase/web/src/patterns/DiscoveryGallery.stories.tsx`와
+`showcase/native/src/DiscoveryGallery.stories.tsx`다. 이 이름의 공개 화면 API는 없다.
+제품의 비동기 검색은 [검색 결과와 필터](common-search.md)의 SearchScreen을 먼저 검토한다.
+갤러리 격자가 필요하면 기존 Grid·Sheet와 아래 ScreenLayout 상태를 결합한다.
 
 ```tsx
 // Web
-import { AspectRatio, Container, Grid, Stack, Text } from "@hjmds/react/layout";
-import { Heading } from "@hjmds/react/heading";
+import { ScreenLayout } from "@hjmds/react/screens";
 import { Button } from "@hjmds/react/actions";
-import { SegmentedControl } from "@hjmds/react/selection";
-import { SearchField } from "@hjmds/react/forms";
-import { Sheet } from "@hjmds/react/overlays";
-import { EmptyState, Notice, Skeleton } from "@hjmds/react/feedback";
-import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
-
-type Category = "all" | "web" | "mobile" | "dashboard";
-type Sort = "popular" | "latest";
-type LoadError = "network" | "server";
-const categories: readonly Category[] = ["all", "web", "mobile", "dashboard"];
-const categoryKey = { all: "gallery.category.all", web: "gallery.category.web", mobile: "gallery.category.mobile", dashboard: "gallery.category.dashboard" } as const satisfies Record<Category, string>;
-const sortKey = { popular: "gallery.sort.popular", latest: "gallery.sort.latest" } as const satisfies Record<Sort, string>;
-const errorKey = { network: "gallery.error.network", server: "gallery.error.server" } as const satisfies Record<LoadError, string>;
-const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" : "regular";
-const gridProps = { columns: { compact: 1, medium: 2, expanded: 3 }, gap: { compact: "xl" }, minColumnWidth: { compact: 320 } } as const;
-
-<main><Container size="content" gutter={gutter}><Stack gap="xl">
-  <Stack gap="md">
-    <Text tone="brand">{t("gallery.eyebrow")}</Text>
-    <Heading level="level3" semanticLevel={1}>{t("gallery.title")}</Heading>
-    <Text as="p">{t("gallery.intro")}</Text>
-    <SearchField label={t("gallery.search")} clearLabel={t("gallery.clear")} loading={loading} value={query} onValueChange={setQuery} />
-  </Stack>
-  <SegmentedControl label={t("gallery.category")} presentation="pills"
-      items={categories.map(id => ({ value: id, label: t(categoryKey[id]) }))} value={category} onValueChange={setCategory} />
-  <Stack axis="inline" wrap gap="sm">
-    <Button tone="secondary" onClick={toggleSort}>{t("gallery.sort", { value: t(sortKey[sort]) })}</Button>
-    <Button tone="ghost" selected={savedOnly} onClick={() => setSavedOnly(v => !v)}>{t("gallery.savedOnly", { count: savedCount })}</Button>
-  </Stack>
-  <Text role="status">{loading ? "" : t("gallery.count", { count: results.length })}</Text>
-  {error ? <Notice tone="danger" title={t(errorKey[error])}
-    action={<Button tone="secondary" size="small" loading={retrying} onClick={retry}>{t("common.retry")}</Button>} /> : null}
-  {loading && results.length === 0 ? (
-    <Grid {...gridProps} aria-busy="true" aria-label={t("gallery.loading")}>
-      {[0, 1, 2].map(i => <Stack key={i} gap="sm"><AspectRatio ratio={1.6} aria-hidden="true"><Skeleton shape="block" height="100%" /></AspectRatio><Skeleton shape="text" width="60%" /></Stack>)}
-    </Grid>
-  ) : results.length ? (
-    <Grid {...gridProps}>
-      {results.map(item => <article key={item.id}><Stack gap="sm">
-        <Thumbnail item={item} />
-        <Text variant="label">{item.title}</Text>
-        <Text tone="muted">{t("gallery.meta", { author: item.author, category: item.categoryLabel })}</Text>
-        <Stack axis="inline" wrap gap="sm">
-          <Button tone="ghost" aria-label={t("gallery.viewNamed", { title: item.title })} onClick={() => setSelected(item)}>{t("gallery.details")}</Button>
-          <Button tone="secondary" selected={isSaved(item)} onClick={() => toggleSaved(item.id)}
-            aria-label={t(isSaved(item) ? "gallery.unsaveNamed" : "gallery.saveNamed", { title: item.title })}>
-            {t(isSaved(item) ? "gallery.saved" : "gallery.save")}</Button>
-        </Stack>
-      </Stack></article>)}
-    </Grid>
-  ) : error ? null : <EmptyState title={t("gallery.empty.title")} description={t("gallery.empty.body")}
-      action={<Button onClick={reset}>{t("gallery.reset")}</Button>} />}
-  <Sheet open={selected !== null} onOpenChange={o => { if (!o) setSelected(null); }}
-    title={selected?.title ?? t("gallery.detail")} closeLabel={t("common.close")}
-    footer={selected ? <Button selected={isSaved(selected)} onClick={() => toggleSaved(selected.id)}
-      aria-label={t(isSaved(selected) ? "gallery.unsaveNamed" : "gallery.saveNamed", { title: selected.title })}>
-      {t(isSaved(selected) ? "gallery.unsave" : "gallery.saveToCollection")}</Button> : null}>
-    {selected ? <Stack gap="lg">
-      <Thumbnail item={selected} />
-      <Text>{t("gallery.meta", { author: selected.author, category: selected.categoryLabel })}</Text>
-      <Text as="p">{selected.description}</Text>
-    </Stack> : null}
-  </Sheet>
-</Stack></Container></main>
+import { Notice } from "@hjmds/react/feedback";
+
+// hasLoaded는 성공한 조회가 있는지다. 0건 성공도 true이며 배열 길이로 대신하지 않는다.
+<>
+<ScreenLayout title={t("gallery.title")} actions={categoryControls}
+  notice={<>{searchAndSort}{hasLoaded && error ? <Notice tone="danger" title={t(errorKey[error])}
+    action={<Button tone="secondary" loading={retrying} onClick={retry}>{t("common.retry")}</Button>} /> : null}</>}
+  state={!hasLoaded
+    ? error ? { kind: "error", title: t(errorKey[error]) } : { kind: "loading", title: t("gallery.loading") }
+    : results.length === 0 ? { kind: "empty", title: t("gallery.empty.title") } : { kind: "ready" }}
+  stateAction={!hasLoaded && error ? <Button loading={retrying} onClick={retry}>{t("common.retry")}</Button>
+    : hasLoaded && results.length === 0 ? <Button onClick={reset}>{t("gallery.reset")}</Button> : null}>
+  {galleryGrid}
+</ScreenLayout>
+{detailSheet}
+</>
 ```
 
 ```tsx
 // Native
-import { ScrollView, useWindowDimensions } from "react-native";
-import { spacing } from "@hjmds/design-contracts/foundations";
-import { resolveWindowClass } from "@hjmds/design-contracts/responsive";
-import { AspectRatio, Container, Grid, Stack, Text } from "@hjmds/react-native/primitives";
-import { Heading } from "@hjmds/react-native/heading";
+import { ScreenLayout } from "@hjmds/react-native/screens";
 import { Button } from "@hjmds/react-native/actions";
-import { SegmentedControl } from "@hjmds/react-native/inputs";
-import { SearchField } from "@hjmds/react-native/inputs";
-import { Sheet } from "@hjmds/react-native/overlays";
-import { EmptyState, Notice, Skeleton } from "@hjmds/react-native/feedback";
-
-// categories·categoryKey·sortKey·errorKey는 Web과 같다.
-const { width } = useWindowDimensions();
-const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
-const gridProps = { columns: { compact: 1, medium: 2, expanded: 3 }, gap: { compact: "xl" }, minColumnWidth: { compact: 320 } } as const;
-
-<ScrollView automaticallyAdjustKeyboardInsets keyboardShouldPersistTaps="handled"
-  contentContainerStyle={{ paddingVertical: spacing.lg }}>
-  <Container size="content" gutter={gutter}><Stack gap="xl">
-    <Stack gap="md">
-      <Text tone="brand">{t("gallery.eyebrow")}</Text>
-      <Heading level="level3" semanticLevel={1}>{t("gallery.title")}</Heading>
-      <Text>{t("gallery.intro")}</Text>
-      <SearchField label={t("gallery.search")} clearLabel={t("gallery.clear")} busy={loading} busyLabel={t("gallery.searching")}
-        value={query} onValueChange={setQuery} />
-    </Stack>
-    <SegmentedControl label={t("gallery.category")} presentation="pills"
-      items={categories.map(id => ({ value: id, label: t(categoryKey[id]) }))} value={category} onValueChange={setCategory} />
-    <Stack axis="inline" wrap gap="sm">
-      <Button tone="secondary" onPress={toggleSort}>{t("gallery.sort", { value: t(sortKey[sort]) })}</Button>
-      <Button tone="ghost" selected={savedOnly} onPress={() => setSavedOnly(v => !v)}>{t("gallery.savedOnly", { count: savedCount })}</Button>
-    </Stack>
-    <Text accessibilityLiveRegion="polite">{loading ? "" : t("gallery.count", { count: results.length })}</Text>
-    {error ? <Notice tone="danger" announcement="assertive" title={t(errorKey[error])}
-      action={<Button tone="secondary" size="small" loading={retrying} onPress={retry}>{t("common.retry")}</Button>} /> : null}
-    {loading && results.length === 0 ? (
-      <Grid {...gridProps}>
-        {[0, 1, 2].map(i => <Stack key={i} gap="sm">
-          <AspectRatio ratio={1.6}><Skeleton shape="block" layoutStyle={{ flex: 1 }} {...(i === 0 ? { accessibilityLabel: t("gallery.loading") } : {})} /></AspectRatio>
-          <Skeleton shape="text" width="60%" />
-        </Stack>)}
-      </Grid>
-    ) : results.length ? (
-      <Grid {...gridProps}>
-        {results.map(item => <Stack key={item.id} gap="sm">
-          <Thumbnail item={item} />
-          <Text variant="label">{item.title}</Text>
-          <Text tone="muted">{t("gallery.meta", { author: item.author, category: item.categoryLabel })}</Text>
-          <Stack axis="inline" wrap gap="sm">
-            <Button tone="ghost" accessibilityLabel={t("gallery.viewNamed", { title: item.title })} onPress={() => setSelected(item)}>{t("gallery.details")}</Button>
-            <Button tone="secondary" selected={isSaved(item)} onPress={() => toggleSaved(item.id)}
-              accessibilityLabel={t(isSaved(item) ? "gallery.unsaveNamed" : "gallery.saveNamed", { title: item.title })}>
-              {t(isSaved(item) ? "gallery.saved" : "gallery.save")}</Button>
-          </Stack>
-        </Stack>)}
-      </Grid>
-    ) : error ? null : <EmptyState title={t("gallery.empty.title")} description={t("gallery.empty.body")}
-        action={<Button onPress={reset}>{t("gallery.reset")}</Button>} />}
-    <Sheet scrollable open={selected !== null} onOpenChange={o => { if (!o) setSelected(null); }}
-      title={selected?.title ?? t("gallery.detail")} closeLabel={t("common.close")}
-      footer={selected ? <Button fullWidth selected={isSaved(selected)} onPress={() => toggleSaved(selected.id)}
-        accessibilityLabel={t(isSaved(selected) ? "gallery.unsaveNamed" : "gallery.saveNamed", { title: selected.title })}>
-        {t(isSaved(selected) ? "gallery.unsave" : "gallery.saveToCollection")}</Button> : null}>
-      {selected ? <Stack gap="lg">
-        <Thumbnail item={selected} />
-        <Text>{t("gallery.meta", { author: selected.author, category: selected.categoryLabel })}</Text>
-        <Text>{selected.description}</Text>
-      </Stack> : null}
-    </Sheet>
-  </Stack></Container>
-</ScrollView>
+import { Notice } from "@hjmds/react-native/feedback";
+
+<>
+<ScreenLayout title={t("gallery.title")} actions={categoryControls}
+  notice={<>{searchAndSort}{hasLoaded && error ? <Notice tone="danger" announcement="assertive" title={t(errorKey[error])}
+    action={<Button tone="secondary" loading={retrying} onPress={retry}>{t("common.retry")}</Button>} /> : null}</>}
+  state={!hasLoaded
+    ? error ? { kind: "error", title: t(errorKey[error]) } : { kind: "loading", title: t("gallery.loading") }
+    : results.length === 0 ? { kind: "empty", title: t("gallery.empty.title") } : { kind: "ready" }}
+  stateAction={!hasLoaded && error ? <Button loading={retrying} onPress={retry}>{t("common.retry")}</Button>
+    : hasLoaded && results.length === 0 ? <Button onPress={reset}>{t("gallery.reset")}</Button> : null}>
+  {galleryGrid}
+</ScreenLayout>
+{detailSheet}
+</>
 ```
 
+위 ReactNode 슬롯은 제품이 기존 SearchField·SegmentedControl·Grid·Sheet로 구성한다.
+ScreenLayout host는 남은 본문 높이를 확보하고 로딩·오류·빈 상태를 그 영역 중앙에 둔다.
+재조회는 hasLoaded와 마지막 성공 결과를 유지한다. 검색어·필터·정렬을 request key에 넣고 응답 key가
+현재 선택과 같을 때만 적용한다. 이전 검색 결과를 유지하는 동안 그 결과의 현재성은 제품이 표시하고
+맞지 않는 항목의 확정 행동을 막는다. 저장 pending·실패는 해당 작품 ID별로 관리해 전체 격자를 교체하지 않는다.
+
 ## 큰 글자·다크·좁은 폭
 
 | 조건 | 바뀌는 것 |
@@ -287,7 +193,7 @@ const gridProps = { columns: { compact: 1, medium: 2, expanded: 3 }, gap: { comp
 | --- | --- | --- |
 | 격자 | Grid(폭은 `ResizeObserver`로 잰다), 사이 `spacing.xl` 24 | Grid(폭은 `onLayout`으로 잰다), 사이 `spacing.xl` 24 |
 | 그림 접근성 | `aria-hidden="true"` | `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` |
-| 결과 수 알림 | `role="status"` | 라이브 영역(Android) + iOS는 제품이 직접 알림(문구가 바뀌었을 때만, `AppState` active일 때만 — [대시보드](dashboard.md) 함정) |
+| 결과 수 알림 | `role="status"` | 공개 StatusText(Android live region + iOS active 문구 변경 알림 — [사용법](../components/text.md#statustext)) |
 | 검색 진행 | `loading` | `busy` + `busyLabel`(필수) |
 | 시트 footer | 오른쪽 정렬 가로 줄 | 세로 열, `fullWidth` |
 | 오류 Notice 알림 | `tone="danger"`가 알림 영역 | `announcement="assertive"`를 명시(기본 `none`) |
@@ -304,3 +210,6 @@ const gridProps = { columns: { compact: 1, medium: 2, expanded: 3 }, gap: { comp
 - 시트 확정 행동은 footer에 둔다. Native는 scrollable 본문과 분리해 큰 글자에서도 접근 가능하게 한다.
 - 현재 스토리의 카드 메타는 "작가 · 카테고리 · 좋아요 N"을 한국어 템플릿으로 조립한다. 제품은 `t("gallery.meta", { author, category })`처럼
   보간 키 하나로 둔다. 좋아요 수가 필요하면 같은 키에 값을 더한다.
+
+
+2026-10-13 행동 검수에서 제거/복구 뒤 키보드 문맥 유실을 확인해 보강했다. Web 저장만 보기에서 저장 취소로 카드가 사라지면 저장 필터로 초점을 돌린다. 상세를 닫을 때는 원래 상세 버튼, 해당 카드가 제거됐으면 저장 필터를 양 플랫폼 Sheet returnFocusRef로 지정한다. Web 빈 결과 초기화는 검색 필드로 이어진다. Native ref 연결과 실제 OS 접근성 초점 이동 검증은 구분한다.

package/docs/usage/screens/flow-collection.md

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/목록과 상세`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/콘텐츠/목록과 상세`
 
@@ -39,7 +39,24 @@ host: 남은 높이·safe area·키보드
 | 기본 | 목록 헤더 → 목록 → 더 보기 / 상세 헤더 → 상세 | 각 공개 콜백을 제품 상태에 연결 |
 | 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
 | 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
-| 오류 | 목록 pane 유지; 상세 실패는 detail.content 안에서 복구 | 실패 원인과 재시도 경로 제공 |
+| 오류 | 목록 pane 유지; 상세 실패는 detail.state·detail.stateAction으로 복구 | 실패 원인과 재시도 경로 제공 |
+
+### 목록과 상세의 독립 상태
+
+`state`는 목록에, `detail.state`는 상세에만 적용한다. 새 상세 prop은 미게시(1.18.0 이후)이며
+기존 `detail: { title, content }` 사용법은 그대로 유지한다. 목록 입력·스크롤을 보존한 채
+상세의 최초 조회·오류·재시도를 중앙 상태로 표현하려고 추가했다.
+
+| 상황 | 공개 슬롯 | 남겨야 하는 것 |
+| --- | --- | --- |
+| 상세 최초 조회 | detail.state=loading | 숨겨진 목록의 검색·선택·스크롤 |
+| 상세 조회 실패 | detail.state=error + detail.stateAction | 상세 제목·목록으로 돌아가기 |
+| 이미 읽은 상세 재조회 실패 | detail.state=ready + detail.notice | 기존 상세 내용 |
+| 목록 추가 조회 실패 | list 안 LoadMore | 이미 표시된 행·페이지 cursor |
+| 상세 닫기 | detail 생략 | 원래 목록으로 복귀, Web 원래 포커스 복원 |
+
+선택 id가 바뀌거나 상세를 닫으면 해당 요청을 취소하거나 늦은 응답을 무시한다.
+상세 요청 실패를 목록 `state=error`로 넘기면 복귀한 목록까지 사라진다.
 
 ## 사용하는 지침
 
@@ -59,7 +76,7 @@ import { ListDetailScreen } from "@hjmds/react/screen-flows";
 <ListDetailScreen
   title={t("orders.title")}
   list={<List label={t("orders.list")}>{rows}</List>}
-  {...(selected ? { detail: { title: selected.name, content: <OrderDetail order={selected} /> } } : {})}
+  {...(selected ? { detail: { title: selected.name, content: <OrderDetail order={selected} />, state: detailState, stateAction: detailRetry, notice: detailNotice } } : {})}
   back={{ label: t("common.back"), onAction: () => setSelected(null) }}
   refresh={{ label: t("common.refresh"), onAction: refetch, pending: isRefetching }}
 />
@@ -73,24 +90,36 @@ import { ListDetailScreen } from "@hjmds/react-native/screen-flows";
 <ListDetailScreen
   title={t("orders.title")}
   list={<List label={t("orders.list")}>{rows}</List>}
-  {...(selected ? { detail: { title: selected.name, content: <OrderDetail order={selected} /> } } : {})}
+  {...(selected ? { detail: { title: selected.name, content: <OrderDetail order={selected} />, state: detailState, stateAction: detailRetry, notice: detailNotice } } : {})}
   back={{ label: t("common.back"), onAction: () => setSelected(null) }}
   refresh={{ label: t("common.refresh"), onAction: refetch, pending: isRefetching }}
 />
 ```
 
+`detailState`는 `{ kind: "ready" }` 또는 지역화된 title을 가진 loading/error/restricted 상태다.
+`detailRetry`는 해당 id만 다시 조회하는 Button, `detailNotice`는 기존 상세를 유지하는 Notice다.
+
+<!-- usage-example: Web ../../../../../showcase/web/src/patterns/list-detail-recovery-preview.tsx -->
+- [Web 상세 복구 실행 예제](../../../../../showcase/web/src/patterns/list-detail-recovery-preview.tsx)
+<!-- usage-example: Native ../../../../../showcase/native/src/list-detail-recovery-preview.tsx -->
+- [Native 상세 복구 실행 예제](../../../../../showcase/native/src/list-detail-recovery-preview.tsx)
+
+스토리 `상세 조회 실패와 복구`: 목록 메모 입력 → 다음 상세 조회 실패시키기 → 항목 열기 →
+상세만 다시 불러오기 → 목록으로 복귀해 메모 유지 확인. 예제의 지연·서버 응답은 메모리 모의다.
+
 콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다.
 
-## 큰 글자·다크·좁은 폭
+## 다크·좁은 폭
 
 | 조건 | 바뀌는 것 |
 | --- | --- |
-| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
 | 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
 | 좁은 폭 | 320px부터 한 열로 읽기 순서 유지. 가상화 본문은 scroll=content, 중첩 스크롤 금지 |
 | 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
 
 ## 함정
 
-- 목록 pane 유지; 상세 실패는 detail.content 안에서 복구.
-- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.
+- 목록 pane 유지; 상세 실패는 detail.state·detail.stateAction으로 복구.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크와 실패/복구를 각각 확인한다.
+
+2026-10-13 실제 예제 연결 검수: 새 기록은 빈 초안으로 시작하고, 성공한 제목·본문을 고유 ID의 목록 항목에 함께 보관한다. 다른 기록 상세는 현재 편집 초안을 읽지 않는다. 저장 성공 시 전체 목록으로 돌아가 새 항목을 보이며, 빈 목록에서 작성한 뒤에는 ready로 전환한다. 필터와 새 기록 행동을 표시해도 새로고침 실패 Notice를 덮어쓰지 않는다.

package/docs/usage/screens/flow-editor.md

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/작성과 수정`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/콘텐츠/작성과 수정`
 
@@ -41,6 +41,23 @@ host: 남은 높이·safe area·키보드
 | 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
 | 오류 | 저장 실패는 입력 유지; 저장 성공 확인 후에만 dirty 해제 | 실패 원인과 재시도 경로 제공 |
 
+
+### 초안과 서버 확정
+
+2026-10-13 전수 점검에서 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| 새 작성 | ready + 빈 입력 | 빈 초안은 화면 empty가 아니다. 입력을 바로 보여 준다 |
+| 저장 시작 | submit.pending + 제출 snapshot | cancel과 이미 열린 초안 버리기 확인을 HJM이 잠근다. 확인창은 종료하며 입력 잠금·추가 요청 차단은 제품이 연결한다 |
+| 저장 실패 | ready 유지 + notice | dirty를 해제하거나 입력을 다시 mount하지 않는다 |
+| 저장 성공 | 제출 snapshot을 saved로 갱신 | 요청 후 새로 쓴 내용까지 saved로 처리하지 않는다. draftStatus는 실제 임시 저장 성공 때만 표시한다 |
+| 브라우저·OS 뒤로 | 제품 router의 이탈 가드 | EditorScreen cancel의 discard와 같은 제품 결정을 공유한다 |
+
+본문이 ready가 아닌 최초 조회·오류·제한 상태에서는 헤더/하단 어느 위치의 저장도 비활성이다.
+2026-10-13 입력을 표시하지 않는 상태에서도 저장할 수 있던 경로를 수정했다. 실패한 저장은
+본문을 오류 화면으로 교체하지 않고 위 표처럼 ready + notice로 유지한다.
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |
@@ -71,7 +88,7 @@ import { TextField } from "@hjmds/react/forms";
     tone: "danger",
     fallbackErrorMessage: t("common.error"),
   }}
-  draftStatus={<Text variant="caption" tone="muted">{t("post.edit.draftSaved")}</Text>}
+  draftStatus={draftStatus ? <Text variant="caption" tone="muted">{draftStatus}</Text> : null}
 >
   <TextField label={t("post.edit.body")} value={draft} onValueChange={setDraft} />
 </EditorScreen>
@@ -97,7 +114,7 @@ import { TextField } from "@hjmds/react-native/inputs";
     tone: "danger",
     fallbackErrorMessage: t("common.error"),
   }}
-  draftStatus={<Text variant="caption" tone="muted">{t("post.edit.draftSaved")}</Text>}
+  draftStatus={draftStatus ? <Text variant="caption" tone="muted">{draftStatus}</Text> : null}
 >
   <TextField label={t("post.edit.body")} value={draft} onValueChange={setDraft} />
 </EditorScreen>
@@ -105,11 +122,10 @@ import { TextField } from "@hjmds/react-native/inputs";
 
 콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다.
 
-## 큰 글자·다크·좁은 폭
+## 다크·좁은 폭
 
 | 조건 | 바뀌는 것 |
 | --- | --- |
-| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
 | 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
 | 좁은 폭 | 320px부터 한 열로 읽기 순서 유지. 가상화 본문은 scroll=content, 중첩 스크롤 금지 |
 | 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
@@ -117,4 +133,6 @@ import { TextField } from "@hjmds/react-native/inputs";
 ## 함정
 
 - 저장 실패는 입력 유지; 저장 성공 확인 후에만 dirty 해제.
-- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크와 실패/복구를 각각 확인한다.
+
+2026-10-13 실제 예제 연결 검수: 저장 중 입력은 Web readOnly·Native disabled로 잠그고, 같은 렌더 사이에 들어온 저장 요청도 동기 잠금으로 한 번만 처리한다. 실패 예약은 요청 시작 때 소비하며 진행 중 예약 변경은 무시한다. 실패 후 현재 초안으로 재시도하고, 폐기하면 마지막으로 확정한 snapshot으로 돌아간다. 예제의 400ms 지연과 메모리 저장은 서버 저장 증거가 아니다.

package/docs/usage/screens/flow-media.md

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/사진 선택과 업로드`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/콘텐츠/사진 선택과 업로드`
 
@@ -41,6 +41,21 @@ host: 남은 높이·safe area·키보드
 | 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
 | 오류 | 업로드 실패 항목만 재시도, 완료 버튼은 제품 정책으로 제한 | 실패 원인과 재시도 경로 제공 |
 
+
+### 항목별 업로드와 완료 조건
+
+Web·Native `media-picker-preview.tsx`는 최대 5장을 순서대로 고른 뒤 공통 `items` 격자에서 메모리 업로드를 시연한다. `실패와 복구`는 첫 항목 한 번만 실패하며, 항목의 재시도로 해당 사진만 다시 처리한다. 업로드·실패·0장 상태에서는 완료를 막고, 사진 제거·선택 화면 복귀 뒤 도착한 이전 결과는 무시한다. 모두 성공한 뒤 완료하면 순서를 포함한 읽기 전용 결과가 남고 `새로 선택`으로 초기화한다. `showcase/shared/media-picker-example.ts`는 이 예제만의 메모리 어댑터이며 실제 OS 사진 접근·권한이나 서버 업로드를 수행하지 않는다.
+
+2026-10-13 전수 점검에서 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| 선택 0개 | empty + add | 새 사진 선택은 계속 가능하고 done은 제품 정책에 따라 잠근다 |
+| 업로드 혼재 | 썸네일·순서와 각 UploadItem 상태 유지 | 실패한 항목만 재시도한다. 성공한 사진을 다시 업로드하지 않는다 |
+| 완료 가능 | 필수 항목 모두 서버 확정 | 업로드 중이 아니어도 실패·취소 항목이 남으면 done을 바로 활성화하지 않는다 |
+| 권한 제한 | restricted + 권한 안내 행동 | 로컬 썸네일이 존재한다는 이유로 OS 접근 권한을 얻었다고 판단하지 않는다 |
+| 제거·취소 | 제품이 요청 취소 및 id별 결과 무시 | 늦은 응답이 제거한 사진을 다시 추가하지 않게 한다 |
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |
@@ -60,7 +75,7 @@ import { MediaSelectionScreen } from "@hjmds/react/screen-flows";
   items={picked.map((p) => ({ descriptor: { id: p.id, name: p.fileName, state: p.upload },
     preview: <img src={p.uri} alt="" width={p.width} height={p.height} /> }))}
   add={{ label: t("media.add"), onAction: openPicker }}
-  done={{ label: t("media.done"), onAction: submit, disabled: uploading }}
+  done={{ label: t("media.done"), onAction: submit, disabled: uploading || !canComplete }}
   labels={{ pending: t("upload.pending"), uploading: t("upload.uploading"),
     success: t("upload.success"), cancel: t("upload.cancel"), retry: t("upload.retry") }}
   actionLabels={{ remove: t("media.remove"), moveUp: t("media.moveUp"), moveDown: t("media.moveDown") }}
@@ -82,7 +97,7 @@ import { Image } from "react-native";
   items={picked.map((p) => ({ descriptor: { id: p.id, name: p.fileName, state: p.upload },
     preview: <Image src={p.uri} width={p.width} height={p.height} /> }))}
   add={{ label: t("media.add"), onAction: openPicker }}
-  done={{ label: t("media.done"), onAction: submit, disabled: uploading }}
+  done={{ label: t("media.done"), onAction: submit, disabled: uploading || !canComplete }}
   labels={{ pending: t("upload.pending"), uploading: t("upload.uploading"),
     success: t("upload.success"), cancel: t("upload.cancel"), retry: t("upload.retry") }}
   actionLabels={{ remove: t("media.remove"), moveUp: t("media.moveUp"), moveDown: t("media.moveDown") }}
@@ -94,13 +109,14 @@ import { Image } from "react-native";
 />
 ```
 
+`canComplete`는 필수 파일의 성공·선택 개수 등 제품 완료 조건이다. 단순히 uploading=false인 실패 상태를 완료로 취급하지 않는다.
+
 콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다. 미리보기 이미지는 제품이 공급한다(Web `img`, Native `Image`).
 
-## 큰 글자·다크·좁은 폭
+## 다크·좁은 폭
 
 | 조건 | 바뀌는 것 |
 | --- | --- |
-| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
 | 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
 | 좁은 폭 | 기본 격자는 `minColumnWidth` 없이 `columns={{ compact: 2, expanded: 3 }}`라 320px에서도 2열이다(한 열로 접지 않는다). 960 미만 2열, 이상 3열. 이동·제거 버튼 행은 줄바꿈된다. 한 열이 필요하면 `library` 슬롯으로 제품 격자를 넘긴다 |
 | 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
@@ -108,4 +124,4 @@ import { Image } from "react-native";
 ## 함정
 
 - 업로드 실패 항목만 재시도, 완료 버튼은 제품 정책으로 제한.
-- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크와 실패/복구를 확인한다. 최대 글자와 이를 모사하는 확대 조건은 공통 사용자 지침에 따라 검증·설계 고려에서 제외한다.

package/docs/usage/screens/flow-moderation.md

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/신고와 차단`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/소통/신고와 차단`
 
@@ -41,6 +41,19 @@ host: 남은 높이·safe area·키보드
 | 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
 | 오류 | 신고 실패에 선택 사유·설명 유지; 차단은 성공 후 확정 | 실패 원인과 재시도 경로 제공 |
 
+
+### 신고와 차단의 서로 다른 결과
+
+2026-10-13 전수 점검에서 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| 사유 미선택 | submit 비활성 | reason은 현재 reasons의 값이어야 한다 |
+| 신고 실패 | 선택 사유·설명 유지 + notice | 다시 신고는 같은 대상과 현재 초안으로 한다 |
+| 차단 확인 취소 | 기존 차단 상태 유지 | 신고 초안은 별개이므로 지우지 않는다 |
+| 차단 실패 | AlertDialog 유지 | Promise 실패를 전달한다. 확인창을 먼저 닫고 성공 처리하지 않는다 |
+| 대상 변경 | 대상 id와 초안·요청 묶음 갱신 | 이전 대상의 늦은 응답이 새 대상 상태를 덮지 않게 한다 |
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |

package/docs/usage/screens/flow-onboarding.md

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screen-flows.tsx`(`OnboardingScreen`), 예제 `showcase/*/screen-flow-previews.tsx`(`OnboardingFlowPreview`)·`showcase/shared/onboarding-pattern.ts`(주제·요약). 2026-10-06 사용자 승인으로 실험 `기본 흐름/온보딩`(OnboardingScreen)을 배포하면서 같은 일을 직접 조립하던 배포 `화면/온보딩`을 대체했다(Web id `patterns-onboarding` 보존, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/소개/온보딩`
 
@@ -188,7 +188,7 @@ const topicPicker = <Stack axis="inline" wrap gap="xs">
 ## 함정
 
 - `notice` 자리는 진행 문구가 차지한다. 저장 실패를 띄우려고 OnboardingScreen에 notice를 넘길 수 없으니 마지막 단계 `content`에 둔다.
-- 완료 `pending` 동안에도 이전 버튼은 막히지 않는다. 저장 중 단계 이동이 문제가 되면 `onIndexChange`에서 무시한다.
+- 완료 또는 건너뛰기 `pending` 동안 HJM은 이동 버튼을 함께 잠근다(미게시(1.18.0 이후)). 제품은 같은 완료 요청에 pending을 연결하고, 실패하면 현재 단계·선택값을 유지한 채 잠금을 푼다. 라우터 이탈은 별도로 연결한다.
 - 현재 스토리의 진행 문구는 `` `${index} / ${total}` `` 고정 문자열이다. 제품은 보간 키 하나(`onboarding.progress`)를 쓴다.
 - Storybook은 실제 서버·라우터 연동 증거가 아니다. 기본·어두운 테마·큰 글자와 실패와 복구를 각각 확인한다.
 

package/docs/usage/screens/flow-permission.md

@@ -3,8 +3,8 @@
 - 단계: 화면
 - 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 적용: 구성 API 지침 참조
+- 검토일: 2026-10-13
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/권한 안내`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/소개/권한 안내`
 
@@ -38,9 +38,23 @@ host: 남은 높이·safe area·키보드
 | --- | --- | --- |
 | 기본 | 선택적 그림 → 권한 이유 → 상태별 행동 | 각 공개 콜백을 제품 상태에 연결 |
 | 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
-| 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
+| 빈 | 해당 없음: 권한은 목록 0건이 아니라 OS 상태다 | 상태에 맞는 행동을 제공 |
+| 사용 불가 | status=unavailable, 기능 미지원·대체 경로 안내 | skip 등 제품 대안 |
 | 오류 | 렌더 시 OS 요청 금지; 설정 복귀 시 제품이 상태 재조회 | 실패 원인과 재시도 경로 제공 |
 
+
+### OS 상태에 맞는 다음 행동
+
+2026-10-13 전수 점검에서 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+
+| 상황 | 연결 | 유지·복구 |
+| --- | --- | --- |
+| prompt | request | 사용자 행동에서만 OS 권한 요청 |
+| denied | settings | 설정 앱·브라우저 도움으로 이동; 복귀 시 실제 권한 재조회 |
+| granted | continueAction | 사용할 기능으로 이동 |
+| unavailable | skip 또는 제품 대안 | 권한 재요청을 반복하지 않는다 |
+| 조회·요청 실패 | notice + 같은 요청 재시도 | denied와 통신·호스트 오류를 같은 상태로 저장하지 않는다 |
+
 ## 사용하는 지침
 
 | 지침 | 쓰는 곳 |