@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/segmented-control/AGENTS.md

@@ -0,0 +1,153 @@
+# SegmentedControl
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+몇 개의 보기 · 필터 중 하나를 고르는 컨트롤. 선택 배경이 항목 사이를 미끄러지듯 옮겨 가요. 탭을 누르거나 포커스한 뒤 ← → 키로 바꿀 수 있고, 끝에서는 반대쪽 처음으로 돌아가요.
+
+```tsx
+import { SegmentedControl, type SegmentOption } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 탭은 `Tabs`(패널 연결). `SegmentedControl`은 같은 화면 안의 보기 전환에만.
+
+## API
+
+### SegmentedControl
+
+role="tablist"로 렌더되고 각 항목은 role="tab"이에요. 선택된 항목만 Tab으로 포커스돼요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `options` (필수) | `SegmentOption<T>[]` |  | 항목 목록. |
+| `value` (필수) | `T` |  | 선택된 값. |
+| `onChange` (필수) | `(value: T) => void` |  | 선택이 바뀔 때(클릭, ← → 키). |
+| `variant` | `'pill' \| 'underline' \| 'chip' \| 'text'` | `'pill'` | 모양. |
+| `ariaLabel` | `string` |  | 스크린 리더용 이름. 꼭 넣어 주세요. |
+
+### SegmentOption
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `T extends string` |  | 고유 값. |
+| `label` (필수) | `ReactNode` |  | 보이는 글자. |
+| `icon` | `ReactNode` |  | 글자 앞 아이콘. |
+| `count` | `number` |  | 글자 뒤 숫자. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본 (pill)
+
+움푹 들어간 트랙 위에서 흰 선택 배경이 움직여요. value와 onChange로 제어해요.
+
+```tsx
+import { useState } from 'react'
+import { SegmentedControl } from '@iamfiro/design'
+
+type Period = 'day' | 'week' | 'month' | 'year'
+
+export default function Example() {
+  const [period, setPeriod] = useState<Period>('week')
+  return (
+    <SegmentedControl
+      ariaLabel="기간"
+      value={period}
+      onChange={setPeriod}
+      options={[
+        { value: 'day', label: '일간' },
+        { value: 'week', label: '주간' },
+        { value: 'month', label: '월간' },
+        { value: 'year', label: '연간' },
+      ]}
+    />
+  )
+}
+```
+
+### 아이콘
+
+icon은 글자 앞에 붙어요. 보기 방식 전환에 잘 어울려요.
+
+```tsx
+import { useState } from 'react'
+import { Columns3, LayoutGrid, List } from 'lucide-react'
+import { SegmentedControl, type SegmentOption } from '@iamfiro/design'
+
+type View = 'grid' | 'list' | 'board'
+
+const VIEWS: SegmentOption<View>[] = [
+  { value: 'grid', label: '그리드', icon: <LayoutGrid /> },
+  { value: 'list', label: '리스트', icon: <List /> },
+  { value: 'board', label: '보드', icon: <Columns3 /> },
+]
+
+export default function Example() {
+  const [view, setView] = useState<View>('grid')
+  return <SegmentedControl ariaLabel="보기 방식" value={view} onChange={setView} options={VIEWS} />
+}
+```
+
+### 밑줄 탭 (underline) · 개수
+
+페이지 상단 탭 바. count를 주면 글자 옆에 숫자가 붙어요(tabular-nums).
+
+```tsx
+import { useState } from 'react'
+import { SegmentedControl, type SegmentOption } from '@iamfiro/design'
+
+type Filter = 'all' | 'open' | 'review' | 'done'
+
+const FILTERS: SegmentOption<Filter>[] = [
+  { value: 'all', label: '전체', count: 24 },
+  { value: 'open', label: '진행 중', count: 9 },
+  { value: 'review', label: '검토 중', count: 3 },
+  { value: 'done', label: '완료', count: 12 },
+]
+
+export default function Example() {
+  const [filter, setFilter] = useState<Filter>('all')
+  return <SegmentedControl variant="underline" ariaLabel="이슈 상태" value={filter} onChange={setFilter} options={FILTERS} />
+}
+```
+
+### 칩 (chip) · 텍스트 (text)
+
+chip은 항목이 서로 떨어진 칩 모양, text는 배경 없이 글자 색만 바뀌어요.
+
+```tsx
+import { useState } from 'react'
+import { SegmentedControl, Text, type SegmentOption } from '@iamfiro/design'
+
+type Section = 'overview' | 'analytics' | 'reports' | 'notifications'
+
+const SECTIONS: SegmentOption<Section>[] = [
+  { value: 'overview', label: '개요' },
+  { value: 'analytics', label: '분석' },
+  { value: 'reports', label: '리포트' },
+  { value: 'notifications', label: '알림', count: 3 },
+]
+
+export default function Example() {
+  const [chip, setChip] = useState<Section>('overview')
+  const [text, setText] = useState<Section>('overview')
+  return (
+    <div style={{ display: 'grid', gap: 20, justifyItems: 'start' }}>
+      <div style={{ display: 'grid', gap: 8 }}>
+        <Text variant="caption" tone="tertiary">
+          chip
+        </Text>
+        <SegmentedControl variant="chip" ariaLabel="대시보드" value={chip} onChange={setChip} options={SECTIONS} />
+      </div>
+      <div style={{ display: 'grid', gap: 8 }}>
+        <Text variant="caption" tone="tertiary">
+          text
+        </Text>
+        <SegmentedControl variant="text" ariaLabel="대시보드" value={text} onChange={setText} options={SECTIONS} />
+      </div>
+    </div>
+  )
+}
+```

package/agents/select/AGENTS.md

@@ -0,0 +1,159 @@
+# Select
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+목록에서 하나를 고르는 커스텀 셀렉트. 그룹·설명·아이콘·비활성 항목을 지원하고, 키보드(↑↓, Home/End, 글자 입력)로 빠르게 이동해요. 팝오버는 열리고 닫힐 때 모두 애니메이션돼요.
+
+```tsx
+import { Select, type ListOption } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 숫자만 받는 칸(금액 · 전화번호 · 카드 번호)은 `useDigitInput`을 Input에 펼친다: 글자는 아예 안 들어가고, 쉼표 · 하이픈은 `format`으로 붙이고, 커서는 같은 숫자 뒤에 머물고, 구분자 위 Backspace는 앞 숫자를 지운다. `type="number"`는 쓰지 않는다. 전화번호는 `PhoneInput`(칸 안 `Select bare` 국가 선택 + 국기 `Flag`, 목록은 `anchorRef`로 칸 전체 폭). 국기는 이모지 대신 `Flag`(Windows에서 이모지 국기는 글자로 나온다).
+
+## API
+
+### Select
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `options` (필수) | `ListOption<V>[]` |  | 선택지 목록. |
+| `value` | `V \| null` |  | 선택된 값(제어). null은 선택 없음. |
+| `defaultValue` | `V \| null` | `null` | 처음 선택값(비제어). |
+| `onValueChange` | `(value: V) => void` |  | 값이 바뀔 때. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `placeholder` | `ReactNode` | `'선택하세요'` | 선택 전 문구. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `invalid` | `boolean` |  | 오류 표시. |
+| `disabled` | `boolean` |  | 비활성. |
+| `leading` | `ReactNode` |  | 값 앞 아이콘. 생략하면 선택된 항목의 icon. |
+| `renderValue` | `(option) => ReactNode` |  | 트리거에 보일 내용을 직접 그릴 때. |
+| `renderOption` | `(option, state) => ReactNode` |  | 목록 행을 직접 그릴 때. |
+| `name` | `string` |  | 폼 제출용 hidden input 이름. |
+| `maxHeight` | `number` | `300` | 팝오버 최대 높이. |
+
+### ListOption
+
+Select · MultiSelect · Combobox가 함께 쓰는 선택지 형태.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `V extends string` |  | 고유 값. |
+| `label` (필수) | `string` |  | 표시 이름(검색·글자 이동에도 사용). |
+| `description` | `ReactNode` |  | 이름 아래 보조 설명. |
+| `icon` | `ReactNode` |  | 앞 아이콘. |
+| `group` | `string` |  | 그룹 제목. 같은 그룹은 붙여 두세요. |
+| `disabled` | `boolean` |  | 선택 불가. |
+| `keywords` | `string[]` |  | Combobox 검색에 쓰는 추가 단어. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+options와 value / onValueChange만 있으면 돼요. value를 생략하면 defaultValue로 비제어 사용.
+
+```tsx
+import { useState } from 'react'
+import { Select, type ListOption } from '@iamfiro/design'
+
+const FRUITS: ListOption[] = [
+  { value: 'apple', label: '사과' },
+  { value: 'banana', label: '바나나' },
+  { value: 'grape', label: '포도' },
+  { value: 'peach', label: '복숭아' },
+]
+
+export default function Example() {
+  const [fruit, setFruit] = useState<string | null>('apple')
+  return (
+    <div style={{ width: 280 }}>
+      <Select options={FRUITS} value={fruit} onValueChange={setFruit} aria-label="과일" />
+    </div>
+  )
+}
+```
+
+### 그룹 · 설명 · 비활성
+
+같은 group 값을 가진 항목은 제목 아래 묶여요. disabled 항목은 건너뛰고 선택할 수 없어요.
+
+```tsx
+import { Select, type ListOption } from '@iamfiro/design'
+
+const REGIONS: ListOption[] = [
+  { value: 'icn', label: '서울', description: 'icn1 · 지연 시간 가장 짧음', group: '아시아' },
+  { value: 'nrt', label: '도쿄', description: 'nrt1', group: '아시아' },
+  { value: 'sin', label: '싱가포르', description: 'sin1', group: '아시아' },
+  { value: 'sfo', label: '샌프란시스코', description: 'sfo1', group: '미국' },
+  { value: 'iad', label: '워싱턴', description: 'iad1 · 점검 중', group: '미국', disabled: true },
+  { value: 'fra', label: '프랑크푸르트', description: 'fra1', group: '유럽' },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: 300 }}>
+      <Select options={REGIONS} defaultValue="icn" aria-label="리전" />
+    </div>
+  )
+}
+```
+
+### 아이콘
+
+선택된 항목의 아이콘은 트리거에도 표시돼요.
+
+```tsx
+import { Circle, CircleCheck, CircleDashed, CircleDot } from 'lucide-react'
+import { Select, type ListOption } from '@iamfiro/design'
+
+const STATUSES: ListOption[] = [
+  { value: 'todo', label: '할 일', icon: <CircleDashed /> },
+  { value: 'doing', label: '진행 중', icon: <CircleDot color="var(--info)" /> },
+  { value: 'review', label: '검토 중', icon: <Circle color="var(--warning)" /> },
+  { value: 'done', label: '완료', icon: <CircleCheck color="var(--success)" /> },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: 260 }}>
+      <Select options={STATUSES} placeholder="상태를 선택하세요" aria-label="상태" />
+    </div>
+  )
+}
+```
+
+### 크기와 상태
+
+size, invalid, disabled. Field와 함께 쓰면 라벨이 자동으로 연결돼요.
+
+```tsx
+import { Field, Select, type ListOption } from '@iamfiro/design'
+
+const PLANS: ListOption[] = [
+  { value: 'starter', label: '스타터' },
+  { value: 'team', label: '팀' },
+  { value: 'enterprise', label: '엔터프라이즈' },
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 220px)', gap: 16 }}>
+      <Field label="작게 (sm)" htmlFor="plan-sm">
+        <Select id="plan-sm" size="sm" options={PLANS} defaultValue="team" />
+      </Field>
+      <Field label="크게 (lg)" htmlFor="plan-lg">
+        <Select id="plan-lg" size="lg" options={PLANS} defaultValue="team" />
+      </Field>
+      <Field label="오류" invalid hint="플랜을 선택해 주세요." htmlFor="plan-err">
+        <Select id="plan-err" options={PLANS} invalid />
+      </Field>
+      <Field label="비활성" htmlFor="plan-off">
+        <Select id="plan-off" options={PLANS} defaultValue="starter" disabled />
+      </Field>
+    </div>
+  )
+}
+```

package/agents/selector-button/AGENTS.md

@@ -0,0 +1,122 @@
+# SelectorButton
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+지금 선택된 것을 보여 주고 눌러서 바꾸는 조용한 버튼. 워크스페이스 · 계정 전환, 드롭다운이 달린 페이지 제목에 써요. 앞(leading) · 이름 · 회색 설명 · chevron으로 이루어지고, DropdownMenu의 trigger에 넣으면 메뉴가 열린 동안 아래 chevron이 뒤집혀요.
+
+```tsx
+import { SelectorButton } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 사이드바 머리 = `SelectorButton`(앱 이름) + 검색 · 접기 아이콘 버튼. 접으면(`sidebarCollapsed`) 헤더 왼쪽에 여는 버튼이 나타난다. 본문 헤더 = 왼쪽 `Breadcrumb`, 오른쪽 작은 ghost 액션.
+- 행 앞 타일: 사람은 `Avatar`, 도구·사이트·문서는 `IconTile`(회색 채움 + 아이콘/글자). 선택된 것을 보여 주고 메뉴로 바꾸는 버튼(워크스페이스·계정 전환, 드롭다운 제목)은 `SelectorButton`을 `DropdownMenu` trigger에.
+
+## API
+
+### SelectorButton
+
+나머지 props는 <button>으로 전달돼요(ref 포함).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 선택된 이름. 길면 말줄임돼요. |
+| `description` | `ReactNode` |  | 아래 회색 줄(요금제, 이메일). |
+| `leading` | `ReactNode` |  | 앞의 아바타 · 글자 타일 · 아이콘. |
+| `chevron` | `'down' \| 'updown' \| 'right' \| 'none'` | `'down'` | down은 메뉴가 열리면 뒤집혀요. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | lg는 헤딩 크기 글자(페이지 제목). |
+| `block` | `boolean` |  | 부모 폭을 채우고 chevron을 끝에 붙여요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 워크스페이스 전환
+
+block으로 사이드바 폭을 채우고, 글자 아바타(Avatar square)와 요금제 설명을 붙였어요. 누르는 순간 메뉴가 열려요.
+
+```tsx
+import { useState } from 'react'
+import { Plus, Settings } from 'lucide-react'
+import { Avatar, SelectorButton, DropdownMenu, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator } from '@iamfiro/design'
+
+const WORKSPACES = [
+  { id: 'lumen', name: '루멘 디자인팀', plan: '팀 요금제 · 멤버 12명' },
+  { id: 'side', name: '사이드 프로젝트', plan: '무료 · 멤버 3명' },
+]
+
+export default function Example() {
+  const [current, setCurrent] = useState('lumen')
+  const ws = WORKSPACES.find((w) => w.id === current)!
+  return (
+    <div style={{ width: 248 }}>
+      <DropdownMenu
+        minWidth={248}
+        trigger={<SelectorButton block leading={<Avatar name={ws.name.slice(0, 1)} square size={28} />} label={ws.name} description={ws.plan} />}
+      >
+        <DropdownMenuLabel>워크스페이스</DropdownMenuLabel>
+        <DropdownMenuRadioGroup value={current} onValueChange={setCurrent}>
+          {WORKSPACES.map((w) => (
+            <DropdownMenuRadioItem key={w.id} value={w.id}>
+              {w.name}
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem icon={<Plus />}>새 워크스페이스</DropdownMenuItem>
+        <DropdownMenuItem icon={<Settings />}>설정</DropdownMenuItem>
+      </DropdownMenu>
+    </div>
+  )
+}
+```
+
+### 크기 · chevron
+
+lg는 페이지 제목, md는 사이드바 머리 · 바닥 행, sm은 작은 행. chevron은 down · updown · right · none.
+
+```tsx
+import { Copy, LogOut, Pencil, Settings, Trash2, UserRound } from 'lucide-react'
+import { Avatar, SelectorButton, Stack, Text, DropdownMenu, DropdownMenuItem, DropdownMenuSeparator } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={6} align="start" style={{ width: 260 }}>
+      <Stack gap={2}>
+        <Text variant="caption" tone="tertiary">
+          size="lg" · 페이지 제목
+        </Text>
+        <DropdownMenu trigger={<SelectorButton size="lg" label="3분기 회고" />}>
+          <DropdownMenuItem icon={<Pencil />}>이름 바꾸기</DropdownMenuItem>
+          <DropdownMenuItem icon={<Copy />}>복제</DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem icon={<Trash2 />} danger>
+            삭제
+          </DropdownMenuItem>
+        </DropdownMenu>
+      </Stack>
+
+      <Stack gap={2} style={{ alignSelf: 'stretch' }}>
+        <Text variant="caption" tone="tertiary">
+          block · 사용자 메뉴 (chevron="updown")
+        </Text>
+        <DropdownMenu align="start" minWidth={240} trigger={<SelectorButton block chevron="updown" leading={<Avatar name="김민지" size={28} />} label="김민지" />}>
+          <DropdownMenuItem icon={<UserRound />}>내 프로필</DropdownMenuItem>
+          <DropdownMenuItem icon={<Settings />}>설정</DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem icon={<LogOut />}>로그아웃</DropdownMenuItem>
+        </DropdownMenu>
+      </Stack>
+
+      <Stack gap={2}>
+        <Text variant="caption" tone="tertiary">
+          size="sm" · chevron="right" · disabled
+        </Text>
+        <SelectorButton size="sm" chevron="right" label="모든 프로젝트" />
+        <SelectorButton size="sm" label="권한 없음" disabled />
+      </Stack>
+    </Stack>
+  )
+}
+```

package/agents/sidebar/AGENTS.md

@@ -0,0 +1,201 @@
+# Sidebar
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+세로 내비게이션. 위쪽 header, 스크롤되는 그룹 목록, 아래에 고정되는 footer로 이루어져요. 그룹은 접을 수 있고, 펼치고 접을 때 실제 높이만큼 부드럽게 움직여요. 보통 AppShell의 sidebar로 써요.
+
+```tsx
+import { Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 사이드바 footer가 남은 높이보다 크면 잘리지 않고 footer 안에서 스크롤된다(`Sidebar`). 미리보기 상자 높이는 `--shell-height`로.
+
+## API
+
+### Sidebar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | SidebarGroup 목록. 이 영역만 스크롤돼요. |
+| `header` | `ReactNode` |  | 위쪽 영역(브랜드, 워크스페이스 전환). |
+| `footer` | `ReactNode` |  | 아래에 고정되는 영역(사용자, 설정). |
+| `aria-label` | `string` | `'메뉴'` | <nav>의 접근성 이름. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+### SidebarGroup
+
+Sidebar.Group으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | SidebarItem 목록. |
+| `label` | `ReactNode` |  | 그룹 제목. 생략하면 제목 없이 항목만 보여요. |
+| `icon` | `ReactNode` |  | 제목 앞 아이콘. |
+| `count` | `number` |  | 제목 끝에 보이는 숫자. |
+| `collapsible` | `boolean` |  | 제목을 눌러 접고 펼칠 수 있게 해요. |
+| `defaultOpen` | `boolean` | `true` | 처음 펼침 여부(collapsible일 때). |
+
+### SidebarItem
+
+Sidebar.Item으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 항목 이름. 길면 말줄임돼요. |
+| `href` | `string` | `'#'` | 링크 주소. |
+| `onClick` | `() => void` |  | 클릭 처리. 있으면 기본 링크 이동을 막아요(클라이언트 라우팅용). |
+| `active` | `boolean` |  | 현재 페이지(aria-current="page"). |
+| `icon` | `ReactNode` |  | 앞 아이콘(16px). |
+| `badge` | `ReactNode` |  | 끝에 붙는 배지·점·숫자. |
+| `disabled` | `boolean` |  | 비활성. 링크가 사라지고 눌리지 않아요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+header에는 브랜드나 워크스페이스 전환, footer에는 사용자 정보를 넣어요. 현재 페이지 항목에 active를 주면 aria-current="page"가 붙어요.
+
+```tsx
+import { useState } from 'react'
+import { Calendar, FolderKanban, House, Inbox, Settings, Users } from 'lucide-react'
+import { Avatar, Text, Card, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+
+export default function Example() {
+  const [page, setPage] = useState('home')
+  const item = (id: string) => ({ active: page === id, onClick: () => setPage(id) })
+
+  return (
+    <Card padding="none" style={{ width: 260, height: 460, overflow: 'hidden' }}>
+      <Sidebar
+        header={
+          <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+            <Avatar name="Lumen" square size={28} />
+            <Text variant="label-lg">Lumen</Text>
+          </div>
+        }
+        footer={
+          <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+            <Avatar name="김민지" online />
+            <div style={{ minWidth: 0 }}>
+              <Text variant="label-md" as="div">
+                김민지
+              </Text>
+              <Text variant="caption" tone="tertiary" as="div" truncate>
+                minji@lumen.app
+              </Text>
+            </div>
+          </div>
+        }
+      >
+        <SidebarGroup>
+          <SidebarItem icon={<House />} {...item('home')}>
+            홈
+          </SidebarItem>
+          <SidebarItem icon={<Inbox />} {...item('inbox')}>
+            받은 편지함
+          </SidebarItem>
+          <SidebarItem icon={<Calendar />} {...item('calendar')}>
+            일정
+          </SidebarItem>
+        </SidebarGroup>
+        <SidebarGroup label="워크스페이스">
+          <SidebarItem icon={<FolderKanban />} {...item('projects')}>
+            프로젝트
+          </SidebarItem>
+          <SidebarItem icon={<Users />} {...item('members')}>
+            멤버
+          </SidebarItem>
+          <SidebarItem icon={<Settings />} {...item('settings')}>
+            설정
+          </SidebarItem>
+        </SidebarGroup>
+      </Sidebar>
+    </Card>
+  )
+}
+```
+
+### 그룹 · 접기
+
+label이 있으면 그룹 제목이 생겨요. collapsible이면 제목을 눌러 접고 펼치며, defaultOpen={false}로 접힌 채 시작해요. count는 제목 끝에 숫자로 보여요.
+
+```tsx
+import { useState } from 'react'
+import { Folder, Hash, Star } from 'lucide-react'
+import { Card, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+
+const PROJECTS = ['웹사이트 리뉴얼', '모바일 앱 2.0', '디자인 시스템', '연말 캠페인']
+const CHANNELS = ['공지', '디자인', '개발', '잡담']
+
+export default function Example() {
+  const [current, setCurrent] = useState('디자인 시스템')
+
+  return (
+    <Card padding="none" style={{ width: 260, height: 460, overflow: 'hidden' }}>
+      <Sidebar>
+        <SidebarGroup label="즐겨찾기" icon={<Star />}>
+          <SidebarItem active={current === '디자인 시스템'} onClick={() => setCurrent('디자인 시스템')}>
+            디자인 시스템
+          </SidebarItem>
+        </SidebarGroup>
+        <SidebarGroup label="프로젝트" count={PROJECTS.length} collapsible>
+          {PROJECTS.map((name) => (
+            <SidebarItem key={name} icon={<Folder />} active={current === name} onClick={() => setCurrent(name)}>
+              {name}
+            </SidebarItem>
+          ))}
+        </SidebarGroup>
+        <SidebarGroup label="채널" count={CHANNELS.length} collapsible defaultOpen={false}>
+          {CHANNELS.map((name) => (
+            <SidebarItem key={name} icon={<Hash />} active={current === name} onClick={() => setCurrent(name)}>
+              {name}
+            </SidebarItem>
+          ))}
+        </SidebarGroup>
+      </Sidebar>
+    </Card>
+  )
+}
+```
+
+### 항목 상태
+
+icon, 끝에 붙는 badge(Badge·점·숫자), active, disabled. 비활성 항목은 흐리게 보이고 눌리지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { Archive, ChartColumn, CreditCard, Inbox, Sparkles } from 'lucide-react'
+import { Badge, Card, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+
+export default function Example() {
+  const [page, setPage] = useState('inbox')
+
+  return (
+    <Card padding="none" style={{ width: 260, overflow: 'hidden' }}>
+      <Sidebar>
+        <SidebarGroup label="메뉴">
+          <SidebarItem icon={<Inbox />} badge={<Badge>12</Badge>} active={page === 'inbox'} onClick={() => setPage('inbox')}>
+            받은 편지함
+          </SidebarItem>
+          <SidebarItem icon={<Sparkles />} badge={<Badge tone="accent">New</Badge>} active={page === 'ai'} onClick={() => setPage('ai')}>
+            AI 요약
+          </SidebarItem>
+          <SidebarItem icon={<ChartColumn />} active={page === 'reports'} onClick={() => setPage('reports')}>
+            리포트
+          </SidebarItem>
+          <SidebarItem icon={<CreditCard />} badge={<Badge tone="warning" dot>결제 필요</Badge>} active={page === 'billing'} onClick={() => setPage('billing')}>
+            결제
+          </SidebarItem>
+          <SidebarItem icon={<Archive />} disabled>
+            보관함
+          </SidebarItem>
+        </SidebarGroup>
+      </Sidebar>
+    </Card>
+  )
+}
+```