Delivery Svg Markdown

Delivery: SVG in Markdown

Render dashboards as static SVG panels that embed directly in Markdown files. The output works in GitHub READMEs, VS Code preview, and any browser. No JavaScript runtime, no external CSS, no build step.

This is the mid-tier delivery format: richer than ASCII (color, curves, precise positioning), simpler than HTML (no interactivity, no CDN). The agent uses D3.js concepts (scales, shape generators, axes) as a mental model for producing SVG markup, but the output is raw SVG text, not a running D3 program.

When to Use

• Dashboards that live in GitHub repos (README, wiki, docs)
• Reports rendered in VS Code Markdown preview
• Static visual artifacts that need color, precise layout, or curves
• Anywhere SVG is supported but JavaScript is not (email clients with SVG support, static sites)

When NOT to Use

• Interactive filtering, drill-through, or tooltips needed (use delivery-html-dashboard)
• Terminal-only consumers with no graphical display (use delivery-ascii-dashboard)
• PowerPoint or PDF required (use delivery-slides or delivery-pdf-report)
• The audience is non-technical and expects branded corporate visuals (use HTML or Power BI)

Module 1: SVG Foundations

Coordinate System

SVG uses a top-left origin with y increasing downward. All positioning uses the viewBox attribute for responsive scaling.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 600"
     width="800" height="600" font-family="system-ui, -apple-system, sans-serif">

GitHub Compatibility Rules

GitHub's SVG sanitizer strips many features. These constraints are non-negotiable:

Inline Style Pattern

Every visual element carries its own style as attributes:

<rect x="60" y="100" width="120" height="30"
      fill="#4A90D9" stroke="none" rx="2"/>
<text x="120" y="150" text-anchor="middle"
      fill="#E0E0E0" font-size="12" font-weight="500">Label</text>

Module 2: D3.js Mental Model

The agent does not run D3. It uses D3's conceptual framework to compute SVG coordinates mathematically.

Scales (D3-scale concepts)

A scale maps a data domain to a visual range.

Linear scale (continuous values):

domain: [0, maxValue]
range: [marginLeft, width - marginRight]
map(value) = range[0] + (value - domain[0]) / (domain[1] - domain[0]) * (range[1] - range[0])

Band scale (categorical values):

domain: [categories...]
range: [marginLeft, width - marginRight]
bandwidth = (range[1] - range[0]) / domain.length * (1 - padding)
step = (range[1] - range[0]) / domain.length
map(category) = range[0] + index * step + (step - bandwidth) / 2

Ordinal scale (category to color):

domain: [categories...]
range: [color1, color2, ...]
map(category) = range[index % range.length]

Shape Generators (D3-shape concepts)

Arc generator (pie/donut):

arc(startAngle, endAngle, innerRadius, outerRadius):
  x1 = cx + outerRadius * sin(startAngle)
  y1 = cy - outerRadius * cos(startAngle)
  ...
  path = "M x1,y1 A outerRadius,outerRadius 0 largeArc,1 x2,y2 ..."

Line generator (line charts):

points: [(x1,y1), (x2,y2), ...]
path = "M x1,y1 L x2,y2 L x3,y3 ..."

Area generator (area charts):

path = "M x1,y1_top L x2,y2_top ... L xN,yN_top L xN,yN_bottom ... L x1,y1_bottom Z"

Axis Generation

Axes are groups of lines and text elements:

<!-- Y-axis -->
<g transform="translate(60, 0)">
  <line x1="0" y1="40" x2="0" y2="250" stroke="#666" stroke-width="1"/>
  <!-- Ticks -->
  <g transform="translate(0, 100)">
    <line x1="-5" x2="0" stroke="#666"/>
    <text x="-8" text-anchor="end" fill="#999" font-size="11">50K</text>
  </g>
</g>

Tick count heuristic: 4-7 ticks for most charts. Use round numbers (multiples of 1, 2, 5, 10, 25, 50, 100...).

Module 3: Color Palettes

Dark-Slate Theme (default)

For dark backgrounds (terminal themes, dark-mode READMEs):

Light Theme

For light backgrounds (printed docs, light-mode preview):

Color Assignment Rules

1. Use sequential assignment (Accent 1, 2, 3...) for unrelated categories
2. Use semantic colors (Positive/Negative) when data has inherent direction
3. Never exceed 5 distinct data colors in a single chart (split into panels)
4. Maintain 3:1 minimum contrast ratio between data elements and background
5. For single-series charts, use Accent 1 only

Module 4: Chart Primitives

KPI Strip

A row of metric cards, each showing label + value + optional delta.

<g transform="translate(0, 0)">
  <!-- Card 1 -->
  <rect x="0" y="0" width="250" height="80" rx="4" fill="#2A2A3E"/>
  <text x="20" y="25" fill="#999" font-size="11">REVENUE</text>
  <text x="20" y="55" fill="#E0E0E0" font-size="24" font-weight="700">$246.4K</text>
  <text x="20" y="72" fill="#50C878" font-size="11">+12.3% YoY</text>
</g>

Layout: cards evenly spaced across dashboard width. Gap = 16px between cards. Formula: cardWidth = (dashWidth - (n-1) * gap) / n

Horizontal Bar Chart

<g transform="translate(60, 80)">
  <!-- Bar -->
  <rect x="0" y="0" width="320" height="24" rx="2" fill="#4A90D9"/>
  <!-- Label (left of axis) -->
  <text x="-8" y="16" text-anchor="end" fill="#E0E0E0" font-size="12">North</text>
  <!-- Value (right of bar) -->
  <text x="328" y="16" fill="#999" font-size="11">$139.1K</text>
</g>

Bar spacing: bandwidth = step * 0.7 (30% gap between bars).

Vertical Bar Chart

Same as horizontal, rotated. Y-axis for values, x-axis for categories. Use band scale for x, linear scale for y.

Line Chart

<polyline points="60,200 160,180 260,150 360,160 460,130 560,140"
          fill="none" stroke="#4A90D9" stroke-width="2" stroke-linejoin="round"/>
<!-- Data points -->
<circle cx="60" cy="200" r="3" fill="#4A90D9"/>

For multiple series: one <polyline> per series, different stroke colors.

Area Chart

<path d="M 60,200 L 160,180 L 260,150 ... L 560,250 L 60,250 Z"
      fill="#4A90D9" fill-opacity="0.3" stroke="#4A90D9" stroke-width="2"/>

Pie / Donut Chart

Each slice is a <path> using arc commands:

<path d="M cx,cy-r A r,r 0 largeArc,1 x2,y2 L cx,cy Z" fill="#4A90D9"/>

For donut: add inner radius, close path along inner arc. Maximum slices: 6. Group remaining into "Other."

Sparkline

Minimal line chart without axes, embedded in KPI cards:

<polyline points="0,10 5,8 10,12 15,6 20,9 25,4 30,7"
          fill="none" stroke="#4A90D9" stroke-width="1.5"
          transform="translate(180, 30)"/>

Module 5: Layout System

Grid Layouts

Dashboard Structure

+--[ Title Bar ]------------------------------------------+
|                                                          |
+--[ KPI Strip ]------------------------------------------+
|  [Card 1]  [Card 2]  [Card 3]  [Card 4]               |
+--[ Row 1 ]----------------------------------------------+
|  [Chart: full width]                                     |
+--[ Row 2 ]----------------------------------------------+
|  [Chart: left]          [Chart: right]                  |
+--[ Footer ]---------------------------------------------+
|  Action / Insight sentence                              |
+---------------------------------------------------------+

Vertical Spacing

Total height = sum of all elements + spacing. Set viewBox height accordingly.

Module 6: Construction Process

Step 1: Compute Layout

From the dashboard plan (structured data from orchestrator):

1. Count panels and their layout positions (full, left, right)
2. Assign each panel a row
3. Compute total height: sum all row heights + spacing
4. Set viewBox="0 0 800 {totalHeight}"

Step 2: Compute Scales

For each chart panel:

1. Determine domain from data (min/max for linear; categories for band)
2. Determine range from panel dimensions and margins
3. Use the scale math (Module 2) to get pixel positions

Step 3: Generate SVG Elements

For each panel:

1. Render panel background (<rect> with fill and rx)
2. Render axes (lines + tick marks + labels)
3. Render data elements (bars, lines, arcs)
4. Render data labels (positioned relative to data elements)
5. Render title

Step 4: Assemble Document

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 {h}"
     width="800" height="{h}" font-family="system-ui, -apple-system, sans-serif">
  <!-- Background -->
  <rect width="800" height="{h}" fill="{theme.background}"/>

  <!-- Title -->
  <text x="400" y="30" text-anchor="middle" fill="{theme.textPrimary}"
        font-size="16" font-weight="600">{title}</text>

  <!-- KPI Strip (if present) -->
  <g transform="translate(0, 50)">...</g>

  <!-- Chart panels -->
  <g transform="translate(0, {rowY})">...</g>

  <!-- Footer -->
  <text x="400" y="{h - 15}" text-anchor="middle" fill="{theme.textSecondary}"
        font-size="12">{footer}</text>
</svg>

Step 5: Embed in Markdown

Two output modes:

Inline SVG (for GitHub README):

## Dashboard

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 600" ...>
  ...
</svg>

External file (for linking):

## Dashboard

![Sales Dashboard](./dashboard.svg)

Module 7: Anti-Patterns

Module 8: Validation Checklist

Before delivering SVG output, verify:

Cross-References

• visual-vocabulary -- select chart types before rendering
• storytelling-requirements -- the brief determines delivery target
• delivery-ascii-dashboard -- downgrade path for terminal-only environments
• delivery-html-dashboard -- upgrade path when interactivity is needed