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

package/dist/guide/docs/DESIGN_PRINCIPLES.md

@@ -0,0 +1,254 @@
+# Design Principles
+
+**판단이 부딪힐 때 무엇을 앞에 두는지, Palda가 지향하는 인상과 원칙을 담는 문서다.**
+
+> 정돈·편안함으로 셀러의 피로를 덜고, **퍼플의 강조와 오렌지의 포인트로 매출의 방향을 가리킨다.**
+
+**이 문서는 "왜"와 "무엇을 앞에 두나"만 갖는다.** 값과 사용 조건은
+[`TOKEN_POLICY.md`](TOKEN_POLICY.md), 화면을 조립하며 갈리는 판단은
+[`DESIGN_GRAMMAR.md`](DESIGN_GRAMMAR.md), 틀과 여백은 [`LAYOUT.md`](LAYOUT.md)가 갖는다. 여기서
+다시 정하지 않는다.
+
+## 1. 사용자와 제품 역할
+
+**주요 사용자는 스마트스토어를 운영하는 1인 자영업자다.** 파는 일과 그 외의 모든 일을 혼자
+한다. 하루에 여러 번 같은 화면을 지나가고, 옆에서 대신 봐 줄 사람이 없다.
+
+여기서 두 가지가 따라온다.
+
+- **반복해도 피로하지 않은 것이 한 번의 인상보다 먼저다.** 매일 지나는 화면이라 첫인상보다
+  누적이 크다.
+- **혼자 판단할 수 있어야 한다.** 다음 할 일이 화면에서 바로 보여야 하고, 틀렸을 때 무엇이
+  틀렸는지 화면이 말해야 한다. 교육이나 안내 문서를 전제하지 않는다.
+
+**Palda는 "파는 일을 가볍게" 만든다.** 셀러가 손을 덜 쓰고 다음 할 일을 알아보게 돕는다.
+
+## 2. 사용자가 받아야 하는 인상
+
+> **정돈 · 편안함 · 생기**
+
+**정돈과 편안함을 바탕에 깔고, 생기를 포인트로만 얹는다.** 셋은 대등하지 않다. 생기가 앞의 둘을
+해치면 생기를 뺀다.
+
+## 3. 핵심 원칙
+
+### 1. 정돈 (Clarity)
+
+흩어진 것을 하나로 모은 인상. **강조는 색이 아니라 위계로 만든다.**
+
+- **추구** — 넓은 여백, 질서 있는 정렬, 카드 하나에 정보 하나, 명도로 만드는 강조
+- **지양** — 빽빽한 화면, 장식 요소, 여러 색의 나열
+
+### 2. 편안함 (Ease)
+
+손이 덜 가는, 홀가분하고 순한 인상. (가벼움 + 부드러움)
+
+- **추구** — 밝은 뉴트럴 바탕, 순수 검정 대신 먹색, 얇은 라인(1px)과 순한 색조, 둥근 모서리와
+  라운드 아이콘
+- **지양** — 어둡고 무거운 배경, 두꺼운 테두리, 쨍한 원색, 과한 굵기
+
+### 3. 생기 (Vitality)
+
+앞으로 뻗어나가는, 매출을 돕는 인상. **절제된 한 번의 강조로.**
+
+- **추구** — 시그니처 퍼플로 또렷한 강조, 오렌지로 행동을 부르는 포인트, 위로 살짝 뜨는 가벼운
+  모션
+- **지양** — 강조색의 남발, 무채색만의 정적인 화면, 튀는 네온·요란한 효과
+
+## 4. 정보 위계와 강조
+
+**가장 강한 것은 색이 아니라 명도와 채움이다.** 그래서 시스템의 최강조(`primary`)는 브랜드색이
+아니라 중립 다크(먹색)이고, 퍼플·오렌지는 **역할이 다를 때만** 얹는다.
+
+**한 화면의 강한 강조는 하나다.** 강조를 더 만들어야 하면 색을 늘리지 말고 먹색의 명도 위계로
+먼저 낸다. 강조 액션(`accent`)이 둘이면 하나는 강조가 아니다.
+
+**상태 색은 이 한도에 들어가지 않는다.** 성공·주의·위험은 강조가 아니라 알림이고, 대부분
+`subtle` 틴트 배경 위에서 조용히 쓴다. 한 화면에 상태 배지가 여럿 있어도 강조 예산을 쓰지 않는다.
+
+**다만 면적이 작은 표시에 한한다.** 배지와 아이콘은 여럿이어도 예산 밖이지만, 풀폭 틴트 배너
+(`Alert` · `FormSection`의 `error`)는 폭이 본문과 같고 면을 가져서 본문과 무게를 겨룬다. 한
+화면에 하나이고, 본문보다 먼저 보이면 뺀다. 어느 자리가 상태를 드는지는
+[`DESIGN_GRAMMAR.md`](DESIGN_GRAMMAR.md) §상태는 누가 갖나와
+[`decisions/0024`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0024-state-belongs-to-the-nearest-owner.md)에 있다.
+
+**곁은 강조 예산을 쓰지 않는다.** 이 화면이 선언한 본문에 들지 않은 것 — 다른 기능의 요약이나
+그리로 가는 입구 — 에는 `primary`·`accent` 채움을 주지 않는다. 강조 하나는 본문이 갖는다.
+곁이 무엇이고 어떻게 그리는지는 [`DESIGN_GRAMMAR.md`](DESIGN_GRAMMAR.md) §곁을 어디 두나에 있고,
+근거는 [`decisions/0022`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0022-screens-declare-their-body.md)다.
+
+**뉴트럴이 대부분이다.** 퍼플은 핵심 액션과 선택 상태에만, 오렌지는 CTA·알림 같은 최소한의
+순간에만 쓴다.
+
+색을 어느 자리에 쓰는지(패밀리·켤레·글자와 아이콘)는 [`TOKEN_POLICY.md`](TOKEN_POLICY.md) §색이
+갖는다.
+
+### 주 액션의 자리는 시스템이 고정하지 않는다
+
+**둘 다 맞는 자리다.** 페이지 헤더 우측 상단과 화면 아래 `BottomBar`는 서비스 성격에 따라
+갈린다 — 읽다가 가끔 누르는 화면은 위가, 채워 넣고 마지막에 확정하는 화면은 아래가 맞다. 어느
+쪽인지는 제품이 알고 디자인 시스템은 모른다.
+
+그래서 시스템은 **자리를 정해 주는 대신 선언하게 한다.** 화면을 만드는 쪽이 둘 중 하나를 고르고,
+고른 것을 화면 단위로 밝힌다.
+
+**지키는 것은 개수다. 한 화면에 주 액션은 하나이고, 선언한 자리도 하나다.** 위아래에 같은 액션을
+두 번 두지 않는다. 자리를 고르는 것은 자유지만 강조 하나 규칙(위 §4)은 그대로다.
+
+**화면 단위 선언은 둘이다.** 주 액션의 자리가 하나이고, **이 화면의 본문**이 나머지 하나다
+([`decisions/0022`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0022-screens-declare-their-body.md)). 같은 장치를 두 축에 쓴다 —
+시스템이 정해 주는 대신 화면이 고르고 밝히고, 지키는 것은 개수다. 둘 다 승인 화면 문서가 받는다.
+
+슬롯은 이미 둘 다 있다 — 페이지 헤더 우측 상단은 바디 안이고, 아래는 `AppShell`의 `footer`에
+얹는 `BottomBar`다. 표는 [`LAYOUT.md`](LAYOUT.md) §셸의 콘텐츠 세로 순서에 있다.
+
+> **타이포 위계는 확정됐다.** 페이지 `headline`(24) → 섹션·카드 `body1`(16) → 행 `body2`(14) →
+> 보조 `label`(12)이고, 표는 [`TOKEN_POLICY.md`](TOKEN_POLICY.md) §타이포에 있다. 화면이 고르는
+> 것은 페이지 제목 하나뿐이며 나머지는 pattern이 갖고 있다.
+
+## 5. Palda다운 대표 특징
+
+다른 제품과 구분되는 자리다.
+
+- **최강조가 브랜드색이 아니다.** 주력 액션은 퍼플이 아니라 먹색이다. 브랜드색은 강조와 포인트에만
+  얹는다.
+- **읽는 면이 가장 밝다.** 캔버스가 흰색이고 틀(사이드바·모달·드롭다운·입력)이 회색으로 물러난다.
+  "조작하는 것"과 "읽는 것"이 밝기로 갈린다.
+- **박스가 없는 것이 기본값이다.** 정보는 여백·디바이더·타이포 위계로 구조화한다.
+- **선은 항상 1px이다.** 포커스 링까지 같다.
+- **아이콘은 색을 갖지 않는다.** outline 전용, `currentColor`로 부모 색을 상속한다.
+
+### 브랜드 색 이름
+
+색 이름은 브랜드 쪽 언어이고, 값과 사용 조건은 토큰이 갖는다.
+
+**바탕과 글자**
+
+| 역할                   | 이름(제안)     | HEX       | 토큰                                                         |
+| ---------------------- | -------------- | --------- | ------------------------------------------------------------ |
+| 최강조·본문(중립 다크) | 딥 잉크 (먹색) | `#323236` | `--color-primary-default` / `--color-text-primary` (gray900) |
+| 바탕(캔버스·읽는 면)   | 퓨어 화이트    | `#FFFFFF` | `--color-surface-base` (gray00)                              |
+| 바탕(틀·채운 면)       | 에어 그레이    | `#F5F5F7` | `--color-surface-raised` (gray50)                            |
+| 바탕(눌린 컨트롤 안쪽) | 미스트         | `#EDEDF2` | `--color-surface-sunken` (gray100)                           |
+| 텍스트(보조)           | 소프트 잉크    | `#86868D` | `--color-text-primary-sub` (gray500)                         |
+
+**역할색**
+
+| 역할              | 이름(제안)    | HEX       | 토큰                                    |
+| ----------------- | ------------- | --------- | --------------------------------------- |
+| 주색(브랜드 강조) | 시그니처 퍼플 | `#6466FA` | `--color-accent-default` (purple500)    |
+| 포인트(CTA·알림)  | 에너지 오렌지 | `#F77520` | `--color-secondary-default` (orange600) |
+| 위험·경고         | 소프트 레드   | `#DE7661` | `--color-danger-default` (red400)       |
+| 성공              | 프레시 그린   | `#45922C` | `--color-success-default` (green700)    |
+| 주의              | 앰버 오렌지   | `#D9671C` | `--color-warning-default` (orange700)   |
+
+**액션 색과 상태 색은 다르게 움직인다.** 누르는 색(퍼플·오렌지·레드)은 default / hover-pressed /
+subtle 3켤레로 움직이고, 알리기만 하는 색(그린·앰버)은 눌리지 않으므로 `hover-pressed`가 없다.
+레드는 액션이면서 상태이기도 한 유일한 색이라 켤레를 그대로 쓴다. 켤레 표는
+[`TOKEN_POLICY.md`](TOKEN_POLICY.md) §패밀리·§켤레에 있다.
+
+> **값의 원본은 `tokens/color.tokens.json`이고 이 표는 사본이다.** 어긋나면 토큰이 옳다
+> ([`decisions/0001`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0001-design-system-ssot.md)). 색 이름은 제안이며 디자이너가
+> 확정한다. CSS에는 hex를 쓰지 않는다 — 언제나 `var(--token)`이다.
+
+### 타이포
+
+Pretendard, 절제된 무게. **강조는 크기가 아니라 계층과 무게로.**
+
+- **무게** — Medium(500) 본문 · Semibold(600) 강조·라벨 · Bold(700) 제목 전용
+- **자간** — 약간 타이트하게(-0.5% ~ -1%), 제목일수록 더 타이트
+- **행간** — 한 줄 UI는 좁게(100%), 읽는 문장(본문·설명)은 넉넉하게(140%)
+
+스케일과 semantic 이름은 [`TOKEN_POLICY.md`](TOKEN_POLICY.md) §타이포에 있다.
+
+### 아이콘
+
+가볍고 순한 라인 세트. outline 전용, 단일 굵기, 부모 색 상속. 그리기 규칙과 고르는 법은
+[`ICON_POLICY.md`](ICON_POLICY.md)가 갖는다.
+
+### 이미지
+
+밝고 채광 좋은 톤, 흰 여백. **어수선한 매대보다 정돈된 한 컷.**
+
+### 모션
+
+가볍고 빠른 전환, 위로 살짝 뜨는 상승감. 튀지 않되 생기 있게. 빠름·보통 두 단계와 감속 이징을
+쓰고, `prefers-reduced-motion`을 존중한다([`ACCESSIBILITY.md`](ACCESSIBILITY.md)). 값은
+`tokens/motion.tokens.json`이다.
+
+## 6. 지양할 디자인
+
+**시각** — 위 §3의 각 원칙 §지양이 원본이고, 자주 어기는 것을 모았다.
+
+| 하지 않는 것              | 대신                                       |
+| ------------------------- | ------------------------------------------ |
+| 강조색을 여러 개 나열     | 강조 하나 + 먹색의 명도 위계               |
+| 쨍한 원색·네온            | 순한 색조. 브랜드색도 `default` 단계까지다 |
+| 순수 검정                 | 먹색(gray-900)                             |
+| 두꺼운 테두리             | 1px                                        |
+| 어둡고 무거운 배경        | 밝은 뉴트럴                                |
+| 의미 없는 장식            | 여백                                       |
+| 크기를 키워서 만드는 강조 | 계층과 무게                                |
+
+**구조** — 이미 결정된 anti-pattern이다. 판단 기준은 [`DESIGN_GRAMMAR.md`](DESIGN_GRAMMAR.md)에
+있고, 여기서는 "하지 않는다"만 적는다.
+
+| 하지 않는 것                   | 대신                            | 어디                                        |
+| ------------------------------ | ------------------------------- | ------------------------------------------- |
+| 모든 것을 카드로 감싸기        | 여백 + 디바이더 + 제목          | [`0011`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0011-no-over-carding.md) |
+| 컨테이너 중첩 (카드 안 보더)   | 디바이더. 최대 1 depth          | `DESIGN_GRAMMAR.md` §절대 규칙              |
+| 정적인 블록을 보더로 둘러 강조 | 상태·타이포·색                  | 〃                                          |
+| 필터를 채운 칩 박스로          | 언더라인 탭(`Tab`)              | 〃                                          |
+| 설정 폼·정보 패널을 벤토로     | `FormSection`                   | 〃                                          |
+| 카드 전체를 눌러 무언가 열기   | 카드 안의 `Button`              | `DESIGN_GRAMMAR.md` §세 번째 질문           |
+| 회색 카드를 여러 장 세우기     | 기본은 흰 카드, 강조는 한 장만  | 〃 §쓰는 경우                               |
+| 그림자로 붙어 있는 블록 띄우기 | `shadow/100`은 떠 있는 표면에만 | 〃                                          |
+| 색만으로 상태 전달             | 색 + 글자·아이콘                | [`ACCESSIBILITY.md`](ACCESSIBILITY.md)      |
+| CSS에 hex 리터럴               | `var(--token)`                  | [`TOKEN_POLICY.md`](TOKEN_POLICY.md)        |
+
+## 7. 판단이 충돌할 때
+
+**순서다. 위가 아래를 이긴다.**
+
+1. 사용자의 이해와 과업 완수
+2. 접근성과 일관성
+3. 시각적 표현
+
+브랜드 키워드끼리 부딪히면 **정돈 · 편안함 → 생기** 순이다. 생기는 앞의 둘 위에 얹는 것이지 앞의
+둘과 겨루지 않는다.
+
+자주 부딪히는 자리다.
+
+| 부딪히는 것                        | 이기는 쪽         | 왜                                                           |
+| ---------------------------------- | ----------------- | ------------------------------------------------------------ |
+| 강조를 하나 더 넣고 싶다           | 하나로 둔다       | 둘이면 어느 것도 강조가 아니다 (§4)                          |
+| 시안이 "카드 전체 클릭"을 요구한다 | 문법              | `DESIGN_GRAMMAR.md` §세 번째 질문                            |
+| 시안의 색·값이 코드와 다르다       | 코드              | 코드가 SSOT ([`0001`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0001-design-system-ssot.md)) |
+| 브랜드색이 예뻐서 넓게 깔고 싶다   | 뉴트럴            | 브랜드색은 강조와 포인트 전용 (§4)                           |
+| 글자가 배경에 묻힌다               | 읽히는 쪽         | 수치 기준은 없어도 안 읽히면 시각 표현이 아니다 (2 > 3)      |
+| 필요한 토큰·variant·아이콘이 없다  | 멈추고 확인받는다 | 지어내지 않는다 ([`AGENTS.md`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/AGENTS.md) §항상)          |
+
+**시안이 코드를 이기는 경우는 값의 다툼이 아니라 결정을 뒤집을 때뿐이다.** 그때는 ADR을 새로 쓴다
+([`0000-template`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0000-template.md)).
+
+## 하지 않기로 한 것
+
+**빠진 것이 아니라 정한 것이다.** 아래를 요구하는 시안이 오면 만들기 전에 이 절이 뒤집혔는지
+먼저 묻는다.
+
+| 무엇                   | 지금                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| 다크 모드              | **쓰지 않는다.** 토큰은 라이트 한 벌이고 두 벌로 늘리지 않는다                  |
+| 파란색(`info`)         | **만들지 않는다.** primitive에 파랑이 없고, 정보성 배너는 `neutral`로 받는다    |
+| 대비 수치 기준(AA/AAA) | **세우지 않는다.** [`ACCESSIBILITY.md`](ACCESSIBILITY.md)의 "확인한다" 선까지다 |
+
+## 아직 확정되지 않은 것
+
+이 문서가 답해야 하는데 아직 못 답하는 것들이다. **여기 있는 항목은 화면에서 마주쳐도 지어내지
+않고 멈춘다.**
+
+| 무엇                    | 상태                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| 표기(날짜·금액·수량)    | [`CONTENT.md`](CONTENT.md) §아직 확정되지 않은 것. 말투는 확정됐다 |
+| 로고·일러스트 사용 규칙 | `assets/` 아래에서 작업 예정. 지금은 README뿐이다                  |
+| 색 이름                 | §5의 이름은 제안이다                                               |

package/dist/guide/docs/FIGMA_ALIGNMENT_DELTA.md

@@ -0,0 +1,141 @@
+# Figma 정렬 delta
+
+**코드와 값이 어긋나는 자리를 모아, Figma 쪽에서 해야 할 변경으로 내보내는 목록이다.**
+
+**코드가 정답이다.** 이 문서는 Figma를 코드에 맞추기 위해 **Figma 쪽에서 해야 할 변경**을 모아
+둔 것이다. 여기 적힌 것은 코드에서 고칠 일이 아니다. 코드는 이미 오른쪽 열의 값을 갖고 있다.
+
+이 저장소에서는 Figma를 편집할 수 없다. 그래서 "Figma가 이렇게 바뀌어야 한다"를 코드 변경 대신
+문서로 내보낸다. 근거는 [`decisions/0001`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0001-design-system-ssot.md)이다.
+
+**뉴트럴 스케일 자체는 더 이상 delta가 아니다.** primitive `gray-50`~`gray-900`을 Figma와 같은
+차가운 회색으로 옮겼다([`decisions/0015`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0015-neutral-scale-adopts-figma-cool-gray.md)).
+값의 방향을 다시 정한 것이지 SSOT가 바뀐 것은 아니고, 아래 남은 항목은 여전히 **Figma가 코드에
+맞춰야 할 것**이다.
+
+## 반영 방법
+
+1. Figma Variables에서 아래 변수의 값을 "코드 값" 열로 바꾼다.
+2. 반영이 끝난 줄은 이 문서에서 지운다. 남아 있는 줄이 곧 미반영 목록이다.
+3. 값이 아니라 **이름**이 다른 항목은 이 문서가 아니라
+   [`FIGMA_NAME_MAPPING.md`](FIGMA_NAME_MAPPING.md)에 있다.
+
+## 남은 항목 — 값이 어긋나는 자리
+
+primitive는 양쪽이 같아졌고, 아래 셋은 **semantic이 어느 단계를 가리키는지**가 다르다. 색을
+바꾸는 것이 아니라 참조를 옮기는 일이다.
+
+| semantic token         | Figma 현재 값 | 코드 값 (정답) | 코드의 primitive |
+| ---------------------- | ------------- | -------------- | ---------------- |
+| `color/text/primary`   | `#86868d`     | `#323236`      | `gray-900`       |
+| `color/surface/base`   | `#f5f5f7`     | `#FFFFFF`      | `gray-00`        |
+| `color/surface/sunken` | `#c8c8cc`     | `#EDEDF2`      | `gray-100`       |
+
+`color/text/primary`는 Figma가 `gray-500`을, 코드가 `gray-900`을 가리킨다. 본문 글자라 가장 어두운
+단계가 맞다. `#86868d`는 보조 문구(`color/text/primary-sub`)의 자리다.
+
+`color/surface/base`와 `color/surface/sunken`은 배경 위계를 뒤집으면서 한 단계씩 옮겨졌다
+([`decisions/0013`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0013-surface-base-is-white.md)). 캔버스가 흰색이고 떠 있는 면과
+요약 행이 회색이다.
+
+## 남은 항목 — Figma에 아직 없는 것
+
+값이 어긋난 것이 아니라 **코드에만 있고 Figma에 없는** 자산이다. 위 표와 달리 변수 값을 바꾸는
+일이 아니라 Figma에서 새로 만들거나 기존 컴포넌트를 고치는 일이다.
+
+전부 `status: draft`이고, 아래 §시안 없이 만든 것에 적힌 항목은 **시안이 나오면 코드가 바뀔 수
+있다.** 그때는 코드가 정답이라는 규칙이 아니라 `docs/FIGMA_WORKFLOW.md`의 반영 절차를 따른다.
+
+### 색 semantic 6개 — 새 변수
+
+primitive는 양쪽에 이미 있다. **새로 만들 것은 semantic 6개뿐이고, 값이 아니라 참조를 거는
+일이다.**
+
+| semantic token          | 참조할 primitive | 값        |
+| ----------------------- | ---------------- | --------- |
+| `color/success/default` | `green-700`      | `#45922C` |
+| `color/success/subtle`  | `green-50`       | `#F3F7F0` |
+| `color/warning/default` | `orange-700`     | `#D9671C` |
+| `color/warning/subtle`  | `orange-50`      | `#FDF9F7` |
+| `color/text/success`    | `green-800`      | `#40772E` |
+| `color/text/warning`    | `orange-800`     | `#A7531B` |
+
+`success`·`warning`은 상태 색이라 `hover-pressed`를 만들지 않는다. 눌리는 것이 아니기 때문이고,
+근거는 [`TOKEN_POLICY.md`](TOKEN_POLICY.md)의 §패밀리에 있다. `danger`는 이미 있는 켤레를 그대로
+쓴다 — 액션 색이면서 status이기도 한 유일한 패밀리다.
+
+### 기존 컴포넌트에 반영할 변경 4건
+
+| Figma 컴포넌트 | 무엇                                                                                                                                            |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Badge`        | variant에 `success`·`warning`·`danger` 3종 추가 (기존 3종 → 6종)                                                                                |
+| `Card`         | `tone` property 신설(`plain`/`filled`)하고 **기본값을 `filled`→`plain`으로**                                                                    |
+| `Modal`        | 배경을 `surface/raised`(`#F5F5F7`) → `surface/base`(`#FFFFFF`)                                                                                  |
+| `ListRow`      | `tone="filled"` 배경을 `surface/sunken`(`#EDEDF2`) → `surface/raised`(`#F5F5F7`). 상하 여백 8 → 16은 `filled`만이 아니라 **모든 행**에 적용한다 |
+
+Badge의 status variant는 틴트 배경 위 조합이다 — 배경 `{status}/subtle`, 글자 `text/{status}`,
+아이콘 `{status}/default`이고 보더는 없다.
+
+**`Card`의 기본값 뒤집기가 이 목록에서 가장 넓게 번진다.** Card를 쓴 시안 전부가 흰 면으로
+바뀐다. 카드가 여럿 선 화면에서 회색 면이 반복되면 어느 것도 앞에 서지 못해서이고, 강조는
+기본값이 아니라 한 화면에서 하나를 골라 `filled`로 올려서 낸다.
+
+`Modal`은 스크림 위에 뜨는 유일한 면이라 흰색이다. 드롭다운·토스트·프리뷰·사이드바는 `raised`
+그대로다.
+
+`ListRow`의 `tone="filled"`는 `Card`의 `tone="filled"`와 같은 회색이 된다. 두 곳의 `filled`가 같은
+뜻이라 값도 같아야 하고, 층은 색이 아니라 여백·라운드로 갈린다
+([`decisions/0018`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0018-summary-row-shares-the-filled-surface.md)).
+
+### 새 컴포넌트 2종
+
+| 코드          | Figma에서 만들 것                                                                                        |
+| ------------- | -------------------------------------------------------------------------------------------------------- |
+| `Alert`       | variant 4종 — `neutral`(기본) · `accent` · `warning` · `danger`. 제목·본문·아이콘·action 슬롯. 보더 없음 |
+| `ProgressBar` | variant·size 없음. 높이 8px 한 종류, 채움은 `primary`, label 필수                                        |
+
+`Alert`에 `info` variant가 없다. 파랑 계열 primitive가 코드에 없어서이고, 명세의 파란 배너는
+`neutral`로 받는다. **파란 배너가 필요하면 Figma에서 파랑 스케일을 먼저 정해야 한다.**
+
+### 새 아이콘 7종
+
+`shield-check` · `unplug` · `pause` · `message` · `success` · `store` · `loading`
+
+원본은 `icons/svg/`이고, 그리기 규칙(24px 그리드 · 코너 radius 2px)은
+[`ICON_POLICY.md`](ICON_POLICY.md)에 있다.
+
+### 시안 없이 만든 것
+
+아래는 Figma 시안 없이 코드에서 먼저 만든 초안이라, **Figma에 옮기기 전에 디자이너 확정이 먼저
+필요하다.** 각 항목의 미정 사항은 `catalog/`의 `planned` 필드에 적혀 있다.
+
+- `Alert` — `info` variant 없음, 닫기 버튼 없음
+- `ProgressBar` — 높이 8px이 명세 실측값이고 대응 토큰이 없음
+- 아이콘 7종 — 전부 `status: draft`
+
+## 해결됨 — 뉴트럴 4건
+
+아래는 0015로 primitive를 옮기면서 양쪽 값이 같아졌다. Figma에서 할 일이 없다.
+
+`color/border/default`(`#ededf2`) · `color/border/strong`(`#c8c8cc`) ·
+`color/primary/default`(`#323236`) · `color/primary/hover-pressed`(`#47474c`).
+
+`border`는 값이 같아진 것과 별개로 참조 단계도 함께 내렸다 — `default`는 `gray-200` → `gray-100`,
+`strong`은 `gray-300` → `gray-200`이다. 박스를 걷어낸 뒤 화면의 구분이 디바이더 하나에 걸려서
+이전 단계는 너무 진했다.
+
+## 해결됨 — `color/accent/subtle`
+
+이 항목은 처음에 위 표에 있었으나 **코드를 고쳐서 없앴다.** delta가 아니라 코드의 결함이었다.
+
+Figma의 purple 스케일은 `50 #F3F3FF` · `100 #EBEBFE` · `200 #B3B4FC`로 갈라져 있는데, 코드는
+`50`과 `100`이 둘 다 `#EBEBFE`였다. `50` 자리에 `100`의 값이 들어가 있었고, `200` 이하는 양쪽이
+일치하므로 어긋난 것은 `purple-50` 한 칸이었다.
+
+양쪽 모두 `accent/subtle → purple-50`으로 매핑은 같았다. semantic의 이견이 아니라 primitive 한
+칸의 값 사고였으므로, **코드를 정답으로 두는 규칙의 예외가 아니다.** 코드의 `purple-50`을
+`#F3F3FF`로 고쳐 양쪽이 같아졌다.
+
+`color/accent/subtle`이 한 단계 밝아지면서 이 토큰을 쓰는 Chip·Button·IconButton·Badge의 틴트와
+`ListRow`의 선택 배경이 함께 밝아졌다. 배경이 밝아진 방향이라 그 위 `text/accent`(purple-600)의
+대비는 올라간다.

package/dist/guide/docs/FIGMA_NAME_MAPPING.md

@@ -0,0 +1,84 @@
+# Figma → 코드 이름 매핑
+
+**같은 것을 Figma와 코드가 다르게 부르는 자리의 대조표다.**
+
+**코드 이름이 정답이다.** Figma에서 다른 이름을 쓰고 있는 항목을 여기 모은다. 시안을 읽고 코드를
+쓸 때 이 표로 옮기고, Figma 쪽을 정리할 때도 이 표를 목표로 삼는다.
+
+값이 다른 항목은 이 문서가 아니라 [`FIGMA_ALIGNMENT_DELTA.md`](FIGMA_ALIGNMENT_DELTA.md)에 있다.
+여기는 **이름만** 다루고, 근거는 [`decisions/0001`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0001-design-system-ssot.md)이다.
+
+## CSS 변수 접두사
+
+코드의 CSS 변수는 Figma가 선언한 `cssVar`에 `palda-` 접두사를 붙인 것이다
+(`--radius-md` ↔ `--palda-radius-md`). 무접두사 이름이 소비 앱의 전역 변수와 충돌해서다
+([`decisions/0017`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0017-css-variable-prefix.md)). Figma에서 변수 이름을 검색해
+코드로 올 때는 접두사만 붙이면 되고, 그 외 규칙은 아래 표와 같다. 이 문서에서 패밀리를
+뭉뚱그려 부를 때는 `--layout-*`처럼 접두사 없이 쓰고, 코드에 실재하는 변수를 가리킬 때는
+`--palda-layout-inset`처럼 전체 이름을 쓴다.
+
+## 색 패밀리
+
+| Figma 이름 | 코드 이름 (정답) | 값     |
+| ---------- | ---------------- | ------ |
+| `point`    | `secondary`      | orange |
+
+오렌지 패밀리는 `secondary`다. Figma의 `point`는 채택하지 않는다. `point`는 "강조"라는 뜻이라
+`accent`와 구분되지 않고, Palda에서 강조 액션은 `accent`(퍼플) 하나다.
+
+## 텍스트 색 — 매핑이 뒤바뀐 자리
+
+**주의: 이름이 서로 바뀌어 있다.** 기계적으로 같은 이름끼리 옮기면 색이 뒤집힌다.
+
+| Figma            | 코드 (정답)      | 값                  |
+| ---------------- | ---------------- | ------------------- |
+| `text/accent`    | `text/secondary` | `orange-500` (주황) |
+| `text/secondary` | `text/accent`    | `purple-600` (퍼플) |
+
+코드는 패밀리 이름과 텍스트 이름을 맞춰 두었다. `secondary` 패밀리가 주황이므로 `text/secondary`도
+주황이고, `accent` 패밀리가 퍼플이므로 `text/accent`도 퍼플이다. Figma는 이 둘이 어긋나 있다.
+
+## 상태 접미사
+
+| Figma     | 코드 (정답)       |
+| --------- | ----------------- |
+| `*-hover` | `*-hover-pressed` |
+
+코드는 hover와 pressed를 한 상태로 다룬다. `docs/TOKEN_POLICY.md`의 켤레 규칙에서 정한 것이고,
+`color/{family}/hover-pressed` 하나가 두 상태를 모두 덮는다. Figma의 `*-hover`는 pressed가 빠진
+이름이라 채택하지 않는다.
+
+대상: `color/primary/hover-pressed` · `color/accent/hover-pressed` ·
+`color/secondary/hover-pressed` · `color/danger/hover-pressed` · `color/state/hover-pressed`.
+
+## 폰트 웨이트
+
+**주의: 이름은 겹치는데 가리키는 값이 다르다.** `medium`이 양쪽에 있고 값이 500과 600으로 다르다.
+
+| Figma     | 값  | 코드 (정답) | 값  |
+| --------- | --- | ----------- | --- |
+| `regular` | 500 | `medium`    | 500 |
+| `medium`  | 600 | `semibold`  | 600 |
+| —         | 700 | `bold`      | 700 |
+
+코드는 CSS `font-weight` 숫자의 관례 이름을 따른다. 500은 medium, 600은 semibold, 700은 bold다.
+Figma의 `regular`는 관례상 400이므로 500에 붙으면 다른 곳에서 읽을 때 어긋난다.
+
+`palda-text-*` 클래스 이름에도 이 이름이 그대로 들어간다
+(`palda-text-body2-regular-medium`의 뒷부분이 웨이트다).
+
+## 그림자
+
+| Figma      | 코드 (정답)  |
+| ---------- | ------------ |
+| `depth100` | `shadow/100` |
+
+단계 번호는 그대로 두고 접두어만 코드 컨벤션에 맞춘다. 근거는
+[`decisions/0009`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0009-elevation-shadow-tokens.md)에 있다.
+
+## 이 표에 없는 것
+
+레이아웃 여백·치수 토큰(`--layout-*` 패밀리와 `--palda-space-gap-xl` 등)은 Figma에 대응하는 변수가 없다. Figma
+실측값을 코드에서 처음 토큰화한 것이라 매핑할 짝이 없다.
+[`decisions/0008`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0008-layout-scale-separate-from-component-scale.md)과
+[`LAYOUT.md`](LAYOUT.md)를 본다.

package/dist/guide/docs/FIGMA_WORKFLOW.md

@@ -0,0 +1,33 @@
+# Figma Workflow
+
+**Figma에서 정한 것을 저장소에 반영하고, 시안 코드를 읽어 구현으로 옮기는 절차다.**
+
+**원본은 저장소이고 Figma는 미러다**([`decisions/0016`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0016-asset-ssot-boundary.md)).
+그래서 이 문서의 절차는 한 방향이다 — Figma에서 정한 것을 저장소에 **반영해야** 끝나고, 반영되기
+전까지는 확정이 아니다. 값이 어긋나면 코드가 옳고, Figma가 바뀌어야 할 목록은
+[`FIGMA_ALIGNMENT_DELTA.md`](FIGMA_ALIGNMENT_DELTA.md)에 낸다.
+
+1. `figma/LIBRARY_LINKS.md`에서 디자인 시스템 파일의 placeholder 이름을 확인한다. 실제 URL은 저장소가 아니라 각자의 `figma.local.config.json`에 있다([`decisions/0026`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0026-figma-keys-stay-out-of-the-repository.md)).
+2. Variables는 `tokens/`와 같은 이름과 의미를 사용한다. 이름이 다른 자리는
+   [`FIGMA_NAME_MAPPING.md`](FIGMA_NAME_MAPPING.md)에 있고, 정답은 `tokens/` 쪽 이름이다.
+3. 반복 요소는 Component와 Variant로 만든다.
+4. Auto Layout과 semantic layer name을 사용한다.
+5. Figma에서 정한 변경은 저장소의 원본(`tokens/`·`icons/svg/`·`components/src/`·`catalog/`)에
+   반영해야 확정된다. 값을 옮기더라도 "Figma가 옳으니 따른다"가 아니라 저장소에서 다시 정한
+   것으로 기록한다 — 전례는 [`decisions/0015`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/decisions/0015-neutral-scale-adopts-figma-cool-gray.md)다.
+6. Library publish 전에 Storybook의 실제 브라우저 결과를 확인한다. 승인은 Figma가 아니라
+   Storybook과 `contact-sheet`에서 난다.
+
+## 시안 코드 읽는 법
+
+Figma가 내보낸 코드는 `box-sizing: border-box` 기준의 **고정 `height`**로 읽는다. Auto Layout 프레임의 높이가 고정이면 export에는 `height`와 padding이 함께 적히지만, 실제 렌더 높이를 결정하는 것은 `height`다.
+
+- `height`와 `padding`, 텍스트 `line-height`의 합이 어긋나 보여도 스펙 오류가 아니다. 남는 padding이 압축되고 내용은 flex 정렬로 중앙에 남는다. 예: `height: 24px` + `padding-block: 8px` + `line-height: 12px`는 28px이 아니라 24px로 렌더된다.
+- 이 값들을 `min-height`로 옮기면 계산이 어긋나 실제보다 큰 높이가 나온다. `height`를 그대로 쓰고 padding도 시안 값을 유지한다.
+- 수치가 맞지 않아 보인다고 padding을 임의로 조정하지 않는다.
+
+`fontSize`와 같은 `lineHeight`는 `line-height: 100%`를 뜻하므로, 대응하는 텍스트 스타일 token이 있으면 개별 속성 대신 그 스타일을 쓴다.
+
+## 시안에 없는 값
+
+focus 링, transition, hover 피드백처럼 시안이 다루지 않은 항목은 임의로 정하지 않는다. 구현에 필요해 값을 넣었다면 어떤 값을 왜 넣었는지 함께 알리고 확정을 받는다.