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

package/README.md

@@ -8,8 +8,8 @@ npm 패키지입니다.
 계정이나 읽기 토큰 없이 설치할 수 있습니다.
 
 ```bash
-npm install @highpixel-co/palda-design-system
-# pnpm 프로젝트: pnpm add @highpixel-co/palda-design-system
+npm install --save-exact @highpixel-co/palda-design-system
+# pnpm 프로젝트: pnpm add --save-exact @highpixel-co/palda-design-system
 ```
 
 ## 사용
@@ -31,6 +31,25 @@ import { Button } from '@highpixel-co/palda-design-system/ui';
 
 루트 경로에서는 아이콘, UI와 패턴을 함께 내보냅니다. JS 토큰은 `/tokens`에서만 가져옵니다.
 
+## 설명서와 앱 검사
+
+이 패키지는 같은 버전의 사용 문서·catalog·앱용 하네스를 함께 포함합니다. 별도의 DS clone은
+필요하지 않습니다. Node.js 22.12 이상에서 실행합니다.
+
+```bash
+pnpm exec palda-ds guide
+pnpm exec palda-ds check
+pnpm exec palda-ds screens # HTML 화면 시안이 있는 프로젝트
+```
+
+npm은 `npm exec -- palda-ds check`로 실행합니다. [사용 설명서](./dist/guide/docs/CONSUMER_GUIDE.md)에
+검사 범위, 경로 설정, 기존 코드 예외, AI 작업 규칙과 CI 연결 방법이 있습니다. `guide` 명령은
+설치된 설명서의 파일 경로를 출력합니다. 기계가 읽는 export·자산 상태 목록은 `/catalog`에 있습니다.
+
+앱은 DS 버전을 정확히 고정하고 package.json과 잠금 파일을 함께 갱신합니다. 앱의 기존 전체
+검사와 CI에 `palda-ds check`를 한 번 연결합니다. 작업 중 검사 시점은 AI가 판단하고, 제출 전에는
+전체 검사를 수행합니다. GitHub에서 검사 통과를 병합 조건으로 지정하는 것은 관리자 설정입니다.
+
 ## 릴리스
 
 내부 `@palda/tokens`, `@palda/icons`, `@palda/ui`, `@palda/patterns` workspace는 개별 배포하지

package/dist/guide/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 highpixel Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/guide/NOTICE

@@ -0,0 +1,29 @@
+Palda Design System
+Copyright (c) 2026 highpixel Co., Ltd.
+
+이 저장소는 MIT 라이선스로 배포한다. 전문은 `LICENSE`에 있다.
+
+## 상표
+
+"Palda", "팔다", "highpixel"의 이름과 로고, 그 밖의 브랜드 표지는 highpixel Co., Ltd.의
+상표다. MIT 라이선스는 이 상표를 사용할 권리를 부여하지 않는다. 이 저장소에서 파생한 결과물이
+highpixel의 제품이거나 highpixel이 보증한다는 인상을 주는 방식으로 브랜드 표지를 쓰지 않는다.
+
+그래서 로고 원본은 이 저장소에 담지 않는다. `assets/logos/`는 비어 있고 `.gitignore`가
+막는다. MIT로 배포되는 자리에 상표를 두면 두 규칙이 서로 반대말을 하기 때문이다
+(`docs/decisions/0028`).
+
+## 서드파티
+
+### Lucide (ISC)
+
+`icons/svg/`의 아이콘 일부는 Lucide(https://lucide.dev)의 path 데이터를 Palda 아이콘 규격으로
+변환한 것이다. 아이콘마다의 출처는 `icons/manifest.json`의 `origin`에 있고, 세트별 목록과
+라이선스 전문은 거기서 생성되는 `icons/NOTICE`에 있다 (`docs/decisions/0027`). npm으로 배포하는
+파일의 `NOTICE`에도 이 전문을 함께 넣는다.
+
+### Pretendard (SIL Open Font License 1.1)
+
+기본 서체는 Pretendard(https://github.com/orioncactus/pretendard)를 CSS에서 이름으로만
+참조하며, 이 저장소는 폰트 파일을 포함하거나 배포하지 않는다. 폰트 파일을 함께 배포하려면
+OFL 1.1 전문을 동봉해야 한다.

package/dist/guide/README.md

@@ -0,0 +1,57 @@
+# Palda Design System
+
+Palda의 디자인 원칙, 토큰, 컴포넌트, 아이콘, 패턴을 관리하는 단일 원본(SSOT)입니다.
+
+## 시작하기
+
+```bash
+pnpm install
+pnpm storybook
+```
+
+## 제품에서 사용하기
+
+공개 npm 패키지 하나만 설치합니다. 계정이나 읽기 토큰은 필요하지 않습니다.
+
+```bash
+npm install --save-exact @highpixel-co/palda-design-system
+# pnpm 프로젝트: pnpm add --save-exact @highpixel-co/palda-design-system
+```
+
+예전에 이 패키지를 GitHub Packages에서 설치했다면 `npm config get
+@highpixel-co:registry`로 사용자 설정을 확인합니다. 결과가 `https://npm.pkg.github.com`이고 같은
+scope의 다른 비공개 패키지를 쓰지 않는다면 `npm config delete @highpixel-co:registry
+--location=user`로 예전 설정을 지운 뒤 다시 설치합니다.
+
+```ts
+import '@highpixel-co/palda-design-system/styles.css';
+
+import { SearchIcon } from '@highpixel-co/palda-design-system/icons';
+import { EmptyState } from '@highpixel-co/palda-design-system/patterns';
+import { SemanticSpaceGapLg } from '@highpixel-co/palda-design-system/tokens';
+import { Button } from '@highpixel-co/palda-design-system/ui';
+```
+
+`styles.css`를 함께 불러오지 않으면 토큰이 없어 색이 나오지 않습니다.
+
+`tokens/`, `icons/`, `components/`, `patterns/`는 저장소 내부 모듈이며 개별 배포하지 않습니다.
+배포와 소비 설정은 [`packages/palda-design-system/README.md`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/packages/palda-design-system/README.md)를
+따릅니다.
+
+- 디자이너: [`docs/REPOSITORY_GUIDE.md`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/REPOSITORY_GUIDE.md)부터 읽습니다.
+- 디자인 원칙: [`docs/DESIGN_PRINCIPLES.md`](docs/DESIGN_PRINCIPLES.md)
+- Figma 운영: [`docs/FIGMA_WORKFLOW.md`](docs/FIGMA_WORKFLOW.md)
+- 기여 절차: [`docs/CONTRIBUTING.md`](https://github.com/highpixel-co/palda-design-system/blob/0504d8eaa033955d7a70414616ee999e447a0ced/docs/CONTRIBUTING.md)
+
+현재 토큰과 컴포넌트 값은 구조를 보여주기 위한 예시이며, 디자이너 검토 후 확정해야 합니다.
+
+## 라이선스
+
+MIT 라이선스로 배포합니다. 전문은 [`LICENSE`](LICENSE)에 있습니다.
+
+"Palda", "팔다", "highpixel"의 이름과 로고는 highpixel Co., Ltd.의 상표입니다. MIT
+라이선스는 이 상표를 사용할 권리를 부여하지 않습니다.
+
+포함된 서드파티 저작물과 상표 조건은 [`NOTICE`](NOTICE)를 따릅니다.
+
+Copyright (c) 2026 highpixel Co., Ltd.

package/dist/guide/catalog/components.yml

@@ -0,0 +1,272 @@
+alert:
+  status: draft
+  source: components/src/Alert/Alert.tsx
+  story: components/src/Alert/Alert.stories.tsx
+  figma: TODO
+  use_for:
+    - 화면에 남아 있는 안내·경고·오류 배너
+    - 안내와 함께 이어서 할 액션을 하나 내놓기 (action 슬롯)
+  avoid_for:
+    - 잠깐 떴다 사라지는 알림 (Toast를 쓴다)
+    - 흐름을 끊고 확인·결정을 받는 것 (Modal을 쓴다)
+    - 입력 필드 하나의 오류 (TextField의 error를 쓴다)
+    - 섹션 단위 오류 (FormSection을 쓴다)
+    - 행 하나의 실패 (그 행의 Badge를 쓴다 — 0024)
+  variant:
+    neutral: 분류 없는 안내. 기본값이다
+    accent: 이어서 할 일이 있는 안내
+    warning: 되돌릴 수 있는 주의 상황
+    danger: 오류와 실패
+  note: >-
+    role은 prop이 아니라 variant에서 파생한다(0004) — danger만 role="alert"이고 나머지는
+    role="status"다. 색은 제목과 아이콘이 내고 본문은 text/primary다. 여러 줄로 읽는 문장이라
+    틴트 배경 위 글자를 text/{family}로 두는 Badge와 갈린다. 보더를 주지 않는다(0011).
+  planned: >-
+    시안 없이 만든 초안. 파랑 계열 primitive가 없어 info variant가 없고, 명세의 파란 배너는
+    neutral로 받는다. 닫기 버튼은 두지 않았다 — 닫는 배너가 쓰이는 자리가 아직 없다.
+
+badge:
+  status: stable
+  source: components/src/Badge/Badge.tsx
+  story: components/src/Badge/Badge.stories.tsx
+  figma: TODO
+  use_for:
+    - 항목의 상태나 분류를 읽기 전용으로 표시
+    - 목록·카드에 덧붙이는 짧은 라벨
+  avoid_for:
+    - 누르는 동작. 배지는 누를 수 없다 (Chip이나 Button을 쓴다)
+    - 상태에 따라 달라지는 표시 (hover·focus·disabled가 없다)
+
+button:
+  status: stable
+  source: components/src/Button/Button.tsx
+  story: components/src/Button/Button.stories.tsx
+  figma: TODO
+  use_for:
+    - 주요 액션
+    - 폼 제출
+  avoid_for:
+    - 아이콘만 남는 액션 (IconButton을 쓴다)
+    - 처리 중 표시 (loading prop이 없다. disabled로 표현한다)
+  variant:
+    primary: 화면에서 가장 중요한 액션. 기본값이다
+    accent: 브랜드 포인트를 주는 강조 액션
+    secondary: 눈에 띄어야 하는 보조 액션
+    outline: 주 액션 옆에 놓는 보조 액션. 취소·뒤로
+    subtle: 최소 강조. 인라인과 툴바
+
+checkbox:
+  status: draft
+  source: components/src/Checkbox/Checkbox.tsx
+  story: components/src/Checkbox/Checkbox.stories.tsx
+  figma: TODO
+  use_for:
+    - 여러 개를 동시에 켜고 끄는 폼 입력
+    - 약관 동의처럼 하나를 켜고 끄는 폼 입력
+  avoid_for:
+    - 상호 배타적인 단일 선택 (Radio를 쓴다)
+    - 저장 없이 즉시 반영되는 설정 켜기·끄기 (Switch를 쓴다)
+    - 목록을 좁히는 필터 토글 (Chip을 쓴다)
+  note: 라벨을 넘기지 않으면 접근 가능한 이름을 `aria-label`로 준다. 히트 영역은 `<label>` 전체라 라벨을 눌러도 켜진다. 체크 표시는 아이콘 세트를 쓰지 않고 컨트롤이 직접 그린다 — `check` 아이콘의 `avoidFor`에 "체크박스 컨트롤"이 있다.
+  planned: 상자 보더 1.5px은 시안 값이라 그대로 뒀다 (시스템 보더 1px 규칙의 예외, 2026-08-05 확정). disabled + checked의 체크 표시는 시안대로 흰색(`primary/subtle`)이다. 밝은 배경 규칙(`state/disabled`)을 그대로 따르면 채움과 같은 색이라 체크가 사라지고, 지금 값은 채움 위 대비가 1.1:1이라 흐리게 보인다. 시안에 hover가 없어 hover 채움은 두지 않았다(2026-08-05 확정). 부분 선택(indeterminate)은 시안에 없어서 없다.
+
+chip:
+  status: stable
+  source: components/src/Chip/Chip.tsx
+  story: components/src/Chip/Chip.stories.tsx
+  figma: TODO
+  use_for:
+    - 목록을 좁히는 필터 토글
+    - 여러 개를 켜고 끄는 선택지 모음
+  avoid_for:
+    - 읽기 전용 분류 표시 (Badge를 쓴다)
+    - 상호 배타적인 단일 선택 (Radio를 쓴다)
+  note: 선택 상태는 색만으로 전달하지 않도록 `aria-pressed`로 함께 노출한다. 아이콘은 라벨 뒤에 온다.
+
+dropdown-button:
+  status: draft
+  source: components/src/DropdownButton/DropdownButton.tsx
+  story: components/src/DropdownButton/DropdownButton.stories.tsx
+  figma: TODO
+  use_for:
+    - 버튼 하나에 묶이는 여러 액션
+    - 목록의 정렬·보기 방식 바꾸기
+    - 라디오를 펼쳐 놓을 자리가 없는 단일 선택
+  avoid_for:
+    - 액션이 하나뿐일 때 (Button을 쓴다)
+  variant:
+    outline: 테두리가 있는 기본 트리거
+    subtle: 테두리 없는 저강도 트리거. 툴바와 인라인
+  note: 트리거는 시안 확정. 메뉴 패널·align·chevron 아이콘은 확정 전이다.
+  planned: 다중 선택은 아직 없다. 들일 때 선택된 항목은 체크 아이콘(`CheckIcon`)으로 표시한다(2026-07-31 확정). 아이콘은 2026-07-31에 추가했다. 남은 것은 `DropdownButtonItem`에 선택 상태를 어떻게 두고 `onSelect`가 무엇을 돌려줄지 정하는 것이며, 공개 API가 바뀌므로 결정 기록을 함께 남긴다.
+
+icon-button:
+  status: stable
+  source: components/src/IconButton/IconButton.tsx
+  story: components/src/IconButton/IconButton.stories.tsx
+  figma: TODO
+  use_for:
+    - 아이콘만으로 뜻이 통하는 액션
+    - 툴바·입력 안쪽처럼 라벨을 놓을 자리가 없는 액션
+  avoid_for:
+    - 라벨을 놓을 자리가 있는 액션 (Button을 쓴다)
+  note: variant 다섯 종의 뜻은 Button과 같다. 접근 가능한 이름은 `label`로 주며 필수다.
+
+link:
+  status: draft
+  source: components/src/Link/Link.tsx
+  story: components/src/Link/Link.stories.tsx
+  figma: TODO
+  use_for:
+    - 눌러서 다른 주소로 이동하는 것. 문장 안 인라인과 보조 안내 줄에 쓴다
+    - 새 탭으로 여는 외부 문서 (external을 켠다)
+  avoid_for:
+    - 이동하지 않는 동작 (Button을 쓴다). 반대로 이동하는 것을 Button으로 대신하지도 않는다 —
+      새 탭·주소 복사·가운데 클릭이 전부 달라진다
+    - 화면의 주 액션 (Button을 쓴다)
+  note: >-
+    밑줄은 rest에서도 있다. 색만으로 링크임을 전하지 않는다(docs/ACCESSIBILITY.md).
+    variant는 primary(먹색)와 accent(보라) 둘이고, accent는 아껴 쓴다 — 한 화면에서 강조는
+    하나다. 읽은 링크는 text/primary-sub로 물러난다. 전용 visited 색 토큰은 없고, 두려면
+    새로 정해야 한다. 상태를 prop으로 갖지 않는다(0004) — hover·focus·visited는 전부 CSS다.
+
+modal:
+  status: draft
+  source: components/src/Modal/Modal.tsx
+  story: components/src/Modal/Modal.stories.tsx
+  figma: TODO
+  use_for:
+    - 흐름을 멈추고 확인·결정을 받는 대화상자
+    - 본문 위에서 처리하는 짧은 작업
+  avoid_for:
+    - 흐름을 끊지 않아도 되는 알림 (Toast를 쓴다)
+    - 뒤 화면을 보면서 해야 하는 일 (인라인으로 펼친다)
+    - 필드가 여러 개인 편집 폼 (새 페이지로 연다)
+    - 모달 위에 다시 여는 것 (이중 모달은 금지다)
+  note: >-
+    시안은 카드 표면만 정의한다. 기본 폭 480px. 포커스 트랩과 스크롤 잠금은 접근성 요구라 시안
+    대상이 아니고 디자인 판단으로 뒤집지 않는다 — 4층이 흐름을 끊는다는 정의를 이 둘이 만든다.
+    스크림은 overlay/dim(70%)으로 두는 것을 2026-08-31에 확정했다. 시안에서 온 값은 아니지만
+    옅게 잡으면 모달 카드가 흰색인 것(0013)이 성립하지 않는다 — 근거는
+    docs/DESIGN_GRAMMAR.md §띄우나 마나에 있고, 그 문서가 언제 모달인지와 겹침 규칙의 정본이다.
+
+navigation-button:
+  status: draft
+  source: components/src/NavigationButton/NavigationButton.tsx
+  story: components/src/NavigationButton/NavigationButton.stories.tsx
+  figma: TODO
+  use_for:
+    - 사이드바·내비게이션의 화면 이동 항목
+    - 지금 보고 있는 화면을 목록에서 표시하기
+  avoid_for:
+    - 화면을 옮기지 않는 액션 (Button을 쓴다)
+    - 목록을 좁히는 필터 토글 (Chip을 쓴다)
+  note: 현재 위치는 색만으로 전달하지 않도록 `aria-current="page"`로 함께 노출한다. 아이콘은 라벨 앞에 온다. 폭은 부모를 채우고 라벨은 넘치면 잘린다.
+  planned: 시안에 hover/pressed가 없어 default 위에 `state/hover-pressed` 채움만 얹는 것으로 정의했고 확정 전이다. 선택 안 된 항목의 텍스트는 시안대로 `text/disabled`라 흰 배경에서 대비가 2.3:1로 미달이다. `<a href>` 렌더는 두지 않았다.
+
+progress-bar:
+  status: draft
+  source: components/src/ProgressBar/ProgressBar.tsx
+  story: components/src/ProgressBar/ProgressBar.stories.tsx
+  figma: TODO
+  use_for:
+    - 끝이 정해진 작업이 얼마나 찼는지 보여 주기
+  avoid_for:
+    - 얼마나 걸릴지 모르는 대기 (스피너를 쓴다)
+    - 단계 목록 자체를 보여 주기 (진행률은 값 하나다)
+  note: >-
+    막대만으로는 무엇의 진행률인지 알 수 없어 label이 필수다. 채움은 accent가 아니라 primary다 —
+    한 화면에 여럿 놓이고 강조가 아니라 값을 읽는 자리다. 0~100을 벗어난 값은 잘라서 그리고,
+    aria와 채움이 같은 값을 쓴다.
+  planned: >-
+    시안 없이 만든 초안. 높이 8px은 명세 실측값이고 대응 토큰이 없다. variant와 size를 두지
+    않았다 — 색으로 상태를 가르는 자리도, 다른 높이가 필요한 자리도 아직 없다.
+
+radio:
+  status: stable
+  source: components/src/Radio/Radio.tsx
+  story: components/src/Radio/Radio.stories.tsx
+  figma: TODO
+  use_for:
+    - 상호 배타적인 선택지 하나 고르기
+    - 폼의 단일 선택 필드
+  avoid_for:
+    - 여러 개를 동시에 고르는 선택 (Chip을 쓴다)
+    - 즉시 반영되는 켜기·끄기 (Switch를 쓴다)
+    - 선택지를 펼쳐 놓을 자리가 좁을 때 (DropdownButton을 쓴다)
+  note: 라벨을 넘기지 않으면 접근 가능한 이름을 `aria-label`로 준다.
+
+switch:
+  status: stable
+  source: components/src/Switch/Switch.tsx
+  story: components/src/Switch/Switch.stories.tsx
+  figma: TODO
+  use_for:
+    - 즉시 반영되는 설정 켜기/끄기
+    - 저장 버튼 없이 값이 바뀌는 단일 옵션
+  avoid_for:
+    - 저장 버튼을 눌러야 반영되는 값
+    - 선택지가 둘보다 많은 경우 (Radio를 쓴다)
+  note: 라벨 슬롯이 없어서 접근 가능한 이름을 `aria-label`이나 바깥 label로 준다.
+
+tab:
+  status: draft
+  source: components/src/Tab/Tab.tsx
+  story: components/src/Tab/Tab.stories.tsx
+  figma: TODO
+  use_for:
+    - 같은 화면 안에서 보이는 내용만 갈아 끼우는 전환
+    - 한 번에 하나만 열리는 상호 배타적인 화면 묶음
+    - 목록 위에서 갈래를 가르는 단일 선택 필터 (2026-09-01에 FilterTabs를 흡수했다, 0023)
+  avoid_for:
+    - 다른 화면으로 옮기는 이동 (NavigationButton을 쓴다)
+    - 여러 개를 동시에 거는 토글 (Chip을 쓴다)
+    - 상호 배타적인 폼 입력값 (Radio를 쓴다)
+  note: 항목 하나만 있는 컴포넌트다. `role="tab"`이 유효하려면 쓰는 쪽이 `role="tablist"`로 감싸야 하고, 화살표 키 이동(roving tabindex)과 패널 연결(`aria-controls`)도 쓰는 쪽 몫이다. 선택 상태는 색과 밑줄만으로 전달하지 않도록 `aria-selected`로 함께 노출한다. 아이콘은 라벨 앞에 온다. 폭은 라벨 길이만큼이고 라벨은 접히지 않는다. 탭은 이것 하나다 — 2026-09-01에 `FilterTabs` pattern을 흡수했고, 목록을 좁히는 자리와 패널을 갈아 끼우는 자리가 같은 값을 쓴다(0023). 줄 전체를 받치는 1px 선도 감싸는 쪽이 갖는다.
+  planned: 선택 밑줄 2px은 시안 값이라 그대로 뒀다 (시스템 보더 1px 규칙의 예외, 2026-08-05 확정). 안 고른 탭의 텍스트는 `text/primary-sub`다 — 시안의 `text/disabled`는 대비 2.3:1 미달이고 disabled와 색이 같아 안 고른 탭이 꺼진 탭으로 읽혀서 0023에서 뒤집었다. 아이콘 색은 아직 `state/disabled`라 글자와 짝이 맞지 않는다. 시안의 채움이 각져서 다른 컨트롤과 달리 `radius/control`을 쓰지 않는다. 시안에 없는 것 — 고른 탭의 hover는 안 고른 탭과 같은 채움으로 정의했고, disabled는 안 고른 탭에 커서만 바꿔 정의했다. 모두 확정 전이다. TabList 컨테이너는 두지 않았다.
+
+textfield:
+  status: stable
+  source: components/src/TextField/TextField.tsx
+  story: components/src/TextField/TextField.stories.tsx
+  figma: TODO
+  use_for:
+    - 한 줄 텍스트 입력
+    - 글자 수 제한이 있는 긴 문장 입력
+  avoid_for:
+    - 읽기 전용 표시 (`readOnly`를 설계상 두지 않았다. decisions/0004 참고)
+    - 여러 줄 입력에 `sm` (`sm`은 40px 한 줄 input이다)
+  variant:
+    outline: 흰 배경에 회색 보더. 대부분의 입력이고 기본값이다
+    accent: 흰 배경에 보라 보더. 강조하는 입력
+    subtle: 배경과 보더 없음. 인라인과 저강도
+  note: 크기가 렌더 요소를 정한다. `md`는 120px textarea, `sm`은 40px input이다. 글자 수 표시는 `maxLength`로 켠다.
+
+toast:
+  status: draft
+  source: components/src/Toast/Toaster.tsx
+  story: components/src/Toast/Toaster.stories.tsx
+  figma: TODO
+  use_for:
+    - 작업 결과를 흐름을 끊지 않고 알리기
+    - 실행취소처럼 잠깐만 유효한 액션 내놓기
+  avoid_for:
+    - 확인이나 결정을 받아야 하는 경우 (Modal을 쓴다)
+    - 성공·경고·정보를 색으로 구분하기 (대응 token이 없어 variant가 둘뿐이다)
+  variant:
+    primary: 일반 알림. `role=status`로 읽힌다
+    danger: 오류와 실패. `role=alert`로 읽힌다
+  note: 시안 없이 만든 초안. 공개 API는 `<Toaster />` 하나와 `toast()` 함수이고 Toast 자체는 내부 구현이다. variant는 토큰이 있는 primary·danger 둘뿐이고 success·warning·info는 토큰이 없어 두지 않았다. 자동 닫힘 5초·폭 400px·뜨는 자리는 확정 전이다.
+
+tooltip:
+  status: draft
+  source: components/src/Tooltip/Tooltip.tsx
+  story: components/src/Tooltip/Tooltip.stories.tsx
+  figma: TODO
+  use_for:
+    - 트리거만 봐서는 모자란 짧은 보충 설명
+    - 아이콘 버튼의 동작을 글로 덧붙이기
+  avoid_for:
+    - 아이콘 버튼의 접근 가능한 이름 (aria-label을 쓴다)
+    - 툴팁을 열어야만 알 수 있는 정보 (터치에는 hover가 없다)
+  note: 시안 없이 만든 초안. placement·최대 폭·여는 지연·화살표 크기는 확정 전이다. 트리거는 포커스를 받을 수 있는 요소 하나여야 한다.