Canvas DSL
Canvas DSL describes a small stepwise diagram. Use it for at most four boxes/icons in a linear flow. Groups, branching arrows, layered architectures, and larger diagrams use HTML/CSS; static AWS architecture can use a Draw.io export.
Example
---
@type: canvas
@canvas-id: request-flow
## Request flow
:::canvas
box client "Client" at 40,150 size 100,50 color accent step 1
box api "API" at 220,150 size 100,50 color blue step 2
box store "Store" at 400,150 size 100,50 color green step 3
arrow client -> api "request" step 4
arrow api -> store "write" step 5
:::
Elements
box <id> "<label>" at <x>,<y> size <width>,<height> color <color> [step <n>]
circle <id> "<label>" at <x>,<y> radius <r> color <color> [step <n>]
icon <id> "<service-or-path>" at <x>,<y> size <s> [step <n>]
arrow <from-id> -> <to-id> "<label>" [color <color>] [style dashed|dotted] [step <n>]
group "<label>" containing <id1>, <id2> [color <color>] [step <n>]
The compiler resolves the named colors accent, blue, green, yellow, red, and cyan. Use six-digit hex colors for other values.
The parser recognizes groups, but current authoring policy sends grouped architecture to HTML/CSS. Icon names resolve through the shipped icon mapping; use a verified local path for a custom icon. Do not assume every marketing service name is an accepted alias.
Steps and routing
Elements without step appear immediately; numbered steps reveal them in sequence. Up/Down uses the registered Canvas controls. Arrows use the compiler's routing and anchors, but automatic routing does not replace overlap inspection. The validator checks visual-element complexity and overlapping box/icon bounds; groups contribute to the complexity count. Its branching check does not currently recognize the from_id field produced by the demonstrated arrow syntax. Apply the group/branching authoring policy explicitly; a clean validation report is not proof that policy was checked.
Extensions
:::canvas mermaid and :::canvas js provide integration paths where supported. Preset syntax is parsed into a CanvasPresets lookup; it only works when the corresponding runtime preset is actually supplied. A parsed preset name is not proof that the bundle includes its implementation.
HTML alternative
Use .flow-h/.flow-v, .flow-group, .flow-box, .flow-arrow, and .icon-item with semantic theme tokens. data-fragment-index supports ordered reveal. Calculators and simulations use actual HTML controls and script state, tested in the browser.