29 lines
6.7 KiB
Markdown
29 lines
6.7 KiB
Markdown
# HMDesign AI 화면 구현 — 필수 규칙
|
|
|
|
> 기준 우선순위: 2026-10-10 추가 수정 요청의 확정 사항 → 충돌하지 않는 D-01/D-02 → 현재 HM Component/Pattern/Theme → 현재 Storybook/구현 → 과거 문서. [현재 추가 수정 기준](docs/guidelines/publisher-additional-review-2026-10-10.md). 미확정 값은 임의 확정하지 않으며 과거 검증 기록은 보존합니다.
|
|
|
|
이 파일을 먼저 읽고 필요한 항목만 탐색한다. 전체 문서·전체 소스·전체 Storybook을 반복해서 읽지 않는다.
|
|
|
|
1. 범위 `STORYBOOK_ONLY | PRODUCTION_UI | BOTH`, Runtime, 요구사항·필수 동작·완료 조건을 확인한다. 신규 AI 업무 화면은 실제 HM React 컴포넌트를 사용한다. 명시적 다른 Runtime adapter는 [상세 계약](docs/guidelines/runtime-portability.md)을 따른다.
|
|
2. [기능별 선택·완료 계약](docs/guidelines/ai-screen-contract.md) → [Component / Pattern 인덱스](docs/guidelines/component-pattern-reference.md) → 선택한 문서·대표 All Story·필요한 Props 순으로 읽는다. Import는 `@hm-design/ui` 공개 API가 기본이다. 의존성은 package.json의 exports/types와 실제 파일 목록을 확인하며 내부 src/dist 경로를 추측하지 않는다. verification Story는 운영 기준이 아니다.
|
|
3. 요구 기능에 맞는 기존 Pattern을 먼저 확인한 뒤 기존 Component → Variant/Prop → Composition 순으로 재사용한다. 목록 검색은 [FilterBar](docs/patterns/filter-bar.md)를 Table 유무와 관계없이 검토한다. 미사용 시 요구사항과 맞지 않는 API·구조 제약을 기록하며 강제하지 않는다. 기본 HTML·임의 CSS·`data-slot`으로 HM을 모방하지 않는다. 재사용은 import가 아닌 실제 렌더링으로 확인한다.
|
|
4. 기존 Theme/Semantic Token의 실제 선언을 확인한다. 변수 이름을 추측하거나 없는 Token을 fallback 색으로 감추지 않는다. React CSS entry는 `index.css → hm-theme.css` 및 필요 시 공개 status CSS를 연결한다. [Runtime Theme](docs/guidelines/runtime-theme.md), [Tailwind/Asset 계약](docs/guidelines/runtime-portability.md)은 관련 변경 때만 읽는다.
|
|
5. 페이지 Navigation은 GNB/LNB/DASHBOARD 중 하나다. 공식 LNB ONLY는 허용한다. 신규 GNB ONLY·DASHBOARD ONLY의 Sidebar는 금지한다. GNB는 GNBMobileMenu도 구성한다. Dashboard는 전용 48px Header와 최소 폭 960px·내부 스크롤을 유지한다. 미지정 시 [선택 근거](docs/guidelines/navigation-single-mode.md#선택-근거)를 기록한다.
|
|
6. Storybook은 참조 전용이다. 신규 업무 화면을 Story로 등록하거나 대표 Story를 교체하지 않는다. 독립 미리보기 HTML은 실제 React bootstrap을 실행해야 한다. 별도 HTML 모방 화면·이미지를 실제 React 결과로 제출하지 않는다.
|
|
7. 완료 후 Guard를 1회 실행한다: `node scripts/ai-generation-guard.mjs --target <앱> --scope FULL_SCREEN|PARTIAL`. Navigation 재사용 시 `--mode GNB_ONLY|LNB_ONLY|DASHBOARD_ONLY`, PARTIAL은 `--files <수정 파일,...>`을 전달한다. 최종 제출 경로 확인은 같은 실행에 `--result <실제 React HTML 또는 bootstrap>`을 추가한다.
|
|
8. FAIL만 수정하고 수정 범위만 PARTIAL 재검사한다. 정상 검사는 반복하지 않는다. Guard `staticStatus`는 정적 계약, 원본 `status`는 미검증을 포함한다. 실제 React 빌드·브라우저 결과는 [별도 증거 연결](docs/guidelines/ai-generation-guard.md#runtime-증거-연결)로 기록한다. 원본 미검증을 덮어쓰지 않는다.
|
|
CSS 검사는 `styleEvidence`/결합 `styleVerification`의 STATIC·RUNTIME·DESIGN_INTENT·FINAL을 함께 보고한다. HM Component의 HEX/RGB/HSL·Spacing/Radius 하드코드 override는 STYLE-001 FAIL이며 일반 콘텐츠 CSS는 일괄 금지하지 않는다. 동적 Token의 유한 후보는 모두 선언을 확인하고 외부 입력·Props·미해석 className/style은 위치별 Runtime 근거 없이는 NOT VERIFIED다. 문서 recipe나 computed PASS는 디자인 의도 승인이 아니다. [검사 범위와 증거 형식](docs/guidelines/ai-generation-guard.md#css-intent와-동적-token-검사-2026-10-10)을 따른다.
|
|
9. Field Label은 공개 [Label](docs/components/label.md#5-api)과 실제 control ID/접근성 이름을 연결한다. 레이아웃·콘텐츠용 HTML은 허용하며 HM이 지원하지 않는 native control/label은 이유를 기록한다. 무조건적인 native HTML 금지는 적용하지 않는다.
|
|
10. 요구사항에 없는 CSV·다운로드·외부 API·추가 메뉴·Navigation은 구현하지 않고 제안으로만 보고한다. Story의 예제 기능은 필수 요구사항이 아니다. Component·Pattern·Theme·대표 Story·공개 API를 요청 없이 변경하지 않는다.
|
|
11. 390/768/1280/1440px에서 overflow·줄바꿈·Navigation을 확인한다(Dashboard는 960px 내부 스크롤). 숨김 absolute 알림의 위치 기준과 문서/내부 scrollHeight·clientHeight, ID의 한 줄 식별 가능성도 확인한다. Label/접근성 이름, 키보드·focus 복귀, disabled/readOnly, 핵심 상호작용을 확인한다. 결과는 실제 사용 요소·Pattern 선택/미사용 이유·Navigation·검증·미검증으로 보고하며 확인하지 않은 항목은 `NOT VERIFIED`다.
|
|
|
|
필요할 때만 [보존된 상세 지침](docs/guidelines/ai-implementation-details.md)을 읽는다. 신규 화면에는 위 필수 규칙이 우선한다.
|
|
|
|
## 공식 작업 경로와 Git 정책 — 2026-10-11 사용자 확정
|
|
|
|
- HMDesign 실제 수정은 `D:\디자인시스템\HMDesign-Gitea-Transfer`에서 진행한다. 시작 전 절대경로·`main` 브랜치·공식 origin `https://gitea.hmac.kr/b25027/HMDesign.git`·최신 원격 HEAD·Working Tree·기존 미커밋 변경을 확인한다.
|
|
- 퍼블리셔 요청에 필요한 부분만 수정하고 기존 Component·Pattern·Theme·Storybook을 보존한다. 변경 영향과 관련 MD/Storybook 정합성을 검증하고 유효한 기존 정상 검증은 불필요하게 반복하지 않는다.
|
|
- 필수 검증을 통과하면 관련 파일만 Stage하고 Staged Diff를 검토한 뒤 Commit·공식 Gitea `main` 일반 Push를 수행한다. 작업별 사용자의 명시적 Commit/Push 보류 지시가 있으면 그 지시를 우선한다.
|
|
- Commit/Push 직전에 원격 `main`을 다시 확인한다. 시작 기준 이후 원격이 변경됐거나 중요한 충돌이 있으면 자동으로 덮어쓰지 않고 중단한다. 완료 후 Local/Remote SHA와 Working Tree를 확인한다.
|
|
- GitHub 이전 원본 폴더·remote에는 수정/Push하지 않는다. Force Push·Reset·Clean·기존 이력 삭제·백업 브랜치 변경·무관한 파일 Stage를 금지한다.
|