Chart Visualization

Chart Visualization Skill

This skill provides a comprehensive workflow for transforming data into visual charts. It handles chart selection, parameter extraction, and image generation.

Workflow

To visualize data, follow these steps:

1. Normalize the Request Into a Chart Brief

Before choosing any chart, reduce the user's request into a brief with these fields:

{
  "goal": "What decision or comparison the chart should support",
  "audience": "executive | analytical | operational | academic | unknown",
  "data_story": "trend | comparison | composition | distribution | relationship | flow | geography | hierarchy",
  "source_data_state": "explicit data provided | partially described | no data",
  "must_show": ["metrics or categories that must appear"],
  "constraints": ["units, time grain, brand colors, report context, etc."]
}

If any of these are ambiguous enough to affect chart correctness, call ask_clarification before generating.

2. Ground the Data Before Chart Selection

• If the user uploaded CSV/XLSX or described tabular data, use data-analysis first to inspect schema and derive the exact rows/columns for charting.
• If the request contains only prose and no reliable numbers, do not invent plausible values just to make a chart. Ask for the missing data or clearly state that you can only produce a conceptual mock chart.
• Always produce a clean data array before generation. The final chart spec must be reproducible from that array alone.

3. Intelligent Chart Selection

Analyze the grounded data and the chart brief to determine the most appropriate chart type. Use the following guidelines (and consult references/ for detailed specs):

• Time Series: Use generate_line_chart (trends) or generate_area_chart (accumulated trends). Use generate_dual_axes_chart for two different scales.
• Comparisons: Use generate_bar_chart (categorical) or generate_column_chart. Use generate_histogram_chart for frequency distributions.
• Part-to-Whole: Use generate_pie_chart or generate_treemap_chart (hierarchical).
• Relationships & Flow: Use generate_scatter_chart (correlation), generate_sankey_chart (flow), or generate_venn_chart (overlap).
• Maps: Use generate_district_map (regions), generate_pin_map (points), or generate_path_map (routes).
• Hierarchies & Trees: Use generate_organization_chart or generate_mind_map.
• Specialized:
  • generate_radar_chart: Multi-dimensional comparison.
  • generate_funnel_chart: Process stages.
  • generate_liquid_chart: Percentage/Progress.
  • generate_word_cloud_chart: Text frequency.
  • generate_boxplot_chart or generate_violin_chart: Statistical distribution.
  • generate_network_graph: Complex node-edge relationships.
  • generate_fishbone_diagram: Cause-effect analysis.
  • generate_flow_diagram: Process flow.
  • generate_spreadsheet: Tabular data or pivot tables for structured data display and cross-tabulation.

4. Parameter Extraction

Once a chart type is selected, read the corresponding file in the references/ directory (e.g., references/generate_line_chart.md) to identify the required and optional fields. Extract the data from the user's input and map it to the expected args format.

5. Build a Validated Chart Spec

Before running the generator, create a chart spec with this structure:

{
  "tool": "generate_chart_type_name",
  "args": {
    "data": [],
    "title": "",
    "theme": "default",
    "style": {},
    "axisXTitle": "",
    "axisYTitle": ""
  },
  "intent": {
    "data_story": "trend",
    "reason_for_choice": "Line chart fits sequential time-based change.",
    "source_summary": "Derived from monthly revenue totals grouped from Orders table.",
    "validation_notes": [
      "x field is temporal",
      "y field is numeric",
      "title matches metric and grain"
    ]
  }
}

Rules:

• intent.data_story must agree with the selected chart type.
• intent.reason_for_choice must explain why this chart is a better fit than obvious alternatives.
• intent.source_summary must say where the plotted data came from.
• intent.validation_notes must explicitly mention the key field checks you performed.

6. Validate Before Generation

Do not call generate.js until these checks are true:

• The selected chart type matches the requested story.
• Required fields for that chart type exist in every row.
• Numeric fields are actually numeric.
• Axis titles or labels are present for charts that use axes.
• Pie charts use 6 slices or fewer, or you aggregated a remainder bucket.
• Bar/column charts do not imply a misleading truncated scale.
• Titles describe the takeaway or exact metric, not a vague topic label.

If any check fails, revise the spec or ask for clarification instead of generating a wrong chart.

7. Chart Generation

Invoke the scripts/generate.js script with a JSON payload.

Payload Format:

{
  "tool": "generate_chart_type_name",
  "args": {
    "data": [...],
    "title": "...",
    "theme": "...",
    "style": { ... }
  }
}

Execution Command:

node ./scripts/generate.js '<payload_json>'

8. Result Return

The script will output the URL of the generated chart image. Return the following to the user:

• The image URL.
• The complete validated spec used for generation.
• A one-paragraph explanation of why this chart type was chosen.

Reference Material

Detailed specifications for each chart type are located in the references/ directory. Consult these files to ensure the args passed to the script match the expected schema.

Color Palettes & Presets