@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/brand-icon/AGENTS.md

@@ -0,0 +1,82 @@
+# BrandIcon
+
+> 아이콘 & 아바타 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+연동 앱의 원래 색 로고. 앱 연결 줄, 연동 목록에서 써요. 버튼 안에 넣어도 버튼 아이콘 크기 규칙에 줄어들지 않고 size 그대로 보여요.
+
+```tsx
+import { BrandIcon, BRAND_NAMES } from '@iamfiro/design'
+```
+
+## API
+
+### BrandIcon
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `name` (필수) | `'gmail' \| 'slack' \| 'clickup' \| 'figma' \| 'github' \| 'hubspot' \| 'notion' \| 'google-calendar' \| 'google' \| 'apple'` |  | 앱. |
+| `size` | `number` | `18` | 가로·세로(px). |
+| `title` | `string` |  | 접근성 이름. 없으면 장식으로 취급해요(옆에 글자가 있을 때). |
+| `className` | `string` |  | svg에 붙일 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 로고 목록
+
+지금 들어 있는 로고 10개(Gmail, Slack, ClickUp, Figma, GitHub, HubSpot, Notion, Google Calendar, Google, Apple). Apple은 한 색 로고라 글자색을 따라요. 새 앱은 BrandIcon.tsx의 MARKS에 추가해요.
+
+```tsx
+import { BRAND_NAMES, BrandIcon, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={8}>
+      {BRAND_NAMES.map((name) => (
+        <Stack key={name} gap={2} align="center">
+          <BrandIcon name={name} size={28} title={name} />
+          <Text variant="caption" tone="secondary">
+            {name}
+          </Text>
+        </Stack>
+      ))}
+    </Inline>
+  )
+}
+```
+
+### 앱 연결
+
+로고 몇 개 + 글자를 ghost 버튼의 icon으로. ChatComposer footer에 쓰는 모양이에요.
+
+```tsx
+import { BrandIcon, Button, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={3}>
+      <Button
+        variant="ghost"
+        size="sm"
+        icon={
+          <Inline gap={1} wrap={false}>
+            <BrandIcon name="gmail" size={16} />
+            <BrandIcon name="slack" size={16} />
+            <BrandIcon name="clickup" size={16} />
+            <BrandIcon name="notion" size={16} />
+            <BrandIcon name="google-calendar" size={16} />
+            <BrandIcon name="hubspot" size={16} />
+          </Inline>
+        }
+      >
+        앱 연결
+      </Button>
+      <Button icon={<BrandIcon name="figma" size={16} />}>Figma에서 가져오기</Button>
+      <Button variant="primary" icon={<BrandIcon name="github" size={16} />}>
+        GitHub로 계속하기
+      </Button>
+    </Inline>
+  )
+}
+```

package/agents/breadcrumb/AGENTS.md

@@ -0,0 +1,133 @@
+# Breadcrumb
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+지금 페이지가 어디에 있는지 보여 주는 경로. 마지막 항목이 현재 페이지(aria-current="page")이고, 나머지는 위 단계로 돌아가는 링크예요. 길어지면 다음 줄로 자연스럽게 넘어가요.
+
+```tsx
+import { Breadcrumb, type BreadcrumbItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 사이드바 머리 = `SelectorButton`(앱 이름) + 검색 · 접기 아이콘 버튼. 접으면(`sidebarCollapsed`) 헤더 왼쪽에 여는 버튼이 나타난다. 본문 헤더 = 왼쪽 `Breadcrumb`, 오른쪽 작은 ghost 액션.
+
+## API
+
+### Breadcrumb
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` (필수) | `BreadcrumbItem[]` |  | 경로. 마지막 항목이 현재 페이지예요. |
+| `separator` | `ReactNode` | `<ChevronRight />` | 항목 사이 구분 기호. |
+| `className` | `string` |  | 루트 <nav>에 붙일 클래스. |
+
+### BreadcrumbItem
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 표시 이름. |
+| `href` | `string` |  | 링크 주소. |
+| `onClick` | `() => void` |  | 클릭 처리(라우터 이동 등). 있으면 기본 링크 이동을 막아요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+items 배열만 넘기면 돼요. 링크 항목에는 href나 onClick을 주세요(onClick이 있으면 기본 이동을 막아요).
+
+```tsx
+import { Breadcrumb, toast } from '@iamfiro/design'
+
+// 실제 앱에서는 href를 주거나, onClick에서 라우터로 이동해요.
+const go = (label: string) => () => toast(`‘${label}’ 페이지로 이동`)
+
+export default function Example() {
+  return (
+    <Breadcrumb
+      items={[
+        { label: '홈', onClick: go('홈') },
+        { label: '프로젝트', onClick: go('프로젝트') },
+        { label: '웹사이트 리뉴얼', onClick: go('웹사이트 리뉴얼') },
+        { label: '디자인 검토' },
+      ]}
+    />
+  )
+}
+```
+
+### 폴더 탐색
+
+경로를 상태로 들고, 위 단계를 누르면 그 지점까지 잘라 내요.
+
+```tsx
+import { useState } from 'react'
+import { Folder } from 'lucide-react'
+import { Button, Text, Breadcrumb } from '@iamfiro/design'
+
+const FOLDERS: Record<string, string[]> = {
+  '내 드라이브': ['디자인', '마케팅'],
+  디자인: ['2026', '아카이브'],
+  '2026': ['10월 리뷰', '11월 리뷰'],
+  마케팅: ['연말 캠페인'],
+}
+
+export default function Example() {
+  const [path, setPath] = useState(['내 드라이브', '디자인'])
+  const children = FOLDERS[path[path.length - 1]] ?? []
+
+  return (
+    <div style={{ display: 'grid', gap: 16, width: 360 }}>
+      <Breadcrumb items={path.map((label, i) => ({ label, onClick: () => setPath(path.slice(0, i + 1)) }))} />
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+        {children.map((name) => (
+          <Button key={name} size="sm" icon={<Folder />} onClick={() => setPath([...path, name])}>
+            {name}
+          </Button>
+        ))}
+        {!children.length && (
+          <Text variant="body-sm" tone="tertiary">
+            하위 폴더가 없어요.
+          </Text>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+### 구분자 · 아이콘
+
+separator로 구분 기호를 바꾸고, label에 아이콘을 함께 넣을 수 있어요. href와 onClick이 모두 없는 항목은 링크가 아닌 글자로 보여요.
+
+```tsx
+import { House, Slash } from 'lucide-react'
+import { Breadcrumb, toast } from '@iamfiro/design'
+
+const go = (label: string) => () => toast(`‘${label}’ 페이지로 이동`)
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 20 }}>
+      <Breadcrumb
+        separator={<Slash />}
+        items={[
+          {
+            label: (
+              <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6 }}>
+                <House size={14} />홈
+              </span>
+            ),
+            onClick: go('홈'),
+          },
+          { label: '설정', onClick: go('설정') },
+          { label: '알림' },
+        ]}
+      />
+      <Breadcrumb separator="·" items={[{ label: '도움말', onClick: go('도움말') }, { label: '결제' }, { label: '환불 정책' }]} />
+    </div>
+  )
+}
+```

package/agents/button/AGENTS.md

@@ -0,0 +1,195 @@
+# Button
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+동작을 실행하는 기본 버튼. 화면에서 가장 중요한 동작 하나에 primary를, 나머지는 secondary · ghost를 써요. 클릭은 누른 버튼을 놓는 순간 확정되고, 누른 채 밖으로 나가면 취소돼요.
+
+```tsx
+import { Button } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 단축키가 있는 버튼은 `Button shortcut`(힌트만) + `hotkey`(듣기: 입력 중 글자 키 · IME 조합 · 비활성은 무시). 여러 개는 `ActionBar`(흰 바탕 + 위 그림자, `pending`이면 fieldset으로 한꺼번에 잠금).
+- 글 속 변경 내용(추적된 변경)은 `InlineDiff`: 삭제 = 빨간 취소선 + `--danger-soft`, 추가 = 초록 + `--success-soft`, 진짜 `<del>` · `<ins>` + 화면 읽기 "삭제" · "추가". 검토(수락 · 거절)는 `reviewable`, 툴바(남은 개수 `CountBadge variant="soft" tone="success"`, 이전 · 다음 `Button iconOnly`, 모두 거절 · 모두 수락)는 `useDiffReview` 상태를 함께 써서 조립한다. 검토 카드는 `CardFrame header`(회색 판 위 아이콘 + 문서 이름) 안에 `Card raised` — 회색 Box를 카드 안 제목줄로 넣으면 입력창처럼 보인다. 본문 줄 간격은 넉넉하게(위아래 줄의 색 배경이 닿지 않게). 모두 수락 · 거절은 확인 대신 `toast.undo`. 두 문자열 비교는 `diffWords`, 결과 글은 `applyDiffDecisions`.
+
+## API
+
+### Button
+
+나머지 props는 <button>에 그대로 전달돼요. type 기본값은 "button"이에요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `'primary' \| 'accent' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'secondary'` | 버튼 스타일. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 28 / 34 / 40px. |
+| `icon` | `ReactNode` |  | 글자 앞 아이콘. |
+| `iconRight` | `ReactNode` |  | 글자 뒤 아이콘. |
+| `iconOnly` | `boolean` |  | icon만 보이는 정사각형 버튼. children은 그리지 않으니 aria-label을 넣어 주세요. |
+| `loading` | `boolean` |  | icon 자리에 스피너를 보이고 클릭을 막아요(aria-busy). |
+| `disabled` | `boolean` |  | 비활성. |
+| `block` | `boolean` |  | 너비 100%. |
+| `shortcut` | `string \| string[]` |  | 글자 뒤의 단축키 힌트(Kbd 키 이름: "A", ["mod", "enter"]). 버튼 색에 맞춘 납작한 키캡으로 보여요. 보여 주기만 하고, 듣는 건 hotkey. |
+| `hotkey` | `boolean` |  | shortcut을 페이지 어디서 눌러도 버튼을 눌러요(잠깐 눌린 모양 + click). 입력 칸에서 글자 키 · IME 조합 중 · 길게 누른 반복 입력은 무시하고(⌘/Ctrl/Alt 조합은 동작), disabled · loading · 비활성 fieldset(ActionBar pending) · inert 안이면 무시해요. 한글 자판이어도 같은 자리의 키로 동작해요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 종류
+
+primary는 검정 단색, accent는 파랑, secondary는 흰 바탕 + 옅은 윤곽, ghost는 글자만, danger는 연한 빨강이에요.
+
+```tsx
+import { Trash2 } from 'lucide-react'
+import { Button } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+      <Button variant="primary">변경사항 저장</Button>
+      <Button variant="accent">업그레이드</Button>
+      <Button variant="secondary">취소</Button>
+      <Button variant="outline">내보내기</Button>
+      <Button variant="ghost">건너뛰기</Button>
+      <Button variant="danger" icon={<Trash2 />}>
+        삭제
+      </Button>
+    </div>
+  )
+}
+```
+
+### 크기
+
+sm · md · lg는 높이 28 / 34 / 40px. iconOnly 버튼은 높이와 같은 정사각형이 돼요.
+
+```tsx
+import { Plus } from 'lucide-react'
+import { Button } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 12, justifyItems: 'start' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <Button size="sm" variant="primary">
+          작게
+        </Button>
+        <Button variant="primary">기본</Button>
+        <Button size="lg" variant="primary">
+          크게
+        </Button>
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <Button size="sm" iconOnly icon={<Plus />} aria-label="추가" />
+        <Button iconOnly icon={<Plus />} aria-label="추가" />
+        <Button size="lg" iconOnly icon={<Plus />} aria-label="추가" />
+      </div>
+    </div>
+  )
+}
+```
+
+### 아이콘
+
+icon은 글자 앞, iconRight는 글자 뒤에 붙어요. 아이콘만 있는 버튼은 aria-label을 꼭 넣고 Tooltip으로 설명을 보여 주세요.
+
+```tsx
+import { ArrowRight, Download, MoreHorizontal, Pencil, Share2 } from 'lucide-react'
+import { Button, Tooltip } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 8 }}>
+      <Button icon={<Download />}>다운로드</Button>
+      <Button variant="primary" iconRight={<ArrowRight />}>
+        계속하기
+      </Button>
+      <Tooltip content="수정">
+        <Button variant="ghost" iconOnly icon={<Pencil />} aria-label="수정" />
+      </Tooltip>
+      <Tooltip content="공유">
+        <Button variant="ghost" iconOnly icon={<Share2 />} aria-label="공유" />
+      </Tooltip>
+      <Tooltip content="더보기">
+        <Button variant="ghost" iconOnly icon={<MoreHorizontal />} aria-label="더보기" />
+      </Tooltip>
+    </div>
+  )
+}
+```
+
+### 로딩 · 비활성 · 꽉 채우기
+
+loading이면 아이콘이 스피너로 바뀌고 클릭이 막혀요. block은 부모 너비를 채워요.
+
+```tsx
+import { useState } from 'react'
+import { Upload } from 'lucide-react'
+import { Button } from '@iamfiro/design'
+
+export default function Example() {
+  const [uploading, setUploading] = useState(false)
+
+  const upload = () => {
+    setUploading(true)
+    setTimeout(() => setUploading(false), 2000)
+  }
+
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 320 }}>
+      <div style={{ display: 'flex', gap: 8 }}>
+        <Button variant="primary" icon={<Upload />} loading={uploading} onClick={upload}>
+          {uploading ? '업로드 중' : '파일 업로드'}
+        </Button>
+        <Button disabled>보관하기</Button>
+      </div>
+      <Button variant="primary" size="lg" block>
+        가입하기
+      </Button>
+    </div>
+  )
+}
+```
+
+### 단축키 (shortcut · hotkey)
+
+shortcut은 글자 뒤에 키캡 힌트를(글자와 6px), hotkey는 그 키로 버튼을 눌러요. 입력 칸 안에선 글자 키를 무시하고 ⌘/Ctrl 조합만 받아요. 비활성 버튼은 단축키도 무시해요. 여러 개를 모아 두는 바는 ActionBar.
+
+```tsx
+import { useState } from 'react'
+import { Check, Send } from 'lucide-react'
+import { Button, Inline, Input, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [log, setLog] = useState('A · S를 누르거나 버튼을 눌러 보세요.')
+  return (
+    <Stack gap={4} align="start">
+      <Inline gap={2}>
+        <Button variant="primary" icon={<Check />} shortcut="A" hotkey onClick={() => setLog('승인했어요 (A)')}>
+          승인
+        </Button>
+        <Button shortcut="S" hotkey onClick={() => setLog('건너뛰었어요 (S)')}>
+          건너뛰기
+        </Button>
+        <Button variant="ghost" shortcut="D" disabled>
+          보류
+        </Button>
+        <Button variant="danger" shortcut={['shift', 'R']} hotkey onClick={() => setLog('거절했어요 (Shift + R)')}>
+          거절
+        </Button>
+      </Inline>
+      {/* 입력 칸 안에서는 글자 단축키가 무시되고, ⌘/Ctrl 조합은 그대로 동작해요. */}
+      <Inline gap={2} wrap={false}>
+        <Input placeholder="여기서 A를 눌러도 승인되지 않아요" wrapperStyle={{ width: 280 }} />
+        <Button variant="accent" size="sm" icon={<Send />} shortcut={['mod', 'enter']} hotkey onClick={() => setLog('보냈어요 (⌘/Ctrl + Enter)')}>
+          보내기
+        </Button>
+      </Inline>
+      <Text variant="body-sm" tone="secondary" aria-live="polite">
+        {log}
+      </Text>
+    </Stack>
+  )
+}
+```

package/agents/card/AGENTS.md

@@ -0,0 +1,141 @@
+# Card
+
+> 컨테이너 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+관련 내용을 한 덩어리로 묶는 흰 표면. 테두리 대신 아주 옅은 윤곽과 그림자로 구분해요. Header · Body · Footer · Media를 조합하고, interactive로 클릭 가능한 카드를 만들어요.
+
+```tsx
+import { Card, CardHeader, CardBody, CardFooter, CardMedia } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 차트: 시리즈 색은 `--chart-1…6`을 순서대로, 그리드는 `--chart-grid`로 아주 옅게(세로선·축선 없음). 범례·툴팁의 색 표시는 `ColorDot`, 툴팁은 `Card raised` + `Separator`로 조립. 축·툴팁·범례·호버/키보드는 `components/Chart/`의 공용 조각(`ChartTooltip`, `ChartLegend`, `useChartInteraction`)을 쓴다. → `LineChart` · `BarChart` · `PieChart` · `Sparkbar`
+- 카드: `Card` 하나로. 테두리 대신 `default`(옅은 윤곽+그림자) · `raised` · `plain`(여백만). 클릭 카드는 `interactive`(떠오름+눌림). 선택 카드는 테두리 링 대신 오른쪽 위 체크(빈 원 → 파랗게 채움) + 아이콘 파란 톤.
+- 파운데이션보다 **이미 있는 조합 컴포넌트를 먼저** 쓴다: 카드 제목줄은 `CardHeader`(오른쪽은 `actions`), 행 목록은 `List` + `ListItem`(`leading` · `trailing`). Stack/Inline으로 같은 것을 다시 짜지 않는다. List를 카드 안에 넣을 땐 `Card padding="sm"`(12px)이면 행 안쪽 여백(12px)과 왼쪽 끝이 맞는다.
+- 읽기 전용 단계 타임라인(계획 · 활동 기록 · 승인 흐름)은 `StepList`(`ol`, 마커 + 연결선, `meta` 시간, 아래 내용엔 Collapsible inline). 번호 원은 `StatusIcon number`(`persistNumber`면 모든 상태에서 번호). 사용자가 체크하는 목록은 `ProgressTracker`. 카드 아래 상태 띠는 `CardFooter band`.
+- 카드를 회색 판으로 한 번 더 감싸고 맥락(몇 단계 · 어떤 도구 · 진행 상태)을 카드 바깥에 둘 땐 `CardFrame`(`header` 캡션 / `footer` 상태 줄, `--surface-active` 판 + 4px 테두리 + 바깥 모서리 20px로 카드 16px와 겹치지 않게). 카드 안쪽 아래 띠는 여전히 `CardFooter band`.
+- 글 속 변경 내용(추적된 변경)은 `InlineDiff`: 삭제 = 빨간 취소선 + `--danger-soft`, 추가 = 초록 + `--success-soft`, 진짜 `<del>` · `<ins>` + 화면 읽기 "삭제" · "추가". 검토(수락 · 거절)는 `reviewable`, 툴바(남은 개수 `CountBadge variant="soft" tone="success"`, 이전 · 다음 `Button iconOnly`, 모두 거절 · 모두 수락)는 `useDiffReview` 상태를 함께 써서 조립한다. 검토 카드는 `CardFrame header`(회색 판 위 아이콘 + 문서 이름) 안에 `Card raised` — 회색 Box를 카드 안 제목줄로 넣으면 입력창처럼 보인다. 본문 줄 간격은 넉넉하게(위아래 줄의 색 배경이 닿지 않게). 모두 수락 · 거절은 확인 대신 `toast.undo`. 두 문자열 비교는 `diffWords`, 결과 글은 `applyDiffDecisions`.
+
+## API
+
+### Card
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'raised' \| 'plain'` | `'default'` | 표면 스타일. |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 안쪽 여백(14 / 20 / 28px). Header·Body·Footer가 함께 따라요. |
+| `interactive` | `boolean` |  | 호버 시 떠오름 + 누름 피드백. |
+| `selected` | `boolean` |  | 선택 카드. false여도 빈 체크가 보이고, true면 체크가 채워져요. |
+| `as` | `ElementType` | `'div'` | 렌더할 요소. 예: 'a', 'button', Link. |
+
+### CardHeader
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` |  | 제목. |
+| `description` | `ReactNode` |  | 제목 아래 설명. |
+| `eyebrow` | `ReactNode` |  | 제목 위 작은 글씨(분류, 날짜). |
+| `icon` | `ReactNode` |  | 앞 아이콘 또는 아바타. |
+| `actions` | `ReactNode` |  | 오른쪽 버튼·배지·메뉴. |
+
+### CardFooter
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `align` | `'start' \| 'end' \| 'between'` | `'end'` | 정렬. |
+| `divided` | `boolean` |  | 본문과의 사이에 얇은 구분선. |
+| `band` | `boolean` |  | 아래 가장자리를 꽉 채우는 옅은 회색 띠(상태 줄 + 경과 시간). 선 대신 채움으로 구분해요. |
+
+### CardMedia
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `ratio` | `number \| string` |  | 가로세로 비율. 예: 16 / 9, '16/9'. 주면 AspectRatio로 감싸 자식이 틀을 채워요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+Header(제목·설명·액션) + Body + Footer.
+
+```tsx
+import { CreditCard, MoreHorizontal } from 'lucide-react'
+import { Button, Card, CardBody, CardFooter, CardHeader } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card style={{ width: 380 }}>
+      <CardHeader
+        icon={<CreditCard />}
+        title="결제 수단"
+        description="매월 1일에 자동 결제돼요."
+        actions={<Button iconOnly variant="ghost" size="sm" icon={<MoreHorizontal />} aria-label="더보기" />}
+      />
+      <CardBody>신한카드 •••• 4821 · 2028년 4월 만료</CardBody>
+      <CardFooter>
+        <Button variant="ghost">삭제</Button>
+        <Button variant="secondary">변경</Button>
+      </CardFooter>
+    </Card>
+  )
+}
+```
+
+### 표면
+
+default는 옅은 윤곽, raised는 더 떠 보이고, plain은 그림자 없이 여백으로만 묶어요.
+
+```tsx
+import { Card, CardBody, CardHeader, type CardVariant } from '@iamfiro/design'
+
+const VARIANTS: Array<[CardVariant, string]> = [
+  ['default', '옅은 윤곽 + 그림자'],
+  ['raised', '더 떠 보이는 카드'],
+  ['plain', '그림자 없이 여백으로'],
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 200px)', gap: 16 }}>
+      {VARIANTS.map(([variant, text]) => (
+        <Card key={variant} variant={variant}>
+          <CardHeader title={variant} />
+          <CardBody>{text}</CardBody>
+        </Card>
+      ))}
+    </div>
+  )
+}
+```
+
+### 클릭 가능한 카드
+
+interactive는 마우스를 올리면 살짝 떠오르고 누르면 눌려요. as로 a / button을 지정하세요. selected를 주면 오른쪽 위에 체크가 생기고, 선택되면 파랗게 채워지며 아이콘도 파란 톤이 돼요.
+
+```tsx
+import { useState } from 'react'
+import { Building2, User, Users } from 'lucide-react'
+import { Card, CardHeader } from '@iamfiro/design'
+
+const PLANS = [
+  { id: 'solo', icon: <User />, title: '개인', description: '혼자 쓰는 프로젝트' },
+  { id: 'team', icon: <Users />, title: '팀', description: '최대 20명까지' },
+  { id: 'org', icon: <Building2 />, title: '조직', description: 'SSO · 감사 로그 포함' },
+]
+
+export default function Example() {
+  const [plan, setPlan] = useState('team')
+  return (
+    <div role="radiogroup" aria-label="플랜" style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 190px)', gap: 12 }}>
+      {PLANS.map((p) => (
+        <Card key={p.id} as="button" type="button" role="radio" aria-checked={plan === p.id} interactive selected={plan === p.id} padding="sm" onClick={() => setPlan(p.id)}>
+          <CardHeader icon={p.icon} title={p.title} description={p.description} />
+        </Card>
+      ))}
+    </div>
+  )
+}
+```