@x-plat/design-system 0.11.0 → 0.13.0

package/guidelines/Guidelines.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,270 @@
+# @x-plat/design-system — 마이그레이션 노트
+
+버전을 올릴 때 **실제로 깨지는 것만** 모았다. 추가된 기능은 여기 적지 않는다 —
+그건 각 컴포넌트 문서에 있다.
+
+- 최신본 URL: `https://unpkg.com/@x-plat/design-system/guidelines/MIGRATION.md`
+- 자기 버전부터 아래로 읽어 내려가면 된다.
+
+## 이 문서를 믿어도 되는 범위
+
+각 항목은 **커밋 해시**를 달아 뒀다. 커밋 제목만 보고 판단하지 말 것 —
+`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/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/editor.md

@@ -28,10 +28,20 @@ const [html, setHtml] = useState("");
 
 ## 툴바
 
-기본은 13종 전부다. `toolbar` 로 골라서 줄일 수 있다.
+기본은 전부 켜져 있다. `toolbar` 로 골라서 줄일 수 있다.
 
-`bold` `italic` `underline` `strikethrough` `code` `heading` `list` `ordered-list`
-`blockquote` `code-block` `link` `image` `divider`
+| 갈래 | 항목 |
+|---|---|
+| 인라인 | `bold` `italic` `underline` `strikethrough` `code` `highlight` `superscript` `subscript` |
+| 블록 | `heading-1` `heading-2` `heading-3` `list` `ordered-list` `checklist` `blockquote` `code-block` |
+| 삽입 | `link` `image` `table` `divider` |
+| 정렬 | `align-left` `align-center` `align-right` |
+| 기타 | `clear-format` `undo` `redo` |
+
+- **제목은 세 단계가 따로다.** 같은 레벨을 다시 누르면 단락으로 돌아간다.
+- **정렬은 `style` 이 아니라 클래스**(`align-center` 등)로 들어간다. `style` 속성을
+  허용하면 붙여넣기로 아무 CSS 나 들어올 수 있다.
+- `highlight` 는 `<mark>` 로 감싼다.
 
 ## 마크다운 단축키
 
@@ -54,12 +64,38 @@ const [html, setHtml] = useState("");
 여러 줄을 선택하고 코드 블록을 누르면 **하나의** `<pre><code>` 가 된다.
 블록마다 따로 만들어지지 않는다.
 
+### 문법 강조
+
+캐럿이 코드 블록 안에 있으면 툴바 오른쪽에 **언어 선택**이 나타난다.
+`plain` `javascript` `typescript` `json` `html` `css` `python` `sql` `bash` 9종.
+
+외부 라이브러리를 쓰지 않는 **자체 토크나이저**다. 문자열·주석·숫자·키워드를
+구분하는 수준이고, 중첩 템플릿 리터럴이나 정규식 리터럴 같은 까다로운 것은
+일부러 다루지 않는다 — 틀리게 칠하느니 안 칠하는 쪽이 낫다.
+
+언어는 `<pre class="lang-javascript">` 로 저장되어 `value` 에 함께 나간다.
+
 ```
 Enter   코드 블록 안에서 줄바꿈 (블록이 쪼개지지 않는다)
 Tab     공백 2칸 들여쓰기 (포커스가 밖으로 나가지 않는다)
 Enter × 빈 줄 둘이 이어지면 코드 블록을 빠져나온다
 ```
 
+## 표 · 목록 · 체크리스트
+
+```
+목록에서   Tab / Shift+Tab   들여쓰기 / 내어쓰기
+표 안에서  Tab / Shift+Tab   다음 칸 / 이전 칸
+표 마지막 칸에서 Tab          행 추가
+```
+
+체크리스트는 항목 **왼쪽 체크박스 영역**을 눌러 토글한다. 실제 `<input>` 이 아니라
+가상 요소로 그린다 — contentEditable 안에 input 을 넣으면 캐럿이 그 안으로 들어간다.
+
+## 평문으로 붙여넣기
+
+`⌘⇧V` (`⌃⇧V`) 는 서식 없이 글자만 넣는다. 코드 블록 안에서는 항상 평문이다.
+
 코드 블록 안에서 다시 코드 블록을 누르면 **해제**되어 일반 단락으로 돌아간다.
 
 ## 코드 블록 안에서는
@@ -69,6 +105,25 @@ Enter × 빈 줄 둘이 이어지면 코드 블록을 빠져나온다
 - **마크다운 단축키와 슬래시 메뉴가 뜨지 않는다.** 코드에 `# ` 이나 `/` 는 흔하다.
 - **붙여넣기는 순수 텍스트로만** 들어간다.
 
+## 되돌리기 / 다시하기
+
+```
+⌘Z   ⌃Z          되돌리기
+⌘⇧Z  ⌃⇧Z  ⌃Y     다시하기
+```
+
+툴바에도 `undo` / `redo` 버튼이 있다. 기본 툴바에 포함되어 있고, `toolbar` 를
+직접 지정할 때는 넣어야 나온다.
+
+- **브라우저 기본 undo 를 쓰지 않는다.** 이 에디터는 코드블럭·인라인코드·마크다운
+  단축키·슬래시 명령을 DOM 직접 조작으로 처리하는데, 그런 작업은 브라우저 undo
+  스택에 올라가지 않는다. 그대로 두면 ⌘Z 가 그 작업을 건너뛰고 엉뚱한 지점으로 간다.
+- **연속 입력은 한 덩어리**로 묶인다(500ms). 한 글자씩 되돌아가지 않는다.
+- **블록을 만드는 작업**(코드블럭·구분선)은 따로 경계를 만든다. 코드블럭을 넣은 뒤
+  ⌘Z 한 번이면 정확히 그것만 취소된다.
+- 되돌린 뒤 새로 입력하면 앞쪽(redo) 기록은 버려진다.
+- `value` 가 **밖에서** 바뀌면(폼 리셋 등) 그 지점이 새 기준이 되어 이전 기록은 사라진다.
+
 ## 붙여넣기
 
 붙여넣는 HTML 은 항상 정화된다. 허용 태그 밖은 자식을 살려 벗겨내고,

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.11.0",
+  "version": "0.13.0",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",