@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/rating/AGENTS.md

@@ -0,0 +1,165 @@
+# Rating
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+별점. 포인터를 올리면 누를 때 정해질 값을 미리 보여 주고, 벗어나면 원래 값으로 돌아가요. 누르면 확정되며 별이 살짝 튀어요. 같은 값을 다시 누르면 지워져요(allowClear). 키보드는 radiogroup: ←→ 한 칸, Home/End 끝, Backspace 지우기. 평균처럼 보여 주기만 할 땐 readOnly로 4.3처럼 소수까지 채워요.
+
+```tsx
+import { Rating } from '@iamfiro/design'
+```
+
+## API
+
+### Rating
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `number \| null` |  | 값(제어). null = 아직 평가 안 함. |
+| `defaultValue` | `number \| null` | `null` | 처음 값(비제어). |
+| `onValueChange` | `(value: number \| null) => void` |  | 누르거나 키를 누를 때 호출. 지우면 null. |
+| `max` | `number` | `5` | 아이콘 개수. |
+| `allowHalf` | `boolean` | `false` | 0.5 단위 선택. |
+| `allowClear` | `boolean` | `true` | 같은 값을 다시 누르거나 Backspace/Delete로 지우기. |
+| `readOnly` | `boolean` |  | 보여 주기만. 소수(4.3)만큼 채우고 포커스되지 않아요. |
+| `disabled` | `boolean` |  | 비활성. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 아이콘 16 / 20 / 28px. |
+| `tone` | `'amber' \| 'accent' \| 'danger' \| 'neutral'` | `'amber'` | 채움 색. |
+| `icon` | `ReactNode` | `<Star />` | 다른 아이콘(예: <Heart />). 빈 바탕과 채움에 두 번 그려요. |
+| `labels` | `string[]` |  | 값마다 옆에 보일 문구. labels[0]이 1점. |
+| `showValue` | `boolean` |  | 숫자(4.3)를 옆에 표시. |
+| `count` | `number` |  | 평가 수. "(128)"로 표시. |
+| `name` | `string` |  | 폼 제출용 hidden input 이름. |
+| `aria-label` | `string` | `'별점'` | radiogroup 이름. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+labels를 주면 값마다 문구가 옆에 붙고, 미리보기 중에는 옅은 글자로 바뀌어요. 같은 별을 다시 누르면 지워져요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, Rating } from '@iamfiro/design'
+
+const LABELS = ['별로예요', '그저 그래요', '괜찮아요', '좋아요', '최고예요']
+
+export default function Example() {
+  const [score, setScore] = useState<number | null>(4)
+  return (
+    <Stack gap={2}>
+      <Text variant="label-md">배송은 만족스러우셨나요?</Text>
+      <Rating value={score} onValueChange={setScore} labels={LABELS} aria-label="배송 만족도" />
+      <Text variant="body-sm" tone="tertiary" numeric>
+        {score === null ? '아직 평가하지 않았어요' : `${score}점을 남겼어요`}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 반 개 단위
+
+allowHalf: 별의 왼쪽 반은 .5, 오른쪽 반은 정수. 키보드도 0.5씩 움직여요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, Rating } from '@iamfiro/design'
+
+export default function Example() {
+  const [score, setScore] = useState<number | null>(3.5)
+  return (
+    <Stack gap={2}>
+      <Text variant="label-md">이 영화를 평가해 주세요</Text>
+      <Rating value={score} onValueChange={setScore} allowHalf showValue size="lg" aria-label="영화 별점" />
+    </Stack>
+  )
+}
+```
+
+### 읽기 전용 · 평균
+
+readOnly는 포커스되지 않는 그림(role="img")이고 소수만큼 별을 잘라 채워요. showValue로 숫자, count로 "(128)".
+
+```tsx
+import { Stack, Text, Rating } from '@iamfiro/design'
+
+const PRODUCTS = [
+  { name: '무선 키보드 K3', score: 4.3, count: 128 },
+  { name: '노이즈 캔슬링 헤드폰', score: 4.8, count: 2041 },
+  { name: 'USB-C 허브 7in1', score: 3.6, count: 57 },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      {PRODUCTS.map((p) => (
+        <Stack key={p.name} gap={1}>
+          <Text variant="label-md">{p.name}</Text>
+          <Rating readOnly value={p.score} showValue count={p.count} size="sm" />
+        </Stack>
+      ))}
+    </Stack>
+  )
+}
+```
+
+### 아이콘과 색
+
+icon에 다른 lucide 아이콘을, tone으로 amber(기본) · danger · accent · neutral.
+
+```tsx
+import { Flame, Heart, ThumbsUp } from 'lucide-react'
+import { Stack, Text, Rating } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">관심도</Text>
+        <Rating icon={<Heart />} tone="danger" defaultValue={3} aria-label="관심도" />
+      </Stack>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">추천 정도</Text>
+        <Rating icon={<ThumbsUp />} tone="accent" max={3} defaultValue={2} labels={['글쎄요', '추천해요', '강력 추천']} aria-label="추천 정도" />
+      </Stack>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">매운 정도</Text>
+        <Rating icon={<Flame />} tone="neutral" defaultValue={1} labels={['순한맛', '약간 매움', '매움', '아주 매움', '극한']} aria-label="매운 정도" />
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+### 크기와 상태
+
+size sm / md / lg, disabled. 폼에는 name으로 값이 실려요.
+
+```tsx
+import { Stack, Text, Rating } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">작게 (sm)</Text>
+        <Rating size="sm" defaultValue={2} aria-label="작은 별점" />
+      </Stack>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">기본 (md) · 지우기 없음</Text>
+        <Rating defaultValue={3} allowClear={false} name="score" aria-label="기본 별점" />
+      </Stack>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">크게 (lg)</Text>
+        <Rating size="lg" defaultValue={4} aria-label="큰 별점" />
+      </Stack>
+      <Stack gap={1}>
+        <Text variant="label-sm" tone="secondary">비활성</Text>
+        <Rating disabled defaultValue={3} aria-label="비활성 별점" />
+      </Stack>
+    </Stack>
+  )
+}
+```

package/agents/relative-time/AGENTS.md

@@ -0,0 +1,103 @@
+# RelativeTime
+
+> 라벨 & 배지 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+"방금", "2분 전", "어제", "10월 25일"처럼 한국어 상대 시간을 <time dateTime>으로 보여 줘요. 마우스를 올리면 전체 날짜가 툴팁으로 나오고, 화면에 있는 동안 문구가 바뀌어야 하는 순간에 맞춰 스스로 갱신해요.
+
+```tsx
+import { RelativeTime, formatRelativeTime, formatFullDate } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 메시지·댓글은 `Comment` + `CommentThread`(선 없이 여백, 같은 사람의 연속 메시지는 `continued`로 가깝게). 상대 시간은 직접 만들지 말고 `RelativeTime` / `formatRelativeTime`.
+
+## API
+
+### RelativeTime
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `date` (필수) | `Date \| string \| number` |  | 표시할 시각. |
+| `format` | `(date: Date, now: Date) => string` | `formatRelativeTime` | 문구를 직접 만들 때. |
+| `tooltip` | `boolean` | `true` | 올리면 전체 날짜("2026년 10월 25일 오후 3:24"). |
+| `tooltipSide` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | 툴팁 방향. |
+| `refreshInterval` | `number \| false` |  | 고정 갱신 간격(ms). 생략하면 문구가 바뀌는 순간에 맞춰, false면 갱신하지 않아요. |
+| `variant` | `TextVariant` | `'caption'` | 글자 역할. |
+| `tone` | `TextTone` | `'tertiary'` | 글자 색. |
+| `className` | `string` |  | <time>에 전달. |
+
+### formatRelativeTime / formatFullDate / nextRelativeTimeChange
+
+컴포넌트 없이 쓰는 함수들.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `formatRelativeTime(date, now?)` | `string` |  | 한국어 상대 시간. |
+| `formatFullDate(date)` | `string` |  | 툴팁용 전체 날짜. |
+| `nextRelativeTimeChange(date, now?)` | `number` |  | 문구가 다음에 바뀌기까지 남은 ms(1초~1시간). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 표현 규칙
+
+45초 안은 "방금", 1시간 안은 분, 같은 날(또는 6시간 안)은 시간, 그다음 "어제" · "N일 전", 일주일이 넘으면 날짜. 해가 다르면 연도도 붙어요. 미래는 "N분 후" · "내일".
+
+```tsx
+import { List, ListItem, RelativeTime } from '@iamfiro/design'
+
+const MINUTE = 60_000
+const now = Date.now()
+
+const ROWS = [
+  { label: '방금 전', date: now - 10_000 },
+  { label: '몇 분 전', date: now - 2 * MINUTE },
+  { label: '몇 시간 전', date: now - 3 * 60 * MINUTE },
+  { label: '어제', date: now - 26 * 60 * MINUTE },
+  { label: '며칠 전', date: now - 4 * 24 * 60 * MINUTE },
+  { label: '올해', date: now - 40 * 24 * 60 * MINUTE },
+  { label: '작년 이전', date: now - 400 * 24 * 60 * MINUTE },
+  { label: '앞으로', date: now + 3 * 24 * 60 * MINUTE },
+]
+
+export default function Example() {
+  return (
+    <List density="compact" style={{ width: 320 }}>
+      {ROWS.map((r) => (
+        <ListItem key={r.label} title={r.label} trailing={<RelativeTime date={r.date} variant="body-sm" tone="secondary" />} />
+      ))}
+    </List>
+  )
+}
+```
+
+### 실시간 갱신 · 함수
+
+타이머는 문구가 바뀔 때에만 깨어나요. 컴포넌트 밖에서는 formatRelativeTime(date, now) · formatFullDate(date)를 그대로 써요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, RelativeTime, Stack, Text, formatRelativeTime } from '@iamfiro/design'
+
+export default function Example() {
+  const [savedAt, setSavedAt] = useState(() => new Date())
+  const [yesterday] = useState(() => Date.now() - 26 * 60 * 60_000)
+  return (
+    <Stack gap={4} align="start">
+      <Inline gap={2}>
+        <Text variant="body-md">마지막 저장</Text>
+        <RelativeTime date={savedAt} variant="body-md" />
+      </Inline>
+      <Button size="sm" onClick={() => setSavedAt(new Date())}>
+        지금 저장
+      </Button>
+      <Text variant="caption" tone="tertiary">
+        문구가 바뀌는 순간(1분, 1시간 경계)에만 다시 그려요. 함수로도 쓸 수 있어요: formatRelativeTime(어제) → “
+        {formatRelativeTime(yesterday)}”
+      </Text>
+    </Stack>
+  )
+}
+```

package/agents/resizable/AGENTS.md

@@ -0,0 +1,390 @@
+# Resizable
+
+> 컨테이너 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+경계를 끌어 크기를 나누는 패널 묶음. 가로 · 세로로 여러 칸을 두고, 그룹 안에 그룹을 넣어 IDE · 메일 같은 배치를 만들어요. 크기는 퍼센트(minSize · maxSize)이고, collapsible 패널은 최소 크기를 한참 지나 끌면 접히고 다시 당기면 펴져요. 경계는 자리를 차지하지 않는 9px 손잡이로, 올리면 얇은 선이, 끄는 동안 · 키보드로 고르면 파란 선이 보여요. 끄는 동안은 그대로 따라오고(미리보기), 놓을 때 확정(onLayout)돼요. 접기 · 펴기와 키보드 이동은 부드럽게 움직여요. 높이는 부모가 정해요.
+
+```tsx
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@iamfiro/design'
+```
+
+## API
+
+### ResizablePanelGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 가로로 나란히 · 세로로 쌓기. |
+| `children` (필수) | `ReactNode` |  | ResizablePanel과 그 사이 ResizableHandle. 직계 자식 또는 Fragment 안에. |
+| `autoSaveId` | `string` |  | 확정된 배치를 localStorage에 이 이름으로 기억. |
+| `onLayoutChange` | `(sizes: number[]) => void` |  | 끄는 동안의 미리보기(퍼센트). Esc로 취소하면 원래 값으로 한 번 더. |
+| `onLayout` | `(sizes: number[]) => void` |  | 확정될 때: 끌기를 놓을 때, 키보드, 접기 · 펴기. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에. 기본 width · height 100%, 세로 flex 부모 안이면 style={{ flex: 1, minHeight: 0 }}. |
+
+### ResizablePanel
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `defaultSize` | `number` |  | 처음 크기(%). 없는 패널끼리 남은 만큼 나눠요. |
+| `minSize / maxSize` | `number` | `10 / 100` | 열려 있을 때의 크기 범위(%). |
+| `collapsible` | `boolean` |  | 최소 크기를 절반 넘게 지나 끌면 접힘. 접힌 패널은 그만큼 당겨야 최소 크기로 펼쳐져요. |
+| `collapsedSize` | `number` | `0` | 접혔을 때 크기(%). 0이면 내용은 포커스 순서에서도 빠져요(inert). |
+| `collapsed / defaultCollapsed` | `boolean` |  | 접힘 상태(제어 / 비제어). |
+| `onCollapsedChange` | `(collapsed: boolean) => void` |  | 사용자가 접거나 펼 때(확정 시점). |
+| `id` | `string` |  | 경계의 aria-controls가 가리키는 id. 없으면 자동. |
+
+### ResizableHandle
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `withGrip` | `boolean` |  | 경계 가운데 작은 손잡이(평소엔 옅은 회색, 끄는 동안 파랑). |
+| `disabled` | `boolean` |  | 끌기 · 키보드 끄기. |
+| `aria-label` | `string` | `'패널 크기 조절'` | role="separator"의 이름. aria-valuenow = 앞 패널 크기(%). |
+| `키보드` | `—` |  | ← → (세로면 ↑ ↓), Shift는 크게 · Home / End = 앞 패널 최소 / 최대 · Enter = 옆 collapsible 패널 접기 / 펴기(없으면 처음 비율로) · 끄는 중 Esc = 취소. 더블 클릭은 Enter와 같아요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### IDE 배치 (중첩 · 접기)
+
+가로 그룹 안 오른쪽 패널에 세로 그룹을 넣었어요. 탐색기와 터미널은 collapsible이라 경계를 더블 클릭하거나 포커스 후 Enter로 접고 펴요. 위 버튼은 collapsed / onCollapsedChange로 같은 상태를 제어해요. 각 칸의 스크롤은 ScrollArea로.
+
+```tsx
+import { useState } from 'react'
+import { Folder, FolderOpen, PanelBottom, PanelLeft } from 'lucide-react'
+import { Box, Button, FileIcon, Inline, Stack, Text, Card, CodeBlock, ResizableHandle, ResizablePanel, ResizablePanelGroup, ScrollArea, TreeView, type TreeNode } from '@iamfiro/design'
+
+const file = (id: string, name: string): TreeNode => ({ id, label: name, leading: <FileIcon name={name} size={16} /> })
+
+const FILES: TreeNode[] = [
+  {
+    id: 'src',
+    label: 'src',
+    children: [
+      {
+        id: 'src/components',
+        label: 'components',
+        children: [file('src/components/Button.tsx', 'Button.tsx'), file('src/components/Card.tsx', 'Card.tsx'), file('src/components/Dialog.tsx', 'Dialog.tsx')],
+      },
+      file('src/App.tsx', 'App.tsx'),
+      file('src/main.tsx', 'main.tsx'),
+      file('src/styles.css', 'styles.css'),
+    ],
+  },
+  file('package.json', 'package.json'),
+  file('README.md', 'README.md'),
+]
+
+const withFolderIcons = (nodes: TreeNode[], open: string[]): TreeNode[] =>
+  nodes.map((n) => (n.children ? { ...n, leading: open.includes(n.id) ? <FolderOpen /> : <Folder />, children: withFolderIcons(n.children, open) } : n))
+
+const CODE = `import { useState } from 'react'
+import { Button } from './components/Button'
+import { Card } from './components/Card'
+
+export default function App() {
+  const [count, setCount] = useState(0)
+
+  return (
+    <Card>
+      <h1>안녕하세요, 김민지 님</h1>
+      <p>오늘 처리할 일이 {count}개 남았어요.</p>
+      <Button onClick={() => setCount((c) => c + 1)}>
+        할 일 추가
+      </Button>
+    </Card>
+  )
+}`
+
+const LOG = `$ npm run dev
+
+  VITE v8.0.0  ready in 412 ms
+
+  ➜  Local:   http://localhost:5173/
+  ➜  Network: use --host to expose
+
+10:42:03 [vite] hmr update /src/App.tsx
+10:42:19 [vite] hmr update /src/components/Card.tsx
+10:43:07 [vite] page reload src/main.tsx`
+
+export default function Example() {
+  const [expanded, setExpanded] = useState(['src', 'src/components'])
+  const [selected, setSelected] = useState<string | null>('src/App.tsx')
+  const [explorerClosed, setExplorerClosed] = useState(false)
+  const [terminalClosed, setTerminalClosed] = useState(false)
+
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 880, height: 480 }}>
+      <Box paddingX={3} paddingY={2}>
+        <Inline justify="between" wrap={false}>
+          <Text variant="label-md">my-app</Text>
+          <Inline gap={1} wrap={false}>
+            <Button
+              size="sm"
+              variant="ghost"
+              iconOnly
+              icon={<PanelLeft />}
+              aria-label={explorerClosed ? '탐색기 열기' : '탐색기 닫기'}
+              aria-pressed={!explorerClosed}
+              onClick={() => setExplorerClosed((v) => !v)}
+            />
+            <Button
+              size="sm"
+              variant="ghost"
+              iconOnly
+              icon={<PanelBottom />}
+              aria-label={terminalClosed ? '터미널 열기' : '터미널 닫기'}
+              aria-pressed={!terminalClosed}
+              onClick={() => setTerminalClosed((v) => !v)}
+            />
+          </Inline>
+        </Inline>
+      </Box>
+
+      <ResizablePanelGroup direction="horizontal" style={{ flex: 1, minHeight: 0, height: 'auto' }}>
+        <ResizablePanel
+          defaultSize={26}
+          minSize={18}
+          maxSize={40}
+          collapsible
+          collapsed={explorerClosed}
+          onCollapsedChange={setExplorerClosed}
+        >
+          <ScrollArea style={{ height: '100%' }}>
+            <Box padding={2}>
+              <TreeView
+                aria-label="파일 탐색기"
+                density="compact"
+                items={withFolderIcons(FILES, expanded)}
+                expanded={expanded}
+                onExpandedChange={setExpanded}
+                selected={selected}
+                onSelectedChange={setSelected}
+                expandOnClick
+              />
+            </Box>
+          </ScrollArea>
+        </ResizablePanel>
+        <ResizableHandle aria-label="탐색기 너비 조절" />
+        <ResizablePanel minSize={40}>
+          <ResizablePanelGroup direction="vertical">
+            <ResizablePanel minSize={25}>
+              <ScrollArea orientation="both" fade style={{ height: '100%' }} aria-label="App.tsx 편집기">
+                <Box padding={3}>
+                  <CodeBlock code={CODE} title={selected ?? 'App.tsx'} showLineNumbers copyable={false} />
+                </Box>
+              </ScrollArea>
+            </ResizablePanel>
+            <ResizableHandle aria-label="터미널 높이 조절" />
+            <ResizablePanel
+              defaultSize={34}
+              minSize={20}
+              collapsible
+              collapsed={terminalClosed}
+              onCollapsedChange={setTerminalClosed}
+            >
+              <ScrollArea stickToBottom style={{ height: '100%' }} aria-label="터미널 출력">
+                <Box padding={3}>
+                  <Stack gap={2}>
+                    <Text variant="overline" tone="tertiary">
+                      터미널
+                    </Text>
+                    <CodeBlock code={LOG} language="text" copyable={false} />
+                  </Stack>
+                </Box>
+              </ScrollArea>
+            </ResizablePanel>
+          </ResizablePanelGroup>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </Card>
+  )
+}
+```
+
+### 메일 (아이콘 레일로 접기)
+
+collapsedSize를 주면 0이 아니라 그 크기로 접혀요. 편지함 칸을 왼쪽으로 끌어 접으면 아이콘만 남은 레일이 되고, 다시 당기면 펼쳐져요. withGrip은 경계에 작은 손잡이를 보여 줘요.
+
+```tsx
+import { useState, type ReactNode } from 'react'
+import { Archive, File, Inbox, Send, Star, Trash2 } from 'lucide-react'
+import { Avatar, Box, Button, CountBadge, Inline, Stack, Text, List, ListItem, ResizableHandle, ResizablePanel, ResizablePanelGroup, ScrollArea, Card } from '@iamfiro/design'
+
+const FOLDERS: Array<{ id: string; label: string; icon: ReactNode; count?: number }> = [
+  { id: 'inbox', label: '받은편지함', icon: <Inbox />, count: 12 },
+  { id: 'star', label: '중요', icon: <Star /> },
+  { id: 'sent', label: '보낸편지함', icon: <Send /> },
+  { id: 'draft', label: '임시보관함', icon: <File />, count: 2 },
+  { id: 'archive', label: '보관함', icon: <Archive /> },
+  { id: 'trash', label: '휴지통', icon: <Trash2 /> },
+]
+
+const MAILS = [
+  { id: 'm1', from: '김민지', subject: '4분기 로드맵 검토 부탁드려요', preview: '지난주 회의에서 나온 의견을 반영해 일정을 조금 당겼어요.', time: '9:41' },
+  { id: 'm2', from: '이도현', subject: '배포 결과 공유', preview: '오후 4시 배포가 문제없이 끝났어요. 오류율은 0.05%예요.', time: '어제' },
+  { id: 'm3', from: '박서연', subject: '브랜드 가이드 최종본', preview: '색상 표와 로고 여백 규칙을 마지막으로 정리했어요.', time: '어제' },
+  { id: 'm4', from: '정하늘', subject: '사용자 인터뷰 일정', preview: '다음 주 화요일과 목요일 오후로 잡아 두었어요.', time: '10월 23일' },
+  { id: 'm5', from: '한지우', subject: '디자인 리뷰 메모', preview: '결제 화면의 버튼 위계를 한 번 더 보면 좋겠어요.', time: '10월 22일' },
+  { id: 'm6', from: '오세훈', subject: 'API 문서 업데이트', preview: '새 엔드포인트 세 개와 오류 코드 표를 추가했어요.', time: '10월 21일' },
+]
+
+export default function Example() {
+  const [folder, setFolder] = useState('inbox')
+  const [mailId, setMailId] = useState('m1')
+  const [railed, setRailed] = useState(false)
+  const mail = MAILS.find((m) => m.id === mailId) ?? MAILS[0]
+
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 920, height: 460 }}>
+      <ResizablePanelGroup direction="horizontal">
+        {/* 접으면 아이콘만 남는 레일(collapsedSize 7%) */}
+        <ResizablePanel defaultSize={20} minSize={16} maxSize={28} collapsible collapsedSize={7} collapsed={railed} onCollapsedChange={setRailed}>
+          <ScrollArea style={{ height: '100%' }}>
+            <Box padding={2}>
+              {railed ? (
+                <Stack gap={1} align="center">
+                  {FOLDERS.map((f) => (
+                    <Button
+                      key={f.id}
+                      size="sm"
+                      variant={folder === f.id ? 'secondary' : 'ghost'}
+                      iconOnly
+                      icon={f.icon}
+                      aria-label={f.label}
+                      onClick={() => setFolder(f.id)}
+                    />
+                  ))}
+                </Stack>
+              ) : (
+                <List density="compact" aria-label="편지함">
+                  {FOLDERS.map((f) => (
+                    <ListItem
+                      key={f.id}
+                      leading={f.icon}
+                      title={f.label}
+                      trailing={f.count ? <CountBadge count={f.count} variant="soft" /> : undefined}
+                      selected={folder === f.id}
+                      onClick={() => setFolder(f.id)}
+                    />
+                  ))}
+                </List>
+              )}
+            </Box>
+          </ScrollArea>
+        </ResizablePanel>
+        <ResizableHandle withGrip aria-label="편지함 너비 조절" />
+        <ResizablePanel defaultSize={34} minSize={24}>
+          <ScrollArea fade style={{ height: '100%' }}>
+            <Box padding={2}>
+              <List density="compact" aria-label="메일 목록">
+                {MAILS.map((m) => (
+                  <ListItem
+                    key={m.id}
+                    leading={<Avatar name={m.from} size={28} />}
+                    title={m.subject}
+                    description={m.preview}
+                    meta={m.time}
+                    selected={mailId === m.id}
+                    onClick={() => setMailId(m.id)}
+                  />
+                ))}
+              </List>
+            </Box>
+          </ScrollArea>
+        </ResizablePanel>
+        <ResizableHandle withGrip aria-label="메일 목록 너비 조절" />
+        <ResizablePanel minSize={30}>
+          <ScrollArea style={{ height: '100%' }} aria-label="메일 본문">
+            <Box padding={5}>
+              <Stack gap={4}>
+                <Inline gap={3} wrap={false}>
+                  <Avatar name={mail.from} size={36} />
+                  <Stack gap={0}>
+                    <Text variant="label-md">{mail.from}</Text>
+                    <Text variant="caption" tone="tertiary">
+                      {mail.time}
+                    </Text>
+                  </Stack>
+                </Inline>
+                <Text variant="heading-sm">{mail.subject}</Text>
+                <Text variant="body-md" tone="secondary">
+                  {mail.preview} 자세한 내용은 첨부한 문서를 확인해 주세요. 궁금한 점이 있으면 편하게 답장 주세요.
+                </Text>
+              </Stack>
+            </Box>
+          </ScrollArea>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </Card>
+  )
+}
+```
+
+### 미리보기 · 확정 · 기억
+
+onLayoutChange는 끄는 동안 계속, onLayout은 놓을 때 · 키를 누를 때 한 번. autoSaveId를 주면 확정된 배치를 localStorage에 기억해요. 패널과 경계는 그룹의 직계 자식(Fragment 안도 가능)이어야 해요.
+
+```tsx
+import { Fragment, useState } from 'react'
+import { RotateCcw } from 'lucide-react'
+import { Box, Button, Inline, Stack, Text, Card, ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@iamfiro/design'
+
+const SAVE_KEY = 'docs-resizable-layout'
+const NAMES = ['목차', '문서', '댓글']
+
+const format = (sizes: number[]) => sizes.map((s) => `${Math.round(s)}%`).join(' · ')
+
+export default function Example() {
+  const [live, setLive] = useState<number[] | null>(null)
+  const [committed, setCommitted] = useState<number[] | null>(null)
+  const [version, setVersion] = useState(0)
+
+  const reset = () => {
+    try {
+      window.localStorage.removeItem(`lumen:resizable:${SAVE_KEY}`)
+    } catch {
+      /* storage blocked */
+    }
+    setLive(null)
+    setCommitted(null)
+    setVersion((v) => v + 1)
+  }
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 720 }}>
+      <Inline justify="between">
+        <Stack gap={1}>
+          <Text variant="caption" tone="tertiary" numeric>
+            미리보기 {live ? format(live) : '—'}
+          </Text>
+          <Text variant="caption" numeric>
+            확정 {committed ? format(committed) : '—'}
+          </Text>
+        </Stack>
+        <Button size="sm" variant="ghost" icon={<RotateCcw />} onClick={reset}>
+          처음 배치로
+        </Button>
+      </Inline>
+      <Card padding="none" style={{ height: 240 }}>
+        <ResizablePanelGroup key={version} direction="horizontal" autoSaveId={SAVE_KEY} onLayoutChange={setLive} onLayout={setCommitted}>
+          {NAMES.map((name, i) => (
+            <Fragment key={name}>
+              {i > 0 && <ResizableHandle withGrip aria-label={`${NAMES[i - 1]} · ${name} 경계`} />}
+              <ResizablePanel minSize={15}>
+                <Box padding={4}>
+                  <Text variant="label-md">{name}</Text>
+                </Box>
+              </ResizablePanel>
+            </Fragment>
+          ))}
+        </ResizablePanelGroup>
+      </Card>
+      <Text variant="caption" tone="tertiary">
+        경계를 끌거나 Tab으로 고른 뒤 ← → (Shift는 크게) · Home / End. 끄는 동안은 미리보기만 바뀌고 놓을 때 확정돼요. 끄는 중 Esc는 원래 자리로. 새로고침해도 배치가 남아 있어요.
+      </Text>
+    </Stack>
+  )
+}
+```