115 lines
13 KiB
Markdown
115 lines
13 KiB
Markdown
# 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에 동일하게 적용한다. [상세 정책](docs/guidelines/navigation-single-mode.md), [AI 작업 지침](AGENTS.md).
|
|
|
|
새 화면을 구현하는 AI는 [AI 화면 구현 Quick Start](AGENTS.md#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 작업 또는 운영 업로드는 필요 없습니다. [실행 및 포함 범위](docs/guidelines/portable-test-distribution.md).
|
|
|
|
## 오전 소스 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 환경의 프로젝트 루트에서 다음을 실행합니다.
|
|
|
|
```powershell
|
|
# 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)
|
|
|
|
```ts
|
|
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/
|
|
```
|
|
|
|
```css
|
|
@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 예제](docs/patterns/dashboard-layout.md#dashboard-업무-상태-공통-계약)를 적용합니다. API import나 Status CSS만으로 Badge 색상이 자동 선택되지는 않습니다.
|
|
|
|
별도 React 앱은 [Tailwind v4 검색 범위 가이드](docs/guidelines/runtime-portability.md#21-tailwind-v4-소비자-검색-범위)를 확인합니다. `source("./")`는 CSS 위치에 따라 범위가 달라지며 HM `tailwind.css`의 명시 source를 유지해야 합니다. 공개 package Theme는 동봉된 `dist/fonts/`를 상대 URL로 참조합니다. 개발 저장소·포터블 ZIP·React 소비자·단일 HTML의 차이는 [폰트·Asset 경로](docs/guidelines/runtime-portability.md#41-noto-sans-kr-경로-실행-환경별-확인)를 따릅니다.
|
|
|
|
화면 생성 Reference: [Navigation 선택 근거](docs/guidelines/navigation-single-mode.md#선택-근거), [GNB Desktop·Mobile 구성](docs/patterns/gnb.md#8-desktop--mobile)과 [내부 Sidebar](docs/patterns/gnb.md#15-gnb-only-sidebar-composition-2026-10-08), [FilterBar 조회·초기화 소비 예제](docs/patterns/filter-bar.md#61-조회-버튼으로-적용하는-소비-예제). 일반 업무 목록의 모드를 임의 확정하거나 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](docs/guidelines/theme-delivery.md). 디자인팀 사용법: [Theme guide](docs/guidelines/designer-theme-guide.md).
|
|
|
|
## 공식 가이드 / Source of Truth
|
|
|
|
- AI 구현·Component 재사용: [AGENTS](AGENTS.md), [Component 구현 원칙](docs/guidelines/shadcn-기반-구현-원칙.md)
|
|
- Component / Pattern 탐색: [통합 Reference Index](docs/guidelines/component-pattern-reference.md), `packages/ui/src/index.ts`, 구현 소스·사용 문서·대표 Story
|
|
- Theme: [Token 정책](docs/guidelines/테마-토큰-가이드.md), [Runtime 계약·사용법](docs/guidelines/runtime-theme.md)
|
|
- Runtime portability: [Runtime / AI Independent Portability Policy](docs/guidelines/runtime-portability.md)
|
|
- Navigation: [단일 모드 정책](docs/guidelines/navigation-single-mode.md)
|
|
- Dashboard: [Dashboard Pattern](docs/patterns/dashboard-layout.md)
|
|
- CENTER: [CENTER 구현·사용 범위](docs/center-graphic/README.md)
|
|
- 프로젝트·서비스 적용: [프로젝트 지침](docs/guidelines/프로젝트-지침.md), [개발 적용](docs/guidelines/개발-적용-가이드.md)
|
|
|
|
## Package Registry / Publish (별도 내부 운영 정보)
|
|
|
|
패키지 build와 Registry publish는 별도 단계입니다. Registry 설치·publish·실제 CDN 운영은 이번 테스트 ZIP의 실행 조건이나 검증 범위가 아닙니다. 서비스 배포·버전·캐시·롤백 계획은 [운영/배포 가이드](docs/guidelines/운영-배포-가이드.md)를 따릅니다.
|
|
|
|
CENTER Graphic은 현재 내부 테스트/검토 목적 범위에서 제공합니다. 외부 공개 또는 사외 배포 전 별도 License 확정이 필요합니다. 임의의 오픈소스 License를 부여하지 않습니다.
|