academic-flowchart

name

academic-flowchart

description

Use this skill when a user asks to create, revise, render, or export professional flowcharts from natural-language descriptions, structured outlines, or Mermaid-like definitions. Mermaid is only an optional input definition format; the final diagram should be produced through a custom TypeScript or Python SVG/vector graphics pipeline with PNG export, configurable line routing, fonts, shapes, and academic styling.

Academic Flowchart

Overview

Transform natural-language process descriptions, algorithms, research workflows, and system architectures into professional flowcharts. Accept plain-language requirements or user-provided Mermaid syntax as definitions, then build the final diagram through a custom vector graphics pipeline that produces editable SVG artwork and exported PNG previews.

Do not rely on Mermaid rendering as the implementation. Mermaid may be parsed as an input DSL, but final layout, styling, lines, typography, SVG generation, and PNG export must be controlled by the skill's own rendering pipeline or external graphics code.

Workflow

1. Identify the input mode: natural-language description, Mermaid source, rough outline, or existing diagram to revise.
2. Extract process steps, decisions, data stores, actors, inputs, outputs, feedback loops, and required visual constraints.
3. Confirm or infer key style controls: layout direction, line routing, font family, theme, color mode, node shape language, and target output size.
4. Convert the input into an internal diagram model: nodes, edges, groups, labels, layout hints, style tokens, and export settings.
5. If the user supplied Mermaid, parse it only to populate the internal model; do not treat Mermaid output as the final rendering.
6. Compute or refine layout using custom code, a graph layout library, or deterministic positioning rules.
7. Draw the final diagram as SVG with explicit control over paths, fonts, shapes, spacing, colors, arrowheads, and grouping.
8. Export the finalized SVG to PNG after all vector styling and layout adjustments are complete.
9. For revision requests, edit the internal model and renderer configuration first, then regenerate both SVG and PNG.

Input Modes

• Natural language: convert the user's description directly into the internal diagram model.
• Mermaid syntax: parse the user's Mermaid as a graph definition only, then render through the custom SVG pipeline.
• Mixed input: merge the user's Mermaid definition with extra textual requirements such as "use right-angle lines" or "change the font".
• Existing SVG or image: inspect the current structure if possible, then rebuild or post-process it rather than making blind cosmetic edits.

Definition Rules

• Mermaid is allowed only as an input definition format, similar to JSON, YAML, or a plain outline.
• Preserve node IDs, labels, direction hints, edge labels, subgraphs, and shape intent from Mermaid input.
• Do not use Mermaid's built-in renderer as the source of final visual quality.
• Prefer concise labels; split long labels visually in SVG text layout rather than relying on Mermaid line wrapping.
• Represent process nodes, decisions, databases, terminals, groups, and connectors explicitly in the internal diagram model.
• Keep edges semantically meaningful when labels clarify conditions, such as Yes, No, Success, or Failure.
• Avoid dense all-in-one diagrams. If the workflow is large, separate it into clear subgraphs or propose multiple figures.
• Preserve the user's domain terminology, but normalize inconsistent wording before rendering.
• Do not add unverified scientific claims. If the source text is ambiguous, mark the diagram label generically or ask a targeted question.

Vector Styling Controls

Treat SVG as the primary deliverable. The internal diagram model is the structural source for rendering, while Mermaid is only one possible input format.

• Line routing: support straight lines, orthogonal/right-angle lines, curved lines, dashed lines, and arrowhead changes when requested.
• Typography: support font family, font size, weight, letter spacing, and multilingual font fallback when requested.
• Nodes: support custom fill, stroke, radius, padding, shape selection, and semantic style classes.
• Layout: support TD, LR, compact spacing, wide architecture layouts, and grouped subgraphs.
• Export: preserve crisp SVG geometry and export PNG at high resolution or the requested pixel size.

Use TypeScript or Python to implement layout and rendering when needed. Keep transformation logic separated from diagram semantics. For exact function contracts, read references/rendering-interface.md before writing renderer code.

The bundled Python reference renderer lives at scripts/render_flowchart.py. Use it as the default implementation when the current project has no existing renderer.

Renderer modules are intentionally composable:

• scripts/flowchart_renderer/types.py: shared dataclasses and type contracts.
• scripts/flowchart_renderer/parser.py: input definition parsing.
• scripts/flowchart_renderer/model.py: raw structure to internal diagram model.
• scripts/flowchart_renderer/layout.py: node layout and edge routing.
• scripts/flowchart_renderer/svg.py: SVG drawing.
• scripts/flowchart_renderer/themes.py: academic theme colour palettes.
• scripts/flowchart_renderer/export.py: PNG export adapters.
• scripts/flowchart_renderer/pipeline.py: default orchestration.
• scripts/flowchart_renderer/cli.py: argument parsing and CLI entry point.
• scripts/render_flowchart.py: CLI wrapper.
• scripts/check_png_export.py: PNG converter availability check.
• scripts/setup_png_export.py: create a local venv and install PNG export dependencies.
• requirements.txt: Python PNG export dependency (cairosvg).

Implementation Guidance

• Keep user input definitions separate from the internal diagram model and renderer.
• If Mermaid is provided, convert it to the internal model before rendering.
• Keep deterministic visual transformations in separate scripts or renderer modules.
• Replace only the module that needs different behavior. For example, swap layout.py for a new layout engine without changing parser.py or svg.py.
• Avoid hard-coding user-specific content into reusable renderer logic.
• Use the standard pipeline functions: parseDefinition, buildDiagramModel, computeLayout, routeEdges, renderSvg, exportPng, and renderFlowchart.
• Add brief inline comments in generated code only where the transformation is not self-explanatory.

Theme Selection

Default to ieee unless the user specifies a venue or visual preference.

• ieee: grayscale, Times New Roman, sharp academic style.
• acm: sans-serif, sharp edges, deeper colors.
• nature: serif, low saturation, elegant curved lines.
• monochrome: pure black and white with hatch patterns for print.
• springer: Arial nodes with Times New Roman text, classic journal style.

For more theme and layout guidance, read references/theme-guide.md only when choosing or explaining visual style.

Rendering

Use the bundled Python renderer as the default implementation. It accepts a .mmd file (or JSON/YAML/outline) as a definition input and outputs custom SVG and PNG rather than Mermaid's default rendering:

python3 academic-flowchart/scripts/render_flowchart.py <input.mmd> --format mermaid --theme ieee --routing orthogonal --basename final_diagram

It can also be invoked as a module:

python3 -m flowchart_renderer <input.mmd> --format mermaid --theme ieee --basename final_diagram
# (run from academic-flowchart/scripts, or with that directory on PYTHONPATH)

If the host project already ships its own renderer CLI, prefer that project's renderer instead — but still emit custom SVG/PNG, never Mermaid's default output.

PNG export is part of the skill. Prefer installing the bundled Python dependency:

python3 -m pip install -r academic-flowchart/requirements.txt
python3 academic-flowchart/scripts/check_png_export.py

If the system Python is externally managed, use the bundled setup script instead:

python3 academic-flowchart/scripts/setup_png_export.py
academic-flowchart/.venv/bin/python academic-flowchart/scripts/check_png_export.py

The renderer will use cairosvg first, then fall back to rsvg-convert, inkscape, or ImageMagick magick if present. Use --require-png when PNG output is mandatory and the command should fail instead of returning a warning.

Expected outputs:

• <output_basename>.svg
• <output_basename>.png

If the renderer is missing or still delegates visual control to Mermaid's default output, inspect the workspace and implement a small TypeScript or Python SVG pipeline only when necessary. Do not invent output files.

Delivery

Return the generated file paths and briefly state:

• the selected theme,
• the layout direction,
• the line routing and font choices when customized,
• any assumptions made while structuring the diagram,
• whether rendering succeeded or what blocked it.