@design-ai/cli 4.55.0

package/examples/component-lottie-player.md

@@ -0,0 +1,279 @@
+<!-- hand-written -->
+# `LottiePlayer` (custom — designer-led After Effects animation in product UI) — spec
+
+> Renders a Lottie JSON animation with sane defaults: lazy-load, pause when offscreen, respect reduced motion, fall back to a poster image. Pairs with [`knowledge/motion/motion-tools.md`](../knowledge/motion/motion-tools.md) and [`knowledge/motion/marketing-motion.md`](../knowledge/motion/marketing-motion.md).
+
+## Purpose
+
+Designers create motion in After Effects → export with Bodymovin → engineer drops the JSON in via `LottiePlayer`. This component handles the **lifecycle** concerns engineers usually forget:
+
+1. Lazy-load the JSON (don't ship a 200kB animation in the main bundle).
+2. Pause when offscreen (battery + perf).
+3. Provide a poster image for `prefers-reduced-motion`, slow connections, and SSR.
+4. Standardize play / loop / once-only semantics across the app.
+
+Without this: each Lottie usage hand-rolls these concerns, and at least one will skip them.
+
+## Anatomy
+
+```
+┌──────────────────────────────────┐
+│                                  │
+│      [Lottie animation]          │  ← canvas / SVG render
+│                                  │
+└──────────────────────────────────┘
+        ↓ if reduced-motion or no JS
+┌──────────────────────────────────┐
+│                                  │
+│      [Poster image — last frame] │  ← static fallback
+│                                  │
+└──────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<LottiePlayer
+  src="/animations/checkmark-success.json"
+  poster="/animations/checkmark-success.png"
+  mode="once"
+  onComplete={() => navigate("/done")}
+  width={240}
+  height={240}
+  ariaLabel="결제 완료"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string \| object` | — | URL to JSON or imported JSON object |
+| `poster` | `string` | — | Poster image URL for fallback (REQUIRED for animations >50kB or above-fold) |
+| `mode` | `"once" \| "loop" \| "controlled"` | `"once"` | Play behavior |
+| `autoplay` | `boolean` | `true` (loop & once); `false` (controlled) | Start playing on mount |
+| `playing` | `boolean` | — | Controlled play state (when `mode="controlled"`) |
+| `speed` | `number` | `1` | Playback speed multiplier |
+| `direction` | `1 \| -1` | `1` | Forward or reverse |
+| `loop` | `boolean \| number` | derived from mode | Override loop count |
+| `pauseOffscreen` | `boolean` | `true` | Auto-pause when not in viewport |
+| `width` | `number \| string` | — | Render dimensions |
+| `height` | `number \| string` | — | Render dimensions |
+| `ariaLabel` | `string` | — | REQUIRED — describes what the animation conveys |
+| `onComplete` | `() => void` | — | Fires after `mode="once"` completes |
+| `onLoop` | `() => void` | — | Fires each loop iteration |
+| `renderer` | `"svg" \| "canvas"` | `"svg"` | SVG = sharper; canvas = better perf for complex |
+| `disabled` | `boolean` | auto via `prefers-reduced-motion` | Show poster instead |
+
+## Modes
+
+### `once`
+
+Plays through, fires `onComplete`, holds last frame. Used for success states, error states, milestones.
+
+```tsx
+<LottiePlayer src={successAnim} poster={successPng} mode="once" onComplete={dismiss} />
+```
+
+### `loop`
+
+Plays continuously. Used for ambient brand moments, loading indicators with character.
+
+```tsx
+<LottiePlayer src={loadingAnim} poster={loadingPng} mode="loop" pauseOffscreen />
+```
+
+### `controlled`
+
+Parent controls play / pause via `playing` prop. Used for scroll-triggered, hover-triggered, gesture-triggered.
+
+```tsx
+const [hovered, setHovered] = useState(false);
+<div onMouseEnter={() => setHovered(true)} onMouseLeave={() => setHovered(false)}>
+  <LottiePlayer src={iconAnim} mode="controlled" playing={hovered} />
+</div>
+```
+
+## States
+
+| State | Visual | Why |
+| --- | --- | --- |
+| Loading JSON | Poster image | First paint while ~50–150kB JSON streams in |
+| Playing | Animation rendering | Normal |
+| Paused (offscreen) | Last rendered frame held | Saves CPU + battery |
+| Paused (controlled false) | Last rendered frame held | Parent decided |
+| Reduced motion | Poster image, never animates | a11y |
+| Error (JSON failed to load) | Poster image | Graceful degradation |
+| No JS / SSR | Poster image | `<noscript>` |
+
+## Tokens consumed
+
+```
+--motion-fast               (poster → animation cross-fade once JSON loads)
+--ease-out
+```
+
+LottiePlayer is mostly a wrapper around an external JSON; it does not consume color / typography tokens directly. The animation itself was authored in After Effects with brand colors baked in.
+
+## Korean fintech use cases
+
+| Scenario | Animation type | Mode |
+| --- | --- | --- |
+| 송금 완료 (transfer success) | Money flying / checkmark | `once` |
+| 결제 실패 (payment failed) | Error pulse / X mark | `once` |
+| 가입 환영 (signup welcome) | Brand mascot wave | `once` |
+| 로딩 (loading with character) | Mascot bouncing | `loop` (paused after 5s if still loading) |
+| 잔액 변화 (balance change) | Number counter | `controlled` (triggered by data update) |
+
+For all of the above: provide a poster image showing the **end state** (checkmark, X, mascot final pose) so reduced-motion users still get the meaning.
+
+## Accessibility
+
+- `ariaLabel` is REQUIRED. Describe what the animation conveys, not what it visually does:
+  - ✓ "결제가 완료되었습니다"
+  - ✗ "체크마크가 그려지는 애니메이션"
+- Wrap in `role="img"` (animation conveys meaning) OR `role="presentation"` (purely decorative + adjacent text already conveys meaning). Pick one consciously.
+- For `mode="once"` success / error states: also fire `role="status"` text announcement adjacent. Don't rely on the animation alone.
+- `prefers-reduced-motion: reduce` → show poster, never animate. Required.
+- Don't auto-play sound (Lottie can carry audio in some exports — strip it in Bodymovin export).
+
+## Lazy-loading strategy
+
+For Lottie files >30kB:
+
+```tsx
+const SuccessLottie = lazy(() =>
+  import("./animations/success.json").then(mod => ({
+    default: () => <LottiePlayer src={mod.default} poster="/success.png" mode="once" />
+  }))
+);
+
+<Suspense fallback={<img src="/success.png" alt="결제 완료" />}>
+  <SuccessLottie />
+</Suspense>
+```
+
+For above-the-fold animations: include the poster as `<link rel="preload" as="image">` and let the JSON stream in.
+
+## Implementation hints
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+import lottie, { AnimationItem } from "lottie-web";
+
+function LottiePlayer({
+  src, poster, mode = "once", autoplay, playing, pauseOffscreen = true,
+  ariaLabel, onComplete, renderer = "svg", width, height,
+}: Props) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const animRef = useRef<AnimationItem | null>(null);
+  const [loaded, setLoaded] = useState(false);
+  const [errored, setErrored] = useState(false);
+  const reduced = usePrefersReducedMotion();
+
+  // Skip everything if reduced motion
+  if (reduced || errored) {
+    return <img src={poster} alt={ariaLabel} width={width} height={height} />;
+  }
+
+  // Load + initialize
+  useEffect(() => {
+    if (!containerRef.current) return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const data = typeof src === "string" ? await fetch(src).then(r => r.json()) : src;
+        if (cancelled) return;
+        animRef.current = lottie.loadAnimation({
+          container: containerRef.current!,
+          renderer,
+          loop: mode === "loop",
+          autoplay: mode !== "controlled" && (autoplay ?? true),
+          animationData: data,
+        });
+        animRef.current.addEventListener("complete", () => onComplete?.());
+        setLoaded(true);
+      } catch {
+        setErrored(true);
+      }
+    })();
+    return () => {
+      cancelled = true;
+      animRef.current?.destroy();
+    };
+  }, [src]);
+
+  // Controlled mode play/pause
+  useEffect(() => {
+    if (mode !== "controlled" || !animRef.current) return;
+    if (playing) animRef.current.play();
+    else animRef.current.pause();
+  }, [playing, mode]);
+
+  // Pause offscreen
+  useEffect(() => {
+    if (!pauseOffscreen || !containerRef.current) return;
+    const obs = new IntersectionObserver(([entry]) => {
+      if (!animRef.current) return;
+      if (entry.isIntersecting) animRef.current.play();
+      else animRef.current.pause();
+    });
+    obs.observe(containerRef.current);
+    return () => obs.disconnect();
+  }, [pauseOffscreen]);
+
+  return (
+    <div
+      ref={containerRef}
+      role="img"
+      aria-label={ariaLabel}
+      style={{ width, height, position: "relative" }}
+    >
+      {!loaded && poster && <img src={poster} alt="" style={{ position: "absolute", inset: 0 }} />}
+    </div>
+  );
+}
+```
+
+## Bundle / performance
+
+| Library | Bundle | Notes |
+| --- | --- | --- |
+| `lottie-web` | ~150kB | Full-featured, all renderers |
+| `lottie-react` | ~150kB (wraps lottie-web) | React API |
+| `lottie-react-light` | ~50kB | Subset (svg renderer only) |
+| `@lottiefiles/dotlottie-react` | ~80kB | Smaller binary `.lottie` format |
+
+Recommendation: use `lottie-react-light` if you only need SVG (sharpest, most cases). Use canvas renderer only for complex animations with many shapes.
+
+For `.lottie` (compressed binary): 30–50% smaller files than JSON. Worth the swap if you ship 5+ animations.
+
+## Edge cases
+
+- **JSON fails to load (404, network error)**: show poster image. Never blank.
+- **Animation has audio**: strip it in Bodymovin export (`Audio: Off`). Don't auto-play sound.
+- **User rapid-mounts/unmounts (e.g., toast notifications)**: each mount creates lottie instance. Ensure `destroy()` runs in cleanup.
+- **Animation longer than 5 seconds**: reconsider — Lottie is for moments, not videos. Use a real video element.
+- **Same animation in 50 instances on a page (icon list)**: lottie-web shares JSON parse cache, but DOM nodes still cost. Consider sprite or static SVG instead.
+- **SSR (Next.js)**: lottie-web requires DOM. Wrap in `dynamic(() => import("./LottiePlayer"), { ssr: false })`.
+
+## Don't
+
+- Don't ship Lottie for what CSS can do (fade-in, simple icon flip). Bundle cost not justified.
+- Don't auto-play decorative loops on every page — battery drain on mobile.
+- Don't skip the poster — it's the fallback for reduced motion, slow networks, errors, and SSR.
+- Don't ship animations with embedded fonts (massively inflates JSON). Convert text to outlines in After Effects.
+- Don't ship 60fps animations when 30fps reads identically. Cuts file size in half.
+- Don't include color in the JSON if the surrounding theme might change (dark mode). Use `expressions` or post-load color override.
+
+## References
+
+- [`lottie-web`](https://github.com/airbnb/lottie-web) — Airbnb's renderer
+- [`lottie-react`](https://lottiereact.com/) — React wrapper
+- [Bodymovin plugin](https://aescripts.com/bodymovin/) — After Effects → JSON exporter
+- [LottieFiles](https://lottiefiles.com/) — animation library + dotlottie format
+
+## Cross-reference
+
+- [`knowledge/motion/motion-tools.md`](../knowledge/motion/motion-tools.md) — when Lottie vs Rive vs CSS
+- [`knowledge/motion/marketing-motion.md`](../knowledge/motion/marketing-motion.md) — Lottie in marketing
+- [`examples/component-empty-state.md`](component-empty-state.md) — uses Lottie for empty illustrations
+- [`examples/component-result.md`](component-result.md) — success / error states

package/examples/component-masonry.md

@@ -0,0 +1,191 @@
+# `Masonry` — spec
+
+> Synthesized from MUI `Masonry`. A Pinterest-style staggered grid where items pack vertically into columns, varying heights aligned cleanly. Distinct from Grid (uniform cells) and Flex (single-direction layout).
+
+## When to use
+
+- **Image gallery** with varied aspect ratios (Pinterest, Unsplash, gallery wall).
+- **Card grid** where cards have varied content lengths.
+- **Quote / testimonial wall** with naturally varying lengths.
+
+When NOT to use:
+- Uniform-height cards (use Grid).
+- Reading flow / accessible content sequence (Masonry's visual order ≠ DOM order — bad for screen readers).
+- Tables / data — use Table.
+
+## Anatomy
+
+```
+Column 1   Column 2   Column 3
+┌──────┐   ┌──────┐   ┌──────┐
+│      │   │      │   │      │
+│      │   ├──────┤   │      │
+├──────┤   │      │   │      │
+│      │   │      │   ├──────┤
+│      │   ├──────┤   │      │
+│      │   │      │   │      │
+├──────┤   │      │   │      │
+│      │   │      │   ├──────┤
+└──────┘   └──────┘   │      │
+                      └──────┘
+```
+
+Items flow vertically into columns; each item lands at the bottom of the shortest column.
+
+## API
+
+```tsx
+<Masonry columns={3} spacing={2}>
+  {photos.map(photo => (
+    <PhotoCard key={photo.id} photo={photo} />
+  ))}
+</Masonry>
+
+<Masonry columns={{ mobile: 1, tablet: 2, desktop: 3, wide: 4 }} spacing={2}>
+  {items}
+</Masonry>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | `number \| { mobile, tablet, desktop, wide }` | `3` | Column count (responsive object also accepted) |
+| `spacing` | `number` | `2` | Gap between items (typically token-multiplier) |
+| `defaultColumns` | `number` | `3` | SSR fallback before client measures |
+| `sequential` | `boolean` | `false` | If true, items fill columns left-to-right (DOM order = visual order) |
+| `children` | `ReactNode[]` | — | Items |
+
+## Implementation approaches
+
+### CSS Multicolumn (modern, simplest)
+
+```css
+.masonry {
+  column-count: 3;
+  column-gap: var(--space-md);
+}
+.masonry > * {
+  break-inside: avoid;
+  margin-bottom: var(--space-md);
+}
+```
+
+**Pros**: pure CSS, no JS measurement, SSR-friendly.
+**Cons**: items flow top-to-bottom in column 1 first (column 1 fills, then column 2). DOM order ≠ visual reading order.
+
+### JS column-measurement (Pinterest-style)
+
+```ts
+// Measure each item's height after render
+// Place each new item in the currently-shortest column
+// Update on resize / item changes
+```
+
+**Pros**: items appear in DOM order (column 1 row 1, column 2 row 1, etc.) so reading order matches.
+**Cons**: requires JS measurement, layout flicker on first render, more complex.
+
+MUI `Masonry` uses the JS approach with React refs.
+
+### CSS Grid masonry (future)
+
+```css
+.masonry {
+  display: grid;
+  grid-template-rows: masonry;  /* CSS Grid Level 3 */
+  grid-template-columns: repeat(3, 1fr);
+}
+```
+
+`grid-template-rows: masonry` is a draft spec (Firefox-only as of 2024). Wait for Chromium / Safari before adopting.
+
+## Variants
+
+### Responsive columns
+
+```tsx
+<Masonry columns={{ mobile: 1, tablet: 2, desktop: 3, wide: 4 }} />
+```
+
+Different column counts per breakpoint.
+
+### Sequential mode
+
+`sequential={true}` makes items fill left-to-right per row (like Grid but with varied heights). Loses the Pinterest "shortest column wins" advantage but preserves DOM order strictly.
+
+## States
+
+Stateless — Masonry is layout only.
+
+## Tokens consumed
+
+```
+--space-sm, --space-md             (gap)
+--motion-medium                    (item enter animation, optional)
+```
+
+## Accessibility
+
+- **Reading order matters**. Masonry's visual columns may not match DOM order. Screen readers read DOM order.
+- For accessible Masonry: ensure DOM order = priority order (most important first), even if columns shuffle visually.
+- Each item is independently accessible (semantic markup inside).
+- Keyboard: Tab moves through items in DOM order (which may zigzag visually — acceptable for galleries; not for reading).
+- Avoid Masonry for primary content / reading flow. Reserve for media-grid surfaces.
+
+## Performance
+
+- For 1000+ items: virtualize using `react-virtuoso` or similar Masonry-aware virtualizer.
+- For images: lazy-load (`loading="lazy"`) so off-screen items don't block initial paint.
+- Measure-once on resize (debounce 150ms) — measuring per-frame kills performance.
+- For aspect-ratio-known items (image with width / height): provide ratio so layout settles before image loads.
+
+## Code example
+
+```tsx
+function PhotoGallery({ photos }: Props) {
+  return (
+    <Masonry columns={{ mobile: 1, tablet: 2, desktop: 3 }} spacing={2}>
+      {photos.map(photo => (
+        <figure key={photo.id} className="photo-card">
+          <img
+            src={photo.url}
+            width={photo.width}
+            height={photo.height}
+            alt={photo.alt}
+            loading="lazy"
+            style={{ aspectRatio: `${photo.width}/${photo.height}` }}
+          />
+          <figcaption>{photo.caption}</figcaption>
+        </figure>
+      ))}
+    </Masonry>
+  );
+}
+```
+
+## Edge cases
+
+- **All items same height**: result looks like Grid. Use Grid instead.
+- **One very tall item**: it dominates one column; others may look empty. Cap maximum height OR balance manually.
+- **Lazy-loaded items popping in**: layout reflows. With `aspect-ratio` set, reflow is minimal.
+- **Server-render with unknown heights**: SSR shows items in their column-fill order; client re-measures and adjusts. Brief flicker possible — accept or use CSS-multicolumn as SSR-stable fallback.
+- **RTL**: column order reverses (rightmost = column 1). Verify your layout.
+- **Print**: CSS multicolumn handles print well; JS-based Masonry may not — provide a print stylesheet that disables Masonry (`column-count: 1`).
+
+## Don't
+
+- Don't use Masonry for forms or data tables. Wrong tool.
+- Don't use Masonry for content that requires linear reading. Confusing.
+- Don't put items with vastly different sizes (5x height differences) — looks broken.
+- Don't omit `aspect-ratio` on images. Without it, layout shifts as images load.
+- Don't run measurement per scroll-event. Measure once on resize / item change.
+
+## References
+
+- MUI: [`Masonry`](../refs/mui/packages/mui-material/src/Masonry)
+- CSS Multicolumn Layout (MDN)
+- Pinterest engineering blog on Masonry layout
+
+## Cross-reference
+
+- [`examples/component-image.md`](component-image.md) — common Masonry child
+- [`examples/component-card.md`](component-card.md) — alternative for uniform cards
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)

package/examples/component-mentions.md

@@ -0,0 +1,189 @@
+# `Mention` (@-trigger autocomplete) — spec
+
+> Citing Ant Design `Mentions`, MUI (no built-in), shadcn-ui (composition with `command`)
+
+## Purpose
+
+A textarea-style input where typing a trigger character (`@`, `#`, `:`) opens a popover with suggestions. The picked suggestion is inserted into the text as a "mention chip" (highlighted token).
+
+Used for: comments, chat, descriptions with @-mentions of users, #-tags, :emoji shortcodes, /commands.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────┐
+│ Hey @mi|                                              │  ← cursor after @mi
+└──────────────────────────────────────────────────────┘
+            │
+            ▼
+       ┌──────────────────┐
+       │ ▶ 김민지 (@minji) │  ← active suggestion
+       │   김민호 (@minho) │
+       │   민혜진 (@hye)   │
+       └──────────────────┘
+
+After picking "김민지":
+┌──────────────────────────────────────────────────────┐
+│ Hey [김민지]                                          │  ← chip rendered as highlighted token
+└──────────────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Mention
+  value={text}
+  onValueChange={setText}
+  triggers={[
+    {
+      char: "@",
+      onSearch: (query) => searchUsers(query),
+      renderItem: (user) => <UserItem user={user} />,
+      onSelect: (user) => ({ value: `@${user.username}`, label: user.name, data: user }),
+    },
+    {
+      char: "#",
+      onSearch: (query) => searchTags(query),
+    },
+  ]}
+  placeholder="댓글을 작성하세요..."
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Text content (with chips encoded as tokens) |
+| `onValueChange` | `(value: string, mentions: Mention[]) => void` | — | Returns plain text + structured mentions |
+| `triggers` | `Trigger[]` | — | Per-trigger config |
+| `placeholder` | `string` | — | |
+| `multiline` | `boolean` | `true` | Textarea vs input |
+| `maxLength` | `number` | — | |
+| `disabled` | `boolean` | `false` | |
+
+```ts
+type Trigger = {
+  char: string;                    // "@", "#", ":", "/"
+  onSearch: (query: string) => Promise<Option[]>;
+  renderItem?: (item: Option) => ReactNode;
+  onSelect: (item: Option) => { value: string; label: string; data?: unknown };
+};
+
+type Mention = {
+  trigger: string;
+  value: string;
+  data: unknown;       // The original Option's data
+  position: { start: number; end: number };
+};
+```
+
+## Behavior
+
+### Trigger detection
+
+When user types a trigger char:
+1. Detect cursor position immediately after.
+2. Open popover anchored at cursor.
+3. As user continues typing, send query (the chars after trigger) to `onSearch`.
+4. Show suggestions in popover.
+
+### Picking a suggestion
+
+When user selects a suggestion (click or Enter):
+1. Replace `@query` with the chip representation.
+2. Close popover.
+3. Cursor advances past the chip.
+4. The chip is **non-editable** as a unit — backspace deletes the whole chip, not character-by-character.
+
+### Cancelling
+
+Type `Esc`, click outside, or type a space: closes popover, leaves typed text as-is (no chip created).
+
+## Storage format
+
+Two common storage approaches:
+
+### A. Plain text + structured mentions
+
+```ts
+{
+  text: "Hey @minji and @minho, please review",
+  mentions: [
+    { trigger: "@", value: "minji", position: { start: 4, end: 10 } },
+    { trigger: "@", value: "minho", position: { start: 15, end: 21 } },
+  ]
+}
+```
+
+Mentions array references positions in the text. Render-time: replace those positions with chips.
+
+### B. Markdown-like syntax
+
+```
+"Hey @[김민지](minji) and @[김민호](minho)"
+```
+
+Storage is plain string with markup. Easier for back-end indexing; harder to render WYSIWYG live.
+
+For chat (sub-second updates): A. For documents: either.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | Placeholder, no popover |
+| Typing (no trigger) | Standard textarea |
+| Trigger typed | Popover opens at cursor |
+| Searching | Spinner in popover |
+| Has suggestions | List visible |
+| Picked | Chip inserted; popover closed |
+| Empty results | "결과 없음" or hide popover |
+
+## Accessibility — WAI-ARIA Combobox pattern
+
+For the dropdown:
+- Container has `role="combobox"` characteristics applied to the textarea + popover.
+- Each suggestion: `role="option"`, `aria-selected` on highlighted.
+- Use `aria-activedescendant` on the textarea pointing at the highlighted option.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| Type trigger char | Opens popover at cursor |
+| `↓` / `↑` | Move highlight (in popover) |
+| `Enter` | Pick highlighted suggestion |
+| `Esc` | Close popover; keep typed text |
+| `Backspace` (after a chip) | Deletes the chip (whole unit) |
+| `Backspace` (during search) | Deletes character; if last trigger char deleted, close popover |
+
+### Screen reader
+
+When chip inserted: announce via live region: "김민지 mentioned" or similar.
+
+## Korean considerations
+
+- `@` is the standard mention trigger (universal).
+- `#` for hashtags works; some apps use Korean characters as triggers but stick with `@`/`#` for compatibility.
+- Korean usernames: typically `@박민지` (full name) or `@minji` (romanized). Both should work.
+- IME composition: don't fire suggestions during composition. Wait for `compositionend`. See [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md).
+- Chip rendering: Korean names sometimes longer (3-4 chars) — chip width adapts.
+
+## Don't
+
+- Don't make chips editable as text. Backspace deletes whole chip, single Tab moves through.
+- Don't use Mentions for fields where suggestions are NOT inserted as text. Use AutoComplete.
+- Don't allow free-text @-mentions that bypass the picker (creates broken mentions). Either pick from suggestions OR show error.
+- Don't render chips with critical styling that breaks copy-paste — they should stringify gracefully.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/mentions/`](../refs/ant-design/components/mentions/) — `Mentions`. Multi-trigger support, async data.
+- MUI: no built-in. Use `react-mentions` or build on Slate.
+- shadcn-ui: no built-in. Compose with `command` (cmdk) + textarea + custom popover positioning.
+
+## Cross-reference
+
+- [`examples/component-auto-complete.md`](component-auto-complete.md) — when no trigger character is needed
+- [`examples/component-select.md`](component-select.md) — combobox pattern
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — IME composition
+- [`knowledge/patterns/search-ux.md`](../knowledge/patterns/search-ux.md) — typeahead patterns