shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity

fix(sw): stabilize theme regression test and update integration docs

Browse Source
This commit is contained in:
shkim4 committed 2026-10-20 12:47:48 +09:00
1 parent 73e30242f2
commit 47972c55ff
11 files changed
+186 -23
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+33 -5
View File
@@ -1,6 +1,20 @@
# HM Design System
React + TypeScript + Vite와 shadcn/Radix 기반 HM 디자인 시스템입니다. UI Component·업무/Layout Pattern·CENTER Graphic을 독립 workspace 패키지와 통합 Storybook으로 확인합니다.
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)](docs/guidelines/external-install-submodule.md)를 따릅니다.
## Navigation 정책
@@ -28,7 +42,7 @@ Storybook은 기존 HM Component·Pattern·Theme·Variant·State·Interaction을
최신 [Generic Status Error](docs/reports/generic-status-error-token-2026-10-11.md)는 `#B3261E` / Provisional이며 기존 Destructive `#D32F2F`를 유지합니다. [Disabled Input Label](docs/reports/disabled-input-label-2026-10-11.md)은 승인된 Input Story 소비 범위 60%, 공통 Label은 50%입니다. [Background Gradient 기록](docs/reports/brown-orange-background-gradients-2026-10-11.md)과 [현재 계약](docs/guidelines/runtime-theme-contract.md)은 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**입니다. Node 설치 시 제공되는 npm과 PATH를 확인하고, 재현 시에는 검증한 버전을 사용합니다. 최초 설치에는 공식 Gitea와 npm 레지스트리 접근이 필요합니다.
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 레지스트리 접근이 필요합니다.
```powershell
git clone https://gitea.hmac.kr/b25027/HMDesign.git
@@ -71,7 +85,7 @@ 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가 컨테이너를 교체하므로 빌드 중에는 현재 서비스를 유지합니다.
`.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로 배포 서버에 접속할 수 있어야 합니다.
@@ -95,6 +109,9 @@ npm run dev:publisher-example
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
```
```css
@@ -107,9 +124,11 @@ import { DataTable, FilterBar, useDataTable } from "@hm-design/ui" // Patterns:
별도 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-경로-실행-환경별-확인)를 따릅니다.
SW는 Tailwind 없이 앱 진입점에서 `import "@hm-design/sw/styles.css"`를 한 번 추가합니다. 한 화면에서는 SW 일반 모드와 뷰어 모드 중 하나를 고르고, 글꼴 등 토큰은 가장 바깥 `<SWTheme style>`에서 바꿉니다([SW 사용 안내](packages/sw/ai/AI_USAGE.md)). SW 기본 글꼴은 Noto Sans KR이며 Figma의 Dotum을 기본값으로 쓸지는 디자인 승인 대기입니다. OrgChart는 Core CSS 두 개(`@hm-design/org-chart/engine.css`, `/style.css`)의 URL을 `stylesheetUrls`로 전달합니다(Shadow DOM, [OrgChart React README](packages/org-chart-react/README.md)).
화면 생성 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 기반 테스트 공유의 검증 범위에 포함하지 않습니다.
루트 `package.json`의 `workspaces`(`packages/*`)로 연결됩니다. 확인: `npm run typecheck`, `npm run build`. 위 [패키지 구성](#패키지-구성)의 5개 패키지는 모두 private이 아니며 ESM JS·타입 선언·CSS를 `dist`에서 export합니다. `npm run build:packages`로 재빌드할 수 있고, Registry publish 이력은 Git 기반 테스트 공유의 검증 범위에 포함하지 않습니다.
## 파일 위치
@@ -120,6 +139,11 @@ import { DataTable, FilterBar, useDataTable } from "@hm-design/ui" // Patterns:
- `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 구현 기준 문서
@@ -134,7 +158,8 @@ import { DataTable, FilterBar, useDataTable } from "@hm-design/ui" // Patterns:
- `docs/components/`: 컴포넌트별 현재 구현 기준 문서
- `public/fonts/`: 기존 자료의 Noto Sans KR 글꼴과 라이선스
- `docs/guidelines/`: 프로젝트 지침·구현 원칙·Theme Token·적용/배포 가이드
- 로컬 검증·감사·진단 자료는 Git에서 제외합니다. 과거 증거 경로는 로컬 보관 기록이며 Clone에서 열 수 있는 링크가 아닙니다.
- 로컬 검증·감사·진단 자료는 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). 두 경우 모두 기록 보존을 위해 삭제·링크 제외 없이 유지하며, 보관 위치는 별도로 결정합니다.
## 참고 범위
@@ -155,6 +180,9 @@ Component Mapping은 Semantic/Theme palette를 참조하며 기본 API로 HM 스
- Navigation: [단일 모드 정책](docs/guidelines/navigation-single-mode.md)
- Dashboard: [Dashboard Pattern](docs/patterns/dashboard-layout.md)
- CENTER: [CENTER 구현·사용 범위](docs/center-graphic/README.md)
- SW: [SW 패키지 README](packages/sw/README.md), [SW AI 사용 안내](packages/sw/ai/AI_USAGE.md)
- OrgChart: [최종 디자인 승인 기록](docs/org-chart/design-approval.md), [AI 조직도 자동 생성 정책](docs/org-chart/ai-page-generation-rules.md)
- 외부 프로젝트 설치: [Git Submodule + npm Workspace](docs/guidelines/external-install-submodule.md)
- 프로젝트·서비스 적용: [프로젝트 지침](docs/guidelines/프로젝트-지침.md), [개발 적용](docs/guidelines/개발-적용-가이드.md)
## Package Registry / Publish (별도 내부 운영 정보)