# Layout selection guide

How to pick the right layout for a given piece of source/analysis data when
building a Ubisam SW 설계서 / HMI Manual deck. Read this before writing the spec.

## Slide master background (유비샘 산출물 고정)

`build()` 호출 시 자동으로 슬라이드 마스터에 배경을 적용한다. 모든 pptx에 공통 적용.

| 요소 | 값 | 적용 범위 |
|---|---|---|
| 캔버스 배경색 | `BG_SOFT` #F4F7FA (연회색) | 전체 슬라이드 마스터 + 모든 레이아웃 |
| 하단 accent 바 | `ACCENT` #4A8DCB (blue), h=0.15in | 마스터 공통 장식 (y=7.35in) |

**상속 규칙**: 개별 레이아웃에서 full-slide `rect(fill=WHITE)` 를 그리면 마스터 배경을 덮는다.
- 배경 **덮음** (자체 흰색 rect): `cover` · `divider` · `closing`
- 배경 **상속** (BG_SOFT 노출): `history` · `agenda` · `content` · `flow` · `table` · `screen_guide` · `procedure` · `icon_ref` · `alarm`

spec JSON에서 `"background_color": "RRGGBB"` 키로 배경색 재정의 가능 (기본 = F4F7FA).


## Quick decision table

| If the data is… | use | not |
|------------------|-----|-----|
| Document identity (title, 장비명, 담당자) | `cover` | — |
| Revision log (버전·날짜·작성자·변경내용) | `history` | `table` |
| List of sections / TOC | `agenda` | — |
| A chapter / section break | `divider` | — |
| 2–4 parallel sub-areas, each 1 line | `content` | `table` |
| Machine/SW execution sequence **with conditions/branches** | `flow` | `procedure` |
| Reference data in rows × columns (IO, 축, 스펙, 파라미터) | `table` | `content` |
| One screenshot to annotate by region | `screen_guide` | `icon_ref` |
| Ordered **human actions**, no branching | `procedure` | `flow` |
| Set of discrete buttons/icons (name + function, ≤6) | `icon_ref` | `table` |
| Faults with cause → action (+ safety) | `alarm` | `table` |
| Closing / contact | `closing` | — |

## Per-layout: what data belongs

### Document layouts

- **cover** — The deliverable's identity. Fields: doc tag, 설계서/매뉴얼 title,
  장비 한/영 설명, team, 담당자 contacts. One per deck, first slide.
- **history** — Revision rows `[No, Version, 날짜, 변경자, 변경내용]`. Use only
  for the change log; any other 5-column data → `table`.
- **agenda** — Up to 6 top-level sections `{no, title(EN), sub(KO)}`. Mirrors the
  `divider` numbers used later.
- **divider** — Section break: big `no` + EN title + KO subtitle. No body data.
- **content** — 2–4 panels `{title, body}`, each panel one parallel facet
  (e.g. UI 화면 영역, 기능 블록). Body is a one-line description, NOT a list of
  rows. If you have ≥5 items or columnar data, switch to `table`.
- **flow** — Sequence steps `{title, code, kind}` where `code` is the
  method/condition name and `kind` is `proc` or `dec` (decision). Add `branch`
  for the fail/stop path. Use for control sequences, state machines, 공정 흐름.
  If there are no conditions/branches and the actor is a person → `procedure`.
- **table** — Any structured reference data: IO map, 축 구성, 통신 스펙, 레시피
  파라미터. Define `headers`, `widths`, `center_cols`. Keep cells short.
- **closing** — Thank-you + contacts. Last slide.

### Manual layouts (HMI Manual / 27번)

- **screen_guide** — Exactly ONE screen, annotated. `caption` = what the capture
  shows; `items[]` = numbered callouts `{title, desc, pos:[x,y]}` where `pos` is
  the marker offset (inch) inside the capture box. Use when regions of a single
  image need labels. Many separate images → multiple `screen_guide` slides.
- **procedure** — Ordered operator steps `{title, desc}`. Each step is an action
  the user performs in order (전원 ON → 원점 복귀 → …). No machine codes, no
  branches (those belong in `flow`). Aim for 3–6 steps.
- **icon_ref** — ≤6 discrete controls `{icon, name, func}`. One card per button/
  icon with its function. For long control lists with extra columns → `table`.
- **alarm** — Troubleshooting rows `[코드, 알람명, 발생원인, 조치방법]` plus a
  `notice` safety banner. Use for alarm/fault handling; pairs each fault with its
  remedy. Generic specs without cause→action → `table`.

## Disambiguation rules (the common mistakes)

1. **procedure vs flow** — Person doing steps in order = `procedure`. Machine/SW
   executing with `if`/branches/return-to = `flow`.
2. **content vs table** — ≤4 facets each described in a sentence = `content`.
   Repeating records with the same columns = `table`.
3. **icon_ref vs table** — Each item is a single control with one function =
   `icon_ref`. Items have multiple attributes/columns = `table`.
4. **alarm vs table** — Rows pair a problem with its corrective action (needs the
   safety banner) = `alarm`. Pure reference rows = `table`.
5. **screen_guide vs icon_ref** — Annotating positions on one image =
   `screen_guide`. Listing controls independent of an image = `icon_ref`.