134 lines
16 KiB
Markdown
134 lines
16 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 화면 구현 필수 규칙](AGENTS.md)을 따른다. 세부 Component·Pattern·Theme·Runtime 계약과 대표 Story 경로도 그 지침에서 연결한다.
|
|
|
|
## Storybook Reference와 화면 생성
|
|
|
|
퍼블리셔·개발자는 [화면 조합 확인](docs/guidelines/개발-적용-가이드.md#8-publisher--developer-화면-조합-확인)과 [Tabs의 Card/페이지 Usage](docs/components/tabs.md#16-publisher--developer-조합-안내-2026-10-09)를 참고한다. 사전공유 자료의 반영·보류 범위는 [2026-10-09 통합 보고](docs/guidelines/publisher-integration-2026-10-09.md)에 기록한다. 디자인 방향 승인과 공통 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 설치·실행 (현재 테스트 공유 기준)
|
|
|
|
v2 추가 5개 요청의 구현·실제 Storybook 검증과 Orange Dark 1/2 보류는 [2026-10-11 선택 검증 보고](docs/reports/v2-publisher-review-2026-10-11.md)를 확인합니다.
|
|
|
|
공식 소스 저장소는 [Gitea HMDesign](https://gitea.hmac.kr/b25027/HMDesign)입니다. 이전 원본은 [GitHub HMDesignSystemTest](https://github.com/shkim25027/HMDesignSystemTest)의 `90583ab6046ab5dc1ac35d94d38f3301c9a4dfe1`이며, GitHub 이력을 병합하지 않고 공식 Gitea의 기존 이력 위에 소스만 반영합니다. 먼저 [AGENTS.md](AGENTS.md)를 읽고 기존 Component → Variant/Prop → Composition 순서로 재사용합니다.
|
|
|
|
현재 검증 범위와 남은 제한은 [2026-10-10 잔여 이슈 회귀 보고](docs/guidelines/publisher-validation-2026-10-10.md)를 확인합니다.
|
|
|
|
후속 Select 비교 화면 넘침 수정, Guard 46개 회귀 테스트, 개발 의존성 분석과 접근성 제한은 [2026-10-10 최종 안정화 보고](docs/guidelines/publisher-stabilization-2026-10-10.md)를 확인합니다. 이전 보고서는 당시 기록으로 보존합니다.
|
|
|
|
이후 Guard CSS Intent·동적 Token 확장(75개 + 증거 연결 20개 + 요구사항 연결 5개)은 [Guard 보고](docs/reports/guard-css-intent-dynamic-token-2026-10-10.md), Combobox·GNB/LNB 접근성 보완은 [접근성 보고](docs/reports/accessibility-residual-2026-10-10.md)를 따릅니다. 현재 [Gitea 이전 전 최종 정합성 확인](docs/reports/pre-gitea-finalization-2026-10-11.md)과 [2026-10-12 이전 준비](docs/guidelines/gitea-source-transfer-preparation-2026-10-11.md)에는 재사용 근거와 잔여 미검증을 구분합니다. 공식 이전의 Commit·Push는 최종 검토와 별도 승인 후 수행합니다. 인용한 과거 보고서는 당시 기록으로 보존합니다.
|
|
|
|
Node.js는 lockfile의 `^20.19.0 || >=22.12.0` 조건을 충족해야 합니다(Node 21 제외). 이번 재현 환경은 **Node 20.20.1 / npm 10.8.2**입니다. Node 설치 시 제공되는 npm과 PATH를 확인하고, 재현 시에는 검증한 버전을 사용합니다. 최초 설치에는 공식 Gitea와 npm 레지스트리 접근이 필요합니다.
|
|
|
|
```powershell
|
|
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 사용법](docs/guidelines/designer-theme-guide.md).
|
|
|
|
Windows에서는 기존 `start-storybook.bat`도 사용할 수 있습니다. 의존성이 없으면 `npm ci`, package 산출물이 없으면 `npm run build:packages`를 수행하고 Story index·preview 응답 준비 후 6024 주소를 엽니다. 포트 충돌 시 오류를 표시합니다. 서버 종료는 실행 터미널의 Ctrl+C입니다.
|
|
|
|
정적 Storybook 빌드는 `npm run build-storybook`, 앱 빌드는 `npm run build`, 타입 확인은 `npm run typecheck`입니다. 명령은 루트 package.json의 현재 scripts를 기준으로 합니다.
|
|
|
|
문서 내부 링크 검사는 프로젝트 루트에서 `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 화면
|
|
|
|
```powershell
|
|
npm run dev:publisher-example
|
|
```
|
|
|
|
별도 터미널에서 실행하고 출력된 Vite 주소(기본 5173)를 엽니다. [예제](examples/publisher-list/README.md)는 실제 공개 HM React Component로 GNB·모바일 메뉴·PageHeader·Card·FilterBar·Select·Button·DataTable을 조합합니다. 새 폴더에 복사한 뒤 title/data/columns를 수정하고 bootstrap의 CSS 연결을 유지합니다. 신규 업무 화면은 Storybook에 등록하지 않습니다. 제작·빌드·Guard·브라우저 확인 절차는 [Git 공유 안내](docs/guidelines/publisher-distribution-guide.md)에 있습니다.
|
|
|
|
## 과거 배포 기록
|
|
|
|
과거 `HMDesignTest.zip`, 포터블 r1/r2/r3 및 `HMDesign-Publisher-2026-10-10.zip`은 당시 스냅샷 기록입니다. 현재 Git Clone에는 ZIP·포터블 Node·사전 빌드 Storybook·로컬 검증 증거가 포함되지 않습니다. 이번 공유를 위해 ZIP을 새로 생성하지 않습니다. 당시 실행 조건과 검증 결과는 [과거 포터블 안내](docs/guidelines/portable-test-distribution.md)와 [추가 수정 보고서](docs/guidelines/publisher-additional-review-2026-10-10.md)에 보존합니다. 과거 ZIP의 6007과 현재 개발 Storybook의 6024를 구분합니다.
|
|
|
|
## 사용 (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 이력은 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/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에서 제외합니다. 과거 증거 경로는 로컬 보관 기록이며 Clone에서 열 수 있는 링크가 아닙니다.
|
|
|
|
## 참고 범위
|
|
|
|
초기 디자인의 색상, 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](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 운영은 Git 기반 테스트 공유의 실행 조건이나 검증 범위가 아닙니다. 서비스 배포·버전·캐시·롤백 계획은 [운영/배포 가이드](docs/guidelines/운영-배포-가이드.md)를 따릅니다.
|
|
|
|
CENTER Graphic은 현재 내부 테스트/검토 목적 범위에서 제공합니다. 외부 공개 또는 사외 배포 전 별도 License 확정이 필요합니다. 임의의 오픈소스 License를 부여하지 않습니다.
|