@ceed/cds 1.22.3 → 1.22.5

package/dist/components/surfaces/Divider.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Divider 컴포넌트는 콘텐츠를 시각적으로 구분하는 선을 그려주는 컴포넌트입니다. Joy UI의 Divider 컴포넌트를 기반으로 하며, Framer Motion 애니메이션 지원이 추가되었습니다. 리스트 항목, 카드 섹션, 폼 영역 등을 구분할 때 사용하여 콘텐츠의 가독성을 향상시킬 수 있습니다.
+Divider is a visual separator component that draws a thin line between content sections. It helps organize layouts by creating clear visual boundaries between groups of related content. Built on Joy UI's Divider component, it supports horizontal and vertical orientations, multiple color options, and Framer Motion animation props for animated transitions.
+
+Dividers are commonly used to separate list items, form sections, card content areas, navigation groups, and dashboard panels. They can optionally contain centered text to label the sections they divide.
 
 ```tsx
 <Box sx={{
@@ -32,19 +34,17 @@ import { Divider } from '@ceed/cds';
 function MyComponent() {
   return (
     <div>
-      <p>첫 번째 콘텐츠</p>
+      <p>First section</p>
       <Divider />
-      <p>두 번째 콘텐츠</p>
+      <p>Second section</p>
     </div>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-가장 기본적인 Divider 사용법입니다.
+The simplest usage of Divider in both horizontal and vertical orientations.
 
 ```tsx
 <Stack spacing={3}>
@@ -81,9 +81,9 @@ function MyComponent() {
 </Stack>
 ```
 
-### Orientations
+## Orientations
 
-구분선의 방향을 설정할 수 있습니다.
+Divider supports `horizontal` (default) and `vertical` orientations. Vertical dividers are useful for separating inline or row-based content.
 
 ```tsx
 <Stack spacing={4}>
@@ -118,9 +118,9 @@ Vertical
 </Stack>
 ```
 
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+Apply semantic colors to dividers for emphasis or to match the surrounding context.
 
 ```tsx
 <Stack spacing={3}>
@@ -140,9 +140,9 @@ Vertical
 </Stack>
 ```
 
-### With Text
+## With Text
 
-구분선 중앙에 텍스트를 배치할 수 있습니다.
+Place text or other elements inside a Divider to create labeled section breaks (e.g., "OR" between login options).
 
 ```tsx
 <Stack spacing={3}>
@@ -172,9 +172,9 @@ Vertical
 </Stack>
 ```
 
-### In Cards
+## In Cards
 
-카드나 패널 내에서 섹션을 구분하는 용도로 사용할 수 있습니다.
+Use Dividers within cards and panels to separate distinct content sections.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -272,9 +272,9 @@ Vertical
 </Stack>
 ```
 
-### List Separators
+## List Separators
 
-목록 항목들을 구분하는 구분선으로 사용할 수 있습니다.
+Dividers work naturally as separators between list items.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -316,9 +316,9 @@ Vertical
 </Sheet>
 ```
 
-### Responsive Orientation
+## Responsive Orientation
 
-화면 크기에 따라 방향을 변경할 수 있습니다.
+Divider orientation can change based on screen size using responsive values, switching from horizontal on mobile to vertical on larger screens.
 
 ```tsx
 <Stack spacing={3}>
@@ -369,9 +369,9 @@ Vertical
 </Stack>
 ```
 
-### With Motion
+## With Motion
 
-Framer Motion 애니메이션을 적용할 수 있습니다.
+Framer Motion animation props can be applied directly to Divider for animated reveal effects.
 
 ```tsx
 <Stack spacing={3}>
@@ -438,9 +438,9 @@ Framer Motion 애니메이션을 적용할 수 있습니다.
 </Stack>
 ```
 
-### Custom Styling
+## Custom Styling
 
-CSS 스타일을 이용해 구분선을 커스터마이징할 수 있습니다.
+Advanced styling techniques including rounded corners, gradients (using Box), and shadow effects.
 
 ```tsx
 <Stack spacing={4}>
@@ -515,248 +515,97 @@ borderRadius: '1px'
 </Stack>
 ```
 
-## Key Props
-
-### orientation
-
-구분선의 방향을 설정합니다.
-
-```tsx
-<Divider orientation="horizontal" /> {/* 기본값 */}
-<Divider orientation="vertical" />
-
-{/* 반응형 방향 */}
-<Divider orientation={{ xs: 'horizontal', sm: 'vertical' }} />
-```
-
-### variant
-
-구분선의 스타일을 설정합니다.
-
-```tsx
-<Divider variant="solid" />    {/* 기본값 - 실선 */}
-<Divider variant="plain" />    {/* 평면 스타일 */}
-<Divider variant="soft" />     {/* 부드러운 스타일 */}
-```
-
-### color
-
-구분선의 색상을 설정합니다.
-
-```tsx
-<Divider color="neutral" />    {/* 기본값 */}
-<Divider color="primary" />
-<Divider color="danger" />
-<Divider color="success" />
-<Divider color="warning" />
-```
-
 ## Common Use Cases
 
-### Navigation Sections
-
-```tsx
-<nav>
-  <Link href="/home">Home</Link>
-  <Link href="/about">About</Link>
-
-  <Divider sx={{ my: 1 }} />
-
-  <Link href="/login">Login</Link>
-  <Link href="/signup">Sign Up</Link>
-</nav>
-```
-
-### Form Sections
+### Form Section Break
 
 ```tsx
-<form>
-  <Stack spacing={2}>
-    <Typography level="title-md">개인 정보</Typography>
-    <FormControl>
-      <FormLabel>이름</FormLabel>
-      <Input />
-    </FormControl>
-    <FormControl>
-      <FormLabel>이메일</FormLabel>
-      <Input type="email" />
-    </FormControl>
-
-    <Divider sx={{ my: 3 }}>추가 정보</Divider>
-
-    <FormControl>
-      <FormLabel>회사명</FormLabel>
-      <Input />
-    </FormControl>
-  </Stack>
-</form>
-```
-
-### Card Content Separation
-
-```tsx
-<Card>
-  <CardContent>
-    <Typography level="title-lg">제품명</Typography>
-    <Typography level="body-md">제품 설명...</Typography>
-
-    <Divider sx={{ my: 2 }} />
-
-    <Stack direction="row" justifyContent="space-between">
-      <Typography level="title-lg" color="primary">
-        ₩99,000
-      </Typography>
-      <Button>장바구니</Button>
-    </Stack>
-  </CardContent>
-</Card>
-```
-
-### List Items
-
-```tsx
-<Stack>
-  {items.map((item, index) => (
-    <React.Fragment key={item.id}>
-      <Box sx={{ p: 2 }}>
-        <Typography level="title-sm">{item.title}</Typography>
-        <Typography level="body-sm">{item.description}</Typography>
-      </Box>
-      {index < items.length - 1 && <Divider />}
-    </React.Fragment>
-  ))}
-</Stack>
-```
-
-### Dashboard Sections
-
-```tsx
-<Sheet variant="outlined" sx={{ p: 3 }}>
-  <Typography level="title-lg">대시보드</Typography>
-
-  <Divider sx={{ my: 2 }} />
-
-  <Grid container spacing={2}>
-    <Grid item xs={12} sm={6}>
-      <StatCard title="사용자" value="1,234" />
-    </Grid>
-    <Grid item xs={12} sm={6}>
-      <StatCard title="매출" value="₩5.6M" />
-    </Grid>
-  </Grid>
-
-  <Divider sx={{ my: 2 }} />
-
-  <Typography level="title-md">최근 활동</Typography>
-  {/* 활동 목록 */}
-</Sheet>
-```
-
-### Modal Content
-
-```tsx
-<Modal open={open}>
-  <Sheet variant="outlined" sx={{ p: 4, borderRadius: 'md' }}>
-    <Typography level="title-lg">설정</Typography>
-
-    <Divider sx={{ my: 2 }} />
+import { Divider, Stack, FormControl, FormLabel, Input, Typography } from '@ceed/cds';
 
+function SectionedForm() {
+  return (
     <Stack spacing={2}>
+      <Typography level="title-md">Personal Info</Typography>
       <FormControl>
-        <FormLabel>알림 설정</FormLabel>
-        <Switch />
+        <FormLabel>Name</FormLabel>
+        <Input />
       </FormControl>
-
       <FormControl>
-        <FormLabel>테마 설정</FormLabel>
-        <Select defaultValue="light">
-          <Option value="light">Light</Option>
-          <Option value="dark">Dark</Option>
-        </Select>
+        <FormLabel>Email</FormLabel>
+        <Input type="email" />
       </FormControl>
-    </Stack>
 
-    <Divider sx={{ my: 3 }} />
+      <Divider sx={{ my: 3 }}>Additional Info</Divider>
 
-    <Stack direction="row" spacing={2} justifyContent="flex-end">
-      <Button variant="outlined" onClick={handleClose}>
-        취소
-      </Button>
-      <Button onClick={handleSave}>저장</Button>
+      <FormControl>
+        <FormLabel>Company</FormLabel>
+        <Input />
+      </FormControl>
     </Stack>
-  </Sheet>
-</Modal>
+  );
+}
 ```
 
-## Best Practices
+### Login Separator
 
-1. **적절한 여백**: 구분선 위아래에 충분한 여백을 두어 콘텐츠가 명확히 구분되도록 하세요.
+```tsx
+import { Divider, Stack, Button, Typography } from '@ceed/cds';
+
+function LoginOptions() {
+  return (
+    <Stack spacing={2} sx={{ maxWidth: 400 }}>
+      <Button fullWidth>Sign in with Email</Button>
 
-2. **의미있는 구분**: 논리적으로 관련 있는 콘텐츠끼리 그룹화하고 구분선으로 섹션을 나누세요.
+      <Divider>or</Divider>
 
-3. **과도한 사용 금지**: 너무 많은 구분선은 인터페이스를 복잡하게 만들 수 있습니다.
+      <Button fullWidth variant="outlined">Sign in with Google</Button>
+      <Button fullWidth variant="outlined">Sign in with GitHub</Button>
+    </Stack>
+  );
+}
+```
 
-4. **수직 구분선 사용**: 수직 구분선을 사용할 때는 부모 컨테이너의 높이를 명시해주세요.
+### Dashboard Section Separator
 
-5. **반응형 고려**: 모바일에서는 수직 구분선이 수평으로 변경되어야 할 수 있습니다.
+```tsx
+import { Divider, Sheet, Typography, Stack } from '@ceed/cds';
 
-6. **색상 일관성**: 프로젝트 전반에서 일관된 구분선 색상과 스타일을 사용하세요.
+function Dashboard() {
+  return (
+    <Sheet variant="outlined" sx={{ p: 3 }}>
+      <Typography level="title-lg">Dashboard</Typography>
 
-7. **접근성**:
-   - 구분선은 단순히 시각적 구분을 위한 것이므로 스크린 리더에서는 무시됩니다
-   - 의미적 구분이 필요한 경우 적절한 HTML 섹션 태그를 함께 사용하세요
+      <Divider sx={{ my: 2 }} />
 
-## Responsive Behavior
+      <Typography level="title-md">Recent Activity</Typography>
+      {/* Activity list */}
 
-Divider는 모든 props에서 반응형 값을 지원합니다:
+      <Divider sx={{ my: 2 }} />
 
-```tsx
-<Divider
-  orientation={{ xs: 'horizontal', md: 'vertical' }}
-  sx={{
-    width: { xs: '100%', md: 'auto' },
-    height: { xs: 'auto', md: 50 },
-    my: { xs: 2, md: 0 },
-    mx: { xs: 0, md: 2 },
-  }}
-/>
+      <Typography level="title-md">Statistics</Typography>
+      {/* Stats content */}
+    </Sheet>
+  );
+}
 ```
 
-## Motion Support
-
-Divider는 Framer Motion을 지원합니다:
+## Best Practices
 
-```tsx
-<Divider
-  initial={{ scaleX: 0 }}
-  animate={{ scaleX: 1 }}
-  transition={{ duration: 0.5 }}
-  sx={{ transformOrigin: 'left' }}
-/>
-
-<Divider
-  orientation="vertical"
-  initial={{ scaleY: 0 }}
-  animate={{ scaleY: 1 }}
-  whileHover={{ scaleY: 1.1 }}
-  transition={{ duration: 0.3 }}
-/>
-```
+- **Use adequate margin around dividers.** Apply `my` (vertical margin) for horizontal dividers and `mx` (horizontal margin) for vertical dividers to give surrounding content breathing room.
 
-## When to Use Divider
+- **Do not overuse dividers.** If content sections are already visually distinct through background colors, spacing, or card boundaries, adding a divider is redundant.
+  - ✔ Use a Divider between items in a flat list
+  - ✘ Add a Divider between cards that already have borders
 
-### ✅ 사용하기 좋은 경우
+- **Set explicit height for vertical dividers.** Vertical dividers require a parent with a defined height, or an explicit `height` value via `sx`, to render correctly.
 
-- **리스트 항목 구분**: 긴 리스트에서 항목들을 명확히 구분할 때
-- **폼 섹션 구분**: 관련 필드들을 그룹으로 나눌 때
-- **카드 내 콘텐츠 구분**: 카드 내에서 다른 성격의 정보를 구분할 때
-- **네비게이션 메뉴**: 메뉴 그룹을 시각적으로 구분할 때
-- **대시보드 섹션**: 대시보드의 위젯이나 섹션을 구분할 때
+- **Use responsive orientation for adaptive layouts.** When a row layout collapses to a column on mobile, switch the divider orientation accordingly using responsive values.
 
-### ❌ 사용하지 않는 것이 좋은 경우
+- **Reserve text-bearing dividers for clear context switches.** Only use dividers with text (e.g., "OR", "Section 2") when the label genuinely helps users understand the content transition.
 
-- **단순한 여백으로 충분한 경우**: 과도한 구분선 사용은 피하세요
-- **이미 다른 구분 요소가 있는 경우**: 색상, 배경, 테두리 등으로 이미 구분되어 있다면 불필요
-- **너무 짧은 콘텐츠**: 한두 줄 정도의 짧은 콘텐츠에는 구분선이 과할 수 있습니다
+## Accessibility
 
-Divider는 콘텐츠의 구조를 명확히 하고 가독성을 향상시키는 유용한 도구입니다. 적절히 사용하면 사용자가 정보를 더 쉽게 이해할 수 있는 인터페이스를 만들 수 있습니다.
+- Divider renders with `role="separator"` by default, which screen readers recognize as a visual boundary. No additional ARIA attributes are needed for purely decorative dividers.
+- When a Divider contains text (e.g., `<Divider>or</Divider>`), the text is readable by screen readers and provides semantic context for the content transition.
+- Dividers are non-interactive and non-focusable, so they do not interfere with keyboard navigation.
+- If you need a semantic section break rather than a visual one, use appropriate HTML elements (`<section>`, `<hr>`) alongside or instead of Divider.