@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/command-menu/AGENTS.md

@@ -0,0 +1,169 @@
+# CommandMenu
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+⌘K(Windows는 Ctrl+K)로 어디서든 여는 명령 팔레트. 검색칸 아래에 섹션별 명령이 있고, 입력하면 이름 · 힌트 · 키워드로 바로 걸러져요. 화살표로 움직이고 Enter로 실행, Tab은 다음 섹션의 첫 명령으로 건너뛰어요. 명령마다 단축키를 달면 메뉴가 열린 상태에서 바로 실행돼요. Dialog(bare, top) · Input(bare) · Listbox · Kbd로 조립했어요.
+
+```tsx
+import { CommandMenu } from '@iamfiro/design'
+```
+
+## API
+
+### CommandMenu
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `groups` (필수) | `CommandGroup[]` |  | 섹션 목록. { heading, items } |
+| `open / defaultOpen / onOpenChange` | `boolean / boolean / (open) => void` |  | 제어 · 비제어 열림 상태. |
+| `trigger` | `ReactElement` |  | 누르면 메뉴를 여는 버튼. |
+| `onSelect` | `(item: CommandItem) => void` |  | 명령이 실행될 때마다(항목의 onSelect 다음에) 불려요. |
+| `shortcutKey` | `string \| null` | `'k'` | ⌘/Ctrl과 함께 눌러 어디서든 열고 닫는 글자. null이면 꺼요. |
+| `placeholder` | `string` | `'명령어 또는 검색어를 입력하세요'` | 검색칸 안내 문구. |
+| `filter` | `(item, query) => boolean` | `defaultCommandFilter` | 걸러내기 규칙. 기본은 label · 문자열 hint · keywords에 포함되는지. |
+| `emptyText` | `(query) => ReactNode` |  | 결과가 없을 때 문구. |
+| `footer` | `ReactNode \| false` |  | 하단 안내 줄. 기본은 Tab 섹션 이동 · ⌘K 열기 · 닫기. false면 숨겨요. |
+| `closeOnSelect` | `boolean` | `true` | 실행 후 닫기. |
+| `title` | `string` | `'명령 메뉴'` | 화면에는 안 보이는 대화상자 이름(스크린 리더용). |
+
+### CommandItem
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` (필수) | `string` |  | 고유 값. |
+| `label` (필수) | `string` |  | 명령 이름. |
+| `hint` | `ReactNode` |  | 이름 뒤 회색 글자(앱, 채널, 경로). 문자열이면 검색에도 쓰여요. |
+| `icon` | `ReactNode` |  | 앞 타일. IconTile에 아이콘이나 BrandIcon을 담아요. |
+| `shortcut` | `string[]` |  | 메뉴가 열려 있을 때 바로 실행하는 키. 예: ['mod', '1'] |
+| `keywords` | `string[]` |  | 추가 검색어(별칭, 영어 이름). |
+| `disabled` | `boolean` |  | 보이지만 고를 수 없어요. 키보드 이동도 건너뛰어요. |
+| `onSelect` | `() => void` |  | 실행할 동작. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+버튼이나 ⌘K로 열어요. 앱 로고는 흰 IconTile(tone="surface")에 BrandIcon을 담고, 오른쪽에는 단축키 키캡이 붙어요. 열린 상태에서 ⌘1 … ⌘5를 누르면 해당 명령이 바로 실행돼요. "메일", "slack"처럼 키워드로도 찾아져요.
+
+```tsx
+import { CalendarPlus, FilePlus, FolderOpen, Settings, Sparkles } from 'lucide-react'
+import { BrandIcon, Button, IconTile, Inline, Kbd, Text, CommandMenu, toast, type CommandGroup, type CommandItem } from '@iamfiro/design'
+
+const logo = (name: Parameters<typeof BrandIcon>[0]['name']) => (
+  <IconTile tone="surface" size={26}>
+    <BrandIcon name={name} size={15} />
+  </IconTile>
+)
+
+const sections: { heading: string; items: Omit<CommandItem, 'onSelect'>[] }[] = [
+  {
+    heading: '추천',
+    items: [
+      { id: 'email', label: '이메일 쓰기', hint: 'Gmail', icon: logo('gmail'), shortcut: ['mod', '1'], keywords: ['메일', 'email'] },
+      {
+        id: 'assistant',
+        label: '어시스턴트에게 묻기',
+        hint: '요약, 초안, 답변',
+        icon: (
+          <IconTile tone="surface" size={26}>
+            <Sparkles color="var(--accent)" />
+          </IconTile>
+        ),
+        shortcut: ['mod', '2'],
+        keywords: ['ai'],
+      },
+      { id: 'task', label: '할 일 만들기', hint: 'ClickUp', icon: logo('clickup'), shortcut: ['mod', '3'], keywords: ['task', '태스크'] },
+      { id: 'crm', label: 'CRM에 연락처 추가', hint: 'HubSpot', icon: logo('hubspot'), shortcut: ['mod', '4'], keywords: ['contact'] },
+      { id: 'meeting', label: '회의 예약', hint: 'Google Calendar', icon: logo('google-calendar'), shortcut: ['mod', '5'], keywords: ['일정', 'meeting'] },
+    ],
+  },
+  {
+    heading: '공유',
+    items: [
+      { id: 'post', label: '업데이트 올리기', hint: '#team-updates', icon: logo('slack'), keywords: ['slack'] },
+      { id: 'page', label: '페이지로 저장', hint: 'Notion · 회의록', icon: logo('notion'), keywords: ['notion'] },
+    ],
+  },
+  {
+    heading: '일반',
+    items: [
+      { id: 'doc', label: '새 문서', icon: <IconTile size={26}><FilePlus /></IconTile>, shortcut: ['n'] },
+      { id: 'open', label: '최근 파일 열기', icon: <IconTile size={26}><FolderOpen /></IconTile> },
+      { id: 'event', label: '일정 추가', icon: <IconTile size={26}><CalendarPlus /></IconTile> },
+      { id: 'settings', label: '설정', icon: <IconTile size={26}><Settings /></IconTile>, keywords: ['settings', '환경설정'] },
+    ],
+  },
+]
+
+const groups: CommandGroup[] = sections.map((g) => ({
+  ...g,
+  items: g.items.map((it) => ({ ...it, onSelect: () => toast.success(`'${it.label}' 실행`) })),
+}))
+
+export default function Example() {
+  return (
+    <Inline gap={3}>
+      <CommandMenu groups={groups} trigger={<Button>명령 메뉴 열기</Button>} />
+      <Inline gap={2}>
+        <Text variant="body-sm" tone="tertiary">
+          또는
+        </Text>
+        <Kbd keys={['mod', 'k']} />
+      </Inline>
+    </Inline>
+  )
+}
+```
+
+### 제어 · 비활성 · 하단 숨김
+
+open과 onOpenChange로 바깥에서 열고, onSelect로 실행된 명령을 받아요. 한 화면에 메뉴가 여럿이면 shortcutKey={null}로 전역 단축키를 하나만 남겨요. 비활성 명령은 키보드 이동에서 건너뛰고, footer={false}는 하단 안내 줄을 숨겨요.
+
+```tsx
+import { useState } from 'react'
+import { Archive, Copy, Link, Pencil, Trash2 } from 'lucide-react'
+import { Button, IconTile, Stack, Text, CommandMenu, type CommandGroup } from '@iamfiro/design'
+
+const groups: CommandGroup[] = [
+  {
+    heading: '문서',
+    items: [
+      { id: 'rename', label: '이름 바꾸기', icon: <IconTile size={26}><Pencil /></IconTile>, keywords: ['rename'] },
+      { id: 'duplicate', label: '복제', icon: <IconTile size={26}><Copy /></IconTile>, keywords: ['copy'] },
+      { id: 'link', label: '링크 복사', hint: 'docs.lumen.app/…', icon: <IconTile size={26}><Link /></IconTile> },
+    ],
+  },
+  {
+    heading: '정리',
+    items: [
+      { id: 'archive', label: '보관', icon: <IconTile size={26}><Archive /></IconTile> },
+      { id: 'delete', label: '휴지통으로 이동', hint: '편집 권한 필요', icon: <IconTile size={26}><Trash2 /></IconTile>, disabled: true },
+    ],
+  },
+]
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  const [last, setLast] = useState<string | null>(null)
+
+  return (
+    <Stack gap={3} align="start">
+      <Button onClick={() => setOpen(true)}>문서 작업</Button>
+      <Text variant="body-sm" tone="tertiary">
+        마지막 실행: {last ?? '없음'}
+      </Text>
+      <CommandMenu
+        open={open}
+        onOpenChange={setOpen}
+        groups={groups}
+        onSelect={(it) => setLast(it.label)}
+        shortcutKey={null}
+        footer={false}
+        placeholder="이 문서에서 할 작업"
+      />
+    </Stack>
+  )
+}
+```

package/agents/comment/AGENTS.md

@@ -0,0 +1,206 @@
+# Comment
+
+> 대화 & 활동 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+댓글 · 토론의 메시지 한 개. 아바타, 굵은 이름, 오른쪽의 상대 시간(RelativeTime), 본문, 마우스를 올리면 나타나는 액션으로 이루어져요. CommentThread로 묶으면 선 없이 여백으로 구분되고, 같은 사람이 이어 쓴 메시지(continued)는 더 가깝게 붙어 한 묶음으로 읽혀요.
+
+```tsx
+import { Comment, CommentThread } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 메시지·댓글은 `Comment` + `CommentThread`(선 없이 여백, 같은 사람의 연속 메시지는 `continued`로 가깝게). 상대 시간은 직접 만들지 말고 `RelativeTime` / `formatRelativeTime`.
+
+## API
+
+### Comment
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `author` (필수) | `ReactNode` |  | 작성자. 문자열이면 기본 Avatar도 그려요. |
+| `children` | `ReactNode` |  | 본문. Text variant="code" 같은 인라인 요소를 섞을 수 있어요. |
+| `date` | `Date \| string \| number` |  | 작성 시각. RelativeTime으로 "2분 전"처럼 보이고, 올리면 전체 날짜가 나와요. |
+| `avatar` | `ReactNode` |  | 기본 아바타 대신 쓸 요소. |
+| `meta` | `ReactNode` |  | 이름 뒤 작은 요소(배지, "수정됨"). |
+| `actions` | `ReactNode` |  | 오른쪽 버튼들. hover · focus 때 나타나요. |
+| `footer` | `ReactNode` |  | 본문 아래(첨부, 상태 줄, 반응). |
+| `continued` | `boolean` |  | 같은 사람의 이어 쓴 메시지. 아바타 · 이름 없이 본문만, 위 메시지에 가깝게. |
+| `avatarSize` | `number` | `28` | 아바타 크기(px). 본문 들여쓰기도 따라가요. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+### CommentThread
+
+Comment.Thread로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | Comment들(오래된 것부터). |
+| `aria-label` | `string` |  | 주면 role="group"과 함께 붙어요. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 댓글 카드
+
+Card + CardHeader 안에 CommentThread와 ChatComposer size="sm"을 조립했어요. 본문 앞에는 Text variant="code" 칩, footer에는 Collapsible variant="inline" 상태 줄을 넣었어요. 답글을 보내면 아래에 추가돼요.
+
+```tsx
+import { useState } from 'react'
+import { CircleCheck, X } from 'lucide-react'
+import { Button, Stack, Text, Card, CardBody, CardHeader, ChatComposer, Collapsible, Comment, CommentThread } from '@iamfiro/design'
+
+const minutesAgo = (m: number) => new Date(Date.now() - m * 60_000)
+const ASKED = minutesAgo(12)
+const ANSWERED = minutesAgo(10)
+
+interface Message {
+  id: string
+  author: string
+  date: Date
+  text: string
+}
+
+export default function Example() {
+  const [messages, setMessages] = useState<Message[]>([])
+
+  return (
+    <Card padding="sm" style={{ width: 380 }}>
+      <CardHeader
+        title={
+          <Text as="span" variant="label-md">
+            댓글{' '}
+            <Text as="span" variant="label-md" tone="tertiary">
+              메시지 {messages.length + 2}개
+            </Text>
+          </Text>
+        }
+        actions={<Button variant="ghost" size="sm" iconOnly icon={<X />} aria-label="댓글 닫기" />}
+      />
+      <CardBody>
+        <Stack gap={4}>
+          <CommentThread aria-label="댓글">
+            <Comment author="이도현" date={ASKED}>
+              <Text variant="code">/수정</Text> 소개 문단을 더 짧고 분명하게 다듬어 주세요.
+            </Comment>
+            <Comment
+              author="김민지"
+              date={ANSWERED}
+              footer={
+                <Collapsible variant="inline" icon={<CircleCheck />} iconTone="success" label="수정 완료">
+                  소개 문단 · 3문장 → 2문장, 128자 줄임
+                </Collapsible>
+              }
+            >
+              다듬었어요. 확인해 주세요.
+            </Comment>
+            {messages.map((m) => (
+              <Comment key={m.id} author={m.author} date={m.date}>
+                {m.text}
+              </Comment>
+            ))}
+          </CommentThread>
+          <ChatComposer
+            size="sm"
+            placeholder="답글을 쓰거나 @로 멤버를 불러 보세요"
+            aria-label="답글"
+            onSubmit={(text) => setMessages((prev) => [...prev, { id: String(Date.now()), author: '이도현', date: new Date(), text }])}
+          />
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 이어 쓴 메시지 묶기
+
+같은 사람이 5분 안에 이어 쓰면 continued로 아바타와 이름을 생략해요. 본문은 위 메시지와 같은 선에 맞춰져요.
+
+```tsx
+import { Badge, Comment, CommentThread } from '@iamfiro/design'
+
+const at = (minutesAgo: number) => new Date(Date.now() - minutesAgo * 60_000)
+
+const MESSAGES = [
+  { id: '1', author: '김민지', date: at(64), text: '디자인 시안 2안 올렸어요.' },
+  { id: '2', author: '김민지', date: at(63), text: '색은 아직 확정 전이라 회색으로 두었어요.' },
+  { id: '3', author: '김민지', date: at(61), text: '내일 오전까지 의견 주시면 반영할게요.' },
+  { id: '4', author: '이도현', date: at(25), text: '2안이 좋아요. 버튼 문구만 "저장"으로 바꿔 주세요.' },
+  { id: '5', author: '박서연', date: at(3), text: '저도 2안이요!' },
+]
+
+/** Same author within 5 minutes of their previous message → shown as a follow-up. */
+const isContinued = (i: number) => {
+  const prev = MESSAGES[i - 1]
+  const cur = MESSAGES[i]
+  return !!prev && prev.author === cur.author && cur.date.getTime() - prev.date.getTime() < 5 * 60_000
+}
+
+export default function Example() {
+  return (
+    <CommentThread aria-label="토론" style={{ width: 400 }}>
+      {MESSAGES.map((m, i) => (
+        <Comment key={m.id} author={m.author} date={m.date} continued={isContinued(i)} meta={m.author === '김민지' ? <Badge>작성자</Badge> : undefined}>
+          {m.text}
+        </Comment>
+      ))}
+    </CommentThread>
+  )
+}
+```
+
+### 액션 · 메타
+
+actions는 마우스를 올리거나 포커스가 들어오면 나타나요(터치 기기에선 항상). meta 자리엔 배지나 "수정됨"을 넣어요.
+
+```tsx
+import { useState } from 'react'
+import { MoreHorizontal, Reply, SmilePlus } from 'lucide-react'
+import { Button, Text, Comment, CommentThread, DropdownMenu, DropdownMenuItem } from '@iamfiro/design'
+
+const POSTED = new Date(Date.now() - 2 * 24 * 60 * 60_000)
+const EDITED = new Date(Date.now() - 90_000)
+
+export default function Example() {
+  const [replies, setReplies] = useState(0)
+  const actions = (
+    <>
+      <Button variant="ghost" size="sm" iconOnly icon={<SmilePlus />} aria-label="반응 남기기" />
+      <Button variant="ghost" size="sm" iconOnly icon={<Reply />} aria-label="답글" onClick={() => setReplies((n) => n + 1)} />
+      <DropdownMenu align="end" trigger={<Button variant="ghost" size="sm" iconOnly icon={<MoreHorizontal />} aria-label="더 보기" />}>
+        <DropdownMenuItem>링크 복사</DropdownMenuItem>
+        <DropdownMenuItem>수정</DropdownMenuItem>
+      </DropdownMenu>
+    </>
+  )
+  return (
+    <CommentThread style={{ width: 420 }}>
+      <Comment author="이도현" date={POSTED} actions={actions}>
+        3분기 회고 문서 초안이에요. 각자 맡은 부분에 의견 남겨 주세요.
+      </Comment>
+      <Comment
+        author="김민지"
+        date={EDITED}
+        meta={
+          <Text variant="caption" tone="tertiary">
+            수정됨
+          </Text>
+        }
+        actions={actions}
+        footer={
+          replies > 0 ? (
+            <Text variant="caption" tone="accent">
+              답글 {replies}개
+            </Text>
+          ) : undefined
+        }
+      >
+        목표 대비 결과 표는 제가 채울게요.
+      </Comment>
+    </CommentThread>
+  )
+}
+```

package/agents/context-menu/AGENTS.md

@@ -0,0 +1,303 @@
+# ContextMenu
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+마우스 오른쪽 버튼을 누른 자리에서 열리는 메뉴. 터치에서는 손가락을 움직이지 않고 500ms(TIMING.longPress) 누르고 있으면 열리고, 키보드는 영역에 포커스한 뒤 Shift+F10 또는 메뉴 키로 포커스한 요소 아래에 열어요. 항목 · 단축키 · 체크/라디오 · 하위 메뉴 · 구분선은 DropdownMenu와 같은 조각을 그대로 써요. 화면 가장자리에 가까우면 왼쪽 · 위로 뒤집히고 화면 안으로 밀려 들어와요. Esc · 바깥 클릭 · 항목 실행으로 닫히고(닫힐 때도 애니메이션), 포커스는 열기 전 자리로 돌아가요. 스크롤하거나 창 크기가 바뀌면 누른 자리가 어긋나므로 닫혀요.
+
+```tsx
+import { ContextMenu, ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuSub } from '@iamfiro/design'
+```
+
+## API
+
+### ContextMenu
+
+항목은 DropdownMenu와 같아요: ContextMenuItem(= DropdownMenuItem) · ContextMenuCheckboxItem · ContextMenuRadioGroup · ContextMenuRadioItem · ContextMenuLabel · ContextMenuSeparator · ContextMenuSub. props는 DropdownMenu 문서를 보세요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `trigger` (필수) | `ReactNode` |  | 오른쪽 클릭 · 길게 누르기 · Shift+F10을 받는 영역. 감싸는 요소는 display: contents라 레이아웃에 끼어들지 않아요. 키보드로 열려면 포커스할 수 있어야 해요(tabIndex 또는 버튼). |
+| `children` (필수) | `ReactNode` |  | 항목, 라벨, 구분선, 하위 메뉴. |
+| `disabled` | `boolean` |  | 가로채지 않고 브라우저 기본 메뉴를 그대로 둬요. |
+| `minWidth` | `number` | `200` | 패널 최소 폭(px). |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `aria-label` | `string` |  | 메뉴(role="menu")의 접근성 이름. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 파일 목록
+
+항목마다 ContextMenu로 감싸면 그 항목에 대한 메뉴가 돼요. 휴지통 · 이동처럼 되돌릴 수 있는 동작은 바로 실행하고 toast.undo()로 실행 취소를 줘요. 하위 메뉴는 DropdownMenu와 같이 잠깐 머물면 열리고, 대각선으로 이동하는 동안은 지나는 행이 강조를 빼앗지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { Copy, Download, ExternalLink, Folder, FolderInput, Link2, Mail, Pencil, Share2, Star, Trash2 } from 'lucide-react'
+import { FileIcon, Grid, Stack, Text, Card, CardBody, ContextMenu, ContextMenuItem, ContextMenuSeparator, ContextMenuSub, toast } from '@iamfiro/design'
+
+interface FileRow {
+  id: string
+  name: string
+  meta: string
+  folder: string
+}
+
+const INITIAL: FileRow[] = [
+  { id: '1', name: '3분기 이사회 보고서.pdf', meta: '2.4MB · 10월 25일', folder: '회의록' },
+  { id: '2', name: '브랜드 가이드.fig', meta: '18MB · 10월 21일', folder: '디자인' },
+  { id: '3', name: '고객 인터뷰.mp4', meta: '312MB · 10월 18일', folder: '마케팅' },
+  { id: '4', name: '예산안_v3.xlsx', meta: '86KB · 10월 12일', folder: '회의록' },
+  { id: '5', name: '출시 일정.docx', meta: '41KB · 10월 9일', folder: '마케팅' },
+  { id: '6', name: '로고 원본.png', meta: '1.2MB · 9월 30일', folder: '디자인' },
+]
+const FOLDERS = ['디자인', '마케팅', '회의록', '보관함']
+
+export default function Example() {
+  const [files, setFiles] = useState(INITIAL)
+  const [starred, setStarred] = useState<string[]>(['2'])
+
+  const remove = (file: FileRow) => {
+    const before = files
+    setFiles((list) => list.filter((f) => f.id !== file.id))
+    toast.undo(`‘${file.name}’을 휴지통으로 옮겼어요`, { onUndo: () => setFiles(before) })
+  }
+  const move = (file: FileRow, to: string) => {
+    const from = file.folder
+    setFiles((list) => list.map((f) => (f.id === file.id ? { ...f, folder: to } : f)))
+    toast.undo(`‘${to}’ 폴더로 옮겼어요`, {
+      onUndo: () => setFiles((list) => list.map((f) => (f.id === file.id ? { ...f, folder: from } : f))),
+    })
+  }
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 560 }}>
+      <Grid columns={3} gap={3}>
+        {files.map((file) => {
+          const isStarred = starred.includes(file.id)
+          return (
+            <ContextMenu
+              key={file.id}
+              aria-label={`${file.name} 메뉴`}
+              trigger={
+                <Card
+                  as="button"
+                  type="button"
+                  padding="sm"
+                  interactive
+                  style={{ textAlign: 'left' }}
+                  onDoubleClick={() => toast(`‘${file.name}’을 열었어요`)}
+                >
+                  <CardBody>
+                    <Stack gap={2} align="start">
+                      <FileIcon name={file.name} size={28} />
+                      <Stack gap={0} align="start" style={{ minWidth: 0, width: '100%' }}>
+                        <Text variant="label-sm" truncate style={{ maxWidth: '100%' }}>
+                          {file.name}
+                        </Text>
+                        <Text variant="caption" tone="tertiary">
+                          {file.folder} · {file.meta}
+                        </Text>
+                      </Stack>
+                    </Stack>
+                  </CardBody>
+                </Card>
+              }
+            >
+              <ContextMenuItem icon={<ExternalLink />} shortcut={['enter']} onSelect={() => toast(`‘${file.name}’을 열었어요`)}>
+                열기
+              </ContextMenuItem>
+              <ContextMenuItem icon={<Pencil />} shortcut={['F2']} onSelect={() => toast('이름 바꾸기를 열었어요')}>
+                이름 바꾸기
+              </ContextMenuItem>
+              <ContextMenuItem icon={<Copy />} shortcut={['mod', 'D']} onSelect={() => toast.success('사본을 만들었어요')}>
+                사본 만들기
+              </ContextMenuItem>
+              <ContextMenuItem
+                icon={<Star />}
+                onSelect={() => setStarred((ids) => (isStarred ? ids.filter((x) => x !== file.id) : [...ids, file.id]))}
+              >
+                {isStarred ? '별표 해제' : '별표 표시'}
+              </ContextMenuItem>
+              <ContextMenuSeparator />
+              <ContextMenuSub label="이동" icon={<FolderInput />}>
+                {FOLDERS.map((f) => (
+                  <ContextMenuItem
+                    key={f}
+                    icon={<Folder />}
+                    disabled={f === file.folder}
+                    description={f === file.folder ? '현재 폴더' : undefined}
+                    onSelect={() => move(file, f)}
+                  >
+                    {f}
+                  </ContextMenuItem>
+                ))}
+              </ContextMenuSub>
+              <ContextMenuSub label="공유" icon={<Share2 />}>
+                <ContextMenuItem icon={<Link2 />} onSelect={() => toast.success('링크를 복사했어요')}>
+                  링크 복사
+                </ContextMenuItem>
+                <ContextMenuItem icon={<Mail />} onSelect={() => toast('메일 작성 창을 열었어요')}>
+                  이메일로 보내기
+                </ContextMenuItem>
+              </ContextMenuSub>
+              <ContextMenuItem icon={<Download />} onSelect={() => toast('다운로드를 시작했어요')}>
+                다운로드
+              </ContextMenuItem>
+              <ContextMenuSeparator />
+              <ContextMenuItem icon={<Trash2 />} danger shortcut={['delete']} onSelect={() => remove(file)}>
+                휴지통으로 이동
+              </ContextMenuItem>
+            </ContextMenu>
+          )
+        })}
+      </Grid>
+      <Text variant="caption" tone="tertiary">
+        파일을 마우스 오른쪽 버튼으로 클릭하거나 길게 누르세요. 별표 {starred.length}개
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 캔버스 · 보기 옵션
+
+빈 영역의 메뉴. 체크 항목과 라디오 그룹은 고른 뒤에도 메뉴가 열려 있어요. 영역에 tabIndex를 주면 키보드로 포커스한 뒤 Shift+F10으로 열 수 있고, 이때는 첫 항목이 바로 강조돼요. 오른쪽 아래 구석에서 열어 보면 패널이 뒤집혀요.
+
+```tsx
+import { useState } from 'react'
+import { ClipboardPaste, Plus, Square, StickyNote, Type } from 'lucide-react'
+import { Box, Inline, Kbd, Stack, Text, ContextMenu, ContextMenuCheckboxItem, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuSub, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [ruler, setRuler] = useState(true)
+  const [snap, setSnap] = useState(false)
+  const [zoom, setZoom] = useState('100')
+  const [shapes, setShapes] = useState(0)
+
+  const add = (name: string) => {
+    setShapes((n) => n + 1)
+    toast(`${name}을 추가했어요`)
+  }
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 520 }}>
+      <ContextMenu
+        aria-label="캔버스 메뉴"
+        trigger={
+          <Box
+            tabIndex={0}
+            background="subtle"
+            radius="lg"
+            padding={6}
+            style={{ height: 220, display: 'grid', placeItems: 'center' }}
+            aria-label="캔버스"
+          >
+            <Stack gap={2} align="center">
+              <Text variant="label-md" tone="secondary">
+                빈 곳을 마우스 오른쪽 버튼으로 클릭하세요
+              </Text>
+              <Inline gap={1} align="center">
+                <Text variant="caption" tone="tertiary">
+                  키보드는 포커스한 뒤
+                </Text>
+                <Kbd keys={['shift', 'F10']} size="sm" />
+              </Inline>
+            </Stack>
+          </Box>
+        }
+      >
+        <ContextMenuItem icon={<ClipboardPaste />} shortcut={['mod', 'V']} disabled description="클립보드가 비어 있어요">
+          붙여넣기
+        </ContextMenuItem>
+        <ContextMenuSub label="새로 만들기" icon={<Plus />}>
+          <ContextMenuItem icon={<Square />} shortcut={['R']} onSelect={() => add('사각형')}>
+            사각형
+          </ContextMenuItem>
+          <ContextMenuItem icon={<Type />} shortcut={['T']} onSelect={() => add('텍스트')}>
+            텍스트
+          </ContextMenuItem>
+          <ContextMenuItem icon={<StickyNote />} shortcut={['N']} onSelect={() => add('메모')}>
+            메모
+          </ContextMenuItem>
+        </ContextMenuSub>
+        <ContextMenuSeparator />
+        <ContextMenuLabel>보기</ContextMenuLabel>
+        <ContextMenuCheckboxItem checked={ruler} onCheckedChange={setRuler} shortcut={['shift', 'R']}>
+          눈금자 표시
+        </ContextMenuCheckboxItem>
+        <ContextMenuCheckboxItem checked={snap} onCheckedChange={setSnap}>
+          격자에 맞추기
+        </ContextMenuCheckboxItem>
+        <ContextMenuSeparator />
+        <ContextMenuRadioGroup label="확대" value={zoom} onValueChange={setZoom}>
+          <ContextMenuRadioItem value="50">50%</ContextMenuRadioItem>
+          <ContextMenuRadioItem value="100">100%</ContextMenuRadioItem>
+          <ContextMenuRadioItem value="200">200%</ContextMenuRadioItem>
+        </ContextMenuRadioGroup>
+      </ContextMenu>
+      <Text variant="caption" tone="tertiary">
+        눈금자 {ruler ? '켜짐' : '꺼짐'} · 격자 맞춤 {snap ? '켜짐' : '꺼짐'} · {zoom}% · 도형 {shapes}개
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 비활성 · 제어
+
+disabled면 브라우저 기본 메뉴가 그대로 떠요(글을 복사해야 하는 화면 등). open · onOpenChange로 열림 상태를 밖에서 읽거나 정할 수 있어요. 비활성 항목은 description으로 이유를 알려 주세요.
+
+```tsx
+import { useState } from 'react'
+import { Copy, Highlighter, Link2, MessageSquarePlus, Search } from 'lucide-react'
+import { Stack, Switch, Text, Card, CardBody, ContextMenu, ContextMenuItem, ContextMenuSeparator, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [native, setNative] = useState(false)
+  const [open, setOpen] = useState(false)
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 460 }}>
+      <ContextMenu
+        aria-label="문단 메뉴"
+        disabled={native}
+        open={open}
+        onOpenChange={setOpen}
+        trigger={
+          <Card padding="sm" tabIndex={0}>
+            <CardBody>
+              <Text as="p" variant="body-md">
+                다음 분기에는 온보딩 흐름을 세 단계로 줄이고, 첫 주 안에 팀원을 초대한 워크스페이스의 비율을 40%까지 올리는 것을 목표로
+                해요.
+              </Text>
+            </CardBody>
+          </Card>
+        }
+      >
+        <ContextMenuItem icon={<Copy />} shortcut={['mod', 'C']} onSelect={() => toast.success('문단을 복사했어요')}>
+          복사
+        </ContextMenuItem>
+        <ContextMenuItem icon={<Link2 />} onSelect={() => toast.success('이 문단의 링크를 복사했어요')}>
+          문단 링크 복사
+        </ContextMenuItem>
+        <ContextMenuItem icon={<Search />} onSelect={() => toast('문서에서 검색했어요')}>
+          문서에서 찾기
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem icon={<MessageSquarePlus />} shortcut={['mod', 'alt', 'M']} onSelect={() => toast('댓글 입력 창을 열었어요')}>
+          댓글 달기
+        </ContextMenuItem>
+        <ContextMenuItem icon={<Highlighter />} disabled description="읽기 전용 문서예요">
+          하이라이트
+        </ContextMenuItem>
+      </ContextMenu>
+      <Switch label="브라우저 기본 메뉴 쓰기 (disabled)" checked={native} onChange={(e) => setNative(e.target.checked)} />
+      <Text variant="caption" tone="tertiary">
+        메뉴 {open ? '열림' : '닫힘'} — open · onOpenChange로 상태를 밖에서 읽을 수 있어요.
+      </Text>
+    </Stack>
+  )
+}
+```