Pagination

구조는 당근 SEED Pagination(Apache-2.0)을 따른다 — "여러 페이지로 나뉜 콘텐츠를 탐색할 수 있도록 돕는 네비게이션 컴포넌트" 로, 이전 · 다음 버튼 · 쪽 번호 · 생략. 번호 · 화살표 칸 40 × 40 을 사이 없이 잇고, 지금 쪽은 짙게 채우며, 칸 수는 화면 폭으로 고정이다(480 이상 9칸 · 미만 7칸). 값은 groo 토큰이고, SEED 와 다른 자리는 맨 아래 "SEED 와 다른 점" 에 적었다(2026-10-04 사용자 결정). 옛 Pagination 스펙(shadcn — 지금 쪽 테두리 · 칸 사이 4 · 이전 · 다음 글자)을 대신한다.

수치 원본은 pagination.yaml(넘김 줄)과 infinite-list.yaml(폰의 끝없이 불러오기 — 목록 끝 자리)이다. 수치 표 자리([표: …])와 그림 자리([그림: …])는 사이트가 그 파일로 그린다 — GitHub 에서는 그 파일 · 그림 코드로 가는 링크로 보인다.

직접 골라 보기제목 링크 복사

전체 쪽 수 · 지금 쪽 · 화면 폭(480 이상 · 미만)을 고르면 스펙대로 그린 줄과 그 코드가 바뀐다. 실제로 누르면 칸 자리는 그대로이고 생략(…)만 옮겨 간다. 첫 · 마지막 쪽에서는 화살표 자리가 비고, 키보드로 끝 쪽에 닿으면 초점이 지금 쪽 번호로 옮겨 간다.

import { useSearchParams } from "react-router-dom"
import { Pagination } from "@/components/ui/pagination"

const [params] = useSearchParams()
const page = Number(params.get("page") ?? 1)

<section ref={listRef} aria-labelledby="card-list-title">…</section>
{/* 칸은 링크 — 쪽마다 방문 기록이 쌓여 뒤로 가기가 앞 쪽으로 온다 */}
<Pagination totalPages={12} page={page} getHref={(p) => `?page=${p}`} scrollTarget={listRef} aria-label="카드 혜택 페이지 탐색" />

Anatomy제목 링크 복사

부위

Properties제목 링크 복사

칸제목 링크 복사

번호 · 화살표 · 생략 칸은 모두 40 × 40 이고 사이 없이 붙는다. 번호는 14 / 19 · 700 · fg-neutral · 숫자 폭을 같게, 화살표는 아이콘만(chevron 16), 모서리는 8 이다. 바탕은 누를 때 · 마우스를 올릴 때만 보인다.

쪽 번호

번호 글자

이전 · 다음

넘김 줄

지금 쪽제목 링크 복사

지금 쪽은 짙은 채움(bg-neutral-inverted) + 반전 글자(fg-neutral-inverted)다 — 다크에서는 밝은 칸에 짙은 글자다. 브랜드 색으로 칠하지 않는다. 보조 기술에는 aria-current="page" 로 알린다.

지금 쪽

칸 수 — 9 · 7제목 링크 복사

칸 수는 화면 폭으로 고정이다 — 480 이상 9칸, 480 미만 7칸(화살표 둘 포함). 쪽이 바뀌어도 줄의 폭과 칸 자리는 그대로이고 생략(…)만 옮겨 간다. 전체 쪽이 칸 수보다 적으면 모든 번호를 보인다.

7칸의 가운데 구간에서는 첫 · 마지막 번호가 없다(SEED) — 앞뒤 쪽을 바로 고르는 것을 먼저 둔다.

칸 수

끝 쪽 — 빈 칸제목 링크 복사

첫 쪽에서는 이전 자리에, 마지막 쪽에서는 다음 자리에 40 빈 칸을 둔다 — 막힌 화살표를 그리지 않고 자리만 지킨다(SEED). 키보드로 "다음" 을 눌러 마지막 쪽에 닿으면 누르던 버튼이 빈 칸이 되므로, 초점을 지금 쪽 번호로 옮긴다(초점이 화면 맨 앞으로 떨어지지 않게).

누르는 영역 — 40 의 예외제목 링크 복사

칸은 40 이다 — 누르는 영역은 위아래만 44 로 넓히고(보이지 않는 여백 2 씩), 옆은 칸 폭 40 그대로다. 칸이 붙어 있어 옆으로 넓히면 이웃 칸과 겹친다. 이것은 v106 "누르는 영역은 늘 44 이상" 의 예외다 — groo 폰은 끝없이 불러오기라 넘김 줄은 주로 마우스로 누른다(사용자 결정 2026-10-04). WCAG 2.5.8(AA, 24) 은 통과하고 2.5.5(AAA, 44) 는 옆으로 미달이다.

State제목 링크 복사

상태 — 다른 쪽

상태 — 지금 쪽

모션

Guidelines제목 링크 복사

언제 쪽을 나누나제목 링크 복사

동작 상황으로 고른다 — "늘 데스크톱은 Pagination" 이 아니다(2026-10-23 사용자 결정 — 가계부 다시 짜기 https://claude.ai/artifact/CCAra9mCf1q77pqgM1D2xc 5A). 사용자 말: "데스크톱처럼 쪽 단위로 훑는 자리는 Pagination 이 좋을 수 있지만, 스크롤로 내려가는 환경(폰 · 긴 목록)은 끝에 닿으면 저절로 더 불러오는 쪽이 동작상 자연스럽다. 가계부처럼 달이 자연스러운 묶음인 목록은 달 이동이 쪽 넘김이다."

1쪽 이하면 넘김 줄을 그리지 않는다. 같은 목록이 폰에서는 끝없이 불러오고 데스크톱에서는 쪽을 나눌 수 있다(지금 카드 혜택과 같다). 이 표는 고르는 참고다 — 화면마다 동작으로 고른다. 화면 틀 쪽 표는 DESIGN.md Layout "화면 틀" 의 "목록 넘기기".

쪽을 넘기면제목 링크 복사

쪽을 넘기면 목록의 위 끝이 화면 위에 오게 스크롤하고, 보조 기술에 "2페이지, 전체 12페이지" 를 한 번 알린다(숨은 상태 글). 초점은 누른 칸에 남는다 — 끝 쪽에 닿아 그 칸이 빈 칸이 되면 지금 쪽 번호로 옮긴다. 넘기는 동안 목록은 Skeleton 의 "다른 내용을 받을 때" 를 따른다(바뀔 줄만 기다리고, 옛 쪽의 줄을 남기지 않는다).

쪽은 주소에 — 칸은 링크제목 링크 복사

웹 화면의 목록은 쪽을 주소에 둔다(?page=3) — 칸이 링크(<a>)라 새 탭에서 열고 주소를 나눌 수 있고, 뒤로 가기가 앞 쪽으로 돌아온다(쪽마다 방문 기록이 쌓인다). 주소가 없는 자리(대화상자 · 시트 안 목록)만 칸이 버튼이다. 어느 쪽이든 모양 · 키보드 · 이름은 같다.

폰은 끝없이 불러오기제목 링크 복사

768 미만의 긴 목록은 쪽을 나누지 않는다 — 목록 끝이 화면 아래에서 300 안으로 오면 다음 쪽을 받아 아래에 잇는다. 목록 맨 아래 한 자리가 지금 상태를 보인다(infinite-list.yaml).

폰 목록은 둘로 가른다(2026-10-22 사용자 결정 6B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX) — 목록 화면의 긴 목록은 끝없이 불러온다(위). 카드 · 띠 안의 몇 줄 미리보기는 머리의 "전체 보기" 로 목록 화면에 보낸다(Card 의 머리 동작). 목록 끝에 줄을 덧붙이는 "더 보기" 버튼은 두지 않는다 — 끝없이 불러오기와 두 벌이 된다. 데스크톱은 쪽 넘김이다. 첫 쪽을 못 불러오면 목록 자리가 Result Section 의 실패다. 끝없이 불러오는 목록이 길어져도 맨 위로 가는 길은 상단 바 · 탭 바(지금 탭 다시 누르기)가 맡는다.

목록 끝 자리

목록 끝 자리 — 공통

글 · 이름제목 링크 복사

넘김 줄의 이름은 "페이지 탐색"(목록이 둘 이상이면 "카드 혜택 페이지 탐색" 처럼), 칸 이름은 "N페이지", 화살표는 "이전 페이지" · "다음 페이지" 다(SEED 문구). 영어("pagination" · "More pages" · "Page x of y")를 쓰지 않는다.

코드제목 링크 복사

레시피 recipes/shadcn/components/ui/pagination.tsx 를 쓴다. 아래 미리보기는 스펙 값으로 그린 모습이다.

• Pagination — 넘김 줄(<nav aria-label="페이지 탐색">). totalPages(1 이하면 그리지 않는다) · page · defaultPage(1) · onPageChange(page, { reason })(reason — "page-item" · "previous" · "next") · getHref(page)(주면 칸이 링크 — 쪽이 주소에 있을 때) · scrollTarget(목록 상자 — 쪽이 바뀌면 그 위 끝으로 스크롤) · disabled · aria-label. 칸 수는 breakpoint-sm(480)으로 9 · 7 을 스스로 고른다. 쪽이 바뀌면 숨은 상태 글로 "N페이지, 전체 M페이지" 를 알리고, 끝 쪽에서 초점을 지금 쪽 번호로 옮긴다.
• paginationItems(page, totalPages, slots) — 칸 배열({ type: "page" | "ellipsis" | "previous" | "next" | "empty", page? })을 돌려주는 규칙 함수. 앱도 같은 규칙으로 쓴다.
• InfiniteListEnd — 폰 목록 끝 자리. status("loading" · "error" · "end") · onRetry · endText(기본 "모두 봤어요.") · onReachEnd(목록 끝이 300 안으로 오면 한 번 부른다 — status 가 "loading" 이면 "다음 쪽이 있다" 는 뜻이다. 목록이 자라거나 300 밖으로 나갔다 다시 오면 또 부를 수 있고, "error" · "end" 이거나 "다시 시도" 를 누른 직후에는 부르지 않는다).

데스크톱 목록 — 쪽은 주소에제목 링크 복사

import { useSearchParams } from "react-router-dom"
import { Pagination } from "@/components/ui/pagination"

const [params] = useSearchParams()
const page = Number(params.get("page") ?? 1)

<section ref={listRef} aria-labelledby="card-list-title">…</section>
{/* 칸은 링크 — 쪽마다 방문 기록이 쌓여 뒤로 가기가 앞 쪽으로 온다 */}
<Pagination totalPages={totalPages} page={page} getHref={(p) => `?page=${p}`} scrollTarget={listRef} aria-label="카드 혜택 페이지 탐색" />

폰 목록 — 끝없이 불러오기제목 링크 복사

import { InfiniteListEnd } from "@/components/ui/pagination"

<ul>{cards.map((c) => <CardRow key={c.id} card={c} />)}</ul>
<InfiniteListEnd
  status={isError ? "error" : hasNextPage ? "loading" : "end"}
  onReachEnd={fetchNextPage}
  onRetry={fetchNextPage}
  endText="카드를 모두 봤어요."
/>

Behavior제목 링크 복사

Accessibility제목 링크 복사

Do / Don't제목 링크 복사

✅ Do제목 링크 복사

• 데스크톱 목록 아래 가운데 — 칸 40 을 붙이고 지금 쪽은 짙게 채운다.
• 칸 수를 화면 폭으로 고정(9 · 7) — 끝 쪽은 빈 칸으로 자리를 지킨다.
• 쪽을 넘기면 목록 맨 위 + "N페이지" 알림.
• 쪽은 주소에, 칸은 링크.
• 폰은 끝없이 불러오고, 끝 글 · 다시 시도 · 받는 중을 보인다.
• 달처럼 자연스러운 묶음이 있는 목록은 묶음 옮기기를 쪽 넘김으로(가계부 거래 — 달 이동).

❌ Don't제목 링크 복사

• 지금 쪽을 테두리만 · 브랜드 색으로.
• 칸 사이를 띄우거나 이전 · 다음에 글자.
• 끝 쪽에서 막힌 화살표 · 초점을 잃는 화살표.
• 화면 3 ~ 4개 분량 이하의 목록을 쪽으로 나누기 · 1쪽뿐인 넘김 줄.
• 폰에 쪽 넘김 · 목록 끝에 줄을 덧붙이는 "더 보기" 버튼(카드 · 띠 미리보기는 머리 "전체 보기").
• 표 아래에 이 넘김 줄(표는 Table Pagination).

Specification제목 링크 복사

pagination.yaml · infinite-list.yaml 의 규칙을 하나도 빼지 않고 조건마다 그린다 — 웹 · 앱이 Pagination 과 목록 끝 자리를 만들 때 이 값을 그대로 쓴다. 조건이 없는 Base 가 모든 조합에 걸리고, 뒤의 규칙이 앞의 같은 값을 덮는다. 상태는 enabled 에서 바뀌는 값만 적었다.

SEED 와 다른 점제목 링크 복사

• 지금 쪽은 bg-neutral-inverted — SEED bg.neutral-solid(#2A3038)의 groo 짝이다(다크는 밝은 반전). 누름은 bg-neutral-inverted-pressed(v112).
• 누름 · 호버 바탕은 불투명한 bg-layer-default-pressed · 누름 축소는 2px 거리(40 이면 0.95) — SEED 는 투명한 bg.transparent-pressed · scale 0.97 이다(v102 · v104).
• 누르는 영역은 세로만 44 — SEED 는 40 그대로다. 옆은 칸이 붙어 넓히지 않는다(v106 의 예외 — 사용자 결정).
• 끝 쪽에서 초점을 지금 쪽 번호로 — SEED 는 누르던 화살표가 빈 칸이 되어 초점이 body 로 떨어진다.
• 쪽이 주소에 있으면 칸은 링크 — SEED 디자인 문서는 "Page Link" 라 부르지만 코드는 늘 버튼이다.
• 쪽이 바뀌면 넘김 줄이 알린다 — SEED 는 "결과 안내는 목록 영역에서" 로 남겼다.
• 폰은 끝없이 불러오기 — SEED 에는 끝없이 불러오기 · "더 보기" 의 규칙이 없다. groo 가 정했다(받는 시점 300 · 끝 글 · 다시 시도 — 2026-10-04 화면 틀 비교 페이지의 따라오는 것). 미리보기는 머리 "전체 보기", 줄을 덧붙이는 "더 보기" 는 두지 않는다(2026-10-22 사용자 결정 6B).

Migration notes제목 링크 복사

2026-10-23 — 쪽 넘김은 상황으로제목 링크 복사

"언제 쪽을 나누나" 의 "데스크톱의 긴 목록 → Pagination · 폰의 긴 목록 → 끝없이 불러오기" 를 동작 상황 표로 바꿨다 — 쪽 단위로 훑는 자리는 Pagination 이 좋을 수 있고, 스크롤로 내려가는 환경(폰 · 긴 목록)은 끝없이 불러오기, 달처럼 자연스러운 묶음이 있는 목록은 묶음 옮기기가 쪽 넘김이다(가계부 거래 — 달 하나 = 한 쪽). DESIGN 세 파일 Layout "화면 틀" 의 문턱 표 "긴 목록" 줄도 "상황에 따라" 로 바꾸고 "목록 넘기기" 표를 더했다. 사용자 결정 — 가계부 다시 짜기 https://claude.ai/artifact/CCAra9mCf1q77pqgM1D2xc 5A(고르지 않은 안 5B). 값 변경 없음.

2026-10-22 — 목록 화면 · 미리보기 둘로제목 링크 복사

""더 보기" 버튼은 두지 않는다" 는 근거 없이 들어간 문장이라 카드 머리 "전체 보기" 까지 막는 것처럼 읽혔다. 목록 화면의 긴 목록(끝없이 불러오기) · 카드 · 띠 안의 미리보기(머리 "전체 보기")로 가르고, 목록 끝에 줄을 덧붙이는 "더 보기" 만 두지 않는다고 적었다(사용자 결정 6B — https://claude.ai/artifact/NuEPiLRH2fJidXdKzcDsCX). 지금 동작은 그대로다.

2026-10-15 — 구현 세션 질문 정리(Q-011-6)제목 링크 복사

사용자가 비교 페이지에서 정리 항목을 "추천대로" 정했다(2026-10-15). 쪽 번호 칸 · 화살표 칸의 transitionProperty 를 background-color, scale 로 적었다 — 누를 때 2px 축소가 있으므로 다른 누르는 칸(카드 · 차트 타일)과 같은 표기이고, SEED pagination-button 도 색과 축소 둘을 전환한다. 화살표 칸에는 빠져 있던 전환 시간 · 이징도 쪽 번호 칸과 같게 적었다. 보이는 모습은 바뀌지 않는다 — 웹 · 레시피는 이미 둘 다 전환한다.

2026-10-04 — SEED Pagination 으로 다시 쓴다제목 링크 복사

사용자가 화면 틀 · 이동 비교 페이지에서 정했다 — SEED Pagination(10A: 번호 · 화살표 40 × 40 · 사이 0 · 14 / 19 · 700 · 모서리 8 · 지금 쪽 bg-neutral-inverted + fg-neutral-inverted 채움 · 이전 · 다음은 아이콘만 16 · 9칸 / 7칸 · 끝 쪽은 화살표 대신 40 빈 칸 + 초점은 지금 쪽 · 1쪽 이하면 그리지 않음) + 데이터 표는 Table Pagination. 같은 날 추가로 — 칸 40 그대로, 누르는 영역 44 규칙(v106)의 예외로 적는다(위아래만 44). 그리고 "따라오는 것" — 폰 긴 목록은 끝없이 불러오기 + 끝 글 · 실패 다시 하기 · 불러오는 동안 표시, 데스크톱은 Pagination, 쪽을 넘기면 목록 맨 위 + 쪽 바뀜 알림. groo 옛 스펙(10B — 지금 쪽 테두리 · 칸 사이 4 · 이전 · 다음 글자 · 끝 막힘 · 좁으면 "이전 · 현재/총 · 다음")과 44 로 키우기는 고르지 않았다. 옛 스펙은 pagination.history/v-pre-seed-nav.*.

제품은 앱 적용 단계에서 옮긴다(2026-10-04 조사 — Desk 웹 · HR 은 크로미움에 띄워 쟀다). 세 제품 모두 숫자 칸 · aria-current · 쪽 바뀜 알림이 0 이다.

• Desk 웹 카드 혜택(데스크톱) — ghost sm 57.9 × 32 "이전 / 다음" + 화살표 14 · 12 / 500 + 가운데 "1 / 3", 끝에서 불투명도 .5(pages/card-benefit/ui/CardBenefitPage.tsx:676-810). "다음" 이 window.scrollTo 를 불러 실제로 스크롤하는 셸 상자가 움직이지 않아, 바닥에서 넘기면 2쪽 첫 카드가 −4564 에 있다(:780 · 804 ↔ widgets/layout/ui/AppLayout.tsx:122, F4). 넘김 줄 + 목록 맨 위로.
• Desk 웹 · 앱 카드 혜택(폰) — 끝없이 불러오기는 있다(웹 IntersectionObserver · 앱 끝 300 앞 — card_benefits_screen.dart:121-153 · 300-345). 작은 스피너뿐이고 aria-live · 끝 글이 없으며, 앱은 첫 쪽 뒤의 실패를 화면에 보이지 않는다. 목록 끝 자리(받는 중 · 못 불러옴 + 다시 시도 · 끝 글)로.
• HR 표 셋 — Pagination 이 아니라 Table Pagination 으로 옮긴다(그 스펙의 Migration notes).
• 옛 스펙의 예시("HR 결재 목록" · "Desk 메모 보관함 142쪽")는 제품에 없다(S2).