@design-ai/cli 4.55.0

package/examples/component-auto-complete.md

@@ -0,0 +1,199 @@
+# `AutoComplete` — spec
+
+> Citing Ant Design `AutoComplete`, MUI `Autocomplete`, shadcn-ui (composition with `command`)
+>
+> Distinct from `Select` (covered combined in [`component-select.md`](component-select.md)) — AutoComplete allows **free-form text input** with suggestions, while Select requires choosing from the list.
+
+## Purpose
+
+A text input with type-ahead suggestions. User can:
+- Pick a suggestion (like Select).
+- Type free text (unlike Select).
+
+Used for: search bars with suggestions, address auto-fill, email input with recent contacts, tag creation, command palettes.
+
+## When AutoComplete vs Select vs Combobox
+
+| Pattern | Behavior |
+| --- | --- |
+| **Select** | User picks from list. Free text not allowed. |
+| **AutoComplete** | User can pick OR type free text. |
+| **Combobox** (the WAI-ARIA pattern) | Umbrella term; both Select and AutoComplete are flavors. |
+
+If your input requires the value be from a list: Select.
+If your input allows custom values: AutoComplete (or Select with `creatable`).
+
+## Anatomy
+
+```
+Closed:                         Typing (open):
+┌─────────────────────────┐    ┌─────────────────────────┐
+│ Search recipes...      🔍│    │ chocolate              ✕ │
+└─────────────────────────┘    ├─────────────────────────┤
+                                │ ▶ chocolate cake         │
+                                │   chocolate chip cookies │
+                                │   chocolate fondue       │
+                                │ ───                      │
+                                │ Recent searches:         │
+                                │   chocolate truffles     │
+                                └─────────────────────────┘
+```
+
+## API
+
+```tsx
+<AutoComplete
+  value={query}
+  onValueChange={setQuery}
+  options={suggestions}
+  onSelect={(value) => navigate(`/recipes?q=${value}`)}
+  placeholder="레시피 검색"
+  loading={isLoading}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Input value (controlled) |
+| `onValueChange` | `(value: string) => void` | — | Fires per keystroke |
+| `onSelect` | `(value: string, option: Option) => void` | — | Fires when user picks a suggestion (vs typing then submitting) |
+| `options` | `Option[]` or `(query: string) => Promise<Option[]>` | — | Suggestions; can be async |
+| `loading` | `boolean` | `false` | Shows spinner in dropdown |
+| `placeholder` | `string` | — | |
+| `disabled` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | |
+| `freeText` | `boolean` | `true` | Allow committing values not in suggestions |
+| `clearable` | `boolean` | `true` | ✕ to clear |
+| `iconStart` | `ReactNode` | — | E.g., search icon |
+| `noResultsMessage` | `ReactNode` | "결과 없음" | When suggestions empty |
+
+```ts
+type Option = {
+  value: string;
+  label?: ReactNode;          // Custom display
+  description?: string;
+  group?: string;
+  data?: unknown;
+};
+```
+
+## Behavior
+
+- Typing fires `onValueChange` (per keystroke, debounced for async).
+- Suggestions filter (client) or fetch (async).
+- User picks a suggestion: `onSelect` fires with the picked value.
+- User types and presses Enter without picking: input commits free text.
+- Search suggestions vs typing: matched substring highlighted.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | Placeholder, no dropdown |
+| Typing | Dropdown opens with filtered suggestions |
+| Loading | Spinner in dropdown |
+| Has suggestions | List visible |
+| No results | "결과 없음" empty state |
+| Selected | Input shows picked value, dropdown closes |
+| Disabled | Standard |
+
+## Korean IME composition
+
+Critical for Korean apps. Don't fire suggestions during IME composition (mid-syllable):
+
+```tsx
+const [isComposing, setIsComposing] = useState(false);
+
+<input
+  onCompositionStart={() => setIsComposing(true)}
+  onCompositionEnd={(e) => {
+    setIsComposing(false);
+    setQuery(e.target.value); // Now fire suggestions
+  }}
+  onChange={(e) => {
+    if (!isComposing) setQuery(e.target.value);
+  }}
+/>
+```
+
+Cite [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) for IME details.
+
+## Accessibility — WAI-ARIA Combobox pattern
+
+- Input: `role="combobox"`, `aria-autocomplete="list"`, `aria-expanded={isOpen}`, `aria-controls={listboxId}`.
+- Listbox: `role="listbox"`, `id={listboxId}`.
+- Each option: `role="option"`, `aria-selected={isHighlighted}`.
+- Highlighted option: `aria-activedescendant={optionId}` on the input.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach input |
+| `↓` (closed) | Open dropdown |
+| `↓` / `↑` (open) | Move highlight |
+| `Enter` | Select highlighted (if any) OR commit typed value |
+| `Esc` | Close dropdown (first press), clear input (second press) |
+
+## Common patterns
+
+### Search bar
+
+User types a query; dropdown shows matching items + recent searches:
+
+```tsx
+<AutoComplete
+  options={searchResults}
+  onSelect={navigate}
+  iconStart={<SearchIcon />}
+  placeholder="검색"
+/>
+```
+
+See [`knowledge/patterns/search-ux.md`](../knowledge/patterns/search-ux.md).
+
+### Email input with contacts
+
+```tsx
+<AutoComplete
+  options={contacts.map(c => ({ value: c.email, label: c.name, description: c.email }))}
+  freeText
+  iconStart={<EnvelopeIcon />}
+/>
+```
+
+### Address auto-fill
+
+For Korean addresses: don't use AutoComplete. Use Daum Postcode lookup. See [`component-address-input.md`](component-address-input.md).
+
+### Tag creation
+
+```tsx
+<AutoComplete
+  options={existingTags}
+  freeText
+  onSelect={(value, option) => addTag(value, !option ? "new" : "existing")}
+/>
+```
+
+When user selects an option: existing tag. When user types and commits: new tag.
+
+## Don't
+
+- Don't use AutoComplete when the value MUST be from a list. Use Select.
+- Don't fire suggestions on every keystroke during IME composition.
+- Don't ship without keyboard navigation.
+- Don't show 100+ suggestions. Cap at 10–20; let the user refine the query.
+- Don't force user to pick a suggestion. Allow free text commit.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/auto-complete/`](../refs/ant-design/components/auto-complete/) — `AutoComplete`. Built on top of Select with free-text mode.
+- MUI: [`refs/mui/packages/mui-material/src/Autocomplete/`](../refs/mui/packages/mui-material/src/Autocomplete/) — `Autocomplete` with `freeSolo` prop. Most comprehensive.
+- shadcn-ui: compose `command` (cmdk) + Popover for autocomplete-like behavior.
+
+## Cross-reference
+
+- [`examples/component-select.md`](component-select.md) — for picking from a list (no free text)
+- [`knowledge/patterns/search-ux.md`](../knowledge/patterns/search-ux.md) — when AutoComplete is a search bar
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — IME composition handling

package/examples/component-avatar-group.md

@@ -0,0 +1,170 @@
+# `AvatarGroup` - spec
+
+> Direct upstream component: MUI `AvatarGroup`. Parent pattern references: Ant Design `Avatar.Group`, MUI `AvatarGroup`, shadcn-ui avatar examples.
+
+## Purpose
+
+`AvatarGroup` shows a compact set of people or entities by overlapping avatars and summarizing overflow as a surplus item such as `+3`. Use it in collaboration surfaces, assignee lists, chat participants, document viewers, and activity feeds.
+
+Use a text list instead when the user must compare every participant name.
+
+## Anatomy
+
+```
+AvatarGroup
+├── Avatar item 1
+├── Avatar item 2
+├── Avatar item 3
+└── Surplus item       optional; "+N" or custom renderer
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root | yes | Groups stacked avatars as one visual unit. |
+| Avatar child | yes | Individual `Avatar` components or compatible nodes. |
+| Surplus item | conditional | Represents hidden participants when `total > max`. |
+| Tooltip/popover | optional | Reveals hidden names when surplus is interactive. |
+
+## API
+
+```tsx
+<AvatarGroup
+  max={4}
+  total={project.members.length}
+  renderSurplus={(count) => `+${count}`}
+>
+  {project.members.slice(0, 4).map((member) => (
+    <Avatar key={member.id} src={member.photoUrl} alt={member.name} />
+  ))}
+</AvatarGroup>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | - | Avatars to stack. |
+| `classes` | `Partial<AvatarGroupClasses>` | - | Style override hooks for MUI-style implementations. |
+| `component` | `React.ElementType` | `"div"` | Root element override. Use semantic list elements when names are meaningful content. |
+| `max` | `number` | `5` | Maximum visible avatars before showing surplus. |
+| `renderSurplus` | `(surplus: number) => ReactNode` | - | Custom surplus renderer. Keep accessible text. |
+| `spacing` | `"small" \| "medium" \| number` | `"medium"` | Overlap distance between avatars. |
+| `slots` | `{ surplus?: React.ElementType }` | - | Slot override for surplus item. |
+| `slotProps` | `{ surplus?: object }` | - | Props forwarded to surplus slot. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+| `total` | `number` | `children.length` | Total count when only a subset of avatars is rendered. |
+| `variant` | `"circular" \| "rounded" \| "square"` | `"circular"` | Shape passed to visible avatars and surplus. |
+
+## API choices made
+
+- Keep `max`, `total`, and `renderSurplus` because they solve the common virtualized/partial-render participant case.
+- Keep `spacing` as a token-mapped prop, but prefer named values over arbitrary numbers in product code.
+- Do not add `size` to this thin spec because parent `Avatar` already owns sizing. A product wrapper may pass size to children.
+- Use composition over an `items` prop so existing `Avatar` fallback, status, and image behavior stay intact.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Default | `children.length <= max` | Avatars overlap by a tokenized offset and share a border ring. |
+| Surplus | `total > max` | Last visible item displays surplus count with same size/shape as avatars. |
+| Hover | Pointer over interactive avatar/surplus | Raise z-index and show tooltip/popover only if the item is actionable. |
+| Focus-visible | Keyboard focus on interactive child | 2px focus ring, not clipped by overlap. |
+| Active | Press interactive surplus | Pressed state belongs to the surplus button/popover trigger. |
+| Disabled | Parent surface disabled | Avoid interactive affordances; avatars remain visible but muted only if the parent is disabled. |
+| Loading | Participants loading | Use skeleton avatars with fixed group width to avoid layout shift. |
+| Error | Failed participant load | Fall back to initials/default avatar; do not hide the person. |
+
+## Tokens consumed
+
+```
+--avatar-size-sm
+--avatar-size-md
+--avatar-size-lg
+--avatar-overlap-sm
+--avatar-overlap-md
+--color-bg-default
+--color-bg-subtle
+--color-text-primary
+--color-text-secondary
+--color-border-default
+--color-focus-ring
+--radius-full
+--radius-md
+```
+
+If these avatar tokens do not exist, map them to the existing size, spacing, border, and radius tokens instead of adding raw values.
+
+## Accessibility
+
+- If the group conveys meaningful membership, render as `<ul aria-label="참여자">` with each avatar in an `<li>`.
+- If visible names already appear adjacent to the group, the avatar images can be hidden from the accessibility tree to avoid duplicate announcements.
+- Each image avatar still needs correct `alt` text when it is the only name representation.
+- Surplus item needs an accessible name such as `aria-label="외 3명"`.
+- If surplus opens a popover, it must be a real `<button>` and the popover must list the hidden names.
+- Interactive avatars must meet 44x44 mobile touch target. For smaller visual avatars, extend hit area without changing visual size.
+
+## Layout rules
+
+| Rule | Value |
+| --- | --- |
+| Stacking | Later avatars sit visually above earlier avatars in LTR unless `direction` is explicitly reversed by a wrapper. |
+| Border ring | Use `--color-bg-default` or parent surface color so overlap remains legible. |
+| Overlap | About one quarter to one third of avatar size; use tokens. |
+| Surplus | Same size and shape as avatars; do not use a loose text label outside the stack. |
+| RTL | Reverse margin direction with logical CSS. |
+
+## Code example
+
+```tsx
+<AvatarGroup
+  component="ul"
+  aria-label="프로젝트 참여자"
+  max={4}
+  total={members.length}
+  renderSurplus={(count) => (
+    <button type="button" aria-label={`외 ${count}명 보기`}>
+      +{count}
+    </button>
+  )}
+>
+  {members.slice(0, 4).map((member) => (
+    <li key={member.id}>
+      <Avatar
+        src={member.photoUrl}
+        alt={member.name}
+        fallback={initials(member.name)}
+      />
+    </li>
+  ))}
+</AvatarGroup>
+```
+
+## Edge cases
+
+- **`max` less than 2**: clamp in product wrappers or warn in development. One visible avatar plus surplus is the minimum useful group.
+- **`total` exceeds rendered children**: surplus should use `total - visibleCount`, not hidden rendered children only.
+- **Duplicate names**: tooltip/popover should include secondary identifiers, such as team or email.
+- **Hundreds of participants**: render only visible avatars plus surplus; do not mount every avatar image.
+- **RTL**: overlap direction and z-index order must be reviewed visually.
+- **High contrast mode**: overlap boundaries must remain visible through border, not only shadow.
+- **Failed image loads**: each avatar follows `Avatar` fallback rules; group layout must not shift.
+
+## Don't
+
+- Don't use `AvatarGroup` when exact identity comparison is the primary task.
+- Don't make each avatar separately clickable inside a clickable parent row.
+- Don't show `+0` or a surplus item when all avatars are visible.
+- Don't use color alone to indicate online/away status in the group.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/AvatarGroup/AvatarGroup.d.ts`](../refs/mui/packages/mui-material/src/AvatarGroup/AvatarGroup.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/AvatarGroup/AvatarGroup.js`](../refs/mui/packages/mui-material/src/AvatarGroup/AvatarGroup.js)
+- Ant Design parent pattern: [`refs/ant-design/components/avatar/`](../refs/ant-design/components/avatar/)
+- shadcn-ui avatar source: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/avatar.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/avatar.tsx)
+- shadcn-ui group examples: [`refs/shadcn-ui/apps/v4/examples/base/avatar-group.tsx`](../refs/shadcn-ui/apps/v4/examples/base/avatar-group.tsx)
+- Accessibility baseline: [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+
+## Cross-reference
+
+- [examples/component-avatar.md](component-avatar.md)
+- [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md)

package/examples/component-avatar.md

@@ -0,0 +1,191 @@
+# `Avatar` — spec
+
+> Citing Ant Design `Avatar`, MUI `Avatar`, shadcn-ui `avatar`
+
+## Purpose
+
+A small visual representation of a user, group, or entity. Optimized for image, with deterministic fallbacks (initials, then default icon) when image is missing or fails to load.
+
+## Anatomy
+
+```
+[image]              [initials]          [default icon]      [group → cluster]
+   ◯                    ◯                    ◯                ◯◯◯+2
+                     "김민지"                                
+                       MJ                                     
+```
+
+## API
+
+```tsx
+<Avatar
+  src="/avatars/minji.jpg"
+  alt="김민지"
+  fallback="민지"
+  size="md"
+/>
+
+<AvatarGroup max={4} size="sm">
+  <Avatar src="..." alt="A" fallback="A" />
+  <Avatar src="..." alt="B" fallback="B" />
+  <Avatar src="..." alt="C" fallback="C" />
+  <Avatar src="..." alt="D" fallback="D" />
+  <Avatar src="..." alt="E" fallback="E" />
+</AvatarGroup>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string` | — | Image URL |
+| `alt` | `string` | — | Alt text. Required if `src` set. |
+| `fallback` | `string \| ReactNode` | first 1–2 chars of `alt` | Initials, emoji, or custom node when image fails/missing |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` or `number` | `"md"` | |
+| `shape` | `"circle" \| "rounded"` | `"circle"` | `rounded` for org / company avatars |
+| `bgColor` | `string` | derived from name hash | Background when showing fallback |
+| `status` | `"online" \| "offline" \| "away" \| "busy"` | — | Optional indicator dot |
+| `loading` | `boolean` | `false` | Show skeleton variant |
+
+### AvatarGroup
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max` | `number` | `5` | Visible avatars before "+N" |
+| `size` | same as Avatar | `"md"` | Applied to all children |
+| `direction` | `"row" \| "row-reverse"` | `"row-reverse"` | Stacking order (rightmost overlaps leftmost when row-reverse) |
+
+## Sizes
+
+| Size | Diameter | Font (initials) |
+| --- | --- | --- |
+| `xs` | 16px | 9px |
+| `sm` | 24px | 11px |
+| `md` (default) | 32px | 13px |
+| `lg` | 48px | 16px |
+| `xl` | 64px | 22px |
+| Hero (custom number) | 96px+ | 28px+ |
+
+## Fallback strategy
+
+```
+1. Try image (src)
+2. On image error → render initials (fallback)
+3. If no fallback or empty → render default user icon
+```
+
+Initials rules:
+- Latin: 1–2 uppercase chars from first name + last name (e.g., "Jane Smith" → "JS").
+- Korean: usually 1 char (성 — surname). "김민지" → "민" or "김". Pick one and be consistent. Many KR apps prefer the given name's first syllable (`민`) over surname (`김`).
+- Empty / unknown: default user icon.
+
+### Background color from name
+
+Hash the name to a stable color from a curated palette of 8–12 colors. Same name always gets same color across the app:
+
+```ts
+const colors = ['#EF4444', '#F59E0B', '#10B981', '#3B82F6', '#8B5CF6', '#EC4899', '#14B8A6', '#F97316'];
+const hash = name.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
+const bg = colors[hash % colors.length];
+```
+
+Pick colors with text readable in white.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Loading image | Skeleton placeholder, 4–6 sec timeout to fallback |
+| Image loaded | Cropped to circle, `object-fit: cover` |
+| Image failed | Fallback (initials or icon) |
+| With status indicator | Small dot at bottom-right (1/4 of diameter, 2px white border) |
+
+## Tokens consumed
+
+```
+--color-bg-subtle              (default fallback bg)
+--color-text-primary           (initials text on light fallback)
+--color-text-on-fallback        (initials text — usually white)
+--color-border-default          (status dot border, group offset)
+--color-success                 (online status)
+--color-text-tertiary           (offline)
+--color-warning                 (away)
+--color-error                   (busy / do-not-disturb)
+--radius-full                   (circle)
+--radius-md                     (rounded square)
+```
+
+## Group behavior
+
+```
+●●●●● +3
+```
+
+- Avatars overlap by 25–30% of their width (depending on size).
+- The "+N" item is the same size as avatars, with `--color-bg-subtle` background and `--color-text-primary` text.
+- Hover/focus on "+N" shows a Popover or Tooltip with the full list.
+- Direction: `row-reverse` is the default stacking order (rightmost on top), looks more natural in LTR.
+
+## Accessibility
+
+- `<img alt="...">` for image avatars. **Don't omit alt** — even if you think the image is decorative, the user's name matters for context.
+- Initials fallback should also include `aria-label="Jane Smith"` or wrap text in `aria-hidden="true"` if the avatar has a separate visible name nearby.
+- Default icon (no fallback): `aria-label="User"` or appropriate generic.
+- Avatar group "+N": `aria-label="3 more"` or `"3 more users"`.
+- Avatar inside a clickable card / button: don't make avatar separately clickable — let the parent handle.
+- For large hero avatars used as buttons (e.g., "change avatar"): `<button>` wrapper with proper label.
+
+## Code example
+
+```tsx
+// Standard user avatar
+<Avatar src={user.photoUrl} alt={user.name} fallback={initials(user.name)} />
+
+// Avatar with status (online indicator)
+<Avatar src={user.photoUrl} alt={user.name} fallback="민지" status="online" />
+
+// Avatar group
+<AvatarGroup max={3}>
+  {participants.map(p => (
+    <Avatar key={p.id} src={p.photoUrl} alt={p.name} fallback={initials(p.name)} />
+  ))}
+</AvatarGroup>
+
+// Org / company (rounded square)
+<Avatar shape="rounded" src={org.logoUrl} alt={org.name} fallback={org.name[0]} />
+
+// Hero size for profile screen
+<Avatar src={user.photoUrl} alt={user.name} size={120} />
+
+// Default fallback icon (user has no image, no name)
+<Avatar />
+```
+
+## Edge cases
+
+- **Image takes too long to load**: render fallback after 6s of waiting.
+- **Image returns 200 with broken bytes**: catch via `onerror`; render fallback.
+- **Image without `alt`**: lint should flag. Don't silently skip alt.
+- **Name with emoji**: "김민지 🌸" — strip emoji from initials computation, but keep in `alt`.
+- **All-Latin name in Korean app**: still works; initials draw from the Latin name as expected.
+- **Anonymous users**: use a stable random ID-based color but a default icon fallback (no initials).
+- **Cropping issues**: `object-fit: cover` + `object-position: center`. For face-aware cropping, depend on server-side image processing.
+- **Hi-DPI**: serve 2× resolution image for retina; use `srcset` if available.
+
+## Don't
+
+- Don't omit `alt`. Empty avatars have no semantic meaning.
+- Don't let initials wrap to two lines — use `overflow: hidden` and clip.
+- Don't use rectangular avatars for people. People are circles, organizations can be rounded squares.
+- Don't use the same fallback color for every avatar — distinguishable colors help readability.
+- Don't put status indicators on avatars where the status isn't meaningful (e.g., a list of past authors — they're not "online").
+- Don't wrap avatars in additional buttons for navigation if the parent row is already clickable.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/avatar/`](../refs/ant-design/components/avatar/) — `Avatar`, `Avatar.Group`. `shape="circle" | "square"`. Multi-size + scaling for groups.
+- MUI: [`refs/mui/packages/mui-material/src/Avatar/`](../refs/mui/packages/mui-material/src/Avatar/) — `Avatar` + `AvatarGroup`. Falls back to first letter of `children` text.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/avatar.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/avatar.tsx) — Radix Avatar primitive. Composition: `Avatar`, `AvatarImage`, `AvatarFallback`.
+
+## Cross-reference
+
+- [knowledge/i18n/korean-typography.md](../knowledge/i18n/korean-typography.md) — Korean initials conventions
+- [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md) — chat / conversation list avatars

package/examples/component-back-top.md

@@ -0,0 +1,123 @@
+# `BackTop` — spec
+
+> Synthesized from Ant Design `BackTop`. Floating "scroll to top" button that appears after the user scrolls past a threshold. Pairs with long-content pages.
+
+## When to use
+
+- Long content pages (articles, feeds, dashboards) where users scroll far.
+- Mobile particularly (more painful to scroll back).
+
+When NOT to use:
+- Short pages (< 1.5 viewport heights).
+- Scroll-snap pages where each snap is a "section" (different nav pattern).
+
+## Anatomy
+
+```
+[content]
+[content]
+[content]
+[content]
+[content]
+                       [↑]   ← appears after scroll past threshold
+[content]
+```
+
+## API
+
+```tsx
+<BackTop
+  visibilityHeight={400}
+  duration={500}
+  onClick={() => track("back-to-top")}
+>
+  <button className="back-top-button">↑</button>
+</BackTop>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `visibilityHeight` | `number` | `400` | Px scrolled before button appears |
+| `duration` | `number` | `450` | Ms for smooth-scroll-up animation |
+| `target` | `() => HTMLElement` | window | Scrollable container |
+| `onClick` | `() => void` | — | Custom callback |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Hidden (scroll < threshold) | Not rendered / fade-out |
+| Visible | Floating button bottom-right; subtle shadow |
+| Hover | Subtle bg shift |
+| Pressed | Scrolling animation in progress |
+
+## Position + tokens
+
+Bottom-right anchor; safe-area-aware for iOS.
+
+```
+--back-top-bg
+--back-top-fg
+--back-top-shadow
+--back-top-size                  (40-48px)
+--space-md                       (offset from edges)
+--motion-medium                  (fade + scroll)
+--ease-out
+--z-fab
+```
+
+## Accessibility
+
+- `<button aria-label="페이지 맨 위로 이동">`.
+- Smooth scroll respects `prefers-reduced-motion` (instant scroll if reduced).
+- Focus visible.
+- Keyboard: Home key also scrolls to top in many browsers; BackTop is a visual affordance, not a replacement.
+
+## Code example
+
+```tsx
+<BackTop visibilityHeight={600}>
+  <button
+    className="back-top-button"
+    aria-label="맨 위로"
+  >
+    <ArrowUpIcon />
+  </button>
+</BackTop>
+```
+
+## Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Replace smooth scroll with instant jump */
+}
+```
+
+JS:
+```js
+const reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
+window.scrollTo({ top: 0, behavior: reduced ? "auto" : "smooth" });
+```
+
+## Korean conventions
+
+- 맨 위로 / 위로 / 처음으로 — typical labels (해요체 OK).
+- For Korean B2C: chevron arrow icon usual; some apps use full-text "맨 위로" in narrow strip.
+
+## Don't
+
+- Don't show BackTop on short pages — visual noise.
+- Don't omit `aria-label`.
+- Don't override scroll behavior without reduced-motion check.
+- Don't auto-fire scroll without user click.
+
+## References
+
+- Ant: [`BackTop`](../refs/ant-design/components/back-top)
+- Native: `window.scrollTo({ behavior: "smooth" })`
+
+## Cross-reference
+
+- [`examples/component-float-button.md`](component-float-button.md)
+- [`examples/component-affix.md`](component-affix.md) — sticky positioning sibling