@hjmds/design-contracts 1.15.0 → 1.16.1

package/docs/usage/compositions/command-records.md

@@ -1,12 +1,12 @@
 # 명령 기록 표시
 
 - 단계: 구성
-- 상태: 실험
+- 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.14.0 이후)
-- 검토일: 2026-10-07
+- 적용: 1.16.0
+- 검토일: 2026-10-08
 - 근거: [후보 조사](../../../../../docs/qa/2026-10-07-reference-parallel-b.md), 양 Showcase `command-records-preview.tsx`
-- 스토리북: `실험/구성/정보 표시/명령 기록 표시`
+- 스토리북: `배포/구성/정보 표시/명령 기록 표시`
 
 ## 언제 쓰나
 

package/docs/usage/compositions/content-transition-comparison.md

@@ -1,12 +1,12 @@
 # 내용 전환 비교
 
 - 단계: 구성
-- 상태: 실험
+- 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.14.0 이후)
-- 검토일: 2026-10-07
+- 적용: 1.16.0
+- 검토일: 2026-10-08
 - 근거: [Motion 검토](../../../../../docs/qa/2026-10-07-motion-reference-page-review.md), 양 Showcase `content-transition-comparison-preview.tsx`
-- 스토리북: `실험/구성/비교와 검증/내용 전환 비교`
+- 스토리북: `배포/구성/비교와 검증/내용 전환 비교`
 
 ## 언제 쓰나
 
@@ -40,7 +40,7 @@ Motion Primitives Transition Panel의 두 제공 예제를 실제 검토한 후
 
 | 영역 | 컴포넌트 | 위치 | 크기·간격 |
 | --- | --- | --- | --- |
-| 바깥 틀 | Stack | 세로 | `spacing.lg` 20 |
+| 바깥 틀 | Stack·Native ScrollView | 세로, 비교 도구와 단계 viewport를 함께 스크롤 | `spacing.lg` 20 |
 | 표현 선택 | SegmentedControl | 안내 아래 | 공개 `presentation="pills"`, 큰 글자·좁은 화면 줄바꿈 |
 | 탭 본문 | TabPanel·ContentTransition·Stack | 탭 목록 아래 | `spacing.md` 16, 높이는 현재 내용 측정 |
 | 단계 틀 | OnboardingScreen | 표현 선택 아래 | Web preview 70dvh/minHeight 360, Native preview 720. 이는 fixture viewport이며 제품은 실제 가용 높이 사용 |
@@ -106,3 +106,9 @@ import { OnboardingScreen } from "@hjmds/react-native/screen-flows";
 이는 짧은 viewport에서도 body scroll과 footer를 함께 검증하려는 fixture 한계값이며
 제품의 spacing/width 토큰을 높이로 전용하지 않는다. token-boundary-exceptions.json에
 해당 selector·minHeight·360만 한정해 등록했다. 제품 host는 실제 가용 높이를 공급한다.
+
+2026-10-07 실제 iOS 개발 검수에서 비교 도구 아래 720unit 단계 viewport의 footer가
+Canvas 바깥에 있어 다음 버튼에 도달할 수 없었다. Native 비교 host에 바깥 ScrollView를
+추가해 도구와 viewport를 함께 내리며, OnboardingScreen의 내부 본문 scroll과 footer 소유권은
+유지한다. viewport 축소로 실제 화면의 본문/행동 배치를 바꾸는 대안은 사용하지 않았다.
+제품 host는 이 fixture 높이를 복사하지 않고 실제 가용 높이를 공급한다.

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

@@ -1,12 +1,12 @@
 # 날짜와 시각 선택
 
 - 단계: 구성
-- 상태: 실험
+- 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.14.0 이후)
-- 검토일: 2026-10-07
+- 적용: 1.16.0
+- 검토일: 2026-10-08
 - 근거: [Magic 조사](../../../../../docs/qa/2026-10-07-reference-parallel-b.md), 양 Showcase `date-time-selection-preview.tsx`, shared `date-time-selection.ts`
-- 스토리북: `실험/구성/선택과 필터/날짜와 시각 선택`
+- 스토리북: `배포/구성/선택과 필터/날짜와 시각 선택`
 
 ## 언제 쓰나
 

package/docs/usage/compositions/design-profile-comparison.md

@@ -1,12 +1,12 @@
 # 테마 조합
 
 - 단계: 구성
-- 상태: 실험
+- 상태: 배포
 - 지원: Web · Native
-- 적용: 미게시(1.14.0 이후)
-- 검토일: 2026-10-07
+- 적용: 1.16.0
+- 검토일: 2026-10-08
 - 근거: [프로필 계약](../../design-profile.md), [조사와 QA](../../../../../docs/qa/2026-10-07-design-profile-research.md), 두 Showcase `design-profile-preview.tsx`
-- 스토리북: `실험/구성/비교와 검증/테마 조합`
+- 스토리북: `배포/구성/비교와 검증/테마 조합`
 
 ## 언제 쓰나
 
@@ -112,3 +112,14 @@ slide로 해석되고 나머지 6종은 standard다. 명시 값은 프로필보
 이 샘플의 패널 수명을 기본값으로 복사하지 않고 초안과 탭의 사용 목적에 맞춰 선택한다.
 
 Web의 팝오버는 비모달 편집 초안과 테마 순회를 추가 비교한다. Native의 같은 용도는 기존 Sheet 경로다. 저장/실패 샘플은 두 플랫폼 공개 BottomCTA이며 브랜드가 바뀌어도 같은 저장 상태·초안·재시도 callback을 유지한다.
+
+
+### 플로팅 행동 변형
+
+2026-10-07 FAB의 그림자 소비 누락을 수정하며 같은 실험의 `FloatingAction` 변형을 추가했다.
+10종 선택 → 행동 실행 횟수/다음 테마 → 논리적 끝 하단의 단일 FAB로 비교한다.
+Web은 기존 viewport-fixed 배치, Native는 기존 비교 화면과 같은 640unit fixture viewport 안의
+absolute 배치를 사용한다. 전체 비교 tile마다 FAB를 붙이면 행동이 겹치므로 별도 변형으로 둔다.
+두 플랫폼 모두 공개 FloatingActionButton의 `onContentClearanceChange` 값을 본문 하단
+padding으로 예약한다. 프로필 전환은 같은 버튼과 실행 횟수를 유지하며 실제 저장/서버 호출은 없다.
+[플로팅 실행 버튼](../components/floating-action-button.md)의 원/pill과 행동·여백 계약을 따른다.

package/docs/usage/compositions/paper-surface.md

@@ -0,0 +1,101 @@
+# 종이 줄무늬 비교
+
+- 단계: 구성
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.16.0
+- 검토일: 2026-10-08
+- 근거: [EffectSurface 계약](../../effect-surface.md), A-02 종이 표현 후보의 줄무늬 보완
+- 스토리북: `배포/구성/비교와 검증/종이 줄무늬 비교`
+
+## 언제 쓰나
+
+같은 입력·기록에서 종이 preset의 grain+ruled 상속과 앱이 지정한 평면/줄무늬 표현을 비교한다.
+테마를 바꾸고 싶다는 이유로 앱이 별도 배경·입력 wrapper를 만들지 않고 기존 공개 profile와 OverviewScreen을 쓴다.
+선은 정적 장식이며 글자 기준선을 맞추는 편집기 grid가 아니다. 테이프·찢어진 경계·물결/타공·회전된 내용은 제공하지 않는다.
+
+## 구성 요소
+
+| 컴포넌트 | 역할 | 지침 |
+| --- | --- | --- |
+| HjmProvider/HjmNativeProvider | 앱 소유 profile 한 번 주입 | [테마](../../theming.md) |
+| OverviewScreen | canvas·카드·도구·footer의 기존 틀 | [개요 화면](../components/overview-screen.md) |
+| EffectSurface | 화면 내부 canvas의 grain/ruled | [배경 효과](../components/effect-surface.md) |
+| SegmentedControl | 상속/명시 표현과 간격 선택 | [단일 선택](../components/segmented-control.md) |
+| TextField/Button/Dialog | 초안·확인·상세와 복귀 | [입력](../components/field.md), [Dialog](../components/dialog.md) |
+
+## 배치
+
+```text
+[종이 표현: 테마 따르기 / 줄무늬 없는 면 / 줄무늬 추가]
+[줄무늬 간격: 24 / 40]  [다음 테마]
+┌ OverviewScreen: 테마의 기존 화면/구성 기본값 ┐
+│ 제목 → 설명 → 산책 메모                    │
+│ 기록 2개: 제목 → 본문                       │
+│ 확인 결과 → [기록 확인] [자세히 읽기]        │
+└ 정적 canvas: 내용 뒤, 입력/읽기 순서 없음 ──┘
+[표현 한계]
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | Stack | 화면 앞쪽 비교 도구부터 세로 | gap lg20; Native는 바깥 ScrollView와 기존 테마 비교와 같은 640host-unit 화면 viewport |
+| 기록 항목 | OverviewScreen·Stack | items 본문 | gap sm12; rows/grid/cards와 화면은 profile 기본값 |
+| 줄무늬 | EffectSurface | 화면 canvas 뒤 SVG | 한 선 1host unit, spacing 기본24, 명시 비교40; userSpaceOnUse |
+| footer | Stack·Button | 기존 OverviewScreen footer | gap sm12, primary 확인 다음 secondary 상세 |
+| 상세 | Dialog·Text | 기존 modal | 현재 초안 읽기, close/Escape·초점 복귀는 기존 계약 |
+
+## 흐름과 상태
+
+| 상태 | 모습 | 포커스·알림 |
+| --- | --- | --- |
+| 기본 | 테마 따르기. paper=grain+ruled/intensity0.06/spacing24 | 테마를 subtree key로 쓰지 않음 |
+| 진행 중 | 표현·간격·테마를 즉시 반영, 인위적인 대기 없음 | 동일 입력·초안 유지 |
+| 줄무늬 없는 면 | canvas grain/intensity0.12/정적 | 동일 입력·초안·기록 |
+| 줄무늬 추가 | canvas grain+ruled/intensity0.12/spacing24 또는40 | 동일 입력·초안·기록 |
+| 상세 | 현재 초안 읽기 | 닫기와 trigger 복귀 |
+| 실패 | 기존 EffectSurface의 장식 host 배경 대안 | 내용·입력과 행동 유지; peer 미설치는 번들 실패라 별도 확인 |
+
+1. 초안을 입력한 뒤 표현·간격·테마를 바꾼다. 입력과 기록의 owner는 같은 컴포넌트에 남는다.
+2. 기록 확인은 예제 결과만 바꾸며 서버 저장·자동 성공·운영 데이터 반영을 뜻하지 않는다.
+3. 자세히 읽기에서 현재 초안을 확인하고 닫는다. 줄무늬를 접근성 이름/조작 요소로 노출하지 않는다.
+
+## 코드 골격
+
+```tsx
+// Web
+import { defineHjmDesignProfile } from "@hjmds/design-contracts/design-profile";
+import { HjmProvider } from "@hjmds/react/provider";
+const productDesign = defineHjmDesignProfile({ extends: "paper", material: {
+  canvas: { layers: ["grain", "ruled"], ruledSpacing: 40, intensity: 0.06, active: false },
+} });
+// 실제 제품의 필드/데이터/저장 흐름을 기존 OverviewScreen props로 공급한다.
+<HjmProvider designProfile={productDesign}>{children}</HjmProvider>;
+```
+
+```tsx
+// Native
+import { defineHjmDesignProfile } from "@hjmds/design-contracts/design-profile";
+import { HjmNativeProvider } from "@hjmds/react-native/provider";
+const productDesign = defineHjmDesignProfile({ extends: "paper", material: {
+  canvas: { layers: ["grain", "ruled"], ruledSpacing: 40, intensity: 0.06, active: false },
+} });
+<HjmNativeProvider designProfile={productDesign}>{children}</HjmNativeProvider>;
+```
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 선 단위 | CSS pixel | logical host unit; iPhone17Pro/iOS26.5 개발 호스트에서 24/40 간격 확인 |
+| 그리기 | SVG Pattern/Rect | 기존 optional react-native-svg15.15.5, 새 peer 없음 |
+| 모션 | atmospheric SVG 밖 정적 | Animated scale 밖 정적 |
+| 내용 | 일반 DOM 레이아웃 | 기존 Native 화면·입력 host |
+
+강도를 올려 원제품의 종이·사진 재질과 같다고 주장하지 않는다. 중요한 문구는 불투명 Surface에 놓고 실제 대비를 확인한다.
+제공하지 않는 경계를 대체한 것으로 세지 않는다. 최대 글자 조건은 사용자 지시로 실행·후속·완료 조건에서 제외한다.
+
+Native 비교 도구를 높이 없는 Stack에 넣으면 flex 화면이 접혔고, 작은 남은 화면 높이만 주면 도구가 본문을
+밀어냈다. 그래서 기존 테마 비교의 640unit viewport를 사용하고 바깥도 스크롤한다. 제품은 이 예제 높이를
+복사하지 않고 실제 route 영역을 제공한다. iOS 줄무늬는 1unit 폭/백분율 Rect 조합에서 보이지 않아
+spacing×spacing 타일과 명시적 물리 폭을 사용한다. [수정 전후 기기 결과](../../../../../docs/qa/2026-10-07-native-reference-validation.md)를 참고한다.

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

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 미게시(1.12.1 이후)
-- 검토일: 2026-10-06
+- 검토일: 2026-10-07
 - 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/공통 화면/댓글`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
 - 스토리북: `배포/화면/소통/댓글`
 
@@ -29,7 +29,7 @@ host: 남은 높이·safe area·키보드
 
 | 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
 | --- | --- | --- | --- |
-| 작업 | CommentThreadScreen 공개 행동 슬롯 | 좋아요·답글은 각 댓글; 보내기는 하단 composer | 같은 표면에 경쟁하는 primary 하나만 |
+| 작업 | CommentThreadScreen 공개 행동 슬롯 | 좋아요와 세로 점 더보기는 댓글 오른쪽의 같은 행; 답글은 본문 아래; 보내기는 하단 composer | 같은 표면에 경쟁하는 primary 하나만 |
 | 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
 
 ## 상태
@@ -106,3 +106,7 @@ import { MessageComposer } from "@hjmds/react-native/screens";
 
 - 빈 댓글에서도 작성창 유지; 실패한 전송은 초안 유지.
 - Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.
+
+2026-10-07 하트 옆 더보기 요청에 따라 두 renderer의 `CommentThreadItem.actions`를
+좋아요 바로 뒤에 둔다. Storybook 예제는 공개 Menu와 MoreVertical을 쓰며 메뉴의 답글/좋아요는
+기존 controlled callback을 호출한다. 제품의 신고·삭제 권한이나 서버를 예제에서 추정하지 않는다.

package/docs/usage/tokens/font-roles.md

@@ -0,0 +1,87 @@
+# 표시·읽기·기술 글자
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.16.0
+- 검토일: 2026-10-08
+- 근거: [서체 역할 계약](../../font-roles.md), `src/foundations.ts`, `src/design-profile.ts`, 양 renderer Text/Heading/Provider
+- 스토리북: `배포/토큰/색과 글자/표시·읽기·기술 글자`
+
+## 언제 쓰나
+
+앱의 제목·읽기용 본문·입력/조작 문구·기술값을 서로 다른 서체로 표시할 때 쓴다.
+[프로필](../compositions/design-profile-comparison.md)에 font stack만 넣으면 기존 Heading/Text를 사용하는
+구성·화면에 전파한다. 서체 파일을 선택/로드하고 출처를 검토할 때는 [글꼴 편집](typography-studio.md)을 쓴다.
+참고 서체 조합을 제품 브랜드 기본값으로 복사하지 않는다.
+
+## 값
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `tokens.fontFamily.ui` | 기존 Inter/Pretendard 등 stack, Native OS 기본 | `--hjm-font-family-ui` | `theme.tokens.fontFamily.ui` | 입력·버튼·caption·label |
+| `tokens.fontFamily.display` | optional stack, 생략하면 현재 ui | `--hjm-font-family-display` | `resolveFontFamilyStack(theme.tokens.fontFamily, "display")` | Heading·Text title/titleLarge/heading |
+| `tokens.fontFamily.reading` | optional stack, 생략하면 현재 ui | `--hjm-font-family-reading` | `resolveFontFamilyStack(theme.tokens.fontFamily, "reading")` | Text body/bodyLarge |
+| `tokens.fontFamily.code` | 기존 ui-monospace 등 stack | `--hjm-font-family-code` | `theme.tokens.fontFamily.code` | CodeBlock·Text fontRole=code |
+| Text `fontRole` | ui/display/reading/code, 생략하면 위 variant 역할 | 같은 역할 변수 | 같은 역할의 첫 named font | 문구 역할만 변경. 제목 level·variant 크기/굵기는 유지 |
+
+순수 helper `resolveFontFamilyStack`·`resolveTextFontRole`는 `@hjmds/design-contracts/foundations`에 있다.
+Web은 전체 stack, Native는 기존 host helper로 단일 font name을 해석한다. Native의 기본 code는 iOS Menlo/그 외 monospace다.
+
+## 쓰는 법
+
+```tsx
+// Web
+import { defineHjmDesignProfile } from "@hjmds/design-contracts/design-profile";
+import { HjmProvider } from "@hjmds/react/provider";
+import { Heading } from "@hjmds/react/heading";
+import { Text } from "@hjmds/react/layout";
+
+const design = defineHjmDesignProfile({ extends: "paper", tokens: { fontFamily: {
+  display: ["ProductDisplay", "serif"], reading: ["ProductReading", "sans-serif"],
+} } });
+<HjmProvider designProfile={design}>
+  <Heading level="level3">{t("reading.title")}</Heading>
+  <Text as="p" variant="bodyLarge">{t("reading.body")}</Text>
+  <Text fontRole="ui">{t("reading.actionHint")}</Text>
+</HjmProvider>
+```
+
+```tsx
+// Native
+import { defineHjmDesignProfile } from "@hjmds/design-contracts/design-profile";
+import { HjmNativeProvider } from "@hjmds/react-native/provider";
+import { Heading } from "@hjmds/react-native/heading";
+import { Text } from "@hjmds/react-native/primitives";
+
+// Product registers these names with its font loader before selecting this profile.
+const design = defineHjmDesignProfile({ extends: "paper", tokens: { fontFamily: {
+  display: ["ProductDisplay"], reading: ["ProductReading"],
+} } });
+<HjmNativeProvider designProfile={design}>
+  <Heading level="level3">{t("reading.title")}</Heading>
+  <Text variant="bodyLarge">{t("reading.body")}</Text>
+  <Text fontRole="code">{t("reading.recordId")}</Text>
+</HjmNativeProvider>
+```
+
+## 하지 말 것
+
+- 폰트 이름 지정만으로 파일 설치·라이선스·한글 글리프·실기기 표시가 확인됐다고 하지 않는다.
+- 크기나 문서 제목 레벨을 서체 역할로 대신하지 않는다. Heading의 level/semanticLevel과 Text의 variant는 그대로 쓴다.
+- 본문 글꼴을 입력에 직접 style override하지 않는다. 조작 host는 ui, 읽기 본문은 reading으로 분리한다.
+- 같은 역할을 앱마다 또 다른 Provider/전역 CSS 엔진으로 구현하지 않는다. 설정·자산·로딩은 앱이 관리한다.
+- 글꼴 전환 시 입력 또는 열린 상세를 key로 다시 마운트하지 않는다. 상태는 기존 구성/제품이 소유한다.
+
+### 조작 라벨과 읽기 본문의 구분 — 미게시
+
+2026-10-07 소비 감사에서 Native 조작 라벨 24곳이 body/bodyLarge 크기를 사용하면서 읽기 서체로 해석됐다.
+Button의 내부 라벨·제공자 버튼·ToggleGroup·선택 컨트롤·Switch·SegmentedControl·Chip·Tabs·Menu·Select·
+Combobox·동의·Toast 행동·Link·날짜 선택/Calendar 날짜·disclosure·멘션/태그 후보·TransferList는 기존
+Text의 `fontRole="ui"`를 명시한다. 크기 variant는 그대로 유지하고 가까운 Provider의 ui stack을 읽는다.
+본문/description의 reading, 의미 제목의 display, label/caption의 기존 ui와 고정 glyph는 바꾸지 않는다.
+일반 Text의 기본값을 ui로 바꾸는 대안은 실제 읽기 본문의 제품 서체를 잃으므로 채택하지 않았다.
+
+추가 1곳인 TopBar 제목은 Web과 같은 경계를 유지한다. 클릭형 제목은 일반 버튼 라벨이므로 ui,
+비클릭형 제목은 의미 heading이므로 display다. 제목 행동·접근성 이름·정적 heading 역할은 유지한다.
+서체 선택 검사는 Native host 모사에서 수행했으며 폰트 자산 설치·실제 기기 표시 검증을 뜻하지 않는다.

package/docs/usage/tokens/typography.md

@@ -101,3 +101,6 @@ Heading의 다섯 시각 단계는 `defineHjmDesignProfile({ tokens: { heading:
 metrics로 연결된다. 해당 heading을 담은 Provider에서 가장 가까운 profile을 읽는다.
 level3/4/5는 기존 typography heading/titleLarge/title override를 기본으로 병합하며
 명시적인 heading 값이 우선한다. 문서의 h1~h6 순서는 `semanticLevel`이 소유한다.
+
+제목·본문에 서로 다른 글꼴이 필요하면 [표시·읽기·기술 글자](font-roles.md)를 사용한다.
+현재 ui/code-only 설정은 유지되며 신규 optional display/reading은 1.15.0 이후 미게시다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -714,6 +714,12 @@
       "react-native": "./dist/design-profile-layout.js",
       "import": "./dist/design-profile-layout.js",
       "default": "./dist/design-profile-layout.js"
+    },
+    "./collection-rail": {
+      "types": "./dist/collection-rail.d.ts",
+      "react-native": "./dist/collection-rail.js",
+      "import": "./dist/collection-rail.js",
+      "default": "./dist/collection-rail.js"
     }
   },
   "files": [