Spayscript Syntax & Grammar

Design Philosophy

Spayscript is built on one idea: write less, express more. You describe what you want — the system figures out sizes, colors, and positions automatically.

• No hex codes. Use semantic color names like color: blue — the system resolves a coordinated fill, stroke, and text color.
• No hardcoded sizes. Never write width: 360 or height: 80 — containers and nodes auto-size.
• No version preamble. There is one grammar. Just write your diagram.
• Inline [ ] attributes. All styling, layout, and config go in a single lightweight bracket block — not verbose brace blocks.

The Minimal Example

A complete diagram in 3 lines. No sizes. No hex. No config:

123"API Gateway" [icon: api gateway, color: blue]"Database" [icon: postgresql, color: red]"API Gateway" -> "Database": SQL

Nodes — Quoted Strings

Every element is declared by its label text in double quotes. The ID is auto-derived (slugified) from the label. Inline attributes go inside [ ]:

12345"Web Client"                              // plain shape, auto-id: web-client"Web Client" [color: blue]               // colored shape"Database" [db]                          // variant shorthand → database shape"Load Balancer" [icon: loadbalancer, color: blue]  // icon node"Attention Block" [ml: attention, color: purple]   // ML layer node

Named Colors

Instead of hex codes, use semantic color names. The compiler resolves each name to a coordinated fill + stroke + text triple tuned for both light and dark themes:

123456"Frontend" [color: blue]      // clear sky palette"Backend"  [color: green]     // fresh sage palette"Database" [color: red]       // warm coral palette"Auth"     [color: purple]    // soft violet palette"Worker"   [color: orange]    // warm amber palette"Neutral"  [color: slate]     // cool grey palette

Aliases: gray/grey/neutral → slate, danger/error → red, success/ok → green, info/primary → blue, warning/warn → orange, accent/secondary → purple

Shape Variant Shorthands

A bare identifier inside [ ] that matches a known variant sets the shape type:

123456"Primary DB" [db]       // → database shape"API Step" [process]    // → process shape"Branch" [dec]          // → decision diamond"Start" [term]          // → terminal shape"Payload" [data]        // → data parallelogram"Report" [doc]          // → document shape

Comments

Any text following // on a line is treated as a comment and ignored by the compiler:

12// This is a comment"API Gateway" [color: blue]  // inline comment — ignored

Flat Namespace

All node IDs share one flat global namespace. Even nodes inside nested containers must have unique IDs. This means you can always reference any node by its simple ID — no dot-notation path required:

1234567// ❌ INVALID — duplicate IDs (both become "web-node")stack "Cluster A" [color: blue] { "Web Node" }stack "Cluster B" [color: green] { "Web Node" } // ✅ VALID — unique IDsstack "Cluster A" [color: blue] { "Web Node A" }stack "Cluster B" [color: green] { "Web Node B" }