# Card

Bề mặt có viền để nhóm nội dung liên quan. Dùng radius-container và một viền; không đổ bóng (đổ bóng chỉ dành cho các lớp nổi).

**Phụ thuộc:** npm: 0 trực tiếp, 1 tổng; registry: 2 trực tiếp, 2 tổng.

## Cách dùng

### Khi nào dùng

- Nhóm nội dung liên quan về một chủ đề, chẳng hạn một dự án với title, một mô tả ngắn và các action của nó.
- Cho nhóm một header, một phần thân và tối đa một hành động chính, ở footer.

### Khi nào không dùng

- Một dòng chữ hoặc một giá trị đơn. Dùng một hàng danh sách.
- Nội dung đã nằm trong một card. Dùng divider hoặc spacing.
- Một bề mặt đóng vai một button. Card không phải button; để cả card nhấn được, trải một link phủ lên nó và không đặt button hoặc link nào khác bên trong.

## Ví dụ

### Mặc định

```tsx
<Card>
  <CardHeader>
    <CardTitle>Dự án</CardTitle>
    <CardDescription>Chỉnh sửa lần cuối 2 giờ trước.</CardDescription>
  </CardHeader>
  <CardContent>Token thiết kế và thành phần cho vibe coder.</CardContent>
  <CardFooter>
    <Button variant="secondary">Hủy</Button>
    <Button>Lưu</Button>
  </CardFooter>
</Card>
```

### Có action

```tsx
<Card>
  <CardHeader>
    <CardTitle>Dự án</CardTitle>
    <CardDescription>Chỉnh sửa lần cuối 2 giờ trước.</CardDescription>
    <CardAction>
      <Button variant="secondary" size="sm">Chia sẻ</Button>
    </CardAction>
  </CardHeader>
  <CardContent>Token thiết kế và thành phần cho vibe coder.</CardContent>
</Card>
```

## Nên và không nên

### Nên

- Dùng Card để nhóm nội dung liên quan. Cho nó tối đa một action chính, ở footer.
- Để cả card nhấn được, trải một link phủ lên nó, dùng color-overlay-hover khi hover và hiện focus ring trên card. Rồi đừng đặt button nào khác bên trong.
- Dùng viền, không dùng đổ bóng. Đổ bóng dành cho menu, popover và dialog.

### Không nên

- Đừng đặt card trong card. Dùng một divider (color-border) hoặc spacing.
- Đừng dùng card cho một dòng chữ hoặc một giá trị đơn. Dùng một hàng danh sách.
- Đừng chỉnh nền qua className. Nếu màu bề mặt sai, mở một issue thay vì ghi đè.

## Props

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `header` | không | Header tùy chọn: title, description và một CardAction tùy chọn. |
| `content` | không | Nội dung thân chính. |
| `footer` | không | Action hoặc meta ở footer, tùy chọn. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Bề mặt card: viền, radius-container, background-surface. |
| `header` | Khối trên cho title và description. Thành lưới hai cột khi chứa một action. |
| `action` | Slot tùy chọn ở góc trên bên phải của header (một button hoặc menu), cạnh title và description. |
| `title` | Nhãn chính của card. |
| `description` | Chữ bổ trợ dưới title. |
| `content` | Thân chính của card. |
| `footer` | Hàng action hoặc meta ở dưới cùng. |

## Khả năng truy cập

Role: `generic`

- Root là một div thuần, không có role. Nếu card cần được thông báo như một group, thêm role="group" và aria-labelledby trỏ tới CardTitle tại nơi gọi.
- Card không tự tương tác. Đặt button và link bên trong; đừng biến cả card thành một button.
- Nếu cả card nhấn được, dùng một link trải phủ lên card (một ::after trên link với absolute inset-0; root là relative) và không có button hoặc link nào khác bên trong.
- Title nên là cấp heading khớp outline của trang (h2 hoặc h3 trong hầu hết các view).

## Cài đặt

```bash
npx werewolf-ui add card
```

Chạy `npx werewolf-ui init` một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem [Cài đặt](https://www.werewolf-ui.dev/vi/docs/installation.md) để biết yêu cầu và cách cài qua registry.