viz-craftsman

Files (2)

• SKILL.md
• chart-selector.md · references/

SKILL.md (first lines)

# Viz Craftsman

Create clean, insightful, presentation-ready visualizations.

---

## Workflow

```
1. Understand data and intent
2. Select chart type (references/chart-selector.md)
3. Generate visualization with styling rules
4. Polish and export
```

---

## Step 1 -- Understand Data and Intent

Determine:
- **Data shape**: What columns exist? Types? How many rows?
- **Message**: What insight should the chart convey?
- **Audience**: Technical (detailed) vs. executive (simplified)?
- **Medium**: Notebook, slide deck, report, social media?

If the user just says "plot this" with no specifics, default to the most informative chart for the data type.

---

## Step 2 -- Select Chart Type

Read `references/chart-selector.md` for the decision tree.

Quick reference:

| Data relationship | Chart type |
|---|---|
| Distribution (1 variable) | Histogram, KDE, box plot, violin |
| Comparison (categories) | Bar chart (horizontal for many categories), grouped bar |
| Relationship (2 numeric) | Scatter plot, hexbin for large N |
| Trend over time | Line chart, area chart |
| Composition (parts of whole) | Stacked bar, treemap (NOT pie charts) |
| Correlation matrix | Heatmap with annotated values |
| Geographic | Choropleth, scatter on map |
| Ranking | Horizontal bar, lollipop chart |
| Flow / hierarchy | Sankey, treemap |

---

## Step 3 -- Generate Visualization

### Default Styling Rules (apply to EVERY chart)

```python
import matplotlib.pyplot as plt
import matplotlib as mpl

# Apply to all charts
plt.rcParams.update({
    "figure.figsize": (10, 6),
    "figure.dpi": 150,
    "figure.facecolor": "white",
    "axes.facecolor": "white",
    "axes.spines.top": False,
    "axes.spines.right": False,
    "axes.grid": True,
    "axes.grid.axis": "y",
    "grid.alpha": 0.3,
    "grid.linestyle": "--",
    "font.size": 12,
    "axes.titlesize": 16,
    "axes.titleweight": "bold",
    "axes.labelsize": 13,
})
```

### Color Palettes

| Purpose | Palette | Code |
|---|---|---|
| Categorical (<=6) | Custom muted | `["#4C72B0", "#DD8452", "#55A868", "#C44E52", "#8172B3", "#937860"]` |
| Categorical (>6) | `tab20` | `plt.cm.tab20` |
| Sequential | `viridis` or `Blues` | `cmap="viridis"` |
| Diverging | `RdBu_r` | `cmap="RdBu_r"` |
| Accessible | `colorblind` from seaborn | `sns.color_palette("colorblind")` |

**Default to colorblind-friendly palettes.**

### Must-Have Elements

Every chart MUST include:
1. **Title**: Descriptive, states the insight (not just "Bar Chart of X").
   - Good: "Revenue grew 3x in Q4, driven by enterprise segment"
   - Bad: "Revenue by Quarter"
2. **Axis labels**: With units where applicable.
3. **No clutter**: Remove unnecessary gridlines, borders, legends when obvious.
4. **Data labels**: On bar charts with few bars (<8). On line charts at key inflection points.
5. **Source annotation**: `plt.figtext(0.99, 0.01, "Source: ...", ha="right", fontsize=8, color="gray")` when data source is known.

### Anti-Patterns (NEVER do these)

- Pie charts (use horizontal bar instead).
- 3D charts (distorts perception).
- Dual y-axes (use two panels instead).
- Rainbow color schemes (not accessible).
- Truncated y-axes without clear indication.
- Excessive grid lines or chart junk.

---

## Step 4 -- Polish and Export

### For Notebooks
```python
plt.tight_layout()
plt.show()
```

### For Files

From tezansahu/ai-garage, GPL-3.0.

More from tezansahu/ai-garage