# 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 키보드 흐름.