HMDesign/docs/components/breadcrumb.md

Breadcrumb

현재 HM 구현의 기준 문서. 공통 원칙은 docs/guidelines/프로젝트-지침.md(§6, §7), Token 구조 원칙은 테마-토큰-가이드.md를 따른다. 이 문서는 Breadcrumb 고유의 API·Token·상태·결정만 기록한다.

1. 상태

항목	내용
구현 상태	구현 완료 (현재 HM 규격)
기준일	2026-10-02
기반	shadcn/ui Breadcrumb (Radix 없음, nav > ol > li + Slot)
대표 Story	Components/Navigation/Breadcrumb → All (이름 "Breadcrumb")
보류	아래 §11

2. 적용 근거

• 참고 근거: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Breadcrumb이 컴포넌트 이름으로만 있고 규격은 없다. 참고할 수치가 없었다.
• 현재 HM 규격: 아래 §3~§4. 현재 HM Semantic 체계(fg-primary/secondary)로 새로 정했다.
• 구현 방식: shadcn Breadcrumb 구조 유지, theme CSS로 HM 스타일 연결. 페이지 안에 직접 놓이는 navigation primitive라 Portal·overlay가 없다.
• 역할 범위: 현재 위치와 상위 이동만 담당한다. 메뉴 시스템·자동 접기(maxItems)는 없다.
• 보류: §11.

3. 기본 규격 (현재 HM 규격)

항목	값
Typography	14 / 20 / 400
Item 간격	8px(Item 안 gap, 목록 gap)
Link	--hm-sem-fg-secondary, hover 시 --hm-sem-fg-primary + 밑줄(offset 4px)
Current Page	--hm-sem-fg-primary, weight 700, 기본 커서
Separator	shadcn ChevronRightIcon 16px, --hm-sem-fg-secondary
Ellipsis	20px 영역, 아이콘 16px, --hm-sem-fg-secondary
긴 경로	flex-wrap으로 줄바꿈 (break-words)

4. 상태 규격

상태	값
Hover (Link)	전경 primary + 밑줄
Focus (:focus-visible)	ring 모양 0 0 0 3px ring 50%, radius 2px
Current	aria-current="page", aria-disabled="true", role="link" (shadcn), 링크가 아닌 span
Disabled	없음(없는 상태를 만들지 않음)

5. API

export: Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis.

• BreadcrumbLink: 기본 a, asChild로 router Link 등과 조합(특정 router에 의존하지 않음).
• BreadcrumbPage: 현재 위치 표시용 span. 클릭할 수 없다.
• BreadcrumbSeparator: 기본 chevron, children으로 교체(예: /). aria-hidden, role="presentation".
• BreadcrumbEllipsis: 표시용(aria-hidden, sr-only "More"). Dropdown과 자동 결합하지 않는다. 메뉴 연결은 소비 조합(Story 예시).
• variant, size, maxItems는 만들지 않았다.

6. Token

Component Mapping 위치: packages/ui/src/theme/breadcrumb.css (--hm-breadcrumb-*).

font-size, line-height, font-weight, gap, link-color, link-hover-color, page-color, page-font-weight, separator-color, separator-size, ellipsis-size, focus-radius. Semantic만 참조하고 다른 컴포넌트 Token을 쓰지 않는다. 신규 Primitive 없음.

7. shadcn에서 유지한 항목

nav aria-label="breadcrumb", ol/li 구조, BreadcrumbPage의 ARIA, separator의 aria-hidden, asChild(Slot), chevron·MoreHorizontal 아이콘, data-slot, cn(..., className).

8. HM에서 변경한 항목

• shadcn text-sm text-muted-foreground gap-1.5 sm:gap-2.5, Link hover:text-foreground, Page font-normal text-foreground, 아이콘 size-3.5/size-9 class 제거 → theme CSS.
• Current Page를 weight 700으로 강조(shadcn은 normal).
• Link에 밑줄 hover 및 focus ring 추가(shadcn은 색 변화만).

9. Storybook

• 대표 Story All("Breadcrumb"): Basic(3 depth), Ellipsis(Dropdown Menu 조합), Long path, Custom link(asChild)와 custom separator를 한 페이지에 둔다.
• verification: Basic, Ellipsis, Long Path.

10. 사용자 확정 결정

• 2026-10-02: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 개별 수치에 대한 별도 결정은 없다.

11. 미확정 / 보류

• 수치(14/20, gap 8px, Current weight 700, chevron 16px)는 현재 HM 규격이며 디자인 확정 시 재검토.
• 긴 경로의 자동 접기(maxItems)와 모바일 축약 표현은 만들지 않았다. 지금은 줄바꿈만 한다.
• Separator 색은 Link와 같은 secondary(별도 색 결정 없음).
• Ellipsis는 표시용이다. 접힌 항목을 보여주는 메뉴 규칙은 소비 조합으로 남긴다.

12. 관련 파일

packages/ui/src/components/ui/breadcrumb.tsx
packages/ui/src/theme/breadcrumb.css
packages/ui/src/theme.css            (import)
packages/ui/src/index.ts             (export)
src/components/breadcrumb.stories.tsx

13. 검증 상태

• npm run typecheck, npm run build: 통과(2026-10-02).
• 실제 interaction(Browser pane): Link는 a, Current Page는 span(aria-current="page", aria-disabled="true", 커서 default), Tab으로 Link 사이 이동하고 Current Page는 포커스 대상이 아님, Separator·Ellipsis aria-hidden.
• computed style: Link rgb(110,103,89) 14/20, Current rgb(10,34,29) 700.
• Responsive: 390×844에서 목록 폭 358px, 긴 경로(7 depth)는 4줄(76px)로 줄바꿈되고 가로 overflow 없음.
• 미확인: 실제 pointer hover/focus ring 시각, Ellipsis 안 Dropdown Menu 키보드 흐름.