@ceed/cds 1.28.1 → 1.29.0-next.1

package/dist/components/surfaces/Card.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-Card is a versatile container component that groups related content and actions into a single, cohesive unit. It provides a structured surface for displaying information such as product listings, user profiles, news articles, and dashboard widgets. Cards help users scan and compare content quickly by presenting it in a consistent, visually bounded format.
-
-The Card component is composed of several sub-components -- `CardContent`, `CardActions`, `CardCover`, and `CardOverflow` -- that work together to create rich, flexible layouts. It supports multiple variants, colors, and sizes for full visual customization.
+Card 컴포넌트는 관련된 내용과 액션을 하나의 컨테이너로 묶어서 표시하는 UI 요소입니다. 정보를 구조화하고 시각적으로 그룹화하여 사용자가 쉽게 스캔하고 이해할 수 있도록 도와줍니다. 뉴스피드, 제품 목록, 사용자 프로필, 대시보드 위젯 등 다양한 용도로 사용됩니다.
 
 ```tsx
 <Card {...args} sx={{
@@ -26,26 +24,25 @@ The Card component is composed of several sub-components -- `CardContent`, `Card
 ## Usage
 
 ```tsx
-import { Card, CardContent, CardActions, Typography, Button } from '@ceed/cds';
+import { Card, CardContent, CardActions, CardCover, CardOverflow } from '@ceed/cds';
 
 function MyComponent() {
   return (
     <Card sx={{ maxWidth: 320 }}>
       <CardContent>
-        <Typography level="title-lg">Card Title</Typography>
-        <Typography level="body-md">Card description goes here.</Typography>
+        <Typography level="title-lg">카드 제목</Typography>
+        <Typography level="body-md">카드의 내용이 들어갑니다.</Typography>
       </CardContent>
-      <CardActions>
-        <Button size="sm">Action</Button>
-      </CardActions>
     </Card>
   );
 }
 ```
 
-## Basic
+## Examples
+
+### Basic Usage
 
-The simplest form of a Card with a title and description inside CardContent.
+가장 기본적인 카드 사용법입니다.
 
 ```tsx
 <div style={{
@@ -66,9 +63,9 @@ The simplest form of a Card with a title and description inside CardContent.
 </div>
 ```
 
-## Variants
+### Variants
 
-Four style variants -- `solid`, `soft`, `outlined`, and `plain` -- allow you to control the visual weight of the card.
+다양한 스타일 변형을 제공합니다.
 
 ```tsx
 <div style={{
@@ -114,9 +111,9 @@ Four style variants -- `solid`, `soft`, `outlined`, and `plain` -- allow you to
 </div>
 ```
 
-## Colors
+### Colors
 
-Apply semantic colors to convey meaning: `primary`, `neutral`, `danger`, `success`, or `warning`.
+다양한 색상을 적용할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -171,9 +168,9 @@ Apply semantic colors to convey meaning: `primary`, `neutral`, `danger`, `succes
 </div>
 ```
 
-## Sizes
+### Sizes
 
-Three sizes are available: `sm`, `md`, and `lg`. The size affects internal padding and typography scaling.
+크기를 조절할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -211,9 +208,9 @@ Three sizes are available: `sm`, `md`, and `lg`. The size affects internal paddi
 </div>
 ```
 
-## With Cover
+### With Cover
 
-Use `CardCover` to place a full-bleed background image behind the card content, creating visually striking hero-style cards.
+이미지를 배경으로 사용할 수 있는 CardCover 컴포넌트를 활용한 카드입니다.
 
 ```tsx
 <div style={{
@@ -257,9 +254,9 @@ Use `CardCover` to place a full-bleed background image behind the card content,
 </div>
 ```
 
-## With Actions
+### With Actions
 
-`CardActions` provides a dedicated area at the bottom of the card for buttons and interactive elements. Use the `buttonFlex` prop for equal-width buttons.
+하단에 액션 버튼들을 배치할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -308,9 +305,9 @@ Use `CardCover` to place a full-bleed background image behind the card content,
 </div>
 ```
 
-## With Overflow
+### With Overflow
 
-`CardOverflow` allows content to extend beyond the card's default padding, enabling full-bleed images, colored footers, and edge-to-edge elements.
+CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표시할 수 있습니다.
 
 ```tsx
 <div style={{
@@ -445,9 +442,9 @@ Use `CardCover` to place a full-bleed background image behind the card content,
 </div>
 ```
 
-## Interactive Cards
+### Interactive Cards
 
-Add hover effects and click handlers to create cards that respond to user interaction.
+클릭 가능하고 호버 효과가 있는 인터랙티브한 카드들입니다.
 
 ```tsx
 <div style={{
@@ -485,9 +482,9 @@ Add hover effects and click handlers to create cards that respond to user intera
 </div>
 ```
 
-## Media Cards
+### Media Cards
 
-Combine `CardOverflow` with `AspectRatio` to create product or media cards with consistent image proportions.
+이미지와 함께 사용하는 미디어 카드들입니다.
 
 ```tsx
 <div style={{
@@ -562,9 +559,9 @@ Combine `CardOverflow` with `AspectRatio` to create product or media cards with
 </div>
 ```
 
-## Complex Layout
+### Complex Layout
 
-Compose multiple sub-components together to build rich, social-media-style card layouts with avatars, images, and action bars.
+복잡한 레이아웃을 가진 소셜 미디어 스타일 카드입니다.
 
 ```tsx
 <div style={{
@@ -632,95 +629,158 @@ Compose multiple sub-components together to build rich, social-media-style card
 </div>
 ```
 
-## Common Use Cases
+## Card Components
+
+Card는 여러 하위 컴포넌트로 구성됩니다:
+
+### Card
 
-### Product Card
+메인 카드 컨테이너입니다.
 
 ```tsx
-import { Card, CardContent, CardActions, CardOverflow, AspectRatio, Typography, Button } from '@ceed/cds';
+<Card variant="outlined" color="neutral" size="md">
+  {/* 카드 내용 */}
+</Card>
+```
 
-function ProductCard({ name, description, price, imageUrl }) {
-  return (
-    <Card sx={{ maxWidth: 320 }}>
-      <CardOverflow>
-        <AspectRatio ratio="1">
-          <img src={imageUrl} alt={name} loading="lazy" />
-        </AspectRatio>
-      </CardOverflow>
-      <CardContent>
-        <Typography level="title-lg">{name}</Typography>
-        <Typography level="body-md">{description}</Typography>
-        <Typography level="title-lg" color="primary">
-          {price}
-        </Typography>
-      </CardContent>
-      <CardActions>
-        <Button variant="solid" fullWidth>
-          Add to Cart
-        </Button>
-      </CardActions>
-    </Card>
-  );
-}
+### CardContent
+
+카드의 주요 내용을 담는 영역입니다.
+
+```tsx
+<CardContent>
+  <Typography level="title-lg">제목</Typography>
+  <Typography level="body-md">내용</Typography>
+</CardContent>
 ```
 
-### Profile Card
+### CardCover
+
+카드 전체를 덮는 배경 이미지나 미디어를 표시합니다.
 
 ```tsx
-import { Card, CardContent, CardActions, Typography, Avatar, Button } from '@ceed/cds';
+<CardCover>
+  <img src="image.jpg" alt="Cover" />
+</CardCover>
+```
 
-function ProfileCard({ name, role, avatarUrl }) {
-  return (
-    <Card sx={{ maxWidth: 320 }}>
-      <CardContent sx={{ alignItems: 'center', textAlign: 'center' }}>
-        <Avatar size="lg" src={avatarUrl} />
-        <Typography level="title-lg">{name}</Typography>
-        <Typography level="body-sm">{role}</Typography>
-      </CardContent>
-      <CardActions>
-        <Button size="sm" variant="soft">Follow</Button>
-        <Button size="sm" variant="solid">Message</Button>
-      </CardActions>
-    </Card>
-  );
-}
+### CardActions
+
+액션 버튼들을 배치하는 영역입니다.
+
+```tsx
+<CardActions>
+  <Button>확인</Button>
+  <Button>취소</Button>
+</CardActions>
 ```
 
-### Dashboard Widget
+### CardOverflow
+
+카드의 패딩을 무시하고 전체 너비를 사용하는 영역입니다.
 
 ```tsx
-import { Card, CardContent, Typography } from '@ceed/cds';
+<CardOverflow>
+  <AspectRatio ratio="3/4">
+    <img src="full-width-image.jpg" alt="Full width" />
+  </AspectRatio>
+</CardOverflow>
+```
 
-function DashboardWidget({ label, value, trend }) {
-  return (
-    <Card variant="soft" color="primary">
-      <CardContent>
-        <Typography level="body-sm">{label}</Typography>
-        <Typography level="h2">{value}</Typography>
-        <Typography level="body-xs">{trend}</Typography>
-      </CardContent>
-    </Card>
-  );
-}
+## Common Use Cases
+
+### Product Cards
+
+```tsx
+<Card sx={{ maxWidth: 320 }}>
+  <CardOverflow>
+    <AspectRatio ratio="1">
+      <img src="product.jpg" alt="Product" />
+    </AspectRatio>
+  </CardOverflow>
+  <CardContent>
+    <Typography level="title-lg">제품명</Typography>
+    <Typography level="body-md">제품 설명</Typography>
+    <Typography level="title-lg" color="primary">
+      ₩199,000
+    </Typography>
+  </CardContent>
+  <CardActions>
+    <Button variant="solid" fullWidth>
+      구매하기
+    </Button>
+  </CardActions>
+</Card>
+```
+
+### User Profile Cards
+
+```tsx
+<Card sx={{ maxWidth: 320 }}>
+  <CardContent sx={{ alignItems: 'center', textAlign: 'center' }}>
+    <Avatar size="lg" src="profile.jpg" />
+    <Typography level="title-lg">사용자 이름</Typography>
+    <Typography level="body-sm">직책</Typography>
+  </CardContent>
+  <CardActions>
+    <Button size="sm" variant="soft">
+      팔로우
+    </Button>
+    <Button size="sm" variant="solid">
+      메시지
+    </Button>
+  </CardActions>
+</Card>
+```
+
+### News Cards
+
+```tsx
+<Card sx={{ maxWidth: 400 }}>
+  <CardOverflow>
+    <AspectRatio ratio="3/2">
+      <img src="news.jpg" alt="News" />
+    </AspectRatio>
+  </CardOverflow>
+  <CardContent>
+    <Typography level="body-xs" color="neutral">
+      뉴스 · 2시간 전
+    </Typography>
+    <Typography level="title-md">뉴스 제목</Typography>
+    <Typography level="body-sm">뉴스 요약...</Typography>
+  </CardContent>
+</Card>
+```
+
+### Dashboard Widget Cards
+
+```tsx
+<Card variant="soft" color="primary">
+  <CardContent>
+    <Typography level="body-sm">총 사용자</Typography>
+    <Typography level="h2">1,234</Typography>
+    <Typography level="body-xs">+12% from last month</Typography>
+  </CardContent>
+</Card>
 ```
 
 ## Best Practices
 
-- **Use consistent card sizing.** When displaying cards in a grid or list, ensure they share the same `maxWidth`, variant, and size to create a uniform appearance.
+1. **적절한 크기**: 카드의 내용에 맞는 적절한 크기를 설정하세요. 너무 크거나 작으면 가독성이 떨어집니다.
+
+2. **일관된 스타일**: 같은 맥락에서 사용되는 카드들은 일관된 variant, color, size를 사용하세요.
 
-- **Limit actions per card.** Place only the most relevant actions (1-3 buttons) in `CardActions`. Too many options overwhelm users and dilute the card's purpose.
+3. **명확한 계층구조**: Typography의 level을 활용하여 정보의 중요도에 따른 시각적 계층을 만드세요.
 
-- **Provide image alt text.** Always include descriptive `alt` attributes on images inside `CardCover` and `CardOverflow` for screen readers.
-  - ✔ `alt="Red running shoes, side view"`
-  - ✘ `alt="image"` or missing alt
+4. **적절한 간격**: 여러 카드를 나열할 때는 적절한 간격을 두어 각각을 구분할 수 있게 하세요.
 
-- **Use CardOverflow for full-bleed content.** Instead of negative margins or workarounds, use `CardOverflow` to extend images and colored sections to the card edges.
+5. **접근성 고려**:
+   - 카드가 클릭 가능한 경우 키보드 탐색을 지원하세요
+   - 이미지에는 적절한 alt 텍스트를 제공하세요
+   - 색상만으로 정보를 전달하지 마세요
 
-- **Choose the right variant for the context.** Use `outlined` for general content cards, `soft` for dashboard widgets, and `plain` for minimal or embedded layouts.
+6. **반응형 디자인**: 다양한 화면 크기에서 잘 작동하도록 maxWidth나 responsive 속성을 활용하세요.
 
-## Accessibility
+7. **로딩 상태**: 데이터를 불러오는 동안에는 Skeleton 컴포넌트를 활용하여 로딩 상태를 표시하세요.
 
-- When a card is clickable, wrap the primary action in a link or button element rather than making the entire card a click target. This ensures keyboard and screen reader users can identify the interactive element.
-- Provide meaningful `alt` text for all images. Decorative images should use `alt=""` to be skipped by screen readers.
-- Use proper heading levels inside cards (`level="title-lg"`, `level="title-md"`) to maintain the document's heading hierarchy.
-- Ensure sufficient color contrast between card backgrounds and text, especially when using `variant="solid"` with colored themes.
+8. **액션 버튼**: CardActions에는 카드와 직접 관련된 주요 액션만 포함하세요. 너무 많은 버튼은 혼란을 야기할 수 있습니다.