@design-ai/cli 4.55.0

package/examples/component-image.md

@@ -0,0 +1,282 @@
+# `Image` — spec
+
+> Citing Ant Design `Image`, MUI (composition), shadcn-ui (composition with native `<img>`)
+
+## Purpose
+
+A wrapper around `<img>` that adds: lazy loading, fallback for broken images, lightbox preview, aspect ratio enforcement, optional zoom + skeleton. Use for any non-trivial image display in product UIs.
+
+For pure `<img>` (decorative icons, avatars): use the native element OR `Avatar` component.
+
+## Anatomy
+
+```
+Default:                       With preview enabled (click to expand):
+┌──────────────────────┐       ┌──────────────────────┐
+│                      │       │                      │
+│    [image]           │       │    [image]      🔍   │ ← magnifier overlay
+│                      │       │                      │
+└──────────────────────┘       └──────────────────────┘
+
+In lightbox (after click):
+   ┌───────────────────────────────────────────┐
+   │  [image at full resolution, zoom enabled] │ ← modal-style overlay
+   │                                            │
+   │  [previous] [next]              [close ✕] │
+   └───────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Image
+  src="/photo.jpg"
+  alt="Product photo"
+  aspectRatio="1/1"
+  preview
+  fallback="/placeholder.png"
+  loading="lazy"
+/>
+
+<Image.Group>
+  <Image src="/p1.jpg" alt="..." />
+  <Image src="/p2.jpg" alt="..." />
+  <Image src="/p3.jpg" alt="..." />
+</Image.Group>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string` | — | Required. Image URL. |
+| `alt` | `string` | — | Required. Alt text — describe meaning, or `""` for decorative. |
+| `width` / `height` | `number \| string` | — | |
+| `aspectRatio` | `string` | — | `"16/9"`, `"1/1"`, `"4/3"`. Cleaner than width+height. |
+| `fit` | `"cover" \| "contain" \| "fill" \| "scale-down" \| "none"` | `"cover"` | CSS object-fit |
+| `position` | CSS object-position | `"center"` | |
+| `preview` | `boolean` | `false` | Click opens lightbox |
+| `fallback` | `string \| ReactNode` | default broken-image icon | What to render on load error |
+| `placeholder` | `ReactNode` | skeleton | What to render while loading |
+| `loading` | `"lazy" \| "eager"` | `"lazy"` | Native lazy-load attribute |
+| `srcset` | `string` | — | Responsive sources |
+| `sizes` | `string` | — | Hints for srcset selection |
+| `priority` | `boolean` | `false` | If true, sets `loading="eager"` and `fetchpriority="high"` (above-fold images) |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"none"` | Corner radius |
+
+### Image.Group (lightbox sequence)
+
+When grouped, clicking any image opens the lightbox with previous/next navigation:
+
+```tsx
+<Image.Group>
+  <Image src="/p1.jpg" alt="..." />
+  <Image src="/p2.jpg" alt="..." />
+  <Image src="/p3.jpg" alt="..." />
+</Image.Group>
+```
+
+The lightbox shows previous/next arrows + counter "1 / 3".
+
+## Behavior
+
+### Loading sequence
+
+1. Render skeleton (`placeholder` or default).
+2. Browser fetches image.
+3. On load: replace skeleton with image.
+4. On error: render fallback.
+
+### Aspect ratio
+
+Use `aspectRatio` to prevent layout shift (CLS):
+
+```css
+.image-wrapper {
+  aspect-ratio: 16 / 9;
+  width: 100%;
+}
+img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+```
+
+The wrapper takes its full width; height is computed from aspect ratio. Image fills the wrapper with object-fit cover.
+
+### Fallback
+
+When the image fails to load (404, CORS, network):
+- Default: small icon (broken image symbol) + "이미지를 불러올 수 없습니다."
+- Custom: pass `fallback` (URL or React node).
+
+### Lightbox
+
+When `preview: true`:
+- Click image → opens modal-style overlay with the image at full resolution.
+- Lightbox features: zoom (mouse wheel / pinch), pan, close on Escape, close on backdrop click.
+- For Image.Group: keyboard arrows navigate between images; click outside closes.
+
+### Lazy loading
+
+Default `loading="lazy"` defers image fetch until near viewport. Saves bandwidth on long pages.
+
+For above-fold (hero) images: set `priority` to load eagerly.
+
+## Sizes / aspect ratios
+
+Common ratios:
+
+| Ratio | Use |
+| --- | --- |
+| `1/1` | Avatars, product cards (square), Instagram-style |
+| `4/3` | Standard photo |
+| `16/9` | Video thumbnails, hero banners |
+| `21/9` | Cinematic banners |
+| `2/3` | Portrait product photos |
+| `9/16` | Story / vertical mobile content |
+
+Always set an aspect ratio — this prevents the browser-jumping layout shift when images load.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Loading | Skeleton (or `placeholder`) at the aspect ratio |
+| Loaded | Image visible |
+| Error | Fallback icon + text |
+| Lightbox open | Modal overlay; underlying page locked |
+| Lightbox zooming | Cursor changes to zoom-in/out; image scales |
+
+## Tokens consumed
+
+```
+--color-bg-subtle               (skeleton bg)
+--color-text-tertiary           (fallback icon)
+--color-text-secondary          (fallback caption)
+--color-bg-overlay              (lightbox backdrop, ~rgba(0,0,0,0.85))
+--color-on-overlay              (lightbox text/icons — typically white)
+--space-md
+--radius-md, --radius-lg, --radius-full
+--motion-default                (lightbox open/close)
+--easing-out
+--shadow-modal                   (lightbox surface)
+```
+
+## Accessibility
+
+### Alt text rules
+
+- **Decorative** (alt=""): screen readers skip. Use for purely visual flourishes.
+- **Functional** (icon-button image): `alt` describes the action.
+- **Informational**: `alt` describes what the image shows. Don't say "image of" — screen readers announce it's an image already.
+
+```html
+<!-- Decorative -->
+<img src="/decorative-blob.svg" alt="" />
+
+<!-- Functional -->
+<button>
+  <img src="/print-icon.svg" alt="Print this page" />
+</button>
+
+<!-- Informational -->
+<img src="/team-photo.jpg" alt="Three engineers in front of a whiteboard during a sprint planning session" />
+```
+
+### Lightbox accessibility
+
+- Modal pattern: focus trap, restore focus on close. See [`examples/component-modal.md`](component-modal.md).
+- Image in lightbox: `role="img" aria-label={alt}` on the wrapper if multiple are stacked.
+- Counter "N / M" announced on slide change via `aria-live="polite"`.
+- Zoom: keyboard `+` / `-` for zoom in / out, `0` to reset. (Optional but nice.)
+
+## Korean considerations
+
+- Alt text in Korean for KR-primary apps.
+- For e-commerce / fashion: include garment color + style in alt (helps blind users compare).
+- For receipts / 영수증: never replace text content with screenshots without an accessible alternative.
+
+## Code example
+
+```tsx
+// Standard product card image
+<Image
+  src={product.imageUrl}
+  alt={product.name}
+  aspectRatio="1/1"
+  fit="cover"
+  radius="md"
+  loading="lazy"
+/>
+
+// Hero image (above fold)
+<Image
+  src="/hero.jpg"
+  alt="Workspace with laptop and coffee"
+  aspectRatio="16/9"
+  priority
+/>
+
+// Image gallery with lightbox
+<Image.Group>
+  {product.images.map(img => (
+    <Image
+      key={img.id}
+      src={img.thumbnailUrl}
+      srcset={`${img.thumbnailUrl} 400w, ${img.fullUrl} 1200w`}
+      sizes="(max-width: 768px) 100vw, 400px"
+      alt={`${product.name} 사진 ${img.index}`}
+      aspectRatio="1/1"
+      preview
+    />
+  ))}
+</Image.Group>
+
+// Avatar-style with full radius
+<Image
+  src={user.photoUrl}
+  alt={user.name}
+  aspectRatio="1/1"
+  radius="full"
+  fallback="/default-avatar.png"
+/>
+```
+
+## Edge cases
+
+- **Image takes >5s to load**: still show skeleton; don't fall back to error prematurely. Errors are for actual failures (404, CORS).
+- **Very large image** (10MB+): forces user to wait. Always serve resized versions via `srcset`.
+- **Hi-DPI / retina**: serve 2x resolution for retina screens via `srcset` `2x` descriptor.
+- **CORS-blocked image**: counts as load error, fallback renders. Inform user if it's a recurring issue.
+- **Image with broken `src` URL**: fallback renders. Log the error for debugging (don't silently hide).
+- **Zoomed image larger than viewport** (lightbox): allow pan; clamp at edges.
+- **Reduced motion**: lightbox open/close animations are minimal; respect `prefers-reduced-motion`.
+- **Print**: images print by default. For receipts/invoices: ensure print stylesheet renders them at appropriate sizes.
+
+## Don't
+
+- Don't omit `alt`. Even decorative images need `alt=""` (empty, but present).
+- Don't lazy-load above-fold images. Use `priority` or `loading="eager"`.
+- Don't render images at unspecified aspect ratio — causes layout shift.
+- Don't put critical info only in images. Provide text alternative.
+- Don't auto-zoom without user input. The user should drive zoom.
+- Don't use `Image` for icons. Use `Icon` component or inline SVG.
+- Don't ship images without responsive sources (`srcset`/`sizes`) for content-heavy pages.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/image/`](../refs/ant-design/components/image/) — `Image` + `Image.PreviewGroup` for lightbox. Has `placeholder`, `fallback`, `preview` config. Solid impl.
+- MUI: no dedicated component. Compose with native `<img>`.
+- shadcn-ui: no built-in. Compose `<img>` + Tailwind. For lightbox: `react-photo-view` or `yet-another-react-lightbox`.
+
+API choices made:
+- **`aspectRatio` as first-class prop**: prevents layout shift; cleaner than separate width+height.
+- **`preview` opt-in**: most images don't need lightbox; opting in is the right friction.
+- **`Image.Group` for sequence**: mirrors Ant's pattern; lightbox navigates within group.
+- **`priority` boolean**: simpler than passing `loading="eager"` + `fetchpriority="high"` separately for the common above-fold case.
+
+## Cross-reference
+
+- [`examples/component-avatar.md`](component-avatar.md) — for user/profile images (different fallback semantics)
+- [`examples/component-modal.md`](component-modal.md) — lightbox uses modal a11y pattern
+- [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md) — text on image overlays

package/examples/component-input-adornment.md

@@ -0,0 +1,101 @@
+# `InputAdornment` — spec
+
+> Synthesized from MUI `InputAdornment`. Leading or trailing content slot for an input — icons (search, calendar, currency), text prefixes/suffixes (`₩`, `@`), or interactive controls (clear button, password toggle).
+
+## When to use
+
+- Search input → leading magnifying glass.
+- Currency input → leading `₩` or `$`.
+- Password input → trailing show/hide toggle.
+- Email input → trailing domain hint.
+
+## API
+
+```tsx
+<OutlinedInput
+  startAdornment={
+    <InputAdornment position="start">
+      <SearchIcon />
+    </InputAdornment>
+  }
+  endAdornment={
+    <InputAdornment position="end">
+      <IconButton aria-label="지우기" size="small">
+        <CloseIcon />
+      </IconButton>
+    </InputAdornment>
+  }
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `position` | `'start' \| 'end'` | required | Which side |
+| `children` | `ReactNode` | — | The content |
+| `disablePointerEvents` | `boolean` | `false` | When the adornment is decorative-only (icon, prefix text), this lets clicks pass through to the input |
+| `disableTypography` | `boolean` | `false` | Skip default Typography wrapping (for non-text adornments) |
+
+## Tokens consumed
+
+```
+--space-sm        /* gap between adornment and input value */
+--icon-size-md    /* default 24px */
+--color-fg-muted  /* default adornment color */
+```
+
+## Accessibility
+
+- **Decorative icons**: set `aria-hidden="true"` on the icon + `disablePointerEvents={true}` on the adornment.
+- **Interactive adornments** (clear button, password toggle): use `IconButton` inside with explicit `aria-label`. Set `edge="start"` or `edge="end"` on the IconButton for proper alignment.
+- **Text prefixes** like `₩` are decorative — wrap in `<Typography>` and `aria-hidden="true"`. The input's `inputMode="decimal"` + numeric value handle the actual semantics.
+
+## Edge cases
+
+- **Adornment focus tab order** — interactive adornments are part of the tab order BEFORE/AFTER the input, depending on `position`. End-adornments tab AFTER the input — usually correct (clear button after typing).
+- **Korean prefix labels** — for "원" suffix, use `position="end"`. Don't put it inside the input as text — the input's value should stay numeric.
+- **Combining start + end** — fine, but watch for narrow widths; long text in both can squeeze the input.
+
+## Code example
+
+```tsx
+function PriceInput({ value, onChange }) {
+  return (
+    <FormControl fullWidth>
+      <FormLabel htmlFor="price">가격</FormLabel>
+      <OutlinedInput
+        id="price"
+        type="number"
+        inputMode="decimal"
+        value={value}
+        onChange={(e) => onChange(Number(e.target.value))}
+        startAdornment={
+          <InputAdornment position="start" disablePointerEvents>
+            <Typography aria-hidden>₩</Typography>
+          </InputAdornment>
+        }
+        endAdornment={
+          <InputAdornment position="end" disablePointerEvents>
+            <Typography color="text.secondary" aria-hidden>원</Typography>
+          </InputAdornment>
+        }
+      />
+    </FormControl>
+  );
+}
+```
+
+## Don't
+
+- Don't put non-trivial UI in adornments (whole forms, multi-line text) — they collapse oddly.
+- Don't omit `aria-label` on interactive adornments.
+- Don't set `disablePointerEvents` on interactive adornments — it breaks them.
+
+## References
+
+- MUI: [`InputAdornment`](../refs/mui/packages/mui-material/src/InputAdornment/)
+
+## Cross-reference
+
+- [`component-input-base.md`](component-input-base.md)
+- [`component-outlined-input.md`](component-outlined-input.md)
+- [`component-amount-input.md`](component-amount-input.md) — currency-specific composition

package/examples/component-input-base.md

@@ -0,0 +1,134 @@
+# `InputBase` — spec
+
+> Synthesized from MUI `InputBase`. The unstyled foundation of every MUI input variant (`OutlinedInput`, `FilledInput`, `Input`, `TextField`'s internals). Use directly when you need a fully custom-styled input that still gets MUI's accessibility + IME + adornment behavior.
+
+## When to use
+
+- Building a custom-styled input that doesn't fit `OutlinedInput`/`FilledInput`.
+- Composition primitive for design-system-specific input variants.
+- For 99% of cases, prefer `OutlinedInput` (default styling + label notch).
+
+## Anatomy
+
+```
+┌─[start adornment]─[input element]─[end adornment]─┐
+│                                                    │
+└────────────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<InputBase
+  inputProps={{ "aria-label": "search" }}
+  startAdornment={<SearchIcon />}
+  placeholder="검색..."
+  sx={{ /* full custom styling */ }}
+/>
+```
+
+39 props (full surface). Most-used:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `unknown` | — | Controlled / uncontrolled value |
+| `onChange` | `(e) => void` | — | Change handler |
+| `type` | `string` | `'text'` | HTML input type |
+| `multiline` | `boolean` | `false` | Render as `<textarea>` |
+| `rows` / `minRows` / `maxRows` | `number` | — | Multi-line height |
+| `placeholder` | `string` | — | Placeholder text |
+| `startAdornment` / `endAdornment` | `ReactNode` | — | Leading/trailing content |
+| `disabled` | `boolean` | `false` | |
+| `readOnly` | `boolean` | `false` | Caret disabled, no editing |
+| `error` | `boolean` | `false` | Error state |
+| `fullWidth` | `boolean` | `false` | |
+| `autoFocus` | `boolean` | `false` | Focus on mount |
+| `inputProps` | `InputHTMLAttributes` | — | Pass-through to native input (autoComplete, inputMode, pattern, maxLength, etc.) |
+| `inputRef` | `Ref` | — | Ref to native input |
+| `inputComponent` | `ElementType` | `'input'` | Override the inner element (e.g., for masked input libraries) |
+| `name` | `string` | — | Form name |
+| `required` | `boolean` | `false` | |
+| `slots` / `slotProps` | `object` | — | MUI v5+ component override pattern |
+| `sx` | `SxProps` | — | Style override |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | inherits parent FormControl styling |
+| Focus | inherits FormControl focus styling |
+| Disabled | reduced opacity, no caret |
+| Error | inherits FormControl error styling |
+| Read-only | no caret, but still focusable + selectable |
+
+## Tokens consumed
+
+InputBase has no built-in tokens — it inherits from the parent FormControl + your custom `sx` styles. Token cascade comes from the variant wrapper (`OutlinedInput`, `FilledInput`).
+
+## Accessibility
+
+- `inputProps` is the right place for native semantics: `autoComplete`, `inputMode`, `pattern`, `maxLength`, `aria-*`.
+- For required: pair `required` with `aria-required="true"` (for older AT compatibility).
+- `inputComponent` is the seam for masked-input libraries (react-imask, react-text-mask) — they need to forward refs correctly; check the library docs.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Korean IME composition** — `onChange` fires per keystroke including IME composition. For "search-as-you-type" patterns, use `onCompositionEnd` instead. Cite [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md).
+- **`inputComponent` swap** — when using a masked-input lib, the component must implement `forwardRef` correctly. Common gotcha: cursor jumps on every keystroke if the implementation doesn't preserve selection.
+- **`multiline=true` + `maxRows`** — the textarea grows up to `maxRows` then becomes scrollable. Don't set both `rows` and `maxRows` — pick auto-grow or fixed.
+- **`type="search"`** — adds an "X" clear button in some browsers (Safari, Chrome on macOS). For consistent UX, render your own end-adornment with a clear icon.
+
+## Code example
+
+```tsx
+// Custom search field with clear + icon
+function SearchField({ value, onChange, onClear }) {
+  return (
+    <InputBase
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      placeholder="검색..."
+      sx={{
+        bgcolor: 'background.paper',
+        border: 1,
+        borderColor: 'divider',
+        borderRadius: 1,
+        px: 2,
+        py: 1,
+        '&:focus-within': { borderColor: 'primary.main' },
+      }}
+      startAdornment={
+        <SearchIcon sx={{ color: 'text.secondary', mr: 1 }} aria-hidden />
+      }
+      endAdornment={
+        value && (
+          <IconButton size="small" onClick={onClear} aria-label="검색어 지우기">
+            <CloseIcon fontSize="small" />
+          </IconButton>
+        )
+      }
+      inputProps={{ "aria-label": "검색", autoComplete: "off" }}
+    />
+  );
+}
+```
+
+## Don't
+
+- Don't use directly when an existing variant (`OutlinedInput`, `FilledInput`, `TextField`) fits — you'll re-implement focus styling, label association, and helper-text wiring.
+- Don't omit `inputProps={{ "aria-label": ... }}` if there's no associated `<label>` — the input has no accessible name otherwise.
+- Don't pass styling via `style` prop — use `sx` for theme integration.
+
+## References
+
+- MUI: [`InputBase`](../refs/mui/packages/mui-material/src/InputBase/)
+
+## Cross-reference
+
+- [`component-outlined-input.md`](component-outlined-input.md) — outlined variant (default)
+- [`component-filled-input.md`](component-filled-input.md) — filled variant
+- [`component-input.md`](component-input.md) — standard variant
+- [`component-input-adornment.md`](component-input-adornment.md)
+- [`component-form-control.md`](component-form-control.md)
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — IME notes

package/examples/component-input-number.md

@@ -0,0 +1,141 @@
+# `InputNumber` — spec
+
+> Synthesized from Ant Design `InputNumber`. Numeric input with up/down stepper buttons, formatting, and min/max constraints. shadcn / MUI ship a generic `<TextField type="number">` instead — Ant's specialized component handles formatting (commas, decimals), parsing, and IME edge cases that the generic falls down on.
+
+## When to use
+
+- Quantities (수량, 인원, 횟수).
+- Prices / amounts where commas matter.
+- Bounded inputs (rating 1-5, percentage 0-100).
+
+## When NOT to use
+
+- Currency input with extensive formatting → use a specialized `AmountInput` per [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md).
+- Phone numbers → text input with masking, not numeric.
+
+## Anatomy
+
+```
+┌────────────────┐
+│ 12,345    ▲▼  │   ← stepper buttons (up/down)
+└────────────────┘
+```
+
+## API
+
+```tsx
+<InputNumber
+  min={0}
+  max={100}
+  step={1}
+  value={qty}
+  onChange={setQty}
+  formatter={(v) => `${v}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
+  parser={(v) => v.replace(/,/g, '')}
+  addonAfter="개"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number` | — | Controlled / uncontrolled value |
+| `onChange` | `(value) => void` | — | Fires on commit (blur, Enter, stepper) |
+| `min` / `max` | `number` | `-Infinity` / `Infinity` | Bounds |
+| `step` | `number` | `1` | Stepper increment |
+| `precision` | `number` | — | Decimal places |
+| `formatter` | `(value) => string` | — | Display transform (e.g., add commas) |
+| `parser` | `(displayValue) => number` | — | Reverse the formatter on input |
+| `controls` | `boolean \| { upIcon, downIcon }` | `true` | Show stepper buttons |
+| `prefix` / `addonBefore` | `ReactNode` | — | Leading content (icon / unit) |
+| `suffix` / `addonAfter` | `ReactNode` | — | Trailing content (unit / "원") |
+| `disabled` | `boolean` | `false` | |
+| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | |
+| `keyboard` | `boolean` | `true` | Enable arrow keys to step |
+| `stringMode` | `boolean` | `false` | Use string for big-int values (decimals beyond JS number precision) |
+| `status` | `'error' \| 'warning'` | — | Validation state |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Border, fg-default |
+| Focus | Brand border + ring |
+| Hover | Stepper buttons reveal (or always visible per design system) |
+| Error | Red border + helper |
+| Disabled | Muted, stepper hidden |
+
+## Tokens consumed
+
+```
+--input-bg
+--input-border
+--input-border-focus
+--input-border-error
+--input-min-height-32
+--input-min-height-40
+--input-padding-x
+--font-family-mono     /* tabular numerals for clean alignment */
+```
+
+## Accessibility
+
+- Renders as `<input type="text" inputmode="decimal">` (NOT `type="number"` — that breaks `formatter`).
+- Stepper buttons need `aria-label="증가"` / `aria-label="감소"`.
+- Arrow Up/Down keys step through values when focused.
+- For min/max bounds, surface invalid attempts via `aria-invalid` + helper text rather than silently clamping.
+- Cite [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md).
+
+## Edge cases
+
+- **Korean IME entering numbers** — IME shouldn't intercept; `inputmode="decimal"` brings up numeric keyboard on mobile. Test on a real device — desktop testing misses IME edge cases per [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md).
+- **Paste with formatting** — "12,345원" pasted should parse to 12345 via `parser`. Don't reject — clean it.
+- **Decimal precision overflow** — JS `0.1 + 0.2 = 0.30000000000000004`. Use `precision={2}` + display rounding, or `stringMode` for invoices/finance.
+- **Negative values** — explicit `min={0}` if not allowed; otherwise minus sign is accepted.
+- **Empty value** — `value=null` vs `value=undefined` vs `value=0` are distinct. Decide your convention; document it.
+- **Big numbers (> Number.MAX_SAFE_INTEGER)** — use `stringMode={true}` to keep precision.
+
+## Code example
+
+```tsx
+// Quantity picker
+<InputNumber
+  min={1}
+  max={99}
+  defaultValue={1}
+  onChange={(qty) => setQty(qty ?? 1)}
+  addonAfter="개"
+  size="middle"
+  aria-label="수량"
+/>
+
+// Price input with comma formatting
+<InputNumber
+  min={0}
+  step={100}
+  precision={0}
+  value={price}
+  onChange={setPrice}
+  addonBefore="₩"
+  formatter={(v) => `${v}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
+  parser={(v) => Number(v?.replace(/,/g, '') ?? 0)}
+  style={{ width: '100%' }}
+/>
+```
+
+## Don't
+
+- Don't use `<input type="number">` for prices — formatting/IME break.
+- Don't silently clamp to bounds without a message — user wonders why their input changed.
+- Don't omit unit suffix for ambiguous numbers (12 what?).
+- Don't use without `inputmode="decimal"` on mobile.
+
+## References
+
+- Ant Design: [`InputNumber`](../refs/ant-design/components/input-number/)
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md)
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md)
+- [`component-input.md`](component-input.md)
+- [`component-amount-input.md`](component-amount-input.md)