@hjmds/design-contracts 1.12.0 → 1.13.0

package/docs/usage/tokens/size.md

@@ -0,0 +1,74 @@
+# 크기
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/foundations.ts`(`glyph`·`control`), `src/component-recipes.ts`(`iconRecipe`·`spinnerRecipe`·`chipRecipe`·`avatarRecipe`·`skeletonRecipe`), `src/base-recipes.ts`(`buttonRecipe`), `src/design-system-provider.ts`(`visibleControlHeight`), `packages/react/src/theme.ts`
+- 스토리북: `배포/토큰/공간과 크기/크기`
+
+## 언제 쓰나
+
+아이콘·작은 그림(glyph)의 크기와 누를 수 있는 컨트롤의 높이·최소 터치 영역을 정할 때 쓴다. 모든 버튼의 폭이나 화면 요소의
+크기를 뜻하지 않는다. 화면 폭·행 높이는 [화면 여백과 너비](layout.md)에 있다.
+
+## 값
+
+### glyph(아이콘·작은 그림)
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `glyph.xs` | 14 | — | `glyph.xs` | Spinner `small` |
+| `glyph.sm` | 20 | — | `glyph.sm` | Spinner `medium`(기본), 작은 아이콘 |
+| `glyph.md` | 24 | — | `glyph.md` | Icon 기본 크기, Steps 표지 |
+| `glyph.lg` | 28 | — | `glyph.lg` | Spinner `large`, EmptyState 아이콘 |
+| `glyph.xl` | 32 | — | `glyph.xl` | 큰 아이콘 |
+| `glyph.xxl` | 44 | — | `glyph.xxl` | Skeleton 원 기본 지름, Calendar `large` 날짜 칸 지름 |
+| `glyph.xxxl` | 48 | — | `glyph.xxxl` | 가장 큰 아이콘 |
+
+Icon의 `size` prop은 이 이름(`"md"`)을 받는다. Avatar는 glyph가 아니라 자기 크기(`small` 32 · `medium` 40 · `large` 48 · `xlarge` 64)를 쓴다.
+
+### control(컨트롤 높이·터치 영역)
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `control.minTouchTarget` | 44 | `--hjm-control-min-touch-target` | `control.minTouchTarget` | 누를 수 있는 모든 것의 최소 터치 영역(가로·세로). ListRow `compact` 한 줄, Calendar `medium` 칸 |
+| `control.buttonHeight.small` | 36 | `--hjm-control-button-small` | `control.buttonHeight.small` | Button `size="small"`. `control.buttonHitSlop.small` 4를 더해 터치 영역 44 |
+| `control.buttonHeight.medium` | 44 | `--hjm-control-button-medium` | `control.buttonHeight.medium` | Button `size="medium"`(기본) |
+| `control.buttonHeight.large` | 52 | `--hjm-control-button-large` | `control.buttonHeight.large` | Button `size="large"`, 화면 하단 주 행동 |
+| `control.fieldHeight` | 44 | `--hjm-control-field-height` | `control.fieldHeight` | 한 줄 입력 필드 높이 |
+| `control.chipHeight.small` | 36 | — | `control.chipHeight.small` | Chip `size="small"` |
+| `control.chipHeight.medium` | 44 | — | `control.chipHeight.medium` | Chip `size="medium"` |
+| `control.selectionIndicator` | 24 | — | `control.selectionIndicator` | Checkbox·Radio 표지 상자 |
+
+Provider의 `minimumVisualTarget`을 켜면 보이는 버튼 높이가 44보다 작아지지 않는다(`small`도 44). Web은 `--hjm-control-button-*`에 반영된다.
+Native 경로의 `glyph`·`control`은 `@hjmds/design-contracts/foundations` import다.
+
+## 쓰는 법
+
+```tsx
+// Web
+import { Icon } from "@hjmds/react/display";
+
+<Icon name="search" size="sm" />
+// 제품 고유 누름 영역: .product-tile { min-block-size: var(--hjm-control-min-touch-target); }
+```
+
+```tsx
+// Native
+import { Pressable } from "react-native";
+import { control, glyph } from "@hjmds/design-contracts/foundations";
+
+<Pressable style={{ minHeight: control.minTouchTarget, minWidth: control.minTouchTarget }} onPress={open}>
+  <ProductMark width={glyph.md} height={glyph.md} />
+</Pressable>
+```
+
+아이콘 사용법은 [Icon](../components/icon.md), 버튼 크기 선택은 [Button 배치](../components/button.md#배치)를 본다.
+
+## 하지 말 것
+
+- 누를 수 있는 영역을 44보다 작게 만들지 않는다. 그림이 작으면 hitSlop·padding으로 터치 영역을 44로 맞춘다.
+- Button·필드 높이를 `style`로 바꾸지 않는다. `size` prop으로만 고른다.
+- 아이콘 크기에 18, 22 같은 새 숫자를 쓰지 않는다.

package/docs/usage/tokens/spacing.md

@@ -0,0 +1,73 @@
+# 간격
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/foundations.ts`(`spacing`·`layout`), `src/grid.ts`(`gridGaps`), `src/base-recipes.ts`(`buttonRecipe`·`fieldRecipe`), `src/auth-screen.ts`, `packages/react/src/theme.ts`, `packages/react/src/styles.css`
+- 스토리북: `배포/토큰/공간과 크기/간격`
+
+## 언제 쓰나
+
+요소 사이 간격(gap)과 영역 안쪽 여백(padding)을 정할 때 쓴다. 숫자는 Web에서 CSS px, Native에서 dp(pt)다.
+화면 좌우 여백·최대 폭은 이 값을 묶어 이름을 붙인 [화면 여백과 너비](layout.md)를 먼저 본다.
+
+## 값
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `spacing.xxs` | 4 | `--hjm-space-xxs` | `spacing.xxs` · `theme.tokens.spacing.xxs` | 목록 팝업 안쪽 여백(Select·Menubar) |
+| `spacing.xs` | 8 | `--hjm-space-xs` | `spacing.xs` · `theme.tokens.spacing.xs` | 필드 라벨과 입력 사이, DatePicker 팝업과 입력 사이, EmptyState 안 요소 사이 |
+| `spacing.sm` | 12 | `--hjm-space-sm` | `spacing.sm` · `theme.tokens.spacing.sm` | 나란한 버튼 사이, Toast 사이, small 버튼 좌우·필드 위아래 안쪽 여백 |
+| `spacing.md` | 16 | `--hjm-space-md` | `spacing.md` · `theme.tokens.spacing.md` | Stack·Grid 기본 gap, medium 버튼·필드 좌우 안쪽 여백, `layout.contentGap`, `layout.pagePadding.compact` |
+| `spacing.lg` | 20 | `--hjm-space-lg` | `spacing.lg` · `theme.tokens.spacing.lg` | large 버튼 좌우 안쪽 여백, `layout.pagePadding.regular`, Dialog 하단 여백 |
+| `spacing.xl` | 24 | `--hjm-space-xl` | `spacing.xl` · `theme.tokens.spacing.xl` | `layout.sectionGap`, `layout.pagePadding.spacious`, EmptyState·Result 좌우 여백 |
+| `spacing.xxl` | 32 | `--hjm-space-xxl` | `spacing.xxl` · `theme.tokens.spacing.xxl` | EmptyState 위아래 여백 |
+| `spacing.xxxl` | 40 | `--hjm-space-xxxl` | `spacing.xxxl` · `theme.tokens.spacing.xxxl` | Result 위아래 여백, AuthScreen regular 위아래 여백 |
+
+- Native 경로의 `spacing`은 `@hjmds/design-contracts/foundations` import, `theme`은 `useHjmNativeTheme()` 결과다.
+- Stack·Grid·Surface의 `gap`·`padding` prop은 이 토큰 이름(`"md"`)을 받는다. Grid는 `none`(0)을 하나 더 받는다.
+- 두 단계 사이에서 애매하면 작은 쪽을 고른다. 새 숫자(10, 18 등)를 만들지 않는다.
+
+## 쓰는 법
+
+```tsx
+// Web
+import { Stack, Surface } from "@hjmds/react/layout";
+
+<Surface padding="lg">
+  <Stack gap="sm">{children}</Stack>
+</Surface>
+
+// 제품 CSS가 꼭 필요하면 변수로: .product-toolbar { gap: var(--hjm-space-xs); padding-inline: var(--hjm-space-md); }
+```
+
+```tsx
+// Native
+import { StyleSheet } from "react-native";
+import { spacing } from "@hjmds/design-contracts/foundations";
+import { Stack, Surface } from "@hjmds/react-native/primitives";
+
+<Surface padding="lg">
+  <Stack gap="sm">{children}</Stack>
+</Surface>
+
+const styles = StyleSheet.create({ toolbar: { gap: spacing.xs, paddingHorizontal: spacing.md } });
+```
+
+간격 배치 규칙은 [Stack](../components/stack.md)·[Grid](../components/grid.md)·[Container](../components/container.md) 지침에 있다.
+
+## 하지 말 것
+
+- `margin: 13px`, `padding: 10` 같은 숫자를 직접 쓰지 않는다. 토큰에 없는 리듬은 계약 공백이므로 이슈로 올린다.
+- 자식마다 margin을 붙여 간격을 만들지 않는다. 감싸는 Stack·Grid의 `gap`으로 정한다.
+- `--hjm-space-*` 변수를 제품 CSS에서 재정의하지 않는다([브랜드 경계 §3](../../brand-boundary.md)).
+- 화면 좌우 여백을 화면마다 `spacing.lg`로 적지 않는다. [Container](../components/container.md)의 `gutter`를 쓴다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 단위 | CSS px(`--hjm-space-*`는 `px` 문자열) | dp(pt) 숫자 |
+| Stack `gap` 타입 | 토큰 이름만 | 토큰 이름 또는 숫자 |

package/docs/usage/tokens/stroke.md

@@ -0,0 +1,50 @@
+# 테두리
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/foundations.ts`(`stroke`), `src/component-contracts.ts`(`focusIndicatorContract`), `src/base-recipes.ts`(`fieldRecipe`), `src/component-recipes.ts`(`segmentedControlRecipe`·`tabsRecipe`), `packages/react/src/theme.ts`
+- 스토리북: `배포/토큰/표면과 움직임/테두리`
+
+## 언제 쓰나
+
+테두리·구분선·포커스 링의 두께를 정할 때 쓴다. 색은 [색상](color.md)의 테두리 역할(`border`·`borderControl`·`border.focus`)에서 고른다.
+
+## 값
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `stroke.subtle` | 1 | `--hjm-stroke-subtle` | `stroke.subtle` | 약한 경계(`border.subtle` 색과 함께) |
+| `stroke.default` | 1 | `--hjm-stroke-default` | `stroke.default` | 영역 경계·구분선·필드 테두리(`fieldRecipe.borderWidth` 1) |
+| `stroke.strong` | 2 | `--hjm-stroke-strong` | `stroke.strong` | 선택 표시: SegmentedControl 선택 칸 테두리, Tabs 현재 탭 밑줄 높이 |
+| `stroke.focus` | 2 | `--hjm-stroke-focus` · `--hjm-focus-width` | `stroke.focus` | 키보드 포커스 링. 바깥 간격 2(`--hjm-focus-offset`), 색 `contentBrand`(`--hjm-color-focus`) |
+
+Native 경로의 `stroke`는 `@hjmds/design-contracts/foundations` import다.
+
+## 쓰는 법
+
+```tsx
+// Web
+// 제품 고유 영역: .product-panel { border: var(--hjm-stroke-default) solid var(--hjm-color-border); }
+import { Surface } from "@hjmds/react/layout";
+
+<Surface bordered>{children}</Surface>
+```
+
+```tsx
+// Native
+import { View } from "react-native";
+import { stroke } from "@hjmds/design-contracts/foundations";
+import { useHjmNativeTheme } from "@hjmds/react-native/provider";
+
+const theme = useHjmNativeTheme();
+<View style={{ borderWidth: stroke.default, borderColor: theme.colors.border }} />;
+```
+
+## 하지 말 것
+
+- 0.5·1.5 같은 두께를 만들지 않는다. hairline이 필요하면 `stroke.subtle`과 `border.subtle` 색을 쓴다.
+- HJM 컴포넌트의 포커스 링을 지우거나(`outline: none`) 다시 그리지 않는다. 제품 고유 컨트롤만 같은 값(`stroke.focus` 2, 간격 2)으로 그린다.
+- 테두리 두께로 선택 상태를 알리는 경우 색도 함께 바꾼다. 두께만으로는 구분이 약하다.

package/docs/usage/tokens/theme-studio.md

@@ -0,0 +1,70 @@
+# 테마 편집
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [테마 작업실](../../theme-studio.md), [브랜드 경계](../../brand-boundary.md), `src/theme-studio.ts`, `src/palette-contrast.ts`, `showcase/web/src/foundations/ThemeStudio.stories.tsx`, `showcase/native/src/ThemeStudio.stories.tsx`
+- 스토리북: `배포/토큰/편집 도구/테마 편집`
+
+## 언제 쓰나
+
+제품 브랜드 색을 정할 때, 바꿀 색을 light·dark 양쪽에서 실제 컴포넌트에 입혀 보고 대비를 확인한 뒤
+Provider에 넣을 `brandPalette` 설정을 얻는 작업 도구다. 새 테마 엔진이나 자동 색 생성기가 아니다.
+
+도구 흐름(Storybook 화면, Web·Native 같음):
+
+1. light·dark 각각 세 역할(주요 버튼 배경 `primary`, 주요 버튼 글자 `onPrimary`, 브랜드 강조 글자 `contentBrand`)에 `#rrggbb`를 넣고 적용한다.
+2. 같은 화면 아래 샘플(버튼·입력·비활성·오류·아이콘·알림·기록 목록)이 그 팔레트로 다시 그려진다.
+3. "색 대비 확인"에서 각 쌍의 대비·기준·통과 여부를 본다. 미달이 하나라도 있으면 색을 고친다.
+4. "설정 내보내기"로 `{ "brandPalette": … }` JSON을 받는다(Web 파일 다운로드, Native OS 공유). 아래 코드 블록에서 복사해도 된다.
+
+## 값
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `StudioColorRole` | `primary` · `onPrimary` · `contentBrand` | `--hjm-color-primary` · `--hjm-color-on-primary` · `--hjm-color-content-brand` | `theme.colors.primary` 등 | 도구에서 바꿀 수 있는 세 역할 |
+| `applyStudioColor(palette, theme, role, color)` | 여섯 자리 HEX만 허용(아니면 `TypeError`), 소문자로 저장, 입력 객체 불변 | — | `@hjmds/design-contracts/theme-studio` | 역할 하나의 색 바꾸기 |
+| `studioReport(palette, theme)` | 각 규칙의 `foreground`·`background`·`ratio`·`minimum`·`pass` | — | `@hjmds/design-contracts/theme-studio` | HJM 기본 팔레트에 바꾼 값을 합쳐 대비 검사. 통과 판정은 반올림 전 값 |
+| `exportStudioPalette(palette)` | `{ "brandPalette": { "light": {…}, "dark": {…} } }` JSON 문자열 | — | `@hjmds/design-contracts/theme-studio` | 산출물. 바꾼 key만 담는다 |
+| 대비 기준 | 글자 4.5 · 형태(`primary`·`borderControl`)와 `textWeak` 3 | — | `paletteContrastRules` | [색상](color.md)의 쌍 표와 같다 |
+
+## 쓰는 법
+
+산출물은 Provider의 `brandPalette` prop에 그대로 넣고, 같은 값을 제품 테스트에서 `checkBrandPaletteContrast`로 검사한다.
+
+```tsx
+// Web
+import { HjmProvider } from "@hjmds/react/provider";
+import { brandPalette } from "./brand-palette"; // 테마 편집에서 내보낸 JSON의 brandPalette
+
+<HjmProvider brandPalette={brandPalette}>{app}</HjmProvider>
+```
+
+```tsx
+// Native
+import { HjmNativeProvider } from "@hjmds/react-native/provider";
+import { checkBrandPaletteContrast } from "@hjmds/design-contracts/palette-contrast";
+import { brandPalette } from "./brand-palette";
+
+<HjmNativeProvider brandPalette={brandPalette} safeAreaInsets={insets}>{app}</HjmNativeProvider>
+
+// 제품 테스트
+expect(checkBrandPaletteContrast(brandPalette)).toEqual([]);
+```
+
+## 하지 말 것
+
+- 통과 표시를 전체 접근성 인증으로 보고하지 않는다. 지정된 색 쌍의 대비일 뿐이고 hover·focus·실제 배경은 따로 확인한다.
+- 내보낸 JSON을 HJM 중앙 토큰이나 다른 제품 기본값으로 쓰지 않는다. 그 제품의 `brandPalette`에만 쓴다.
+- 도구 밖에서 `--hjm-color-*`를 재정의해 같은 효과를 내지 않는다([브랜드 경계 §3](../../brand-boundary.md)).
+- Showcase 샘플 문구·예시 색을 제품에 복사하지 않는다. 도구의 라벨·오류 문구는 showcase 소유다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 내보내기 | `hjm-brand-palette.json` 파일 다운로드 | OS 공유 시트(`Share.share`) |
+| 기록 샘플 | DataTable | List |
+| 키보드 | — | 입력이 키보드에 가리지 않게 스크롤이 키보드 높이를 따른다 |

package/docs/usage/tokens/typography-studio.md

@@ -0,0 +1,70 @@
+# 글꼴 편집
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [테마 작업실](../../theme-studio.md), `src/foundations.ts`(`fontFamily`), `showcase/web/src/foundations/TypographyStudio.stories.tsx`, `showcase/native/src/TypographyStudio.stories.tsx`, `showcase/shared/typography-studio.ts`
+- 스토리북: `배포/토큰/편집 도구/글꼴 편집`
+
+## 언제 쓰나
+
+제품 서체 후보를 정할 때, 후보 폰트를 기본 서체와 나란히 같은 크기로 그려 한글·영문·숫자·긴 문장을 비교하고
+출처·라이선스를 함께 기록하는 작업 도구다. 공개 API가 없는 Storybook 도구이며 HJM 토큰을 바꾸지 않는다.
+
+도구 흐름:
+
+1. 후보 폰트를 넣는다. Web은 `.woff`·`.woff2`·`.ttf`·`.otf` 파일 선택, Native는 사용 권한이 있는 OTF·TTF 주소(`https://` 또는 `file://`)를 넣고 "서체 불러오기".
+2. 상태 문구가 비어 있음 → 불러오는 중 → 불러옴 / 실패로 바뀐다. 실패하면 기본 서체로 표시한다.
+3. "기본 서체"와 "비교할 서체" 두 카드에서 `heading` 크기 제목, 본문, 굵은 본문을 비교한다. 한글 글리프가 없는 부분은 기본 서체로 대체될 수 있다.
+4. 서체 출처·라이선스 문서 주소를 적고, 아래 "서체 후보 설정" 코드 블록을 기록으로 가져간다.
+
+## 값
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| 비교 기준 서체 | Web `system-ui, sans-serif`, Native OS 기본 | `--hjm-font-family-ui`(HJM 기본 목록은 [타이포그래피](typography.md)) | — | "기본 서체" 카드 |
+| 비교 글자 크기 | `typography.heading` 24 · `typography.body` 14 · body bold | `--hjm-type-heading-*` · `--hjm-type-body-*` | `theme.tokens.typography` | 두 카드가 같은 단계로 그린다 |
+| 산출물(Web) | `{ fileName, source, license, status, fallback: "system-ui, sans-serif" }` JSON | — | — | 후보 기록. 폰트 파일은 포함하지 않는다 |
+| 산출물(Native) | `{ family, status, source, license }` JSON | — | — | 후보 기록 |
+| `status` | `empty` · `loading` · `ready` · `error` | — | — | 불러오기 상태 |
+
+## 쓰는 법
+
+후보가 정해지면 제품이 폰트 파일과 라이선스를 소유하고 제품 앱에서 등록한다. HJM 컴포넌트는 Web에서 Provider 루트의 서체를,
+`host="contents"`일 때는 제품 루트의 서체를 상속한다.
+
+```tsx
+// Web
+import { HjmProvider } from "@hjmds/react/provider";
+
+// 제품 CSS: @font-face { font-family: "ProductSans"; src: url("/fonts/product-sans.woff2") format("woff2"); }
+// 제품 CSS: .product-root { font-family: "ProductSans", system-ui, sans-serif; }
+<div className="product-root">
+  <HjmProvider host="contents">{app}</HjmProvider>
+</div>
+```
+
+```tsx
+// Native
+import { useFonts } from "expo-font";
+
+const [loaded] = useFonts({ ProductSans: require("./assets/fonts/ProductSans.otf") });
+// HJM Native 컴포넌트는 fontFamily를 지정하지 않는다. 제품 서체 적용 범위는 제품 Text 래퍼가 정한다.
+```
+
+## 하지 말 것
+
+- 라이선스가 확인되지 않은 폰트를 제품에 넣지 않는다. 도구에 적은 출처·라이선스 주소를 제품 문서에 남긴다.
+- 도구에서 불러온 폰트를 저장·배포 경로로 쓰지 않는다. Web 파일은 현재 미리보기에서만 쓰고, Native 등록은 앱 종료까지만 남는다.
+- `--hjm-font-family-ui`를 제품 CSS에서 재정의하지 않는다([브랜드 경계 §3](../../brand-boundary.md)).
+- 서체를 바꾸면서 글자 크기·줄 높이 토큰을 함께 바꾸지 않는다. 같은 크기에서 비교한 결과로 고른다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 폰트 입력 | 파일 선택, `FontFace`로 메모리에서 등록(업로드 없음) | 주소 입력, `expo-font` `loadAsync` |
+| 초기화 | 등록한 폰트를 문서에서 제거 | 기본 서체로 돌아가지만 등록은 앱 종료까지 유지 |
+| 서체 적용 | 스타일 `fontFamily: "<family>", system-ui, sans-serif` | 등록이 끝난 뒤에만 `fontFamily` 적용 |

package/docs/usage/tokens/typography.md

@@ -0,0 +1,89 @@
+# 타이포그래피
+
+- 단계: 토큰
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/foundations.ts`(`typography`·`heading`·`fontFamily`·`fontWeight`·`letterSpacing`·`numeric`·`largeTextThreshold`), `src/component-recipes.ts`(`textRecipe`), `packages/react/src/theme.ts`, `packages/react/src/provider.tsx`, `packages/react-native/src/provider.tsx`
+- 스토리북: `배포/토큰/색과 글자/타이포그래피`
+
+## 언제 쓰나
+
+글자 크기·줄 높이·굵기를 정할 때 쓴다. 대부분은 [Text](../components/text.md)의 `variant`·`emphasis`와
+[Heading](../components/heading.md)의 `level`로 고르고, 토큰을 직접 읽는 것은 제품 고유 그림(차트 라벨 등)일 때다.
+
+## 값
+
+### 글자 단계(`typography`, Text `variant`)
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `typography.caption` | 11 / 줄 16 / 400 | `--hjm-type-caption-size` · `-line-height` · `-weight` | `theme.tokens.typography.caption` | 가장 작은 보조 표기, AuthScreen 정책 링크 |
+| `typography.label` | 12 / 줄 18 / 600 | `--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 / 700 | `--hjm-type-title-*` | `theme.tokens.typography.title` | 카드 제목(`heading.level5`) |
+| `typography.titleLarge` | 20 / 줄 28 / 800 | `--hjm-type-title-large-*` | `theme.tokens.typography.titleLarge` | 큰 구획 제목(`heading.level4`) |
+| `typography.heading` | 24 / 줄 32 / 800 | `--hjm-type-heading-*` | `theme.tokens.typography.heading` | 화면의 가장 큰 제목 |
+
+### 문서 제목 단계(`heading`, Heading `level`)
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `heading.level1` | 40 / 줄 48 / 800 | — | `heading.level1` | 랜딩·문서의 대표 제목 |
+| `heading.level2` | 32 / 줄 40 / 800 | — | `heading.level2` | 긴 페이지의 큰 구획 제목 |
+| `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` | 카드 제목 |
+
+### 서체·굵기·자간·숫자
+
+| 토큰 | 값 | Web CSS 변수 | Native 경로 | 용도 |
+| --- | --- | --- | --- | --- |
+| `fontFamily.ui` | Inter, Pretendard, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif | `--hjm-font-family-ui` | `fontFamily.ui` | 화면 글자. Native는 HJM이 서체를 지정하지 않아 OS 기본 서체로 그린다 |
+| `fontFamily.code` | ui-monospace, SFMono-Regular, 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 |
+| `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 경로의 `theme`은 `useHjmNativeTheme()`, 나머지 이름은 `@hjmds/design-contracts/foundations` import다.
+Web 크기 변수는 `rem × --hjm-text-scale`이라 Provider의 `textScale`을 따른다.
+
+## 쓰는 법
+
+```tsx
+// Web
+import { Text } from "@hjmds/react/layout";
+import { Heading } from "@hjmds/react/heading";
+
+<Heading level="level3">{t("orders.title")}</Heading>
+<Text as="p" variant="body" tone="muted">{t("orders.hint")}</Text>
+// 제품 고유 그림: .product-axis-label { font-size: var(--hjm-type-caption-size); line-height: var(--hjm-type-caption-line-height); }
+```
+
+```tsx
+// Native
+import { Text } from "@hjmds/react-native/primitives";
+import { Heading } from "@hjmds/react-native/heading";
+
+<Heading level="level3">{t("orders.title")}</Heading>
+<Text variant="body" tone="muted">{t("orders.hint")}</Text>
+```
+
+## 하지 말 것
+
+- `font-size: 15px`, `fontWeight: "900"`처럼 단계 밖 값을 쓰지 않는다.
+- 크기를 맞추려고 Heading의 `semanticLevel`을 바꾸지 않는다. 시각 크기는 `level`, 문서 구조는 `semanticLevel`이다.
+- 글자 크기를 고정해 OS 글자 크기 설정을 막지 않는다(`allowFontScaling={false}`, px 고정 `font-size`).
+- 줄 높이를 지워 글자를 겹치게 하지 않는다. 한국어 본문은 토큰 줄 높이를 그대로 쓴다.
+- 제품 서체는 [글꼴 편집](typography-studio.md)으로 비교·라이선스를 확인한 뒤 제품이 소유한다. `--hjm-font-family-ui`를 재정의하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 단위 | rem(16px 기준) × `--hjm-text-scale` | dp. OS 글자 크기를 따르고, Provider `textScale`을 주면 HJM이 한 번만 곱한다 |
+| 서체 | `--hjm-font-family-ui` 목록 | OS 기본 서체(HJM이 `fontFamily`를 지정하지 않음) |
+| 큰 글자 판정 | 루트 `data-large-text` | `isLargeTextScale(environment.textScale)` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -660,6 +660,12 @@
       "react-native": "./dist/action-session.js",
       "import": "./dist/action-session.js",
       "default": "./dist/action-session.js"
+    },
+    "./screen-patterns": {
+      "types": "./dist/screen-patterns.d.ts",
+      "react-native": "./dist/screen-patterns.js",
+      "import": "./dist/screen-patterns.js",
+      "default": "./dist/screen-patterns.js"
     }
   },
   "files": [