@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/empty-state/AGENTS.md

@@ -0,0 +1,203 @@
+# EmptyState
+
+> 알림 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+보여 줄 내용이 없을 때 이유와 다음 행동을 알려 주는 자리. 처음 사용, 검색 결과 없음, 오류, 권한 없음처럼 상황에 맞게 아이콘 · 문구 · 버튼을 바꿔 써요. 나타날 때 아이콘부터 버튼까지 차례로 떠올라요.
+
+```tsx
+import { EmptyState } from '@iamfiro/design'
+```
+
+## API
+
+### EmptyState
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 한 줄 요약. |
+| `description` | `ReactNode` |  | 이유와 다음 행동 설명. |
+| `icon` | `ReactNode` |  | 둥근 배지 안에 보이는 아이콘. |
+| `media` | `ReactNode` |  | 아이콘 배지 대신 쓸 일러스트 · 이미지. |
+| `actions` | `ReactNode` |  | 버튼. 보통 첫 번째가 주요 행동이에요. |
+| `footer` | `ReactNode` |  | 버튼 아래 작은 줄(도움말 링크, 단축키 안내). |
+| `tone` | `'default' \| 'accent' \| 'danger' \| 'warning' \| 'success'` | `'default'` | 아이콘 배지 색. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 아이콘 36 / 48 / 60px과 여백. |
+| `align` | `'center' \| 'start'` | `'center'` | start는 왼쪽 정렬(패널·표 안). |
+| `className / style` | `string / CSSProperties` |  | 루트에 적용돼요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 처음 사용
+
+무엇을 할 수 있는지 알려 주고 첫 행동을 primary 버튼으로 제안해요. footer에는 작은 도움말을 넣어요.
+
+```tsx
+import { FolderKanban, Plus } from 'lucide-react'
+import { Button, EmptyState, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <EmptyState
+      tone="accent"
+      icon={<FolderKanban />}
+      title="첫 프로젝트를 만들어 보세요"
+      description="프로젝트에서 팀원과 할 일, 파일, 일정을 한곳에서 관리할 수 있어요."
+      actions={
+        <>
+          <Button variant="primary" icon={<Plus />} onClick={() => toast.success('새 프로젝트를 만들었어요')}>
+            새 프로젝트
+          </Button>
+          <Button variant="ghost">템플릿 둘러보기</Button>
+        </>
+      }
+      footer="팀원이 프로젝트에 초대하면 여기에 바로 보여요."
+    />
+  )
+}
+```
+
+### 검색 결과 없음
+
+검색어를 그대로 보여 주고, 검색어를 지우는 버튼을 함께 둬요. 좁은 곳에서는 size="sm".
+
+```tsx
+import { useState } from 'react'
+import { SearchX } from 'lucide-react'
+import { Button, SearchInput, EmptyState } from '@iamfiro/design'
+
+export default function Example() {
+  const [query, setQuery] = useState('분기 매출 보고서')
+
+  return (
+    <div style={{ display: 'grid', gap: 8, width: 360 }}>
+      <SearchInput placeholder="문서 검색" value={query} onChange={(e) => setQuery(e.target.value)} aria-label="문서 검색" />
+      {query ? (
+        <EmptyState
+          size="sm"
+          icon={<SearchX />}
+          title="검색 결과가 없어요"
+          description={`‘${query}’와 일치하는 문서가 없어요. 철자를 확인하거나 다른 단어로 찾아보세요.`}
+          actions={
+            <Button size="sm" onClick={() => setQuery('')}>
+              검색어 지우기
+            </Button>
+          }
+        />
+      ) : (
+        <EmptyState size="sm" title="찾을 문서 이름을 입력하세요" />
+      )}
+    </div>
+  )
+}
+```
+
+### 오류 · 다시 시도
+
+tone="danger"로 아이콘을 빨갛게 하고, 다시 시도 버튼에는 loading으로 진행 중임을 보여 줘요.
+
+```tsx
+import { useState } from 'react'
+import { CloudOff, RefreshCw } from 'lucide-react'
+import { Button, EmptyState } from '@iamfiro/design'
+
+export default function Example() {
+  const [retrying, setRetrying] = useState(false)
+  const [attempts, setAttempts] = useState(0)
+
+  const retry = () => {
+    setRetrying(true)
+    setTimeout(() => {
+      setRetrying(false)
+      setAttempts((n) => n + 1)
+    }, 1400)
+  }
+
+  return (
+    <EmptyState
+      tone="danger"
+      icon={<CloudOff />}
+      title="목록을 불러오지 못했어요"
+      description="서버와 연결이 끊겼어요. 잠시 후 다시 시도해 주세요."
+      actions={
+        <Button icon={<RefreshCw />} loading={retrying} onClick={retry}>
+          다시 시도
+        </Button>
+      }
+      footer={attempts > 0 ? `${attempts}번 다시 시도했어요 · 오류 코드 503` : '오류 코드 503'}
+    />
+  )
+}
+```
+
+### 권한 없음
+
+tone="warning". 왜 볼 수 없는지와 누구에게 요청하면 되는지 적어요.
+
+```tsx
+import { useState } from 'react'
+import { Lock } from 'lucide-react'
+import { Button, EmptyState, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [requested, setRequested] = useState(false)
+
+  const request = () => {
+    setRequested(true)
+    toast.success('접근 권한을 요청했어요', { description: '김민지님이 승인하면 알려 드릴게요.' })
+  }
+
+  return (
+    <EmptyState
+      tone="warning"
+      icon={<Lock />}
+      title="이 폴더를 볼 권한이 없어요"
+      description="‘재무 · 2026 예산’ 폴더는 재무팀만 볼 수 있어요. 관리자에게 권한을 요청하세요."
+      actions={
+        <Button variant="primary" disabled={requested} onClick={request}>
+          {requested ? '요청 보냄' : '권한 요청'}
+        </Button>
+      }
+    />
+  )
+}
+```
+
+### 크기 · 정렬
+
+size는 sm / md / lg로 아이콘과 여백이 함께 바뀌어요. 패널이나 표 안에서는 align="start"로 왼쪽에 맞춰요.
+
+```tsx
+import { Bell, CheckCheck, Inbox } from 'lucide-react'
+import { Button, Card, CardHeader, EmptyState } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(260px, 1fr))', gap: 16, width: '100%', maxWidth: 720 }}>
+      <Card>
+        <CardHeader title="알림" />
+        <EmptyState
+          size="sm"
+          align="start"
+          tone="success"
+          icon={<CheckCheck />}
+          title="모두 확인했어요"
+          description="새 알림이 오면 여기에 보여요."
+          style={{ paddingInline: 0 }}
+        />
+      </Card>
+      <Card>
+        <CardHeader title="받은 편지함" />
+        <EmptyState
+          size="lg"
+          icon={<Inbox />}
+          title="받은 메일이 없어요"
+          description="새 메일이 도착하면 알려 드릴게요."
+          actions={<Button icon={<Bell />}>알림 설정</Button>}
+        />
+      </Card>
+    </div>
+  )
+}
+```

package/agents/file-chip/AGENTS.md

@@ -0,0 +1,79 @@
+# FileChip
+
+> 파일 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+첨부 파일을 작게 보여 주는 링크형 칩. 클립(또는 색 FileIcon), 파일 이름, 선택적인 크기로 이뤄져요. 이름이 길면 가운데가 줄어 확장자는 항상 보여요. href면 링크, onClick이면 버튼, 둘 다 없으면 글자예요. 업로드 진행 · 재시도가 필요하면 FileUpload를 쓰세요.
+
+```tsx
+import { FileChip } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 민감한 값은 `MaskedText`(양 끝만, 점 한 묶음이라 길이를 드러내지 않음, 화면 읽기는 "가려진 값"), 글 속 강조 + 메모 말풍선은 `Highlight note`, 첨부 파일 링크는 `FileChip`(확장자는 줄이지 않음).
+
+## API
+
+### FileChip
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `name` (필수) | `string` |  | 파일 이름. 확장자는 줄어들지 않아요. |
+| `size` | `number \| string` |  | 바이트(formatBytes로 표시) 또는 문자열("1.2MB"). |
+| `href` | `string` |  | 링크로 만들어요. |
+| `download` | `boolean \| string` |  | href와 함께: 이동 대신 내려받기(파일 이름 지정 가능). |
+| `target` | `string` |  | 링크 대상. '_blank'면 rel=noreferrer. |
+| `onClick` | `(event) => void` |  | 버튼으로 만들어요(미리보기 열기 등). |
+| `icon` | `'clip' \| 'file' \| ReactNode` | `'clip'` | 클립 / 색 FileIcon / 직접 넣은 아이콘. |
+| `variant` | `'ghost' \| 'soft'` | `'ghost'` | 채움 없음(링크형) / 회색 칩. |
+| `maxWidth` | `number` | `220` | 이름이 이 폭(px)을 넘으면 줄어요. |
+| `disabled` | `boolean` |  | 누를 수 없게. |
+| `aria-label` | `string` |  | 이름 대신 읽을 접근성 이름. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+ghost(기본)는 채움 없이 링크처럼, hover에서만 옅게 채워져요. size가 숫자면 formatBytes로 바꿔요.
+
+```tsx
+import { Inline, Stack, Text, FileChip, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={2} align="start">
+      <Text variant="body-sm" tone="secondary">
+        김민지 님이 청구서를 첨부했어요.
+      </Text>
+      <Inline gap={1}>
+        <FileChip name="INV-2207.pdf" size={248_000} onClick={() => toast('INV-2207.pdf 미리보기를 열었어요')} />
+        <FileChip name="10월-정산-내역.xlsx" size="1.2MB" onClick={() => toast('10월-정산-내역.xlsx 미리보기를 열었어요')} />
+        <FileChip name="계약서-사본.pdf" />
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 아이콘 · 채움 · 줄임
+
+icon="file"은 종류별 색 FileIcon, variant="soft"는 회색 칩. maxWidth를 넘는 이름은 확장자 앞에서 줄어요.
+
+```tsx
+import { Stack, FileChip, toast } from '@iamfiro/design'
+
+const open = (name: string) => () => toast(`${name} 미리보기를 열었어요`)
+
+export default function Example() {
+  return (
+    <Stack gap={2} align="start">
+      <FileChip icon="file" name="배포-체크리스트.docx" size={52_300} onClick={open('배포-체크리스트.docx')} />
+      <FileChip icon="file" variant="soft" name="결제-화면-시안.png" size={3_400_000} onClick={open('결제-화면-시안.png')} />
+      <FileChip variant="soft" name="2026년-4분기-거래처별-미수금-정리-최종본-이도현-검토.xlsx" maxWidth={180} size="840KB" />
+      <FileChip name="만료된-링크.zip" onClick={open('만료된-링크.zip')} disabled />
+    </Stack>
+  )
+}
+```

package/agents/file-icon/AGENTS.md

@@ -0,0 +1,66 @@
+# FileIcon
+
+> 파일 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+파일 종류를 색 띠로 알려 주는 종이 아이콘. 이름 · 확장자 · MIME 타입에서 종류를 추측해요(PDF 빨강, 이미지 보라, 시트 초록…). 색은 tokens.css의 --file-* 토큰이에요.
+
+```tsx
+import { FileIcon, fileKind } from '@iamfiro/design'
+```
+
+## API
+
+### FileIcon
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `name` | `string` |  | 파일 이름, 확장자 또는 MIME 타입. |
+| `kind` | `'pdf' \| 'image' \| 'sheet' \| 'doc' \| 'slide' \| 'video' \| 'audio' \| 'archive' \| 'code' \| 'other'` |  | name에서 추측한 종류 대신 직접 지정. |
+| `size` | `number` | `20` | 크기(px). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 종류
+
+확장자에서 고른 색. 모르는 형식은 회색.
+
+```tsx
+import { FileIcon, Inline, Stack, Text } from '@iamfiro/design'
+
+const FILES = ['보고서.pdf', '시안.png', '예산.xlsx', '기획서.docx', '발표.pptx', '데모.mp4', '녹음.m4a', '자료.zip', 'index.ts', '메모']
+
+export default function Example() {
+  return (
+    <Inline gap={6}>
+      {FILES.map((name) => (
+        <Stack key={name} gap={2} align="center">
+          <FileIcon name={name} size={28} />
+          <Text variant="caption" tone="tertiary">
+            {name}
+          </Text>
+        </Stack>
+      ))}
+    </Inline>
+  )
+}
+```
+
+### 크기
+
+size로 px를 정해요. 목록 행에서는 기본 20.
+
+```tsx
+import { FileIcon, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={4} align="end">
+      {[16, 20, 24, 32, 40].map((size) => (
+        <FileIcon key={size} kind="pdf" size={size} />
+      ))}
+    </Inline>
+  )
+}
+```

package/agents/file-upload/AGENTS.md

@@ -0,0 +1,168 @@
+# FileUpload
+
+> 파일 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+파일을 끌어 놓거나 골라서 올리고, 줄마다 진행률과 남은 시간을 보여 줘요. 파운데이션(Card · Dropzone · List · FileIcon · Progress · Text)만 조립해 만들었어요. ×는 보내는 중이면 요청을 끊고, 줄은 높이를 접으며 빠져요. 형식 · 크기 · 개수 제한에 걸린 파일은 빨간 글자로 이유를 남겨요.
+
+```tsx
+import { FileUpload, type UploadHandler, type UploadItem } from '@iamfiro/design'
+```
+
+## API
+
+### FileUpload
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `upload` | `(file, { onProgress, signal }) => Promise` |  | 파일 하나를 보내요. 끝나면 resolve, 실패하면 reject(메시지가 줄에 나와요). ×를 누르면 signal이 끊겨요. 없으면 고른 파일을 목록에만 넣어요. |
+| `items` | `UploadItem[]` |  | 목록(제어). |
+| `defaultItems` | `UploadItem[]` |  | 처음 목록(비제어). uploading이고 file이 있으면 바로 보내기 시작해요. |
+| `onItemsChange` | `(items: UploadItem[]) => void` |  | 추가 · 진행 · 완료 · 삭제 때마다. |
+| `onRemove` | `(item: UploadItem) => void` |  | ×로 뺄 때. 서버에 올라간 파일을 지우는 곳. |
+| `accept` | `string` |  | <input accept>와 같은 문법. 끌어 놓은 파일에도 적용돼요. |
+| `maxSize` | `number` |  | 파일당 최대 바이트. |
+| `maxFiles` | `number` |  | 한 번에 둘 수 있는 파일 수(실패한 줄은 세지 않아요). |
+| `multiple` | `boolean` | `true` | 여러 개 고르기. |
+| `disabled` | `boolean` |  | 새 파일을 받지 않아요. |
+| `title` | `ReactNode` |  | 드롭 영역 첫 줄. |
+| `description` | `ReactNode` |  | 드롭 영역 회색 줄. 기본은 accept · maxSize로 만들어요. |
+| `showSummary` | `boolean` | `true` | 아래 "3개 중 2개 업로드 중 · 1.2 / 8.1MB" 줄. |
+
+### UploadItem
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` (필수) | `string` |  | 고유 id. |
+| `name` (필수) | `string` |  | 파일 이름. 확장자로 아이콘 색이 정해져요. |
+| `size` (필수) | `number` |  | 바이트. |
+| `status` (필수) | `'uploading' \| 'done' \| 'error'` |  | 상태. |
+| `loaded` | `number` |  | 보낸 바이트. |
+| `error` | `ReactNode` |  | 실패 이유(빨간 글자). |
+| `file` | `File` |  | 원본 파일. 있어야 보내고 다시 시도할 수 있어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+upload 함수가 onProgress로 보낸 바이트를 알려 주면 막대와 남은 시간이 따라와요. 파일을 더 끌어 놓아 보세요.
+
+```tsx
+import { useState } from 'react'
+import { FileUpload, type UploadHandler, type UploadItem } from '@iamfiro/design'
+
+const MB = 1024 * 1024
+
+// 실제 앱에서는 fetch · XHR로 보내고 진행 이벤트를 onProgress로 넘겨요. signal이 끊기면 요청도 멈춰요.
+const fakeUpload: UploadHandler = (file, { onProgress, signal }) =>
+  new Promise((resolve) => {
+    let loaded = 0
+    const timer = setInterval(() => {
+      loaded = Math.min(file.size, loaded + file.size * (0.02 + Math.random() * 0.04))
+      onProgress(loaded)
+      if (loaded >= file.size) {
+        clearInterval(timer)
+        resolve(undefined)
+      }
+    }, 200)
+    signal.addEventListener('abort', () => clearInterval(timer))
+  })
+
+const sample = (name: string, mb: number) => new File([new Uint8Array(Math.round(mb * MB))], name)
+
+export default function Example() {
+  // 올리고 있던 파일로 시작해요. status가 'uploading'이고 file이 있으면 바로 보내기 시작해요.
+  const [initial] = useState<UploadItem[]>(() => [
+    { id: 'q3', name: '3분기 이사회 보고서.pdf', size: 4.2 * MB, status: 'uploading', file: sample('3분기 이사회 보고서.pdf', 4.2) },
+    { id: 'hero', name: '메인 이미지.png', size: 2.6 * MB, status: 'uploading', file: sample('메인 이미지.png', 2.6) },
+    { id: 'budget', name: '2027 예산안.xlsx', size: 1.3 * MB, status: 'uploading', file: sample('2027 예산안.xlsx', 1.3) },
+    { id: 'demo', name: '제품 데모.mp4', size: 48 * MB, status: 'error', error: '너무 커요 · 최대 25MB' },
+  ])
+
+  return (
+    <FileUpload
+      upload={fakeUpload}
+      defaultItems={initial}
+      maxSize={25 * MB}
+      description="PDF, PNG, JPG 등 · 파일당 최대 25MB"
+      style={{ width: 460 }}
+    />
+  )
+}
+```
+
+### 제한과 실패
+
+accept · maxSize · maxFiles에 걸리면 이유를 적은 줄이 생겨요(형식이 다르면 영역이 흔들려요). 보내다 실패하면 ↻로 다시 시도해요.
+
+```tsx
+import { FileUpload, type UploadHandler } from '@iamfiro/design'
+
+const MB = 1024 * 1024
+
+// 셋 중 하나는 절반쯤 가다가 실패해요. 실패한 줄의 ↻로 다시 보내요.
+const flakyUpload: UploadHandler = (file, { onProgress, signal }) =>
+  new Promise((resolve, reject) => {
+    const fail = Math.random() < 0.34
+    let loaded = 0
+    const timer = setInterval(() => {
+      loaded = Math.min(file.size, loaded + file.size * 0.08)
+      onProgress(loaded)
+      if (fail && loaded > file.size / 2) {
+        clearInterval(timer)
+        reject(new Error('연결이 끊겼어요 · 다시 시도해 주세요'))
+      } else if (loaded >= file.size) {
+        clearInterval(timer)
+        resolve(undefined)
+      }
+    }, 180)
+    signal.addEventListener('abort', () => clearInterval(timer))
+  })
+
+export default function Example() {
+  return (
+    <FileUpload
+      upload={flakyUpload}
+      accept="image/*,.pdf"
+      maxSize={5 * MB}
+      maxFiles={3}
+      title="증빙 서류를 끌어 놓거나 찾아보기"
+      style={{ width: 460 }}
+    />
+  )
+}
+```
+
+### 고르기만 하기 (제어)
+
+upload 없이 items로 목록만 관리하다가 폼을 보낼 때 한꺼번에 처리해요.
+
+```tsx
+import { useState } from 'react'
+import { Send } from 'lucide-react'
+import { Button, Stack, FileUpload, toast, type UploadItem } from '@iamfiro/design'
+
+export default function Example() {
+  // upload 없이 쓰면 고른 파일을 목록으로만 보여 줘요. 실제 전송은 폼을 보낼 때.
+  const [items, setItems] = useState<UploadItem[]>([])
+  const ready = items.filter((it) => it.status === 'done')
+
+  return (
+    <Stack gap={3} style={{ width: 460 }}>
+      <FileUpload items={items} onItemsChange={setItems} accept=".pdf,.docx,.hwp" maxFiles={5} showSummary={false} />
+      <Button
+        variant="primary"
+        icon={<Send />}
+        disabled={ready.length === 0}
+        onClick={() => {
+          toast.success(`파일 ${ready.length}개를 보냈어요`)
+          setItems([])
+        }}
+      >
+        {ready.length > 0 ? `${ready.length}개 보내기` : '보내기'}
+      </Button>
+    </Stack>
+  )
+}
+```

package/agents/filter-chips/AGENTS.md

@@ -0,0 +1,167 @@
+# FilterChips
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+목록을 좁히는 필터 칩. FilterChipGroup으로 묶어 하나 또는 여러 개를 고르거나, FilterChip 하나만 켜고 끄는 토글로 써요. 개수 표시, 초기화 버튼, 제거 가능한 적용 필터를 지원해요.
+
+```tsx
+import { FilterChipGroup, FilterChip } from '@iamfiro/design'
+```
+
+## API
+
+### FilterChipGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `type` (필수) | `'single' \| 'multiple'` |  | 하나만 / 여러 개. |
+| `value` | `V \| null  ·  V[] (multiple)` |  | 선택된 값(제어). V는 string \| number. |
+| `defaultValue` | `V \| null  ·  V[] (multiple)` |  | 처음 선택값(비제어). |
+| `onValueChange` | `(value: V \| null) => void  ·  (value: V[]) => void` |  | 값이 바뀔 때. |
+| `required` | `boolean` |  | type='single' 전용. 선택된 칩을 다시 눌러도 해제되지 않아요. |
+| `variant` | `'solid' \| 'soft'` | `'solid'` | solid: 선택 시 진한 색 · soft: 선택 시 파란 톤. 칩에 그대로 전달돼요. |
+| `size` | `'sm' \| 'md'` | `'md'` | 칩 크기. |
+| `clearable` | `boolean` |  | 하나라도 선택되면 초기화 버튼 표시. |
+| `clearLabel` | `ReactNode` | `'초기화'` | 초기화 버튼 문구. |
+| `disabled` | `boolean` |  | 모든 칩 비활성. |
+| `aria-label` | `string` |  | 그룹 이름(스크린 리더). |
+
+### FilterChip
+
+나머지 button 속성도 받아요. FilterChipGroup.Chip으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `string \| number` |  | 그룹 안에서 이 칩이 켜고 끄는 값. |
+| `selected` | `boolean` |  | 단독 사용 시 선택 상태(제어). |
+| `onSelectedChange` | `(selected: boolean) => void` |  | 단독 사용 시 눌렀을 때. |
+| `onRemove` | `() => void` |  | 있으면 × 버튼을 보여주고, 누르면 호출. |
+| `removeLabel` | `string` | `'필터 제거'` | × 버튼의 aria-label. |
+| `icon` | `ReactNode` |  | 앞 아이콘. 선택되면 체크로 바뀌어요. |
+| `count` | `number` |  | 오른쪽 개수. |
+| `variant` | `'solid' \| 'soft'` | `그룹 값 또는 'solid'` | 선택 스타일. |
+| `size` | `'sm' \| 'md'` | `그룹 값 또는 'md'` | 크기. |
+| `disabled` | `boolean` |  | 비활성. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 여러 개 선택 · 초기화
+
+count로 항목 수를 보여줘요. clearable이면 하나라도 고른 뒤에 초기화 버튼이 나타나요.
+
+```tsx
+import { useState } from 'react'
+import { FilterChip, FilterChipGroup } from '@iamfiro/design'
+
+export default function Example() {
+  const [teams, setTeams] = useState<string[]>(['design'])
+  return (
+    <FilterChipGroup type="multiple" value={teams} onValueChange={setTeams} clearable aria-label="팀">
+      <FilterChip value="design" count={12}>
+        디자인
+      </FilterChip>
+      <FilterChip value="dev" count={8}>
+        개발
+      </FilterChip>
+      <FilterChip value="marketing" count={5}>
+        마케팅
+      </FilterChip>
+      <FilterChip value="pm" count={3}>
+        기획
+      </FilterChip>
+      <FilterChip value="legal" count={0} disabled>
+        법무
+      </FilterChip>
+    </FilterChipGroup>
+  )
+}
+```
+
+### 하나만 선택 · soft
+
+variant='soft'는 선택된 칩을 파란 톤으로 칠해요. required면 선택을 끌 수 없어요.
+
+```tsx
+import { useState } from 'react'
+import { FilterChip, FilterChipGroup } from '@iamfiro/design'
+
+export default function Example() {
+  const [sort, setSort] = useState<string | null>('recent')
+  return (
+    <FilterChipGroup type="single" variant="soft" required value={sort} onValueChange={setSort} aria-label="정렬">
+      <FilterChip value="recent">최신순</FilterChip>
+      <FilterChip value="popular">인기순</FilterChip>
+      <FilterChip value="rating">평점순</FilterChip>
+      <FilterChip value="price">낮은 가격순</FilterChip>
+    </FilterChipGroup>
+  )
+}
+```
+
+### 적용된 필터
+
+onRemove를 주면 오른쪽에 × 버튼이 생겨요. removeLabel에 무엇을 지우는지 적어 주세요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Text, FilterChip } from '@iamfiro/design'
+
+const DEFAULT_FILTERS = [
+  { id: 'status', label: '상태: 진행 중' },
+  { id: 'owner', label: '담당자: 김민지' },
+  { id: 'due', label: '마감: 이번 주' },
+]
+
+export default function Example() {
+  const [filters, setFilters] = useState(DEFAULT_FILTERS)
+
+  const remove = (id: string) => setFilters((list) => list.filter((f) => f.id !== id))
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 8 }}>
+      {filters.map((f) => (
+        <FilterChip key={f.id} variant="soft" selected removeLabel={`${f.label} 필터 제거`} onRemove={() => remove(f.id)}>
+          {f.label}
+        </FilterChip>
+      ))}
+      {filters.length === 0 && (
+        <>
+          <Text variant="body-sm" tone="tertiary">
+            적용된 필터가 없어요
+          </Text>
+          <Button variant="ghost" size="sm" onClick={() => setFilters(DEFAULT_FILTERS)}>
+            기본 필터 복원
+          </Button>
+        </>
+      )}
+    </div>
+  )
+}
+```
+
+### 단독 사용
+
+그룹 없이 selected / onSelectedChange로 켜고 꺼요. icon은 선택되면 체크로 바뀌어요.
+
+```tsx
+import { useState } from 'react'
+import { Paperclip, Star } from 'lucide-react'
+import { FilterChip } from '@iamfiro/design'
+
+export default function Example() {
+  const [starred, setStarred] = useState(false)
+  const [withFiles, setWithFiles] = useState(true)
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <FilterChip size="sm" icon={<Star />} selected={starred} onSelectedChange={setStarred}>
+        즐겨찾기만
+      </FilterChip>
+      <FilterChip size="sm" icon={<Paperclip />} selected={withFiles} onSelectedChange={setWithFiles}>
+        첨부파일 있음
+      </FilterChip>
+    </div>
+  )
+}
+```