@x-plat/design-system 0.12.0 → 0.14.0

package/dist/layout/Grid/Item/index.d.cts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { b as GridColumnConfig } from '../../../breakpoints-DsXkJgdl.cjs';
+import { G as GridColumnConfig } from '../../../breakpoints-CKkNxA-y.cjs';
 
 /**
  * Grid column span — 브레이크포인트별 컬럼 수.

package/dist/layout/Grid/Item/index.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { b as GridColumnConfig } from '../../../breakpoints-DsXkJgdl.js';
+import { G as GridColumnConfig } from '../../../breakpoints-CKkNxA-y.js';
 
 /**
  * Grid column span — 브레이크포인트별 컬럼 수.

package/dist/layout/Grid/index.d.cts

@@ -1,5 +1,5 @@
 export { FullGrid } from './FullGrid/index.cjs';
 export { FullScreen } from './FullScreen/index.cjs';
 export { GridItem } from './Item/index.cjs';
-export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, b as GridColumnConfig, G as GridSpanFor } from '../../breakpoints-DsXkJgdl.cjs';
+export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, G as GridColumnConfig, b as GridSpanFor } from '../../breakpoints-CKkNxA-y.cjs';
 import 'react';

package/dist/layout/Grid/index.d.ts

@@ -1,5 +1,5 @@
 export { FullGrid } from './FullGrid/index.js';
 export { FullScreen } from './FullScreen/index.js';
 export { GridItem } from './Item/index.js';
-export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, b as GridColumnConfig, G as GridSpanFor } from '../../breakpoints-DsXkJgdl.js';
+export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, G as GridColumnConfig, b as GridSpanFor } from '../../breakpoints-CKkNxA-y.js';
 import 'react';

package/dist/layout/index.d.cts

@@ -1,7 +1,7 @@
 export { FullGrid } from './Grid/FullGrid/index.cjs';
 export { FullScreen } from './Grid/FullScreen/index.cjs';
 export { GridItem } from './Grid/Item/index.cjs';
-export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, b as GridColumnConfig, G as GridSpanFor } from '../breakpoints-DsXkJgdl.cjs';
+export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, G as GridColumnConfig, b as GridSpanFor } from '../breakpoints-CKkNxA-y.cjs';
 export { Header } from './Header/index.cjs';
 export { Layout } from './Layout/index.cjs';
 export { SideBar, SideBarContext, useSideBarContext } from './SideBar/index.cjs';

package/dist/layout/index.d.ts

@@ -1,7 +1,7 @@
 export { FullGrid } from './Grid/FullGrid/index.js';
 export { FullScreen } from './Grid/FullScreen/index.js';
 export { GridItem } from './Grid/Item/index.js';
-export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, b as GridColumnConfig, G as GridSpanFor } from '../breakpoints-DsXkJgdl.js';
+export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, G as GridColumnConfig, b as GridSpanFor } from '../breakpoints-CKkNxA-y.js';
 export { Header } from './Header/index.js';
 export { Layout } from './Layout/index.js';
 export { SideBar, SideBarContext, useSideBarContext } from './SideBar/index.js';

package/dist/tokens/index.d.cts

@@ -1,4 +1,4 @@
-export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, b as GridColumnConfig, G as GridSpanFor, c as breakpoints, g as gridColumns } from '../breakpoints-DsXkJgdl.cjs';
+export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, G as GridColumnConfig, b as GridSpanFor, c as breakpoints, g as gridColumns } from '../breakpoints-CKkNxA-y.cjs';
 export { TokenVar, cssVar, semantic } from '@x-plat/tokens-core';
 import React from 'react';
 

package/dist/tokens/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, b as GridColumnConfig, G as GridSpanFor, c as breakpoints, g as gridColumns } from '../breakpoints-DsXkJgdl.js';
+export { B as BREAKPOINT_KEYS_ORDERED, a as BreakpointKey, G as GridColumnConfig, b as GridSpanFor, c as breakpoints, g as gridColumns } from '../breakpoints-CKkNxA-y.js';
 export { TokenVar, cssVar, semantic } from '@x-plat/tokens-core';
 import React from 'react';
 

package/guidelines/Guidelines.md

@@ -55,7 +55,7 @@ React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1
    - [피드백](./components/feedback.md) - Alert, Toast, NotificationBadge
    - [오버레이](./components/overlay.md) - Modal, Drawer, PopOver, Tooltip
    - [폼 컨트롤](./components/form.md) - CheckBox, Radio, Switch
-   - [Chip & Tag](./components/chip-tag.md)
+   - [Chip & ToggleChip & Tag](./components/chip-tag.md)
    - [내비게이션](./components/navigation.md) - Tab, CardTab, Breadcrumb, Pagination, Steps
    - [DatePicker](./components/datepicker.md) - Calendar, DatePicker 4종
    - [Accordion](./components/accordion.md)
@@ -74,3 +74,15 @@ React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1
 4. **컴포지션**
    - [Grid](./composition/grid.md) - Grid 시스템, 위젯 패턴
    - [Layout](./composition/layout.md) - Layout, Header, SideBar
+
+---
+
+## 버전을 올릴 때
+
+[마이그레이션 노트](./MIGRATION.md) — 0.5.x 이후 **실제로 깨지는 것만** 버전별로
+모아 뒀다. 자기 버전부터 아래로 읽으면 된다.
+
+- 최신본: `https://unpkg.com/@x-plat/design-system/guidelines/MIGRATION.md`
+- 커밋 제목만 보고 판단하지 말 것. `refactor!` 인데 별칭이 살아 있어 안 깨지는
+  것이 있고, 평범한 `refactor` 인데 prop 이 사라진 것이 있다.
+

package/guidelines/MIGRATION.md

@@ -0,0 +1,297 @@
+# @x-plat/design-system — 마이그레이션 노트
+
+버전을 올릴 때 **실제로 깨지는 것만** 모았다. 추가된 기능은 여기 적지 않는다 —
+그건 각 컴포넌트 문서에 있다.
+
+- 최신본 URL: `https://unpkg.com/@x-plat/design-system/guidelines/MIGRATION.md`
+- 자기 버전부터 아래로 읽어 내려가면 된다.
+
+## 먼저: 지금 내가 위험한가
+
+**`0.x` 에서 캐럿(`^`)은 마이너를 고정한다.** 메이저가 0 이면 npm 은 마이너 번호를
+메이저처럼 다룬다.
+
+```
+^0.12.0  ≡  >=0.12.0 <0.13.0      ← 0.13.0 은 안 온다
+^0.5.42  ≡  >=0.5.42 <0.6.0       ← 0.6.0 은 안 온다
+```
+
+그래서 **`install` 을 다시 돌려도 아래 변경들은 오지 않는다.** 전부
+`package.json` 의 명시 버전을 직접 올리는 순간에 한꺼번에 온다.
+
+이 말은 두 가지를 뜻한다.
+
+1. **당장 안 올릴 거면 이 문서를 읽지 않아도 된다.** 지금 화면은 안 깨진다.
+2. **올릴 때는 건너뛴 구간의 절을 전부 읽어야 한다.** 한 마이너씩 올라가는 게
+   아니라 여러 마이너를 한 번에 건너뛰게 되기 때문이다.
+
+특히 오래 머물러 있던 저장소는 **성격이 다른 변경 둘을 한꺼번에 맞는다.**
+`0.5.x` 에서 최신으로 올리면 [0.6.0 CSS 변수 개명](#05x--060--css-변수-이름-전면-교체)과
+[0.13.0 `label` 의미 변경](#0120--0130--fileupload--imageselector-의-label-뜻이-바뀜)을
+같이 겪는다. **둘 다 타입이나 빌드가 잡아 주지 않고 화면만 바뀐다.** 이관 후
+눈으로 확인할 것.
+
+---
+
+## 이 문서를 믿어도 되는 범위
+
+각 항목은 **커밋 해시**를 달아 뒀다. 커밋 제목만 보고 판단하지 말 것 —
+`refactor!` 라고 외치지만 별칭이 살아 있어 안 깨지는 것이 있고(0.7.1 `Badge`),
+평범한 `refactor` 인데 prop 이 사라진 것이 있다(0.8.0 `Button`).
+
+「실제로 걸린 것」 표는 진짜 이관에서 확인된 것이고, 나머지는 소스에서 확인한 것이다.
+
+---
+
+## 0.5.x → 0.6.0 — CSS 변수 이름 전면 교체
+
+**`92dac35` · 가장 큰 변경이다.** Figma 변수 컬렉션 구조에 맞춰 컬러 레이어를
+4단계에서 3단계로 줄이면서 semantic 이름을 전부 바꿨다.
+
+`var(--semantic-*)` 를 직접 쓰는 CSS 가 있으면 **조용히 깨진다** — 정의되지 않은
+변수는 오류를 내지 않고 색만 사라진다. 이관 후 화면을 눈으로 확인할 것.
+
+| 예전 | 지금 |
+|---|---|
+| `--semantic-*-strong` | `--semantic-*-primary` |
+| `--semantic-*-subtle` | `--semantic-*-secondary` |
+| `--semantic-*-muted` | `--semantic-*-tertiary` |
+| `--semantic-*-brand` | `--semantic-*-brand-primary` |
+| `--semantic-*-sunday` | `--semantic-*-accent-red` |
+| `--semantic-*-saturday` | `--semantic-*-accent-blue` |
+| `--semantic-*-emphasis-*` | 삭제 → `--semantic-surface-*-strong` |
+| `--brand-base-black-alpha-10/25` | `--brand-base-overlay-5/10/25/50/75/85` |
+
+`color/primitive.ts` 가 삭제되고 `brand`/`system` 이 hex 실값을 직접 갖는다.
+`var(--primitive-*)` 를 참조하던 곳은 전부 끊긴다.
+
+**값이 바뀐 것 6건** (이름은 그대로인데 색이 달라진다):
+`text-brand-primary` · `border-brand-primary` · `border-warning` ·
+`surface-info-default` · `icon-success` · `icon-info`.
+`system.link` 는 purple → deep-purple.
+
+> 컴포넌트만 쓰고 CSS 변수를 직접 참조하지 않는다면 이 절은 건너뛰어도 된다.
+
+## 0.6.0 → 0.7.0 — effects · typography 토큰 정합
+
+**`6429909`** 컴포넌트가 하드코딩하던 그림자·폰트를 토큰으로 옮겼다.
+컴포넌트를 그대로 쓰면 영향 없다. 그림자나 폰트 크기를 CSS 로 덮어쓰고 있었다면
+우선순위가 달라질 수 있다.
+
+## 0.7.0 → 0.7.1 — Badge 이름 변경
+
+**`c95ee21` · `6430c9c`**
+
+| 대상 | 깨지나 | 조치 |
+|---|---|---|
+| `import { Badge }` | **안 깨짐** | `Badge` 가 `@deprecated` 별칭으로 계속 나간다. 새로 쓰는 곳만 `NotificationBadge` |
+| CSS 클래스 `.lib-xplat-badge` | **깨짐** | `.lib-xplat-notification-badge` 로. 별칭 없음 |
+
+**`NotificationBadge` 는 알약(pill) 라벨이 아니다.** 아이콘 위에 올라타는 개수
+인디케이터다. `count` 도 `dot` 도 없으면 **뱃지가 렌더되지 않고 children 만 통과한다.**
+
+```tsx
+<Badge type="error">품절</Badge>        // ✗ 아무것도 안 그려지고 "품절" 만 나온다
+<NotificationBadge count={3}><BellIcon /></NotificationBadge>   // ○
+```
+
+알약 라벨이 필요하면 `Tag` 를 쓴다. 이 오용은 이름이 바뀌기 전부터 조용히
+실패하고 있었으므로, 올리기 전에 `<Badge>` 사용처를 훑어 볼 것.
+
+## 0.7.2 → 0.8.0 — `Button` 이 `<button>` 전용으로 복귀
+
+**`f5668dd` · `0a4ab14` · 실제로 제일 많이 깨지는 항목이다.**
+
+`Button` 은 이제 `<button>` 하나만 렌더한다. `href` prop 이 없다.
+
+```tsx
+<Button href="/about">소개</Button>        // ✗ 더 이상 없다
+<LinkButton href="/about">소개</LinkButton> // ○
+<Link href="/about">소개</Link>             // ○ 본문 안 링크
+```
+
+> ⚠ 커밋 `f5668dd` 에 나오는 **`buttonClass()` 는 쓰지 말 것.** 바로 다음 커밋
+> `0a4ab14` 에서 `LinkButton` 으로 대체됐고 지금 소스에 없다(export 0건).
+> 커밋을 순서대로 훑다 보면 유효한 경로로 오해하기 쉽다.
+
+## 0.8.0 → 0.8.1 — 오버레이가 항상 `document.body` 로 portal
+
+**`17004e7`** Modal · Select · Dropdown · PopOver · TimePicker 의 팝업이 조상
+DOM 이 아니라 항상 `body` 로 들어간다. 조상에 `transform`/`filter`/`will-change`/
+`contain` 이 있으면 `position: fixed` 의 기준이 그 조상으로 바뀌어 오버레이가
+엉뚱한 자리에 뜨던 것을 고친 것이다.
+
+**오버레이를 조상 기준으로 위치 잡는 CSS 가 있으면 깨진다.** 그런 CSS 는 지워야 한다 —
+위치는 DS 가 계산한다.
+
+## 0.8.1 → 0.8.2 — `modal-box` 에 `position: relative`
+
+**`c3611ee`** 0.8.1 에서 모달의 `transform` 을 걷어내면서 모달 **안쪽**
+`position: absolute` 요소들의 기준이 모달이 아니라 화면 전체(`.dim`)로 튀었다.
+그 회귀를 되돌린 것이다. 0.8.1 을 건너뛰고 0.8.2 이상으로 올리면 겪지 않는다.
+
+## 0.8.3 → 0.9.0 — 폼 검증 API 가 `validations` 로 통일
+
+**`6e64fbc`** 컴포넌트마다 제각각이던 에러 표시 방식을 하나로 모았다.
+**추가이므로 기존 코드를 깨지 않는다.** 다만 이제 직접 그릴 필요가 없다.
+
+```tsx
+validations?: { status: "error" | "warning" | "success" | "default"; message: string }[]
+```
+
+- 렌더는 `FieldMessage` 가 전담한다. 아이콘·색·간격이 DS 전체에서 같아진다.
+- `aria-invalid` 도 DS 가 붙인다 — 직접 붙이던 코드는 걷어낼 것.
+- `hasError(validations)` 가 배럴에서 나간다.
+- `Input/InputValidations` 는 **삭제됐다.** 직접 import 하던 곳이 있으면 끊긴다.
+
+`Select.error?: boolean` 은 하위호환으로 남아 있다. `validations` 와 OR 로
+합쳐지므로 둘 다 써도 되지만, 새로 쓰는 곳은 `validations` 를 쓴다.
+
+## 0.9.0 → 0.10.0 — `type` = 상태색 / `variant` = 모양 변형
+
+**`12f4319`** 한 컴포넌트에서 `type` 이 색을 뜻하기도 하고 모양을 뜻하기도 하던
+것을 두 축으로 갈랐다. **별칭이 살아 있어 깨지지 않는다.**
+
+| 축 | prop | 값 |
+|---|---|---|
+| 상태 색 | `type` | `primary` `success` `error` `warning` `info` |
+| 모양 변형 | `variant` | 컴포넌트마다 다름 |
+
+- 모양 변형을 `type` 으로 주던 곳(`Tooltip` `Chart` `Tab` `Tag`)은 `variant` 로
+  옮기는 게 맞지만, `variant ?? type ?? 기본값` 으로 받으므로 **지금 동작한다.**
+- `type="brand"` → `type="primary"`. `normalizeStatus()` 가 `brand` 를 계속 받는다.
+
+**별칭 제거 시점은 아직 정해지지 않았다.** 업그레이드와 무관한 diff 를 섞기
+싫으면 나중에 한 번에 정리해도 된다. 제거가 정해지면 이 문서에 적는다.
+
+## 0.10.0 → 0.11.0 — 폼 컨트롤에 `label` / `required`
+
+**`9f7700d` · 추가지만 기존 마크업과 겹칠 수 있다.**
+
+`Field` 가 **진짜 `<label htmlFor>` 를 그린다.** 바깥에서 `<label>` 로 감싸던
+코드에 DS 의 `label` prop 을 같이 주면 `<label>` 안에 `<label>` 이 들어간다 —
+유효하지 않은 HTML 이고, 클릭 시 포커스가 어디로 갈지 브라우저마다 다르다.
+
+> **「DS `label` 도입」과 「기존 `<label>` 제거」는 같은 커밋에 넣을 것.**
+> 한쪽만 하면 중첩되거나 라벨이 사라진다.
+
+같이 걷어낼 것:
+
+- `htmlFor` / `id` — DS 가 `React.useId()` 로 만들어 잇는다. 직접 넘길 필요 없다.
+- `aria-invalid` — DS 가 붙인다.
+
+`Field` 는 **붙일 게 없으면 래퍼를 만들지 않고 `children` 을 그대로 통과시킨다.**
+안 쓰는 곳의 DOM 은 늘지 않으므로 그대로 둬도 된다.
+
+## 0.11.0 → 0.12.0 — Editor 확충
+
+**`7bf563f` · `97e668c` · 추가만 있다.** 되돌리기/다시하기, 표, 체크리스트,
+정렬, 문법 강조, 형광펜, 위/아래 첨자가 들어갔다.
+
+**저장된 HTML 을 직접 다루는 쪽은 허용 태그 목록을 갱신해야 한다.**
+저장 값에 표·체크리스트·`mark`·`sub`/`sup` 이 새로 나타난다. 태그 목록을
+직접 들고 있다면(예: "이 값이 HTML 인가" 판별) 아래 **31개를 그대로** 복사할 것.
+
+```
+p br div span
+h1 h2 h3 h4 h5 h6
+ul ol li
+blockquote pre code
+strong b em i u s strike del
+a img hr
+sub sup mark
+table thead tbody tr th td
+```
+
+주의할 점 둘:
+
+- **`b` `i` `u` `strike` 는 옛날 태그가 아니라 평상시 출력이다.** DS 는
+  `styleWithCSS` 를 켜지 않으므로 브라우저 `execCommand` 가 `<strong>` 이 아니라
+  `<b>` 를 낸다. 굵게 쓴 글이 흔하므로 이게 빠지면 자주 밟힌다.
+- **`input` 은 필요 없다.** 체크리스트는 `<li data-checked>` + CSS `::before` 로
+  그린다. `<input>` 은 한 번도 나오지 않는다.
+
+허용 목록은 `Editor.tsx` 안의 상수이고 prop 으로 열려 있지 않다. 버전을 올리면
+따라온다. `readOnly` 로 그릴 때도 같은 태그가 전부 나온다 — sanitize 경로와
+스타일이 편집 모드와 같다.
+
+HTML 을 검색 색인에 넣는다면 **닫는 태그를 공백이나 줄바꿈으로 치환**할 것.
+`</td>` `</th>` `</tr>` `</li>` `</p>` `</h1>`~`</h6>` `</blockquote>` `<br>` 을
+그냥 지우면 칸 글자가 붙어 `가격수량` 같은 낱말이 생긴다.
+
+## 0.12.0 → 0.13.0 — `FileUpload` / `ImageSelector` 의 `label` 뜻이 바뀜
+
+**깨진다. 그런데 타입 오류가 나지 않는다 — 글자 위치만 바뀐다.**
+
+이 둘의 `label` 은 DS 안에서 혼자 다른 뜻이었다. 다른 폼 컨트롤에서는 컨트롤
+**위**에 붙는 필드 라벨인데, 여기서는 상자 **안**에 찍히는 안내 문구였다.
+그 문구를 `placeholder` 로 옮기고 `label` 을 필드 라벨로 되돌렸다.
+
+```tsx
+// 0.12.0 이하
+<FileUpload label="파일을 드래그하거나 클릭하여 업로드" />
+
+// 0.13.0 — 같은 화면을 얻으려면
+<FileUpload placeholder="파일을 드래그하거나 클릭하여 업로드" />
+
+// 이제 가능해진 것
+<FileUpload label="첨부파일" required placeholder="끌어다 놓으세요" />
+```
+
+`label` 을 그대로 두면 **그 글자가 상자 안이 아니라 상자 위 라벨로 올라간다.**
+`label?: string` 에서 `label?: React.ReactNode` 로 넓어졌으므로 기존 문자열도
+타입은 통과한다. `grep -rn 'FileUpload\|ImageSelector'` 로 훑어 `label=` 이 있는
+곳을 `placeholder=` 로 바꾸면 된다.
+
+같이 들어간 것:
+
+- `required` — 라벨 뒤에 `*`
+- `htmlFor` 연결 — 라벨을 클릭하면 파일 선택창이 열린다
+- **`ImageSelector` 의 하드코딩된 `id="image-input"` 제거.** 한 화면에 둘 이상
+  놓으면 DOM id 가 겹치던 버그였다. 이제 `React.useId()` 로 만든다.
+  `#image-input` 을 잡는 CSS 나 테스트 셀렉터가 있으면 끊긴다.
+
+### 같은 릴리스: DatePicker 3종에 `label` / `required` / `validations`
+
+**추가만 있다.** `SingleDatePicker` · `RangeDatePicker` · `InputDatePicker` 가
+다른 폼 컨트롤과 같은 방식으로 라벨·검증을 받는다.
+
+`PopupDatePicker` 와 `Dropdown` 은 받지 않는다 — 전자는 트리거를 `component` 로
+직접 넘기는 구조라 라벨이 가리킬 대상이 없고, 후자는 `role="menu"` 인 액션
+메뉴라 검증할 값이 없다.
+
+---
+
+## 실제 이관에서 걸린 것 / 안 걸린 것
+
+`xplat-shop-templat` (pnpm 모노레포, 워크스페이스 4개) 을 **0.6.1 → 0.12.0** 으로
+올렸을 때의 결과다. DS 를 어댑터 한 곳에서만 쓰는 구조였다.
+
+| 항목 | 결과 | 이유 |
+|---|---|---|
+| `Button` href 제거 | 안 걸림 | `<Button href>` 사용 0곳 |
+| `Badge` → `NotificationBadge` | 안 걸림 | `@deprecated` 별칭으로 통과 |
+| CSS 클래스 rename | 안 걸림 | `.lib-xplat-*` 을 덮어쓰는 CSS 0곳 |
+| 오버레이 body portal | 안 걸림 | 오버레이 기준을 잡는 CSS 없음 |
+| **`label` 중첩** | **걸림** | 어댑터가 `<label htmlFor>` 를 직접 그리고 있었다 |
+
+**목록을 훑기 전에 자기 저장소에서 먼저 세어 볼 것.** 위 표에서 보듯 대부분은
+해당 사항이 없고, 진짜 걸리는 건 한둘이다. `<Button href`, `.lib-xplat-`,
+`<label` 세 가지를 grep 하는 것으로 대부분 판별된다.
+
+결과: 어댑터 241줄 → 216줄, 쓰이지 않던 CSS 30줄 삭제. DS 가 `label`·
+`aria-invalid`·`useId`·검증 메시지를 맡으면서 어댑터가 얇아진다.
+
+---
+
+## 아직 확인되지 않은 것
+
+**Editor 는 브라우저에서 검증되지 않았다.** `contentEditable`·`execCommand`·IME 는
+자동 테스트로 흉내 낼 수 없다. 특히 아래 넷은 직접 눌러 봐야 한다.
+
+- 한글 조합 중 `⌘Z` / `Ctrl+Z`
+- 툴바 서식 버튼
+- 표 안에서 Enter · Backspace
+- 체크박스 클릭 판정
+
+이상이 보이면 재현 조건과 함께 알려 주면 좋겠다.

package/guidelines/components/chip-tag.md

@@ -1,4 +1,4 @@
-# Chip & Tag
+# Chip & ToggleChip & Tag
 
 ## Chip
 
@@ -41,9 +41,82 @@
 
 ---
 
+## ToggleChip
+
+**눌러서 고르는** 칩이다. 켜짐/꺼짐을 다룬다 — `Tag` 의 클릭은 삭제이고, 이쪽은
+삭제가 아니다.
+
+```tsx
+<ToggleChip selected={picked.has("ko")} onClick={() => toggle("ko")}>
+  한국어
+</ToggleChip>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| children | `ReactNode` | — | 내용 |
+| selected | `boolean` | `false` | 켜진 상태. `aria-pressed` 도 함께 바뀐다 |
+| onClick | `() => void` | — | 누를 때 |
+| disabled | `boolean` | `false` | 흐리게 하고 못 누르게 한다 |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | `Chip` 과 같은 눈금 |
+
+**여러 개 고르기와 한 개 고르기 양쪽에 쓴다.** 몇 개까지 켤 수 있는지, 마지막
+하나를 뗄 수 있는지 같은 규칙은 쓰는 쪽 사정이라 여기서 정하지 않는다. 묶어
+주는 껍데기도 없다 — 낱개로 늘어놓고 상태만 쥐고 있으면 된다.
+
+```tsx
+// 여러 개 고르기
+const [picked, setPicked] = useState<Set<string>>(new Set());
+const toggle = (v: string) =>
+  setPicked((prev) => {
+    const next = new Set(prev);
+    next.has(v) ? next.delete(v) : next.add(v);
+    return next;
+  });
+
+{OPTIONS.map((o) => (
+  <ToggleChip key={o.value} selected={picked.has(o.value)} onClick={() => toggle(o.value)}>
+    {o.label}
+  </ToggleChip>
+))}
+
+// 한 개 고르기 (거르개)
+{FILTERS.map((f) => (
+  <ToggleChip key={f} selected={filter === f} onClick={() => setFilter(f)}>
+    {f}
+  </ToggleChip>
+))}
+```
+
+`Chip` 과 **같은 알약 모양·같은 크기 눈금**을 쓴다. 두 CSS 가 따로 있는 게
+아니라 `ToggleChip` 이 `.lib-xplat-chip` 을 그대로 입고 상호작용분만 얹으므로
+둘이 따로 놀 수 없다. 거르개 칩 아래에 표시용 `Chip` 이 깔리는 화면에서
+겉돌지 않는다.
+
+색은 `Chip` 의 상태 색(primary·success…)을 받지 않는다. **고른 것과 안 고른 것**
+두 가지뿐이라 상태 색 어휘가 끼어들 자리가 없다. 고른 것은 옅은 브랜드 바탕에
+브랜드 테두리다 — 여러 개를 한꺼번에 켜는 쓰임이 더 많은데 진한 채움이 여럿이면
+화면이 시끄럽고 곁의 버튼과 구분이 안 된다.
+
+---
+
 ## 의사결정
 
 | 상황 | 사용할 것 |
 |------|----------|
-| 상태/분류 라벨 (삭제 불필요) | Chip |
+| 상태/분류 라벨 (누를 일 없음) | Chip |
+| 눌러서 고르기 (켜짐/꺼짐) | **ToggleChip** |
 | 사용자가 제거할 수 있는 태그 | Tag |
+| 개수·점 표시 | NotificationBadge |
+
+셋이 비슷하게 생겼으므로 **무엇이 일어나는가**로 고른다.
+
+| | 누르면 | 렌더 |
+|---|---|---|
+| `Chip` | 아무 일도 없다 | `<div>` |
+| `ToggleChip` | 켜지거나 꺼진다 | `<button aria-pressed>` |
+| `Tag` | (X 를 누르면) 사라진다 | `<span>` + 닫기 `<button>` |
+
+> 고르는 칩을 `Chip` 을 `<button>` 으로 감싸서 만들지 말 것. 커서·초점 테두리·
+> `aria-pressed` 가 빠지고, 실제로 그렇게 만든 화면들에서 **아무도 누를 수 있는
+> 줄 몰랐다.** `ToggleChip` 이 그 셋을 기본으로 갖는다.

package/guidelines/components/datepicker.md

@@ -50,6 +50,32 @@ Input + 드롭다운 형태이다.
 />
 ```
 
+## 라벨과 검증
+
+`SingleDatePicker` · `RangeDatePicker` · `InputDatePicker` 는 다른 폼 컨트롤과
+똑같이 `label` · `required` · `validations` 를 받는다.
+
+```tsx
+<InputDatePicker
+  value={date}
+  onChange={setDate}
+  label="계약일"
+  required
+  validations={[{ status: "error", message: "계약일을 선택하세요" }]}
+/>
+```
+
+검증 메시지는 `FieldMessage` 가 그린다 — 아이콘·색·간격이 Input·Select 와 같다.
+직접 `<p>` 로 그리지 말 것.
+
+달력을 펼쳐 놓는 `SingleDatePicker` · `RangeDatePicker` 는 **포커스 대상이 날짜
+칸마다 있어 `htmlFor` 로 하나를 고를 수 없다.** 그래서 `role="group"` +
+`aria-labelledby` 로 라벨과 묶는다. 쓰는 쪽에서 신경 쓸 것은 없다.
+
+`PopupDatePicker` 는 라벨·검증을 받지 않는다 — 트리거를 `component` 로 직접
+넘기는 구조라 라벨이 가리킬 대상이 정해지지 않는다. 라벨이 필요하면 트리거로
+`InputDatePicker` 를 쓰거나 바깥에서 `Field` 로 감싼다.
+
 ---
 
 ## 의사결정

package/guidelines/components/file-media.md

@@ -14,16 +14,27 @@ import { FileUpload } from "@x-plat/design-system";
 | multiple | `boolean` | `false` | 다중 파일 허용 |
 | maxSize | `number` | — | 최대 파일 크기 (bytes). 초과 파일은 자동 필터 |
 | onChange | `(files: File[]) => void` | — | 파일 선택 콜백 |
-| label | `string` | `"파일을 드래그하거나 클릭하여 업로드"` | 안내 텍스트 |
-| description | `string` | — | 부가 설명 |
+| placeholder | `string` | `"파일을 드래그하거나 클릭하여 업로드"` | **상자 안** 안내 텍스트 |
+| description | `string` | — | 상자 안 부가 설명 |
+| label | `ReactNode` | — | **상자 위** 필드 라벨. 클릭하면 파일 선택창이 열린다 |
+| required | `boolean` | `false` | 라벨 뒤에 `*` 표시 |
+| validations | `Validation[]` | — | 상자 아래 검증 메시지 |
+
+> ⚠ **0.13.0 에서 `label` 의 뜻이 바뀌었다.** 예전에는 상자 **안** 글자였고
+> 지금은 상자 **위** 필드 라벨이다. 상자 안 글자는 `placeholder` 로 옮겼다.
+> 타입 오류가 나지 않고 글자 위치만 바뀌므로 눈으로 확인해야 한다.
+> 자세한 것은 [마이그레이션 노트](../MIGRATION.md) 참고.
 
 ```tsx
 <FileUpload
+  label="첨부파일"
+  required
   accept="image/*"
   multiple
   maxSize={5 * 1024 * 1024}
   onChange={(files) => console.log(files)}
   description="최대 5MB, 이미지만 허용"
+  validations={[{ status: "error", message: "파일을 첨부하세요" }]}
 />
 ```
 
@@ -40,13 +51,19 @@ import { ImageSelector } from "@x-plat/design-system";
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
 | value | `File` | — | 선택된 이미지 파일 |
-| label | `string` | `"이미지 추가하기"` | 빈 상태 안내 텍스트 |
+| placeholder | `string` | `"이미지 추가하기"` | **상자 안** 빈 상태 안내 텍스트 |
 | onChange | `(value: File \| undefined) => void` | — | 변경 콜백 (삭제 시 `undefined`) |
+| label | `ReactNode` | — | **상자 위** 필드 라벨 |
+| required | `boolean` | `false` | 라벨 뒤에 `*` 표시 |
+| validations | `Validation[]` | — | 상자 아래 검증 메시지 |
+
+> ⚠ `FileUpload` 와 같은 변경이 0.13.0 에 있었다. `label` 은 이제 필드 라벨이고,
+> 상자 안 글자는 `placeholder` 다.
 
 ```tsx
 const [image, setImage] = useState<File | undefined>();
 
-<ImageSelector value={image} onChange={setImage} />
+<ImageSelector label="대표 이미지" required value={image} onChange={setImage} />
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-plat/design-system",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",