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"totsconfig.jsonor declare types manually invite-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
| Kind | Views |
|---|---|
flow | process (default), cycle, funnel, swimlane |
tier | pyramid (default), concentric |
hierarchy | org_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 onflow,tier,hub_spoke, andmatrixitems.
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.
-
Design exclusion. Declaration files contain no visual information: no colors, coordinates, fonts, sizes, margins, or layout hints. These are the engine's domain.
-
Semantics only. Fields express meaning, not appearance.
emphasis: primaryis allowed;color: redis not. The engine decides how emphasis looks. -
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. -
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.
-
One representation per diagram. Each
kind + viewpair 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
| Field | Type | Description |
|---|---|---|
| kind | string | One of: flow, tier, hierarchy, timeline, matrix, hub_spoke, venn, comparison, state, system |
Optional fields
| Field | Type | Description |
|---|---|---|
| title | string | Display title rendered above the diagram. Omit to suppress. |
| view | string | Rendering 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
flowandtier. Thematrixkind uses[[quadrants]];hierarchyuses[[nodes]];timelineuses[[events]];hub_spokeuses[[spokes]];vennuses[[sets]];comparisonuses[[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:
| Value | Meaning |
|---|---|
primary | Most important item in the diagram |
secondary | Secondary importance |
The engine decides visual representation. Omitting emphasis means default weight.
primary: white outline stroke + bold textsecondary: 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.
| Value | Meaning |
|---|---|
success | Explicitly good / done |
normal | Assessed as nominal (the unmarked baseline) |
warning | Needs attention |
critical | Failing / 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_fieldsmeans invalid keys are caught immediately. The LLM cannot silently produce a broken diagram. - Explicit kind: the
kindfield 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)
| kind | views | Notes |
|---|---|---|
flow | process (default), cycle, funnel, swimlane | view optional — defaults to process. swimlane requires an actor per item |
tier | pyramid (default), concentric | Ranked levels (pyramid) or nested rings / onion (concentric) — view optional |
hierarchy | org_chart, fishbone, mind_map | view 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
concentricfor containment / dependency (architecture layers, stakeholder rings); usepyramidfor 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
positionto 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"
Hub-and-Spoke — Central concept with related items
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, orYYYY-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.endis inclusive:end = "2024-04"runs through April 30. Periods render as bars below the axis and overlapping periods stack automatically. An event may carryemphasisandstatuslike 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. Theeffectfield is rendered as the spine-end effect label; ifeffectis omitted,titleis 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).parentreferences another node'sid(preferred) orlabel. For stable references that survive label renames, addid = "stable-key"to each node and use that inparent. 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.actoris 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_mapmust 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 infrom/tobyid(preferred) orlabel.triggeris optional (unconditional transition);type = "exception"marks error paths. Self-loops (from=to) are valid.
System — Components in boundaries, joined by links
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/parentname a group; groups nest at most two deep. A link'sfrom/toname a node or a group, never an end and itself, never a group and something inside it.directionisforward(default),bothornone;relationisdirect(default) orindirect;roleisstore,externaloractor. 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 toemphasis— an item can be bothprimaryandcritical. 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.normaland omittedstatusrender no marker. Supported onflow,tier,hub_spoke,matrix, andtimelineitems. Declaringstatuson other kinds is a parse error.
Tips for LLMs
| Rule | Detail |
|---|---|
kind is required | Always include it as the first field |
view is optional | Omit to use the default; include to declare intent explicitly |
| No unknown fields | Don't add color, style, or other keys not in the spec |
emphasis values | Only "primary" or "secondary" |
status values | Only "success", "normal", "warning", "critical". Orthogonal to emphasis. Supported on flow, tier, hub_spoke, matrix, timeline |
| Flow views | kind = "flow" + view: process (default), cycle, funnel, swimlane |
| Swimlane actors | view = "swimlane" requires an actor on every item; ≥2 distinct actors |
| Tier views | kind = "tier" + view: pyramid (default and only) |
| Hierarchy nodes | label must be unique; parent references id (preferred) or label of another node |
Hierarchy id | Add id = "key" to nodes for stable parent references that survive label renames |
| Hierarchy views | org_chart, fishbone, mind_map. 1 root → org_chart; 2+ roots → fishbone (auto). mind_map must be explicit |
Fishbone effect | Rendered as the spine-end effect label; falls back to title if omitted |
| Matrix quadrants | Always exactly 4 [[quadrants]] entries |
| Matrix items | Optional [[items]] with quadrant (position) to classify into quadrants (BCG/Gartner). Max 6 per quadrant |
| Timeline dates | ISO 8601: YYYY, YYYY-MM, or YYYY-MM-DD (must be a real calendar date) |
| Timeline periods | date for a milestone, or start + end for a period (inclusive end) — not both |
| Venn sets | Only 2 or 3 sets supported |
| Comparison cells | Column label in each row must match an existing [[columns]] label |
| State roles | At 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
| Field | Required | Type | Description |
|---|---|---|---|
kind | yes | "flow" | Must be exactly "flow" |
view | no | string | Rendering intent. Default: process |
title | no | string | Title rendered above the diagram |
items | yes | array of Item | At least one item required |
Item fields
| Field | Required | Type | Description |
|---|---|---|---|
label | yes | string | Text displayed in the item |
emphasis | no | string | "primary" or "secondary". See schema. |
status | no | string | "success", "normal", "warning", or "critical" — health/severity signal, orthogonal to emphasis. See schema. |
View values
| value | Meaning | Min items | Max items |
|---|---|---|---|
process | Linear left-to-right steps (default) | 1 | — |
cycle | Closed loop — last item connects to first | 2 | — |
funnel | Tapering stages (conversion/filtering) | 2 | 10 |
swimlane | Steps grouped into horizontal actor lanes, top→down | 2 | — |
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:
| Field | Required | Type | Description |
|---|---|---|---|
actor | yes | string | Lane owner of this step |
actor is ignored by all other views. At least 2 distinct actor values are required.
Swimlane example
Example
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).
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
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
items[].label | 3 items | 20 / 42 | 39 / 81 |
cycle
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
items[].label | 3 items | 9 / 9 | 15 / 15 |
funnel
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
items[].label | 3 items | 22 / 22 | 49 / 49 |
swimlane
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
items[].label | 3 items | 18 / 36 | 34 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | flow |
view | enum | no | process, cycle, funnel, swimlane |
title | string | no |
items — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
cycle
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | flow |
view | enum | no | process, cycle, funnel, swimlane |
title | string | no |
items — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
funnel
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | flow |
view | enum | no | process, cycle, funnel, swimlane |
title | string | no |
items — 2 to 10 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
swimlane
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | flow |
view | enum | no | process, cycle, funnel, swimlane |
title | string | no |
items — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
actor | string | yes | the lane the step belongs to |
Rules
actormust 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
| Field | Required | Type | Description |
|---|---|---|---|
kind | yes | "tier" | Must be exactly "tier" |
view | no | string | Rendering intent. Default: pyramid |
title | no | string | Title rendered above the diagram |
items | yes | array of Item | At least one item required |
Item fields
| Field | Required | Type | Description |
|---|---|---|---|
label | yes | string | Text displayed in the tier level |
emphasis | no | string | "primary" or "secondary". See schema. |
status | no | string | "success", "normal", "warning", or "critical". See schema. |
View values
| value | Meaning | Min items | Max items |
|---|---|---|---|
pyramid | Stacked layers from apex (first) to base (last) | 1 | — |
concentric | Nested 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
Example — concentric (onion)
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
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
items[].label | 3 items | — / — | — / — |
concentric
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
items[].label | 3 items | 11 / 11 | 19 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | tier |
view | enum | no | pyramid, concentric |
title | string | no |
items — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
concentric
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | tier |
view | enum | no | pyramid, concentric |
title | string | no |
items — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, 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
| Field | Required | Type | Description |
|---|---|---|---|
kind | yes | "hierarchy" | Must be exactly "hierarchy" |
view | no | string | Rendering intent. Auto-selected if omitted. |
title | no | string | Chart title (rendered above the diagram) |
effect | no | string | Fishbone view only: spine-end effect label. Falls back to title if omitted. |
nodes | yes | array of Node | At least one node required |
Node fields
| Field | Required | Type | Description |
|---|---|---|---|
label | yes | string | Display text |
id | no | string | Stable identifier for parent references. If set, other nodes reference this node by id, not label. |
parent | no | string | id (preferred) or label of the parent node; omit for root nodes |
View values
| value | Meaning | Auto-selected when |
|---|---|---|
org_chart | Top-down tree; exactly one root required | exactly 1 root node |
fishbone | Cause-and-effect diagram | 2+ root nodes |
mind_map | Radial tree centered on the root node | never (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)
Example — fishbone view
Example — mind_map view
Example — org_chart with stable id references
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
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
nodes[].label (no parent) | a root, 2 children | 7 / 20 | 14 / 38 |
nodes[].label (parent set) | a root, 2 children | 7 / 20 | 14 / 38 |
fishbone
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
nodes[].label (no parent) | 2 categories, 2 causes | 9 / 9 | 15 / 15 |
nodes[].label (parent set) | 2 categories, 2 causes | 7 / 7 | 14 / 14 |
effect | 2 categories, 2 causes | 10 / 10 | 19 / 19 |
mind_map
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
nodes[].label (no parent) | a root, 2 children | 6 / 6 | 13 / 13 |
nodes[].label (parent set) | a root, 2 children | 8 / 8 | 16 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | hierarchy |
view | enum | no | org_chart, fishbone, mind_map |
title | string | no | |
effect | string | no | fishbone: the label at the end of the spine; falls back to title |
nodes — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
id | string | no | a short name to refer to the node by |
parent | reference | no | the id or label of the node above; a node without one is a root |
Rules
- node labels are unique
- node ids are unique
parentnames another node's id or label, never the node itself- without
view: one node without aparentmakes an org_chart, more make a fishbone (2 to 20 of them)
org_chart
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | hierarchy |
view | enum | no | org_chart, fishbone, mind_map |
title | string | no | |
effect | string | no | fishbone: the label at the end of the spine; falls back to title |
nodes — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
id | string | no | a short name to refer to the node by |
parent | reference | no | the id or label of the node above; a node without one is a root |
Rules
- node labels are unique
- node ids are unique
parentnames another node's id or label, never the node itself- exactly one node has no
parent(the root)
fishbone
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | hierarchy |
view | enum | no | org_chart, fishbone, mind_map |
title | string | no | |
effect | string | no | fishbone: the label at the end of the spine; falls back to title |
nodes — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
id | string | no | a short name to refer to the node by |
parent | reference | no | the id or label of the node above; a node without one is a root |
Rules
- node labels are unique
- node ids are unique
parentnames another node's id or label, never the node itself- 2 to 20 nodes have no
parent(the cause categories)
mind_map
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | hierarchy |
view | enum | no | org_chart, fishbone, mind_map |
title | string | no | |
effect | string | no | fishbone: the label at the end of the spine; falls back to title |
nodes — 1 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
id | string | no | a short name to refer to the node by |
parent | reference | no | the id or label of the node above; a node without one is a root |
Rules
- node labels are unique
- node ids are unique
parentnames 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
| Field | Required | Type | Description |
|---|---|---|---|
| kind | yes | "timeline" | Must be exactly "timeline" |
| title | no | string | Title rendered above the diagram |
| events | yes | array of Event | At least two events required |
Event fields
| Field | Required | Type | Description |
|---|---|---|---|
| date | milestone | string | The milestone's date |
| start | period | string | First date of the period |
| end | period | string | Last date of the period (inclusive) |
| label | yes | string | Text displayed with the milestone marker or period bar |
| emphasis | no | "primary" | "secondary" | Importance — see the shared Emphasis field |
| status | no | "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
dateor a periodstart, 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.
emphasisandstatusare the shared optional fields. Aprimarymilestone has a larger marker and a bold label, aprimaryperiod a bold label and a background-colored outline;secondarytints the marker or bar lighter. Astatusother thannormaldraws 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
Milestones and periods
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
events[].label | 4 milestones | 10 / 10 | 19 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | timeline |
title | string | no |
events — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
date | date | no | a milestone |
start | date | no | a period; with end |
end | date | no | a period; with start |
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
Rules
- each event has a
date, or bothstartandend, not both kinds endis not beforestart
Matrix 2×2
A two-by-two matrix diagram. Used for prioritization, strategy frameworks, and categorization with two independent axes.
Fields
| Field | Required | Type | Description |
|---|---|---|---|
| kind | yes | "matrix" | Must be exactly "matrix" |
| title | no | string | Title rendered above the diagram |
| x_axis | yes | string | Label for the horizontal axis |
| y_axis | yes | string | Label for the vertical axis |
| quadrants | yes | array of 4 | Exactly 4 quadrants, in reading order |
| items | no | array of Item | Optional items classified into quadrants (BCG/Gartner style) |
Quadrant fields
| Field | Required | Type | Description |
|---|---|---|---|
| label | yes | string | Text displayed in the quadrant |
| emphasis | no | string | "primary" or "secondary". See schema. |
| status | no | string | "success", "normal", "warning", or "critical". See schema. |
| position | no | string | Explicit 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):
- Top-left (high Y, low X)
- Top-right (high Y, high X)
- Bottom-left (low Y, low X)
- 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).
| Field | Required | Type | Description |
|---|---|---|---|
| label | yes | string | Text displayed for the item |
| quadrant | yes | string | Owning quadrant by position: top-left/top-right/bottom-left/bottom-right |
| emphasis | no | string | "primary" or "secondary". See schema. |
| status | no | string | "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. quadrantreferences the position slot, so it is independent of whether quadrants were declared with explicitpositionor in index order.- At most 6 items per quadrant (legibility). When a quadrant has items, its
labelis 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_axisis rendered below the horizontal center line.y_axisis rendered to the left of the vertical center line, rotated 90°.- Exactly 4 quadrants are required; more or fewer is a parse error.
Example
Item placement example (BCG)
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
quadrants[].label | 4 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | matrix |
title | string | no | |
x_axis | string | yes | |
y_axis | string | yes |
quadrants — exactly 4 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
position | enum | no | top-left, top-right, bottom-left, bottom-right |
items — any number of elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
quadrant | enum | yes | top-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
| Field | Required | Type | Description |
|---|---|---|---|
| kind | yes | "hub_spoke" | Must be exactly "hub_spoke" |
| title | no | string | Title rendered above the diagram |
| center | yes | string | Label for the central hub node |
| spokes | yes | array of Spoke | At least two spokes required |
Spoke fields
| Field | Required | Type | Description |
|---|---|---|---|
| label | yes | string | Text displayed in the spoke node |
| emphasis | no | string | "primary" or "secondary". See schema. |
| status | no | string | "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
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
center | 3 spokes | 9 / 9 | 22 / 22 |
spokes[].label | 3 spokes | 9 / 9 | 15 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | hub_spoke |
title | string | no | |
center | string | yes |
spokes — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
emphasis | enum | no | primary, secondary |
status | enum | no | success, 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
| Field | Required | Type | Description |
|---|---|---|---|
| kind | yes | "venn" | Must be exactly "venn" |
| title | no | string | Title rendered above the diagram |
| sets | yes | array of Set | 2 or 3 sets required |
| intersections | no | array of Intersection | Labeled regions in the overlap areas |
Set fields
| Field | Required | Type | Description |
|---|---|---|---|
| label | yes | string | Name of the set |
Intersection fields
| Field | Required | Type | Description |
|---|---|---|---|
| sets | yes | array of string | Set labels identifying which overlap region this labels |
| label | yes | string | Text 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
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
sets[].label | 2 sets | — / — | — / — |
intersections[].label | 2 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | venn |
title | string | no |
sets — 2 to 3 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes |
intersections — any number of elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
sets | string[] | yes | the labels of the sets that overlap |
label | string | yes |
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
| Constraint | Rule |
|---|---|
| Rows | 1–10 |
| Columns | 1–8 |
| Column label | Must not be "label" (reserved for the row identifier) |
| Cell keys in rows | Must match a declared columns[].label; unknown keys are an error |
| Missing cells | Treated 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
Example Files
valid/basic.toml— 2 rows × 2 columns, inline cellsvalid/no_title.toml— title omittedvalid/empty_cells.toml— no cells defined (sparse table)valid/basic.json— JSON formatinvalid/no_rows.toml— missing rows → errorinvalid/no_columns.toml— missing columns → errorinvalid/invalid_cell_ref.toml— row uses undeclared column key → errorinvalid/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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
columns[].label | 2 columns, 2 rows | 21 / 21 | 40 / 40 |
rows[].label | 2 columns, 2 rows | 12 / 12 | 23 / 23 |
rows[].<column> | 2 columns, 2 rows | 21 / 21 | 40 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | comparison |
title | string | no |
columns — 1 to 8 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes |
rows — 1 to 10 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
<column> | string | no | one 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 —
triggeris 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
| Field | Required | Type | Description |
|---|---|---|---|
kind | yes | "state" | Must be exactly "state" |
title | no | string | Rendered above the diagram |
states | yes | array of State | At least 2 states required |
transitions | no | array of Transition | May be empty (unconnected states) |
State fields
| Field | Required | Type | Description |
|---|---|---|---|
label | yes | string | Display text. Must be unique unless id is set. |
id | no | string | Stable identifier for from/to references. Falls back to label if omitted. |
role | no | string | "initial" or "terminal". At most one "initial"; multiple "terminal" allowed. |
Transition fields
| Field | Required | Type | Description |
|---|---|---|---|
from | yes | string | id (preferred) or label of source state |
to | yes | string | id (preferred) or label of target state |
trigger | no | string | Event or condition causing this transition |
type | no | string | "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
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
states[].label | 3 states | 7 / 30 | 14 / 55 |
transitions[].trigger | 3 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | state |
title | string | no |
states — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
id | string | no | a short name to refer to the state by |
role | enum | no | initial, terminal |
transitions — any number of elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
from | reference | yes | a state's id or label |
to | reference | yes | a state's id or label |
trigger | string | no | |
type | enum | no | normal, exception |
Rules
- state labels are unique
- state ids are unique
- at most one state has the role
initial fromandtoname 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 order | flow |
| one centre with items radiating from it | hub_spoke |
| the stages of one thing's life, moving between states | state |
| a tree — every item has one parent | hierarchy |
| anything else: components in boundaries, or linked in more than a tree | system |
Fields
| Field | Required | Type | Description |
|---|---|---|---|
kind | yes | "system" | Must be exactly "system" |
title | no | string | Rendered above the diagram |
groups | no | array of Group | Boundaries. At most 6 |
nodes | yes | array of Node | Components. At least 2, at most 16 |
links | no | array of Link | Connections. At most 24 |
Group fields
| Field | Required | Type | Description |
|---|---|---|---|
id | yes | string | Unique across all groups and nodes |
label | yes | string | Display text |
parent | no | string | id of the group this one sits inside. Nesting is at most two deep |
Node fields
| Field | Required | Type | Description |
|---|---|---|---|
id | yes | string | Unique across all groups and nodes |
label | yes | string | Display text |
group | no | string | id of the group the node sits in |
role | no | string | "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 |
emphasis | no | string | "primary" or "secondary" — see Schema |
status | no | string | "success", "normal", "warning" or "critical" — see Schema |
Link fields
| Field | Required | Type | Description |
|---|---|---|---|
from | yes | string | id of a node or a group |
to | yes | string | id of a node or a group |
label | no | string | What passes along the link |
direction | no | string | "forward" (default, from → to), "both", or "none" (an association) |
relation | no | string | "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. groupandparentmust name an existing group;fromandtomust 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_diagnosedreports 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
A link to a whole group:
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.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
groups[].label | 2 groups, 2 nodes, 1 link | 22 / 32 | 42 / 60 |
nodes[].label | 3 nodes, 2 links | 30 / 42 | 28 / 79 |
links[].label | 3 nodes, 2 links | 15 / 21 | 28 / 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
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | system |
title | string | no |
groups — 0 to 6 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
id | string | yes | a short name to refer to the group by |
label | string | yes | |
parent | reference | no | the id of the group this one sits inside |
nodes — 2 to 16 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
id | string | yes | a short name to refer to the node by |
label | string | yes | |
group | reference | no | the id of the group the node sits in |
role | enum | no | store, external, actor |
emphasis | enum | no | primary, secondary |
status | enum | no | success, normal, warning, critical |
links — 0 to 24 elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
from | reference | yes | the id of a node or a group |
to | reference | yes | the id of a node or a group |
label | string | no | |
direction | enum | no | forward, both, none |
relation | enum | no | direct, indirect |
Rules
- node ids and group ids are unique, all in one set
parentnames another group's id, never the group itself- groups nest two deep at most (a group inside a group)
groupnames a group's idfromandtoname 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