@design-ai/cli 4.55.0

package/examples/component-carousel.md

@@ -0,0 +1,266 @@
+# `Carousel` — spec
+
+> Citing Ant Design `Carousel`, MUI (no built-in — composition), shadcn-ui `carousel` (Embla)
+
+## Purpose
+
+A horizontally rotating sequence of items. Used for: hero banners (marketing), product image galleries, onboarding screens, content highlights.
+
+## When NOT to use a carousel
+
+This is the most-misused component on the web. Before reaching for a carousel, ask:
+- **"Will users actually scroll past slide 1?"** — Most don't. Average click-through on slide 2+ is < 5%.
+- **"Is the content equally important?"** — If slide 1 is the priority, kill the carousel; commit to one hero.
+- **"Is this auto-playing?"** — Auto-play hurts a11y, distracts users, and is widely disliked.
+
+Use a carousel when:
+- It's a genuine gallery (e.g., product photos — user expects multiple).
+- Content is browsable (testimonials, news highlights — equally weighted).
+- Touch swipe is the intended interaction model (mobile native pattern).
+
+Don't use for:
+- Hero banner where one message is the goal (use a single hero).
+- Long-form content (use a list or scroll).
+- Critical conversion elements (most users miss them past slide 1).
+
+## Anatomy
+
+```
+       ◀  ┌──────────────────────────────────────┐  ▶
+          │                                       │
+          │           Slide 1 of 4                │
+          │                                       │
+          │                                       │
+          └──────────────────────────────────────┘
+                ●  ○  ○  ○      ← dot indicators
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Slide content | yes | The items |
+| Previous arrow | usually (desktop) | Hidden on mobile (rely on swipe) |
+| Next arrow | usually (desktop) | |
+| Indicators (dots / numbers / thumbs) | yes for > 1 slide | Shows position + count |
+| Auto-play controls | only if auto-playing | Pause/play button required |
+
+## API
+
+```tsx
+<Carousel
+  autoplay={false}
+  loop
+  showArrows
+  showDots
+  onSlideChange={setActive}
+>
+  <Carousel.Slide>{slide1}</Carousel.Slide>
+  <Carousel.Slide>{slide2}</Carousel.Slide>
+  <Carousel.Slide>{slide3}</Carousel.Slide>
+</Carousel>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | Auto-advance |
+| `autoplayInterval` | `number` | `5000` | ms between slides |
+| `loop` | `boolean` | `true` | Wrap from last to first |
+| `showArrows` | `boolean` | `true` (desktop) / `false` (mobile) | Prev/next buttons |
+| `showDots` | `boolean` | `true` | Dot indicators |
+| `dotsPosition` | `"bottom" \| "top" \| "side"` | `"bottom"` | |
+| `slidesPerView` | `number` | `1` | Multi-slide view (e.g., 3 product cards visible) |
+| `slidesPerScroll` | `number` | `1` | How many to advance per click |
+| `gap` | `number` | `0` | Space between slides (when slidesPerView > 1) |
+| `swipeable` | `boolean` | `true` (touch) | Touch/drag swipe |
+| `effect` | `"slide" \| "fade"` | `"slide"` | Transition |
+| `value` | `number` | — | Controlled active index |
+| `onSlideChange` | `(index) => void` | — | |
+
+## Behavior
+
+### Navigation
+
+- **Arrows** (desktop): click to advance one slide.
+- **Dots**: click any dot to jump to that slide.
+- **Swipe** (touch): horizontal swipe past 50% of slide width advances.
+- **Keyboard**: `←` / `→` when carousel is focused.
+- **Auto-play** (if enabled): advances every `autoplayInterval` ms; pauses on hover or focus inside; resumes on leave.
+
+### Loop vs no loop
+
+- `loop: true`: clicking next on last slide goes to first; previous on first goes to last.
+- `loop: false`: arrows disabled at boundary. Last slide visually marks "end".
+
+### Multi-slide view
+
+For browse-style carousels (product cards):
+
+```
+slidesPerView: 3
+[card 1] [card 2] [card 3] [card 4 (off-screen)] [card 5 (off-screen)]
+```
+
+Click next: scrolls by `slidesPerScroll` (often 1 for incremental browsing, full = slidesPerView for "page" navigation).
+
+## Sizes
+
+Carousel container takes its parent's dimensions. The slide aspect ratio depends on content:
+
+| Use | Aspect ratio (desktop) |
+| --- | --- |
+| Hero banner | 16:9 or 21:9 wide |
+| Product gallery | 1:1 (square) |
+| Testimonial cards | 4:3 or 5:3 |
+| Mobile portrait | 4:5 or 9:16 |
+
+For responsive: `aspect-ratio: 16 / 9` and `width: 100%` lets it scale.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Settled | Slide visible, indicator highlighted |
+| Sliding | 250–400ms transition (slide or fade) |
+| Auto-advance pause | When user hovers, focuses, or `prefers-reduced-motion` is set |
+| Loading slides (lazy) | Skeleton in slide area until image loads |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-text-primary
+--color-text-on-image          (text overlay on image carousels)
+--color-bg-overlay              (subtle overlay for text legibility)
+--color-primary-default         (active dot)
+--color-text-tertiary           (inactive dots)
+--space-md
+--radius-md, --radius-lg        (rounded slide corners)
+--motion-default, --motion-slow  (slide transitions)
+--easing-out
+```
+
+## Accessibility — high stakes
+
+Carousels are notorious for a11y problems. Get these right.
+
+### ARIA
+
+- `role="region" aria-roledescription="carousel" aria-label="..."` on the container.
+- Each slide: `role="group" aria-roledescription="slide" aria-label="Slide N of M"`.
+- Hidden slides should have `aria-hidden="true"` and `tabindex="-1"` on focusable elements (so tab doesn't reach off-screen content).
+- Live region: `aria-live="polite"` on the slide container — but only when **not auto-playing** (auto-play would chatter). Set `aria-live="off"` while auto-playing.
+
+### Auto-play
+
+- **Don't auto-play by default**. WCAG 2.2.2 requires controls for moving content > 5 seconds.
+- If auto-playing: provide visible Pause/Play button.
+- Pause on hover, focus, and **`prefers-reduced-motion`** — these are not optional.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach carousel (arrows + dots are tab stops) |
+| `←` / `→` | Move slide (when carousel is focused) |
+| Inside slide: `Tab` reaches links/buttons in the visible slide only |
+
+### Touch
+
+Swipe is a touch convention. For accessibility, ensure arrows are visible OR a clear alternative exists.
+
+## Code example
+
+```tsx
+// Hero banner (no auto-play, single slide visible)
+<Carousel showArrows showDots loop>
+  {banners.map(banner => (
+    <Carousel.Slide key={banner.id}>
+      <BannerSlide banner={banner} />
+    </Carousel.Slide>
+  ))}
+</Carousel>
+
+// Product gallery (multi-slide, no auto-play, no loop)
+<Carousel
+  slidesPerView={4}
+  slidesPerScroll={1}
+  gap={16}
+  loop={false}
+  showArrows
+  showDots={false}
+>
+  {products.map(product => (
+    <Carousel.Slide key={product.id}>
+      <ProductCard product={product} />
+    </Carousel.Slide>
+  ))}
+</Carousel>
+
+// Testimonials with auto-play (carefully)
+<Carousel
+  autoplay
+  autoplayInterval={6000}
+  loop
+  showDots
+  showArrows
+  effect="fade"
+>
+  {testimonials.map(t => (
+    <Carousel.Slide key={t.id}>
+      <TestimonialCard testimonial={t} />
+    </Carousel.Slide>
+  ))}
+</Carousel>
+
+// Image gallery on a product detail page
+<Carousel slidesPerView={1} loop showDots>
+  {product.images.map(img => (
+    <Carousel.Slide key={img.id}>
+      <Image src={img.url} alt={img.alt} />
+    </Carousel.Slide>
+  ))}
+</Carousel>
+```
+
+## Mobile-specific behaviors
+
+- Arrows hidden by default (rely on swipe).
+- Dots smaller (4–6px).
+- Snap to slide (`scroll-snap-type: x mandatory`).
+- Don't auto-play on mobile — wastes battery, reduces user agency.
+
+## Edge cases
+
+- **Single slide**: don't render arrows/dots. Just the slide.
+- **Loading slides** (async): render skeleton until image loads. Don't block carousel rendering.
+- **Different slide heights**: cap with `align-items: center` or set fixed height. Inconsistent heights cause carousel to "jump".
+- **Long text in slides** (testimonials): cap height and add `overflow: scroll` per slide if needed.
+- **Auto-play with focus inside**: pause until focus leaves.
+- **RTL**: arrow icons flip; swipe direction inverts.
+- **No JS / SSR**: render as a horizontal scroll list with snap points. Carousel chrome is enhancement.
+
+## Don't
+
+- Don't auto-play by default.
+- Don't use carousel for primary CTAs (most users miss slide 2+).
+- Don't combine fade and slide effects in the same carousel.
+- Don't show 3+ rows of carousels on one page (visual chaos).
+- Don't disable the user's swipe direction (force them to use arrows). Touch users expect swipe.
+- Don't make dots invisible on dark slides — ensure 3:1 contrast.
+- Don't put videos in auto-playing carousels — accessibility nightmare.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/carousel/`](../refs/ant-design/components/carousel/) — `Carousel`. Wraps `react-slick`. Has `autoplay`, `dots`, `effect`. Solid baseline.
+- MUI: no dedicated component. Use `react-slick` or `swiper`.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/carousel.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/carousel.tsx) — wraps **Embla** carousel. Modern, framework-agnostic, excellent accessibility. **Default for new projects.**
+
+API choices made:
+- **`autoplay: false` default**: matches a11y best practice. Most carousels don't need it.
+- **`slidesPerView` exposed**: covers product gallery use case without separate component.
+- **`effect`**: fade for hero (each slide is the message), slide for sequential browsing.
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — auto-play + reduced motion
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — carousel keyboard contract
+- [WAI-ARIA Carousel Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/)

package/examples/component-cascader.md

@@ -0,0 +1,135 @@
+# `Cascader` — spec
+
+> Citing Ant Design `Cascader`, MUI (no built-in — composition), shadcn-ui (no built-in)
+
+## Purpose
+
+Multi-level select. User picks a leaf value by drilling through hierarchical levels. Used for: address (state → city → district), category trees (electronics → phones → models), org structure.
+
+## When Cascader vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **Cascader** | Hierarchical with 2–4 fixed levels; user picks ONE leaf |
+| **Tree (with select)** | Variable depth, user might pick any node |
+| **Cascader → drill-in screens** | Mobile, when each level needs more space |
+| **Three Selects in a row** | When levels are independent (e.g., size, color, material — pick all three) |
+
+## Anatomy
+
+```
+Trigger:                          Open (3-level cascade):
+┌──────────────────────┐         ┌──────┬──────┬──────┐
+│ 서울 / 강남구 / 역삼동  ▾│         │ 서울  │ 강남구│ 역삼동│
+└──────────────────────┘         │ 부산  │ 서초구│ 청담동│
+                                  │ 인천  │ 송파구│ 삼성동│
+                                  └──────┴──────┴──────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Trigger | yes | Shows full path or placeholder |
+| Per-level panel | yes | Each level renders its options |
+| Hover/click expand | yes | Hovering a parent expands its children |
+| Search input | optional | Searches across all levels |
+
+## API
+
+```tsx
+<Cascader
+  value={["seoul", "gangnam", "yeoksam"]}
+  onValueChange={setValue}
+  options={addressTree}
+  separator=" / "
+  searchable
+/>
+
+// where addressTree is:
+type CascaderOption = {
+  value: string;
+  label: string;
+  children?: CascaderOption[];
+  disabled?: boolean;
+  isLeaf?: boolean;
+};
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string[]` | — | Path to selected leaf (level values in order) |
+| `onValueChange` | `(value: string[], path: CascaderOption[]) => void` | — | |
+| `options` | `CascaderOption[]` | — | Hierarchical data |
+| `separator` | `string` | `" / "` | Display separator in trigger |
+| `placeholder` | `string` | — | When empty |
+| `searchable` | `boolean` | `false` | Cross-level search |
+| `expandTrigger` | `"click" \| "hover"` | `"click"` | How to expand levels |
+| `changeOnSelect` | `boolean` | `false` | Allow selection at non-leaf levels |
+| `showFullPath` | `boolean` | `true` | In trigger: full path vs leaf-only |
+| `loadData` | `(option) => Promise<CascaderOption[]>` | — | Async lazy-load children |
+| `disabled` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | |
+
+## Behavior
+
+- **Click a parent**: expands children to its right.
+- **Click a leaf**: selects, closes popover.
+- **`changeOnSelect`**: allows selecting at any level. Triggers `onValueChange` on every click.
+- **Search mode**: input at top of popover; results show full paths matching query, flattened.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default trigger | Placeholder or value path |
+| Open | Popover with N panels visible |
+| Hover row | Highlighted; if has children, panel to right opens |
+| Selected leaf | Filled bg, checkmark |
+| Loading (async) | Spinner in current panel |
+
+## Accessibility
+
+- Trigger: `role="combobox"`, `aria-expanded`, `aria-haspopup="tree"`, `aria-controls`.
+- Each panel: `role="listbox"` (or "tree" for accessibility tools).
+- Each option: `role="option"`, `aria-selected`, `aria-haspopup="listbox"` if has children.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach trigger |
+| `Enter` / `Space` | Open popover |
+| `↑` / `↓` | Move within current panel |
+| `→` | Expand to next panel (if has children) |
+| `←` | Back to previous panel |
+| `Enter` (on leaf) | Select |
+| `Esc` | Close |
+
+## Mobile pattern
+
+Cascader's horizontal panel UI breaks on mobile. Switch to a **drill-in screen pattern**:
+
+```
+[Tap trigger] → [Level 1 list screen] → [Level 2 list] → [Level 3 list] → [back to form]
+```
+
+Each level is a full-screen list with a back button. Visual breadcrumb at top: "서울 > 강남구 > ..."
+
+For Korean address: combine with Daum Postcode (more user-friendly for actual addresses) — see [`component-address-input.md`](component-address-input.md).
+
+## Don't
+
+- Don't use Cascader for non-hierarchical multi-select. Use a Tree.
+- Don't use for 5+ levels — too deep; user gets lost.
+- Don't use for hierarchies that change frequently (categories that move). Tree handles dynamic shape better.
+- Don't combine `changeOnSelect` with deep hierarchies — user accidentally selects at level 1.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/cascader/`](../refs/ant-design/components/cascader/) — `Cascader` with full feature set. Most exhaustive.
+- MUI / shadcn-ui: no built-in. Compose from Select-like primitives.
+
+## Cross-reference
+
+- [`examples/component-tree.md`](component-tree.md) — when hierarchy is variable depth
+- [`examples/component-select.md`](component-select.md) — flat alternative
+- [`examples/component-address-input.md`](component-address-input.md) — Korean address pattern using Daum Postcode

package/examples/component-category-picker.md

@@ -0,0 +1,271 @@
+# `CategoryPicker` (custom — Korean fintech / 가계부) — spec
+
+> Custom component pattern. Universal in Korean 가계부 (personal finance / expense tracker) apps. Not in any upstream design system.
+
+## Purpose
+
+Lets the user pick a category for a transaction (식비 / 교통 / 쇼핑 / etc.). Uses **emoji + Korean label** as the category visual identity — distinctive Korean app convention.
+
+## Anatomy
+
+```
+Horizontal scrollable pills (default):
+┌───────────────────────────────────────────────────────┐
+│ [🍽 식비]  [🚌 교통]  [🛍 쇼핑]  [🏠 주거]  [💊 건강]  │
+└───────────────────────────────────────────────────────┘
+                  ↑ active (filled bg)
+
+Grid (alternative for many categories):
+┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+│  🍽    │ │  🚌    │ │  🛍    │ │  🏠    │
+│  식비   │ │  교통   │ │  쇼핑   │ │  주거   │
+└────────┘ └────────┘ └────────┘ └────────┘
+┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+│  💊    │ │  🎬    │ │  ✈     │ │   +    │
+│  건강   │ │  엔터  │ │  여행   │ │ 추가  │
+└────────┘ └────────┘ └────────┘ └────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Category icon | yes | Emoji or pictogram (Korean 가계부 apps overwhelmingly use emoji) |
+| Category label | yes | Korean term |
+| "Add custom" affordance | optional | Lets user create their own category |
+| Search / filter | optional | For 30+ categories |
+
+## API
+
+```tsx
+<CategoryPicker
+  value={categoryId}
+  onValueChange={setCategoryId}
+  categories={[
+    { id: "food", icon: "🍽", label: "식비" },
+    { id: "transport", icon: "🚌", label: "교통" },
+    { id: "shopping", icon: "🛍", label: "쇼핑" },
+    // ...
+  ]}
+  layout="horizontal"
+  allowCustom
+  onCustomAdd={(name, icon) => addCategory({ name, icon })}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string \| null` | — | Selected category id |
+| `onValueChange` | `(id: string \| null) => void` | — | |
+| `categories` | `Category[]` | — | List of categories |
+| `layout` | `"horizontal" \| "grid" \| "list"` | `"horizontal"` | |
+| `allowCustom` | `boolean` | `false` | Show "+ 추가" button |
+| `onCustomAdd` | `(name: string, icon: string) => void` | — | Open modal to create new |
+| `searchable` | `boolean` | `false` | Search input above |
+| `disabled` | `boolean` | `false` | |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+
+```ts
+type Category = {
+  id: string;
+  icon: string;        // Emoji or icon name
+  label: string;       // Korean
+  color?: string;      // Optional bg tint
+  isCustom?: boolean;  // User-created
+};
+```
+
+## Default categories (Korean 가계부 standard)
+
+Korean apps converge on this categorization. Use as a starting point:
+
+| ID | Emoji | Korean | English |
+| --- | --- | --- | --- |
+| `food` | 🍽 | 식비 | Food |
+| `cafe` | ☕ | 카페 / 간식 | Cafe / Snack |
+| `transport` | 🚌 | 교통 | Transport |
+| `shopping` | 🛍 | 쇼핑 | Shopping |
+| `housing` | 🏠 | 주거 | Housing |
+| `utilities` | 💡 | 공과금 | Utilities |
+| `health` | 💊 | 건강 / 의료 | Health |
+| `entertainment` | 🎬 | 엔터테인먼트 | Entertainment |
+| `education` | 📚 | 교육 | Education |
+| `travel` | ✈ | 여행 | Travel |
+| `gift` | 🎁 | 선물 / 경조사 | Gift / Ceremony |
+| `subscription` | 📺 | 구독 | Subscription |
+| `salary` | 💰 | 급여 | Income — salary |
+| `bonus` | 💵 | 부수입 | Income — side |
+| `investment` | 📈 | 투자 | Investment |
+| `other` | ✨ | 기타 | Other |
+
+Income vs expense: usually two separate `CategoryPicker` instances OR a single picker with type filter.
+
+## Layouts
+
+### Horizontal scrollable pills (default for mobile)
+
+Best for 6–12 categories. User swipes horizontally to see more.
+
+```
+[🍽 식비] [🚌 교통] [🛍 쇼핑] ...→
+```
+
+### Grid (4-column on mobile, 6-column on tablet+)
+
+Best for 12+ categories. All visible at once.
+
+### List (vertical)
+
+Best for accessibility / dense desktop forms.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default (unselected) | Outline border, neutral bg |
+| Hover | Slight bg shift |
+| Selected | Filled bg `--color-primary-subtle-bg`, border `--color-primary-default`, text `--color-primary-default` |
+| Custom (user-added) | Same as default but with subtle "edit" icon on hover |
+| Disabled | Muted, no events |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle
+--color-primary-subtle-bg     (selected bg)
+--color-primary-default        (selected border + text)
+--color-text-primary
+--color-text-secondary
+--color-border-default
+--color-focus-ring
+--space-xs, --space-sm, --space-md
+--radius-md, --radius-full     (pill style for horizontal)
+--font-size-sm
+```
+
+## Sizes
+
+| Size | Pill height | Icon | Font |
+| --- | --- | --- | --- |
+| `sm` | 32px | 16px | 12px |
+| `md` (default) | 40px | 20px | 14px |
+| `lg` | 48px | 24px | 16px |
+
+For grid layout: each cell is square (e.g., 80×80 for `md`), with icon on top + label below.
+
+## Accessibility
+
+- Container: `role="radiogroup"`, `aria-label="카테고리 선택"`.
+- Each category: `role="radio"`, `aria-checked={value === id}`.
+- Emoji icons: `aria-hidden="true"` (the label carries meaning for screen readers).
+- "+ 추가" button: standard `<button>` with `aria-label="새 카테고리 추가"`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach the active category (single tab stop) |
+| `←` / `→` (horizontal) or `↑` / `↓` (grid) | Move + select next |
+| `Home` / `End` | First / last |
+| `Space` / `Enter` | Activate (or auto-activate on focus, configurable) |
+
+## Korean conventions
+
+- **Emoji is mandatory**, not decorative. Korean users associate emoji with categories — text-only feels sterile.
+- **Label is short** — 1-3 syllables typically. "식비", "교통", "쇼핑".
+- **Income categories use 💰 / 💵 / 📈 family**; expense uses everything else.
+- **Subscription** (구독) is a major Korean fintech category — Netflix, YouTube Premium, music services.
+- **경조사** (special-occasion gifts: weddings, funerals, holidays) is a uniquely Korean expense category — not in Western 가계부 apps.
+
+## Custom category creation
+
+When user clicks "+ 추가":
+
+```
+┌──────────────────────────────────┐
+│ 새 카테고리                        │
+│                                  │
+│ 이름:    [____________]            │
+│ 아이콘:  [😀] (tap to change)      │
+│                                  │
+│ 색상:    ●  ●  ●  ●  ●            │
+│                                  │
+│      [취소]    [추가]             │
+└──────────────────────────────────┘
+```
+
+- Name (required): Korean, 1-10 chars.
+- Icon (emoji picker — use system emoji picker or grid of common ones).
+- Color (optional): bg tint for visual distinction.
+
+Save to user-scoped storage (server-side typically, with sync).
+
+## Code example
+
+```tsx
+function TransactionForm() {
+  const [categoryId, setCategoryId] = useState<string | null>(null);
+  const categories = useCategories();
+  const [createOpen, setCreateOpen] = useState(false);
+
+  return (
+    <Form>
+      <Form.Field name="amount">
+        <AmountInput value={amount} onValueChange={setAmount} />
+      </Form.Field>
+
+      <Form.Field name="category">
+        <Form.Label>카테고리</Form.Label>
+        <CategoryPicker
+          value={categoryId}
+          onValueChange={setCategoryId}
+          categories={categories}
+          layout="horizontal"
+          allowCustom
+          onCustomAdd={() => setCreateOpen(true)}
+        />
+        <Form.ErrorText />
+      </Form.Field>
+
+      <CreateCategoryModal
+        open={createOpen}
+        onOpenChange={setCreateOpen}
+        onSave={(c) => {
+          createCategory(c);
+          setCategoryId(c.id);
+        }}
+      />
+    </Form>
+  );
+}
+```
+
+## Edge cases
+
+- **Many custom categories** (50+): switch to grid layout + search.
+- **No selection allowed** (clear): show null state, `value={null}`.
+- **Income vs expense**: filter list based on transaction type. Don't show `food` for income.
+- **Emoji rendering inconsistency** (Apple vs Android vs Web): emoji are rendered by OS; minor visual differences across platforms are acceptable.
+- **Korean accessibility**: aria-checked state needs Korean translation if assistive tech localized.
+
+## Don't
+
+- Don't use category icons without labels — Korean users want to see "식비" written out.
+- Don't omit emoji — text-only categorization feels lifeless to Korean users.
+- Don't use Western category emoji standards (🍔 for food). Use 🍽 for "Korean meal" feel.
+- Don't pre-select a default category. Let the user pick — wrong default is annoying.
+- Don't allow > 30 categories without search. Cognitive overload.
+
+## References
+
+No upstream component is exactly this. Closest analogs:
+- Ant Design: `Tag` checkable mode (but no emoji-first design)
+- MUI: `Chip` with avatar (similar idea)
+
+This is a **Korean-market-specific custom pattern**.
+
+## Cross-reference
+
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — Korean app conventions
+- [`examples/component-amount-input.md`](component-amount-input.md) — paired in transaction forms
+- [`examples/component-form.md`](component-form.md) — form orchestration
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)