# Card

## Introduction

Card 컴포넌트는 관련된 내용과 액션을 하나의 컨테이너로 묶어서 표시하는 UI 요소입니다. 정보를 구조화하고 시각적으로 그룹화하여 사용자가 쉽게 스캔하고 이해할 수 있도록 도와줍니다. 뉴스피드, 제품 목록, 사용자 프로필, 대시보드 위젯 등 다양한 용도로 사용됩니다.

```tsx
<Card {...args} sx={{
  maxWidth: 320
}}>
<CardContent>
  <Typography level="title-md">Card Title</Typography>
  <Typography level="body-sm">이것은 카드의 내용입니다. 여기에 다양한 정보를 표시할 수 있습니다.</Typography>
</CardContent>
</Card>
```

| Field   | Description | Default    |
| ------- | ----------- | ---------- |
| variant | 카드 스타일 변형   | "outlined" |
| color   | 카드 색상       | "neutral"  |
| size    | 카드 크기       | "md"       |

## Usage

```tsx
import { Card, CardContent, CardActions, CardCover, CardOverflow } from '@ceed/cds';

function MyComponent() {
  return (
    <Card sx={{ maxWidth: 320 }}>
      <CardContent>
        <Typography level="title-lg">카드 제목</Typography>
        <Typography level="body-md">카드의 내용이 들어갑니다.</Typography>
      </CardContent>
    </Card>
  );
}
```

## Examples

### Basic Usage

가장 기본적인 카드 사용법입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-lg">기본 카드</Typography>
  <Typography level="body-md">
    이것은 가장 기본적인 카드 형태입니다. 제목과 내용으로 구성되어 있습니다.
  </Typography>
</CardContent>
</Card>
</div>
```

### Variants

다양한 스타일 변형을 제공합니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card variant="solid" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Solid</Typography>
  <Typography level="body-sm">Solid 스타일 카드</Typography>
</CardContent>
</Card>

<Card variant="soft" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Soft</Typography>
  <Typography level="body-sm">Soft 스타일 카드</Typography>
</CardContent>
</Card>

<Card variant="outlined" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Outlined</Typography>
  <Typography level="body-sm">Outlined 스타일 카드</Typography>
</CardContent>
</Card>

<Card variant="plain" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Plain</Typography>
  <Typography level="body-sm">Plain 스타일 카드</Typography>
</CardContent>
</Card>
</div>
```

### Colors

다양한 색상을 적용할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card color="primary" variant="soft" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Primary</Typography>
  <Typography level="body-sm">Primary 색상 카드</Typography>
</CardContent>
</Card>

<Card color="neutral" variant="soft" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Neutral</Typography>
  <Typography level="body-sm">Neutral 색상 카드</Typography>
</CardContent>
</Card>

<Card color="danger" variant="soft" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Danger</Typography>
  <Typography level="body-sm">Danger 색상 카드</Typography>
</CardContent>
</Card>

<Card color="success" variant="soft" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Success</Typography>
  <Typography level="body-sm">Success 색상 카드</Typography>
</CardContent>
</Card>

<Card color="warning" variant="soft" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Warning</Typography>
  <Typography level="body-sm">Warning 색상 카드</Typography>
</CardContent>
</Card>
</div>
```

### Sizes

크기를 조절할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  alignItems: 'flex-start',
  flexWrap: 'wrap'
}}>
<Card size="sm" sx={{
  maxWidth: 250
}}>
<CardContent>
  <Typography level="title-sm">Small</Typography>
  <Typography level="body-xs">작은 크기의 카드입니다.</Typography>
</CardContent>
</Card>

<Card size="md" sx={{
  maxWidth: 300
}}>
<CardContent>
  <Typography level="title-md">Medium</Typography>
  <Typography level="body-sm">중간 크기의 카드입니다.</Typography>
</CardContent>
</Card>

<Card size="lg" sx={{
  maxWidth: 350
}}>
<CardContent>
  <Typography level="title-lg">Large</Typography>
  <Typography level="body-md">큰 크기의 카드입니다.</Typography>
</CardContent>
</Card>
</div>
```

### With Cover

이미지를 배경으로 사용할 수 있는 CardCover 컴포넌트를 활용한 카드입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card sx={{
  maxWidth: 320
}}>
<CardCover>
  <img src="https://images.unsplash.com/photo-1502657877623-f66bf489d236?auto=format&fit=crop&w=320" loading="lazy" alt="Night view" />
</CardCover>
<CardContent>
  <Typography level="body-lg" textColor="#fff">
    Beautiful Night View
  </Typography>
  <Typography level="body-sm" textColor="neutral.300">
    A stunning cityscape at night
  </Typography>
</CardContent>
</Card>

<Card sx={{
  maxWidth: 320
}}>
<CardCover>
  <img src="https://images.unsplash.com/photo-1527549993586-dff825b37782?auto=format&fit=crop&w=320" loading="lazy" alt="Mountain" />
</CardCover>
<CardContent sx={{
  justifyContent: 'flex-end'
}}>
<Typography level="title-lg" textColor="#fff">
  Mountain Peak
</Typography>
<Typography level="body-sm" textColor="neutral.300">
  Majestic mountain landscape
</Typography>
</CardContent>
</Card>
</div>
```

### With Actions

하단에 액션 버튼들을 배치할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card sx={{
  maxWidth: 320
}}>
<CardContent>
  <Typography level="title-lg">게시물</Typography>
  <Typography level="body-md">
    이것은 액션 버튼이 있는 카드입니다. 하단에 다양한 액션을 수행할 수 있는 버튼들이 있습니다.
  </Typography>
</CardContent>
<CardActions>
  <Button variant="soft" size="sm">
    좋아요
  </Button>
  <Button variant="soft" size="sm">
    공유하기
  </Button>
  <Button variant="soft" size="sm">
    더보기
  </Button>
</CardActions>
</Card>

<Card sx={{
  maxWidth: 320
}}>
<CardContent>
  <Typography level="title-lg">설정</Typography>
  <Typography level="body-md">설정을 변경하시겠습니까? 이 작업은 되돌릴 수 없습니다.</Typography>
</CardContent>
<CardActions buttonFlex={1}>
  <Button variant="outlined" color="neutral">
    취소
  </Button>
  <Button variant="solid" color="primary">
    확인
  </Button>
</CardActions>
</Card>
</div>
```

### With Overflow

CardOverflow를 사용하여 카드의 경계를 넘나드는 콘텐츠를 표시할 수 있습니다.

```tsx
<div style={{
  display: 'flex',
  gap: '2rem',
  flexWrap: 'wrap',
  alignItems: 'flex-start'
}}>
{/* CardOverflow 비교 예제 */}
<div>
  <Typography level="body-sm" sx={{
    mb: 2,
    textAlign: 'center'
  }}>
  일반 Card (패딩 있음)
</Typography>
<Card variant="outlined" sx={{
  maxWidth: 280
}}>
<CardContent sx={{
  bgcolor: 'background.level1'
}}>
<img src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?auto=format&fit=crop&w=280" loading="lazy" alt="Profile" style={{
  width: '100%',
  height: 160,
  objectFit: 'cover',
  borderRadius: '4px'
}} />
</CardContent>
<CardContent>
  <Typography level="title-md">John Doe</Typography>
  <Typography level="body-sm">Software Engineer</Typography>
</CardContent>
<CardActions>
  <Button size="sm" variant="soft">
    팔로우
  </Button>
  <Button size="sm" variant="solid">
    메시지
  </Button>
</CardActions>
</Card>
</div>

{/* CardOverflow 사용 예제 */}
<div>
  <Typography level="body-sm" sx={{
    mb: 2,
    textAlign: 'center'
  }}>
  CardOverflow 사용 (패딩 무시)
</Typography>
<Card variant="outlined" sx={{
  maxWidth: 280
}}>
<CardOverflow>
  <AspectRatio ratio="3/4">
    <img src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?auto=format&fit=crop&w=280" loading="lazy" alt="Profile" />
  </AspectRatio>
</CardOverflow>
<CardContent>
  <Typography level="title-md">John Doe</Typography>
  <Typography level="body-sm">Software Engineer</Typography>
</CardContent>
<CardOverflow variant="soft" sx={{
  bgcolor: 'background.level1'
}}>
<CardActions sx={{
  pt: 2,
  pb: 2,
  px: 2
}} buttonFlex={1}>
<Button size="sm" variant="soft">
  팔로우
</Button>
<Button size="sm" variant="solid">
  메시지
</Button>
</CardActions>
</CardOverflow>
</Card>
</div>

{/* 복합 CardOverflow 예제 */}
<div>
  <Typography level="body-sm" sx={{
    mb: 2,
    textAlign: 'center'
  }}>
  다양한 CardOverflow 활용
</Typography>
<Card variant="outlined" sx={{
  maxWidth: 280
}}>
<CardOverflow>
  <AspectRatio ratio="3">
    <div style={{
      background: 'linear-gradient(45deg, #2196F3 30%, #21CBF3 90%)',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      color: 'white'
    }}>
    <Typography level="title-lg" textColor="white">
      HEADER OVERFLOW
    </Typography>
  </div>
</AspectRatio>
</CardOverflow>
<CardContent sx={{
  textAlign: 'center'
}}>
<Typography level="title-md">카드 제목</Typography>
<Typography level="body-sm">
  CardOverflow를 사용하면 카드의 패딩을 무시하고 전체 너비를 활용할 수 있습니다.
</Typography>
</CardContent>
<CardOverflow variant="plain" sx={{
  bgcolor: 'warning.50'
}}>
<Divider inset="context" />
<CardContent sx={{
  py: 1.5
}}>
<Typography level="body-xs" textAlign="center" color="warning">
  ⚠️ 이 영역도 CardOverflow로 만들어졌습니다
</Typography>
</CardContent>
</CardOverflow>
</Card>
</div>
</div>
```

### Interactive Cards

클릭 가능하고 호버 효과가 있는 인터랙티브한 카드들입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card variant="outlined" sx={{
  maxWidth: 320,
  cursor: 'pointer',
  '&:hover': {
    boxShadow: 'md',
    borderColor: 'primary.outlinedHoverBorder'
  }
}} onClick={() => alert('카드를 클릭했습니다!')}>
<CardContent>
  <Typography level="title-md">클릭 가능한 카드</Typography>
  <Typography level="body-sm">이 카드를 클릭하면 액션이 실행됩니다. 호버 효과도 확인해보세요.</Typography>
</CardContent>
</Card>

<Card variant="soft" color="primary" sx={{
  maxWidth: 320,
  cursor: 'pointer',
  transition: 'transform 0.2s',
  '&:hover': {
    transform: 'translateY(-2px)'
  }
}}>
<CardContent>
  <Typography level="title-md">호버 애니메이션</Typography>
  <Typography level="body-sm">마우스를 올리면 카드가 살짝 올라갑니다.</Typography>
</CardContent>
</Card>
</div>
```

### Media Cards

이미지와 함께 사용하는 미디어 카드들입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card sx={{
  maxWidth: 320
}}>
<CardOverflow>
  <AspectRatio ratio="1">
    <img src="https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=320" loading="lazy" alt="Shoes" />
  </AspectRatio>
</CardOverflow>
<CardContent>
  <Typography level="title-lg">운동화</Typography>
  <Typography level="body-md">편안하고 스타일리시한 운동화입니다.</Typography>
  <Typography level="title-lg" sx={{
    color: 'primary.main'
  }}>
  ₩129,000
</Typography>
</CardContent>
<CardActions>
  <Button variant="solid" color="primary" fullWidth>
    구매하기
  </Button>
</CardActions>
</Card>

<Card sx={{
  maxWidth: 320
}}>
<CardOverflow>
  <AspectRatio ratio="1">
    <img src="https://images.unsplash.com/photo-1551963831-b3b1ca40c98e?auto=format&fit=crop&w=320" loading="lazy" alt="Breakfast" />
  </AspectRatio>
</CardOverflow>
<CardContent>
  <div style={{
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'center'
  }}>
  <Typography level="title-lg">맛있는 아침식사</Typography>
  <Button size="sm" variant="plain" sx={{
    p: 0.5
  }}>
  <MoreVertIcon />
</Button>
</div>
<Typography level="body-sm" sx={{
  color: 'text.secondary',
  mb: 1
}}>
<LocationOnIcon sx={{
  fontSize: 16
}} /> 서울, 한국
</Typography>
<Typography level="body-md">건강하고 맛있는 아침 식사로 하루를 시작해보세요.</Typography>
</CardContent>
<CardActions>
  <Button size="sm" variant="plain" startDecorator={<FavoriteIcon />}>
    좋아요
  </Button>
  <Button size="sm" variant="plain" startDecorator={<ShareIcon />}>
    공유
  </Button>
</CardActions>
</Card>
</div>
```

### Complex Layout

복잡한 레이아웃을 가진 소셜 미디어 스타일 카드입니다.

```tsx
<div style={{
  display: 'flex',
  gap: '1rem',
  flexWrap: 'wrap'
}}>
<Card sx={{
  maxWidth: 400
}}>
<CardContent sx={{
  pb: 2
}}>
<div style={{
  display: 'flex',
  alignItems: 'center',
  gap: '1rem',
  marginBottom: '1rem'
}}>
<Avatar size="sm" src="https://i.pravatar.cc/40?img=1" />
<div>
  <Typography level="title-sm">김철수</Typography>
  <Typography level="body-xs" sx={{
    color: 'text.secondary'
  }}>
  5분 전
</Typography>
</div>
</div>
<Typography level="body-md" sx={{
  mb: 2
}}>
오늘 정말 좋은 하루였습니다! 새로운 프로젝트를 시작했는데 너무 흥미진진해요. 팀원들과의 협업도 잘 되고 있고,
앞으로가 기대됩니다.
</Typography>
</CardContent>
<CardOverflow>
  <AspectRatio ratio="2">
    <img src="https://images.unsplash.com/photo-1519389950473-47ba0277781c?auto=format&fit=crop&w=400" loading="lazy" alt="Team work" />
  </AspectRatio>
</CardOverflow>
<CardContent sx={{
  pt: 1
}}>
<div style={{
  display: 'flex',
  alignItems: 'center',
  gap: '1rem'
}}>
<Button size="sm" variant="plain" startDecorator={<FavoriteIcon />}>
  12
</Button>
<Button size="sm" variant="plain" startDecorator={<ShareIcon />}>
  공유
</Button>
<Typography level="body-xs" sx={{
  ml: 'auto',
  color: 'text.secondary'
}}>
댓글 3개
</Typography>
</div>
</CardContent>
</Card>
</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

액션 버튼들을 배치하는 영역입니다.

```tsx
<CardActions>
  <Button>확인</Button>
  <Button>취소</Button>
</CardActions>
```

### CardOverflow

카드의 패딩을 무시하고 전체 너비를 사용하는 영역입니다.

```tsx
<CardOverflow>
  <AspectRatio ratio="3/4">
    <img src="full-width-image.jpg" alt="Full width" />
  </AspectRatio>
</CardOverflow>
```

## 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

1. **적절한 크기**: 카드의 내용에 맞는 적절한 크기를 설정하세요. 너무 크거나 작으면 가독성이 떨어집니다.

2. **일관된 스타일**: 같은 맥락에서 사용되는 카드들은 일관된 variant, color, size를 사용하세요.

3. **명확한 계층구조**: Typography의 level을 활용하여 정보의 중요도에 따른 시각적 계층을 만드세요.

4. **적절한 간격**: 여러 카드를 나열할 때는 적절한 간격을 두어 각각을 구분할 수 있게 하세요.

5. **접근성 고려**:
   - 카드가 클릭 가능한 경우 키보드 탐색을 지원하세요
   - 이미지에는 적절한 alt 텍스트를 제공하세요
   - 색상만으로 정보를 전달하지 마세요

6. **반응형 디자인**: 다양한 화면 크기에서 잘 작동하도록 maxWidth나 responsive 속성을 활용하세요.

7. **로딩 상태**: 데이터를 불러오는 동안에는 Skeleton 컴포넌트를 활용하여 로딩 상태를 표시하세요.

8. **액션 버튼**: CardActions에는 카드와 직접 관련된 주요 액션만 포함하세요. 너무 많은 버튼은 혼란을 야기할 수 있습니다.
