@ceed/cds 1.22.3 → 1.22.5

package/dist/components/surfaces/Card.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Card 컴포넌트는 관련된 내용과 액션을 하나의 컨테이너로 묶어서 표시하는 UI 요소입니다. 정보를 구조화하고 시각적으로 그룹화하여 사용자가 쉽게 스캔하고 이해할 수 있도록 도와줍니다. 뉴스피드, 제품 목록, 사용자 프로필, 대시보드 위젯 등 다양한 용도로 사용됩니다.
+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.
 
 ```tsx
 <Card {...args} sx={{
@@ -24,25 +26,26 @@ Card 컴포넌트는 관련된 내용과 액션을 하나의 컨테이너로 묶
 ## Usage
 
 ```tsx
-import { Card, CardContent, CardActions, CardCover, CardOverflow } from '@ceed/cds';
+import { Card, CardContent, CardActions, Typography, Button } from '@ceed/cds';
 
 function MyComponent() {
   return (
     <Card sx={{ maxWidth: 320 }}>
       <CardContent>
-        <Typography level="title-lg">카드 제목</Typography>
-        <Typography level="body-md">카드의 내용이 들어갑니다.</Typography>
+        <Typography level="title-lg">Card Title</Typography>
+        <Typography level="body-md">Card description goes here.</Typography>
       </CardContent>
+      <CardActions>
+        <Button size="sm">Action</Button>
+      </CardActions>
     </Card>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-가장 기본적인 카드 사용법입니다.
+The simplest form of a Card with a title and description inside CardContent.
 
 ```tsx
 <div style={{
@@ -63,9 +66,9 @@ function MyComponent() {
 </div>
 ```
 
-### Variants
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Four style variants -- `solid`, `soft`, `outlined`, and `plain` -- allow you to control the visual weight of the card.
 
 ```tsx
 <div style={{
@@ -111,9 +114,9 @@ function MyComponent() {
 </div>
 ```
 
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+Apply semantic colors to convey meaning: `primary`, `neutral`, `danger`, `success`, or `warning`.
 
 ```tsx
 <div style={{
@@ -168,9 +171,9 @@ function MyComponent() {
 </div>
 ```
 
-### Sizes
+## Sizes
 
-크기를 조절할 수 있습니다.
+Three sizes are available: `sm`, `md`, and `lg`. The size affects internal padding and typography scaling.
 
 ```tsx
 <div style={{
@@ -208,9 +211,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Cover
+## With Cover
 
-이미지를 배경으로 사용할 수 있는 CardCover 컴포넌트를 활용한 카드입니다.
+Use `CardCover` to place a full-bleed background image behind the card content, creating visually striking hero-style cards.
 
 ```tsx
 <div style={{
@@ -254,9 +257,9 @@ function MyComponent() {
 </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={{
@@ -305,9 +308,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Overflow
+## With Overflow
 
-CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표시할 수 있습니다.
+`CardOverflow` allows content to extend beyond the card's default padding, enabling full-bleed images, colored footers, and edge-to-edge elements.
 
 ```tsx
 <div style={{
@@ -442,9 +445,9 @@ CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표
 </div>
 ```
 
-### Interactive Cards
+## Interactive Cards
 
-클릭 가능하고 호버 효과가 있는 인터랙티브한 카드들입니다.
+Add hover effects and click handlers to create cards that respond to user interaction.
 
 ```tsx
 <div style={{
@@ -482,9 +485,9 @@ CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표
 </div>
 ```
 
-### Media Cards
+## Media Cards
 
-이미지와 함께 사용하는 미디어 카드들입니다.
+Combine `CardOverflow` with `AspectRatio` to create product or media cards with consistent image proportions.
 
 ```tsx
 <div style={{
@@ -559,9 +562,9 @@ CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표
 </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={{
@@ -629,158 +632,95 @@ CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표
 </div>
 ```
 
-## Card Components
-
-Card는 여러 하위 컴포넌트로 구성됩니다:
-
-### Card
-
-메인 카드 컨테이너입니다.
-
-```tsx
-<Card variant="outlined" color="neutral" size="md">
-  {/* 카드 내용 */}
-</Card>
-```
-
-### CardContent
-
-카드의 주요 내용을 담는 영역입니다.
-
-```tsx
-<CardContent>
-  <Typography level="title-lg">제목</Typography>
-  <Typography level="body-md">내용</Typography>
-</CardContent>
-```
-
-### CardCover
-
-카드 전체를 덮는 배경 이미지나 미디어를 표시합니다.
-
-```tsx
-<CardCover>
-  <img src="image.jpg" alt="Cover" />
-</CardCover>
-```
-
-### CardActions
+## Common Use Cases
 
-액션 버튼들을 배치하는 영역입니다.
+### Product Card
 
 ```tsx
-<CardActions>
-  <Button>확인</Button>
-  <Button>취소</Button>
-</CardActions>
-```
-
-### CardOverflow
+import { Card, CardContent, CardActions, CardOverflow, AspectRatio, Typography, Button } from '@ceed/cds';
 
-카드의 패딩을 무시하고 전체 너비를 사용하는 영역입니다.
-
-```tsx
-<CardOverflow>
-  <AspectRatio ratio="3/4">
-    <img src="full-width-image.jpg" alt="Full width" />
-  </AspectRatio>
-</CardOverflow>
+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>
+  );
+}
 ```
 
-## Common Use Cases
-
-### Product Cards
+### Profile Card
 
 ```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
+import { Card, CardContent, CardActions, Typography, Avatar, Button } from '@ceed/cds';
 
-```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>
+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>
+  );
+}
 ```
 
-### News Cards
+### Dashboard Widget
 
 ```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>
-```
+import { Card, CardContent, Typography } from '@ceed/cds';
 
-### 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>
+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>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **적절한 크기**: 카드의 내용에 맞는 적절한 크기를 설정하세요. 너무 크거나 작으면 가독성이 떨어집니다.
-
-2. **일관된 스타일**: 같은 맥락에서 사용되는 카드들은 일관된 variant, color, size를 사용하세요.
+- **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.
 
-3. **명확한 계층구조**: Typography의 level을 활용하여 정보의 중요도에 따른 시각적 계층을 만드세요.
+- **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.
 
-4. **적절한 간격**: 여러 카드를 나열할 때는 적절한 간격을 두어 각각을 구분할 수 있게 하세요.
+- **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
 
-5. **접근성 고려**:
-   - 카드가 클릭 가능한 경우 키보드 탐색을 지원하세요
-   - 이미지에는 적절한 alt 텍스트를 제공하세요
-   - 색상만으로 정보를 전달하지 마세요
+- **Use CardOverflow for full-bleed content.** Instead of negative margins or workarounds, use `CardOverflow` to extend images and colored sections to the card edges.
 
-6. **반응형 디자인**: 다양한 화면 크기에서 잘 작동하도록 maxWidth나 responsive 속성을 활용하세요.
+- **Choose the right variant for the context.** Use `outlined` for general content cards, `soft` for dashboard widgets, and `plain` for minimal or embedded layouts.
 
-7. **로딩 상태**: 데이터를 불러오는 동안에는 Skeleton 컴포넌트를 활용하여 로딩 상태를 표시하세요.
+## Accessibility
 
-8. **액션 버튼**: CardActions에는 카드와 직접 관련된 주요 액션만 포함하세요. 너무 많은 버튼은 혼란을 야기할 수 있습니다.
+- 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.