shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
6c61edadc1639c2cb9834c3b36c9b86999c705b5
HMDesign/docs/guidelines/component-pattern-reference.md
T
shkim4 4c29894e56 refactor(storybook): simplify component and preview examples 
Drop page / section descriptions, state notes and repeated captions from
the representative Stories of 44 components, the Patterns, Center
Graphic and OrgChart pages. Value readouts, spec lists and captions hide
only on the representative page; hidden verification Stories keep them.
Tabs Default API and the Filter Bar draft / applied counts move to the
hidden DefaultApi and DraftApplied Stories; Center Overview is hidden
with its direct URL kept. Story IDs are unchanged.

Align the component, pattern and OrgChart docs with the pages, point the
quality reference check at the DraftApplied Story, and make the P8
styles check expect no section header on the preview-only Expanded page.
2026-10-23 00:28:05 +09:00

104 lines
15 KiB
Markdown
Raw Blame History

# Component / Pattern Reference Index
AI 화면 구현 Quick Start의 Component·Pattern 검색에 사용하는 파일 인덱스다. 현재 테스트 공유 기준은 [README의 Git Clone 안내](../../README.md#git-clone-설치실행-현재-테스트-공유-기준)와 해당 checkout의 소스다. `HMDesignTest.zip`과 포터블 r1/r2/r3는 과거 스냅샷이며 현재 Git 소스와 별도로 취급한다. 당시 r3에는 44개 Component와 8개 Pattern 모듈, Dashboard Status 소스/export/CSS/문서/정적 예제와 사전 빌드된 Storybook을 포함했다. Git Clone에는 생성 dist·사전 빌드 Storybook·포터블 Node가 포함되지 않으므로 안내대로 설치·빌드한다. 아래 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
화면 요구 기능별 첫 선택은 [선택·완료 계약](ai-screen-contract.md#구현-전-기록)을 따른다. 공개 Form/Empty/Error Pattern은 현재 없으며 기존 Component composition으로 구성한다. FilterBar의 목록형 opt-in은 `layout="list-basic" | "list-extended"`다. Story의 추가 조건·액션은 사용자 요구사항이 아니다.
현재 개발 저장소의 `packages/ui/src/patterns/`에는 8개 디렉터리와 63개 named export(값과 type 포함, FilterBarProps 추가)가 있다. 기존 포터블 r3 스냅샷은 62개이며 이번 작업에서 ZIP을 갱신하지 않는다. 역사적 오전 배포 기준 `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에 실제 포함된 Dashboard 구현·Story·문서와 공개 API를 확인하고, Status 공개 API가 없으면 없다고 보고한다. 현재 Git checkout에서는 실제 파일 목록과 공개 exports를 확인한 뒤 사용한다.
## Reference 읽는 순서
### 화면 생성 시 놓치기 쉬운 소비 계약
- 검색·필터: Table이 없어도 [FilterBar](../patterns/filter-bar.md)를 먼저 확인한다. 공개 Pattern 미사용 시 요구사항과 맞지 않는 제약을 기록한다. 대표 Story의 fixture·추가 액션은 요구사항이 아니다.
- Field Label: [공개 Label의 control 연결 예제](../components/label.md#5-api)를 확인한다. 기본 HTML은 레이아웃·콘텐츠나 미지원 사용처에 허용하며 기존 HM 위젯 대체는 이유 없이 만들지 않는다.
- 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 조합 예시이고 입력/조회 적용 상태 구분은 숨김 `patterns-data-filter-bar--draft-applied`가 표시한다. 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 소스와 문서만 근거로 삼고, 검증하지 않은 시각 동작은 미확인으로 보고한다.
View Git Blame Copy Permalink