HMDesign/packages/org-chart-react/ai/AI_GUIDE.md

HMDesign AI 작업 가이드 — 공통 진입점

이 파일은 HMDesign 패키지(@hm-design/ui, @hm-design/sw, @hm-design/org-chart, @hm-design/org-chart-react)의 ai/AI_GUIDE.md에 같은 내용으로 들어 있습니다. 원본은 HMDesign 저장소 docs/ai/AI_GUIDE.md이며 패키지 사본은 npm run sync:ai-docs로 갱신합니다. 사본을 직접 고치지 않습니다.

사용자가 "HMDesign 패키지를 기준으로 화면을 구현해 주세요"처럼 요청하면 AI 코딩 도구는 이 파일의 1~6단계를 순서대로 따릅니다. 이 문서와 각 패키지의 ai/ 문서는 실제 공개 API·CSS에서 확인한 내용만 적습니다. 여기에 없는 컴포넌트·Props·토큰은 없는 것으로 취급합니다.

0. 읽는 순서

1. 이 파일(어느 패키지의 사본이든 같음)
2. 선택한 패키지의 ai/AI_USAGE.md → ai/COMPONENT_CATALOG.md → ai/DESIGN_RULES.md → ai/COMPOSITION_PATTERNS.md
3. API가 의심스러우면 그 패키지의 dist/*.d.ts(공개 진입점에서 export되는 것만)

유형	패키지	지침 위치(설치 후)	JS 진입점	CSS
① Web UI	@hm-design/ui	node_modules/@hm-design/ui/ai/	@hm-design/ui, @hm-design/ui/theme	@hm-design/ui/tailwind.css + @hm-design/ui/theme.css(Tailwind CSS 4 필요), 선택 @hm-design/ui/dashboard-status.css
② SW UI	@hm-design/sw	node_modules/@hm-design/sw/ai/	@hm-design/sw	@hm-design/sw/styles.css
③ OrgChart	@hm-design/org-chart(Core) + React면 @hm-design/org-chart-react	node_modules/@hm-design/org-chart/ai/ (React 어댑터 안내는 node_modules/@hm-design/org-chart-react/ai/AI_USAGE.md)	@hm-design/org-chart, @hm-design/org-chart-react, 선택 @hm-design/org-chart-react/hm-dialog	@hm-design/org-chart/engine.css, @hm-design/org-chart/style.css(URL로 전달 — Shadow DOM 안에 로드)
기타	@hm-design/center-graphic	AI 지침 없음. 패키지 README.md만	@hm-design/center-graphic	자동 import

모든 패키지는 서로 독립입니다(@hm-design/org-chart-react만 Core에 의존, @hm-design/ui는 /hm-dialog를 쓸 때만 선택 peer). React·React DOM ^19는 peer입니다.

1단계. 사용 목적 확인

다음 순서로 판단하고, 판단되면 다시 묻지 않습니다.

1. 소비 프로젝트의 AGENTS.md·CLAUDE.md 등에 HMDesign 사용 유형: 설정이 있으면 그대로 따릅니다(§9).
2. 사용자 요청이 유형을 분명히 말하면 그대로 따릅니다.
   • Web: 웹 화면, 관리자·업무 화면, 목록·검색·Form, 대시보드, GNB/LNB, Dialog, Table …
   • SW: 데스크톱 SW, 뷰어, 도면·CAD, SW Header, 툴바, 레이어/색상/선스타일, 속성창·SW Popup …
   • OrgChart: 조직도, 조직 계층·직원 카드, 조직 JSON/CSV/Excel 시각화 …
   • 둘 이상이 함께 나오면 ④ 혼합(예: "업무 화면 안에 조직도" = Web + OrgChart).
3. 위로 정할 수 없으면 코드 작성 전에 그대로 묻습니다.

어떤 HMDesign 디자인 시스템을 사용하시겠습니까?

1. Web
2. SW
3. OrgChart
4. 혼합 사용

• package.json에 설치된 패키지가 하나뿐이어도 그것만으로 유형을 확정하지 않습니다(설치가 덜 된 상태일 수 있음). 요청 내용과 맞을 때만 근거로 씁니다.
• 혼합을 고르면 영역별 패키지(예: "페이지 = Web, 가운데 영역 = OrgChart")를 확인합니다.
• OrgChart가 포함되고 생성 방식이 없으면 같은 메시지에서 다음도 묻습니다(이미 말했으면 묻지 않음): "조직도만 기존 페이지에 삽입할까요(Chart Only), 아니면 레이아웃까지 구성한 새 페이지 전체를 생성할까요(Full Page)?" 상세는 @hm-design/org-chart/ai/AI_USAGE.md §1.
• 선택한 패키지가 설치되어 있지 않으면 설치가 필요하다고 보고합니다. 다른 HMDesign 패키지나 임의 라이브러리로 대신하지 않습니다.

2단계. 패키지 분석

1. node_modules/@hm-design/<패키지>/package.json의 version·exports·peerDependencies를 확인합니다. exports에 없는 경로(src/..., dist/components/...)는 import하지 않습니다.
2. 그 패키지의 ai/ 문서를 §0 순서로 읽습니다. 필요한 절만 읽고 전체 dist를 훑지 않습니다.
3. 카탈로그와 실제 dist/index.d.ts가 다르면 .d.ts가 기준입니다. 차이를 결과 보고에 적습니다.
4. 소비 프로젝트의 기존 CSS 진입점·폰트·빌드 도구(Vite 등)·이미 쓰는 디자인 시스템을 확인합니다. 기존 프로젝트의 디자인 시스템을 바꾸지 않습니다.

3단계. 화면 분석

요청 화면을 항목으로 나누고 항목마다 판단을 기록합니다.

요청 항목	판단	근거(카탈로그의 실제 이름)
예: 상단 메뉴	재사용	Web GNB + GNBMobileMenu
예: 레이어 선택	재사용	SW SWHeaderLayerMenu
예: 검색 상자(SW)	신규	SW 카탈로그에 없음 → SWHeaderInput 재사용 + SW 토큰

판단 값은 재사용(그대로) / Props 설정(기존 Variant·Props) / 조합(기존 컴포넌트 배치) / 신규(소비 프로젝트에 최소 구현) 중 하나입니다.

4단계. UI 구현

우선순위(위가 먼저):

1. 선택 패키지의 기존 컴포넌트·Pattern을 그대로 사용
2. 기존 Variant / Props / Callback으로 해결
3. 기존 컴포넌트 조합(배치용 CSS만 소비 프로젝트에 작성)
4. 조합으로 안 되는 부분만 소비 프로젝트에 새로 구현 — 패키지 토큰만 읽고, 안쪽에 기존 컴포넌트를 재사용

규칙:

• node_modules 안 패키지 파일을 수정하지 않습니다. 패키지 dist 구현이나 내부 CSS 블록을 복사해 같은 컴포넌트를 다시 만들지 않습니다.
• 이미 있는 컴포넌트와 같은 역할의 컴포넌트를 새로 만들지 않습니다(예: Web에 Dialog가 있는데 자체 Modal 작성 금지).
• 새 디자인 값을 만들지 않습니다. 색·크기·간격·radius·그림자는 각 패키지 DESIGN_RULES.md의 토큰·확인값만 씁니다. 값이 없으면 추측하지 말고 사용자에게 확인합니다.
• 공통: Font Weight는 400 / 500 / 700만 씁니다(600 없음). Light/Dark 분기를 만들지 않습니다. 새 컴포넌트 CSS에 html·body·* 전역 규칙을 넣지 않습니다. 새 class는 소비 프로젝트 접두사(예: app-)를 씁니다.
• 요청에 없는 메뉴·통계·설명·다운로드·외부 API·AI 입력 UI를 추가하지 않습니다. 필요해 보이면 제안으로만 보고합니다.

없는 UI를 같은 스타일로 만들 때 확인할 항목

신규 항목마다 아래를 선택 패키지 DESIGN_RULES.md에서 찾아 그대로 적용합니다. 찾을 수 없는 항목은 "값 없음 — 사용자 확인 필요"로 보고합니다.

항목	Web(@hm-design/ui)	SW(@hm-design/sw)	OrgChart
토큰·CSS 변수	--hm-sem-*, --hm-color-*, --hm-radius-*(:root)	--hm-sw-header-*, --hm-sw-property-*(SWTheme 범위)	--hm-orgchart-* 공개 입력(Shadow DOM 상속)
색·Typography	DESIGN_RULES §2·§3	DESIGN_RULES §2·§3	DESIGN_RULES §2·§3
크기·여백	DESIGN_RULES §4	DESIGN_RULES §1	카드·간격 변경 금지(승인 디자인)
Border·Radius·배경·그림자	DESIGN_RULES §2·§4	DESIGN_RULES §2·§8	공개 입력만
아이콘	lucide-react(패키지 의존성)	패키지 내장 SVG만, 새 아이콘은 사용자 제공	Core 내장
스크롤바	ScrollArea(Radix), DESIGN_RULES §6	전용 디자인 없음 — 브라우저 기본(AI_USAGE §2)	Core 내부 Zoom/Pan
Hover / Active / Focus / Disabled	DESIGN_RULES §5	DESIGN_RULES §4	Core 내장
Popup·Panel	Dialog·AlertDialog·Sheet·Drawer·Popover	SWPopup + SWPopupSection/SWPopupRow	Core 팝업 / HM Dialog / 어댑터
동작·키보드	Radix 동작 유지	카탈로그 "공통 키보드"	Core 키보드(Pan, Alt+M 이동 등)

5단계. 패키지별 디자인 분리 (혼합 사용 포함)

각 패키지의 스타일 범위는 다음과 같습니다(실제 CSS 기준).

패키지	스타일이 적용되는 범위	주의
Web	theme.css의 토큰은 :root, [data-hm-theme]. tailwind.css는 Tailwind base에서 *(border·outline), body(배경·글자), html(글꼴)을 문서 전체에 적용. 앱이 import하는 tailwindcss의 Preflight도 전역	Web CSS를 넣은 문서에서는 다른 영역에도 전역 초기화가 적용됨
SW	토큰은 .hm-sw-header와 .hm-sw-theme(<SWTheme>)에만 정의. 전역 선택자 없음	Header 밖 SW 부품은 반드시 <SWTheme> 안
OrgChart	Core가 자기 open Shadow DOM에만 CSS 로드. 호스트 CSS selector는 안쪽에 닿지 않고 Custom Property 상속만 통과	호스트 class로 카드 모양을 바꾸려 하지 않음

혼합 규칙:

1. 영역마다 하나의 패키지를 정하고 그 영역의 신규 UI는 그 패키지의 토큰만 읽습니다. Web 토큰(--hm-sem-*)을 SW 영역에, SW 토큰(--hm-sw-*)을 Web 영역에 쓰지 않습니다. OrgChart 내부는 --hm-orgchart-*만 씁니다.
2. 다른 패키지 컴포넌트는 문서에 허용된 지점에서만 씁니다.
   • SW SWPopup의 children 안 Web 컨트롤(SW 카탈로그가 허용, 예: Popup 하단 Button)
   • OrgChart Full Page의 바깥 레이아웃 = Web(또는 요청된 패키지)
   • OrgChart React의 직원 팝업 = 선택 @hm-design/org-chart-react/hm-dialog(Web Dialog, Web Theme CSS 필요)
3. 패키지 class(hm-sw-*, hm-orgchart-*, Web data-slot)를 소비 코드에서 덮어쓰지 않습니다. 배치는 className·style과 소비 프로젝트 class로 합니다.
4. Web + SW를 한 문서에 함께 쓰면 Web의 전역 base(위 표)가 SW 화면에도 적용됩니다. SW는 자기 범위에서 버튼 등을 초기화하지만 이 조합의 시각 결과는 패키지에서 검증된 적이 없습니다(NOT VERIFIED). 이 조합이면 브라우저에서 SW 부품의 글꼴·테두리·배경을 직접 확인하고 차이를 보고합니다. 가능하면 Web CSS가 없는 SW 전용 화면(별도 entry)으로 분리합니다.
5. Web Scoped Theme([data-hm-theme])는 body Portal(Select·Popover·DatePicker 팝업)에 전달되지 않습니다. Web 영역만 다른 테마로 바꾸려면 Global Theme를 쓰거나 차이를 보고합니다.

6단계. 디자인 검증

소비 프로젝트에서 실제로 실행한 것만 PASS로 적습니다.

1. Typecheck(tsc --noEmit 등)와 Production Build
2. 브라우저 렌더링: 재사용한 컴포넌트가 HM 외형으로 보이는지(CSS 진입점 누락 확인), 신규 UI가 같은 토큰을 쓰는지
3. 상태·동작: Hover / Focus(키보드) / Disabled, Popup 열기·닫기·Escape·Focus 복귀, 선택 패키지의 핵심 동작
4. 폭: Web 390 / 768 / 1280 / 1440px, SW는 대상 창 폭(Header는 반응형 More 포함), OrgChart는 캔버스 크기·초기 Fit
5. 혼합이면 영역 경계에서 스타일 침범이 없는지(§5)
6. 실행하지 못한 항목은 NOT VERIFIED로 남깁니다.

7단계. 결과 보고 형식

## HMDesign 적용 결과
- 사용 유형: Web | SW | OrgChart(Chart Only|Full Page) | 혼합(영역별: …)
- 패키지·버전: @hm-design/ui 0.1.0, …
- 재사용한 컴포넌트: …(Props 설정 포함)
- 조합한 부분: …
- AI가 새로 구현한 부분: 파일 경로 · 이유(카탈로그에 없음) · 안쪽에서 재사용한 컴포넌트
- 적용한 디자인 토큰: --hm-… (신규 UI가 읽은 것)
- 카탈로그와 .d.ts 차이: 없음 | …
- 검증: Typecheck PASS · Build PASS · 브라우저(폭/상태) … · NOT VERIFIED: …
- 제안(구현하지 않음): …

8. 상황별 예시

예시 A — Web 화면 (목록 + 검색)

• 읽기: node_modules/@hm-design/ui/ai/ → COMPOSITION_PATTERNS "목록 화면"
• 재사용: LNB(또는 GNB) 중 하나, PageHeader, Card, FilterBar + FilterBarSearch + FilterBarActions, DataTable + useDataTable, Button
• 신규(필요 시만): 카탈로그에 없는 콘텐츠 블록 → 소비 프로젝트 컴포넌트, --hm-sem-* 토큰과 Card 재사용

/* src/index.css */
@import "tailwindcss";
@import "@hm-design/ui/tailwind.css";
@import "@hm-design/ui/theme.css";

import { Button, Card, CardContent, FilterBar, FilterBarActions, FilterBarSearch, PageHeader, PageHeaderContent, PageHeaderTitle } from "@hm-design/ui"

예시 B — SW 뷰어

• 읽기: node_modules/@hm-design/sw/ai/ → COMPOSITION_PATTERNS "6. 파일 열기 + 도구 막대", 예제 ai/examples/ExampleF-ViewerToolbar.tsx
• 재사용: SWHeader(documentOpenPlacement="header", controls, tools), SWToolGroup + SWToolButton(Model/Layout 탭, Fit 등), SWPopup + SWPopupSection + SWPopupRow + SWHeaderInput(설정 Popup)
• 신규: SW에 없는 기능(예: 검색) → 소비 프로젝트 컴포넌트, <SWTheme> 안, --hm-sw-header-* 토큰, 안쪽 입력은 SWHeaderInput(예제 ExampleD-SearchExtension.tsx)

import { SWHeader, SWPopup, SWTheme, SWToolButton, SWToolGroup } from "@hm-design/sw"
import "@hm-design/sw/styles.css"

예시 C — 조직도만 (Chart Only)

• 읽기: node_modules/@hm-design/org-chart/ai/ → COMPOSITION_PATTERNS "1. Chart Only"
• 재사용: React OrgChart(@hm-design/org-chart-react) 또는 Vanilla createOrgChart, 데이터 JsonOrgChartDataSource + validateOrgChartDataset
• 필수 옵션: layoutMode="auto" + presentationMode="chart-only"(초기 Fit·직접 휠 Zoom이 기본)
• 추가하지 않음: 페이지 제목·통계·설명·Zoom 버튼 바·외부 회색 배경·Navigation. Fixed Chart Only는 미지원(TypeError)

import { OrgChart } from "@hm-design/org-chart-react"
import { JsonOrgChartDataSource } from "@hm-design/org-chart"
import engineUrl from "@hm-design/org-chart/engine.css?url" // Vite. 다른 도구는 실제 배포 URL
import coreUrl from "@hm-design/org-chart/style.css?url"

예시 D — Web + OrgChart (Full Page)

• 영역: 페이지 레이아웃·제목·필터 = Web, 조직도 영역 = OrgChart
• 읽기: Web ai/ + OrgChart ai/COMPOSITION_PATTERNS.md "2. Full Page"
• 재사용: Web LNB/GNB 중 하나, PageHeader, Card, Select·Label(회사 선택 등 요청된 컨트롤만) + OrgChart OrgChart(selectedCompanyIds 등 Props로 연결)
• 직원 팝업을 Web Dialog로: import { OrgChart } from "@hm-design/org-chart-react/hm-dialog" + employeePopup="hm-dialog"(Web CSS 진입점 필요)
• 분리: 조직도 카드·색은 OrgChart 기본 유지. Web 토큰을 조직도에 넣지 않음(바꿔야 하면 --hm-orgchart-* 공개 입력만)

9. 소비 프로젝트 설정 — AI가 이 지침을 찾게 하기

AI 코딩 도구는 보통 프로젝트 루트의 AGENTS.md(Codex 등)·CLAUDE.md(Claude Code)·도구별 규칙 파일만 자동으로 읽고 node_modules는 읽지 않습니다. 패키지 설치만으로 지침이 자동 적용되지는 않으므로 소비 프로젝트에서 한 번 연결합니다.

1. 패키지에 들어 있는 ai/AGENTS_SNIPPET.md를 루트 AGENTS.md(없으면 새로 만듦)에 붙여 넣고 HMDesign 사용 유형: 줄을 프로젝트에 맞게 고칩니다. 정하지 않았으면 그 줄을 지워 AI가 1단계에서 묻게 합니다.

   cat node_modules/@hm-design/ui/ai/AGENTS_SNIPPET.md >> AGENTS.md
   

   (PowerShell: Get-Content node_modules/@hm-design/ui/ai/AGENTS_SNIPPET.md | Add-Content AGENTS.md. 설치한 아무 HMDesign 패키지의 사본이나 같습니다.)
2. Claude Code는 CLAUDE.md에 @AGENTS.md 한 줄을 두면 같은 내용을 읽습니다. 다른 도구(Cursor 규칙 등)는 그 도구의 규칙 파일에 같은 내용을 넣습니다.
3. 패키지를 업데이트한 뒤 스니펫이 바뀌었는지 확인합니다(스니펫은 경로 안내만 하므로 보통 그대로 둡니다).

자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(postinstall 없음), 도구가 node_modules를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다.

10. 문서 갱신 (HMDesign 저장소 유지보수자)

컴포넌트를 추가·수정하면 같은 변경에서 해당 패키지 ai/COMPONENT_CATALOG.md와 필요한 DESIGN_RULES.md·COMPOSITION_PATTERNS.md를 갱신하고 npm run check:ai-docs를 통과시킵니다. 절차는 저장소 docs/ai/MAINTAINING.md(패키지 미포함)에 있습니다.