@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/color-picker/AGENTS.md

@@ -0,0 +1,224 @@
+# ColorPicker
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+색을 고르는 패널. 채도·밝기 영역과 색상 · 불투명도 슬라이더를 끌거나 화살표 키로 움직이고, HEX · RGB · HSL 값을 직접 입력해요. 프리셋, 최근 사용한 색, 화면 스포이트(지원 브라우저), 값 복사가 함께 있어요. 끄는 동안은 미리보기(onValueChange), 놓을 때 확정(onValueCommit)이고 끄는 중 Esc는 원래 색으로 돌아가요. 입력칸처럼 생긴 트리거가 필요하면 ColorField.
+
+```tsx
+import { ColorField, ColorPicker, CHART_COLOR_PRESETS } from '@iamfiro/design'
+```
+
+## API
+
+### ColorPicker
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `string` |  | 값(제어). #rrggbb, alpha가 있고 반투명이면 #rrggbbaa(소문자). |
+| `defaultValue` | `string` | `'#3b82f6'` | 처음 값(비제어). |
+| `onValueChange` | `(value: string) => void` |  | 끄는 동안·입력 중 매번 호출(미리보기). |
+| `onValueCommit` | `(value: string) => void` |  | 놓을 때, 키 한 번, Enter·칸 벗어남, 스와치·스포이트 선택 때 한 번 호출(확정). Esc로 취소하면 호출되지 않아요. |
+| `alpha` | `boolean` | `false` | 불투명도 슬라이더와 A 칸. |
+| `format / defaultFormat` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | 입력칸과 복사에 쓰는 형식. onFormatChange로 받아요. |
+| `presets` | `Array<string \| { color: string; label?: string }>` |  | 프리셋 스와치. CSS 색이나 토큰 이름(--chart-1). CHART_COLOR_PRESETS가 준비돼 있어요. |
+| `presetsLabel` | `ReactNode` | `'기본 색'` | 프리셋 줄 제목. |
+| `recentColors / defaultRecentColors` | `string[]` |  | 최근 사용한 색. 바꾼 뒤 포커스가 피커를 벗어나면 맨 앞에 추가돼요(onRecentColorsChange). |
+| `maxRecent` | `number` | `8` | 최근 색 최대 개수. |
+| `showRecent` | `boolean` | `true` | 최근 사용 줄을 보일지. |
+| `eyeDropper` | `boolean` | `true` | EyeDropper API가 있는 브라우저에서만 스포이트 버튼을 보여요. |
+| `copyable` | `boolean` | `true` | 현재 형식의 값을 복사하는 버튼. |
+| `disabled` | `boolean` |  | 비활성. |
+| `aria-label` | `string` | `'색 선택'` | 피커 그룹 이름. |
+
+### ColorField
+
+ColorPicker의 props를 모두 받고, 아래가 더해져요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 입력칸 높이 36 / 44 / 52. |
+| `open / defaultOpen` | `boolean` |  | 팝오버 열림(onOpenChange). |
+| `invalid` | `boolean` |  | 오류 테두리. |
+| `popoverWidth` | `number` | `264` | 팝오버 폭(px). |
+| `name` | `string` |  | 폼 제출용 hidden input 이름. |
+| `aria-label` | `string` | `'색'` | 트리거 이름. 화면 읽기에는 "이름: 값"으로 읽혀요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+영역은 가로 = 채도, 세로 = 밝기. 화살표 키로 1%씩, Shift를 누르면 10%씩 움직여요. presets에 토큰 이름(--chart-1)을 주면 현재 테마의 실제 색으로 풀어서 써요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, CHART_COLOR_PRESETS, Card, ColorPicker } from '@iamfiro/design'
+
+export default function Example() {
+  const [color, setColor] = useState('#4a6cf7')
+  return (
+    <Stack gap={3} style={{ width: 264 }}>
+      <Card variant="raised" padding="sm">
+        <ColorPicker value={color} onValueChange={setColor} presets={CHART_COLOR_PRESETS} aria-label="차트 색" />
+      </Card>
+      <Text variant="body-sm" tone="secondary" numeric>
+        선택한 색 {color}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 입력칸 트리거 (ColorField)
+
+색 칩 + 값이 보이는 입력칸 모양 트리거. 누르면 팝오버로 피커가 열리고 첫 포커스는 영역 손잡이에 가요. 바꾼 뒤 닫으면 그 색이 "최근 사용"에 쌓여요.
+
+```tsx
+import { Field, Stack, CHART_COLOR_PRESETS, ColorField } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: 280 }}>
+      <Field label="라벨 색" htmlFor="label-color">
+        <ColorField id="label-color" defaultValue="#2bb39b" presets={CHART_COLOR_PRESETS} aria-label="라벨 색" />
+      </Field>
+      <Field label="워크스페이스 강조색" htmlFor="brand-color">
+        <ColorField
+          id="brand-color"
+          defaultValue="#e5488f"
+          defaultRecentColors={['#9b5cf6', '#f08a2a', '#1f1f1f']}
+          presets={CHART_COLOR_PRESETS}
+          aria-label="워크스페이스 강조색"
+        />
+      </Field>
+    </Stack>
+  )
+}
+```
+
+### 불투명도
+
+alpha를 켜면 체커보드 위 불투명도 슬라이더와 A 칸이 생기고, 값은 반투명일 때만 #rrggbbaa가 돼요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, Card, ColorPicker } from '@iamfiro/design'
+
+export default function Example() {
+  const [overlay, setOverlay] = useState('#1f1f1f80')
+  return (
+    <Stack gap={3} style={{ width: 264 }}>
+      <Card variant="raised" padding="sm">
+        <ColorPicker
+          alpha
+          value={overlay}
+          onValueChange={setOverlay}
+          presets={[
+            { color: '#1f1f1f80', label: '어두운 오버레이' },
+            { color: '#ffffffcc', label: '밝은 오버레이' },
+            { color: '#3b82f633', label: '선택 영역' },
+            { color: '#d1393f26', label: '오류 배경' },
+          ]}
+          presetsLabel="오버레이 프리셋"
+          aria-label="오버레이 색"
+        />
+      </Card>
+      <Text variant="body-sm" tone="secondary" numeric>
+        오버레이 {overlay}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### HEX · RGB · HSL 입력
+
+형식을 바꾸면 칸이 나뉘어요. 맞는 값을 입력하는 즉시 미리보기되고, Enter나 칸을 벗어날 때 확정돼요. 틀린 값은 빨갛게 표시되고 벗어나면 마지막 올바른 값으로 돌아가요. 입력 중 Esc는 입력 전 색으로 되돌려요.
+
+```tsx
+import { useState } from 'react'
+import { Stack, Text, Card, ColorPicker, type ColorFormat } from '@iamfiro/design'
+
+const NAMES: Record<ColorFormat, string> = { hex: 'HEX', rgb: 'RGB', hsl: 'HSL' }
+
+export default function Example() {
+  const [format, setFormat] = useState<ColorFormat>('rgb')
+  return (
+    <Stack gap={3} style={{ width: 264 }}>
+      <Card variant="raised" padding="sm">
+        <ColorPicker defaultValue="#2bb39b" format={format} onFormatChange={setFormat} showRecent={false} aria-label="테마 색" />
+      </Card>
+      <Text variant="body-sm" tone="secondary">
+        {NAMES[format]} 형식으로 입력하고 복사해요. 칸에 300처럼 범위를 벗어난 값을 넣어 보세요.
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 미리보기와 확정
+
+저장·서버 요청은 onValueCommit에서. 끄는 중에 Esc를 누르면 미리보기가 취소되고 아무것도 확정되지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { Inline, Stack, Text, Card, ColorPicker, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [preview, setPreview] = useState('#9b5cf6')
+  const [saved, setSaved] = useState('#9b5cf6')
+  return (
+    <Stack gap={3} style={{ width: 264 }}>
+      <Card variant="raised" padding="sm">
+        <ColorPicker
+          value={preview}
+          onValueChange={setPreview}
+          onValueCommit={(c) => {
+            setSaved(c)
+            toast.success('프로젝트 색을 저장했어요', { description: c })
+          }}
+          copyable={false}
+          showRecent={false}
+          aria-label="프로젝트 색"
+        />
+      </Card>
+      <Inline justify="between">
+        <Text variant="body-sm" tone="secondary" numeric>
+          미리보기 {preview}
+        </Text>
+        <Text variant="body-sm" weight="semibold" numeric>
+          저장됨 {saved}
+        </Text>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 크기와 상태
+
+ColorField size sm / md / lg, invalid, disabled.
+
+```tsx
+import { Field, Stack, ColorField } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: 280 }}>
+      <Field label="작게 (sm)">
+        <ColorField size="sm" defaultValue="#f08a2a" aria-label="경고 색" />
+      </Field>
+      <Field label="크게 (lg) · RGB 표시">
+        <ColorField size="lg" defaultValue="#4a6cf7" defaultFormat="rgb" aria-label="링크 색" />
+      </Field>
+      <Field label="오류" hint="배경과 대비가 너무 낮아요" invalid>
+        <ColorField invalid defaultValue="#f5f5f5" aria-label="글자 색" />
+      </Field>
+      <Field label="비활성">
+        <ColorField disabled defaultValue="#9a9a9a" aria-label="비활성 색" />
+      </Field>
+    </Stack>
+  )
+}
+```

package/agents/colors/AGENTS.md

@@ -0,0 +1,168 @@
+# Colors
+
+> 파운데이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+모든 색은 tokens.css의 CSS 변수로만 써요. 배경은 흰색, 회색은 칩·트랙 같은 작은 채움에만, 강조색은 파랑 하나예요. 기본 액션은 거의 검정이고, 상태는 진한 색 대신 -soft 배경 + 색 글자로 보여줘요. 다크 테마는 [data-theme="dark"]에서 같은 이름에 다른 값을 넣어요.
+
+```tsx
+import { Swatch } from '@iamfiro/design'
+```
+
+## API
+
+### Swatch
+
+토큰 문서용 색 칩. 토큰 이름과 실제 계산된 값을 함께 보여줘요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `color` (필수) | `string` |  | CSS 변수 이름('--accent') 또는 아무 CSS 색. |
+| `name` | `string` |  | 표시할 이름. 생략하면 color 값. |
+| `showValue` | `boolean` | `true` | 이름 아래에 계산된 값(hex 등)을 표시. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 뉴트럴 램프
+
+--n0(가장 밝음)부터 --n12(가장 진한 글자)까지. 컴포넌트에서는 직접 쓰기보다 아래의 의미 토큰을 거쳐 써요.
+
+```tsx
+import { Swatch } from '@iamfiro/design'
+
+const NEUTRALS = Array.from({ length: 13 }, (_, i) => `--n${i}`)
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(88px, 1fr))', gap: 16 }}>
+      {NEUTRALS.map((token) => (
+        <Swatch key={token} color={token} />
+      ))}
+    </div>
+  )
+}
+```
+
+### 표면 · 글자 · 선
+
+역할로 이름 붙인 토큰. 회색 채움은 --surface-active(기본)와 --surface-hover(마우스 오버)만 써요.
+
+```tsx
+import { Swatch, Text } from '@iamfiro/design'
+
+const GROUPS = [
+  { title: '표면', tokens: ['--bg', '--surface', '--surface-raised', '--surface-sunken', '--surface-hover', '--surface-active', '--overlay'] },
+  { title: '글자', tokens: ['--text', '--text-2', '--text-3', '--text-inverse'] },
+  { title: '선', tokens: ['--line', '--line-strong', '--line-focus'] },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', display: 'grid', gap: 32 }}>
+      {GROUPS.map((group) => (
+        <section key={group.title} style={{ display: 'grid', gap: 12 }}>
+          <Text as="h4" variant="overline" tone="tertiary">
+            {group.title}
+          </Text>
+          <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))', gap: 16 }}>
+            {group.tokens.map((token) => (
+              <Swatch key={token} color={token} />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  )
+}
+```
+
+### 브랜드 · 상태
+
+강조색과 상태색. 배경은 -soft, 글자는 진한 색으로 짝지어 써요. Badge 톤이 이 짝을 그대로 사용해요.
+
+```tsx
+import { Badge, Swatch, Text, type Tone } from '@iamfiro/design'
+
+const FAMILIES: Array<{ tone: Tone; label: string; tokens: string[] }> = [
+  { tone: 'accent', label: '강조', tokens: ['--accent', '--accent-strong', '--accent-soft', '--accent-text'] },
+  { tone: 'success', label: '성공', tokens: ['--success', '--success-soft'] },
+  { tone: 'warning', label: '경고', tokens: ['--warning', '--warning-soft'] },
+  { tone: 'danger', label: '위험', tokens: ['--danger', '--danger-soft'] },
+  { tone: 'info', label: '정보', tokens: ['--info', '--info-soft'] },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', display: 'grid', gap: 28 }}>
+      {FAMILIES.map((family) => (
+        <section key={family.tone} style={{ display: 'grid', gridTemplateColumns: '96px 1fr', alignItems: 'start', gap: 16 }}>
+          <div style={{ display: 'grid', gap: 8, justifyItems: 'start' }}>
+            <Text variant="label-md">{family.label}</Text>
+            <Badge tone={family.tone} dot>
+              {family.tone}
+            </Badge>
+          </div>
+          <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))', gap: 16 }}>
+            {family.tokens.map((token) => (
+              <Swatch key={token} color={token} />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  )
+}
+```
+
+### 차트
+
+--chart-1부터 순서대로 시리즈에 배정해요. 그리드 선은 --chart-grid로 아주 옅게, 축 글자는 --chart-axis로 써요. 한 수량을 나눈 조각(나눠진 Progress)은 진한 파랑부터 옅어지는 --chart-seq-1…5를 써요.
+
+```tsx
+import { Swatch } from '@iamfiro/design'
+
+const TOKENS = ['--chart-1', '--chart-2', '--chart-3', '--chart-4', '--chart-5', '--chart-6', '--chart-grid', '--chart-axis', '--chart-seq-1', '--chart-seq-2', '--chart-seq-3', '--chart-seq-4', '--chart-seq-5']
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))', gap: 16 }}>
+      {TOKENS.map((token) => (
+        <Swatch key={token} color={token} />
+      ))}
+    </div>
+  )
+}
+```
+
+### 액션
+
+primary는 거의 검정 단색, secondary는 흰 바탕 + 옅은 윤곽. 버튼이 이 토큰만 읽어요.
+
+```tsx
+import { Button, Swatch, type ButtonVariant } from '@iamfiro/design'
+
+const ACTIONS: Array<{ variant: ButtonVariant; label: string; tokens: string[] }> = [
+  { variant: 'primary', label: '변경사항 저장', tokens: ['--primary', '--primary-hover', '--primary-text'] },
+  { variant: 'secondary', label: '취소', tokens: ['--secondary', '--secondary-hover', '--secondary-border'] },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', display: 'grid', gap: 28 }}>
+      {ACTIONS.map((action) => (
+        <section key={action.variant} style={{ display: 'grid', gridTemplateColumns: '120px 1fr', alignItems: 'center', gap: 16 }}>
+          <div>
+            <Button variant={action.variant}>{action.label}</Button>
+          </div>
+          <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))', gap: 16 }}>
+            {action.tokens.map((token) => (
+              <Swatch key={token} color={token} />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  )
+}
+```

package/agents/combobox/AGENTS.md

@@ -0,0 +1,218 @@
+# Combobox
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+입력하면서 검색해 고르는 셀렉트. 이름과 keywords를 띄어쓰기·대소문자 상관없이 찾고, 일치한 부분은 굵게 보여줘요. multiple이면 고른 항목이 태그로 쌓이고, onCreate로 없는 항목을 바로 추가할 수 있어요. 선택지 형태(ListOption)는 Select 페이지를 참고하세요.
+
+```tsx
+import { Combobox, type ListOption } from '@iamfiro/design'
+```
+
+## API
+
+### Combobox
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `options` (필수) | `ListOption<V>[]` |  | 선택지 목록. ListOption은 Select 페이지 참고. |
+| `multiple` | `boolean` | `false` | 여러 개 선택. value 타입이 V[]로 바뀌어요. |
+| `value` | `V \| null  ·  V[] (multiple)` |  | 선택된 값(제어). |
+| `defaultValue` | `V \| null  ·  V[] (multiple)` |  | 처음 선택값(비제어). |
+| `onValueChange` | `(value: V \| null) => void  ·  (value: V[]) => void` |  | 값이 바뀔 때. |
+| `inputValue / onInputChange` | `string / (text) => void` |  | 검색어를 밖에서 제어할 때(서버 검색 등). |
+| `filter` | `(option, query) => boolean` | `defaultComboboxFilter` | 일치 규칙. 기본은 label + keywords, 대소문자·띄어쓰기 무시. |
+| `onCreate` | `(query: string) => void` |  | 있으면 일치하는 항목이 없을 때 추가 행을 보여줘요. |
+| `createLabel` | `(query: string) => ReactNode` | `‘query’ 추가` | 추가 행 문구. |
+| `emptyText` | `ReactNode` | `'결과가 없어요'` | 검색 결과가 없을 때 문구. |
+| `highlight` | `boolean` | `true` | 일치한 부분을 굵게. |
+| `renderOption` | `(option, state & { query }) => ReactNode` |  | 목록 행을 직접 그릴 때. 검색어도 함께 받아요. |
+| `placeholder` | `string` | `'검색해서 선택'` | 입력 전 문구. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `invalid` | `boolean` |  | 오류 표시. |
+| `disabled` | `boolean` |  | 비활성. |
+| `leading` | `ReactNode` |  | 입력창 앞 아이콘. |
+| `maxHeight` | `number` | `300` | 팝오버 최대 높이. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+keywords에 넣은 단어(영문 이름 등)로도 검색돼요. ↑↓로 이동, Enter로 선택, Esc로 닫기. 한글 조합 중에는 키 입력을 기다려요.
+
+```tsx
+import { useState } from 'react'
+import { Avatar, Field, Combobox, type ListOption } from '@iamfiro/design'
+
+const PEOPLE: ListOption[] = [
+  { value: 'minji', label: '김민지', description: '디자인', keywords: ['minji kim'] },
+  { value: 'dohyun', label: '이도현', description: '프론트엔드', keywords: ['dohyun lee'] },
+  { value: 'seoyeon', label: '최서연', description: '백엔드', keywords: ['seoyeon choi'] },
+  { value: 'woojin', label: '정우진', description: '프로덕트', keywords: ['woojin jung'] },
+  { value: 'jisu', label: '한지수', description: '데이터', keywords: ['jisu han'] },
+  { value: 'yuna', label: '박유나', description: '디자인', keywords: ['yuna park'] },
+].map((person) => ({ ...person, icon: <Avatar name={person.label} size={22} /> }))
+
+export default function Example() {
+  const [owner, setOwner] = useState<string | null>('minji')
+  return (
+    <div style={{ width: 320 }}>
+      <Field label="담당자" htmlFor="owner">
+        <Combobox id="owner" options={PEOPLE} value={owner} onValueChange={setOwner} placeholder="이름 또는 영문으로 검색" />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 여러 개 선택
+
+multiple이면 목록이 열린 채로 유지되고, 검색어가 비어 있을 때 Backspace는 마지막 태그를 지워요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Combobox, type ListOption } from '@iamfiro/design'
+
+const SKILLS: ListOption[] = [
+  { value: 'react', label: 'React', keywords: ['리액트'] },
+  { value: 'typescript', label: 'TypeScript', keywords: ['타입스크립트', 'ts'] },
+  { value: 'node', label: 'Node.js', keywords: ['노드'] },
+  { value: 'figma', label: 'Figma', keywords: ['피그마'] },
+  { value: 'python', label: 'Python', keywords: ['파이썬'] },
+  { value: 'sql', label: 'SQL', keywords: ['데이터베이스'] },
+]
+
+export default function Example() {
+  const [skills, setSkills] = useState<string[]>(['react', 'typescript'])
+  return (
+    <div style={{ width: 360 }}>
+      <Field label="보유 기술" htmlFor="skills">
+        <Combobox id="skills" multiple options={SKILLS} value={skills} onValueChange={setSkills} placeholder="기술 검색" />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 새 항목 추가
+
+정확히 일치하는 항목이 없으면 맨 아래에 추가 행이 생겨요. onCreate에서 options에 넣고 선택까지 직접 해주세요. 문구는 createLabel로 바꿔요.
+
+```tsx
+import { useState } from 'react'
+import { Field, Combobox, type ListOption } from '@iamfiro/design'
+
+export default function Example() {
+  const [labels, setLabels] = useState<ListOption[]>([
+    { value: 'bug', label: '버그' },
+    { value: 'feature', label: '기능 요청' },
+    { value: 'design', label: '디자인' },
+    { value: 'infra', label: '인프라' },
+    { value: 'docs', label: '문서' },
+  ])
+  const [picked, setPicked] = useState<string[]>(['bug'])
+
+  const createLabel = (label: string) => {
+    const value = `label-${Date.now()}`
+    setLabels((list) => [...list, { value, label }])
+    setPicked((list) => [...list, value])
+  }
+
+  return (
+    <div style={{ width: 360 }}>
+      <Field label="라벨" htmlFor="issue-labels">
+        <Combobox
+          id="issue-labels"
+          multiple
+          options={labels}
+          value={picked}
+          onValueChange={setPicked}
+          onCreate={createLabel}
+          createLabel={(query) => `새 라벨 ‘${query}’ 만들기`}
+          placeholder="라벨 검색 또는 추가"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 검색 방식 바꾸기
+
+filter로 일치 규칙을 직접 정해요. 기본 규칙(defaultComboboxFilter)과 함께 쓰면 기존 검색도 그대로 유지돼요.
+
+```tsx
+import { Field, Combobox, defaultComboboxFilter, type ListOption } from '@iamfiro/design'
+
+const CITIES: ListOption[] = [
+  { value: 'seoul', label: '서울' },
+  { value: 'busan', label: '부산' },
+  { value: 'incheon', label: '인천' },
+  { value: 'daegu', label: '대구' },
+  { value: 'daejeon', label: '대전' },
+  { value: 'gwangju', label: '광주' },
+  { value: 'ulsan', label: '울산' },
+  { value: 'jeju', label: '제주' },
+]
+
+const CHOSEONG = 'ㄱㄲㄴㄷㄸㄹㅁㅂㅃㅅㅆㅇㅈㅉㅊㅋㅌㅍㅎ'
+
+// '서울' → 'ㅅㅇ'
+const toChoseong = (text: string) =>
+  [...text]
+    .map((ch) => {
+      const code = ch.charCodeAt(0) - 0xac00
+      return code >= 0 && code < 11172 ? CHOSEONG[Math.floor(code / 588)] : ch
+    })
+    .join('')
+
+// 초성이 맞으면 통과('ㄷㄱ' → 대구), 아니면 기본 검색(이름 · keywords)으로
+const matchChoseong = (option: ListOption, query: string) =>
+  toChoseong(option.label).includes(query) || defaultComboboxFilter(option, query)
+
+export default function Example() {
+  return (
+    <div style={{ width: 300 }}>
+      <Field label="도시" hint="초성으로도 찾을 수 있어요. 예: ㄷㄱ" htmlFor="city">
+        <Combobox id="city" options={CITIES} filter={matchChoseong} emptyText="일치하는 도시가 없어요" placeholder="도시 검색" />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 크기와 상태
+
+size, leading 아이콘, highlight 끄기, invalid, disabled.
+
+```tsx
+import { Search } from 'lucide-react'
+import { Field, Combobox, type ListOption } from '@iamfiro/design'
+
+const TEAMS: ListOption[] = [
+  { value: 'design', label: '디자인팀' },
+  { value: 'frontend', label: '프론트엔드팀' },
+  { value: 'backend', label: '백엔드팀' },
+  { value: 'data', label: '데이터팀' },
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 240px)', gap: 16 }}>
+      <Field label="작게 (sm) · 아이콘" htmlFor="team-sm">
+        <Combobox id="team-sm" size="sm" options={TEAMS} leading={<Search />} placeholder="팀 검색" />
+      </Field>
+      <Field label="강조 끄기 (highlight)" htmlFor="team-plain">
+        <Combobox id="team-plain" options={TEAMS} highlight={false} placeholder="팀 검색" />
+      </Field>
+      <Field label="오류" invalid hint="팀을 선택해 주세요." htmlFor="team-err">
+        <Combobox id="team-err" options={TEAMS} invalid placeholder="팀 검색" />
+      </Field>
+      <Field label="비활성" htmlFor="team-off">
+        <Combobox id="team-off" options={TEAMS} defaultValue="design" disabled />
+      </Field>
+    </div>
+  )
+}
+```