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.