@ceed/cds 1.29.0 → 1.30.0

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.
+The Card component is a UI element that groups related content and actions within a single container. It helps users scan and understand information more easily by structuring and visually grouping it. It is commonly used for news feeds, product lists, user profiles, dashboard widgets, and more.
 
 ```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.
+The most basic way to use a card.
 
 ```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.
+Provides various style variants.
 
 ```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`.
+You can apply various colors.
 
 ```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.
+You can adjust the size.
 
 ```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.
+A card that uses the `CardCover` component to display an image as the background.
 
 ```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.
+You can place action buttons at the bottom.
 
 ```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.
+Use `CardOverflow` to display content that extends beyond the card's padded boundary.
 
 ```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.
+Interactive cards with click behavior and hover effects.
 
 ```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.
+Media cards used with images.
 
 ```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.
+A social-media-style card with a complex layout.
 
 ```tsx
 <div style={{
@@ -632,95 +629,174 @@ Compose multiple sub-components together to build rich, social-media-style card
 </div>
 ```
 
-## Common Use Cases
+## Card Components
+
+Card is composed of several subcomponents:
+
+### Card
 
-### Product Card
+The main card container.
 
 ```tsx
-import { Card, CardContent, CardActions, CardOverflow, AspectRatio, Typography, Button } from '@ceed/cds';
+<Card variant="outlined" color="neutral" size="md">
+  {/* card content */}
+</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
+
+The area that contains the card's primary content.
+
+```tsx
+<CardContent>
+  <Typography level="title-lg">제목</Typography>
+  <Typography level="body-md">내용</Typography>
+</CardContent>
 ```
 
-### Profile Card
+### CardCover
+
+Displays background media or an image that covers the entire card.
 
 ```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
+
+The area used to place action buttons.
+
+```tsx
+<CardActions>
+  <Button>확인</Button>
+  <Button>취소</Button>
+</CardActions>
 ```
 
-### Dashboard Widget
+### CardOverflow
+
+An area that ignores the card's padding and uses the full width.
 
 ```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>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default      | Description                                              |
+| ---------------- | -------------------------------------------------------------- | ------------ | -------------------------------------------------------- |
+| `children`       | `ReactNode`                                                    | -            | Card content (CardContent, CardCover, CardActions, etc.) |
+| `variant`        | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'outlined'` | Visual style                                             |
+| `size`           | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Card size (affects padding)                              |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`  | Color scheme                                             |
+| `orientation`    | `'horizontal' \| 'vertical'`                                   | `'vertical'` | Card layout direction                                    |
+| `invertedColors` | `boolean`                                                      | `false`      | Invert child component colors                            |
+| `sx`             | `SxProps`                                                      | -            | Custom styles                                            |
+
+> **Note**: Card also accepts all Joy UI Card props and Framer Motion props.
+
 ## 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. **Use an appropriate size**: Set a size that fits the card content. If it is too large or too small, readability suffers.
+
+2. **Keep styles consistent**: Cards used in the same context should share consistent `variant`, `color`, and `size` values.
 
-- **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. **Create clear hierarchy**: Use Typography levels to build a visual hierarchy based on the importance of the information.
 
-- **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 proper spacing**: When listing multiple cards, keep enough space between them so each one is clearly distinguishable.
 
-- **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. **Consider accessibility**:
+   - Support keyboard navigation when cards are clickable
+   - Provide appropriate `alt` text for images
+   - Do not rely on color alone to communicate information
 
-- **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. **Use responsive design**: Use `maxWidth` or responsive props so cards work well across different screen sizes.
 
-## Accessibility
+7. **Handle loading states**: Use Skeleton components to represent loading states while data is being fetched.
 
-- 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. **Limit action buttons**: Include only primary actions directly related to the card in `CardActions`. Too many buttons can create confusion.