13 KiB
HMDesign 공식 Gitea 소스 이전 준비
2026-10-12 월요일에는 검증된 GitHub 최신 추적 소스 전체를 공식 Gitea의 기존 이력 위에 반영한다. 이번 작업은 소스 정합성과 준비 자료만 정리했으며 공식 Gitea 접근·Clone·Commit·Push·연결 전환은 실행하지 않았다. 최종 정합성 보고와 전체 소스 목록을 함께 사용한다. 10월 10일 준비 기록은 당시 기록으로 보존한다.
기준 소스와 전달 자료
현재 소스 기준은 GitHub shkim25027/HMDesignSystemTest의 main이다. 이번 작업 시작 Local/GitHub HEAD는 모두 4fe549da01683c363b0715aedeb82a089717f685, 작업 트리는 CLEAN이었다. 이 기준에서 실행 코드·CSS·Theme·의존성·Story는 바꾸지 않고 문서만 보완한다. 문서를 포함한 최종 commit SHA는 자기 커밋 파일에 넣을 수 없으므로 작업 종료 보고와 로컬 _local/finalization-20261011/release-manifest.json에 기록한다. 월요일에는 전달받은 최종 전체 SHA와 아래 실제 GitHub main 조회 결과를 비교해 대상 소스를 고정한다.
git rev-parse HEAD
git branch --show-current
git status --porcelain=v1
git ls-remote https://github.com/shkim25027/HMDesignSystemTest.git HEAD refs/heads/main
git ls-files
최종 소스 목록은 595개 경로다(기존 592개 + 이번 준비/보고/목록 3개). JSON의 paths와 실제 git ls-files를 비교한다. 이후 새 commit이 생기면 SHA·목록·변경 영향 판정을 새로 확인한다. GitHub에서 일부 최근 변경 파일만 복사하면 기존 기반 파일을 누락할 수 있다.
Git 소스와 별도로 보관할 로컬 증거는 다음과 같다. 이 경로는 Clone에서 열 수 있는 문서 링크가 아니다.
- HMDesign:
_local/finalization-20261011/의 최종 보고, release manifest, tracked-files.txt, 재사용/보존 근거, 검증 로그. - 독립 실험:
D:/디자인시스템/HMDesign-AI-CrossModel-Test/finalization-20261011/의 실행기 V3 후보와 21개 모의검사 근거. - 과거 실험·접근성·보안 증거: 기존 폴더를 그대로 보관하며 소스 이전 commit에 추가하지 않는다.
프로젝트 진입점
| 영역 | 실제 경로와 역할 |
|---|---|
| workspace | package.json, package-lock.json, packages/* |
| UI 공개 API | packages/ui/src/index.ts, packages/ui/package.json |
| UI 구현과 Pattern | packages/ui/src/components/ui/, packages/ui/src/patterns/ |
| Theme | themes/default.json, packages/ui/src/theme/, packages/ui/src/theme.css, packages/ui/src/tailwind.css |
| CENTER | packages/center-graphic/src/index.ts, packages/center-graphic/package.json |
| 기본 React 앱 | index.html → src/main.tsx → src/App.tsx, src/index.css → src/hm-theme.css |
| Storybook | .storybook/main.ts, .storybook/preview.tsx, .storybook/manager.css, src/**/*.stories.tsx |
| 새 목록 제작 예제 | examples/publisher-list/README.md, main.tsx, vite.config.ts |
| AI 규칙과 검사 | AGENTS.md, docs/guidelines/ai-screen-contract.md, scripts/ai-generation-guard.mjs |
| Windows 실행기 | start-storybook.bat, scripts/start-storybook.mjs |
Storybook manager 스타일은 main.ts의 managerHead에서 CSS를 연결한다. 별도 manager.ts/tsx 파일은 필수 파일이 아니다. 생성 package dist·앱 dist·storybook-static·theme-dist는 Git에 없으며 설치 후 재빌드한다. Noto Sans KR는 public/fonts/의 추적 asset과 라이선스를 유지한다.
의존성과 실행 조건
Node.js 조건은 lockfile/Vite 기준 ^20.19.0 || >=22.12.0이며 Node 21은 제외한다. 검증 환경은 Node 20.20.1, npm 10.8.2, Windows, React/ReactDOM 19.3.0, TypeScript 7.0.2, Vite 8.3.0, Storybook 10.6.1, Tailwind/@tailwindcss/vite 4.3.3이다. 공식 회사 환경의 버전·프록시·인증·레지스트리 접근은 NOT VERIFIED다.
정확한 전체 의존성은 package-lock.json으로 고정한다. root의 UI/CENTER workspace, UI의 Radix·cmdk·TanStack Table·lucide-react 등과 React/Tailwind peer 계약을 유지한다. @tanstack/react-table과 @tanstack/table-core는 모두 9.2.4다. 개발 shadcn과 CSS 복사 계약도 유지하며 이번에 업데이트하지 않았다.
최초 설치와 실행:
node --version
npm --version
npm ci --no-audit --no-fund
npm run build:packages
npm run storybook
# http://localhost:6024/
# 별도 터미널의 실제 React 목록 예제:
npm run dev:publisher-example
Windows의 start-storybook.bat은 의존성/산출물이 없으면 준비하고 6024의 index/preview 응답을 확인한다. Node/npm/Git은 별도 설치 대상이며 포터블 Node나 ZIP을 제공하지 않는다. 공식 사내 실행 환경의 설치·호스팅 결과는 월요일 확인한다.
검증 명령과 선택 기준
소스 이전 후 package를 빌드하고 최종 타입과 build를 확인한다. typecheck의 prehook가 Theme defaults 확인과 package build를 수행한다. 같은 source/dependency 조건에서 이미 성공한 hook는 --ignore-scripts로 중복을 줄일 수 있다.
npm run typecheck
npm run build --ignore-scripts
npm run build-storybook --ignore-scripts
node scripts/check-doc-links.mjs
node scripts/public-theme-tokens.mjs
변경 영향에 따라 아래 검사 중 필요한 것만 선택한다. 소스와 의존성·환경이 같은 기존 PASS를 재사용하고, 전체 292 Story 렌더를 무조건 반복하지 않는다. 회사 환경에서 새로운 설치/빌드 실패가 생기면 해당 실패를 해결·재검사한 뒤 진행한다.
# Guard 또는 증거 계약이 달라졌을 때: 현재 75 + 20 + 5
node --test scripts/ai-generation-guard.test.mjs scripts/guard-evidence.test.mjs scripts/guard-requirements.test.mjs
# Component / 접근성 / Theme 영향이 있을 때:
npm run test:components
node --test scripts/accessibility-regression.test.mjs
node --test scripts/theme-verification.test.mjs
# 소비 예제 영향이 있을 때:
npm run build:publisher-example
npm run build:dashboard-export
node node_modules/vite/bin/vite.js build --config vite.recruit-export.config.ts
브라우저 QA는 별도 설치된 Playwright·Chrome을 HM_PLAYWRIGHT_DIR·HM_CHROME_PATH로 연결한다. scripts/verify-accessibility-runtime.mjs는 HM_A11Y_URL과 별도 HM_A11Y_OUTPUT에 명명된 선택 검사를 기록한다. 실제 SR 발화·실터치는 이 스크립트의 PASS로 대체하지 않는다.
audit-quality-contracts.mjs는 과거 GitHub BASE와 로컬 절대 증거 경로 2개에 의존하는 역사 비교 도구다. 공식 Gitea 이력에 BASE commit을 가져와 실행하지 않는다. 공식 환경에서 그대로 실행하는 검증 목록에서 제외하고, 필요 시 별도 승인 범위에서 baseline 입력을 연결한다. 제품 앱·package manifest의 로컬 절대경로 의존성은 발견되지 않았다. CSS의 외부 Reference 경로 주석과 과거 QA 안내는 실행 의존성이 아니다.
AI Guard 명령
현재 scope는 FULL_SCREEN/PARTIAL이고, STORYBOOK은 profile이다. Production --result는 실제 React bootstrap에 연결한다.
node scripts/ai-generation-guard.mjs --target <앱> --scope FULL_SCREEN --mode GNB_ONLY --result index.html --json
node scripts/ai-generation-guard.mjs --target <앱> --scope PARTIAL --mode LNB_ONLY --files src/main.tsx --result index.html --json
node scripts/ai-generation-guard.mjs --target . --profile STORYBOOK --scope PARTIAL --files src/components/combobox.stories.tsx,src/patterns/gnb.stories.tsx,src/patterns/lnb.stories.tsx --json
node scripts/guard-evidence.mjs <guard.json> <runtime.json>
--scope STORYBOOK과 STORYBOOK profile의 --result는 설정 오류다. exit 0만으로 PASS로 판단하지 않는다. 원본 status, staticStatus 및 CSS의 STATIC/RUNTIME/DESIGN_INTENT/FINAL을 별도로 보고한다. 오래된 source/contract 해시를 새 값으로 덮어쓰지 않는다. STYLE-001 FAIL, 동적 Token 유한 후보 선언, 외부 입력 미검증과 recipe가 디자인 승인 근거가 아니라는 계약을 유지한다. 비신뢰 Storybook 설정·glob 입력은 개발 의존성 위험 때문에 제한한다.
보존할 디자인과 정책
- D-01 중첩 Panel 제거·
padding: 24px 0, D-02 Primary 상단 White alpha 0.8, Secondary·Legacy 유지. - 확정 목록 구성·조회 Solid Green/초기화 Outline Gray, Button Gray/Solid Red, Table 강조 20%, Progress 우측 radius, Accordion 제목 hover 5%, Sheet 안쪽 모서리, Drawer 모바일 버튼 순서.
- Green LNB 펼친 2Depth와 Storybook 왼쪽 목차 배경 Black 8%. 선택·Hover·Focus와 전체 opacity 유지.
- Theme 값의 원본은
themes/default.json. 공통 Color/Typography/Spacing/Token·Component API·대표 Story ID를 임의 변경하지 않는다. Sheet 최종 radius 등 미확정 값은 확정하지 않는다. - 실제 HM React 공개 Component/Pattern을 사용한다. ONE PAGE = ONE NAVIGATION MODE, GNB mobile 동반, 공식 LNB ONLY 허용, 신규 GNB/Dashboard Sidebar 금지, Dashboard Header 48px·최소 960px 내부 스크롤.
- Storybook은 Reference다. 신규 업무 화면을 Story로 추가하지 않고 소비 bootstrap의 공개 Theme/Tailwind/status와 package font asset 연결을 유지한다.
남은 문제
| 분류 | 보존할 상태 |
|---|---|
| T03 Medium/High | 화면 생성 전 중단. 생성·품질·반응형·접근성 모두 NOT VERIFIED. 승인 12/12 사용, 추가 모델 호출 0 |
| T03 실행기 | V3 후보 로컬 21/21 PASS. 기존 실행기·launcher·승인·STOP 보존. 실제 모델 세션에서의 통합은 NOT VERIFIED; 별도 승인 후 새 manifest로 사용 |
| CSS Intent | T01 디자인 의도·미실행 동적 Theme/상태 NOT VERIFIED. 이전 contract는 역사적 결과만 재사용 |
| 보안 | 과거 감사 기준 개발 High 7·Critical 0, 운영 0. braces 전파 경로, 안전한 patch 미확인. 새 audit/업데이트 없음 |
| 접근성 | 활성 placeholder·일부 버튼/오류 대비 FAIL/DEFERRED. SR·실터치·Drawer drag·확대·모든 Theme/브라우저 NOT VERIFIED |
| 빌드 | 기존 500kB chunk와 Storybook bundler 성능 경고 보존 |
| 공식 환경 | Gitea 전용 파일·기존 소스 차이·분기/보호 정책·사내 Node/npm·호스팅·인증 NOT VERIFIED |
월요일 공식 이력을 유지하는 반영 순서
아래는 월요일 별도 승인된 작업의 절차이며 이번에는 실행하지 않았다.
- 공식 Gitea checkout의 실제 branch/HEAD/working tree를 기록한다. 공식 저장소에만 있는 파일과 사용자 변경을 보존한다. 기존 이력 위에서 작업용 branch를 만들고 GitHub 소스와의 경로별 차이를 확인한다.
- 고정한 최종 GitHub SHA의 추적 파일만 별도 소스 디렉터리에서 비교·복사한다.
.git을 복사하거나 GitHub main을 공식 main에 merge/cherry-pick하지 않는다. ZIP을 배포 수단으로 만들지 않는다. .gitignore, package/lock,.storybook, Component/Pattern/Theme, fonts/assets, scripts, examples/docs를 빠짐없이 반영한다.node_modules·dist·storybook-static·_local·실험 자료·개인 환경/비밀정보를 넣지 않는다.- GitHub에 없는 공식 파일은 삭제 대상으로 간주하지 않는다. 양쪽에서 같은 경로를 변경했거나 삭제 후보가 있으면 소스/회사 설정의 용도를 확인해 결정한다. 일괄 미러링 삭제나 사용자 변경 덮어쓰기는 하지 않는다.
- 공식 작업 branch에서 설치·타입·build·Storybook과 변경 영향 검증을 수행한다. 실제 공식 assets/경로, 문서 링크와 staged diff를 확인한다. 필수 실패가 있으면 공식 반영을 보류한다.
- 회사의 review/branch 정책에 따라 공식 저장소에서 별도 commit하고 공식 기존 이력에 반영한다. GitHub 임시 이력을 가져오거나 force push/reset/clean으로 맞추지 않는다. 공식 Local/Remote SHA와 working tree를 확인한다.
- 공식 이전·검증·원격 확인이 모두 끝난 다음 별도 지시로 GitHub 원격 연결을 해제한다. 먼저
git remote -v로 실제 이름/URL을 기록하고 공식 remote를 확인한다. 공식 clone의 origin이 Gitea라면 origin을 제거하지 않는다. GitHub URL을 가리키는 정확한 remote만git remote remove <확인한 GitHub remote 이름>으로 제거하고git remote -v를 다시 확인한다. GitHub 저장소·이력 자체는 삭제하지 않는다.
작업 환경
- 1순위 추천: 공식 Gitea에 접근 가능한 로컬 Git·Node.js 개발 환경.
- 추천 이유: 공식 이력과 회사 전용 파일을 비교하고 설치·명령 실행·검증·staged diff 검토까지 같은 checkout에서 수행할 수 있다.
- 사용 방식: 별도 이전 지시와 함께 이 문서, 최종 전체 SHA, 소스 목록, 로컬 release manifest를 전달한다. 실제 회사 네트워크·권한·도구 가용성은 월요일 확인한다.