@design-ai/cli 4.55.0

package/examples/component-outlined-input.md

@@ -0,0 +1,145 @@
+# `OutlinedInput` — spec
+
+> Synthesized from MUI `OutlinedInput`. The outlined-border input variant — clearer affordance than filled or underline. Default for most product UIs.
+
+## When to use
+
+- Default form input for product UIs.
+- When users need a clear "this is a field" affordance (vs filled which can blend into card backgrounds).
+- For dense forms with many fields, consider `FilledInput` (less visual noise) — but accessibility default is outlined.
+
+## Anatomy
+
+```
+┌── Label ─────────────┐
+│ Input value          │   ← label notches the border on focus
+└──────────────────────┘
+```
+
+## API
+
+```tsx
+<FormControl variant="outlined" fullWidth>
+  <FormLabel htmlFor="email">이메일</FormLabel>
+  <OutlinedInput
+    id="email"
+    type="email"
+    value={email}
+    onChange={(e) => setEmail(e.target.value)}
+    placeholder="hong@example.com"
+    startAdornment={<InputAdornment position="start"><EmailIcon /></InputAdornment>}
+  />
+</FormControl>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | — | Controlled / uncontrolled |
+| `onChange` | `(e) => void` | — | Change handler |
+| `type` | `string` | `'text'` | HTML input type |
+| `placeholder` | `string` | — | Placeholder (NOT a substitute for label) |
+| `startAdornment` | `ReactNode` | — | Leading content (icon, prefix) |
+| `endAdornment` | `ReactNode` | — | Trailing content (clear button, unit) |
+| `multiline` | `boolean` | `false` | Render as textarea |
+| `rows` | `number` | — | Multi-line height |
+| `maxRows` / `minRows` | `number` | — | Auto-resize bounds |
+| `disabled` | `boolean` | `false` | |
+| `error` | `boolean` | inherited | From parent FormControl |
+| `fullWidth` | `boolean` | inherited | |
+| `inputProps` | `InputHTMLAttributes` | — | Pass-through to native input (autoComplete, inputMode, pattern) |
+| `inputRef` | `Ref` | — | Ref to native input |
+| `notched` | `boolean` | derived | Notch label-cutout (auto when label is visible) |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | 1px border-default |
+| Hover | border-strong |
+| Focus | 2px brand border, label fg-primary |
+| Error | 2px error border, label fg-error |
+| Disabled | muted border, muted fg |
+| Read-only | same as default but no caret |
+
+## Tokens consumed
+
+```
+--input-border-default
+--input-border-hover
+--input-border-focus      /* brand */
+--input-border-error
+--input-bg                /* surface */
+--input-radius
+--input-padding-x
+--input-min-height-40     /* touch-friendly */
+--input-min-height-32     /* small */
+--font-size-body
+--space-sm                /* gap to adornment */
+```
+
+## Accessibility
+
+- Pair with `FormLabel` via `id` ↔ `htmlFor`.
+- For required: `aria-required="true"` (in addition to FormControl `required` for the visual asterisk).
+- For error: `aria-invalid="true"` + `aria-describedby` matching FormHelperText `id`.
+- Touch target: 40px min (default `medium` size). For dense forms `small` (32px) — desktop only.
+- `inputProps={{ autoComplete: '...' }}` — set semantically (`email`, `name`, `tel`, `address-line1`, etc.) so password managers and autofill work.
+
+## Edge cases
+
+- **Korean IME composition** — `onChange` fires on each keystroke including IME composition characters. For "search-as-you-type" scenarios that should wait for committed input, use `onCompositionEnd`. Cite [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md).
+- **Long values** — input scrolls horizontally inside the field. For multi-line, set `multiline maxRows={4}`.
+- **Clear button** — not built-in. Add via `endAdornment` with a small IconButton; show only when `value.length > 0`.
+- **Password visibility toggle** — same pattern: `endAdornment` IconButton that toggles `type` between `password` and `text`.
+
+## Code example
+
+```tsx
+function PasswordField({ value, onChange, error }) {
+  const [show, setShow] = useState(false);
+
+  return (
+    <FormControl error={!!error} fullWidth>
+      <FormLabel htmlFor="pw">비밀번호</FormLabel>
+      <OutlinedInput
+        id="pw"
+        type={show ? 'text' : 'password'}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        inputProps={{ autoComplete: 'current-password', minLength: 8 }}
+        endAdornment={
+          <InputAdornment position="end">
+            <IconButton
+              aria-label={show ? '비밀번호 숨기기' : '비밀번호 보기'}
+              onClick={() => setShow(!show)}
+              edge="end"
+            >
+              {show ? <VisibilityOffIcon /> : <VisibilityIcon />}
+            </IconButton>
+          </InputAdornment>
+        }
+      />
+      <FormHelperText>{error ?? '8자 이상, 영문 + 숫자 + 특수문자'}</FormHelperText>
+    </FormControl>
+  );
+}
+```
+
+## Don't
+
+- Don't use `placeholder` as the only label — disappears on focus, accessibility issue.
+- Don't omit `autoComplete` — autofill won't work, slowing user-friction in onboarding.
+- Don't toggle `disabled` based on transient state without restoring focus on re-enable.
+
+## References
+
+- MUI: [`OutlinedInput`](../refs/mui/packages/mui-material/src/OutlinedInput/) + [`InputBase`](../refs/mui/packages/mui-material/src/InputBase/)
+
+## Cross-reference
+
+- [`component-input.md`](component-input.md)
+- [`component-input-base.md`](component-input-base.md)
+- [`component-filled-input.md`](component-filled-input.md)
+- [`component-input-adornment.md`](component-input-adornment.md)
+- [`component-form-control.md`](component-form-control.md)
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md)

package/examples/component-page-transition.md

@@ -0,0 +1,281 @@
+<!-- hand-written -->
+# `PageTransition` (custom — route-level animation wrapper) — spec
+
+> Wraps the route outlet of an SPA to animate transitions between pages. One component handles cross-fade, slide-in, and shared-element variants. Pairs with [`knowledge/motion/app-loading-sequences.md`](../knowledge/motion/app-loading-sequences.md) and [`knowledge/motion/choreography-depth.md`](../knowledge/motion/choreography-depth.md).
+
+## Purpose
+
+- Smooth transitions between routes without per-page boilerplate.
+- One opinion per app (cross-fade vs slide vs hero), not per-screen ad-hoc choices.
+- Reduced-motion safe.
+- Compatible with React Router, TanStack Router, Next.js App Router.
+
+Without this: route change is an instant DOM swap. Reads as a page reload, breaks spatial sense.
+
+## Anatomy
+
+```
+<RootLayout>
+  <Header />
+  <PageTransition variant="fade">
+    {/* current route */}
+    <Outlet />
+  </PageTransition>
+  <Footer />
+</RootLayout>
+```
+
+Or for slide-style native iOS feel:
+
+```
+<PageTransition variant="slide" direction={navDirection}>
+  <Outlet />
+</PageTransition>
+```
+
+## API
+
+```tsx
+<PageTransition
+  variant="fade"          // "fade" | "slide" | "hero"
+  routeKey={pathname}     // change → trigger transition
+  direction="forward"     // for slide variant
+  duration={200}
+  reducedMotionFallback="instant"  // "instant" | "fade-only"
+>
+  {children}
+</PageTransition>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"fade" \| "slide" \| "hero"` | `"fade"` | Transition style |
+| `routeKey` | `string` | — | Unique key per route (typically pathname); change = transition |
+| `direction` | `"forward" \| "back"` | `"forward"` | Slide direction (slide variant only) |
+| `duration` | `number` | `200` | Ms; capped at 300 even if higher passed |
+| `easing` | `string` | `"ease-out"` | CSS easing (typically `var(--ease-out)`) |
+| `reducedMotionFallback` | `"instant" \| "fade-only"` | `"fade-only"` | What to do when user prefers reduced motion |
+| `onTransitionEnd` | `() => void` | — | Fires after exit + enter complete |
+| `children` | `ReactNode` | — | Current route content |
+
+## Variants
+
+### `fade` (default)
+
+200ms cross-fade. Calm, content-led. Default for content apps (docs, dashboards, forms).
+
+```css
+.page--enter { opacity: 0; transform: translateY(8px); }
+.page--enter-active { opacity: 1; transform: translateY(0); transition: 200ms ease-out; }
+.page--exit { opacity: 1; }
+.page--exit-active { opacity: 0; transition: 150ms ease-out; }
+```
+
+### `slide` (native iOS feel)
+
+New page slides in from right (forward) or left (back). Old page slides off the opposite side.
+
+```
+forward:    [old]────► offscreen left   [new]◄──── from right
+back:       [old]────► offscreen right  [new]◄──── from left
+```
+
+For slide direction tracking, expose it via router state (e.g. `useNavigationDirection()` hook returning `"forward" | "back"`).
+
+### `hero` (shared element)
+
+Uses View Transitions API or Framer Motion `layoutId`. An element on outgoing page morphs into an element on incoming page.
+
+```tsx
+// On screen A:
+<motion.img layoutId="user-avatar-42" src={avatar} />
+
+// On screen B (detail view):
+<motion.img layoutId="user-avatar-42" src={avatar} />
+// Same id = morph between positions
+```
+
+For browser-native (Chrome / Edge / Safari TP):
+
+```css
+.user-avatar { view-transition-name: user-avatar-42; }
+```
+
+```js
+document.startViewTransition(() => {
+  navigate("/users/42");
+});
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| `idle` | Current route fully visible |
+| `exiting` | Outgoing page transitioning out (opacity fade or x-translate) |
+| `entering` | Incoming page transitioning in |
+| `done` | New route fully visible; `onTransitionEnd` fires |
+
+`exiting` and `entering` overlap during cross-fade; for slide they sequence.
+
+## Tokens consumed
+
+```
+--motion-fast      (150ms exit)
+--motion-medium    (200ms enter)
+--motion-slow      (300ms slide)
+--ease-out         (default)
+--ease-in-out      (slide)
+--space-sm         (translate-Y for fade)
+```
+
+## Behavior rules
+
+- **Don't transition on initial mount** — first render is not a navigation. Watch for `routeKey` change after mount only.
+- **Don't transition between hash changes** on same path (`/page#a` → `/page#b`).
+- **Cancel previous transition** if route changes mid-transition (rapid back-tap during animation). Snap to new route.
+- **Maintain scroll position**: page-transition wrapper does NOT manage scroll; router does. But the wrapper must not interfere (e.g., `overflow: hidden` on root breaks scroll-restoration).
+
+## Reduced motion
+
+```tsx
+const reduced = useReducedMotion();
+const effectiveVariant = reduced
+  ? (reducedMotionFallback === "instant" ? null : "fade")
+  : variant;
+```
+
+| Setting | Behavior |
+| --- | --- |
+| `instant` | No transition; instant DOM swap |
+| `fade-only` (default) | Cross-fade at duration 100ms regardless of variant; no translate / slide |
+
+Slide and hero variants both downgrade to fade-only — translation triggers vestibular issues.
+
+## Implementation — Framer Motion
+
+```tsx
+import { AnimatePresence, motion } from "framer-motion";
+
+function PageTransition({ children, routeKey, variant = "fade", duration = 200 }: Props) {
+  const reduced = useReducedMotion();
+
+  const variants = reduced
+    ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }
+    : variantsByName[variant];
+
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.div
+        key={routeKey}
+        initial={variants.initial}
+        animate={variants.animate}
+        exit={variants.exit}
+        transition={{ duration: duration / 1000, ease: "easeOut" }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  );
+}
+
+const variantsByName = {
+  fade: {
+    initial: { opacity: 0, y: 8 },
+    animate: { opacity: 1, y: 0 },
+    exit: { opacity: 0, y: -8 },
+  },
+  slide: {
+    initial: { opacity: 0, x: 24 },
+    animate: { opacity: 1, x: 0 },
+    exit: { opacity: 0, x: -24 },
+  },
+  // hero handled via layoutId on individual elements; this wrapper just cross-fades the rest
+  hero: {
+    initial: { opacity: 0 },
+    animate: { opacity: 1 },
+    exit: { opacity: 0 },
+  },
+};
+```
+
+## Implementation — View Transitions API (modern web)
+
+```tsx
+function PageTransition({ children, routeKey }: Props) {
+  const previousKey = useRef(routeKey);
+
+  useLayoutEffect(() => {
+    if (previousKey.current === routeKey) return;
+    if (!document.startViewTransition) {
+      previousKey.current = routeKey;
+      return;
+    }
+    document.startViewTransition(() => {
+      previousKey.current = routeKey;
+      // React already updated; this just signals the browser to capture before/after
+    });
+  }, [routeKey]);
+
+  return <>{children}</>;
+}
+```
+
+```css
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 200ms;
+  animation-timing-function: var(--ease-out);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation: none;
+  }
+}
+```
+
+## Korean app convention
+
+- **Mobile webview / hybrid app**: prefer `slide` variant — matches native iOS / Android feel users expect from Toss / KakaoBank.
+- **Desktop web (toss.im, naver.com)**: `fade` is standard.
+- **Marketing landing pages**: skip PageTransition entirely; full reload feel is fine.
+
+## Accessibility
+
+- `aria-live="polite"` on the page region so screen readers announce route change. (Don't use `assertive`; that interrupts.)
+- After transition: focus moves to `<h1>` of new page (router-level concern, not PageTransition's).
+- `prefers-reduced-motion`: enforce via the variant downgrade above.
+- For long transitions (>250ms), risk of focus loss; keep transitions short.
+
+## Edge cases
+
+- **Modal-on-route**: don't apply page transition when the route change is just opening a modal (use `<Outlet />` only on actual page changes; modals stack above).
+- **Tab-style navigation**: tabs that swap content within the same route should NOT trigger PageTransition. Use a separate `<Tabs>` animation.
+- **Programmatic navigation during transition**: cancel current transition; new one wins. Framer Motion's `mode="wait"` handles this.
+- **Server-rendered first paint**: first hydration must not trigger transition. Use `initial={false}` (Framer Motion) or check `previousKey.current` (View Transitions).
+- **Memory of scroll position**: each route should restore its scroll. PageTransition itself doesn't scroll; do this via router scroll-restoration.
+
+## Don't
+
+- Don't use slide variant on desktop wide screens — large translation feels heavy.
+- Don't transition every route — landing → app, login → dashboard, payment success — sometimes reset feels right.
+- Don't apply PageTransition twice (e.g., wrapping both layout + page). Pick one level.
+- Don't run more than 300ms — feels slow on rapid-tap navigation.
+- Don't animate `width`/`height` of the wrapper — causes layout thrash.
+
+## References
+
+Patterns drawn from:
+- React Router v6 + Framer Motion AnimatePresence patterns
+- Next.js 14 App Router + View Transitions API
+- React Native Stack Navigator transition presets
+
+## Cross-reference
+
+- [`knowledge/motion/app-loading-sequences.md`](../knowledge/motion/app-loading-sequences.md) — when to use which variant
+- [`knowledge/motion/choreography-depth.md`](../knowledge/motion/choreography-depth.md) — shared-element / hero patterns
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — duration tiers
+- [`examples/component-loading-sequence.md`](component-loading-sequence.md) — splash before first route
+- [`examples/component-scroll-reveal.md`](component-scroll-reveal.md) — within-page motion

package/examples/component-pagination.md

@@ -0,0 +1,226 @@
+# `Pagination` — spec
+
+> Citing Ant Design `Pagination`, MUI `Pagination`, shadcn-ui `pagination`
+
+## Purpose
+
+Lets users navigate large result sets in chunks. Three modes — pick the right one for context:
+
+| Mode | Use |
+| --- | --- |
+| **Numbered pagination** | Tables, search results, content where users want to know position. |
+| **Cursor-based "Load more"** | Feeds, social timelines, infinite content. |
+| **Infinite scroll** | Engagement-driven feeds (Instagram, TikTok). See [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md). |
+
+This spec covers numbered pagination + Load more. Infinite scroll is a list pattern, not a "Pagination component".
+
+## Anatomy — numbered
+
+```
+[‹]  [1]  [2]  [3]  4  [5]  ...  [12]  [›]              총 142개
+                ↑ active                  Page size: [20 ▾]   (1–20 of 142)
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Previous (‹) | yes | Disabled on page 1 |
+| Page numbers | yes | Subset shown with ellipsis for many pages |
+| Next (›) | yes | Disabled on last page |
+| Page size selector | optional | Common in tables, rare in mobile |
+| Total count display | optional | "총 142개" / "1–20 of 142" |
+| Jump to page | optional | Input field to type a page number (desktop only) |
+
+## API
+
+```tsx
+<Pagination
+  page={currentPage}
+  pageSize={20}
+  total={142}
+  onPageChange={setPage}
+  onPageSizeChange={setPageSize}
+  pageSizeOptions={[10, 20, 50, 100]}
+  showTotal
+  showJumper
+  siblingCount={1}
+  boundaryCount={1}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `page` | `number` | — | Current page (1-indexed) |
+| `pageSize` | `number` | `20` | Items per page |
+| `total` | `number` | — | Total item count (server-provided) |
+| `onPageChange` | `(page: number) => void` | — | Fires on navigation |
+| `onPageSizeChange` | `(size: number) => void` | — | Fires on size change |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Options in size selector |
+| `showSizeChanger` | `boolean` | `true` | Show page size dropdown |
+| `showTotal` | `boolean` | `true` | Show total count |
+| `showJumper` | `boolean` | `false` | Show "go to page X" input (desktop only) |
+| `siblingCount` | `number` | `1` | Pages shown on each side of current (e.g., 4 [5] 6) |
+| `boundaryCount` | `number` | `1` | Pages always shown at start/end (e.g., [1] ... [12]) |
+| `simple` | `boolean` | `false` | Compact mobile mode: just `< 5/12 >` |
+
+## Numbered display algorithm
+
+For `total=142, pageSize=20, currentPage=5, siblingCount=1, boundaryCount=1`:
+
+```
+[‹]  [1]  ...  [4]  [5]  [6]  ...  [8]  [›]
+       ↑boundary  ↑siblings   ↑boundary
+```
+
+Pages: `1, ..., 4, 5, 6, ..., 8`.
+
+When near the start: `[1] [2] [3] [4] ... [8]`.
+When near the end: `[1] ... [5] [6] [7] [8]`.
+When few pages (≤ 7): show all without ellipsis.
+
+## Variants
+
+### `simple` mode (mobile)
+
+```
+[‹]  5 / 12  [›]
+```
+
+Just prev/next + position display. Avoids cramped numbered buttons on mobile.
+
+### Compact (no size changer, no total)
+
+```
+[‹]  [1]  [2]  [3]  ...  [12]  [›]
+```
+
+For minimal UIs where the count and page size are not user-relevant.
+
+### Load more variant
+
+```
+... existing items ...
+[Load more (122 remaining)]
+```
+
+Single button at the bottom of the list. Replaces numbered pagination for feed-like content.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default page button | Border `--color-border-default`, text `--color-text-primary` |
+| Hover | Border `--color-border-strong`, bg `--color-bg-subtle` |
+| Active (current page) | Background `--color-primary-default`, text `--color-on-primary` |
+| Disabled (prev on page 1, next on last) | Opacity 0.4, no events |
+| Focus-visible | 2px ring |
+
+## Sizes
+
+| Size | Button height | Font |
+| --- | --- | --- |
+| `sm` | 28px | 13px |
+| `md` (default) | 32px | 14px |
+| `lg` | 40px | 16px |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle           (hover)
+--color-primary-default     (active page bg)
+--color-on-primary          (active page text)
+--color-text-primary
+--color-text-secondary      (disabled)
+--color-border-default
+--color-border-strong
+--color-focus-ring
+--space-xs, --space-sm
+--radius-md                 (button corners) or radius-full (pill style)
+--font-size-sm
+```
+
+## Accessibility
+
+- `<nav role="navigation" aria-label="Pagination">` wraps the controls.
+- Each page button is a `<button>` (or `<a href="?page=N">` for crawlable pages).
+- Current page: `aria-current="page"` on the button. Don't use `disabled` on the current page — the user might want to click it (no-op, but accessible).
+- Previous/Next buttons:
+  - `aria-label="이전 페이지"` / `"다음 페이지"`
+  - `disabled` when at boundary
+- Page size selector: standard Select with `aria-label="페이지당 항목 수"`.
+- Total count: live region `aria-live="polite"` so screen reader announces when it changes (e.g., after filtering).
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach individual buttons in order |
+| `Enter` / `Space` | Activate focused button |
+| Arrow keys | NOT used — user tabs through |
+
+## URL sync (highly recommended)
+
+Pagination should sync to URL:
+
+```
+/transactions?page=5&size=20
+```
+
+Benefits:
+- Browser back/forward works.
+- Shareable links to specific pages.
+- Refresh preserves position.
+- SEO: search crawlers see all pages.
+
+Implementation: read from `useSearchParams` in React Router / Next.js. Update query on `onPageChange`.
+
+## Korean copy
+
+| English | Korean |
+| --- | --- |
+| Previous | 이전 |
+| Next | 다음 |
+| First | 처음 |
+| Last | 마지막 |
+| Page X of Y | X 페이지 / 총 Y 페이지 |
+| Go to page | 페이지로 이동 |
+| 1–20 of 142 | 142개 중 1–20 |
+| Items per page | 페이지당 항목 수 |
+| Show N | N개씩 보기 |
+
+## Edge cases
+
+- **Only 1 page**: hide pagination entirely. Don't render an empty navigation.
+- **Empty results**: render the empty state instead of page 1 with no items.
+- **Invalid page in URL**: clamp to valid range (`?page=999` with 12 pages → page 12). Surface to user with a toast: "페이지 999는 존재하지 않아 마지막 페이지로 이동했습니다".
+- **Page size change reset**: when user changes page size, reset to page 1 (otherwise, current page might no longer exist).
+- **Filter change reset**: when filters change, reset to page 1.
+- **Server returns total=null** (cursor pagination, unknown total): use Load More variant instead.
+- **Very large totals (10,000+ pages)**: jumper input is essential. Numbered pagination becomes unwieldy past ~100 pages.
+- **Fast-clicking through pages**: debounce 100ms or cancel previous request on new click. Don't blast 5 requests.
+
+## Don't
+
+- Don't show "Page 1 of 1" — hide the component.
+- Don't disable the active page button. Use `aria-current` instead.
+- Don't put pagination ABOVE the list. Always below (and optionally also above for very long pages, like > 50 items per page).
+- Don't auto-scroll to top on page change. Let the user choose. (Exception: if pagination is far below the fold, auto-scroll **into view** is OK.)
+- Don't combine numbered pagination + infinite scroll.
+- Don't lose scroll position on page change for inline tables (where pagination is at the table footer).
+
+## References
+
+- Ant Design: [`refs/ant-design/components/pagination/`](../refs/ant-design/components/pagination/) — most exhaustive: `simple`, `total`, `showSizeChanger`, `showJumper`, `itemRender`, `disabled`, `responsive`. Common in admin tables.
+- MUI: [`refs/mui/packages/mui-material/src/Pagination/`](../refs/mui/packages/mui-material/src/Pagination/) — `Pagination` + `PaginationItem`. Cleaner API, fewer features.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/pagination.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/pagination.tsx) — primitive only (`Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis`). Compose for behavior. **No built-in pagination logic** — pair with TanStack Table or your own state.
+
+API choices made:
+- **`siblingCount` and `boundaryCount` exposed**: lets the consumer tune the numbered display algorithm without overriding rendering.
+- **`simple` mode** for mobile: separate concept, not just CSS — different ARIA semantics (a single button group with status text vs. a list of page buttons).
+- **`showJumper` opt-in, off by default**: useful for power users (admin, analytics), noise for consumers.
+- **No `itemRender` prop** (Ant has it): too much surface area. If you need custom rendering, compose `PaginationItem` manually.
+
+## Cross-reference
+
+- [examples/component-table.md](component-table.md) — pagination at the table footer
+- [knowledge/patterns/list-and-feed.md](../knowledge/patterns/list-and-feed.md) — Load More vs infinite scroll vs pagination