HMDesign/packages/org-chart/ai/DESIGN_RULES.md

OrgChart 디자인 규칙

출처: Core style.css(원본 src/styles/design-tokens.css)·src/core/style-presets.ts·company-color-presets.ts와 사용자 승인 기록(2026-10-13 APPROVED). OrgChart는 독립 디자인입니다. Web(--hm-sem-*)·SW(--hm-sw-*) 토큰의 영향을 받지 않고, 그 토큰을 조직도 안에 넣지 않습니다.

1. 원칙

1. 승인된 기본 디자인을 그대로 씁니다. 카드·회사색·그룹 제목·연결선·Typography·간격·배치를 바꾸지 않습니다. 기본값 자체를 바꾸려면 사용자 확인이 먼저입니다.
2. 커스터마이징은 공개 CSS 입력(--hm-orgchart-*)만으로 합니다(외부 테마). 이는 기본값 변경과 구분해 보고합니다.
3. 새 카드·연결선·노드 디자인을 만들지 않습니다. Shadow DOM 내부 DOM을 스크립트로 바꾸지 않습니다.
4. resolved-*, current-*, expanded-primary, expanded-card-primary는 내부 계산 변수입니다. 쓰지 않습니다.

2. 승인된 기본값

항목	값
Auto(Expanded)·Chart Only 캔버스	흰색 #FFFFFF
Fixed readOnly / Full Composition 배경	#F5F8FB(bg-content 기본)
회사 메인 컬러(Auto 그룹 제목·카드 강조)	hanmac 한맥기술 #CB2E28, saman 삼안 #F08300, jangheon-industry 장헌산업 #4580A6, jangheon 장헌 #1D418D, ptc 피티씨 #84338E, halla 한라산업개발 #0068B7, baron 바론컨설턴트 #0C367F
그룹 제목 글자	흰색
Auto 연결선	#738399(expanded-line-color 기본)
Fixed 부서 Gradient	6종(business-management, business-planning, talent-growth, integrated-system, design-planning, solution-sales). 회사색과 별개 — 서로 대체하지 않음
글꼴	Noto Sans KR(--hm-orgchart-font-family로 override 가능). 호스트가 font-face 등록
Weight	400 / 500 / 700만

접근성 미해결(숨기지 않음): 삼안 #F08300(흰 글자 약 2.64:1), 장헌산업 #4580A6(약 4.29:1)은 WCAG AA 4.5:1 미달입니다. 디자인은 승인됐지만 접근성 준수 판정은 NOT VERIFIED입니다.

3. 공개 CSS 입력 (--hm-orgchart- 접두사)

입력(접두사 생략)	범위
fixed-canvas-background, expanded-canvas-background	Fixed composition·stage / Auto 내부 viewport 배경(서로 독립)
bg-surface, bg-content, bg-subtle, bg-brand	캔버스·내용·보조·브랜드 배경
fg-primary, fg-secondary	글자
stroke-default, stroke-input-default, stroke-input-focus	테두리·Focus
accent-color, on-accent, action-primary, on-action-primary	강조·액션
company-{id}, company-{id}-secondary-{n}	Auto 회사 제목·소속 카드 강조선(7개 ID)
group-title-background, group-title-color, group-border	그룹 제목·Fixed 조직 카드 상단 Border
card-background, card-color, card-position-color, card-border, card-accent	카드
leader-card-background, top-leader-card-background	Auto 그룹장·대표자 카드
card-hover-background, card-focus-color	Hover·Focus
expanded-line-color, fixed-line-color	연결선
gradient, border, department-color, {department}-gradient / -border / -department-color / -card-background / -card-color	Fixed 부서
status-title-*, status-card-*, dispatched-*, on-leave-*	파견·휴직
dialog-background, dialog-color, dialog-border, dialog-close-color, dialog-close-hover-background, dialog-focus-color	Core 기본 팝업
font-family	글꼴

적용 방법 (둘 중 하나)

/* A. 호스트 상속: 기본 stylesheetUrls.core 유지 + 컨테이너 class (변수만 Shadow DOM을 통과) */
.app-orgchart-theme {
  --hm-orgchart-company-hanmac: #2457a7;
  --hm-orgchart-expanded-line-color: #249a79;
}

/* B. Shadow DOM 안 외부 테마 파일: 기본 CSS를 먼저 import하고 :host에 override → 이 파일 URL을 stylesheetUrls.core로 */
@import "@hm-design/org-chart/style.css"; /* Vite. 일반 서버는 복사한 style.css URL */
:host { --hm-orgchart-card-background: #f4f8ff; }

• 호스트의 .hm-orgchart-… 같은 selector는 Shadow DOM 안에 닿지 않습니다. 내부 selector 수정이 꼭 필요하면 B 파일 안에 작성합니다.
• stylesheetUrls.core를 변수만 있는 파일로 바꾸면 기본 레이아웃이 사라집니다(B는 반드시 기본 CSS import 포함).
• Fixed의 PNG·SVG 카드·로고 이미지 내부 색은 CSS로 바뀌지 않습니다.
• Web Dialog(/hm-dialog) 팝업은 Shadow DOM 밖 Web 컴포넌트라 dialog-* 입력이 아니라 Web Theme를 따릅니다.

4. 레이아웃·동작 기준

항목	Fixed	Auto(Expanded)
배치	승인된 Workdesk 구성, 비례 축소	데이터 기반 가변 계층(TB / LR / Hybrid)
Zoom / Pan	없음	5–300%(zoom), Ctrl/⌘+휠(기본) 또는 일반 휠(wheelZoom='direct'), 빈 공간 Drag Pan, 방향키 Pan
Chart Only	미지원	presentationMode='chart-only'
접기	—	그룹 제목 클릭(native toggle, aria-expanded)
직원 팝업	Core 팝업	Core / HM Dialog / 어댑터 / 없음
이동 편집	없음	dragDropEnabled (기본 OFF)

• Chart Only 초기 Fit: 전체 Bounds를 16px 여백 안에 가로·세로 중앙 배치, 100% 이상 확대하지 않음. 사용자가 조작한 뒤에는 크기가 바뀌어도 다시 Fit하지 않음.
• 캔버스 높이는 container 높이(정해지지 않으면 최소 320px). Chart Only 컴포넌트의 높이는 호스트가 정합니다.
• 조직도 바깥(제목·필터·패널)은 OrgChart 디자인이 아닙니다. Full Page에서는 Web 등 선택한 패키지의 규칙을 따릅니다.