DGMO Language Specification

Authoritative reference for the DGMO diagram language. This document describes what is valid syntax. If it is not in this document, it is not valid DGMO.

1.0 freeze: DGMO syntax freezes at the 1.0 release tag — after 1.0, any change to valid syntax is a major-version bump. Pre-1.0 the language was deliberately tightened toward one canonical form per construct; the last cleanups shipped through 0.44 (channel-named value ramps in 0.42, chart-type consolidation 50→44 + alias removal in 0.43 per #23–28, chord folded into arc + layout chord in 0.44). Retired legacy/ambiguous forms include: bare description, PERT analysis, C4 bare same-line tail, timeline positional duration (→ duration:), gantt legacy scheduling, and the standalone chord / chart-type-alias keywords; bare tag values now auto-assign a palette color. Each removed form fails loudly — a generic parse error, or a targeted hint where one survives (e.g. a C4 bare tail names the description: fix and the diagram does not render). See dgmo-language-spec-decisions.md § “1.0 Freeze Decisions”.

Diagnostic codes (0.43.0, decision #28): the dedicated E_*_REMOVED family was deleted for minimal surface — removed forms fail however they naturally fail, not via a named code. Treat every E_*_REMOVED reference below as historical; re-verify behavior against the parser. Note two forms are deliberately accepted, not errors: data-row numeric values may use thousands-grouping commas (1,000 → 1000) or underscores (1_000 → 1000), and separator commas between values are tolerated (values are canonically space-separated). (2026-07-05: the C4 bare-tail case, which regressed to a silent drop after #28, was restored to a hard error — see §“C4”.)

Table of Contents

1. Universal Constructs
2. Universal Name Handling
3. Sequence Diagrams
4. Infrastructure Diagrams
5. Flowchart Diagrams
6. State Diagrams
7. Org Charts
8. C4 Architecture Diagrams
9. Entity-Relationship Diagrams
10. Class Diagrams
11. Kanban Boards
12. Sitemap Diagrams
13. Gantt Charts
14. Boxes and Lines Diagrams
15. Timeline Diagrams
16. Data Charts
17. Visualizations
18. Mindmap Diagrams
19. Wireframe Diagrams
20. Tech Radar Diagrams
21. Cycle Diagrams
22. Journey Map Diagrams
23. Pyramid Diagrams
24. Ring Diagrams
    • RACI Matrices
    • Map Diagrams
25. Colon Usage Summary
26. Authoring Rules (Generators Read This First)
27. Swimlane Diagrams
28. Event Line Diagrams
29. Version-Control Diagrams
30. Block Diagrams
31. Sketch Diagrams
32. Family Diagrams

1. Universal Constructs

These patterns are shared across all or most diagram types.

1.1 Chart Type Declaration (First Line)

<chart-type> [Title]

• Space-separated, NO colon
• Title is optional
• Examples: bar Treasure Hauls, sequence Auth Flow, gantt Product Launch

1.2 Comments

// comment text

• Full-line only (no inline comments after code)
• # is NOT a comment character
• One documented carve-out: PERT (§13A) accepts both # and //, full-line and trailing-after-whitespace — the only chart type with inline comments. Everywhere else # is content.

1.3 Tag Declarations

tag GroupName as <alias>
  Value1 color
  Value2 color

• tag keyword, NO colon
• Name: a single identifier ([A-Za-z_][A-Za-z0-9_-]* — letters, digits, underscore, hyphen), e.g. Team, Trust-Zone. For a multi-word display name with spaces, quote it: tag "Trust Zone" as tz. The quoted text becomes the legend label; internally it slugs to a DOM-safe key (Trust Zone → trust-zone) used for assignment, matching, and active-tag. Always pair a quoted name with an as <alias> so values stay terse (Node tz: client). An unquoted multi-word name is ambiguous (the trailing word is read as an alias) and is not a spaced name.
• Alias: optional postfix as <alias> per §2A (universal alias syntax — [A-Za-z][A-Za-z0-9_]{0,11})
• Inline values also supported: tag Priority as p Low green, High red
• Color follows the value as a bare trailing token (see §1.5). Capitalize the color word (Red, Yellow) to keep it as a literal value with no color.
• Color is optional — a bare value auto-assigns a palette color. A value declared without an explicit color (High, not High red) is not an error: at parse time it is given a deterministic categorical color drawn from the recognized color names (red, orange, yellow, green, blue, purple, teal, cyan — neutrals excluded), cycling in that order. Auto-assignment skips any color already used by an explicit entry in the same group (including explicit entries that appear after the bare one), so High / Low red gives High a non-red color. An explicit Value color always wins. This lets you sketch a group as a plain value list (tag Priority as p High, Med, Low) and let the palette pick distinct colors. This is the language’s single canonical categorical rotation — chart sections that rotate colors (e.g. ring layers, §24.6) cite this order; pyramid’s primary-mix ramp (§23.6) is the one documented exception.
• First entry is the default — applied to nodes that don’t carry an explicit value for this group. Reorder the entries to change the default. Three charts opt out of first-value defaulting: sketch and body render untagged shapes neutral gray (meaning is absent until assigned — decision #33), and swimlane untagged nodes fall back to the lane shade (tag → symbol → lane cascade, §27.7)
• Must appear before diagram content
• none is reserved — cannot be used as a tag group name
• The first declared group is active by default — declaring a tag group colours nodes by that group immediately; the legend renders it expanded/active with the other groups as collapsed pills. active-tag <GroupName> is therefore only needed when ≥2 colouring dimensions exist (multiple tag groups, or a group plus a score ramp) and you want one other than the first-declared active. With a single tag group, active-tag is redundant. In the app a reader can click any legend pill to flip the active group (live preview only — it does not edit the source)
• Opt-out: active-tag none suppresses all tag colouring — every node renders neutral and all groups stay collapsed. This is the opposite of omitting active-tag (which activates the first group); use it to author the quiet, no-colour default deliberately (case-insensitive: none, None, NONE)
• Legacy bare shorthand (tag Priority p) and explicit alias keyword (tag Priority alias p) emit E_TAG_SHORTHAND_REMOVED per TD-18

Diagram types that support tags: sequence, infra, state, org, mindmap, c4, er, kanban, gantt, sitemap, timeline, boxes-and-lines, swimlane, pert, journey-map, treemap, map, event-line, block, sketch, family, body, bracket

This list is enforced, not hand-maintained: it must match TAG_SUPPORTING_TYPES in dgmo/src/completion.ts (derived from STRUCTURAL_KEYWORDS, the parser-validated source of truth) and is checked by the completion-conformance suite.

Strict ordering: tag declarations must precede content

Tag declarations (and their aliases) feed the chart’s reserved-key registry (§1.4.3) — that registry must be finalized before the parser enters content-line mode. DGMO is a single-pass parser with no lookahead, so a tag alias declared after the first content line is unreachable: any earlier line that could have used the alias was already classified under the pre-declaration registry.

A tag block appearing after the first non-tag content line emits E_TAG_DECLARED_AFTER_CONTENT. The declaration is still parsed (so the legend renders), but no upstream content lines retroactively pick up the alias.

sequence Voyage

tag Concern as c                            // ✅ before content
Alice -login-> Bob c: Auth

[Backend]
tag Concern as c                            // ❌ E_TAG_DECLARED_AFTER_CONTENT

This applies uniformly across all chart types that support tags.

1.4 Metadata Grammar

DGMO has one metadata grammar that every chart type uses. Entity metadata may be written same-line after the name, or as indented lines beneath the entity. Both forms are valid wherever metadata is supported; per-chart-type preferred form is listed in §26.

// Same-line form (canonical for most chart types)
EntityName k: v, k2: v2
API Gateway c: Auth                          // name = "API Gateway"; meta = { c: Auth }
Alice -login-> Bob c: Auth                   // edge metadata, no delimiter
20bd Database Schema progress: 100           // gantt: leading-duration prefix preserved

// Indented form (canonical for org, c4; available everywhere)
API Gateway
  c: Auth                                    // attribute — `c` is a declared tag alias
  description: Main gateway

The | operator that delimited metadata in pre-0.18.0 DGMO is removed as a metadata delimiter. Before 0.43.0 a stray | emitted E_PIPE_OPERATOR_REMOVED; as of 0.43.0 (#28) that guard is gone, so a | outside its surviving uses (§1.4.5) is no longer a dedicated error — it falls through to normal parsing (treated as a literal / ignored).

1.4.1 Same-line form

The parser scans the line left-to-right and flips into metadata mode the first time it encounters a whitespace-delimited token whose shape is <key>: (a key followed by a colon, with the key matching the chart type’s reserved-key registry or a declared tag alias). Everything to the left of that token is the entity’s name region; everything to the right is comma-separated key: value pairs.

Foo k: v                       // name = "Foo",          meta = { k: v }
Foo k: v, k2: v2               // name = "Foo",          meta = { k: v, k2: v2 }
Foo green k: v                 // name = "Foo",          color = green, meta = { k: v }  (color peeled from name region — §1.5)
Foo as f k: v                  // name = "Foo",          alias = f, meta = { k: v }

Whitespace around : is tolerated — tokenization treats c: Auth, c :Auth, c : Auth, and c:Auth identically. The value start is after :, with leading whitespace trimmed.

Quoted values escape the comma terminator. Wrap a value in "..." when it contains commas.

Foo description: "My, complicated, value"        // meta = { description: "My, complicated, value" }
Foo description: "with spaces", color: red       // meta = { description: "with spaces", color: red }

No line continuation. Same-line metadata is single-line. A trailing comma on a metadata line is a parse error. For long metadata sets, use the indented form.

Empty values are dropped. Foo c: (no value) emits W_EMPTY_METADATA_VALUE and the key/value pair is discarded from the entity’s metadata.

Quoted names tokenize as one unit before the first-:-token scan. A colon inside a quoted name does not trigger the metadata cut.

"Auth: Service"                              // name = "Auth: Service" (single token)
"Order | Items" k: v                         // name = "Order | Items", meta = { k: v }

1.4.2 Indented form (reserved-key dispatch)

An indented line of shape key: value attaches as metadata to the parent entity only when key matches the chart type’s reserved-key registry or a declared tag alias. Otherwise, the line falls through to the chart type’s own grammar (class members, RACI role assignments, ER columns, function entries, sequence notes, etc.).

API Gateway
  c: Auth                                    // attribute — `c` is a declared tag alias
  latency-ms: 50                             // known-schema property (colon required — see §4.3)

Ship                                         // class
  + name: string                             // member — `+` prefix; not a reserved-key match
  description: Capital ship                  // attribute — `description` is reserved

[Departure]                                  // RACI phase
  Plot the course                            // task
    Cap: A                                   // role assignment — `Cap` is a declared role
    Nav: R

Indented lines without a colon remain structural children (sub-nodes, columns, dependencies, cards, etc.). ER columns (id int pk) are space-separated known-schema properties that don’t carry colons; the dispatch is unambiguous. Infra node properties require colons (latency-ms: 50) — see §4.3.

Drift warning. When an indented key: value line where key is in the reserved-key registry appears at the same indent level as preceding structural children, the parser emits W_ATTRIBUTE_AT_PARENT_INDENT — the attribute attaches to the parent above, but a reader could plausibly intend it to attach to the preceding structural child. The hint: indent further if you meant it on the preceding child.

1.4.3 Reserved-key registry

Each chart type publishes a closed set of reserved attribute keys. These keys, plus any declared tag aliases (§1.3), trigger metadata dispatch on indented lines and the same-line first-:-token cut. Everything else falls through to chart-specific grammar.

Keys not in a chart type’s registry are not metadata. Tag aliases declared via tag Group as x are added to that chart’s effective registry for the duration of the parse.

1.4.4 Diagnostic catalog

The *_REMOVED rows below were deleted in 0.43.0 (#28) and no longer fire — see the 0.43.0 update note at the top of this spec. They are kept here, marked, for historical reference.

1.4.5 Surviving uses of |

The | character is not reserved in DGMO 0.18.0; it survives as a literal in three specific contexts:

• Wireframe dropdown options: {Option A | Option B | Option C} — inside {...} braces, | separates dropdown options (§19.3).
• In-arrow label characters: A -file|name-> B — | inside an arrow label is preserved verbatim (§1.10).
• Quoted name characters: "Order | Items" — inside "..." quoted strings, | is a literal name character.

Outside these three contexts, | used to trigger E_PIPE_OPERATOR_REMOVED; as of 0.43.0 (#28) that guard is gone, so a stray | is simply parsed as a literal / ignored rather than flagged. dgmo migrate still mechanically converts legacy pipe content.

1.5 Color Suffixes

Color is set by typing the color name at the end of a label, lowercase. Example: Done green colors Done green. Eleven colors exist: red, orange, yellow, green, blue, purple, teal, cyan, gray, black, white. To use a color word as a literal label, capitalize it: Red stays as the word Red.

These eleven names are the ONLY valid colors. Hex (#e6194b), rgb(...)/hsl(...), and CSS keyword colors (crimson, pink, …) are NOT supported anywhere in DGMO — not on groups, series, nodes, edges, tags, or any other element. A hex or CSS value is rejected with an error diagnostic and the element falls back to its default / auto-assigned palette color. The only way to specify a color is one of the eleven names above. This is deliberate: a named color resolves to the right hex per active palette and light/dark theme, so the same source stays palette-portable — a hardcoded hex would not.

Label color           // bare trailing color token
Done green            // value=Done, color=green
Senior Engineer red   // value="Senior Engineer", color=red
Red                   // value=Red, no color (capitalized → escape hatch)

The universal rule — color trails the label:

Color is the trailing whitespace-delimited token of a label region, when that token (case-sensitive, lowercase) is one of the 11 names above. Otherwise the label region has no color.

The “label region” is everything left after the parser strips off structural terminators it owns: same-line metadata (§1.4.1), as <alias> postfix, numeric values, date ranges, structural brackets, arrow constructs. The color rule operates only on the label region — never on a raw line — so Tortuga Distillery orange 3000 is { label: "Tortuga Distillery", color: "orange", value: 3000 }: the parser splits off 3000 as the flow value first, then orange peels off as the trailing color.

Cut order is pinned. On any line that could carry all of (a) metadata, (b) an as <alias> postfix, and (c) a trailing-token color, the parser strips them in this order:

1. Metadata cut (§1.4.1) — the first <key>: token where key is in the chart’s reserved-key registry or a declared tag alias splits the line into name-region + metadata (left-to-right). Color tokens that appear inside a metadata value are NOT extracted as the entity’s color — they belong to the value.
2. Trailing-token color (§1.5) — applied to the name region. The last whitespace-delimited token, when it is exactly a lowercase color name from the 11-name palette, is peeled as color.
3. as <alias> postfix — stripped from the right-hand side of what remains of the name region. The alias is registered against the canonical name.

Step 2 runs before step 3 because in source order the alias sits between the label and the trailing color (<label> as <alias> <color>); peeling the color first exposes the alias at end-of-string. Both forms work, so Spring as s green and Spring green both produce the expected (alias, color) result.

Spring green c: Auth                  // name = "Spring", color = green, meta = { c: Auth }     — color is in name region (before metadata cut)
Spring c: Auth green                  // name = "Spring", meta = { c: "Auth green" }            — `green` is part of the metadata VALUE, not the entity color
Spring as s green c: Auth             // name = "Spring", alias = s, color = green, meta = { c: Auth }

To color the entity alongside other metadata, write the color before the metadata cut. To color something inside a metadata value, use the explicit color: key in metadata (the metadata value can contain a color word as text, but it never feeds back into the entity’s color slot).

Aliases come between the label and the color in the name region. as <alias> sits between the label and the trailing color token — <label> as <alias> <color>. After the metadata cut runs first, color is the trailing token of what remains of the name region.

Where the rule applies:

• Tag values: Done green, Blocked red. The color is optional here — a tag value with no trailing color (Done) auto-assigns a deterministic palette color at parse time (see §1.3). This auto-assignment is specific to declared tag-group values; everywhere else, omitting the color simply leaves the element uncolored.
• Kanban columns: [Done] green (color follows the closing bracket)
• Venn items: Swordsmanship as sw red (color trails the alias)
• Quadrant position labels: top-right Promote green
• Gantt / timeline eras and markers: era 1710 -> 1716 Rise green
• Data-chart series + data rows: series Cloud blue, Legacy red and North 1500 red
• Sankey nodes + link lines: Sugar Plantations green, Source -> Target 3000 red
• Cycle / pyramid / ring / RACI / boxes-and-lines node labels: Spring green
• ER tables
• Scatter [Category] headers and arc [Group] headers
• RACI phase headers + roles-block entries
• Swimlane lane lines
• Version-control branch declarations
• Bracket [Side] headers
• Map regions and POIs: Texas red
• Title lines of goal / countdown / bracket (see “Title-line accent” below)

Title-line accent. A trailing color token on the chart declaration line sets the chart accent on the types that have one: goal (meter/figure color, §34.5), countdown (figure tint, §36.1), and bracket (winner accent, §35 — its former accent <color> directive is a legacy alias). Other chart types currently ignore a title-line trailing color.

Long form color: <name> is reserved for multi-key metadata. Use color: <name> only when another metadata key (description:, span:, width:, quadrant:, …) needs to accompany the color. When color is the only thing being set, write it as a trailing token in the name region.

Spring green                          // canonical — color is the only metadata
Spring green description: First       // trailing-token color + same-line metadata
Spring color: green, icon: ❄          // long form REQUIRED when color rides with another key in metadata
-Label-> color: red, width: 6         // edges have no trailing-token slot; long form is the only path

One narrow exception accepts long-form-only color:

• Cycle edges (and any other edges that carry a color) — edges have no trailing-token slot, so color: <name> is the only form.

Journey-map personas follow the universal rule: persona Nadia green colors the persona green; capitalize the word (persona Nadia Green) to keep it as literal name text. The long form persona <name> color: <name> is also accepted.

Accepted tradeoffs:

• No typo diagnostics: an unrecognized trailing token is silently treated as label text. Done grren (typo) → { value: "Done grren", color: undefined }, no warning. Internal corpus has its own near-miss smoke test; user content gets no help.
• Case-sensitivity is the escape hatch: only lowercase recognized. Red, Yellow, Green stay as labels — useful for traffic-light tag groups that want the color word as the literal name.
• No edge color: edges on flowchart, state, and sitemap diagrams have no color slot. A -(red)-> B and A -yes-> B both render with the default theme color.
• 11-name palette is a frozen public contract: adding a 12th color name is itself a breaking grammar change because any user diagram that already has the new color word as a label would silently change behavior. See decision log.
• No hex / CSS colors: hex (#e6194b), rgb(...), hsl(...), and CSS keyword colors are rejected. Where a color is parsed from an explicit slot (e.g. a [group] header), a hex value emits an error diagnostic; where color comes from the bare trailing-token rule (which silently ignores any non-name), the hex token simply stays as label text. Either way it never colors the element.

1.6 Indentation

• Spaces or tabs (1 tab = 4 spaces)
• Determines hierarchy and block scope

1.7 Edge Notation — Prefer Indented-Under-Source

Many diagram types support both flat (Source -label-> Target) and indented forms for edges. Always prefer the indented form — it is more concise, avoids repeating the source name, and reads as a natural dependency tree:

// Preferred — indented under source
API
  -routes-> UserService
  -routes-> ProductService

// Avoid — repetitive flat form
API -routes-> UserService
API -routes-> ProductService

When a node has outgoing edges, declare the node first, then indent its edges below it. Use the flat form only for cross-links where the source node was already declared earlier — re-declaring a node just to indent an edge under it creates a duplicate.

Combining metadata with indented edges. Put same-line metadata on the declaration line and indent the edges below it — splitting metadata onto a separate node re-declaration emits a Duplicate node warning. Indented metadata (key in the chart’s reserved-key registry per §1.4.3) may also appear among the indented children, intermixed with edges; the parser dispatches per-line.

// Preferred — one declaration carries both metadata and edges
API description: Main gateway
  -routes-> UserService
  -routes-> ProductService

// Also valid — metadata on declaration line, more metadata indented alongside edges
API description: Main gateway
  tech: Node.js                      // indented attribute (reserved-key dispatch)
  -routes-> UserService
  -routes-> ProductService

// Avoid — declaring API twice produces a duplicate-node warning
API description: Main gateway
...
API
  -routes-> UserService

When mixing indented attributes and structural children, watch the indentation: an attribute line at the same indent as a structural child attaches to the parent (the node declared above), not to the structural child. The parser emits W_ATTRIBUTE_AT_PARENT_INDENT when an attribute follows a structural child at the same indent level — indent the attribute one more level if you meant it on the child.

Edge targets must already exist. A -> Target reference (or labeled variant) must point at an entity that has been declared on a previous line or is being declared inline by the edge itself (e.g. pert’s -> dest 1 2 4 forward declaration with durations). Bare -> Unknown to an undeclared entity emits a Target not found error. The same rule applies to group references: -> [GroupName] requires the group to exist (see §1.8).

Diagram types supporting indented-under-source: infra, flowchart, C4, ER, class, sitemap, boxes-and-lines, gantt, pert, swimlane, cycle, sketch, map (POI hub edges and route legs).

Map native edges are the one anti-carve-out: outside a route, indented -> dest is a parse error (§24B.6) — map native edges are flat-only.

1.8 Groups / Containers

[Group Name]
[Group Name] k: v, k2: v2

• Bracket-enclosed name
• Optional same-line metadata after the closing bracket (per §1.4.1), or indented attributes below (per §1.4.2)
• Indented content below belongs to the group
• Trailing-token color on groups — examples include kanban columns ([Column] green) and era/marker labels (era 1710 -> 1716 Rise green)
• Group references must be declared. Edges that target a group via -> [Name] require the group to be declared elsewhere in the file; group references do not auto-create groups (an undeclared group reference emits a Group not found error). Forward references — using a group before its declaration line — are not allowed.

Collapsing groups. The canonical form is a bare collapsed trailing flag on the group/container line (e.g. [Backend] collapsed, [Done] collapsed). The older collapsed: true metadata (same-line or indented) remains accepted as legacy. Wireframe’s flag-enum collapsed and block/sketch’s comma-list collapsed are the same token in their native grammars.

The authoritative support list, stated once here: sequence, infra, gantt, kanban, mindmap, pert, state, c4, event-line (eras), block, sketch, wireframe. treemap and timeline collapse is interactive-only (no source marker; view-state, decision #32). §26.3 and §26.7 defer to this list.

A group whose name ends in the word “collapsed” uses the standard capitalize/quote escape (same class as trailing colors): capitalize it ([Mission Collapsed]) or quote the name (["Mission collapsed"]) to keep the word as name text.

The collapsed flag is portable view-state: because it lives in the source text, every renderer (the app, the dgmo CLI, remark-dgmo, Obsidian, code-fence embeds) reproduces the collapsed view from the .dgmo alone — a diagram in a code fence looks the way its author left it, not fully expanded. In the app, collapsing/expanding a node writes/removes this marker in the source (the source stays the single source of truth). A runtime viewState.cg (share-link / live app state) is applied in addition to the source markers. (Mindmap honored this field starting 2026-07; see the decision log. The broader effort to give every view-state key a native spelling is tracked separately.)

1.9 Boolean Options

option-name          // on
no-option-name       // off

• Bare keyword = on; no- prefix = off
• Must appear before diagram content

Cross-cutting boolean directives (recognized in every chart type that has the corresponding rendering surface):

The three fill-* directives form one fill family and are mutually exclusive; when more than one appears, the last one wins. The family replaces the earlier solid-fill boolean (decision #46) — fill-solid is the exact successor. Charts whose fill encodes data ignore the family: map regions (choropleth — saturation is the data), infra severity tints, gantt progress bars, and tech-radar blips. A small group honors fill-solid but ignores fill-outline because hollowing the fill would erase the chart: the line/function area fill and sankey/chord ribbons (the surface is the flow). Everything else — including goal meters (hollow meter, colored rim, §34.5), heatmap cells (bg cells, full-intent ramp strokes), countdown chips (§36), clock’s decorative surfaces (state tints like daylight stay), bracket, body, quadrant, and arc — renders outline for real (decision #47). Under fill-outline, colorless/untagged shapes render with a strengthened neutral outline so they don’t vanish against the background.

Layout direction is likewise cross-cutting: every direction-bearing chart accepts the bare booleans direction-lr / direction-tb (last-one-wins), each chart keeping its own sensible default — flowchart, org, and c4 default TB; infra, state, sitemap, boxes-and-lines, swimlane, pert, version-control, and event-line default LR (event-line accepts only direction-lr; direction-tb is a reserved seam); clock defaults rows (direction-tb), where direction-lr selects columns mode. The key+value form direction LR|TB is accepted legacy. Cycle’s direction-counterclockwise belongs to the same boolean family.

Example: no-title (all chart types with a banner title).

The fill-* family states one treatment for the whole chart, so it can never express a hierarchy within one. That axis — which elements are figure and which are ground — is the emphasis family (highlight / dim, §1.11). It is not a boolean family: both directives take a name list, so they live in their own section.

1.10 In-Arrow Message Labels

An in-arrow label is the text embedded inside an arrow between the opening delimiter and the arrow token, as in A -label-> B.

A -label-> B
 ^ ^---^ ^^
 | |     ||
 | |     |+- destination id
 | |     +- arrow token
 | +- label text (plain, no markdown)
 +- opening delimiter (matches arrow type)

Chart types that support in-arrow labels: sequence, flowchart, state, infra, c4, er, class, boxes-and-lines.

Cheat sheet

// happy-path: labels are plain text with punctuation allowed
A -location[]-> B          // label = "location[]"
A -a[b]c-> B                // label = "a[b]c"
A -{json}-> B               // label = "{json}"

// unicode: all scripts and emoji preserved verbatim
A -café-> B
A -日本語-> B
A -🎉-> B

// punctuation is literal — no markdown interpretation
A -(parenthetical)-> B      // label = "(parenthetical)"
A -*emphasis*-> B           // label = "*emphasis*"       (NOT bold)
A -`code`-> B               // label = "`code`"           (NOT a code span)

// forbidden: -> and ~> substrings inside a label
A -uses -> chain-> B        // ERROR (E_ARROW_SUBSTRING_IN_LABEL)
// fix: rephrase the label, or move detail to same-line metadata
A -uses to chain-> B
A -uses-> B detail: chains to next

// migration from pre-gauntlet (legacy) syntax
A -Makes calls [HTTP]-> B   // label is now the FULL "Makes calls [HTTP]"
A -Makes calls-> B tech: HTTP   // preferred: technology on target metadata

Character-set contract

• Allowed: any Unicode codepoint except the forbidden list below. Brackets [] {} (), pipes |, quotes "' , backticks, punctuation, digits, emoji, ZWJ sequences, combining marks — all pass through as literal characters.
• Forbidden substrings: -> and ~>. These terminate the arrow. If you need them inside a label, rephrase it or move the detail to same-line metadata (A -uses-> B detail: chains to next); there is no escape mechanism.
• Forbidden characters: C0 control characters U+0000–U+001F except U+0009 (tab), and U+007F (DEL). Silent renderer breakage and log-injection surface — no legitimate use case.
• Whitespace: leading and trailing whitespace is trimmed; internal whitespace runs (including tabs, non-breaking spaces, and zero-width spaces) are preserved, never collapsed.
• Plain text only: no markdown interpretation. *foo* renders as *foo*, not italicized. [label](url) renders as literal [label](url), not a hyperlink. Clickable URLs belong in notes, not in in-arrow labels.
• HTML-safe: all renderers emit label text as a DOM text node. <script>alert(1)</script> renders as literal text — the entire label is a sequence of codepoints, not a markup fragment.

Edge color is not a feature

Edges on flowchart, state, and sitemap diagrams have NO color slot. A -(red)-> B is a literal label with text (red); A -yes-> B and A -no-> B no longer auto-color the arrow. Arrows render with the default theme color, period. To color a node, use tags (§1.3).

Sankey link lines DO accept a trailing-token color, because the link itself carries data:

Sugar Plantations -> Tortuga Distillery 3000 red    // link is colored red

Migrating from pre-gauntlet syntax

One legacy form changed with this spec:

1. C4 trailing [technology] sugar is removed. A C4 arrow like -Makes calls [HTTPS]-> API used to extract HTTPS as the technology annotation. The full Makes calls [HTTPS] is now the label. Use the same-line form for technology: -Makes calls-> API tech: HTTPS.

No code migration is required for in-arrow label character escaping — any label that was valid before remains valid, with one exception: if your label happened to contain the literal substring -> or ~>, the parser now rejects it with E_ARROW_SUBSTRING_IN_LABEL. Move those labels to the post-colon form.

See also

• Engineering rationale, decision log, and party-mode trade-offs: dgmo-language-spec-decisions.md → “In-Arrow Message Labels”.

1.11 Emphasis — highlight / dim

Every diagram has a background element — losses, “other”, last year’s line, the control group — that must stay visible without competing for attention. Emphasis is the directive family that says so.

highlight <Name>[, <Name>…]     // the named elements are the figure; everything else recedes
dim <Name>[, <Name>…]           // the named elements recede; everything else is untouched

Both are chart-level directives, written on their own line anywhere in the diagram — never a trailing token on a data row. The line-trailing bare-token slot already belongs to color (§1.5), and on a chart like sankey a node is named by many link lines and declared by none, so there is no single row a per-element modifier could live on.

The two forms are mutually exclusive and last-one-wins, the same rule the fill-* family follows (§1.9). Stating both is contradictory, not additive.

Chart types that support emphasis:

Every further chart type is a separate decision — the family is not silently available elsewhere. On a chart type that has not adopted it, highlight/dim are not directives and the line is read as ordinary content.

What dimming does

A receded element is drawn at reduced opacity, multiplied onto the paint it already had. It is never recolored.

• Hue survives, so emphasis composes with color instead of competing with it — a receded brand-red flow is still red. This is precisely why receding cannot be spelled by recoloring an element gray: gray is a full-weight palette color (§1.5), and spending the color slot on it destroys the element’s identity.
• Where a baseline translucency already exists (sankey ribbons), the dim multiplies it rather than replacing it. Replacing would render dimmed ribbons more solid than undimmed ones.
• Shapes and text recede by different amounts. Shapes carry the hierarchy; labels only need to stop competing, so they keep a legibility floor. The requirement is “recede”, not “remove”.
• The result is a baked attribute in the rendered output — no stylesheet, no script, no hover. PNG and SVG exports carry the emphasis exactly as the preview shows it.

There is no numeric opacity control. Two states — figure and ground — are the whole hierarchy a diagram can carry legibly, and the language spells states with named tokens rather than tuned values (the same reason it has no hex colors).

highlight lights a story, not a single element

highlight is the dual that names the foreground and derives the background from it. What counts as foreground is more than the named element alone: each chart type extends the named elements to the structure that explains them.

• family lights the named person’s bloodline — that person plus all ancestors and all descendants.
• sankey lights the named node’s flow closure — everything upstream that feeds it plus everything downstream it feeds. Without this, highlight Barrel Aging would recede Barrel Aging’s own inflows, deleting the explanation the highlight exists to give.

dim deliberately takes no such closure. dim Spoilage recedes exactly Spoilage, not everything that feeds it — which on most charts is nearly everything. The duals are asymmetric because their intents are: highlight names a story, dim names one thing to push back.

Which form to reach for depends only on which list is shorter. Use dim when one or two elements should recede; use highlight when one story matters and the rest is context.

Naming elements

dim Spoilage                    // one element
dim Ship Provisions             // ONE two-word element
dim Spoilage, Ship Provisions   // two elements — the comma is authoritative
highlight Barrel Aging

• The comma is the list separator and is authoritative whenever it appears.
• Without a comma, the whole argument is read as one name, because element names routinely contain spaces. Only if that phrase matches nothing is it re-read as whitespace-separated names, so dim Spoilage Losses still works — but a comma is the reliable way to name several.
• Matching is case-insensitive and whitespace-normalized: emphasis names an element you already typed elsewhere in the diagram, so it does not demand an exact retype.
• A name matching no element is reported as a warning and ignored. A directive whose names all miss resolves to no emphasis at all — a typo must never blank the chart.

Not supported where every element is load-bearing

Emphasis restages a diagram; it must not misreport one. Chart types whose every element carries the reading by construction do not take the family: goal meters, countdown, clock, wireframe (fidelity, not emphasis), quadrant, and map choropleth (position and saturation are the datum — a receded region reads as a lower value). The same charts whose fill encodes data and therefore ignore the fill-* family — infra severity, gantt progress, tech-radar blips — are excluded for the same reason.

Reserved leading tokens

On a chart type that supports emphasis, highlight and dim are reserved as the first token of a line. An element genuinely named “dim …” needs the usual escape — capitalize it or quote it — the same hazard class as trailing colors (§1.5) and bare collapsed (§1.8).

See also

• Engineering rationale and the rejected alternatives (per-element trailing token, numeric opacity, guidance-only): dgmo-language-spec-decisions.md → decision #49.

2. Universal Name Handling

DGMO uses one rule for entity names across every chart type. Names accept spaces verbatim. Equality is forgiving — case-insensitive and whitespace-collapsed. The first-seen casing/spacing wins for display. Quoting is on-demand — required only when a name contains a reserved character.

2.1 Pinned Algorithm

Two names are the same entity when they reduce to the same key under this algorithm:

1. NFC normalize the input
2. Replace runs of Unicode whitespace with a single ASCII space
3. Trim leading/trailing whitespace
4. Case-fold via toLocaleLowerCase('en-US')

'Auth Service', 'auth service', 'AUTH\tSERVICE', and ' auth service ' all normalize to 'auth service'. The first declaration wins for the display label. Subsequent re-declarations with a different casing or spacing fold into the first and emit I_NAME_MERGED (warning) so the divergence is visible to the author.

The locale is pinned to en-US to keep behavior stable across build environments — language-neutral case folding silently diverges on Turkish dotted/dotless I and German ß the moment the default locale changes. The shared utility lives at dgmo/src/utils/name-normalize.ts; every parser imports from it so normalization can never drift between chart types.

2.2 Reserved Characters

Bare names accept letters, digits, spaces, and hyphens. The following characters are reserved and require "..." quoting if you want them in a name:

There is no "-inside-" escape — names cannot contain a double quote.

2.2a Quoting + Alias + Metadata — Combination Constraints

Bare names compose freely with as <alias> (§2A) and same-line metadata (§1.4) on the same declaration line. Quoted names are more restricted: the following combinations are rejected in current parsers and should not appear in generated DGMO.

Workarounds when you need both quoting and aliasing:

• Quoting exists to escape reserved characters in a name. If the only reason for quoting is multi-word, drop the quotes — bare names already accept spaces and hyphens (Auth Service as a is valid).
• If the name genuinely needs a reserved character (e.g. | or :), keep the quotes and drop the alias — references can use forgiving normalization (§2.1) to match the full quoted name.

2.2b Sequence Participants — Declaration Forms

Sequence has an additional constraint layered on §2.2a: standalone participant declarations (without is a <type>) accept only the bare-name-plus-optional-metadata form. Anything else needs the typed declaration form.

Rule of thumb for sequence: if a participant needs an alias, a quoted name, or both, declare it with is a <type> (use is a person or another valid type from §2.6). Bare implicit declarations are only for simple cases.

Bare and typed declarations may be freely interleaved in the declaration preamble — a typed line such as User is an actor does not close the window for subsequent bare names. The bare-declaration window closes at the first message, section (== … ==), or block keyword (if/loop/parallel); after that, a bare word is reported as a stray line rather than registered as a participant.

2.3 Side-by-Side Examples

2.4 Migration: aka Removed

Sequence’s Name is a type aka Alias modifier is removed. The forgiving-normalization rule above handles casing/spacing variants; short-code aliasing for genuinely-different tokens is now the universal as postfix — see §2A.

// before — removed
Alice is an actor aka Authenticator

// after — universal alias (when a short-code is wanted)
Alice is an actor as a

Encountering \baka\b in a participant declaration produces E_AKA_REMOVED with a migration hint in the message.

2.5 Carve-Outs by Design

These are intentionally outside the universal rule:

• D3 chart data rows (slope, venn, quadrant, arc) — labels in data rows are not entity names; they participate in the chart’s data model rather than the entity-graph that universal name handling governs.
• tags: and import: directives in org — values are file/tag references, not entity names. Normalizing them would silently change what file is imported or what tag is referenced.
• Flowchart and state shape brackets [], (), {}, <> — these are shape sigils, not name quoting. The text inside is normalized as a name.
• Tag suffix-alias tag Priority p — the p is a tag-system alias, not an entity name. It’s resolved through a separate alias map and stays unaffected.

2.6 Error Catalog

I_NAME_MERGED warnings are suppressible per-line with an # allow-merge comment annotation at the call site for intentional merges.

See also

• Engineering rationale: dgmo-language-spec-decisions.md
• Implementation phases (A–D landed; E in progress): _bmad-output/implementation-artifacts/tech-spec-universal-name-handling.md

2A. Universal Aliases (as keyword)

A single postfix syntax — Name as <alias> — applies anywhere a name appears across every chart type with named entities. Replaces the prior tag-shorthand and venn alias keyword forms with a uniform rule.

2A.1 Syntax

sequence
Alice is an actor as a
Bob is a database as b
a -hello-> b
b -ack-> a

infra
[Edge] as edge
  Cloudflare
[Origin] as origin
  AppServer
edge -routes-> origin

venn
Swordsmanship as sw red
Navigation as nav blue
sw + nav Sea Raiders

tag Priority as p
tag Concern as c

2A.2 Rules

• Token shape: [A-Za-z][A-Za-z0-9_]{0,11} — letter start, letters/digits/underscore, length 1–12. Case-sensitive: pm and PM are distinct aliases.
• Modifier order on declarations: <name> [is a type] [as <alias>] [color] [key: value, …]. Color is the trailing token of the name region; same-line metadata (§1.4.1), when present, follows and is comma-separated.
• Strict ordering: aliases must be declared on or before first use. E_ALIAS_BEFORE_DECL flags out-of-order references.
• Flat global namespace: one alias literal has exactly one binding per source.
• Shape/type inference reads canonical: *Service inference rules fire on the resolved canonical, never on the alias.
• Aliases are NEVER UNH-normalized — they are exact-match ASCII short-codes. Unicode canonicals (Цена as p) work because normalization applies to the canonical only.
• Reserved tokens that cannot be used as aliases: DGMO grammar keywords (as, is, tag, alias, aka) plus chart-type tokens (bar, flowchart, venn, …). English articles (a, an, the) are NOT reserved — Alice as a is valid.
• SaaS-naming is safe: Storage as a Service, Backend as a Service do not match the alias regex (the trailing token can never reach end-of-line) — they parse as canonicals untouched.

Two charts deviate from the alias token shape: clock as <label…> accepts multi-word, punctuation-bearing labels that DO render as the row label (as Dani (NY) — decision #43), and map keeps as as a non-rendering ≤12-char routing token, using label: for multi-word display names (§24B.14).

2A.3 When to use aliases

Aliases earn their keep on names that repeat 3+ times. Single-use names should not be aliased. Two- and three-character source names rarely benefit. Aliases should aid comprehension, not obscure it.

2A.4 Universal Name Handling vs. Aliases

• UNH = same-name typo tolerance. Alice ≡ alice ≡ ALICE ≡ Alice (trailing space). Author intent is the same string with cosmetic variation.
• Aliases = different-token short codes. pm ≡ Product Manager. Author intent is two distinct strings bound at declaration time.

2A.5 Migration from legacy syntaxes

Pre-1.0 hard break — no compat shim:

Diagnostics:

• E_TAG_SHORTHAND_REMOVED fires on legacy bare tag shorthand.
• E_VENN_ALIAS_KEYWORD_REMOVED fires on legacy venn alias keyword.

Internal-fixture migration is automated via dgmo/scripts/migrate-as-aliases.mjs (see also the CI guardrail dgmo/scripts/lint-no-legacy-alias.sh).

2A.6 Diagnostic Catalog

See also

• Engineering rationale: dgmo-language-spec-decisions.md → TD-18
• Tech-spec: _bmad-output/implementation-artifacts/tech-spec-universal-alias-syntax.md

2B. Universal Date Handling

Every chart type that reads a date accepts the grammar below. Input is liberal; dates are stored internally as ISO, so rendering, sorting, and snapshots stay byte-deterministic. Applies to gantt (§13), timeline (§15), event-line (§28), countdown (§36), and pert (§13A). Family (§32) uses year-grain only; clock (§37) has no date input.

2B.1 Accepted input formats

2B.2 Slash order — US month-first

Numeric slash/dash forms (7/4, 07-04) default to US month-first (MDY).

• The date-order dmy directive flips the whole document to day-first (7/4 → Apr 7). date-order mdy is the default.
• Out-of-range self-disambiguates regardless of the directive: 13/2 can’t be month 13 → Feb 13.
• Applies only to ambiguous numeric forms. Month-name forms (Jul 4, 4 Jul) and ISO are never affected by date-order.

2B.3 Year resolution — first match wins

A date without a year resolves through this ladder:

1. Explicit year on the date itself — wins outright.
2. year 20XX directive anywhere in the document — the base year.
3. Derived from a sibling dated row. Timeline/event-line carry the year forward from the nearest full date above and roll to the next year if a bare month-day falls earlier (Nov start → a later Jan row = next year). Gantt and pert are dependency-driven, so they instead anchor to a single base year (the first explicit-year date in the document, usually start / start-date).
4. Current render year — last resort, only when the chart has zero full dates anywhere. Emits a soft, non-blocking hint suggesting year 20XX for reproducibility. Suppressed by no-current-year, which instead makes a fully-bare chart a hard error.

Levels 1–3 never read the clock, so those charts are snapshot-stable. Only a chart with no full date at all touches the wall clock.

2B.4 Directives

Recognized in any date-bearing chart (colon-free; bare where boolean):

All three are position-independent (pre-scanned), so they may appear before or after the dates they govern.

Existing ISO diagrams are unaffected — the grammar is an additive superset and ISO output is byte-identical.

3. Sequence Diagrams

2.1 Participants

Name is a <type> [as <alias>] [position: N]
Name key: value

Types: actor, database, cache, queue (plus default — the plain rectangle, used when is a is omitted).

Type names in is a X are case-insensitive (is a Actor, is an ACTOR, is an actor all parse identically). Both is a and is an are accepted regardless of the type’s leading letter.

A participant named with a removed-type keyword (e.g. service -> User: hi declares a participant whose id is service) remains valid. The trim affects only the is a X declaration syntax, not name resolution.

Inference rules — the parser infers the type (and shape) from the participant name. Only use is a when the name does not match or you want to override:

Inference is intentionally conservative: only names whose role is unambiguous at a glance get a distinctive shape. Anything else falls through to the default rectangle. Adding new patterns should resist suffix catch-alls (e.g. *-er → service) that historically inflated the table and rarely held up across diverse diagrams.

Inference handles it (skip is a):

PostgresDB           // database (matches *DB)
Redis                // cache (exact match)
User                 // actor (exact match)
Kafka                // queue (exact match)

Inference would miss (use is a):

Vault is a database         // "Vault" matches no rule, but you want database
Notifications is a queue    // "Notifications" matches no rule

Names that previously inferred to a removed type — AuthService, WebApp, Cloudflare, API Gateway, Stripe, Webhook, Upstream — now fall through to default (plain rectangle). That is the intended outcome of the trim: the visual differentiation is gone because the underlying distinction did not pull its weight.

Removed Type Keywords (0.16.0)

The keywords service, frontend, networking, gateway, and external were removed in 0.16.0. Using any of them in is a X emits E_PARTICIPANT_TYPE_REMOVED (one diagnostic per offending line — the parser collects all errors in a single pass rather than stopping at the first):

// All of these fail to parse:
Auth is a service           // E_PARTICIPANT_TYPE_REMOVED
WebApp is a frontend        // E_PARTICIPANT_TYPE_REMOVED
LB is a networking          // E_PARTICIPANT_TYPE_REMOVED
API is a gateway            // E_PARTICIPANT_TYPE_REMOVED
Stripe is an external       // E_PARTICIPANT_TYPE_REMOVED

// Fix: drop the override — participant renders as default rectangle
Auth
WebApp
LB
API
Stripe

The trim is sequence-only — is a external / is a database / etc. remain valid in C4, infra, and org diagrams under their own taxonomies (see §7).

2.2 Participant Ordering

Participants are laid out left-to-right. The default order is first appearance in messages — the first participant mentioned in a message gets the leftmost position, and so on.

Declaring a participant (§2.2b) assigns its tag, type, or alias but does not pin a column — a declared participant that appears in a message is still placed by first appearance, in whatever order the arrows reach it. Declaration order decides placement only for participants that never appear in any message. So you can declare just the participants you need to tag (e.g. the External or Customer exceptions) without those declarations dragging them out of message-flow order; use an explicit position: when you do want to pin one.

Explicit position override:

Name position: N

• position is colon-keyed same-line metadata (§1.4) — the colon is required. The legacy bare-keyword form Name position N was removed; a surviving bare position N raises E_SEQUENCE_BARE_POSITION_REMOVED.
• 0 is leftmost, 1 is second from left, etc.
• Negative values count from the right: -1 is rightmost, -2 is second from right
• When two participants target the same position, the later one shifts to the nearest free slot
• Position overrides take priority over all other ordering
• May combine with other metadata (DB position: -1, role: Storage). When also using as <alias>, the alias precedes the metadata (Alice is an actor as a position: 1) — metadata runs to end of line.

Group coherence: members of the same group (§2.3) always stay adjacent. The group is placed where its first member would naturally appear in message order.

Priority (highest to lowest):

1. Explicit position: N
2. Group adjacency
3. First appearance in messages
4. Declaration order (for participants not mentioned in any message)

2.3 Participant Groups

[Group Name]
  Participant1
  Participant2

• Metadata goes outside brackets: [Backend] t: Eng

Collapsible Groups

[Group Name] collapsed
  Participant1
  Participant2

The bare collapsed trailing flag (§1.8) declares a group as collapsed by default (legacy: collapsed: true). Collapsed groups render as a single participant lifeline with the group name as label. A drill-bar accent bar on the participant box signals expandability.

• Messages to/from group members remap to the group lifeline
• Messages between members of the same collapsed group render as self-referential on the group lifeline
• Unlabeled internal returns between members are suppressed
• Notes attached to members display on the group lifeline
• Fragment blocks (if/loop/parallel) resize to reflect collapsed participant positions
• In the app, clicking the collapsed participant expands it; clicking an expanded group label collapses it
• Export/share and CLI rendering honor the collapse state

2.3 Messages (Arrows)

• Whitespace around arrows is optional: A-label->B works
• Labels can contain spaces, hyphens, special chars
• Labels cannot contain arrow chars (->, ~>)
• Same-line metadata: A -msg-> B c: Caching

2.4 Section Dividers

== Label ==
== Label

Trailing == is optional.

Section dividers exist to separate a diagram into two or more distinct phases (e.g. == Authentication == then == Checkout ==). Use them only when there is more than one phase to delimit — a lone divider above a single run of messages adds a redundant band and a title that just restates the diagram’s subject. If the whole diagram is one phase, omit the divider entirely and let the diagram’s own title (or the surrounding prose) carry the name.

2.5 Notes

note Text
note right Text
note left of ParticipantID Text

Multi-line notes use an indented body below the note heading:

note right of API
  - First bullet point
  - Second bullet point
  **Bold text** and *italic text*
  `inline code`
  [link text](https://example.com)
  https://example.com

Content formatting:

• - prefix on indented lines = bullet points
• Inline markdown: **bold**, *italic*, `code`
• Links: [text](url) and bare URLs (auto-truncated in display)

2.6 Structural Blocks

Sequence diagrams support three structural blocks: if, loop, and parallel. Blocks nest via indentation.

Conditional (if / else if / else):

if registered user
  User -login-> WebApp
  WebApp -authenticate-> Auth
else if guest
  User -browse-> WebApp
else
  WebApp -403 forbidden-> User

• else if (two words) introduces additional branches; you can have zero or more.
• else (no label) is optional and must come last.
• else if and else align with the opening if indent.

Loop:

loop until success
  Client -poll-> Server

Parallel (requires a label, does not accept else):

parallel fan-out
  Coordinator -task A-> WorkerA
  Coordinator -task B-> WorkerB

Common errors:

• elif foo → use else if foo
• else foo (label after bare else) → use else if foo
• loop and parallel blocks do not support else branches
• end (or deactivate/activate/autonumber) → not dgmo syntax. Blocks (and multi-line notes) close by dedenting, never with a terminator keyword; a bare end line is rejected. Activation is controlled by the activations option (§2.7), not per-message keywords.
• A tag/color on a message (A -msg-> B tag: x) → tags color participants, not messages. Declare a tag <Name> as <alias> group and assign <Participant> <alias>: <Value>.

2.7 Sequence Options

• no-activations — hide inferred activation bars (on by default)
• active-tag GroupName — set active tag group for coloring
• active-tag none — suppress tag coloring

4. Infrastructure Diagrams

4.1 Declaration

infra [Title]

4.2 Nodes

NodeName
NodeName key: value
NodeName as alias
NodeName as alias key: value
"Node name with | reserved chars"
"Node name with reserved chars" key: value

Nodes are plain names. Capabilities come from properties (see §4.3), not type declarations.

• Aliases (§2A): NodeName as alias binds a short alias used by edges and group references. Alias must start with a letter/underscore and be ≤12 chars.
• Quoted names: wrap the label in double quotes when it contains reserved chars (|, :). Multi-word names without reserved chars do not need quoting (webapp api gateway is a valid bare name).
• Quoted names cannot combine with as <alias> on the same declaration line (see §2.2a). If both quoting and aliasing are required, redesign the name to avoid the reserved character.

4.3 Node Properties (Indented, Colon-Separated)

NodeName
  latency-ms: 50
  max-rps: 8000
  uptime: 99.99%
  cache-hit: 75%
  description: My API gateway
  firewall-block: 10%
  instances: 3

Properties use a known schema with colon-separated values:

Mutually exclusive: concurrency ≠ instances ≠ max-rps; buffer ≠ max-rps. A node is serverless, traditional, or a queue — not two at once.

4.4 Connections

• Connection metadata: split: 50%, fanout: 3 (same-line, comma-separated)
• Indent under source node (see §1.7) — avoid flat Source -> Target form
• Async edges (~>) render with a wiggle pattern and a Fan-Out badge is added when fanout > 1
• Target may be a node id, an alias, or a group ref [Group Name]

4.5 Fanout

SearchAPI
  -> SearchShards fanout: 6

fanout: N multiplies the per-edge RPS delivered to the target by N (request amplification — scatter-gather, shard fanout, pub/sub).

• Effect: target_rps = source_post_behavior_rps × fanout (then split-distributed across declared targets)
• Combine with split: -> Target split: 50%, fanout: 3
• N must be ≥ 1; sub-1 values are warned and clamped
• Sources with at least one fanout > 1 outgoing edge gain the Fan-Out capability badge
• The legacy xN suffix (e.g. ... -> Target x5) is removed — use fanout: N

4.6 Groups

[Group Name]
[Group Name] as alias
[Group Name] key: value
[Group Name] collapsed

• Bracket syntax only. Group coloring via tags (§2).
• Optional as <alias> postfix (§2A) and same-line metadata.
• No nesting. A group cannot contain another [...] group; only indented components.
• Collapse: a bare collapsed trailing flag on the group line ([Backend] collapsed, §1.8) starts the group collapsed — it renders as a single node showing the worst child health. (Legacy: indented collapsed true.)
• Group properties (indented under the bracket line, colon-keyed like node properties §4.3):
  • instances: N or instances: N-M — capacity multiplier on children (auto-scaling). The space forms instances N / instances N-M are accepted legacy.

4.7 Infra Options (Space-Separated, NO Colon)

• direction-lr / direction-tb (booleans, §1.9; default is LR)
• default-latency-ms N
• default-rps N — fallback edge RPS when no rps is declared on the edge node
• default-uptime DECIMAL
• slo-availability DECIMAL — target availability for SLO compliance highlighting
• slo-p90-latency-ms N — target p90 for SLO compliance highlighting
• slo-warning-margin DECIMAL — margin below SLO that triggers warning state
• active-tag GroupName / active-tag none — pre-select a tag filter on render

The universal options no-title and the fill-* family (§1.9) also apply — but severity/SLO status tints are data and are never restyled by the fill family.

4.8 Edge Nodes

edge
internet

Special top-level entry points. Either name works; internet only accepts rps and the description is silently ignored on entry-point nodes.

4.9 Node Descriptions

API Gateway
  description: Handles routing and auth
  description: Supports rate limiting
  latency-ms: 50
  max-rps: 8000

• description: text (colon required; a description always needs the description: keyword — bare prose lines are NOT auto-promoted)
• Multiple description: lines accumulate into a multi-line description
• Supports inline markdown: **bold**, *italic*, `code`, [links](url)
• - bullet text renders as • bullet text
• Descriptions are ignored on edge and internet nodes

5. Flowchart Diagrams

4.1 Declaration

flowchart [Title]

4.2 Node Shapes

• Node coloring is automatic by shape — there is no manual node color. Start terminals render green, end terminals red, processes blue, decisions yellow, I/O purple, subroutines teal, documents orange. Flowcharts have no tag groups and no node metadata: a tag … as … block, a trailing color word, and a Node s: value suffix are all unsupported (a trailing suffix is ignored with a warning).

4.3 Arrows

Flowchart edges have no color slot. Node colors are automatic by shape (§5.2) — flowcharts have no manual node color and do not use the tag system.

4.4 Groups

[GroupName]
  [Child nodes...]

Bracket syntax only.

4.5 Edges (Indented Under Source)

Prefer indented-under-source form (see §1.7).

Decision branches are indented under their source node — the most common and readable pattern:

(Start) -> [Validate Input] -> <Valid?>
  -yes-> [Process Data] -> (Done)
  -no-> [Show Error] -> [Validate Input]

Nested decisions:

<Authenticated?>
  -yes-> <Authorized?>
    -yes-> [Process Request] -> (Done)
    -no-> [Return 403] -> (End)
  -no-> [Return 401] -> (End)

Inline chains (flat form) work for simple linear flows:

(Start) -> [Step 1] -> [Step 2] -> (End)

4.6 Options

• direction-lr / direction-tb (booleans, §1.9; default is TB — flowcharts read top-down). The key+value form direction LR|TB is accepted legacy.
• fill-solid / fill-outline (§1.9 fill family; default is the 25% tint — fill-solid renders shapes at full intent color, fill-outline drops the fill and carries color on the outline alone)
• no-notes (boolean; default off — suppress all note boxes, see §4.7)

4.7 Notes (Nodes)

Attach a hide-able annotation to a node with note <NodeId> text. The NodeId is the node’s label (quote it for multi-word labels). The note renders as a folded-corner box near the node, tethered to it with a solid connector line (UML note convention). The note floats beside the node — defaulting to the right for top-down graphs and below for left-right graphs — and is collision-aware: it flips to the opposite side (or pushes further out) to keep a comfortable distance from other shapes and other notes. It never moves the node it annotates, so the node keeps its position and edge connections. Notes are expanded at rest (in both the app and exports).

flowchart Order Pipeline
(Start) -> [Validate] -> (Done)
note Validate checks the payload schema
note "Start" entry point

Multi-line body — indent lines below the note heading (same as sequence notes, §2.5). Bullets (- ) and inline markdown (**bold**, *italic*, `code`, [link](url), bare URLs) are supported:

note Validate
  - rejects unknown fields
  - **400** on bad schema
  see `validate.ts`

Color — end the note heading line with a lowercase palette color word (the universal trailing-token convention, §1.5) to recolor the note (faded fill + matching border). Default is yellow.

note Validate checks the manifest red
note Launch all hands on deck green

Because the color word is the last token of the heading, capitalize it to keep it as literal body text (note Sky the sea turns Red keeps “Red”).

Rules:

• A note may be declared before its target node (forward references resolve at end-of-parse).
• One note per node — a second note on the same node is ignored with a warning. An unknown NodeId is an error (with a “did you mean?” hint), never silently dropped. A note with no text is ignored with a warning.
• Arrows (->) are allowed inside a note body. Only a line where -> immediately follows note (e.g. note -> Active) is treated as an edge rather than a note — in state diagrams that is a transition from a state named note.
• no-notes (diagram directive) suppresses every note box and reclaims the space they reserve.

Notes are wired into flowchart, state, class, er, and boxes-and-lines diagrams — the same note <NodeId> syntax, multi-line body, trailing-color word, forward references, and no-notes opt-out throughout. The NodeId is the node’s label: a class name, table name, or box label (quote multi-word labels). Org and sitemap are intentionally excluded — their indentation is the tree structure, which conflicts with the indented-body grammar (a note would silently swallow following nodes). Other chart types adopt the same syntax in later work.

6. State Diagrams

5.1 Declaration

state [Title]

5.2 States

StateName
[*]                    // initial/final pseudostate

5.3 Transitions

5.4 Groups

[Group Name]

5.5 Notes (States)

State diagrams support the same note <StateName> text annotation as flowcharts — single-line or indented multi-line body, forward references, and the no-notes opt-out. See §4.7 for the full rules.

state Connection
[*] -> Idle -> Active
note Idle waiting for input

5.6 Options

• direction-lr / direction-tb (booleans, §1.9; default is LR)
• fill-solid / fill-outline (§1.9 fill family; default is the 25% tint — collapsed groups follow the same mode, e.g. full saturation under fill-solid)
• no-notes (boolean; default off — suppress all note boxes, see §4.7)
• active-tag GroupName / active-tag none

5.7 Tags

State diagrams support the universal tag system (§1.3). Declare tag <Group> as <alias> blocks above the diagram body and apply values via same-line key: value metadata on state lines:

state Document Lifecycle
tag Phase as ph
  Intake blue
  Review orange
  Terminal green

Draft ph: Intake
Draft -submit-> In Review
In Review ph: Review
Published ph: Terminal

Tags color states exactly as in org and boxes-and-lines — 25% tint fill + solid outline, with the fill-* family (§1.9) applying as usual. Untagged states take the group’s first value per §1.3.

Historical note: state diagrams were long excluded from the tag system (“color the transitions instead”). That rationale predated the removal of edge colors (§1) and no longer holds — decision #48 brings state in line with the other node-and-edge charts.

7. Org Charts

6.1 Declaration

org [Title]

6.2 Nodes (Indentation = Hierarchy)

CEO
  CTO
    Engineer1
    Engineer2
  CFO

• Node coloring: use tags (§2)
• Same-line metadata: Alice role: CEO, t: Exec

6.3 Metadata (Indented, Colon REQUIRED)

Alice
  role: Senior Engineer
  location: NYC

This is key-value metadata assignment, consistent with same-line metadata syntax.

6.4 Containers

[Team Name]
  members...

6.5 Options

• direction-lr / direction-tb (booleans, §1.9; default is TB)
• sub-node-label Text
• show-sub-node-count (the language’s one documented positive opt-in flag — the badge is an auto-derived count, not authored data, and default-on would be noisy for small orgs; decision #48)
• hide
• active-tag GroupName / active-tag none

8. C4 Architecture Diagrams

7.1 Declaration

c4 [Title]

7.2 Elements

Name is a <type>
Name is a container is a database     // shape override

Types: person, system, container, component Shape overrides: database, cache, queue, cloud, external

7.3 Element Metadata (Indented, Colon REQUIRED)

Web App is a container
  description: SPA built with React
  tech: React

Indented metadata uses colon-separated key: value, consistent with org charts and same-line metadata.

7.4 Same-Line Metadata

Web App is a container description: SPA, tech: React

Same-line metadata requires key: value. A non-empty tail with no key: (e.g. Captain is a person Commands the fleet) is a hard error and the diagram does not render — use description: Commands the fleet. (History: dropped silently before the 0.30.0 freeze; the freeze added E_C4_BARE_TAIL_REMOVED; #28 deleted that code and the case regressed to a silent drop again; restored to a hard error — with a generic description: hint, no dedicated code — on 2026-07-05.)

7.5 Relationships (Indented Under Source Element)

Prefer indented-under-source form (see §1.7).

Relationships are indented under the source element:

Web App is a container
  description: SPA built with React
  -Makes API calls-> API
  -Loads-> CDN

API is a container
  -Reads/writes-> Database
  ~Sends events~> Queue

7.6 Sections

containers
  ...
components
  ...
deployment
  container Web App    // reference existing container

7.7 Options

• direction-lr / direction-tb (booleans, §1.9; default is TB)
• active-tag GroupName / active-tag none

7.8 Element Descriptions

// Indented metadata form (colon required)
Web App is a container
  description: SPA built with React
  description: Supports SSR and client-side routing

// Bare keyword form (DEPRECATED — emits a warning; prefer the colon form above)
API is a container
  description Handles all REST endpoints

// Same-line metadata form
Database is a container description: PostgreSQL with read replicas

• The description keyword requires a colon (description: text). The bare description text form is removed at 1.0 and emits E_DESCRIPTION_BARE_REMOVED (an error; the value is still applied so the diagram renders).
• Multiple description lines accumulate into a multi-line description
• description is extracted as a dedicated field, not stored in general metadata
• Supports inline markdown: **bold**, *italic*, `code`, [links](url)
• - bullet text renders as • bullet text

9. Entity-Relationship Diagrams

Notes. Annotate any table with note <Table> text — the same hide-able note box as flowcharts (multi-line body, trailing-color word, forward refs, no-notes opt-out). It floats beside the table without moving it. See §4.7.

8.1 Declaration

er [Title]

8.2 Tables

users
users blue
users domain: Core

• Same-line metadata on declaration line only
• Indented lines are columns or relationships

8.3 Columns (Indented, Space-Separated, NO Colon)

users
  id int pk
  name varchar
  email string unique
  created_at timestamp nullable

Format: name [type] [constraints...] Constraints: pk, fk, unique, nullable

8.4 Relationships (Indented Under Source Table)

Prefer indented-under-source form (see §1.7).

ships
  id int pk
  name varchar
  captain_id int fk
  1-aboard-* crew_members
  ?-frequents-1 ports

Columns and relationships can be intermixed under the same table. Cardinality symbols: 1 (one), * (many), ? (optional)

8.5 Options

• notation labels — render relationship cardinalities as text labels. Default is crow’s-foot markers (the coded default; any notation value other than labels falls back to crow’s-foot)
• active-tag GroupName / active-tag none
• no-semantic-colors — bare flag; suppress the semantic PK/FK role colors (on by default). View-state opt-out written by the app’s Semantic-colors toggle.

10. Class Diagrams

Notes. Annotate any class with note <ClassName> text — the same hide-able note box as flowcharts (multi-line body, trailing-color word, forward refs, no-notes opt-out). It floats beside the class without moving it. See §4.7 for the full rules.

9.1 Declaration

class [Title]

9.2 Classes

Ship
abstract Vessel
interface Serializable
Ship extends Vessel
Galleon implements Serializable
Galleon extends Ship implements Serializable
enum ShipType

extends and implements may co-occur on the same declaration line. Order is fixed: extends before implements. Each may name only one parent / interface.

9.3 Members (Indented, Colon for Types)

Fields:

+ name: string
- speed: number
# protectedField: int

Methods:

+ sail(): void
- calculate(x: number): boolean
+ getName() {static}: string

Visibility: + public, - private, # protected

Enum values:

enum ShipType
  Galleon
  Sloop

9.4 Relationships (Indented Under Source Class)

Prefer indented-under-source form (see §1.7).

Relationships are indented under the source class:

Ship
  --|> Vessel
  *-- Cannon

Optional label: --|> Vessel : extends (colon optional before label)

extends and implements on class declarations still work as part of the declaration syntax.

9.5 Options

(No chart-specific options. The universal directives no-title and the fill-* family (§1.9) apply.)

11. Kanban Boards

10.1 Declaration

kanban [Title]

10.2 Columns

[Column Name]
[Column Name] color wip: 3
[Column Name] collapsed

A column may carry the bare collapsed trailing flag (§1.8) to start folded to a narrow strip; the app writes/removes it on the column toggle and it round-trips to any renderer (legacy: collapsed: true).

10.3 Cards (Indented Under Columns)

[To Do]
  Card title priority: High, c: Owner
    Detail text (indented deeper)

10.4 Options

• hide
• active-tag GroupName / active-tag none
• lane-by GroupName — slice the board into swimlanes by a tag group (the swimlane axis). Named lane-by, not swimlane, because swimlane is itself a chart type. View-state directive written by the app’s swimlane picker.

12. Sitemap Diagrams

11.1 Declaration

sitemap [Title]

11.2 Pages (Indentation = Hierarchy)

Home
  About
  Pricing Auth: Public
    Enterprise
  Blog

11.3 Arrows

Prefer indented-under-source form (see §1.7).

Home
  -pricing-> Pricing
  -login-> Login

Arrows can target containers using bracket syntax:

Home
  -> [Port Market]

All permutations are supported: node→group, group→node, group→group.

[Port Market]
  Shop
  -> [Warehouse]
[Warehouse]
  Storage

When a group is the source, place the arrow directly after the group header (before any child pages). Brackets are required to distinguish group targets from page targets.

11.4 Containers

[Marketing]
  Pricing Auth: Public

A container holds a flat list of pages — pages inside a [Container] may not have indented sub-pages. Over-indenting a page under another page within a container is an error:

[Marketing]
  Docs
    Guides          ← ERROR: pages inside a container can't have sub-pages
    API Reference   ← ERROR
  Blog

Pages inside container '[Marketing]' cannot have indented sub-pages.

Sub-page hierarchy via indentation is supported only at the top level (§11.2), outside any container. Indented arrows under a container page are still allowed (they declare edges, not sub-pages):

[Workspace]
  Dashboard
    -projects-> Projects   ← OK: arrow, not a sub-page
  Projects

11.5 Options

• direction-lr / direction-tb (booleans, §1.9; default is LR)
• active-tag GroupName / active-tag none

11.6 Node Descriptions

// Bare keyword form (DEPRECATED — emits a warning; prefer description: above)
About
  description Company history and team bios

// Same-line metadata form
Pricing description: Compare plans and features

// Multi-line
Blog
  description: Engineering and product updates
  description: Published weekly

• description: text (colon required; bare prose lines are not auto-detected as descriptions)
• Multiple description: lines accumulate into a multi-line description
• Supports inline markdown: **bold**, *italic*, `code`, [links](url)
• - bullet text renders as • bullet text

13. Gantt Charts

Dates (start-date, task start:, eras, markers, holidays, today-marker, sprint-start) follow the liberal grammar + year ladder in §2B Universal Date Handling.

13.1 Declaration

gantt [Title]

13.2 Options (Space-Separated, NO Colon)

start-date 2026-03-15
today-marker
today-marker 2026-03-27
critical-path
no-dependencies
// swimlane axis (canonical); equivalent to `sort tag:Team`
lane-by Team
// back-compat spelling of lane-by
sort tag:Team
active-tag GroupName
active-tag none
sprint-length 2w
sprint-number 5
sprint-start 2026-01-05

start-date anchors the chart start (canonical — shared spelling with PERT, §13A.2); the historical bare start is accepted legacy.

13.3 Holidays

holiday
  2024-02-19 Presidents Day
  2024-05-27 -> 2024-05-29 Memorial Weekend

13.4 Workweek

workweek mon-fri
workweek sun-thu

Top-level directive (not nested under holiday).

13.5 Eras

Flat form:

era 2026-04-06 -> 2026-04-10 Conference purple

Block form:

era
  2026-04-06 -> 2026-04-10 Conference purple
  2026-06-01 -> 2026-06-05 Sprint Review blue

13.6 Markers

Flat form:

marker 2026-03-27 Board Review

Block form:

marker
  2026-03-27 Board Review
  2026-06-15 Release green

13.7 Groups (Swimlanes)

[Backend] t: Engineering

Bracket syntax only.

13.8 Tasks

Duration is positional — the last whitespace-separated token (right-to-left scan):

Database Schema 20bd
API Integration 10bd t: Engineering
Launch Day 0d
Research Phase 10bd?
Data Migration 30bd progress: 80

Positional duration: Task Name 30bd — duration is the rightmost token matching <number><unit>.

Trailing metadata: Task Name 30bd t: Engineering, progress: 80 — comma-separated key: value pairs after the duration.

Milestones: Launch 0d — zero-duration task renders as a diamond marker.

Uncertain: Task Name 10bd? — trailing ? on the duration token.

Progress: progress: 80 in trailing metadata (integer 0–100; implicit percent — write progress: 80, not progress: 80%).

Offset prefix: +4w Task Name 30bd — task starts at chart-start + 4 weeks. Useful for tasks not chained by dependencies. Offset token is +<number><unit> before the task name.

Group offsets: +2w [Mobile] — floors all tasks inside the group to chart-start + 2 weeks.

Scope-based metadata: indented key: value on the line below attaches to the parent task:

API Integration 10bd
  t: Engineering
  progress: 50

Fallback metadata keys: duration: and start: are accepted as same-line metadata for ambiguous names:

Setup start: 2026-03-15, duration: 30d
Phase 2 duration: 10bd

Duration units: min, h, d, bd (business days), w, m, q, y, sp (sprints — see §13.11); bare s accepted legacy in gantt/pert

13.9 Dependencies (Arrow Graph)

Arrows create dependencies AND define tasks in one line:

[Backend]
  Database Schema 20bd
    -> API Integration 10bd
      -> E2E Testing 5bd
  Auth Module 15bd

Bare siblings are parallel by default — Database Schema and Auth Module above start at the same time (no parallel keyword needed).

Arrow = sequential: -> Next Task 10bd indented under a task means “Next Task starts after parent finishes.”

Lag (delay): -3w-> Next Task 10bd — target starts 3 weeks after source finishes.

Lead (overlap): --2w-> Next Task 10bd — target starts 2 weeks before source finishes.

Cross-group references: -> [Backend].API Design — reference-only dependency (does not create a new task):

[Frontend]
  Wireframes 10bd
    -> [Backend].API Design

Multiple arrows from one task:

API Integration 10bd
  -> E2E Testing 5bd
  -> Documentation 3bd

13.10 Scheduling Model

• Bare siblings = parallel (start at chart start, or group start if offset).
• Arrow = sequential (target starts after source finishes, plus optional lag/lead).
• Offset prefix = pinned start relative to chart start.

This replaces the legacy parallel keyword — groups and arrows express all scheduling relationships.

Removed at 1.0 (error E_GANTT_LEGACY_REMOVED): the four pre-1.0 scheduling shorthands no longer parse as valid syntax — each raises E_GANTT_LEGACY_REMOVED (error; the value is still applied best-effort so the diagram renders):

1. The parallel keyword — sibling tasks already run in parallel by default; delete it.
2. Duration-before-name — 30bd Database Layer → positional Database Layer 30bd (or Database Layer duration: 30bd).
3. Explicit-date task — 2024-01-15 Kickoff → Kickoff start: 2024-01-15.
4. Legacy timeline-duration — 2024-01-15 -> 30d Build → Build start: 2024-01-15, duration: 30d.

Kept (NOT legacy): duration: and start: are canonical fallback metadata keys (§13.8) — they parse cleanly with no error. Use them for ambiguous names where the positional/offset forms are awkward.

13.11 Sprints

The sp duration unit expresses task duration in sprints. Sprint length is configurable via sprint-length (default 2w). Using sp in any task auto-enables sprint mode; explicit sprint-* options also enable it.

Options (space-separated, no colons):

Duration resolution: 2sp with sprint-length 2w = 4 calendar weeks (28 days). Fractional sprints work: 0.5sp = half a sprint. Changing sprint-length rescales all sp-based durations across the chart.

Sprint bands: When sprint mode is active, alternating shaded vertical bands render on the timeline with adaptive labels (“Sprint N”, “N”, or every 5th). Dashed boundary lines mark sprint edges.

Eras vs sprints: Eras and sprints share the same visual lane. When both are defined, eras display by default (with a toggle in the app). In static SVG, eras always win.

Note: sp means sprints; the historical bare s still parses in Gantt/PERT context but is no longer documented — timeline’s s is seconds. Sprints use calendar time, not business days. For teams with irregular sprint calendars, use eras instead.

gantt
sprint-length 2w
sprint-number 5
sprint-start 2026-01-05
start-date 2026-03-01

[Phase 1]
  Design 2sp
    -> Build 3sp
      -> QA 1sp

13A. PERT Diagrams

Anchor dates (start-date, end-date, sprint-start) follow the liberal grammar + year ladder in §2B Universal Date Handling. Anchors require a full (day-grain), calendar-valid date.

PERT diagrams visualize project networks with three-point duration estimates and surface critical path, slack, and project μ/σ. Activity-on-Node notation: each activity is a rectangle node; dependencies are arrows between activities.

13A.1 Declaration

pert [Title]

13A.2 Directives (Space-Separated, NO Colon)

time-unit w               # Unit for bare-number durations (default: d)
default-confidence medium # M-only heuristic level: high | medium | low (default: medium)
                          # …or a custom O/P factor pair: default-confidence 0.6/2.5
                          # Per-activity override via same-line `confidence: low` metadata
direction-lr              # Layout direction booleans (§1.9): direction-lr (default) | direction-tb
                          # Key+value form `direction LR|TB` accepted legacy
node-detail compact       # Visual density: compact (default) | full
no-analysis               # Bare flag — hide the analysis layer (tornado + S-curve); on by default — see §13A.10
trials 10000              # Canonical-MC trial count
seed 42                   # Mulberry32 PRNG seed for determinism
scrubber-trials 300       # Fast-MC trials for the duration scrubber
start-date 2026-06-01     # Anchor project start (forward pass) — see §13A.12
end-date 2026-09-15       # Anchor project end (backward pass) — see §13A.12
                          # Specify start-date OR end-date (not both); 'now' valid for start-date only
sprint-length 2w          # Sprint length (default 2w; only when sprint mode active)
sprint-number 5           # Starting sprint label N — cells render as S<N+offset> (default 1)
sprint-start 2026-06-01   # Optional ISO date the starting sprint begins on
active-tag Crew           # Activate a non-first tag group (first is active by default) — see §13A.2a

Sprint mode is activated automatically when time-unit sp is set (sp = sprints, mirroring the Gantt duration unit §13.11; bare s accepted legacy), or explicitly when any sprint-* directive appears. In sprint mode, ES/EF/LS/LF cells render as S5, S7, S12 etc. instead of numeric offsets or ISO dates, and the project-stats summary reports duration in sprints. Mirrors the Gantt sprint surface.

13A.2a Tags

PERT supports the universal tag system (§1.3). Declarations live above the diagram body and apply to activities (and groups) via same-line metadata.

pert Pirate Voyage by Crew Role
time-unit w
default-confidence medium

tag Crew as c
  Captain red
  Bosun orange
  Quartermaster blue

recruit crew 1 2 4 c: Quartermaster
load powder 0.5 1 2 c: Bosun

• Activities carry <alias>: <Value> (or <GroupName>: <Value>) inside the existing same-line metadata segment alongside other keys like confidence and collapsed.
• Group headers also accept tag metadata: [outfit ship] c: Bosun colors the cluster header.
• The first declared group is active by default (per §1.3). active-tag <GroupName> only matters with ≥2 groups when you want a non-first group active; active-tag none suppresses all colouring (cards render neutral, all groups collapsed).
• Visual placement: when a group is active, the activity card’s middle (name) band picks up the tag color. The card border continues to communicate criticality (red/orange/etc bands per §13A.10), so tag fill and crit border compose without conflict. Milestone diamonds adopt the tag color across the full pill.

The analysis layer (tornado + S-curve, §13A.10) renders by default in every render — CLI, embedded docs, share link, export — whenever Monte Carlo ran (at least one O/M/P estimate). The bare no-analysis flag (mirrors no-title) suppresses it for a cleaner, network-only view. Precedence at render time: an explicit viewState.an (desktop-app toggle or share link) wins; otherwise no-analysis decides; otherwise the layer is on. In analytical mode (no MC) the layer is silently omitted regardless. The legacy analysis directive (historically analysis monte-carlo, to opt into simulation — now auto-derived from data, §13A.9) is removed at 1.0: it emits an error-severity diagnostic (E_PERT_ANALYSIS_REMOVED) and is otherwise ignored (the diagram still renders). Use the bare no-analysis flag to hide the layer.

13A.3 Activities

An activity is <name> [<durations>] [as <id>] [metadata]. Durations follow the name, separated by spaces or commas. Three forms:

Two-number durations are an error (the parser cannot disambiguate between O+M, M+P, or O+P).

pert
time-unit w
default-confidence medium

recruit crew 1 2 4 as rc confidence: low
careen hull 1.5
load powder
celebrate

13A.4 Dependencies

Indented -> dest lines under an activity declare a dependency from that activity to dest. The destination must reference a previously-declared activity name or alias — inline durations on the arrow line (-> name 1 2 4) are rejected by the parser. Declare the destination on its own source line first, then reference it.

// ✅ Declare destinations first; arrows reference by name/alias only
load powder 0.5 1 2
careen hull 1.5
recruit crew 1 2 4 as rc
  -> load powder
  -> careen hull

// ❌ Inline forward-declaration is rejected:
// "Inline forward-declaration not allowed — move attributes to a source line"
recruit crew 1 2 4 as rc
  -> load powder 0.5 1 2

Each activity has one declaration site. Repeating an activity’s name on a non-indented line is allowed (it acts as a “source line” for further -> arrows) but providing conflicting duration tokens raises a diagnostic that names both line numbers.

Dependency types and lag/lead

Edges default to Finish-to-Start (FS) with zero lag — the dominant case. The arrow may carry an inline label between two dashes to override either piece:

A -> B            # FS, 0 lag (default — unchanged)
A -SS-> B         # Start-to-Start
A -2d-> B         # FS with +2d lag (lag-only shortcut)
A -SS+2d-> B      # SS with +2d lag
A -FF-1d-> B      # FF with -1d lead (negative lag)
A -SF+3d-> B      # SF with +3d lag

Grammar: -[TYPE][±LAG]-> — both pieces optional, but at least one must be present when a label is given.

Type names are case-insensitive (SS, ss, Ss all valid). Lag amount inherits the diagram’s time-unit; per-edge unit overrides are accepted (-SS+2d->, -FF+4h->). A - sign denotes a lead (overlap): -FS-1d-> = successor starts 1 day before predecessor finishes.

The renderer paints a small midpoint label on every non-default edge (SS +2d, FF -1d, +2d for FS-only lag). FS+0 edges remain visually clean.

A diagnostic warning fires when a lead’s magnitude exceeds the predecessor’s duration (an FS edge that implies the successor starts before the predecessor — logically impossible).

There is no default-edge-type directive: every -> is FS regardless of what’s been written elsewhere in the file. This keeps each edge self-evident to readers and prevents copy-paste from silently flipping semantics.

13A.5 Aliases (as <id>)

The universal as <ident> suffix (§2A) applies. PERT aliases share namespace with activity names. Names containing the literal token as parse cleanly when no actual alias suffix is appended (e.g. serve as quartermaster 2 3 5).

13A.6 Milestones

Milestones are zero-duration nodes rendered as diamonds. They participate in the dependency graph and critical-path computation and are excluded from criticality summary statistics.

There is no milestone keyword. Declare a milestone as a zero-duration activity using the standard activity grammar — <name> 0 (M-only zero) or <name> 0 0 0 (three-point zero):

voyage approved 0
landfall 0 0 0

Both forms render as diamonds. The parser explicitly rejects the legacy milestone <name> keyword with Unknown keyword 'milestone'.

13A.7 Groups

Bracketed [group-name] blocks group activities. Whether a group renders as a hammock super-edge or a cluster bounding rectangle is auto-detected from edge topology:

• Hammock: single entry + single exit → collapses to a labeled super-edge with rolled-up μ ± σ
• Cluster: multi-entry or multi-exit → renders as a tinted bounding rectangle

[outfit ship]
  recruit crew 1 2 4
    -> load powder
  careen hull 1 1.5 2.5
    -> load powder
  load powder 0.5 1 2
    -> sail to atoll

sail to atoll 3 5 8

Groups can author a bare collapsed trailing flag (§1.8) to start collapsed (legacy: collapsed: true).

13A.8 Same-Line Metadata

13A.9 Analysis

Mode is auto-derived from the data:

The forward/backward pass, slack, M-world critical path, project μ along that path, and project σ from the variance sum on that path are always computed. Activities downstream of a TBD activity inherit null for ES/EF/LS/LF/slack; the project end likewise becomes ? until all upstream TBDs are estimated.

On top of that base analysis, Monte Carlo simulation runs whenever at least one non-milestone activity has a duration — either an explicit three-point (O M P) estimate or an M-only value whose O/P are filled from default-confidence. The canonical run uses N = trials Beta-PERT samples with seed = seed, and reports P50/P80/P95 plus per-activity criticality index. The interactive duration scrubber uses scrubber-trials samples for live re-analysis.

When no non-milestone activity has any duration (or every terminal is poisoned by TBD propagation), MC is skipped and the diagram renders in analytical mode — caption shows expected duration only, no percentile rows or S-curve.

Heads-up: an all-M-only diagram still produces real MC percentiles, but the spread is a mechanical function of default-confidence (every activity’s σ scales with M). The simulation is honest about its inputs; it cannot be more informed than the confidence directive it was given.

trials < 100 clamps mode back to analytical (with a one-sentence caveat in the project-stats caption) — ten-trial samples produce nonsense percentiles. The trials, seed, and scrubber-trials directives stay valid but are silently inert in analytical mode.

13A.10 Visual Encoding

The project-stats caption is rendered below the title (or at the top when no title) as a centered, multi-line text block. It reports expected duration and — in Monte-Carlo mode — standard deviation and percentile dates (finishes in forward / no-anchor mode, latest-safe starts in backward mode; see §13A.12). Critical-path, bottleneck, and hidden-risk emphasis is delegated to the diagram itself (red/orange node-border bands).

Comments use # line-leading (or trailing-after-whitespace) for PERT specifically — both # and // are recognized.

13A.11 Worked Example

pert Pirate Voyage
time-unit w
default-confidence medium

voyage approved 0
  -> recruit crew

[outfit ship]
  recruit crew 1 2 4 as rc confidence: low
    -> load powder
  careen hull 1 1.5 2.5
    -> load powder
  load powder 0.5 1 2
    -> sail to atoll

sail to atoll 3 5 8
  -> count gold
  -> repair hull

count gold 0.5d
  -> divvy shares

repair hull 2 3 5 confidence: low
  -> divvy shares

divvy shares 1 2 3

Variant: with date anchoring. Add start-date to render every ES / EF / LS / LF as a real calendar date instead of a numeric offset. Slack still reports as a duration (calendar days when anchored). Critical-path coloring is unchanged.

pert Pirate Voyage
time-unit w
default-confidence medium
start-date 2026-06-01    # NEW: anchor

voyage approved 0
  -> recruit crew

recruit crew 1 2 4 as rc
  -> load powder

load powder 0.5 1 2
  -> sail to atoll

sail to atoll 3 5 8
  -> count gold
  -> repair hull

count gold 0.5
  -> divvy shares

repair hull 2 3 5
  -> divvy shares

divvy shares 1 2 3

With time-unit w and start-date 2026-06-01, the recruit crew activity (μ ≈ 2.17w ≈ 15 days) renders ES: 2026-06-01, EF: 2026-06-16. Slack normalizes to Xd everywhere.

13A.12 Date Anchoring

PERT charts compute ES / EF / LS / LF in the diagram’s time-unit. The start-date YYYY-MM-DD and end-date YYYY-MM-DD directives anchor those numbers to a calendar so all four cells render as real dates. They are mutually exclusive — author one or the other, not both.

Terminology. Anchor refers to the user-supplied date (start-date or end-date). projectStart refers to the date the formatter uses internally — equal to the start-date in forward mode, derived as end-date − projectMu in backward mode. The chart never displays projectStart directly except via the corner-cell labels of source/sink activities.

Critical-path framing. On critical-path activities, LS = ES and LF = EF — there is no slack — so the corner-cell labels are unambiguous regardless of forward/backward mode. The “earliest possible” framing of backward mode applies only to non-critical activities, whose ES/EF represent the earliest start/finish given the deadline. The chart’s title annotation establishes this framing once for the whole diagram, but readers can rely on critical-path nodes (red/orange band coloring) being mode-invariant.

Visual node-card specimens. The same activity (recruit crew, μ ≈ 2.17w) under each mode:

No anchor:

┌──────┬──────┬──────┐
│  0   │ 2.17w│ 2.17w│
├──────┴──────┴──────┤
│     recruit crew    │
├──────┬──────┬──────┤
│  0   │  0w  │ 2.17w│
└──────┴──────┴──────┘

Forward anchor (start-date 2026-06-01):

┌────────────┬──────┬────────────┐
│ 2026-06-01 │ 2.17w│ 2026-06-16 │
├────────────┴──────┴────────────┤
│          recruit crew           │
├────────────┬──────┬────────────┤
│ 2026-06-01 │  0d  │ 2026-06-16 │
└────────────┴──────┴────────────┘

Backward anchor (end-date 2026-09-15, derived projectStart = 2026-06-01):

┌────────────┬──────┬────────────┐
│ 2026-06-01 │ 2.17w│ 2026-06-16 │   ← critical-path: LS=ES, LF=EF
├────────────┴──────┴────────────┤
│          recruit crew           │
├────────────┬──────┬────────────┤
│ 2026-06-01 │  0d  │ 2026-06-16 │
└────────────┴──────┴────────────┘
   (italic title note above chart: "Backward-anchored from end-date 2026-09-15 (as of 2026-05-10)")

mu always renders as a duration (2.17w) regardless of mode — it’s a timespan, not a date. slack normalizes to days (0d) when anchored.

Latest-safe start (backward mode). When end-date is set and Monte Carlo is active, the project-stats caption reframes its percentile rows from finishes to latest-safe starts. Each row reports end-date − duration_PX — the latest date the project can begin and still hit the deadline with that confidence:

Pirate Voyage — Backward-anchored from end-date 2026-09-15 (as of 2026-05-10)
• Expected duration: 15w
• σ: 2w
• P50 latest-safe start: 2026-06-08
• P80 latest-safe start: 2026-05-27
• P95 latest-safe start: 2026-05-13

Higher confidence demands an earlier start: P95 is earlier than P50, mirroring how P95 finish is later than P50 finish in forward mode. Analytical mode (no MC) omits the percentile rows; the μ-derived projectStart already appears in source-activity ES cells, so the caption would only duplicate that single date.

Rounding direction. When sub-day precision arises (e.g. fractional days from time-unit h arithmetic), latest-safe-start dates round down to the nearest whole day — earlier date = more schedule buffer = more conservative. Forward-mode finishes round up for symmetric conservatism. This rule ensures that a reported date never overstates the safety margin.

Past-date annotation. When a latest-safe-start date falls in the past relative to the parse-time today date (i.e. duration_PX > end-date − today), the row appends (latest-safe start has passed) so readers don’t silently misread a pre-today date as actionable:

• P95 latest-safe start: 2026-04-01 (latest-safe start has passed)

The annotation is factual — no verdict on whether the project is “infeasible”; the math is reported honestly and the reader judges. P50/P80 rows in the same caption may still be feasible and render without the annotation.

“Today” capture timing. The past-date check uses the parse-time today date — captured once when the analyzer runs, then frozen. This matches the start-date now precedent (which substitutes its resolved date before share-link compression) so that a shared backward-anchored diagram preserves the author’s view rather than re-evaluating against each recipient’s local date. To make this freshness signal legible, the backward-anchored title annotation includes the parse-time today date in an (as of YYYY-MM-DD) suffix:

Backward-anchored from end-date 2026-09-15 (as of 2026-05-10)

Recipients who see a stale (as of …) know to re-render for an updated past-date check.

Analytical mode (no MC) + past projectStart. Analytical-mode backward anchoring renders only the μ-derived projectStart in source-activity ES cells — there are no percentile rows to annotate. The ES cell date itself communicates “past” via its calendar value; no separate past-date annotation is emitted. (If you need a confidence-banded readout, add three-point estimates to switch to Monte-Carlo mode.)

If any TBD activity makes projectMu indeterminate, all percentile rows render ? (the analyzer has no duration distribution to subtract from end-date); the expected-duration row likewise renders ?.

Completion-probability S-curve axes. The optional S-curve widget (§13A.10) interprets the Monte-Carlo trial distribution differently per mode:

The backward curve is the forward curve mirrored horizontally and shifted — same trial distribution, different time axis. Both modes annotate the curve with vertical reference lines at the percentile dates reported in the caption (P50/P80/P95 finishes in forward mode, P50/P80/P95 latest-safe starts in backward mode). Authors should be able to read the chart and the caption as one cross-referenced unit.

S-curve degenerate cases:

• Monte Carlo did not run → S-curve silently omitted.
• projectMu indeterminate (any upstream TBD) → empty axes with a ? placeholder.
• A reference line in backward mode that resolves to a past date (matching the caption’s past-date annotation) renders dashed instead of solid; the percentile label includes a (past) suffix.

Special tokens and degenerate cases.

• start-date now resolves to today’s local date at parse time. Share-link encoding substitutes the resolved date BEFORE compression so the recipient sees the dates the author saw, not “today, wherever you are.” end-date now is a parse error.
• Backward-anchored diagram with any TBD activity upstream → projectStart cannot be derived; all four schedule cells render ?. The title annotation still names the end-date.
• time-unit bd + anchor → warning (bd is treated as calendar days for date math; for business-day scheduling use Gantt).
• time-unit min / h + anchor → warning (date display rounds to whole days).

Diagnostic codes.

14. Boxes and Lines Diagrams

Notes. Annotate any box with note <Box> text — the same hide-able note box as flowcharts (multi-line body, trailing-color word, forward refs, no-notes opt-out). It floats beside the box (respecting the diagram’s LR/TB direction) without moving it. See §4.7 for the full rules.

13.1 Declaration

boxes-and-lines [Title]

Requires explicit first line — no heuristic detection. Default direction is left-to-right.

13.2 Nodes

NodeLabel
NodeLabel key: value, key2: value2
NodeLabel description: Some text here

Nodes are created explicitly or implicitly (when referenced in edges). All nodes render as uniform rounded rectangles.

The description key is extracted as a dedicated field and not stored in metadata.

13.3 Edges

Prefer indented-under-source form (see §1.7). Declare the node, then indent its outgoing edges below it.

Source -> Target
Source -> Target key: value
Source -label-> Target
Source <-> Target
Source <-label-> Target

Indented shorthand (source from preceding node):

API description: Main gateway
  -routes-> UserService
  -routes-> ProductService

Same-line metadata on edges:

A -reads-> DB frequency: High

Group-targeted edges: Use bracket syntax [Group Name] to reference groups as edge endpoints:

API -> [Backend]
[Backend] -> [Frontend]

Indented shorthand also supports groups. Place the arrow directly after the group header:

[Backend]
  -> [Frontend]
  DB
  Cache

Top-level group-to-group edges:

[Region A] -> [Region B]
[Region A] <-> [Region B]
[Region A] -label-> [Region B]

13.4 Groups

[Group Name]
  indented nodes...

[Group Name] key: value
  indented nodes...

Nested groups (max depth 2):

[AWS]
  [us-east-1]
    API
    DB

Group metadata cascades to children (node metadata overrides). Nodes already declared above can be referenced inside groups to assign membership.

13.5 Group-to-Group Edges

[Region A] -> [Region B]
[Region A] <-> [Region B]
[Region A] -VPN-> [Region B]

13.6 Directives

• direction-lr / direction-tb (booleans, §1.9; default is LR). The key+value form direction LR|TB is accepted legacy.
• heat <Label> [low] [high] — name a numeric color ramp (see §13.9); one trailing color sets the high (full-value) hue over a neutral low, two set explicit low high ramp endpoints
• no-value — suppress the per-box numeric value labels (values render by default; a box value is authored data). Legacy show-values is accepted as a no-op opt-in from the off-default era.

13.7 Node Descriptions

// Same-line metadata form
API description: Main gateway for all services

// Multi-line via indented description: lines
UserService
  description: Handles user CRUD
  description: Manages sessions and auth tokens

• description is extracted as a dedicated field (not stored in generic metadata)
• Multiple description lines accumulate into a multi-line description
• Supports inline markdown: **bold**, *italic*, `code`, [links](url)
• - bullet text renders as • bullet text

13.8 Options

• active-tag GroupName — set active tag group for coloring
• active-tag none — suppress tag coloring
• active-tag <heat-label> — make the heat ramp the active dimension (see §13.9)
• hide team:Backend, team:Frontend — hide nodes with matching tag values (colon syntax for tag:value)

13.9 Heat (numeric color ramp)

Boxes can carry a numeric measure that drives a continuous color ramp — a choropleth-style “heat dimension” alongside the categorical tag groups.

boxes-and-lines Fleet Crews
heat Crew blue

Flagship heat: 120
Frigate heat: 40
Sloop heat: 12
Flagship -> Frigate
Flagship -> Sloop

• heat: <number> on any box line records its measure (a reserved metadata key — lifted out, never rendered as a tag). Non-numeric values are an error.
• heat <Label> [low] [high] names the dimension and optionally sets the ramp endpoint colors. Pre-content directive.
  • No color → high hue is the palette’s primary color over a neutral low.
  • One color → that color is the high (full-value) hue; the low end stays the neutral floor (unchanged from the single-color form).
  • Two colors → explicit low high endpoints, in that order — a diverging ramp like heat Risk green red reads green (low) → red (high). The order is taken literally; which end means “good” vs “bad” is your choice (dgmo encodes only “low color = the low-value end”). A wide-hue-gap pair (e.g. green→red) routes through a neutral midpoint so mid values stay clean instead of muddy; analogous pairs (e.g. yellow→red) blend directly.
  • Up to two trailing color names are peeled from the right and never empty the label — heat Red blue keeps the label Red with high blue.
• The ramp anchors at the data minimum (low end = lowest value), maximising within-diagram contrast; equal-value data renders at the top of the ramp.
• Active dimension: the heat ramp is the resting-active dimension whenever any box has a heat: (so heat shading works in static export with no interaction). active-tag <tag-group> switches to a tag group; active-tag none suppresses all tinting; active-tag <heat-label> forces the heat ramp. On a name collision between a tag group and the heat label, the tag group wins.
• When the heat ramp is active the legend shows a gradient capsule and each box is coloured by its value, following the standard box convention — a 25% faded (muted) fill + a solid colour outline (and fill-solid opts into the full fill), consistent with tag-coloured boxes. Boxes without a heat: get a neutral fill. The outline differs by ramp kind:
  • Two-colour ramp (heat Risk green red): value is carried by HUE, so each box’s outline is its own ramp colour (green→red) and the fill is the muted tint of it.
  • Single-colour ramp (heat Crew blue): one hue, so the outline is the constant ramp hue and value reads from the muted fill’s depth (low → near-bg, high → 25% hue tint). (Unlike the map, which fills regions with the full saturated ramp colour — a choropleth — boxes are never solid-filled by default.)
• Each box’s number additionally prints as text by default (independent of which dimension is active); suppress with no-value (§13.6).

13.10 Tag groups (categorical color)

Boxes carry categorical color via standard tag groups (§1.3). Declare tag <Facet> as <alias> with one color per value — values indented under the tag header, color as a trailing token — then reference the alias in box metadata (<alias>: <Value>). The <alias> <Value> line form is not valid grammar (it parses as a content node).

boxes-and-lines Service Map
tag Tier as t
  Client blue
  Edge teal
  Compute green
  Data purple

[Client]
  Web App t: Client
[Edge]
  API Gateway t: Edge
[Compute]
  Auth Service t: Compute
[Data]
  Postgres t: Data

Categorical tag color and the numeric heat ramp (§13.9) are separate dimensions; active-tag selects which one colors the boxes. Tag declarations must precede content (§1.3).

15. Timeline Diagrams

Event, era, and marker dates follow the liberal grammar + year ladder in §2B Universal Date Handling (including BCE/CE era-signed years).

15.1 Declaration

timeline [Title]

15.2 Events

Events use date-first syntax — the date (or date range) leads, followed by the event name, with optional trailing metadata (§1.4).

Point event (single date):

1718-05 Blockades Charleston

Range event (-> between dates, spaces around -> optional):

1716 -> 1717 Sails under Hornigold
1716->1717 Sails under Hornigold

Duration event (date + name + duration: same-line metadata):

2026-03-20 Sprint 1 duration: 30d

Datetime (date with HH:MM time component):

2026-03-20 14:30 Standup Meeting

Uncertain ending (? suffix on end date or duration value):

1718 -> 1719? Rackham builds crew
2026-03-20 Sprint 1 duration: 30d?

Trailing metadata (§1.4 same-line form, after name):

1718-05 Blockades Charleston p: Blackbeard, color: red
1716 -> 1717 Sails under Hornigold p: Blackbeard

Event type is determined by positional structure:

• Single date → point event
• date -> date → range event
• Single date + duration: metadata → duration event

Date formats: any liberal form from §2B Universal Date Handling — year, year-month, or day-grain — with an optional HH:MM / HH:MM:SS time component on day-grain dates. Duration units: s (seconds), min, h, d, w, m, y. Here s is seconds — not sprints; gantt/pert use sp.

Time: the time component accepts an optional seconds field (14:30 or 14:30:45); hours 0–23, minutes/seconds 0–59 (out-of-range warns). Sub-minute spans get adaptive second-level axis ticks.

BCE / pre-year-1 dates: suffix a year with BCE (or BC) for a pre-Common-Era date — 753 BCE, 44 BC. CE/AD are accepted as positive no-ops (14 CE). Markers allow 1–4 digit years (the marker is what distinguishes an ancient year from a stray number — a bare 753 is not a date). Ranges may cross the boundary (27 BCE -> 14 CE). Display normalizes to 753 BCE. Numbering is astronomical-naive (N BCE ↔ internal year -N), so ordering is correct but there is no year-0 adjustment.

Duration syntax (1.0)

duration: is the canonical (and only) form. A bare trailing duration-like token is not parsed as a duration — it is treated as part of the event name (so 2026-03-20 Sprint 1 30d is a point event named “Sprint 1 30d”). This is intentional: it keeps event names that begin with a duration-like word unambiguous. Use the colon-keyed form to apply a duration:

2026-03-20 Sprint 1 duration: 30d

Thus 1918 42d Street is unambiguously a point event named “42d Street”; a duration is only ever expressed via duration:.

15.3 Eras

Flat form:

era 1716 -> 1718 Nassau Republic

Block form:

era
  1716 -> 1718 Nassau Republic
  1718 -> 1720 Woodes Rogers Era orange

15.4 Markers

Flat form:

marker 1718-07 Woodes Rogers arrives orange

Block form:

marker
  1718-07 Woodes Rogers arrives orange
  1720-01 End of Golden Age red

15.5 Groups

Groups use bracket syntax. Metadata on a group line is inherited by all child events; event-level metadata overrides group metadata. Events must be indented under the [Group] header to be associated with it.

[Royal Navy] t: British
  1718-07 Woodes Rogers arrives
  1718-11 Captures Vane color: red

In this example, both events inherit t: British from the group. The second event also carries color: red, which is event-specific.

Default rendering: swimlanes. When [Group] headers exist, the timeline renders each group as a horizontal swimlane with a labeled header band and a ▼ collapse toggle. Clicking the header toggles between expanded (events visible) and collapsed (single date-range summary bar showing Group (N events)). Ungrouped events appear in an implicit (Other) lane at the bottom. Use sort time to opt out of swimlanes and render events as a flat time-sorted list instead.

15.6 Options (Space-Separated, NO Colon)

// opt out of swimlanes — flat, time-sorted layout
sort time
// explicit grouped layout (default when [Group] exists)
sort group
// swimlane axis (canonical); equivalent to `sort tag:GroupName`
lane-by GroupName
// back-compat spelling of lane-by
sort tag:GroupName
active-tag CrewName
active-tag none
no-scale

Precedence (when multiple sort hints apply):

1. sort tag:X — tag swimlanes (cross-cutting), takes priority over groups
2. [Group] headers present (no sort directive) — group swimlanes (default)
3. sort time — flat interleaved, ignores groups

15.7 Tags

Tag groups follow §1.3. Tag aliases work in trailing metadata:

tag Crew as p
  Blackbeard red
  Bonnet green

1718-05 Blockades Charleston p: Blackbeard
1716 -> 1717 Sails under Hornigold p: Bonnet

16. Data Charts

Conventions shared across all data charts

Every section under §15 follows the same two rules. Each sub-section may add chart-specific shape, but the rules below are authoritative and apply uniformly.

Rule A — data-row values are space-separated (canonical); commas are accepted. Values within a row are canonically separated by spaces. Commas do not error: thousands grouping inside a number is normalized (1,000 → 1000), and separator commas between values are tolerated (Q1 400, 700 parses the same as Q1 400 700). An underscore digit-group separator is also accepted (1_000). Write new diagrams space-separated, without thousands commas.

History: a 1.0-era rule briefly made commas a hard error (E_DATA_COMMA_REMOVED, 2026-06-14); decision #28 deleted the E_*_REMOVED family and settled on tolerant acceptance — spaces canonical, commas accepted.

Q1 400 700 300 500    ✅  canonical
Q1 400, 700, 300, 500 ✓  accepted — separator commas tolerated
Revenue 1000          ✅  canonical
Revenue 1,000         ✓  accepted — thousands grouping, parses as 1000
Revenue 1_000         ✓  underscore grouping accepted

Comma handling above concerns only the value region of a data row. Commas in metadata (Foo t: a, b), axis labels (x-label Low, High), series/column declarations (series A, B), quoted strings, and prose were never in question.

Rule A-bis — labels ending in a number, and surplus values. The parser peels trailing numbers off a row as values. On a single-value row (no series/stack/group block) the last token is the value and everything before it is the label, so Day 1 8 → label Day 1, value 8 — the common axis-label pattern (Day N, Q3 2024) works as written, no quoting needed. Quote a label only when it is nothing but a number, or to be explicit. In multi-value mode the series block fixes an exact count, so a surplus of trailing numbers is genuinely ambiguous and warns, naming the quoted rewrite (Armor 50 60 70 80 with 2 series → “has 4 value(s), but 2 series defined… quote it: "Armor 50 60" 70 80”). This mirrors the treemap/ER leaf-label quoting rule (§24C, §9).

Day 1 8              ✅  single-value: label "Day 1", value 8 — no quoting needed
"Region 2" 400       ✅  quoted — label "Region 2", value 400
Armor 50 60 70 80    ⚠  multi-series (2 defined): surplus warns, suggests "Armor 50 60" 70 80

Rule B — list-of-labelled-items directives prefer the indented block form. Directives that take a list of labelled items (series, tag, categories, and any similar construct) should use the indented one-per-line form. A comma-separated one-line form is tolerated for very short lists (≤3 items, no colour annotations, no spaces in names) but is not idiomatic.

series                               ✅  preferred
  Cloud Platform blue
  Legacy Suite red
  Mobile App green
  Analytics orange

series Cloud blue, Legacy red        ⚠  tolerated (back-compat); prefer the block

Parsers accept either form everywhere. The rules above are authoring guidance, not parser constraints.

15.1 Simple Charts (bar, line, pie, polar-area, radar)

Declaration: bar [Title], line [Title], etc.

Multi-series:

• bar — a layout block header declares the series AND the layout: stack (stacked bars, one bar per category) or group (clustered, side-by-side). series is not accepted on a bar chart (decision #24).

  stack            // or: group
    Cloud Platform blue
    Legacy Suite red

• line — a series block (every series is plotted). Follows Rule B (prefer the indented block); series A, B one-line form also parses.

  series
    Cloud Platform blue
    Legacy Suite red

• radar — a series block plots one polygon per series over the shared axes, each in its series color (palette index or the trailing color token), with the standard series legend. Same series block form as line; the dual-axis grouping (§15.1.1) is line-only. Each data row still carries one value per series (Firepower 85 70 95).

  series
    Black Pearl blue
    Flying Dutchman purple

Data rows — follows Rule A (space-separated, no colons):

Label 100
Label 100 200 300
Label color 100        // trailing color before numeric values
Q1 400 700 300 500

Options (space-separated, NO colon):

x-label X Label
y-label Y Label
orientation-horizontal   // bar: horizontal bars
fill                     // line: fill the area under the line
hole                     // pie: doughnut ring (bare, or a ratio e.g. `hole 0.5`)
no-center-total          // pie: hide the center total (shown by default with `hole`)
no-auto-y                // line: anchor the y-axis at 0 (opt out of auto-fit)

• orientation-horizontal (bar; default is vertical bars)
• fill (line; fills the area under the line)
• no-auto-y (line only) — opt out of the data-driven y-axis. By default a line chart auto-fits its y-axis to a padded window around the data (min→max across all series and both axes, ~5% headroom each side, then .nice()-rounded), so a tight cluster of values (e.g. weekly 315→395 lbs) fills the plot instead of hugging the top of a forced 0→400 scale. no-auto-y restores the 0 baseline for magnitude honesty. Non-negative data never auto-fits to a negative floor. Bar charts always anchor at 0 (bar length encodes magnitude) and ignore this flag — it is line-only.
• hole (pie; renders the doughnut ring — bare hole, or hole <0–0.9> for a custom inner-radius ratio. The value total shows in the center by default; suppress with no-center-total)
• Stacked vs. clustered bars are chosen by the stack / group header above — there is no separate stacked option.
• title directive removed — the chart title is line 1 (bar My Chart). Using title raises an error diagnostic with a fix-hint pointing at the declaration line.
• Legend renders by default; suppress with the universal no-legend (§1.9)

Value-display flags — show-everything default. Every renderable part is on by default on every data chart. Authors suppress with no-*. Three flags:

• no-name — hide the segment / point / cell / node / set name
• no-value — hide the numeric value
• no-percent — hide the percentage (share-of-total on the pie family; stage-over-stage conversion on funnel)

Each chart family honors only the subset of flags that has a renderable atom on that chart. Flags that don’t apply are silently no-op (typos, future flags, copy-paste from other chart types). Per-chart honoring at runtime:

There are no show-* flags (org’s show-sub-node-count is the one documented exception, §7.5). A flag exists only to suppress a default-on behavior. To restore a suppressed part, remove the flag.

Cartesian value labels: bar and line render values atop each bar / at each data point by default. On horizontal bars (orientation-horizontal), values render to the right of each bar. labelLayout: { hideOverlap: true } suppresses overlapping labels at high data-point density. Add no-value to opt out wholesale.

Stacked-bar clarification: on a stack-layout bar chart, no-value suppresses per-segment values inside each stack — not stack totals. Stack totals are a separate (currently unrendered) concept.

Eras (line only):

era Day 1 -> Day 3 Rough Seas red

15.1.1 Dual y-axes (line)

A line chart can plot series against two independent y-axes — one on the left, one on the right — so two metrics with unrelated units and ranges share an x-axis (e.g. oil price in $/barrel vs. reserve size in million barrels). Each axis auto-scales to the range of the series assigned to it.

Dual axes are expressed by grouping the series block under axis-label headers. A series block whose indented children include a y-label and/or y-right-label header is in grouped form: each header opens an axis group, and the series indented beneath it are assigned to that axis. The header’s text is that axis’ label.

line Oil Price vs Strategic Reserve
series
  y-label $ / barrel
    Oil Price blue
  y-right-label Million barrels
    SPR Size green
    China Reserves orange

2020 40 640 920
2021 68 620 1010
2022 95 372 1090

• Left = y-label, right = y-right-label. Side is keyword-driven, not positional; a group may list any number of series, and the right axis can hold more than one (above, SPR Size and China Reserves).
• At most two axes. A second y-label (or second y-right-label) header merges into the same side — there is no third axis.
• Value order is unchanged. Data rows stay positional across both groups in document order: 2020 40 640 920 → Oil=40 (left), SPR=640 (right), China=920 (right). Each row still needs one value per series (§15.1).
• Single-axis is the flat form. A flat series block (no headers) and a top-level y-label option behave exactly as before — single-axis charts are untouched. A grouped block with only a y-label (no right group) renders single-axis; the wrapper is unnecessary but harmless.
• Rendering aids. Only the left axis draws gridlines (a second grid would not align); an axis owned by exactly one series adopts that series’ color (axis line, ticks, name) so each line pairs with its scale at a glance.

Diagnostics:

• y-right-label (or a right group) on a non-line chart type → warning; the secondary axis is dropped.
• A y-right-label with no series assigned to the right axis → warning (wrap the intended series in a y-right-label group).

Combo (bar + line on dual axes) is deferred. A per-series mark token (bars on one axis, a line on the other) is intentionally not in 1.0 — see dgmo-language-spec-decisions.md. Today every series in a dual-axis chart renders as a line.

Removed in 1.0 (decisions #23–#27): the standalone area, multi-line, doughnut, and bar-stacked chart types no longer exist. Use line + fill (area), line + a series block (multi-line), pie + hole (doughnut), and bar + a stack header (stacked bars; group for clustered). Authoring one of the removed type keywords is a hard error.

15.2 Scatter / Bubble Charts

Data rows — follows §15 Rule A (space-separated, no colon):

Name x y
Name x y size

Categories:

[Caribbean] red
  Blackbeard 90 8500

Options:

x-label Weight
y-label Height
size-label Crew
no-name

Point names render by default. Use no-name to hide them.

15.3 Heatmap

Columns — follows §15 Rule B (prefer the indented block for multiple columns):

columns
  Jan
  Feb
  Mar

Short one-line form is tolerated: columns Jan Feb Mar.

Data rows — follows §15 Rule A (space-separated, no colon):

RowLabel 5 4 3

15.4 Function Charts (Colon REQUIRED)

function Trajectories
x-label Distance
y-label Height
x 0 to 250

15 degrees blue: -0.001*x^2 + 0.27*x
45 degrees red: -0.003*x^2 + 0.75*x

The colon between name and expression is required — both sides can contain spaces, so colon is the unambiguous delimiter.

Options:

• fill (boolean; off by default, shades the area below each curve when enabled — same directive as line + fill, §14; 25% palette tint, or opaque with fill-solid)

15.5 Sankey Charts

Tree structure (indented, space-separated):

Sugar Plantations green
  Tortuga Distillery orange 3000
  Nassau Distillery 2500

Explicit links:

Source -> Target 3500
Source -- Target 2000
Source -> Target 3500 red    // optional trailing-token link color

-> = directed, -- = undirected. Data values follow §15 Rule A. A trailing color word AFTER the numeric flow value colors the link (sankey is the one chart type where edges carry data, so they still accept a color slot).

Emphasis (§1.11) — sankey supports the highlight / dim family:

dim Spoilage                 // the Spoilage node and its ribbons recede
highlight Barrel Aging       // the Barrel Aging flow stays lit; everything else recedes

highlight lights the named node’s flow closure — everything upstream that feeds it plus everything downstream it feeds — so the path that explains the node stays visible. dim recedes exactly the named nodes and no more. A ribbon is receded when either endpoint is; the dim multiplies the ribbon’s existing translucency rather than replacing it, so a dimmed flow is never more solid than an undimmed one.

15.6 Funnel Charts

Data rows — follows §15 Rule A (space-separated, no colon):

Visits 1200
Signups 800
Purchases 200

Rendering: each stage’s name sits to the left of its band (in the band’s color); its value is centered inside the band (falling back beside it when the band is too narrow); a muted stage-over-stage conversion % sits to the right — no leader lines. The first stage carries no % (nothing to convert from). no-percent hides the conversion %.

17. Visualizations

16.1 Slope Charts

slope Fleet Strength

period 1715 1725

Blackbeard 40 4
Roberts 12 52

• Period directive required: period Label1 Label2 (one-line) or indented block for multi-token labels:

  period
    Before COVID
    After COVID

• Data rows: Label value1 value2 — follows §15 Rule A (space-separated canonical; commas accepted — thousands grouping 1,000 → 1000 and separator commas both parse, per #28)
• Underscore grouping 1_000 also accepted
• Color annotations: Label color value1 value2 (trailing color word before numeric values)
• Minimum 2 periods required

16.2 Wordcloud

wordcloud Pirate Skills
rotate none
max 50
size 14 80

swordsmanship 95
navigation 88

• Data: space-separated only (word value)
• Options: rotate none|mixed|angled, max N, size min max

16.3 Arc Diagrams

arc Pirate Alliances

[Caribbean] red
  Blackbeard -> Bonnet 8
  Blackbeard -> Vane 5

order group

• Link: Source -> Target [color] weight — space before the optional trailing color and weight
• Options: order appearance|name|group|degree
• orientation-vertical (boolean; default horizontal) — draw the spine top-to-bottom with nodes down the axis. Standard boolean form (§4.6), matching orientation-horizontal on bars.
• Groups: [Group Name] color declares a band; its member links must be indented under the header (an un-indented link closes the group). The band is filled with the group’s color, and every arc inherits its source node’s group color — an explicit per-link color still wins, and a link whose endpoints are ungrouped falls back to the palette cycle.
• layout arc|chord — layout selector over the same pairwise edges. arc (default) draws nodes on a line with connecting arcs; chord arranges them around a circle (the circular “chord” layout). There is no standalone chord chart type — the circular layout is reachable only through arc + layout chord (decision #29).

arc Inter-Department Collaboration
layout chord

Engineering -> Design 85
Design -> Product 68

16.4 Venn Diagrams

venn Skill Overlap

Swordsmanship as sw red
Navigation as nav blue
Leadership as lead green

sw + nav Sea Raiders
sw + nav + lead Legendary Pirates

• Set declaration: Name [as <alias>] [color] — color is the line-trailing token, AFTER the optional alias (universal modifier order, §2A.2)
• Intersections: Set1 + Set2 Label — label follows the last set reference (no colon)
• Legacy Name(color) alias X emits E_VENN_ALIAS_KEYWORD_REMOVED per TD-18

16.5 Quadrant Diagrams

quadrant Crew Assessment
x-label Low Skill, High Skill
y-label Low Loyalty, High Loyalty

top-right Promote green
top-left Train yellow
bottom-left Maroon red
bottom-right Watch Closely purple

Quartermaster 0.9 0.95
Navigator 0.85 0.8

• Axis labels: x-label Low, High — comma-separated (this is a low/high pair, not a data row; comma is the delimiter here by design)
• Position labels: top-right Label — space-separated
• Data points: Label x y — follows §15 Rule A (space-separated canonical; Label x, y also parses — separator commas are tolerated per #28. The axis-label comma above is a true delimiter by design)

18. Mindmap Diagrams

17.1 Declaration

mindmap [Title]

• First line declares chart type and optional title
• Title doubles as the root node — mindmap Product Strategy creates a root node labeled “Product Strategy”
• mindmap alone (no title) enables multi-root mode; title is inferred from the first root

17.2 Nodes

Nodes are defined by indentation:

mindmap Root
  Level 1a
    Level 2a
    Level 2b
  Level 1b

• Indentation establishes parent-child hierarchy
• When title is present, indent-0 lines are children of the title root
• When title is absent, indent-0 lines are independent roots (multi-root)
• Node coloring: use tags (§2)

17.3 Same-Line Metadata

Node priority: High, status: Done
Node description: Short note
Node collapsed: true

• Standard same-line metadata syntax (colons required)
• description is extracted as a dedicated field (not generic metadata)
• collapsed: true sets default collapsed view state for that subtree

17.4 Description Field

Two forms:

// Same-line form
Surveys description: Quarterly NPS survey

// Indented form (colon required; bare `description OAuth …` is REMOVED → error)
Auth System
  description: Handle login, signup, and OAuth flows
  description: OAuth includes Google and GitHub
  Login Page

• description: text (colon required; the bare description text form is removed at 1.0 and emits E_DESCRIPTION_BARE_REMOVED, an error)
• Both same-line and indented forms set the same description field
• Same-line form takes precedence if both are specified
• Multiple description lines accumulate into a multi-line description
• Indented description must appear before child nodes (warning if after)
• Empty description: (no value) is silently skipped
• Bare Description (no trailing text) is treated as a child node name, not a description
• Only description / description: is recognized as indented metadata — all other indented lines are child nodes (e.g., role: Engineer becomes a child node, not metadata)
• Supports inline markdown: **bold**, *italic*, `code`, [links](url)
• - bullet text renders as • bullet text

17.5 Multi-Root

mindmap

Q1 Goals
  Ship MVP
Q2 Goals
  Launch marketing

• No title on first line enables multi-root mode
• Each indent-0 line starts a new root tree
• Title is inferred from first root’s label

17.6 Tags

Standard tag declarations (§1.3):

mindmap Root

tag Priority as p
  High red
  Low green

  Task p: High

Parent → child cascade. A tag value set on a node cascades to its descendants: a sub-node with no value of its own for that group inherits the value of its nearest tagged ancestor. A sub-node’s own value always overrides the inherited one and re-roots the cascade for its own subtree. This lets you tag a category once and have the whole branch pick up the color:

mindmap Wine Varieties

tag Style as s
  Red red
  White white
  Sparkling yellow

Whites s: White
  Chardonnay            // inherits White
  Sauvignon Blanc       // inherits White
    Loire s: Sparkling  // overrides → Sparkling (and its subtree)

Cascade only flows from an explicitly tagged ancestor. A node with no tagged ancestor falls back to the group’s global default (the first declared value) — it does not inherit across an untagged parent.

17.7 Options

Options are bare keywords or key value on their own line, before content.

17.8 Collapse/Expand

• Nodes with children can be collapsed/expanded in the app
• collapsed: true in same-line metadata sets the default collapsed state
• Collapsed nodes show a drill-bar (accent bar at bottom)
• Collapse is portable view-state (§1) — the app writes/removes the marker on toggle and any renderer reproduces it from source

17.9 Full Example

mindmap Product Strategy

tag Priority as p
  High red
  Medium yellow
  Low green

tag Department as d
  Engineering blue
  Design purple
  Marketing orange

Research d: Marketing
  User Interviews p: High
    Surveys description: Quarterly NPS survey
    Focus Groups
  Competitor Analysis d: Engineering
    Feature Matrix
    Pricing Review
Development p: High, d: Engineering
  MVP Features
    Auth System
      description: Handle login, signup, OAuth flows
    Dashboard
  Nice-to-haves p: Low, collapsed: true
    Dark Mode
    Export PDF
Go-to-Market d: Marketing
  Launch Plan
    Blog Post
    Demo Video description: 2-min product walkthrough

19. Wireframe Diagrams

18.1 Declaration

wireframe [Title]

• First line declares chart type and optional title
• wireframe Login Page creates a wireframe titled “Login Page”

18.2 Form Factor

mobile

• mobile keyword switches to a narrow vertical layout (375px viewport)
• Default (no keyword) is desktop layout (1200px viewport)
• Must appear before diagram content

18.3 Visual-Mnemonic Element Syntax

Elements use bracket shapes that visually suggest their rendered control:

18.4 Keyword Elements

Nine special keyword elements render common UI patterns:

Table explicit rows: comma-separated values, first row is the header.

table
  Name, Email, Role
  Alice, alice@co.com, Admin
  Bob, bob@co.com, User

Image and chart hints appear after the keyword:

image round
image wide
chart line
chart bar
chart pie

18.5 Flags (Trailing-Keyword List)

(Submit) primary
[Email] disabled
(Delete) destructive ghost

Wireframe flags are a trailing-keyword list in the same slot occupied by the §1.5 trailing-token color rule on other chart types: any whitespace-delimited lowercase tokens at the end of an element line, drawn from the closed 16-keyword flag enum below, are extracted as flags. Multiple flags are space-separated (NOT comma-separated). Flag extraction stops at the first token that is not in the enum — everything to the left is the element’s literal label.

(Submit) primary                            // label = "Submit",  flags = [primary]
(Submit) primary destructive                // label = "Submit",  flags = [primary, destructive]
(Save Changes) primary                      // label = "Save Changes", flags = [primary]

Available flags (closed enum — 16 keywords):

Indented fallback

For elements where the trailing-keyword form is ambiguous or visually noisy (long flag lists, labels that need to clearly read as labels), drop the trailing tokens and indent the flags one level deeper. Both forms produce the same parsed element.

(Submit) primary destructive                 // canonical trailing-keyword form

(Submit)                                     // indented fallback — same semantics
  primary
  destructive

Indented flag lines under a wireframe element follow the same reserved-key-registry dispatch (§1.4.2): the parser recognizes lines whose first token is in the 16-keyword flag enum and attaches them as flags. Indented lines that don’t match flag keywords fall through to child-element grammar.

Label-vs-flag collision

When an element’s literal label happens to lexically match a flag keyword (e.g. a button literally named “Primary”), authors have two escape hatches:

1. §1.5 capitalization rule. Flag extraction is case-sensitive lowercase — (Primary) is a button labeled “Primary” with no flags; (primary) is the lowercase form and gets matched against the flag enum (parsed as a label with no flags too, because the lone primary is the label, not a trailing token).
2. Indented form. Drop the trailing tokens and indent flags — unambiguous regardless of label content.

(Primary)                                    // label = "Primary", no flags
(Primary) primary                            // label = "Primary", flags = [primary]
(Primary)                                    // indented fallback for clarity
  primary

Authoring guidance: capitalize wireframe element labels ((Submit), (Cancel), (Delete) rather than (submit), (cancel), (delete)) to match real-world UI button conventions and to keep the lowercase flag enum from colliding lexically with labels. Lowercase labels remain valid but produce visually confusing source where label and flag share the same token shape.

18.6 Multi-Element Lines

Two or more elements on the same line, separated by 2+ spaces:

[First Name]  [Last Name]
(Cancel)  (Submit) primary

• 2 segments with bare text + element = label-field pairing:

  Email  [user@example.com]

• 3+ segments = inline items laid out horizontally:

  (Back)  (Next)  (Skip)

18.7 Layout Model

• Desktop (default): 1200px viewport, horizontal regions. Region names like “sidebar” get smart sizing (~25% width); “main” or “content” fills remaining space.
• Mobile: 375px viewport, all regions stack vertically.

Regions are defined by top-level groups:

wireframe Dashboard

[Sidebar]
  nav
  - Overview
  - Settings
[Main]
  # Dashboard
  chart line

18.8 Group Disambiguation

The [text] syntax is ambiguous — it renders as a text input when it has no children, or a group/container when it has indented children:

[Search]              // text input (no children = leaf)

[Search Form]         // group (has children below)
  [Query]
  (Search)

Group-only flags (horizontal, scrollable, collapsed) force group interpretation even without children:

[Empty Panel] collapsed      // group (forced by flag)

18.9 Full Example

wireframe E-Commerce Product Page

[Header]
  nav
  [Search] empty
  (Cart)  (Account)

[Breadcrumb] horizontal
  - Electronics
  - Phones
  - Galaxy S25

[Main Content] horizontal
  [Product Images]
    image wide
    image  image  image

  [Product Details]
    # Galaxy S25
    ## $899.99

    {Black | White | Blue}

    Quantity  [1]
    (Add to Cart) primary
    (Buy Now) ghost

    ---

    ## Description
    The latest flagship phone with advanced AI features,
    a stunning display, and all-day battery life.

    ---

    ## Specifications
    table
      Feature, Detail
      Display, 6.2" AMOLED
      Processor, Snapdragon 8 Gen 4
      RAM, 12GB
      Storage, 256GB

[Reviews]
  # Customer Reviews
  progress 85

  table 3x4

[Footer]
  - About
  - Contact
  - Privacy Policy
  - Terms of Service

20. Tech Radar Diagrams

Tech radars visualize technology adoption decisions across an organization, inspired by the ThoughtWorks Technology Radar format.

Declaration

tech-radar Title

Rings Block

Ring names are declared in a rings block, one per indented line. Order is innermost (first) to outermost (last). Variable count supported.

rings
  Adopt
  Trial
  Assess
  Hold

Quadrant Sections

Exactly 4 quadrants required, each as a top-level section header with same-line metadata specifying position:

Techniques quadrant: top-right
Tools quadrant: top-left
Platforms quadrant: bottom-left
Languages & Frameworks quadrant: bottom-right

Positions: top-left, top-right, bottom-left, bottom-right. Each position must be used exactly once.

Optional color override: Tools quadrant: top-left, color: purple

Default colors by position: top-left=blue, top-right=green, bottom-left=red, bottom-right=orange.

Blips

Blips are indented under their quadrant. Each blip requires ring metadata matching a declared ring name. Optional trend metadata specifies movement direction.

  Continuous Deployment ring: Adopt, trend: stable
  Micro Frontends ring: Trial, trend: up

ring (required): Must match a declared ring name exactly (case-insensitive).

trend (optional): new, up, down, stable. No indicator rendered if omitted.

Descriptions

Further-indented lines below a blip are collected as description text. Supports simple markdown (bold, italic, inline code, links).

  Rust ring: Assess, trend: new
    Evaluating for **performance-critical** services.
    See [evaluation doc](https://wiki.example.com/rust).

Global Numbering

Blips receive sequential global numbers for unambiguous reference. Order: quadrants clockwise (top-left, top-right, bottom-right, bottom-left), then by ring (innermost first), then by declaration order.

Directives

Top-level bare keywords that toggle rendering behavior. Place after the chart-type declaration, before the rings block.

Complete Example

tech-radar Engineering Tech Radar Q2 2026

rings
  Adopt
  Trial
  Assess
  Hold

Techniques quadrant: top-right
  Continuous Deployment ring: Adopt, trend: stable
    Fully adopted across all services.
  Infrastructure as Code ring: Adopt, trend: stable
  Micro Frontends ring: Trial, trend: up

Tools quadrant: top-left
  GitHub Copilot ring: Trial, trend: new
  Vite ring: Adopt, trend: up
  Webpack ring: Hold, trend: down
    Migrating to Vite across all projects.

Platforms quadrant: bottom-left
  Kubernetes ring: Adopt, trend: stable
  Cloudflare Workers ring: Trial, trend: up

Languages & Frameworks quadrant: bottom-right
  TypeScript ring: Adopt, trend: stable
  Rust ring: Assess, trend: new
    Evaluating for performance-critical services.
  React ring: Adopt, trend: stable

21. Cycle Diagrams

Cycle diagrams show a circular process flow where nodes are arranged on a circle and directed edges connect each node to the next, with the last node wrapping back to the first. Common use: OODA loops, PDCA, product lifecycles, continuous improvement.

Render category: visualization

20.1 Chart Type Declaration

cycle [Title]

20.2 Nodes

Top-level (non-indented) lines declare nodes. Nodes are positioned on a circle in declaration order.

NodeLabel
NodeLabel color: blue, span: 3, description: inline text

Node Same-Line Metadata

20.3 Node Descriptions

Indented lines under a node are descriptions. Markdown inline formatting is supported: **bold**, *italic*, `code`, [links](url). Bullet points: - item renders as • item.

Observe blue
  Gather raw information from the environment
  Monitor unfolding circumstances

If both description: text (same-line) and indented lines exist, they concatenate (same-line first, then indented).

20.4 Edges

Edges are implicit — every node connects to the next in declaration order, with the last wrapping to the first. The -> syntax annotates edges with labels, descriptions, and styling; omitting -> lines just means unstyled edges.

-Label-> color: red, width: 6
->
-> width: 4

Indented under a node, before or after description lines. Explicit targets after -> (e.g., -> Orient) are accepted but silently ignored — cycle edges always connect to the next node. If the explicit target doesn’t match the actual next node, an info diagnostic is emitted.

Edge Same-Line Metadata

Edge Descriptions

Indented lines under an edge line are edge descriptions:

Observe blue
  -Unfold circumstances->
    Synthesize raw data into actionable context
    Identify **key patterns** and anomalies

20.5 Directives

20.6 Parsing Constraints

• Node labels cannot contain -> or <- — parse error with helpful message
• Lines starting with - followed by text and -> are edges; bare - followed by non-arrow text is a description (bullet point)
• Minimum 2 nodes required — parse error on fewer
• span must be a positive number — parse error on zero or negative

20.7 Complete Example

cycle OODA Loop

Observe blue
  Gather raw information from the environment
  Monitor unfolding circumstances
  -Unfold circumstances-> color: blue
    Synthesize raw data into actionable context
    Identify **key patterns** and anomalies

Orient green
  Analyze and synthesize observations
  Form a mental model of the situation
  -Form hypothesis-> color: green

Decide orange
  Select a course of action
  -Commit to action-> color: orange

Act red
  Execute the chosen course of action
  Generate results that feed back
  -Generate feedback-> color: red
    Results flow back into observation

22. Journey Map Diagrams

Chart Type Declaration

journey-map [Title]

The journey-map keyword must appear on the first line. No inference — explicit declaration required (avoids conflict with kanban’s identical [Column] + indented items pattern).

Persona

persona Name
  Optional indented description text

Declares the journey’s protagonist. Name is everything after persona (rest-of-line). Bare persona with no name is an error. Only one persona per diagram. A §1.5 trailing-token color sets the card color (persona Nadia green); capitalize the word (persona Nadia Green) to keep it as literal name text, or use the color: long form (persona Nadia color: green). The indented description supports the same rich text as notes: bullet lines (- / * → a hanging ”•”) and inline markdown (**bold**, *italic*).

Phases

[Phase Name]
  Step Name score: 4

Phases are declared with bracket syntax at indent 0. Steps are indented within phases. Phases are optional — steps can appear at root level for a flat continuous flow.

Steps

Steps appear indented within phases (or at indent 0 in flat mode).

Score syntax — score and emotion are explicit keys:

// score only
Step Name score: 4
// score + emotion label (single word)
Step Name score: 4, emotion: Delighted
// score + tag metadata
Step Name score: 4, ch: Web
// score + label + metadata
Step Name score: 4, emotion: Delighted, ch: Web
// no metadata = scoreless step
Step Name

• Score scale: 1–5 integer, high = good. Floats, negatives, out-of-range values produce parse errors.
• Emotion label: optional single word (e.g., Frustrated, Delighted, Neutral). Multi-word labels are rejected.
• Scoreless steps: render as cards but produce no emotion curve point. A diagnostic hint is emitted.
• Legacy bare-score (Step | 4 Delighted) is removed. A line of shape <name> | <N> (or | <N> <Word>) emits E_JOURNEY_BARE_SCORE_REMOVED with hint to use score: <N>, emotion: <Word>.

Annotations

Annotations appear as deeper-indented lines under a step:

  Step Name score: 2
    pain: Wants guest checkout
    opportunity: Add setup guide
    thought: Excited to try it
    description: Additional context

• pain: — pain point (rendered in red)
• opportunity: — improvement opportunity (rendered in green)
• thought: — user thought (rendered in italic)
• description: — general context text

Multiple annotations per step are allowed.

Tag Blocks

Standard tag blocks with aliases and colored entries:

tag Channel as ch
  Web blue
  Mobile purple
  In-Person green

Tag values referenced in step metadata via alias: Step score: 4, ch: Web

Directives

Visual Rendering

• Emotion curve: filled area chart (mood landscape) with gradient — green above midline (3), red below. The curve is the hero visual element.
• Grid lines: subtle horizontal lines at score levels 1–5 behind the curve.
• Step cards: color-intensity mapped to score (1=red → 5=green, palette-aware).
• Phase headers: color auto-derived from average step score within the phase.
• Sharp-drop zones: auto-accent where score drops by ≥ 2 between consecutive scored steps.
• Score legend: auto-generated.

Flat Mode

Steps at root level (no [Phase] brackets) render as a continuous horizontal strip with emotion curve:

journey-map Quick Feedback

Opened app score: 4
Searched for feature score: 3
Hit error score: 1, emotion: Frustrated
  pain: No helpful error message
Contacted support score: 2
Got resolution score: 5, emotion: Relieved

Full Example

journey-map Buying a Laptop

persona Tech-Savvy Shopper
  28yo developer, price-sensitive, does extensive research

tag Channel as ch
  Web blue
  Mobile purple
  Email teal
  In-Person green

[Research]
  Compare specs score: 4, ch: Web
    description: Checked 12 laptops across 4 review sites
  Watch reviews score: 5, emotion: Engaged, ch: Mobile
  Ask friends score: 4, ch: In-Person

[Purchase]
  Add to cart score: 3, ch: Web
  Forced account creation score: 1, emotion: Frustrated, ch: Web
    pain: Wants guest checkout
    pain: Password requirements too strict
  Complete payment score: 3, ch: Web

[Delivery]
  Track package score: 4, ch: Mobile
  Unboxing score: 5, emotion: Delighted, ch: In-Person
    opportunity: Include setup guide
    thought: Excited to try it out

Minimal Example