---
name: ui_layout_image
description: UI 소스코드(예 C# WPF XAML, WinForms, Qt, HTML/CSS, Android/Flutter)를 읽어 화면의 레이아웃 구조를 분석하고, 스크린샷 없이 그리드/컨테이너 구조를 그대로 도식(wireframe mockup) 이미지로 생성해 저장한다. 필요 시 PPT/매뉴얼에 삽입. "화면 구성 이미지로 만들어줘", "XAML 보고 레이아웃 그려줘", "코드 보고 화면 도식/목업 만들어 매뉴얼에 넣어줘", "스크린샷 말고 코드로 화면 그려줘"(**`matplotlib` 필요 — 미설치면 설치 안내 후 중단**), 그리고 후속 표현("다시 그려줘", "이미지만 재생성", "그 화면만 다시") 시 사용. **대상 화면·소스가 명시되지 않으면 기동하지 않고 되묻는다** — 이 스킬은 하네스에서 유일하게 원본 문서를 직접 수정하므로 오발동 비용이 크다. 맨손 "업데이트"·"다시 실행"만으로는 고르지 않는다.
---

# ui_layout_image — 코드 기반 화면 레이아웃 도식 생성 스킬

**실행 중인 앱 스크린샷이 아니라**, UI 소스코드의 레이아웃 정의(컨테이너/그리드/컨트롤)를 읽어
화면 구성을 도식(wireframe mockup) 이미지로 렌더링한다. 매뉴얼·산출물·문서에 삽입하기 위함.

## 언제 쓰나
- 앱을 띄울 수 없거나(하드웨어/시뮬 불가), 스크린샷이 부적절할 때
- 코드만으로 "이 화면이 이렇게 생겼다"를 문서/매뉴얼에 보여줄 때
- 여러 화면을 일관된 스타일의 도식으로 빠르게 만들 때

## 입력(args) 해석
- 대상 화면(들)의 소스 파일 경로 또는 화면 이름. 비어 있으면 무엇을 그릴지 한 줄로 물어본다.
- 선택 옵션: 스타일(dark HMI / light), 출력 경로, 삽입 대상(PPTX 경로·슬라이드).

## 동작 절차

### 1) UI 소스 식별 및 레이아웃 파싱 (프레임워크별)
대상 언어/프레임워크를 판별하고 **레이아웃 트리**(중첩 컨테이너 + 컨트롤 + 라벨/바인딩)를 추출한다.

| 프레임워크 | 읽을 것 | 핵심 레이아웃 단서 |
|-----------|--------|-------------------|
| **C# WPF** (이 프로젝트 기본) | `*.xaml` | `Grid`(RowDefinitions/ColumnDefinitions, `*`/`auto`/비율), `GroupBox.Header`, `StackPanel`, `UniformGrid(Rows/Columns)`, `Button.Content`, `TextBlock.Text`, `usercontrols:UCKeyValue KeyText/Unit`, `Grid.Row/Column/ColumnSpan` |
| C# WinForms | `*.Designer.cs` | `Controls.Add`, `.Location`, `.Size`, `.Dock`, `.Text` |
| Qt | `*.ui`(XML) | `<layout class="QGridLayout/QVBoxLayout">`, `<widget>`, `<property name="text">` |
| HTML/CSS | `*.html`/`*.css`/JSX | div 구조, flex/grid, 라벨 텍스트 |
| Android | `res/layout/*.xml` | `LinearLayout`/`ConstraintLayout`, `android:text` |
| Flutter | `*.dart` | `Row`/`Column`/`Grid`/`Container`, `Text(...)` |

- 비율(`2*:1*` 등), 행/열 수, 헤더 텍스트, 버튼/입력칸/표 컬럼을 **코드에서 그대로** 가져온다. 임의로 지어내지 않는다.
- 바인딩(`{Binding ...}`)은 라벨/예시값으로 치환(예: "Process Running", "1234")하되 의미를 보존한다.

### 2) 도식 이미지 렌더링 (Python · matplotlib)
- 실행: Windows에선 `py`(파이썬 런처).
- **라이브러리 가용성을 먼저 확인한다** — `matplotlib`은 이 환경에 없을 수 있다:
  `PYTHONUTF8=1 py -c "import matplotlib"` → 실패하면 `py -m pip install matplotlib` 설치를
  사용자에게 안내하고 **중단한다.** 없는 상태로 진행하면 첫 import에서 죽는다. (`Pillow`는 설치 확인됨)
- 한글 폰트: `C:\Windows\Fonts\malgun.ttf` 를 `font_manager`로 등록.
- 좌표계: `ax.set_ylim(H, 0)` 로 좌상단 원점(화면 좌표계와 동일).
- 스타일 기본값 = **dark HMI** (이 프로젝트 UI와 일치):
  - 배경 `#2D2D30`, 패널 `#3E3E42`, 테두리 `#6E6E72`, 헤더바 `#007ACC`, 글자 `#DDDDDD`,
    강조버튼 보라 `#7E57C2`/파랑 `#2D6CA2`, 입력칸 `#252528`.
- 컴포넌트 헬퍼: `panel(header)`(둥근 박스+헤더바), `kv(key,val)`(키-값 입력칸), `button(text,color)`, `label`.
- **그리드 구조를 그대로**: 컬럼 비율 → 폭 배분, 행 정의(auto/`*`) → 높이 배분, GroupBox → panel, UniformGrid → 균등 분할.
- **구현체는 같은 폴더의 `render_helpers.py`다.** 처음부터 짜지 말고 이걸 임포트한다 —
  `sys.path.insert(0, "<스킬폴더>")` 후 `from render_helpers import new_canvas, panel, kv, button, label, save`.
  위 팔레트 상수도 거기 들어 있어, 직접 구현하면 값이 갈라진다.
- 참고: `UnTrackedLocalFiles/`의 `gen_mockups.py`·`gen_menubar.py`는 부가 예시이며
  `.gitignore` 제외라 **clone 직후에는 없다.** 없어도 무방하다.

### 3) 저장
- 기본 출력: `UnTrackedLocalFiles/hmi_mockups/<screen>.png` (git 제외 위치). 다른 위치 지정 시 그곳에.
- **저장 전 폴더를 만든다** — `mkdir -p UnTrackedLocalFiles/hmi_mockups`. 이 폴더는 `.gitignore`
  대상이라 clone 직후 **없다.** 없으면 `savefig`가 `FileNotFoundError`로 죽는다. 백업 경로도 동일.
- 생성 후 Read 도구로 PNG를 열어 **시각 검증**(겹침/라벨 누락 확인). 문제 있으면 수정 후 재생성.

### 4) (선택) 문서/PPT 삽입
- PPTX: `python-pptx`로 대상 슬라이드의 기존 스크린샷(PICTURE)·번호 콜아웃(예 "타원*")을 제거하고
  같은 위치/크기에 `add_picture`. 빈 콜아웃 박스도 정리.
- 검증(선택): LibreOffice(`soffice --headless --convert-to pdf`) → PyMuPDF(`fitz`)로 PNG 렌더 후 Read.
  **둘 다 이 환경에 없을 수 있다** — `command -v soffice` / `py -c "import fitz"`로 확인하고,
  없으면 삽입 검증을 생략하고 보고서에 **`미검증 — soffice/fitz 부재`** 로 명시한다. 검증했다고 하지 않는다.

### 5) 보고
- 생성한 이미지 경로, 반영한 화면/소스, 삽입 위치를 한 줄로 요약. 코드와 다르게 추정한 부분은 명시.

## 주의
- 반드시 **소스코드 기준**. 실제 값이 불명확하면 라벨/예시값으로 두고 "(예시)" 표기.
- **원본 문서(PPT/Excel)를 수정하기 전에 승인을 받는다** (`rules.md` #2) — 수정할 슬라이드·시트와
  제거·교체할 도형 목록을 먼저 제시한다. 이 스킬은 하네스에서 **유일하게 원본을 직접 고치는** 스킬이다.
- 수정 전 백업(`UnTrackedLocalFiles/...backup`). 서식 보존.
- 기존 pptx에 이미지를 삽입하는 것은 `ubisam-ppt-make`의 "python-pptx 직접 사용 금지"의 예외다
  (덱 생성이 아니라 삽입이므로).
- 생성 스크립트·중간 렌더는 `UnTrackedLocalFiles/`(커밋 제외)에 둔다. 산출물(이미지가 삽입된 문서)만 커밋.
- 제거·교체할 도형 목록은 `rules.md` #11~13 형식으로 제시한다 — 교체 대상 줄은 초록 화살표(→),
  단어 단위는 주황, 미변경은 기본색.

## 호출 예시
- `/ui_layout_image UCMainAutoRun.xaml 화면 도식 만들어줘`
- `/ui_layout_image Manual/Calibration 화면들 dark 스타일로 그려서 HMI Manual.pptx 슬라이드에 넣어줘`
- 자연어: "스크린샷 말고 XAML 그리드 구조 보고 화면 레이아웃 이미지로 만들어서 매뉴얼에 넣어줘"

> 보고는 `rules.md` #11~13 출력 형식을 따르고(수정 줄=초록 화살표, 단어=주황, 미변경=기본색),
> 단계 전환마다 진행을 한 줄로 알리며(#10), 끝에 관련 `.md` 갱신 필요 여부를 묻는다(#6).