HMDesign/packages/ui/ai/COMPONENT_CATALOG.md

@hm-design/ui 컴포넌트 카탈로그 (Web UI)

기준: @hm-design/ui 0.1.0, 공개 Export(src/index.ts → dist/index.d.ts, dist/theme/index.d.ts). 모든 컴포넌트 import는 from "@hm-design/ui", Theme API는 from "@hm-design/ui/theme"입니다. 이 표에 없는 이름은 공개 API가 아닙니다. 저장소의 npm run check:ai-docs가 이 문서와 실제 Export의 일치를 검사합니다.

• 구조: shadcn/ui(Radix) 구조와 공개 API를 유지하고 외형만 HM Theme로 바꿨습니다. 아래 "HM Props"에 없는 Props는 shadcn·Radix 원래 Props입니다.
• 상태 소유: 대부분 Radix처럼 open/onOpenChange, value/onValueChange(Controlled)와 default*(Uncontrolled)를 지원합니다.
• 외형 보정 금지: HM 외형은 기본 API만으로 적용됩니다. className은 배치용이며 색·간격·radius를 덮어쓰지 않습니다.

1. Form

컴포넌트 (Export)	용도	HM Props·Variant (기본값)
Button, buttonVariants / 타입 ButtonAppearance	작업 실행	variant: primary(기본) · secondary(Brown) · modify(Orange) · destructive(Red) · cancel(Gray), 별칭 default(=primary) · outline(=primary+outline), 호환 ghost · link(HM 외형 없음). appearance: brand(기본) · solid · outline. size: HM 규격은 sm(28) · default(34) · lg(42), xs·icon*는 shadcn 기본. asChild
Input / 타입 InputSize	한 줄 입력	size: small(28) · medium(34) · large(42, 기본). 상태는 native disabled·readOnly·aria-invalid
Textarea / 타입 TextareaResize	여러 줄 입력	resize: vertical(기본) · none · both
Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton / 타입 SelectSize	목록 선택	SelectTrigger size: medium(34) · large(44, 기본). Content·Item은 Trigger 크기를 따름
Label	입력 라벨	없음. htmlFor ↔ control id 연결
Checkbox	복수 선택	없음(Radix)
RadioGroup, RadioGroupItem	단일 선택	없음(Radix)
Switch	켜기·끄기	없음(Radix)
Slider	범위 값	없음(Radix)
Toggle, toggleVariants	선택 상태 버튼	variant: default · outline, size: default · sm · lg
ToggleGroup, ToggleGroupItem	선택 버튼 묶음	variant, size(Toggle과 같음), spacing

Button 조합 규칙(필수). 디자인이 있는 조합만 씁니다. TypeScript가 통과해도 아래에 없는 조합은 디자인이 없습니다.

variant	허용 appearance
primary	brand, solid, outline
secondary	brand, solid, outline
modify	brand, solid (outline 없음)
cancel	solid, outline (brand 없음)
destructive	solid, outline (brand 없음)

• brand는 페이지 대표 실행 1개에만 씁니다(팝업 안 금지). 일반 실행·저장·확인은 solid, 반복·보조·표 행 작업은 outline.
• 결정 세트(취소 + 저장/확인/삭제)는 같은 appearance·size: 예) <Button variant="cancel" appearance="solid">취소</Button> + <Button appearance="solid">저장</Button>.
• 기본값이 brand이므로 variant="cancel"·"destructive"만 쓰면 미지원 조합이 됩니다. 항상 appearance를 명시합니다.
• 검색 영역: 조회 primary/solid + 초기화 cancel/outline, 같은 size.

2. Overlay

컴포넌트 (Export)	용도	HM Props·주의
Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter, DialogClose, DialogOverlay, DialogPortal	모달	DialogBody(HM 추가: 본문 여백·스크롤, Header·Footer 고정). DialogContent showCloseButton(기본 true), DialogFooter showCloseButton(기본 false)
AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogAction, AlertDialogCancel, AlertDialogOverlay, AlertDialogPortal	작업 확인	AlertDialogAction: variant(기본 primary)·appearance(기본 solid)·size. AlertDialogCancel: variant(기본 cancel)·appearance(기본 solid). 삭제 확인 = Action variant="destructive"
Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetBody, SheetFooter, SheetClose, SheetOverlay, SheetPortal	측면 패널	SheetContent side: right(기본) · left · top · bottom, showCloseButton(기본 true)
Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter, DrawerClose, DrawerOverlay, DrawerPortal	하단 슬라이드(vaul)	드래그 동작은 vaul 기본
Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverClose	보조 팝업	없음
Tooltip, TooltipTrigger, TooltipContent, TooltipProvider	보조 설명	없음
HoverCard, HoverCardTrigger, HoverCardContent	Hover 카드	없음
DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent	작업 메뉴	DropdownMenuItem variant: default · destructive, inset
ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuShortcut, ContextMenuGroup, ContextMenuPortal, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent	우클릭 메뉴	DropdownMenu와 같음
Toaster, toast / 타입 ExternalToast, ToasterProps	토스트(sonner)	앱에 <Toaster /> 한 번, 호출은 toast("…")

3. Navigation (컴포넌트)

컴포넌트 (Export)	용도	HM Props
Tabs, TabsList, TabsTrigger, TabsContent / 타입 TabsPanelSurface	탭	TabsList fill(기본 true = 균등 폭 Primary Fill, false = Legacy), TabsList panelSurface: content(기본) · surface — 실제 배경(Card surface)과 맞춤
Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis	현재 경로	BreadcrumbLink asChild
Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis	페이지 선택	PaginationLink isActive, size(기본 icon)
NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport	링크 메뉴	NavigationMenu viewport
Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarLabel, MenubarSeparator, MenubarShortcut, MenubarGroup, MenubarPortal, MenubarSub, MenubarSubTrigger, MenubarSubContent	메뉴 막대	DropdownMenu와 같음

페이지 Navigation(상단·좌측 메뉴)은 컴포넌트가 아니라 Pattern GNB / LNB / DashboardLayout 중 하나를 씁니다(§6).

4. Data & Display

컴포넌트 (Export)	용도	HM Props
Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter / 타입 CardSurface	콘텐츠 묶음	surface: surface(White, 기본) · content(Beige), size: default · sm
Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption	표(표시만)	없음. 정렬·선택·페이지가 필요하면 Pattern DataTable
Badge, badgeVariants	상태·라벨	variant: default · secondary · destructive · outline(success/warning/info 없음), asChild
Alert, AlertTitle, AlertDescription	안내·경고	variant: default · destructive
Avatar, AvatarImage, AvatarFallback	사용자 이미지	size: default · sm · lg
Separator	구분선	없음
Progress	진행률	없음
Skeleton	로딩 자리	없음
ScrollArea, ScrollBar	스크롤 영역(HM 스크롤바)	없음. 스크롤바 외형은 DESIGN_RULES §6
AspectRatio	비율 유지	없음
Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, useCarousel / 타입 CarouselApi	슬라이드(embla)	opts, plugins, orientation, setApi
Accordion, AccordionItem, AccordionTrigger, AccordionContent	접고 펼치기	없음
Collapsible, CollapsibleTrigger, CollapsibleContent	영역 접기	없음
ResizablePanelGroup, ResizablePanel, ResizableHandle	크기 조절	ResizableHandle withHandle

5. Search & Date

컴포넌트 (Export)	용도	HM Props
Calendar	달력(react-day-picker)	react-day-picker Props
DatePicker / 타입 DatePickerSize	날짜 입력	value·defaultValue(Date), onValueChange, controlled, placeholder, size: medium · large(기본), format(기본 YYYY.MM.DD), calendarProps(disabled·startMonth·endMonth·locale·captionLayout·weekStartsOn·today)
Combobox / 타입 ComboboxOption, ComboboxSize	검색 가능한 선택	options: { value, label, disabled? }[](필수), value·defaultValue, onValueChange, controlled, placeholder, searchPlaceholder, emptyText, size: medium · large(기본)
Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut	명령 검색(cmdk)	없음

6. Pattern (업무 화면 단위)

Pattern은 위 컴포넌트를 조합한 것이며 자체 primitive 외형을 추가하지 않습니다. 조합 예시는 COMPOSITION_PATTERNS.md.

Pattern (Export)	용도	주요 Props
DataTable, useDataTable, DataTableColumnHeader, DataTablePagination, DataTableViewOptions, dataTableSelectColumn / 타입 DataTableColumnDef, DataTableInstance, DataTableOptions, DataTableProps	데이터 표(TanStack Table v9: 정렬·필터·선택·페이지·열 표시)	useDataTable({ columns, data, … })(columns·data는 참조 안정), DataTable table loading emptyMessage pagination(기본 true) pageSizeOptions, DataTableColumnHeader column title, DataTableViewOptions table label labels, dataTableSelectColumn()
FilterBar, FilterBarSearch, FilterBarActions / 타입 FilterBarProps, FilterBarSearchProps	조회 조건 행(레이아웃)	FilterBar layout: default · list-basic(가운데) · list-extended(추가 조건 왼쪽). FilterBarSearch value onValueChange size(기본 medium) placeholder(기본 "검색")
GNB, GNBBrand, GNBNav, GNBUtilities, GNBUser, GNBMobileMenu, GNBMobileLink, GNBMobileGroup / 타입 GNBUserProps, GNBMobileMenuProps	상단 Navigation	GNB sticky, GNBBrand asChild, GNBUser name description, GNBMobileMenu title side open defaultOpen onOpenChange, GNBMobileLink active asChild, GNBMobileGroup label
LNB, LNBBrand, LNBNav, LNBItem, LNBGroup, LNBProfile / 타입 LNBGroupProps, LNBProfileProps	좌측 Navigation(3뎁스까지 LNBGroup 중첩)	LNBItem active asChild, LNBGroup label current, LNBProfile name description
LNBMobileHeader, LNBMobileBrand, LNBMobileMenu, LNBMobileLink, LNBMobileGroup / 타입 LNBMobileMenuProps	LNB 모바일 Header + Sheet	LNBMobileMenu title side open defaultOpen onOpenChange, LNBMobileLink active
PageHeader, PageHeaderContent, PageHeaderTitle, PageHeaderDescription, PageHeaderActions	페이지 제목·설명·주요 작업	HTML 속성만
DashboardLayout, DashboardHeader, DashboardMain, DashboardContent, DashboardSidebar / 타입 DashboardLayoutProps	Dashboard 전용 레이아웃(Header 48px, 최소 폭 960px·내부 스크롤)	DashboardLayout header sidebar children. 신규 화면은 sidebar·DashboardSidebar를 쓰지 않음(호환성 전용)
dashboardStatusDefinitions, dashboardStatusAttributes, dashboardFilterDefinitions, dashboardFilterIds, countDashboardFilter, matchesDashboardFilter / 타입 DashboardStatusId, DashboardStatusDefinition, DashboardStatusRecord, DashboardStatusTone, DashboardFilterId, DashboardFilterDefinition	Dashboard 업무 상태·필터 계약(데이터 helper)	색은 @hm-design/ui/dashboard-status.css의 --hm-dashboard-status-active · -hold · -done · -issue 변수만 제공. Badge 등 자동 스타일 없음 — 소비자가 연결
LoadingScreen	전체·부분 로딩	fullscreen(기본 false), children(기본 "Loading")

7. Theme API (@hm-design/ui/theme)

Export	용도
applyRuntimeTheme(root, theme) → boolean	root(예: document.documentElement 또는 [data-hm-theme] 요소)에 Runtime Theme 적용. 잘못된 입력은 전체 거부(false)
resetRuntimeTheme(root)	적용한 값 제거, HM Default로 복원
isRuntimeTheme(value)	형식 검사
fetchRuntimeTheme(url, request?), resolveRuntimeTheme(theme, defaults?), loadRuntimeTheme(root, url, options?) / 타입 RuntimeThemeLoadOptions	URL의 Theme JSON 불러오기·병합·적용
runtimeThemeContract, defaultRuntimeTheme / 타입 RuntimeTheme, RuntimeThemeToken	계약(토큰 키 → CSS 변수)과 HM Default 값. RuntimeTheme = { schemaVersion: 1, tokens: Partial<Record<RuntimeThemeToken, string>> }

Theme JSON 원본·CDN은 패키지에 포함되지 않습니다(URL은 소비 앱이 정함).

8. 공개하지 않은 것

cn, 내부 lib/utils, 각 컴포넌트 파일의 비공개 helper, components/ui/* 직접 경로, theme/*.css 개별 파일은 공개 API가 아닙니다. shadcn CLI로 같은 컴포넌트를 소비 프로젝트에 다시 추가하지 않습니다(같은 이름의 중복 컴포넌트가 됨).