@idbrnd/design-system 1.2.0 → 1.2.1

package/README.md

@@ -1,5 +1,10 @@
 # @idbrnd/design-system
 
+![Version](https://img.shields.io/badge/version-1.2.0-4B5FE1?style=flat-square)
+![React](https://img.shields.io/badge/React-18.3.1-61DAFB?style=flat-square&logo=react&logoColor=white)
+![Vite](https://img.shields.io/badge/Vite-7.3.0-646CFF?style=flat-square&logo=vite&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178C6?style=flat-square&logo=typescript&logoColor=white)
+
 React 기반 IDB 디자인 시스템 컴포넌트 라이브러리입니다.
 
 ## 설치
@@ -26,105 +31,171 @@ export default function App() {
 }
 ```
 
-## 제공 컴포넌트 / API
-
-- 버튼
-  - `FillButton`
-  - `OutlineButton`
-  - `TextButton`
-  - `WeakButton`
-  - `BasicIconButton`
-  - `FillIconButton`
-  - `OutlineIconButton`
-- 입력
-  - `Input`
-  - `SearchBar`
-- 컨트롤
-  - `CheckBox`
-  - `Radio`
-  - `ToggleSwitch`
-- 피드백
-  - `showToast`, `dismissToast`
-  - `showSnackbar`, `dismissSnackbar`
-  - `Spinner`, `CustomSpinner`, `Clip`, `FadeSpinner`
-- 기타
-  - `PushBadge`
-
-## 사용 예시
-
-### 1. Fill / Outline / Text / Weak Button
+---
+
+## 컴포넌트
+
+- [버튼](#버튼)
+  - [FillButton](#fillbutton)
+  - [OutlineButton](#outlinebutton)
+  - [TextButton](#textbutton)
+  - [WeakButton](#weakbutton)
+- [아이콘 버튼](#아이콘-버튼)
+  - [BasicIconButton](#basiciconbutton)
+  - [FillIconButton](#filliconbutton)
+  - [OutlineIconButton](#outlineiconbutton)
+- [입력](#입력)
+  - [Input](#input)
+  - [SearchBar](#searchbar)
+- [컨트롤](#컨트롤)
+  - [CheckBox](#checkbox)
+  - [Radio](#radio)
+  - [ToggleSwitch](#toggleswitch)
+- [피드백](#피드백)
+  - [Toast](#toast)
+  - [Snackbar](#snackbar)
+  - [PushBadge](#pushbadge)
+- [Content](#content)
+  - [ContentBadge](#contentbadge)
+  - [StateBadge](#statebadge)
+- [기타](#기타)
+  - [Spinner](#spinner)
+
+---
+
+## 버튼
+
+### FillButton
 
 ```tsx
-import {
-  FillButton,
-  OutlineButton,
-  TextButton,
-  WeakButton,
-} from "@idbrnd/design-system";
+import { FillButton } from "@idbrnd/design-system";
 
-function ButtonExample() {
-  return (
-    <>
-      <FillButton variant="primary">저장</FillButton>
-      <OutlineButton variant="secondary">취소</OutlineButton>
-      <TextButton size="small" variant="assistive">
-        텍스트 버튼
-      </TextButton>
-      <WeakButton size="xsmall" variant="error">
-        삭제
-      </WeakButton>
-    </>
-  );
-}
+<FillButton variant="primary" size="large">저장</FillButton>
+<FillButton variant="error" loading>삭제 중</FillButton>
+<FillButton variant="primary" disabled>비활성화</FillButton>
 ```
 
-### 2. Icon Button + PushBadge
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"primary"` \| `"assistive"` \| `"error"` | `"primary"` | 색상 변형 |
+| `size` | `"xsmall"` \| `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `widthType` | `"hug"` \| `"fixed"` \| `"fill"` | `"hug"` | 너비 방식 |
+| `loading` | `boolean` | `false` | 로딩 스피너 표시 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+
+### OutlineButton
 
 ```tsx
-import {
-  BasicIconButton,
-  FillIconButton,
-  OutlineIconButton,
-  PushBadge,
-} from "@idbrnd/design-system";
+import { OutlineButton } from "@idbrnd/design-system";
 
-function IconButtonExample() {
-  return (
-    <>
-      <div style={{ position: "relative", width: "fit-content" }}>
-        <BasicIconButton>+</BasicIconButton>
-        <PushBadge variant="dot" />
-      </div>
+<OutlineButton variant="primary" size="large">확인</OutlineButton>
+<OutlineButton variant="secondary">취소</OutlineButton>
+<OutlineButton variant="assistive" loading>처리 중</OutlineButton>
+```
 
-      <FillIconButton variant="primary" size="large">
-        +
-      </FillIconButton>
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"primary"` \| `"secondary"` \| `"assistive"` \| `"error"` | `"assistive"` | 색상 변형 |
+| `size` | `"xsmall"` \| `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `widthType` | `"hug"` \| `"fixed"` \| `"fill"` | `"hug"` | 너비 방식 |
+| `loading` | `boolean` | `false` | 로딩 스피너 표시 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
-      <OutlineIconButton size="medium">+</OutlineIconButton>
-    </>
-  );
-}
+### TextButton
+
+```tsx
+import { TextButton } from "@idbrnd/design-system";
+
+<TextButton variant="primary">텍스트 버튼</TextButton>
+<TextButton variant="assistive" size="small">작은 버튼</TextButton>
 ```
 
-`PushBadge` 단독 사용:
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"primary"` \| `"assistive"` \| `"error"` | `"assistive"` | 색상 변형 |
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `widthType` | `"hug"` \| `"fixed"` \| `"fill"` | `"hug"` | 너비 방식 |
+| `loading` | `boolean` | `false` | 로딩 스피너 표시 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+
+### WeakButton
 
 ```tsx
-import { PushBadge } from "@idbrnd/design-system";
+import { WeakButton } from "@idbrnd/design-system";
 
-function PushBadgeExample() {
-  return (
-    <>
-      <PushBadge variant="number" count={32} />
-      <PushBadge variant="info" />
-      <PushBadge variant="dot" />
-    </>
-  );
-}
+<WeakButton variant="primary">확인</WeakButton>
+<WeakButton variant="error" size="xsmall">삭제</WeakButton>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"primary"` \| `"assistive"` \| `"error"` | `"assistive"` | 색상 변형 |
+| `size` | `"xsmall"` \| `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `widthType` | `"hug"` \| `"fixed"` \| `"fill"` | `"hug"` | 너비 방식 |
+| `loading` | `boolean` | `false` | 로딩 스피너 표시 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+
+---
+
+## 아이콘 버튼
+
+### BasicIconButton
+
+```tsx
+import { BasicIconButton } from "@idbrnd/design-system";
+
+<BasicIconButton size="large"><SearchIcon /></BasicIconButton>
+<BasicIconButton size="small" disabled><SearchIcon /></BasicIconButton>
 ```
 
-### 3. Input (Controlled)
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
-`Input`은 `value` + `onChange`를 받는 controlled 컴포넌트입니다.
+### FillIconButton
+
+```tsx
+import { FillIconButton } from "@idbrnd/design-system";
+
+<FillIconButton variant="primary" size="large"><PlusIcon /></FillIconButton>
+<FillIconButton variant="overlay"><PlusIcon /></FillIconButton>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"primary"` \| `"basic"` \| `"overlay"` | `"primary"` | 색상 변형 |
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+
+### OutlineIconButton
+
+```tsx
+import { OutlineIconButton } from "@idbrnd/design-system";
+
+<OutlineIconButton size="large"><EditIcon /></OutlineIconButton>
+<OutlineIconButton disabled><EditIcon /></OutlineIconButton>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+
+---
+
+## 입력
+
+### Input
+
+`value` + `onChange`를 받는 controlled 컴포넌트입니다.
 
 ```tsx
 import { useState } from "react";
@@ -138,27 +209,37 @@ function InputExample() {
       headingContent="이메일"
       placeholder="이메일을 입력하세요"
       value={email}
-      onChange={(event) => setEmail(event.target.value)}
+      onChange={(e) => setEmail(e.target.value)}
       description="가입 안내 메일을 받을 주소입니다."
     />
   );
 }
 ```
 
-유의사항:
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `value` | `string` | — | **(필수)** 입력값 |
+| `onChange` | `ChangeEventHandler` | — | **(필수)** 변경 핸들러 |
+| `variant` | `"error"` \| `"success"` | — | 수동 상태 지정. 미지정 시 값 유무로 자동 결정 |
+| `headingContent` | `ReactNode` | — | 상단 라벨 |
+| `description` | `ReactNode \| boolean` | — | 하단 설명 텍스트 |
+| `errorMessage` | `ReactNode` | — | `variant="error"` 시 표시되는 메시지 |
+| `leadingIcon` | `ReactNode` | — | 입력 필드 좌측 아이콘 |
+| `trailingContent` | `ReactNode` | — | 입력 필드 우측 콘텐츠 |
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `width` | `number \| string` | `"100%"` | 너비 |
+| `readOnly` | `boolean` | `false` | 읽기 전용 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
-- `heading={false}`이면 상단 라벨과 `required` 별표 표시는 렌더링되지 않습니다. 다만 실제 `<input>`의 `required` 속성은 그대로 적용됩니다.
-- `description`은 문자열뿐 아니라 JSX도 받을 수 있습니다. `variant="error"`일 때는 `description` 대신 `errorMessage`가 우선 노출됩니다.
-- `errorMessage`도 문자열뿐 아니라 JSX를 받을 수 있습니다.
-- `leadingIcon`, `headingContent`, `trailingContent`는 모두 JSX를 넣을 수 있습니다. 특히 `trailingContent`에는 버튼, 텍스트, 아이콘 조합 등 원하는 형태의 trailing UI를 구성할 수 있습니다.
-- `width`는 `number | string`을 지원하며, 지정하지 않으면 기본값은 `100%`입니다.
+유의사항:
 - `variant`를 지정하지 않으면 값 존재 여부에 따라 내부적으로 `basic` 또는 `typed` 상태가 자동 적용됩니다.
+- `variant="error"`일 때는 `description` 대신 `errorMessage`가 우선 노출됩니다.
+- `defaultValue`는 지원하지 않습니다. 반드시 `value` + `onChange`로 제어해야 합니다.
 
-### 4. SearchBar
+### SearchBar
 
-`SearchBar`는 `Enter` 입력 또는 우측 검색 버튼 클릭 시 `onSearch`를 호출합니다.
-우측 삭제 버튼은 입력값이 있을 때만 표시되며, `onClear`를 전달하면 커스텀 삭제 동작을 사용할 수 있습니다.
-`variant="default"`는 내부 `Input`의 `basic`에 매핑되며, `onTyping`/`typed`/`error`도 각각 대응됩니다.
+`Enter` 입력 또는 우측 검색 버튼 클릭 시 `onSearch`를 호출합니다.
 
 ```tsx
 import { useState } from "react";
@@ -170,20 +251,32 @@ function SearchExample() {
   return (
     <SearchBar
       value={keyword}
-      onChange={(event) => setKeyword(event.target.value)}
-      onSearch={(value) => {
-        console.log("search:", value);
-      }}
+      onChange={(e) => setKeyword(e.target.value)}
+      onSearch={(value) => console.log("search:", value)}
       placeholder="검색어를 입력하세요"
     />
   );
 }
 ```
 
-### 5. CheckBox
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `value` | `string` | — | **(필수)** 입력값 |
+| `onChange` | `ChangeEventHandler` | — | **(필수)** 변경 핸들러 |
+| `onSearch` | `(value: string) => void` | — | 검색 실행 콜백 |
+| `onClear` | `() => void` | — | 삭제 버튼 클릭 콜백. 미지정 시 기본 동작 사용 |
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `variant` | `"default"` \| `"onTyping"` \| `"typed"` \| `"error"` | — | 상태 변형 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
-`CheckBox`는 `checked` + `onChange`를 받는 controlled 컴포넌트입니다.
-`indeterminate`는 `checked={true}`와 함께 사용하면 체크 아이콘 대신 대시(–) 아이콘을 표시합니다.
+---
+
+## 컨트롤
+
+### CheckBox
+
+`checked` + `onChange`를 받는 controlled 컴포넌트입니다.
 
 ```tsx
 import { useState } from "react";
@@ -191,40 +284,41 @@ import { CheckBox } from "@idbrnd/design-system";
 
 function CheckBoxExample() {
   const [checked, setChecked] = useState(false);
-  const [indeterminate, setIndeterminate] = useState(false);
 
   return (
     <>
-      {/* 기본 */}
       <CheckBox checked={checked} onChange={(value) => setChecked(value)} />
 
       {/* indeterminate: checked와 함께 사용 */}
-      <CheckBox
-        checked={indeterminate}
-        indeterminate={indeterminate}
-        onChange={(value) => setIndeterminate(value)}
-      />
+      <CheckBox checked={true} indeterminate onChange={() => {}} />
 
       {/* variant / size / density */}
-      <CheckBox variant="assistive" size="small" density="compact" checked />
+      <CheckBox variant="assistive" size="small" density="compact" checked onChange={() => {}} />
 
-      {/* disabled */}
       <CheckBox checked disabled />
     </>
   );
 }
 ```
 
-유의사항:
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `checked` | `boolean` | — | **(필수)** 체크 상태 |
+| `onChange` | `(checked: boolean) => void` | — | 변경 핸들러 |
+| `indeterminate` | `boolean` | `false` | `checked={true}`와 함께 사용 시 대시(–) 아이콘 표시 |
+| `variant` | `"primary"` \| `"assistive"` | `"primary"` | 색상 변형 |
+| `size` | `"medium"` \| `"small"` | `"medium"` | 크기 |
+| `density` | `"default"` \| `"compact"` | `"default"` | wrapper 밀도 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
-- `indeterminate={true}`는 `checked={true}`일 때만 대시 아이콘을 표시합니다. `checked={false}`이면 빈 박스로 표시됩니다.
-- `variant`는 `"primary"(기본값)` | `"assistive"`를 지원합니다.
-- `density="compact"`은 wrapper 크기만 줄이며, 아이콘은 box width에 맞춰 `size` 기준으로 그대로 표시됩니다.
+유의사항:
+- `indeterminate={true}`는 `checked={true}`일 때만 대시 아이콘을 표시합니다.
+- `density="compact"`은 wrapper 크기만 줄이며, 아이콘은 `size` 기준으로 그대로 표시됩니다.
 
-### 6. Radio
+### Radio
 
-`Radio`는 그룹 내 단일 선택을 위한 controlled 컴포넌트입니다.
-브라우저 기본 `name` 그룹 동작에 의존하지 않으며, `checked` prop으로 직접 선택 상태를 제어합니다.
+그룹 내 단일 선택을 위한 controlled 컴포넌트입니다.
 
 ```tsx
 import { useState } from "react";
@@ -236,10 +330,7 @@ function RadioGroupExample() {
   return (
     <>
       {["A", "B", "C"].map((v) => (
-        <label
-          key={v}
-          style={{ display: "flex", alignItems: "center", gap: 6 }}
-        >
+        <label key={v} style={{ display: "flex", alignItems: "center", gap: 6 }}>
           <Radio
             name="group"
             value={v}
@@ -254,15 +345,25 @@ function RadioGroupExample() {
 }
 ```
 
-유의사항:
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `checked` | `boolean` | — | **(필수)** 선택 상태 |
+| `onChange` | `(checked: boolean) => void` | — | 변경 핸들러 |
+| `name` | `string` | — | input name 속성 |
+| `value` | `string` | — | input value 속성 |
+| `variant` | `"primary"` \| `"assistive"` | `"primary"` | 색상 변형 |
+| `size` | `"medium"` \| `"small"` | `"medium"` | 크기 |
+| `density` | `"default"` \| `"compact"` | `"default"` | wrapper 밀도 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
+유의사항:
 - `name`이 같아도 자동으로 하나만 선택되지 않습니다. `checked={selected === value}` 비교로 직접 제어해야 합니다.
-- `onChange`는 `(checked: boolean) => void` 시그니처이며, 클릭 시 `true`가 전달됩니다. `isChecked && setSelected(v)` 패턴으로 true일 때만 state를 변경합니다.
-- `variant`는 `"primary"(기본값)` | `"assistive"`를 지원합니다.
+- `onChange`는 클릭 시 `true`가 전달됩니다. `isChecked && setSelected(v)` 패턴으로 true일 때만 state를 변경합니다.
 
-### 7. ToggleSwitch
+### ToggleSwitch
 
-`ToggleSwitch`는 `active` + `onChange`를 받는 controlled 컴포넌트입니다.
+`active` + `onChange`를 받는 controlled 컴포넌트입니다.
 
 ```tsx
 import { useState } from "react";
@@ -274,107 +375,185 @@ function ToggleSwitchExample() {
   return (
     <>
       <ToggleSwitch active={active} onChange={(value) => setActive(value)} />
-
-      {/* size */}
       <ToggleSwitch size="small" active={active} onChange={setActive} />
-      <ToggleSwitch size="large" active={active} onChange={setActive} />
-
-      {/* disabled */}
       <ToggleSwitch active disabled />
     </>
   );
 }
 ```
 
-유의사항:
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `active` | `boolean` | — | **(필수)** 활성 상태 |
+| `onChange` | `(active: boolean) => void` | — | 변경 핸들러 |
+| `size` | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
 
+유의사항:
 - 체크 상태를 나타내는 prop 이름이 `checked`가 아닌 `active`입니다.
-- `size`는 `"small"` | `"medium"(기본값)` | `"large"`를 지원합니다.
 
-### 9. Spinner
+---
+
+## 피드백
+
+### Toast
+
+`showToast` / `dismissToast`는 `document.body`에 포털을 생성하는 명령형 API입니다.
 
 ```tsx
-import {
-  Spinner,
-  CustomSpinner,
-  Clip,
-  FadeSpinner,
-} from "@idbrnd/design-system";
+import { showToast, dismissToast } from "@idbrnd/design-system";
 
-function SpinnerExample() {
-  return (
-    <div style={{ display: "flex", gap: "12px", alignItems: "center" }}>
-      <Spinner />
-      <CustomSpinner size={12} />
-      <Clip size={24} color="var(--semantic-primary-default)" />
-      <FadeSpinner width={4} height={12} />
-    </div>
-  );
-}
+showToast({ variant: "positive", message: "저장되었습니다." });
+showToast({ variant: "negative", message: "오류가 발생했습니다." });
+showToast({ variant: "basic", message: "알림 메시지입니다." });
+
+dismissToast();
 ```
 
-### 10. Toast
+| 옵션 | 타입 | 설명 |
+|------|------|------|
+| `message` | `string` | **(필수)** 표시할 메시지 |
+| `variant` | `"basic"` \| `"positive"` \| `"negative"` | 색상 변형 |
+| `duration` | `number` | 자동 닫힘 시간(ms) |
+
+### Snackbar
+
+`showSnackbar` / `dismissSnackbar`는 `document.body`에 포털을 생성하는 명령형 API입니다.
 
 ```tsx
-import { FillButton, showToast, dismissToast } from "@idbrnd/design-system";
+import { showSnackbar, dismissSnackbar } from "@idbrnd/design-system";
 
-function ToastExample() {
-  return (
-    <>
-      <FillButton
-        onClick={() =>
-          showToast({
-            variant: "positive",
-            message: "저장되었습니다.",
-          })
-        }
-      >
-        Toast 열기
-      </FillButton>
-
-      <FillButton variant="assistive" onClick={() => dismissToast()}>
-        Toast 닫기
-      </FillButton>
-    </>
-  );
-}
+showSnackbar({
+  variant: "basic",
+  heading: "Message deleted.",
+  description: "You can undo this action.",
+  actionLabel: "실행 취소",
+  onActionClick: () => console.log("undo"),
+  closeButton: true,
+});
+
+showSnackbar({ variant: "loading", heading: "처리 중..." });
+
+dismissSnackbar();
 ```
 
-### 11. Snackbar
+| 옵션 | 타입 | 설명 |
+|------|------|------|
+| `heading` | `string` | **(필수)** 제목 텍스트 |
+| `variant` | `"basic"` \| `"loading"` | 색상 변형 |
+| `description` | `string` | 본문 텍스트 |
+| `actionLabel` | `string` | 액션 버튼 레이블 |
+| `onActionClick` | `() => void` | 액션 버튼 클릭 콜백 |
+| `closeButton` | `boolean` | 닫기 버튼 표시 여부 |
+
+### PushBadge
+
+알림 뱃지 컴포넌트입니다.
 
 ```tsx
-import {
-  FillButton,
-  showSnackbar,
-  dismissSnackbar,
-} from "@idbrnd/design-system";
+import { PushBadge } from "@idbrnd/design-system";
 
-function SnackbarExample() {
-  return (
-    <>
-      <FillButton
-        onClick={() =>
-          showSnackbar({
-            variant: "basic",
-            heading: "Message deleted.",
-            description: "You can undo this action.",
-            actionLabel: "실행 취소",
-            onActionClick: () => console.log("undo"),
-            closeButton: true,
-          })
-        }
-      >
-        Snackbar 열기
-      </FillButton>
-
-      <FillButton variant="assistive" onClick={() => dismissSnackbar()}>
-        Snackbar 닫기
-      </FillButton>
-    </>
-  );
-}
+<PushBadge variant="dot" />
+<PushBadge variant="number" count={5} />
+<PushBadge variant="info" />
 ```
 
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"dot"` \| `"number"` \| `"info"` | — | **(필수)** 표시 형태 |
+| `count` | `number` | — | `variant="number"` 시 표시할 숫자 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+
+---
+
+## Content
+
+### ContentBadge
+
+텍스트에 variant와 size를 적용하는 인라인 배지 컴포넌트입니다.
+
+```tsx
+import { ContentBadge } from "@idbrnd/design-system";
+
+<ContentBadge variant="basic">기본</ContentBadge>
+<ContentBadge variant="primary">주요</ContentBadge>
+
+<ContentBadge size="default">default</ContentBadge>
+<ContentBadge size="compact">compact</ContentBadge>
+<ContentBadge size="compact-small">compact-small</ContentBadge>
+
+{/* 커스텀 색상 */}
+<ContentBadge contentColor="#6366f1" borderColor="#6366f1">커스텀</ContentBadge>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"basic"` \| `"primary"` | `"basic"` | 색상 변형 |
+| `size` | `"default"` \| `"compact"` \| `"compact-small"` | `"default"` | 크기 |
+| `contentColor` | `string` | — | 텍스트/아이콘 색상 오버라이드 |
+| `backgroundColor` | `string` | — | 배경색 오버라이드 |
+| `borderColor` | `string` | — | 테두리색 오버라이드 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+| `className` | `string` | — | 추가 클래스명 |
+| `children` | `ReactNode` | — | 배지 내용 |
+
+### StateBadge
+
+상태를 표시할 때 사용하는 배지 컴포넌트입니다. `stateIcon` prop으로 variant에 맞는 원형 dot을 표시할 수 있습니다.
+
+```tsx
+import { StateBadge } from "@idbrnd/design-system";
+
+{/* variant */}
+<StateBadge variant="basic">기본</StateBadge>
+<StateBadge variant="error">오류</StateBadge>
+<StateBadge variant="success">성공</StateBadge>
+<StateBadge variant="info">정보</StateBadge>
+<StateBadge variant="warning">경고</StateBadge>
+
+{/* size */}
+<StateBadge size="default">default</StateBadge>
+<StateBadge size="compact">compact</StateBadge>
+
+{/* stateIcon */}
+<StateBadge variant="error" stateIcon>오류</StateBadge>
+<StateBadge variant="success" stateIcon>성공</StateBadge>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `"basic"` \| `"error"` \| `"success"` \| `"info"` \| `"warning"` | `"basic"` | 상태 색상 변형 |
+| `size` | `"default"` \| `"compact"` | `"default"` | 크기 |
+| `stateIcon` | `boolean` | `false` | `true`이면 variant 색상의 원형 dot 표시 |
+| `customStyle` | `CSSProperties` | — | 추가 인라인 스타일 |
+| `className` | `string` | — | 추가 클래스명 |
+| `children` | `ReactNode` | — | 배지 내용 |
+
+---
+
+## 기타
+
+### Spinner
+
+```tsx
+import { Spinner, CustomSpinner, Clip, FadeSpinner } from "@idbrnd/design-system";
+
+<Spinner />
+<CustomSpinner size={12} />
+<Clip size={24} color="var(--semantic-primary-default)" />
+<FadeSpinner width={4} height={12} />
+```
+
+| 컴포넌트 | 주요 Props | 설명 |
+|----------|-----------|------|
+| `Spinner` | — | 기본 스피너 |
+| `CustomSpinner` | `size` | 크기 조정 가능한 스피너 |
+| `Clip` | `size`, `color` | 원형 클립 스피너 |
+| `FadeSpinner` | `width`, `height`, `color` | 페이드 인/아웃 스피너 |
+
+---
+
 ## TypeScript
 
 모든 컴포넌트의 Props 타입을 패키지에서 직접 import 할 수 있습니다.
@@ -394,9 +573,18 @@ import type {
   ToggleSwitchProps,
   ToggleSwitchSize,
   ToastShowOptions,
+  SnackbarShowOptions,
+  ContentBadgeProps,
+  ContentBadgeVariant,
+  ContentBadgeSize,
+  StateBadgeProps,
+  StateBadgeVariant,
+  StateBadgeSize,
 } from "@idbrnd/design-system";
 ```
 
+---
+
 ## 주의사항
 
 - `Input`, `SearchBar`, `CheckBox`, `Radio`, `ToggleSwitch`는 controlled 방식으로 사용해야 합니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idbrnd/design-system",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",