@design-ai/cli 4.55.0

package/examples/component-skeleton.md

@@ -0,0 +1,178 @@
+# `Skeleton` — spec
+
+> Citing Ant Design `Skeleton`, MUI `Skeleton`, shadcn-ui `skeleton`
+
+## Purpose
+
+A placeholder rendered while content loads. Shows the **shape** of what's coming — title bar, paragraph lines, image, etc. Reduces perceived load time and prevents layout shift when the real content arrives.
+
+## When Skeleton vs Spinner
+
+| Use Skeleton | Use Spinner |
+| --- | --- |
+| First load of a screen (we know the shape) | Async action with no shape (form submit, API call) |
+| List of items where each item has a known structure | Indeterminate "thinking" state |
+| Component with predictable layout | Inline loading on a button |
+
+For pagination or refresh of an existing list: **don't replace items with skeletons**. Show a small inline spinner. Keep the loaded data.
+
+## Anatomy — primitives
+
+A Skeleton is composed from three primitive shapes:
+
+```
+Text line:    ▔▔▔▔▔▔▔▔▔▔▔▔▔
+Block:        ▢▢▢▢
+Circle:       ◯
+```
+
+```tsx
+<Skeleton variant="text" width="80%" />
+<Skeleton variant="rect" width={120} height={120} />
+<Skeleton variant="circle" size={48} />
+```
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"text" \| "rect" \| "circle"` | `"text"` | Shape |
+| `width` | `string \| number` | `"100%"` (text) | Pixels or CSS unit |
+| `height` | `string \| number` | scaled to text size | |
+| `size` | `number` | — | Convenience for circle (W=H) |
+| `lines` | `number` | `1` | For variant="text" — render N lines |
+| `animation` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` | |
+
+## Composition for higher-level shapes
+
+Build screen-specific skeletons by composing primitives:
+
+```tsx
+// Card skeleton
+<Card>
+  <Skeleton variant="rect" height={160} />   {/* hero image */}
+  <Card.Body>
+    <Skeleton variant="text" width="60%" />   {/* title */}
+    <Skeleton variant="text" width="100%" />  {/* desc line 1 */}
+    <Skeleton variant="text" width="80%" />   {/* desc line 2 */}
+  </Card.Body>
+</Card>
+
+// List item skeleton
+<div className="flex gap-3 py-3">
+  <Skeleton variant="circle" size={40} />     {/* avatar */}
+  <div className="flex-1">
+    <Skeleton variant="text" width="40%" />   {/* name */}
+    <Skeleton variant="text" width="80%" />   {/* preview */}
+  </div>
+</div>
+```
+
+For frequent shapes, expose a higher-level skeleton: `<Skeleton.Card />`, `<Skeleton.ListItem />`.
+
+## Animation
+
+| Animation | Look | Use |
+| --- | --- | --- |
+| `shimmer` (default) | Diagonal gradient sweeps left → right, 1500ms loop linear | Universal — most polished |
+| `pulse` | Opacity 0.5 → 1 fade-pulse | Calmer, less attention-grabbing |
+| `none` | Static | Reduced-motion mode, or when many skeletons are on screen |
+
+Implement shimmer as:
+```css
+.skeleton {
+  background: linear-gradient(90deg, var(--color-bg-subtle), var(--color-bg-elevated), var(--color-bg-subtle));
+  background-size: 200% 100%;
+  animation: shimmer 1500ms linear infinite;
+}
+@keyframes shimmer {
+  0%   { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+```
+
+## States
+
+The Skeleton itself doesn't have states — it's a placeholder. The transition is from skeleton → real content.
+
+### Transition rules
+
+- Show skeleton immediately on mount when waiting for data.
+- If data arrives in < 200ms: never show skeleton. (Avoid flicker.)
+- If data arrives in 200–600ms: showing skeleton helps perceived speed.
+- If data arrives in > 600ms: skeleton is **essential**.
+- On data arrive: skeleton unmounts, real content appears. Match heights to prevent layout shift.
+
+```tsx
+{isLoading ? <Skeleton.Card /> : <ProductCard data={data} />}
+```
+
+## Tokens consumed
+
+```
+--color-bg-subtle              (skeleton base)
+--color-bg-elevated            (shimmer highlight)
+--radius-sm                     (text shape)
+--radius-md                     (rect shape)
+--radius-full                   (circle shape)
+```
+
+## Accessibility
+
+- Wrap a group of skeletons in `aria-busy="true"` with `aria-label="Loading"`.
+- The skeletons themselves can be `aria-hidden="true"` — they don't add information for screen readers.
+- **Don't** announce "loading loading loading" for each skeleton. One container-level announcement.
+- When data loads, remove `aria-busy` and announce result if helpful (`role="status"` with `"5 results loaded"`).
+
+```tsx
+<div aria-busy={isLoading} aria-live="polite" aria-label={isLoading ? "Loading transactions" : undefined}>
+  {isLoading ? (
+    <>
+      <Skeleton.ListItem />
+      <Skeleton.ListItem />
+      <Skeleton.ListItem />
+    </>
+  ) : (
+    <TransactionList items={data} />
+  )}
+</div>
+```
+
+## Reduced motion
+
+Honor `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .skeleton { animation: none; }
+}
+```
+
+The skeleton still renders (showing layout); just no animation.
+
+## Edge cases
+
+- **Skeleton matched to wrong content shape**: real content arrives, layout shifts. Bug. Always preview the skeleton vs the real component.
+- **Skeleton everywhere**: a page entirely of skeletons feels slow even at fast TTI. Try to render at least the page chrome (header, nav) immediately and skeleton only the data area.
+- **Skeleton inside a Skeleton**: don't nest. Compose at the outer level.
+- **Skeleton on a dark mode card**: token `--color-bg-subtle` is darker than `--color-bg-default` in dark mode — confirm visibility.
+- **Variable-width text**: skeleton width should approximate the average. 60% / 80% / 100% mix reads natural.
+
+## Don't
+
+- Don't show a skeleton for < 200ms. The flicker is worse than briefly-empty.
+- Don't show a skeleton on user actions (button clicks). Use a button loading state.
+- Don't replace existing data with skeletons during refresh — keep stale data + show subtle progress.
+- Don't ship without `prefers-reduced-motion` handling.
+- Don't use skeletons as decorative loading bars. They're for content shape.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/skeleton/`](../refs/ant-design/components/skeleton/) — most exhaustive: `Skeleton.Avatar`, `Skeleton.Button`, `Skeleton.Image`, `Skeleton.Input`, `Skeleton.Node`. Pre-composed shapes for common components.
+- MUI: [`refs/mui/packages/mui-material/src/Skeleton/`](../refs/mui/packages/mui-material/src/Skeleton/) — primitive only. Composition is up to the consumer.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/skeleton.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/skeleton.tsx) — minimal Tailwind-based primitive.
+
+## Cross-reference
+
+- [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md) — list-loading patterns
+- [knowledge/patterns/ux-guidelines.md](../knowledge/patterns/ux-guidelines.md) — broader loading-state rules

package/examples/component-slide.md

@@ -0,0 +1,89 @@
+# `Slide` — spec
+
+> Synthesized from MUI `Slide`. Transition primitive that slides a child in / out from a specified direction. Sibling to `Fade`, `Zoom`, `Grow`, `Collapse`.
+
+## When to use
+
+- Drawer / Sheet entrance (slides from edge).
+- Toast / Snackbar entrance (slides up from bottom).
+- Sequential reveals on scroll-into-view.
+
+## API
+
+```tsx
+<Slide direction="up" in={open} mountOnEnter unmountOnExit>
+  <div className="card">
+    Content
+  </div>
+</Slide>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `in` | `boolean` | required | Show / hide |
+| `direction` | `"up" \| "down" \| "left" \| "right"` | `"down"` | Slide-from direction |
+| `timeout` | `number \| { enter, exit }` | `225` | Ms |
+| `easing` | `string \| { enter, exit }` | per Material | CSS easing |
+| `appear` | `boolean` | `false` | Animate on first mount |
+| `mountOnEnter` / `unmountOnExit` | `boolean` | `false` | DOM mount control |
+
+## CSS
+
+```css
+.slide-up-enter {
+  transform: translateY(100%);
+}
+.slide-up-enter-active {
+  transform: translateY(0);
+  transition: transform 250ms var(--ease-out);
+}
+.slide-up-exit-active {
+  transform: translateY(100%);
+  transition: transform 195ms var(--ease-out);
+}
+```
+
+Direction variants flip the translate axis.
+
+## Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .slide-* { transition: none; }
+}
+```
+
+## Tokens consumed
+
+```
+--motion-medium
+--ease-out
+```
+
+## Code example — bottom sheet entrance
+
+```tsx
+<Slide in={open} direction="up" mountOnEnter unmountOnExit>
+  <div className="bottom-sheet">
+    <SheetContent />
+  </div>
+</Slide>
+```
+
+## Don't
+
+- Don't slide horizontally large amounts on narrow viewports — content invisible mid-transition.
+- Don't ignore reduced motion.
+- Don't combine Slide with Fade and Zoom together — pick one motion idiom.
+
+## References
+
+- MUI: [`Slide`](../refs/mui/packages/mui-material/src/Slide)
+- Material Design motion
+
+## Cross-reference
+
+- [`examples/component-zoom.md`](component-zoom.md)
+- [`examples/component-sheet.md`](component-sheet.md) — uses slide internally
+- [`examples/component-drawer.md`](component-drawer.md) — uses slide internally
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md)

package/examples/component-slider.md

@@ -0,0 +1,208 @@
+# `Slider` — spec
+
+> Citing Ant Design `Slider`, MUI `Slider`, shadcn-ui `slider`
+
+## Purpose
+
+A control for selecting a numeric value (or a range) by dragging. Used for: volume, price filter, opacity, brightness, age range.
+
+## When Slider vs Input
+
+| Use Slider | Use Input (numeric) |
+| --- | --- |
+| Approximate value matters more than exact | Exact value matters |
+| Continuous range with no obvious snap points | Discrete options or precise numbers |
+| Visual feedback as the user adjusts | User knows the value (e.g., DOB year, transaction amount) |
+
+For amounts (currency, distance), prefer Input. For preferences (volume, contrast adjustment), Slider.
+
+## Anatomy
+
+```
+Single value:
+0 ──────●─────────── 100
+        45
+
+Range:
+0 ─────●━━━━━━━●─── 100
+       20      80
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Track | yes | Background line |
+| Range fill | yes | Filled portion (single: 0→thumb, range: thumb1→thumb2) |
+| Thumb(s) | yes | Draggable circle(s) |
+| Tick marks | optional | Small lines at intervals |
+| Step labels | optional | Numbers at tick positions |
+| Value display | optional | Tooltip at thumb OR fixed display nearby |
+
+## API
+
+```tsx
+<Slider
+  value={volume}
+  onValueChange={setVolume}
+  min={0}
+  max={100}
+  step={1}
+  label="볼륨"
+  showValue
+/>
+
+<Slider
+  value={priceRange}
+  onValueChange={setPriceRange}
+  min={0}
+  max={1000000}
+  step={10000}
+  range
+  label="가격대"
+  formatValue={(v) => `₩${v.toLocaleString()}`}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number \| [number, number]` | — | Single or range. `[number, number]` triggers range mode |
+| `onValueChange` | `(value) => void` | — | Fires while dragging (debounced) |
+| `onValueCommit` | `(value) => void` | — | Fires only on drag-end (use for expensive updates) |
+| `range` | `boolean` | inferred from value type | Force range mode |
+| `min` / `max` | `number` | `0` / `100` | |
+| `step` | `number` | `1` | Increment per arrow key / tick |
+| `marks` | `{ value: number, label?: string }[]` | — | Custom marks |
+| `disabled` | `boolean` | `false` | |
+| `label` | `string` | — | Visible label (above slider) |
+| `showValue` | `boolean` | `false` | Render value as tooltip on thumb |
+| `formatValue` | `(value) => string` | `String(value)` | Custom format |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | |
+| `inverted` | `boolean` | `false` | Right-to-left direction |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Track + thumb at value position |
+| Hover (thumb) | Thumb slightly larger or shadow |
+| Focus-visible | 2px ring around thumb |
+| Dragging | Cursor: grabbing; thumb scaled up; tooltip visible |
+| Disabled | Track + thumb muted, no events |
+
+## Sizes
+
+| Size | Track height | Thumb size |
+| --- | --- | --- |
+| `sm` | 2px | 14px |
+| `md` (default) | 4px | 18px |
+| `lg` | 6px | 22px |
+
+For mobile touch: `md` minimum. The thumb's hit area extends beyond the visible thumb by ~12px each side to support thumb dragging.
+
+## Tokens consumed
+
+```
+--color-bg-subtle           (track)
+--color-primary-default      (range fill, thumb)
+--color-bg-default           (thumb center, ring)
+--color-text-primary         (value display)
+--color-focus-ring
+--space-xs, --space-sm
+--radius-full                (thumb)
+--motion-fast, --easing-out
+--shadow-card                 (thumb shadow)
+```
+
+## Accessibility — WAI-ARIA Slider pattern
+
+- Single thumb: `role="slider"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-orientation`, `aria-label` (or `aria-labelledby`).
+- Range: two `role="slider"` thumbs, each with their own valuenow + label ("Minimum price" / "Maximum price").
+- `aria-valuetext` if the displayed value isn't a plain number (e.g., "₩50,000" instead of "50000").
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach slider (thumb 1; if range, then thumb 2) |
+| `←` / `↓` | Decrement by `step` |
+| `→` / `↑` | Increment by `step` |
+| `Home` | min value |
+| `End` | max value |
+| `PageUp` / `PageDown` | Larger step (typically 10× step) |
+
+For range slider with overlapping thumbs: each thumb maintains independent focus + keyboard control. Thumb that would cross the other "pushes" it (or stops at the other's position).
+
+## Touch / drag behavior
+
+- Hit area for thumb: 44×44 pt minimum (extend with invisible padding).
+- Drag the track: should jump-to-value-and-start-drag from any track position.
+- Snap to step: cleanly, no fractional positions.
+- Vibration / haptic feedback (mobile): subtle haptic at each step crossing for some apps; off by default for sliders that are continuous-feeling.
+
+## Edge cases
+
+- **Range thumbs overlap**: when min and max meet, thumbs occupy the same space. Allow this (they're interchangeable). Visual: render z-index so the active one is on top.
+- **`step` doesn't divide `max - min` evenly**: thumb snaps to nearest step; the max position might not be reachable. Prefer round-numbered max + step combinations.
+- **Very large ranges with small step**: 0–1,000,000 with step=1 gives a million positions but only ~1000 px of track. Thumb position is still continuous; consider bumping step to 1000 or showing a numeric input next to the slider for precision.
+- **Vertical orientation**: arrow keys reverse on `↑`/`↓` semantically (up = increase). Keep that.
+- **RTL**: track flows right-to-left automatically with `dir="rtl"`. Use logical CSS.
+- **Dragging while page scrolls**: prevent accidental page scroll on touch — use `touch-action: none` on the slider.
+
+## Code example
+
+```tsx
+// Volume control
+<Slider
+  label="볼륨"
+  value={volume}
+  onValueChange={setVolume}
+  min={0}
+  max={100}
+  step={1}
+  showValue
+  formatValue={(v) => `${v}%`}
+/>
+
+// Price range filter
+<Slider
+  label="가격대"
+  value={priceRange}
+  onValueChange={setPriceRange}    // updates UI live
+  onValueCommit={fetchResults}      // server-fetch only on release
+  min={0}
+  max={1000000}
+  step={10000}
+  range
+  marks={[
+    { value: 0, label: "₩0" },
+    { value: 250000, label: "₩25만" },
+    { value: 500000, label: "₩50만" },
+    { value: 750000, label: "₩75만" },
+    { value: 1000000, label: "₩100만+" },
+  ]}
+  formatValue={(v) => `₩${v.toLocaleString()}`}
+/>
+
+// Disabled state with explanation
+<Slider value={50} disabled aria-label="요금제 한도 도달" />
+```
+
+## Don't
+
+- Don't use Slider for exact numeric input where the exact value matters. Use a number input (or both — common in price filters: slider + two number inputs synced).
+- Don't omit `aria-label` (or `label` prop). Sliders without an accessible name are unusable.
+- Don't fire expensive operations on `onValueChange` (debounce 100ms minimum, or use `onValueCommit`).
+- Don't disable the slider without explaining why (tooltip or inline help).
+- Don't have `step` so small that arrow keys feel useless (1 over a 0–1,000,000 range — 1,000,000 keypresses).
+- Don't show a slider for binary choices. Use a Switch.
+- Don't layer two sliders on top of each other to fake range. Use proper range mode.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/slider/`](../refs/ant-design/components/slider/) — `Slider` with `range`, `marks`, `step`, `included` (whether range fill shows). Solid impl.
+- MUI: [`refs/mui/packages/mui-material/src/Slider/`](../refs/mui/packages/mui-material/src/Slider/) — `Slider` with rich `marks`, `valueLabelDisplay`, `track="normal" | "false" | "inverted"`. Most comprehensive.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/slider.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/slider.tsx) — Radix Slider primitive. Simplest API.
+
+## Cross-reference
+
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md) — keyboard contract for slider
+- [`examples/component-input.md`](component-input.md) — when number input is the right choice instead

package/examples/component-snackbar-content.md

@@ -0,0 +1,92 @@
+# `SnackbarContent` — spec
+
+> Synthesized from MUI `SnackbarContent`. The default visual surface inside a `Snackbar` — message text + optional action button. Use for custom Snackbars beyond the simple message-string case.
+
+## When to use
+
+- Snackbars with rich content (icon + text + action button).
+- Inline banners that look like Snackbars but live in-page (rare).
+- For simple toasts, `Snackbar message="..."` auto-renders SnackbarContent — no direct use needed.
+
+## API
+
+```tsx
+<Snackbar open={open} onClose={handleClose}>
+  <SnackbarContent
+    message="저장됐어요"
+    action={
+      <Button color="inherit" size="small" onClick={handleUndo}>
+        실행 취소
+      </Button>
+    }
+  />
+</Snackbar>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `message` | `ReactNode` | — | The message |
+| `action` | `ReactNode` | — | Action button (right-aligned) |
+| `role` | `string` | `'alert'` | ARIA role |
+
+## Tokens consumed
+
+```
+--snackbar-bg            /* dark surface (high-contrast for floating ephemeral UI) */
+--snackbar-fg
+--snackbar-padding
+--snackbar-radius
+--snackbar-shadow-md
+```
+
+## Accessibility
+
+- Default `role="alert"` makes the message announce to screen readers immediately on appear.
+- Use `role="status"` for less-urgent updates ("저장 중...").
+- Action button's accessible name comes from its label — keep concise (1-2 words).
+
+## Edge cases
+
+- **Korean message brevity** — Snackbars auto-dismiss in ~5s; keep messages short ("저장됐어요" not "변경사항이 성공적으로 저장됐습니다").
+- **Multiple actions** — limit to 1 action; if more needed, use a Dialog instead.
+- **Long messages** — wrap to 2 lines max.
+
+## Code example
+
+```tsx
+<Snackbar
+  open={state.open}
+  autoHideDuration={5000}
+  onClose={handleClose}
+  anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+>
+  <SnackbarContent
+    message={
+      <Stack direction="row" alignItems="center" gap={1}>
+        <CheckCircleIcon fontSize="small" aria-hidden />
+        <span>저장됐어요</span>
+      </Stack>
+    }
+    action={
+      <Button color="inherit" size="small" onClick={handleUndo}>
+        실행 취소
+      </Button>
+    }
+  />
+</Snackbar>
+```
+
+## Don't
+
+- Don't use for errors that block flow — those are Dialogs.
+- Don't pile multiple Snackbars on screen — at most one at a time.
+
+## References
+
+- MUI: [`SnackbarContent`](../refs/mui/packages/mui-material/src/SnackbarContent/)
+
+## Cross-reference
+
+- [`component-snackbar.md`](component-snackbar.md)
+- [`component-alert.md`](component-alert.md)
+- [`component-toast.md`](component-toast.md)

package/examples/component-snackbar.md

@@ -0,0 +1,121 @@
+# `Snackbar` — spec
+
+> Synthesized from MUI `Snackbar` and Material 3 snackbar pattern. Bottom-anchored brief notification with optional action — Material's specific name for the Toast pattern. See [`component-toast.md`](component-toast.md) for the broader Toast family.
+
+## Snackbar vs Toast vs Message vs Notification
+
+| Library | Position | Use |
+| --- | --- | --- |
+| Snackbar (Material) | Bottom-center / bottom-left | Brief result + optional Undo |
+| Toast (Sonner / shadcn / Ant) | Bottom-right (configurable) | Same as Snackbar |
+| Message (Ant) | Top-center | Brief inline confirmation |
+| Notification (Ant) | Top-right corner card | Rich title + description |
+
+In design-ai's canonical synthesis: **Snackbar = MUI's name for Toast**. Pick one terminology per project.
+
+## Anatomy
+
+```
+                                 ┌────────────────────────┐
+                                 │ Marked as read [Undo] [×] │
+                                 └────────────────────────┘
+                                          ↑ bottom-center (Material default)
+```
+
+## API
+
+```tsx
+<Snackbar
+  open={open}
+  onClose={() => setOpen(false)}
+  message="읽음 처리됨"
+  action={
+    <Button size="sm" onClick={undo}>실행 취소</Button>
+  }
+  autoHideDuration={6000}
+  anchorOrigin={{ vertical: "bottom", horizontal: "center" }}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | controlled | Visibility |
+| `onClose` | `(reason) => void` | — | Close callback (auto / manual / clickaway) |
+| `message` | `string \| ReactNode` | — | Content |
+| `action` | `ReactNode` | — | Trailing action button(s) |
+| `autoHideDuration` | `number` | `6000` | Ms before auto-close; null = persistent |
+| `anchorOrigin` | `{ vertical, horizontal }` | bottom-left | Position |
+| `severity` | `"success" \| "info" \| "warning" \| "error"` | none | Color preset |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Hidden |
+| Opening | Slide up + fade in (200ms) |
+| Open | Visible; auto-hide timer ticks |
+| Closing | Slide down + fade out |
+
+## Tokens consumed
+
+```
+--snackbar-bg                     (default; near-black on light, near-white on dark)
+--snackbar-fg
+--snackbar-action                 (action button text)
+--snackbar-shadow
+--radius-md
+--motion-medium
+--ease-out
+--z-snackbar                      (above content, below modals)
+```
+
+## Accessibility
+
+- `role="status"` (informational) or `role="alert"` (errors).
+- `aria-live="polite"` (status) or `assertive` (alert) — be sparing.
+- Auto-hide pauses on hover / focus (don't dismiss while user is reading or interacting).
+- Esc closes if focusable.
+
+## Code example — undo pattern
+
+```tsx
+async function deleteItem(id: string) {
+  const item = items.find(i => i.id === id);
+  setItems(prev => prev.filter(i => i.id !== id));
+
+  toast.snackbar({
+    message: "삭제되었어요",
+    action: <Button onClick={() => setItems(prev => [...prev, item])}>실행 취소</Button>,
+    autoHideDuration: 5000,
+    onClose: (reason) => {
+      if (reason !== "clickaway") {
+        api.deleteItem(id);  // commit deletion when snackbar closes
+      }
+    },
+  });
+}
+```
+
+## Korean conventions
+
+- 삭제됐어요 / 저장됐어요 / 복사됐어요 — typical 해요체 messages
+- 실행 취소 (Undo) — standard label
+- For network errors: "네트워크 오류 — 다시 시도하시겠어요?" + Retry button
+
+## Don't
+
+- Don't use Snackbar for blocking errors. Use Modal / AlertDialog.
+- Don't show 3+ Snackbars stacked. Queue them.
+- Don't auto-dismiss persistent errors (let user dismiss manually).
+- Don't make autoHide < 4 seconds for messages with Undo. Users need time to act.
+
+## References
+
+- MUI: [`Snackbar`](../refs/mui/packages/mui-material/src/Snackbar)
+- Material 3: Snackbar pattern
+
+## Cross-reference
+
+- [`examples/component-toast.md`](component-toast.md) — broader Toast family
+- [`examples/component-message.md`](component-message.md) — top-positioned alternative
+- [`examples/component-notification.md`](component-notification.md) — richer card variant