HM Design System

React + TypeScript + Vite와 shadcn/Radix 기반 HM 디자인 시스템입니다. Web UI·SW UI·조직도·CENTER Graphic을 독립 workspace 패키지와 통합 Storybook으로 확인합니다.

패키지 구성

npm workspace(packages/*)의 패키지 5개입니다. 서로 의존하지 않으며(아래 표의 예외 제외) 각자 dist/의 ESM JS·타입·CSS를 exports로 공개합니다.

패키지	역할	공개 진입점	Storybook	AI 지침
@hm-design/ui	Web 일반 웹 UI Component(shadcn/Radix)·업무/Layout Pattern·HM Theme Runtime	., /theme, /theme.css, /tailwind.css, /dashboard-status.css	Foundation · Components · Patterns · Theme	packages/ui/ai/
@hm-design/sw	SW 설치형·도면 SW UI. SW 일반 모드(SWHeader·SWPopup·SWFooter)와 SW 뷰어 모드(SWViewer*), 공통 범위 SWTheme. @hm-design/ui와 독립	., /styles.css	SW	packages/sw/ai/
@hm-design/org-chart	OrgChart Core(Vanilla, Shadow DOM, 데이터·배치·상호작용)	., /style.css, /engine.css, /browser	OrgChart	packages/org-chart/ai/
@hm-design/org-chart-react	OrgChart React Wrapper. Core @hm-design/org-chart에 의존하고, 선택 Entry /hm-dialog만 @hm-design/ui(optional peer)를 사용	., /hm-dialog	OrgChart	packages/org-chart-react/ai/
@hm-design/center-graphic	CENTER 그래픽(제목·정보·노선/공간·시설물). 내부 검토 범위, License 미확정	., /reference, /style.css	Center Graphic	없음(README)

다른 프로젝트에서의 설치는 외부 설치 가이드(Git Submodule + npm Workspace)를 따릅니다.

Navigation 정책

ONE PAGE = ONE NAVIGATION MODE. GNB ONLY / LNB ONLY / DASHBOARD ONLY 중 하나를 선택한다. 모바일도 선택한 Navigation 자체의 Responsive Variant를 사용한다. 이 정책은 AI 코드 생성·제안, 신규 페이지, 기존 화면 수정, 프로토타입, Storybook, Production에 동일하게 적용한다. 상세 정책, AI 작업 지침.

새 화면을 구현하는 AI는 AI 화면 구현 필수 규칙을 따른다. 세부 Component·Pattern·Theme·Runtime 계약과 대표 Story 경로도 그 지침에서 연결한다.

Storybook Reference와 화면 생성

퍼블리셔·개발자는 화면 조합 확인과 Tabs의 Card/페이지 Usage를 참고한다. 사전공유 자료의 반영·보류 범위는 2026-10-09 통합 보고에 기록한다. 디자인 방향 승인과 공통 Theme·외부 소비 화면 적용 완료를 구분한다.

Storybook은 기존 HM Component·Pattern·Theme·Variant·State·Interaction을 확인하는 Reference 환경이다. 일반적인 업무 화면 생성에서는 신규 화면을 Storybook Story나 사이드바에 등록하지 않고, 대표 Story를 교체하지 않으며, Storybook 실행을 필수 미리보기 경로로 요구하지 않는다. AI는 별도의 React 화면을 만들고 화면별 빌드·필요한 검증과 독립 미리보기를 제공한다. H-2 또는 유사 자동화가 사용 가능한 경우에는 preview.html·desktop/mobile 이미지 같은 독립 미리보기 산출에만 사용하며 Storybook 등록 기능으로 취급하지 않는다. Storybook 전용 helper/CSS는 운영 화면에 사용하지 않는다. Component·Pattern 추가/수정, 대표/Verification Story 작성 또는 Storybook Reference 개선을 명시적으로 요청한 경우에만 Storybook을 수정한다.

Git Clone 설치·실행 (현재 테스트 공유 기준)

현재 한맥그린·브라운·오렌지는 각 8단계가 완료됐습니다. Orange는 Light 4 #FEBA88 → Light 3 #EC8F53 → Light 2 #F87725 → Light 1 #EB5F00 → Default #CC5200 → Dark 1 #BC4C00 → Dark 2 #883700 → Dark 3 #4F2000입니다. 최신 확정 Palette, Orange 확정 기록, Runtime 계약을 따릅니다. v2 선택 검증 보고의 Dark 1/2 보류는 당시 기록입니다.

공식 소스 저장소는 Gitea HMDesign입니다. 이전 원본은 GitHub HMDesignSystemTest의 90583ab6046ab5dc1ac35d94d38f3301c9a4dfe1이며, GitHub 이력을 병합하지 않고 공식 Gitea의 기존 이력 위에 소스 반영을 완료했습니다. 먼저 AGENTS.md를 읽고 기존 Component → Variant/Prop → Composition 순서로 재사용합니다.

현재 검증 범위와 남은 제한은 2026-10-10 잔여 이슈 회귀 보고를 확인합니다.

후속 Select 비교 화면 넘침 수정, Guard 46개 회귀 테스트, 개발 의존성 분석과 접근성 제한은 2026-10-10 최종 안정화 보고를 확인합니다. 이전 보고서는 당시 기록으로 보존합니다.

이후 Guard CSS Intent·동적 Token 확장(75개 + 증거 연결 20개 + 요구사항 연결 5개)은 Guard 보고, Combobox·GNB/LNB 접근성 보완은 접근성 보고를 따릅니다. 과거 Gitea 이전 전 최종 정합성 확인과 2026-10-12 이전 준비에는 재사용 근거와 잔여 미검증을 구분합니다. 공식 Gitea 이전은 완료됐으며 현재 설치·실행은 위 공식 저장소를 기준으로 합니다. 인용한 과거 보고서는 당시 기록으로 보존합니다.

최신 Generic Status Error는 #B3261E / Provisional이며 기존 Destructive #D32F2F를 유지합니다. Disabled Input Label은 승인된 Input Story 소비 범위 60%, 공통 Label은 50%입니다. Background Gradient 기록과 현재 계약은 Green·Brown·Orange 공통 배경을 구분하며, Foundation Color의 Button 전용 미리보기는 제거하고 실제 Button·Dashboard Gradient는 유지합니다. Focus #266651은 시험 적용 상태입니다.

Node.js는 lockfile의 ^20.19.0 || >=22.12.0 조건을 충족해야 합니다(Node 21 제외). 검증 기록은 Node 20.20.1 / npm 10.8.2(2026-10-11)와 Node 22.23.2 / npm 10.9.8(2026-10-20, SW 포함 전체 build·Storybook build)입니다. Docker 이미지는 node:24-alpine에서 빌드하며 Docker 경로는 아직 실제 빌드로 검증하지 않았습니다. Node 설치 시 제공되는 npm과 PATH를 확인하고, 재현 시에는 검증한 버전을 사용합니다. 최초 설치에는 공식 Gitea와 npm 레지스트리 접근이 필요합니다.

git clone https://gitea.hmac.kr/b25027/HMDesign.git
cd HMDesign
node --version
npm --version
npm ci
npm run build:packages
npm run storybook

브라우저에서 http://localhost:6024/ 를 엽니다. Component는 Components, 업무/Layout Pattern은 Patterns, 브랜드 컬러·Typography는 Foundation에서 확인합니다. 내부 Theme 확인은 ?path=/story/theme-runtime-contract--comparison, Designer는 ?path=/story/theme-designer-playground--editor를 사용합니다. 확정 컬러로 검수하며 Designer 임시 편집은 해당 Story 안에서만 적용됩니다. Designer 사용법.

일반 열람은 로컬 설치 없이 웹 Storybook(https://design.hmac.kr/, main 배포본)을 사용합니다. 위 npm run storybook은 소스를 수정·확인하는 로컬 개발용이며, 종료는 실행 터미널의 Ctrl+C입니다. 기존 서버를 유지하는 별도 포트 QA는 신규 Clone 독립 실행 QA를 따릅니다. 과거 Windows 실행기(start-storybook.bat)는 웹 Storybook 운영으로 제거했습니다.

정적 Storybook 빌드는 npm run build-storybook, 앱 빌드는 npm run build, 타입 확인은 npm run typecheck입니다. 명령은 루트 package.json의 현재 scripts를 기준으로 합니다.

Docker로 Storybook 실행

Docker Engine과 Docker Compose plugin만 있으면 호스트에 Node.js/npm이나 프로젝트 의존성을 설치하지 않고 Storybook을 실행할 수 있습니다. 저장소 루트에서 실행하면 Docker 이미지 안에서 npm ci, 앱 빌드, 정적 Storybook 빌드를 수행한 뒤 nginx가 결과를 제공합니다.

docker compose up -d --build

기본 주소는 http://localhost:6024/ 입니다. 6024가 사용 중이면 로컬 실행 포트를 변경할 수 있습니다.

STORYBOOK_PORT=6025 docker compose up -d --build

PowerShell에서는 다음과 같이 실행합니다.

$env:STORYBOOK_PORT = "6025"
docker compose up -d --build

상태와 로그는 docker compose ps, docker compose logs -f storybook으로 확인하고, 중지할 때는 docker compose down을 실행합니다. 소스 변경 후 docker compose up -d --build를 실행하면 이미지를 다시 빌드하고 서비스를 갱신합니다.

Gitea Actions 배포

.gitea/workflows/deploy-storybook.yml은 main에 push되거나 수동 실행될 때 해당 실행 커밋의 소스 archive를 SSH로 배포 서버에 보내고, 서버에서 Docker build와 Compose 갱신을 수행합니다. 기존 Git 작업 트리는 건드리지 않고 빌드는 서버에서 이뤄지며, 빌드 산출물은 Actions Runner에서 전송하지 않습니다. 실행 커밋별 소스는 .storybook-deploy/releases/에 보관하고 서비스는 배포 서버의 6024 포트를 사용합니다. 새 이미지 빌드가 끝난 뒤 Compose가 컨테이너를 교체하므로 빌드 중에는 현재 서비스를 유지합니다. 따라서 웹 Storybook(https://design.hmac.kr/)은 main 배포본이며, main에 병합되지 않은 브랜치(예: SW 패키지 작업 브랜치)의 Story는 표시되지 않습니다.

저장소 Actions Variables에 DEPLOY_HOST (10.13.10.4), DEPLOY_USER (user), DEPLOY_PATH (/home/user/services/HMDesign), DEPLOY_PORT (22), DEPLOY_KNOWN_HOSTS (배포 서버의 검증된 SSH host key)를 설정하고, Actions Secret에 DEPLOY_SSH_KEY를 등록합니다. 배포 서버 계정은 지정한 경로에 .storybook-deploy/releases/를 만들고 Docker Engine/Compose plugin을 실행할 권한이 필요합니다. Actions Runner는 SSH와 SCP로 배포 서버에 접속할 수 있어야 합니다.

문서 내부 링크 검사는 프로젝트 루트에서 node scripts/check-doc-links.mjs로 실행합니다. .git이 있으면 기존 Git 추적·비추적(ignored 제외) Markdown 수집을 유지하고, .git 없는 압축 해제본에서는 파일 시스템과 루트·하위 .gitignore의 현재 경로·와일드카드·제외/예외 규칙으로 수집합니다. .git 메타데이터와 ignored 폴더는 순회하지 않습니다. Node만 있으면 독립 실행할 수 있으며 결과에 collectionMode, 실제 MD/링크 수와 문제 목록을 출력합니다. 종료 코드 0은 통과, 1은 링크 오류, 2는 수집 실행 오류입니다. 회귀 검사는 node --test scripts/check-doc-links.test.mjs입니다(두 수집 방식 비교에는 Git 필요).

기존 Component 기반 새 React 화면

npm run dev:publisher-example

별도 터미널에서 실행하고 출력된 Vite 주소(기본 5173)를 엽니다. 예제는 실제 공개 HM React Component로 GNB·모바일 메뉴·PageHeader·Card·FilterBar·Select·Button·DataTable을 조합합니다. 새 폴더에 복사한 뒤 title/data/columns를 수정하고 bootstrap의 CSS 연결을 유지합니다. 신규 업무 화면은 Storybook에 등록하지 않습니다. 제작·빌드·Guard·브라우저 확인 절차는 Git 공유 안내에 있습니다.

과거 배포 기록

과거 HMDesignTest.zip, 포터블 r1/r2/r3 및 HMDesign-Publisher-2026-10-10.zip은 당시 스냅샷 기록입니다. 현재 Git Clone에는 ZIP·포터블 Node·사전 빌드 Storybook·로컬 검증 증거가 포함되지 않습니다. 이번 공유를 위해 ZIP을 새로 생성하지 않습니다. 당시 실행 조건과 검증 결과는 과거 포터블 안내와 추가 수정 보고서에 보존합니다. 과거 ZIP의 6007과 현재 개발 Storybook의 6024를 구분합니다.

사용 (workspace)

import { Button } from "@hm-design/ui"
import { CenterTitle, TunnelFacility } from "@hm-design/center-graphic"
import { DataTable, FilterBar, useDataTable } from "@hm-design/ui" // Patterns: docs/patterns/
import { SWTheme, SWHeader, SWFooter } from "@hm-design/sw" // SW 일반 모드
import { SWViewerHeader, SWViewerPanel } from "@hm-design/sw" // SW 뷰어 모드
import { OrgChart } from "@hm-design/org-chart-react" // Core: @hm-design/org-chart

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

이 CSS entry를 소비 앱 bootstrap에서 import합니다. Dashboard 업무 상태를 표시할 때는 Theme 다음에 @hm-design/ui/dashboard-status.css를 추가하고 기존 Badge 색상 mapping과 React 예제를 적용합니다. API import나 Status CSS만으로 Badge 색상이 자동 선택되지는 않습니다.

별도 React 앱은 Tailwind v4 검색 범위 가이드를 확인합니다. source("./")는 CSS 위치에 따라 범위가 달라지며 HM tailwind.css의 명시 source를 유지해야 합니다. 공개 package Theme는 동봉된 dist/fonts/를 상대 URL로 참조합니다. 개발 저장소·포터블 ZIP·React 소비자·단일 HTML의 차이는 폰트·Asset 경로를 따릅니다.

SW는 Tailwind 없이 앱 진입점에서 import "@hm-design/sw/styles.css"를 한 번 추가합니다. 한 화면에서는 SW 일반 모드와 뷰어 모드 중 하나를 고르고, 글꼴 등 토큰은 가장 바깥 <SWTheme style>에서 바꿉니다(SW 사용 안내). SW와 Web UI의 기본 글꼴은 모두 Noto Sans KR입니다(SW는 2026-10-20 Dotum 기본값을 철회하고 확정). 글꼴 토큰은 패키지마다 따로 쓰며 서로의 글꼴 설정을 복사하지 않습니다. OrgChart는 Core CSS 두 개(@hm-design/org-chart/engine.css, /style.css)의 URL을 stylesheetUrls로 전달합니다(Shadow DOM, OrgChart React README).

화면 생성 Reference: Navigation 선택 근거, GNB Desktop·Mobile 구성과 내부 Sidebar, FilterBar 조회·초기화 소비 예제. 일반 업무 목록의 모드를 임의 확정하거나 FilterBar에 조회 API가 있다고 가정하지 않습니다.

루트 package.json의 workspaces(packages/*)로 연결됩니다. 확인: npm run typecheck, npm run build. 위 패키지 구성의 5개 패키지는 모두 private이 아니며 ESM JS·타입 선언·CSS를 dist에서 export합니다. npm run build:packages로 재빌드할 수 있고, Registry publish 이력은 Git 기반 테스트 공유의 검증 범위에 포함하지 않습니다.

파일 위치

아래 경로는 Git 저장소 루트 기준입니다. packages/ui/ 하위 경로도 전체 상대경로로 표기합니다.

• packages/ui/ (@hm-design/ui): UI Component·업무/Layout Pattern과 HM Theme
  • packages/ui/src/components/ui/: shadcn 기반 컴포넌트, packages/ui/src/patterns/: 조합 Pattern(Data Table, Filter Bar 등), packages/ui/src/index.ts: 공개 export
  • packages/ui/src/theme/primitives.css, packages/ui/src/theme/default.css: Default JSON에서 생성한 package fallback과 Semantic/shadcn 연결
  • packages/ui/src/theme/<component>.css: 컴포넌트별 Theme 매핑과 상태 스타일
  • packages/ui/src/theme.css: Theme CSS 진입점, packages/ui/src/tailwind.css: Tailwind 쪽 설정
• packages/sw/ (@hm-design/sw): SW 일반 모드·뷰어 모드 컴포넌트(src/components/), SW Theme CSS(src/theme/), 패키지 테스트(tests/), 소비 AI 지침(ai/)
• src/sw/: SW Storybook(SW 그룹), docs/sw/: SW 설계·Figma 매핑·검증 기록
• packages/org-chart/ (@hm-design/org-chart), packages/org-chart-react/ (@hm-design/org-chart-react): OrgChart Core와 React Wrapper
• src/org-chart/: OrgChart Storybook(OrgChart 그룹), docs/org-chart/: 디자인 승인·AI 생성 정책·구현 보고
• docs/ai/: 패키지 ai/ 공통 지침 원본(npm run sync:ai-docs, npm run check:ai-docs)
• packages/center-graphic/ (@hm-design/center-graphic): CENTER 그래픽(제목·정보·노선/공간·시설물), @hm-design/ui에 의존하지 않음
• src/center/: CENTER Storybook (Center Graphic 그룹)
• docs/center-graphic/: CENTER 구현 기준 문서
• src/App.tsx: 기본 UI 확인 화면 (@hm-design/ui 사용)
• src/hm-theme.css: App/Storybook 예시 화면 스타일. 장식용 시제품 색상은 고정값으로 남아 있음
• themes/default.json, themes/service-example.json: 공식 Default 컬러와 partial 서비스 예제; UI package와 별도 배포
• scripts/theme-templates/, scripts/theme-defaults.mjs: JSON에서 package fallback CSS/데이터 생성; 값은 JSON만 편집
• packages/ui/src/theme/contract.ts, runtime.ts, loader.ts: 공개 Runtime 계약·검증·Global/Scoped 적용 및 URL Loader. @hm-design/ui/theme으로 export
• src/theme/preview.ts: 패키지 Runtime API의 호환 어댑터. themes/drafts/는 Theme 초안 자료
• src/components/*.stories.tsx, src/patterns/*.stories.tsx: Component/Pattern 대표 Story와 숨김 verification Story
• src/theme/*.stories.tsx: Default/External 및 Runtime 계약 검증 Story
• docs/components/: 컴포넌트별 현재 구현 기준 문서
• public/fonts/: 기존 자료의 Noto Sans KR 글꼴과 라이선스
• docs/guidelines/: 프로젝트 지침·구현 원칙·Theme Token·적용/배포 가이드
• 로컬 검증·감사·진단 자료는 Git에서 제외하는 것이 원칙입니다(test-results/, _local/, *.log 등 .gitignore). 과거 증거 경로는 로컬 보관 기록이며 Clone에서 열 수 있는 링크가 아닙니다.
  • 현재 상태와의 불일치(2026-10-20 기준, 정리 정책 미결정): docs/sw/*-qa*/ 등에는 SW 작업의 QA 증거(스크린샷·JSON, 약 600개 파일·40MB)가 Git에 포함되어 있습니다. 반대로 docs/org-chart/ 보고서 일부는 Git에서 제외된 test-results/ 증거를 링크합니다(node scripts/check-doc-links.mjs의 missing path). 두 경우 모두 기록 보존을 위해 삭제·링크 제외 없이 유지하며, 보관 위치는 별도로 결정합니다.

참고 범위

초기 디자인의 색상, Typography, Radius와 Button·Input·Select·Dialog에는 외부 ui_viz Reference를 참고했습니다. 이 Reference는 Git 공유에 포함되지 않으며 실행에 필요하지 않습니다. 현재 Source of Truth는 HM Component/Pattern 구현, 대표 Storybook Story와 아래 공식 정책 문서입니다.

HM Default 컬러의 운영 원본은 themes/default.json이며 생성한 CSS preset은 최초 렌더와 네트워크 실패 시 package fallback입니다. 외부 Theme도 같은 공개 계약을 사용합니다. Active와 Focus는 독립 Semantic이고 Global override와 독립 Scoped override를 지원합니다. Theme/Designer Playground/Editor에서 JSON URL/파일 Preview와 컬러 편집·Reset·Export/Import를 지원합니다. Portal은 실제 DOM scope를 따릅니다.

Component Mapping은 Semantic/Theme palette를 참조하며 기본 API로 HM 스타일이 적용됩니다. Input/Select 크기 규격, Calendar/Date Picker, GNB/LNB 3Depth·Standalone Mobile, Dashboard 내부 Navigation까지 구현되어 있습니다. 현재 상태와 제한은 docs/components/, docs/patterns/, docs/guidelines/runtime-theme.md에서 확인합니다.

하나의 Git Repository에서 UI/Graphic/Theme를 관리합니다. UI는 .·/theme·/theme.css·/dashboard-status.css·/tailwind.css, CENTER는 .·/reference·/style.css를 compiled dist에서 export합니다. Runtime URL Loader와 Theme JSON 독립 산출은 구현했습니다. npm run build:themes는 theme-dist/themes/만 생성하며 UI/Graphic build나 version up을 수행하지 않습니다. Default fallback을 새 package에 반영할 때는 npm run generate:theme-defaults를 사용합니다. 상세 적용·배포: Theme delivery. 디자인팀 사용법: Theme guide.

공식 가이드 / Source of Truth

• AI 구현·Component 재사용: AGENTS, Component 구현 원칙
• Component / Pattern 탐색: 통합 Reference Index, packages/ui/src/index.ts, 구현 소스·사용 문서·대표 Story
• Theme: Token 정책, Runtime 계약·사용법
• Runtime portability: Runtime / AI Independent Portability Policy
• Navigation: 단일 모드 정책
• Dashboard: Dashboard Pattern
• CENTER: CENTER 구현·사용 범위
• SW: SW 패키지 README, SW AI 사용 안내
• OrgChart: 최종 디자인 승인 기록, AI 조직도 자동 생성 정책
• 외부 프로젝트 설치: Git Submodule + npm Workspace
• 프로젝트·서비스 적용: 프로젝트 지침, 개발 적용

Package Registry / Publish (별도 내부 운영 정보)

패키지 build와 Registry publish는 별도 단계입니다. Registry 설치·publish·실제 CDN 운영은 Git 기반 테스트 공유의 실행 조건이나 검증 범위가 아닙니다. 서비스 배포·버전·캐시·롤백 계획은 운영/배포 가이드를 따릅니다.

CENTER Graphic은 현재 내부 테스트/검토 목적 범위에서 제공합니다. 외부 공개 또는 사외 배포 전 별도 License 확정이 필요합니다. 임의의 오픈소스 License를 부여하지 않습니다.