Language Reference

FractalForm diagrams are plain-text scripts for animated system diagrams.

client -> api: GET /users

Basic request

Loading preview

Edges and state updates create components automatically. Add stages, notes, overlays, artifacts, playback directives, and control blocks only when the diagram needs them.

Quick Reference

Minimal syntax for each FractalForm construct.

Construct

Minimal form

Details

Component

component api "API"

Details

Initial body

component api
  Ready
end

Details

Colors

component api shape:server style:#warning icon:check,#success
text style:#7c3aed: Label

Details

Edge

api -> db: query

Details

Static edge

edge from:api to:db "Query users"

Details

State

api: Ready

Details

Replay state

state api: Thinking

Details

Content Rendering

api:
  pairs:
    status: ok

Details

Group

group "Backend"
  component api
end

Details

Stage

# stage: Send request

Details

Note

# note: Explain next action

Details

Overlay

# overlay pause: Five minutes later

Details

Artifact

api -> user: issue %token

Details

Text

text "Callout"

Details

Shape

circle "Label"

Details

Tree

tree "Routing" shape:decision
  - Valid?
    ? yes
      - Route
end

Details

Playback

--wait 1s

Details

Repeat

repeat 3
  api -> db
end

Details

Parallel

parallel
  api -> db
  api -> cache
end

Details

Block

block healthcheck
  api -> db
end

Details

Detached

*repeat
  monitor -> api
end

Details

Variable

$state.count++

Details

Quick Notation

Backend
  - api

Details

Components

Declare topology nodes when you need a label, shape, icon, tier, tags, hierarchy, or an initial visible body. Edges and state updates still create undeclared components automatically.

Syntax

component key "Display Name" shape:shape,many style:tier,title-hidden,#color icon:name,badge [tags]

component key "Display Name"
  Initial body
end

Details

Parameter	Description	Example
key	Addressable identifier.	`component api`
"Display Name"	Quoted label.	`component api "API"`
shape:shape,many	Structural shape and multiplicity.	`shape:server,many`
Shapes	default, circle, database, hexagon, diamond, note, actor, icon, cloud, external, browser, server, funnel, code.	`shape:cloud`
style:tier,title-hidden,#color	Presentation tier, icon title visibility, and outline color.	`style:lg,title-hidden,#info`
many	Render one logical component as a stacked or repeated visual.	`shape:server,many`
#color	Theme color token or hex color for visual emphasis.	`style:#warning`
icon:name,badge	Icon or badge metadata.	`icon:server,badge`
[tags]	Short visual metadata; tags can carry colors.	`[backend, public #info]`
Initial body	Indented body under `component ... end`. Plain text becomes markdown; decorator bodies become structured content. Last declaration wins.	`component api Ready end`

Examples

Component Declaration

# Declarations set labels, shapes, icons, and tags.
component api "API" shape:server style:lg icon:server,badge [backend]
component db "Database" shape:database icon:database,badge

api -> db: query

Loading preview

Full component example

Colors

Color modifiers are visual metadata used across components, groups, tags, edges, notes, overlays, artifacts, text, and shapes. Named colors adapt to the active diagram theme; hex colors keep the authored value.

Syntax

#success

#error

#warning

#info

#red #blue #green #yellow #purple #gray #orange #pink #cyan #primary #secondary

#abc #7c3aed #7c3aedff

Details

Token	Visual	Use
#success	Green	Successful, healthy, complete, accepted.
#error	Red	Failed, blocked, rejected, unavailable.
#warning	Amber or orange	Risk, degraded, retry, needs attention.
#info	Blue	Neutral status, context, informational callout.
#primary	Theme accent	Primary emphasis aligned with the active theme.
#secondary	Muted	Subtle metadata or secondary visual weight.
#red, #blue, ...	Named palette color	Non-semantic grouping.
#abc, #7c3aed, #7c3aedff	Exact hex color	One-off brand or diagram-specific accents.

Examples

Semantic Color Tokens

# Semantic colors carry meaning and follow the active theme.
component api "API" shape:server style:#info icon:server,#info [public #info]
component worker "Worker" shape:hexagon style:#warning icon:cpu,#warning [retry #warning]
component db "Database" shape:database style:#success icon:database,#success [healthy #success]

api -> worker: retry <icon:alert-triangle #warning>
worker -> db mark:#success: write <icon:check #success>
worker -> api mark:dropped,#error: timeout <icon:x #error>
# note pause #warning: Retry is safe, but it needs attention.
api -> worker: retry again

Loading preview

Edges

Bare arrows are replay sends. Use edge to declare a static edge and optional default label without emitting a particle. Labels are plain text; rich data belongs in component or artifact state.

Syntax

source -> target: label

edge from:source to:target "label"

edge from:source to:target
  label
end

source -> middle -> target: label

source -> [target-a, target-b]: label

source -> target mark:dropped,#error: label

Details

Arrow	Meaning
->	Synchronous call
->>	Async fire-and-forget
~>	Streaming
-->	Optional or conditional
-->>	Async optional or conditional
..>	Inferred or weak
..>>	Async inferred or weak
<->	Bidirectional
<~>	Bidirectional streaming
<-->	Bidirectional optional or conditional
<..>	Bidirectional inferred or weak

Examples

Basic Edges

# Plain edges create components if needed.
client -> api: request
api -> db: query

Loading preview

Full edge example

State

State is replay-only content on a component. Put starting visible content on an explicit component ... end body instead. Plain text works for simple status; structured or Markdown state shows useful internal detail.

Syntax

component: content

state component: content

state component
  Markdown body
end

component:
  Markdown body

component:
  pairs:
    status: ok

component mark:destroyed: content

component <mark:destroyed>: content

Details

Form	Description	Example
Text	Simple replay status.	`api: Processing`
Keyword state	Explicit replay alternative to inline `key:`.	`state api: Thinking`
Structured	Decorated state body.	`api: pairs: status: ok`
Markdown body	Indented Markdown after a state opener.	`api:`
Timeline mark	Transient node treatment.	`session mark:destroyed: removed`

Examples

Component State

# Inline state updates change what a component displays during replay.
api: Processing request

api:
  pairs:
    status: ok
    count: 3

api:
  Handles **requests**.
  - validates input

Loading preview

Full state example

Content Rendering

Indented bodies can render as Markdown or as decorated content. The same body forms work in component state, artifact state, attached or standalone text, and shape bodies. Decorated bodies use a small YAML-like syntax.

Markdown Bodies

A body with plain indented text renders as Markdown. Use this for prose, lists, headings, emphasis, code spans, and inline icons.

Where	Structure	Body
Component state	`api: Handles requests. - validates input`	Markdown rendered in the component body.
Artifact state	`%token: Signed JWT. - expires in 15m`	Markdown rendered on the artifact.
Standalone text	`text: Release notes. - watch latency`	Markdown rendered as free canvas text.
Attached text	`text @api \| Handles requests. - validates input`	Markdown rendered beside the target.
Shape body	`diamond decision: Policy check. - allow - deny`	Markdown rendered inside the shape.

Decorator Bodies

A body whose first content line is a decorator uses that decorator to choose the rendered shape. Decorators can be combined in the same body.

Decorator	Structure	Body
text:	`api: text: Ready`	Plain text content.
pairs:	`api: Ready pairs: status: ok count: 3 latency: [42, ms]`	Mapping rendered as labeled rows.
list:	`api: Checks list: - auth - quota`	Sequence rendered as bullets.
list:ordered:	`api: Steps list:ordered: - authorize - capture`	Sequence rendered as numbered steps.
list:segmented:	`text: list:segmented: - First item - Second item`	Sequence rendered as adjacent cells on one unwrapped row.
progress:	`api: Deployment progress: current: provision steps: validate: Validate input provision: Provision deployment verify: Verify health`	Ordered progress list. The writable current_index reference path selects a step by zero-based position.
progress:segmented:	`text: progress:segmented: current: provision steps: validate: Validate input provision: Provision deployment verify: Verify health`	Equal-width adjacent progress cells; current is bold, and current_index can be driven by a counter.
group:panel:	`api: Details group:panel: metadata pairs: region: us-east-1`	Panel groups contain decorated blocks in a collapsible section.
table:	`api: Services table: - service: auth status: ok - service: payment status: <icon:check>`	Sequence of mappings rendered as table rows.
table:grid:	`text service-status style:#rose: table:grid: - service: auth status: ready - service: worker status: running`	Sequence of mappings rendered with an outer border and row and column dividers.
error:	`api: Failed error: code: 503 message: Unavailable`	Mapping rendered with error styling.
group:	`api: Cache group: stats pairs: hits: 12 misses: 3`	A group contains other decorated content blocks.
markdown:	`api: text: Deployment note markdown: Rollout is healthy. - canary checks passed`	Markdown body inside decorated content.
json:	`api: json: { "status": "ok" }`	JSON code body after a state opener.

Examples

Text

The text decorator renders plain component content.

component api "Text"

api:
  text: Ready

Loading preview

Groups

Groups draw visual boundaries around related components, text, trees, or nested groups.

Syntax

group key "Display Name" shape:shape style:stroke,radius-12px,title-hidden,#color icon:name [tags]
  component key
end

group "Display Name"
  existing-key
end

Details

Part	Description	Example
key	Optional addressable identifier; quoted-only groups get an internal key.	`group backend "Backend"`
"Display Name"	Visible group label.	`group "Infrastructure"`
shape	Border geometry: rect, circle, diamond, hex, or ellipse.	`shape:ellipse`
stroke	Border stroke: solid, dashed, or dotted.	`style:stroke-dotted`
radius	Boundary corner radius in pixels.	`style:radius-12px`
title-hidden	Hide the title bar without removing the group label or identity.	`style:title-hidden`
#color	Theme color token for the border.	`style:#warning`
icon:name	Optional group icon and color.	`icon:cloud,#info`

Examples

Group Block

# Group related components under one boundary.
group backend "Backend"
  component api "API" shape:server
  component db "Database" shape:database
end

api -> db: query

Loading preview

Full group example

Stages

Stages are independently playable chapters. A chapter starts at its marker and stops before the next stage; description lines immediately after the marker become stage context.

Syntax

# stage: Title

# Description line

Examples

Stage

# Stages create bounded, directly playable chapters.
# stage: Title
# Description line

client -> api: POST /orders
api -> db: insert

Loading preview

Notes

Notes attach explanation to the next timeline command. Put the note directly above the state or edge it explains.

Syntax

# note: Text

# note pause: Text

# note n 5s #warning: Text

Details

Modifier	Effect
pause	Manual advance required.
3s	Auto-dismiss after duration.
n	Next action number.
#warning	Accent color.

Examples

Basic Note

# Notes explain the next event.
# note: Client sends the request.
client -> api: request

Loading preview

Overlays

Overlays are canvas-level messages for scenario transitions, time skips, or major status changes.

Syntax

# overlay: Text

# overlay pause: Text

# overlay 10s: Text

Details

Modifier	Effect
pause	Manual advance required.
10s	Auto-dismiss after duration.
<icon:name #color>	Optional icon and accent.

Examples

Basic Overlay

# Overlays narrate scene changes.
# overlay: Explain the next scene.
client -> api: start

Loading preview

Artifacts

Artifacts are data objects with identity. They can travel with edges, receive state, and be cleared independently.

Syntax

artifact key "Name" icon:name

source -> target: label %artifact

%artifact:
  Markdown body

%artifact:
  pairs:
    status: ok

%artifact#copy

Details

Feature	Syntax
Declare	artifact token "Token" icon:key-round
No declaration	client -> api: upload %file
Attach to edge	auth -> user: issue %token
Instance copy	%item#copy
Multiple	api -> client: done %order %receipt
Markdown state	%token: Token issued
State	%token: pairs: sub: user123
Clear	--clear %token

Examples

Declared Artifact

# Artifacts are data objects with identity.
artifact token "Token" icon:key-round
auth -> user: issue %token

%token:
  pairs:
    sub: user123
    exp: 15m

user -> api: GET /profile %token

Loading preview

Text

Text creates static canvas annotations. It can stand alone or attach to an element or group with side markers.

Syntax

text "Display Text"

text "Display Text" style:xl

text @target |
  Markdown body

text @target marker:|
  Markdown body

text @target |
  pairs:
    status: ok

text @target style:#info ->
  Markdown body

Details

Form	Description	Example
Standalone	Free-floating annotation.	`text "Request Flow"`
Attached	Sidecar beside a target.	`text @api "Handles ingress"`
:	Plain markdown body.	`text @api:`
Decorated body	Body rendered with a content decorator.	`text @api: pairs: status: ok`
\|	Guide bar beside the text.	`text @api \|`
]	Bracket marker.	`text @api ]`
}	Brace marker.	`text @api }`
-> / <-	Arrow connector direction.	`text @api ->`
-o / o-	Step connector direction.	`text @api -o`
marker:	Property form for the same marker options.	`text @api marker:\|`
Style	Standalone size/opacity, or attached description presentation metadata.	`text @api style:#info \|`

Examples

Standalone Text

text "Request Flow"

Loading preview

Full text example

Shapes

Shapes add primitive canvas geometry independent of topology nodes.

Syntax

circle "Label"

rect id style:dashed,#color

ellipse id @target style:#warning "Label"

diamond id:
  Markdown body

diamond id:
  pairs:
    status: ok

Details

Part	Description	Example
primitive	Primitive element command.	`circle`
Primitive	Canvas geometry: rect, circle, diamond, ellipse, hex, or line.	`circle`
id	Optional stable identifier; omitted shapes get generated ids.	`rect boundary`
@target	Optional attachment target for relative placement.	`circle halo @api`
style modifiers	Stroke, direction, size, and color metadata.	`style:dashed,#info`
Label/body	Quoted inline label or indented body after a colon.	`diamond gate "Policy"`
Decorated body	Shape body rendered with a content decorator.	`diamond gate: pairs: status: ok`

Examples

Circle Shape

circle "Label"

Loading preview

Trees

Trees add supporting canvas detail for decisions, nested ideas, or ordered logic.

Syntax

tree "Title" shape:spine
  - branch
end

tree "Title" shape:spine style:arrows
  - step
end

tree "Title" shape:mindmap
  - topic
end

tree "Title" shape:decision
  - State
    ? event
      - Next
end

Details

Form	Use For	Example
shape:spine	Ordered paths, routes, steps, or escalation logic.	`tree "Routing" shape:spine`
style:arrows	Draw directional connectors between tree items.	`shape:spine style:arrows`
shape:mindmap	Related capabilities, concerns, or design areas.	`tree "Platform" shape:mindmap`
shape:decision	Named choices, state machines, or policy transitions.	`tree "Breaker" shape:decision`
- label	A branch.	`- auth check`
? label	A decision/event branch in decision trees.	`? failure`
-> id "Label"	Reference another tree node.	`-> closed "Closed"`

Examples

Routing Detail

# Spine trees show ordered supporting detail.
tree "Routing" shape:spine
  - incoming request
  - auth check
end

Loading preview

Full tree example

Playback Directives

Playback directives control visibility, clearing, timing, and numbering. Visibility directives apply from their position in the timeline forward.

Syntax

--dim target

--show target

--hide target

--outline target

--clear target

--wait 1s

--travel 1s

--dwell 1s

--gap 200ms

--speed 5

--autonumber

Details

Directive	Effect
--dim	Dim components.
--show	Restore hidden, dimmed, or outlined components.
--hide	Remove components from the canvas.
--outline	Show a ghost outline.
--clear	Clear state or artifacts.
--wait	Insert a delay.
--travel	Set edge particle travel duration.
--dwell	Set readable dwell for state and artifacts.
--gap	Set rest after each event.
--speed	Set or reset playback speed.
--autonumber	Add action badges.

Examples

Dim

component api "API" shape:server
api: ready
--dim api

Loading preview

Control Blocks

Control blocks group commands for reuse, repetition, concurrency, and detached background work.

Syntax

repeat 3
  ...
end

parallel
  ...
end

block name
  ...
end

@name

*repeat name
  ...
end

--detach @name

--attach @name

Details

Block	Effect
repeat	Loop a command sequence.
parallel	Run commands concurrently.
block	Define a reusable command group.
@name	Invoke a block.
block / repeat	Start a detached block or repeating background lane.
--detach / --attach	Run a block in the background or wait for it.
* @name / ^name	Shorthand detach and attach forms.

Examples

Repeat

# Repeat loops the body.
repeat 3
  client -> api: poll
end

Loading preview

Variables

Variables are illustration helpers for diagrams that need a value to change over time. Use them for small counters, statuses, or repeated values that make a concept easier to follow; they are not a general-purpose programming model.

Syntax

$name: value

$name:
  Markdown body

$name:
  pairs:
    status: ok

$name.field: value

$name.field++

$name.field--

text label:
  $name

rect status:
  $name.progress

component:
  pairs:
    field: $name.field

Details

Form	Effect
$breaker: value	Set a variable.
$breaker.field: value	Set a field.
$breaker.field++	Increment a field.
$breaker.field--	Decrement a field.
$count++ / $count--	Increment or decrement a scalar variable.
text label: $summary	Materialize a variable as standalone text content.
rect status: $summary.progress	Materialize a decorated variable path as primitive content.
$summary: pairs: status: ok	Set a variable with a decorated body.
component: pairs: field: $breaker.field	Render a variable read in a decorated body.

Examples

Declare Variable

# Variables help illustrate values that change over time.
$breaker: {
  status: closed,
  failures: 0
}

Loading preview

Quick Notation

Quick Notation is a concise, indentation-based way to sketch components, groups, and flows. Regular FractalForm constructs also work directly, including artifacts, variables, marked edges, and playback directives such as --dim, --wait, and --speed.

Syntax

// Groups are bare labels; indentation creates nesting
Platform (platform) ~#blue [production]
  Services
    [server,cloud] API (api) -badge [backend]

// Component marker families
[] Service (service)
[[cpu,server]] Workers (workers)
(postgresql) Database (db)
<shield> Gateway (gateway)
{bot} Agent (agent)
{{bot}} Agents (agents)

// Child and related components
[] Parent (parent)
  - Child
  -- {sheet} Related
[,server] fractalform.io
  -- [,text] /share

// > is the Quick Notation replay shorthand
client > api > db: query
edge from:api to:db "static label"

// Initial content and attached descriptions
[] API (api)
  : Ready
  / Handles requests
  | Public endpoint

// Canvas text, primitive shapes, and paths
/ Request flow ~lg,#info
[.] Boundary (boundary) ~opacity-75
(.) Cache
<.> Region
<<.>> Decision
((.)) Pool
path divider "Divider" ~#gray

// Stages, notes, and overlays
/// Request flow
  Follow the request from ingress to storage.
## Validate input ..
### Five minutes later 5s..

// Indentation closes blocks; do not write end
repeat 3
  client > api: retry

parallel
  api > db
  api > cache

// Named and detached blocks also close on dedent
block healthcheck
  api > db: ping

*repeat heartbeat
  monitor > api: GET /health

// Quick tree starts
?tree "Request path" =spine ~arrows
  - Receive
  - Validate

?tree "Platform" =mindmap
  - Services

?tree "Retry policy" =decision
  - Closed
    ? failure
      - Open

Details

Quick Form	Converts To
Label	group "Label"
Label (id)	group id "Label"
- api	component api
[] API (api)	component api "API"
[,browser] Web	component web "Web" shape:browser
[,text] /share	component share "/share" shape:text
[globe,browser] Web	component web "Web" shape:browser icon:globe
[[cpu,server] ] Workers	component workers "Workers" shape:server,many icon:cpu
(postgresql) DB	component db "DB" shape:database icon:postgresql
<shield> Gateway	component gateway "Gateway" shape:hexagon icon:shield
{bot} Agent	component agent "Agent" shape:icon icon:bot
[[cloud,server] ] API (api) ~lg,#info -#warning	component api "API" shape:server,many style:lg,#info icon:cloud,#warning
Platform =circle ~stroke-dashed,radius-12px,title-hidden	group "Platform" shape:circle style:stroke-dashed,radius-12px,title-hidden
[] API -icon:server,badge,#warning	component api "API" icon:server,badge,#warning
- Child / -- Related	component parent.child / parent..related
A>B>C: call	A -> B -> C: call
edge from:A to:B "static"	edge from:A to:B "static"
: Ready under [] API	initial component body
/ or \| under [] API	attached text description
[.] Label (id) ~opacity-75	named styled primitive
(.) / <.> / <<.>> / ((.))	circle / hex / diamond / ellipse primitive
/// Stage	# stage: Stage
## n. Note	# note n: Note
### Overlay 10s..	# overlay 10s: Overlay
repeat / parallel + indentation	block closed by dedent
block / *repeat + indentation	named / detached block closed by dedent
?tree "Title" =spine / =mindmap / =decision	tree block

Examples

Outline

Backend
  - api
  - worker
  (postgresql) DB

group "Backend"
  component api
  component worker
  component db "DB" shape:database icon:postgresql
end

Loading preview