# HMDesignSystem

> 기준 우선순위: 2026-10-10 추가 수정 요청의 확정 사항 → 충돌하지 않는 D-01/D-02 → 현재 HM Component/Pattern/Theme → 현재 Storybook/구현 → 과거 문서. [현재 추가 수정 기준](docs/guidelines/publisher-additional-review-2026-10-10.md). 미확정 값은 임의 확정하지 않으며 과거 검증 기록은 보존합니다.

shadcn/ui(Radix, Tailwind v4, CVA) 기반 HM 디자인 시스템 시제품. React + TypeScript + Vite, 개발 Storybook 포트 6024(포터블 테스트 ZIP은 기본 6007, 충돌 시 자동 변경). 실행법과 파일 위치는 `README.md`를 따른다.

## 지침 문서

- 확장형 OrgChart의 조직 계층 생성 시 팀(Team)은 셀(Cell)의 직접 자식 및 모든 하위 계층에 배치하지 않는다. 팀 → 셀은 허용하며 셀의 다른 하위 조직을 일괄 금지하지 않는다. Storybook 샘플과 AI 생성 데이터에 같은 기준을 적용한다. 다른 조직 유형의 기존 관계·공개 API·런타임 검증은 유지하며 [AI 생성 정책 §2.1](docs/org-chart/ai-page-generation-rules.md#21-확장형-조직-위계-규칙)을 따른다.
규칙의 기준은 아래 문서이며, 이 파일에는 규칙 본문을 복사하지 않는다. 작업 전에 해당 문서를 읽는다.

- `AGENTS.md` — AI Implementation Defaults와 Navigation 필수 요약. 기존 Component / Storybook Reference 우선, Theme / Semantic 기본 적용, 단일 Navigation, 최소 Custom은 사용자의 별도 지시 없이 모든 신규·수정 UI에 적용한다.
- [최종 디자인 승인 기록](docs/org-chart/design-approval.md) — OrgChart UI 수정 또는 AI 생성 작업 전에 먼저 확인하고 승인된 기본 디자인을 따른다. 기본값 변경·외부 테마 커스터마이징·데이터 생성의 구분과 접근성 미해결 상태는 해당 문서를 따른다.
- [AI 조직도 자동 생성 정책](docs/org-chart/ai-page-generation-rules.md) — 자연어 또는 JSON·CSV·Excel에서 새 조직도 컴포넌트 또는 전체 페이지를 생성할 때 먼저 읽는다. 생성 방식 미지정 시 코드 작성 전에 위 정책의 사전 선택 질문으로 Chart Only / Full Page를 확인하고 답변 후 구현한다. 이미 명시한 방식은 다시 묻지 않는다. Chart Only는 흰색 캔버스·노드·연결선의 삽입용 컴포넌트, 최초 Fit·휠 Zoom·Pan과 외부 UI 제외를 따르고, Full Page는 기존 HM UI로 요청 UI·전체 배치·반응형을 구성한다. 두 방식 모두 가변 계층·정확한 인원·제공 데이터 보존·기존 Core/React 재사용을 따른다. Fixed·Auto/Expanded는 생성 방식 선택을 대신하지 않는다. Chart Only의 Navigation 예외와 Full Page의 HM 화면 계약은 `AGENTS.md`를 따른다. 기존 Full Composition·Expanded OrgChart·Department Colors·Overview·P9.5·P-AI1에는 소급 적용하지 않는다.
- 일반 업무 화면은 Storybook에 등록하지 않고 별도 React 화면·독립 미리보기로 제공한다. Storybook 수정은 Component/Pattern 또는 명시적 Storybook Reference 작업에 한정한다. 상세한 Storybook / 화면 생성 분리는 `AGENTS.md`와 `docs/guidelines/shadcn-기반-구현-원칙.md`를 따른다.
- `docs/guidelines/프로젝트-지침.md` — §6 컴포넌트·Storybook·CSS 작업 규칙 (모든 컴포넌트 작업 전 필독)
- `docs/ai/MAINTAINING.md` — 패키지에 포함되는 소비 프로젝트용 AI 지침(`packages/*/ai/`, 공통 원본 `docs/ai/AI_GUIDE.md`). 공개 API·토큰 변경 시 같은 변경에서 갱신하고 `npm run check:ai-docs`를 실행한다.
- `docs/guidelines/shadcn-기반-구현-원칙.md` — Component / Pattern / Story의 재사용 우선순위와 Custom 구현 허용 조건 (관련 작업 전 필독)
- `docs/guidelines/테마-토큰-가이드.md` — Token 구조, 이름 규칙, HM Default/External Runtime 계약, Light/Dark 없음
- `docs/guidelines/개발-적용-가이드.md`, `운영-배포-가이드.md`, `theme-delivery.md` — JSON 원본/Runtime URL Loader/독립 Theme 배포와 향후 실제 CDN·Publish의 경계

> `docs/guidelines/`의 개정안/검토용 표기와 관계없이 2026-10-07 사용자 확정 AI 기본 구현 정책과 2026-10-08 Navigation Sidebar 운영 정책은 필수 적용한다. 과거 로컬 지침은 현재 정책을 대체하지 않는다.

## 반드시 지킬 것 (요약)

- HMDesign의 Font Weight는 400(Regular), 500(Medium), 700(Bold)의 3단계만 사용한다. Font Weight 600은 사용하지 않으며, 카드 제목은 700을 기본으로 한다. 신규 컴포넌트와 AI 생성 코드에도 적용하며, 상세 기준은 [테마·토큰 가이드](docs/guidelines/테마-토큰-가이드.md#font-weight-policy)를 따른다.

- 구현 우선순위는 기존 `@hm-design/ui` → 기존 Variant / Prop → 기존 Composition → shadcn → Radix Primitive → 최소 Custom이다. Visual은 처음부터 기존 Theme / Semantic / Component Mapping에 연결한다. 상세 탐색·범위 분류·예외 조건은 `docs/guidelines/shadcn-기반-구현-원칙.md`를 따른다.
- Behavior / Structure는 shadcn/Radix를 유지하고 Visual은 HM Theme로 조정한다. 디자인 차이만으로 별도 Component, interaction logic 또는 Production API를 만들지 않는다.
- HM이 값을 지정한 속성은 Theme Token으로, 지정하지 않은 속성은 shadcn 기본 구현 그대로 둔다.
- shadcn 구조(CVA, `data-slot`, `cn(..., className)`)와 공개 API를 불필요하게 바꾸지 않는다. wrapper를 추가하지 않는다.
- `<Button />`처럼 기본 API만으로 HM 디자인이 적용되어야 한다. 소비자가 `hm-*` class를 붙이는 구조를 새로 만들지 않는다. `className`은 사용자 확장용이다.
- Story는 소비 프로젝트와 같은 API로 작성한다. Story 전용 class로 외형을 보정하지 않는다.
- HM Default와 외부 JSON은 같은 Runtime 계약을 쓴다(`docs/guidelines/runtime-theme.md`). 컬러 원본은 `themes/*.json`, package fallback은 생성한다. Storybook의 Designer JSON Preview/Editor는 이 계약의 소비자다. Light/Dark preset이나 `dark:` 분기/Dark Token은 추가하지 않는다.
- 컴포넌트 CSS에 `html`, `body`, `*` 전역 규칙이나 페이지 레이아웃을 넣지 않는다.

## 검색·검증 효율

- 변경과 관련된 소스 경로(`packages/ui/src`, `src/components`, `src/patterns`, `docs/<영역>`)부터 검색한다. 드라이브나 저장소 전체 탐색은 하지 않는다.
- `rg`를 우선 사용하고 `node_modules`, `_local`, `dist`, `storybook-static` 등 생성물·로컬 작업본은 기본 검색에서 제외한다(`-g '!…'`). 전체 검색 후 `grep -v`로 걸러내는 방식은 쓰지 않는다.
- 검증은 변경 범위에 필요한 최소 단위로 한다. 공유 `dist`를 쓰는 build는 동시에 실행하지 않는다.
- 속도를 이유로 파일 삭제나 캐시 정리를 하지 않는다.
- 실제로 실행·확인하지 않은 항목은 PASS로 보고하지 않고 미검증으로 기록한다.

## 디자인 규격 (ui_viz)

> 2026-10-02: ui_viz는 최종 기준이 아니라 이전 테스트/검증 프로젝트이며 참고 자료다. 새 컴포넌트의 기준은 `프로젝트-지침.md` §6.9와 `docs/components/<name>.md`를 따른다. 아래 항목은 이 기준으로 읽는다.

- 정합성 감사의 1차 Source of Truth는 현재 Production 코드와 실제 Storybook이다. 이 저장소 문서는 코드와 대조하며 과거 보고서는 참고 자료다. 외부 ui_viz는 ZIP 미포함 선택적 Reference이며, 제공받은 경우에만 당시 `Confirmed` 근거를 참고한다. `TBD`/`HOLD`/`Candidate`/`Temporary`/`REVIEW VALUE`는 확정값이 아니다.
- 해당 도메인의 HM 문서와 대표 Story부터 읽는다: UI는 `docs/components/<component>.md`, Layout은 `docs/patterns/`, Theme은 `docs/guidelines/runtime-theme.md`를 따른다. 외부 ui_viz의 owner 문서·asset은 제공된 경우에만 관련 범위에서 참고한다. CENTER 자료는 `center-graphic` 작업에만 사용하며 UI 규격과 섞지 않는다.
- UI 컴포넌트를 수정할 때는 이 저장소의 `docs/components/<component>.md`를 먼저 읽고 현재 코드와 대조한다. HM 사용자 확정 결정은 외부 ui_viz보다 우선한다. 외부 문서 경로는 이 저장소의 동명 문서와 구분한다. 상세는 `프로젝트-지침.md` §6.8.
- ui_viz의 Web class와 DOM은 복사하지 않고 shadcn API로 구현한다. 상세는 `프로젝트-지침.md` §6.7.
- Layout/Pattern(GNB, LNB, Dashboard, Page) 작업도 현재 HM 대표 Story / Pattern과 단일 Navigation 정책을 먼저 따른다. 외부 ui_viz의 기존 테스트 레이아웃(ZIP 미포함)은 현재 HM 기준과 충돌하지 않는 구조·시각 참고 자료로 사용한다(`프로젝트-지침.md` §6.11).

## 작업 방식

- 요청하지 않은 리팩토링을 하지 않는다. 변경은 요청된 컴포넌트와 직접 필요한 범위로 제한한다.
- 새 패턴은 기준 컴포넌트(Button)에서 먼저 검증한 뒤 다른 컴포넌트로 확장한다.
- 다른 작업자나 AI가 같은 파일을 수정 중일 수 있다. 수정 전 파일의 현재 상태를 다시 읽는다.

## 현재 상태

- Button(`variant`=역할, `appearance`=treatment, `size`), Input(`size`, native 상태 selector), Select(Trigger `size`, Radix 상태 속성)는 ui_viz Confirmed 규격으로 구현했다. Card도 `<Card />`만으로 HM 스타일이 적용된다(ui_viz Content Card, `packages/ui/src/theme/card.css`). Dialog도 `<DialogContent />`만으로 HM 스타일이 적용된다(`packages/ui/src/theme/dialog.css`).
- 구조(2026-10-02 패키지 분리, npm workspaces): UI 컴포넌트·Theme 구현은 `packages/ui`(`@hm-design/ui`, 컴포넌트 `src/components/ui/`, Theme `src/theme/*.css`, 진입점 `src/theme.css`·`src/tailwind.css`), 컴포넌트 문서는 `docs/components/`, Storybook·Demo는 루트(`.storybook/`, `src/`; Demo 스타일은 `src/hm-theme.css`), `packages/center-graphic`(`@hm-design/center-graphic`)은 CENTER 구현(제목·정보·노선/공간·시설물), 기준 문서는 `docs/center-graphic/`다.
- 작업 순서: 컴포넌트 문서 정리, Card, Dialog, 패키지 분리, CENTER 구현, 1단계 UI 컴포넌트(Textarea, Tabs, Label, Checkbox, Radio Group, Switch, Badge, Alert, Separator)와 2단계 A묶음 Floating(Dropdown Menu, Popover, Tooltip, Hover Card)과 B묶음 Modal(Sheet, Drawer(vaul), Alert Dialog)과 C묶음 Expand(Accordion, Collapsible)과 D묶음 Navigation(Breadcrumb, Pagination, Navigation Menu, Menubar)까지 완료로 2단계 UI가 끝났다. 3단계 A묶음 Data/Feedback(Table, Progress, Skeleton, Avatar, Scroll Area)과 B묶음 Selection Controls(Slider, Toggle, Toggle Group)과 C묶음 Search/Date(Calendar, Command, Date Picker, Combobox)까지 완료(새 dependency: `react-day-picker`, `cmdk`)과 D묶음 Layout/Media(Carousel, Aspect Ratio, Resizable)까지 완료로 3단계 UI가 끝났다(새 dependency: `embla-carousel-react`, `react-resizable-panels`). floating surface Semantic 정합성 작업도 완료했다. 4단계 A묶음 독립 UI(Context Menu, Toast/Sonner)까지 완료(새 dependency: `sonner`). 4단계 B묶음 업무 Pattern(Data Table, Filter Bar)까지 완료(새 dependency: `@tanstack/react-table` v9)로 4단계 핵심이 끝났다. Layout Pattern은 GNB·LNB·Page Header·Dashboard Layout까지 완료(`docs/patterns/gnb.md`, `lnb.md`, `page-header.md`, `dashboard-layout.md`, ui-viz 시각 기준)했다. 각 Navigation Mode는 독립 레이아웃을 소유한다. GNB ONLY는 기존 LNB 메뉴 부품을 재사용하는 내부 Sidebar를 허용하며 외곽 배경만 Green Light 2로 적용한다. DASHBOARD ONLY 운영 화면은 전용 Header(48px)·업무 상태 필터 + Content로 구성하고 Sidebar를 금지한다. 운영 최소 폭 960px·내부 가로 스크롤을 유지한다. 기존 DashboardSidebar Export·sidebar slot·1232px 구성은 호환성·검증용이며 신규 운영 Reference가 아니다. LNB 3뎁스(`LNBGroup` 중첩, 2026-10-06)와 모바일 Sheet 중첩 그룹까지 완료(`docs/patterns/lnb.md` §3a). 현재 LNB 모바일은 독립 LNB Mobile Header와 Sheet를 사용한다(`lnb.md` §3b). 과거 GNB+LNB 조합·Brand ownership·gradient 접점 기준은 Navigation Single Mode Policy로 대체되었다. 한 페이지에는 GNB / LNB / DASHBOARD 중 하나만 사용하며 기존 혼합 Story는 verification / VERIFICATION ONLY 조건의 기술 검증에만 한정한다. 경로: UI primitive `packages/ui/src/components/ui`, Pattern `packages/ui/src/patterns`, Pattern 문서 `docs/patterns`. Field는 코드 없이 `docs/components/field.md` 소비 가이드만 둔다.
- 패키지는 5개다: `@hm-design/ui`(Web), `@hm-design/sw`(SW 일반·뷰어 모드, `packages/sw`, Story `src/sw/`, 문서 `docs/sw/`), `@hm-design/org-chart`·`@hm-design/org-chart-react`(OrgChart, Story `src/org-chart/`, 문서 `docs/org-chart/`), `@hm-design/center-graphic`(CENTER). 역할·진입점 표는 `README.md`의 패키지 구성, 외부 설치는 `docs/guidelines/external-install-submodule.md`를 따른다. `org-chart-react`가 Core에 의존하고 `/hm-dialog`만 `@hm-design/ui`를 optional peer로 쓰는 것 외에는 서로 의존하지 않는다. 모두 private이 아니며 compiled dist export(JS·타입·CSS)와 library build가 구현되어 있다. Registry publish 이력은 ZIP 검증 범위 밖이다. Runtime Theme URL Loader와 Theme JSON 독립 산출은 구현되었고 실제 CDN infrastructure/publish pipeline은 미구현이다. CENTER 기준은 `docs/center-graphic/README.md`, `packages/center-graphic/src/`, `src/center/`의 현재 HM 구현과 대표 Story다. 외부 ui_viz owner 자료는 제공된 경우에만 참고하며 필수 실행 경로가 아니다. UI와 CENTER 규격을 섞지 않는다.

> 위 작업 순서는 구현 이력이다. 현재 API·제약은 코드와 Component/Pattern 문서를 대조한다.

## Runtime Theme 구현 (2026-10-06)

- 공개 계약/API: packages/ui/src/theme/contract.ts 및 runtime.ts, @hm-design/ui/theme 진입점. src/theme/preview.ts는 호환 어댑터다.
- HM Default CSS preset과 defaultRuntimeTheme는 같은 계약이다. Partial override, atomic invalid fallback, cleanup, Global/독립 Scoped override를 지원한다.
- Scoped Theme의 Portal은 DOM 경계를 따른다. SelectContent/PopoverContent/DatePicker에는 현재 container 전달 API가 없으므로 wrapper Scoped Theme가 body Portal에 자동 전달되지 않는다. Global Theme는 Portal에도 적용된다. Scoped popup 지원은 별도 API 검토 항목이다.
- Runtime의 fetch/resolve/load API는 구현되어 있고 실제 CDN/Publish/pipeline은 미구현이다. `build:themes`는 UI/Graphic build 없이 JSON만 산출한다. Theme Runtime은 HM_THEME / Theme infrastructure이며 새 Component HM_CUSTOM 항목이 아니다.
- 상세 계약·제한·사용법: `docs/guidelines/runtime-theme.md`, `docs/guidelines/runtime-theme-contract.md`.