@ceed/cds 1.29.0 → 1.30.0

package/dist/components/feedback/Skeleton.md

@@ -249,6 +249,23 @@ function UserProfile({ loading, user }: { loading: boolean; user?: User }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop        | Type                                                             | Default     | Description                                    |
+| ----------- | ---------------------------------------------------------------- | ----------- | ---------------------------------------------- |
+| `variant`   | `'rectangular' \| 'circular' \| 'text' \| 'overlay' \| 'inline'` | `'overlay'` | Skeleton shape                                 |
+| `animation` | `'pulse' \| 'wave' \| false`                                     | `'pulse'`   | Animation type                                 |
+| `width`     | `number \| string`                                               | -           | Skeleton width                                 |
+| `height`    | `number \| string`                                               | -           | Skeleton height                                |
+| `level`     | Typography level                                                 | -           | Matches text height for `text` variant         |
+| `loading`   | `boolean`                                                        | `true`      | When false, shows children instead of skeleton |
+| `children`  | `ReactNode`                                                      | -           | Content to show when not loading               |
+| `sx`        | `SxProps`                                                        | -           | Custom styles                                  |
+
+> **Note**: Skeleton also accepts all Joy UI Skeleton props.
+
 ## Best Practices
 
 1. **Match the final layout**: Skeleton placeholders should closely approximate the size and position of the real content to prevent layout shifts.

package/dist/components/inputs/Button.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Button 컴포넌트는 사용자가 클릭하여 특정 작업을 수행할 수 있는 기본적인 UI 요소입니다. Joy UI의 Button을 기반으로 하며, Framer Motion 애니메이션 지원이 추가되었습니다. 폼 제출, 페이지 이동, 모달 열기/닫기, 데이터 처리 등 다양한 상호작용에 사용됩니다.
+Button is the primary interactive element for triggering actions. Built on Joy UI's Button with Framer Motion animation support, it provides multiple visual variants, sizes, colors, loading states, and decorator slots. Use buttons for form submissions, navigation triggers, modal actions, and data operations.
 
 ```tsx
 <>
@@ -26,7 +26,7 @@ Button 컴포넌트는 사용자가 클릭하여 특정 작업을 수행할 수
 import { Button } from '@ceed/cds';
 
 function MyComponent() {
-  return <Button onClick={() => console.log('클릭됨!')}>클릭하세요</Button>;
+  return <Button onClick={() => console.log('Clicked!')}>Click me</Button>;
 }
 ```
 
@@ -34,7 +34,7 @@ function MyComponent() {
 
 ### Basic Usage
 
-가장 기본적인 버튼 사용법입니다.
+The most basic button usage.
 
 ```tsx
 <>
@@ -46,7 +46,7 @@ function MyComponent() {
 
 ### Disabled State
 
-비활성 상태의 버튼입니다. 사용자가 클릭할 수 없으며 시각적으로도 비활성 상태임을 나타냅니다.
+A disabled button cannot be clicked and is visually dimmed.
 
 ```tsx
 <>
@@ -67,7 +67,7 @@ function MyComponent() {
 
 ### Loading State
 
-로딩 중일 때 사용하는 버튼입니다. 비동기 작업 수행 중에 사용자에게 진행 상태를 알려줍니다.
+Shows a loading indicator during async operations. The button is automatically disabled while loading.
 
 ```tsx
 <Button
@@ -84,7 +84,7 @@ function MyComponent() {
 
 ### Variants
 
-버튼의 시각적 스타일을 다양하게 변경할 수 있습니다.
+Four visual styles are available to indicate action importance.
 
 ```tsx
 <>
@@ -103,14 +103,14 @@ function MyComponent() {
 </>
 ```
 
-- **solid**: 강조가 필요한 주요 액션 (기본값)
-- **soft**: 부드러운 배경의 보조 액션
-- **outlined**: 테두리만 있는 중요도가 낮은 액션
-- **plain**: 텍스트만 있는 최소한의 스타일
+- **solid**: High-emphasis primary actions (default)
+- **soft**: Medium-emphasis secondary actions with a subtle background
+- **outlined**: Low-emphasis actions with a border
+- **plain**: Minimal actions with text only
 
 ### Sizes
 
-버튼의 크기를 조절할 수 있습니다.
+Three sizes are available: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <>
@@ -126,13 +126,9 @@ function MyComponent() {
 </>
 ```
 
-- **sm**: 작은 크기 (제한된 공간에서 사용)
-- **md**: 중간 크기 (기본값)
-- **lg**: 큰 크기 (강조가 필요한 경우)
-
 ### Colors
 
-다양한 색상 테마를 적용할 수 있습니다.
+Apply semantic colors to communicate intent.
 
 ```tsx
 <>
@@ -154,15 +150,15 @@ function MyComponent() {
 </>
 ```
 
-- **primary**: 주요 액션 (기본값)
-- **neutral**: 중립적인 액션
-- **success**: 성공/확인 액션
-- **warning**: 주의가 필요한 액션
-- **danger**: 위험한/삭제 액션
+- **primary**: Main actions (default)
+- **neutral**: Neutral actions
+- **success**: Confirmation or positive actions
+- **warning**: Caution-required actions
+- **danger**: Destructive or irreversible actions
 
 ### Decorators
 
-버튼에 아이콘이나 다른 요소를 추가할 수 있습니다.
+Add icons or other elements before or after the button text using `startDecorator` and `endDecorator`.
 
 ```tsx
 <>
@@ -177,7 +173,7 @@ function MyComponent() {
 
 ### Loading Indicator
 
-로딩 표시기를 커스터마이징할 수 있습니다.
+Customize the loading spinner with the `loadingIndicator` prop.
 
 ```tsx
 <>
@@ -192,7 +188,7 @@ function MyComponent() {
 
 ### Loading Position
 
-로딩 표시기의 위치를 조절할 수 있습니다.
+Control where the loading indicator appears with `loadingPosition`.
 
 ```tsx
 <>
@@ -212,15 +208,15 @@ function MyComponent() {
 ```tsx
 <form onSubmit={handleSubmit}>
   <Stack spacing={2}>
-    <Input placeholder="이름을 입력하세요" />
-    <Input placeholder="이메일을 입력하세요" />
+    <Input placeholder="Enter your name" />
+    <Input placeholder="Enter your email" />
 
     <Stack direction="row" spacing={2} justifyContent="flex-end">
       <Button variant="outlined" type="button" onClick={handleCancel}>
-        취소
+        Cancel
       </Button>
       <Button type="submit" loading={isSubmitting}>
-        {isSubmitting ? '저장 중...' : '저장'}
+        {isSubmitting ? 'Saving...' : 'Save'}
       </Button>
     </Stack>
   </Stack>
@@ -233,15 +229,15 @@ function MyComponent() {
 <Modal open={open}>
   <ModalDialog>
     <ModalClose />
-    <DialogTitle>삭제 확인</DialogTitle>
-    <DialogContent>정말로 이 항목을 삭제하시겠습니까? 이 작업은 되돌릴 수 없습니다.</DialogContent>
+    <DialogTitle>Confirm Deletion</DialogTitle>
+    <DialogContent>Are you sure you want to delete this item? This action cannot be undone.</DialogContent>
 
     <DialogActions>
       <Button variant="outlined" onClick={handleClose}>
-        취소
+        Cancel
       </Button>
       <Button color="danger" onClick={handleDelete}>
-        삭제
+        Delete
       </Button>
     </DialogActions>
   </ModalDialog>
@@ -252,14 +248,14 @@ function MyComponent() {
 
 ```tsx
 <Stack direction="row" spacing={2}>
-  <Button startDecorator={<AddIcon />}>새로 만들기</Button>
+  <Button startDecorator={<AddIcon />}>Create New</Button>
 
   <Button variant="outlined" startDecorator={<DownloadIcon />} onClick={handleDownload}>
-    다운로드
+    Download
   </Button>
 
   <Button variant="soft" color="success" startDecorator={<ShareIcon />}>
-    공유
+    Share
   </Button>
 </Stack>
 ```
@@ -274,9 +270,6 @@ function AsyncButton() {
     setLoading(true);
     try {
       await api.processData();
-      // 성공 처리
-    } catch (error) {
-      // 에러 처리
     } finally {
       setLoading(false);
     }
@@ -284,51 +277,84 @@ function AsyncButton() {
 
   return (
     <Button loading={loading} onClick={handleAsyncAction} startDecorator={<ProcessIcon />}>
-      데이터 처리
+      Process Data
     </Button>
   );
 }
 ```
 
-### Button Groups
+## Props and Customization
+
+### Key Props
+
+| Prop               | Type                                                           | Default                | Description                                                       |
+| ------------------ | -------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------- |
+| `children`         | `ReactNode`                                                    | -                      | Button content (text, icons, etc.)                                |
+| `variant`          | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'solid'`              | Visual style                                                      |
+| `size`             | `'sm' \| 'md' \| 'lg'`                                         | `'md'`                 | Button size                                                       |
+| `color`            | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'`            | Color scheme                                                      |
+| `disabled`         | `boolean`                                                      | `false`                | Disables the button                                               |
+| `loading`          | `boolean`                                                      | `false`                | Shows a loading indicator and disables the button                 |
+| `loadingIndicator` | `ReactNode`                                                    | `<CircularProgress />` | Custom loading indicator element                                  |
+| `loadingPosition`  | `'start' \| 'end'`                                             | `'start'`              | Where the loading indicator appears                               |
+| `startDecorator`   | `ReactNode`                                                    | -                      | Content rendered before the button text                           |
+| `endDecorator`     | `ReactNode`                                                    | -                      | Content rendered after the button text                            |
+| `fullWidth`        | `boolean`                                                      | `false`                | Stretches the button to fill its container width                  |
+| `component`        | `ElementType`                                                  | `'button'`             | Root element type (polymorphic — can render as `a`, `Link`, etc.) |
+| `type`             | `'button' \| 'submit' \| 'reset'`                              | `'button'`             | HTML button type attribute                                        |
+| `onClick`          | `(event: MouseEvent) => void`                                  | -                      | Click event handler                                               |
+| `sx`               | `SxProps`                                                      | -                      | Custom styles using the MUI system                                |
+
+> **Note**: Button also accepts all Joy UI Button props and Framer Motion props.
+
+### Polymorphic Usage
+
+Button supports the `component` prop to render as a different element:
 
 ```tsx
-<Stack direction="row" spacing={1}>
-  <Button variant="soft" size="sm">
-    전체
-  </Button>
-  <Button variant="outlined" size="sm">
-    진행중
-  </Button>
-  <Button variant="outlined" size="sm">
-    완료
-  </Button>
-</Stack>
+// Render as an anchor tag
+<Button component="a" href="/dashboard">Go to Dashboard</Button>
+
+// Render as a React Router Link
+<Button component={Link} to="/settings">Settings</Button>
 ```
 
 ## Best Practices
 
-1. **명확한 라벨**: 버튼의 기능을 명확하게 나타내는 텍스트를 사용하세요.
+1. **Choose the right variant for the action hierarchy**:
+   - Primary action: `solid`
+   - Secondary action: `outlined` or `soft`
+   - Tertiary/minimal action: `plain`
 
-2. **적절한 변형 선택**:
-   - 주요 액션: `solid`
-   - 보조 액션: `outlined` 또는 `soft`
-   - 최소한의 액션: `plain`
+2. **Use consistent color semantics**:
+   - Destructive actions: `danger`
+   - Confirmations: `success`
+   - Caution: `warning`
 
-3. **색상 의미 일관성**:
-   - 위험한 작업: `danger`
-   - 성공/확인: `success`
-   - 주의 필요: `warning`
+3. **Use clear, specific labels.** The button text should describe exactly what happens when clicked.
 
-4. **로딩 상태 표시**: 비동기 작업 시 사용자에게 피드백을 제공하세요.
+```tsx
+// ✅ Good
+<Button color="danger">Delete Account</Button>
 
-5. **접근성**: 적절한 ARIA 라벨과 키보드 탐색을 지원하세요.
+// ❌ Bad
+<Button color="danger">OK</Button>
+```
 
-## Accessibility
+4. **Show loading state during async operations** to provide user feedback.
 
-- 키보드로 접근 가능 (Tab, Space, Enter)
-- 스크린 리더 지원
-- 적절한 색상 대비
-- 비활성 상태에서 포커스 불가
+```tsx
+<Button loading={isSubmitting} type="submit">
+  Save Changes
+</Button>
+```
+
+5. **Limit the number of primary buttons** in a view. Typically one `solid` primary button per section.
+
+## Accessibility
 
-Button은 사용자 인터페이스에서 가장 기본적이면서도 중요한 상호작용 요소입니다. 적절한 스타일과 상태 관리를 통해 직관적이고 접근 가능한 사용자 경험을 제공할 수 있습니다.
+- **Keyboard accessible**: Tab to focus, Space or Enter to activate.
+- **Screen reader support**: Button text is announced as the accessible name.
+- **Disabled state**: When `disabled`, the button is removed from the tab order.
+- **Loading state**: When `loading`, the button is announced as disabled. Consider adding `aria-label` to describe the loading context if the loading indicator replaces the text.
+- **Color contrast**: All color/variant combinations meet WCAG AA contrast ratios.

package/dist/components/inputs/ButtonGroup.md

@@ -383,6 +383,23 @@ const [view, setView] = useState('list');
 
 5. **Consider vertical orientation for narrow layouts.** On mobile or in sidebars, `orientation="vertical"` prevents horizontal overflow and improves usability.
 
+## Props and Customization
+
+### Key Props
+
+| Prop          | Type                                                           | Default        | Description                         |
+| ------------- | -------------------------------------------------------------- | -------------- | ----------------------------------- |
+| `children`    | `ReactNode`                                                    | -              | Button elements inside the group    |
+| `variant`     | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'outlined'`   | Visual style applied to all buttons |
+| `size`        | `'sm' \| 'md' \| 'lg'`                                         | `'md'`         | Size applied to all buttons         |
+| `color`       | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`    | Color applied to all buttons        |
+| `disabled`    | `boolean`                                                      | `false`        | Disables all buttons in the group   |
+| `orientation` | `'horizontal' \| 'vertical'`                                   | `'horizontal'` | Layout direction                    |
+| `spacing`     | `number \| string`                                             | `0`            | Gap between buttons                 |
+| `sx`          | `SxProps`                                                      | -              | Custom styles using the MUI system  |
+
+> **Note**: ButtonGroup accepts all Joy UI ButtonGroup props.
+
 ## Accessibility
 
 - **Keyboard navigation**: All buttons within the group are focusable and navigable using the `Tab` key. Each button is a standard focusable element that responds to `Enter` and `Space`.