Maradona renders Mermaid diagrams as native Compose Multiplatform composables on Desktop (JVM), Android, and iOS — without a WebView or JavaScript runtime. It is inspired by Pele: fast Mermaid rendering that adapts to your application's theme, built for Compose instead of the browser.
- All 23 Mermaid diagram families parsed and laid out in pure Kotlin (
commonMain), from Flowcharts, Sequence, Class, State, and ER diagrams to C4, Architecture, ZenUML, Gantt, Mindmap, Sankey, XY Chart, Radar, Packet, Kanban, and Treemap. - Interactive Compose UI: pan, pinch/Ctrl+scroll zoom anchored at the pointer, double-tap to reset,
click/linkcallbacks viaonNodeClick, and per-node screen-reader accessibility traversal. - Live-editing resilience: when the input text is mid-edit and temporarily fails to parse, Maradona keeps the last valid diagram visible (dimmed) and displays a compact error banner at the bottom.
- Host-customizable theming, live connectors & Jewel Markdown extension: built-in
light(),dark(),jewelLight(), andjewelDark()presets,MaradonaTheme.fromHost(...), dedicated theme connectors for Material 3 (:maradona-material3across Desktop, Android, and iOS) and JetBrains Jewel (:maradona-jewelon Desktop JVM), plus a Jewel Markdown extension (dev.maradona.markdown.jewel) that renders```mermaid/```mmdfenced code blocks natively inside Jewel'sMarkdownandLazyMarkdowncomposables. - Standalone SVG export:
MaradonaSvgExporter.exportToSvg(source, theme)produces standalone SVG strings across all 23 families without needing a Compose window.
Clone the repository and launch the interactive desktop editor (which includes live examples for all 23 diagram families and theme switching):
./gradlew :sample-desktop:run # Desktop live editor & diagram preview
./gradlew :sample-desktop:run --args="--markdown" # Desktop Jewel Markdown + Mermaid demo
./gradlew :sample-android:installDebug # Android sample app (requires ANDROID_HOME)
open iosApp/iosApp.xcodeproj # iOS sample app (Apple Silicon simulator or device)Maradona 0.1.0 is published on Maven Central (dev.sebastiano.maradona):
// settings.gradle.kts or build.gradle.kts
repositories {
mavenCentral()
google()
}
// build.gradle.kts (commonMain or platform source set)
dependencies {
// Core parser, 23 layout engines, MaradonaDiagram & MaradonaSvgExporter (Desktop JDK 25+, Android minSdk 24, iOS arm64 / simulatorArm64)
implementation("dev.sebastiano.maradona:maradona:0.1.0")
// Optional: live MaterialTheme connector (Desktop, Android, iOS)
implementation("dev.sebastiano.maradona:maradona-material3:0.1.0")
// Optional: live JetBrains Jewel theme connector & Jewel Markdown Mermaid extension (Desktop JVM / JDK 25+ only)
implementation("dev.sebastiano.maradona:maradona-jewel:0.1.0")
}Note for
:maradona-jewelconsumers: JetBrains Jewel0.41.0-262.*artifacts are hosted in the JetBrains IntelliJ repository (maven("https://www.jetbrains.com/intellij-repository/releases")andmaven("https://packages.jetbrains.team/maven/p/ij/intellij-dependencies/")); include those repositories alongsidemavenCentral()when addingdev.sebastiano.maradona:maradona-jewel:0.1.0.
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import dev.maradona.render.MaradonaDiagram
import dev.maradona.render.MaradonaTheme
@Composable
fun CheckoutFlowScreen() {
MaradonaDiagram(
source = """
flowchart LR
subgraph client[Client App]
UI[Compose UI] --> VM[ViewModel]
end
subgraph engine[Maradona]
P[Parser] --> L[Layout Engine]
L --> R([Native Composables])
end
VM --> P
R --> UI
""".trimIndent(),
theme = MaradonaTheme.light(), // or MaradonaTheme.dark(), jewelDark(), jewelLight()
modifier = Modifier.fillMaxSize(),
)
}Maradona ships two optional theme connector modules so diagrams automatically derive their surfaces, borders, text, semantic accents, and typography from your active host theme while keeping desktop-only dependencies out of mobile builds:
dev.sebastiano.maradona:maradona-material3(Desktop, Android, iOS):ProvideMaterial3MaradonaTheme,rememberMaterial3MaradonaTheme, andMaradonaTheme.fromMaterial3(colorScheme, typography)readMaterialTheme.colorSchemeandMaterialTheme.typography.dev.sebastiano.maradona:maradona-jewel(Desktop JVM only):ProvideJewelMaradonaTheme,rememberJewelMaradonaTheme, andMaradonaTheme.fromJewel(...)readJewelTheme.globalColors,JewelTheme.defaultTextStyle,JewelTheme.editorTextStyle, andJewelTheme.isDark(supporting both standaloneIntUiThemeand IntelliJ IDESwingBridgeTheme).
import androidx.compose.material3.MaterialTheme
import dev.maradona.render.MaradonaDiagram
import dev.maradona.theme.jewel.ProvideJewelMaradonaTheme
import dev.maradona.theme.material3.ProvideMaterial3MaradonaTheme
import org.jetbrains.jewel.intui.standalone.theme.IntUiTheme
// Material 3 (Desktop, Android, iOS) — derives from active MaterialTheme.colorScheme & typography
MaterialTheme {
ProvideMaterial3MaradonaTheme {
MaradonaDiagram(source = mermaidSource)
}
}
// JetBrains Jewel (Desktop JVM only) — derives from active JewelTheme.globalColors & text styles
IntUiTheme(isDark = true) {
ProvideJewelMaradonaTheme(useToolwindowBackground = true) {
MaradonaDiagram(source = mermaidSource)
}
}For custom design systems (or when you don't want a connector dependency), :maradona also includes MaradonaTheme.fromHost(...) and static MaradonaTheme.light(), dark(), jewelLight(), and jewelDark() presets:
import dev.maradona.render.MaradonaDiagram
MaradonaDiagram(
source = """
flowchart LR
Spec[Design Spec] --> PR[Pull Request]
click Spec "https://example.com/spec" "Open design spec"
click PR call openPullRequest("42") "Review PR #42"
""".trimIndent(),
onNodeClick = { event ->
// event.nodeId, event.label, event.url, event.callback, event.tooltip
println("Clicked ${event.nodeId}: url=${event.url}, callback=${event.callback}")
},
)import dev.maradona.export.MaradonaSvgExporter
import dev.maradona.render.MaradonaTheme
val svgString: String = MaradonaSvgExporter.exportToSvg(
source = mermaidSource,
theme = MaradonaTheme.light(),
):maradona-jewel also provides a Jewel Markdown extension (dev.maradona.markdown.jewel) that turns ```mermaid and ```mmd fenced code blocks into interactive MaradonaDiagram composables inside Jewel's Markdown and LazyMarkdown while leaving standard code fences (kotlin, sql, json, etc.) to Jewel's syntax highlighter:
import dev.maradona.markdown.jewel.rememberMaradonaMarkdownBlockRenderer
import dev.maradona.markdown.jewel.rememberMaradonaMarkdownProcessor
import org.jetbrains.jewel.intui.markdown.standalone.ProvideMarkdownStyling
import org.jetbrains.jewel.intui.markdown.standalone.styling.dark
import org.jetbrains.jewel.intui.standalone.theme.IntUiTheme
import org.jetbrains.jewel.markdown.Markdown
import org.jetbrains.jewel.markdown.rendering.MarkdownStyling
IntUiTheme(isDark = true) {
val styling = MarkdownStyling.dark()
val processor = rememberMaradonaMarkdownProcessor()
val blockRenderer = rememberMaradonaMarkdownBlockRenderer(rootStyling = styling)
ProvideMarkdownStyling(
isDark = true,
markdownStyling = styling,
markdownProcessor = processor,
markdownBlockRenderer = blockRenderer,
) {
Markdown(
markdown = """
# Architecture Overview
```mermaid
flowchart LR
MD[Markdown] --> Mara([MaradonaDiagram])
```
""".trimIndent(),
)
}
}See docs/diagram-syntax.md for the complete syntax and directive reference for every family.
| Diagram Family | Mermaid Header Keywords | Highlights |
|---|---|---|
| Flowchart | flowchart, graph (TD/TB, BT, LR, RL) |
12 node shapes, v2 @{ shape } metadata, nested subgraphs, click, style / classDef |
| Sequence | sequenceDiagram |
participant & actor, activations (+/-), loop/alt/opt/par/critical/break/rect/box, Note, autonumber |
| Class | classDiagram, classDiagram-v2 |
Generics (~T~), stereotypes, visibility & static/abstract classifiers, UML relations, lollipop interfaces, namespace |
| State | stateDiagram, stateDiagram-v2 |
Composite states, concurrent -- regions, [*] start/end, <<choice>>, <<fork>>, <<join>>, notes |
| Entity-Relationship | erDiagram |
Crow's-foot & natural-language cardinalities, { type name PK/FK/UK "comment" } tables, nested subgraph |
| Mindmap | mindmap |
Indentation tree, 7 node shapes, ::icon(...), :::class, multi-line markdown labels |
| Gantt | gantt |
section, done/active/crit/milestone/vert, after/until dependencies, excludes weekends, compact mode |
| Pie | pie, pie showData |
Percentage slices, configurable donutHole, highlightSlice explosion, legend |
| GitGraph | gitGraph (LR, TB, BT) |
commit (NORMAL/REVERSE/HIGHLIGHT), branch, checkout, merge, cherry-pick, tags |
| Timeline | timeline |
section, multi-era periods, stacked event cards |
| User Journey | journey |
section, task score tracks (1–5), actor dots & legend, satisfaction mood faces |
| Quadrant Chart | quadrantChart |
4 labeled quadrants, rotated Y-axis titles, normalized [x, y] points, classDef point styling |
| XY Chart | xychart, xychart-beta |
Vertical & horizontal orientations, grouped bar series, line series with point labels |
| Kanban | kanban |
Columns, task cards with @{ ticket, assigned, priority, icon }, ticketBaseUrl links |
| Sankey | sankey, sankey-beta |
RFC-4180 CSV flows, proportional node bars, gradient/source/target Bezier ribbons |
| Requirement | requirementDiagram |
6 requirement stereotypes + element, risk & verify badges, contains (⊕) & trace relationships |
| Packet | packet, packet-beta |
Bit-range (0-15), single-bit, and relative (+8) fields, automatic bitsPerRow word wrapping |
| Radar | radar, radar-beta |
Radial axes, polygon & circle graticules, multi-curve overlays, legend |
| Block | block, block-beta |
columns N, column spans, nested composite blocks, 15 block shapes & directional block arrows |
| Architecture | architecture, architecture-beta |
group, service, junction, vector icons (cloud, database, disk, internet, server), port-to-port edges |
| Treemap | treemap, treemap-beta |
Hierarchical sections & valued leaves, squarified proportional tile layout |
| C4 | C4Context, C4Container, C4Component, C4Dynamic, C4Deployment |
Person, System, Container, Component, _Db/_Queue/_Ext, nested boundaries, Rel / RelIndex |
| ZenUML | zenuml |
@Actor/@Boundary/@Database stereotypes, nested call blocks, if/else/while/try/catch, // comments |
| Module | Targets | Purpose |
|---|---|---|
:maradona |
jvm("desktop") (JDK 25+), android (minSdk 24, JDK 25+), iosArm64(), iosSimulatorArm64() |
Core parser, 23 layout engines, MaradonaDiagram, MaradonaTheme, MaradonaSvgExporter (compose-runtime, compose-foundation, compose-ui only) |
:maradona-material3 |
jvm("desktop") (JDK 25+), android (minSdk 24, JDK 25+), iosArm64(), iosSimulatorArm64() |
Live MaterialTheme connector (ProvideMaterial3MaradonaTheme, rememberMaterial3MaradonaTheme, MaradonaTheme.fromMaterial3) |
:maradona-jewel |
jvm("desktop") (Desktop JVM / JDK 25+ only) |
Live JetBrains JewelTheme connector (ProvideJewelMaradonaTheme, rememberJewelMaradonaTheme, MaradonaTheme.fromJewel) and Jewel Markdown Mermaid extension (MermaidMarkdownProcessorExtension, MermaidMarkdownRendererExtension, MaradonaMarkdownBlockRenderer) |
All library code lives in commonMain across three layers:
- Parser (
dev.maradona.parse.MaradonaParser) — Pure Kotlin. Detects the diagram header/frontmatter and parses the source into a typedMaradonaDiagramModelwithout Compose dependencies. - Layout (
dev.maradona.layout.*) — Pure Kotlin. Measures and positions nodes, containers, and edge routes (using a multiplatform port of Dagre/Sugiyama for directed graphs and dedicated layout engines for sequence, tree, timeline, chart, and grid families). - Render & Export (
dev.maradona.render.MaradonaDiagram,dev.maradona.export.MaradonaSvgExporter) — Compose Multiplatform layouts that measure real composable nodes (preserving native text shaping, click hit-testing, and accessibility semantics), draw underlay splines/containers on a single canvas layer, or export standalone SVG.
- Release status & binary/API compatibility (
0.1.0on Maven Central): Maradona0.1.0is published on Maven Central. While pre-1.0, all three published modules (:maradona,:maradona-material3,:maradona-jewel) track binary and source compatibility across JVM, Android, and iOS KLib targets via Kotlin's built-inabiValidation()baselines (./gradlew checkKotlinAbi) and automated API-design/boundary lint (./gradlew verifyApiDesign), both enforced in CI and release workflows. Published-sources.jarartifacts carry complete KDoc for IDE quick-documentation;-javadoc.jaris an intentionalJavadocJar.Empty()placeholder for Sonatype Central validation rather than generated Dokka HTML. - Structural vs. pixel parity with
mermaid.js: Flowchart layout ports Dagre's ranking, crossing reduction, and Brandes–Köpf coordinate assignment (<= 5%node size and<= 2%centre tolerance againstmermaid.js), while the other 22 families use independent pure-Kotlin layout engines. Renders are structurally faithful and verified across 71 fixtures on Desktop, Android, and iOS, not pixel-identical to Chromiummermaid.js. - Large diagram scalability: Inputs are capped at
50,000characters,5,000nodes, and5,000edges. When zoomed in (viewportCullingEnabled = true, the default), Maradona lazily composes only on-screen nodes/labels and culls off-screen underlay elements across all 23 diagram families while keeping cross-viewport edges and off-screen accessibility actions intact (~2.6 ms/frame when panning a 400-node graph). When zoomed out so that thousands of nodes are simultaneously visible inside the viewport, layout and frame times remain CPU-bound.
- Supported Mermaid Syntax Reference (
docs/diagram-syntax.md) — Per-family syntax, directives, and styling options across all 23 families. - Theming, Interaction & SVG Export (
docs/theming-and-integration.md) —ProvideMaterial3MaradonaTheme,ProvideJewelMaradonaTheme,MaradonaTheme,LocalMaradonaTheme,fromHost,onNodeClick,LocalMaradonaImageResolver, andMaradonaSvgExporter. - Oracle Verification & Testing (
docs/oracle-and-testing.md) — Running unit tests, screenshot smoke tests, and the 71-fixture × 3-platform visual & layout oracle. - Publishing & Release Guide (
docs/publishing.md) — Maven Central coordinates, tag-driven release pipeline,:verifyMavenLocalPublication, andscripts/central_portal_check.py. - Changelog (
CHANGELOG.md) — Release history and0.1.0summary.
Apache License 2.0 — see LICENSE.



