HMDesign/docs/reports/hmdesign-v2-final-baseline-2026-10-11.md

HMDesign v2 최종 완료 기준점 및 AI 활용 인수인계 — 2026-10-11

RESULT: PASS — 정의된 내부 공유·React AI 화면 제작·Git Clone 활용 범위. 아래 기존 검증과 변경 영향 대조를 근거로 HMDesign v2를 최종 완료본으로 기록한다. Runtime·Design Intent·접근성 등의 잔여 미검증은 별도로 보존하며 전체 환경 인증으로 확대하지 않는다.

1. 공식 Baseline

항목	확정 기준
VERSION	HMDesign v2. 루트/package.json의 npm 버전 0.1.0과 별개의 프로젝트 완료 명칭이며 package version을 변경하지 않는다.
IMPLEMENTATION_SHA	09321e7d1491df3ef8358e566fffb57761992eb2
구현 Commit	docs(storybook): simplify Foundation Color to brand palettes
공식 저장소	Gitea HMDesign, Clone URL: https://gitea.hmac.kr/b25027/HMDesign.git
공식 수정 경로	D:\디자인시스템\HMDesign-Gitea-Transfer
시작 상태	main, Local HEAD = 실제 원격 main = 위 IMPLEMENTATION_SHA, Working Tree CLEAN, 기존 미커밋 변경 없음
기준 이후 변경	작업 시작 시 없음. 이번 작업은 이 보고서 1개만 추가하며 구현 파일은 보존한다.
DOCUMENTATION_COMMIT_SHA	이 보고서가 들어간 후속 문서 Commit. 아래 조회 명령으로 식별하며 IMPLEMENTATION_SHA와 구분한다.

문서 Commit은 자기 SHA를 본문에 포함하지 않는다. 최종 응답에는 실제 문서 Commit SHA·Push 결과·Local/Remote 일치·Working Tree를 기록한다. 문서 후속 Commit으로 main이 전진해도 위 구현 Baseline은 바뀌지 않는다. 별도 Git Tag는 생성하지 않는다.

2. 완료 범위와 현재 계약

기준 우선순위와 변경/Git 정책은 AGENTS.md가 우선한다. 이 보고서는 완료 상태와 기존 계약의 진입점을 연결하며 새로운 구현 규칙을 만들지 않는다.

영역	Baseline 상태 / 공식 근거
Component·Pattern·공개 API	기존 HM React Component와 업무/Layout Pattern 유지. Reference Index, 공개 export, package exports/types를 기준으로 선택한다. 기존 Component 회귀 9/9 PASS를 재사용한다.
Theme·Token Contract	Default JSON → 생성 기본값/CSS → Runtime 계약 연결 유지. 현재 Runtime 입력 94개(색상 92 + radius 2), JSON 컬러 92개. 공개 CSS 고유 선언명 1,203개는 다른 집계 단위이며 기준 3ebc84e32cf91298a2a4d8046753244c499fd719 이후 관련 CSS 불변 범위의 기록이다.
브랜드 Palette	한맥그린·한맥브라운·한맥오렌지 각 8단계, 총 24개. 현재 브랜드 단계와 Orange 최종 확정을 따른다. 과거 Orange Dark 1/2 보류는 당시 기록이다.
Semantic Color	기존 Primary·Content/Surface·Foreground·Stroke·Active/Focus·Destructive mapping 보존. Generic Status Error #B3261E는 독립 Provisional, Destructive #D32F2F 유지. Focus #266651 시험 적용 상태를 최종 확정으로 바꾸지 않는다.
Background Gradient	Green·Brown·Orange 공통 배경 3종, 각 5-stop. Background 기록 및 현재 Runtime 계약을 따른다. 색·방향·Stop 정의를 변경하지 않는다.
Button·Dashboard Gradient	기존 Button 전용 Gradient, Dashboard Header/Compact 배경 유지. Foundation에서 미리보기가 제거되어도 실제 Token·기능은 존재한다. 공통 Background와 전용 Gradient를 동일 역할로 안내하지 않는다.
Typography·Spacing	기존 정의·geometry 보존. Token 정책과 v2 선택 검수의 변경 영향·보존 증거를 재사용한다. 미정의 Token을 만들어 사용하지 않는다.
Navigation	단일 모드 정책: GNB ONLY / LNB ONLY / DASHBOARD ONLY 중 하나. 공식 독립 LNB 허용. 신규 GNB/Dashboard Sidebar 금지. GNB는 GNBMobileMenu, Dashboard는 48px Header·최소 960px·내부 스크롤을 유지한다.

2026-10-11 완료 요청은 v2 선택 검수, Orange 8단계 확정, Input Story Disabled Label 60%(공통 Label 50% 유지), Generic Status Error 추가, Brown/Orange 공통 Background 추가, Foundation 최종 표시 정리, 실행 안내 보완, Guard CSS 클래스 오판정 수정이다. Disabled Label 기록을 포함한 당시 보고서는 삭제하지 않는다. Provisional·미확정 값의 디자인 승인은 이 완료 판정과 별개다.

3. Storybook / Foundation Color 최종 상태

최종 표시 보고서와 실제 Color Story를 기준으로 한다.

• 한맥그린 8개 + 한맥브라운 8개 + 한맥오렌지 8개 = 24개 컬러칩.
• 각 칩에 단계명·현재 HEX 표시, Default 3개 강조 유지.
• Accent·Semantic 별도 섹션, Gradient 섹션, Mid·Deep 등 Button 전용 칩, 개발용 Token 상세, 단계 순서 나열 소개 문구는 Color 화면에서 제외.
• 실제 Theme·Semantic Token·공통 Background·Button·Dashboard Gradient 기능은 유지.
• 기존 Foundation/Color / All / foundation-color--all, 기존 292개 Story ID 유지. 신규 업무 화면 Story 등록 없음.

최종 정적 Storybook build·실제 React 렌더·390/768/1280/1440px 검사 PASS를 재사용한다. 24개 표시 HEX·computed 배경색·Default JSON 일치, 콘솔 error 0. 좁은 폭은 Palette 행 내부 가로 스크롤이며 문서 전체 가로 넘침 없음. 이 증거는 Baseline Color 표시 범위이며 전체 292 Story Runtime 전수 인증이 아니다.

4. 검증 증거와 SHA별 변경 영향

기존 Acceptance Test

기준은 **e9144348e5f2f9be12130b707b1e2b389476880e**다. 새 공식 Gitea Clone의 원본 acceptance-report.txt, guard.json, runtime.json, combined.json, browser-evidence.json을 확인했다. 원본은 테스트 Clone D:\디자인시스템\HMDesign-AI-Acceptance의 _local/acceptance/에 보존되며 Git Clone 배포에는 포함되지 않는다. 공유 가능한 요약은 배포 안내의 Acceptance 근거에 있다.

항목	보존 결과 / 재사용 범위
AI Dashboard 생성·독립 React build/렌더	REUSED PASS, 당시 소비 화면 소스 기준. 이번에 새 화면을 생성하지 않음
390·768·1280·1440px	REUSED PASS, 네 폭 모두 PASS. Dashboard 48px Header·960px 내부 스크롤
핵심 상호작용	12/12 REUSED PASS
상태 색상	48/48 REUSED PASS, computed 측정 범위. CSS site 전수·Design Intent 승인으로 확대하지 않음
신규 공식 Gitea Clone·npm ci·workspace 연결	REUSED PASS, Node 20.20.1 / npm 10.8.2
독립 Storybook	REUSED PASS, 별도 6124에서 당시 새 Clone 실행·대표 9개 Story. 기본 6024 재사용과 별개
원본 Guard / 결합 판정	원본 status/staticStatus/runtimeStatus 및 결합 status NOT VERIFIED. 당시 결합 Runtime PASS와 미검증을 구분
실행 안내 정합성	당시 PARTIAL의 원인이었던 기존 서버 재사용 설명은 26d78763cc18aa35666643e245a3edd1ef0bd2dc에서 보완. 현재 README·배포 안내와 실제 실행기 분기를 대조하여 확인

Acceptance 소스 fingerprint와 당시 contract fingerprint는 원본 Clone에 여전히 일치한다. 현재 Baseline의 contract fingerprint는 Guard 수정 때문에 불일치한다. 당시 결합 Runtime PASS는 역사적 해시 연결 결과로 보존하며 현재 Guard 계약의 결합 PASS로 이식하지 않는다.

Acceptance 이후 완료 변경

Commit	변경 / 증거 영향
26d78763cc18aa35666643e245a3edd1ef0bd2dc	README·배포 안내의 6024 재사용·독립 QA 설명 보완. 실행기·Component·Theme 불변. 당시 배포 PARTIAL의 문서 원인 해소
d6d6eb53afa57cc267e5ff337177e00c7d2e92f2	Guard·스타일 분석·회귀 테스트 3개 파일만 수정. 주석·일반 문자열·부분 클래스의 오판정 수정, 실제 클래스·동적 입력 보호 유지. 최신 회귀 소스 해시와 보존 로그 일치
09321e7d1491df3ef8358e566fffb57761992eb2	Color Story 표시와 관련 문서 정리. Foundation은 새 최종 build/4폭/24칩 증거 사용. 다른 Component·Pattern·Theme·Token·Dashboard·실행 설정은 불변

e9144348… → 09321e7d…의 Git diff에서 packages/themes/Storybook 설정/package·lock/실행기/Theme entry/Pattern 구현 변경은 0이다. 따라서 기존 Dashboard·Theme 소비·설치 경로 PASS는 변경되지 않은 구현의 근거로 재사용한다. 최신 Foundation 화면을 과거 Color 캡처로 증명하지 않는다.

최신 Guard·Component 및 Foundation 증거

• Guard 94/94 + 증거 연결 20/20 + 요구사항 5/5 = 119/119 PASS, 실패·skip 0.
• Component 회귀 9/9 PASS, 실패·skip 0.
• 최종 Foundation의 typecheck·Storybook build·4폭 React 렌더 PASS는 최종 표시 보고서와 _local/foundation-color-cleanup-20261011/의 보존 로그/JSON을 재사용.
• Foundation 최종 Guard의 source/contract fingerprint는 현재 Baseline에 일치. 원본 status/staticStatus/runtimeStatus: NOT VERIFIED, FAIL 0. styleEvidence: STATIC PASS / RUNTIME NOT VERIFIED / DESIGN_INTENT PASS / FINAL NOT VERIFIED. 결합 styleVerification은 생성하지 않았다.
• Acceptance의 결합 styleVerification: STATIC PASS / RUNTIME NOT VERIFIED / DESIGN_INTENT NOT VERIFIED / FINAL NOT VERIFIED. Foundation의 승인 범위를 Acceptance 소비 CSS 승인으로 확대하지 않는다.

이번 작업에서는 원본 증거·Git diff·해시·회귀 로그 수량을 대조하고 문서 링크·내용·개인정보·Stage 범위를 검사한다. 전체 Build·Dashboard 재생성·브라우저 회귀·Guard/Component 정상 suite·npm 설치를 반복하지 않는다. 문서만 추가하므로 AI 화면용 Guard 재실행은 해당하지 않는다.

5. AI 활용 순서와 시작 안내

1. 공식 Gitea 저장소를 Clone하고 사용 SHA가 Baseline인지, 그 이후 어떤 변경이 있는지 확인한다.
2. AGENTS.md를 먼저 읽고 Scope·Runtime·요구사항·필수 동작·완료 조건을 정한다.
3. AI 화면 선택·완료 계약 → Component/Pattern Index → 선택 문서·필요 Props를 확인한다. Pattern → Component → Variant/Prop → Composition 순으로 재사용한다. 목록 검색은 FilterBar를 검토하고 부적합하면 구체적 제약을 기록한다.
4. 선택한 Storybook 대표 All Story의 디자인·상태·동작을 확인한다. verification Story를 운영 디자인 기준으로 삼지 않는다.
5. 기존 Theme·Token과 공개 CSS entry를 사용한다. React bootstrap의 index.css → hm-theme.css, 필요 시 공개 Status CSS 연결을 유지한다. Runtime Theme와 Portability의 관련 계약만 읽는다.
6. 공개 @hm-design/ui API로 독립 React 화면을 생성한다. 공개되지 않은 Component·내부 package 경로·Token을 추측하지 않는다. Storybook은 참조용이며 새 업무 화면을 등록하지 않는다.
7. 화면 build/typecheck·AI Guard·실제 React 렌더를 검증한다. Guard는 --target <앱> --scope FULL_SCREEN --mode <선택 모드> --result <실제 bootstrap>으로 완료 후 1회 실행하며, FAIL 수정 시 변경 범위만 PARTIAL 재검사한다. 네 폭·필수 상호작용·Label/접근성 이름·키보드/focus·disabled/readOnly를 확인한다. 원본·정적·Runtime·STYLE 판정과 미검증을 구분한다.

Codex / ChatGPT Work

Clone한 프로젝트 또는 접근 가능한 실행 환경을 연결하고 다음 시작 프롬프트에 실제 업무 요구사항을 채워 전달한다.

HMDesign v2 기반으로 [화면 목적]을 구현하세요.
공식 저장소: https://gitea.hmac.kr/b25027/HMDesign.git
구현 Baseline: 09321e7d1491df3ef8358e566fffb57761992eb2
소비 앱 경로: [경로], Scope: PRODUCTION_UI, Runtime: React
요구사항·필수 동작·완료 조건: [기재]

AGENTS.md를 먼저 읽고 기존 AI 화면 계약 → 선택한 Component/Pattern 문서
→ 대표 All Story → 공개 API/Theme/CSS entry를 확인하세요.
기존 HM Component·Pattern·Token과 한 가지 Navigation 모드를 재사용하세요.
요청된 기능만 구현하고 신규 업무 화면을 Storybook에 등록하지 마세요.
AGENTS에 따른 최종 통합 검증과 실제 React 렌더 근거를 남기고
재사용한 검증·새로 수행한 검증·NOT VERIFIED를 구분해 보고하세요.
기준 이후 변경이 있으면 영향부터 확인하고 기존 이력을 보존하세요.
공식 저장소 변경/Git 작업은 현재 AGENTS와 사용자 작업 지시를 따르세요.

• 1순위 추천: Codex의 로컬 저장소·명령·브라우저 검증 가능한 환경.
• 추천 이유: React 소스 수정, 공개 API 확인, build/Guard 실행, 실제 렌더 및 Git diff 검증이 한 작업에 필요하다.
• 차선책: Claude Code(아래 안내), 또는 동일한 저장소·명령·렌더 도구 접근이 제공되는 ChatGPT Work.
• 사용 방식: Clone한 프로젝트와 업무 요구사항을 함께 제공하고 시작 프롬프트를 붙여넣는다. 일반 채팅에 URL만 전달하는 것으로 파일 접근·실행 검증이 보장되지는 않는다.

ChatGPT Work의 실제 저장소·사내 Gitea 접근, 터미널·브라우저 연결 가능 여부는 현재 플랫폼·계정·요금제·조직 정책과 제공된 도구에 따라 확인한다. 접근 불가 시 실행·수정·검증 완료를 주장하지 않는다. OpenAI 공식 로컬 환경 안내와 설정 안내를 2026-10-11 확인했다. Work의 관리형 환경이 로컬 Codex 설정을 그대로 읽는다고 가정하지 않는다.

Claude Code

coding-development-orchestrator Skill이 설치된 Claude Code 환경이라면 위 시작 프롬프트 앞에 다음 문장을 추가한다. 설치 여부는 확인하며 설치되어 있다고 단정하지 않는다.

`coding-development-orchestrator` Skill을 사용하여 다음 작업을 처리하세요.

설치되어 있지 않다면 위 프롬프트와 AGENTS 기준으로 직접 진행한다. 전문 Skill 전체를 처음부터 지정하지 않으며 오케스트레이터가 필요한 역할만 선택하도록 한다. 중간에는 다음 진행에 필요한 확인만 하고 최종 통합 검증에 필요한 검사를 모은다. 실제 저장소·명령·렌더 접근 조건을 갖춘 Claude Code에서 사용한다.

• 1순위 추천: 위 로컬 개발·검증 작업 전체에는 Codex.
• 추천 이유: 현재 프로젝트에서 확인된 저장소·명령·공식 Git 검증 도구를 활용할 수 있다.
• 차선책: 관련 Skill과 로컬 도구 접근이 준비된 Claude Code.
• 사용 방식: Claude Code 프로젝트에 동일 Clone과 요구사항을 제공하고, 설치 조건에 맞는 첫 문장과 공통 시작 프롬프트를 함께 전달한다.

6. 배포·Storybook 활용

정확한 설치·실행 방법은 README와 기존 배포 안내를 재사용한다. 별도 배포 문서를 만들지 않는다.

• Node.js ^20.19.0 || >=22.12.0, Node 21 제외. npm과 PATH, Gitea/npm 레지스트리 접속 필요. 검증 환경은 Node 20.20.1 / npm 10.8.2이며 npm의 별도 버전 고정 계약은 없다.
• 최초 독립 설치: Clone 루트에서 npm ci → npm run build:packages → npm run storybook. 실제 scripts를 따른다. Git 소스에는 node_modules·dist·사전 빌드 Storybook·포터블 Node가 없다.
• 기본 Storybook 6024, Windows start-storybook.bat 제공. BAT는 Node 실행기 scripts/start-storybook.mjs를 호출한다(두 파일은 2026-10-22 제거, 당시 기록).
• 준비된 6024의 index/대표 Story ID/iframe 조건을 만족하면 기존 서버를 열고 종료한다. Node 검사 후 npm 설치·package build를 생략할 수 있으며 새 Clone 독립 실행의 증거가 아니다.
• 준비되지 않은 점유 서버는 오류. 빈 포트는 필요한 의존성 설치·export 산출물 build 후 새 서버를 실행한다. BAT에 포트 변경 옵션은 없다. 전체 의존성 정상 상태·산출물 최신성을 자동 인증하지 않는다.
• 독립 QA의 6124는 기존 서버 보존용 개발 포트 사례. 최신 Foundation의 6322는 당시 정적 build 열람 포트 사례. 과거 ZIP의 6007과 모두 기본 6024에서 구분한다. 독립 QA 절차를 따른다.
• Registry publish·실제 CDN 운영은 Git 내부 공유 완료 범위 밖이다. 신규 ZIP은 생성하지 않는다.

7. 남은 제한과 후속 검토

BLOCKERS: 이번 Baseline 확인에서 신규 구현·설치·렌더 차단 오류 없음. 추가 구현 없이 내부 공유·AI 화면 제작용 최종 완료본으로 판정한다.

SHOULD_FIX: AI Guard 가이드의 Theme Token 검사 도입부(현재 15행)에 “현재 suite는 Guard 75개·증거 연결 20개·요구사항 연결 5개”가 남아 있다. 최신 수량은 94+20+5=119이며 위 최신 로그와 보고서를 따른다. 명백한 수량 참조 오류의 정정 대상만 보고하고, 이번 허용 범위에 따라 기존 문서는 수정하지 않는다. Guard 구현/판정 차단 오류는 아니다.

NOT VERIFIED / 미확정 상태는 다음과 같이 보존한다.

• Guard 원본·CSS site 전수, 미해석 동적 className/style·미실행 분기의 Runtime, 소비 CSS Design Intent, 최종 STYLE 판정. source/contract가 달라진 옛 증거를 최신 연결 PASS로 바꾸지 않음.
• 실제 스크린리더, 실기기 touch/drag, 확대, 모든 Component × viewport × Theme × 브라우저 전수, 신규 Acceptance 화면의 외부 Theme. 과거 승인 색 대비 FAIL/DEFERRED 및 일부 접근성 잔여 기록은 안정화 보고 등 당시 기록대로 보존하며 새 인증으로 대체하지 않음.
• Node 미설치 PC, 기본 빈 6024의 신규 서버 분기, BAT 자동 npm-ci 분기, 비HM 포트 점유 등의 미실행 실제 분기. 코드 설명과 실행 PASS를 구분함.
• 교차 모델·낮은 추론 재생성, T03 생성/품질·수치 디자인 점수. 과거 실험의 미검증을 이번 완료 판정으로 해소하지 않음.
• Generic Status Error Provisional, Focus 시험 적용, Sheet 등 기존 미확정 디자인 값. 과거 개발 의존성 High 7 기록은 보존하며 최신 취약점 재감사·안전한 patch 확인은 이번 범위 밖이다.
• Git Registry publish·외부 공개 License·실제 CDN 운영·모든 내부 사용자 PC 실행. 현재 개인 경로/비밀정보 후보 점검은 Git 과거 이력의 개인정보 삭제 인증이 아니다.

OPTIONAL: 후속 Guard 가이드 수량 정정, 사용자 승인을 거친 Baseline Tag, 별도 접근성/배포 환경 검증. 이번에는 Tag·코드 변경·과거 Commit 작성자 문제 처리·이력 재작성 없음.

8. 향후 기준 Commit 확인과 Git 운영

git remote get-url origin
git branch --show-current
git rev-parse HEAD
git ls-remote origin refs/heads/main
git status --short
git show --no-patch --format=fuller 09321e7d1491df3ef8358e566fffb57761992eb2
git log --oneline 09321e7d1491df3ef8358e566fffb57761992eb2..HEAD
git diff --stat 09321e7d1491df3ef8358e566fffb57761992eb2 HEAD
git log -1 --format=%H -- docs/reports/hmdesign-v2-final-baseline-2026-10-11.md

위 마지막 git log는 이 보고서의 최신 문서 Commit SHA를 반환한다. 이후 본문을 갱신하면 갱신 Commit이 반환되므로 최초 기록은 git log --follow -- docs/reports/hmdesign-v2-final-baseline-2026-10-11.md로 확인한다.

후속 HEAD는 Baseline 이후 변경을 검토하고 사용하며 이전 SHA를 자동으로 덮어쓰지 않는다. 공식 origin·main·기존 미커밋 변경·최신 원격을 확인하고, 원격이 작업 시작 이후 바뀌면 중단해 영향을 확인한다. 관련 파일만 Stage·Staged Diff 검토 후 일반 Commit/Push한다. 공식 계정과 일치하는 Author/Committer를 사용하고 전역 설정·인증값·과거 Git 이력을 변경하지 않는다. GitHub 이전 원본·백업 브랜치·Force Push·Reset·Clean은 사용하지 않는다.

이번 보고서는 구현 Baseline 09321e7d…를 기록하는 후속 문서다. 이 문서의 추가는 Component·Pattern·Theme·Token·Storybook·Guard 구현과 기존 정상 검증 증거를 보존한다.