@highpixel-co/palda-design-system 0.4.1 → 0.6.0

package/dist/guide/docs/TOKEN_POLICY.md

@@ -0,0 +1,266 @@
+# Token Policy
+
+**모든 디자인 값을 token으로만 쓰게 하는 규칙과, 자리마다 어느 token을 고르는지의 canonical 이름
+목록이다.**
+
+- 모든 색상, spacing, typography, radius, motion 값은 token으로 정의한다.
+- 이름은 실제 값이 아니라 역할을 표현한다. 예: `color.action.primary.background`.
+- 컴포넌트 CSS에는 `var(--token)` 참조만 쓴다. 시안에 적힌 리터럴 값(`#54B336`, `36px`)을 그대로 옮기지 않는다.
+- 필요한 token이 없으면 추가하지 말고 먼저 확인받는다. 값을 지어내지 않는다. 과거에 있던 token이라도 복원은 확인 대상이다.
+- **값이 어긋나면 코드가 옳다.** 저장소가 SSOT이고([`decisions/0001`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0001-design-system-ssot.md), 자산별 경계는 [`decisions/0016`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0016-asset-ssot-boundary.md)), Figma와 다른 자리는 코드를 고치지 않고 [`FIGMA_ALIGNMENT_DELTA.md`](FIGMA_ALIGNMENT_DELTA.md)에 Figma가 바뀌어야 할 목록으로 적는다. 이름이 어긋나는 자리는 [`FIGMA_NAME_MAPPING.md`](FIGMA_NAME_MAPPING.md)에 있다.
+- 저장소의 token 값은 확정치로 취급한다. 명도 대비 미달처럼 품질 문제를 발견하면 보고하되, 컴포넌트에서 다른 색으로 바꾸거나 값 변경을 반복해서 제안하지 않는다.
+- 보더 두께는 예외다. 시스템 전체가 항상 `1px`이며 token으로 만들지 않고 CSS에 직접 쓴다.
+- `tokens/generated/`는 직접 수정하지 않는다. `tokens/*.tokens.json`을 고치고 `pnpm tokens:build`로 다시 만든 뒤, 소스와 생성 파일을 함께 커밋한다. 생성 파일이 빠지면 `pnpm check:generated`가 실패한다.
+
+## canonical 이름
+
+**아래 이름이 정답이다.** Figma가 다른 이름을 쓰더라도 코드는 이 이름을 유지한다. 시안에서 옮길
+때 헷갈리는 자리는 [`FIGMA_NAME_MAPPING.md`](FIGMA_NAME_MAPPING.md)에 짝을 적어 두었다.
+
+| 자리          | 이름                                          | 아닌 것                        |
+| ------------- | --------------------------------------------- | ------------------------------ |
+| 오렌지 패밀리 | `secondary`                                   | `point`                        |
+| 주황 텍스트   | `text/secondary`                              | `text/accent`                  |
+| 퍼플 텍스트   | `text/accent`                                 | `text/secondary`               |
+| hover·pressed | `*-hover-pressed`                             | `*-hover`                      |
+| 폰트 웨이트   | `medium`(500) · `semibold`(600) · `bold`(700) | `regular`(500) · `medium`(600) |
+| 그림자        | `shadow/100`                                  | `depth100`                     |
+
+텍스트 색 둘과 폰트 웨이트는 **Figma와 이름이 뒤바뀌어 있다.** 같은 이름끼리 기계적으로 옮기면
+색과 굵기가 뒤집히므로, 이 자리는 표를 보고 옮긴다.
+
+패밀리 이름과 텍스트 이름은 항상 같은 색을 가리킨다. `secondary` 패밀리가 주황이므로
+`text/secondary`도 주황이다. 새 token을 만들 때도 이 짝을 깨지 않는다.
+
+아래는 어떤 상황에 어떤 token을 고르는지다. semantic token을 먼저 찾고, 대응하는 것이 없을 때만
+primitive를 쓴다.
+
+## 색
+
+primitive 색과 hex 리터럴은 쓰지 않는다. 지금 컴포넌트에 하나도 없고, 그 상태를 유지한다.
+색만으로 상태를 전달하지 않는 것은 [`ACCESSIBILITY.md`](ACCESSIBILITY.md)를 따른다.
+
+### 패밀리
+
+**액션 색**은 눌리는 것에 쓴다. 넷 다 hover를 갖는다.
+
+| 패밀리      | 값         | 언제                                                         |
+| ----------- | ---------- | ------------------------------------------------------------ |
+| `primary`   | gray-900   | 주력 액션, 본문, 기본 아이콘, 중립 컨트롤                    |
+| `accent`    | purple-500 | 강조 액션과 선택 상태. 라디오 선택, 스위치 켜짐, 입력 포커스 |
+| `secondary` | orange-600 | 보조 강조                                                    |
+| `danger`    | red-400    | 위험과 오류 전용                                             |
+
+`accent`는 아껴 쓴다. 한 화면에서 강조 액션은 하나다. 강조를 더 만들어야 하면 색이 아니라
+명도와 채움으로 낸다.
+
+**status 색**은 읽는 것에 쓴다. 상태 배지와 배너처럼 **눌리지 않는 표시** 전용이다.
+
+| 패밀리    | 채움      | 아이콘·보더 | 글자       |
+| --------- | --------- | ----------- | ---------- |
+| `success` | green-50  | green-700   | green-800  |
+| `warning` | orange-50 | orange-700  | orange-800 |
+
+`danger`는 액션이면서 status이기도 하다 — 오류 배지·배너는 `danger/subtle` 채움에
+`text/danger` 글자를 쓴다.
+
+**`warning`과 `secondary`는 같은 orange 램프를 쓴다.** primitive에 amber 계열이 없어서이고,
+단계가 갈려(`warning`은 700·800, `secondary`는 500·600) 화면에서는 구분된다. 램프를 나눌지는
+Figma 결정 대기다.
+
+### 켤레
+
+액션 색은 셋을 한 켤레로 쓴다. 켤레를 벗어난 조합을 만들지 않는다.
+
+| 자리                     | token                          |
+| ------------------------ | ------------------------------ |
+| 채움                     | `color/{family}/default`       |
+| hover·active             | `color/{family}/hover-pressed` |
+| rest 틴트, disabled 배경 | `color/{family}/subtle`        |
+
+hover와 pressed는 하나로 다룬다. `color/state/pressed`가 정의되어 있지만 쓰는 곳이 없다.
+
+**status 색은 이 켤레를 따르지 않는다.** `success`·`warning`에는 `hover-pressed`가 없다. 눌리지
+않으니 hover가 생길 자리가 없고, 켤레를 맞추자고 쓰지 않을 토큰을 만들지 않는다. 이 둘이 버튼에
+필요해지는 날 그때 추가한다.
+
+**`primary/subtle`만 틴트가 아니라 흰색(gray-00)이다.** 그래서 중립 배지·칩의 rest 채움은
+`primary/subtle`이 아니라 `color/state/hover-pressed`를 쓴다. 흰색으로는 배경과 구분되지 않는다.
+아웃라인 컨트롤의 채움과 솔리드 채움 위 아이콘 색이 `primary/subtle`인 것도 흰색이라서다.
+
+### 글자와 아이콘
+
+| 놓이는 자리                 | 글자                     | 아이콘                   |
+| --------------------------- | ------------------------ | ------------------------ |
+| 솔리드 `{family}` 채움 위   | `color/text/on-{family}` | `color/primary/subtle`   |
+| 틴트 배경 위                | `color/text/{family}`    | `color/{family}/default` |
+| 밝은 배경, 아웃라인, 고스트 | `color/text/primary`     | `color/primary/default`  |
+| 보조 문구, placeholder      | `color/text/primary-sub` | —                        |
+| 오류 문구                   | `color/text/danger`      | —                        |
+| status 틴트 위              | `color/text/{status}`    | `color/{status}/default` |
+
+**아이콘은 글자를 따라가지 않는다.** 솔리드 채움 위 아이콘은 패밀리와 무관하게 흰색이다. accent
+칩이 선택돼도 purple-50이 아니라 흰 아이콘을 올린다. 아이콘에 텍스트 token을 쓰지 않는 이유는
+[`ICON_POLICY.md`](ICON_POLICY.md)에 있다.
+
+솔리드 `secondary` 채움 위 글자는 시안대로 `text/on-primary`를 쓴다. `text/on-secondary`도
+거의 흰색(orange-50)이라 대비는 사실상 같다.
+
+### 표면과 오버레이
+
+| token                  | 언제                                  |
+| ---------------------- | ------------------------------------- |
+| `color/surface/base`   | 바닥. 비활성 컨트롤의 배경. 모달 카드 |
+| `color/surface/raised` | 떠 있는 면. 카드·입력·메뉴 패널       |
+| `color/surface/sunken` | 눌린 면. 스위치 트랙                  |
+| `color/overlay/dim`    | 모달 뒤 스크림                        |
+| `color/overlay/glass`  | 비활성 베일. 스위치 disabled          |
+
+**모달만 `base`다.** 스크림 위에 뜨는 면이라 캔버스와 나란히 놓이지 않고, `raised`로는 dim 위에서
+떠 있다는 신호가 `shadow/100` 하나에만 남는다. 드롭다운 메뉴·토스트·프리뷰·카드는 캔버스와 같은
+평면에 놓이므로 `raised` 그대로다.
+
+투명하거나 중립인 요소의 hover는 `color/state/hover-pressed`를 덮는다.
+
+### 보더와 포커스
+
+| 상황              | token                                           |
+| ----------------- | ----------------------------------------------- |
+| 기본              | `color/border/default`                          |
+| hover             | `color/border/strong`                           |
+| 컬러 아웃라인     | `color/border/accent`, `color/border/secondary` |
+| 입력 focus 테두리 | `color/border/accent`                           |
+| 오류              | `color/border/danger`                           |
+| 포커스 링         | `color/border/focus`                            |
+
+**포커스 링은 `border/focus` 하나이고 `:focus-visible`에만 준다.** `:focus`는 클릭으로도 걸려서
+마우스 사용자에게 링이 뜬다. `check:css`가 막는다.
+
+`border/focus`는 purple-600이라 `accent`(purple-500)와 다른 값이다. 저장소 값이 확정치이므로
+그대로 쓰고 `accent`에 맞추지 않는다.
+
+포커스 링과 입력의 focus 테두리는 다른 자리다. 링은 요소 바깥의 `outline`이고, 입력은 테두리
+색이 `border/accent`로 바뀐다. TextField의 `accent` variant만 rest에서 이미 accent 보더라
+focus에서 `border/focus`로 구분한다.
+
+### 비활성
+
+배경 밝기로 갈린다. **섞어 쓰면 안 된다.**
+
+| 배경        | 글자                     | 아이콘                    |
+| ----------- | ------------------------ | ------------------------- |
+| 밝은 배경   | `color/text/disabled`    | `color/state/disabled`    |
+| 어두운 채움 | `color/text/on-disabled` | `color/state/on-disabled` |
+
+`text/disabled`는 검정 알파(alpha-black-30)라 어두운 채움 위에서 대비 1.42:1로 사라진다. 판단
+기준은 variant 이름이 아니라 그 상태에서 실제로 깔리는 배경이다.
+
+`opacity`로 일괄 처리하지 않는다. variant마다 배경과 글자 token을 각각 지정한다.
+
+## 타이포
+
+클래스 이름은 `palda-text-{계층}-{행간}-{무게}`다. 계층 → 행간 → 무게 순으로 고른다.
+개별 `font-*` 속성을 컴포넌트 CSS에서 조립하지 않는다. 이유는
+[`COMPONENT_POLICY.md`](COMPONENT_POLICY.md)에 있다.
+
+| 계층       | 크기 | 언제                                     | 쓰는 곳                                                     |
+| ---------- | ---- | ---------------------------------------- | ----------------------------------------------------------- |
+| `display`  | 32px | 쓰지 않는다                              | **없음 — 폐기 후보**                                        |
+| `headline` | 24px | 페이지 제목                              | 화면의 페이지 헤더 `h1`                                     |
+| `title`    | 20px | 빈 화면 제목                             | EmptyState                                                  |
+| `body1`    | 16px | 섹션·카드·모달 제목, 본문 목록의 행 제목 | FormSection·Card·Modal 제목·ListRow(`strong`)               |
+| `body2`    | 14px | 기본 컨트롤 라벨과 본문                  | Button·Chip·Radio·DropdownButton·TextField·Toast·EmptyState |
+| `label`    | 12px | 작은 라벨, 보조 문구                     | Badge(md)·Button(sm)·Chip(sm)·TextField 하단·Tooltip        |
+| `caption`  | 10px | 초소형 캡션                              | Badge(sm)                                                   |
+
+**한 화면의 제목 위계는 셋이다** — 페이지 `headline`(24) → 섹션·카드 `body1`(16) → 행
+`body2`(14). 그 아래 보조 문구가 `label`(12)이다. 코드가 이미 이 값을 갖고 있어(`FormSection`·
+`Card`·`ListRow`) 화면이 다시 고르는 것은 페이지 제목과 **본문 목록 여부** 둘이다.
+
+**행은 두 칸이고 그 목록이 화면의 본문인지가 고른다**
+([`decisions/0034`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0034-the-body-list-lifts-one-step.md)). 곁·요약·참조 나열은 제목
+`body2`(14) + 설명 `label`(12) 그대로이고, 선언서의 본문 문장이 가리키는 목록만 한 칸씩 올라가
+제목 `body1`(16) + 설명 `body2`(14)가 된다. `ListRow`의 `emphasis`가 그것이고 기본값은 올리지
+않는 쪽이다. **한 화면에 올린 목록은 하나다.**
+
+**제목과 설명은 같이 움직인다.** 제목만 올리면 16 → 12로 두 칸을 건너뛰어 설명이 각주처럼
+떨어진다.
+
+**페이지 제목은 `headline`(24)이다.** 섹션 제목이 `body1`(16)이라 32는 두 칸을 건너뛰고, 화면에서
+실제로 무겁게 읽힌다. 시안이 `display`(32)와 `title`(20)로 갈려 있던 것을 2026-09-02에 이렇게
+확정했다. 컨트롤에는 쓰지 않는다.
+
+**`display`(32)는 쓰는 자리가 없다.** 페이지 제목이 `headline`으로 가면서 남았다. 토큰과 클래스는
+두지만 새 화면에서 쓰지 않고, 다음 시안에서도 자리를 찾지 못하면 폐기한다.
+
+**행간**은 줄이 늘어나는지로 고른다. `regular`(100%)는 높이가 고정된 한 줄, `reading`(140%)은
+여러 줄이 될 수 있는 문장이다. TextField가 이 규칙을 그대로 따른다 — `md`는 여러 줄 textarea라
+`body2-reading-medium`, `sm`은 40px 한 줄 input이라 `body2-regular-medium`이다.
+
+**무게**는 `bold`가 `display`·`headline`·`title`에 붙박이다. token 정의가 그렇게 되어 있어서
+고를 여지가 없다. `body2` 이하에서 `medium`과 `semibold` 중 무엇을 쓸지는 강조 여부이고 시안을
+따른다. 누를 수 있는 컨트롤이라고 `semibold`가 되지는 않는다. Button은 `semibold`지만 Chip(md)과
+DropdownButton은 `medium`이다.
+
+크기를 키워서 강조를 만들지 않는다. **임의의 px을 얹지 않는다**는 뜻이다. 고르는 것은 언제나
+계층이고, 계층을 고르는 근거는 그것이 놓인 층이다 — `ListRow`의 `emphasis`가 px이 아니라 값
+둘을 받는 것이 그래서다 (`decisions/0034`).
+
+읽는 문장에 `label`(12px)을 쓰지 않는다. `label`은 `sm` 컨트롤 라벨과 하단 보조 문구처럼 짧은
+조각의 자리다. 본문 목록의 행 설명이 `body2`로 올라가는 이유도 이것이다.
+
+## 간격
+
+`inset`은 안쪽 padding, `gap`은 요소 사이다. **값이 같아도 역할이 다르면 섞어 쓰지 않는다.**
+`inset/sm`과 `gap/sm`은 둘 다 8px이지만 서로를 대신하지 않는다.
+
+| token      | 값   | 언제                                            |
+| ---------- | ---- | ----------------------------------------------- |
+| `inset/sm` | 8px  | 작은 컨트롤 안쪽. 칩·배지·입력·아이콘 버튼·툴팁 |
+| `inset/md` | 16px | 컨테이너 안쪽. 모달·토스터·카드·목록의 행       |
+| `inset/lg` | 24px | 큰 면 안쪽. EmptyState                          |
+| `gap/xs`   | 4px  | 밀착된 짝. 아이콘 ↔ 라벨                        |
+| `gap/sm`   | 8px  | 가까운 묶음. 라벨 ↔ 필드, 메뉴 항목             |
+| `gap/md`   | 12px | 구분되는 요소 사이. 아직 쓰는 곳이 없다         |
+| `gap/lg`   | 16px | 그룹 ↔ 그룹. 모달 본문 ↔ 액션                   |
+| `gap/xl`   | 24px | 블록 ↔ 블록, 컬럼 ↔ 컬럼. 페이지 안의 큰 묶음   |
+
+컨트롤은 `sm`, 컨테이너는 `md`, 큰 면은 `lg`가 기준이다. **목록의 행은 컨트롤이 아니라 `md`다** —
+행은 눌리는 컨트롤이 아니라 읽는 줄이고, 제목이 `line-height/100`이라 `sm`으로는 디바이더가 글자에
+붙는다([`decisions/0019`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0019-list-row-vertical-inset.md)).
+
+**페이지를 조립하는 여백과 폭은 이 스케일이 아니라 `--layout-*`이다.** 컴포넌트 안쪽을 재는
+`--space-*`와 이름 공간이 갈라져 있다. 고르는 규칙은 [`LAYOUT.md`](LAYOUT.md), 근거는
+[`decisions/0008`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0008-layout-scale-separate-from-component-scale.md)에 있다.
+`gap/xl`이 layout이 아니라 여기 있는 것은 성격이 "요소 사이"로 같고 값도 이미 primitive에 있어서다.
+
+primitive를 직접 쓰는 자리가 둘 있다. focus 링의 `outline-offset`은 `space/1`을 쓴다. 안쪽도
+사이도 아니라 대응하는 semantic이 없다. Button의 좌우 padding은 `space/4`(md)·`space/3`(sm)이고
+위아래는 `space/2`다. 높이가 시안 고정값이라 안쪽 여백이 좌우로만 의미가 있어서 `inset`을 쓰지
+않는다. 이 둘 말고는 semantic을 쓴다.
+
+## 라운드
+
+요소의 종류로 고른다. 사이즈가 `sm`이면 `control-sm`, `md`면 `control`이다.
+
+| token        | 값     | 언제                                                                           |
+| ------------ | ------ | ------------------------------------------------------------------------------ |
+| `control-sm` | 6px    | `sm` 사이즈 컨트롤과 툴팁. Button·Chip·Badge·IconButton의 `sm`, Tooltip        |
+| `control`    | 10px   | 컨트롤 기본. 버튼·입력·칩·배지·아이콘 버튼·드롭다운 트리거, 컨테이너 안쪽 요소 |
+| `container`  | 16px   | 면과 패널. 모달·드롭다운 메뉴·토스트·EmptyState                                |
+| `pill`       | 9999px | 원형과 토글. 라디오·스위치                                                     |
+
+컨트롤에 `container`를, 카드에 `control`을 바꿔 쓰지 않는다. 컨테이너 안에 들어가는 요소는
+바깥이 `container`여도 `control`을 쓴다.
+
+보더 두께는 위 목록대로 항상 `1px`이고 radius token과 무관하다.
+
+## 무엇이 강제되나
+
+`pnpm check:css`가 막는 것은 정의되지 않은 token 참조, `1px`이 아닌 보더·아웃라인 두께,
+`:focus-visible` 대신 쓴 `:focus` 셋이다. 위 표의 선택 규칙 자체는 검사하지 않으므로 사람과
+에이전트가 지킨다. 같은 실수가 반복되면 [`AGENTS.md`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/AGENTS.md) §항상의 "반복되는 오류는
+검사로 승격한다"에 따라 검사로 올린다.
+
+시안에 없는 값은 임의로 정하지 않고 확인받는다. 위 표에서 아직 쓰는 곳이 없다고 적힌 항목은
+자리를 비워 둔 것이지 그 값으로 쓰라는 뜻이 아니다.