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에 공통 적용.

요소	값	적용 범위
캔버스 배경색	`WHITE`	`_apply_master_background()`가 마스터 + 전 레이아웃에 적용 (`build_deck.py:55-73`)
하단 accent 바	`ACCENT` #4A8DCB (blue), h=0.15in	마스터 공통 장식 (y=7.35in)

상속 규칙: 마스터 배경이 이미 WHITE이므로 레이아웃별 배경 차이는 없다. cover·divider·closing만 자체 full rect로 별도 색을 덮는다.

배경 덮음 (자체 흰색 rect): cover · divider · closing
배경 상속(= 흰 배경): history · agenda · content · flow · table · screen_guide · procedure · icon_ref · alarm

BG_SOFT(#F4F7FA)는 배경색이 아니라 패널·표 짝수행 fill 전용이다.

캔버스 배경은 build_deck.py의 _apply_master_background()가 WHITE로 고정. spec JSON 키로 재정의되지 않는다 — 바꾸려면 build_deck.py를 수정해야 한다.

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)

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

5.2 KiB Raw Blame History Unescape Escape