HMDesign/docs/org-chart/quality-review-p1.md

HMDesign OrgChart P1 — 품질 보완 및 디자인 검수

RESULT: PARTIAL

이번 변경은 기존 P1의 Gradient 대비 검사, Department Colors, 실제 로고 표시, Guard 원인 분석으로 제한했다. 사용자가 최종 확인한 대로 Workdesk 전체 디자인 재현 첨부는 참고 자료로만 사용했다. 전체 배치·카드 구조를 다시 개발하지 않았다. 기존 기능·데이터 계약·공개 API·React Wrapper·공통 Theme/Token·운영 main은 보존했다.

작업 정보

• 작업 폴더: D:\디자인시스템\HMDesign-OrgChart
• 브랜치: feature/orgchart-package
• 전/후 HEAD: d18e3c33801e165e17b6d971e2f6198eed483c3c
• 실제 병렬 수행: Track A/B/C 읽기 전용 분석을 병렬 수행했다. 이후 B는 대비 모듈과 Department Colors, C는 두 Summary Story의 가상 데이터 안내, 메인은 로고 렌더링·CSS·검증·보고서를 담당했다. 같은 파일의 동시 수정은 없었다.
• Started At: 2026-10-12 11:55:44 KST
• Completed At: 2026-10-12 12:25:20 KST
• Actual Duration: 29분 36초
• Variance: 최초 예상 하한 45분 대비 15분 24초 단축, 상한 90분 대비 60분 24초 단축. 병렬 분석 및 기존 PASS 재사용으로 재검증 범위를 줄였다.
• Estimated Duration: 45–90분. 필요한 범위만 검사하며 시간을 채우기 위한 재검증은 하지 않았다.

Track A — Guard: 원인 분석 PASS, 전체 해결 PARTIAL

공통 Guard를 변경하거나 검사 규칙을 비활성화하지 않았다. 실제 themeAnalysis에 인메모리 fixture를 전달한 최소 재현 8/8이 통과했다. 이는 오탐 재현 PASS이며 실제 Guard PASS가 아니다.

최종 PARTIAL/STORYBOOK Guard 결과는 원본 status=FAIL, staticStatus=FAIL로 보존했다. TOKEN-001 FAIL 8건, TOKEN-002 NOT VERIFIED 6건, SCOPE-001 NOT VERIFIED 3건이다.

• Shadow CSS 연결 누락 1건: --hm-orgchart-resolved-bg-surface는 design-tokens.css에 선언되고 공개 CSS로 번들되어 Shadow DOM에 연결된다. Guard graph는 ?url import와 Shadow link의 연결을 증명하지 못한다.
• setProperty 정의 미수집 4건: current-gradient, current-card-background, current-border는 applyOrganizationStyle이 정의한다. Guard가 이 DOM 선언을 수집하지 않아 참조를 미선언으로 판정한다.
• 선택적 입력 오분류 3건: 대비 후보의 --hm-orgchart-contrast-candidate-color 및 --hm-orgchart-contrast-candidate-chip-background는 로컬 fallback을 가진 외부 override 입력이다. 기본값은 각각 #10243b, #ffffff이며 실제로 정상 적용된다. 공식 Theme 변수의 누락과 동일하게 처리하는 현재 검사 정책은 이 계약을 표현하지 못한다.
• 동적 TOKEN-002 6건: 유한한 조직 preset/legend 문자열 조합을 정적으로 해석하지 못한다.
• CSS SCOPE-001 3건: 카드·콘텐츠·통계 CSS는 실제 Core CSS 번들과 Shadow link에 포함되지만 Storybook graph 범위 밖으로 판정된다.

브라우저에서 Shadow CSS 로딩, 6개 preset의 computed 값, fallback과 HTML/React 동일 렌더링을 확인했다. 이 증거로 raw FAIL을 덮어쓰지 않았다. 검사한 범위에서 실제 Production 미선언 변수 결함은 발견하지 못했다.

styleEvidence: STATIC PASS, RUNTIME NOT VERIFIED, DESIGN_INTENT NOT VERIFIED, FINAL NOT VERIFIED. 이 값은 Guard의 증거 연결 상태이며 별도 브라우저 PASS와 구분한다. 이번에는 결합 styleVerification으로 승격하지 않았다.

승인 필요한 최소 공통 Guard 변경안: 증명 가능한 Shadow CSS 연결, setProperty 정의 수집, 유한 후보 해석, 명시적 선택적 입력 계약 지원. Guard 분석기·style inventory/증거 연결·관련 회귀 fixture와 문서에 영향이 있으므로 별도 승인 전에 구현하지 않는다. 전역 CSS 강제 연결, dummy 선언, 변수 namespace 변경, fallback 일괄 면제는 적용하지 않았다.

근거: test-results/org-chart-quality/guard-reproduction.json, guard-storybook.json. 분석기 SHA 전/후 동일하며 기존 P1 Guard 원본도 유지했다.

Track B — Color Contrast: PARTIAL

기준은 WCAG 2.2 Contrast Minimum의 일반 텍스트 4.5:1, 큰 텍스트 3:1 및 Non-text Contrast의 의미 있는 UI/그래픽 3:1이다. 판정에는 반올림 전 값을 사용했다. 로고를 변색하지 않았다.

측정 방법과 범위

Core의 제한된 opaque sRGB/세로 Gradient 모델과 실제 Chrome DPR1 PNG를 분리해 기록했다. 모델은 Gradient stop, 전체 구간, DOM Range의 텍스트 line 구간을 구분한다. PNG에서는 텍스트 옆 빈 padding 열의 실제 배경 픽셀과 computed foreground를 사용한다. 안티앨리어싱된 글자 픽셀로 전경색을 추측하지 않았다. 모델과 픽셀 차이가 2 channel 값을 초과하거나 스크롤에 가려지면 NOT VERIFIED다.

지원하지 않는 alpha·복수 배경·다른 각도·다른 색 공간·합성 효과 등은 임의로 PASS하지 않는다. 이번 PNG 검사의 84개 가려진/일치하지 않은 probe는 NOT VERIFIED로 남겼다. 그중 솔루션영업 두 부서명은 마지막 가지로 스크롤한 별도 캡처에서 추가 검증했다. 숫자는 화면별 반복 측정이며 서로 다른 접근성 요구사항의 개수가 아니다. 전체 WCAG 인증으로 확대하지 않는다.

기존 HEX와 실제 텍스트 대비

6개 헤더 Gradient와 흰 부서명 #ffffff는 Workdesk v1.2610.9c5e, 2026-10-12의 기존 computed 근거를 유지했다. 직원 카드 배경은 자체 기본 #ffffff이고 테두리 기본은 해당 조직 시작색이다. 카드 면·테두리·geometry는 DESIGN_ADAPTATION, 공식 Workdesk 실측으로 승격하지 않았다. 변수 prefix에 -card-background, -department-color, -border, -gradient를 각각 사용한다.

• 사업관리: #194d82 → #1d395c, --hm-orgchart-business-management-*. 흰색 stop 최소 8.659:1. Full 실제 부서명 9.357:1 PASS.
• 경영기획: #2164a8 → #254975, --hm-orgchart-business-planning-*. stop 최소 6.082:1. Full 실제 부서명 약 6.654–6.676:1 PASS.
• 인재성장: #0f6ace → #044a94, --hm-orgchart-talent-growth-*. stop 최소 5.286:1. Full 실제 부서명 약 5.879–5.882:1 PASS.
• 통합시스템 Div: #8c67b6 → #5d3494, --hm-orgchart-integrated-system-*. stop 최소 4.439:1이지만 Full 실제 텍스트 구간은 약 5.008–5.197:1 PASS. stop 하나만으로 실제 텍스트를 FAIL 처리하지 않았다.
• 디자인기획: #09a7a2 → #00847f, --hm-orgchart-design-planning-*. stop 최소 2.974:1. Full의 15px bold 부서명 약 3.188–3.263:1 REVIEW. Department Colors의 19.5px bold 제목은 약 3.228:1로 큰 텍스트 기준 PASS, 일반 크기 비교는 약 3.263:1 REVIEW다. 큰 제목의 PASS를 Full에 대입하지 않았다.
• 솔루션영업: #5a963c → #3f7629, --hm-orgchart-solution-sales-*. stop 최소 3.582:1. 스크롤 후 Full 15px 부서명 약 3.916–3.917:1 REVIEW. Department Colors 큰 제목 약 3.922:1 PASS, 일반 크기 비교 약 3.922:1 REVIEW다.

위 Full 수치는 1440px 대표 실측이다. Department Colors의 화면 내 MODEL 값은 픽셀 실측과 별도이며 실제 geometry·브라우저 반올림에 따라 차이가 있다. UI에 MODEL임을 명시했다. Default 값만 검사했으며 모든 소비자 override 조합의 대비를 보장하지 않는다.

기타 확인:

• 직원 이름 #10243b / #ffffff: 15.701:1 PASS.
• 직위·상태의 보조 텍스트 #596575 / #ffffff: 5.927:1 PASS. 기본 콘텐츠 면 #f4f7fb 기준 약 5.516:1.
• 직책 배지 및 통계 헤더/숫자 텍스트: 검사한 solid 조합 PASS. 원본 값 변경 없음.
• 협업 허브 #45639f → #809dd7 위 흰 일반 텍스트: 실제 약 3.321:1 REVIEW; stop 최소 약 2.720:1. 허브 색은 Workdesk 실측으로 확인된 브랜드 값이 아니라 자체 디자인 기본값이다.
• 관계 표현 연결선 #bac7d7: 실제 Storybook 배경 #f5f0e5와 약 1.510:1, 흰 면과 1.716:1 REVIEW. 모든 카드 프레임·테이블 divider를 무조건 의미 있는 UI 경계로 판정하지는 않았다. 부모-자식 관계 연결선은 정보 전달 그래픽으로 검토했다.
• 키보드 focus-visible: 실제 2px solid #45639f, Storybook 배경 대비 5.222:1 PASS. 전체 키보드/스크린리더 검증으로 확대하지 않았다.

적용한 보완과 승인 대기안

실제 Production 브랜드 HEX 변경: 0건. Department Colors에 Aa, 실제 변수/HEX, 카드 배경과 부서명 전경 구분, 일반/큰 텍스트 대비, stop 보수값, MODEL/NOT VERIFIED 및 미적용 후보 표시를 추가했다. resize 시 실제 텍스트 구간을 다시 계산한다.

중요한 색상·geometry 변경은 승인 없이 적용하지 않았다. 후보는 UNAPPROVED_NOT_APPLIED로 표시하며 Full Composition에 반영하지 않았다.

• 디자인기획 흰 부서명 → #000000 후보: 전체 Gradient stop 최소 4.607:1. 텍스트 브랜드 표현 변경에 대한 승인 후 실제 화면 재검증 필요.
• 모든 Gradient의 단순 #10243b 전경 후보는 어두운 조직에서 실패한다. Department Colors에 실패 수치도 표시해 보편적 해결안으로 제시하지 않았다.
• 디자인기획/솔루션영업: 흰 label backing #ffffff + #10243b 후보는 15.701:1. 기존 Gradient를 유지하지만 새 시각 요소이므로 승인 대기. 솔루션영업은 검정/흰색 어느 하나도 전체 Gradient 전 구간을 일반 텍스트 기준으로 통과하지 않는다(검정 stop 최소 3.835:1).
• 큰 bold 텍스트 사용은 별도 대안이며 layout 영향을 확인하고 승인한 뒤 실제 geometry에서 다시 검사해야 한다.
• 허브: 흰 backing + 짙은 텍스트 또는 배경/크기 보완 승인 필요. 후보 수치와 actual 허브 적용은 구분했다.
• 의미 있는 연결선 #bac7d7 → #7b899d 후보: 실제 Storybook 배경 3.128:1, 흰 면 3.555:1, #f4f7fb 3.308:1. --hm-orgchart-stroke-default 보완 범위와 시각 의도 승인 후 적용할 수 있다. 적용하지 않았다.

근거: browser.json, contrast-pixels.json, contrast-last-branch.json, boundaries.json 및 대응 PNG.

Track C — Storybook: 변경 표시 범위 PASS

사용자용 메뉴 Logo / Department Colors / Position Summary / Affiliation Summary / Full Composition 5개 유지. 기존 내부 Story 8개 및 테스트 로직 유지.

• Logo: Figma 정식 Footer에서 확보한 7개 PNG(한맥·삼안·장헌·장헌산업·피티씨·한라·바론)와 ID 매핑 유지. 473×473 원본 SHA와 RGBA 투명성 유지, 수정·재제작·가상 대체 없음. 누락 Asset 0건. 원본 이미지 비율은 contain으로 보존했다.
• 로고 최소 수정: 이미지의 흰 CSS 배경을 transparent로 변경하고, 로고 정상일 때 fallback 글자가 투명 영역 뒤에 보이지 않도록 숨겼다. 이미지 실패 시 fallback을 다시 표시하며 관계사명 접근성 이름을 유지했다. 기존 실제 broken-image PASS를 재사용하고 이번에는 변경된 handler 표시만 검사했다.
• 한라처럼 가로 wordmark인 원본은 직원 16px mark에서 실제 ink 높이가 약 4px, Summary 28px에서는 약 7px라 작은 크기의 판독성 한계가 남는다. 원본 비율을 임의로 crop/recolor하지 않았다. 크기/여백 변경은 후속 디자인 검토 대상이다.
• Department Colors: 6개 조직명, 실제 HEX/CSS Variable, Gradient/Border, 원본 출처와 자체 디자인 구분, 실제 computed/model 대비·미승인 후보 표시 정상. 390px 줄바꿈 정상.
• Position Summary / Affiliation Summary: 두 Story에 가상 직원 자동 집계·운영 인원 아님 안내를 추가했다. Core selector/표/정책은 변경하지 않았다. 가상 raw total 41, 관계사 0명 세 항목 표시를 유지한다. 실제 인사 집계 정책 승인으로 간주하지 않는다.
• Full Composition: 리더·허브·6개 그룹과 부서/팀·직원 카드·직위 통계·관계사 통계·파견/휴직을 유지했다. Header·GNB·LNB·Dashboard Layout 없음. 390/768에서는 통계 아래 배치, 1280/1440에서는 오른쪽 통계 배치. 조직도 및 표의 내부 스크롤 유지, 변경으로 인한 새 겹침/페이지 overflow 없음.
• Position Summary 최초 390px PNG의 안내 첫 paint가 불완전해 그 화면만 다시 확인했다. DOM·최종 PNG에서 두 줄 전체 문장 정상. 원본 캡처를 보존하고 position-note-recheck.json과 storybook-position-summary-390-final.png를 최종 근거로 사용한다.
• HTML/React: 4개 폭의 computed 카드·로고 스타일 일치. 이미 촬영한 PNG를 비교한 결과 390/768/1280/1440 모두 픽셀 동일. 별도 React UI를 추가하지 않았다.

독립 API는 변경하지 않았다. OrgChartTree, PositionSummary, AffiliationSummary, StatusSummary의 기존 factory/React Wrapper/P1 독립 사용 PASS를 재사용한다. 두 Summary의 변경 Story 렌더링은 이번 브라우저 검사로 확인했다. 사용법은 기존 공개 컴포넌트·스타일 API를 유지한다.

확인된 Workdesk 차이는 유지했다: IS/디자인 하위 팀의 세로 배치, 추가 root 카드·ID/raw metadata·collapse control, 더 큰 전체 높이, 18행 상세 통계, 1440px Story host 제한과 마지막 가지 내부 스크롤, 파견/휴직의 after-tree 배치. 이는 이번 변경으로 생긴 회귀가 아니며 사용자가 예고한 별도 전체 디자인 작업에서 다룬다. 픽셀 완전 일치 PASS가 아니다.

근거: test-results/org-chart-quality/visual-review.json. Workdesk 최신 화면은 조직명/색/배치 참고로만 사용했고 실제 직원 개인정보·운영 인원수를 fixture에 복제하지 않았다. Figma Dev Mode 미확인 속성을 실측이라고 기재하지 않았다.

검증 및 재사용

이번에 실행:

• Core Typecheck: npm.cmd run typecheck:org-chart PASS.
• 변경 Story/preview source Typecheck: npm.cmd exec -- tsc -p tsconfig.app.json --noEmit PASS.
• Core Package Build: npm.cmd run build:org-chart PASS(ESM/IIFE/types/CSS).
• HTML demo prepare 및 React demo Vite Build PASS. React Wrapper 구현 변경 없음.
• Storybook production Build PASS. 기존 큰 chunk 경고가 있으며 이번 작업에서 배포 구조를 리팩터링하지 않았다.
• 신규 대비 unit 10/10 PASS: 수학/비반올림 경계/일반·큰 텍스트/Gradient 구간/unsupported NOT VERIFIED. 기존 unit output을 지우지 않는 별도 폴더로 실행.
• 변경 UI browser 62/62 PASS, console/runtime error 0. 5개 Story 390/1440 및 Full 768/1280, Theme 미연결 HTML/React 4개 폭 확인.
• Position 390 안내만 후속 PASS, 가려진 솔루션영업 제목 2곳 후속 대비 REVIEW. 정상 데이터/생명주기 검사를 반복하지 않았다.
• Guard 재현 8/8 PASS; 최종 관련 Guard 원본 FAIL(앞서 원인/범위 기록).
• 실제 텍스트 대비: 검증된 부분 PASS/REVIEW 구분, 가려지거나 모델 불일치한 부분 NOT VERIFIED 유지.
• git diff --check PASS. 운영 D:\디자인시스템\HMDesign은 읽기 전용 확인: main, 동일 HEAD, Working Tree clean. Commit/Push/Merge/새 브랜치/공통 코드 수정 없음.

재사용한 근거: 기존 Core 22/22, HTML 69/69, React 79/79, P1 selector 7/7, P1 browser의 성공 196건 및 console/menu 후속 4/4. 원본 기록은 P1 구현 보고와 test-results/org-chart-p1/에 유지한다. Data Source/validation/집계/JSON 갱신/lifecycle/API/Wrapper/원본 Story 로직이 변경되지 않아 전체 테스트를 다시 실행하지 않았다. 현재 검사는 변경된 스타일·표시·신규 대비 모델·관련 Guard 문제에 한정했다.

변경 파일 — 이번 품질 작업만

시작 706파일 SHA snapshot과 비교해 기존 파일 삭제 0건, 수정 7건, 신규 소스/검증 6건과 이 보고서 1건이다. 기존 package.json, package-lock.json 미커밋 변경, 원본 자산·7개 설계 문서·P1 보고/Story·Spike·공통 코드의 시작값은 보존했다.

수정:

1. packages/org-chart/src/core/affiliation-mark.ts — fallback span과 정상/오류 표시 연결.
2. packages/org-chart/src/core/department-colors.ts — 대비 정보와 미적용 비교 후보.
3. packages/org-chart/src/styles/employee-card.css — 로고 투명 배경 및 fallback 숨김.
4. packages/org-chart/src/styles/org-chart-content.css — Department Colors 비교 표시만.
5. packages/org-chart/src/styles/summary-sections.css — standalone 주석 정정만.
6. src/org-chart/core-component-preview.tsx — Department Colors resize 계산/cleanup.
7. src/org-chart/org-chart-p1.stories.tsx — 두 독립 Summary의 가상 데이터 안내.

신규:

8. packages/org-chart/src/core/contrast.ts — 내부 대비 모델(공개 API 추가 없음).
9. packages/org-chart/src/core/contrast.test.ts — 신규 모델 10개 검증.
10. examples/org-chart/verify-guard-p1.mjs — Guard 최소 오탐 재현.
11. examples/org-chart/verify-quality-p1.mjs — 변경 UI 62개 검사/PNG/값 수집.
12. examples/org-chart/audit-quality-pixels.py — PNG 읽기 전용 대비 감사.
13. examples/org-chart/verify-quality-boundaries.mjs — 실제 연결선/포커스 CSS 확인.
14. docs/org-chart/quality-review-p1.md — 이번 결과 기록.

test-results/org-chart-quality/에는 신규 증거, 실행 로그, PNG 및 baseline을 별도 보존했다. Build 산출물은 기존 생성 경로에서 갱신했다.

최종 판정 / 승인 / 후속

PARTIAL: 로고 표시·Department Colors 설명·가상 안내·변경 렌더링 보완은 PASS다. 실제 대비 부족과 공통 Guard 개선 승인이 남아 전체 P1을 PASS로 처리하지 않는다. 원본 Guard FAIL은 분석상 오탐으로 구분했지만 승인·수정 없이 PASS로 치환하지 않았다.

승인 대기: 디자인기획/솔루션영업/허브의 텍스트·backing·크기 선택, 의미 있는 연결선 대비 보완, 공통 Guard 제한적 추적 개선. 모두 미적용이다. Workdesk 전체 배치 수정은 사용자가 지정한 별도 Codex 작업으로 남긴다.

NOT VERIFIED: 전체 Heap/GC 회수, 전체 스크린리더, 미확인 Figma Dev Mode 속성, Workdesk 픽셀 완전 일치, 실제 HR API, 미승인 집계 정책, 무관한 Guard 항목, 지원하지 않거나 가려진 contrast probe, 모든 소비자 override의 접근성.

후속 P2: 전체 디자인 작업 결과의 확인, 승인된 대비 대안만 적용/부분 재검사, 작은 wordmark 크기 검토, 승인된 집계 정책·실제 API·전체 접근성·메모리 검증. Commit·Push·Merge는 수행하지 않았다.

완료 기록

Started At: 2026-10-12 11:55:44 KST. Completed At: 2026-10-12 12:25:20 KST(최종 검사 종료 시각). Actual Duration: 29분 36초. Estimated Duration: 45–90분. Variance: 하한 대비 −15분 24초 / 상한 대비 −60분 24초. 보고서 정리와 결과 표시 시간은 별도다.

최종 보존 근거: test-results/org-chart-quality/preservation.json — baseline 706개 중 수정 7개, 유지 699개, 삭제 0개, 신규 7개(보고서 포함), HEAD/main 동일, diff check 0. Preview: http://127.0.0.1:6027/?path=/story/orgchart--full-composition.