@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/toolbar/AGENTS.md

@@ -0,0 +1,277 @@
+# Toolbar
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+버튼 · 토글 · ToggleGroup · 메뉴 트리거를 한 줄로 묶는 WAI-ARIA 툴바. Tab 정지점은 툴바 전체에 하나뿐이고, 안에서는 ←→(세로면 ↑↓) · Home · End로 옮겨 다녀요. 다시 Tab으로 들어오면 마지막에 있던 버튼으로 돌아와요. 아이콘 버튼은 label이 이름 · 툴팁이 되고, 툴팁에 단축키 키캡이 함께 보여요. 테두리 없이 plain(여백만) · floating(흰 바탕 + 그림자) 두 가지.
+
+```tsx
+import { Toolbar, ToolbarButton, ToolbarSeparator, ToolbarSpacer } from '@iamfiro/design'
+```
+
+## API
+
+### Toolbar
+
+role="toolbar" + aria-orientation. 안의 button · input · [data-toolbar-item]이 모두 로빙 tabindex 대상이에요(비활성 · 숨김 제외).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | ToolbarButton, ToolbarSeparator, ToggleGroup, DropdownMenu 등. |
+| `aria-label / aria-labelledby` | `string` |  | 툴바 이름("서식"). |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 배치와 화살표 키 방향. |
+| `variant` | `'plain' \| 'floating'` | `'plain'` | plain: 여백만 · floating: 흰 바탕 + 그림자(테두리 없음). |
+| `size` | `'sm' \| 'md'` | `'md'` | 안의 ToolbarButton 크기. ToggleGroup은 size를 직접 맞춰요. |
+| `loop` | `boolean` | `true` | 끝에서 화살표를 누르면 처음으로. |
+| `overflow` | `boolean` |  | 자리가 모자라면 ToolbarButton · ToolbarSeparator를 뒤에서부터 "더보기" 메뉴로(가로만). 이때 툴바는 부모 폭을 채워요. |
+| `overflowLabel` | `string` | `'더보기'` | 더보기 버튼 이름. |
+
+### ToolbarButton
+
+ghost Button 기반. 나머지 Button 속성(icon, iconRight, onClick, hotkey, disabled…)을 그대로 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `string` |  | 하는 일. 아이콘 버튼의 이름 · 툴팁 · 더보기 메뉴 글자. |
+| `children` | `ReactNode` |  | 글자 버튼일 때. 없으면 아이콘만 있는 정사각형 버튼. |
+| `pressed / defaultPressed` | `boolean` |  | 주면 토글 버튼(aria-pressed). 제어 / 비제어. |
+| `onPressedChange` | `(pressed: boolean) => void` |  | 토글이 바뀔 때. |
+| `shortcut` | `string[]` |  | 단축키 힌트(['mod', 'B']). 툴팁 · 더보기 메뉴에 키캡으로. hotkey를 함께 주면 실제로 들어요. |
+| `tooltip` | `boolean \| ReactNode` | `아이콘 버튼이면 true` | 툴팁. false로 끄거나 내용을 바꿔요. |
+| `tooltipSide` | `'top' \| 'bottom' \| 'left' \| 'right'` |  | 기본은 가로 툴바 위, 세로 툴바 오른쪽. |
+| `variant` | `ButtonVariant` | `'ghost'` | 끝의 주요 동작은 primary로. |
+| `collapsible` | `boolean` | `true` | 더보기로 옮겨 갈 수 있는지. DropdownMenu 트리거처럼 클릭이 제 동작이 아닌 버튼은 false. |
+
+### ToolbarSeparator
+
+묶음 사이 짧은 선(가로 툴바면 세로선). role="separator".
+
+### ToolbarSpacer
+
+뒤의 항목을 반대쪽 끝으로 밀어요(flex: 1).
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 글 서식 툴바
+
+실행 취소 · 문단 스타일 메뉴 · 굵게/기울임/밑줄 토글(⌘/Ctrl+B · I · U로도 눌려요) · 정렬 ToggleGroup · 링크 · 더보기 메뉴. Tab으로 들어와 ←→로 이동하고, 메뉴 트리거에선 ↓ · Enter로 메뉴를 열어요. 정렬 묶음 안에서도 화살표는 툴바 전체를 따라 움직이고, Space · Enter로 골라요.
+
+```tsx
+import { useState } from 'react'
+import {
+  AlignCenter,
+  AlignLeft,
+  AlignRight,
+  Bold,
+  ChevronDown,
+  Code,
+  Eraser,
+  Italic,
+  Link,
+  MoreHorizontal,
+  Quote,
+  Redo2,
+  Strikethrough,
+  Table2,
+  Underline,
+  Undo2,
+} from 'lucide-react'
+import { DropdownMenu, DropdownMenuItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, ToolbarSeparator, Stack, Text } from '@iamfiro/design'
+
+const BLOCKS = { body: '본문', h1: '제목 1', h2: '제목 2', h3: '제목 3' } as const
+type Block = keyof typeof BLOCKS
+
+export default function Example() {
+  const [block, setBlock] = useState<Block>('body')
+  const [marks, setMarks] = useState({ bold: true, italic: false, underline: false, strike: false })
+  const [align, setAlign] = useState<string | null>('left')
+  const [last, setLast] = useState('')
+  const mark = (key: keyof typeof marks) => ({
+    pressed: marks[key],
+    onPressedChange: (on: boolean) => setMarks((m) => ({ ...m, [key]: on })),
+  })
+
+  const on = Object.entries(marks)
+    .filter(([, v]) => v)
+    .map(([k]) => ({ bold: '굵게', italic: '기울임', underline: '밑줄', strike: '취소선' })[k])
+
+  return (
+    <Stack gap={4} align="start">
+      <Toolbar aria-label="서식" variant="floating">
+        <ToolbarButton label="실행 취소" icon={<Undo2 />} shortcut={['mod', 'Z']} onClick={() => setLast('실행 취소')} />
+        <ToolbarButton label="다시 실행" icon={<Redo2 />} shortcut={['mod', 'shift', 'Z']} onClick={() => setLast('다시 실행')} />
+        <ToolbarSeparator />
+        <DropdownMenu
+          minWidth={160}
+          trigger={
+            <ToolbarButton label="문단 스타일" iconRight={<ChevronDown />} tooltip collapsible={false}>
+              {BLOCKS[block]}
+            </ToolbarButton>
+          }
+        >
+          <DropdownMenuRadioGroup value={block} onValueChange={(v) => setBlock(v as Block)}>
+            {(Object.keys(BLOCKS) as Block[]).map((k) => (
+              <DropdownMenuRadioItem key={k} value={k}>
+                {BLOCKS[k]}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
+        </DropdownMenu>
+        <ToolbarSeparator />
+        <ToolbarButton label="굵게" icon={<Bold />} shortcut={['mod', 'B']} hotkey {...mark('bold')} />
+        <ToolbarButton label="기울임" icon={<Italic />} shortcut={['mod', 'I']} hotkey {...mark('italic')} />
+        <ToolbarButton label="밑줄" icon={<Underline />} shortcut={['mod', 'U']} hotkey {...mark('underline')} />
+        <ToolbarButton label="취소선" icon={<Strikethrough />} shortcut={['mod', 'shift', 'X']} {...mark('strike')} />
+        <ToolbarSeparator />
+        <ToggleGroup type="single" required variant="ghost" value={align} onValueChange={setAlign} aria-label="정렬">
+          <ToggleGroupItem value="left" icon={<AlignLeft />} aria-label="왼쪽 정렬" />
+          <ToggleGroupItem value="center" icon={<AlignCenter />} aria-label="가운데 정렬" />
+          <ToggleGroupItem value="right" icon={<AlignRight />} aria-label="오른쪽 정렬" />
+        </ToggleGroup>
+        <ToolbarSeparator />
+        <ToolbarButton label="링크" icon={<Link />} shortcut={['mod', 'K']} onClick={() => setLast('링크 넣기')} />
+        <DropdownMenu align="end" trigger={<ToolbarButton label="더보기" icon={<MoreHorizontal />} collapsible={false} />}>
+          <DropdownMenuItem icon={<Quote />} onSelect={() => setLast('인용')}>
+            인용
+          </DropdownMenuItem>
+          <DropdownMenuItem icon={<Code />} shortcut={['mod', 'E']} onSelect={() => setLast('코드 블록')}>
+            코드 블록
+          </DropdownMenuItem>
+          <DropdownMenuItem icon={<Table2 />} onSelect={() => setLast('표 넣기')}>
+            표 넣기
+          </DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem icon={<Eraser />} onSelect={() => setMarks({ bold: false, italic: false, underline: false, strike: false })}>
+            서식 지우기
+          </DropdownMenuItem>
+        </DropdownMenu>
+      </Toolbar>
+      <Text variant="body-sm" tone="secondary">
+        {BLOCKS[block]} · {on.length ? on.join(', ') : '서식 없음'} · {{ left: '왼쪽', center: '가운데', right: '오른쪽' }[align ?? 'left']} 정렬
+        {last && ` · 방금: ${last}`}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### plain · 목록 위 도구
+
+글자 버튼은 툴팁 없이(tooltip={false}), ToolbarSpacer로 뒤쪽 버튼을 오른쪽 끝에 붙여요. 토글은 눌리면 회색 채움이 자라나요.
+
+```tsx
+import { useState } from 'react'
+import { ArrowDownUp, Download, LayoutGrid, List, ListFilter, Plus } from 'lucide-react'
+import { ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, ToolbarSeparator, ToolbarSpacer, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [view, setView] = useState<string | null>('list')
+  const [filtered, setFiltered] = useState(false)
+  return (
+    <Stack gap={3}>
+      <Toolbar aria-label="문서 목록 도구" size="sm" style={{ width: '100%' }}>
+        <ToolbarButton label="필터" icon={<ListFilter />} pressed={filtered} onPressedChange={setFiltered} tooltip={false}>
+          필터
+        </ToolbarButton>
+        <ToolbarButton label="정렬" icon={<ArrowDownUp />} tooltip={false}>
+          최근 수정순
+        </ToolbarButton>
+        <ToolbarSeparator />
+        <ToggleGroup type="single" required size="sm" variant="ghost" value={view} onValueChange={setView} aria-label="보기">
+          <ToggleGroupItem value="list" icon={<List />} aria-label="목록으로 보기" />
+          <ToggleGroupItem value="grid" icon={<LayoutGrid />} aria-label="격자로 보기" />
+        </ToggleGroup>
+        <ToolbarSpacer />
+        <ToolbarButton label="내보내기" icon={<Download />} />
+        <ToolbarButton label="새 문서" variant="primary" icon={<Plus />} tooltip={false}>
+          새 문서
+        </ToolbarButton>
+      </Toolbar>
+      <Text variant="body-sm" tone="secondary">
+        {filtered ? '필터 적용됨' : '전체 문서'} · {view === 'grid' ? '격자' : '목록'} 보기
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 세로 · 그리기 도구
+
+orientation='vertical'이면 ↑↓로 이동하고 툴팁은 오른쪽에 떠요. 구분선도 가로로 바뀌어요.
+
+```tsx
+import { useState } from 'react'
+import { Circle, Hand, MousePointer2, Pen, Square, Type, ZoomIn, ZoomOut } from 'lucide-react'
+import { ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, ToolbarSeparator, Inline, Text } from '@iamfiro/design'
+
+const TOOLS = { select: '선택', hand: '손', rect: '사각형', ellipse: '원', pen: '펜', text: '텍스트' } as const
+
+export default function Example() {
+  const [tool, setTool] = useState<string | null>('select')
+  const [zoom, setZoom] = useState(100)
+  return (
+    <Inline gap={6} align="start">
+      <Toolbar aria-label="그리기 도구" orientation="vertical" variant="floating">
+        <ToggleGroup type="single" required orientation="vertical" variant="ghost" value={tool} onValueChange={setTool} aria-label="도구">
+          <ToggleGroupItem value="select" icon={<MousePointer2 />} aria-label="선택 (V)" />
+          <ToggleGroupItem value="hand" icon={<Hand />} aria-label="손 (H)" />
+          <ToggleGroupItem value="rect" icon={<Square />} aria-label="사각형 (R)" />
+          <ToggleGroupItem value="ellipse" icon={<Circle />} aria-label="원 (O)" />
+          <ToggleGroupItem value="pen" icon={<Pen />} aria-label="펜 (P)" />
+          <ToggleGroupItem value="text" icon={<Type />} aria-label="텍스트 (T)" />
+        </ToggleGroup>
+        <ToolbarSeparator />
+        <ToolbarButton label="확대" icon={<ZoomIn />} shortcut={['mod', '=']} disabled={zoom >= 400} onClick={() => setZoom((z) => z * 2)} />
+        <ToolbarButton label="축소" icon={<ZoomOut />} shortcut={['mod', '-']} disabled={zoom <= 25} onClick={() => setZoom((z) => z / 2)} />
+      </Toolbar>
+      <Text variant="body-sm" tone="secondary" numeric>
+        도구: {TOOLS[tool as keyof typeof TOOLS]} · 확대 {zoom}%
+      </Text>
+    </Inline>
+  )
+}
+```
+
+### 자리가 모자라면 더보기로
+
+overflow를 주면 들어가지 않는 버튼이 뒤에서부터 "더보기" 메뉴로 옮겨 가요. 토글은 메뉴에서 체크 항목이 되고, 단축키 힌트도 그대로 따라가요. 폭을 줄여 보세요.
+
+```tsx
+import { useState } from 'react'
+import { Bold, Code, Highlighter, Image, Italic, Link, List, ListOrdered, Quote, Strikethrough, Underline } from 'lucide-react'
+import { Slider, Toolbar, ToolbarButton, ToolbarSeparator, Box, Field, Stack } from '@iamfiro/design'
+
+export default function Example() {
+  const [width, setWidth] = useState(300)
+  const [marks, setMarks] = useState<Record<string, boolean>>({ bold: false, italic: true })
+  const toggle = (key: string) => ({
+    pressed: !!marks[key],
+    onPressedChange: (on: boolean) => setMarks((m) => ({ ...m, [key]: on })),
+  })
+  return (
+    <Stack gap={5}>
+      <Field label="툴바 폭">
+        <Slider value={width} onValueChange={setWidth} min={160} max={560} step={10} formatValue={(v) => `${v}px`} aria-label="툴바 폭" />
+      </Field>
+      <Box style={{ width }}>
+        <Toolbar aria-label="댓글 서식" variant="floating" overflow>
+          <ToolbarButton label="굵게" icon={<Bold />} shortcut={['mod', 'B']} {...toggle('bold')} />
+          <ToolbarButton label="기울임" icon={<Italic />} shortcut={['mod', 'I']} {...toggle('italic')} />
+          <ToolbarButton label="밑줄" icon={<Underline />} shortcut={['mod', 'U']} {...toggle('underline')} />
+          <ToolbarButton label="취소선" icon={<Strikethrough />} {...toggle('strike')} />
+          <ToolbarButton label="형광펜" icon={<Highlighter />} {...toggle('highlight')} />
+          <ToolbarSeparator />
+          <ToolbarButton label="글머리 목록" icon={<List />} />
+          <ToolbarButton label="번호 목록" icon={<ListOrdered />} />
+          <ToolbarButton label="인용" icon={<Quote />} />
+          <ToolbarSeparator />
+          <ToolbarButton label="링크" icon={<Link />} shortcut={['mod', 'K']} />
+          <ToolbarButton label="이미지" icon={<Image />} />
+          <ToolbarButton label="코드" icon={<Code />} shortcut={['mod', 'E']} />
+        </Toolbar>
+      </Box>
+    </Stack>
+  )
+}
+```

package/agents/tooltip/AGENTS.md

@@ -0,0 +1,154 @@
+# Tooltip
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+아이콘 버튼처럼 글자가 없는 요소에 짧은 설명을 붙여요. 마우스는 500ms 머물러야 열려서 툴바를 훑고 지나갈 때 깜빡이지 않고, 하나가 열린 뒤(또는 닫힌 지 300ms 안에) 옆으로 옮기면 기다림 없이 바로 열려요. 키보드 포커스는 즉시 열리고, 누르거나 Esc를 누르면 닫혀요.
+
+```tsx
+import { Tooltip } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 툴팁: 첫 번째는 `TIMING.tooltipDelay`(500ms) 뒤, 닫힌 지 `TIMING.tooltipSkip`(300ms) 안에 옆 툴팁으로 옮기면 즉시. 단 "즉시"는 **이미 기다린 시간만큼만** 건너뛴다 — `delay={0}` 툴팁을 거쳐 왔다고 `delay={1000}` 툴팁이 바로 열리면 안 된다(대기 시간 고장 버그). 키보드 포커스는 즉시, 누르면 닫고, Esc로 닫힌다. → `Tooltip`
+- 아바타는 hover하면 이름 `Tooltip`이 기본(`tooltip={false}`로 끔). `title` 속성 툴팁은 쓰지 않는다.
+
+## API
+
+### Tooltip
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `content` (필수) | `ReactNode` |  | 말풍선 내용. 짧은 글자나 작은 인라인 요소(Kbd 등). |
+| `children` (필수) | `ReactNode` |  | 툴팁을 붙일 트리거. 아이콘 버튼이면 aria-label도 함께 주세요. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | 말풍선이 열리는 방향. |
+| `delay` | `number` | `500` | 마우스를 올린 뒤 첫 툴팁이 열리기까지(ms). 다른 툴팁이 열려 있거나 닫힌 지 300ms(TIMING.tooltipSkip) 안이면 그 툴팁에서 이미 기다린 시간만큼 빼고 기다려요(같은 delay끼리는 즉시). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 툴바
+
+첫 툴팁은 잠깐 기다렸다 열리고, 그다음부터는 옆 버튼으로 옮기는 즉시 바뀌어요. Tab으로 이동해도 바로 보여요.
+
+```tsx
+import { Bold, Code, Italic, Link, List, Strikethrough, Underline } from 'lucide-react'
+import { Button, Tooltip } from '@iamfiro/design'
+
+const TOOLS = [
+  { label: '굵게', icon: <Bold /> },
+  { label: '기울임', icon: <Italic /> },
+  { label: '밑줄', icon: <Underline /> },
+  { label: '취소선', icon: <Strikethrough /> },
+  { label: '링크 삽입', icon: <Link /> },
+  { label: '목록', icon: <List /> },
+  { label: '코드', icon: <Code /> },
+]
+
+export default function Example() {
+  return (
+    <div role="toolbar" aria-label="서식" style={{ display: 'flex', gap: 4 }}>
+      {TOOLS.map((tool) => (
+        <Tooltip key={tool.label} content={tool.label}>
+          <Button iconOnly variant="ghost" icon={tool.icon} aria-label={tool.label} />
+        </Tooltip>
+      ))}
+    </div>
+  )
+}
+```
+
+### 방향
+
+side로 위 · 아래 · 왼쪽 · 오른쪽. 열릴 때 트리거 쪽에서 살짝 밀려 나와요.
+
+```tsx
+import { Button, Tooltip, type TooltipSide } from '@iamfiro/design'
+
+const SIDES: Array<[TooltipSide, string]> = [
+  ['top', '위'],
+  ['bottom', '아래'],
+  ['left', '왼쪽'],
+  ['right', '오른쪽'],
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', gap: 16 }}>
+      {SIDES.map(([side, label]) => (
+        <Tooltip key={side} side={side} content={`${label}에 열려요`}>
+          <Button variant="secondary">{label}</Button>
+        </Tooltip>
+      ))}
+    </div>
+  )
+}
+```
+
+### 단축키 함께 보여주기
+
+content에 Kbd를 넣으면 어두운 말풍선에 맞춰 키캡 색이 바뀌어요.
+
+```tsx
+import { Bell, Plus, Search } from 'lucide-react'
+import { Button, Kbd, Tooltip } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <Tooltip
+        content={
+          <>
+            검색 <Kbd keys={['mod', 'K']} size="sm" />
+          </>
+        }
+      >
+        <Button iconOnly variant="ghost" icon={<Search />} aria-label="검색" aria-keyshortcuts="Meta+K Control+K" />
+      </Tooltip>
+      <Tooltip
+        content={
+          <>
+            새 문서 <Kbd keys={['C']} size="sm" />
+          </>
+        }
+      >
+        <Button iconOnly variant="ghost" icon={<Plus />} aria-label="새 문서" aria-keyshortcuts="C" />
+      </Tooltip>
+      <Tooltip
+        content={
+          <>
+            알림 <Kbd keys={['G', 'N']} separator="다음" size="sm" />
+          </>
+        }
+      >
+        <Button iconOnly variant="ghost" icon={<Bell />} aria-label="알림" />
+      </Tooltip>
+    </div>
+  )
+}
+```
+
+### 대기 시간
+
+delay로 첫 툴팁의 대기 시간을 바꿔요. 기본값(TIMING.tooltipDelay, 500ms)을 쓰는 게 좋아요. 옆 툴팁이 막 열려 있었다면 이미 기다린 시간만큼은 건너뛰어요. 기본(500ms) 툴팁을 보다가 delay 1000으로 옮기면 남은 500ms만, delay 0을 보다 옮기면 1초를 다 기다려요.
+
+```tsx
+import { Button, Tooltip } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', gap: 16 }}>
+      <Tooltip content="바로 열려요" delay={0}>
+        <Button variant="secondary">delay 0</Button>
+      </Tooltip>
+      <Tooltip content="0.5초 뒤에 열려요">
+        <Button variant="secondary">기본 (500ms)</Button>
+      </Tooltip>
+      <Tooltip content="1초 뒤에 열려요" delay={1000}>
+        <Button variant="secondary">delay 1000</Button>
+      </Tooltip>
+    </div>
+  )
+}
+```

package/agents/tracker/AGENTS.md

@@ -0,0 +1,158 @@
+# Tracker
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+하루(또는 한 시간)에 한 칸씩 상태를 색으로 늘어놓은 기록 띠. 가동률 · 배포 · 장애 이력을 한눈에 보여 줘요. 띠의 양 끝만 둥글고 안쪽 칸은 작은 모서리예요. 처음엔 칸이 왼쪽부터 차례로 올라오고, 마우스를 올리면 날짜와 상태가 차트 툴팁 카드에 떠요. 첫 툴팁은 잠깐 기다린 뒤 열리고, 그다음 칸으로 옮기면 바로 바뀌어요.
+
+```tsx
+import { Tracker } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 상태 이력(가동률 · 배포 · 장애)은 `Tracker`: 같은 칸이 2–3px 간격으로, 띠의 양 끝만 둥글고 안쪽 칸은 2px. 정상 `--success` · 배포/기록 없음 회색 · 장애 빨강 · 저하 주황. 툴팁은 portal(fixed)로 띄워 Card `overflow: hidden`에 잘리지 않게, 첫 툴팁만 `TIMING.tooltipDelay`.
+
+## API
+
+### Tracker
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `TrackerBlock[]` |  | { key, tone?, color?, tooltip?, status?, value? } 목록. 오래된 칸부터. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 칸 높이 24 · 32 · 40px(fixed일 때 칸 폭 6 · 8 · 10px). |
+| `height` | `number` |  | 칸 높이(px). size보다 우선. |
+| `layout` | `'fill' \| 'fixed'` | `'fill'` | fill: 폭에 맞춰 칸이 줄고 늘어요 · fixed: 칸 폭 고정. |
+| `tooltip` | `boolean` | `true` | 날짜 · 상태 카드 표시. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 고른 칸(제어/비제어). |
+| `aria-label` | `string` | `'상태 기록'` | 이름. 고른 칸은 aria-live로 읽어요. |
+
+### TrackerBlock
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `key` (필수) | `string` |  | 칸의 고유 키. |
+| `tone` | `'success' \| 'warning' \| 'danger' \| 'neutral' \| 'accent' \| 'empty'` | `'success'` | 정상 · 성능 저하 · 장애 · 배포 · 점검 · 기록 없음. |
+| `color` | `string` |  | tone 대신 쓸 색. CSS 변수 이름('--chart-3') 또는 색. |
+| `tooltip` | `ReactNode` |  | 툴팁 제목(보통 날짜). |
+| `status` | `ReactNode` |  | 툴팁 행 이름. 기본은 tone 이름("정상", "장애"…). |
+| `value` | `ReactNode` |  | 툴팁 행 오른쪽 값("99.2%"). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+정상은 초록, 배포 · 기록 없음은 회색, 장애는 빨강 · 성능 저하는 주황이에요. 포커스한 뒤 ←/→, Home/End로 칸을 옮기고 Esc로 닫아요.
+
+```tsx
+import { Tracker, type TrackerBlock, type TrackerTone } from '@iamfiro/design'
+
+// 9월 26일 … 10월 25일, 하루에 한 칸. s 정상 · w 성능 저하 · d 장애 · n 배포 · e 기록 없음
+const PATTERN = 'eessssssnssssswssssssdsssnssss'
+const TONES: Record<string, TrackerTone> = { s: 'success', w: 'warning', d: 'danger', n: 'neutral', e: 'empty' }
+const dayLabel = (i: number) => (i < 5 ? `9월 ${26 + i}일` : `10월 ${i - 4}일`)
+
+const DAYS: TrackerBlock[] = PATTERN.split('').map((c, i) => ({ key: `d${i}`, tone: TONES[c], tooltip: dayLabel(i) }))
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', maxWidth: 480 }}>
+      <Tracker data={DAYS} aria-label="최근 30일 상태" />
+    </div>
+  )
+}
+```
+
+### 크기 · 높이 · 칸 폭
+
+size(sm · md · lg)나 height로 높이를 정해요. 기본 layout="fill"은 칸이 폭에 맞춰 줄고 늘며, "fixed"는 칸 폭을 고정해요.
+
+```tsx
+import { Stack, Text, Tracker, type TrackerBlock, type TrackerTone } from '@iamfiro/design'
+
+const PATTERN = 'sssssssssssswsssssssssssssdssssssssssssssssnssssssssssss'
+const TONES: Record<string, TrackerTone> = { s: 'success', w: 'warning', d: 'danger', n: 'neutral' }
+
+// 지난 56시간, 한 시간에 한 칸.
+const HOURS: TrackerBlock[] = PATTERN.split('').map((c, i) => ({ key: `h${i}`, tone: TONES[c], tooltip: `${56 - i}시간 전` }))
+
+export default function Example() {
+  return (
+    <Stack gap={5} style={{ width: '100%', maxWidth: 520 }}>
+      <Stack gap={2}>
+        <Text variant="label-sm">sm · 24px</Text>
+        <Tracker data={HOURS} size="sm" aria-label="시간별 상태" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm">lg · 40px</Text>
+        <Tracker data={HOURS} size="lg" aria-label="시간별 상태" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm">height · 16px</Text>
+        <Tracker data={HOURS} height={16} size="sm" aria-label="시간별 상태" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="label-sm">layout=&quot;fixed&quot; · 칸 폭 고정</Text>
+        <Tracker data={HOURS.slice(-24)} layout="fixed" aria-label="최근 24시간 상태" />
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+### 가동률 카드
+
+CardHeader 아래에 라벨 줄("가동률 99.8%")과 양 끝 날짜("30일 전" … "오늘")를 붙여 조립해요. value는 툴팁 행 오른쪽에 나와요.
+
+```tsx
+import { Badge, Inline, Stack, Text, Card, CardBody, CardHeader, Tracker, type TrackerBlock, type TrackerTone } from '@iamfiro/design'
+
+// s 정상 · w 성능 저하 · d 장애 · n 배포
+const PATTERN = 'sssssnsssssssssswsssssssnsdsss'
+const TONES: Record<string, TrackerTone> = { s: 'success', w: 'warning', d: 'danger', n: 'neutral' }
+const UPTIME: Record<string, string> = { s: '100%', w: '99.1%', d: '97.4%', n: '100%' }
+const dayLabel = (i: number) => (i < 5 ? `9월 ${26 + i}일` : `10월 ${i - 4}일`)
+
+const DAYS: TrackerBlock[] = PATTERN.split('').map((c, i) => ({
+  key: `d${i}`,
+  tone: TONES[c],
+  tooltip: dayLabel(i),
+  value: UPTIME[c],
+}))
+
+export default function Example() {
+  return (
+    <Card style={{ width: '100%', maxWidth: 480 }}>
+      <CardHeader
+        title="API 서버"
+        description="api.example.com"
+        actions={
+          <Badge tone="success" dot>
+            정상 운영
+          </Badge>
+        }
+      />
+      <CardBody>
+        <Stack gap={2}>
+          <Inline justify="between" gap={3}>
+            <Text variant="label-sm">최근 30일</Text>
+            <Text variant="label-sm" tone="secondary" numeric>
+              가동률 99.8%
+            </Text>
+          </Inline>
+          <Tracker data={DAYS} aria-label="API 서버 최근 30일 가동 기록" />
+          <Inline justify="between" gap={3}>
+            <Text variant="caption" tone="tertiary">
+              30일 전
+            </Text>
+            <Text variant="caption" tone="tertiary">
+              오늘
+            </Text>
+          </Inline>
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```