@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/sparkbar/AGENTS.md

@@ -0,0 +1,92 @@
+# Sparkbar
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+축 없이 막대만 늘어놓은 작은 막대 줄. 합계 아래 일별 추이처럼 흐름만 보여 줄 때 써요. 바닥에서 자라고 데이터가 바뀌면 새 높이로 미끄러지며, 마우스·터치·←/→로 막대를 고르면 차트 툴팁 카드에 값이 떠요. null은 아직 기록이 없는 칸으로 납작한 자리 표시가 돼요.
+
+```tsx
+import { Sparkbar } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 차트: 시리즈 색은 `--chart-1…6`을 순서대로, 그리드는 `--chart-grid`로 아주 옅게(세로선·축선 없음). 범례·툴팁의 색 표시는 `ColorDot`, 툴팁은 `Card raised` + `Separator`로 조립. 축·툴팁·범례·호버/키보드는 `components/Chart/`의 공용 조각(`ChartTooltip`, `ChartLegend`, `useChartInteraction`)을 쓴다. → `LineChart` · `BarChart` · `PieChart` · `Sparkbar`
+- 표 칸 · KPI 카드의 작은 추이는 `SparkLine` · `SparkArea` · `Sparkbar`(같은 props, 하나로 고르면 `SparkChart type`). 축 없음, 실제 픽셀 크기로 그려 24–40px에서도 또렷하게, 값 범위는 0이 아니라 최솟값–최댓값. 색은 `tone="trend"` + `higherIs`(Delta와 같은 규칙), 마지막 값은 `endDot`. 긴 표에선 `tooltip={false}`로 이벤트 없는 정적 그림(`role="img"`). KPI 카드는 Card 안 `Stat` + `Delta` + `SparkArea`.
+
+## API
+
+### Sparkbar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `(number \| null)[]` |  | 한 칸에 값 하나. null은 기록 없음(자리 표시). |
+| `height` | `number` | `48` | 높이(px). |
+| `max` | `number` |  | 막대가 꽉 차는 값. 기본은 가장 큰 값. |
+| `color` | `string` | `'--n5'` | 막대 색. CSS 변수 이름('--accent') 또는 색. |
+| `tone / higherIs / worseTone` | `'accent' \| 'neutral' \| 'trend'` |  | SparkLine과 같은 색 규칙. trend는 처음 대비 마지막 값의 방향으로 초록 / 주황. color가 우선이고, 둘 다 없으면 옅은 회색. |
+| `formatLabel` | `(index) => string` | `'3일'` | 툴팁 제목. |
+| `formatValue` | `(value) => string` | `'1,234'` | 툴팁 값 형식. |
+| `valueLabel` | `string` | `'값'` | 툴팁 행 이름. |
+| `tooltip` | `boolean` | `true` | 값 카드 표시. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 고른 막대(제어/비제어). |
+| `aria-label` | `string` | `'막대 그래프'` | 이름. 고른 막대는 aria-live로 읽어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+기본 막대는 옅은 회색이고, 고른 막대만 조금 진해져요. 포커스한 뒤 ←/→, Home/End, Esc로도 움직여요.
+
+```tsx
+import { Sparkbar } from '@iamfiro/design'
+
+const VISITS = [42, 58, 51, 66, 73, 40, 35, 61, 70, 68, 77, 82, 49, 44, 69, 88, 91, 76, 84, 52, 47, 79, 86, 93]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', maxWidth: 360 }}>
+      <Sparkbar data={VISITS} formatLabel={(i) => `${i}시`} valueLabel="방문" aria-label="시간대별 방문 수" />
+    </div>
+  )
+}
+```
+
+### 자리 표시 · 색 · 데이터 바뀜
+
+앞으로 올 날은 null로 두면 바닥에 납작한 선으로 보여요. color로 막대 색을 바꾸고, 달을 바꾸면 막대가 새 높이로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, Sparkbar } from '@iamfiro/design'
+
+// 10월은 22일까지만 기록이 있어요. 남은 날은 null → 납작한 자리 표시.
+const OCTOBER = [12, 31, 29, 25, 42, 36, 16, 14, 38, 35, 34, 44, 33, 17, 19, 48, 42, 38, 40, 47, 22, 23, ...Array<null>(9).fill(null)]
+const SEPTEMBER = [26, 30, 28, 33, 31, 18, 15, 29, 35, 33, 30, 36, 20, 17, 31, 38, 34, 32, 40, 21, 19, 33, 36, 35, 31, 39, 22, 18, 30, 32]
+
+export default function Example() {
+  const [month, setMonth] = useState<9 | 10>(10)
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 360 }}>
+      <Sparkbar
+        data={month === 10 ? OCTOBER : SEPTEMBER}
+        height={56}
+        color="--accent"
+        formatLabel={(i) => `${month}월 ${i + 1}일`}
+        formatValue={(v) => `${v}건`}
+        valueLabel="주문"
+        aria-label={`${month}월 일별 주문`}
+      />
+      <Inline gap={2}>
+        <Button size="sm" variant={month === 9 ? 'primary' : 'secondary'} onClick={() => setMonth(9)}>
+          9월
+        </Button>
+        <Button size="sm" variant={month === 10 ? 'primary' : 'secondary'} onClick={() => setMonth(10)}>
+          10월
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```

package/agents/spinner/AGENTS.md

@@ -0,0 +1,123 @@
+# Spinner
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+옅은 고리 위로 호가 돌면서 늘었다 줄었다 하는 로딩 표시. 진행률을 알 수 없는 짧은 기다림에 써요. 기본 색은 주변 글자 색을 따라가고, 스크린 리더에는 label을 읽어 줘요.
+
+```tsx
+import { Spinner } from '@iamfiro/design'
+```
+
+## API
+
+### Spinner
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | `'sm'` | 이름 있는 크기 또는 px 숫자. |
+| `tone` | `'default' \| 'muted' \| 'accent' \| 'inverse' \| 'inherit'` | `'inherit'` | 색. inherit은 글자 색을 따라가요. |
+| `label` | `string` | `'불러오는 중'` | 스크린 리더가 읽는 이름(role="status"). |
+| `className / style` | `string / CSSProperties` |  | 루트에 적용돼요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 크기
+
+xs 12 · sm 14 · md 18 · lg 24 · xl 32px. 숫자를 넘기면 그 크기(px)로 그려요.
+
+```tsx
+import { Spinner, Text, type SpinnerSize } from '@iamfiro/design'
+
+const SIZES: SpinnerSize[] = ['xs', 'sm', 'md', 'lg', 'xl']
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'flex-end', gap: 32 }}>
+      {SIZES.map((size) => (
+        <div key={size} style={{ display: 'grid', justifyItems: 'center', gap: 10 }}>
+          <Spinner size={size} tone="default" />
+          <Text variant="caption" tone="tertiary">
+            {size}
+          </Text>
+        </div>
+      ))}
+      <div style={{ display: 'grid', justifyItems: 'center', gap: 10 }}>
+        <Spinner size={48} tone="default" />
+        <Text variant="caption" tone="tertiary">
+          48
+        </Text>
+      </div>
+    </div>
+  )
+}
+```
+
+### 색
+
+default · muted · accent는 정해진 색, inverse는 어두운 배경용이에요. 기본값 'inherit'은 currentColor를 써서 글자 색을 따라가요.
+
+```tsx
+import { Spinner, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', justifyContent: 'center', gap: 28 }}>
+      <Spinner size="lg" tone="default" label="기본" />
+      <Spinner size="lg" tone="muted" label="흐리게" />
+      <Spinner size="lg" tone="accent" label="강조" />
+      <div style={{ display: 'grid', placeItems: 'center', width: 48, height: 48, borderRadius: 12, background: 'var(--primary)' }}>
+        <Spinner size="lg" tone="inverse" label="어두운 배경" />
+      </div>
+      <Text tone="success" style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+        <Spinner />
+        글자 색을 따라가요
+      </Text>
+    </div>
+  )
+}
+```
+
+### 버튼 · 인라인
+
+Button의 loading을 켜면 아이콘 자리에 Spinner가 들어가고 눌리지 않아요. 짧은 상태 문구 옆에도 써요.
+
+```tsx
+import { useState } from 'react'
+import { RefreshCw, Save } from 'lucide-react'
+import { Button, Spinner, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [saving, setSaving] = useState(false)
+  const [syncing, setSyncing] = useState(false)
+
+  const save = () => {
+    setSaving(true)
+    setTimeout(() => setSaving(false), 1600)
+  }
+
+  const sync = () => {
+    setSyncing(true)
+    setTimeout(() => setSyncing(false), 2400)
+  }
+
+  return (
+    <div style={{ display: 'grid', justifyItems: 'center', gap: 20 }}>
+      <div style={{ display: 'flex', gap: 8 }}>
+        <Button variant="primary" icon={<Save />} loading={saving} onClick={save}>
+          {saving ? '저장 중…' : '저장'}
+        </Button>
+        <Button iconOnly icon={<RefreshCw />} loading={syncing} onClick={sync} aria-label="동기화" />
+        <Button size="sm" loading>
+          작은 버튼
+        </Button>
+      </div>
+      <Text variant="body-sm" tone="tertiary" style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+        {syncing && <Spinner size="xs" />}
+        {syncing ? '동기화 중…' : '2분 전에 동기화됨'}
+      </Text>
+    </div>
+  )
+}
+```

package/agents/split-view/AGENTS.md

@@ -0,0 +1,290 @@
+# SplitView
+
+> 컨테이너 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+목록 – 상세(master–detail) 두 칸 레이아웃. 왼쪽 목록과 오른쪽 상세가 각자 스크롤되고, 목록은 옅은 회색 판 위에 놓여 ListItem variant="raised"로 고른 행이 흰 카드처럼 떠올라요. resizable이면 가운데 경계를 끌거나, 포커스한 뒤 ← → 로 목록 너비를 바꿔요. 높이는 부모가 정해요.
+
+```tsx
+import { SplitView } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 목록–상세는 `SplitView`(칸마다 스크롤, 경계는 `role="separator"`). 회색 판 위의 선택 행은 `ListItem variant="raised"`.
+
+## API
+
+### SplitView
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `list` (필수) | `ReactNode` |  | 왼쪽 목록 칸. |
+| `children` (필수) | `ReactNode` |  | 오른쪽 상세 칸. 세로 flex라 ActionBar가 아래에 붙어요. |
+| `listWidth` | `number` |  | 목록 너비 px(제어). |
+| `defaultListWidth` | `number` | `300` | 처음 너비(비제어). 더블 클릭 · Enter로 돌아가는 너비. |
+| `onListWidthChange` | `(width: number) => void` |  | 끌거나 키로 바꿀 때. |
+| `minListWidth / maxListWidth` | `number` | `220 / 520` | 너비 범위. |
+| `resizable` | `boolean` |  | 경계를 끌어 너비 조절. role="separator"(aria-valuenow), ← → (Shift는 크게) · Home / End. |
+| `listTone` | `'soft' \| 'plain'` | `'soft'` | soft: 목록 칸이 옅은 회색 판 · plain: 흰 바탕. |
+| `listLabel / detailLabel` | `string` | `'목록' / '상세'` | 두 칸(section)의 접근성 이름. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. 부모가 flex 세로면 style={{ flex: 1, minHeight: 0 }}. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 검토 대기열
+
+위쪽은 제목 · 작은 진행 막대 · "26 / 33 검토" · 실행 취소(Z). 왼쪽은 개수가 붙은 Tabs와 요청 목록, 오른쪽은 요청 내용과 아래에 붙은 ActionBar(승인 A · 수정 E · 거절 R · 건너뛰기 S). 처리 중엔 버튼과 단축키가 잠기고, 끝나면 다음 요청이 골라져요.
+
+```tsx
+import { useEffect, useState, type ReactNode } from 'react'
+import { Check, ChevronsRight, CircleCheck, FileSignature, KeyRound, Pencil, Receipt, Undo2, UserPlus, X } from 'lucide-react'
+import { Badge, Box, Button, Grid, IconTile, Inline, Progress, Stack, Text, ActionBar, Card, List, ListItem, SplitView, Tab, TabList, TabPanel, Tabs } from '@iamfiro/design'
+
+interface ReviewItem {
+  id: string
+  icon: ReactNode
+  title: string
+  kind: string
+  time: string
+  from: string
+  risk?: boolean
+  note: string
+  amount: string
+  due: string
+}
+
+const REQUESTS: ReviewItem[] = [
+  { id: 'r1', icon: <Receipt />, title: '10월 법인 카드 정산', kind: '경비', time: '방금', from: '김민지', risk: true, note: '영수증 12장 중 2장의 금액이 카드 내역과 달라요.', amount: '1,248,000원', due: '10월 27일' },
+  { id: 'r2', icon: <UserPlus />, title: '이도현 님 관리자 권한 요청', kind: '권한', time: '14분', from: '이도현', note: '디자인팀 워크스페이스의 관리자 권한을 요청했어요.', amount: '—', due: '10월 26일' },
+  { id: 'r3', icon: <FileSignature />, title: '협력사 계약서 갱신', kind: '계약', time: '1시간', from: '김민지', note: '단가가 작년보다 4% 올랐어요. 나머지 조건은 같아요.', amount: '32,000,000원', due: '10월 31일' },
+  { id: 'r4', icon: <KeyRound />, title: '외부 공유 링크 허용', kind: '보안', time: '2시간', from: '이도현', risk: true, note: '고객사에 보낼 폴더를 링크로 공유하려고 해요.', amount: '—', due: '10월 25일' },
+]
+
+const REVIEWED_BEFORE = 26
+const TOTAL = REVIEWED_BEFORE + REQUESTS.length
+
+export default function Example() {
+  const [queue, setQueue] = useState(REQUESTS)
+  const [done, setDone] = useState<ReviewItem[]>([])
+  const [tab, setTab] = useState('all')
+  const [selectedId, setSelectedId] = useState(REQUESTS[0].id)
+  const [pending, setPending] = useState(false)
+
+  const shown = tab === 'risk' ? queue.filter((r) => r.risk) : queue
+  const selected = queue.find((r) => r.id === selectedId) ?? shown[0]
+
+  // 데모용 처리: 0.6초 동안 잠갔다가 목록에서 빼고 다음 요청을 골라요.
+  useEffect(() => {
+    if (!pending || !selected) return
+    const id = window.setTimeout(() => {
+      const rest = queue.filter((r) => r.id !== selected.id)
+      setQueue(rest)
+      setDone((d) => [selected, ...d])
+      setSelectedId(rest[0]?.id ?? '')
+      setPending(false)
+    }, 600)
+    return () => window.clearTimeout(id)
+  }, [pending, selected, queue])
+
+  const undo = () => {
+    const [last, ...older] = done
+    if (!last) return
+    setDone(older)
+    setQueue((q) => REQUESTS.filter((r) => r.id === last.id || q.some((x) => x.id === r.id)))
+    setSelectedId(last.id)
+  }
+
+  const act = () => setPending(true)
+  const reviewed = REVIEWED_BEFORE + done.length
+
+  const rows = (items: ReviewItem[]) => (
+    <List density="compact" aria-label="검토할 요청">
+      {items.map((r) => (
+        <ListItem
+          key={r.id}
+          variant="raised"
+          selected={selected?.id === r.id}
+          onClick={() => setSelectedId(r.id)}
+          leading={<IconTile tone="surface">{r.icon}</IconTile>}
+          title={r.title}
+          description={r.kind}
+          meta={r.time}
+        />
+      ))}
+    </List>
+  )
+
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 880, height: 520 }}>
+      <Box paddingX={4} paddingY={3}>
+        <Inline justify="between" wrap={false}>
+          <Inline gap={2} wrap={false}>
+            <IconTile tone="accent" size={24}>
+              <CircleCheck />
+            </IconTile>
+            <Text variant="label-md">검토 센터</Text>
+            <Progress value={reviewed} max={TOTAL} size="sm" tone="accent" aria-label="검토 진행률" style={{ width: 72 }} />
+            <Text variant="label-sm" numeric>
+              {reviewed} / {TOTAL} 검토
+            </Text>
+            <Text variant="caption" tone="tertiary">
+              가장 오래된 요청 2시간
+            </Text>
+          </Inline>
+          <Button variant="ghost" size="sm" icon={<Undo2 />} shortcut="Z" hotkey disabled={done.length === 0 || pending} onClick={undo}>
+            실행 취소
+          </Button>
+        </Inline>
+      </Box>
+
+      <SplitView
+        resizable
+        defaultListWidth={300}
+        listLabel="요청 목록"
+        detailLabel="요청 내용"
+        style={{ flex: 1, minHeight: 0 }}
+        list={
+          <Tabs value={tab} onValueChange={setTab}>
+            <TabList size="sm" aria-label="요청 거르기">
+              <Tab value="all" count={queue.length}>
+                전체
+              </Tab>
+              <Tab value="risk" count={queue.filter((r) => r.risk).length}>
+                위험 높음
+              </Tab>
+            </TabList>
+            <TabPanel value="all">{rows(queue)}</TabPanel>
+            <TabPanel value="risk">{rows(queue.filter((r) => r.risk))}</TabPanel>
+          </Tabs>
+        }
+      >
+        {selected ? (
+          <>
+            <Box padding={5}>
+              <Stack gap={4}>
+                <Inline gap={2}>
+                  <Text variant="label-md">{selected.from}</Text>
+                  {selected.risk && (
+                    <Badge tone="danger" size="sm">
+                      위험 높음
+                    </Badge>
+                  )}
+                  <Text variant="caption" tone="tertiary">
+                    {selected.kind} · {selected.time} 전
+                  </Text>
+                </Inline>
+                <Text variant="heading-sm">{selected.title}</Text>
+                <Text variant="body-md" tone="secondary">
+                  {selected.note}
+                </Text>
+                <Grid columns={2} gap={4} style={{ maxWidth: 360 }}>
+                  <Stack gap={1}>
+                    <Text variant="caption" tone="tertiary">
+                      금액
+                    </Text>
+                    <Text variant="label-md" numeric>
+                      {selected.amount}
+                    </Text>
+                  </Stack>
+                  <Stack gap={1}>
+                    <Text variant="caption" tone="tertiary">
+                      기한
+                    </Text>
+                    <Text variant="label-md">{selected.due}</Text>
+                  </Stack>
+                </Grid>
+              </Stack>
+            </Box>
+            <ActionBar pending={pending} aria-label="요청 처리">
+              <Button variant="primary" icon={<Check />} shortcut="A" hotkey loading={pending} onClick={act}>
+                승인
+              </Button>
+              <Button variant="ghost" icon={<Pencil />} shortcut="E" hotkey onClick={act}>
+                수정
+              </Button>
+              <Button variant="ghost" icon={<X />} shortcut="R" hotkey onClick={act}>
+                거절
+              </Button>
+              <Button variant="ghost" icon={<ChevronsRight />} shortcut="S" hotkey onClick={act}>
+                건너뛰기
+              </Button>
+            </ActionBar>
+          </>
+        ) : (
+          <Box padding={6}>
+            <Text variant="body-md" tone="tertiary" align="center">
+              모든 요청을 검토했어요.
+            </Text>
+          </Box>
+        )}
+      </SplitView>
+    </Card>
+  )
+}
+```
+
+### 너비 제어
+
+listWidth / onListWidthChange로 제어해요. 경계를 끄는 동안엔 포인터를 그대로 따르고, 키보드 · 버튼으로 바꾸면 부드럽게 움직여요. 끄는 중 Esc는 원래 너비로, 더블 클릭 · Enter는 기본 너비로 돌아가요.
+
+```tsx
+import { useState } from 'react'
+import { Bell, Lock, User } from 'lucide-react'
+import { Box, Button, Inline, Stack, Text, Card, List, ListItem, SplitView } from '@iamfiro/design'
+
+const SECTIONS = [
+  { id: 'profile', icon: <User />, title: '프로필', body: '이름, 사진, 소개를 바꿔요. 김민지 님의 프로필은 팀원 모두에게 보여요.' },
+  { id: 'alarm', icon: <Bell />, title: '알림', body: '멘션과 승인 요청만 바로 알려 드리고, 나머지는 하루 한 번 모아서 보내요.' },
+  { id: 'security', icon: <Lock />, title: '보안', body: '2단계 인증이 켜져 있어요. 마지막 로그인은 10월 25일 오전 9시예요.' },
+]
+
+export default function Example() {
+  const [width, setWidth] = useState(220)
+  const [selected, setSelected] = useState('profile')
+  const section = SECTIONS.find((s) => s.id === selected) ?? SECTIONS[0]
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 640 }}>
+      <Inline gap={2}>
+        <Text variant="caption" tone="tertiary" numeric>
+          목록 너비 {width}px
+        </Text>
+        <Button size="sm" variant="ghost" onClick={() => setWidth(180)}>
+          좁게
+        </Button>
+        <Button size="sm" variant="ghost" onClick={() => setWidth(300)}>
+          넓게
+        </Button>
+      </Inline>
+      <Card padding="none" style={{ height: 280 }}>
+        <SplitView
+          resizable
+          listWidth={width}
+          onListWidthChange={setWidth}
+          minListWidth={160}
+          maxListWidth={360}
+          listLabel="설정 목록"
+          detailLabel="설정 내용"
+          list={
+            <List aria-label="설정">
+              {SECTIONS.map((s) => (
+                <ListItem key={s.id} variant="raised" leading={s.icon} title={s.title} selected={selected === s.id} onClick={() => setSelected(s.id)} />
+              ))}
+            </List>
+          }
+        >
+          <Box padding={5}>
+            <Stack gap={2}>
+              <Text variant="heading-sm">{section.title}</Text>
+              <Text variant="body-md" tone="secondary">
+                {section.body}
+              </Text>
+            </Stack>
+          </Box>
+        </SplitView>
+      </Card>
+    </Stack>
+  )
+}
+```

package/agents/stat/AGENTS.md

@@ -0,0 +1,138 @@
+# Stat
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+라벨과 숫자 하나. 옅은 라벨, 굵은 값, 옅은 "/ 전체"나 단위, 그리고 증감(Delta) 자리로 이뤄져요. 한 줄(inline)로 행 안에 넣거나, 라벨 위 큰 숫자(stacked)로 지표 띠를 만들어요. StatGroup은 여러 Stat을 옅은 세로선으로 나눠 한 줄에 놓고, 좁아지면 줄을 바꿔요.
+
+```tsx
+import { Stat, StatGroup } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 표 칸 · KPI 카드의 작은 추이는 `SparkLine` · `SparkArea` · `Sparkbar`(같은 props, 하나로 고르면 `SparkChart type`). 축 없음, 실제 픽셀 크기로 그려 24–40px에서도 또렷하게, 값 범위는 0이 아니라 최솟값–최댓값. 색은 `tone="trend"` + `higherIs`(Delta와 같은 규칙), 마지막 값은 `endDot`. 긴 표에선 `tooltip={false}`로 이벤트 없는 정적 그림(`role="img"`). KPI 카드는 Card 안 `Stat` + `Delta` + `SparkArea`.
+- 라벨 + 숫자는 `Stat`(한 줄 "시간 1:52 / 2:55" 또는 오버라인 라벨 위 큰 숫자), 지표 띠는 `StatGroup`(칸 사이 `Separator`, 줄이 바뀌어도 줄 첫 칸 앞엔 선 없음).
+- 단독 개수 타일("완료 137 / 실패 3")은 `Stat tile icon iconTone`. 카드 · 팝오버 안의 옅은 회색 패널은 모서리 `--r-panel`(12px) + 여백 12px.
+
+## API
+
+### Stat
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 무엇을 잰 값인지. |
+| `value` (필수) | `ReactNode` |  | 형식을 맞춘 값("1:52", "₩8,500"). |
+| `total` | `ReactNode` |  | 값이 속한 전체. 옅게 "/ 전체"로 붙어요. |
+| `unit` | `ReactNode` |  | 값 뒤 옅은 단위("초", "건"). |
+| `delta` | `ReactNode` |  | 값 뒤 증감 자리. 보통 <Delta>. |
+| `caption` | `ReactNode` |  | 값 아래 옅은 한 줄(stacked). |
+| `layout` | `'stacked' \| 'inline'` | `'stacked'` | 라벨 위 큰 숫자 / 한 줄. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 값 크기(number-sm · md · lg 역할). |
+| `tone` | `TextTone` | `'default'` | 값 색. 오류가 있으면 danger 같은 식으로. |
+| `tile` | `boolean` |  | 옅은 회색 패널(--surface-active, 모서리 12, 여백 12)로 감싼 단독 타일. |
+| `icon` | `ReactNode` |  | 라벨 앞 작은 아이콘. IconTile 네모 안에 들어가요. |
+| `iconTone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | 아이콘 네모의 색. |
+| `className` | `string` |  | 추가 클래스. |
+| `style` | `CSSProperties` |  | 인라인 스타일. |
+
+### StatGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | Stat들(또는 아무 칸). |
+| `gap` | `Space` | `6` | 칸 사이 간격. 세로선은 그 가운데에 놓여요. |
+| `minItemWidth` | `number` | `96` | 칸의 최소 폭(px). 모자라면 줄을 바꿔요. |
+| `fill` | `boolean` | `true` | 칸이 폭을 똑같이 나눠 가질지, 내용 폭만 쓸지. |
+| `dividers` | `boolean` | `true` | 칸 사이 옅은 세로선. |
+| `aria-label` | `string` |  | 묶음 이름("배포 지표"). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 한 줄
+
+layout="inline": "시간 1:52 / 2:55"처럼 행 · 카드 아래쪽에 넣는 짧은 지표.
+
+```tsx
+import { Delta, Inline, Stack, Stat } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Inline gap={5}>
+        <Stat layout="inline" label="시간" value="1:52" total="2:55" />
+        <Stat layout="inline" label="비용" value="₩8,500" total="₩10,300" />
+        <Stat layout="inline" label="완료" value="7" total="12" />
+      </Inline>
+      <Inline gap={5}>
+        <Stat layout="inline" size="sm" label="빌드" value="48" unit="초" delta={<Delta value={-6} higherIs="worse" format={(n) => `${n}초`} size="sm" />} />
+        <Stat layout="inline" size="sm" label="경고" value="3" unit="건" tone="warning" />
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 라벨 위 숫자
+
+layout="stacked"(기본): 오버라인 라벨 + 큰 숫자. size로 숫자 크기를, delta로 증감을 붙여요.
+
+```tsx
+import { Delta, Grid, Stat } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Grid minItemWidth={160} gap={6} style={{ width: '100%' }}>
+      <Stat size="sm" label="이번 주 배포" value="14" unit="회" />
+      <Stat label="평균 리뷰 시간" value="3.2" unit="시간" delta={<Delta value={-0.8} higherIs="worse" format={(n) => `${n}시간`} size="sm" />} />
+      <Stat size="lg" label="활성 사용자" value="12,480" delta={<Delta value={4.2} format={(n) => `${n}%`} arrow size="sm" />} caption="지난주 11,977명" />
+    </Grid>
+  )
+}
+```
+
+### 타일
+
+tile: 옅은 회색 패널(모서리 12, 촘촘한 여백) 안의 Stat. icon은 라벨 앞 색 네모(IconTile)로 들어가고, iconTone으로 상태색을 고르며, 숫자 색은 tone으로 따로 정해요.
+
+```tsx
+import { Check, Clock, X } from 'lucide-react'
+import { Grid, Stat } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Grid columns={3} gap={2} style={{ width: '100%', maxWidth: 420 }}>
+      <Stat tile icon={<Check />} iconTone="success" label="완료" value="137" />
+      <Stat tile icon={<X />} iconTone="danger" label="실패" value="3" tone="danger" />
+      <Stat tile icon={<Clock />} label="대기" value="12" unit="건" />
+    </Grid>
+  )
+}
+```
+
+### StatGroup
+
+지표 띠. 칸 사이 세로선은 Separator이고, 줄이 바뀌어도 각 줄의 첫 칸 앞에는 선이 생기지 않아요. 미리보기 폭을 줄여 보세요.
+
+```tsx
+import { Delta, Card, CardBody, CardHeader, Stat, StatGroup } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card style={{ width: '100%' }}>
+      <CardHeader title="배포 #1284" description="main · 10월 25일 오후 2:14" />
+      <CardBody>
+        <StatGroup aria-label="배포 지표">
+          <Stat label="소요 시간" value="25" unit="초" />
+          <Stat label="비용" value="₩2,500" />
+          <Stat label="요청" value="128" />
+          <Stat label="캐시 적중" value="92%" />
+          <Stat label="재시도" value="3" delta={<Delta value={2} higherIs="worse" size="sm" />} />
+          <Stat label="오류" value="0" />
+        </StatGroup>
+      </CardBody>
+    </Card>
+  )
+}
+```