Rethinking diagrams: from fixed types to composition (Runiq DSL)

Justin Greywolf — Sun, 12 Apr 2026 18:49:00 +0000

Most diagram tools ask you to make a decision before you even start:

Do you want a flowchart? Sequence diagram, Architecture diagram, UML diagram, etc.

Each comes with its own syntax, rules, and constraints. And that works well - until it doesn’t.

Real systems don’t fit neatly into a single diagram type. They blend structure, flow, relationships, and context. But most tools force you to pick one model and stay within it.

Switching between diagram types often means switching syntax, mental models, and sometimes even tools.

Over time, that friction adds up.

Background:

I’ve spent a lot of time working with diagramming software and tooling in general, and was even a member of the MermaidJS team, so I’ve seen firsthand where these tools shine, and where they start to feel a little rigid.

Runiq grew out of that experience.

I kept running into the same problem. Switching diagram types meant switching syntax, tools, and mental models. As systems grew, adding new features became harder, and supporting new diagram types often meant building entirely new structures from scratch.

Runiq is an attempt to unify that into a single system. Without forcing everything into one box.

The idea: "composable diagrams"

Instead of defining diagrams strictly by type, Runiq is built around a shared system.

In the main diagram profile, you can:

mix shapes from different diagram styles
combine flow, structure, and relationships
reuse styling and layout concepts consistently

For example, a single diagram might include:

flowchart-style decisions
architecture-style containers
labeled relationships between components

This allows diagrams to reflect how systems actually work, rather than forcing them into predefined categories. Or even being able to display a flowchart and pie charts in the same diagram.

Domain boundaries (important)

Granted, not everything can be mixed together.

Some diagram types live in their own profiles because they follow different rules or require specialized layouts:

sequence diagrams
timelines
family trees (pedigree diagrams)
technical schematics (electrical, digital, etc.)

These are intentionally separate.

So the model is:

composable where it makes sense
separate where the domain requires it

Runiq also includes glyphsets, which are essentially predefined layout patterns—similar to SmartArt.

These let you quickly generate common diagram structures like:

cycles
hierarchies
matrices

They’re useful when you want to move fast without manually defining every node and connection. You can also "convert" most glyphsets to a different style, without having to change your syntax or adjust your existing items

Example:
Here is an example that combines flowchart + typed containers + C4/cloud + UML state + chart/requirement/threat shapes in a single diagram.

diagram "Composable Checkout" {
  direction LR

  container insight "Signals" as @requirementPackage {
    shape funnel as @pyramid label:"Checkout Funnel" data:[100,72,48,41]
    shape audit as @requirement label:"REQ-12\nAudit every order"
  }
  container journey "Checkout Flow" as @systemBoundary  {
    shape user as @actor label:"Customer"
    shape cart as @document label:"Cart"
    shape valid as @rhombus label:"Payment valid?"
    shape receipt as @document label:"Receipt"
    shape retry as @rounded label:"Retry"
  }

  container platform "Platform" as @awsVpc {
    shape api as @c4Container label:"Checkout API"
    shape worker as @awsLambda label:"Worker"
    shape db as @awsRds label:"Orders DB"
  }

  container lifecycle "Order State" as @umlPackage {
    shape received as @state label:"Received"
    shape paid as @state label:"Paid"
    shape fulfilled as @state label:"Fulfilled"
  }

  shape fraud as @threat label:"Fraud attempt"
  shape mfa as @mitigation label:"Risk scoring"

  user -> cart
  cart -> valid
  valid -yes-> receipt
  valid -no-> retry
  retry -> valid

  receipt -> api
  api -> worker
  worker -> db

  db -> received
  received -> paid
  paid -> fulfilled

  fulfilled -> funnel
  db -> audit

  fraud -> valid
  mfa -> fraud
}

Output

Runiq generates clean, standards-compliant SVG.

There are no HTML-based rendering tricks, which makes the output more reliable in environments like PowerPoint, PDFs, and other strict SVG consumers.

Tradeoffs

Runiq isn’t strictly better than existing tools in every case.

Mermaid’s markdown-style syntax is lighter and faster for simple diagrams
PlantUML has a mature ecosystem and broad support
Runiq is newer, with a smaller ecosystem
Not all diagram types are composable (some are intentionally separate)

Runiq leans toward:

more structure (DSL instead of markdown-like syntax)
more flexibility (composition where appropriate)

Why this approach

The goal isn’t to replace every diagram tool.

It’s to explore a different model:

A system where diagrams share a common foundation, instead of being isolated by type.

Try it out

Docs: https://runiq.org/
Editor: https://editor.runiq.org/

Feedback

If you’re coming from Mermaid or PlantUML, I’d especially be interested in:

where this feels better
where it feels worse -anything that feels confusing or missing

DEV Community: Justin Greywolf

Rethinking diagrams: from fixed types to composition (Runiq DSL)