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

먼저 [AI_GUIDE.md](./AI_GUIDE.md)(공통 1~7단계, 사용 유형 정의)를 읽습니다. 사용 유형은 `1 Web / 2 SW(SW 일반 모드 · SW 뷰어 모드) / 3 OrgChart / 4 혼합`이고, 소비 프로젝트 설정 값은 `HMDesign 사용 유형: Web | SW 일반 | SW 뷰어 | OrgChart | 혼합(영역별)`입니다. **이 폴더는 유형이 Web이거나 혼합의 Web 영역일 때만** 씁니다. 이 폴더(`node_modules/@hm-design/ui/ai/`)의 내용은 `@hm-design/ui` 0.1.0의 공개 Export(`src/index.ts` → `dist/index.d.ts`)와 `theme.css`에서 확인한 값만 적습니다.

- 요청에 SW(일반/뷰어) 화면이 섞이면 그 영역은 [SW 안내](../../sw/ai/AI_USAGE.md), OrgChart가 섞이면 [OrgChart 안내](../../org-chart/ai/AI_USAGE.md)로 넘기고, 영역·모드 사이에 컴포넌트·토큰을 임의로 섞지 않습니다. 유형이 정해지지 않았으면 AI_GUIDE의 확인 질문을 먼저 합니다.
- Web 컴포넌트(`Button`, `DropdownMenu`, `Dialog` 등)를 SW 화면의 Header·뷰어 메뉴·툴바 대용으로 쓰지 않습니다. SW 화면 안에서 Web 컴포넌트는 SW 문서가 허용한 지점에만 둡니다: 일반 모드는 `SWPopup`의 `children` 안(예: Popup 하단 `Button`), 뷰어 모드는 `SWViewerPanel`의 `children` 안이며 `SWViewer*` 컨트롤로 안 될 때만입니다.

| 문서 | 내용 |
|---|---|
| [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. **없을 때만 새로 만든다 (3단계).**
   - ① 기존 Pattern·컴포넌트·Variant·Props·조합으로 되는지 먼저 확인한다(위 1~4).
   - ② 없으면 소비 프로젝트에 새로 작성한다. 색·간격·radius·글꼴은 [DESIGN_RULES.md](./DESIGN_RULES.md)의 Web 토큰(`--hm-sem-*`, `--hm-color-*`, `--hm-radius-*`)을 `var(--…)`로 읽고, hover·focus·disabled·invalid 등 상태 표현도 같은 문서를 따른다. 안쪽에는 기존 컴포넌트(`Card`, `Button`, `Label` …)를 재사용한다. **쓸 수 있는 토큰이 있으면 반드시 토큰을 쓴다.**
   - ③ 참고할 토큰·스타일이 없을 때만 HMDesign 공통 규칙(Font Weight 400/500/700만, Light/Dark 없음, 전역 CSS 금지)과 조화되게 구성한다. 이때 토큰에 없는 값은 결과 보고에 **"AI 구성 값 — 디자인 확인 필요"** 로 적는다.
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`가 기준이다.