feat: integrate latest HMDesign design system updates

README.md

@@ -6,46 +6,53 @@ React + TypeScript + Vite와 shadcn/Radix 기반 HM 디자인 시스템입니다
 
 **ONE PAGE = ONE NAVIGATION MODE.** GNB ONLY / LNB ONLY / DASHBOARD ONLY 중 하나를 선택한다. 모바일도 선택한 Navigation 자체의 Responsive Variant를 사용한다. 이 정책은 AI 코드 생성·제안, 신규 페이지, 기존 화면 수정, 프로토타입, Storybook, Production에 동일하게 적용한다. [상세 정책](docs/guidelines/navigation-single-mode.md), [AI 작업 지침](AGENTS.md).
 
-새 화면을 구현하는 AI는 [AI 화면 구현 Quick Start](AGENTS.md#ai-화면-구현-quick-start)의 7단계를 순서대로 따른다. 세부 Component·Pattern·Theme·Runtime 계약과 대표 Story 경로도 그 지침에서 연결한다.
+새 화면을 구현하는 AI는 [AI 화면 구현 필수 규칙](AGENTS.md)을 따른다. 세부 Component·Pattern·Theme·Runtime 계약과 대표 Story 경로도 그 지침에서 연결한다.
 
 ## Storybook Reference와 화면 생성
 
+퍼블리셔·개발자는 [화면 조합 확인](docs/guidelines/개발-적용-가이드.md#8-publisher--developer-화면-조합-확인)과 [Tabs의 Card/페이지 Usage](docs/components/tabs.md#16-publisher--developer-조합-안내-2026-10-09)를 참고한다. 사전공유 자료의 반영·보류 범위는 [2026-10-09 통합 보고](docs/guidelines/publisher-integration-2026-10-09.md)에 기록한다. 디자인 방향 승인과 공통 Theme·외부 소비 화면 적용 완료를 구분한다.
+
 Storybook은 기존 HM Component·Pattern·Theme·Variant·State·Interaction을 확인하는 Reference 환경이다. 일반적인 업무 화면 생성에서는 신규 화면을 Storybook Story나 사이드바에 등록하지 않고, 대표 Story를 교체하지 않으며, Storybook 실행을 필수 미리보기 경로로 요구하지 않는다. AI는 별도의 React 화면을 만들고 화면별 빌드·필요한 검증과 독립 미리보기를 제공한다. H-2 또는 유사 자동화가 사용 가능한 경우에는 `preview.html`·desktop/mobile 이미지 같은 독립 미리보기 산출에만 사용하며 Storybook 등록 기능으로 취급하지 않는다. Storybook 전용 helper/CSS는 운영 화면에 사용하지 않는다. Component·Pattern 추가/수정, 대표/Verification Story 작성 또는 Storybook Reference 개선을 명시적으로 요청한 경우에만 Storybook을 수정한다.
 
-## 설치 없는 테스트 배포
+## Git Clone 설치·실행 (현재 테스트 공유 기준)
 
-현재 검증된 테스트 배포 기준은 `HMDesignTest-Portable-Test-r3.zip`입니다. 사전 빌드된 Storybook과 Windows x64 포터블 Node를 포함하며 정확한 포함 범위는 r3의 BUILD-INFO·Inventory를 기준으로 확인합니다. `HMDesignTest-Portable-Test-r2.zip`과 `HMDesignTest-Portable-Test.zip`은 이전 스냅샷 기록으로 보존하며 현재 기준이 아닙니다. 포터블 ZIP의 기본 포트는 6007이고 충돌 시 자동으로 다른 포트를 사용합니다. 개발 저장소 Storybook의 6024와는 별개입니다. 테스트 사용자는 ZIP 해제 → `HMDesignTest/start-preview.bat` 더블클릭 → 표시된 로컬 URL 열기만 수행합니다. 별도 Node/npm 설치, npm 명령, Git 작업 또는 운영 업로드는 필요 없습니다. [실행 및 포함 범위](docs/guidelines/portable-test-distribution.md).
+공식 소스 저장소는 [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 소스 다운로드 / Windows Storybook 실행
+현재 검증 범위와 남은 제한은 [2026-10-10 잔여 이슈 회귀 보고](docs/guidelines/publisher-validation-2026-10-10.md)를 확인합니다.
 
-정식 저장소 `https://gitea.hmac.kr/b25027/HMDesign.git`를 Git Clone하거나 Gitea 소스 ZIP을 다운로드해 전체 압축을 풉니다. 이 방식은 포터블 ZIP과 달리 PC에 Node.js/npm이 필요합니다. 현재 lockfile의 요구 조건은 **Node.js 20.x의 20.19 이상 또는 22.12 이상**이며 Node.js 21.x는 지원하지 않습니다.
+후속 Select 비교 화면 넘침 수정, Guard 46개 회귀 테스트, 개발 의존성 분석과 접근성 제한은 [2026-10-10 최종 안정화 보고](docs/guidelines/publisher-stabilization-2026-10-10.md)를 확인합니다. 이전 보고서는 당시 기록으로 보존합니다.
 
-프로젝트 루트의 `start-storybook.bat`을 더블클릭하세요. 의존성이 없으면 `npm ci`를 자동 실행하고, workspace 패키지 산출물이 없으면 기존 `npm run build:packages`를 실행합니다. 이후 기존 `npm run storybook`으로 서버를 시작하며, HMDesign Storybook의 Story index와 preview HTTP 응답이 준비된 뒤 기본 브라우저에서 **http://localhost:6024/** 를 엽니다. 이미 준비된 HMDesign Storybook이 있으면 서버를 추가 실행하지 않고 기존 주소를 엽니다. 서버 실행 창의 `Ctrl+C`로 종료합니다.
+이후 Guard CSS Intent·동적 Token 확장(75개 + 증거 연결 20개 + 요구사항 연결 5개)은 [Guard 보고](docs/reports/guard-css-intent-dynamic-token-2026-10-10.md), Combobox·GNB/LNB 접근성 보완은 [접근성 보고](docs/reports/accessibility-residual-2026-10-10.md)를 따릅니다. 현재 [Gitea 이전 전 최종 정합성 확인](docs/reports/pre-gitea-finalization-2026-10-11.md)과 [2026-10-12 이전 준비](docs/guidelines/gitea-source-transfer-preparation-2026-10-11.md)에는 재사용 근거와 잔여 미검증을 구분합니다. 공식 이전의 Commit·Push는 최종 검토와 별도 승인 후 수행합니다. 인용한 과거 보고서는 당시 기록으로 보존합니다.
 
-실행 파일 위치를 기준으로 동작하므로 한글·공백 폴더, 다른 드라이브 및 Git이 없는 ZIP 환경에서도 사용할 수 있습니다. 최초 설치에는 npm 레지스트리 접속이 필요합니다. 포트 6024를 다른 프로그램이 사용하거나 아직 준비되지 않은 서버가 점유하면 포트를 바꾸지 않고 오류를 표시합니다. 해당 프로그램을 종료하거나 기존 서버 준비를 기다린 뒤 다시 실행하세요. 오류가 발생한 경우에만 창을 유지합니다. 출력된 오류, Node.js/npm의 PATH와 버전, 전체 소스 압축 해제 여부 및 네트워크를 확인하세요. 의존성이 불완전하면 프로젝트 루트에서 `npm ci`를 직접 실행하고 다시 시도합니다.
-
-## 오전 소스 ZIP / 개발자 전용 절차 (AI 참조용)
-
-오전 소스 배포의 역사적 기준은 `HMDesignTest.zip`입니다. 당시 전달 구성에서는 `.git` 디렉터리와 Git 이력·원격 연결 정보를 제외하고 `.gitignore`와 소스·Storybook·문서·패키지 설정을 유지했습니다. 이 절의 수량·실행 조건은 오전 ZIP에 대한 기록이며 현재 포터블 r3의 포함 범위는 위 절과 BUILD-INFO를 기준으로 확인합니다. `HMDesignSystem-test-2026-10-08-r4.zip`, `HMDesignSystem-Distribution-Test-v2.zip`, `HMDesignSystem-AI-Reference-Test.zip`은 오전 기준을 대체하지 않습니다.
-
-기준 ZIP에는 UI·Pattern·CENTER Graphic, 공개 API, Theme, Storybook 소스, 문서, 예제, 패키지 dist, lockfile 및 폰트가 포함됩니다. `node_modules`와 `storybook-static`은 포함되지 않으므로 ZIP 단독으로 정적 Storybook을 바로 열 수는 없습니다.
-
-오전 소스 ZIP을 개발 환경으로 실행할 경우 Node.js 20.20.1 / npm 10.8.2 환경의 프로젝트 루트에서 다음을 실행합니다.
+Node.js는 lockfile의 `^20.19.0 || >=22.12.0` 조건을 충족해야 합니다(Node 21 제외). 이번 재현 환경은 **Node 20.20.1 / npm 10.8.2**입니다. Node 설치 시 제공되는 npm과 PATH를 확인하고, 재현 시에는 검증한 버전을 사용합니다. 최초 설치에는 공식 Gitea와 npm 레지스트리 접근이 필요합니다.
 
 ```powershell
-# ZIP을 풀고 프로젝트 루트에서 실행
+git clone https://gitea.hmac.kr/b25027/HMDesign.git
+cd HMDesign
+node --version
+npm --version
 npm ci
 npm run build:packages
-npm run dev
 npm run storybook
 ```
 
-HM 패키지는 ZIP 안의 workspace를 사용하므로 HM Registry 설치가 필요하지 않습니다. `npm ci`로 의존성을 복원하고 `npm run build:packages`로 패키지를 빌드한 뒤 앱과 Storybook을 시작합니다. 정적 Storybook이 필요하면 `npm run build-storybook`을 실행합니다. 이 문서는 배포본의 새 환경 실행 결과를 보증하지 않습니다.
+브라우저에서 **http://localhost:6024/** 를 엽니다. Component는 Components, 업무/Layout Pattern은 Patterns, 브랜드 컬러·Typography는 Foundation에서 확인합니다. 내부 Theme 확인은 `?path=/story/theme-runtime-contract--comparison`, Designer는 `?path=/story/theme-designer-playground--editor`를 사용합니다. 확정 컬러로 검수하며 Designer 임시 편집은 해당 Story 안에서만 적용됩니다. [Designer 사용법](docs/guidelines/designer-theme-guide.md).
 
-- Storybook: 기준 ZIP의 `npm run storybook`은 기본 포트 6007입니다. 다른 포트는 `npm run storybook -- --port <available-port>`로 지정할 수 있습니다.
-- ZIP 확인 빌드: `npm run build`, `npm run build-storybook`
+Windows에서는 기존 `start-storybook.bat`도 사용할 수 있습니다. 의존성이 없으면 `npm ci`, package 산출물이 없으면 `npm run build:packages`를 수행하고 Story index·preview 응답 준비 후 6024 주소를 엽니다. 포트 충돌 시 오류를 표시합니다. 서버 종료는 실행 터미널의 Ctrl+C입니다.
 
-현재 개발 저장소는 ZIP과 별개로 `npm run storybook` 기본 포트가 6024이며(포터블 ZIP 6007과 통일하지 않음), `npm run build:dashboard-export` → `dist-dashboard/index.html`도 제공합니다. `dist-dashboard`는 H-1(독립 단일 HTML 미리보기 POC, PASS)의 성공 산출물과 동일하지 않으며 ZIP에도 있다고 가정하지 않습니다. H-2(AI 생성 화면의 자동 빌드·캡처·검증)는 Storybook 배포와 별도 기능이며 구현 완료 여부는 현재 파일과 별도 작업 결과로 확인합니다.
+정적 Storybook 빌드는 `npm run build-storybook`, 앱 빌드는 `npm run build`, 타입 확인은 `npm run typecheck`입니다. 명령은 루트 package.json의 현재 scripts를 기준으로 합니다.
+
+## 기존 Component 기반 새 React 화면
+
+```powershell
+npm run dev:publisher-example
+```
+
+별도 터미널에서 실행하고 출력된 Vite 주소(기본 5173)를 엽니다. [예제](examples/publisher-list/README.md)는 실제 공개 HM React Component로 GNB·모바일 메뉴·PageHeader·Card·FilterBar·Select·Button·DataTable을 조합합니다. 새 폴더에 복사한 뒤 title/data/columns를 수정하고 bootstrap의 CSS 연결을 유지합니다. 신규 업무 화면은 Storybook에 등록하지 않습니다. 제작·빌드·Guard·브라우저 확인 절차는 [Git 공유 안내](docs/guidelines/publisher-distribution-guide.md)에 있습니다.
+
+## 과거 배포 기록
+
+과거 `HMDesignTest.zip`, 포터블 r1/r2/r3 및 `HMDesign-Publisher-2026-10-10.zip`은 당시 스냅샷 기록입니다. 현재 Git Clone에는 ZIP·포터블 Node·사전 빌드 Storybook·로컬 검증 증거가 포함되지 않습니다. 이번 공유를 위해 ZIP을 새로 생성하지 않습니다. 당시 실행 조건과 검증 결과는 [과거 포터블 안내](docs/guidelines/portable-test-distribution.md)와 [추가 수정 보고서](docs/guidelines/publisher-additional-review-2026-10-10.md)에 보존합니다. 과거 ZIP의 6007과 현재 개발 Storybook의 6024를 구분합니다.
 
 ## 사용 (workspace)
 
@@ -67,11 +74,11 @@ import { DataTable, FilterBar, useDataTable } from "@hm-design/ui" // Patterns:
 
 화면 생성 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`. 두 패키지는 `private: false`이며 ESM JS·타입 선언·CSS를 `dist`에서 export합니다. `npm run build:packages`로 재빌드할 수 있고, Registry publish 이력은 이번 ZIP 검증 범위에 포함하지 않습니다.
+루트 `package.json`의 `workspaces`(`packages/*`)로 연결됩니다. 확인: `npm run typecheck`, `npm run build`. 두 패키지는 `private: false`이며 ESM JS·타입 선언·CSS를 `dist`에서 export합니다. `npm run build:packages`로 재빌드할 수 있고, Registry publish 이력은 Git 기반 테스트 공유의 검증 범위에 포함하지 않습니다.
 
 ## 파일 위치
 
-아래 경로는 저장소 루트(압축 해제 시 `HMDesignTest/`) 기준입니다. `packages/ui/` 하위 경로도 전체 상대경로로 표기합니다.
+아래 경로는 Git 저장소 루트 기준입니다. `packages/ui/` 하위 경로도 전체 상대경로로 표기합니다.
 
 - `packages/ui/` (`@hm-design/ui`): UI Component·업무/Layout Pattern과 HM Theme
   - `packages/ui/src/components/ui/`: shadcn 기반 컴포넌트, `packages/ui/src/patterns/`: 조합 Pattern(Data Table, Filter Bar 등), `packages/ui/src/index.ts`: 공개 export
@@ -92,11 +99,11 @@ import { DataTable, FilterBar, useDataTable } from "@hm-design/ui" // Patterns:
 - `docs/components/`: 컴포넌트별 현재 구현 기준 문서
 - `public/fonts/`: 기존 자료의 Noto Sans KR 글꼴과 라이선스
 - `docs/guidelines/`: 프로젝트 지침·구현 원칙·Theme Token·적용/배포 가이드
-- 로컬 검증·감사·진단 자료는 테스트 ZIP에서 제외합니다.
+- 로컬 검증·감사·진단 자료는 Git에서 제외합니다. 과거 증거 경로는 로컬 보관 기록이며 Clone에서 열 수 있는 링크가 아닙니다.
 
 ## 참고 범위
 
-초기 디자인의 색상, Typography, Radius와 Button·Input·Select·Dialog에는 외부 ui_viz Reference를 참고했습니다. 이 Reference는 ZIP에 포함되지 않으며 실행에 필요하지 않습니다. 현재 Source of Truth는 HM Component/Pattern 구현, 대표 Storybook Story와 아래 공식 정책 문서입니다.
+초기 디자인의 색상, Typography, Radius와 Button·Input·Select·Dialog에는 외부 ui_viz Reference를 참고했습니다. 이 Reference는 Git 공유에 포함되지 않으며 실행에 필요하지 않습니다. 현재 Source of Truth는 HM Component/Pattern 구현, 대표 Storybook Story와 아래 공식 정책 문서입니다.
 
 HM Default 컬러의 운영 원본은 `themes/default.json`이며 생성한 CSS preset은 최초 렌더와 네트워크 실패 시 package fallback입니다. 외부 Theme도 같은 공개 계약을 사용합니다. Active와 Focus는 독립 Semantic이고 Global override와 독립 Scoped override를 지원합니다. `Theme/Designer Playground/Editor`에서 JSON URL/파일 Preview와 컬러 편집·Reset·Export/Import를 지원합니다. Portal은 실제 DOM scope를 따릅니다.
 
@@ -117,6 +124,6 @@ Component Mapping은 Semantic/Theme palette를 참조하며 기본 API로 HM 스
 
 ## Package Registry / Publish (별도 내부 운영 정보)
 
-패키지 build와 Registry publish는 별도 단계입니다. Registry 설치·publish·실제 CDN 운영은 이번 테스트 ZIP의 실행 조건이나 검증 범위가 아닙니다. 서비스 배포·버전·캐시·롤백 계획은 [운영/배포 가이드](docs/guidelines/운영-배포-가이드.md)를 따릅니다.
+패키지 build와 Registry publish는 별도 단계입니다. Registry 설치·publish·실제 CDN 운영은 Git 기반 테스트 공유의 실행 조건이나 검증 범위가 아닙니다. 서비스 배포·버전·캐시·롤백 계획은 [운영/배포 가이드](docs/guidelines/운영-배포-가이드.md)를 따릅니다.
 
 CENTER Graphic은 현재 내부 테스트/검토 목적 범위에서 제공합니다. 외부 공개 또는 사외 배포 전 별도 License 확정이 필요합니다. 임의의 오픈소스 License를 부여하지 않습니다.