@ceed/cds 1.29.0 → 1.29.1

package/dist/Overview.md

@@ -1,11 +1,11 @@
 # CDS (Customer Design System)
 
-CDS는 Customer Design System의 약자로, 유려한 UI를 중심으로 두는 시스템으로 개발되었습니다. 이 시스템은 사용자 친화적인 경험을 제공하고, 개발 및 디자인 프로세스를 효율화하기 위해 제작되었습니다.
+CDS stands for Customer Design System, and it was developed as a system centered around polished UI. It was created to provide a user-friendly experience and streamline development and design processes.
 
-이 디자인시스템은 [JoyUI](https://mui.com/joy-ui/getting-started/)를 기반으로 하므로 대부분 [JoyUI](https://mui.com/joy-ui/getting-started/)의 문서를 참고할 수 있지만, 일부 컴포넌트는 추상화 레이어가 추가되어 인터페이스가 다를 수 있습니다.
+This design system is built on [JoyUI](https://mui.com/joy-ui/getting-started/), so you can refer to the [JoyUI](https://mui.com/joy-ui/getting-started/) documentation for most cases, although some components may have different interfaces due to added abstraction layers.
 
-데이터 중심보다는 시각적이고 직관적인 UI를 목적으로 이름이 지어졌으며 주로 고객이 사용하는 UI에 적용됩니다.
+It is named for UIs that prioritize visual and intuitive experiences over data-centric interfaces, and it is mainly applied to customer-facing UI.
 
-## 문서 및 가이드
+## Documentation and Guides
 
-CDS에 대한 자세한 내용은 [Design System 문서](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System)를 참조하세요.
+For more information about CDS, refer to the [Design System documentation](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System).

package/dist/components/data-display/Avatar.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Avatar 컴포넌트는 사용자의 프로필 이미지, 이니셜 또는 아이콘을 표시하는 컴포넌트입니다. Joy UI의 Avatar를 기반으로 하며, 다양한 크기, 색상, 변형을 지원합니다. 사용자 인터페이스에서 개인을 시각적으로 나타내거나 그룹, 브랜드를 표현하는 데 사용됩니다.
+The Avatar component displays a user's profile image, initials, or icon. It is based on Joy UI Avatar and supports various sizes, colors, and variants. It is used to visually represent individuals, groups, or brands in a user interface.
 
 ```tsx
 <Avatar alt="User avatar" />
@@ -25,13 +25,13 @@ import { Avatar } from '@ceed/cds';
 function MyComponent() {
   return (
     <div>
-      {/* 이미지가 있는 아바타 */}
+      {/* Avatar with an image */}
       <Avatar src="/path/to/image.jpg" alt="사용자 이름" />
 
-      {/* 이니셜 아바타 */}
+      {/* Initials avatar */}
       <Avatar>김철수</Avatar>
 
-      {/* 단일 문자 아바타 */}
+      {/* Single-character avatar */}
       <Avatar>김</Avatar>
     </div>
   );
@@ -42,7 +42,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-가장 기본적인 Avatar 사용법입니다.
+The most basic Avatar usage.
 
 ```tsx
 <Avatar alt="User avatar" />
@@ -50,7 +50,7 @@ function MyComponent() {
 
 ### With Image
 
-이미지를 사용한 아바타입니다.
+An avatar that uses an image.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -60,7 +60,7 @@ function MyComponent() {
 
 ### With Text
 
-텍스트나 이니셜을 사용한 아바타입니다.
+An avatar that uses text or initials.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -72,7 +72,7 @@ function MyComponent() {
 
 ### Variants
 
-다양한 시각적 스타일을 적용할 수 있습니다.
+You can apply various visual styles.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -80,14 +80,14 @@ function MyComponent() {
 </Stack>
 ```
 
-- **solid**: 배경색이 채워진 스타일
-- **soft**: 부드러운 배경색 스타일
-- **outlined**: 테두리만 있는 스타일
-- **plain**: 최소한의 스타일
+- **solid**: A style with a filled background color
+- **soft**: A style with a soft background color
+- **outlined**: A style with only a border
+- **plain**: A minimal style
 
 ### Sizes
 
-다양한 크기의 아바타를 사용할 수 있습니다.
+You can use avatars in various sizes.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -97,14 +97,14 @@ function MyComponent() {
 </Stack>
 ```
 
-- **xs**: 매우 작은 크기 (16px)
-- **sm**: 작은 크기 (24px)
-- **md**: 중간 크기 (32px, 기본값)
-- **lg**: 큰 크기 (40px)
+- **xs**: Extra small size (16px)
+- **sm**: Small size (24px)
+- **md**: Medium size (32px, default)
+- **lg**: Large size (40px)
 
 ### Colors
 
-다양한 색상 테마를 적용할 수 있습니다.
+You can apply various color themes.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
@@ -112,15 +112,15 @@ function MyComponent() {
 </Stack>
 ```
 
-- **primary**: 주요 브랜드 색상
-- **neutral**: 중립적인 회색톤
-- **danger**: 경고나 오류를 나타내는 빨간색
-- **success**: 성공을 나타내는 녹색
-- **warning**: 주의를 나타내는 주황색
+- **primary**: Primary brand color
+- **neutral**: Neutral gray tone
+- **danger**: Red for warnings or errors
+- **success**: Green for success
+- **warning**: Orange for caution
 
 ### All Combinations
 
-모든 변형, 크기, 색상 조합을 확인할 수 있습니다.
+You can review all variant, size, and color combinations.
 
 ```tsx
 <Stack gap={8}>
@@ -150,11 +150,15 @@ function MyComponent() {
 
 ### User Profile
 
-사용자 프로필에서 아바타를 사용하는 경우입니다.
+An example of using an avatar in a user profile.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center">
-  <Avatar src="/user-profile.jpg" alt="김철수" size="lg" />
+  <Avatar
+    src="/user-profile.jpg"
+    alt="김철수"
+    size="lg"
+  />
   <Stack>
     <Typography level="title-md">김철수</Typography>
     <Typography level="body-sm" color="neutral">
@@ -166,7 +170,7 @@ function MyComponent() {
 
 ### Navigation Bar
 
-네비게이션 바에서 현재 사용자를 표시할 때 사용합니다.
+Used to display the current user in a navigation bar.
 
 ```tsx
 <Stack direction="row" spacing={2} alignItems="center" sx={{ ml: 'auto' }}>
@@ -182,7 +186,7 @@ function MyComponent() {
 
 ### Comment System
 
-댓글이나 피드에서 사용자를 나타낼 때 사용합니다.
+Used to represent a user in comments or feeds.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -196,14 +200,16 @@ function MyComponent() {
         2시간 전
       </Typography>
     </Stack>
-    <Typography level="body-md">이것은 사용자의 댓글 내용입니다.</Typography>
+    <Typography level="body-md">
+      이것은 사용자의 댓글 내용입니다.
+    </Typography>
   </Stack>
 </Stack>
 ```
 
 ### Team Members
 
-팀 구성원 목록을 표시할 때 사용합니다.
+Used to display a list of team members.
 
 ```tsx
 <Stack spacing={3}>
@@ -211,7 +217,13 @@ function MyComponent() {
 
   {teamMembers.map((member) => (
     <Stack key={member.id} direction="row" spacing={2} alignItems="center">
-      <Avatar src={member.avatar} alt={member.name} size="md" variant="soft" color="primary">
+      <Avatar
+        src={member.avatar}
+        alt={member.name}
+        size="md"
+        variant="soft"
+        color="primary"
+      >
         {member.name.charAt(0)}
       </Avatar>
       <Stack flex={1}>
@@ -230,19 +242,13 @@ function MyComponent() {
 
 ### Avatar Groups
 
-여러 사용자를 그룹으로 표시할 때 사용합니다.
+Used to display multiple users as a group.
 
 ```tsx
 <Stack direction="row" spacing={-1}>
-  <Avatar size="sm" variant="solid" color="primary">
-    김
-  </Avatar>
-  <Avatar size="sm" variant="solid" color="success">
-    이
-  </Avatar>
-  <Avatar size="sm" variant="solid" color="warning">
-    박
-  </Avatar>
+  <Avatar size="sm" variant="solid" color="primary">김</Avatar>
+  <Avatar size="sm" variant="solid" color="success">이</Avatar>
+  <Avatar size="sm" variant="solid" color="warning">박</Avatar>
   <Avatar size="sm" variant="outlined" color="neutral">
     <Typography level="body-xs">+3</Typography>
   </Avatar>
@@ -251,7 +257,7 @@ function MyComponent() {
 
 ### Status Indicators
 
-사용자 상태를 함께 표시할 때 사용합니다.
+Used to display user status alongside the avatar.
 
 ```tsx
 <Box sx={{ position: 'relative', display: 'inline-block' }}>
@@ -274,7 +280,7 @@ function MyComponent() {
 
 ### Empty State
 
-데이터가 없을 때 플레이스홀더로 사용합니다.
+Used as a placeholder when no data is available.
 
 ```tsx
 <Stack alignItems="center" spacing={2}>
@@ -292,7 +298,7 @@ function MyComponent() {
 
 ### List Items
 
-리스트 아이템에서 사용자나 항목을 표현할 때 사용합니다.
+Used to represent users or items in list items.
 
 ```tsx
 <List>
@@ -318,72 +324,107 @@ function MyComponent() {
 
 ### Fallback Behavior
 
-이미지 로드가 실패했을 때 자동으로 이니셜이나 아이콘으로 대체됩니다.
+If image loading fails, it automatically falls back to initials or an icon.
 
 ```tsx
-<Avatar src="/broken-image-url.jpg" alt="김철수" color="primary" variant="soft">
+<Avatar
+  src="/broken-image-url.jpg"
+  alt="김철수"
+  color="primary"
+  variant="soft"
+>
   김
 </Avatar>
 ```
 
 ### Loading States
 
-이미지 로딩 중에는 children이 표시되다가 이미지 로드 완료 후 이미지로 전환됩니다.
+While the image is loading, `children` are shown first, then the image is displayed once loading completes.
 
 ```tsx
-<Avatar src="/slow-loading-image.jpg" alt="사용자" color="neutral" variant="soft">
+<Avatar
+  src="/slow-loading-image.jpg"
+  alt="사용자"
+  color="neutral"
+  variant="soft"
+>
   <PersonIcon />
 </Avatar>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop         | Type                                                           | Default         | Description                                     |
+| ------------ | -------------------------------------------------------------- | --------------- | ----------------------------------------------- |
+| `src`        | `string`                                                       | -               | Image URL for the avatar                        |
+| `alt`        | `string`                                                       | -               | Alt text for the avatar image                   |
+| `children`   | `ReactNode`                                                    | -               | Fallback content (text, icon) when no image     |
+| `getInitial` | `(name: string) => string`                                     | First character | Custom function to extract initials from a name |
+| `size`       | `'sm' \| 'md' \| 'lg'`                                         | `'md'`          | Avatar size                                     |
+| `variant`    | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'soft'`        | Visual style                                    |
+| `color`      | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`     | Color scheme                                    |
+| `sx`         | `SxProps`                                                      | -               | Custom styles using the MUI system              |
+
+> **Note**: Avatar also accepts all Joy UI Avatar props and Framer Motion props.
+
 ## Accessibility
 
-Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+Avatar provides the following accessibility features:
 
 ### Image Alt Text
 
-이미지 아바타의 경우 적절한 alt 텍스트를 제공해야 합니다.
+For image avatars, provide appropriate alt text.
 
 ```tsx
-<Avatar src="/user-profile.jpg" alt="김철수의 프로필 사진" />
+<Avatar
+  src="/user-profile.jpg"
+  alt="김철수의 프로필 사진"
+/>
 ```
 
 ### Semantic Meaning
 
-아바타가 단순히 장식적 목적이 아닌 의미를 가질 때는 적절한 역할을 제공하세요.
+If the avatar carries meaning rather than serving a purely decorative purpose, provide an appropriate role.
 
 ```tsx
-<Avatar src="/user-avatar.jpg" alt="현재 사용자" role="img" aria-label="현재 로그인한 사용자의 프로필 이미지" />
+<Avatar
+  src="/user-avatar.jpg"
+  alt="현재 사용자"
+  role="img"
+  aria-label="현재 로그인한 사용자의 프로필 이미지"
+/>
 ```
 
 ### Color Contrast
 
-텍스트 아바타의 경우 충분한 색상 대비를 유지하세요.
+For text avatars, maintain sufficient color contrast.
 
 ```tsx
-// 좋은 대비를 제공하는 색상 조합
+// Color combinations that provide good contrast
 <Avatar variant="solid" color="primary">김</Avatar>
 <Avatar variant="soft" color="neutral">이</Avatar>
 ```
 
 ## Best Practices
 
-1. **적절한 크기 선택**: 사용 맥락에 맞는 적절한 크기를 선택하세요.
+1. **Choose an appropriate size**: Select a size that fits the usage context.
 
 ```tsx
-// ✅ 적절한 크기 사용
-<Avatar size="sm">김</Avatar>  // 리스트 아이템에서
-<Avatar size="lg">김</Avatar>  // 프로필 페이지에서
+// ✅ Appropriate size usage
+<Avatar size="sm">김</Avatar>  // In a list item
+<Avatar size="lg">김</Avatar>  // On a profile page
 
-// ❌ 부적절한 크기 사용
-<Avatar size="lg">김</Avatar>  // 네비게이션 바에서 (너무 큼)
+// ❌ Inappropriate size usage
+<Avatar size="lg">김</Avatar>  // In a navigation bar (too large)
 ```
 
-2. **일관된 스타일**: 같은 컨텍스트에서는 일관된 변형과 색상을 사용하세요.
+2. **Consistent styling**: Use consistent variants and colors within the same context.
 
-3. **이미지 최적화**: 아바타 이미지는 적절한 크기로 최적화하여 사용하세요.
+3. **Optimize images**: Use avatar images optimized to an appropriate size.
 
-4. **폴백 제공**: 이미지가 없거나 로드 실패 시를 대비해 적절한 폴백을 제공하세요.
+4. **Provide a fallback**: Prepare an appropriate fallback for missing or failed image loads.
 
 ```tsx
 <Avatar src={user.avatar} alt={user.name} color="primary" variant="soft">
@@ -391,14 +432,14 @@ Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
 </Avatar>
 ```
 
-5. **의미적 사용**: 아바타가 누구를 나타내는지 명확하게 식별할 수 있어야 합니다.
+5. **Meaningful usage**: It should be clear whom the avatar represents.
 
 ## Performance Considerations
 
-1. **이미지 최적화**: 아바타 이미지는 작은 크기로 최적화하여 로딩 속도를 향상시키세요.
+1. **Image optimization**: Optimize avatar images to a small size to improve loading speed.
 
-2. **Lazy Loading**: 많은 아바타가 있는 페이지에서는 지연 로딩을 고려하세요.
+2. **Lazy Loading**: Consider lazy loading on pages with many avatars.
 
-3. **캐싱**: 자주 사용되는 아바타 이미지는 적절히 캐싱하세요.
+3. **Caching**: Cache frequently used avatar images appropriately.
 
-Avatar는 사용자 인터페이스에서 개인을 시각적으로 나타내는 중요한 컴포넌트입니다. 적절한 크기, 색상, 변형을 선택하여 일관되고 접근 가능한 사용자 경험을 제공할 수 있습니다.
+Avatar is an important component for visually representing people in a user interface. By choosing the right size, color, and variant, you can provide a consistent and accessible user experience.

package/dist/components/data-display/Badge.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는 레이블을 표시하는 데 사용됩니다. 주로 알림 수, 상태 표시기, 또는 새로운 콘텐츠를 나타내는 데 활용됩니다.
+Badge is a small visual indicator that overlays another UI element to display a count, status, or label. It is commonly used to show unread notification counts, online/offline status indicators, and "NEW" labels on menu items or navigation elements. The Badge wraps a child component (such as an icon button or avatar) and positions itself in the top-right corner by default.
+
+Badge supports multiple colors, variants, and sizes for flexible visual customization. It also provides utility features like a `max` prop for truncating large numbers (e.g., "99+"), a `showZero` prop for controlling zero-count visibility, and a dot-only mode when no `badgeContent` is provided.
 
 ```tsx
 <Badge {...args}>
@@ -26,7 +28,7 @@ Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는
 
 ```tsx
 import { Badge, IconButton } from '@ceed/cds';
-import { NotificationsIcon } from '@mui/icons-material';
+import NotificationsIcon from '@mui/icons-material/Notifications';
 
 function MyComponent() {
   return (
@@ -39,11 +41,9 @@ function MyComponent() {
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-기본적인 Badge 사용법입니다.
+Basic Badge usage showing numeric counts, max overflow, and text content.
 
 ```tsx
 <div style={{
@@ -70,9 +70,9 @@ function MyComponent() {
 </div>
 ```
 
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+Apply semantic colors to convey the badge's meaning: `primary` for general counts, `danger` for urgent notifications, `success` for online status, and `warning` for attention items.
 
 ```tsx
 <div style={{
@@ -111,9 +111,9 @@ function MyComponent() {
 </div>
 ```
 
-### Variants
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Four style variants are available: `solid` (filled), `soft` (subtle background), `outlined` (border only), and `plain` (minimal).
 
 ```tsx
 <div style={{
@@ -146,9 +146,9 @@ function MyComponent() {
 </div>
 ```
 
-### Sizes
+## Sizes
 
-크기를 조절할 수 있습니다.
+Three sizes -- `sm`, `md`, and `lg` -- allow the badge to scale proportionally with its wrapped element.
 
 ```tsx
 <div style={{
@@ -176,9 +176,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Avatar
+## With Avatar
 
-아바타와 함께 사용할 수 있습니다.
+Badge pairs naturally with Avatar to indicate user status (e.g., notification count or online indicator).
 
 ```tsx
 <div style={{
@@ -195,9 +195,9 @@ function MyComponent() {
 </div>
 ```
 
-### Dot Badge
+## Dot Badge
 
-내용 없이 점으로만 표시할 수 있습니다.
+When no `badgeContent` is provided, Badge renders as a small dot. This is useful for simple presence or status indicators without a specific count.
 
 ```tsx
 <div style={{
@@ -216,9 +216,9 @@ function MyComponent() {
 </div>
 ```
 
-### Max Count
+## Max Count
 
-최대 카운트를 설정하여 숫자가 넘을 때 '+' 표시를 할 수 있습니다.
+Use the `max` prop to cap the displayed number. When `badgeContent` exceeds `max`, it renders as "max+" (e.g., "99+").
 
 ```tsx
 <div style={{
@@ -245,9 +245,9 @@ function MyComponent() {
 </div>
 ```
 
-### Show Zero
+## Show Zero
 
-기본적으로 0일 때는 숨겨지지만, showZero 옵션으로 표시할 수 있습니다.
+By default, Badge hides when `badgeContent` is `0`. Use the `showZero` prop to force it to remain visible.
 
 ```tsx
 <div style={{
@@ -276,40 +276,92 @@ function MyComponent() {
 
 ## Common Use Cases
 
-### Notification Count
+### Notification Bell
 
 ```tsx
-<Badge badgeContent={unreadCount} color="danger">
-  <IconButton>
-    <NotificationsIcon />
-  </IconButton>
-</Badge>
+import { Badge, IconButton } from '@ceed/cds';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+
+function NotificationBell({ unreadCount }) {
+  return (
+    <Badge badgeContent={unreadCount} max={99} color="danger">
+      <IconButton aria-label={`${unreadCount} unread notifications`}>
+        <NotificationsIcon />
+      </IconButton>
+    </Badge>
+  );
+}
 ```
 
-### Status Indicator
+### Online Status on Avatar
 
 ```tsx
-<Badge color="success" variant="solid">
-  <Avatar src="/user-avatar.jpg" />
-</Badge>
+import { Badge, Avatar } from '@ceed/cds';
+
+function UserAvatar({ name, avatarUrl, isOnline }) {
+  return (
+    <Badge
+      color={isOnline ? 'success' : 'neutral'}
+      variant="solid"
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+    >
+      <Avatar src={avatarUrl} alt={name} />
+    </Badge>
+  );
+}
 ```
 
-### New Items
+### New Feature Label
 
 ```tsx
-<Badge badgeContent="NEW" color="warning">
-  <Button>메뉴</Button>
-</Badge>
+import { Badge, Button } from '@ceed/cds';
+
+function FeatureButton() {
+  return (
+    <Badge badgeContent="NEW" color="warning" size="sm">
+      <Button variant="outlined">Analytics</Button>
+    </Badge>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **의미 있는 색상**: 색상은 의미를 가지도록 사용하세요 (빨간색은 중요한 알림, 초록색은 성공 상태 등).
+- **Use semantic colors consistently.** Reserve `danger` for urgent notifications, `success` for positive status (e.g., online), `warning` for attention-needed items, and `primary` for neutral counts.
+  - ✔ `color="danger"` for unread message count
+  - ✘ `color="primary"` for critical alert count
+
+- **Set a `max` value for numeric badges.** Avoid displaying very large numbers like "1,247" in a tiny badge. Use `max={99}` or `max={999}` to keep the badge compact and readable.
+
+- **Keep badge content short.** Badges work best with numbers (1-3 digits) or very short text ("NEW", "HOT"). Long text will overflow and look broken.
+
+- **Use dot badges for binary states.** When the specific count does not matter (e.g., "has unread items" vs. "12 unread items"), use a dot badge by omitting `badgeContent`.
+
+- **Do not badge everything.** Only add badges to elements where the count or status information is genuinely useful. Overuse diminishes their attention-grabbing effect.
+
+## Props and Customization
+
+### Key Props
 
-2. **적절한 콘텐츠**: 너무 긴 텍스트는 피하고, 숫자나 짧은 텍스트를 사용하세요.
+| Prop           | Type                                                             | Default                                    | Description                                                           |
+| -------------- | ---------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `badgeContent` | `ReactNode`                                                      | -                                          | Content displayed inside the badge (number, text). Omit for dot badge |
+| `children`     | `ReactNode`                                                      | -                                          | The element the badge is attached to                                  |
+| `color`        | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`   | `'danger'`                                 | Badge color                                                           |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                           | `'md'`                                     | Badge size                                                            |
+| `variant`      | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                     | `'solid'`                                  | Visual style                                                          |
+| `max`          | `number`                                                         | `99`                                       | Maximum value before showing "N+"                                     |
+| `invisible`    | `boolean`                                                        | `false`                                    | Hides the badge                                                       |
+| `showZero`     | `boolean`                                                        | `false`                                    | Shows badge when value is 0                                           |
+| `anchorOrigin` | `{ vertical: 'top' \| 'bottom'; horizontal: 'left' \| 'right' }` | `{ vertical: 'top', horizontal: 'right' }` | Badge position                                                        |
+| `badgeInset`   | `string`                                                         | -                                          | Custom inset for badge positioning                                    |
+| `sx`           | `SxProps`                                                        | -                                          | Custom styles using the MUI system                                    |
 
-3. **대비**: Badge의 색상이 배경과 충분한 대비를 가지도록 하세요.
+> **Note**: Badge also accepts all Joy UI Badge props.
 
-4. **접근성**: 시각적 정보만으로 의존하지 않고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+## Accessibility
 
-5. **일관성**: 애플리케이션 전체에서 Badge 사용 패턴을 일관되게 유지하세요.
+- Badge automatically applies `aria-label` or equivalent attributes so screen readers can announce the badge content alongside the wrapped element.
+- When using Badge on an IconButton, always provide an `aria-label` on the IconButton that includes the badge context (e.g., `aria-label="5 unread notifications"`).
+- Avoid relying solely on color to convey badge meaning. Pair colored badges with icons, text, or positional context so color-blind users can also interpret the status.
+- Dot badges (without `badgeContent`) should have an accessible label on the parent element that describes the status (e.g., "User is online").