id: scene-and-flow title: Scene and Flow — diagrams written as text scope: public updated: 2026-08-07 tags: - fragment - diagrams - specification
Status: working notations — experimental, and they evolve over time. Purpose: keep structural drawings inside the text, so a diagram can be read, diffed, and reviewed like the prose around it. The host format is specified in Fragment format.
Scene and Flow are two small notations for writing diagrams as text inside a fragment. You describe shapes and connections in plain text; the renderer draws them. Both a person and a model read the same structure.
Scene はレイアウトと関係、Flow はプロセスと流れを表します。図解専用ツールでは なく、ノートの中に置けるテキストの図として設計しています。
Why as text
Diagrams are useful. Diagram tools make you spend the time on dragging, aligning, and pixel-perfect layout. Scene and Flow keep only the structural information in text.
- Versionable with ordinary history or Git — it is just text.
- A model can follow the diagram step by step, or propose an alternative.
- Copy between pages, reuse a pattern, refactor as text.
- Lives beside the prose instead of in a separate design file.
Two notations
| Describes | Suits | |
|---|---|---|
| Scene | A canvas with shapes and arrows — boxes, labels, connections | Overviews, architectures, "what sits next to what" |
| Flow | Nodes and edges only — how something moves from A to B to C | Workflows, onboarding, incident handling, "what comes next if…" |
Scene
A Scene describes a layout or a moment: boxes, labels, and arrows on a canvas. Useful when you want to show how parts relate in space, without spending attention on the design.
```yaml block:scene
scene:
canvas:
width: 720
height: 260
shapes:
- type: rect
id: fragment
x: 80
y: 96
w: 160
h: 64
label: "Fragment"
- type: rect
id: prism
x: 320
y: 96
w: 180
h: 64
label: "Prism (YAML)"
- type: arrow
from: fragment
to: prism
label: "settings"
```
Fenced YAML blocks annotated block:scene are rendered as diagrams. Your job in
the text is to name the objects and relationships clearly enough that both a
reader and a model can interpret them — clearly enough, for instance, to ask for
the Scene to be explained in words with one simplification proposed.
Flow
A Flow describes a process: nodes and arrows only. It is about what leads to what, not where things sit on a canvas.
```yaml block:flow
flow:
layout: tb # top-bottom
nodes:
- id: idea
label: "Write Fragment"
- id: config
label: "Add small YAML"
- id: reflect
label: "Review with AI"
edges:
- from: idea
to: config
- from: config
to: reflect
```
Keep Flow blocks small. A few simple ones — how a weekly note reaches done, how an incident is handled — usually beat a single diagram trying to show everything.
Inside Markdown
Both appear as fenced YAML blocks in the middle of ordinary Markdown. Blocks
annotated block:scene or block:flow are rendered alongside the text.
The parser tolerates small formatting mistakes, but the closer the block stays to a YAML-like structure, the more predictable the rendering — and the easier the diagram is to read and change collaboratively.
What this is not
Scene and Flow are not a replacement for a design tool. They are for capturing relationships and processes in a way that
- stays next to the text,
- is easy to diff and review,
- and remains legible even when nothing renders it.
That last point is the reason for the whole design. A diagram you cannot read without its renderer is a diagram you can lose.
Related structure blocks
Scene and Flow sit alongside Prism and the YAML front-matter described in Fragment format. All of them are small structured islands next to Markdown, rather than a separate layer.