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.