chart-visualization

name	chart-visualization
description	Use this skill whenever the user wants a chart, graph, plot, dashboard visual, or asks to visualize structured numbers, trends, comparisons, proportions, distributions, correlations, rankings, or flows. This skill must also trigger when the user describes a reporting need in natural language without explicitly saying "chart". It converts the request into a validated chart specification, checks that the chosen chart type actually matches the data story, and only then generates the visual.
dependency	{"nodejs":">=18.0.0"}

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

Professional Color Palettes

Read references/color_palettes.json for 12 pre-built professional palettes. Select a palette that matches the audience and context:

• business-blue: Corporate reports, dashboards
• tech-vibrant: SaaS products, startup pitches
• medical-clinical: Healthcare, clinical data
• nature-earth: Sustainability, environmental data
• accessible-high-contrast: Public-facing, accessibility-critical
• categorical-distinct: Multi-series comparisons (colorblind-safe)
• dark-mode: Dark dashboards, monitoring

Usage: Pass the palette's colors array directly as style.palette in the chart args.

Chart Presets

Read references/chart_presets.json for 5 scenario presets with recommended chart types, styles, and guidelines:

• executive-dashboard: KPI charts for executives
• technical-report: Detailed charts for engineering teams
• marketing-report: Engaging charts for growth metrics
• financial-analysis: Conservative charts for financial data
• dark-dashboard: Dark-themed monitoring charts

Usage: Use the preset's style object as a starting point for your chart configuration.

Quality Standards (Mandatory)

Before Generation — Clarify Requirements

If ANY of the following are unclear, call ask_clarification BEFORE generating:

• What story should the chart tell? (trend, comparison, distribution, composition)
• Who is the audience? (executive summary vs. technical detail)
• Are there brand colors or style preferences?
• What is the output context? (report, dashboard, presentation slide)
• What exact fields or numbers should be plotted?

Chart Design Checklist

Apply these rules when selecting chart type and configuring args:

1. Data integrity: Never truncate Y-axis without explicit justification. Start at 0 for bar/column charts. Never fabricate missing quantitative data.
2. Chart type fit: Time series → line/area. Comparison → bar/column. Part-to-whole → pie (≤6 slices) or treemap. Distribution → histogram/boxplot/violin. Correlation → scatter.
3. Avoid anti-patterns: No 3D charts. No pie charts with >6 slices. No dual Y-axis without clear labeling. No chartjunk (unnecessary gridlines, decorations, borders).
4. Color: Max 5 colors. Use hex codes in style.color. Ensure color-blind safe palette (avoid red-green only encoding).
5. Labels: Add title. Include data labels for key values. Annotate anomalies or inflection points. Axis-based charts must include axis titles unless the meaning is already explicit in the rendered labels.
6. Readability: Font size ≥12pt for labels, ≥16pt for title. Sufficient contrast against background.

After Generation — Self-Review

Before returning the chart to the user, verify:

• Chart type matches the data story (not just "looks nice")
• The plotted fields match the user's requested metric/category/time grain
• All axes are labeled with units
• Color palette is harmonious and accessible
• No misleading visual encoding (area ≠ value distortion)
• Title clearly states the insight, not just the topic

If any check fails, adjust args and regenerate.

License

This SKILL.md is provided by antvis/chart-visualization-skills. Licensed under the MIT License.