@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/app-shell/AGENTS.md

@@ -0,0 +1,409 @@
+# AppShell
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+앱의 뼈대. 왼쪽에 고정된 사이드바와 스크롤되는 본문 영역, 그 위의 헤더를 배치해요. 화면 너비가 900px 이하이면 사이드바가 왼쪽에서 밀려 나오는 드로어로 바뀌어요.
+
+```tsx
+import { AppShell, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 예외는 앱 뼈대 하나: `AppShell variant="inset"`은 사이드바가 옅은 회색 바탕(`--canvas`) 위에 놓이고, 본문은 그 옆에 흰 패널(`--r-lg` + `--shadow-panel`, 바깥 여백 8px)로 떠 있다. 본문은 패널 안에서만 스크롤. 회색 바탕 위의 hover·선택 채움은 `--canvas-hover` / `--canvas-active`(AppShell이 사이드바 안에서 `--surface-hover/active`를 이것으로 바꿔 준다). 선택된 사이드바 항목은 어둡게 채우지 않고 **흰 칩 + `--shadow-chip`**(옅은 윤곽 + 그림자)으로 떠오르게. docs 사이트가 이 구조.
+
+## API
+
+### AppShell
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `sidebar` (필수) | `ReactNode` |  | 왼쪽 영역. 보통 <Sidebar>. |
+| `header` | `ReactNode` |  | 본문 위에 붙는 상단 바(검색, 액션 등). |
+| `children` (필수) | `ReactNode` |  | 본문. |
+| `variant` | `'plain' \| 'inset'` | `'plain'` | plain: 흰 한 장, 창 전체가 스크롤. inset: 회색 바탕 위 흰 패널로 떠 있는 본문, 패널 안에서만 스크롤. |
+| `sidebarWidth` | `number` | `264` | 넓은 화면에서 사이드바 너비(px). 드로어는 최대 화면의 86%. |
+| `sidebarCollapsed` | `boolean` | `false` | 넓은 화면에서 사이드바를 접어요. 사이드바가 밀려 나가며 본문이 넓어져요. |
+| `mobileSidebarOpen` | `boolean` | `false` | 좁은 화면(≤ 900px)에서 드로어 열림 여부. |
+| `onMobileSidebarOpenChange` | `(open: boolean) => void` |  | 바깥 클릭이나 Esc로 닫힐 때 false로 호출돼요. |
+| `aside` | `ReactNode` |  | 오른쪽 패널(도구, 상세 정보). 패널 안만 따로 스크롤되고, 900px 이하에선 숨어요. |
+| `asideWidth` | `number` | `320` | 오른쪽 패널 너비(px). |
+| `asideOpen` | `boolean` | `true` | 패널 열림. 닫으면 패널이 밀려 나가며 본문이 넓어져요. |
+| `asideLabel` | `string` | `'패널'` | 패널(<aside>)의 접근성 이름. |
+| `scrollKey` | `unknown` |  | 바뀌면(새 페이지) 본문을 맨 위로 스크롤해요. inset이면 패널을, plain이면 창을. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+sidebar에는 보통 Sidebar를, header에는 Breadcrumb와 액션 버튼을 넣어요. 사이드바와 헤더는 페이지를 스크롤해도 제자리에 붙어 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Bell, FolderKanban, House, Inbox, Plus } from 'lucide-react'
+import { Badge, Button, Text, AppShell, Breadcrumb, Card, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+
+const MENU = [
+  { id: 'home', label: '홈', icon: <House /> },
+  { id: 'inbox', label: '받은 편지함', icon: <Inbox />, badge: <Badge tone="accent">3</Badge> },
+  { id: 'projects', label: '프로젝트', icon: <FolderKanban /> },
+]
+
+export default function Example() {
+  const [page, setPage] = useState('projects')
+  const current = MENU.find((m) => m.id === page)!
+
+  const sidebar = (
+    <Sidebar header={<Text variant="label-lg">Lumen</Text>}>
+      <SidebarGroup>
+        {MENU.map((m) => (
+          <SidebarItem key={m.id} icon={m.icon} badge={m.badge} active={m.id === page} onClick={() => setPage(m.id)}>
+            {m.label}
+          </SidebarItem>
+        ))}
+      </SidebarGroup>
+    </Sidebar>
+  )
+
+  const header = (
+    <>
+      <Breadcrumb items={[{ label: '워크스페이스', onClick: () => setPage('home') }, { label: current.label }]} />
+      <div style={{ display: 'flex', gap: 8, marginLeft: 'auto' }}>
+        <Button iconOnly variant="ghost" icon={<Bell />} aria-label="알림" />
+        <Button variant="primary" size="sm" icon={<Plus />}>
+          새로 만들기
+        </Button>
+      </div>
+    </>
+  )
+
+  // 미리보기용 상자예요. 실제 앱에서는 AppShell을 최상단에 두면 화면 전체를 채워요.
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 760, height: 420, overflow: 'hidden', contain: 'layout paint' }}>
+      <AppShell sidebar={sidebar} header={header} sidebarWidth={220}>
+        <div style={{ padding: '8px 24px 24px' }}>
+          <Text variant="heading-md">{current.label}</Text>
+          <Text tone="secondary" style={{ marginTop: 8 }}>
+            사이드바는 제자리에 고정되고, 본문만 스크롤돼요.
+          </Text>
+        </div>
+      </AppShell>
+    </Card>
+  )
+}
+```
+
+### 떠 있는 본문 (inset)
+
+variant="inset"이면 사이드바는 옅은 회색 바탕(--canvas)에 놓이고, 본문은 그 위에 흰 패널로 떠서 패널 안에서만 스크롤돼요. 사이드바 머리는 SelectorButton + 검색 · 접기 아이콘 버튼으로, 접으면 sidebarCollapsed로 사이드바가 밀려 나가고 헤더에 여는 버튼이 생겨요. scrollKey가 바뀌면 본문이 맨 위로 돌아가요.
+
+```tsx
+import { useState, type CSSProperties } from 'react'
+import { FolderKanban, House, Inbox, PanelLeft, Plus, Search, SquarePen } from 'lucide-react'
+import { Badge, Button, IconTile, Inline, SelectorButton, Text, Tooltip, AppShell, Breadcrumb, Card, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+
+const MENU = [
+  { id: 'new', label: '새 대화', icon: <SquarePen /> },
+  { id: 'home', label: '홈', icon: <House /> },
+  { id: 'inbox', label: '받은 편지함', icon: <Inbox />, badge: <Badge tone="accent">3</Badge> },
+  { id: 'projects', label: '프로젝트', icon: <FolderKanban /> },
+]
+
+export default function Example() {
+  const [page, setPage] = useState('projects')
+  const [collapsed, setCollapsed] = useState(false)
+  const current = MENU.find((m) => m.id === page)!
+
+  const sidebar = (
+    <Sidebar
+      header={
+        <Inline justify="between" gap={1} wrap={false}>
+          <SelectorButton
+            leading={
+              <IconTile tone="surface" size={24}>
+                A
+              </IconTile>
+            }
+            label="Acme"
+          />
+          <Inline gap={1} wrap={false}>
+            <Tooltip content="검색">
+              <Button iconOnly variant="ghost" size="sm" icon={<Search />} aria-label="검색" />
+            </Tooltip>
+            <Tooltip content="사이드바 접기">
+              <Button iconOnly variant="ghost" size="sm" icon={<PanelLeft />} aria-label="사이드바 접기" onClick={() => setCollapsed(true)} />
+            </Tooltip>
+          </Inline>
+        </Inline>
+      }
+    >
+      <SidebarGroup>
+        {MENU.map((m) => (
+          <SidebarItem key={m.id} icon={m.icon} badge={m.badge} active={m.id === page} onClick={() => setPage(m.id)}>
+            {m.label}
+          </SidebarItem>
+        ))}
+      </SidebarGroup>
+    </Sidebar>
+  )
+
+  const header = (
+    <>
+      <Inline gap={2} wrap={false}>
+        {collapsed && (
+          <Tooltip content="사이드바 열기">
+            <Button iconOnly variant="ghost" size="sm" icon={<PanelLeft />} aria-label="사이드바 열기" onClick={() => setCollapsed(false)} />
+          </Tooltip>
+        )}
+        <Breadcrumb items={[{ label: 'Acme', onClick: () => setPage('home') }, { label: current.label }]} />
+      </Inline>
+      <Button variant="primary" size="sm" icon={<Plus />} style={{ marginLeft: 'auto' }}>
+        새로 만들기
+      </Button>
+    </>
+  )
+
+  // 미리보기용 상자예요. 실제 앱에서는 AppShell을 최상단에 두면 화면 전체를 채워요.
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 760, height: 420, overflow: 'hidden', contain: 'layout paint', '--shell-height': '420px' } as CSSProperties}>
+      <AppShell variant="inset" sidebar={sidebar} header={header} sidebarWidth={220} sidebarCollapsed={collapsed} scrollKey={page}>
+        <div style={{ padding: '8px 20px 24px' }}>
+          <Text variant="heading-md">{current.label}</Text>
+          <Text tone="secondary" style={{ marginTop: 8 }}>
+            회색 바탕 위에 본문이 흰 패널로 떠 있어요. 본문만 패널 안에서 스크롤돼요.
+          </Text>
+        </div>
+      </AppShell>
+    </Card>
+  )
+}
+```
+
+### 모바일 드로어
+
+좁은 화면에서는 mobileSidebarOpen / onMobileSidebarOpenChange로 드로어를 열고 닫아요. 바깥의 어두운 영역을 누르거나 Esc를 누르면 닫혀요. 항목을 고른 뒤에도 직접 닫아 주세요.
+
+```tsx
+import { useState } from 'react'
+import { ChartColumn, House, Menu, Settings } from 'lucide-react'
+import { Button, Text, AppShell, Card, Sidebar, SidebarGroup, SidebarItem } from '@iamfiro/design'
+
+const MENU = [
+  { id: 'home', label: '홈', icon: <House /> },
+  { id: 'reports', label: '리포트', icon: <ChartColumn /> },
+  { id: 'settings', label: '설정', icon: <Settings /> },
+]
+
+export default function Example() {
+  const [page, setPage] = useState('home')
+  const [drawerOpen, setDrawerOpen] = useState(false)
+
+  const go = (id: string) => {
+    setPage(id)
+    setDrawerOpen(false)
+  }
+
+  const sidebar = (
+    <Sidebar header={<Text variant="label-lg">Lumen</Text>}>
+      <SidebarGroup>
+        {MENU.map((m) => (
+          <SidebarItem key={m.id} icon={m.icon} active={m.id === page} onClick={() => go(m.id)}>
+            {m.label}
+          </SidebarItem>
+        ))}
+      </SidebarGroup>
+    </Sidebar>
+  )
+
+  // contain은 미리보기용이에요. 드로어가 화면 대신 이 상자 안에서 열리게 해요.
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 760, height: 420, overflow: 'hidden', contain: 'layout paint' }}>
+      <AppShell
+        sidebar={sidebar}
+        mobileSidebarOpen={drawerOpen}
+        onMobileSidebarOpenChange={setDrawerOpen}
+        header={<Button iconOnly variant="ghost" icon={<Menu />} aria-label="메뉴 열기" onClick={() => setDrawerOpen(true)} />}
+      >
+        <div style={{ padding: '8px 24px 24px' }}>
+          <Text variant="heading-md">{MENU.find((m) => m.id === page)?.label}</Text>
+          <Text tone="secondary" style={{ marginTop: 8 }}>
+            창 너비를 900px 이하로 줄이면 사이드바가 숨고, 메뉴 버튼으로 열 수 있어요.
+          </Text>
+        </div>
+      </AppShell>
+    </Card>
+  )
+}
+```
+
+### 세 칸 (오른쪽 패널)
+
+aside로 오른쪽 패널을 붙이고 asideOpen으로 열고 닫아요(본문 폭이 함께 부드럽게 바뀌어요). 사이드바는 SelectorButton(워크스페이스 · 사용자), NoticeStack, ProgressTracker collapsible로, 헤더는 SelectorButton size="lg" 제목과 아이콘 버튼으로, 패널은 SearchInput · Card+List(IconTile · Kbd) · 세로 ToggleGroup으로 조립했어요. 패널은 900px 이하 화면에서 숨어요.
+
+```tsx
+import { useState, type CSSProperties } from 'react'
+import {
+  Bookmark,
+  ChevronRight,
+  FileText,
+  FolderClosed,
+  History,
+  House,
+  Inbox,
+  MoreHorizontal,
+  Moon,
+  PanelLeft,
+  PanelRight,
+  Plus,
+  Search,
+  Settings,
+  Share,
+  Sun,
+} from 'lucide-react'
+import { Avatar, Box, Button, IconTile, Inline, Kbd, SearchInput, SelectorButton, Stack, Text, AppShell, Card, DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, EmptyState, List, ListItem, NoticeStack, ProgressTracker, Sidebar, SidebarGroup, SidebarItem, ToggleGroup, ToggleGroupItem, type NoticeItem, type TrackerStep } from '@iamfiro/design'
+
+const NOTICES: NoticeItem[] = [
+  {
+    id: 'shared-folders',
+    eyebrow: '10월 새 기능',
+    title: '공유 폴더',
+    footer: (
+      <Button variant="ghost" size="sm" iconRight={<ChevronRight />}>
+        전체 변경 기록
+      </Button>
+    ),
+  },
+  { id: 'templates', eyebrow: '새 기능', title: '문서 템플릿' },
+]
+
+const STEPS: TrackerStep[] = ['프로필 사진 올리기', '팀원 초대하기', '첫 문서 만들기', '폴더 정리하기', '문서 공유하기', '알림 켜기', '모바일 앱 받기', '테마 고르기'].map(
+  (label, i) => ({ id: String(i), label }),
+)
+
+const TOOLS = [
+  { id: 'bookmark', label: '북마크', icon: <Bookmark />, keys: ['mod', 'shift', 'B'] },
+  { id: 'history', label: '방문 기록', icon: <History />, keys: ['mod', 'Y'] },
+]
+
+const SUGGESTED = [
+  { id: 'wiki', title: '팀 위키', domain: 'wiki.lumen.app' },
+  { id: 'design', title: '디자인 가이드', domain: 'design.lumen.app' },
+]
+
+export default function Example() {
+  const [page, setPage] = useState('home')
+  const [notices, setNotices] = useState(NOTICES)
+  const [panelOpen, setPanelOpen] = useState(true)
+  const [theme, setTheme] = useState<'light' | 'dark'>('light')
+  const item = (id: string) => ({ active: page === id, onClick: () => setPage(id) })
+
+  const sidebar = (
+    <Sidebar
+      header={
+        <Stack gap={2}>
+          <Inline gap={1} justify="end">
+            <Button variant="ghost" size="sm" iconOnly icon={<PanelLeft />} aria-label="사이드바 접기" />
+            <Button variant="ghost" size="sm" iconOnly icon={<Search />} aria-label="검색" />
+          </Inline>
+          <DropdownMenu trigger={<SelectorButton block leading={<Avatar name="L" square size={24} />} label="루멘 디자인팀" />}>
+            <DropdownMenuItem>루멘 디자인팀</DropdownMenuItem>
+            <DropdownMenuItem>사이드 프로젝트</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem icon={<Plus />}>새 워크스페이스</DropdownMenuItem>
+          </DropdownMenu>
+        </Stack>
+      }
+      footer={
+        <Stack gap={3}>
+          <NoticeStack items={notices} onDismiss={(id) => setNotices((prev) => prev.filter((n) => n.id !== id))} />
+          <ProgressTracker
+            collapsible
+            title="시작하기"
+            steps={STEPS}
+            defaultCompleted={['0']}
+            summary={(done, total) => `${Math.round((done / total) * 100)}% 완료 · 좋은 출발이에요!`}
+          />
+          <DropdownMenu minWidth={220} trigger={<SelectorButton block leading={<Avatar name="김민지" size={24} />} label="김민지" />}>
+            <DropdownMenuItem icon={<Settings />}>설정</DropdownMenuItem>
+          </DropdownMenu>
+        </Stack>
+      }
+    >
+      <SidebarGroup>
+        <SidebarItem icon={<House />} {...item('home')}>
+          홈
+        </SidebarItem>
+        <SidebarItem icon={<Inbox />} {...item('inbox')}>
+          받은 편지함
+        </SidebarItem>
+      </SidebarGroup>
+      <SidebarGroup label="프로젝트">
+        <SidebarItem icon={<FolderClosed />} {...item('brand')}>
+          브랜드 리뉴얼
+        </SidebarItem>
+        <SidebarItem icon={<FolderClosed />} {...item('retro')}>
+          3분기 회고
+        </SidebarItem>
+      </SidebarGroup>
+    </Sidebar>
+  )
+
+  const header = (
+    <>
+      <DropdownMenu trigger={<SelectorButton size="lg" label="새 문서" />}>
+        <DropdownMenuItem>이름 바꾸기</DropdownMenuItem>
+        <DropdownMenuItem>복제</DropdownMenuItem>
+      </DropdownMenu>
+      <Inline gap={1} style={{ marginLeft: 'auto' }}>
+        <Button variant="ghost" iconOnly icon={<Share />} aria-label="공유" />
+        <Button variant="ghost" iconOnly icon={<MoreHorizontal />} aria-label="더 보기" />
+        {!panelOpen && <Button variant="ghost" iconOnly icon={<PanelRight />} aria-label="패널 열기" onClick={() => setPanelOpen(true)} />}
+      </Inline>
+    </>
+  )
+
+  const aside = (
+    <Box padding={3}>
+      <Stack gap={3}>
+        <Inline justify="between" wrap={false}>
+          <Text variant="label-lg">워크스페이스</Text>
+          <Button variant="ghost" size="sm" iconOnly icon={<PanelRight />} aria-label="패널 닫기" onClick={() => setPanelOpen(false)} />
+        </Inline>
+        <SearchInput placeholder="검색하거나 URL 입력" size="sm" />
+        <Card padding="sm">
+          <List label="도구" density="compact">
+            {TOOLS.map((t) => (
+              <ListItem key={t.id} leading={<IconTile>{t.icon}</IconTile>} title={t.label} onClick={() => {}} trailing={<Kbd keys={t.keys} size="sm" />} />
+            ))}
+          </List>
+        </Card>
+        <Card padding="sm">
+          <List label="추천" density="compact">
+            {SUGGESTED.map((s) => (
+              <ListItem key={s.id} leading={<IconTile>{s.title.slice(0, 1)}</IconTile>} title={s.title} description={s.domain} href="#" />
+            ))}
+          </List>
+        </Card>
+        <Inline justify="end">
+          <ToggleGroup type="single" required orientation="vertical" size="sm" value={theme} onValueChange={(v) => v && setTheme(v)} aria-label="테마">
+            <ToggleGroupItem value="light" icon={<Sun />} aria-label="밝게" />
+            <ToggleGroupItem value="dark" icon={<Moon />} aria-label="어둡게" />
+          </ToggleGroup>
+        </Inline>
+      </Stack>
+    </Box>
+  )
+
+  // 미리보기용 상자예요. 오른쪽 패널은 화면 너비가 900px보다 넓을 때만 보여요.
+  return (
+    <Card padding="none" style={{ width: '100%', maxWidth: 1080, height: 640, overflow: 'hidden', contain: 'layout paint', '--shell-height': '640px' } as CSSProperties}>
+      <AppShell sidebar={sidebar} header={header} sidebarWidth={240} aside={aside} asideWidth={280} asideOpen={panelOpen} asideLabel="워크스페이스">
+        <EmptyState icon={<FileText />} title="여기에 페이지가 들어가요" description="왼쪽에서 문서를 고르거나 새로 만들어 보세요." />
+      </AppShell>
+    </Card>
+  )
+}
+```

package/agents/area-chart/AGENTS.md

@@ -0,0 +1,183 @@
+# AreaChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+양의 크기와 구성을 함께 보여 주는 영역 차트. LineChart 위에 쌓기 모드를 더한 것이라 축 · Card 툴팁 · 범례 · 키보드 안내선 · bands · referenceLines · endDot · streaming이 그대로 동작해요. default는 시리즈가 바닥에서 겹치는 반투명 영역, stacked는 위로 쌓아 맨 위 선이 합계, percent는 행마다 100%로 맞춘 비율이에요. 데이터가 바뀌면 영역이 새 모양으로 미끄러져요.
+
+```tsx
+import { AreaChart, type LineSeries } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 영역 차트는 `AreaChart`(= LineChart `area` + `stack`), 따로 만들지 않는다. 겹침(default)은 반투명, 쌓기(`stacked`)는 맨 위 선이 합계이고 툴팁은 위층부터 + 합계 줄, 100%(`percent`)는 툴팁에 몫, 합계 줄엔 실제 수. 층은 위 · 아래 가장자리를 같은 명령으로 그려(`bandPath`) 모드 · 데이터가 바뀌어도 모양이 미끄러진다.
+
+## API
+
+### AreaChart
+
+LineChart의 props를 모두 받아요(area · stack 제외). 아래는 AreaChart에서 더하거나 의미가 바뀐 것.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `type` | `'default' \| 'stacked' \| 'percent'` | `'default'` | 겹침 · 쌓기 · 100% 쌓기. 쌓을 땐 빠진 값(null)을 0으로 셈해요. |
+| `fill` | `'gradient' \| 'solid'` | `'gradient'` | 아래로 옅어지는 채움 또는 한 겹의 옅은 색. 쌓기 모드는 층이 구분되게 조금 더 진해요. |
+| `curve` | `'linear' \| 'smooth'` | `'linear'` | 직선 또는 튀어 오르지 않는 단조 곡선. 층의 위 · 아래 가장자리 모두에 적용돼요. |
+| `connectNulls` | `boolean` |  | null을 건너 이어 그려요(default type). |
+| `showTotal` | `boolean` | `stacked · percent면 true` | 툴팁 마지막 줄에 합계. |
+| `tooltipSort` | `'value' \| 'series' \| 'reverse'` | `쌓기 'reverse' · 그 외 'value'` | 툴팁 행 순서. reverse = 위에 쌓인 층부터. |
+| `formatAxisValue` | `(value) => string` | `'6천' · percent '45%'` | y축 라벨. percent에선 값이 0–1 비율이에요. |
+| `yTicks / referenceLines` | `number[] / LineChartReferenceLine[]` |  | percent에선 0–1 비율로 적어요(0.5 = 50%). |
+| `aria-label` | `string` | `'영역 차트'` | 차트 이름. 하이라이트한 값과 합계를 aria-live로 읽어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 채널별 방문 (stacked)
+
+쌓인 영역의 맨 위가 하루 합계예요. 툴팁은 위에 쌓인 시리즈부터 나오고 마지막 줄에 합계가 붙어요. 범례에 마우스를 올리면 그 층만 강조돼요.
+
+```tsx
+import { AreaChart, type LineSeries } from '@iamfiro/design'
+
+const CHANNELS: LineSeries[] = [
+  { key: 'search', label: '검색' },
+  { key: 'direct', label: '직접 방문' },
+  { key: 'social', label: '소셜' },
+  { key: 'email', label: '이메일' },
+]
+
+const DATA = [
+  { day: '10월 13일', search: 4200, direct: 2100, social: 1300, email: 600 },
+  { day: '10월 14일', search: 4500, direct: 2250, social: 1180, email: 720 },
+  { day: '10월 15일', search: 4380, direct: 2400, social: 1420, email: 680 },
+  { day: '10월 16일', search: 4920, direct: 2310, social: 1610, email: 910 },
+  { day: '10월 17일', search: 5100, direct: 2520, social: 1550, email: 840 },
+  { day: '10월 18일', search: 3900, direct: 1980, social: 1890, email: 420 },
+  { day: '10월 19일', search: 3700, direct: 1850, social: 2010, email: 390 },
+  { day: '10월 20일', search: 5300, direct: 2640, social: 1720, email: 1020 },
+  { day: '10월 21일', search: 5480, direct: 2700, social: 1680, email: 960 },
+  { day: '10월 22일', search: 5620, direct: 2810, social: 1840, email: 1110 },
+  { day: '10월 23일', search: 5750, direct: 2760, social: 1930, email: 1040 },
+  { day: '10월 24일', search: 6010, direct: 2920, social: 2080, email: 1180 },
+]
+
+export default function Example() {
+  return (
+    <AreaChart
+      type="stacked"
+      data={DATA}
+      xKey="day"
+      series={CHANNELS}
+      curve="smooth"
+      height={260}
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}명`}
+      aria-label="채널별 방문자"
+      style={{ width: '100%', maxWidth: 640 }}
+    />
+  )
+}
+```
+
+### 비율 (percent)
+
+y축은 0–100%, 툴팁 값은 그 행에서의 몫이고 합계 줄은 실제 수예요. fill="solid"는 한 겹의 옅은 색. 연도를 바꾸면 층 경계가 새 위치로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, AreaChart, type LineSeries } from '@iamfiro/design'
+
+const DEVICES: LineSeries[] = [
+  { key: 'mobile', label: '모바일' },
+  { key: 'desktop', label: '데스크톱' },
+  { key: 'tablet', label: '태블릿' },
+]
+
+const BY_MONTH = [
+  { month: '5월', mobile: 5200, desktop: 4100, tablet: 700 },
+  { month: '6월', mobile: 5800, desktop: 4000, tablet: 760 },
+  { month: '7월', mobile: 6400, desktop: 3900, tablet: 820 },
+  { month: '8월', mobile: 7100, desktop: 3700, tablet: 780 },
+  { month: '9월', mobile: 7600, desktop: 3800, tablet: 900 },
+  { month: '10월', mobile: 8300, desktop: 3600, tablet: 950 },
+]
+
+const LAST_YEAR = [
+  { month: '5월', mobile: 3900, desktop: 4800, tablet: 900 },
+  { month: '6월', mobile: 4100, desktop: 4700, tablet: 880 },
+  { month: '7월', mobile: 4600, desktop: 4500, tablet: 860 },
+  { month: '8월', mobile: 4800, desktop: 4600, tablet: 820 },
+  { month: '9월', mobile: 5100, desktop: 4400, tablet: 800 },
+  { month: '10월', mobile: 5400, desktop: 4300, tablet: 790 },
+]
+
+export default function Example() {
+  const [year, setYear] = useState<2025 | 2026>(2026)
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 640 }}>
+      <AreaChart
+        type="percent"
+        data={year === 2026 ? BY_MONTH : LAST_YEAR}
+        xKey="month"
+        series={DEVICES}
+        fill="solid"
+        yTickCount={5}
+        height={240}
+        formatValue={(v) => `${v.toLocaleString('ko-KR')}명`}
+        aria-label={`${year}년 기기별 방문 비율`}
+      />
+      <Inline gap={2}>
+        <Button size="sm" variant={year === 2025 ? 'primary' : 'secondary'} onClick={() => setYear(2025)}>
+          2025년
+        </Button>
+        <Button size="sm" variant={year === 2026 ? 'primary' : 'secondary'} onClick={() => setYear(2026)}>
+          2026년
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 겹친 두 시리즈 (default)
+
+두 시리즈를 바닥에서 반투명하게 겹쳐요. connectNulls는 빠진 날(null)을 건너 이어 그리고, referenceLines는 목표선이에요. 포커스한 뒤 ←/→, Home/End, Esc로도 움직여요.
+
+```tsx
+import { AreaChart, type LineSeries } from '@iamfiro/design'
+
+const SERIES: LineSeries[] = [
+  { key: 'thisWeek', label: '이번 주', color: '--chart-2' },
+  { key: 'lastWeek', label: '지난주', color: '--chart-5' },
+]
+
+// 이번 주는 금요일까지만 기록이 있고, 수요일은 집계가 빠졌어요(null → connectNulls로 이어 그림).
+const DATA = [
+  { day: '월', thisWeek: 1820, lastWeek: 1640 },
+  { day: '화', thisWeek: 2140, lastWeek: 1710 },
+  { day: '수', thisWeek: null, lastWeek: 1880 },
+  { day: '목', thisWeek: 2480, lastWeek: 1920 },
+  { day: '금', thisWeek: 2610, lastWeek: 2050 },
+  { day: '토', thisWeek: null, lastWeek: 1420 },
+  { day: '일', thisWeek: null, lastWeek: 1290 },
+]
+
+export default function Example() {
+  return (
+    <AreaChart
+      data={DATA}
+      xKey="day"
+      series={SERIES}
+      curve="smooth"
+      connectNulls
+      referenceLines={[{ value: 2400, label: '목표 2,400건', tone: 'accent' }]}
+      height={240}
+      tooltipSort="series"
+      formatValue={(v) => `${v.toLocaleString('ko-KR')}건`}
+      aria-label="요일별 주문 · 이번 주와 지난주"
+      style={{ width: '100%', maxWidth: 560 }}
+    />
+  )
+}
+```