@iamfiro/design 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,81 @@
+# @iamfiro/design — 에이전트 안내
+
+React UI는 **이 디자인 시스템으로만** 만든다. 버튼 · 카드 · 입력 · 메뉴 · 모달 · 표 · 차트를 직접 만들지 않는다.
+이미 100개가 넘는 컴포넌트가 있고, 직접 만든 UI는 여백 · 색 · 애니메이션 · 접근성이 어긋난다.
+
+> 이 저장소에서 디자인 시스템 *자체*를 고치는 중이라면 이 문서가 아니라 `CLAUDE.md`와 `docs/COMPONENT_GUIDE.md`를 따른다.
+
+## 설치
+
+```bash
+npm install @iamfiro/design
+```
+
+앱 진입점에서 CSS를 **한 번** 불러온다(토큰 · 글꼴 · 기본 스타일 포함). 알림을 쓰면 `<Toaster />`도 한 번 둔다.
+
+```tsx
+import '@iamfiro/design/style.css'
+import { Toaster } from '@iamfiro/design'
+
+export function App() {
+  return (
+    <>
+      <Routes />
+      <Toaster />
+    </>
+  )
+}
+```
+
+모든 것은 패키지 루트 하나에서 가져온다: `import { Button, Card, Stack } from '@iamfiro/design'`. 아이콘은 `lucide-react`.
+
+## 작업 순서
+
+1. 만들 화면을 필요한 조각(목록, 필터, 카드, 폼…)으로 나눈다.
+2. 조각마다 [`agents/INDEX.md`](agents/INDEX.md)에서 맞는 컴포넌트를 찾는다.
+3. 쓰기 전에 그 컴포넌트의 `agents/<id>/AGENTS.md`(API · 디자인 규칙 · 예제)를 읽는다. props를 추측하지 않는다.
+4. 컴포넌트를 조립해 화면을 만든다. 배치는 `Stack` · `Inline` · `Grid`.
+
+패키지 안 경로: `node_modules/@iamfiro/design/AGENTS.md`, `node_modules/@iamfiro/design/agents/`.
+
+## 규칙
+
+- **새 UI 컴포넌트 금지.** 필요한 게 목록에 없으면 기존 컴포넌트 조립으로 해결한다(`Card` + `CardHeader` + `List` + `ListItem` + `Badge`…). 조립으로도 안 되면 사용자에게 무엇이 없는지 알린다.
+- **다른 UI 라이브러리 금지.** MUI · Chakra · shadcn/ui · Radix 스타일 컴포넌트 · Tailwind로 만든 버튼/카드를 섞지 않는다.
+- **배치는 레이아웃 컴포넌트로.** 즉석 `<div style={{ display: 'flex' }}>` 대신 `Stack`(세로) · `Inline`(가로) · `Grid` · `Box`. 간격은 `gap={1…10}`(4px 단위)만.
+- **글자는 `Text` · `Heading` · `Prose`로.** `font-size`를 직접 주지 않는다.
+- **스타일을 덮어쓰지 않는다.** `ds-*` 클래스를 재정의하거나 색 · 테두리 · 그림자를 `style`로 바꾸지 않는다. variant · size · tone props로 고른다. 꼭 필요한 색은 토큰(`var(--accent)`, `var(--text-muted)`…)만.
+- **테두리 · 회색 배경을 더하지 않는다.** 바탕은 흰색, 구분은 여백과 컴포넌트 자체 표면(`Card`)으로.
+- **글은 자연스러운 한국어.** 버튼은 동작 이름("삭제", "저장" — "확인" X). 샘플 데이터도 한국어(김민지, "10월 25일", "2분 전").
+- 상태 · 시간 · 숫자 조각도 있는 것을 쓴다: 상대 시간 `RelativeTime`, 증감 `Delta`, 라벨 + 숫자 `Stat`, 진행 `Progress` · `Spinner`, 빈 화면 `EmptyState`, 로딩 `Skeleton`.
+
+## 자주 찾는 것
+
+| 필요 | 쓸 것 |
+| --- | --- |
+| 앱 뼈대 · 사이드바 · 상단 경로 | `AppShell` · `Sidebar` · `Breadcrumb` |
+| 버튼 · 아이콘 버튼 · 링크 | `Button`(`iconOnly` + `aria-label` + `Tooltip`) · `Link` |
+| 콘텐츠 묶음 | `Card` + `CardHeader` / `CardBody` / `CardFooter` |
+| 사람 · 파일 · 설정 행 목록 | `List` + `ListItem`(`leading` · `trailing`) + `Avatar` / `IconTile` |
+| 폼 | `Field` + `Input` / `Textarea` / `Select` / `Combobox` / `Checkbox` / `Switch` / `DatePicker` |
+| 보기 전환 · 탭 | 같은 화면 안 `SegmentedControl`, 패널 전환 `Tabs` |
+| 필터 | `FilterChips` · `SearchInput` · `MultiSelect` |
+| 메뉴 · 팝오버 · 툴팁 | `DropdownMenu` · `Popover` · `Tooltip` · `ContextMenu` · `CommandMenu` |
+| 모달 · 서랍 | `Dialog` · `Drawer`, 되돌릴 수 없는 작업 확인은 `AlertDialog` |
+| 알림 | 잠깐 `toast()`, 되돌릴 수 있는 작업은 확인 대신 `toast.undo()`, 화면 안 `Alert` · `Banner` |
+| 표 | 보기만 `Table`, 편집 · 정렬 · 필터 `DataGrid`, 페이지 `Pagination` |
+| 라벨 · 개수 · 지표 | `Badge` · `CountBadge` · `Stat` / `StatGroup` · `Delta` |
+| 차트 | `LineChart` · `AreaChart` · `BarChart` · `PieChart` · `BarList` · `SparkChart` · `Tracker` |
+| 대화 · 댓글 · 활동 | `ChatBubble` · `ChatComposer` · `Comment` · `StepList` · `Timeline` |
+| 빈 상태 · 로딩 | `EmptyState` · `Skeleton` · `Spinner` |
+
+전체 목록: [`agents/INDEX.md`](agents/INDEX.md)
+
+## 내 프로젝트에 연결하기
+
+사용하는 프로젝트의 `AGENTS.md`(또는 `CLAUDE.md`)에 이 줄을 넣어 두면 에이전트가 매번 여기부터 읽는다.
+
+```md
+UI는 `@iamfiro/design`으로만 만든다. 작업 전에 `node_modules/@iamfiro/design/AGENTS.md`를 읽고,
+컴포넌트를 쓰기 전에 `node_modules/@iamfiro/design/agents/<id>/AGENTS.md`를 읽는다. 직접 컴포넌트를 만들지 않는다.
+```

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @iamfiro/design
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lumen 디자인 시스템 — React 19 컴포넌트 · 디자인 토큰 · 훅.
+
+```bash
+npm install @iamfiro/design
+```
+
+```tsx
+import '@iamfiro/design/style.css'
+import { Button, Card, CardHeader, Stack } from '@iamfiro/design'
+```
+
+- 에이전트(Claude Code · Codex 등) 안내: [AGENTS.md](AGENTS.md), 컴포넌트별 문서: [agents/INDEX.md](agents/INDEX.md)
+- 문서 사이트(개발): `npm run dev` → http://localhost:5179
+- 패키지 빌드: `npm run build:lib`, 에이전트 문서 다시 만들기: `npm run gen:agents`

package/agents/INDEX.md

@@ -0,0 +1,156 @@
+# 컴포넌트 목록
+
+`@iamfiro/design`의 모든 컴포넌트 · 파운데이션. 만들기 전에 여기서 찾고, 쓰기 전에 `agents/<id>/AGENTS.md`를 읽는다.
+
+## 파운데이션
+
+- **Colors** — 모든 색은 tokens.css의 CSS 변수로만 써요. → [`agents/colors/AGENTS.md`](colors/AGENTS.md)
+- **Typography** — 글자는 역할(role)로 골라요. → [`agents/typography/AGENTS.md`](typography/AGENTS.md)
+- **Layout** — 여백을 손으로 맞추지 않도록 돕는 레이아웃 기본 요소. → [`agents/layout/AGENTS.md`](layout/AGENTS.md)
+- **AspectRatio** — 폭은 부모를 따르고 높이는 비율로 정해지는 틀. → [`agents/aspect-ratio/AGENTS.md`](aspect-ratio/AGENTS.md)
+- **ScaledPreview** — 실제 컴포넌트를 높이가 고정된 무대 가운데에 작게 줄여 보여 줘요. → [`agents/scaled-preview/AGENTS.md`](scaled-preview/AGENTS.md)
+- **ScrollArea** — 어느 브라우저에서나 같은 스크롤바를 그리는 스크롤 영역. → [`agents/scroll-area/AGENTS.md`](scroll-area/AGENTS.md)
+
+## 버튼 & 링크
+
+- **Button** — 동작을 실행하는 기본 버튼. → [`agents/button/AGENTS.md`](button/AGENTS.md)
+- **CopyButton** — value를 클립보드에 복사하는 버튼. → [`agents/copy-button/AGENTS.md`](copy-button/AGENTS.md)
+- **SelectorButton** — 지금 선택된 것을 보여 주고 눌러서 바꾸는 조용한 버튼. → [`agents/selector-button/AGENTS.md`](selector-button/AGENTS.md)
+- **Link** — 글 속 링크. → [`agents/link/AGENTS.md`](link/AGENTS.md)
+- **ActionBar** — 상세 화면 · 검토 화면 아래에 붙는 동작 바. → [`agents/action-bar/AGENTS.md`](action-bar/AGENTS.md)
+- **Toolbar** — 버튼 · 토글 · ToggleGroup · 메뉴 트리거를 한 줄로 묶는 WAI-ARIA 툴바. → [`agents/toolbar/AGENTS.md`](toolbar/AGENTS.md)
+
+## 라벨 & 배지
+
+- **Badge** — 상태 · 분류 · 개수를 짧게 알려 주는 작은 라벨. → [`agents/badge/AGENTS.md`](badge/AGENTS.md)
+- **CountBadge** — 섹션 제목 · 아이콘 옆에 붙는 작은 숫자 원. → [`agents/count-badge/AGENTS.md`](count-badge/AGENTS.md)
+- **Kbd** — 단축키를 보여주는 키캡. → [`agents/kbd/AGENTS.md`](kbd/AGENTS.md)
+- **ColorDot** — 라벨과 시리즈·분류 색을 이어 주는 작은 색 표시. → [`agents/color-dot/AGENTS.md`](color-dot/AGENTS.md)
+- **Flag** — 국가를 나타내는 작은 3:2 국기. → [`agents/flag/AGENTS.md`](flag/AGENTS.md)
+- **RelativeTime** — "방금", "2분 전", "어제", "10월 25일"처럼 한국어 상대 시간을 <time dateTime>으로 보여 줘요. → [`agents/relative-time/AGENTS.md`](relative-time/AGENTS.md)
+
+## 아이콘 & 아바타
+
+- **Avatar** — 사람이나 팀을 나타내는 이름 배지. → [`agents/avatar/AGENTS.md`](avatar/AGENTS.md)
+- **IconTile** — 아이콘이나 글자 하나를 담는 작은 채움 타일. → [`agents/icon-tile/AGENTS.md`](icon-tile/AGENTS.md)
+- **IconStack** — 작은 아이콘 · 로고 2–3개를 겹쳐 한 줄로 보여 줘요. → [`agents/icon-stack/AGENTS.md`](icon-stack/AGENTS.md)
+- **BrandIcon** — 연동 앱의 원래 색 로고. → [`agents/brand-icon/AGENTS.md`](brand-icon/AGENTS.md)
+- **StatusIcon** — 체크리스트 · 일정 행 앞에 붙는 작은 단계 아이콘. → [`agents/status-icon/AGENTS.md`](status-icon/AGENTS.md)
+
+## 텍스트 입력
+
+- **Input** — 글자를 입력받는 기본 입력창과 Field · Textarea · NativeSelect. → [`agents/input/AGENTS.md`](input/AGENTS.md)
+- **SearchInput** — 돋보기 아이콘이 붙은 검색 입력창. → [`agents/search-input/AGENTS.md`](search-input/AGENTS.md)
+- **TagInput** — 자유롭게 친 글자를 태그로 모으는 입력 칸. → [`agents/tag-input/AGENTS.md`](tag-input/AGENTS.md)
+- **NumberStepper** — − 숫자 + 로 작은 수(작업자 수, 좌석, 재시도 횟수)를 바꿔요. → [`agents/number-stepper/AGENTS.md`](number-stepper/AGENTS.md)
+- **OTP Input** — 인증번호처럼 정해진 자리수의 코드를 입력하는 칸. → [`agents/otp-input/AGENTS.md`](otp-input/AGENTS.md)
+- **PhoneInput** — 국가를 고르고 전화번호를 입력하는 칸. → [`agents/phone-input/AGENTS.md`](phone-input/AGENTS.md)
+- **ChatComposer** — 대화형 AI 화면의 메시지 입력창. → [`agents/chat-composer/AGENTS.md`](chat-composer/AGENTS.md)
+
+## 선택 컨트롤
+
+- **Checkbox · Radio · Switch** — 켜고 끄는 선택 요소 세 가지. → [`agents/checkbox/AGENTS.md`](checkbox/AGENTS.md)
+- **SegmentedControl** — 몇 개의 보기 · 필터 중 하나를 고르는 컨트롤. → [`agents/segmented-control/AGENTS.md`](segmented-control/AGENTS.md)
+- **ToggleGroup** — 눌러서 켜고 끄는 버튼 묶음. → [`agents/toggle-group/AGENTS.md`](toggle-group/AGENTS.md)
+- **FilterChips** — 목록을 좁히는 필터 칩. → [`agents/filter-chips/AGENTS.md`](filter-chips/AGENTS.md)
+- **Slider** — 끌어서 값을 고르는 슬라이더. → [`agents/slider/AGENTS.md`](slider/AGENTS.md)
+- **Select** — 목록에서 하나를 고르는 커스텀 셀렉트. → [`agents/select/AGENTS.md`](select/AGENTS.md)
+- **MultiSelect** — 목록에서 여러 개를 고르는 셀렉트. → [`agents/multi-select/AGENTS.md`](multi-select/AGENTS.md)
+- **Combobox** — 입력하면서 검색해 고르는 셀렉트. → [`agents/combobox/AGENTS.md`](combobox/AGENTS.md)
+- **DatePicker · Calendar** — 날짜 입력. → [`agents/date-picker/AGENTS.md`](date-picker/AGENTS.md)
+- **ColorPicker** — 색을 고르는 패널. → [`agents/color-picker/AGENTS.md`](color-picker/AGENTS.md)
+- **Rating** — 별점. → [`agents/rating/AGENTS.md`](rating/AGENTS.md)
+- **TimePicker** — 시각 입력. → [`agents/time-picker/AGENTS.md`](time-picker/AGENTS.md)
+
+## 파일
+
+- **FileIcon** — 파일 종류를 색 띠로 알려 주는 종이 아이콘. → [`agents/file-icon/AGENTS.md`](file-icon/AGENTS.md)
+- **FileChip** — 첨부 파일을 작게 보여 주는 링크형 칩. → [`agents/file-chip/AGENTS.md`](file-chip/AGENTS.md)
+- **Dropzone** — 파일을 끌어 놓거나 눌러서 고르는 영역. → [`agents/dropzone/AGENTS.md`](dropzone/AGENTS.md)
+- **FileUpload** — 파일을 끌어 놓거나 골라서 올리고, 줄마다 → [`agents/file-upload/AGENTS.md`](file-upload/AGENTS.md)
+
+## 메뉴 & 오버레이
+
+- **DropdownMenu** — 버튼에서 펼쳐지는 동작 메뉴. → [`agents/dropdown-menu/AGENTS.md`](dropdown-menu/AGENTS.md)
+- **ContextMenu** — 마우스 오른쪽 버튼을 누른 자리에서 열리는 메뉴. → [`agents/context-menu/AGENTS.md`](context-menu/AGENTS.md)
+- **Menubar** — 데스크톱 앱처럼 파일 · 편집 · 보기 메뉴를 가로로 늘어놓은 막대. → [`agents/menubar/AGENTS.md`](menubar/AGENTS.md)
+- **CommandMenu** — ⌘K(Windows는 Ctrl+K)로 어디서든 여는 명령 팔레트. → [`agents/command-menu/AGENTS.md`](command-menu/AGENTS.md)
+- **Popover** — 트리거 옆에 붙어 뜨는 작은 패널. → [`agents/popover/AGENTS.md`](popover/AGENTS.md)
+- **HoverCard** — 이름·링크·저장소 위에 잠깐 머물면 뜨는 풍부한 미리보기. → [`agents/hover-card/AGENTS.md`](hover-card/AGENTS.md)
+- **Tooltip** — 아이콘 버튼처럼 글자가 없는 요소에 짧은 설명을 붙여요. → [`agents/tooltip/AGENTS.md`](tooltip/AGENTS.md)
+- **Dialog** — 페이지 위에 뜨는 모달. → [`agents/dialog/AGENTS.md`](dialog/AGENTS.md)
+- **Drawer · Sheet** — 화면 가장자리에서 미끄러져 들어오는 패널. → [`agents/drawer/AGENTS.md`](drawer/AGENTS.md)
+- **AlertDialog** — 되돌릴 수 없는 작업(영구 삭제, 결제, 대량 발송) 바로 앞에 한 번 더 묻는 확인 창. → [`agents/alert-dialog/AGENTS.md`](alert-dialog/AGENTS.md)
+
+## 내비게이션
+
+- **AppShell** — 앱의 뼈대. → [`agents/app-shell/AGENTS.md`](app-shell/AGENTS.md)
+- **Sidebar** — 세로 내비게이션. → [`agents/sidebar/AGENTS.md`](sidebar/AGENTS.md)
+- **Breadcrumb** — 지금 페이지가 어디에 있는지 보여 주는 경로. → [`agents/breadcrumb/AGENTS.md`](breadcrumb/AGENTS.md)
+- **Tabs** — 같은 자리에서 여러 패널을 바꿔 보여줘요. → [`agents/tabs/AGENTS.md`](tabs/AGENTS.md)
+- **Pagination** — 긴 목록을 페이지로 나눠 이동해요. → [`agents/pagination/AGENTS.md`](pagination/AGENTS.md)
+- **TreeView** — 단계별로 들여쓴 행을 접고 펴는 트리. → [`agents/tree-view/AGENTS.md`](tree-view/AGENTS.md)
+- **NavigationMenu** — 사이트 헤더의 메뉴(제품 · 보안 · 요금). → [`agents/navigation-menu/AGENTS.md`](navigation-menu/AGENTS.md)
+
+## 컨테이너
+
+- **Card** — 관련 내용을 한 덩어리로 묶는 흰 표면. → [`agents/card/AGENTS.md`](card/AGENTS.md)
+- **CardFrame** — 흰 Card를 옅은 회색 판으로 한 번 더 감싸는 틀. → [`agents/card-frame/AGENTS.md`](card-frame/AGENTS.md)
+- **List** — 사람 · 파일 · 설정처럼 같은 모양의 행을 나열해요. → [`agents/list/AGENTS.md`](list/AGENTS.md)
+- **Accordion · Collapsible** — 내용을 접었다 → [`agents/accordion/AGENTS.md`](accordion/AGENTS.md)
+- **SplitView** — 목록 – 상세(master–detail) 두 칸 레이아웃. → [`agents/split-view/AGENTS.md`](split-view/AGENTS.md)
+- **Resizable** — 경계를 끌어 크기를 나누는 패널 묶음. → [`agents/resizable/AGENTS.md`](resizable/AGENTS.md)
+
+## 알림
+
+- **Toast** — 잠깐 떠올랐다 → [`agents/toast/AGENTS.md`](toast/AGENTS.md)
+- **Alert · Banner** — 토스트와 달리 화면에 머무르는 메시지. → [`agents/alert/AGENTS.md`](alert/AGENTS.md)
+- **NoticeStack** — 닫을 수 있는 공지 카드 묶음(새 기능 소개, 팁, 점검 안내). → [`agents/notice-stack/AGENTS.md`](notice-stack/AGENTS.md)
+- **EmptyState** — 보여 줄 내용이 없을 때 이유와 다음 행동을 알려 주는 자리. → [`agents/empty-state/AGENTS.md`](empty-state/AGENTS.md)
+
+## 진행 표시
+
+- **Progress** — 작업이 얼마나 진행됐는지 보여 주는 막대와 원형 표시. → [`agents/progress/AGENTS.md`](progress/AGENTS.md)
+- **Spinner** — 옅은 고리 위로 호가 돌면서 늘었다 → [`agents/spinner/AGENTS.md`](spinner/AGENTS.md)
+- **Skeleton** — 내용이 들어올 자리를 미리 보여 주는 회색 자리 표시. → [`agents/skeleton/AGENTS.md`](skeleton/AGENTS.md)
+- **ProgressTracker** — 온보딩 체크리스트 카드. → [`agents/progress-tracker/AGENTS.md`](progress-tracker/AGENTS.md)
+- **StepList** — 단계를 세로로 이어 보여 주는 읽기 전용 타임라인. → [`agents/step-list/AGENTS.md`](step-list/AGENTS.md)
+- **Countdown** — 남은 시간을 "8초" · "1:05"처럼 글자로 보여 줘요. → [`agents/countdown/AGENTS.md`](countdown/AGENTS.md)
+- **Elapsed** — 시작한 뒤 지난 시간을 "17:40" · "17분 40초"처럼 글자로 올려 세요. → [`agents/elapsed/AGENTS.md`](elapsed/AGENTS.md)
+
+## 텍스트 & 코드
+
+- **Highlight** — 글 속 일부를 연한 상태색 배경으로 표시해요(warning · accent · danger). → [`agents/highlight/AGENTS.md`](highlight/AGENTS.md)
+- **MaskedText** — 계좌번호 · IBAN · 키처럼 민감한 값을 양 끝만 보이고 가운데는 점 묶음으로 가려요("DE89 •••• 3000"). → [`agents/masked-text/AGENTS.md`](masked-text/AGENTS.md)
+- **CodeBlock** — 읽기 전용 코드 블록. → [`agents/code-block/AGENTS.md`](code-block/AGENTS.md)
+- **InlineDiff** — 글 속 변경 내용(추적된 변경)을 그대로 보여 줘요. → [`agents/inline-diff/AGENTS.md`](inline-diff/AGENTS.md)
+
+## 데이터 표시
+
+- **Table** — 격자선 없는 데이터 표. → [`agents/table/AGENTS.md`](table/AGENTS.md)
+- **DataGrid** — Notion 데이터베이스처럼 타입이 있는 속성과 보기(정렬·필터·그룹·검색)를, Google Sheets·Numbers처럼 범위 선택·키보드 편집·복사/붙여넣기·채우기 핸들을 갖춘 표. → [`agents/data-grid/AGENTS.md`](data-grid/AGENTS.md)
+- **Kanban** — 열 사이로 카드를 끌어 옮기는 보드. → [`agents/kanban/AGENTS.md`](kanban/AGENTS.md)
+- **DescriptionList** — 라벨 · 값 쌍을 진짜 <dl>로 보여 줘요. → [`agents/description-list/AGENTS.md`](description-list/AGENTS.md)
+- **Stat** — 라벨과 숫자 하나. → [`agents/stat/AGENTS.md`](stat/AGENTS.md)
+- **Delta** — 이전 · 목표와 비교한 증감을 부호와 함께 보여 줘요. → [`agents/delta/AGENTS.md`](delta/AGENTS.md)
+- **Tracker** — 하루(또는 한 시간)에 한 칸씩 상태를 색으로 늘어놓은 기록 띠. → [`agents/tracker/AGENTS.md`](tracker/AGENTS.md)
+- **TreeDiagram** — 조직도 · 작업 분해처럼 위계를 상자와 연결선으로 그려요. → [`agents/tree-diagram/AGENTS.md`](tree-diagram/AGENTS.md)
+
+## 대화 & 활동
+
+- **Comment** — 댓글 · 토론의 메시지 한 개. → [`agents/comment/AGENTS.md`](comment/AGENTS.md)
+- **ChatBubble** — 채팅 메시지 한 개를 채워진 말풍선으로 보여 줘요. → [`agents/chat-bubble/AGENTS.md`](chat-bubble/AGENTS.md)
+- **Marker** — 대화 · 활동 기록 사이에 끼는 이벤트 한 줄. → [`agents/marker/AGENTS.md`](marker/AGENTS.md)
+- **Timeline** — 숫자 구간(초, 분, 시각)을 가로 위치로 옮겨 그리는 시간 축. → [`agents/timeline/AGENTS.md`](timeline/AGENTS.md)
+
+## 차트
+
+- **LineChart** — 여러 시리즈의 추이를 비교하는 선 차트. → [`agents/line-chart/AGENTS.md`](line-chart/AGENTS.md)
+- **AreaChart** — 양의 크기와 구성을 함께 보여 주는 영역 차트. → [`agents/area-chart/AGENTS.md`](area-chart/AGENTS.md)
+- **BarChart** — 항목끼리 크기를 비교하는 막대 차트. → [`agents/bar-chart/AGENTS.md`](bar-chart/AGENTS.md)
+- **PieChart** — 전체 중 각 부분의 비율을 보여주는 도넛·원 차트. → [`agents/pie-chart/AGENTS.md`](pie-chart/AGENTS.md)
+- **ScatterChart** — 두 값의 관계를 점으로 보여주는 산점도. → [`agents/scatter-chart/AGENTS.md`](scatter-chart/AGENTS.md)
+- **FunnelChart** — 단계별 전환을 보여주는 퍼널 차트. → [`agents/funnel-chart/AGENTS.md`](funnel-chart/AGENTS.md)
+- **BarList** — 많이 본 페이지 · 유입 경로 · 국가처럼 순위를 매긴 가로 막대 목록. → [`agents/bar-list/AGENTS.md`](bar-list/AGENTS.md)
+- **SparkChart** — 축 없이 흐름만 보여 주는 아주 작은 차트. → [`agents/spark-chart/AGENTS.md`](spark-chart/AGENTS.md)
+- **Sparkbar** — 축 없이 막대만 늘어놓은 작은 막대 줄. → [`agents/sparkbar/AGENTS.md`](sparkbar/AGENTS.md)

package/agents/accordion/AGENTS.md

@@ -0,0 +1,279 @@
+# Accordion · Collapsible
+
+> 컨테이너 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+내용을 접었다 펴는 섹션. Collapsible은 하나짜리, Accordion은 여러 개를 묶어 하나만 또는 여러 개를 열어 둬요. 실제 높이만큼 부드럽게 펼쳐지고, 헤더 사이를 ↑ ↓ · Home / End로 이동해요.
+
+```tsx
+import { Accordion, AccordionItem, Collapsible } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 접고 펴는 영역(Accordion, Sidebar 그룹)은 `grid-template-rows: 0fr ↔ 1fr`로 실제 높이까지 애니메이션. 글 안의 작은 상태 줄·"자세히" 토글은 새로 만들지 말고 `Collapsible variant="inline"`.
+
+## API
+
+### Accordion
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `type` (필수) | `'single' \| 'multiple'` |  | 하나만 열기 / 여러 개 열기. |
+| `value` | `string \| null  /  string[]` |  | 열린 항목(제어). single이면 값 하나, multiple이면 배열. |
+| `defaultValue` | `string \| null  /  string[]` |  | 처음 열린 항목(비제어). |
+| `onValueChange` | `(value) => void` |  | 열린 항목이 바뀔 때. |
+| `required` | `boolean` |  | single 전용. 열린 항목을 다시 눌러도 닫히지 않아요. |
+| `variant` | `'plain' \| 'separated' \| 'filled'` | `'plain'` | plain: 여백으로 구분 · separated: 항목마다 흰 카드 · filled: 열린 항목이 옅은 회색 판 위에(카드 안 그룹 체크리스트). |
+| `className` | `string` |  | 바깥 요소에 전달. |
+
+### AccordionItem
+
+Accordion.Item으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 항목 고유 값. |
+| `title` (필수) | `ReactNode` |  | 헤더 제목. |
+| `children` (필수) | `ReactNode` |  | 펼쳐질 내용. |
+| `description` | `ReactNode` |  | 제목 아래 회색 설명. |
+| `icon` | `ReactNode` |  | 제목 앞 아이콘. |
+| `disabled` | `boolean` |  | 비활성. 열리지 않아요. |
+| `flush` | `boolean` |  | 내용 좌우 여백을 없애요. 안에 List를 넣으면 행 여백(12px)이 filled 제목과 왼쪽 끝을 맞춰요. |
+
+### Collapsible
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 항상 보이는 헤더(토글 버튼 안). |
+| `children` (필수) | `ReactNode` |  | 펼쳐질 내용. |
+| `open` | `boolean` |  | 열림 상태(제어). |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `onOpenChange` | `(open: boolean) => void` |  | 열리거나 닫힐 때. |
+| `description` | `ReactNode` |  | 헤더 아래 설명. |
+| `icon` | `ReactNode` |  | 헤더 앞 아이콘. |
+| `disabled` | `boolean` |  | 비활성. |
+| `variant` | `'default' \| 'inline'` | `'default'` | default: 폭을 채우는 헤더 행 · inline: 글자 크기만 한 작은 토글(제목 요소가 아닌 div). |
+| `iconTone` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | 앞 아이콘 색. |
+| `className` | `string` |  | 바깥 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 하나만 열기 (FAQ)
+
+type="single"은 하나를 열면 나머지가 닫혀요. required를 주면 열린 항목을 다시 눌러도 모두 닫히지는 않아요.
+
+```tsx
+import { Box, Text, Accordion, AccordionItem } from '@iamfiro/design'
+
+const FAQ = [
+  { value: 'refund', q: '환불은 어떻게 받나요?', a: '결제일로부터 14일 안에 설정 › 결제에서 환불을 요청하면 3영업일 안에 처리돼요.' },
+  { value: 'seats', q: '멤버를 추가하면 요금이 바로 바뀌나요?', a: '추가한 날부터 남은 기간만큼 일할 계산돼 다음 결제에 함께 청구돼요.' },
+  { value: 'export', q: '데이터를 내보낼 수 있나요?', a: '모든 요금제에서 CSV와 JSON으로 내보낼 수 있어요. 큰 파일은 완료되면 이메일로 링크를 보내 드려요.' },
+  { value: 'cancel', q: '해지하면 데이터는 어떻게 되나요?', a: '해지 후 30일 동안 보관되고, 그 안에 다시 구독하면 그대로 복구돼요.' },
+]
+
+export default function Example() {
+  return (
+    <Box style={{ width: 520 }}>
+      <Accordion type="single" defaultValue="refund">
+        {FAQ.map((item) => (
+          <AccordionItem key={item.value} value={item.value} title={item.q}>
+            <Text variant="body-sm" tone="secondary">
+              {item.a}
+            </Text>
+          </AccordionItem>
+        ))}
+      </Accordion>
+    </Box>
+  )
+}
+```
+
+### 여러 개 열기
+
+type="multiple"은 여러 항목을 함께 열어 둬요. value / onValueChange로 제어하면 모두 펼치기 · 접기도 만들 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, Text, Accordion, AccordionItem } from '@iamfiro/design'
+
+const SECTIONS = [
+  { value: 'scope', title: '범위', body: '랜딩 페이지, 가격 페이지, 온보딩 3단계를 새 디자인 시스템으로 옮겨요.' },
+  { value: 'schedule', title: '일정', body: '10월 28일 디자인 확정, 11월 4일 개발 완료, 11월 7일 출시.' },
+  { value: 'owners', title: '담당자', body: '디자인 김민지 · 프론트엔드 이도현 · QA 박서연.' },
+]
+
+const ALL = SECTIONS.map((s) => s.value)
+
+export default function Example() {
+  const [open, setOpen] = useState<string[]>(['scope'])
+  const allOpen = open.length === ALL.length
+  return (
+    <Stack gap={3} style={{ width: 520 }}>
+      <Inline justify="between">
+        <Text variant="label-md">출시 계획</Text>
+        <Button variant="ghost" size="sm" onClick={() => setOpen(allOpen ? [] : ALL)}>
+          {allOpen ? '모두 접기' : '모두 펼치기'}
+        </Button>
+      </Inline>
+      <Accordion type="multiple" value={open} onValueChange={setOpen}>
+        {SECTIONS.map((s) => (
+          <AccordionItem key={s.value} value={s.value} title={s.title}>
+            <Text variant="body-sm" tone="secondary">
+              {s.body}
+            </Text>
+          </AccordionItem>
+        ))}
+      </Accordion>
+    </Stack>
+  )
+}
+```
+
+### 카드형
+
+variant="separated"는 항목마다 흰 카드에 올려요. icon과 description으로 헤더를 풍부하게. disabled 항목은 열리지 않아요.
+
+```tsx
+import { Bell, CreditCard, Lock, Users } from 'lucide-react'
+import { Box, Switch, Stack, Text, Accordion, AccordionItem } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Box style={{ width: 520 }}>
+      <Accordion type="single" variant="separated" defaultValue="notifications">
+        <AccordionItem value="notifications" icon={<Bell />} title="알림" description="이메일 · 푸시 · 요약 메일">
+          <Stack gap={3}>
+            <Switch label="멘션되면 푸시 알림" defaultChecked />
+            <Switch label="매주 월요일 요약 메일" />
+          </Stack>
+        </AccordionItem>
+        <AccordionItem value="members" icon={<Users />} title="멤버" description="6명 · 관리자 2명">
+          <Text variant="body-sm" tone="secondary">
+            김민지님과 이도현님이 관리자예요. 역할은 멤버 페이지에서 바꿀 수 있어요.
+          </Text>
+        </AccordionItem>
+        <AccordionItem value="billing" icon={<CreditCard />} title="결제" description="팀 요금제 · 다음 결제 11월 1일">
+          <Text variant="body-sm" tone="secondary">
+            신한카드 •••• 4821로 매월 1일에 결제돼요.
+          </Text>
+        </AccordionItem>
+        <AccordionItem value="sso" icon={<Lock />} title="SSO" description="엔터프라이즈 요금제에서 쓸 수 있어요" disabled>
+          SAML 설정
+        </AccordionItem>
+      </Accordion>
+    </Box>
+  )
+}
+```
+
+### 회색 판 (variant="filled")
+
+열린 항목이 옅은 회색 판 위에 놓여요. 카드 안에서 그룹을 나눌 때(ProgressTracker groups). flush 항목 안의 List 행은 제목과 왼쪽 끝이 맞고, ListItem variant="raised"면 회색 판 위에서도 hover가 보여요.
+
+```tsx
+import { CalendarDays, CreditCard, Users } from 'lucide-react'
+import { Box, Accordion, AccordionItem, Card, List, ListItem } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card style={{ width: 360 }}>
+      {/* 4px 안쪽에 회색 판, 판 안의 12px 여백이 카드의 16px 왼쪽 끝과 맞아요. */}
+      <Box padding={1}>
+        <Accordion type="single" defaultValue="team" variant="filled">
+          <AccordionItem value="team" title="팀 설정" flush>
+            <List aria-label="팀 설정">
+              <ListItem variant="raised" leading={<Users />} title="멤버 관리" description="김민지 외 5명" onClick={() => {}} />
+              <ListItem variant="raised" leading={<CalendarDays />} title="근무 일정" description="평일 9시 – 18시" onClick={() => {}} />
+            </List>
+          </AccordionItem>
+          <AccordionItem value="billing" title="결제" flush>
+            <List aria-label="결제">
+              <ListItem variant="raised" leading={<CreditCard />} title="결제 수단" description="법인 카드 · 끝자리 2048" onClick={() => {}} />
+            </List>
+          </AccordionItem>
+          <AccordionItem value="notice" title="공지">
+            새 공지는 매주 월요일 오전에 올라와요. 지난 공지는 보관함에서 다시 볼 수 있어요.
+          </AccordionItem>
+        </Accordion>
+      </Box>
+    </Card>
+  )
+}
+```
+
+### Collapsible
+
+섹션 하나만 접을 때. open / onOpenChange로 제어하거나 defaultOpen으로 비제어.
+
+```tsx
+import { useState } from 'react'
+import { Settings2 } from 'lucide-react'
+import { Button, Field, Inline, Input, Stack, Switch, Collapsible } from '@iamfiro/design'
+
+export default function Example() {
+  const [advanced, setAdvanced] = useState(false)
+  return (
+    <Stack as="form" gap={5} style={{ width: 440 }} onSubmit={(e) => e.preventDefault()}>
+      <Field label="웹훅 URL" htmlFor="hook-url">
+        <Input id="hook-url" placeholder="https://example.com/hooks/lumen" />
+      </Field>
+      <Collapsible
+        icon={<Settings2 />}
+        label="고급 설정"
+        description={advanced ? undefined : '재시도 · 타임아웃 · 서명'}
+        open={advanced}
+        onOpenChange={setAdvanced}
+      >
+        <Stack gap={4}>
+          <Field label="타임아웃 (초)" htmlFor="hook-timeout">
+            <Input id="hook-timeout" type="number" defaultValue={10} />
+          </Field>
+          <Switch label="실패하면 3번까지 다시 보내기" defaultChecked />
+          <Switch label="요청에 서명 헤더 붙이기" />
+        </Stack>
+      </Collapsible>
+      <Inline justify="end">
+        <Button variant="primary" type="submit">
+          저장
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 인라인 상태 줄 (variant="inline")
+
+글자 크기만 한 작은 토글(아이콘 + 라벨 + 회전하는 chevron). 메시지 아래 "수정 완료" 같은 상태 줄이나 "자세히 보기"에 써요. iconTone으로 아이콘 색을 정하고, 펼치면 실제 높이만큼 부드럽게 열려요.
+
+```tsx
+import { CircleAlert, CircleCheck, ListTree } from 'lucide-react'
+import { Stack, Text, Collapsible } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: 360 }}>
+      <Stack gap={1}>
+        <Text variant="body-md">소개 문단을 두 문장으로 줄였어요.</Text>
+        <Collapsible variant="inline" icon={<CircleCheck />} iconTone="success" label="수정 완료" defaultOpen>
+          3문장 → 2문장 · 128자 줄임 · 맞춤법 2곳 고침
+        </Collapsible>
+      </Stack>
+      <Stack gap={1}>
+        <Text variant="body-md">첨부한 표 일부를 읽지 못했어요.</Text>
+        <Collapsible variant="inline" icon={<CircleAlert />} iconTone="warning" label="2개 항목 건너뜀">
+          3행과 7행의 날짜 형식이 달라요. 2026-10-25처럼 맞춰 다시 올려 주세요.
+        </Collapsible>
+      </Stack>
+      <Collapsible variant="inline" icon={<ListTree />} label="자세히 보기">
+        <Text variant="body-sm" tone="secondary">
+          아이콘이 없으면 내용은 왼쪽 끝에, 있으면 라벨과 같은 선에 맞춰져요.
+        </Text>
+      </Collapsible>
+    </Stack>
+  )
+}
+```

package/agents/action-bar/AGENTS.md

@@ -0,0 +1,90 @@
+# ActionBar
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+상세 화면 · 검토 화면 아래에 붙는 동작 바. 흰 바탕에 위쪽으로 옅은 그림자만 있고 선은 없어요. 스크롤되는 영역 안에서 아래에 붙어 있고(sticky), 단축키 힌트가 있는 Button(shortcut · hotkey)을 모아 둬요. pending이면 안의 버튼과 단축키가 한꺼번에 잠겨요.
+
+```tsx
+import { ActionBar } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 단축키가 있는 버튼은 `Button shortcut`(힌트만) + `hotkey`(듣기: 입력 중 글자 키 · IME 조합 · 비활성은 무시). 여러 개는 `ActionBar`(흰 바탕 + 위 그림자, `pending`이면 fieldset으로 한꺼번에 잠금).
+
+## API
+
+### ActionBar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 보통 shortcut이 있는 Button들. |
+| `align` | `'start' \| 'center' \| 'end' \| 'between'` | `'center'` | 버튼 정렬. between은 두 묶음을 양 끝으로. |
+| `sticky` | `boolean` | `true` | 스크롤 영역의 아래에 붙어 있어요. |
+| `pending` | `boolean` |  | 처리 중. 안의 모든 컨트롤을 비활성 fieldset으로 한꺼번에 잠가요(단축키 포함, aria-busy). |
+| `aria-label` | `string` |  | 동작 묶음의 이름(예: "요청 처리"). |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 검토 동작 + 처리 중 잠금
+
+승인 A · 수정 E · 거절 R · 건너뛰기 S. 누르거나 키를 누르면 처리하는 동안(pending) 모든 버튼과 단축키가 잠기고, 끝나면 다음 요청으로 넘어가요.
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Check, ChevronsRight, Pencil, X } from 'lucide-react'
+import { Box, Button, Stack, Text, ActionBar, Card, toast } from '@iamfiro/design'
+
+const REQUESTS = ['10월 법인 카드 정산', '이도현 님 계정 권한 요청', '협력사 계약서 검토']
+
+export default function Example() {
+  const [index, setIndex] = useState(0)
+  const [pending, setPending] = useState<string | null>(null)
+
+  // 데모용 처리: 0.8초 뒤 다음 요청으로 넘어가요. 그동안 버튼과 단축키가 함께 잠겨요.
+  useEffect(() => {
+    if (!pending) return
+    const id = window.setTimeout(() => {
+      toast.success(`${pending} 처리했어요`)
+      setPending(null)
+      setIndex((i) => (i + 1) % REQUESTS.length)
+    }, 800)
+    return () => window.clearTimeout(id)
+  }, [pending])
+
+  const act = (label: string) => () => setPending(label)
+
+  return (
+    <Card padding="none" style={{ width: 520 }}>
+      <Box padding={5}>
+        <Stack gap={1}>
+          <Text variant="caption" tone="tertiary">
+            승인 요청 {index + 1} / {REQUESTS.length}
+          </Text>
+          <Text variant="heading-sm">{REQUESTS[index]}</Text>
+          <Text variant="body-sm" tone="secondary">
+            김민지 님이 2분 전에 보냈어요. A · E · R · S 키로도 처리할 수 있어요.
+          </Text>
+        </Stack>
+      </Box>
+      <ActionBar pending={pending !== null} 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>
+    </Card>
+  )
+}
+```