chart-builder

What this skill does

# Chart Builder

## Overview
This skill provides a systematic approach to data visualization—from choosing the right chart type for your data and message, to implementing it in Python (matplotlib/seaborn) or JavaScript (Chart.js). It covers chart anatomy, color principles, accessibility requirements, and common pitfalls, so every chart communicates its insight clearly and honestly.

## When to Use
- You need to communicate a data insight visually
- You're unsure which chart type fits your data shape and message
- You need reproducible chart code in Python or JavaScript
- You want to improve a chart that isn't communicating clearly
- You're building a report, slide deck, or embedded visualization

## When NOT to Use
- Building a full interactive BI dashboard (use dashboard-designer skill)
- Designing data art or infographics for marketing
- Creating maps or geospatial visualizations (use a GIS tool)
- Animating data for video production

## Quick Reference
| Chart Type | Best For | Avoid When |
|------------|----------|------------|
| Bar (vertical) | Comparing categories, rankings | Too many categories (>12) |
| Bar (horizontal) | Long category labels, rankings | Showing trends over time |
| Line | Trends over time, continuous data | Categorical/unordered x-axis |
| Scatter | Correlation between two variables | Fewer than ~20 data points |
| Pie / Donut | Part-of-whole (max 5 slices) | Comparing many segments |
| Heatmap | Matrix of values, correlation tables | Audiences unfamiliar with the format |
| Box plot | Distribution comparison across groups | Presenting to non-technical audience |
| Histogram | Distribution of a single variable | Showing trends or comparisons |
| Area | Cumulative totals over time | Multiple overlapping series |
| Stacked bar | Part-of-whole across categories | Comparing absolute values |

## Instructions

### Step 1: Choose the Right Chart Type
Answer these questions:
1. **How many variables?** 1 (distribution) → histogram/box. 2 (relationship) → scatter/line. 2+ (comparison) → bar/heatmap.
2. **What's the x-axis?** Time → line/area. Categories → bar. Continuous numeric → scatter.
3. **What's the message?** Trend → line. Ranking → bar. Proportion → pie (≤5 slices). Correlation → scatter.

### Step 2: Chart Anatomy — Label Everything
A complete chart has:
- **Title**: one-sentence insight, not just the topic ("West Region Revenue Up 34% in Q3", not "Revenue by Region")
- **Axis labels** with units (e.g., "Revenue (USD thousands)")
- **Legend** (if multiple series)
- **Data source** in a footer note
- **Gridlines**: horizontal only, light grey, behind data

### Step 3: Color Principles
- Use **2–4 colors maximum** for categorical data
- Use a **sequential palette** (light→dark) for ordered/quantitative data
- Use **diverging palette** (blue→white→red) for data with a meaningful midpoint (e.g., % change, NPS)
- **Never use red/green alone**—colorblind users cannot distinguish them; add pattern or shape
- Highlight the most important series in a strong color; grey out everything else

### Step 4: Accessibility Checklist
- Minimum contrast ratio 4.5:1 for text against background
- Add alt text describing the chart's key finding
- Don't rely on color alone to encode information (add labels, patterns)
- Font size minimum 12pt for axis labels, 14pt for titles
- Provide a data table below the chart for screen readers

### Step 5: Python Implementation (matplotlib / seaborn)

**Bar chart:**
```python
import matplotlib.pyplot as plt
import seaborn as sns
import pandas as pd

df = pd.DataFrame({
    'Region': ['West', 'East', 'North', 'South'],
    'Revenue': [4200, 3100, 1800, 2700]
})

fig, ax = plt.subplots(figsize=(8, 5))
bars = ax.bar(df['Region'], df['Revenue'], color=['#2563EB', '#64748B', '#64748B', '#64748B'])
ax.set_title("West Region Leads Q3 Revenue", fontsize=16, fontweight='bold', pad=12)
ax.set_xlabel("Region", fontsize=12)
ax.set_ylabel("Revenue (USD thousands)", fontsize=12)
ax.yaxis.grid(True, color='#E5E7EB', linewidth=0.8)
ax.set_axisbelow(True)
ax.spines[['top', 'right']].set_visible(False)

# Value labels on bars
for bar in bars:
    ax.text(bar.get_x() + bar.get_width()/2, bar.get_height() + 50,
            f"${bar.get_height():,.0f}K", ha='center', va='bottom', fontsize=11)

plt.tight_layout()
plt.savefig("revenue_by_region.png", dpi=150, bbox_inches='tight')
plt.show()
```

**Line chart (trend):**
```python
import matplotlib.pyplot as plt
import pandas as pd

df = pd.DataFrame({
    'Month': ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    'Revenue': [180, 210, 195, 240, 285, 310]
})

fig, ax = plt.subplots(figsize=(9, 5))
ax.plot(df['Month'], df['Revenue'], color='#2563EB', linewidth=2.5, marker='o', markersize=7)
ax.fill_between(range(len(df)), df['Revenue'], alpha=0.08, color='#2563EB')
ax.set_title("Revenue Growing Steadily — Up 72% H1", fontsize=16, fontweight='bold')
ax.set_ylabel("Revenue (USD thousands)", fontsize=12)
ax.yaxis.grid(True, color='#E5E7EB', linewidth=0.8)
ax.set_axisbelow(True)
ax.spines[['top', 'right']].set_visible(False)
plt.tight_layout()
plt.savefig("revenue_trend.png", dpi=150, bbox_inches='tight')
```

**Scatter plot (correlation):**
```python
import seaborn as sns
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(8, 6))
sns.regplot(data=df, x='marketing_spend', y='revenue', ax=ax,
            scatter_kws={'alpha': 0.6, 'color': '#2563EB'},
            line_kws={'color': '#DC2626', 'linewidth': 1.5})
ax.set_title("Marketing Spend Strongly Correlates with Revenue (r=0.78)", fontsize=14, fontweight='bold')
ax.set_xlabel("Marketing Spend (USD)", fontsize=12)
ax.set_ylabel("Revenue (USD)", fontsize=12)
ax.spines[['top', 'right']].set_visible(False)
plt.tight_layout()
```

**Heatmap (correlation matrix):**
```python
import seaborn as sns
import matplotlib.pyplot as plt

corr = df[['revenue', 'units_sold', 'discount_pct', 'marketing_spend']].corr()
fig, ax = plt.subplots(figsize=(7, 6))
sns.heatmap(corr, annot=True, fmt=".2f", cmap='RdBu_r', center=0,
            vmin=-1, vmax=1, square=True, linewidths=0.5, ax=ax)
ax.set_title("Correlation Matrix — Sales Variables", fontsize=14, fontweight='bold')
plt.tight_layout()
```

### Step 6: JavaScript Implementation (Chart.js)

**Bar chart:**
```html
<canvas id="revenueChart" width="600" height="400"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
const ctx = document.getElementById('revenueChart').getContext('2d');
new Chart(ctx, {
  type: 'bar',
  data: {
    labels: ['West', 'East', 'North', 'South'],
    datasets: [{
      label: 'Revenue (USD K)',
      data: [4200, 3100, 1800, 2700],
      backgroundColor: ['#2563EB', '#64748B', '#64748B', '#64748B'],
      borderRadius: 4,
    }]
  },
  options: {
    responsive: true,
    plugins: {
      title: { display: true, text: 'West Region Leads Q3 Revenue', font: { size: 16 } },
      legend: { display: false }
    },
    scales: {
      y: { grid: { color: '#E5E7EB' }, ticks: { callback: v => `$${v}K` } },
      x: { grid: { display: false } }
    }
  }
});
</script>
```

**Line chart (multi-series):**
```javascript
new Chart(ctx, {
  type: 'line',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    datasets: [
      {
        label: 'Revenue',
        data: [180, 210, 195, 240, 285, 310],
        borderColor: '#2563EB',
        backgroundColor: 'rgba(37,99,235,0.08)',
        fill: true,
        tension: 0.3,
        pointRadius: 5
      },
      {
        label: 'Target',
        data: [200, 220, 220, 250, 270, 300],
        borderColor: '#DC2626',
        borderDash: [6, 3],
        fill: false,
        pointRadius: 0
      }
    ]
  },
  options: {
    plugins: { title: { display: true, text: 'Revenue vs Target — H1 2024' } },
    scales: { y: { grid: { color: '#E5E7EB' } } }
  }
});
```

## Examples

### Example 1: Build a Sales Trend Line Chart
**Input:** "I have monthly revenue data for 2023 and want to show the growth t