Commune

AntV Infographic: Complete Guide

7 min read

AntV Infographic: Complete Guide

AntV Infographic is a template-driven infographic engine that transforms structured data into polished visual layouts. In our infrastructure, it runs as an MCP server (Infographic MCP on port 3012) rendering via Playwright. This guide covers the DSL syntax, every template category with correct field names, theming from basic to advanced, and the brand module architecture for consistent visual identity.

Architecture

The Infographic MCP accepts a DSL specification (template name + structured data) and renders it through Playwright to produce an image. Output can be PNG or HTML—the HTML path unlocks the full JavaScript API for advanced theming.

Agent → DSL spec → Infographic MCP (port 3012) → Playwright render → PNG/HTML

Templates and Field Names

Getting the field names right is critical—the wrong field name produces empty output with no error. Each template category expects a specific top-level data field.

List templates → lists field

Templates: list-* (e.g., list-waterfall-badge-card, list-waterfall-compact-card)

{
  "template": "list-waterfall-badge-card",
  "data": {
    "title": "Project Milestones",
    "lists": [
      { "label": "Phase 1", "desc": "Research and planning", "value": "Q1 2026" },
      { "label": "Phase 2", "desc": "Implementation", "value": "Q2 2026" }
    ]
  }
}

Sequence templates → sequences field

Templates: sequence-* (e.g., sequence-funnel-simple)

{
  "template": "sequence-funnel-simple",
  "data": {
    "title": "Sales Pipeline",
    "sequences": [
      { "label": "Leads", "value": "1000" },
      { "label": "Qualified", "value": "250" },
      { "label": "Closed", "value": "50" }
    ]
  }
}

Compare templates → compares field

Templates: compare-* (e.g., compare-quadrant-quarter-simple-card, compare-quadrant-quarter-circular)

{
  "template": "compare-quadrant-quarter-simple-card",
  "data": {
    "title": "Framework Comparison",
    "compares": [
      { "label": "React", "desc": "Component-based UI", "value": "95" },
      { "label": "Vue", "desc": "Progressive framework", "value": "88" }
    ]
  }
}

Chart templates → values field

Templates: chart-*

{
  "template": "chart-bar-simple",
  "data": {
    "title": "Monthly Revenue",
    "values": [
      { "label": "Jan", "value": 12000 },
      { "label": "Feb", "value": 15000 }
    ]
  }
}

Hierarchy tree templates → root with children nesting

Templates: hierarchy-tree-*, hierarchy-mindmap-* (e.g., hierarchy-mindmap-branch-gradient-capsule-item, hierarchy-mindmap-level-gradient-compact-card)

{
  "template": "hierarchy-mindmap-branch-gradient-capsule-item",
  "data": {
    "title": "System Architecture",
    "root": {
      "label": "Platform",
      "children": [
        {
          "label": "Frontend",
          "children": [
            { "label": "React App" },
            { "label": "Mobile App" }
          ]
        },
        {
          "label": "Backend",
          "children": [
            { "label": "API Gateway" },
            { "label": "Database" }
          ]
        }
      ]
    }
  }
}

Hierarchy structure templates → items field

Template: hierarchy-structure

{
  "template": "hierarchy-structure",
  "data": {
    "title": "Organization",
    "items": [
      { "label": "Engineering", "desc": "Product development" },
      { "label": "Design", "desc": "User experience" }
    ]
  }
}

Relation templates → nodes + relations fields

Templates: relation-* (e.g., relation-dagre-flow-tb-badge-card, relation-dagre-flow-tb-simple-circle-node, plus animated variants)

{
  "template": "relation-dagre-flow-tb-badge-card",
  "data": {
    "title": "Data Pipeline",
    "nodes": [
      { "id": "ingest", "label": "Ingest", "desc": "Raw data collection" },
      { "id": "transform", "label": "Transform", "desc": "Clean and normalize" },
      { "id": "store", "label": "Store", "desc": "Write to warehouse" }
    ],
    "relations": [
      { "source": "ingest", "target": "transform" },
      { "source": "transform", "target": "store" }
    ]
  }
}

Fallback → items field

When unsure which field a template expects, items often works as a fallback.

DSL Theming (Basic)

The DSL supports basic theming through the theme block in your specification.

Theme modes

theme: dark      # Dark background
theme: default   # Light background
theme: hand-drawn # Sketch style

Stylize options

theme:
  stylize: rough              # Hand-drawn look
  stylize: pattern            # Fill patterns
  stylize: linear-gradient    # Gradient fills
  stylize: radial-gradient    # Radial gradient fills

Known limitations

  • theme > palette does NOT work in the MCP — it is silently ignored. Use the JS API for palette control.
  • theme > base > text > font-family only works reliably in rough mode.

JS API Theming (Full Power)

The JavaScript API provides complete control over every visual aspect. This is accessed either through HTML output mode or via the upcoming themeConfig parameter on generate_infographic.

registerTheme

Register a named theme with full configuration:

import { registerTheme } from '@antv/infographic';
 
registerTheme('my-brand', {
  colorPrimary: '#d8e84e',
  colorBg: '#151719',
  
  // Typography
  title: {
    fontSize: 28,
    fontWeight: 'bold',
    fill: '#ffffff',
    fontFamily: 'Inter'
  },
  base: {
    text: {
      fontFamily: 'Inter',
      fontSize: 14,
      fill: '#e0e0e0'
    },
    shape: {
      stroke: '#333333',
      strokeWidth: 1
    }
  },
  
  // Per-element typography
  item: {
    label: { fontSize: 16, fontWeight: 'bold', fill: '#ffffff' },
    desc: { fontSize: 12, fill: '#aaaaaa' },
    value: { fontSize: 20, fontWeight: 'bold', fill: '#d8e84e' }
  },
  
  // Color palettes
  palette: {
    category: ['#d8e84e', '#4ecdc4', '#ff6b6b', '#45b7d1', '#96ceb4'],
    diverging: ['#ff6b6b', '#ffd93d', '#6bcb77']
  },
  
  // Stylize
  stylize: {
    rough: {
      roughness: 1.5,
      bowing: 2,
      fill: 'hachure',
      fillWeight: 2
    }
  }
});

themeConfig (inline, no registration)

Pass theme configuration directly to the Infographic constructor without needing to register:

const infographic = new Infographic({
  template: 'list-waterfall-badge-card',
  data: { /* ... */ },
  themeConfig: {
    colorPrimary: '#ff2600',
    colorBg: '#000000',
    base: { text: { fill: '#ffffff' } }
  }
});

This is the approach the upcoming MCP themeConfig parameter will use.

registerPalette

Create named color palettes:

import { registerPalette } from '@antv/infographic';
 
registerPalette('gothic', {
  category: ['#ff2600', '#cc0000', '#990000', '#660000', '#330000'],
  diverging: ['#ff2600', '#ffffff', '#0026ff']
});

registerFont

Load custom fonts:

import { registerFont, setDefaultFont } from '@antv/infographic';
 
registerFont({
  name: 'Inter',
  source: 'google',
  weights: [400, 600, 700]
});
 
// Or custom hosted font
registerFont({
  name: 'CustomFont',
  source: 'custom',
  weights: [400, 700]
});
 
setDefaultFont('Inter');

Custom Font Loading in MCP Context

CORS Issue: When loading custom fonts from external URLs (e.g., GitHub raw URLs), browser CORS policies block direct @font-face loading. The Infographic MCP server implements server-side font fetching to bypass this:

// Server-side: Fetch fonts and convert to data URLs
async function resolveFonts(fonts) {
  return Promise.all(fonts.map(async (font) => {
    const response = await fetch(font.url);
    const buffer = await response.buffer();
    const base64 = buffer.toString('base64');
    const format = font.format || 'woff2';
    return {
      name: font.name,
      url: `data:font/${format};base64,${base64}`
    };
  }));
}

Canvas Pre-loading: CSS @font-face declarations alone are insufficient for canvas renderers. Fonts must be explicitly pre-loaded via document.fonts.load():

// In Playwright page context before rendering
for (const font of fonts) {
  const fontFace = new FontFace(font.name, `url(${font.url})`);
  document.fonts.add(fontFace);
  await document.fonts.load(`16px "${font.name}"`);
}

MCP API Pattern: The fonts parameter accepts an array of font definitions:

{
  "fonts": [
    {
      "name": "Waning Star",
      "url": "https://raw.githubusercontent.com/oakbrad/dungeonchurch-basilica/refs/heads/main/assets/ws.woff2"
    }
  ],
  "themeConfig": {
    "title": { "fontFamily": "Waning Star, serif" }
  }
}

The server fetches the font, converts to data URL, injects @font-face, and pre-loads before rendering. This pattern enables custom brand fonts (like Dungeon Church’s Waning Star) without CORS errors or missing glyphs in canvas output.

registerPattern

Create custom SVG fill patterns:

import { registerPattern } from '@antv/infographic';
 
registerPattern('diagonal-lines', (color) => `
  <pattern id="diagonal" width="10" height="10" patternUnits="userSpaceOnUse">
    <line x1="0" y1="10" x2="10" y2="0" stroke="${color}" stroke-width="2"/>
  </pattern>
`);

registerResourceLoader

Inject custom icons, logos, or images:

import { registerResourceLoader } from '@antv/infographic';
 
registerResourceLoader(async ({ type, data }) => {
  if (type === 'icon' && data === 'company-logo') {
    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
    // Build or load SVG element
    return svg;
  }
});

generateThemeColors

Auto-generate a harmonious color scheme from a primary color:

import { generateThemeColors } from '@antv/infographic';
 
const colors = generateThemeColors({
  colorPrimary: '#d8e84e',
  colorBg: '#151719',
  isDarkMode: true
});
// Returns a full set of derived colors

JSX rendering

For fully custom layouts beyond templates:

import { renderSVG, createLayout, FlexLayout, Group, Rect, Text, Path } from '@antv/infographic';
 
const svg = renderSVG(
  <FlexLayout direction="column" gap={16}>
    <Text text="Custom Title" fontSize={24} fill="#ffffff" />
    <Rect width={200} height={100} fill="#d8e84e" cornerRadius={8} />
  </FlexLayout>
);

Template Reference

Complete template list

List templates:

  • Standard list variants (badge, compact, card styles)
  • list-waterfall-badge-card — waterfall layout with badge cards
  • list-waterfall-compact-card — waterfall layout, compact

Sequence templates:

  • sequence-funnel-simple — funnel visualization
  • Various timeline and step sequence variants

Compare templates:

  • compare-quadrant-quarter-simple-card — quadrant layout with cards
  • compare-quadrant-quarter-circular — circular quadrant layout

Hierarchy templates:

  • hierarchy-mindmap-branch-gradient-capsule-item — mind map with gradient capsules
  • hierarchy-mindmap-level-gradient-compact-card — mind map with level gradients
  • Various tree layouts

Relation templates:

  • relation-dagre-flow-tb-badge-card — top-to-bottom flow with badge cards
  • relation-dagre-flow-tb-simple-circle-node — top-to-bottom flow with circle nodes
  • Animated variants of the above

Chart templates:

  • Various bar, line, and area chart layouts

When to Use Infographic vs Other Tools

NeedTool
Data-driven charts (bar, line, pie, scatter)Chart MCP
Technical diagrams (flowcharts, ER, sequence)Mermaid MCP
Information layouts, comparisons, hierarchiesInfographic MCP
Branded visual content with custom typographyInfographic MCP + Brand Theming
Quick architecture diagramsMermaid MCP

Infographic excels at information design — presenting structured data in visually appealing layouts with titles, descriptions, and values. It’s the right tool when you want something that looks like a designed infographic rather than a technical chart or diagram.

Reference compiled 2026-02-19 for commune AI agent workflows.

Graph View

Backlinks