@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/scaled-preview/AGENTS.md

@@ -0,0 +1,111 @@
+# ScaledPreview
+
+> 파운데이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+실제 컴포넌트를 높이가 고정된 무대 가운데에 작게 줄여 보여 줘요. 갤러리 카드 · 템플릿 고르기 · 썸네일처럼 "이렇게 생겼어요"를 보여 줄 때 써요. 내용은 contentWidth 폭으로 배치한 뒤 무대에 맞게 줄고(최대 maxScale), 누르기 · 포커스 · 화면 읽기가 막힌 inert 상태예요. 왼쪽 위 흰 칩(label)과 오른쪽 위 회색 칩(meta)을 얹을 수 있고, lazy면 화면 근처에 있을 때만 실행해서 보이지 않는 미리보기가 타이머를 돌리지 않아요.
+
+```tsx
+import { ScaledPreview } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 실제 컴포넌트를 작게 줄여 보여 주는 썸네일(갤러리 카드 · 템플릿 고르기)은 `ScaledPreview`(고정 높이 무대, 맞춰 줄이기, inert, `label` 흰 칩 · `meta` 회색 칩, 타이머가 도는 내용은 `lazy`로 보일 때만). 필터로 바뀌는 카드 격자는 `Grid stagger` + 필터 값을 `key`로.
+
+## API
+
+### ScaledPreview
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 줄여 보여 줄 실제 내용. inert · aria-hidden이라 누를 수 없어요. |
+| `height` | `number` | `320` | 무대 높이(px). |
+| `contentWidth` | `number` | `520` | 줄이기 전 내용이 배치되는 폭(px). width: 100%인 내용이 자리를 갖게. |
+| `maxScale` | `number` | `0.8` | 가장 큰 배율. 무대에 안 맞으면 더 줄어요. |
+| `minScale` | `number` | `0.3` | 가장 작은 배율. 그래도 넘치면 무대 가장자리에서 잘려요. |
+| `inset` | `number` | `24` | 줄인 내용과 무대 가장자리 사이 여백(px). |
+| `label` | `ReactNode` |  | 왼쪽 위 흰 칩(분류). |
+| `meta` | `ReactNode` |  | 오른쪽 위 회색 칩(개수 · 버전). |
+| `lazy` | `boolean` | `false` | 화면 근처에 있을 때만 내용을 붙여요(IntersectionObserver). |
+| `fallback` | `ReactNode` | `Skeleton` | lazy 미리보기가 화면 밖일 때 보여 줄 것. |
+| `tone` | `'subtle' \| 'surface'` | `'subtle'` | subtle = 가장 옅은 회색 무대 · surface = 흰 무대(회색 판 안에서). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 갤러리 카드
+
+Card padding="sm" 안에 ScaledPreview + 제목 · 설명 · CopyButton. label = 분류, meta = 예제 개수.
+
+```tsx
+import { Bell } from 'lucide-react'
+import { Badge, Button, CopyButton, Inline, Stack, Text, Card, CardBody, CardHeader, ScaledPreview } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card padding="sm" style={{ width: '100%', maxWidth: 340 }}>
+      <CardBody>
+        <Stack gap={3}>
+          <ScaledPreview height={240} label="피드백" meta="예제 3개">
+            <Card variant="raised" style={{ width: 360 }}>
+              <CardHeader
+                icon={<Bell />}
+                title="새 댓글 3개"
+                description="김민지 님 외 2명이 3분기 메모에 댓글을 남겼어요."
+                actions={<Badge tone="accent">새 글</Badge>}
+              />
+              <CardBody>
+                <Inline gap={2} justify="end">
+                  <Button size="sm" variant="secondary">
+                    나중에
+                  </Button>
+                  <Button size="sm" variant="primary">
+                    보기
+                  </Button>
+                </Inline>
+              </CardBody>
+            </Card>
+          </ScaledPreview>
+          <Inline gap={2} justify="between" wrap={false}>
+            <Stack gap={0}>
+              <Text variant="label-lg">알림 카드</Text>
+              <Text variant="body-sm" tone="tertiary" truncate>
+                새 소식을 알리고 바로 행동하게 하는 카드
+              </Text>
+            </Stack>
+            <CopyButton value={``} variant="secondary" />
+          </Inline>
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 보일 때만 실행
+
+lazy면 무대가 화면에서 200px 안으로 들어올 때 내용을 붙이고, 멀어지면 떼어 내요. 그동안엔 Skeleton(또는 fallback)을 보여 줘요. 실시간 차트처럼 타이머가 도는 예제를 여러 개 늘어놓을 때 써요.
+
+```tsx
+import { Grid, ScaledPreview, Sparkbar } from '@iamfiro/design'
+
+const SERIES = [
+  [4, 6, 5, 8, 7, 9, 12, 10, 13, 15],
+  [9, 8, 10, 7, 6, 8, 5, 6, 4, 3],
+  [3, 5, 4, 6, 9, 8, 7, 10, 9, 11],
+  [6, 6, 7, 5, 8, 9, 7, 8, 10, 9],
+]
+
+export default function Example() {
+  return (
+    <Grid minItemWidth={180} gap={3} style={{ width: '100%' }}>
+      {SERIES.map((data, i) => (
+        <ScaledPreview key={i} lazy height={140} contentWidth={240} meta={`#${i + 1}`}>
+          <Sparkbar data={data} />
+        </ScaledPreview>
+      ))}
+    </Grid>
+  )
+}
+```

package/agents/scatter-chart/AGENTS.md

@@ -0,0 +1,160 @@
+# ScatterChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+두 값의 관계를 점으로 보여주는 산점도. sizeKey를 주면 넓이가 값에 비례하는 버블 차트가 되고, categoryKey로 점을 분류별 색으로 나눠요. 포인터에서 가장 가까운 점이 커지고 나머지는 흐려지며, 옆의 Card 툴팁에 분류와 x · y · 크기 값을 보여줘요. 점은 왼쪽부터 차례로 나타나요.
+
+```tsx
+import { ScatterChart, type ScatterCategory } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 두 값의 관계는 `ScatterChart`(가장 가까운 점이 커지고 나머지는 흐려짐, 범례 클릭 = 분류 숨김 · 보임은 제자리에서 줄며 사라지기), 단계 전환은 `FunnelChart`(빠진 만큼은 앞 단계 색의 옅은 빗금, 한 색조 단계는 `gradient` = `--chart-seq-*`).
+
+## API
+
+### ScatterChart
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `ScatterChartRow[]` |  | 행 목록. 한 행 = 점 하나. x · y가 숫자가 아닌 행은 건너뛰어요. |
+| `xKey / yKey` (필수) | `string` |  | x · y 값이 든 필드. |
+| `sizeKey` | `string` |  | 버블 크기 필드. 넓이가 값에 비례해요. |
+| `sizeRange` | `[number, number]` | `[4, 22]` | 버블 반지름(px)의 최소 · 최대. |
+| `pointRadius` | `number` | `5` | sizeKey가 없을 때 점 반지름(px). |
+| `categoryKey` | `string` |  | 점의 분류 필드. 분류마다 색이 달라요. |
+| `categories` | `ScatterCategory[]` |  | 분류 순서 · 이름 · 색. 생략하면 categoryKey 값이 나온 순서대로 --chart-1부터. |
+| `labelKey` | `string` |  | 점 이름 필드(툴팁 제목). 생략하면 분류 이름. |
+| `xLabel / yLabel / sizeLabel` | `string` |  | 축 제목이자 툴팁 행 이름. |
+| `height` | `number` | `280` | 축 라벨을 포함한 높이(px). |
+| `xTickCount / yTickCount` | `number` | `5 / 4` | 축 라벨 개수(대략). |
+| `xDomain / yDomain` | `[number, number]` |  | 축이 덮을 범위. 둥근 눈금으로 넓혀요. 생략하면 데이터 범위(0에 가까우면 0부터). |
+| `trendLine` | `boolean \| 'category'` | `false` | 점선 추세선(최소제곱). category는 분류마다 하나씩. |
+| `referenceLines` | `ScatterReferenceLine[]` |  | { axis: 'x' \| 'y', value, label?, tone? } 점선 기준선. |
+| `formatX / formatY / formatSize` | `(value, row) => string` | `'1,234'` | 툴팁 값 형식. |
+| `formatAxisX / formatAxisY` | `(value) => string` | `'6천'` | 축 라벨 형식. |
+| `legend` | `boolean` | `true` | 아래 범례(categoryKey가 있을 때). 누르면 분류를 숨기고 · 보이고, 올리면 강조해요. |
+| `hiddenCategories / defaultHiddenCategories / onHiddenCategoriesChange` | `string[]` |  | 숨긴 분류 key(제어/비제어). |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 하이라이트한 점. 보이는 점을 x 순서로 센 번호(제어/비제어). |
+| `aria-label` | `string` | `'산점도'` | 차트 이름. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 버블 · 고객사별 매출 대비 사용량
+
+버블 크기는 좌석 수, 색은 요금제예요. 범례를 누르면 그 요금제가 제자리에서 줄어들며 사라지고, 다시 누르면 돌아와요. trendLine은 보이는 점 전체의 추세선이에요. ←/→, Home/End로 점을 왼쪽부터 옮기고 Esc로 닫아요.
+
+```tsx
+import { ScatterChart, type ScatterCategory } from '@iamfiro/design'
+
+const PLANS: ScatterCategory[] = [
+  { key: 'starter', label: '스타터', color: '--chart-3' },
+  { key: 'team', label: '팀', color: '--chart-2' },
+  { key: 'enterprise', label: '엔터프라이즈', color: '--chart-4' },
+]
+
+// 고객사별 월 사용량(만 회) · 연 매출(만 원) · 좌석 수
+const CUSTOMERS = [
+  { name: '한빛상사', plan: 'starter', usage: 12, revenue: 480, seats: 8 },
+  { name: '누리테크', plan: 'starter', usage: 18, revenue: 620, seats: 12 },
+  { name: '바른물류', plan: 'starter', usage: 9, revenue: 360, seats: 5 },
+  { name: '소담커머스', plan: 'starter', usage: 26, revenue: 840, seats: 15 },
+  { name: '다온랩', plan: 'starter', usage: 31, revenue: 760, seats: 10 },
+  { name: '새봄디자인', plan: 'team', usage: 42, revenue: 1850, seats: 34 },
+  { name: '온결헬스', plan: 'team', usage: 58, revenue: 2300, seats: 48 },
+  { name: '한결금융', plan: 'team', usage: 36, revenue: 2100, seats: 40 },
+  { name: '푸른교육', plan: 'team', usage: 71, revenue: 2650, seats: 55 },
+  { name: '미래모빌리티', plan: 'team', usage: 64, revenue: 3100, seats: 62 },
+  { name: '가람제약', plan: 'team', usage: 49, revenue: 1720, seats: 28 },
+  { name: '대한전자', plan: 'enterprise', usage: 118, revenue: 7800, seats: 240 },
+  { name: '세종에너지', plan: 'enterprise', usage: 96, revenue: 6200, seats: 180 },
+  { name: '하늘항공', plan: 'enterprise', usage: 142, revenue: 9400, seats: 320 },
+  { name: '우리리테일', plan: 'enterprise', usage: 87, revenue: 5100, seats: 150 },
+  { name: '나래통신', plan: 'enterprise', usage: 128, revenue: 6900, seats: 210 },
+]
+
+export default function Example() {
+  return (
+    <ScatterChart
+      data={CUSTOMERS}
+      xKey="usage"
+      yKey="revenue"
+      sizeKey="seats"
+      categoryKey="plan"
+      categories={PLANS}
+      labelKey="name"
+      xLabel="월 사용량"
+      yLabel="연 매출"
+      sizeLabel="좌석 수"
+      trendLine
+      formatX={(v) => `${v.toLocaleString('ko-KR')}만 회`}
+      formatY={(v) => `${v.toLocaleString('ko-KR')}만 원`}
+      formatSize={(v) => `${v.toLocaleString('ko-KR')}석`}
+      formatAxisX={(v) => `${v}만`}
+      aria-label="고객사별 매출 대비 사용량"
+      style={{ width: '100%', maxWidth: 620 }}
+    />
+  )
+}
+```
+
+### 두 분류 · 기준선
+
+trendLine="category"는 분류마다 자기 색의 추세선을 그려요. referenceLines로 목표선을, yDomain으로 축 범위를 정해요.
+
+```tsx
+import { ScatterChart, type ScatterCategory } from '@iamfiro/design'
+
+const GROUPS: ScatterCategory[] = [
+  { key: 'a', label: '기존 화면' },
+  { key: 'b', label: '새 화면' },
+]
+
+// 응답 시간(초)과 만족도(점) — 사용자 한 명이 점 하나
+const RESPONSES = [
+  { group: 'a', time: 4.2, score: 62 },
+  { group: 'a', time: 5.1, score: 55 },
+  { group: 'a', time: 3.6, score: 70 },
+  { group: 'a', time: 6.4, score: 48 },
+  { group: 'a', time: 4.8, score: 58 },
+  { group: 'a', time: 5.7, score: 51 },
+  { group: 'a', time: 3.9, score: 66 },
+  { group: 'a', time: 7.1, score: 42 },
+  { group: 'a', time: 4.5, score: 64 },
+  { group: 'b', time: 1.8, score: 84 },
+  { group: 'b', time: 2.4, score: 78 },
+  { group: 'b', time: 1.2, score: 91 },
+  { group: 'b', time: 3.1, score: 72 },
+  { group: 'b', time: 2.0, score: 86 },
+  { group: 'b', time: 2.7, score: 75 },
+  { group: 'b', time: 1.5, score: 88 },
+  { group: 'b', time: 3.4, score: 69 },
+  { group: 'b', time: 2.2, score: 81 },
+]
+
+export default function Example() {
+  return (
+    <ScatterChart
+      data={RESPONSES}
+      xKey="time"
+      yKey="score"
+      categoryKey="group"
+      categories={GROUPS}
+      xLabel="응답 시간"
+      yLabel="만족도"
+      trendLine="category"
+      referenceLines={[{ axis: 'y', value: 70, label: '목표 70점', tone: 'accent' }]}
+      formatX={(v) => `${v}초`}
+      formatY={(v) => `${v}점`}
+      formatAxisX={(v) => `${v}초`}
+      yDomain={[40, 100]}
+      height={260}
+      aria-label="응답 시간과 만족도"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```

package/agents/scroll-area/AGENTS.md

@@ -0,0 +1,271 @@
+# ScrollArea
+
+> 파운데이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+어느 브라우저에서나 같은 스크롤바를 그리는 스크롤 영역. 스크롤은 그대로 네이티브(휠 · 터치 · 키보드)이고, 막대만 위에 얹어요. 막대는 .ds-scroll과 같은 규격(12px 영역 · 4px 막대 · 양 끝 6px)으로, 올려 두거나 스크롤하는 동안 나타났다가 잠시 뒤 사라져요. 막대를 끌면 따라오고(끄는 중 Esc는 원래 자리로), 빈 트랙을 누르면 한 화면씩 넘어가요. fade를 주면 더 읽을 내용이 남은 쪽 가장자리만 부드럽게 흐려져요.
+
+```tsx
+import { ScrollArea } from '@iamfiro/design'
+```
+
+## API
+
+### ScrollArea
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | 스크롤할 내용. |
+| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | 스크롤 방향. 가로 · 양방향이면 내용은 자기 너비(max-content)를 유지해요. |
+| `maxHeight` | `number \| string` |  | 이 높이까지는 내용만큼 자라고, 넘으면 스크롤. 고정 높이는 style 또는 부모(flex: 1)로. |
+| `scrollbars` | `'auto' \| 'always'` | `'auto'` | auto: 올려 두거나 스크롤하는 동안만 보이고 사라짐 · always: 넘칠 때 항상. |
+| `fade` | `boolean \| number` |  | 아직 스크롤할 수 있는 쪽 가장자리를 흐리게(mask). 숫자는 흐림 길이 px(기본 28). |
+| `stickToBottom` | `boolean` |  | 맨 아래에서 시작하고, 내용이 늘어도 아래에 붙음. 사용자가 위로 올렸으면 그대로 둠. |
+| `onAtBottomChange` | `(atBottom: boolean) => void` |  | 맨 아래(8px 안)에 닿거나 벗어날 때. |
+| `viewportRef` | `Ref<HTMLDivElement>` |  | 실제로 스크롤되는 요소. scrollTo · scrollTop에. |
+| `focusable` | `boolean` |  | Tab으로 갈 수 있는 영역인지. 기본: 넘치는데 안에 포커스할 요소가 없을 때만. |
+| `aria-label / aria-labelledby` | `string` |  | 주면 영역이 role="region"이 돼요. 키보드로 스크롤할 영역이면 꼭. |
+| `onScroll` | `(e) => void` |  | 스크롤될 때(viewport의 scroll 이벤트). |
+| `viewportClassName / className / style` | `string / CSSProperties` |  | style · className은 바깥 요소에. 부모가 세로 flex면 style={{ flex: 1, minHeight: 0 }}. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 최대 높이 + 가장자리 흐림
+
+maxHeight까지는 내용만큼 자라고 그 뒤로 스크롤돼요. fade는 위 · 아래 중 아직 내용이 숨어 있는 쪽만 흐려서, 맨 위에선 아래만, 중간에선 양쪽이 흐려져요.
+
+```tsx
+import { FileText, GitMerge, MessageSquare, UserPlus } from 'lucide-react'
+import { Avatar, IconTile, Card, CardHeader, List, ListItem, ScrollArea } from '@iamfiro/design'
+
+const PEOPLE = ['김민지', '이도현', '박서연', '정하늘', '한지우', '오세훈']
+const KINDS = [
+  { icon: <MessageSquare />, text: '디자인 리뷰에 댓글을 남겼어요' },
+  { icon: <GitMerge />, text: '결제 화면 개선을 병합했어요' },
+  { icon: <FileText />, text: '4분기 로드맵 문서를 고쳤어요' },
+  { icon: <UserPlus />, text: '새 팀원을 초대했어요' },
+]
+
+const ACTIVITY = Array.from({ length: 18 }, (_, i) => ({
+  id: i,
+  who: PEOPLE[i % PEOPLE.length],
+  ...KINDS[i % KINDS.length],
+  time: i === 0 ? '방금' : i < 6 ? `${i * 7}분 전` : `${Math.floor(i / 3)}시간 전`,
+}))
+
+export default function Example() {
+  return (
+    <Card padding="sm" style={{ width: '100%', maxWidth: 420 }}>
+      <CardHeader title="최근 활동" description="오늘 18건" />
+      <ScrollArea maxHeight={300} fade aria-label="최근 활동">
+        <List density="compact" aria-label="활동 기록">
+          {ACTIVITY.map((a) => (
+            <ListItem
+              key={a.id}
+              leading={<Avatar name={a.who} size={28} />}
+              title={a.who}
+              description={a.text}
+              meta={a.time}
+              trailing={
+                <IconTile size={24} tone="surface">
+                  {a.icon}
+                </IconTile>
+              }
+            />
+          ))}
+        </List>
+      </ScrollArea>
+    </Card>
+  )
+}
+```
+
+### 대화 기록 (아래에 붙기)
+
+stickToBottom이면 맨 아래에서 시작하고, 새 메시지가 와도 아래에 붙어 있어요. 위로 올려 읽는 중이면 끌어내리지 않고, onAtBottomChange로 "맨 아래로" 버튼을 켜요. viewportRef로 scrollTo를 부를 수 있어요.
+
+```tsx
+import { useRef, useState } from 'react'
+import { ArrowDown, Send } from 'lucide-react'
+import { Box, Button, Inline, Card, Comment, CommentThread, ScrollArea } from '@iamfiro/design'
+
+interface Message {
+  id: number
+  author: string
+  text: string
+  date: Date
+}
+
+const ago = (m: number) => new Date(Date.now() - m * 60_000)
+
+const START: Message[] = [
+  { id: 1, author: '김민지', text: '오늘 배포 일정 다시 한번 확인할게요. 오후 4시 맞죠?', date: ago(42) },
+  { id: 2, author: '이도현', text: '네, 4시에 시작해서 30분 안에 끝낼 예정이에요.', date: ago(40) },
+  { id: 3, author: '이도현', text: '결제 모듈은 마지막에 따로 올릴게요.', date: ago(39) },
+  { id: 4, author: '박서연', text: '변경 사항 안내 문구는 제가 정리해 둘게요.', date: ago(31) },
+  { id: 5, author: '김민지', text: '좋아요. 롤백 절차도 문서에 같이 넣어 주세요.', date: ago(25) },
+  { id: 6, author: '정하늘', text: '모니터링 대시보드 링크 공유드려요. 오류율 0.2% 넘으면 알림이 와요.', date: ago(18) },
+  { id: 7, author: '이도현', text: '스테이징 확인 끝났어요. 문제 없어요.', date: ago(9) },
+]
+
+const REPLIES = [
+  { author: '박서연', text: '안내 문구 초안 올렸어요. 한번 봐 주세요.' },
+  { author: '정하늘', text: '지금 오류율 0.05%로 안정적이에요.' },
+  { author: '김민지', text: '확인했어요. 고마워요!' },
+  { author: '이도현', text: '결제 모듈도 올라갔어요. 배포 끝!' },
+]
+
+export default function Example() {
+  const [messages, setMessages] = useState(START)
+  const [atBottom, setAtBottom] = useState(true)
+  const viewport = useRef<HTMLDivElement>(null)
+
+  const receive = () => {
+    const reply = REPLIES[(messages.length - START.length) % REPLIES.length]
+    const date = new Date()
+    setMessages((m) => [...m, { id: m.length + 1, ...reply, date }])
+  }
+  const toBottom = () => viewport.current?.scrollTo({ top: viewport.current.scrollHeight, behavior: 'smooth' })
+
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 520, height: 400 }}>
+      <ScrollArea
+        stickToBottom
+        fade
+        onAtBottomChange={setAtBottom}
+        viewportRef={viewport}
+        aria-label="배포 채널 대화"
+        style={{ flex: 1, minHeight: 0 }}
+      >
+        <Box padding={4}>
+          <CommentThread>
+            {messages.map((m, i) => (
+              <Comment key={m.id} author={m.author} date={m.date} continued={messages[i - 1]?.author === m.author}>
+                {m.text}
+              </Comment>
+            ))}
+          </CommentThread>
+        </Box>
+      </ScrollArea>
+      <Box paddingX={4} paddingY={3}>
+        <Inline justify="between">
+          <Button size="sm" variant="secondary" icon={<ArrowDown />} disabled={atBottom} onClick={toBottom}>
+            맨 아래로
+          </Button>
+          <Button size="sm" variant="primary" icon={<Send />} onClick={receive}>
+            새 메시지 받기
+          </Button>
+        </Inline>
+      </Box>
+    </Card>
+  )
+}
+```
+
+### 가로 스크롤
+
+orientation="horizontal"이면 아래에 가로 막대가 생기고, fade는 왼쪽 · 오른쪽 가장자리에 걸려요. 트랙패드 · Shift+휠로 넘겨 보세요.
+
+```tsx
+import { Box, FileIcon, Inline, Stack, Text, Card, ScrollArea } from '@iamfiro/design'
+
+const FILES = [
+  { name: '4분기 로드맵.pptx', who: '김민지', when: '10분 전' },
+  { name: '10월 매출 정리.xlsx', who: '이도현', when: '1시간 전' },
+  { name: '브랜드 가이드.pdf', who: '박서연', when: '어제' },
+  { name: '랜딩 페이지 시안.png', who: '정하늘', when: '어제' },
+  { name: '사용자 인터뷰 정리.docx', who: '한지우', when: '10월 22일' },
+  { name: '아이콘 세트.zip', who: '오세훈', when: '10월 21일' },
+  { name: '2027 예산안.xlsx', who: '김민지', when: '10월 20일' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={2} style={{ width: '100%', maxWidth: 560 }}>
+      <Text variant="label-md">최근 파일</Text>
+      <ScrollArea orientation="horizontal" fade aria-label="최근 파일">
+        <Box paddingX={1} paddingY={3}>
+          <Inline gap={3} wrap={false}>
+            {FILES.map((f) => (
+              <Card key={f.name} as="button" interactive padding="sm" style={{ width: 168, flex: 'none', textAlign: 'start' }}>
+                <Stack gap={3}>
+                  <FileIcon name={f.name} size={28} />
+                  <Stack gap={1}>
+                    <Text variant="label-sm" truncate>
+                      {f.name}
+                    </Text>
+                    <Text variant="caption" tone="tertiary">
+                      {f.who} · {f.when}
+                    </Text>
+                  </Stack>
+                </Stack>
+              </Card>
+            ))}
+          </Inline>
+        </Box>
+      </ScrollArea>
+    </Stack>
+  )
+}
+```
+
+### 키보드로 읽는 영역
+
+안에 포커스할 요소가 없으면 영역 자체가 Tab으로 갈 수 있는 region이 되어 ↑ ↓ · Page Up / Down · Space로 읽을 수 있어요(aria-label 필수). scrollbars="always"는 넘칠 때 막대를 항상 보여 줘요. 끝까지 읽어야 동의 버튼이 켜져요.
+
+```tsx
+import { useState } from 'react'
+import { Box, Button, Inline, Prose, Stack, Text, Card, ScrollArea } from '@iamfiro/design'
+
+const SECTIONS = [
+  ['제1조 (목적)', '이 약관은 회사가 제공하는 협업 서비스의 이용 조건과 절차, 회사와 이용자의 권리 · 의무를 정하는 것을 목적으로 해요.'],
+  ['제2조 (계정)', '이용자는 하나의 이메일로 하나의 계정을 만들 수 있어요. 계정 정보는 본인이 직접 관리하고, 다른 사람에게 빌려주지 않아요.'],
+  ['제3조 (요금)', '유료 요금제는 매월 같은 날 자동으로 결제돼요. 결제일 7일 전까지 해지하면 다음 달부터 청구되지 않아요.'],
+  ['제4조 (데이터)', '이용자가 올린 문서와 파일의 권리는 이용자에게 있어요. 회사는 서비스 제공에 필요한 범위에서만 데이터를 처리해요.'],
+  ['제5조 (서비스 변경)', '기능을 바꾸거나 끝낼 때는 30일 전에 공지해요. 이용자에게 불리한 변경은 이메일로도 따로 알려요.'],
+  ['제6조 (해지)', '언제든 설정에서 해지할 수 있어요. 해지 후 30일 동안은 데이터를 내려받을 수 있고, 그 뒤에는 완전히 삭제돼요.'],
+] as const
+
+export default function Example() {
+  const [read, setRead] = useState(false)
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 460 }}>
+      <Box padding={4}>
+        <Stack gap={1}>
+          <Text variant="heading-xs">서비스 이용 약관</Text>
+          <Text variant="caption" tone="tertiary">
+            끝까지 읽으면 동의할 수 있어요. 본문을 Tab으로 고른 뒤 ↑ ↓ · Page Up / Down으로도 읽을 수 있어요.
+          </Text>
+        </Stack>
+      </Box>
+      <ScrollArea
+        maxHeight={220}
+        scrollbars="always"
+        fade
+        aria-label="이용 약관 본문"
+        onAtBottomChange={(bottom) => bottom && setRead(true)}
+      >
+        <Box paddingX={4} paddingY={2}>
+          <Prose size="sm">
+            {SECTIONS.map(([title, body]) => (
+              <section key={title}>
+                <h4>{title}</h4>
+                <p>{body}</p>
+              </section>
+            ))}
+          </Prose>
+        </Box>
+      </ScrollArea>
+      <Box padding={4}>
+        <Inline justify="end" gap={2}>
+          <Button variant="ghost">나중에</Button>
+          <Button variant="primary" disabled={!read}>
+            동의하고 계속
+          </Button>
+        </Inline>
+      </Box>
+    </Card>
+  )
+}
+```

package/agents/search-input/AGENTS.md

@@ -0,0 +1,105 @@
+# SearchInput
+
+> 텍스트 입력 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+돋보기 아이콘이 붙은 검색 입력창. shortcutKey를 주면 오른쪽에 키캡이 보이고, 어디서든 ⌘(Mac) 또는 Ctrl + 그 키로 바로 포커스돼요. Input의 다른 props는 모두 그대로 쓸 수 있어요.
+
+```tsx
+import { SearchInput } from '@iamfiro/design'
+```
+
+## API
+
+### SearchInput
+
+Input의 props(size · invalid · disabled · value · onChange 등)를 그대로 받아요. leading · trailing · type은 정해져 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `shortcutKey` | `string` |  | ⌘(Mac) / Ctrl과 함께 누르면 포커스되는 키. 키캡으로 표시돼요. 한 화면에서 같은 키를 두 번 쓰지 마세요. |
+| `placeholder` | `string` | `'검색'` | 빈 칸 안내 문구. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `wrapperClassName` | `string` |  | 바깥 칸에 붙일 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 단축키
+
+⌘/Ctrl + / 를 눌러 보세요. 포커스와 함께 입력된 글자가 전체 선택돼요. 이 문서 사이트는 ⌘K를 이미 쓰고 있어서 예시에서는 /를 썼어요.
+
+```tsx
+import { SearchInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ width: 320 }}>
+      <SearchInput placeholder="문서 검색" shortcutKey="/" aria-label="문서 검색" />
+    </div>
+  )
+}
+```
+
+### 목록 필터링
+
+value / onChange로 제어하며 목록을 바로 걸러요. 결과가 없으면 EmptyState로 알려 주세요.
+
+```tsx
+import { useState } from 'react'
+import { SearchX } from 'lucide-react'
+import { Avatar, SearchInput, Text, EmptyState } from '@iamfiro/design'
+
+const MEMBERS = [
+  { name: '김민지', role: '디자이너' },
+  { name: '이도현', role: '프론트엔드 개발자' },
+  { name: '최서연', role: '프로덕트 매니저' },
+  { name: '정우진', role: '백엔드 개발자' },
+  { name: '한지수', role: '데이터 분석가' },
+]
+
+export default function Example() {
+  const [query, setQuery] = useState('')
+  const results = MEMBERS.filter((m) => m.name.includes(query.trim()) || m.role.includes(query.trim()))
+
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 320 }}>
+      <SearchInput size="sm" placeholder="이름이나 역할로 찾기" value={query} onChange={(e) => setQuery(e.target.value)} aria-label="멤버 찾기" />
+      {results.length > 0 ? (
+        <div style={{ display: 'grid', gap: 10 }}>
+          {results.map((m) => (
+            <div key={m.name} style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+              <Avatar name={m.name} size={28} />
+              <Text variant="label-md">{m.name}</Text>
+              <Text as="span" variant="body-sm" tone="tertiary">
+                {m.role}
+              </Text>
+            </div>
+          ))}
+        </div>
+      ) : (
+        <EmptyState size="sm" icon={<SearchX />} title="찾는 멤버가 없어요" description={`'${query}'와 일치하는 이름이나 역할이 없어요.`} />
+      )}
+    </div>
+  )
+}
+```
+
+### 크기와 상태
+
+Input과 같은 size(36 / 44 / 52px)와 disabled를 받아요.
+
+```tsx
+import { SearchInput } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 320 }}>
+      <SearchInput size="sm" placeholder="작게 (sm)" aria-label="검색 sm" />
+      <SearchInput placeholder="기본 (md)" aria-label="검색 md" />
+      <SearchInput size="lg" placeholder="크게 (lg)" aria-label="검색 lg" />
+      <SearchInput placeholder="검색할 수 없어요" disabled aria-label="검색 비활성" />
+    </div>
+  )
+}
+```