@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/input/AGENTS.md

@@ -0,0 +1,261 @@
+# Input
+
+> 텍스트 입력 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+글자를 입력받는 기본 입력창과 Field · Textarea · NativeSelect. 포커스되면 연한 파란 테두리와 링이 바깥 칸에만 생기고, 오류는 빨간 테두리, 비활성은 회색 배경으로 구분해요.
+
+```tsx
+import { Field, Input, Textarea, NativeSelect } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 다른 표면 안에 들어간 입력(ChatComposer의 글 칸)은 `Textarea bare`: **모든 상태(hover·focus·disabled)에서** 자체 테두리·배경·여백이 없어야 한다. 테두리·링·비활성 회색은 바깥 표면(`.ds-control`) 하나만 그린다. 상태별 리셋을 빠뜨리면 비활성일 때 안쪽 칸이 따로 보인다.
+
+## API
+
+### Input
+
+나머지 props는 안쪽 <input>에 전달돼요. ref도 <input>을 가리켜요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `leading` | `ReactNode` |  | 입력 앞 아이콘이나 글자. |
+| `trailing` | `ReactNode` |  | 입력 뒤 아이콘이나 글자. |
+| `invalid` | `boolean` |  | 오류 표시(빨간 테두리 + aria-invalid). |
+| `disabled` | `boolean` |  | 비활성(회색 배경, 금지 커서). |
+| `bare` | `boolean` |  | 테두리 · 배경 · 포커스 링 · 모서리 · 좌우 여백 없이(모든 상태). 명령 팔레트처럼 바깥 표면이 모양을 그릴 때. SearchInput에도 그대로 전달돼요. |
+| `wrapperClassName` | `string` |  | 바깥 칸(.ds-input)에 붙일 클래스. className은 <input>에 붙어요. |
+| `wrapperStyle` | `CSSProperties` |  | 바깥 칸 스타일. 너비 조절 등에 써요. |
+
+### Field
+
+라벨 · 입력 · 도움말을 세로로 묶어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` |  | 라벨. |
+| `hint` | `ReactNode` |  | 아래 도움말. invalid면 오류 문구로 보여요. |
+| `invalid` | `boolean` |  | 도움말을 빨간색으로. |
+| `htmlFor` | `string` |  | 라벨과 연결할 입력의 id. |
+| `children` (필수) | `ReactNode` |  | 입력 요소. |
+
+### Textarea
+
+<textarea>의 props를 그대로 받아요. 최소 높이 104px, 세로로만 늘릴 수 있어요. 오류는 aria-invalid.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `rows` | `number` |  | 보이는 줄 수. |
+| `autoResize` | `boolean` |  | 글에 맞춰 높이가 자라요(한 줄에서 시작, 손잡이 없음). |
+| `maxRows` | `number` |  | autoResize일 때 최대 줄 수. 넘으면 스크롤. |
+| `bare` | `boolean` |  | 테두리 · 배경 · 여백 없이. 바깥 표면이 포커스를 그릴 때. |
+| `aria-invalid` | `boolean` |  | 오류 표시. |
+| `disabled` | `boolean` |  | 비활성. |
+
+### NativeSelect
+
+<select>의 props를 그대로 받고 <option>을 children으로 넣어요. style은 바깥 칸에 적용돼요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | <option> 목록. |
+| `value / defaultValue` | `string` |  | 선택값. |
+| `onChange` | `(e: ChangeEvent<HTMLSelectElement>) => void` |  | 값이 바뀔 때. |
+| `disabled` | `boolean` |  | 비활성. |
+| `style` | `CSSProperties` |  | 바깥 칸 스타일. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+Field로 감싸면 라벨과 도움말이 붙어요. htmlFor와 Input의 id를 맞추면 라벨을 눌러 포커스할 수 있어요.
+
+```tsx
+import { Mail } from 'lucide-react'
+import { Field, Input } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ width: 320 }}>
+      <Field label="이메일" hint="이메일은 외부에 공유되지 않아요." htmlFor="signup-email">
+        <Input id="signup-email" type="email" placeholder="you@company.com" leading={<Mail />} />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 앞뒤 요소
+
+leading · trailing에는 아이콘이나 짧은 글자(단위, 도메인)를 넣어요. 포커스되면 아이콘 색이 조금 진해져요.
+
+```tsx
+import { useState } from 'react'
+import { Link, Search } from 'lucide-react'
+import { Field, Input, useDigitInput } from '@iamfiro/design'
+
+const won = (digits: string) => (digits ? Number(digits).toLocaleString('ko-KR') : '')
+
+export default function Example() {
+  const [budget, setBudget] = useState('1200000')
+  // Only digits get in; the commas follow as you type.
+  const budgetInput = useDigitInput({ digits: budget, onDigitsChange: setBudget, format: won, maxDigits: 12 })
+
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 260px)', gap: 16 }}>
+      <Field label="워크스페이스 주소" htmlFor="ws-url">
+        <Input id="ws-url" leading={<Link />} trailing=".lumen.app" defaultValue="acme" />
+      </Field>
+      <Field label="월 예산" htmlFor="budget">
+        <Input id="budget" {...budgetInput} trailing="원" placeholder="0" style={{ textAlign: 'right' }} />
+      </Field>
+      <Field label="프로젝트 찾기" htmlFor="project-search">
+        <Input id="project-search" leading={<Search />} placeholder="이름으로 검색" />
+      </Field>
+      <Field label="웹사이트" htmlFor="website">
+        <Input id="website" leading="https://" placeholder="example.com" />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 크기와 상태
+
+size는 높이 36 / 44 / 52px. Field와 Input 모두에 invalid를 주면 도움말도 빨갛게 바뀌어요.
+
+```tsx
+import { Field, Input } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 220px)', gap: 16 }}>
+      <Field label="작게 (sm)" htmlFor="name-sm">
+        <Input id="name-sm" size="sm" placeholder="높이 36px" />
+      </Field>
+      <Field label="기본 (md)" htmlFor="name-md">
+        <Input id="name-md" placeholder="높이 44px" />
+      </Field>
+      <Field label="크게 (lg)" htmlFor="name-lg">
+        <Input id="name-lg" size="lg" placeholder="높이 52px" />
+      </Field>
+      <Field label="워크스페이스 이름" invalid hint="이미 사용 중인 이름이에요." htmlFor="ws-name">
+        <Input id="ws-name" defaultValue="acme" invalid />
+      </Field>
+      <Field label="프로젝트 ID" hint="만든 뒤에는 바꿀 수 없어요." htmlFor="project-id">
+        <Input id="project-id" defaultValue="lumen-web" disabled />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 다른 표면 안의 입력 (bare)
+
+bare면 테두리 · 배경 · 포커스 링 · 좌우 여백이 어떤 상태에서도 없어요. 명령 팔레트 검색 줄처럼 바깥 표면(Card)이 모양을 그리고, 좌우 여백도 바깥에서 정해요. 높이와 글자 크기는 size를 따라요.
+
+```tsx
+import { useState } from 'react'
+import { FileText, Search, Settings, Users } from 'lucide-react'
+import { Box, IconTile, Input, Kbd, Separator, Card, List, ListItem } from '@iamfiro/design'
+
+const items = [
+  { title: '10월 회의록', description: '문서 · 김민지', icon: <FileText /> },
+  { title: '팀원 관리', description: '설정 · 워크스페이스', icon: <Users /> },
+  { title: '알림 설정', description: '설정 · 내 계정', icon: <Settings /> },
+]
+
+export default function Example() {
+  const [query, setQuery] = useState('')
+  const shown = items.filter((item) => item.title.includes(query.trim()))
+
+  return (
+    <Card padding="sm" style={{ maxWidth: 440 }}>
+      <Box paddingX={3}>
+        <Input
+          bare
+          size="lg"
+          type="search"
+          aria-label="명령 검색"
+          placeholder="무엇을 찾고 있나요?"
+          leading={<Search />}
+          trailing={<Kbd keys={['esc']} />}
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+        />
+      </Box>
+      <Separator spacing={1} />
+      <List aria-label="검색 결과">
+        {shown.map((item) => (
+          <ListItem
+            key={item.title}
+            title={item.title}
+            description={item.description}
+            leading={<IconTile tone="surface">{item.icon}</IconTile>}
+            onClick={() => {}}
+          />
+        ))}
+      </List>
+    </Card>
+  )
+}
+```
+
+### Textarea · NativeSelect
+
+여러 줄 입력과 브라우저 기본 select. Textarea의 오류는 aria-invalid로 표시해요. 검색·아이콘이 필요하면 Select를 쓰세요.
+
+```tsx
+import { Field, NativeSelect, Textarea } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 280px)', gap: 16, alignItems: 'start' }}>
+      <div style={{ display: 'grid', gap: 16 }}>
+        <Field label="리전" htmlFor="region">
+          <NativeSelect id="region" defaultValue="icn">
+            <option value="icn">서울 (icn1)</option>
+            <option value="nrt">도쿄 (nrt1)</option>
+            <option value="sfo">샌프란시스코 (sfo1)</option>
+          </NativeSelect>
+        </Field>
+        <Field label="요금제" hint="관리자만 바꿀 수 있어요." htmlFor="plan">
+          <NativeSelect id="plan" defaultValue="team" disabled>
+            <option value="team">팀</option>
+          </NativeSelect>
+        </Field>
+      </div>
+      <div style={{ display: 'grid', gap: 16 }}>
+        <Field label="메모" htmlFor="memo">
+          <Textarea id="memo" placeholder="내용을 입력하세요" rows={3} />
+        </Field>
+        <Field label="취소 사유" invalid hint="10자 이상 입력해 주세요." htmlFor="reason">
+          <Textarea id="reason" defaultValue="일정 변경" aria-invalid />
+        </Field>
+      </div>
+    </div>
+  )
+}
+```
+
+### Textarea 자동 높이
+
+autoResize면 한 줄에서 시작해 글에 맞춰 자라고, maxRows를 넘으면 스크롤돼요. bare는 테두리·여백을 없애 다른 표면 안에 넣을 때 써요(ChatComposer).
+
+```tsx
+import { Field, Textarea } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ width: 360 }}>
+      <Field label="코멘트" hint="5줄까지 늘어나고, 그 뒤로는 스크롤돼요." htmlFor="comment">
+        <Textarea id="comment" autoResize maxRows={5} placeholder="여러 줄을 입력해 보세요" />
+      </Field>
+    </div>
+  )
+}
+```

package/agents/kanban/AGENTS.md

@@ -0,0 +1,352 @@
+# Kanban
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+열 사이로 카드를 끌어 옮기는 보드. 끌기 시작하면 카드 사본이 포인터를 따라오고, 놓일 자리에 빈칸이 열리며 다른 카드가 비켜서요. 놓는 순간 확정되고 사본이 제자리로 날아가 앉아요. Esc를 누르거나 받지 않는 열에서 놓으면 원래 자리로 돌아가요. 키보드(스페이스로 들고 화살표로 옮기기)와 터치(길게 눌러 끌기)도 같은 흐름이고, 모든 위치 변화는 이전 자리에서 미끄러지듯 움직여요.
+
+```tsx
+import { KanbanBoard, KanbanCard, moveKanbanItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 열 사이로 카드를 옮기는 보드는 `KanbanBoard`(회색 레인 위 흰 카드, 기본 카드 면은 `KanbanCard`). 끌기 = 포인터를 따라오는 사본 + 놓일 자리 빈칸, 놓을 때 확정(`onValueChange`)하고 사본이 제자리로 날아가 앉는다. Esc · 거절 = 원래 자리로. 거절 이유는 `canMove`가 문자열로 돌려주면 열 안에 보인다. 진행 한도는 열 `limit`(차면 주황 · 넘으면 빨강, `limitMode="block"`이면 받지 않음). 키보드는 스페이스로 들고 화살표로 옮기기, 터치는 `TIMING.longPress`. 위치 변화는 모두 FLIP(offset 기준으로 재서 진행 중 transform에 흔들리지 않게).
+
+## API
+
+### KanbanBoard
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `columns` (필수) | `KanbanColumn[]` |  | { id, title, label?, description?, color?, limit?, limitMode? } 목록. 순서대로 왼쪽부터. |
+| `value / defaultValue` | `Record<columnId, T[]>` |  | 열마다 카드 목록(제어/비제어). T는 { id } 이상. |
+| `onValueChange` | `(next, move) => void` |  | 놓는 순간 한 번. move = { item, from, to }(index는 옮긴 카드를 뺀 기준). 끄는 동안의 미리보기에선 부르지 않아요. |
+| `canMove` | `(move) => boolean \| string` |  | 다른 열로 옮겨도 되는지. 문자열이면 거절 이유로 열 안에 보여요. 같은 열 안 순서 바꾸기는 언제나 허용. |
+| `renderCard` | `(item, { dragging, lifted }) => ReactNode` | `<KanbanCard {...item} />` | 카드 면. dragging = 포인터를 따라오는 사본, lifted = 키보드로 들린 카드. |
+| `onCardOpen` | `(item) => void` |  | 클릭 또는 Enter. 끌기 뒤의 클릭은 무시해요. |
+| `onCardAdd` | `(columnId, title) => void` |  | 주면 열 아래 "카드 추가". Enter = 추가(칸은 열린 채), Shift+Enter = 줄바꿈, Esc = 닫기. 한글 조합 중 Enter는 무시. |
+| `columnActions` | `(column) => ReactNode` |  | 열 머리 오른쪽 버튼 · 메뉴. |
+| `getItemLabel` | `(item) => string` | `item.title` | 안내 문구에 쓰는 카드 이름. |
+| `columnWidth` | `number` | `288` | 열 폭(px). |
+| `emptyLabel` | `ReactNode` | `'비어 있어요'` | 빈 열 문구. |
+| `aria-label` | `string` | `'칸반 보드'` | 보드 이름. |
+
+### KanbanColumn
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `limit` | `number` |  | 진행 한도(WIP). 머리에 "2/3"으로, 차면 주황 · 넘으면 빨강. |
+| `limitMode` | `'warn' \| 'block'` | `'warn'` | block이면 한도가 찬 열은 다른 열의 카드를 받지 않아요. |
+| `color` | `string` |  | 제목 앞 점 색. CSS 변수 이름('--chart-1') 또는 색. |
+| `description` | `ReactNode` |  | 제목 아래 회색 한 줄. |
+| `label` | `string` |  | title이 문자열이 아닐 때 안내 문구에 쓸 이름. |
+
+### KanbanCard
+
+기본 카드 면. Card · Stack · Inline · Text · Badge 조립.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 최대 3줄. |
+| `description` | `ReactNode` |  | 회색 두 줄 요약. |
+| `labels` | `{ label, tone? }[]` |  | 제목 위 작은 Badge. |
+| `assignees` | `string[]` |  | 담당자 이름, 오른쪽 아래 겹친 Avatar(최대 3). |
+| `due / dueTone` | `ReactNode / 'default' \| 'warning' \| 'danger'` |  | 마감일. 임박 주황 · 지남 빨강. |
+| `checklist` | `{ done, total }` |  | 체크리스트 진행. 다 하면 초록. |
+| `comments / attachments` | `number` |  | 댓글 · 첨부 수. |
+| `meta` | `ReactNode` |  | 아래 줄에 덧붙일 것. |
+| `dragging` | `boolean` |  | 끌리는 사본(raised). |
+
+### moveKanbanItem
+
+(value, id, to) => value. 보드 밖(서버 응답 · 실시간 동기화)에서 같은 규칙으로 카드를 옮길 때.
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 프로젝트 보드
+
+카드를 끌어 열 사이로 옮겨 보세요. 옮기면 "실행 취소" 토스트가 떠요(⌘/Ctrl+Z). 열 아래 "카드 추가"는 Enter로 추가하고 칸이 열린 채 남아 연달아 쓸 수 있어요. 진행 중 열은 한도 3개 — 차면 주황, 넘으면 빨강이에요. 가장자리로 끌면 보드가 스크롤돼요.
+
+```tsx
+import { useState } from 'react'
+import { MoreHorizontal } from 'lucide-react'
+import { Button, DropdownMenu, DropdownMenuItem, KanbanBoard, toast, type KanbanCardProps, type KanbanColumn, type KanbanValue } from '@iamfiro/design'
+
+type Task = KanbanCardProps & { id: string }
+
+const COLUMNS: KanbanColumn[] = [
+  { id: 'todo', title: '할 일', color: '--n6' },
+  { id: 'doing', title: '진행 중', color: '--chart-1', limit: 3 },
+  { id: 'review', title: '검토', color: '--chart-4' },
+  { id: 'done', title: '완료', color: '--success' },
+]
+
+const INITIAL: KanbanValue<Task> = {
+  todo: [
+    { id: 't1', title: '온보딩 이메일 문구 다듬기', labels: [{ label: '콘텐츠' }], assignees: ['김민지'], due: '10월 30일' },
+    {
+      id: 't2',
+      title: '요금제 페이지 비교표 추가',
+      description: '연간 결제 할인율과 팀 요금제 차이를 한눈에 보여 주기',
+      labels: [{ label: '웹', tone: 'info' }],
+      comments: 2,
+    },
+    { id: 't3', title: '접근성 감사 결과 정리', assignees: ['박서연', '이도현'], checklist: { done: 0, total: 6 } },
+  ],
+  doing: [
+    {
+      id: 'd1',
+      title: '결제 실패 재시도 로직',
+      labels: [{ label: '버그', tone: 'danger' }],
+      assignees: ['이도현'],
+      due: '오늘',
+      dueTone: 'warning',
+      checklist: { done: 3, total: 5 },
+    },
+    { id: 'd2', title: '대시보드 차트 다크 모드', labels: [{ label: '디자인', tone: 'accent' }], assignees: ['정하늘', '김민지'], attachments: 3 },
+  ],
+  review: [
+    {
+      id: 'r1',
+      title: 'Kanban 컴포넌트 docs 페이지',
+      description: '예제 4개와 API 표',
+      labels: [{ label: '디자인 시스템', tone: 'accent' }],
+      assignees: ['최유진'],
+      comments: 5,
+      checklist: { done: 4, total: 4 },
+    },
+  ],
+  done: [
+    { id: 'f1', title: '로그인 화면 리뉴얼', assignees: ['박서연'], due: '10월 21일', comments: 12 },
+    { id: 'f2', title: '알림 설정 API 연결', labels: [{ label: '백엔드', tone: 'success' }], assignees: ['이도현'] },
+  ],
+}
+
+let nextId = 1
+
+export default function Example() {
+  const [board, setBoard] = useState(INITIAL)
+
+  return (
+    <div style={{ width: '100%', height: 560 }}>
+      <KanbanBoard
+        columns={COLUMNS}
+        value={board}
+        style={{ height: '100%' }}
+        onValueChange={(next, move) => {
+          const before = board
+          setBoard(next)
+          if (move.from.columnId === move.to.columnId) return
+          const to = COLUMNS.find((c) => c.id === move.to.columnId)?.title
+          toast.undo(`‘${move.item.title}’ → ${to}`, { onUndo: () => setBoard(before) })
+        }}
+        onCardOpen={(task) => toast(`‘${task.title}’ 열기`)}
+        onCardAdd={(columnId, title) => setBoard((b) => ({ ...b, [columnId]: [...(b[columnId] ?? []), { id: `new-${nextId++}`, title }] }))}
+        columnActions={(col) => (
+          <DropdownMenu
+            align="end"
+            aria-label={`${col.title} 메뉴`}
+            trigger={<Button iconOnly variant="ghost" size="sm" icon={<MoreHorizontal />} aria-label="열 메뉴" />}
+          >
+            <DropdownMenuItem onSelect={() => setBoard((b) => ({ ...b, [col.id]: [...(b[col.id] ?? [])].reverse() }))}>순서 뒤집기</DropdownMenuItem>
+            <DropdownMenuItem
+              danger
+              onSelect={() => {
+                const before = board
+                setBoard((b) => ({ ...b, [col.id]: [] }))
+                toast.undo(`${col.title} 열을 비웠어요`, { onUndo: () => setBoard(before) })
+              }}
+            >
+              모두 지우기
+            </DropdownMenuItem>
+          </DropdownMenu>
+        )}
+      />
+    </div>
+  )
+}
+```
+
+### 옮기기 규칙 · 한도
+
+canMove가 문자열을 돌려주면 그 열 위에서 이유가 보이고, 놓으면 원래 자리로 돌아가요. limitMode='block'인 열은 한도가 차면 다른 열의 카드를 받지 않아요. 키보드로 옮길 땐 받지 않는 열을 건너뛰어요.
+
+```tsx
+import { useState } from 'react'
+import { KanbanBoard, type KanbanCardProps, type KanbanColumn, type KanbanValue } from '@iamfiro/design'
+
+type Ticket = KanbanCardProps & { id: string; blocked?: boolean }
+
+const COLUMNS: KanbanColumn[] = [
+  { id: 'backlog', title: '백로그', color: '--n6' },
+  { id: 'doing', title: '개발', color: '--chart-1', limit: 2, limitMode: 'block' },
+  { id: 'qa', title: 'QA', color: '--chart-4' },
+  { id: 'released', title: '배포됨', color: '--success', description: 'QA를 거친 카드만' },
+]
+
+const INITIAL: KanbanValue<Ticket> = {
+  backlog: [
+    { id: 'b1', title: '검색 결과 하이라이트', labels: [{ label: 'P2' }] },
+    { id: 'b2', title: '외부 API 키 교체', labels: [{ label: '막힘', tone: 'danger' }], description: '선행 작업: 비밀 저장소 이전', blocked: true },
+    { id: 'b3', title: 'CSV 내보내기 인코딩', labels: [{ label: 'P1', tone: 'warning' }] },
+  ],
+  doing: [
+    { id: 'd1', title: '세션 만료 안내', assignees: ['이도현'] },
+    { id: 'd2', title: '이미지 지연 로딩', assignees: ['정하늘'] },
+  ],
+  qa: [{ id: 'q1', title: '모바일 탭바 겹침', assignees: ['박서연'], checklist: { done: 2, total: 3 } }],
+  released: [],
+}
+
+export default function Example() {
+  const [board, setBoard] = useState(INITIAL)
+
+  return (
+    <div style={{ width: '100%', height: 440 }}>
+      <KanbanBoard
+        columns={COLUMNS}
+        value={board}
+        onValueChange={setBoard}
+        style={{ height: '100%' }}
+        columnWidth={260}
+        canMove={({ item, from, to }) => {
+          if (item.blocked && to.columnId !== 'backlog') return '선행 작업이 끝나야 시작할 수 있어요'
+          if (to.columnId === 'released' && from.columnId !== 'qa') return 'QA를 먼저 거쳐야 해요'
+          return true
+        }}
+      />
+    </div>
+  )
+}
+```
+
+### 키보드로 옮기기
+
+카드에 포커스하고 스페이스로 들어 올린 뒤 ←/→로 열, ↑/↓로 순서를 바꾸고 스페이스나 Enter로 놓아요. Esc는 원래 자리로. 들지 않았을 땐 화살표가 카드 사이를 오가고(빈 열은 건너뜀), Enter는 onCardOpen을 불러요. 단계마다 화면 읽기 프로그램에 위치를 알려 줘요.
+
+```tsx
+import { useState } from 'react'
+import { Inline, Kbd, Stack, Text, KanbanBoard, toast, type KanbanCardProps, type KanbanColumn, type KanbanValue } from '@iamfiro/design'
+
+type Idea = KanbanCardProps & { id: string }
+
+const COLUMNS: KanbanColumn[] = [
+  { id: 'idea', title: '아이디어' },
+  { id: 'plan', title: '기획' },
+  { id: 'make', title: '제작' },
+]
+
+const INITIAL: KanbanValue<Idea> = {
+  idea: [
+    { id: 'a', title: '사용자 인터뷰 질문지' },
+    { id: 'b', title: '경쟁 서비스 가입 흐름 비교' },
+  ],
+  plan: [{ id: 'c', title: '3분기 로드맵 초안' }],
+  make: [],
+}
+
+const KEYS: Array<[string, string]> = [
+  ['space', '들기 · 놓기'],
+  ['left', '앞 열'],
+  ['right', '뒤 열'],
+  ['up', '위로'],
+  ['down', '아래로'],
+  ['esc', '취소'],
+]
+
+export default function Example() {
+  const [board, setBoard] = useState(INITIAL)
+  return (
+    <Stack gap={4} style={{ width: '100%' }}>
+      <Inline gap={4}>
+        {KEYS.map(([key, label]) => (
+          <Inline key={key} gap={2}>
+            <Kbd keys={[key]} size="sm" />
+            <Text variant="caption" tone="secondary">
+              {label}
+            </Text>
+          </Inline>
+        ))}
+      </Inline>
+      <KanbanBoard
+        columns={COLUMNS}
+        value={board}
+        onValueChange={setBoard}
+        columnWidth={240}
+        onCardOpen={(item) => toast(`‘${item.title}’ 열기`)}
+        aria-label="아이디어 보드"
+      />
+    </Stack>
+  )
+}
+```
+
+### 카드 직접 그리기
+
+renderCard로 카드 면을 바꿔요. 여기선 채용 파이프라인 — Card · Avatar · Text로 조립했어요. 상태(dragging)를 받아 끌리는 사본만 raised로 띄워요.
+
+```tsx
+import { useState } from 'react'
+import { Avatar, Inline, Stack, Text, Card, CardBody, KanbanBoard, type KanbanColumn, type KanbanValue } from '@iamfiro/design'
+
+interface Candidate {
+  id: string
+  name: string
+  role: string
+  applied: string
+}
+
+const COLUMNS: KanbanColumn[] = [
+  { id: 'applied', title: '지원', color: '--chart-2' },
+  { id: 'screen', title: '서류 통과', color: '--chart-1' },
+  { id: 'interview', title: '면접', color: '--chart-4' },
+  { id: 'offer', title: '제안', color: '--success' },
+]
+
+const INITIAL: KanbanValue<Candidate> = {
+  applied: [
+    { id: 'c1', name: '김민지', role: '프로덕트 디자이너', applied: '2일 전' },
+    { id: 'c2', name: '한지우', role: '프런트엔드 엔지니어', applied: '3일 전' },
+    { id: 'c3', name: '오세훈', role: '데이터 분석가', applied: '5일 전' },
+  ],
+  screen: [{ id: 'c4', name: '이도현', role: '백엔드 엔지니어', applied: '1주 전' }],
+  interview: [{ id: 'c5', name: '박서연', role: '프로덕트 매니저', applied: '2주 전' }],
+  offer: [],
+}
+
+export default function Example() {
+  const [board, setBoard] = useState(INITIAL)
+  return (
+    <div style={{ width: '100%' }}>
+      <KanbanBoard
+        columns={COLUMNS}
+        value={board}
+        onValueChange={setBoard}
+        columnWidth={232}
+        getItemLabel={(c) => c.name}
+        emptyLabel="아직 없어요"
+        aria-label="채용 파이프라인"
+        renderCard={(c, { dragging }) => (
+          <Card variant={dragging ? 'raised' : 'default'} padding="sm">
+            <CardBody>
+              <Inline gap={3} wrap={false}>
+                <Avatar name={c.name} size={32} tooltip={false} />
+                <Stack gap={0} style={{ minWidth: 0 }}>
+                  <Text variant="label-md" weight="medium" truncate>
+                    {c.name}
+                  </Text>
+                  <Text variant="caption" tone="tertiary" truncate>
+                    {c.role} · {c.applied}
+                  </Text>
+                </Stack>
+              </Inline>
+            </CardBody>
+          </Card>
+        )}
+      />
+    </div>
+  )
+}
+```