HMDesign/README.md

HM Design System

React + TypeScript + Vite와 shadcn/Radix 기반 HM 디자인 시스템입니다. UI Component·업무/Layout Pattern·CENTER Graphic을 독립 workspace 패키지와 통합 Storybook으로 확인합니다.

Navigation 정책

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

새 화면을 구현하는 AI는 AI 화면 구현 Quick Start의 7단계를 순서대로 따른다. 세부 Component·Pattern·Theme·Runtime 계약과 대표 Story 경로도 그 지침에서 연결한다.

Storybook Reference와 화면 생성

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을 수정한다.

설치 없는 테스트 배포

현재 검증된 테스트 배포 기준은 HMDesignTest-Portable-Test-r3.zip입니다. 사전 빌드된 Storybook과 Windows x64 포터블 Node를 포함하며 정확한 포함 범위는 r3의 BUILD-INFO·Inventory를 기준으로 확인합니다. HMDesignTest-Portable-Test-r2.zip과 HMDesignTest-Portable-Test.zip은 이전 스냅샷 기록으로 보존하며 현재 기준이 아닙니다. 포터블 ZIP의 기본 포트는 6007이고 충돌 시 자동으로 다른 포트를 사용합니다. 개발 저장소 Storybook의 6024와는 별개입니다. 테스트 사용자는 ZIP 해제 → HMDesignTest/start-preview.bat 더블클릭 → 표시된 로컬 URL 열기만 수행합니다. 별도 Node/npm 설치, npm 명령, Git 작업 또는 운영 업로드는 필요 없습니다. 실행 및 포함 범위.

Gitea 소스 다운로드 / Windows Storybook 실행

정식 저장소 https://gitea.hmac.kr/b25027/HMDesign.git를 Git Clone하거나 Gitea 소스 ZIP을 다운로드해 전체 압축을 풉니다. 이 방식은 포터블 ZIP과 달리 PC에 Node.js/npm이 필요합니다. 현재 lockfile의 요구 조건은 Node.js 20.x의 20.19 이상 또는 22.12 이상이며 Node.js 21.x는 지원하지 않습니다.

프로젝트 루트의 start-storybook.bat을 더블클릭하세요. 의존성이 없으면 npm ci를 자동 실행하고, workspace 패키지 산출물이 없으면 기존 npm run build:packages를 실행합니다. 이후 기존 npm run storybook으로 서버를 시작하며, HMDesign Storybook의 Story index와 preview HTTP 응답이 준비된 뒤 기본 브라우저에서 http://localhost:6024/ 를 엽니다. 이미 준비된 HMDesign Storybook이 있으면 서버를 추가 실행하지 않고 기존 주소를 엽니다. 서버 실행 창의 Ctrl+C로 종료합니다.

실행 파일 위치를 기준으로 동작하므로 한글·공백 폴더, 다른 드라이브 및 Git이 없는 ZIP 환경에서도 사용할 수 있습니다. 최초 설치에는 npm 레지스트리 접속이 필요합니다. 포트 6024를 다른 프로그램이 사용하거나 아직 준비되지 않은 서버가 점유하면 포트를 바꾸지 않고 오류를 표시합니다. 해당 프로그램을 종료하거나 기존 서버 준비를 기다린 뒤 다시 실행하세요. 오류가 발생한 경우에만 창을 유지합니다. 출력된 오류, Node.js/npm의 PATH와 버전, 전체 소스 압축 해제 여부 및 네트워크를 확인하세요. 의존성이 불완전하면 프로젝트 루트에서 npm ci를 직접 실행하고 다시 시도합니다.

오전 소스 ZIP / 개발자 전용 절차 (AI 참조용)

오전 소스 배포의 역사적 기준은 HMDesignTest.zip입니다. 당시 전달 구성에서는 .git 디렉터리와 Git 이력·원격 연결 정보를 제외하고 .gitignore와 소스·Storybook·문서·패키지 설정을 유지했습니다. 이 절의 수량·실행 조건은 오전 ZIP에 대한 기록이며 현재 포터블 r3의 포함 범위는 위 절과 BUILD-INFO를 기준으로 확인합니다. HMDesignSystem-test-2026-10-08-r4.zip, HMDesignSystem-Distribution-Test-v2.zip, HMDesignSystem-AI-Reference-Test.zip은 오전 기준을 대체하지 않습니다.

기준 ZIP에는 UI·Pattern·CENTER Graphic, 공개 API, Theme, Storybook 소스, 문서, 예제, 패키지 dist, lockfile 및 폰트가 포함됩니다. node_modules와 storybook-static은 포함되지 않으므로 ZIP 단독으로 정적 Storybook을 바로 열 수는 없습니다.

오전 소스 ZIP을 개발 환경으로 실행할 경우 Node.js 20.20.1 / npm 10.8.2 환경의 프로젝트 루트에서 다음을 실행합니다.

# ZIP을 풀고 프로젝트 루트에서 실행
npm ci
npm run build:packages
npm run dev
npm run storybook

HM 패키지는 ZIP 안의 workspace를 사용하므로 HM Registry 설치가 필요하지 않습니다. npm ci로 의존성을 복원하고 npm run build:packages로 패키지를 빌드한 뒤 앱과 Storybook을 시작합니다. 정적 Storybook이 필요하면 npm run build-storybook을 실행합니다. 이 문서는 배포본의 새 환경 실행 결과를 보증하지 않습니다.

• Storybook: 기준 ZIP의 npm run storybook은 기본 포트 6007입니다. 다른 포트는 npm run storybook -- --port <available-port>로 지정할 수 있습니다.
• ZIP 확인 빌드: npm run build, npm run build-storybook

현재 개발 저장소는 ZIP과 별개로 npm run storybook 기본 포트가 6024이며(포터블 ZIP 6007과 통일하지 않음), npm run build:dashboard-export → dist-dashboard/index.html도 제공합니다. dist-dashboard는 H-1(독립 단일 HTML 미리보기 POC, PASS)의 성공 산출물과 동일하지 않으며 ZIP에도 있다고 가정하지 않습니다. H-2(AI 생성 화면의 자동 빌드·캡처·검증)는 Storybook 배포와 별도 기능이며 구현 완료 여부는 현재 파일과 별도 작업 결과로 확인합니다.

사용 (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 "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 경로를 따릅니다.

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

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

파일 위치

아래 경로는 저장소 루트(압축 해제 시 HMDesignTest/) 기준입니다. 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/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·적용/배포 가이드
• 로컬 검증·감사·진단 자료는 테스트 ZIP에서 제외합니다.

참고 범위

초기 디자인의 색상, Typography, Radius와 Button·Input·Select·Dialog에는 외부 ui_viz Reference를 참고했습니다. 이 Reference는 ZIP에 포함되지 않으며 실행에 필요하지 않습니다. 현재 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 구현·사용 범위
• 프로젝트·서비스 적용: 프로젝트 지침, 개발 적용

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

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

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