@hjmds/design-contracts 1.27.2 → 1.28.0

package/docs/usage/screens/landing.md

@@ -29,20 +29,20 @@
 │ ┌ ① 히어로 EffectSurface(mesh+grain) ──┐ │
 │ │ (안쪽 여백 spacing.xl 24 — HJM 구성 소유) │ │
 │ │ eyebrow  Text tone=muted             │ │  Stack gap lg 20
-│ │ 제목     Heading level1 (h1)         │ │
+│ │ 제목     Heading level3 (h1) 24      │ │
 │ │ 소개     Text as=p                   │ │
 │ │ [ 첫 기록 써보기 ]  ← 주 행동(primary) │ │
 │ └──────────────────────────────────────┘ │
 │              ↕ spacing.xl 24             │
 │ ┌ ② 미리보기 Surface padding lg 20 ────┐ │
-│ │ Heading level2                       │ │  Stack gap md 16
+│ │ Heading level4 (h2) 20               │ │  Stack gap md 16
 │ │ (저장 직후) "추가했어요" status        │ │
 │ │ List > ListRow 한 줄씩(최신이 위)     │ │
 │ └──────────────────────────────────────┘ │
-│ ③ 기능 Heading level2                    │
-│ ┌ Surface padding lg ─┐ Heading level3 + Text (Stack gap sm 12)
+│ ③ 기능 Heading level4 (h2)               │
+│ ┌ Surface padding lg ─┐ Heading level5 (h3) + Text (Stack gap sm 12)
 │ └─────────────────────┘ × 3, 사이 24     │
-│ ④ FAQ Heading level2                     │
+│ ④ FAQ Heading level4 (h2)                │
 │   ▸ 질문 1   Collapsible (트리거 최소 44) │
 │   ▸ 질문 2                               │
 │ ⑤ [ 첫 기록 써보기 ]  ← 같은 행동 반복     │  secondary
@@ -67,8 +67,8 @@
 | 바깥 틀 | Web `main` > `Container size="content" gutter={gutter}` > `Stack gap="xl"`(문서 스크롤) · Native `ScrollView`(`contentContainerStyle={{ paddingVertical: spacing.lg }}`) > `Container size="content" gutter={gutter}` > `Stack gap="xl"` | 화면 전체, 스크롤. 위 안전 영역은 내비게이션 헤더(또는 [TopBar](../components/top-bar.md) `safeAreaTop`)가 맡고 헤더 없이 띄울 때만 제품이 감싼다. 아래 고정 영역은 없다. 바깥에는 입력이 없어 키보드 처리는 ⑥ 시트가 맡는다 | 좌우 gutter: 폭 600 미만 `compact` 16(`layout.pagePadding.compact`), 이상 `regular` 20([화면 여백](../tokens/layout.md)). Native 위아래 `spacing.lg` 20. 직계 요소 사이 `spacing.xl` 24(`layout.sectionGap`) |
 | ① 히어로 | EffectSurface `descriptor={{ layers: ["mesh","grain"], active: false }}` > Surface `padding="xl"` > Stack `gap="lg"` > Text·Heading·Text·Button | 맨 위 | 요소 사이 `spacing.lg` 20. EffectSurface 안에 Surface `padding="xl"`을 두어 spacing.xl 24를 준다. 실제 양 플랫폼 예제와 같은 공개 구성이다 |
 | ② 미리보기 | Surface `padding="lg"` > Stack `gap="md"` > Heading·상태 Text·List | 히어로 아래 | 안쪽 20, 요소 사이 `spacing.md` 16, 한 줄 행 최소 56(`layout.rowHeight.singleLine`). 새 기록이 맨 위 |
-| ③ 기능 | Heading level2 + Surface `padding="lg"` ×3 > Stack `gap="sm"` | 미리보기 아래 | 카드 안 `spacing.sm` 12, 카드 사이 24 |
-| ④ FAQ | Heading level2 + Collapsible × n | 기능 아래 | 트리거 최소 44(`control.minTouchTarget`), 트리거 위아래 `spacing.xs` 8(Web) |
+| ③ 기능 | Heading level4(h2) + Surface `padding="lg"` ×3 > Stack `gap="sm"` | 미리보기 아래 | 카드 안 `spacing.sm` 12, 카드 사이 24 |
+| ④ FAQ | Heading level4(h2) + Collapsible × n | 기능 아래 | 트리거 최소 44(`control.minTouchTarget`), 트리거 위아래 `spacing.xs` 8(Web) |
 | ⑤ 마지막 행동 | Button `secondary` + Text `tone="muted"` | 맨 아래 | 사이 24 |
 | ⑥ 입력 | Sheet(Native `keyboardAvoidance` `scrollable`) > Stack `gap="lg"` > Notice(실패 때)·TextField, 제출은 `footer` | 오버레이, 화면 아래 | 시트 좌우 `spacing.lg` 20, TextField 높이 44(`control.fieldHeight`). 아래 안전 영역·키보드는 시트가 맡는다 |
 
@@ -134,7 +134,7 @@ footer의 저장과 같은 동작을 실행한다. Web에서 IME 조합 확정
 | [Container](../components/container.md) | 바깥 틀 폭·좌우 여백 |
 | [화면 여백과 너비](../tokens/layout.md) | gutter 선택(`resolveWindowClass`) |
 | [EffectSurface](../components/effect-surface.md) | ① 히어로 배경 장식 |
-| [Heading](../components/heading.md) | 히어로 level1, 영역 제목 level2, 기능 카드 level3 |
+| [Heading](../components/heading.md) | 히어로 level3(h1, 24), 영역 제목 level4(h2, 20), 기능 카드 level5(h3, 18) |
 | [Text](../components/text.md) | eyebrow·소개·범위 안내·상태 문구 |
 | [Button](../components/button.md) | 주 행동, 반복 행동, 시트 제출 |
 | [Surface](../components/surface.md) | ② 미리보기, ③ 기능 카드 |
@@ -179,20 +179,20 @@ const gutter = resolveWindowClass(window.innerWidth) === "compact" ? "compact" :
   <EffectSurface descriptor={{ layers: ["mesh", "grain"], seed: "landing", active: false }}><Surface padding="xl">
     <Stack gap="lg" align="start">
       <Text tone="muted">{t("landing.eyebrow")}</Text>
-      <Heading level="level1">{t("landing.title")}</Heading>
+      <Heading level="level3" semanticLevel={1}>{t("landing.title")}</Heading>
       <Text as="p">{t("landing.intro")}</Text>
       <Button onClick={start}>{t("landing.cta")}</Button>
     </Stack>
   </Surface></EffectSurface>
   <Surface padding="lg"><Stack gap="md">
-    <Heading level="level2">{t("landing.preview")}</Heading>
+    <Heading level="level4" semanticLevel={2}>{t("landing.preview")}</Heading>
     {saved ? <Text role="status">{t("landing.saved")}</Text> : null}
     <List label={t("landing.preview")}>{notes.map(n => <ListRow key={n.id} title={n.text} />)}</List>
   </Stack></Surface>
-  <Heading level="level2">{t("landing.features")}</Heading>
+  <Heading level="level4" semanticLevel={2}>{t("landing.features")}</Heading>
   {features.map(f => <Surface key={f.id} padding="lg"><Stack gap="sm">
-    <Heading level="level3">{t(f.titleKey)}</Heading><Text>{t(f.bodyKey)}</Text></Stack></Surface>)}
-  <Heading level="level2">{t("landing.faq")}</Heading>
+    <Heading level="level5" semanticLevel={3}>{t(f.titleKey)}</Heading><Text>{t(f.bodyKey)}</Text></Stack></Surface>)}
+  <Heading level="level4" semanticLevel={2}>{t("landing.faq")}</Heading>
   {faqs.map(q => <Collapsible key={q.id} trigger={t(q.questionKey)}><Text>{t(q.answerKey)}</Text></Collapsible>)}
   <Stack gap="xl" align="start"><Button tone="secondary" onClick={start}>{t("landing.cta")}</Button>
   <Text tone="muted">{t("landing.scope")}</Text></Stack>
@@ -229,7 +229,7 @@ const gutter = resolveWindowClass(width) === "compact" ? "compact" : "regular";
   <Container size="content" gutter={gutter}><Stack gap="xl">
     <EffectSurface descriptor={{ layers: ["mesh", "grain"], seed: "landing", active: false }}><Surface padding="xl">
       <Stack gap="lg">
-        <Heading level="level1">{t("landing.title")}</Heading>
+        <Heading level="level3" semanticLevel={1}>{t("landing.title")}</Heading>
         <Text>{t("landing.intro")}</Text>
         <Button onPress={start}>{t("landing.cta")}</Button>
       </Stack>
@@ -366,6 +366,7 @@ import { ScreenLayout } from "@hjmds/react-native/screens";
 
 ## 근거
 
+- 2026-10-17 사용자 결정("글자 너무 커", "큰 글자 정책은 없애"): 히어로 제목 level1 40px·영역 제목 level2 32px가 지나치게 커서 큰 글자 단계를 폐지했다. 히어로는 HJM 상한인 level3 24px(h1), 영역 제목은 level4 20px(h2), 기능 카드는 level5 18px(h3)로 위계를 만든다.
 - FAQ는 Collapsible(기본·변형): 2026-10-16 사용자 지적 — 변형 스토리가 `selected` 토글 Button 하나로 펼침을 흉내 내 눌림 토글로 읽혔다.
 - 닫을 때 초안 보존·성공 제출만 한 번 추가: 2026-10-13 실제 예제 검수에서 닫은 뒤 초안 소실과 연속 제출 시 중복 행을 재현했다.
 - 히어로 padding·시트 저장 footer: 2026-10-06 지침과 예제 정합성 수정.

package/docs/usage/screens/notification-settings.md

@@ -28,7 +28,7 @@ ScreenLayout: 제목(고정) → 본문(스크롤) → footer(고정)
 | --- | --- | --- | --- |
 | 바깥 틀 | ScreenLayout | host의 남은 높이 | 공통 화면 폭·padding·본문 스크롤 |
 | 설정 묶음 | CompositionLayout | 본문 | 공통 제목·설명·내용 간격 |
-| 설정 값 | Switch | 구성 본문 | 제품 데이터·변경 콜백 |
+| 설정 값 | List(`separator="none"`) > Switch `presentation="row"` | 구성 본문 | 행 사이 gap 없음 — 행 간격 56은 Switch 행 높이·여백이 맡는다. 제품 데이터·변경 콜백 |
 | 저장 | footer | 화면 하단 | HJM 고정 영역; 제품 저장 요청과 pending 연결 |
 
 ## 버튼과 행동 위치
@@ -74,7 +74,8 @@ ScreenLayout: 제목(고정) → 본문(스크롤) → footer(고정)
 | [Notice](../components/notice.md) | 저장 결과·오류 |
 | [Skeleton](../components/skeleton.md) | 첫 값 불러오기 |
 | [Button](../components/button.md) | ③ 하단 저장 |
-| [Stack](../components/stack.md) | 세 층 사이, 스위치 목록 |
+| [Stack](../components/stack.md) | 세 층 사이 |
+| [List](../components/list.md) | 스위치 목록(행 사이 여백 없이) |
 | [화면 여백과 너비](../tokens/layout.md) | `layout.readingMaxWidth`, `layout.pagePadding.compact`·`regular`, `resolveWindowClass` |
 | [간격](../tokens/spacing.md) | `spacing.xxs`·`xs`·`sm`·`md`·`lg` |
 
@@ -114,3 +115,4 @@ ScreenLayout이 화면 여백과 스크롤을, CompositionLayout이 묶음 간
 ## 근거
 
 - 설정 초안의 저장 경계 상황 표: 2026-10-13 전수 점검 — 최초 조회와 변경 요청의 상태를 같은 골격으로 설명하던 부분을 구체화했다.
+- 스위치 목록 List·gap 없음: 2026-10-17 사용자 보고("간격이 커") — Stack `gap="md"` 16이 Switch 행 최소 높이 위에 더해져 행 간격이 84였다.

package/docs/usage/tokens/typography.md

@@ -23,9 +23,9 @@
 | `typography.label` | 12 / 줄 18 / 500 | `--hjm-type-label-*` | `theme.tokens.typography.label` | 라벨·도움말·small 버튼 글자 |
 | `typography.body` | 14 / 줄 20 / 400 | `--hjm-type-body-*` | `theme.tokens.typography.body` | 기본 본문·medium 버튼·필드 글자 |
 | `typography.bodyLarge` | 16 / 줄 24 / 400 | `--hjm-type-body-large-*` | `theme.tokens.typography.bodyLarge` | 읽기용 긴 본문·large 버튼 글자 |
-| `typography.title` | 18 / 줄 26 / 600 | `--hjm-type-title-*` | `theme.tokens.typography.title` | 카드 제목(`heading.level5`) |
-| `typography.titleLarge` | 20 / 줄 28 / 600 | `--hjm-type-title-large-*` | `theme.tokens.typography.titleLarge` | 큰 구획 제목(`heading.level4`) |
-| `typography.heading` | 24 / 줄 32 / 600 | `--hjm-type-heading-*` | `theme.tokens.typography.heading` | 화면의 가장 큰 제목 |
+| `typography.title` | 18 / 줄 26 / 500 | `--hjm-type-title-*` | `theme.tokens.typography.title` | 카드 제목(`heading.level5`) |
+| `typography.titleLarge` | 20 / 줄 28 / 500 | `--hjm-type-title-large-*` | `theme.tokens.typography.titleLarge` | 큰 구획 제목(`heading.level4`) |
+| `typography.heading` | 24 / 줄 32 / 500 | `--hjm-type-heading-*` | `theme.tokens.typography.heading` | 화면의 가장 큰 제목. **HJM 글자 크기의 상한** |
 
 굵기 열은 토큰 원본값이다. 프로필 없는 Text는 기본 `emphasis="regular"`(400)를 사용하므로
 variant만 지정해도 위 굵기가 자동 적용되는 것은 아니다. 예외는 `label`이다. `label`은 프로필이 없어도
@@ -37,11 +37,10 @@ Heading은 제목 단계의 굵기를 쓴다. 두 renderer가 같은 resolver를
 
 | 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
 | --- | --- | --- | --- | --- |
-| `heading.level1` | 40 / 줄 48 / 700 | — | `heading.level1` | 랜딩·문서의 대표 제목 |
-| `heading.level2` | 32 / 줄 40 / 700 | — | `heading.level2` | 긴 페이지의 큰 구획 제목 |
-| `heading.level3` | = `typography.heading` 24 | `--hjm-type-heading-*` | `heading.level3` | 화면 제목 |
+| `heading.level3` | = `typography.heading` 24 | `--hjm-type-heading-*` | `heading.level3` | 화면 제목·랜딩 대표 제목 |
 | `heading.level4` | = `typography.titleLarge` 20 | `--hjm-type-title-large-*` | `heading.level4` | 구획 제목 |
 | `heading.level5` | = `typography.title` 18 | `--hjm-type-title-*` | `heading.level5` | 카드 제목 |
+| `heading.level1` · `level2` | = `heading.level3` 24 (사용 중단) | `--hjm-type-heading-*` | `heading.level1` · `level2` | 새 코드에서 쓰지 않는다. 기존 소비 코드가 깨지지 않도록 이름만 남기고 값은 상한 24로 고정했다 |
 
 ### 서체·굵기·자간·숫자
 
@@ -49,12 +48,12 @@ Heading은 제목 단계의 굵기를 쓴다. 두 renderer가 같은 resolver를
 | --- | --- | --- | --- | --- |
 | `fontFamily.ui` | Pretendard Variable, Pretendard, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif | `--hjm-font-family-ui` | `fontFamily.ui` | 화면 글자. Native는 `fonts="pretendard"`일 때 굵기별 Pretendard face, 그 전에는 OS 서체. 불러오기는 [글꼴 역할](font-roles.md#기본-서체-pretendard-불러오기필수) |
 | `fontFamily.code` | ui-monospace, SFMono-Regular, SF Mono, Menlo, Monaco, Cascadia Mono, Consolas, Liberation Mono, monospace | — (`--hjm-font-family-code` fallback) | `fontFamily.code` | 코드 |
-| `fontWeight.regular` · `medium` · `semibold` · `bold` · `heavy` | 400 · 500 · 600 · 700 · 800 | `--hjm-font-weight-<이름>` | `fontWeight.<이름>` | Text `emphasis`: `regular` 400 · `medium` 600 · `strong` 700 |
+| `fontWeight.regular` · `medium` · `semibold` · `bold` · `heavy` | 400 · 500 · 600 · 700 · 800 | `--hjm-font-weight-<이름>` | `fontWeight.<이름>` | Text `emphasis`: `regular` 400 · `medium` 500 · `strong` 500 (2026-10-17, 가장 강한 강조 = 제목 굵기). 컴포넌트 recipe는 제목 500, 큰 숫자(Statistic 값)·선택 상태 600을 쓰고 700·800은 브루탈리즘 프리셋 외에 쓰지 않는다 |
 | `letterSpacing.tight` · `normal` · `wide` | -0.2 · 0 · 0.2 | — | `letterSpacing.<이름>` | 자간 조정이 필요한 제품 고유 글자. HJM 컴포넌트는 자간을 지정하지 않는다 |
 | `numeric.tabular` · `proportional` | `tabular-nums` · `proportional-nums` | — | `numeric.<이름>` | 바뀌는 숫자(카운터·통계·날짜 칸)는 `tabular`로 폭을 고정 |
 | `largeTextThreshold` | 1.6 | 루트 `data-large-text="true"` | `largeTextThreshold` | 글자 배율이 이 값 이상이면 큰 글자 배치로 바꾼다 |
 
-Native는 `fonts="pretendard"`일 때 500을 `Pretendard-Medium`, 700을 `Pretendard-Bold` face로 그린다.
+Native는 `fonts="pretendard"`일 때 500을 `Pretendard-Medium`, 600을 `Pretendard-SemiBold` face로 그린다(`resolvePretendardNativeFace`).
 `@hjmds/react-native/fonts`의 `hjmPretendardFonts`가 400~800 다섯 face를 모두 번들한다. Web은 Pretendard Variable 한 파일이 모든 굵기를 덮는다.
 
 Native 경로의 `theme`은 `useHjmNativeTheme()`, 나머지 이름은 `@hjmds/design-contracts/foundations` import다.
@@ -62,9 +61,17 @@ Web 크기 변수는 `rem × --hjm-text-scale`이라 Provider의 `textScale`을
 
 ## 근거
 
-2026-10-17 사용자 결정: `label`은 폼 라벨·섹션 부제목이 본문 대비 약해 500(본문 400과 제목 600 사이)으로 정하고
+2026-10-17 사용자 결정: `label`은 폼 라벨·섹션 부제목이 본문 대비 약해 500으로 정하고
 Web·Native 모두 기본으로 그린다. `heading.level1`·`level2`는 Pretendard 800이 큰 크기에서 무겁고 거칠어 700으로
-낮췄다(제목 단계 3~5는 같은 날 600). 브루탈리즘 프리셋은 강한 강조 프리셋이라 level1·2를 800으로 명시해 유지한다.
+낮췄다(제목 단계 3~5는 같은 날 600). 같은 날 두 번째 검토("굵기 좀더 줄여")에서 한 단계씩 더 낮춰 큰 제목 600,
+제목 단계 500, 강조 `strong` 500이 됐다. Web CSS는 `--hjm-type-title-weight`·`--hjm-text-emphasis-*` 역할 변수로 같은 값을 읽는다.
+브루탈리즘 프리셋은 강한 강조 프리셋이라 `typography.heading`(따라서 Heading level1~3) 굵기를 800으로 명시해 유지한다. 크기는 공통 단계를 따른다.
+
+2026-10-17 사용자 결정("글자 너무 커", "큰 글자 정책은 없애"): 큰 글자 단계(display)를 폐지했다. HJM에서 가장 큰 글자는
+`typography.heading` 24 / 줄 32다. 계기는 Native Storybook 서비스 소개 화면의 히어로 제목(level1 40)과 구획 제목(level2 32)이
+화면에 비해 지나치게 컸던 것이다. `heading.level1`·`level2`의 40·32와 semibold 600 단계를 없애고 두 이름을 `level3`(24/32/500)과
+같은 값으로 고정했다. 디자인 프로필도 이 상한을 넘는 글자 크기를 `RangeError`로 거부하므로 에디토리얼(56/42/30)·브루탈리즘(48/38/30)의
+확대 크기도 함께 없앴다. 랜딩 대표 제목은 `level3`, 구획 제목은 `level4`, 카드 제목은 `level5`로 위계를 만든다.
 
 ## 쓰는 법
 
@@ -94,6 +101,7 @@ import { Heading } from "@hjmds/react-native/heading";
 ## 하지 말 것
 
 - `font-size: 15px`, `fontWeight: "900"`처럼 단계 밖 값을 쓰지 않는다.
+- 24보다 큰 글자(히어로·큰 숫자·표지 제목)를 제품 CSS·StyleSheet로 만들지 않는다. 강조는 위계(level3 → level4 → level5)·굵기·여백으로 한다.
 - 크기를 맞추려고 Heading의 `semanticLevel`을 바꾸지 않는다. 시각 크기는 `level`, 문서 구조는 `semanticLevel`이다.
 - 글자 크기를 고정해 OS 글자 크기 설정을 막지 않는다(`allowFontScaling={false}`, px 고정 `font-size`).
 - 줄 높이를 지워 글자를 겹치게 하지 않는다. 한국어 본문은 토큰 줄 높이를 그대로 쓴다.
@@ -117,10 +125,10 @@ import { Heading } from "@hjmds/react-native/heading";
 프로필 계약에서 확인하고 앱 CSS로 내부 값을 덮지 않는다.
 
 
-Heading의 다섯 시각 단계는 `defineHjmDesignProfile({ tokens: { heading: ... } })`로
-일괄 지정한다. Web `--hjm-heading-size/line-height/weight`, Native Heading의 Text
+Heading의 시각 단계는 `defineHjmDesignProfile({ tokens: { heading: ... } })`로
+일괄 지정한다. 어느 단계도 `typography.heading` 24를 넘을 수 없다. Web `--hjm-heading-size/line-height/weight`, Native Heading의 Text
 metrics로 연결된다. 해당 heading을 담은 Provider에서 가장 가까운 profile을 읽는다.
-level3/4/5는 기존 typography heading/titleLarge/title override를 기본으로 병합하며
+level1/2/3은 typography heading, level4/5는 titleLarge/title override를 기본으로 병합하며
 명시적인 heading 값이 우선한다. 문서의 h1~h6 순서는 `semanticLevel`이 소유한다.
 
 제목·본문에 서로 다른 글꼴이 필요하면 [표시·읽기·기술 글자](font-roles.md)를 사용한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.27.2",
+  "version": "1.28.0",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {