# @hm-design/ui — AI 코딩 도구 사용 안내 (Web UI)

먼저 [AI_GUIDE.md](./AI_GUIDE.md)(공통 1~7단계)를 읽고 사용 유형이 **Web** 또는 Web이 포함된 혼합일 때 이 폴더를 씁니다. 이 폴더(`node_modules/@hm-design/ui/ai/`)의 내용은 `@hm-design/ui` 0.1.0의 공개 Export(`src/index.ts` → `dist/index.d.ts`)와 `theme.css`에서 확인한 값만 적습니다.

| 문서 | 내용 |
|---|---|
| [COMPONENT_CATALOG.md](./COMPONENT_CATALOG.md) | 공개 컴포넌트 44종·Pattern 8종·Theme API, HM 전용 Props·Variant |
| [DESIGN_RULES.md](./DESIGN_RULES.md) | 실제 토큰(`--hm-sem-*` 등), 색·Typography·크기·상태·스크롤바·Overlay 규칙 |
| [COMPOSITION_PATTERNS.md](./COMPOSITION_PATTERNS.md) | 화면 유형별 조합(목록·Form·Dashboard·확인창·측면 상세)과 Navigation 단일 모드 |

## 1. 작업 순서 (필수)

1. **Pattern을 먼저 본다.** 화면 단위 요구(목록 검색, 상단/좌측 메뉴, Dashboard, 페이지 제목, 로딩)는 [COMPOSITION_PATTERNS.md](./COMPOSITION_PATTERNS.md) §0 표에서 Pattern을 고른다.
2. **컴포넌트를 찾는다.** [COMPONENT_CATALOG.md](./COMPONENT_CATALOG.md)에서 요청 항목과 같은 역할을 찾는다. 같은 역할이 있으면 새로 만들지 않는다.
3. **Variant·Props로 맞춘다.** `Button`의 `variant` × `appearance`, `Input`/`Select`/`DatePicker`/`Combobox`의 `size`, `Card`·`Tabs`의 `surface` 등 기존 Props로 해결한다. `<Button>`처럼 기본 API만으로 HM 외형이 적용된다. `hm-*` class를 붙이거나 Story 전용 class로 외형을 보정하지 않는다.
4. **조합한다.** 여러 컴포넌트를 배치하고 배치용 레이아웃(flex/grid, 간격)만 소비 프로젝트에 작성한다.
5. **없을 때만 새로 만든다.** 소비 프로젝트에 작성하고, 외형은 [DESIGN_RULES.md](./DESIGN_RULES.md)의 토큰만 `var(--…)`로 읽으며, 안쪽에는 기존 컴포넌트(`Card`, `Button`, `Label` …)를 재사용한다.
6. **추측하지 않는다.** 카탈로그·`dist/index.d.ts`에 없는 Export·Props·토큰은 없다. 기본 HTML·임의 CSS·`data-slot` 흉내로 HM 컴포넌트를 모방하지 않는다(레이아웃·콘텐츠용 HTML은 허용).
7. **실제로 검증한다.** [AI_GUIDE.md](./AI_GUIDE.md) 6단계.

## 2. 설치·Import

```tsx
import { Button, Card, Dialog, DataTable, useDataTable } from "@hm-design/ui"
import { applyRuntimeTheme, resetRuntimeTheme, loadRuntimeTheme } from "@hm-design/ui/theme"
```

앱 CSS 진입점(Tailwind CSS 4 통합이 처리하는 파일)에 이 순서로 넣는다.

```css
@import "tailwindcss";
@import "@hm-design/ui/tailwind.css";
@import "@hm-design/ui/theme.css";
/* Dashboard 업무 상태 색이 필요할 때만 */
@import "@hm-design/ui/dashboard-status.css";
```

- 공개 진입점은 `.`, `./theme`, `./theme.css`, `./tailwind.css`, `./dashboard-status.css`뿐이다. `@hm-design/ui/dist/components/...` 같은 내부 경로를 import하지 않는다.
- Peer: `react`, `react-dom` `^19.0.0`, `tailwindcss` `^4.0.0`. Tailwind CSS 4가 없는 프로젝트에서는 HM 외형이 적용되지 않는다(설치가 필요하다고 보고).
- `tailwind.css`가 패키지의 compiled class를 `@source`로 등록하므로 shadcn CLI 설치나 `components.json`이 필요 없다.
- Noto Sans KR 글꼴과 OFL 라이선스는 `theme.css`에 포함된다(`dist/fonts/`).
- 아이콘은 패키지 의존성인 `lucide-react`를 쓴다.

## 3. 스타일 규칙

- HM이 값을 정한 속성은 Theme Token으로 적용되어 있고, 정하지 않은 속성은 shadcn 기본 그대로다. 새 화면에서도 같은 구분을 지킨다.
- `className`은 배치 확장용이다. HM 컴포넌트에 HEX·RGB·임의 px Spacing/Radius를 덮어쓰지 않는다.
- Light/Dark 분기 없음. `dark:` 분기·Dark Token을 추가하지 않는다.
- 테마 변경은 Runtime Theme(`applyRuntimeTheme(root, theme)`, `loadRuntimeTheme(root, url)`)만 쓴다. `theme`은 `{ schemaVersion: 1, tokens: { "color.bg.content": "#…" } }` 형식이며 키는 `runtimeThemeContract`에 있는 것만 유효하다.
- 한 페이지의 Navigation은 GNB / LNB / DASHBOARD 중 하나다([COMPOSITION_PATTERNS.md](./COMPOSITION_PATTERNS.md) §1).

## 4. 접근성 기본

- 입력 항목명은 `Label htmlFor`와 control `id`를 연결한다(`useId`). placeholder는 항목명이 아니다. `SelectTrigger`·`Combobox`도 `id` 또는 `aria-labelledby`를 연결한다.
- Dialog·AlertDialog·Sheet·Drawer는 Title(필요 시 Description)을 넣는다. Escape와 Trigger Focus 복귀는 Radix 동작을 그대로 쓴다.
- 기존 컴포넌트의 `aria-*` 연결 속성을 임의로 덮어쓰지 않는다.

## 5. 이 패키지에 없는 것

- 공개 Form Pattern, Empty·Error 전용 컴포넌트, Stepper, Tree, Chart(그래프) 컴포넌트는 없다. Form은 `Label` + `Input`/`Textarea`/`Select`/`Checkbox`/`RadioGroup`/`Switch`를 `Card` 안에 조합하고, 빈 목록은 `DataTable`의 `emptyMessage`, 오류 안내는 `Alert`로 만든다.
- Badge에 success / warning / information variant는 없다(HM Theme에 상태 팔레트가 아직 없음). 새 상태색을 만들지 않는다.
- 상세 컴포넌트 문서·Storybook은 HMDesign 저장소(`docs/components/<name>.md`, `docs/patterns/`)에 있고 패키지에는 포함되지 않는다. 패키지만 있을 때는 이 폴더와 `.d.ts`가 기준이다.