feat: integrate latest HMDesign design system updates

docs/guidelines/ai-implementation-details.md

@@ -9,7 +9,7 @@
 
 ## AI 화면 구현 Quick Start
 
-화면 구현 요청을 받으면 아래 순서를 그대로 따른다. 파일이나 API의 존재를 확인할 수 없으면 추측하지 말고 미확인으로 기록한다.
+신규 React 화면은 [선택·완료 계약](./ai-screen-contract.md)을 먼저 따른다. 아래는 Runtime adapter와 기존 소비 경로의 상세 참고다. 파일이나 API의 존재를 확인할 수 없으면 추측하지 말고 미확인으로 기록한다.
 
 1. **프로젝트 구조와 Runtime 확인**: 제공된 파일 범위를 살펴보고 `REACT_VITE | STATIC_HTML | VANILLA_WEB | OTHER_RUNTIME` 중 대상을 정한다. Component·Pattern 파일이 실제 범위에 있는지 확인한다.
 2. **Component 검색**: `packages/ui/src/components/ui/`와 `packages/ui/src/index.ts`에서 공개 Component·Props를 찾고, `docs/components/<component>.md`를 확인한다. 기존 공개 Component를 우선 사용한다.
@@ -27,6 +27,10 @@
 
 **Story 구분**: 운영 기준은 대표 `All` Story이고 `verification`·Compatibility·Fixture Story는 운영 예제가 아니다. Storybook 문서 화면은 `StoryPage` 공통 Inner를 사용하며, 이는 Storybook 표현용으로 `@hm-design/ui` 공개 API가 아니다.
 
+**선택·범위 계약**: 구현 전에 요구사항·필수 동작·완료 조건을 기록하고 기능별 Pattern 후보와 실제 선택/미사용 이유를 남긴다. 목록 검색은 Table 유무와 관계없이 [FilterBar](../patterns/filter-bar.md)를 먼저 검토한다. Field Label은 [공개 Label](../components/label.md#5-api)과 control ID/접근성 이름을 연결한다. 레이아웃·콘텐츠 HTML과 HM 미지원 사용처는 허용하며 native 위젯/label 예외의 구체적인 이유를 기록한다. 기존 공개 Component·Pattern으로 해결되지 않는 기능은 지원 한계와 최소 대안을 보고하고, 요청 없는 Component/API/Token 확장은 하지 않는다. CSV·다운로드·외부 API·추가 메뉴·Navigation 등 요청 밖 기능은 구현하지 않고 제안으로만 보고한다. Story의 fixture·부가 액션은 필수 구현 목록이 아니다.
+
+**최종 확인**: 390/768/1280/1440px에서 페이지 overflow·줄바꿈·Navigation 및 Dashboard 960px 내부 스크롤을 확인한다. 접근성 이름·Label 연결, 키보드 순서·focus 복귀, disabled/readOnly, 요구된 상호작용과 실제 액션 목록을 대조한다. Guard 정적 결과와 브라우저 증거를 구분하며 실행하지 않은 검사·실제 스크린리더 발화 등은 `NOT VERIFIED`로 보고한다.
+
 **화면 생성 시 필수 확인**: Navigation을 지정받으면 아래 모드별 정책에 따라 기존 공식 Component를 적용하고, 미지정이면 기존 모드 선택 규칙을 따르며 그 근거를 기록한다([선택 기준](./navigation-single-mode.md#선택-근거)). LNB ONLY의 정상적인 공식 LNB 생성은 Sidebar 금지 대상에서 명시적으로 제외한다. GNB ONLY의 Sidebar·GNB Sidebar Composition 또는 DASHBOARD ONLY의 Sidebar/LNB가 요청되면 금지 규칙을 안내하고 해당 기능을 구현하지 않으며, 대체 Navigation을 임의로 추가하지 않는다. GNB는 Desktop 메뉴와 `GNBMobileMenu`를 함께 구성한다([GNB 모바일](../patterns/gnb.md#8-desktop--mobile)). Dashboard 운영 화면에는 Sidebar를 생성하지 않는다. `DashboardSidebar` 공개 Export와 선택적 `sidebar` slot은 기존 호환성·검증용이며 운영 허용을 뜻하지 않는다. Dashboard 상태는 Theme 다음에 공개 Status CSS를 로드하고 기존 Badge mapping을 소비한다([상태 예제](../patterns/dashboard-layout.md#dashboard-업무-상태-공통-계약)). FilterBar의 입력 조건과 조회 적용 조건·초기화 책임을 구분한다([조회 예제](../patterns/filter-bar.md#61-조회-버튼으로-적용하는-소비-예제)). `REACT_VITE` 독립 화면은 bootstrap에서 기존 앱 CSS entry(`@/index.css` → `@/hm-theme.css` → 필요 시 공개 상태 CSS)를 로드하며, `@hm-design/ui/tailwind.css`만 단독 import하지 않는다. 빌드 후 `.flex`, `.grid` 등 대표 utility의 생성·실제 적용과 캡처 레이아웃을 확인하고, 빌드 성공만으로 화면 검증을 PASS 처리하지 않는다. React 소비자는 Tailwind 검색 범위와 HM package source를 확인하고([Tailwind](./runtime-portability.md#21-tailwind-v4-소비자-검색-범위)), 폰트·Asset 경로는 실행 위치별로 확인한다([Asset](./runtime-portability.md#4-asset과-실행-위치)).
 
 ## AI Implementation Defaults
@@ -35,7 +39,7 @@
 
 - 구현 전에 `STORYBOOK_ONLY | PRODUCTION_UI | BOTH` 중 변경 범위를 정한다.
 - 기존 Component와 유사 대표 Story를 먼저 검색한다. `packages/ui`, `src/components`, `src/patterns`, `src/center`, 기존 Storybook stories와 shared helpers를 확인하고 도메인에 맞는 구현을 재사용한다.
-- 재사용 순서: 기존 HM Component → 기존 Variant / Prop → 기존 Composition → shadcn → Radix Primitive → 최소 Custom. 새 Component는 기존 Component·Composition으로 표현 불가능하고 Variant 확장이 부적절하며 shadcn/Radix 조합도 어려운 경우에만 만든다. 재사용 불가 사유와 최소 추가 범위를 설명한다.
+- 재사용 순서: 기존 HM Pattern → 기존 HM Component → 기존 Variant / Prop → 기존 Composition. 공개 API가 지원하지 않는 경우에만 근거를 기록하고 shadcn → Radix Primitive → 최소 Custom을 검토한다. 새 Component는 기존 Component·Composition으로 표현 불가능하고 Variant 확장이 부적절하며 shadcn/Radix 조합도 어려운 경우에만 만든다. 재사용 불가 사유와 최소 추가 범위를 설명한다.
 - Storybook은 구현 Reference Catalog다. 대표/PRIMARY Story의 시각 언어와 공통 상태 mapping을 재사용하고 검증 전용 Story를 운영 예제로 삼지 않는다. 신규 업무 화면의 등록 대상이 아니며, 생성 결과는 별도 React 화면·독립 미리보기로 제공한다.
 - Theme은 구현 시작부터 적용한다. 기존 Semantic Token → 해당 Component Token → 기존 CSS Variable을 먼저 확인하고, 없을 때만 필요한 최소 Semantic 확장을 검토한다. 기존 Token이 있는 색상·spacing·값을 하드코딩하거나 같은 Token을 여러 파일에 중복 정의하지 않는다.
 - Theme 사용은 별도 승인 없이 기본 적용한다. Theme Source/값 수정은 명시적 필요성과 영향 범위를 확인한다. `themes/*.json` → Runtime Loader → CSS Custom Properties → Semantic → Component Mapping과 Primary / On Accent의 독립 fallback을 유지한다.
@@ -44,7 +48,7 @@
 - package exports, public props/types, package entry, Story ID, `meta.title`을 불필요하게 변경하지 않는다. 필요한 변경은 소비처·호환성 영향을 먼저 확인한다. Storybook 표현 문제와 Production 동작 문제는 해당 범위에서 해결한다.
 - Badge/Button/FilterBar를 재사용하더라도 동일한 상태 ID·라벨·필터 매칭이 반복되면 화면별 helper로 남기지 말고 Runtime-neutral 상태 계약을 먼저 검토한다. 계약은 React 구현과 분리하고 `data-status`, 독립 flag attribute, `aria-pressed` 등 다른 Runtime이 재현할 수 있는 상태 vocabulary를 정의한다.
 - 명시적 실험·Theme 미적용 prototype·외부 디자인 완전 재현·독립 POC만 별도 격리 범위에서 예외를 검토한다. Navigation 혼합은 아래 단일 모드 정책의 별도 기준을 따른다.
-- Button은 `brand | solid | outline`의 사용 위치와 세트 규칙을 `docs/components/button.md` 기준으로 따른다: 실제 화면 Brand 최대 1개·팝업 Brand 금지, 일반 확인/작성은 Solid 세트, 삭제 확인·행/반복 작업은 Outline 세트이며 세트의 appearance와 size를 통일한다. Runtime 변환은 `docs/guidelines/runtime-portability.md`의 DOM/Theme/keyboard 계약을 함께 보존한다.
+- Button은 `brand | solid | outline`의 사용 위치와 세트 규칙을 `docs/components/button.md` 기준으로 따른다: 실제 화면 Brand 최대 1개·팝업 Brand 금지, 일반 확인/작성은 Solid 세트, 삭제 확인은 Solid 세트, 일반 화면의 행/반복·보조 작업은 Outline을 사용한다. 결정 세트의 appearance·size를 통일하며 검색은 조회 Solid Green / 초기화 Outline Gray 예외다. Runtime 변환은 `docs/guidelines/runtime-portability.md`의 DOM/Theme/keyboard 계약을 함께 보존한다.
 - Dashboard 운영 화면은 전용 Header(48px)·업무 상태 필터와 Content로 구성하며 Sidebar 사용을 금지한다. Dashboard 대표 `Patterns/Layout/Dashboard → Dashboard` Story와 `docs/patterns/dashboard-layout.md`를 기준으로 하며, Header를 GNB로 대체하거나 일반 LNB/GNB를 함께 넣지 않는다. Sidebar verification Story는 신규 운영 화면의 Reference가 아니다.
 - Dashboard 및 DataTable은 기존 Pattern 구조를 우선한다. `Data Table` 대표 Story를 기준으로 하고 숨김 `With Filter Bar`는 verification 용도다.
 - Story의 fixture나 장식은 Component API나 Production 규칙과 구분한다. 대표 Story와 공개 API·사용 문서를 함께 확인한다.