88 lines
4.9 KiB
Markdown
88 lines
4.9 KiB
Markdown
# 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`.
|