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 declarations, 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

Colors

shape:server,#warning
<icon:check #success>
style:#7c3aed

Details

Edge

api -> db: query

Details

State

api: Ready

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

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, or hierarchy. Edges and state updates still create undeclared components automatically.

Syntax

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

Details

Parameter	Description	Example
key	Addressable identifier.	`component api`
"Display Name"	Quoted label.	`component api "API"`
shape:shape,tier	Visual shape and size tier.	`shape:server,lg`
Shapes	default, circle, database, hexagon, diamond, note, actor, icon, cloud, external, browser, server, funnel, code.	`shape:cloud`
Tiers	xl, lg, md, sm, xs. Modifier-only shape tokens use the default shape.	`shape:lg`
many	Render one logical component as a stacked or repeated visual.	`shape:server,many`
#color	Theme color token or hex color for visual emphasis.	`shape:hexagon,#warning`
icon:name,badge	Icon or badge metadata.	`icon:server,badge`
[tags]	Short visual metadata; tags can carry colors.	`[backend, public #info]`

Examples

Component Declaration

# Declarations set labels, shapes, icons, and tags.
component api "API" shape:server,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,#info icon:server,#info [public #info]
component worker "Worker" shape:hexagon,#warning icon:cpu,#warning [retry #warning]
component db "Database" shape:database,#success icon:database,#success [healthy #success]

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

Loading preview

Edges

Edges define interactions between components. Labels are plain text; rich data belongs in component or artifact state.

Syntax

source -> target: label

source -> middle -> target: label

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

source -> target state: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 sets visible content on a component. Use plain text for simple status and structured or Markdown state when the component has useful internal detail.

Syntax

component: content

component:
  Markdown body

component:
  <pairs>
    status: ok

component state:destroyed: content

component <state:destroyed>: content

Details

Form	Description	Example
Text	Simple status.	`api: Processing`
Structured	Decorated state body.	`api: <pairs> status: ok`
Markdown body	Indented Markdown after a state opener.	`api:`
Timeline state	Transient node treatment.	`session state:destroyed: removed`

Examples

Component State

# State updates change what a component displays.
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	`shape decision diamond: 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.
<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.
<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.
<code:json>	`api: <code: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,stroke,tier,#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 shape: rect, circle, diamond, hex, or ellipse.	`shape:ellipse`
stroke	Border stroke: solid, dashed, or dotted.	`shape:rect,dotted`
tier	Size tier metadata for the group treatment.	`shape:rect,lg`
#color	Theme color token for the border.	`shape:rect,#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 label sections of the timeline for navigation. Description lines immediately after the stage become stage context.

Syntax

# stage: Title

# Description line

Examples

Stage

# Stages create timeline navigation sections.
# 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 a component or group with side markers.

Syntax

text "Display Text"

text @target |
  Markdown body

text @target marker:|
  Markdown body

text @target |
  <pairs>
    status: ok

text @target style:rect,#info ->
  Markdown body

// Design note

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 ->`
marker:	Property form for the same marker options.	`text @api marker:\|`
Style	Text container metadata.	`style:rect,#info`
Design note	Canvas-scoped markdown shorthand.	`// Quick note`

Examples

Standalone Text

text "Request Flow"

Loading preview

Full text example

Shapes

Shapes add primitive canvas geometry independent of topology nodes.

Syntax

shape circle "Label"

shape id rect style:dashed,#color

shape id ellipse @target style:#warning "Label"

shape id diamond:
  Markdown body

shape id diamond:
  <pairs>
    status: ok

Details

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

Examples

Circle Shape

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,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`
arrows	Draw directional connectors between tree items.	`shape:spine,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--

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.
$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 one-way authoring shorthand in the editor. It expands into a FractalForm script before runtime parsing.

Syntax

Group
  - member

[,browser] Web

[globe,browser] Web

A>B: call

== Stage

## n. Note

### Overlay 10s..

/ @api -> note

Details

Quick Form	Converts To
Label	group "Label"
- api	component api
[,browser] Web	component web "Web" shape:browser
[globe,browser] Web	component web "Web" shape:browser icon:globe
(postgresql) DB	component db "DB" shape:database icon:postgresql
A>B: call	A -> B: call
== Stage	# stage: Stage
## n. Note	# note n: Note
### Overlay 10s..	# overlay 10s: Overlay
/ @api -> note	text @api ->

Examples

Outline

Backend
  - api
  - worker
  (postgresql) DB

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

Loading preview