@ceed/ads 1.23.3 → 1.23.4

package/dist/components/inputs/IconButton.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-IconButton 컴포넌트는 아이콘만으로 구성된 버튼입니다. 공간 효율적이며, 직관적인 액션을 제공하는 UI 요소로 주로 툴바, 헤더, 카드 등에서 사용됩니다. 텍스트 없이도 의미를 전달할 수 있는 명확한 아이콘과 함께 사용하세요.
+IconButton is a compact, icon-only button component designed for actions where a visual symbol alone is sufficient to communicate meaning. It is ideal for toolbars, table row actions, card headers, navigation bars, and any context where space efficiency is critical.
+
+Because IconButton omits visible text, it relies entirely on the icon's clarity and supplementary accessibility attributes to convey its purpose. Always pair it with `aria-label` or a Tooltip to ensure all users can understand the button's function.
 
 ```tsx
 <IconButton {...args} />
@@ -22,56 +24,26 @@ IconButton 컴포넌트는 아이콘만으로 구성된 버튼입니다. 공간
 ```tsx
 import { IconButton } from '@ceed/ads';
 import AddIcon from '@mui/icons-material/Add';
+import DeleteIcon from '@mui/icons-material/Delete';
 
 function MyComponent() {
   return (
-    <div>
-      <IconButton onClick={() => console.log('clicked')}>
+    <div style={{ display: 'flex', gap: '0.5rem' }}>
+      <IconButton aria-label="Add item" onClick={handleAdd}>
         <AddIcon />
       </IconButton>
 
-      <IconButton color="danger" onClick={() => console.log('delete')}>
+      <IconButton color="danger" aria-label="Delete item" onClick={handleDelete}>
         <DeleteIcon />
       </IconButton>
-
-      <IconButton disabled>
-        <EditIcon />
-      </IconButton>
     </div>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
-
-기본적인 IconButton 사용법입니다.
-
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '1rem',
-  alignItems: 'center'
-}}>
-<IconButton>
-  <Add />
-</IconButton>
-<IconButton>
-  <Edit />
-</IconButton>
-<IconButton>
-  <Delete />
-</IconButton>
-<IconButton>
-  <Settings />
-</IconButton>
-</div>
-```
-
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+IconButton supports five semantic colors: `primary` (default), `neutral`, `danger`, `success`, and `warning`. Choose a color that reflects the nature of the action.
 
 ```tsx
 <div style={{
@@ -97,9 +69,9 @@ function MyComponent() {
 </div>
 ```
 
-### Variants
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Four visual variants are available: `solid` (filled background), `soft` (tinted background), `outlined` (border only), and `plain` (no background). Use `outlined` or `plain` for secondary actions, and `solid` for primary or high-emphasis actions.
 
 ```tsx
 <div style={{
@@ -122,9 +94,9 @@ function MyComponent() {
 </div>
 ```
 
-### Sizes
+## Sizes
 
-크기를 조절할 수 있습니다.
+The `size` prop controls the button dimensions. Available sizes are `sm`, `md` (default), and `lg`. Ensure touch targets meet the minimum 44px recommended size for touch interfaces.
 
 ```tsx
 <div style={{
@@ -144,9 +116,9 @@ function MyComponent() {
 </div>
 ```
 
-### States
+## States
 
-다양한 상태를 표현할 수 있습니다.
+IconButton supports multiple interactive states including normal, disabled, and loading. Use `disabled` to prevent interaction and `loading` to indicate an in-progress async operation.
 
 ```tsx
 <div style={{
@@ -202,9 +174,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Badge
+## With Badge
 
-Badge와 함께 사용하여 알림 수나 상태를 표시할 수 있습니다.
+Combine IconButton with Badge to display notification counts, status indicators, or unread markers alongside the button.
 
 ```tsx
 <div style={{
@@ -230,9 +202,9 @@ Badge와 함께 사용하여 알림 수나 상태를 표시할 수 있습니다.
 </div>
 ```
 
-### With Tooltip
+## With Tooltip
 
-Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
+Wrap IconButton in a Tooltip to provide a text description on hover. This is especially important for icon-only buttons since the icon alone may not be self-explanatory for all users.
 
 ```tsx
 <div style={{
@@ -263,9 +235,40 @@ Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
 </div>
 ```
 
-### Action Buttons
+## Circular Variants
+
+IconButton renders as a circular shape by default, making it visually distinct from rectangular text buttons and well-suited for floating action buttons and compact action rows.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  alignItems: 'center'
+}}>
+<div>
+  <h4>Default</h4>
+  <div style={{
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center'
+  }}>
+  <IconButton>
+    <Add />
+  </IconButton>
+  <IconButton variant="outlined">
+    <Edit />
+  </IconButton>
+  <IconButton variant="soft">
+    <Delete />
+  </IconButton>
+</div>
+</div>
+</div>
+```
+
+## Action Buttons
 
-실제 액션을 수행하는 버튼들의 예제입니다.
+A practical example of IconButton used for common CRUD operations with distinct colors signaling the nature of each action.
 
 ```tsx
 <div style={{
@@ -293,69 +296,115 @@ Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
 
 ## Common Use Cases
 
-### Toolbar Actions
+### Table Row Actions
 
 ```tsx
-<div style={{ display: 'flex', gap: '0.5rem' }}>
-  <IconButton onClick={handleAdd} title="Add item">
-    <AddIcon />
-  </IconButton>
-  <IconButton onClick={handleEdit} color="neutral" title="Edit">
-    <EditIcon />
-  </IconButton>
-  <IconButton onClick={handleDelete} color="danger" title="Delete">
-    <DeleteIcon />
-  </IconButton>
-</div>
+import { IconButton, Tooltip } from '@ceed/ads';
+import EditIcon from '@mui/icons-material/Edit';
+import DeleteIcon from '@mui/icons-material/Delete';
+import VisibilityIcon from '@mui/icons-material/Visibility';
+
+function RowActions({ onView, onEdit, onDelete }) {
+  return (
+    <div style={{ display: 'flex', gap: '0.25rem' }}>
+      <Tooltip title="View details">
+        <IconButton size="sm" variant="plain" color="neutral" onClick={onView}>
+          <VisibilityIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip title="Edit">
+        <IconButton size="sm" variant="plain" color="neutral" onClick={onEdit}>
+          <EditIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip title="Delete">
+        <IconButton size="sm" variant="plain" color="danger" onClick={onDelete}>
+          <DeleteIcon />
+        </IconButton>
+      </Tooltip>
+    </div>
+  );
+}
 ```
 
-### Navigation
+### Dialog Close Button
 
 ```tsx
-<IconButton onClick={() => router.back()} variant="outlined">
-  <ArrowBackIcon />
+import CloseIcon from '@mui/icons-material/Close';
+
+<IconButton
+  variant="plain"
+  color="neutral"
+  size="sm"
+  aria-label="Close dialog"
+  onClick={onClose}
+  sx={{ position: 'absolute', top: 8, right: 8 }}
+>
+  <CloseIcon />
 </IconButton>
 ```
 
-### Settings & More Options
+### Navigation Back Button
 
 ```tsx
-<IconButton onClick={handleSettings} color="neutral">
-  <SettingsIcon />
-</IconButton>
-<IconButton onClick={handleMoreOptions}>
-  <MoreVertIcon />
+import ArrowBackIcon from '@mui/icons-material/ArrowBack';
+
+<IconButton
+  variant="outlined"
+  color="neutral"
+  aria-label="Go back"
+  onClick={() => router.back()}
+>
+  <ArrowBackIcon />
 </IconButton>
 ```
 
-### Social Actions
+## Best Practices
+
+1. **Always provide an accessible label.** Since there is no visible text, use `aria-label` or wrap with a Tooltip to describe the action.
 
 ```tsx
-<IconButton onClick={handleLike} color="danger">
-  <FavoriteIcon />
+// ✅ Accessible icon button
+<IconButton aria-label="Delete item" color="danger">
+  <DeleteIcon />
 </IconButton>
-<IconButton onClick={handleShare} color="primary">
-  <ShareIcon />
+
+// ❌ No accessible label
+<IconButton color="danger">
+  <DeleteIcon />
 </IconButton>
 ```
 
-## Best Practices
+2. **Use semantic colors to convey intent.** Match the color to the action's nature: `danger` for destructive actions, `success` for confirmations, `neutral` for general-purpose actions.
 
-1. **명확한 아이콘**: 사용자가 쉽게 이해할 수 있는 명확하고 직관적인 아이콘을 사용하세요.
+```tsx
+// ✅ Color matches the action
+<IconButton color="danger" aria-label="Delete">
+  <DeleteIcon />
+</IconButton>
 
-2. **적절한 크기**: 터치 인터페이스를 고려하여 최소 44px 이상의 터치 영역을 확보하세요.
+// ❌ Misleading color
+<IconButton color="success" aria-label="Delete">
+  <DeleteIcon />
+</IconButton>
+```
 
-3. **접근성**:
-   - `title` 속성이나 `aria-label`을 제공하여 스크린 리더 사용자를 위한 설명을 추가하세요.
-   - Tooltip과 함께 사용하여 기능을 명확히 설명하세요.
+3. **Use the `loading` prop for async operations.** This prevents double-clicks and provides visual feedback during network requests or processing.
+
+```tsx
+// ✅ Shows loading spinner during async action
+<IconButton loading={isSaving} aria-label="Save" onClick={handleSave}>
+  <SaveIcon />
+</IconButton>
+```
 
-4. **일관된 스타일**: 같은 맥락에서는 일관된 variant와 색상을 사용하세요.
+4. **Prefer universally recognized icons.** Choose icons that are widely understood (e.g., trash can for delete, pencil for edit, plus for add). Avoid ambiguous symbols without a Tooltip.
 
-5. **의미 있는 색상**:
-   - 빨간색(danger): 삭제, 취소 등의 위험한 액션
-   - 초록색(success): 저장, 승인 등의 긍정적인 액션
-   - 회색(neutral): 일반적인 액션
+5. **Maintain consistent sizing within the same context.** Use the same `size` and `variant` for all IconButtons in a toolbar or action group to keep the interface clean and predictable.
 
-6. **피드백 제공**: 클릭 시 명확한 피드백을 제공하여 사용자가 액션이 실행되었음을 알 수 있도록 하세요.
+## Accessibility
 
-7. **로딩 상태**: 비동기 작업 시 `loading` prop을 사용하여 사용자에게 진행 상황을 알려주세요.
+- **`aria-label` is essential**: Every IconButton must have either an `aria-label`, `aria-labelledby`, or a wrapping Tooltip with `title` to provide a text alternative for screen readers.
+- **Keyboard interaction**: IconButton is focusable via `Tab` and can be activated with `Enter` or `Space`. Focus indicators are displayed by default.
+- **Disabled state**: When `disabled` is set, the button receives `aria-disabled="true"` and becomes non-interactive. It remains visible in the DOM for screen readers to announce.
+- **Touch targets**: Ensure the rendered button is at least 44x44 pixels for touch accessibility. The `sm` size may need additional padding in touch-heavy interfaces.