# Visual grammar

Choose the smallest grammar that exposes the paper's mechanism. Adding a second grammar
must add information.

| Fact to expose | Grammar |
|---|---|
| one semantic object | `\sfnode` |
| linear sequence inside one band | `\sfstage` + `\sfrow` … `\sfrowend` |
| an edge between two objects | `\sfconn` for flow, `\sfarrow` for fixed topology |
| an edge label | `\sfconn{name}{label}` or `\sfarrowlabel` |
| a real composite (module, subsystem, shared owner) | `\sfgroup` |
| an operator inside a flow row | `\sfop` |
| a side note about a finished band | `\sfcallout` |
| the bottom explanation | `\sfmeaningbox` |

## Node semantics

One block is one semantic object. If you need two verbs in one block, split it.

- Label is the object's name or role, not a sentence.
- Fill color encodes a role, not importance.
- Width/height may differ to reflect a visual hierarchy, but do not use size to invent
  quantitative meaning unless the figure says so.

## Edge semantics

Every arrow must be one of:

- **data flow** — the output of A becomes the input of B.
- **control flow** — A decides whether or when B runs.
- **dependency** — B needs A to exist or to have run.
- **causality** — A causes B.

A decorative arrow is an error. If an edge does not carry one of those meanings, remove it
or replace it with a grouping/caption.

## Group semantics

`\sfgroup` names a composite object. The members inside must actually belong to that
composite in the paper. Do not draw an outline around nearby nodes merely because it looks
balanced. The fit list is explicit: `{(node1)(node2)}`.

## Captions and meaning box

- `\sfcaption{name}{symbol}{detail}`: one short symbol line plus one muted detail line.
- `\sfmeaningbox`: at most three rows — idea, objects, mechanism. Prefer removing content
  over shrinking type or adding columns.