@iamfiro/design 0.0.0-stage → 0.3.0

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>
+  )
+}
+```

package/agents/status-icon/AGENTS.md

@@ -0,0 +1,243 @@
+# StatusIcon
+
+> 아이콘 & 아바타 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+체크리스트 · 일정 행 앞에 붙는 작은 단계 아이콘. 대기는 회색 점선 원, 진행 중은 파란 링(돌거나 채워짐), 완료는 회색 체크, 오류는 빨간 ×, 확인 필요는 주황 !예요. 모든 상태가 svg 하나에 들어 있어 상태가 바뀌면 링이 차오르고 체크가 그려지며 자연스럽게 넘어가요.
+
+```tsx
+import { StatusIcon } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 단계 행 앞 아이콘은 `StatusIcon`(대기 = 회색 점선 원, 진행 = 파란 링, 완료 = 회색 체크, 오류 · 확인 필요). 상태마다 아이콘을 바꿔 끼우지 않고 한 svg 안에서 전환한다.
+- 읽기 전용 단계 타임라인(계획 · 활동 기록 · 승인 흐름)은 `StepList`(`ol`, 마커 + 연결선, `meta` 시간, 아래 내용엔 Collapsible inline). 번호 원은 `StatusIcon number`(`persistNumber`면 모든 상태에서 번호). 사용자가 체크하는 목록은 `ProgressTracker`. 카드 아래 상태 띠는 `CardFooter band`.
+
+## API
+
+### StatusIcon
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `status` (필수) | `'pending' \| 'active' \| 'done' \| 'error' \| 'warning'` |  | 단계 상태. |
+| `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | 크기(px 숫자도 가능). |
+| `progress` | `number` |  | active일 때 0–100. 생략하면 링이 계속 돌아요. |
+| `colored` | `boolean` |  | 완료를 회색 대신 초록으로. |
+| `number` | `number \| string` |  | 대기 상태를 회색 실선 원 + 번호("5")로. 다른 상태에선 링 · 기호로 넘어가요. |
+| `persistNumber` | `boolean` |  | number와 함께: 모든 상태에서 번호를 남기고 테두리가 상태 색(완료 회색 · 진행 파랑 · 오류 빨강 · 확인 주황)이 돼요. |
+| `label` | `string` |  | 스크린 리더가 읽을 이름. 기본은 "완료", "진행 중 40%"처럼 상태 이름이에요. |
+| `decorative` | `boolean` |  | 옆 글자가 이미 상태를 말할 때 스크린 리더에서 숨겨요. |
+| `className` | `string` |  | 추가 클래스. |
+| `style` | `CSSProperties` |  | 인라인 스타일. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 상태
+
+pending · active · done · error · warning. colored를 주면 완료가 초록이 돼요.
+
+```tsx
+import { Inline, StatusIcon, Text, type StatusIconStatus } from '@iamfiro/design'
+
+const STATES: Array<{ status: StatusIconStatus; label: string }> = [
+  { status: 'pending', label: '대기' },
+  { status: 'active', label: '진행 중' },
+  { status: 'done', label: '완료' },
+  { status: 'error', label: '오류' },
+  { status: 'warning', label: '확인 필요' },
+]
+
+export default function Example() {
+  return (
+    <Inline gap={6}>
+      {STATES.map((s) => (
+        <Inline key={s.status} gap={2} wrap={false}>
+          <StatusIcon status={s.status} decorative />
+          <Text variant="label-sm">{s.label}</Text>
+        </Inline>
+      ))}
+      <Inline gap={2} wrap={false}>
+        <StatusIcon status="done" colored decorative />
+        <Text variant="label-sm">완료 (colored)</Text>
+      </Inline>
+    </Inline>
+  )
+}
+```
+
+### 작업 단계
+
+ListItem의 leading에 놓아 단계 목록을 만들어요. 버튼을 눌러 상태가 바뀌는 움직임을 확인해 보세요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, StatusIcon, type StatusIconStatus, List, ListItem } from '@iamfiro/design'
+
+const STEPS = [
+  { id: 'lint', title: '코드 검사', description: '규칙 위반 0건' },
+  { id: 'test', title: '테스트', description: '412개 통과' },
+  { id: 'build', title: '빌드', description: '번들 크기 확인 중' },
+  { id: 'deploy', title: '운영 배포', description: '서울 리전' },
+  { id: 'notify', title: '팀에 알리기', description: '#release 채널' },
+]
+
+export default function Example() {
+  // Index of the step in progress; steps before it are done.
+  const [current, setCurrent] = useState(2)
+  const [failed, setFailed] = useState(false)
+
+  const statusOf = (i: number): StatusIconStatus => {
+    if (i < current) return 'done'
+    if (i === current) return failed ? 'error' : 'active'
+    return 'pending'
+  }
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      <List label="배포 단계">
+        {STEPS.map((s, i) => (
+          <ListItem
+            key={s.id}
+            leading={<StatusIcon status={statusOf(i)} />}
+            title={s.title}
+            description={i === current && failed ? '빌드 스크립트가 종료 코드 1로 끝났어요' : s.description}
+          />
+        ))}
+      </List>
+      <Inline gap={2}>
+        <Button
+          variant="primary"
+          size="sm"
+          disabled={current >= STEPS.length}
+          onClick={() => {
+            setFailed(false)
+            setCurrent((c) => c + 1)
+          }}
+        >
+          다음 단계
+        </Button>
+        <Button size="sm" disabled={current >= STEPS.length} onClick={() => setFailed((f) => !f)}>
+          {failed ? '다시 시도' : '실패로 표시'}
+        </Button>
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={() => {
+            setFailed(false)
+            setCurrent(0)
+          }}
+        >
+          처음부터
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 번호
+
+number를 주면 대기 상태가 점선 원 대신 회색 실선 원 + 번호가 돼요. 시작하면 링으로, 끝나면 체크로 넘어가요. persistNumber면 모든 상태에서 번호가 남고 테두리 색만 상태를 따라가요(번호 타임라인).
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, StatusIcon, Text, type StatusIconStatus } from '@iamfiro/design'
+
+const ORDER: StatusIconStatus[] = ['pending', 'active', 'done']
+
+export default function Example() {
+  const [step, setStep] = useState(0)
+  const status = ORDER[step]
+  return (
+    <Stack gap={5}>
+      <Inline gap={6}>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="pending" number={5} size="lg" decorative />
+          <Text variant="label-sm">대기 (number)</Text>
+        </Inline>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="pending" number={12} size="lg" decorative />
+          <Text variant="label-sm">두 자리</Text>
+        </Inline>
+      </Inline>
+      <Inline gap={4}>
+        {(['pending', 'active', 'done', 'error', 'warning'] as const).map((s, i) => (
+          <StatusIcon key={s} status={s} number={i + 1} persistNumber size="lg" />
+        ))}
+        <Text variant="label-sm" tone="secondary">
+          persistNumber
+        </Text>
+      </Inline>
+      <Inline gap={3}>
+        <StatusIcon status={status} number={3} size="lg" />
+        <Button size="sm" onClick={() => setStep((s) => (s + 1) % ORDER.length)}>
+          {status === 'pending' ? '시작하기' : status === 'active' ? '완료하기' : '처음으로'}
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 진행률
+
+active에 progress(0–100)를 주면 링이 그만큼 채워지고, 없으면 Spinner처럼 돌아요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, StatusIcon, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [progress, setProgress] = useState(35)
+  const done = progress >= 100
+
+  return (
+    <Stack gap={4} align="start">
+      <Inline gap={6}>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="active" size="lg" />
+          <Text variant="label-sm">파일 정리 중</Text>
+        </Inline>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status={done ? 'done' : 'active'} progress={progress} size="lg" />
+          <Text variant="label-sm" numeric>
+            {done ? '업로드 완료' : `업로드 ${progress}%`}
+          </Text>
+        </Inline>
+      </Inline>
+      <Inline gap={2}>
+        <Button size="sm" disabled={done} onClick={() => setProgress((p) => Math.min(100, p + 25))}>
+          25% 올리기
+        </Button>
+        <Button variant="ghost" size="sm" onClick={() => setProgress(0)}>
+          초기화
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 크기
+
+sm 14 · md 16 · lg 20px, 또는 px 숫자. 텍스트 옆에서도 찌그러지지 않아요(flex: none).
+
+```tsx
+import { Inline, StatusIcon } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={6}>
+      {(['sm', 'md', 'lg', 28] as const).map((size) => (
+        <Inline key={size} gap={2} wrap={false}>
+          <StatusIcon status="done" size={size} />
+          <StatusIcon status="active" progress={60} size={size} />
+          <StatusIcon status="pending" size={size} />
+        </Inline>
+      ))}
+    </Inline>
+  )
+}
+```