HMDesign/docs/guidelines/publisher-distribution-guide.md

퍼블리셔 Git 테스트 공유·실행 안내

현재 공유 기준은 공식 Gitea HMDesign의 Git Clone입니다. 먼저 AGENTS.md를 확인합니다. 과거 ZIP 제작·압축 해제 검증은 추가 수정 보고서의 당시 기록이며 현재 설치 방법을 대체하지 않습니다. 이번 공유에는 신규 ZIP·포터블 패키지를 만들지 않습니다.

설치 조건과 Storybook 열람

Node.js를 별도로 설치하고 PATH에서 node와 npm을 사용할 수 있어야 합니다. 루트 package.json에는 engines/packageManager 버전 고정이 없으며, 현재 lockfile의 Vite Node 조건은 ^20.19.0 || >=22.12.0입니다(Node 21 제외). BAT의 Node 검사도 이 조건에 맞습니다. 검증 환경은 Windows, Node 20.20.1 / npm 10.8.2이며 npm 10.8.2는 검증한 버전입니다. Git, Node/npm의 PATH와 버전을 확인합니다. 최초 Clone에는 의존성과 workspace 빌드 산출물이 없으므로 설치·빌드가 필요합니다. 설치에는 공식 Gitea·npm 레지스트리 접속이 필요합니다. HM Registry 설치·publish는 필요하지 않습니다.

일반 사용자는 아래처럼 Clone 후 Windows BAT를 실행하거나 start-storybook.bat를 더블 클릭합니다. 기존 서버 재사용 시에는 아래 실행 분기가 적용됩니다.

git clone https://gitea.hmac.kr/b25027/HMDesign.git
cd HMDesign
node --version
npm --version
.\start-storybook.bat

수동 설치·실행이 필요하면 Clone한 루트에서 다음을 실행합니다. npm ci는 lockfile 기준으로 의존성과 로컬 workspace 연결을 준비하고, build:packages는 UI/CENTER package 산출물을 만듭니다. 기존 서버가 있는 환경의 독립 재현성 검사는 별도 QA 절차를 따릅니다.

npm ci
npm run build:packages
npm run storybook

브라우저에서 http://localhost:6024/ 를 엽니다. Components에서 기존 UI, Patterns에서 업무/Layout 조합, Foundation에서 Color/Typography를 확인합니다. 내부 Theme 비교는 ?path=/story/theme-runtime-contract--comparison, JSON Loader 검증은 ?path=/story/theme-runtime-contract-loader--cdn-verification입니다. Runtime Focus는 ?path=/story/theme-runtime-contract--verification의 Run verification 버튼에 Tab으로 이동한 뒤 Enter/Space로 검사합니다. 자동·포인터 실행의 Focus는 NOT VERIFIED입니다.

Git Clone에는 node_modules, 사전 빌드 Storybook, 포터블 Node, 로컬 증거가 포함되지 않습니다.

과거 포터블 ZIP은 당시 포함된 Node·정적 Storybook·ZIP 전용 실행기를 사용한 별도 배포물입니다. 일반 Git Clone이나 소스 ZIP에는 그 런타임이 포함되지 않으므로 Node.js/npm 설치 조건을 생략할 수 없습니다. 과거 ZIP의 6007은 현재 개발 Storybook 기본 포트 6024와 다릅니다.

Storybook BAT 실행 분기

start-storybook.bat는 BAT가 있는 폴더를 작업 경로로 설정하고 Node 실행기를 호출합니다. 실행기는 루트 package.json의 scripts.storybook에서 포트를 읽습니다. 현재 기본 포트는 6024이며 BAT 인수나 환경변수로 포트를 변경하는 기능은 없습니다.

1. 기존 서버가 준비됨: http://localhost:6024/index.json의 HTTP 성공 응답과 entries 안의 components-form-button--all, theme-designer-playground--editor 두 ID 존재, iframe.html의 HTTP 성공 응답을 모두 확인하면 기존 서버를 재사용합니다. 각 요청 제한은 1.5초입니다. PowerShell Start-Process로 기본 브라우저에 http://localhost:6024/를 열고 BAT는 종료합니다. npm 실행 가능 여부, 의존성 설치와 package 산출물 검사를 모두 건너뛰므로 npm ci, build:packages, 새 서버 시작이 생략됩니다. Node 버전 검사는 재사용 전에도 수행합니다.
2. 준비 조건 불충족 + 포트 점유: 127.0.0.1:6024 TCP 연결에 성공하거나 연결 확인이 시간 초과되면 점유로 판단하고 오류로 종료합니다. 다른 서버뿐 아니라 아직 준비되지 않은 HM Storybook도 이 분기에 해당할 수 있습니다. 기존 프로세스를 자동 종료하거나 다른 포트로 이동하지 않습니다.
3. 준비 조건 불충족 + 빈 포트: npm.cmd --version 성공을 확인합니다. node_modules/.bin/storybook.cmd가 없을 때만 npm.cmd ci를 실행합니다. UI/CENTER package의 exports에서 문자열 경로 또는 import 경로 중 하나라도 없을 때만 npm.cmd run build:packages를 실행합니다. 모든 의존성의 정상 상태, 타입 산출물이나 기존 산출물의 최신 여부까지 검사하는 것은 아닙니다. 이어서 npm.cmd run storybook -- --exact-port --ci로 현재 Clone의 새 서버를 시작합니다. Story index/preview 준비를 최대 3분 기다리고 기본 브라우저를 연 뒤 서버 종료까지 터미널을 유지합니다. 종료는 이 터미널의 Ctrl+C입니다.

기존 서버 재사용은 신규 Clone의 독립 실행 성공 증거가 아닙니다. 준비 확인은 Story ID와 HTTP 응답만 검사하며 서버의 실행 프로젝트 경로·Git SHA를 확인하지 않습니다. 브라우저에 표시된 화면이 기존 개발 폴더의 Storybook일 수 있습니다. 새 Clone의 Node/npm 설치 조건과 새 소스의 실행 여부를 확인하려면 아래 QA를 사용합니다.

실행 폴더 접근 실패는 BAT의 폴더 오류 안내, Node/npm·설치·빌드·서버·브라우저 열기 실패는 상세 오류와 BAT의 실행 실패 안내로 표시됩니다. 포트 점유, 서버의 비정상 종료(종료 코드가 0이 아닌 경우)와 준비 시간 초과도 오류입니다. BAT는 오류 시 창을 유지하기 위해 pause하고 종료 코드 1을 반환합니다. 포트 점유 오류가 나면 기존 서버의 담당자·실행 위치를 확인하거나 아래 격리 실행을 사용합니다.

신규 Clone 독립 실행 QA

이 절차는 일반 Storybook 열람과 별개입니다. 실행 터미널에서 새 Clone 루트의 Get-Location, git remote get-url origin, git rev-parse HEAD를 기록하고, 최초 설치 전 Test-Path node_modules로 기존 의존성 유무도 구분합니다. 새 Clone에서 npm ci와 npm run build:packages의 성공 로그를 확인하고 다음 workspace 연결을 확인합니다.

Get-Location
git remote get-url origin
git rev-parse HEAD
Test-Path node_modules
npm ci
npm run build:packages
npm ls @hm-design/ui @hm-design/center-graphic --depth=0

@hm-design/ui -> packages/ui, @hm-design/center-graphic -> packages/center-graphic처럼 해당 Clone의 workspace를 가리키는지 확인합니다. 실행 방법은 환경에 따라 다음 중 하나를 선택합니다.

• 기존 6024 서버가 없는 환경: 위 준비 후 .\start-storybook.bat를 실행합니다. 새 서버 시작 로그와 6024의 대표 Story 렌더를 확인합니다. 기존 서버를 열고 BAT가 즉시 종료한 경우는 독립 실행으로 판정하지 않습니다.
• 기존 서버를 유지하는 환경: 사용하지 않는 별도 포트에서 설치된 Storybook CLI를 직접 실행합니다. 아래 6124는 이전 Acceptance Test의 격리 포트 예시이며 현재 공식 기본 포트 6024를 바꾸지 않습니다. 6124가 점유됐으면 명령과 열람 URL의 숫자를 사용 가능한 포트로 함께 바꿉니다.

.\node_modules\.bin\storybook.cmd dev -p 6124 --host 127.0.0.1 --no-open --disable-telemetry --exact-port --ci

이 명령은 BAT를 거치지 않으며 package.json이나 Storybook 설정을 수정하지 않습니다. 현재 설치된 Storybook CLI가 지원하는 -p, --host, --exact-port, --ci를 사용합니다. 포트 점유 시 다른 서버를 재사용하지 않고 실패합니다. 브라우저 자동 열기는 꺼져 있으므로 실행 성공 로그의 포트를 확인한 뒤 http://127.0.0.1:6124/를 직접 엽니다. index/iframe 응답뿐 아니라 Button·Input·DataTable·Dashboard·Theme Comparison 등 대표 Story를 렌더링하고, 실행 터미널의 프로젝트 경로·HEAD·포트와 연결해 기록합니다. 응답이나 화면만으로 Clone의 정체를 판정하지 않습니다. 종료할 때는 이 QA 서버의 터미널에서만 Ctrl+C를 사용합니다.

기존 Acceptance Test 근거와 판정 범위

2026-10-11 공식 소스 e9144348e5f2f9be12130b707b1e2b389476880e를 새 Clone하여 작성한 acceptance-report.txt, guard.json, runtime.json, combined.json, browser-evidence.json을 보존합니다. 증거는 테스트 Clone의 _local/acceptance/에 있으며 Git 배포에는 포함되지 않습니다. 이번 보완은 문서만 수정하므로 같은 소스·화면에 연결된 기존 PASS를 REUSED PASS로 재사용하며 Dashboard 테스트를 반복하지 않습니다.

기존 확인 항목	보존 결과
업무관리 Dashboard 생성·독립 React 렌더	REUSED PASS
390·768·1280·1440px 반응형	REUSED PASS
핵심 상호작용 12건·상태 컬러 측정 48건	REUSED PASS
AI Guard FAIL 0·해시 연결 Runtime	FAIL 0 유지 / 연결 Runtime REUSED PASS
새 Clone npm ci·workspace 연결·6124 Storybook 독립 실행	REUSED PASS
기본 BAT의 준비된 6024 서버 재사용	확인됨 / 신규 Clone 독립 실행과 구분

6124 BAT 검증 당시에는 테스트 Clone의 포트를 일시 변경했고 package.json 원문을 복원했습니다. 이는 과거 검증 방법이며 BAT의 포트 옵션 지원을 뜻하지 않습니다. 위 QA는 설정 변경 없이 CLI로 격리 실행하는 방법입니다. 기존 보고서의 DISTRIBUTION_READY·FINAL_ACCEPTANCE: PARTIAL은 당시 BAT 설명 누락에 대한 기록으로 보존합니다. 이번 문서 정합성·링크·개인정보 검사와 공식 Gitea 반영이 통과하면 정의된 AI 화면 제작·Git Clone 내부 공유 Acceptance 범위의 AI_SCREEN_READY, DISTRIBUTION_READY, FINAL_ACCEPTANCE를 PASS로 판정합니다.

Guard 원본 status/staticStatus/runtimeStatus와 결합 status는 NOT VERIFIED로 보존합니다. STYLE의 STATIC은 PASS, RUNTIME·DESIGN_INTENT·FINAL은 NOT VERIFIED입니다. 48건의 computed 컬러 PASS를 CSS site 전수나 디자인 의도 승인으로 확대하지 않습니다. 실제 스크린리더·실기기 touch/drag·별도 대비 인증·신규 화면의 다른 외부 Theme·Node 미설치 PC·빈 6024 신규 서버 분기·BAT 자동 npm ci 분기는 NOT VERIFIED입니다. 문서 보완은 이 실행 분기들을 새로 검증한 결과가 아니며, 새 차단 오류가 없다면 이 제한을 유지한 채 내부 공유용 완료본으로 판정합니다.

새 React 화면 제작과 실행

위 수동 설치·package build 절차를 완료한 뒤 별도 터미널에서 실행합니다.

npm run dev:publisher-example

출력된 Vite 주소(기본 5173)를 엽니다. 실제 예제는 공개 @hm-design/ui의 GNB/GNBMobileMenu, PageHeader, Card, FilterBar, Select, Button, DataTable을 렌더링합니다. GNB_ONLY이며 Sidebar를 추가하지 않습니다. 예제 폴더를 새 경로에 복사한 뒤 제목·data·columns와 필요한 조합을 수정합니다. 기존 Pattern을 먼저 검토한 뒤 Component → Variant/Prop → Composition 순으로 재사용하고 현재 Theme/Semantic Token과 공개 CSS 연결을 유지합니다. 임시 검증 화면은 공식 Story로 등록하지 않습니다.

검색 조건 → 검색어 → 조회 → 초기화 순서, 8px 간격, 기본 구성 중앙 정렬을 사용합니다. 기간·담당자 등 추가 조건을 제공하는 구성은 hm-list-search-extended를 사용합니다. 입력값으로 정렬을 바꾸지 않습니다. 모바일은 줄바꿈·버튼 우측 정렬·표 내부 가로 스크롤을 유지합니다.

예제 CSS는 index.css → hm-theme.css를 연결하며 source("./")로 실제 예제 폴더를 검색합니다. 공개 @hm-design/ui/tailwind.css는 자체 compiled 폴더를 검색합니다. 폴더·bootstrap을 옮기면 CSS 상대 경로와 Vite/tsconfig 경로도 함께 확인합니다. 공통 Component 스타일을 변경해 가로 넘침을 감추지 않습니다. 루트에서 예제 검증 명령은 다음과 같습니다.

npm run build:publisher-example
node node_modules/typescript/bin/tsc -p examples/publisher-list/tsconfig.json
node scripts/ai-generation-guard.mjs --target examples/publisher-list --scope FULL_SCREEN --mode GNB_ONLY --result index.html

복사한 화면은 해당 Vite config로 build/dev를 실행하고 Guard의 --target을 새 경로로 지정합니다. Guard는 정적 계약만 확인합니다. NOT VERIFIED는 소스 검토와 실제 React 브라우저의 utility·레이아웃·조회/초기화·모바일 메뉴 동작으로 별도 확인합니다. Guard 정책, Component 인덱스, 예제 사용법을 따릅니다.

전체 소스 타입은 npm run typecheck, UI package는 npm run build:ui, 앱은 npm run build, 정적 Storybook은 npm run build-storybook으로 확인합니다. MD 내부 링크는 node scripts/check-doc-links.mjs로 검사합니다.

Designer와 확정 Theme

Designer는 일반 검수 메뉴에서 제외된 내부 환경입니다. http://localhost:6024/?path=/story/theme-designer-playground--editor로 엽니다. 확정 컬러의 원본은 themes/default.json이며 임시 편집은 Designer와 같은 document의 Live Preview/Portal에만 적용됩니다. 다른 Story로 이동하면 override가 해제되어 HM Default로 검수합니다.

편집 데이터는 같은 탭의 sessionStorage에 보관됩니다. 편집기로 돌아오거나 새로고침하면 보관값을 다시 적용합니다. 일반 새 탭은 독립 세션이고 탭 복제/opener는 브라우저가 초기 세션을 복사할 수 있습니다. 이후 각 탭의 편집은 독립적입니다. 유효한 6자리 HEX는 즉시 적용되며 Apply 버튼은 없습니다. Reset to HM Default는 override와 저장 편집값을 비웁니다. JSON Import는 이전 값을 병합하지 않고 교체하며 잘못된 입력은 마지막 유효값을 유지합니다. 서버 저장·공식 Token 변경·CDN publish는 수행하지 않습니다. 상세 사용법.

알려진 제한과 과거 기록

• 실제 데이터 연동·서버 저장은 예제 범위 밖입니다. 업무 화면은 예시 데이터와 브라우저 저장소를 사용합니다.
• Dashboard는 최소 폭 960px과 내부 스크롤 계약을 유지합니다.
• Sheet의 최종 radius 수치, 컬러 상세 의미, 설정·도움말 숨김 범위는 미확정입니다.
• 스크린리더 발화·실기기 touch/drag·Node 미설치 PC 설치는 별도 검증 대상입니다.
• 2026-10-10 npm 감사에서 개발 의존성 High 7건, 운영 의존성 0건을 확인했습니다. 직접 개발 의존성 shadcn의 간접 braces 경로이며 공식 보안 권고는 패치 버전이 없다고 명시합니다. 안전한 패치로 해결할 수 없어 package/lockfile을 유지했습니다. 강제 major 변경은 보류합니다.
• 과거 로컬 증거는 _local/에 보관되고 Git Clone에 포함되지 않습니다. 과거 ZIP·다른 소스의 기록을 현재 실행의 새 PASS로 간주하지 않습니다. 위 Acceptance Test의 동일 소스·화면 근거는 REUSED PASS로 구분합니다. 과거 포터블 안내는 역사적 자료입니다.