@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/flag/AGENTS.md

@@ -0,0 +1,67 @@
+# Flag
+
+> 라벨 & 배지 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+국가를 나타내는 작은 3:2 국기. Windows에선 국기 이모지가 "KR" 글자로 보여서 SVG로 그려요. 모서리를 살짝 둥글리고 옅은 안쪽 윤곽을 둬 흰 국기(한국 · 일본)도 흰 바탕에서 보여요.
+
+```tsx
+import { Flag } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 숫자만 받는 칸(금액 · 전화번호 · 카드 번호)은 `useDigitInput`을 Input에 펼친다: 글자는 아예 안 들어가고, 쉼표 · 하이픈은 `format`으로 붙이고, 커서는 같은 숫자 뒤에 머물고, 구분자 위 Backspace는 앞 숫자를 지운다. `type="number"`는 쓰지 않는다. 전화번호는 `PhoneInput`(칸 안 `Select bare` 국가 선택 + 국기 `Flag`, 목록은 `anchorRef`로 칸 전체 폭). 국기는 이모지 대신 `Flag`(Windows에서 이모지 국기는 글자로 나온다).
+
+## API
+
+### Flag
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `code` (필수) | `'KR' \| 'US' \| 'JP' \| 'CN' \| 'VN' \| 'GB' \| 'DE' \| 'FR'` |  | ISO 국가 코드. |
+| `size` | `number` | `20` | 너비(px). |
+| `label` | `string` |  | 화면 읽기용 이름. 없으면 장식으로 숨겨요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 국가와 크기
+
+size는 너비(px), 높이는 늘 2/3. 옆에 국가 이름이 없으면 label을 주세요.
+
+```tsx
+import { Flag, Inline, Stack, Text, type FlagCode } from '@iamfiro/design'
+
+const COUNTRIES: [FlagCode, string][] = [
+  ['KR', '대한민국'],
+  ['US', '미국'],
+  ['JP', '일본'],
+  ['CN', '중국'],
+  ['VN', '베트남'],
+  ['GB', '영국'],
+  ['DE', '독일'],
+  ['FR', '프랑스'],
+]
+
+export default function Example() {
+  return (
+    <Stack gap={5}>
+      <Inline gap={5}>
+        {COUNTRIES.map(([code, name]) => (
+          <Inline key={code} gap={2}>
+            <Flag code={code} />
+            <Text variant="body-sm">{name}</Text>
+          </Inline>
+        ))}
+      </Inline>
+      <Inline gap={4} align="end">
+        <Flag code="KR" size={16} label="대한민국" />
+        <Flag code="KR" size={24} label="대한민국" />
+        <Flag code="KR" size={36} label="대한민국" />
+        <Flag code="KR" size={54} label="대한민국" />
+      </Inline>
+    </Stack>
+  )
+}
+```

package/agents/funnel-chart/AGENTS.md

@@ -0,0 +1,131 @@
+# FunnelChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+단계별 전환을 보여주는 퍼널 차트. 단계마다 값에 비례한 막대와 값 · 전환율을 적고, 앞 단계에서 빠져나간 만큼은 옅은 빗금 영역으로 남겨요. 막대는 차례로 자라고 데이터가 바뀌면 새 길이로 미끄러지며, 마우스 · 터치 · ↑/↓ 키로 단계의 값 · 전환율 · 이탈을 Card 툴팁에 보여줘요.
+
+```tsx
+import { FunnelChart, type FunnelStep } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 두 값의 관계는 `ScatterChart`(가장 가까운 점이 커지고 나머지는 흐려짐, 범례 클릭 = 분류 숨김 · 보임은 제자리에서 줄며 사라지기), 단계 전환은 `FunnelChart`(빠진 만큼은 앞 단계 색의 옅은 빗금, 한 색조 단계는 `gradient` = `--chart-seq-*`).
+
+## API
+
+### FunnelChart
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `FunnelStep[]` |  | { key, label, value, color? } 단계 목록(순서대로). |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 가로 = 단계마다 한 줄(폭이 값), 세로 = 단계마다 한 열(높이가 값). |
+| `calculateFrom` | `'first' \| 'previous'` | `'first'` | 단계 옆 전환율의 기준. 툴팁에는 두 기준이 모두 나와요. |
+| `color` | `string` | `'--chart-seq-1'` | 막대 색. |
+| `gradient` | `boolean` | `false` | 단계마다 --chart-seq-1부터 옅어지는 한 색조. |
+| `showDropOff` | `boolean` | `true` | 앞 단계에서 빠진 만큼의 빗금 영역. |
+| `height` | `number` | `260` | 세로 방향의 높이(px). 가로는 단계 수 × barSize. |
+| `barSize` | `number` | `32` | 가로 방향 막대 두께(px). |
+| `formatValue` | `(value, step) => string` | `'1,234'` | 값 형식. |
+| `formatPercent` | `(ratio) => string` | `'31.4%'` | 전환율 · 이탈률 형식. |
+| `legend` | `boolean` | `true` | 아래 범례(전환 · 이탈). |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 하이라이트한 단계(제어/비제어). |
+| `aria-label` | `string` | `'퍼널 차트'` | 차트 이름. |
+
+### funnelStats
+
+(data, calculateFrom) => FunnelStepStats[]. 단계마다 fromFirst · fromPrevious · conversion · drop · dropRate를 계산해요. 표나 요약 문구를 차트와 같은 숫자로 맞출 때 써요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `FunnelStep[]` |  | 단계 목록. |
+| `calculateFrom` (필수) | `'first' \| 'previous'` |  | conversion에 담을 기준. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 가입 퍼널
+
+방문 → 가입 → 활성화 → 결제. calculateFrom을 바꾸면 오른쪽 전환율이 첫 단계 대비와 이전 단계 대비 사이에서 바뀌어요.
+
+```tsx
+import { useState } from 'react'
+import { FunnelChart, type FunnelCalculateFrom, type FunnelStep, SegmentedControl, Stack } from '@iamfiro/design'
+
+const STEPS: FunnelStep[] = [
+  { key: 'visit', label: '방문', value: 12480 },
+  { key: 'signup', label: '가입', value: 3920 },
+  { key: 'activate', label: '활성화', value: 2140 },
+  { key: 'pay', label: '결제', value: 610 },
+]
+
+export default function Example() {
+  const [from, setFrom] = useState<FunnelCalculateFrom>('first')
+  return (
+    <Stack gap={5} style={{ width: '100%', maxWidth: 560 }}>
+      <SegmentedControl
+        ariaLabel="전환율 기준"
+        value={from}
+        onChange={setFrom}
+        options={[
+          { value: 'first', label: '첫 단계 대비' },
+          { value: 'previous', label: '이전 단계 대비' },
+        ]}
+      />
+      <FunnelChart data={STEPS} calculateFrom={from} formatValue={(v) => `${v.toLocaleString('ko-KR')}명`} aria-label="가입 퍼널" />
+    </Stack>
+  )
+}
+```
+
+### 세로 · 그라데이션
+
+orientation="vertical"은 단계를 열로 세우고, gradient는 --chart-seq-* 한 색조로 단계마다 옅어져요. 기간을 바꾸면 막대가 새 높이로 움직여요.
+
+```tsx
+import { useState } from 'react'
+import { FunnelChart, type FunnelStep, SegmentedControl, Stack } from '@iamfiro/design'
+
+type Month = 'sep' | 'oct'
+
+const DATA: Record<Month, FunnelStep[]> = {
+  sep: [
+    { key: 'visit', label: '방문', value: 10200 },
+    { key: 'signup', label: '가입', value: 2860 },
+    { key: 'activate', label: '활성화', value: 1320 },
+    { key: 'pay', label: '결제', value: 340 },
+  ],
+  oct: [
+    { key: 'visit', label: '방문', value: 12480 },
+    { key: 'signup', label: '가입', value: 3920 },
+    { key: 'activate', label: '활성화', value: 2140 },
+    { key: 'pay', label: '결제', value: 610 },
+  ],
+}
+
+export default function Example() {
+  const [month, setMonth] = useState<Month>('oct')
+  return (
+    <Stack gap={5} style={{ width: '100%', maxWidth: 560 }}>
+      <SegmentedControl
+        ariaLabel="기간"
+        value={month}
+        onChange={setMonth}
+        options={[
+          { value: 'sep', label: '9월' },
+          { value: 'oct', label: '10월' },
+        ]}
+      />
+      <FunnelChart
+        data={DATA[month]}
+        orientation="vertical"
+        gradient
+        calculateFrom="previous"
+        formatValue={(v) => v.toLocaleString('ko-KR')}
+        aria-label={`${month === 'sep' ? '9월' : '10월'} 가입 퍼널`}
+      />
+    </Stack>
+  )
+}
+```

package/agents/highlight/AGENTS.md

@@ -0,0 +1,119 @@
+# Highlight
+
+> 텍스트 & 코드 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+글 속 일부를 연한 상태색 배경으로 표시해요(warning · accent · danger). note를 주면 그 글자에 붙은 메모 말풍선(Popover)이 생겨요: 상태색 아이콘 + 오버라인 제목, 본문, 출처 칩. 메모가 있는 표시는 Tab으로 포커스할 수 있고, aria-describedby가 항상 있는 메모 사본을 가리켜 말풍선이 닫혀 있어도 설명이 읽혀요.
+
+```tsx
+import { Highlight } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 민감한 값은 `MaskedText`(양 끝만, 점 한 묶음이라 길이를 드러내지 않음, 화면 읽기는 "가려진 값"), 글 속 강조 + 메모 말풍선은 `Highlight note`, 첨부 파일 링크는 `FileChip`(확장자는 줄이지 않음).
+
+## API
+
+### Highlight
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 표시할 글자(또는 MaskedText). |
+| `tone` | `'warning' \| 'accent' \| 'danger'` | `'warning'` | 배경 · 글자 · 메모 제목 색. |
+| `note` | `ReactNode` |  | 메모 본문. 없으면 단순 표시. |
+| `noteTitle` | `ReactNode` |  | 메모의 오버라인 제목("확인 필요"). |
+| `noteIcon` | `ReactNode` |  | 제목 앞 아이콘. 기본은 tone별(경고 삼각형 · 오류 원 · 정보). |
+| `noteFooter` | `ReactNode` |  | 본문 아래 작은 줄. 보통 출처 Badge. |
+| `openOn` | `'hover' \| 'always'` | `'hover'` | hover: 호버 · 포커스 · 누르면 열림 / always: 항상 열림. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때(hover). |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `noteWidth` | `number` | `280` | 메모 폭(px). |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | 표시 기준 메모의 가로 정렬. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 송금 검토 (항상 열림)
+
+openOn="always": 검토 화면처럼 메모가 처음부터 값 아래에 붙어 있어요. 값 자리에는 MaskedText를 그대로 넣었어요.
+
+```tsx
+import { Badge, MaskedText, Stack, Text, DescriptionItem, DescriptionList, FileChip, Highlight, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} align="start" style={{ width: '100%', maxWidth: 420 }}>
+      <Stack gap={1}>
+        <Text variant="heading-sm">한빛물류 INV-2207 송금</Text>
+        <Text variant="body-sm" tone="secondary">
+          금액과 품목은 발주서 PO-118과 같아요. 계좌 정보가 지난 여섯 번의 송금과 달라요.
+        </Text>
+      </Stack>
+      <DescriptionList labelStyle="muted" size="sm" columns="repeat(3, max-content)" gap={8} aria-label="송금 정보">
+        <DescriptionItem label="금액">₩12,480,000</DescriptionItem>
+        <DescriptionItem label="지급일">10월 24일</DescriptionItem>
+        <DescriptionItem label="IBAN">
+          <Highlight
+            openOn="always"
+            noteTitle="확인 필요"
+            note="이틀 전 메일로 바뀐 새 계좌예요. 송금 전에 전화로 확인하세요."
+            noteFooter={<Badge size="sm">billing@hanbit-logis.co.kr 메일</Badge>}
+          >
+            <MaskedText label="IBAN" value="DE89 3704 0044 0532 0130 00" />
+          </Highlight>
+        </DescriptionItem>
+      </DescriptionList>
+      <FileChip name="INV-2207.pdf" size={248_000} onClick={() => toast('INV-2207.pdf 미리보기를 열었어요')} />
+    </Stack>
+  )
+}
+```
+
+### 호버 · 포커스로 열기
+
+기본 openOn="hover": 포인터가 잠깐(200ms) 머물면 열리고 300ms 유예 뒤 닫혀요. Tab 포커스로 바로 열리고 Esc로 닫혀요. 터치에서는 누르면 열리고 바깥을 누르면 닫혀요.
+
+```tsx
+import { Badge, Text, Highlight } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Text variant="body-md" style={{ maxWidth: 460 }}>
+      이번 배포는{' '}
+      <Highlight tone="accent" noteTitle="참고" note="결제 페이지의 쿠폰 처리만 바뀌었어요. 나머지 화면은 그대로예요." noteFooter={<Badge size="sm">이도현 · 2분 전</Badge>}>
+        쿠폰 처리 변경
+      </Highlight>
+      을 포함하고,{' '}
+      <Highlight tone="danger" noteTitle="실패" note="결제 테스트 412개 중 1개가 시간 초과로 실패했어요. 다시 실행하면 통과했어요.">
+        테스트 1건 실패
+      </Highlight>
+      가 있었어요.
+    </Text>
+  )
+}
+```
+
+### 색 · 메모 없는 표시
+
+note가 없으면 포커스되지 않는 단순한 <mark>예요. 열린 동안은 배경이 한 단계 진해져요.
+
+```tsx
+import { Stack, Text, Highlight } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={2}>
+      <Text variant="body-md">
+        지급일이 <Highlight>10월 24일</Highlight>로 하루 앞당겨졌어요.
+      </Text>
+      <Text variant="body-md">
+        새 담당자는 <Highlight tone="accent">김민지</Highlight> 님이에요.
+      </Text>
+      <Text variant="body-md">
+        미납 금액 <Highlight tone="danger">₩1,134,545</Highlight>이 남아 있어요.
+      </Text>
+    </Stack>
+  )
+}
+```

package/agents/hover-card/AGENTS.md

@@ -0,0 +1,271 @@
+# HoverCard
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+이름·링크·저장소 위에 잠깐 머물면 뜨는 풍부한 미리보기. Popover openOn="hover" 위에 만들어서 위치 잡기·뒤집기·퇴장 애니메이션을 그대로 써요. 포인터가 200ms 머물러야 열리고, 벗어나도 300ms 유예가 있어 카드로 옮겨 가는 동안 닫히지 않아요. 키보드 포커스로는 바로 열리고, 터치에서는 첫 탭이 카드를 열어요. 꼭 필요한 정보나 유일한 동작은 여기에만 두지 마세요.
+
+```tsx
+import { HoverCard } from '@iamfiro/design'
+```
+
+## API
+
+### HoverCard
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `trigger` (필수) | `ReactNode` |  | 머무는 대상(Link, Button, 이름). |
+| `media` | `ReactNode` |  | 맨 위 미디어(AspectRatio 이미지 등). |
+| `leading` | `ReactNode` |  | 제목 앞 Avatar · IconTile · 로고. |
+| `title` | `ReactNode` |  | 제목(한 줄). 글자면 카드의 접근성 이름이 돼요. |
+| `subtitle` | `ReactNode` |  | 제목 아래 옅은 한 줄(역할, 도메인). |
+| `description` | `ReactNode` |  | 옅은 설명. 세 줄까지 보여요. |
+| `meta` | `Array<{ icon?, label }> \| ReactNode` |  | 작은 사실들의 줄(위치, 별 수). 배열이면 아이콘 + 글자 칩으로 그려요. |
+| `children` | `ReactNode` |  | 구조 아래 자유 내용. |
+| `actions` | `ReactNode` |  | 맨 아래 버튼 줄. |
+| `loading` | `boolean` | `false` | 자리 표시 모양(아바타 원 + 줄). |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | 트리거 기준 가로 정렬. |
+| `width` | `number \| string` | `320` | 카드 폭. |
+| `touch` | `'tap' \| 'none'` | `'tap'` | tap: 터치의 첫 탭은 트리거를 실행하지 않고 카드를 열어요(두 번째 탭은 그대로). none: 터치에선 평소처럼 동작하고 카드는 마우스·키보드 전용. |
+| `aria-label` | `string` |  | 카드 이름. 생략하면 글자 title. |
+| `className` | `string` |  | 카드 패널에 붙는 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 사람
+
+leading(Avatar) · title · subtitle · description · meta · actions로 구조를 채우면 간격과 정렬이 맞춰져요. meta 아이콘은 14px로 넘겨요.
+
+```tsx
+import { useState } from 'react'
+import { Clock, MapPin, UserPlus } from 'lucide-react'
+import { Avatar, Button, Link, Text, HoverCard } from '@iamfiro/design'
+
+export default function Example() {
+  const [following, setFollowing] = useState(false)
+  return (
+    <Text as="p" variant="body-md" style={{ maxWidth: 420 }}>
+      버튼 여백 수정은{' '}
+      <HoverCard
+        trigger={
+          <Link variant="inherit" href="#" onClick={(e) => e.preventDefault()}>
+            @김민지
+          </Link>
+        }
+        leading={<Avatar name="김민지" size={40} online tooltip={false} />}
+        title="김민지"
+        subtitle="디자인 시스템 팀 · 리드"
+        description="Lumen 컴포넌트와 토큰을 관리해요. 오후 6시 이후엔 답이 늦을 수 있어요."
+        meta={[
+          { icon: <MapPin size={14} />, label: '서울' },
+          { icon: <Clock size={14} />, label: '현지 시간 오후 3:42' },
+        ]}
+        actions={
+          <Button size="sm" variant={following ? 'secondary' : 'primary'} icon={following ? undefined : <UserPlus />} onClick={() => setFollowing(!following)}>
+            {following ? '팔로우 중' : '팔로우'}
+          </Button>
+        }
+      />{' '}
+      님이 검토하고 있어요.
+    </Text>
+  )
+}
+```
+
+### 링크 미리보기
+
+media는 카드 맨 위에 들어가요(AspectRatio). 터치에서는 첫 탭에 미리보기가 열리고 두 번째 탭이 링크를 따라가요.
+
+```tsx
+import { BookOpen } from 'lucide-react'
+import { AspectRatio, IconTile, Inline, Link, Text, HoverCard } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Text as="p" variant="body-md" style={{ maxWidth: 420 }}>
+      자세한 규칙은{' '}
+      <HoverCard
+        width={300}
+        trigger={
+          <Link href="#" onClick={(e) => e.preventDefault()}>
+            컴포넌트 개발 가이드
+          </Link>
+        }
+        media={
+          <AspectRatio ratio="1.91" radius="md" background="subtle">
+            <Inline justify="center" style={{ height: '100%' }}>
+              <IconTile size={48} tone="surface">
+                <BookOpen />
+              </IconTile>
+            </Inline>
+          </AspectRatio>
+        }
+        title="컴포넌트 개발 가이드"
+        subtitle="wiki.lumen.app"
+        description="받은 디자인 피드백을 규칙으로 정리한 문서예요. 바탕·색·테두리, 형태, 애니메이션, 인터랙션 규칙과 체크리스트가 있어요."
+        meta={[{ label: '10월 25일 수정' }, { label: '6분 읽기' }]}
+      />
+      를 보세요. 터치 기기에서는 첫 번째 탭에 미리보기가 열리고, 한 번 더 누르면 링크로 이동해요.
+    </Text>
+  )
+}
+```
+
+### 저장소
+
+meta 줄에 별·포크·이슈 수를, children에 언어·상태 배지를 넣었어요.
+
+```tsx
+import { CircleDot, GitFork, Star } from 'lucide-react'
+import { Badge, BrandIcon, Button, IconTile, Inline, HoverCard } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={2}>
+      <HoverCard
+        trigger={
+          <Button variant="secondary" size="sm" icon={<BrandIcon name="github" />}>
+            lumen/design-system
+          </Button>
+        }
+        leading={
+          <IconTile size={40} tone="surface">
+            <BrandIcon name="github" />
+          </IconTile>
+        }
+        title="lumen/design-system"
+        subtitle="공개 저장소 · 2시간 전 업데이트"
+        description="Vite + React + TypeScript로 만든 Lumen 디자인 시스템. 토큰, 기본 요소, 조합 컴포넌트와 문서 사이트가 들어 있어요."
+        meta={[
+          { icon: <Star size={14} />, label: '1.2천' },
+          { icon: <GitFork size={14} />, label: '84' },
+          { icon: <CircleDot size={14} />, label: '이슈 12' },
+        ]}
+      >
+        <Inline gap={1}>
+          <Badge size="sm">TypeScript</Badge>
+          <Badge size="sm">CSS</Badge>
+          <Badge size="sm" tone="success" dot>
+            빌드 통과
+          </Badge>
+        </Inline>
+      </HoverCard>
+    </Inline>
+  )
+}
+```
+
+### 불러오는 중
+
+열릴 때 데이터를 가져오면 loading으로 자리 표시 모양을 보여 줘요. open · onOpenChange로 열린 순간을 알 수 있어요.
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Avatar, Badge, Button, Inline, HoverCard } from '@iamfiro/design'
+
+interface Profile {
+  name: string
+  role: string
+  bio: string
+}
+
+// A pretend API: the profile arrives a moment after the card opens.
+const fetchProfile = (name: string) =>
+  new Promise<Profile>((resolve) =>
+    setTimeout(() => resolve({ name, role: '프론트엔드 개발 · 플랫폼 팀', bio: '배포 파이프라인과 사내 도구를 만들어요. 이번 주는 재택 근무 중이에요.' }), 900),
+  )
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  const [profile, setProfile] = useState<Profile | null>(null)
+
+  useEffect(() => {
+    if (!open || profile) return
+    let alive = true
+    fetchProfile('이도현').then((p) => alive && setProfile(p))
+    return () => {
+      alive = false
+    }
+  }, [open, profile])
+
+  return (
+    <Inline gap={3}>
+      <HoverCard
+        open={open}
+        onOpenChange={setOpen}
+        loading={!profile}
+        aria-label="이도현 프로필"
+        trigger={
+          <Button variant="ghost" size="sm" icon={<Avatar name="이도현" size={20} tooltip={false} />}>
+            이도현
+          </Button>
+        }
+        leading={<Avatar name="이도현" size={40} tooltip={false} />}
+        title={profile?.name}
+        subtitle={profile?.role}
+        description={profile?.bio}
+      >
+        <Inline gap={1}>
+          <Badge size="sm" tone="info">
+            재택
+          </Badge>
+        </Inline>
+      </HoverCard>
+      <Button size="sm" variant="ghost" onClick={() => setProfile(null)}>
+        다시 불러오기
+      </Button>
+    </Inline>
+  )
+}
+```
+
+### 자유 내용
+
+구조 슬롯과 함께 children에 진행률·아바타 묶음처럼 아무 내용이나 넣을 수 있어요. align으로 트리거 기준 정렬을 바꿔요.
+
+```tsx
+import { Users } from 'lucide-react'
+import { AvatarGroup, Button, IconTile, Progress, Stack, Text, HoverCard } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <HoverCard
+      align="center"
+      trigger={
+        <Button variant="secondary" icon={<Users />}>
+          디자인 시스템 팀
+        </Button>
+      }
+      leading={
+        <IconTile size={40} tone="accent">
+          <Users />
+        </IconTile>
+      }
+      title="디자인 시스템 팀"
+      subtitle="멤버 6명 · #디자인-시스템"
+      actions={
+        <>
+          <Button size="sm" variant="primary">
+            팀 페이지
+          </Button>
+          <Button size="sm" variant="ghost">
+            메시지
+          </Button>
+        </>
+      }
+    >
+      <Stack gap={2}>
+        <Text variant="label-sm" tone="secondary">
+          스프린트 14 · 남은 기간 3일
+        </Text>
+        <Progress value={68} aria-label="스프린트 진행률" />
+        <AvatarGroup names={['김민지', '이도현', '박서준', '최유나', '정하늘', '한지우']} size={24} max={4} />
+      </Stack>
+    </HoverCard>
+  )
+}
+```