Scene — a layout or moment
Describes a canvas with shapes and arrows: boxes, labels, and connections. Good for overviews, architectures, and “what sits next to what”.
Docs · Diagrams — Scene / Flow as text
Scene / Flow diagrams
Scene and Flow are small DSLs for writing diagrams as text inside a Fragment. Instead of drag-and-drop editors, you describe shapes and connections in plain text. Fragment renders them as diagrams, and both humans and AI can read the same structure.
「図解専用ツール」ではなく、ノートの中に埋め込めるテキストの図として設計しています。Scene はレイアウト・関係、Flow はプロセス・流れを表現し、 どちらも AI がたどれるかたちでメモのすぐそばに置いておけます。
Start small: one Scene for an overview, or one Flow for a process you care about. You can always redraw or delete a diagram later — the note stays useful even without it.
Why write diagrams as text?
Visual diagrams are useful, but traditional tools make you spend time on dragging, aligning, and pixel-perfect layout. Scene / Flow keeps only the structural information in text and lets Fragment handle the rendering.
- • Easy to version with history or Git — it's just text.
- • AI can “follow the diagram” step by step or suggest alternatives.
- • Copy / paste between Fragments, reuse patterns, and refactor as text.
- • Lives next to your Markdown narrative instead of in a separate design file.
Two small DSLs: Scene and Flow
Scene and Flow are siblings:
Flow — a process or logic
Describes nodes and edges only: how something moves from step A to B to C. Good for workflows, onboarding, incident flows, and “what comes next if…”.
Scene — a moment or layout
A Scene describes a layout or “moment”: boxes, labels, and arrows on a canvas. It's useful when you want to show how components relate in space without worrying about pixel-perfect design.
Example: a simple Scene block
```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"
```Fragment detects fenced YAML code blocks annotated with block:scene and renders them as diagrams. Your job in the text is to name the objects and relationships clearly enough that both humans and AI can interpret them — for example, asking AI to "explain this Scene in words and suggest one simplification".
Flow — a process or logic
A Flow describes a process: nodes and arrows only. It focuses on what leads to what, rather than where things are placed on the canvas.
Example: a simple Flow block
```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 and focused. It's often better to have a few simple Flows (e.g. "how a weekly note moves to done", "how an incident is handled") than one huge diagram that tries to show everything at once.
Using Scene / Flow inside Markdown
In Studio, Scene and Flow appear as fenced YAML code blocks inside your Markdown. Fragment detects blocks annotated with block:scene or block:flow and renders the diagrams alongside your text.
# Example: using Scene / Flow in a Fragment
Here is some normal Markdown text...
```yaml block:scene
scene:
canvas:
width: 720
height: 260
shapes:
# ...
```
More explanation, notes, or prompts...
```yaml block:flow
flow:
layout: tb
nodes:
# ...
edges:
# ...
```
The parser is tolerant of small formatting mistakes, but the closer you stay to a YAML-like structure, the more predictable the rendering will be — and the easier it is for AI to read and manipulate the diagram with you.
How Scene / Flow relate to other structure blocks
Scene / Flow is part of a broader direction in Fragment: small, text-first blocks for structure that live next to your notes.
Already implemented today
Scene / Flow is one of the first DSLs you can already use in Studio. Alongside Prism and basic YAML front-matter, it lets you:
- draw simple diagrams from text,
- keep them under version control,
- and invite AI to reason about them step by step.
Coming up: tasks, schedules, relations
Other block types such as block:tasks, block:calendar, and block:relations share the same spirit: small structured islands next to Markdown. Scene / Flow is simply the earliest shipping member of that family.
As these mature, the same Fragment can host diagrams, task lists, timelines, and relations — all as text that humans and AI can read together.
Not a full design tool
Scene / Flow is not meant to replace Figma, Excalidraw, or whiteboards. It's for quickly capturing relationships and flows in a way that:
- stays close to your text,
- is easy to diff and review,
- and remains legible even when rendering is unavailable.
Shared with AI from day one
Because diagrams are written as text, you can ask AI to follow the Flow step by step, rewrite a Scene with fewer nodes, or suggest alternative architectures. The diagram becomes an active part of your co-creation loop, not just a static picture.
Start with one Scene or Flow in your next Fragment
You don't have to design the perfect diagram. Start with a single Scene or Flow block in a Fragment, use it to clarify one relationship or process, and refine it only if it proves useful — both for you and for your AI partner.