Declart

Declare what to show. The engine decides how it looks.

Declart is a declarative diagram engine. You write a TOML file describing the structure of your diagram, and Declart renders it to SVG. No layout coordinates. No styling choices. Just content.

Quick Start

CLI

# Install
cargo install declart-cli

# Scaffold a starter diagram
declart init flow > diagram.toml

# Render to SVG
declart render diagram.toml

# Render to PNG
declart render diagram.toml --format png

# Watch and auto-rebuild on changes
declart watch diagram.toml

# Validate without rendering
declart validate diagram.toml

# Also fail when a label would be cut short with "…"
declart validate --strict diagram.toml

Node.js

const declart = require('@iyulab/declart');

const svg = declart.render(`
kind = "flow"
view = "cycle"
title = "PDCA"
[[items]]
label = "Plan"
[[items]]
label = "Do"
`);

Vite / ESM (type resolution): With moduleResolution: "bundler" (Vite default), types resolve automatically (v0.18.0+). For older setups add "moduleResolution": "node" to tsconfig.json or declare types manually in vite-env.d.ts.

Note: This package is a Node.js-runtime WASM build. It works in Vite SSR / Node.js environments. Importing it directly in a browser bundle will throw Cannot find module 'fs'.

Rust (library)

#![allow(unused)]
fn main() {
use declart_core::{parse, render};
use declart_core::render::DEFAULT_THEME;

let diagram = parse(input)?;
let svg = render(&diagram, &DEFAULT_THEME)?;
}

Supported Kinds

KindViews
flowprocess (default), cycle, funnel, swimlane
tierpyramid (default), concentric
hierarchyorg_chart (auto), fishbone (auto), mind_map
timeline—
matrix—
hub_spoke—
venn—
comparison—
state—
system—

Semantic item attributes

Items carry meaning, not styling. Two optional attributes are shared across kinds:

  • emphasis — primary / secondary (importance).
  • status — success / normal / warning / critical (health signal). Rendered as a corner marker dual-encoded by color and shape (circle / triangle / diamond) so it reads in monochrome and for colorblind readers. Supported on flow, tier, hub_spoke, and matrix items.

matrix additionally supports classifying items into quadrants (BCG / Gartner style) via an optional [[items]] array with a quadrant position. See the schema and per-kind pages.

Design Philosophy

See Principles for the full design rationale. The key idea: declarations express what exists, not how it looks. The engine owns visual decisions.

Interactive Playground

→ Open the Declart Playground — no installation required

Edit TOML declarations and see your diagrams rendered live in the browser. All 8 diagram kinds are available, with default and monochrome themes.

Note: The playground requires HTTP to load the WASM module. Use mdbook serve docs/ for local testing rather than opening the file directly.

Declart Grammar Principles

These principles govern every declaration file format in Declart, across all diagram kinds and all implementations.

  1. Design exclusion. Declaration files contain no visual information: no colors, coordinates, fonts, sizes, margins, or layout hints. These are the engine's domain.

  2. Semantics only. Fields express meaning, not appearance. emphasis: primary is allowed; color: red is not. The engine decides how emphasis looks.

  3. LLM-predictable. Field names are single English words. Structure is flat or exactly one level deep ([[items]]). A language model must be able to generate a correct declaration without examples.

  4. Minimal and concise. Each kind defines only its required fields. Optional fields are added only when proven necessary across multiple use cases. When in doubt, leave it out.

  5. One representation per diagram. Each kind + view pair has exactly one valid schema. No aliases, structural variants, or flags that change interpretation. Two declarations expressing the same diagram are byte-for-byte identical except for whitespace.

Common Schema Rules

Rules that apply to every Declart declaration file.

Required fields

FieldTypeDescription
kindstringOne of: flow, tier, hierarchy, timeline, matrix, hub_spoke, venn, comparison, state, system

Optional fields

FieldTypeDescription
titlestringDisplay title rendered above the diagram. Omit to suppress.
viewstringRendering intent within the kind. Valid values depend on kind. Omit to let the engine select automatically.

Item arrays

  • Items are declared as [[items]] TOML array-of-tables.
  • At least one item is required for flow and tier. The matrix kind uses [[quadrants]]; hierarchy uses [[nodes]]; timeline uses [[events]]; hub_spoke uses [[spokes]]; venn uses [[sets]]; comparison uses [[columns]] and [[rows]].
  • Item order in the file is rendering order.

Forbidden fields

Any field not listed in a kind's spec document is forbidden. Forbidden fields cause a parse error. This includes but is not limited to: color, fill, stroke, font, size, x, y, width, height, style, class.

Emphasis (shared optional item field)

When a kind supports item-level emphasis, it uses this field:

ValueMeaning
primaryMost important item in the diagram
secondarySecondary importance

The engine decides visual representation. Omitting emphasis means default weight.

  • primary: white outline stroke + bold text
  • secondary: lighter color tint

Status (shared optional item field)

A semantic condition signal — the "traffic-light" state common in reports and dashboards. status is orthogonal to emphasis: emphasis expresses importance, status expresses health / severity. An item may carry both at once.

ValueMeaning
successExplicitly good / done
normalAssessed as nominal (the unmarked baseline)
warningNeeds attention
criticalFailing / blocked / urgent

The engine decides visual representation — you declare meaning, not color. The current engine renders a small corner marker, dual-encoded by both color and shape so it remains readable in monochrome and under color-vision deficiency: success = circle, warning = triangle, critical = diamond. The marker stays visually independent of emphasis. normal and omitted status render no marker. Marker colors come from the active theme's status palette (the accessible theme uses a colorblind-safe Okabe-Ito palette).

Supported on items of: flow (process / cycle / funnel / swimlane), tier, hub_spoke, matrix (quadrants), timeline (milestones and periods). Like emphasis, declaring it on a kind that does not support it is a parse error.

Using Claude or GPT to Generate Declart Diagrams

Declart's TOML format is designed for LLM generation. The structure is explicit and validated — an LLM can produce a well-formed diagram in one shot, and declart validate catches any mistakes before rendering.

Why Declart works well with LLMs

  • No layout decisions: the LLM only writes content (labels, structure). The engine handles all visual choices.
  • Strict schema: deny_unknown_fields means invalid keys are caught immediately. The LLM cannot silently produce a broken diagram.
  • Explicit kind: the kind field tells the parser exactly what to expect. No ambiguity.
  • Short format: a typical diagram is 5–20 lines of TOML.

Kind and View

Declart v0.16+ uses a two-level structure:

  • kind — the data contract (determines which fields are valid)
  • view — the semantic intent (determines how the engine renders it)
kindviewsNotes
flowprocess (default), cycle, funnel, swimlaneview optional — defaults to process. swimlane requires an actor per item
tierpyramid (default), concentricRanked levels (pyramid) or nested rings / onion (concentric) — view optional
hierarchyorg_chart, fishbone, mind_mapview optional — org_chart/fishbone auto-selected by root count; mind_map must be explicit
timeline—No view field
matrix—No view field
hub_spoke—No view field
venn—No view field
comparison—No view field
state—No view field. States + directed transitions
system—No view field. Nodes in nested groups + labelled links. At most 16 nodes, 6 groups, 24 links

Workflow

1. Prompt LLM → TOML output
2. declart validate diagram.toml   # catches errors with clear messages
3. declart render diagram.toml     # produces SVG

If validate fails, paste the error message back to the LLM and ask it to fix the specific field.

A declaration can be valid and still not fit: a label too long for its slot is cut short with "…" in the picture. declart validate --strict (and declart render --strict, which then writes nothing) fails on that, and its message names each label and what to change, so the loop above closes without anyone looking at the SVG.

To write labels that fit in the first place, ask for the limits: declart limits state (Node limits('state')) lists how many Hangul and Latin characters each label slot takes before the engine changes it. The same tables are at the end of every kind's page in the spec.

To write the declaration itself without guessing at a field, ask for the schema: declart schema flow --view swimlane (Node schema('flow', 'swimlane')) lists the fields with their types and allowed values, how many elements each collection takes, and the rules between fields. Every kind's page in the spec ends with the same reference.


Prompt Templates

Tier (Pyramid) — Hierarchies, priority layers

Prompt: "Generate a Declart TOML diagram showing Maslow's hierarchy of needs as a pyramid. Use kind = 'tier', include a title, and list the 5 levels as items from top (apex) to bottom (base)."

kind = "tier"
title = "Maslow's Hierarchy of Needs"

[[items]]
label = "Self-Actualization"

[[items]]
label = "Esteem"

[[items]]
label = "Love & Belonging"

[[items]]
label = "Safety"

[[items]]
label = "Physiological"
emphasis = "primary"

Tier (Concentric) — Nested layers, onion model

Prompt: "Generate a Declart diagram of Clean Architecture as nested layers. Use kind = 'tier' and view = 'concentric', listing items from the innermost core outward."

kind = "tier"
view = "concentric"
title = "Clean Architecture Layers"

[[items]]
label = "Entities"

[[items]]
label = "Use Cases"

[[items]]
label = "Interface Adapters"

[[items]]
label = "Frameworks & Drivers"

Rule: item order reads inner → outer. The first item is the innermost core; each later item is a ring enclosing it. Use concentric for containment / dependency (architecture layers, stakeholder rings); use pyramid for ranking / priority.


Process — Sequential steps, workflows

Prompt: "Create a Declart TOML diagram for a 4-step CI/CD pipeline. Use kind = 'flow' (process view is the default)."

kind = "flow"
title = "CI/CD Pipeline"

[[items]]
label = "Build"

[[items]]
label = "Test"
emphasis = "primary"

[[items]]
label = "Stage"

[[items]]
label = "Deploy"

Cycle — Closed loops, PDCA, lifecycles

Prompt: "Generate a Declart TOML diagram for the PDCA improvement cycle. Use kind = 'flow' and view = 'cycle'."

kind = "flow"
view = "cycle"
title = "PDCA Cycle"

[[items]]
label = "Plan"

[[items]]
label = "Do"

[[items]]
label = "Check"

[[items]]
label = "Act"

Matrix 2×2 — Prioritization, Eisenhower

Prompt: "Create an Eisenhower Matrix in Declart TOML with x_axis = 'Importance' and y_axis = 'Urgency'."

kind = "matrix"
title = "Eisenhower Matrix"
x_axis = "Importance"
y_axis = "Urgency"

[[quadrants]]
label = "Do First"
position = "top-right"
emphasis = "primary"

[[quadrants]]
label = "Schedule"
position = "top-left"

[[quadrants]]
label = "Delegate"
position = "bottom-right"

[[quadrants]]
label = "Eliminate"
position = "bottom-left"

Note: Use position to explicitly place quadrants. Valid values: top-left, top-right, bottom-left, bottom-right.

Item placement (BCG / Gartner): add an optional [[items]] array to classify items into quadrants. Each item needs a quadrant (one of the four positions) and may carry emphasis/status. Assignment is by category, never coordinates. Max 6 items per quadrant.

kind = "matrix"
title = "BCG Growth-Share Matrix"
x_axis = "Market Share"
y_axis = "Market Growth"

[[quadrants]]
label = "Stars"
position = "top-right"
[[quadrants]]
label = "Question Marks"
position = "top-left"
[[quadrants]]
label = "Cash Cows"
position = "bottom-right"
[[quadrants]]
label = "Dogs"
position = "bottom-left"

[[items]]
label = "Product A"
quadrant = "top-right"
status = "success"

[[items]]
label = "Product B"
quadrant = "bottom-left"
status = "critical"

Prompt: "Make a Declart hub-and-spoke diagram with 'Cloud Architecture' as the center and 5 services as spokes."

kind = "hub_spoke"
title = "Cloud Architecture"
center = "API Gateway"

[[spokes]]
label = "Auth Service"

[[spokes]]
label = "User DB"

[[spokes]]
label = "Payment"

[[spokes]]
label = "Notifications"

[[spokes]]
label = "Analytics"

Venn — Set intersections, overlapping groups

Prompt: "Generate a 2-set Venn diagram showing the overlap between 'Frontend Skills' and 'Backend Skills'."

kind = "venn"
title = "Full-Stack Skills"

[[sets]]
label = "Frontend"

[[sets]]
label = "Backend"

[[intersections]]
sets = ["Frontend", "Backend"]
label = "TypeScript"

Timeline — Milestones and periods

Prompt: "Create a Declart timeline of 5 product launch milestones in 2024, using ISO dates."

kind = "timeline"
title = "Product Launch 2024"

[[events]]
date = "2024-01-15"
label = "Alpha"

[[events]]
date = "2024-03-01"
label = "Beta"

[[events]]
date = "2024-06-01"
label = "RC1"

[[events]]
date = "2024-09-15"
label = "GA"

[[events]]
date = "2024-12-01"
label = "v2 Plan"

Rule: dates accept YYYY, YYYY-MM, or YYYY-MM-DD. Partial forms are placed at the start of that year/month. Declart sorts events automatically.

Prompt: "Create a Declart roadmap for 2024 with a kickoff milestone, overlapping beta and pilot phases, and a GA launch."

kind = "timeline"
title = "Product Roadmap 2024"

[[events]]
date = "2024-01-15"
label = "Kickoff"

[[events]]
start = "2024-02"
end = "2024-04"
label = "Private Beta"

[[events]]
start = "2024-03"
end = "2024-09"
label = "Enterprise Pilot"

[[events]]
date = "2024-07-01"
label = "GA Launch"

Rule: an event is a milestone (date) or a period (start + end) — never both. end is inclusive: end = "2024-04" runs through April 30. Periods render as bars below the axis and overlapping periods stack automatically. An event may carry emphasis and status like items in other kinds (a milestone gets a marker beside its label, a period a marker in its bar). There are no dependency or progress fields — timeline is a qualitative roadmap, not a Gantt scheduler.


Fishbone / Ishikawa — Root cause analysis

Prompt: "Generate a Declart fishbone diagram where the effect is 'Slow API Response' with 4 cause categories and sub-causes. Use kind = 'hierarchy' and view = 'fishbone'. Each cause category is a root node; sub-causes have parent = the category label."

kind = "hierarchy"
view = "fishbone"
title = "Slow API Response"

[[nodes]]
label = "Database"

[[nodes]]
label = "Missing indexes"
parent = "Database"

[[nodes]]
label = "N+1 queries"
parent = "Database"

[[nodes]]
label = "Network"

[[nodes]]
label = "High latency"
parent = "Network"

[[nodes]]
label = "Code"

[[nodes]]
label = "Blocking I/O"
parent = "Code"

[[nodes]]
label = "Infrastructure"

Structure: Root nodes (no parent) become cause categories on the spine. Child nodes become sub-causes. The effect field is rendered as the spine-end effect label; if effect is omitted, title is used as fallback.

Limit: 2–20 root nodes (cause categories). Recommend 8 or fewer for readability.


Org Chart — Hierarchical trees

Prompt: "Create a Declart org chart for a small engineering team with a CTO at the top. Use kind = 'hierarchy'. With a single root node, the engine automatically renders as an org chart."

kind = "hierarchy"
title = "Engineering Team"

[[nodes]]
label = "CTO"

[[nodes]]
label = "Frontend Lead"
parent = "CTO"

[[nodes]]
label = "Backend Lead"
parent = "CTO"

[[nodes]]
label = "FE Developer"
parent = "Frontend Lead"

[[nodes]]
label = "BE Developer"
parent = "Backend Lead"

Rule: exactly one root node (no parent). parent references another node's id (preferred) or label. For stable references that survive label renames, add id = "stable-key" to each node and use that in parent. To explicitly select the view: view = "org_chart".


Funnel — Conversion funnels, sales pipelines

Prompt: "Generate a Declart funnel for a 5-stage sales pipeline. Use kind = 'flow' and view = 'funnel'."

kind = "flow"
view = "funnel"
title = "Sales Pipeline"

[[items]]
label = "Leads"

[[items]]
label = "Qualified"

[[items]]
label = "Proposal"

[[items]]
label = "Negotiation"

[[items]]
label = "Closed Won"
emphasis = "primary"

Limit: 2–10 stages.


Comparison — Feature matrices, trade-off tables

Prompt: "Generate a Declart comparison table for three JavaScript frameworks across four criteria."

kind = "comparison"
title = "JavaScript Framework Comparison"

[[columns]]
label = "Performance"

[[columns]]
label = "Ecosystem"

[[rows]]
label = "React"
Performance = "★★★★"
Ecosystem = "★★★★★"

[[rows]]
label = "Vue"
Performance = "★★★★"
Ecosystem = "★★★"

[[rows]]
label = "Svelte"
Performance = "★★★★★"

Limits: 1–10 rows, 1–8 columns. Declare [[columns]] first for column order. Cell values are inline in each row, keyed by column label. Missing cells are rendered empty. Column label must not be "label" (reserved). Use TOML quoted keys ("My Column" = "val") if a column name contains spaces.


Swimlane — Cross-actor process flows

Prompt: "Generate a Declart swimlane diagram for an order-processing flow across Customer, System, and Payment Gateway. Use kind = 'flow' and view = 'swimlane'. Each item needs an actor."

kind = "flow"
view = "swimlane"
title = "Order Processing"

[[items]]
actor = "Customer"
label = "Place Order"

[[items]]
actor = "System"
label = "Check Inventory"

[[items]]
actor = "Payment Gateway"
label = "Process Payment"

[[items]]
actor = "System"
label = "Confirm Order"

Rule: every item requires an actor; at least 2 distinct actors. Items are grouped into horizontal lanes by actor, ordered top→down. actor is ignored by all other flow views.


Mind Map — Radial topic exploration

Prompt: "Create a Declart mind map for Machine Learning concepts. Use kind = 'hierarchy' and view = 'mind_map' with a single root."

kind = "hierarchy"
view = "mind_map"
title = "Machine Learning"

[[nodes]]
label = "ML Concepts"

[[nodes]]
label = "Supervised"
parent = "ML Concepts"

[[nodes]]
label = "Unsupervised"
parent = "ML Concepts"

[[nodes]]
label = "Classification"
parent = "Supervised"

Rule: exactly one root node. mind_map must be set explicitly (never auto-selected). The root is centered; its subtree radiates outward. Use for learning maps, brainstorms, topic exploration.


State — Lifecycle states and transitions

Prompt: "Generate a Declart state diagram for an order lifecycle. Use kind = 'state' with states and directed transitions. Mark the start state with role = 'initial' and end states with role = 'terminal'."

kind = "state"
title = "Order Lifecycle"

[[states]]
id = "pending"
label = "Pending"
role = "initial"

[[states]]
id = "processing"
label = "Processing"

[[states]]
id = "done"
label = "Completed"
role = "terminal"

[[states]]
id = "cancelled"
label = "Cancelled"
role = "terminal"

[[transitions]]
from = "pending"
to = "processing"
trigger = "Order Received"

[[transitions]]
from = "processing"
to = "done"
trigger = "Payment OK"

[[transitions]]
from = "processing"
to = "cancelled"
trigger = "Payment Failed"
type = "exception"

Rule: at least 2 states. At most one role = "initial"; multiple "terminal" allowed. Reference states in from/to by id (preferred) or label. trigger is optional (unconditional transition); type = "exception" marks error paths. Self-loops (from = to) are valid.


Prompt: "Generate a Declart system diagram for a zero trust architecture with a control plane and a data plane. Use kind = 'system' with groups, nodes (each in a group) and links between nodes. Use relation = 'indirect' for asynchronous or conditional links and role = 'store' for databases. Choose system only when the diagram has boundaries or links beyond a tree — a single line of steps is flow, a tree is hierarchy, one centre is hub_spoke."

kind = "system"
title = "Zero Trust Architecture"

[[groups]]
id = "cp"
label = "Control plane"

[[groups]]
id = "dp"
label = "Data plane"

[[nodes]]
id = "pe"
label = "Policy engine"
group = "cp"

[[nodes]]
id = "pa"
label = "Policy administrator"
group = "cp"

[[nodes]]
id = "subject"
label = "Subject"
group = "dp"
role = "actor"

[[nodes]]
id = "pep"
label = "Policy enforcement point"
group = "dp"

[[nodes]]
id = "resource"
label = "Enterprise resource"
group = "dp"

[[links]]
from = "pe"
to = "pa"
direction = "both"

[[links]]
from = "subject"
to = "pep"

[[links]]
from = "pep"
to = "resource"

[[links]]
from = "pa"
to = "pep"
label = "allow / deny"

[[links]]
from = "pep"
to = "pa"
label = "access request"
relation = "indirect"

Rule: at least 2 nodes; at most 16 nodes, 6 groups, 24 links (split a bigger diagram in two). Node and group ids share one namespace. group / parent name a group; groups nest at most two deep. A link's from / to name a node or a group, never an end and itself, never a group and something inside it. direction is forward (default), both or none; relation is direct (default) or indirect; role is store, external or actor. Never give coordinates or sizes.


Status signals — health / severity per item

Prompt: "Generate a Declart flow showing a release pipeline where each step has a health status. Use the status field with values success / warning / critical / normal. status is orthogonal to emphasis."

kind = "flow"
title = "Release Pipeline Health"

[[items]]
label = "Build"
status = "success"

[[items]]
label = "Test"
status = "warning"

[[items]]
label = "Deploy"
emphasis = "primary"
status = "critical"

[[items]]
label = "Monitor"
status = "normal"

Rule: status ∈ success / normal / warning / critical. It is the "traffic-light" signal common in reports, and is orthogonal to emphasis — an item can be both primary and critical. The engine renders a corner marker dual-encoded by color and shape (success=circle, warning=triangle, critical=diamond), so it reads in monochrome and for colorblind users. normal and omitted status render no marker. Supported on flow, tier, hub_spoke, matrix, and timeline items. Declaring status on other kinds is a parse error.


Tips for LLMs

RuleDetail
kind is requiredAlways include it as the first field
view is optionalOmit to use the default; include to declare intent explicitly
No unknown fieldsDon't add color, style, or other keys not in the spec
emphasis valuesOnly "primary" or "secondary"
status valuesOnly "success", "normal", "warning", "critical". Orthogonal to emphasis. Supported on flow, tier, hub_spoke, matrix, timeline
Flow viewskind = "flow" + view: process (default), cycle, funnel, swimlane
Swimlane actorsview = "swimlane" requires an actor on every item; ≥2 distinct actors
Tier viewskind = "tier" + view: pyramid (default and only)
Hierarchy nodeslabel must be unique; parent references id (preferred) or label of another node
Hierarchy idAdd id = "key" to nodes for stable parent references that survive label renames
Hierarchy viewsorg_chart, fishbone, mind_map. 1 root → org_chart; 2+ roots → fishbone (auto). mind_map must be explicit
Fishbone effectRendered as the spine-end effect label; falls back to title if omitted
Matrix quadrantsAlways exactly 4 [[quadrants]] entries
Matrix itemsOptional [[items]] with quadrant (position) to classify into quadrants (BCG/Gartner). Max 6 per quadrant
Timeline datesISO 8601: YYYY, YYYY-MM, or YYYY-MM-DD (must be a real calendar date)
Timeline periodsdate for a milestone, or start + end for a period (inclusive end) — not both
Venn setsOnly 2 or 3 sets supported
Comparison cellsColumn label in each row must match an existing [[columns]] label
State rolesAt most one role = "initial"; multiple "terminal" allowed. from/to reference state id or label

Validating LLM Output

declart validate diagram.toml

Error messages include field names and hints:

invalid value `(missing)` for field `position`
  = hint: When any quadrant has position, all must specify it.
          Valid: top-left, top-right, bottom-left, bottom-right

Paste the error back to the LLM to get a corrected TOML.

Flow

A flow diagram represents an ordered list of labeled items. The view field determines how the flow is interpreted and rendered.

Fields

FieldRequiredTypeDescription
kindyes"flow"Must be exactly "flow"
viewnostringRendering intent. Default: process
titlenostringTitle rendered above the diagram
itemsyesarray of ItemAt least one item required

Item fields

FieldRequiredTypeDescription
labelyesstringText displayed in the item
emphasisnostring"primary" or "secondary". See schema.
statusnostring"success", "normal", "warning", or "critical" — health/severity signal, orthogonal to emphasis. See schema.

View values

valueMeaningMin itemsMax items
processLinear left-to-right steps (default)1—
cycleClosed loop — last item connects to first2—
funnelTapering stages (conversion/filtering)210
swimlaneSteps grouped into horizontal actor lanes, top→down2—

When view is omitted, the engine uses process.

For ranked/layered visuals (pyramid), use kind = "tier" instead.

Long labels

In the process and swimlane views a label that does not fit on one line — even shrunk to 85% of the label size — is wrapped onto as many lines as the box holds (at most three) — at spaces, and between characters for Chinese and Japanese text without spaces. The label shrinks toward the theme's minimum label size only when wrapping alone is not enough, and only a label that still overflows at that size is truncated with … on its last line. Hangul, CJK and other fullwidth characters are measured one em wide.

Swimlane item fields

When view = "swimlane", each item gains one additional required field:

FieldRequiredTypeDescription
actoryesstringLane owner of this step

actor is ignored by all other views. At least 2 distinct actor values are required.

Swimlane example

Order Processing Swimlane: Place Order (Customer) → Check Inventory (System) → Process Payment (Payment Gateway) → Confirm Order (System) → Receive Confirmation (Customer). Order Processing Customer System Payment Gateway Place Order Check Inventory Process Payment Confirm Order Receive Confirmation

Example

PDCA Cycle: Plan → Do → Check → Act → Plan. PDCA Plan Do Check Act

Status example

status adds a traffic-light health signal per step. It is orthogonal to emphasis, so a step can be both the most important (primary) and in trouble (critical).

Release Pipeline Health Process: Build → Test → Deploy → Monitor. Release Pipeline Health Build Test Deploy Monitor

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

process

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
items[].label3 items20 / 4239 / 81

cycle

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
items[].label3 items9 / 915 / 15

funnel

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
items[].label3 items22 / 2249 / 49

swimlane

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
items[].label3 items18 / 3634 / 72

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

process

Fields

FieldTypeRequiredValues / meaning
kindenumyesflow
viewenumnoprocess, cycle, funnel, swimlane
titlestringno

items — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

cycle

Fields

FieldTypeRequiredValues / meaning
kindenumyesflow
viewenumnoprocess, cycle, funnel, swimlane
titlestringno

items — 2 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

funnel

Fields

FieldTypeRequiredValues / meaning
kindenumyesflow
viewenumnoprocess, cycle, funnel, swimlane
titlestringno

items — 2 to 10 elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

swimlane

Fields

FieldTypeRequiredValues / meaning
kindenumyesflow
viewenumnoprocess, cycle, funnel, swimlane
titlestringno

items — 2 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical
actorstringyesthe lane the step belongs to

Rules

  • actor must not be empty on any item
  • the items name at least 2 distinct actors

Tier

A tier diagram represents an ordered set of labeled levels. The view field determines how the levels are rendered and what relationship they express: pyramid shows them as ranked layers (importance, abstraction, or priority), while concentric shows them as nested rings (containment and dependency — the "onion" model).

Fields

FieldRequiredTypeDescription
kindyes"tier"Must be exactly "tier"
viewnostringRendering intent. Default: pyramid
titlenostringTitle rendered above the diagram
itemsyesarray of ItemAt least one item required

Item fields

FieldRequiredTypeDescription
labelyesstringText displayed in the tier level
emphasisnostring"primary" or "secondary". See schema.
statusnostring"success", "normal", "warning", or "critical". See schema.

View values

valueMeaningMin itemsMax items
pyramidStacked layers from apex (first) to base (last)1—
concentricNested rings from core (first, innermost) to periphery (last)1—

When view is omitted, the engine uses pyramid.

In concentric, item order reads inner → outer: the first item is the innermost core (the contained center), each subsequent item a ring enclosing it. This expresses containment and outer-depends-on-inner relationships (architecture layers, stakeholder rings, product layers). The data structure is identical to pyramid — only the rendering and the relationship it conveys differ.

Example

Maslow's Hierarchy of Needs Pyramid, top to base: Self-Actualization, Esteem, Love & Belonging, Safety, Physiological. Maslow's Hierarchy of Needs Self-Actualization Esteem Love & Belonging Safety Physiological

Example — concentric (onion)

Clean Architecture Layers Concentric rings, core outward: Entities, Use Cases, Interface Adapters, Frameworks & Drivers. Clean Architecture Layers Entities Use Cases Interface Adapters Frameworks & Drivers

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

pyramid

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
items[].label3 items— / —— / —

concentric

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
items[].label3 items11 / 1119 / 19

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

pyramid

Fields

FieldTypeRequiredValues / meaning
kindenumyestier
viewenumnopyramid, concentric
titlestringno

items — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

concentric

Fields

FieldTypeRequiredValues / meaning
kindenumyestier
viewenumnopyramid, concentric
titlestringno

items — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

Hierarchy

A hierarchy diagram represents a tree of labeled nodes connected by parent-child relationships. The view field determines how the tree is rendered.

Fields

FieldRequiredTypeDescription
kindyes"hierarchy"Must be exactly "hierarchy"
viewnostringRendering intent. Auto-selected if omitted.
titlenostringChart title (rendered above the diagram)
effectnostringFishbone view only: spine-end effect label. Falls back to title if omitted.
nodesyesarray of NodeAt least one node required

Node fields

FieldRequiredTypeDescription
labelyesstringDisplay text
idnostringStable identifier for parent references. If set, other nodes reference this node by id, not label.
parentnostringid (preferred) or label of the parent node; omit for root nodes

View values

valueMeaningAuto-selected when
org_chartTop-down tree; exactly one root requiredexactly 1 root node
fishboneCause-and-effect diagram2+ root nodes
mind_mapRadial tree centered on the root nodenever (must be explicit)

Auto-selection: When view is omitted, the engine selects org_chart for exactly one root node, fishbone for two or more root nodes. The CLI emits a warning when view is auto-selected; add an explicit view to suppress it.

View-specific constraints

org_chart: exactly one root node required.
fishbone: 2–20 root nodes (cause categories); effect (or title if effect is omitted) is rendered as the effect label at the right end of the spine. Recommend 8 or fewer root nodes — 9+ cause categories on the same side of the spine may overlap.
mind_map: exactly one root node required. The root is placed at the center; its subtree radiates outward in all directions. Use for learning maps, brainstorm notes, and topic exploration.

Long labels

In the org_chart view a node label that does not fit on one line — even shrunk to 85% of the label size — is wrapped onto the lines the node holds, shrinking toward the theme's minimum label size as needed; only a label that still overflows at that size is truncated with …. Hangul, CJK and other fullwidth characters are measured one em wide.

Example — org_chart view (auto-selected)

Engineering Division Hierarchy: VP Engineering (Backend Team, Frontend Team). Engineering Division VP Engineering Backend Team Frontend Team

Example — fishbone view

Slow Page Load Causes of High Latency: Server (CPU saturation); Network (Bandwidth). High Latency Server CPU saturation Network Bandwidth

Example — mind_map view

Machine Learning Mind map: ML Concepts (Supervised (Classification, Regression), Unsupervised, Reinforce). Machine Learning Supervised Unsupervised Reinforce Classification Regression ML Concepts

Example — org_chart with stable id references

Engineering Team Hierarchy: VP Engineering (Backend Team, Frontend Team). Engineering Team VP Engineering Backend Team Frontend Team

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

org_chart

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
nodes[].label (no parent)a root, 2 children7 / 2014 / 38
nodes[].label (parent set)a root, 2 children7 / 2014 / 38

fishbone

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
nodes[].label (no parent)2 categories, 2 causes9 / 915 / 15
nodes[].label (parent set)2 categories, 2 causes7 / 714 / 14
effect2 categories, 2 causes10 / 1019 / 19

mind_map

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
nodes[].label (no parent)a root, 2 children6 / 613 / 13
nodes[].label (parent set)a root, 2 children8 / 816 / 16

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Without view

Fields

FieldTypeRequiredValues / meaning
kindenumyeshierarchy
viewenumnoorg_chart, fishbone, mind_map
titlestringno
effectstringnofishbone: the label at the end of the spine; falls back to title

nodes — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
idstringnoa short name to refer to the node by
parentreferencenothe id or label of the node above; a node without one is a root

Rules

  • node labels are unique
  • node ids are unique
  • parent names another node's id or label, never the node itself
  • without view: one node without a parent makes an org_chart, more make a fishbone (2 to 20 of them)

org_chart

Fields

FieldTypeRequiredValues / meaning
kindenumyeshierarchy
viewenumnoorg_chart, fishbone, mind_map
titlestringno
effectstringnofishbone: the label at the end of the spine; falls back to title

nodes — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
idstringnoa short name to refer to the node by
parentreferencenothe id or label of the node above; a node without one is a root

Rules

  • node labels are unique
  • node ids are unique
  • parent names another node's id or label, never the node itself
  • exactly one node has no parent (the root)

fishbone

Fields

FieldTypeRequiredValues / meaning
kindenumyeshierarchy
viewenumnoorg_chart, fishbone, mind_map
titlestringno
effectstringnofishbone: the label at the end of the spine; falls back to title

nodes — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
idstringnoa short name to refer to the node by
parentreferencenothe id or label of the node above; a node without one is a root

Rules

  • node labels are unique
  • node ids are unique
  • parent names another node's id or label, never the node itself
  • 2 to 20 nodes have no parent (the cause categories)

mind_map

Fields

FieldTypeRequiredValues / meaning
kindenumyeshierarchy
viewenumnoorg_chart, fishbone, mind_map
titlestringno
effectstringnofishbone: the label at the end of the spine; falls back to title

nodes — 1 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
idstringnoa short name to refer to the node by
parentreferencenothe id or label of the node above; a node without one is a root

Rules

  • node labels are unique
  • node ids are unique
  • parent names another node's id or label, never the node itself
  • exactly one node has no parent (the root)

Timeline

A timeline diagram. Events are placed along a horizontal axis at positions proportional to their dates. An event is either a milestone (a single date) or a period (a start and end date). Used for project histories, product roadmaps, and chronological narratives.

Fields

FieldRequiredTypeDescription
kindyes"timeline"Must be exactly "timeline"
titlenostringTitle rendered above the diagram
eventsyesarray of EventAt least two events required

Event fields

FieldRequiredTypeDescription
datemilestonestringThe milestone's date
startperiodstringFirst date of the period
endperiodstringLast date of the period (inclusive)
labelyesstringText displayed with the milestone marker or period bar
emphasisno"primary" | "secondary"Importance — see the shared Emphasis field
statusno"success" | "normal" | "warning" | "critical"Condition — see the shared Status field

Each event declares either date (a milestone) or both start and end (a period). Any other combination is a validation error.

Dates

All date fields accept YYYY, YYYY-MM, or YYYY-MM-DD, and must name a real calendar date (2024-02-30 is rejected). A partial date names a whole year or month:

  • As a milestone date or a period start, it is placed at the first day of that year/month.
  • As a period end, it is inclusive — the period runs through the last day of that year/month (or through that day, for a full date). start = "2024-02", end = "2024-03" covers February and March.

end must not fall before start. A period may be a single year, month, or day (start = end).

Rendering rules

  • Events are sorted by date (a period by its start) and placed along a horizontal axis.
  • The horizontal position of each event is proportional to its date within the overall date range, which spans from the earliest date to the latest milestone or period end.
  • Milestones are markers on the axis. Their labels alternate above and below the axis to reduce overlap, and the date string is displayed below each marker.
  • Periods are bars below the axis, spanning their dates, with the label inside the bar (or beside it when the bar is too short) and the date range underneath. Overlapping periods stack into separate rows; periods that do not overlap share a row.
  • emphasis and status are the shared optional fields. A primary milestone has a larger marker and a bold label, a primary period a bold label and a background-colored outline; secondary tints the marker or bar lighter. A status other than normal draws a small marker, dual-encoded by color and shape: beside a milestone's label, and in the right end of a period bar (just right of a bar too narrow to hold its label). The two fields are independent — an event may carry both.
  • At least two events are required to establish a time range.
  • This is a qualitative roadmap, not a scheduler: there are no dependencies, progress, or resource fields. Use a project-management tool for precise Gantt charts.

Example

Product Launch History Timeline: 2024-01-15 Alpha; 2024-04-01 Beta; 2024-07-20 Launch; 2024-12-01 v2.0. Product Launch History Alpha 2024-01-15 Beta 2024-04-01 Launch 2024-07-20 v2.0 2024-12-01

Milestones and periods

Product Roadmap 2024 Timeline: 2024-01-15 Kickoff; 2024-02 to 2024-04 Private Beta; 2024-03 to 2024-09 Enterprise Pilot; 2024-05 to 2024-06 Public Beta; 2024-07-01 GA Launch. Product Roadmap 2024 Kickoff 2024-01-15 GA Launch 2024-07-01 Private Beta 2024-02 – 2024-04 Enterprise Pilot 2024-03 – 2024-09 Public Beta 2024-05 – 2024-06

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
events[].label4 milestones10 / 1019 / 19

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyestimeline
titlestringno

events — 2 or more elements

FieldTypeRequiredValues / meaning
datedatenoa milestone
startdatenoa period; with end
enddatenoa period; with start
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

Rules

  • each event has a date, or both start and end, not both kinds
  • end is not before start

Matrix 2×2

A two-by-two matrix diagram. Used for prioritization, strategy frameworks, and categorization with two independent axes.

Fields

FieldRequiredTypeDescription
kindyes"matrix"Must be exactly "matrix"
titlenostringTitle rendered above the diagram
x_axisyesstringLabel for the horizontal axis
y_axisyesstringLabel for the vertical axis
quadrantsyesarray of 4Exactly 4 quadrants, in reading order
itemsnoarray of ItemOptional items classified into quadrants (BCG/Gartner style)

Quadrant fields

FieldRequiredTypeDescription
labelyesstringText displayed in the quadrant
emphasisnostring"primary" or "secondary". See schema.
statusnostring"success", "normal", "warning", or "critical". See schema.
positionnostringExplicit cell: "top-left", "top-right", "bottom-left", "bottom-right"

Quadrant order

Without position (default): Quadrants are declared in reading order (left-to-right, top-to-bottom):

  1. Top-left (high Y, low X)
  2. Top-right (high Y, high X)
  3. Bottom-left (low Y, low X)
  4. Bottom-right (low Y, high X)

With position: All four quadrants must each declare a distinct position. Order in the file does not matter. When any quadrant has position, all four must specify it.

Item placement (optional)

Beyond naming the four quadrants, you can classify items into them — the BCG growth-share matrix (Stars / Cash Cows / Question Marks / Dogs) and Gartner Magic Quadrant pattern. Items are an optional [[items]] array; omit it for a label-only matrix (backward compatible).

FieldRequiredTypeDescription
labelyesstringText displayed for the item
quadrantyesstringOwning quadrant by position: top-left/top-right/bottom-left/bottom-right
emphasisnostring"primary" or "secondary". See schema.
statusnostring"success"/"normal"/"warning"/"critical". See schema.
  • Assignment is by category (which quadrant), never by [x, y] coordinates — the engine lays items out within the cell. This preserves the no-coordinates principle.
  • quadrant references the position slot, so it is independent of whether quadrants were declared with explicit position or in index order.
  • At most 6 items per quadrant (legibility). When a quadrant has items, its label is rendered as a header at the top of the cell and the items are listed below.

Rendering rules

  • The diagram is a 2×2 grid divided by a horizontal and vertical axis line.
  • Each quadrant occupies one cell of the grid and displays its label (centered when empty, as a top header when it has items).
  • x_axis is rendered below the horizontal center line.
  • y_axis is rendered to the left of the vertical center line, rotated 90°.
  • Exactly 4 quadrants are required; more or fewer is a parse error.

Example

Eisenhower Matrix Matrix of Importance by Urgency: Do First (top left); Schedule (top right); Delegate (bottom left); Eliminate (bottom right). Eisenhower Matrix Do First Schedule Delegate Eliminate Importance Low High Urgency Low High

Item placement example (BCG)

BCG Growth-Share Matrix Matrix of Market Share by Market Growth: Question Marks (top left): Product B; Stars (top right): Product A; Dogs (bottom left): Product C; Cash Cows (bottom right). BCG Growth-Share Matrix Question Marks Product B Stars Product A Dogs Product C Cash Cows Market Share Low High Market Growth Low High

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
quadrants[].label4 quadrants— / —— / —

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyesmatrix
titlestringno
x_axisstringyes
y_axisstringyes

quadrants — exactly 4 elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical
positionenumnotop-left, top-right, bottom-left, bottom-right

items — any number of elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical
quadrantenumyestop-left, top-right, bottom-left, bottom-right

Rules

  • when any quadrant has a position, every quadrant has one and each is used once
  • at most 6 items go in one quadrant

Hub-and-Spoke

A hub-and-spoke diagram. A central node radiates connections to surrounding spoke nodes. Used for showing a central concept with related elements, or a hub with connected services.

Fields

FieldRequiredTypeDescription
kindyes"hub_spoke"Must be exactly "hub_spoke"
titlenostringTitle rendered above the diagram
centeryesstringLabel for the central hub node
spokesyesarray of SpokeAt least two spokes required

Spoke fields

FieldRequiredTypeDescription
labelyesstringText displayed in the spoke node
emphasisnostring"primary" or "secondary". See schema.
statusnostring"success", "normal", "warning", or "critical". See schema.

Rendering rules

  • The center node is rendered at the center of the diagram.
  • Spoke nodes are arranged evenly around the center in a circle.
  • Lines connect the center node to each spoke node.
  • The center node is visually distinguished from spoke nodes (larger, different color).
  • Spoke nodes use the base color; the center uses the apex color.

Example

Cloud Architecture API Gateway at the centre, connected to Auth Service, User Service, Order Service, Payment Service, Notification. Cloud Architecture Auth Service User Service Order Service Payment Service Notification API Gateway

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
center3 spokes9 / 922 / 22
spokes[].label3 spokes9 / 915 / 15

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyeshub_spoke
titlestringno
centerstringyes

spokes — 2 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

Venn

A Venn diagram. Two or three overlapping circles represent sets. Intersection regions may be labeled. Used for showing set relationships, similarities, and differences.

Fields

FieldRequiredTypeDescription
kindyes"venn"Must be exactly "venn"
titlenostringTitle rendered above the diagram
setsyesarray of Set2 or 3 sets required
intersectionsnoarray of IntersectionLabeled regions in the overlap areas

Set fields

FieldRequiredTypeDescription
labelyesstringName of the set

Intersection fields

FieldRequiredTypeDescription
setsyesarray of stringSet labels identifying which overlap region this labels
labelyesstringText displayed in the overlap region

Rendering rules

  • Circles are arranged to overlap: two sets side-by-side; three sets in a triangle.
  • Each circle is rendered with partial opacity so overlaps are visible.
  • Set labels appear near the outer edge of each circle (non-overlapping region).
  • Intersection labels appear in the center of the overlap region.
  • Exactly 2 or 3 sets are required; other counts are a parse error.

Example

Skills Overlap Venn of Design, Engineering; Design and Engineering overlap: UX Engineering. Skills Overlap Design Engineering UX Engineering

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
sets[].label2 sets— / —— / —
intersections[].label2 sets— / —— / —

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyesvenn
titlestringno

sets — 2 to 3 elements

FieldTypeRequiredValues / meaning
labelstringyes

intersections — any number of elements

FieldTypeRequiredValues / meaning
setsstring[]yesthe labels of the sets that overlap
labelstringyes

Comparison Table Kind — Specification

Purpose

Presents a matrix of items (rows) evaluated against criteria (columns). Each cell value is declared inline within the row entry.

TOML Schema

kind = "comparison"
title = <string>?         # optional diagram title

[[columns]]
label = <string>          # evaluation criterion (required, unique)

[[rows]]
label = <string>          # item being compared (required, unique)
<ColumnLabel> = <string>  # cell value for that column (optional, omit = empty cell)

Constraints

ConstraintRule
Rows1–10
Columns1–8
Column labelMust not be "label" (reserved for the row identifier)
Cell keys in rowsMust match a declared columns[].label; unknown keys are an error
Missing cellsTreated as empty (allowed)

Rendering Specification

  • Canvas: 800px wide, height = title_area + 45px column header + rows × 50px + 20px padding
  • Row header column: 180px wide, apex-tinted background
  • Column header row: 45px tall, apex color background, bold white/dark text
  • Data cells: 50px tall, equal width distributing remaining canvas; alternating even/odd row backgrounds
  • Grid borders: 1px lines using apex-background interpolated color
  • Text: Noto Sans, 13px; truncated with … if wider than available cell width

Example

JavaScript Framework Comparison Comparison of React, Vue by Performance, Ecosystem. React: Performance ★★★★, Ecosystem ★★★★★; Vue: Performance ★★★★, Ecosystem ★★★. JavaScript Framework Comparison Performance Ecosystem React Vue ★★★★ ★★★★★ ★★★★ ★★★

Example Files

  • valid/basic.toml — 2 rows × 2 columns, inline cells
  • valid/no_title.toml — title omitted
  • valid/empty_cells.toml — no cells defined (sparse table)
  • valid/basic.json — JSON format
  • invalid/no_rows.toml — missing rows → error
  • invalid/no_columns.toml — missing columns → error
  • invalid/invalid_cell_ref.toml — row uses undeclared column key → error
  • invalid/too_many_columns.toml — 9 columns exceeds limit → error

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
columns[].label2 columns, 2 rows21 / 2140 / 40
rows[].label2 columns, 2 rows12 / 1223 / 23
rows[].<column>2 columns, 2 rows21 / 2140 / 40

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyescomparison
titlestringno

columns — 1 to 8 elements

FieldTypeRequiredValues / meaning
labelstringyes

rows — 1 to 10 elements

FieldTypeRequiredValues / meaning
labelstringyes
<column>stringnoone key per declared column, named by the column's label; its value is the cell

Rules

  • a column is not labelled label (the row field uses that name)
  • a row has no key that is not a declared column

State

A state diagram represents a system's lifecycle as a set of named states and directed transitions between them.

Scope

state is a named lifecycle for prose — the diagram that explains how an order, a ticket, or a deployment moves through its stages in a report or design document. It is not an executable state machine notation:

  • No guards, entry/exit actions, or internal transitions — trigger is a display label only.
  • No nested (composite), parallel (orthogonal), or history states.
  • Transitions connect only declared states; layout is chosen by the engine.

If a diagram needs any of the above, use an engineering tool such as Mermaid, D2, or PlantUML.

Fields

FieldRequiredTypeDescription
kindyes"state"Must be exactly "state"
titlenostringRendered above the diagram
statesyesarray of StateAt least 2 states required
transitionsnoarray of TransitionMay be empty (unconnected states)

State fields

FieldRequiredTypeDescription
labelyesstringDisplay text. Must be unique unless id is set.
idnostringStable identifier for from/to references. Falls back to label if omitted.
rolenostring"initial" or "terminal". At most one "initial"; multiple "terminal" allowed.

Transition fields

FieldRequiredTypeDescription
fromyesstringid (preferred) or label of source state
toyesstringid (preferred) or label of target state
triggernostringEvent or condition causing this transition
typenostring"normal" (default) or "exception" — semantic type

Self-loop transitions (from = to) are valid. Transition without trigger is valid (unconditional).

Cross-reference resolution

If a state has an id, use id in from/to. If it has no id, use label. Unknown references → validation error. Duplicate labels without id → validation error.

Example

Order Lifecycle States: Pending (initial), Processing, Completed (final), Cancelled (final). Transitions: Pending → Processing on Order Received; Processing → Completed on Payment OK; Processing → Cancelled on Payment Failed (exception). Order Lifecycle Pending Processing Completed Cancelled Order Received Payment OK Payment Failed

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
states[].label3 states7 / 3014 / 55
transitions[].trigger3 states— / —— / —

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyesstate
titlestringno

states — 2 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
idstringnoa short name to refer to the state by
roleenumnoinitial, terminal

transitions — any number of elements

FieldTypeRequiredValues / meaning
fromreferenceyesa state's id or label
toreferenceyesa state's id or label
triggerstringno
typeenumnonormal, exception

Rules

  • state labels are unique
  • state ids are unique
  • at most one state has the role initial
  • from and to name an existing state's id or label

System

A system diagram explains how a set of components fit together: the components, the boundaries they sit in, and the links between them.

Scope

system is a conceptual architecture diagram for prose — the picture in a report, design document or study note that answers "what are the parts, which ones belong together, and what passes between them". It is not a deployment, network or runtime specification:

  • Components and links are only the ones you declare. There are no ports, protocols, sizes, coordinates or routes in the source; the engine places everything.
  • A group is a boundary (a zone, a plane, a team, a pod). Groups nest at most two deep — a group inside a group.
  • A link says what connects two components, and may carry a short label. Whether it is solid or dashed comes from its relation, not from a style field.
  • One diagram holds at most 16 nodes, 6 groups and 24 links. Past that, a diagram stops being readable at a glance; split it into two diagrams, one per concern. Exceeding a limit is a validation error.

If the diagram needs sequence ordering, entity relationships, class structure or a network topology with addresses, use an engineering tool such as Mermaid, D2 or PlantUML.

Choosing between system and another kind

A diagram has one kind. Pick the first line that fits:

The relationship is…Use
a single line of steps in orderflow
one centre with items radiating from ithub_spoke
the stages of one thing's life, moving between statesstate
a tree — every item has one parenthierarchy
anything else: components in boundaries, or linked in more than a treesystem

Fields

FieldRequiredTypeDescription
kindyes"system"Must be exactly "system"
titlenostringRendered above the diagram
groupsnoarray of GroupBoundaries. At most 6
nodesyesarray of NodeComponents. At least 2, at most 16
linksnoarray of LinkConnections. At most 24

Group fields

FieldRequiredTypeDescription
idyesstringUnique across all groups and nodes
labelyesstringDisplay text
parentnostringid of the group this one sits inside. Nesting is at most two deep

Node fields

FieldRequiredTypeDescription
idyesstringUnique across all groups and nodes
labelyesstringDisplay text
groupnostringid of the group the node sits in
rolenostring"store" (data is kept here — a database, queue or file store), "external" (outside your control), "actor" (a person or client acting on the system). Omit for an ordinary component
emphasisnostring"primary" or "secondary" — see Schema
statusnostring"success", "normal", "warning" or "critical" — see Schema
FieldRequiredTypeDescription
fromyesstringid of a node or a group
toyesstringid of a node or a group
labelnostringWhat passes along the link
directionnostring"forward" (default, from → to), "both", or "none" (an association)
relationnostring"direct" (default — a call, a data flow) or "indirect" (asynchronous, optional or conditional)

A link to a group ends at the group's boundary — use it for "the whole zone talks to X". A link cannot join a group to something inside it, and cannot join an end to itself (a state that loops back is a state diagram).

Rules

  • Node and group ids share one namespace; each must be unique.
  • group and parent must name an existing group; from and to must name an existing node or group.
  • Every link needs two different ends, neither inside the other.
  • The engine chooses the layout. It lays each group out first and then treats it as one box, so boxes never overlap; links run along horizontal and vertical lines and go around components, not through them, and each link label is set on a free stretch of its link. Every label is set whole — a label too long for a box makes the box wider — and render_diagnosed reports the rare label that still had to be shrunk or cut. A group label is set on one line, at most about 320 px wide, and a link label at most about 180 px.

Example

Zero Trust Architecture System: Control plane (Policy decision point, Identity, device state, threat intelligence, logs), Data plane (Subject: user or device, Policy enforcement point, Enterprise resource). Links: Policy engine ↔ Policy administrator; Identity, device state, threat intelligence, logs → Policy engine; Subject: user or device → Policy enforcement point; Policy enforcement point → Enterprise resource; Policy administrator → Policy enforcement point (allow / deny); Policy enforcement point → Policy administrator (access request) [indirect]. Zero Trust Architecture Control plane Policy decision point Data plane Policyengine Policyadministrator Identity, device state,threat intelligence, logs Subject: useror device Policy enforcementpoint Enterpriseresource allow / deny access request

A link to a whole group:

Function point measurement boundary System: Application being measured (ILF: internal logical file), User, EIF: external interface file, kept by another system. Links: User → Application being measured (EI (input)); Application being measured → User (EO (derived output)); EIF: external interface file, kept by another system → Application being measured (reference) [indirect]. Function point measurement boundary Application being measured User ILF: internallogical file EIF: external interface file,kept by another system EI (input) EO (derived output) reference

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
groups[].label2 groups, 2 nodes, 1 link22 / 3242 / 60
nodes[].label3 nodes, 2 links30 / 4228 / 79
links[].label3 nodes, 2 links15 / 2128 / 40

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyessystem
titlestringno

groups — 0 to 6 elements

FieldTypeRequiredValues / meaning
idstringyesa short name to refer to the group by
labelstringyes
parentreferencenothe id of the group this one sits inside

nodes — 2 to 16 elements

FieldTypeRequiredValues / meaning
idstringyesa short name to refer to the node by
labelstringyes
groupreferencenothe id of the group the node sits in
roleenumnostore, external, actor
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

links — 0 to 24 elements

FieldTypeRequiredValues / meaning
fromreferenceyesthe id of a node or a group
toreferenceyesthe id of a node or a group
labelstringno
directionenumnoforward, both, none
relationenumnodirect, indirect

Rules

  • node ids and group ids are unique, all in one set
  • parent names another group's id, never the group itself
  • groups nest two deep at most (a group inside a group)
  • group names a group's id
  • from and to name the id of a node or a group
  • a link joins two different ends
  • a link does not join a group to something inside it