Field Agent Visualization Best Practices

This skill provides comprehensive guidelines for creating professional, executive-ready visualizations for Field Agents using Plotly. Follow these standards to ensure clean, readable, and impactful data visualizations.

When to Use This Skill

Use this skill when you need to:

• Create Plotly visualizations for Field Agent outputs
• Generate charts for data analysis and reporting
• Build dashboards with KPI indicators
• Design executive-ready visual presentations
• Ensure consistent visualization standards across agents

Core Principles

Golden Rules

1. Create SINGLE CHARTS ONLY - NO SUBPLOTS for analysis charts
2. Always use descriptive titles, axis labels, and legends
3. Ensure proper formatting and readability
4. Use the specified color palette consistently
5. Always show numbers/percentages in bar charts and heatmaps
6. LEGENDS MUST BE VISIBLE for pie charts and comparison charts
7. NEVER CREATE SUBPLOTS for analysis - Always create separate individual charts

MANDATORY Color Palette

Always use this Treasure Data color palette for consistency:

TD_COLORS = [
    '#44BAB8',  # Teal (Primary)
    '#8FD6D4',  # Light Teal
    '#DAF1F1',  # Pale Teal
    '#2E41A6',  # Navy Blue
    '#828DCA',  # Purple
    '#D5D9ED',  # Light Purple
    '#8CC97E',  # Green
    '#BADFB2',  # Light Green
    '#E8F4E5',  # Pale Green
    '#EEB53A',  # Accent Yellow
    '#F5D389',  # Light Yellow
    '#5FCFD8',  # Cyan
    '#A05EB0',  # Magenta
    '#C69ED0'   # Light Magenta
]

Usage:

• Use #44BAB8 (Teal) as primary color for single-series charts
• Use #2E41A6 (Navy) for text and titles
• Cycle through colors for multi-series charts
• Use color scales for heatmaps (DAF1F1 → 8FD6D4 → 44BAB8)

Color Conversion Helper Function

For charts requiring RGB/RGBA format (e.g., transparency effects):

def hex_to_rgb(hex_color):
    """Convert hex color to RGB tuple

    Args:
        hex_color (str): Hex color code (e.g., '#44BAB8' or '44BAB8')

    Returns:
        tuple: RGB values as (R, G, B) where each value is 0-255

    Example:
        >>> hex_to_rgb('#44BAB8')
        (68, 186, 184)
    """
    hex_color = hex_color.lstrip('#')
    return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))

def hex_to_rgba(hex_color, alpha=1.0):
    """Convert hex color to RGBA string for Plotly

    Args:
        hex_color (str): Hex color code (e.g., '#44BAB8')
        alpha (float): Opacity value 0.0-1.0

    Returns:
        str: RGBA color string (e.g., 'rgba(68, 186, 184, 0.5)')

    Example:
        >>> hex_to_rgba('#44BAB8', 0.5)
        'rgba(68, 186, 184, 0.5)'
    """
    r, g, b = hex_to_rgb(hex_color)
    return f'rgba({r}, {g}, {b}, {alpha})'

# Usage examples:
td_primary_rgb = hex_to_rgb('#44BAB8')  # (68, 186, 184)
td_primary_transparent = hex_to_rgba('#44BAB8', 0.3)  # 'rgba(68, 186, 184, 0.3)'

---

CRITICAL: JSON Structure Requirements

✅ CORRECT JSON Format

Always use proper JSON objects with native arrays and objects:

{
  "data": [
    {
      "type": "bar",
      "x": ["A", "B", "C"],
      "y": [10, 20, 30],
      "marker": {"color": "#44BAB8"},
      "text": ["10", "20", "30"],
      "textposition": "outside",
      "textfont": {"size": 11, "color": "black"}
    }
  ],
  "layout": {
    "title": {
      "text": "Chart Title",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "showlegend": true,
    "margin": {"t": 120, "b": 80, "l": 80, "r": 80},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

❌ NEVER DO: String Data (Causes Errors)

{
  "data": "[{\"type\": \"bar\", \"x\": [\"A\", \"B\"], \"y\": [10, 20]}]"
}

Critical: Data must be JSON objects and arrays, NOT stringified JSON.

---

CRITICAL: Missing Elements Fixes

For Bar Charts - MANDATORY Properties

{
  "data": [{
    "type": "bar",
    "x": ["Category A", "Category B", "Category C"],
    "y": [45, 30, 25],
    "name": "Series Name",
    "marker": {"color": "#44BAB8"},
    "text": [45, 30, 25],  // ⚠️ CRITICAL: Must include for numbers on bars
    "textposition": "outside",  // ⚠️ CRITICAL: Shows numbers above bars
    "textfont": {"size": 11, "color": "black"}
  }],
  "layout": {
    "title": {"text": "Bar Chart Title", "x": 0.5, "font": {"size": 18}},
    "height": 500,
    "showlegend": true,  // ⚠️ CRITICAL: Must be true for multi-series
    "legend": {
      "orientation": "h",
      "yanchor": "bottom",
      "y": 1.05,  // ⚠️ CRITICAL: Must be above 1.0 to be visible
      "xanchor": "center",
      "x": 0.5
    },
    "margin": {"t": 120, "b": 80, "l": 80, "r": 80},  // ⚠️ CRITICAL: Extra top margin for legend
    "xaxis": {"title": {"text": "Categories", "font": {"size": 14}}},
    "yaxis": {"title": {"text": "Values", "font": {"size": 14}}},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

For Heatmaps - MANDATORY Properties

{
  "data": [{
    "type": "heatmap",
    "x": ["Col A", "Col B", "Col C"],
    "y": ["Row 1", "Row 2", "Row 3"],
    "z": [[23.4, 45.6, 12.3], [34.5, 56.7, 23.1], [45.2, 67.8, 34.5]],
    "text": [[23.4, 45.6, 12.3], [34.5, 56.7, 23.1], [45.2, 67.8, 34.5]],  // ⚠️ CRITICAL: Numbers to display
    "texttemplate": "%{text:.1f}",  // ⚠️ CRITICAL: Format to 1 decimal
    "textfont": {"size": 12, "color": "black"},  // ⚠️ CRITICAL: Visible text
    "showscale": true,  // ⚠️ CRITICAL: Show color scale
    "colorscale": [
      [0, "#DAF1F1"],
      [0.5, "#8FD6D4"],
      [1, "#44BAB8"]
    ],
    "colorbar": {
      "title": {"text": "Value", "font": {"size": 12}},
      "titleside": "right"
    },
    "hovertemplate": "<b>%{y}</b> - <b>%{x}</b><br>Value: %{z:.1f}<extra></extra>"
  }],
  "layout": {
    "title": {"text": "Heatmap Title", "x": 0.5, "font": {"size": 18}},
    "height": 500,
    "xaxis": {"title": {"text": "X Axis", "font": {"size": 14}}},
    "yaxis": {"title": {"text": "Y Axis", "font": {"size": 14}}},
    "margin": {"t": 80, "b": 80, "l": 80, "r": 100},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

Common Issues Fix Checklist

Before generating any chart, verify:

• Bar charts: Include "text", "textposition": "outside", "textfont"
• Multi-series: Include "showlegend": true, legend "y": 1.05 or higher
• Legend spacing: Top margin "t": 120 minimum for horizontal legends
• Heatmaps: Include "text", "texttemplate": "%{text:.1f}", "showscale": true
• Text visibility: Use "textfont": {"color": "black"} for contrast
• JSON format: Use proper objects/arrays, NOT stringified JSON
• Color palette: Use TD colors exclusively
• No subplots: Create individual charts for analysis

---

Chart-Specific Guidelines

1. Pie Charts - LEGEND MANDATORY

Pie charts ALWAYS require visible legends.

{
  "data": [{
    "type": "pie",
    "values": [45, 30, 25],
    "labels": ["Channel A", "Channel B", "Channel C"],
    "marker": {
      "colors": ["#44BAB8", "#8FD6D4", "#DAF1F1"]
    },
    "textinfo": "label+percent",
    "textposition": "auto",
    "textfont": {"size": 14, "color": "black"},
    "hovertemplate": "<b>%{label}</b><br>Value: %{value}<br>Percentage: %{percent}<extra></extra>"
  }],
  "layout": {
    "title": {
      "text": "Attribution Distribution",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "showlegend": true,
    "legend": {
      "orientation": "v",
      "yanchor": "middle",
      "y": 0.5,
      "xanchor": "left",
      "x": 1.02,
      "font": {"size": 12}
    },
    "margin": {"t": 80, "b": 80, "l": 80, "r": 150},
    "font": {"family": "Arial", "size": 12},
    "paper_bgcolor": "white"
  }
}

Key Points:

• Use vertical legend positioned to the right (x: 1.02)
• Include extra right margin (r: 150) for legend space
• Show both label and percent in slices
• Use TD color palette for consistent branding

---

2. Bar Charts with Comparison - LEGEND VISIBLE

Multi-series bar charts require horizontal legends positioned above the chart.

{
  "data": [
    {
      "type": "bar",
      "x": ["Channel A", "Channel B", "Channel C"],
      "y": [45, 30, 25],
      "name": "Metric 1",
      "marker": {"color": "#44BAB8"},
      "text": [45, 30, 25],
      "textposition": "outside",
      "textfont": {"size": 11, "color": "black"}
    },
    {
      "type": "bar",
      "x": ["Channel A", "Channel B", "Channel C"],
      "y": [35, 40, 30],
      "name": "Metric 2",
      "marker": {"color": "#8FD6D4"},
      "text": [35, 40, 30],
      "textposition": "outside",
      "textfont": {"size": 11, "color": "black"}
    }
  ],
  "layout": {
    "title": {
      "text": "Channel Comparison",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "barmode": "group",
    "showlegend": true,
    "legend": {
      "orientation": "h",
      "yanchor": "bottom",
      "y": 1.05,
      "xanchor": "center",
      "x": 0.5,
      "font": {"size": 12}
    },
    "xaxis": {
      "title": {"text": "Channels", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "yaxis": {
      "title": {"text": "Performance %", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "margin": {"t": 120, "b": 80, "l": 80, "r": 80},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

Key Points:

• Set barmode to "group" for side-by-side or "stack" for stacked
• Horizontal legend above chart (y: 1.05)
• Adequate top margin (t: 120)
• Numbers displayed on all bars

---

3. Single Bar Chart - NO Legend Needed

{
  "data": [{
    "type": "bar",
    "x": ["Product A", "Product B", "Product C", "Product D"],
    "y": [1200, 950, 800, 650],
    "marker": {"color": "#44BAB8"},
    "text": ["$1,200", "$950", "$800", "$650"],
    "textposition": "outside",
    "textfont": {"size": 11, "color": "black"}
  }],
  "layout": {
    "title": {
      "text": "Revenue by Product",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "showlegend": false,
    "xaxis": {
      "title": {"text": "Products", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "yaxis": {
      "title": {"text": "Revenue ($)", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "margin": {"t": 80, "b": 80, "l": 80, "r": 80},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

Key Points:

• Single series = no legend needed (showlegend: false)
• Use primary TD color (#44BAB8)
• Show formatted values on bars

---

4. Heatmaps - Numbers with 1 Decimal

{
  "data": [{
    "type": "heatmap",
    "x": ["Channel A", "Channel B", "Channel C"],
    "y": ["Week 1", "Week 2", "Week 3"],
    "z": [
      [23.4, 45.6, 12.3],
      [34.5, 56.7, 23.1],
      [45.2, 67.8, 34.5]
    ],
    "colorscale": [
      [0, "#DAF1F1"],
      [0.5, "#8FD6D4"],
      [1, "#44BAB8"]
    ],
    "showscale": true,
    "colorbar": {
      "title": {"text": "Performance", "font": {"size": 12}},
      "titleside": "right"
    },
    "text": [
      [23.4, 45.6, 12.3],
      [34.5, 56.7, 23.1],
      [45.2, 67.8, 34.5]
    ],
    "texttemplate": "%{text:.1f}",
    "textfont": {"size": 12, "color": "black"},
    "hovertemplate": "<b>%{y}</b> - <b>%{x}</b><br>Value: %{z:.1f}<extra></extra>"
  }],
  "layout": {
    "title": {
      "text": "Performance Heatmap",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "xaxis": {
      "title": {"text": "Channels", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "yaxis": {
      "title": {"text": "Time Periods", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "margin": {"t": 80, "b": 80, "l": 80, "r": 100},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

Key Points:

• Include text array matching z values
• Use texttemplate: "%{text:.1f}" for 1 decimal formatting
• Use TD color scale (light to dark)
• Show color scale bar

---

5. Line Charts with Multiple Series

{
  "data": [
    {
      "type": "scatter",
      "mode": "lines+markers",
      "x": ["Jan", "Feb", "Mar", "Apr"],
      "y": [10, 15, 20, 25],
      "name": "Channel A",
      "line": {"color": "#44BAB8", "width": 3},
      "marker": {"color": "#44BAB8", "size": 8}
    },
    {
      "type": "scatter",
      "mode": "lines+markers",
      "x": ["Jan", "Feb", "Mar", "Apr"],
      "y": [8, 12, 18, 22],
      "name": "Channel B",
      "line": {"color": "#8FD6D4", "width": 3},
      "marker": {"color": "#8FD6D4", "size": 8}
    }
  ],
  "layout": {
    "title": {
      "text": "Performance Trends",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "showlegend": true,
    "legend": {
      "orientation": "h",
      "yanchor": "bottom",
      "y": 1.02,
      "xanchor": "center",
      "x": 0.5,
      "font": {"size": 12}
    },
    "xaxis": {
      "title": {"text": "Time Period", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "yaxis": {
      "title": {"text": "Performance", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "margin": {"t": 100, "b": 80, "l": 80, "r": 80},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

Key Points:

• Use scatter type with mode: "lines+markers"
• Different colors for each series from TD palette
• Horizontal legend above chart
• Visible markers on data points

---

6. Sankey Diagrams

{
  "data": [{
    "type": "sankey",
    "orientation": "h",
    "node": {
      "pad": 15,
      "thickness": 30,
      "line": {"color": "black", "width": 0.5},
      "label": ["Source A", "Source B", "Destination X", "Destination Y"],
      "color": ["#44BAB8", "#8FD6D4", "#2E41A6", "#828DCA"]
    },
    "link": {
      "source": [0, 1, 0, 1],
      "target": [2, 2, 3, 3],
      "value": [10, 20, 15, 25],
      "color": [
        "rgba(68, 186, 184, 0.4)",
        "rgba(143, 214, 212, 0.4)",
        "rgba(68, 186, 184, 0.4)",
        "rgba(143, 214, 212, 0.4)"
      ]
    }
  }],
  "layout": {
    "title": {
      "text": "Customer Journey Flow",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 600,
    "margin": {"t": 80, "b": 50, "l": 50, "r": 50},
    "font": {"family": "Arial", "size": 12},
    "paper_bgcolor": "white"
  }
}

Key Points:

• Node colors from TD palette
• Semi-transparent link colors (0.4 opacity)
• Clear node labels
• Adequate height (600px) for visibility

---

Legend Configuration Standards

When to Show Legends

Chart Type	Show Legend?	Position
Pie Chart	✅ ALWAYS	Vertical, right side
Multi-Series Bar	✅ ALWAYS	Horizontal, top
Single Bar	❌ NEVER	N/A
Multi-Series Line	✅ ALWAYS	Horizontal, top
Single Line	❌ NEVER	N/A
Heatmap	❌ (Use colorbar)	N/A
Sankey	❌ (Labels in nodes)	N/A

Pie Charts - Vertical Legend (Right Side)

{
  "showlegend": true,
  "legend": {
    "orientation": "v",
    "yanchor": "middle",
    "y": 0.5,
    "xanchor": "left",
    "x": 1.02,
    "font": {"size": 12}
  },
  "margin": {"t": 80, "b": 80, "l": 80, "r": 150}
}

Bar/Line Charts - Horizontal Legend (Top)

{
  "showlegend": true,
  "legend": {
    "orientation": "h",
    "yanchor": "bottom",
    "y": 1.05,
    "xanchor": "center",
    "x": 0.5,
    "font": {"size": 12}
  },
  "margin": {"t": 120, "b": 80, "l": 80, "r": 80}
}

---

Text and Number Formatting

Percentage Display

// Option 1: Add % in template
{
  "text": [45.2, 30.1, 24.7],
  "texttemplate": "%{text}%",
  "textposition": "outside",
  "textfont": {"size": 11, "color": "black"}
}

// Option 2: Pre-formatted strings
{
  "text": ["45.2%", "30.1%", "24.7%"],
  "textposition": "outside",
  "textfont": {"size": 11, "color": "black"}
}

Currency Display

// Option 1: Format with template
{
  "text": [1200000, 850000, 650000],
  "texttemplate": "$%{text:,.0f}",
  "textposition": "outside",
  "textfont": {"size": 11, "color": "black"}
}

// Option 2: Pre-formatted strings
{
  "text": ["$1.2M", "$850K", "$650K"],
  "textposition": "outside",
  "textfont": {"size": 11, "color": "black"}
}

Heatmap Numbers (1 Decimal)

{
  "text": [[23.4, 45.6], [34.5, 56.7]],
  "texttemplate": "%{text:.1f}",
  "textfont": {"size": 12, "color": "black"},
  "hovertemplate": "Value: %{z:.1f}<extra></extra>"
}

---

KPI Indicators (ONLY Use Case for Subplots)

KPI indicators are the ONLY exception where subplots are allowed. Use simple number indicators only.

Simple Number Indicators (NO GAUGES)

{
  "data": [
    {
      "type": "indicator",
      "mode": "number+delta",
      "value": 5240,
      "delta": {"reference": 4800, "suffix": " customers"},
      "title": {"text": "Total Customers", "font": {"size": 12, "color": "#2E41A6"}},
      "number": {"font": {"size": 32, "color": "#44BAB8"}},
      "domain": {"x": [0, 0.25], "y": [0, 1]}
    },
    {
      "type": "indicator",
      "mode": "number+delta",
      "value": 42.5,
      "delta": {"reference": 38.2, "suffix": "%"},
      "title": {"text": "Conversion Rate", "font": {"size": 12, "color": "#2E41A6"}},
      "number": {"prefix": "", "suffix": "%", "font": {"size": 32, "color": "#44BAB8"}},
      "domain": {"x": [0.25, 0.5], "y": [0, 1]}
    },
    {
      "type": "indicator",
      "mode": "number+delta",
      "value": 1250000,
      "delta": {"reference": 1100000, "valueformat": "$,.0f"},
      "title": {"text": "Total Revenue", "font": {"size": 12, "color": "#2E41A6"}},
      "number": {"prefix": "$", "valueformat": ",.0f", "font": {"size": 32, "color": "#44BAB8"}},
      "domain": {"x": [0.5, 0.75], "y": [0, 1]}
    },
    {
      "type": "indicator",
      "mode": "number+delta",
      "value": 25.3,
      "delta": {"reference": 22.1, "suffix": "%"},
      "title": {"text": "Champions %", "font": {"size": 12, "color": "#2E41A6"}},
      "number": {"suffix": "%", "font": {"size": 32, "color": "#44BAB8"}},
      "domain": {"x": [0.75, 1], "y": [0, 1]}
    }
  ],
  "layout": {
    "height": 150,
    "margin": {"t": 20, "b": 20, "l": 20, "r": 20},
    "paper_bgcolor": "white"
  }
}

Key Points for KPI Indicators:

• Maximum 4 indicators per row
• Number + Delta ONLY - no gauges, no fancy visuals
• Large number (32pt), clear title (12pt)
• Show change vs. previous period
• Clean, minimal design
• Use domains to position: [0, 0.25], [0.25, 0.5], [0.5, 0.75], [0.75, 1]

---

Quality Checklist

Before generating any visualization, verify:

Required for Every Chart

• Descriptive title with proper positioning ("x": 0.5)
• Clear axis labels with appropriate font size ("font": {"size": 14})
• TD color palette used consistently
• Proper height (500-600px based on chart type)
• Adequate margins (minimum 80px, more for legends)
• White background ("plot_bgcolor": "white", "paper_bgcolor": "white")
• Readable font size (12px minimum)
• Legends visible for multi-category/multi-series charts
• Numbers displayed on bars/heatmaps with proper formatting

Legend Requirements

• "showlegend": true for pie charts and comparisons
• Proper orientation (vertical for pie, horizontal for others)
• Adequate margin space for legend display
• Readable font size for legend items
• Legend positioned visibly (y > 1.0 for horizontal)

Text Display Requirements

• Values shown on bars with "text" and "textposition"
• Heatmap values formatted to 1 decimal place
• Hover templates with meaningful information
• Consistent text formatting across similar chart types
• Black text for visibility ("textfont": {"color": "black"})

---

Forbidden Patterns

❌ NEVER DO

1. Subplots for analysis (yaxis2, xaxis2, domain specifications)
   • Exception: KPI indicators only
2. String data format ("data": "[...]")
3. Missing legends on pie charts or comparisons
4. Legend positioned below visible area (e.g., "y": -0.3)
5. Missing "text" property on bar charts - numbers won't show
6. Missing "textposition" on bar charts - numbers won't be positioned
7. Missing "texttemplate" on heatmaps - numbers won't be formatted
8. Missing "showscale" on heatmaps - color scale won't appear
9. Insufficient top margin for legends ("t": 80 insufficient, use "t": 120)
10. Unformatted numbers in heatmaps
11. Empty or generic titles
12. Non-TD colors
13. Gauges in KPI indicators - use number+delta only

✅ ALWAYS DO

1. Individual separate charts for analysis
2. JSON array data format (proper objects, not strings)
3. Visible legends: "y": 1.05 for horizontal, adequate margins
4. Numbers on bars: "text": [...], "textposition": "outside"
5. Numbers on heatmaps: "text": [...], "texttemplate": "%{text:.1f}"
6. Adequate margins: "t": 120 minimum for legends
7. Formatted numbers with appropriate decimals
8. Descriptive titles and axis labels
9. TD color palette consistently
10. Black text color for visibility: "textfont": {"color": "black"}
11. Simple KPI indicators - number + delta only

---

Complete Examples

Example 1: Customer Segment Distribution (Pie Chart)

{
  "data": [{
    "type": "pie",
    "values": [1250, 2100, 1500, 390],
    "labels": ["Champions", "Loyal Customers", "At Risk", "Lost"],
    "marker": {
      "colors": ["#44BAB8", "#8FD6D4", "#EEB53A", "#828DCA"]
    },
    "textinfo": "label+percent",
    "textposition": "auto",
    "textfont": {"size": 14, "color": "black"},
    "hovertemplate": "<b>%{label}</b><br>Customers: %{value}<br>Percentage: %{percent}<extra></extra>"
  }],
  "layout": {
    "title": {
      "text": "Customer Segment Distribution",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "showlegend": true,
    "legend": {
      "orientation": "v",
      "yanchor": "middle",
      "y": 0.5,
      "xanchor": "left",
      "x": 1.02,
      "font": {"size": 12}
    },
    "margin": {"t": 80, "b": 80, "l": 80, "r": 150},
    "font": {"family": "Arial", "size": 12},
    "paper_bgcolor": "white"
  }
}

Example 2: Revenue by Channel (Multi-Series Bar)

{
  "data": [
    {
      "type": "bar",
      "x": ["Email", "Social", "Search", "Display"],
      "y": [125000, 98000, 156000, 67000],
      "name": "Q3 2024",
      "marker": {"color": "#44BAB8"},
      "text": ["$125K", "$98K", "$156K", "$67K"],
      "textposition": "outside",
      "textfont": {"size": 11, "color": "black"}
    },
    {
      "type": "bar",
      "x": ["Email", "Social", "Search", "Display"],
      "y": [142000, 115000, 178000, 73000],
      "name": "Q4 2024",
      "marker": {"color": "#8FD6D4"},
      "text": ["$142K", "$115K", "$178K", "$73K"],
      "textposition": "outside",
      "textfont": {"size": 11, "color": "black"}
    }
  ],
  "layout": {
    "title": {
      "text": "Revenue by Marketing Channel",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "barmode": "group",
    "showlegend": true,
    "legend": {
      "orientation": "h",
      "yanchor": "bottom",
      "y": 1.05,
      "xanchor": "center",
      "x": 0.5,
      "font": {"size": 12}
    },
    "xaxis": {
      "title": {"text": "Marketing Channels", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "yaxis": {
      "title": {"text": "Revenue ($)", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "margin": {"t": 120, "b": 80, "l": 80, "r": 80},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

Example 3: Performance Heatmap

{
  "data": [{
    "type": "heatmap",
    "x": ["Week 1", "Week 2", "Week 3", "Week 4"],
    "y": ["Email", "Social", "Search", "Display"],
    "z": [
      [85.3, 92.1, 88.7, 94.2],
      [72.5, 78.3, 81.2, 76.8],
      [91.4, 89.6, 93.8, 95.1],
      [68.2, 71.5, 69.9, 73.4]
    ],
    "colorscale": [
      [0, "#DAF1F1"],
      [0.5, "#8FD6D4"],
      [1, "#44BAB8"]
    ],
    "showscale": true,
    "colorbar": {
      "title": {"text": "Performance %", "font": {"size": 12}},
      "titleside": "right"
    },
    "text": [
      [85.3, 92.1, 88.7, 94.2],
      [72.5, 78.3, 81.2, 76.8],
      [91.4, 89.6, 93.8, 95.1],
      [68.2, 71.5, 69.9, 73.4]
    ],
    "texttemplate": "%{text:.1f}",
    "textfont": {"size": 12, "color": "black"},
    "hovertemplate": "<b>%{y}</b> - <b>%{x}</b><br>Performance: %{z:.1f}%<extra></extra>"
  }],
  "layout": {
    "title": {
      "text": "Weekly Channel Performance",
      "x": 0.5,
      "font": {"size": 18, "color": "#2E41A6"}
    },
    "height": 500,
    "xaxis": {
      "title": {"text": "Week", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "yaxis": {
      "title": {"text": "Channel", "font": {"size": 14, "color": "#2E41A6"}}
    },
    "margin": {"t": 80, "b": 80, "l": 100, "r": 100},
    "font": {"family": "Arial", "size": 12},
    "plot_bgcolor": "white",
    "paper_bgcolor": "white"
  }
}

---

Success Criteria

Your visualization is ready when:

✅ Executives can instantly understand the key message ✅ All text is readable at standard screen sizes ✅ Colors are consistent with TD branding ✅ Legends are visible and descriptive (where needed) ✅ Numbers are formatted appropriately ✅ Chart tells a clear story ✅ JSON structure is valid (not stringified) ✅ No subplots for analysis charts ✅ Clean, professional, executive-ready appearance

---

By following these guidelines, your Field Agent visualizations will be professional, consistent, and immediately actionable for decision-makers.