# Component / Pattern Reference Index

AI 화면 구현 Quick Start의 Component·Pattern 검색에 사용하는 파일 인덱스다. 오전 `HMDesignTest.zip`과 현재 개발 저장소는 별도 스냅샷이다. 현재 검증된 최신 테스트 배포 기준 `HMDesignTest-Portable-Test-r3.zip`에는 아래 44개 Component와 8개 Pattern 모듈, Dashboard Status 소스/export/CSS/문서/정적 예제와 사전 빌드된 Storybook을 모두 포함한다. `HMDesignTest-Portable-Test-r2.zip`, 기존 `HMDesignTest-Portable-Test.zip` 및 오전 ZIP은 이전 스냅샷이며, 아래 오전 ZIP 수량은 역사적 비교로 표시한다. 공개 심볼의 Source of Truth는 [`packages/ui/src/index.ts`](../../packages/ui/src/index.ts)이며, Props와 상태는 각 연결 문서 및 구현을 확인한다. 파일 수, 공개 API 심볼 수, Story 그룹 수는 서로 다른 집계 단위다.

## Component

현재 `packages/ui/src/components/ui/`에는 구현 TSX 44개가 있다. 각 구현 파일은 `packages/ui/src/index.ts`의 공개 export를 통해 소비한다. 아래 Story는 실제 Story 파일의 대표 그룹이다.

| Component (문서) | Import 경로 | 주요 용도 | 대표 Story |
|---|---|---|---|
| [Accordion](../components/accordion.md) | `@hm-design/ui` | 접고 펼치는 항목 | [Disclosure/Accordion](../../src/components/accordion.stories.tsx) |
| [Alert](../components/alert.md) | `@hm-design/ui` | 안내·경고 | [Feedback/Alert](../../src/components/alert.stories.tsx) |
| [Alert Dialog](../components/alert-dialog.md) | `@hm-design/ui` | 작업 확인 팝업 | [Overlay/Alert Dialog](../../src/components/alert-dialog.stories.tsx) |
| [Aspect Ratio](../components/aspect-ratio.md) | `@hm-design/ui` | 콘텐츠 비율 | [Data & Display/Aspect Ratio](../../src/components/aspect-ratio.stories.tsx) |
| [Avatar](../components/avatar.md) | `@hm-design/ui` | 사용자 이미지 | [Data & Display/Avatar](../../src/components/avatar.stories.tsx) |
| [Badge](../components/badge.md) | `@hm-design/ui` | 상태·라벨 | [Data & Display/Badge](../../src/components/badge.stories.tsx) |
| [Breadcrumb](../components/breadcrumb.md) | `@hm-design/ui` | 현재 경로 | [Navigation/Breadcrumb](../../src/components/breadcrumb.stories.tsx) |
| [Button](../components/button.md) | `@hm-design/ui` | 작업 실행 | [Form/Button](../../src/components/button.stories.tsx) |
| [Calendar](../components/calendar.md) | `@hm-design/ui` | 날짜 선택 | [Search & Date/Calendar](../../src/components/calendar.stories.tsx) |
| [Card](../components/card.md) | `@hm-design/ui` | 콘텐츠 묶음 | [Data & Display/Card](../../src/components/card.stories.tsx) |
| [Carousel](../components/carousel.md) | `@hm-design/ui` | 슬라이드 콘텐츠 | [Data & Display/Carousel](../../src/components/carousel.stories.tsx) |
| [Checkbox](../components/checkbox.md) | `@hm-design/ui` | 복수 선택 | [Form/Checkbox](../../src/components/checkbox.stories.tsx) |
| [Collapsible](../components/collapsible.md) | `@hm-design/ui` | 영역 접기 | [Disclosure/Collapsible](../../src/components/collapsible.stories.tsx) |
| [Combobox](../components/combobox.md) | `@hm-design/ui` | 검색 가능한 선택 | [Search & Date/Combobox](../../src/components/combobox.stories.tsx) |
| [Command](../components/command.md) | `@hm-design/ui` | 명령 검색 | [Search & Date/Command](../../src/components/command.stories.tsx) |
| [Context Menu](../components/context-menu.md) | `@hm-design/ui` | 우클릭 메뉴 | [Overlay/Context Menu](../../src/components/context-menu.stories.tsx) |
| [Date Picker](../components/date-picker.md) | `@hm-design/ui` | 날짜 입력 | [Search & Date/Date Picker](../../src/components/date-picker.stories.tsx) |
| [Dialog](../components/dialog.md) | `@hm-design/ui` | 모달 | [Overlay/Dialog](../../src/components/dialog.stories.tsx) |
| [Drawer](../components/drawer.md) | `@hm-design/ui` | 슬라이드 패널 | [Overlay/Drawer](../../src/components/drawer.stories.tsx) |
| [Dropdown Menu](../components/dropdown-menu.md) | `@hm-design/ui` | 작업 메뉴 | [Overlay/Dropdown Menu](../../src/components/dropdown-menu.stories.tsx) |
| Hover Card | `HoverCard`, `HoverCardContent`, `HoverCardTrigger`<br>[구현](../../packages/ui/src/components/ui/hover-card.tsx) | [문서](../components/hover-card.md) | [Overlay/Hover Card](../../src/components/hover-card.stories.tsx) |
| [Input](../components/input.md) | `@hm-design/ui` | 단일 입력 | [Form/Input](../../src/components/input.stories.tsx) |
| [Label](../components/label.md) | `@hm-design/ui` | 입력 라벨 | [Form/Label](../../src/components/label.stories.tsx) |
| [Menubar](../components/menubar.md) | `@hm-design/ui` | 메뉴 묶음 | [Navigation/Menubar](../../src/components/menubar.stories.tsx) |
| [Navigation Menu](../components/navigation-menu.md) | `@hm-design/ui` | 페이지 이동 | [Navigation/Navigation Menu](../../src/components/navigation-menu.stories.tsx) |
| [Pagination](../components/pagination.md) | `@hm-design/ui` | 페이지 선택 | [Navigation/Pagination](../../src/components/pagination.stories.tsx) |
| [Popover](../components/popover.md) | `@hm-design/ui` | 보조 팝업 | [Overlay/Popover](../../src/components/popover.stories.tsx) |
| [Progress](../components/progress.md) | `@hm-design/ui` | 진행률 | [Data & Display/Progress](../../src/components/progress.stories.tsx) |
| [Radio Group](../components/radio-group.md) | `@hm-design/ui` | 단일 선택 | [Form/Radio Group](../../src/components/radio-group.stories.tsx) |
| [Resizable](../components/resizable.md) | `@hm-design/ui` | 영역 크기 조절 | [Disclosure/Resizable](../../src/components/resizable.stories.tsx) |
| [Scroll Area](../components/scroll-area.md) | `@hm-design/ui` | 스크롤 영역 | [Data & Display/Scroll Area](../../src/components/scroll-area.stories.tsx) |
| [Select](../components/select.md) | `@hm-design/ui` | 목록 선택 | [Form/Select](../../src/components/select.stories.tsx) |
| [Separator](../components/separator.md) | `@hm-design/ui` | 영역 구분 | [Data & Display/Separator](../../src/components/separator.stories.tsx) |
| [Sheet](../components/sheet.md) | `@hm-design/ui` | 측면 패널 | [Overlay/Sheet](../../src/components/sheet.stories.tsx) |
| [Skeleton](../components/skeleton.md) | `@hm-design/ui` | 로딩 자리 표시 | [Data & Display/Skeleton](../../src/components/skeleton.stories.tsx) |
| [Slider](../components/slider.md) | `@hm-design/ui` | 범위 값 선택 | [Form/Slider](../../src/components/slider.stories.tsx) |
| [Sonner](../components/sonner.md) | `@hm-design/ui` | 토스트 | [Feedback/Sonner](../../src/components/sonner.stories.tsx) |
| [Switch](../components/switch.md) | `@hm-design/ui` | 켜기·끄기 | [Form/Switch](../../src/components/switch.stories.tsx) |
| [Table](../components/table.md) | `@hm-design/ui` | 표 | [Data & Display/Table](../../src/components/table.stories.tsx) |
| [Tabs](../components/tabs.md) | `@hm-design/ui` | 탭 전환 | [Navigation/Tabs](../../src/components/tabs.stories.tsx) |
| [Textarea](../components/textarea.md) | `@hm-design/ui` | 여러 줄 입력 | [Form/Textarea](../../src/components/textarea.stories.tsx) |
| [Toggle](../components/toggle.md) | `@hm-design/ui` | 선택 상태 버튼 | [Form/Toggle](../../src/components/toggle.stories.tsx) |
| [Toggle Group](../components/toggle-group.md) | `@hm-design/ui` | 선택 버튼 묶음 | [Form/Toggle Group](../../src/components/toggle-group.stories.tsx) |
| [Tooltip](../components/tooltip.md) | `@hm-design/ui` | 보조 설명 | [Overlay/Tooltip](../../src/components/tooltip.stories.tsx) |

`packages/ui/src/index.ts`에는 위 44개 Component 모듈의 named export 222개(값과 type 포함)가 연결되어 있다. 사용 시 API·Props·Variant·주요 상태·Theme 연결은 해당 Component 문서의 API/상태/Token/Storybook 절을 따른다. 문서 45개 중 `field.md`는 별도 `field.tsx` 공개 Component를 나타내지 않는 Field 소비 가이드다.

## Pattern

현재 개발 저장소와 포터블 r3의 `packages/ui/src/patterns/`에는 8개 디렉터리와 62개 named export(값과 type 포함)가 있다. 역사적 오전 배포 기준 `HMDesignTest.zip`에는 7개 Pattern 모듈과 50개 named export가 있었다. Pattern 소스 디렉터리, Story 파일, Story 그룹 수는 별도 집계다.

| Pattern (문서) | Import 경로 | 주요 용도 | 대표 Story |
|---|---|---|---|
| [Dashboard Layout](../patterns/dashboard-layout.md) | `@hm-design/ui` | 전용 Header·업무 상태·Content | [Patterns/Layout/Dashboard → Dashboard](../../src/patterns/dashboard-layout.stories.tsx) |
| [Dashboard Status](../patterns/dashboard-layout.md#3-storybook) | `@hm-design/ui` | 업무 상태·필터 계약 | [React 대표 Story](../../src/patterns/dashboard-layout.stories.tsx) |
| [Data Table](../patterns/data-table.md) | `@hm-design/ui` | 데이터 표·정렬·페이지 | [Patterns/Data/Data Table → Data Table](../../src/patterns/data-table.stories.tsx) |
| [Filter Bar](../patterns/filter-bar.md) | `@hm-design/ui` | 조회 조건·조회 액션 | [Patterns/Data/Filter Bar → Filter Bar](../../src/patterns/filter-bar.stories.tsx) |
| [GNB](../patterns/gnb.md) | `@hm-design/ui` | 상단 Navigation | [Patterns/Layout/GNB](../../src/patterns/gnb.stories.tsx) |
| [LNB](../patterns/lnb.md) | `@hm-design/ui` | 좌측 Navigation | [Patterns/Layout/LNB](../../src/patterns/lnb.stories.tsx) |
| [Loading Screen](../patterns/loading-screen.md) | `@hm-design/ui` | 전체 화면 로딩 | [Patterns/Layout/Loading Screen](../../src/patterns/loading-screen.stories.tsx) |
| [Page Header](../patterns/page-header.md) | `@hm-design/ui` | 제목·경로·주요 작업 | [Patterns/Layout/Page Header → Page Header](../../src/patterns/page-header.stories.tsx) |

Data Table은 기존 Table·Pagination·Checkbox·Select·Dropdown Menu 등을 조합한다. 연동 예제가 필요하면 Data Table Story 안의 `With Filter Bar`를 참고하되 숨김 `verification` Story이므로 일반 화면의 단독 기본 Reference로 삼지 않는다. Filter Bar는 단독으로도 사용 가능하며 검색·Select·Combobox·Date Picker 등 조회 조건의 layout이다. Dashboard 빠른 상태 필터는 Filter Bar API가 아니라 Dashboard Status 계약을 따른다.

오전 소스 ZIP을 받은 AI는 Dashboard Status 행의 현재 개발 경로를 사용할 수 있다고 가정하지 않는다. 최신 포터블 ZIP에서는 해당 상대경로와 공개 API를 사용할 수 있다. ZIP에 실제 포함된 Dashboard 구현·Story와 해당 ZIP 안의 Dashboard 문서를 확인하고, Status 공개 API가 없으면 없다고 보고한다.

## Reference 읽는 순서

### 화면 생성 시 놓치기 쉬운 소비 계약

- Navigation 미지정: [선택 근거](navigation-single-mode.md#선택-근거)를 기록한다. GNB/LNB의 목적과 대표 화면 구조로 판단하며 일반 목록의 기본 모드를 임의 확정하지 않는다.
- GNB ONLY: [Desktop·Mobile 구성](../patterns/gnb.md#8-desktop--mobile)을 함께 구현한다. 대표 `patterns-layout-gnb--all`의 Overview·Usage를 확인한다. 신규 AI Production 화면에는 GNB Sidebar를 적용하지 않는다.
- LNB ONLY: 기존 독립 LNB 구조와 [LNB Mobile Header/Menu](../patterns/lnb.md#3b-lnb-mobile-header-2026-10-07)를 유지한다.
- DASHBOARD ONLY: Sidebar를 생성하지 않는다. 대표 `patterns-layout-dashboard-layout--all`의 전용 Header(48px)·업무 상태 필터 + Content, 최소 폭 960px·내부 가로 스크롤을 따른다. `DashboardSidebar`와 `sidebar` slot은 호환성·검증용이며 과거 Sidebar verification Story는 신규 운영 화면 구현 기준이 아니다.
- Dashboard Status: 공개 `@hm-design/ui/dashboard-status.css`는 변수만 제공한다. [Theme → Status CSS → 기존 Outline Badge mapping·React 소비 예제](../patterns/dashboard-layout.md#dashboard-업무-상태-공통-계약)를 사용한다. `issue`는 독립 flag다. [Static HTML Reference](../patterns/dashboard-status-static.html)도 같은 계약을 소비한다.
- FilterBar: [입력 draft / 조회 applied·초기화 예제](../patterns/filter-bar.md#61-조회-버튼으로-적용하는-소비-예제)를 확인한다. 대표 `patterns-data-filter-bar--all`은 조회 callback 없는 조합 예시이며 DataTable의 `patterns-data-data-table--with-filter-bar-story`는 즉시 적용 verification이다.
- React 소비 CSS: [Tailwind v4 검색 범위와 HM source 유지](runtime-portability.md#21-tailwind-v4-소비자-검색-범위), [Runtime Theme 연결](runtime-theme.md)을 확인한다.
- 실행 위치별 Asset: [Noto Sans KR·폰트 URL·단일 HTML 내장](runtime-portability.md#41-noto-sans-kr-경로-실행-환경별-확인)을 확인한다.

### 탐색 절차

1. 이 인덱스에서 후보를 찾고 실제 파일·공개 API가 존재하는지 확인한다.
2. 사용 문서에서 Props/Variant, 상태, Theme Token, 조합 규칙을 확인한다.
3. 대표 Story에서 시각 언어와 실제 composition을 확인한다. Storybook을 실행할 수 없으면 Story 소스에서 확인한다.
4. `verification` Story는 계약·상태 검사로, Compatibility 예제는 호환성 확인으로, Fixture는 시각 테스트 데이터로 분류한다. 이들을 Production API나 운영 화면 예제로 일반화하지 않는다.
5. Dashboard는 GNB/LNB와 함께 사용하지 않는다. 허용되는 페이지 모드와 Responsive 규칙은 [Navigation Single Mode Policy](navigation-single-mode.md)를 따른다.
6. Theme Source of Truth는 `themes/default.json` 및 공개 Runtime 계약이다. Component Token/상태 mapping은 연결된 Theme 문서를 확인한다.

정적 Storybook 빌드가 없거나 실행할 수 없는 환경에서는 확인된 Story 소스와 문서만 근거로 삼고, 검증하지 않은 시각 동작은 미확인으로 보고한다.