diff --git a/AGENTS.md b/AGENTS.md index e3929aa..63bf227 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,7 @@ ## 작업 위치와 Git 정책 — 2026-10-20 개정 (2026-10-11 정책 대체) -- 작업 위치는 고정 폴더가 아니라 **사용자가 지정한 브랜치의 작업 트리**다(별도 Clone·worktree 포함). 시작 전 절대경로·현재 브랜치·HEAD·공식 origin `https://gitea.hmac.kr/b25027/HMDesign.git`·최신 원격 HEAD·Working Tree·기존 미커밋 변경을 확인한다. 같은 폴더를 다른 작업자나 AI가 수정 중일 수 있으므로 수정 전 파일을 다시 읽는다. +- 작업 위치는 고정 폴더가 아니라 **사용자가 지정한 브랜치의 작업 트리**다(별도 Clone·worktree 포함). 시작 전 절대경로·현재 브랜치·HEAD·공식 origin `https://gitea.hmac.kr/shkim4/HMDesign.git`·최신 원격 HEAD·Working Tree·기존 미커밋 변경을 확인한다. 같은 폴더를 다른 작업자나 AI가 수정 중일 수 있으므로 수정 전 파일을 다시 읽는다. - 기능 작업은 기능 브랜치(예: `feature/sw-package`, `feature/orgchart-package`)에서 진행하고 `main`에는 사용자가 지시한 병합(PR 등)으로만 반영한다. `main` 직접 Commit/Push와 병합은 사용자의 명시적 지시가 있을 때만 수행한다. - 요청에 필요한 부분만 수정하고 기존 Component·Pattern·Theme·Storybook을 보존한다. 변경 영향과 관련 MD/Storybook 정합성을 검증하고 유효한 기존 정상 검증은 불필요하게 반복하지 않는다. - Commit·Push는 사용자 승인 후 수행한다. 관련 파일만 Stage하고 Staged Diff를 검토한다. 직전에 대상 원격 브랜치를 다시 확인하고, 시작 기준 이후 원격이 변경됐거나 중요한 충돌이 있으면 자동으로 덮어쓰지 않고 중단한다. 완료 후 Local/Remote SHA와 Working Tree를 확인한다. diff --git a/README.md b/README.md index af68d31..58e4ad0 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Storybook은 기존 HM Component·Pattern·Theme·Variant·State·Interaction을 현재 한맥그린·브라운·오렌지는 각 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](docs/guidelines/brand-color-steps.md), [Orange 확정 기록](docs/reports/orange-final-confirmation-2026-10-11.md), [Runtime 계약](docs/guidelines/runtime-theme-contract.md)을 따릅니다. [v2 선택 검증 보고](docs/reports/v2-publisher-review-2026-10-11.md)의 Dark 1/2 보류는 당시 기록입니다. -공식 소스 저장소는 [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 순서로 재사용합니다. +공식 소스 저장소는 [Gitea HMDesign](https://gitea.hmac.kr/shkim4/HMDesign)입니다. 이전 소유자 주소 `https://gitea.hmac.kr/b25027/HMDesign`은 현재 주소로 리다이렉트되지만 새 Clone·Submodule에는 현재 주소를 사용합니다. 이전 원본은 [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)를 확인합니다. @@ -42,10 +42,10 @@ 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**(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 레지스트리 접근이 필요합니다. +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와 외부 dependency용 공개 npm 레지스트리(`registry.npmjs.org`) 접근이 필요합니다. HM 패키지용 Gitea npm Registry나 `.npmrc` 설정은 필요하지 않습니다. ```powershell -git clone https://gitea.hmac.kr/b25027/HMDesign.git +git clone https://gitea.hmac.kr/shkim4/HMDesign.git cd HMDesign node --version npm --version @@ -128,7 +128,7 @@ SW는 Tailwind 없이 앱 진입점에서 `import "@hm-design/sw/styles.css"`를 화면 생성 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`. 위 [패키지 구성](#패키지-구성)의 5개 패키지는 모두 private이 아니며 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`로 재빌드할 수 있습니다. HM 패키지는 npm Registry로 배포하지 않으며, 다른 프로젝트는 [외부 프로젝트 설치](docs/guidelines/external-install-submodule.md)의 Git Submodule + npm Workspace 방식으로 연결합니다. ## 파일 위치 @@ -185,8 +185,12 @@ Component Mapping은 Semantic/Theme palette를 참조하며 기본 API로 HM 스 - 외부 프로젝트 설치: [Git Submodule + npm Workspace](docs/guidelines/external-install-submodule.md) - 프로젝트·서비스 적용: [프로젝트 지침](docs/guidelines/프로젝트-지침.md), [개발 적용](docs/guidelines/개발-적용-가이드.md) -## Package Registry / Publish (별도 내부 운영 정보) +## 패키지 배포 방식 (Git Submodule + npm Workspace) -패키지 build와 Registry publish는 별도 단계입니다. Registry 설치·publish·실제 CDN 운영은 Git 기반 테스트 공유의 실행 조건이나 검증 범위가 아닙니다. 서비스 배포·버전·캐시·롤백 계획은 [운영/배포 가이드](docs/guidelines/운영-배포-가이드.md)를 따릅니다. +HM 패키지는 npm Registry로 배포하지 않습니다. 다른 React 프로젝트는 이 저장소를 Git Submodule로 고정하고, HMDesign 안에서 `npm ci`·`npm run build:packages`를 실행한 뒤 소비 프로젝트의 npm Workspace로 연결합니다. 절차는 [외부 프로젝트 설치](docs/guidelines/external-install-submodule.md)를 따르며 버전 식별은 Submodule Commit SHA입니다. + +- `package.json`의 `version`은 Workspace 연결과 peer 범위에 쓰는 값이며 Registry 배포 버전이 아닙니다. +- 2026-10-07 Gitea npm Registry에 시험 게시한 `@hm-design/ui@0.1.0`·`@hm-design/center-graphic@0.1.0`은 현재 소스와 다른 이전 산출물이므로 설치에 사용하지 않습니다. 소비 프로젝트의 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. +- Theme CDN 등 서비스 배포·버전·캐시·롤백 계획은 [운영/배포 가이드](docs/guidelines/운영-배포-가이드.md)를 따릅니다. CENTER Graphic은 현재 내부 테스트/검토 목적 범위에서 제공합니다. 외부 공개 또는 사외 배포 전 별도 License 확정이 필요합니다. 임의의 오픈소스 License를 부여하지 않습니다. diff --git a/docs/ai/AI_GUIDE.md b/docs/ai/AI_GUIDE.md index 36e9642..428b6a5 100644 --- a/docs/ai/AI_GUIDE.md +++ b/docs/ai/AI_GUIDE.md @@ -268,7 +268,7 @@ AI 코딩 도구는 보통 **프로젝트 루트의** `AGENTS.md`(Codex 등)·`C 자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(`postinstall` 없음), 도구가 `node_modules`를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다. -**Git Submodule + npm Workspace로 연결한 경우**(Registry 없이 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. +**Git Submodule + npm Workspace로 연결한 경우**(현재 공식 연결 방식. HM 패키지는 npm Registry로 배포하지 않으므로 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. `npm install @hm-design/<패키지>@<버전>`처럼 Registry에서 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. ## 10. 문서 갱신 (HMDesign 저장소 유지보수자) diff --git a/docs/guidelines/external-install-submodule.md b/docs/guidelines/external-install-submodule.md index 7b0e248..9e58b0c 100644 --- a/docs/guidelines/external-install-submodule.md +++ b/docs/guidelines/external-install-submodule.md @@ -1,6 +1,6 @@ # 외부 프로젝트 설치 — Git Submodule + npm Workspace -> 2026-10-20 작성. 현재 HMDesign을 다른 React 프로젝트에서 쓰는 공식 방식입니다. npm Registry publish 없이 Git 저장소를 Submodule로 연결하고, HMDesign 안에서 패키지를 빌드한 뒤 소비 프로젝트의 npm Workspace로 연결합니다. +> 2026-10-20 작성, 2026-10-23 갱신(저장소 주소 `shkim4`, HM 패키지 npm Registry 미사용 명시). 현재 HMDesign을 다른 React 프로젝트에서 쓰는 공식 방식입니다. npm Registry publish 없이 Git 저장소를 Submodule로 연결하고, HMDesign 안에서 패키지를 빌드한 뒤 소비 프로젝트의 npm Workspace로 연결합니다. > 실제 적용 근거: 외부 DWG/DXF Viewer(React 19, `@hm-design/ui` + `@hm-design/sw`)가 이 절차로 연결되었습니다. 패키지 tarball 소비 검증은 `packages/sw/tests/integrated-consumer.mjs`가 별도로 수행합니다. ## 1. 전제 @@ -9,7 +9,7 @@ |---|---| | Node.js / npm | `package-lock.json`의 엔진 조건 `^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) | | React | 소비 프로젝트 `react`·`react-dom` `^19.0.0`(모든 패키지의 peer) | -| 네트워크 | 최초 설치에 Gitea(`https://gitea.hmac.kr/b25027/HMDesign.git`)와 npm Registry 접근 필요 | +| 네트워크 | 최초 설치에 Gitea(`https://gitea.hmac.kr/shkim4/HMDesign.git`)와 외부 dependency용 공개 npm Registry(`registry.npmjs.org`) 접근 필요. HM 패키지용 Gitea npm Registry·`.npmrc` 설정은 쓰지 않음 | | Git | 패키지 `dist/`는 Git에 포함되지 않습니다(`.gitignore`). Clone·Commit 변경 후에는 항상 HMDesign 안에서 다시 빌드합니다. | ## 2. Submodule 연결과 검증 Commit 고정 @@ -17,7 +17,7 @@ 소비 프로젝트 루트에서 실행합니다. `<검증 Commit>`은 사용할 HMDesign Commit의 전체 SHA입니다(브랜치 이름을 그대로 쓰지 않습니다). ```bash -git submodule add https://gitea.hmac.kr/b25027/HMDesign.git HMDesign +git submodule add https://gitea.hmac.kr/shkim4/HMDesign.git HMDesign git -C HMDesign fetch origin git -C HMDesign checkout <검증 Commit> git add .gitmodules HMDesign @@ -26,6 +26,7 @@ git commit -m "chore: pin HMDesign <검증 Commit>" - 소비 프로젝트에 기록되는 것은 Submodule Commit 포인터입니다. 다른 사람·CI는 `git submodule update --init --recursive`로 같은 Commit을 받습니다. - Submodule 안에서 HMDesign 파일을 직접 수정하지 않습니다. `git status`에 `HMDesign (modified content)` / `-dirty`가 보이면 고정 Commit과 다른 코드로 빌드된 상태입니다. 그 상태의 검증 결과는 해당 Commit의 결과로 보고하지 않습니다. +- 이전 주소(`https://gitea.hmac.kr/b25027/HMDesign.git`)로 연결한 Submodule은 리다이렉트로 동작하지만 현재 주소로 바꿉니다. `git submodule set-url HMDesign https://gitea.hmac.kr/shkim4/HMDesign.git` → `git submodule sync` → `.gitmodules` Commit. Submodule Commit 포인터와 `npm ci`·빌드 절차는 바뀌지 않습니다. ## 3. HMDesign 안에서 설치·빌드 @@ -98,4 +99,5 @@ git commit -m "chore: update HMDesign to <새 검증 Commit>" - `dist/`가 Git에 없으므로 Clone·Commit 변경·CI마다 HMDesign 빌드(§3)가 필요합니다. CI에서도 Submodule 초기화와 `npm ci && npm run build:packages`를 실행합니다. - HMDesign 빌드 도구와 소비 프로젝트 도구가 따로 설치됩니다(예: 외부 Viewer는 TypeScript 5.9·Vite 5, HMDesign은 TypeScript 7·Vite 8). 패키지는 HMDesign 도구로 빌드되고 소비 프로젝트는 결과물만 사용합니다. - 버전 식별은 Submodule Commit SHA입니다. SW 패키지는 `dist/build-info.json`에 빌드한 Commit과 dirty 여부를 기록합니다. -- npm Registry publish는 현재 필수가 아닙니다. Registry 배포를 도입하면 이 문서와 별도로 [운영/배포 가이드](./운영-배포-가이드.md)에 절차를 둡니다. +- HM 패키지는 npm Registry로 배포하지 않습니다. `npm install @hm-design/<패키지>@<버전>`으로 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. 2026-10-07 Gitea npm Registry에 시험 게시한 `@hm-design/ui@0.1.0`·`@hm-design/center-graphic@0.1.0`은 현재 소스와 다른 이전 산출물입니다. +- `package.json`의 `version`(예: `0.1.0`)은 Workspace 연결과 peer 범위용 값이며 Registry 배포 버전이 아닙니다. Theme CDN 등 운영 배포는 [운영/배포 가이드](./운영-배포-가이드.md)를 따릅니다. diff --git a/docs/guidelines/publisher-distribution-guide.md b/docs/guidelines/publisher-distribution-guide.md index 7a40da4..b517c31 100644 --- a/docs/guidelines/publisher-distribution-guide.md +++ b/docs/guidelines/publisher-distribution-guide.md @@ -1,6 +1,6 @@ # 퍼블리셔 Git 테스트 공유·실행 안내 -현재 공유 기준은 [공식 Gitea HMDesign](https://gitea.hmac.kr/b25027/HMDesign)의 Git Clone입니다. 먼저 [AGENTS.md](../../AGENTS.md)를 확인합니다. 과거 ZIP 제작·압축 해제 검증은 [추가 수정 보고서](publisher-additional-review-2026-10-10.md)의 당시 기록이며 현재 설치 방법을 대체하지 않습니다. 이번 공유에는 신규 ZIP·포터블 패키지를 만들지 않습니다. +현재 공유 기준은 [공식 Gitea HMDesign](https://gitea.hmac.kr/shkim4/HMDesign)의 Git Clone입니다. 먼저 [AGENTS.md](../../AGENTS.md)를 확인합니다. 과거 ZIP 제작·압축 해제 검증은 [추가 수정 보고서](publisher-additional-review-2026-10-10.md)의 당시 기록이며 현재 설치 방법을 대체하지 않습니다. 이번 공유에는 신규 ZIP·포터블 패키지를 만들지 않습니다. ## 설치 조건과 Storybook 열람 @@ -11,7 +11,7 @@ Node.js를 별도로 설치하고 PATH에서 `node`와 `npm`을 사용할 수 로컬 개발 Storybook이 필요하면 Clone 후 루트에서 다음을 실행합니다. ```powershell -git clone https://gitea.hmac.kr/b25027/HMDesign.git +git clone https://gitea.hmac.kr/shkim4/HMDesign.git cd HMDesign node --version npm --version diff --git a/docs/guidelines/theme-delivery.md b/docs/guidelines/theme-delivery.md index 1a7eac2..13e1d0f 100644 --- a/docs/guidelines/theme-delivery.md +++ b/docs/guidelines/theme-delivery.md @@ -2,7 +2,7 @@ ## Repository와 배포 단위 -하나의 Git Repository에서 소스·Theme·Storybook·문서를 관리한다. UI, CENTER Graphic, Theme JSON은 각각 별도 배포 단위다. 현재 두 패키지는 `private: false`이며 compiled dist(JS·타입·CSS)를 export한다. Library build는 `npm run build:packages`로 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 테스트 ZIP 실행에는 Registry 접근·publish가 필요하지 않다. Theme JSON의 독립 산출 경로는 구현했다. 실제 CDN URL·인프라·인증·CI publish는 미정이다. +하나의 Git Repository에서 소스·Theme·Storybook·문서를 관리한다. UI, CENTER Graphic, Theme JSON은 각각 별도 배포 단위다. 현재 두 패키지는 `private: false`이며 compiled dist(JS·타입·CSS)를 export한다. Library build는 `npm run build:packages`로 구현되어 있다. HM 패키지는 npm Registry로 배포하지 않으며 소비 프로젝트는 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결한다. Theme JSON의 독립 산출 경로는 구현했다. 실제 CDN URL·인프라·인증·CI publish는 미정이다. 운영 배포 경계는 `packages/ui` → UI package, `packages/center-graphic` → Graphic package, `themes/*.json` → Theme CDN이다. **Git push ≠ Theme CDN publish**다. 운영 CI/CD는 JSON 검증·독립 artifact 산출 후 CDN에 배포하는 별도 단계로 구성하며, 현재 저장소에는 실제 CDN publish pipeline이 구현되어 있지 않다. diff --git a/docs/guidelines/개발-적용-가이드.md b/docs/guidelines/개발-적용-가이드.md index 65e711c..867c97d 100644 --- a/docs/guidelines/개발-적용-가이드.md +++ b/docs/guidelines/개발-적용-가이드.md @@ -4,7 +4,7 @@ 페이지 구현 전에 [Navigation Single Mode Policy](navigation-single-mode.md)를 적용한다. AI 코드 생성·제안, 신규/기존 화면, 프로토타입, Production 모두 GNB / LNB / DASHBOARD 중 정확히 하나만 선택한다. 모바일도 같은 체계의 Responsive Variant를 사용하며 별도 요청 없이 Navigation 조합을 생성하거나 제안하지 않는다. -> 대상: 디자인팀과 서비스 개발팀. 현재 UI/CENTER compiled dist build/export, JSON Default/서비스 partial, 공개 Runtime 검증·Global/Scoped Apply와 URL Loader, Storybook JSON Preview, Theme-only artifact 산출이 구현되었다. 현재 테스트 공유는 Git Clone → npm ci → npm run build:packages → npm run storybook(6024)이다. [현재 Git 설치·실행 안내](../../README.md#git-clone-설치실행-현재-테스트-공유-기준)를 먼저 따른다. Registry publish 이력은 Git 테스트 공유 검증 범위 밖이며 실제 CDN infrastructure/publish pipeline은 다음 단계다. Git Clone은 로컬 workspace를 빌드하므로 HM Registry 접근·publish가 필요하지 않다. 아래 장기 운영 예시의 `@company/ui`는 목표명이며 현재 import는 `@hm-design/ui`다. 현재 실제 API/독립 배포 절차는 [Theme delivery](theme-delivery.md), 디자인팀 workflow는 [Theme guide](designer-theme-guide.md)를 따른다. +> 대상: 디자인팀과 서비스 개발팀. 현재 UI/CENTER compiled dist build/export, JSON Default/서비스 partial, 공개 Runtime 검증·Global/Scoped Apply와 URL Loader, Storybook JSON Preview, Theme-only artifact 산출이 구현되었다. 현재 테스트 공유는 Git Clone → npm ci → npm run build:packages → npm run storybook(6024)이다. [현재 Git 설치·실행 안내](../../README.md#git-clone-설치실행-현재-테스트-공유-기준)를 먼저 따른다. HM 패키지는 npm Registry로 배포하지 않으며 실제 CDN infrastructure/publish pipeline은 다음 단계다. Git Clone은 로컬 workspace를 빌드하고 다른 프로젝트는 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결하므로 HM Registry 접근·publish가 필요하지 않다. 아래 장기 운영 예시의 `@company/ui`는 목표명이며 현재 import는 `@hm-design/ui`다. 현재 실제 API/독립 배포 절차는 [Theme delivery](theme-delivery.md), 디자인팀 workflow는 [Theme guide](designer-theme-guide.md)를 따른다. ## 1. 착수 순서 diff --git a/docs/guidelines/운영-배포-가이드.md b/docs/guidelines/운영-배포-가이드.md index 1de5e4b..f01e6cd 100644 --- a/docs/guidelines/운영-배포-가이드.md +++ b/docs/guidelines/운영-배포-가이드.md @@ -1,6 +1,6 @@ # 운영·배포 가이드 (검토용 개정안) -> 이 문서는 장기 운영 목표도 포함한다. 현재 UI/CENTER compiled dist build/export, JSON Default/partial과 공개 URL Loader/Apply, Designer JSON Preview, `npm run build:themes` 독립 artifact 산출이 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 Theme Admin, 실제 CDN/pipeline은 미구현이다. 테스트 ZIP은 포함 dist와 로컬 workspace를 사용하며 Registry 접근·publish는 필수가 아니다. 아래 `@company/ui`는 목표명이며 현재 패키지는 `@hm-design/ui`다. 이번 단계의 실제 배포/캐시/롤백은 [Theme delivery](theme-delivery.md)를 따른다. MVP 수동 운영과 향후 자동화를 구분한다. +> 이 문서는 장기 운영 목표도 포함한다. 현재 UI/CENTER compiled dist build/export, JSON Default/partial과 공개 URL Loader/Apply, Designer JSON Preview, `npm run build:themes` 독립 artifact 산출이 구현되어 있다. HM 패키지는 npm Registry로 배포하지 않고 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결한다. Theme Admin, 실제 CDN/pipeline은 미구현이다. 아래 `@company/ui`는 목표명이며 현재 패키지는 `@hm-design/ui`다. 이번 단계의 실제 배포/캐시/롤백은 [Theme delivery](theme-delivery.md)를 따른다. MVP 수동 운영과 향후 자동화를 구분한다. 단일 `HMDesignSystem` Git 저장소에서 컴포넌트 소스·기본 CSS, Storybook, Theme 초안을 함께 관리한다. **Git 커밋, 패키지 릴리스, Theme Publish는 서로 다른 단계**다. 소스에 CSS/JSON을 수정하거나 Storybook을 빌드하는 것만으로 사용 중인 앱에 변경이 전달되지 않는다. @@ -68,7 +68,7 @@ Draft 값 수정 → 실제 @company/ui Storybook Preview → 자동 검증 | 단계 | 운영 방식 | 필수 증거 | |---|---|---| -| 현재 구현 | compiled dist build/export 패키지·JSON Theme/URL Loader/Apply·Designer Preview·Theme-only artifact. Registry publish 이력은 ZIP 검증 범위 밖; 운영 CDN Publish 미구현 | JSON/Runtime/Default parity/레이아웃 및 URL 실패 fallback 검증 | +| 현재 구현 | compiled dist build/export 패키지·JSON Theme/URL Loader/Apply·Designer Preview·Theme-only artifact. HM 패키지는 Git Submodule + npm Workspace 연결(npm Registry 미사용); 운영 CDN Publish 미구현 | JSON/Runtime/Default parity/레이아웃 및 URL 실패 fallback 검증 | | MVP 서비스 도입 | 구현된 패키지 빌드·로컬 Theme JSON·Storybook Preview를 서비스 앱에 연결하고 수동 검증. Production Publish 없음 | 동일 패키지 컴포넌트의 override/fallback, 새로고침 확인 | | 운영 기반 | Registry, 불변 버전, 검증 API, 승인 기록, 환경별 활성 포인터, API/CDN, 롤백 절차 | STG→PROD 발행과 이전 버전 복귀의 실제 앱 검증 | | 운영 확장 | Theme Admin, 역할별 권한, 감사 로그, 자동 시각·접근성 검사, 관측 | 승인·배포·복구 이력과 서비스별 적용 버전 추적 | diff --git a/docs/guidelines/프로젝트-지침.md b/docs/guidelines/프로젝트-지침.md index f909c82..5a04853 100644 --- a/docs/guidelines/프로젝트-지침.md +++ b/docs/guidelines/프로젝트-지침.md @@ -1,6 +1,6 @@ # Runtime Theme 기반 Design System 프로젝트 지침 (개정안) -> 상태: 현재 하나의 Git Repository에서 UI/CENTER npm workspaces의 compiled dist build/export, JSON 컬러 원본, Global/Scoped Runtime Apply·URL Loader, 통합 Storybook/Designer JSON Preview, Theme-only artifact를 관리한다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 실제 CDN/API/Publish pipeline은 미구현이다. 현재 구현의 운영·배포 절차는 [Theme delivery](theme-delivery.md)를 따른다. +> 상태: 현재 하나의 Git Repository에서 UI/CENTER npm workspaces의 compiled dist build/export, JSON 컬러 원본, Global/Scoped Runtime Apply·URL Loader, 통합 Storybook/Designer JSON Preview, Theme-only artifact를 관리한다. HM 패키지는 npm Registry로 배포하지 않고 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결하며 실제 CDN/API/Publish pipeline은 미구현이다. 현재 구현의 운영·배포 절차는 [Theme delivery](theme-delivery.md)를 따른다. > **2026-10-07 사용자 확정 정책은 개정안 상태와 관계없이 필수 적용한다.** AI의 모든 신규·수정 UI는 사용자의 별도 지시 없이 기존 Component / Storybook Reference를 먼저 확인하고 Theme / Semantic Token과 단일 Navigation Mode를 기본 적용하며 Custom은 최소화한다. 필수 요약은 [AGENTS.md](../../AGENTS.md), 상세 구현 정책은 [shadcn 기반 구현 원칙](shadcn-기반-구현-원칙.md), Theme 정책은 [테마 토큰 가이드](테마-토큰-가이드.md), Navigation 정책은 [Navigation Single Mode Policy](navigation-single-mode.md)가 각각 담당한다. @@ -67,7 +67,7 @@ Primitive (설계·빌드 시 관리) → Semantic (컴포넌트 참조) → Com `HMDesignSystem`을 **하나의 Git 저장소**로 관리한다. 저장소 수와 배포물 수는 다르다. 동일 저장소의 변경이라도 컴포넌트·기본 CSS는 패키지 릴리스, 기존 Semantic Token 값은 Theme Publish, Storybook은 내부 검수용 빌드로 각각 처리한다. 개발팀의 서비스 앱은 이 저장소의 소스 파일을 직접 복사하지 않고 배포된 패키지와 Theme API/CDN을 소비한다. -현재 파일 배치는 다음과 같다. Library dist 산출물과 Runtime URL Loader는 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 운영 CDN/API/Publish pipeline은 별도 도입 대상이다. +현재 파일 배치는 다음과 같다. Library dist 산출물과 Runtime URL Loader는 구현되어 있다. HM 패키지는 npm Registry로 배포하지 않으며 운영 CDN/API/Publish pipeline은 별도 도입 대상이다. ```text HMDesignSystem/ @@ -88,7 +88,7 @@ HMDesignSystem/ ### 5.1 패키지 구성과 Storybook 통합 (구현됨 — 2026-10-02 패키지 분리) -**하나의 Git 저장소 + 두 개의 독립 배포 패키지 + 하나의 통합 Storybook**을 기본으로 한다. 2026-10-02에 npm workspaces(`packages/*`)로 분리했다. `packages/ui`(`@hm-design/ui`)에 Button·Input·Select·Card·Dialog와 Theme(`src/theme/*.css`, `theme.css`, `tailwind.css`)이 있고, `packages/center-graphic`(`@hm-design/center-graphic`)은 ui-viz CENTER Web Reference(제목·정보·노선/공간·시설물)를 이식해 구현했다(기준 문서 `docs/center-graphic/README.md`). 둘은 서로 의존하지 않는다. 루트는 Storybook(`.storybook/`, `src/**/*.stories.tsx`; UI는 `Components`, CENTER는 `Center Graphic` 최상위 그룹)과 Demo(`src/App.tsx`, `src/hm-theme.css`), 컴포넌트 문서(`docs/components/`)를 유지하며 Story와 Demo는 `@hm-design/ui`를 workspace 패키지로 import한다. 두 패키지는 `private: false`이며 ESM JS·타입 선언·CSS를 compiled `dist`에서 export한다. `npm run build:packages`가 library 산출물을 생성하며 Registry publish 이력은 테스트 ZIP 검증 범위 밖이다. 소비 앱은 `@import "tailwindcss"; @import "@hm-design/ui/tailwind.css"; @import "@hm-design/ui/theme.css"`를 쓴다. UI dist에는 `fonts/`의 글꼴과 OFL이 포함되며 compiled `theme.css`는 상대 `./fonts/` 경로를 사용한다. Source `packages/ui/src/theme.css`는 `/fonts/NotoSansKR-variable.ttf`를 사용하므로 App/Storybook 개발 서버는 `public/fonts/`를 서빙한다. +**하나의 Git 저장소 + 두 개의 독립 배포 패키지 + 하나의 통합 Storybook**을 기본으로 한다. 2026-10-02에 npm workspaces(`packages/*`)로 분리했다. `packages/ui`(`@hm-design/ui`)에 Button·Input·Select·Card·Dialog와 Theme(`src/theme/*.css`, `theme.css`, `tailwind.css`)이 있고, `packages/center-graphic`(`@hm-design/center-graphic`)은 ui-viz CENTER Web Reference(제목·정보·노선/공간·시설물)를 이식해 구현했다(기준 문서 `docs/center-graphic/README.md`). 둘은 서로 의존하지 않는다. 루트는 Storybook(`.storybook/`, `src/**/*.stories.tsx`; UI는 `Components`, CENTER는 `Center Graphic` 최상위 그룹)과 Demo(`src/App.tsx`, `src/hm-theme.css`), 컴포넌트 문서(`docs/components/`)를 유지하며 Story와 Demo는 `@hm-design/ui`를 workspace 패키지로 import한다. 두 패키지는 `private: false`이며 ESM JS·타입 선언·CSS를 compiled `dist`에서 export한다. `npm run build:packages`가 library 산출물을 생성하며 HM 패키지는 npm Registry로 배포하지 않고 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결한다. 소비 앱은 `@import "tailwindcss"; @import "@hm-design/ui/tailwind.css"; @import "@hm-design/ui/theme.css"`를 쓴다. UI dist에는 `fonts/`의 글꼴과 OFL이 포함되며 compiled `theme.css`는 상대 `./fonts/` 경로를 사용한다. Source `packages/ui/src/theme.css`는 `/fonts/NotoSansKR-variable.ttf`를 사용하므로 App/Storybook 개발 서버는 `public/fonts/`를 서빙한다. 아래는 목표 구조다. @@ -294,7 +294,7 @@ Layout / Pattern → 현재 HM 대표 Story / Pattern 문서와 단일 | 단계 | 구축 범위 | 다음 단계 진입 조건 | |---|---|---| -| 현재 구현 | UI/CENTER compiled dist build/export, Component·Pattern, 공개 Runtime 계약/API·URL Loader, Default/External verification Story, Theme-only artifact. Registry publish 이력은 ZIP 검증 범위 밖; 운영 CDN/Publish pipeline은 미구현 | 코드/문서/실제 Storybook 정합성 검증 | +| 현재 구현 | UI/CENTER compiled dist build/export, Component·Pattern, 공개 Runtime 계약/API·URL Loader, Default/External verification Story, Theme-only artifact. HM 패키지는 Git Submodule + npm Workspace 연결(npm Registry 미사용); 운영 CDN/Publish pipeline은 미구현 | 코드/문서/실제 Storybook 정합성 검증 | | MVP | 단일 저장소에서 `@company/ui` 패키징, 기본 CSS, Semantic 계약, Storybook, 로컬 JSON Preview/Loader | 같은 패키지 컴포넌트에서 값 override와 fallback을 실제로 확인 | | 운영 기반 | 불변 Theme Registry, 스키마 검증, 버전·호환성, 승인 Publish, API/CDN, 롤백·로그 | 앱 재배포 없이 Theme 값 반영, 실패 시 기본값, 이전 버전 복귀를 확인 | | 운영 확장 | 디자인팀 Admin, 권한·감사, 자동 검수·모니터링 | 운영 절차와 담당자가 정해지고 실제 서비스 적용 기록이 남음 | diff --git a/docs/org-chart/org-chart-usage-guide.md b/docs/org-chart/org-chart-usage-guide.md index b8812e2..e5fddca 100644 --- a/docs/org-chart/org-chart-usage-guide.md +++ b/docs/org-chart/org-chart-usage-guide.md @@ -189,7 +189,7 @@ Fixed에서 회사 로고 PNG, `cards/*.svg`의 대표자·6개 부서 직원/ Git, Node.js와 npm, 공식 Gitea 및 npm 레지스트리 접근이 필요하다. Node.js 조건은 `^20.19.0 || >=22.12.0`이며 Node 21은 제외한다. P10.3 실행 환경은 Node 22.23.2 / npm 10.9.8이다. 기존 폴더를 덮어쓰지 않고 새 경로에서 실행한다. ZIP·별도 설치 파일·다른 작업 폴더의 node_modules/dist 복사는 필요하지 않다. ```powershell -git clone --branch feature/orgchart-package --single-branch https://gitea.hmac.kr/b25027/HMDesign.git HMDesign-OrgChart +git clone --branch feature/orgchart-package --single-branch https://gitea.hmac.kr/shkim4/HMDesign.git HMDesign-OrgChart cd HMDesign-OrgChart git branch --show-current git rev-parse HEAD diff --git a/docs/sw/sw-header-usage.md b/docs/sw/sw-header-usage.md index f31aa97..1d6b831 100644 --- a/docs/sw/sw-header-usage.md +++ b/docs/sw/sw-header-usage.md @@ -14,7 +14,7 @@ `@hm-design/sw`의 SW Header를 화면에 연결하는 방법입니다. 디자인 값과 판정은 [디자인 명세](./sw-header-design-spec.md)를 따릅니다. -> 패키지는 아직 npm Registry에 게시하지 않았습니다. 아래 설치 방법은 HMDesign Workspace 또는 로컬 tarball 기준입니다. +> `@hm-design/sw` 패키지는 npm Registry로 배포하지 않습니다. 다른 프로젝트는 [Git Submodule + npm Workspace](../guidelines/external-install-submodule.md)로 연결하며, 로컬 tarball은 검증용 대안입니다. ## 1. 패키지 구조 @@ -51,16 +51,22 @@ npm run build:sw `build:packages`(typecheck·build·Storybook 전처리)도 마지막에 `build:sw`를 실행합니다. -### 다른 React 프로젝트(로컬 tarball) +### 다른 React 프로젝트(Git Submodule + npm Workspace, 기본) + +HMDesign을 Submodule로 고정하고 HMDesign 안에서 `npm ci`·`npm run build:packages`를 실행한 뒤, 소비 프로젝트 `workspaces`에 `HMDesign/packages/sw`를, dependency에 `"@hm-design/sw": "*"`를 추가하고 `npm install`합니다. 상세는 [외부 프로젝트 설치](../guidelines/external-install-submodule.md)를 따릅니다. + +### 다른 React 프로젝트(로컬 tarball, 검증용) ```bash npm pack -w @hm-design/sw --pack-destination ../packs ``` ```bash -npm install ../packs/hm-design-sw-0.1.0.tgz +npm install ../packs/hm-design-sw-0.2.0.tgz ``` +`hm-design-sw-0.2.0.tgz`는 배포 파일이 아니라 위 `npm pack`이 로컬에서 만드는 파일 이름의 예시입니다. 실제 이름은 `packages/sw/package.json`의 `version`을 따르며 `npm pack` 출력에서 확인합니다. + 소비 프로젝트는 `src` 내부 파일을 참조하지 않고 `dist` 공개 API만 사용합니다. ## 3. Import diff --git a/packages/org-chart-react/README.md b/packages/org-chart-react/README.md index d013ee9..139b684 100644 --- a/packages/org-chart-react/README.md +++ b/packages/org-chart-react/README.md @@ -33,13 +33,13 @@ export function OrganizationContent({ data }: { data: OrgChartDataset }) { } ``` -The `?url` imports above are Vite asset imports, not a universal browser feature. Other hosts resolve the two Core public CSS entries to actual deployment URLs. Importing CSS only into the document does not style the Core's Shadow DOM. Engine CSS is linked first, then standalone Core CSS. P1 owns its colors, typography and geometry without depending on HM Theme. Set public `--hm-orgchart-*` properties on the wrapper container to override only this instance. No HM common variables are redefined. The default entry has no runtime or declaration dependency on HM UI. For independent Tree/Summary integration, use the [Core factories](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/standalone-components-p1.md) in a ref/effect without copying their UI. +The `?url` imports above are Vite asset imports, not a universal browser feature. Other hosts resolve the two Core public CSS entries to actual deployment URLs. Importing CSS only into the document does not style the Core's Shadow DOM. Engine CSS is linked first, then standalone Core CSS. P1 owns its colors, typography and geometry without depending on HM Theme. Set public `--hm-orgchart-*` properties on the wrapper container to override only this instance. No HM common variables are redefined. The default entry has no runtime or declaration dependency on HM UI. For independent Tree/Summary integration, use the [Core factories](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/standalone-components-p1.md) in a ref/effect without copying their UI. ## Explicit popup adapters Minimum React installation: `@hm-design/org-chart`, `@hm-design/org-chart-react`, React 19 and the host renderer (usually `react-dom`). HM UI, HM Theme and Tailwind are unnecessary for the default entry and Core popup. Core + Vanilla requires only `@hm-design/org-chart` and its public CSS URLs. -For the existing HM Dialog, install the optional `@hm-design/ui@0.1.0` peer and its required peers, provide the host's real HM Theme/Tailwind CSS, and explicitly select both the entry and popup mode: +For the existing HM Dialog, add the optional `@hm-design/ui` peer (0.1.0, linked from the same HMDesign Git Submodule + npm Workspace; it is not installed from an npm registry) and its required peers, provide the host's real HM Theme/Tailwind CSS, and explicitly select both the entry and popup mode: ```tsx import { OrgChart } from '@hm-design/org-chart-react/hm-dialog'; @@ -74,11 +74,11 @@ Default named runtime export: `OrgChart`. `/hm-dialog` exports the same `OrgChar - Optional `displayMode`: `'interactive'` (default) or `'readOnly'`, passed to the Core composition. Changing it recreates the Core handle. - Optional `layoutMode`: `'fixed'` (default) or `'auto'`, independent of `displayMode`. Auto renders company forests, collapse and Zoom/Pan/Fit. P5-4 retains the current Expanded card presentation by user decision; external SVG matching is no longer required. Changing mode recreates the Core handle. -See [Expanded usage and styling](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/expanded-usage.md) for company +See [Expanded usage and styling](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/expanded-usage.md) for company selection, top nodes, JSON sources, popup ownership and Auto-only CSS examples. Keyboard focus reveals offscreen controls at the current Zoom; group-title Hover feedback and drag/keyboard activation are implemented in the shared Core. -- Optional `companyId`: legacy Auto fallback company preset (default `hanmac`). Explicit/inherited organization company identity takes priority; Fixed ignores company colors. Changing it recreates the handle. See [Core README](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/packages/org-chart/README.md). +- Optional `companyId`: legacy Auto fallback company preset (default `hanmac`). Explicit/inherited organization company identity takes priority; Fixed ignores company colors. Changing it recreates the handle. See [Core README](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/packages/org-chart/README.md). - Optional `selectedCompanyIds`: undefined selects all, [] selects none. Changes call Core selection on the existing instance, preserving per-company collapse state and source counts. - Optional `autoLayout`: `{ type: 'tb' | 'lr' | 'hybrid', hybridStartDepth: 2 | 3 | 4, initialVisibleDepth: 1 | 2 | 3 | 'all', hybridOrganizationIds?: readonly string[] }` (each field optional). Changes use Core `setAutoLayout` on the existing instance; TB/LR/Hybrid changes retain valid collapse state. Per-group hybrid IDs apply only to TB; clear them when selecting LR/global Hybrid. Omission follows Core defaults (TB, Hybrid depth 3, all visible). - Optional `interactions`: `{ collapse?: boolean, zoom?: boolean, pan?: boolean }`, all enabled by default. Auto independently enables/disables group toggles, Zoom controls/wheel Zoom and drag Pan via Core `setInteractions` on the same instance. Omitted fields are enabled, and removing the prop restores all three defaults. Existing collapse and viewport state remain; TB/LR/Hybrid has no interaction prerequisite. Fixed ignores this option and keeps its existing behavior. diff --git a/packages/org-chart-react/ai/AI_GUIDE.md b/packages/org-chart-react/ai/AI_GUIDE.md index 36e9642..428b6a5 100644 --- a/packages/org-chart-react/ai/AI_GUIDE.md +++ b/packages/org-chart-react/ai/AI_GUIDE.md @@ -268,7 +268,7 @@ AI 코딩 도구는 보통 **프로젝트 루트의** `AGENTS.md`(Codex 등)·`C 자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(`postinstall` 없음), 도구가 `node_modules`를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다. -**Git Submodule + npm Workspace로 연결한 경우**(Registry 없이 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. +**Git Submodule + npm Workspace로 연결한 경우**(현재 공식 연결 방식. HM 패키지는 npm Registry로 배포하지 않으므로 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. `npm install @hm-design/<패키지>@<버전>`처럼 Registry에서 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. ## 10. 문서 갱신 (HMDesign 저장소 유지보수자) diff --git a/packages/org-chart/README.md b/packages/org-chart/README.md index 43c40a8..bf35ce4 100644 --- a/packages/org-chart/README.md +++ b/packages/org-chart/README.md @@ -59,7 +59,7 @@ The existing employee popup still uses its displayMode policy and receives raw d P5-4 adds group-title Hover feedback and reveals offscreen keyboard-focused cards without changing Zoom. Drag click suppression does not block Enter/Space activation. -See [Expanded usage and styling](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/expanded-usage.md) for complete +See [Expanded usage and styling](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/expanded-usage.md) for complete Vanilla/React examples, Shadow DOM CSS ownership and verification boundaries. `selectedCompanyIds` / `setSelectedCompanies(ids?)` filter the view: undefined @@ -181,13 +181,13 @@ Representative cards never render job-title, role or status badges, empty attrib Large department cards use 24px names / 18px positions; compact cards use 18px names / 15px positions. Representative typography and the existing weights, line heights and colors are retained. Read-only dispatched/onLeave cards share the compact content layout (108×52 card, 24×44 photo slot), with their original gray surface and text colors. Status headers share the standard 2Depth 20px/700/19.7px typography; existing department-specific exceptions remain. Position and badge whitespace is removed only for display. -Employee-card logo contain boxes scale exactly 1.5×: small 12→18px; representative/large/status 14→21px. Original assets and footer logos stay unchanged. See [P3.2 report](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/implementation-report-p3.2.md) for before/after browser measurements and preservation evidence. Historical P3.1 geometry below describes that earlier stage. +Employee-card logo contain boxes scale exactly 1.5×: small 12→18px; representative/large/status 14→21px. Original assets and footer logos stay unchanged. See [P3.2 report](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/implementation-report-p3.2.md) for before/after browser measurements and preservation evidence. Historical P3.1 geometry below describes that earlier stage. ### P3.1 display policy and local font loading The OrgChart-scoped default family is **Noto Sans KR**; existing `--hm-orgchart-font-family` overrides remain available. The host must register its font-face once: HM Storybook already loads the existing HM Theme face. The HTML P1 host loads the unchanged `public/fonts/NotoSansKR-variable.ttf` copied to `assets/fonts/`; the React P1 host references that same source through its bundler. Global HM Theme files are unchanged. The Korean Core shell declares `lang="ko"` for consistent glyph shaping across host languages. -Read-only Full Composition suppresses only the `경영진` **job-title badge**. Positions (including a literal `경영진` position), other raw badges, employee records, popup fields and statistics are retained. Position whitespace is removed only in the card display. Other renderer modes keep their badge policy. All card types share one rectangular neutral SVG for a missing or failed profile image; an available profile image takes precedence. Approved cards, photo-slot dimensions and P3 status-card geometry are unchanged. See [P3.1 report](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/implementation-report-p3.1.md) for focused browser evidence and limits. +Read-only Full Composition suppresses only the `경영진` **job-title badge**. Positions (including a literal `경영진` position), other raw badges, employee records, popup fields and statistics are retained. Position whitespace is removed only in the card display. Other renderer modes keep their badge policy. All card types share one rectangular neutral SVG for a missing or failed profile image; an available profile image takes precedence. Approved cards, photo-slot dimensions and P3 status-card geometry are unchanged. See [P3.1 report](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/implementation-report-p3.1.md) for focused browser evidence and limits. Optional `organizationLinks: Readonly>` maps existing organization IDs to host-configured URLs. Only original hierarchy depth 1 titles become native links. Missing, undefined or blank URLs keep ordinary titles; no destination is generated. HTTP(S) and relative URLs are accepted; invalid URLs, other schemes and credentials reject construction with `TypeError`. Group links retain native keyboard navigation and a visible focus outline, separately from employee activation. @@ -225,7 +225,7 @@ Organization and employee IDs have independent namespaces. All references are ch P1 **ships an independent OrgChart design**. It requires no HM Theme, React/UI peer or font download. Resolve the two exported CSS assets to URLs; the Core loads them only into its dedicated open Shadow DOM. `style.css` includes its own scoped defaults and contains no private CSS imports. Summary-only components require only this CSS. `/browser` is a classic IIFE exposing `window.HMOrgChart`; `dist/index.js` is bundled ESM with no bare package imports. -All colors, typography, spacing, borders, radius and gradients belong to `src/styles/design-tokens.css` and `src/core/style-presets.ts`. Public `--hm-orgchart-*` inputs inherit from the caller's container; internal `--hm-orgchart-resolved-*` aliases resolve defaults without overriding inherited inputs. HM Theme variables do not affect this design. Workdesk organization header gradients and white heading text are measured; neutral/card styling is a documented design adaptation, not an official Workdesk value. Existing v0.1 demos and historical validation records are preserved. P1 theme-free examples are `dist/p1.html` (HTTP/ESM) and `dist/p1-classic.html` (direct file/inline JSON). See [standalone component integration](https://gitea.hmac.kr/b25027/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/standalone-components-p1.md). +All colors, typography, spacing, borders, radius and gradients belong to `src/styles/design-tokens.css` and `src/core/style-presets.ts`. Public `--hm-orgchart-*` inputs inherit from the caller's container; internal `--hm-orgchart-resolved-*` aliases resolve defaults without overriding inherited inputs. HM Theme variables do not affect this design. Workdesk organization header gradients and white heading text are measured; neutral/card styling is a documented design adaptation, not an official Workdesk value. Existing v0.1 demos and historical validation records are preserved. P1 theme-free examples are `dist/p1.html` (HTTP/ESM) and `dist/p1-classic.html` (direct file/inline JSON). See [standalone component integration](https://gitea.hmac.kr/shkim4/HMDesign/src/commit/d2b76e766466e1f156f6a0f8f63710e023af900e/docs/org-chart/standalone-components-p1.md). ## Engine disposal boundary diff --git a/packages/org-chart/ai/AI_GUIDE.md b/packages/org-chart/ai/AI_GUIDE.md index 36e9642..428b6a5 100644 --- a/packages/org-chart/ai/AI_GUIDE.md +++ b/packages/org-chart/ai/AI_GUIDE.md @@ -268,7 +268,7 @@ AI 코딩 도구는 보통 **프로젝트 루트의** `AGENTS.md`(Codex 등)·`C 자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(`postinstall` 없음), 도구가 `node_modules`를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다. -**Git Submodule + npm Workspace로 연결한 경우**(Registry 없이 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. +**Git Submodule + npm Workspace로 연결한 경우**(현재 공식 연결 방식. HM 패키지는 npm Registry로 배포하지 않으므로 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. `npm install @hm-design/<패키지>@<버전>`처럼 Registry에서 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. ## 10. 문서 갱신 (HMDesign 저장소 유지보수자) diff --git a/packages/sw/README.md b/packages/sw/README.md index 0f784cc..50d8588 100644 --- a/packages/sw/README.md +++ b/packages/sw/README.md @@ -13,7 +13,7 @@ import "@hm-design/sw/styles.css" // 앱 진입점에서 한 번 - 진입점은 `@hm-design/sw`(JS·타입)와 `@hm-design/sw/styles.css` 두 개뿐입니다. `dist/components/...` 같은 내부 경로는 공개 API가 아닙니다. - Peer: `react`, `react-dom` `^19.0.0`. 런타임 dependency는 없고, SVG·PNG 자산은 JS에 data URI로 포함됩니다. CSS는 자동 import되지 않으며 전역 선택자(`html`, `body`, `*`)를 쓰지 않습니다. -- Registry에는 아직 게시하지 않았습니다. 소비 프로젝트는 HMDesign 저장소를 Git Submodule + npm Workspace로 연결하거나 `npm pack`으로 만든 tarball을 설치합니다. +- `@hm-design/sw`는 npm Registry로 배포하지 않습니다. 소비 프로젝트는 HMDesign 저장소(`https://gitea.hmac.kr/shkim4/HMDesign.git`)를 Git Submodule + npm Workspace로 연결합니다. `npm pack`으로 만든 tarball 설치는 검증용 대안입니다. - 패키지 내용: `dist/`(`index.js`·`index.d.ts`·`styles.css`·`build-info.json` — 출처 Commit·도구 버전), `ai/`(AI 코딩 도구용 안내·예제), `README.md`, `package.json`. ## 글꼴·테마 diff --git a/packages/sw/ai/AI_GUIDE.md b/packages/sw/ai/AI_GUIDE.md index 36e9642..428b6a5 100644 --- a/packages/sw/ai/AI_GUIDE.md +++ b/packages/sw/ai/AI_GUIDE.md @@ -268,7 +268,7 @@ AI 코딩 도구는 보통 **프로젝트 루트의** `AGENTS.md`(Codex 등)·`C 자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(`postinstall` 없음), 도구가 `node_modules`를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다. -**Git Submodule + npm Workspace로 연결한 경우**(Registry 없이 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. +**Git Submodule + npm Workspace로 연결한 경우**(현재 공식 연결 방식. HM 패키지는 npm Registry로 배포하지 않으므로 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. `npm install @hm-design/<패키지>@<버전>`처럼 Registry에서 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. ## 10. 문서 갱신 (HMDesign 저장소 유지보수자) diff --git a/packages/ui/ai/AI_GUIDE.md b/packages/ui/ai/AI_GUIDE.md index 36e9642..428b6a5 100644 --- a/packages/ui/ai/AI_GUIDE.md +++ b/packages/ui/ai/AI_GUIDE.md @@ -268,7 +268,7 @@ AI 코딩 도구는 보통 **프로젝트 루트의** `AGENTS.md`(Codex 등)·`C 자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(`postinstall` 없음), 도구가 `node_modules`를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다. -**Git Submodule + npm Workspace로 연결한 경우**(Registry 없이 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. +**Git Submodule + npm Workspace로 연결한 경우**(현재 공식 연결 방식. HM 패키지는 npm Registry로 배포하지 않으므로 HMDesign 저장소를 예: `HMDesign/` 폴더에 Submodule로 고정하고 `workspaces`에 `HMDesign/packages/<패키지>`를 등록한 구성): `node_modules/@hm-design/<패키지>`는 `HMDesign/packages/<패키지>`로 연결되므로 지침 위치는 위 표와 같습니다(`HMDesign/packages/<패키지>/ai/`와 같은 파일). 공개 진입점은 `dist/`를 가리키므로 HMDesign 폴더 안에서 `npm ci`와 `npm run build:packages`를 먼저 실행해야 하며, `dist/`가 없으면 Import 오류를 컴포넌트 결함으로 보고하지 말고 빌드 필요로 보고합니다. HMDesign 저장소 루트의 `AGENTS.md`·`CLAUDE.md`는 HMDesign 개발용이므로 소비 프로젝트 지침으로 쓰지 않습니다. `npm install @hm-design/<패키지>@<버전>`처럼 Registry에서 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. ## 10. 문서 갱신 (HMDesign 저장소 유지보수자)