agent-skills/minimax-xlsx/charts.md

---
name: charts
description: "Chart creation and verification guide for the minimax-xlsx skill. Read this document when the task requires embedded Excel charts or data visualizations."
---

**Path note**: Relative paths in this document (e.g., `./scripts/`) are anchored to the skill directory that contains this file.

<embedded_objects>

## Charts Must Be Real Embedded Objects

**Proactive stance on visualization:**
- If the user asks for charts or visuals, generate them immediately — don't wait for per-dataset instructions
- When a workbook has multiple data tables, each table should have at least one chart unless the user says otherwise
- If any dataset lacks a chart, explain why and confirm before shipping

**What you must NOT do:**
- Output a helper-only "chart dataset" tab and ask the user to insert charts manually
- Mark chart work complete while expecting end users to finish chart insertion
- Mark "Add visual charts" as completed without embedding actual chart objects

**What you must do:**
- Build embedded charts inside the .xlsx via openpyxl by default
- Standalone image exports (PNG/JPG) only when explicitly requested

</embedded_objects>

<creation_sequence>

**Mandatory sequence:**
```
1. Construct the workbook with openpyxl (data, styling)
2. Insert charts using openpyxl.chart classes
3. Save the file
4. Run chart to confirm charts have data and detect overlaps
5. If exit code is 1 → fix empty/malformed charts
6. If overlaps reported → reposition charts (see overlap fixing below)
```

</creation_sequence>

<code_samples>

**Imports:**
```python
from openpyxl import Workbook
from openpyxl.chart import BarChart, LineChart, PieChart, Reference
from openpyxl.chart.label import DataLabelList
```

**Bar chart walkthrough:**
```python
from openpyxl import Workbook
from openpyxl.chart import BarChart, Reference

wb = Workbook()
ws = wb.active

rows = [
    ['Region', 'Revenue'],
    ['East', 480],
    ['West', 320],
    ['North', 560],
    ['South', 410],
]
for r in rows:
    ws.append(r)

ch = BarChart()
ch.type = "col"
ch.style = 10
ch.title = "Revenue by Region"
ch.y_axis.title = 'Revenue'
ch.x_axis.title = 'Region'

vals = Reference(ws, min_col=2, min_row=1, max_row=5)
cats = Reference(ws, min_col=1, min_row=2, max_row=5)

ch.add_data(vals, titles_from_data=True)
ch.set_categories(cats)
ch.shape = 4

ws.add_chart(ch, "E2")

wb.save('output.xlsx')
```

### Chart Type Selection

| Data Pattern | Chart Class | Key Config |
|---|---|---|
| Vertical comparison | `BarChart()` | `type="col"` (vertical) or `type="bar"` (horizontal) |
| Temporal trend | `LineChart()` | `style=10`, optional markers |
| Proportional split | `PieChart()` | No axes needed |
| Cumulative spread | `AreaChart()` | `grouping="standard"` |

### Line Chart Sample
```python
from openpyxl.chart import LineChart, Reference

ch = LineChart()
ch.title = "Trend Analysis"
ch.style = 13
ch.y_axis.title = 'Value'
ch.x_axis.title = 'Month'

vals = Reference(ws, min_col=2, min_row=1, max_row=13, max_col=3)
ch.add_data(vals, titles_from_data=True)
cats = Reference(ws, min_col=1, min_row=2, max_row=13)
ch.set_categories(cats)

ws.add_chart(ch, "E2")
```

### Pie Chart Sample
```python
from openpyxl.chart import PieChart, Reference

pie = PieChart()
pie.title = "Market Share"

vals = Reference(ws, min_col=2, min_row=1, max_row=5)
labels = Reference(ws, min_col=1, min_row=2, max_row=5)

pie.add_data(vals, titles_from_data=True)
pie.set_categories(labels)

ws.add_chart(pie, "E2")
```

</code_samples>

<post_check>

**Post-generation check (non-negotiable):**
```bash
./scripts/MiniMaxXlsx chart output.xlsx -v
```
Exit code 1 means broken charts — they must be fixed. No rationalizations — if chart fails, the chart IS defective regardless of how data was embedded.

</post_check>

<collision_handling>

### Overlap Detection and Resolution

`chart` automatically detects chart collisions on each sheet. When overlaps are reported, reposition charts before delivery.

**Overlap report fields**: `ChartA`, `ChartB`, `SheetName`, `RangeA`, `RangeB`, `OverlapRegion`, `OverlapPercentage`

**Repositioning guidelines:**
- **Vertical stacking** (preferred): Place charts below each other with **2 empty rows** between
- **Side-by-side**: When sheet width allows, place horizontally with **1 empty column** gap
- **Consistent sizing**: Keep charts on the same sheet at uniform dimensions (default: 10 columns wide x 15 rows tall)
- Use position data from `-v` output to calculate non-overlapping anchors

**Overlap fix example:**
```python
# chart reported: chart1 at E2:N17, chart2 at E15:N30 (overlap at E15:N17)
# Fix: stack vertically with 2-row gap
from openpyxl import load_workbook

wb = load_workbook('output.xlsx')
ws = wb['SheetName']

for i, chart in enumerate(ws._charts):
    chart.anchor = f'E{2 + i * 17}'  # 15 rows height + 2 rows gap

wb.save('output.xlsx')
```

After repositioning, re-run `chart -v` to confirm zero overlaps.

**Theme-appropriate chart colors:**
- Grayscale: `2C2C2C`, `6B6B6B`, `1565C0`, `5B8DB8`
- Financial: `1B3A5C`, `2A6496`, `5B9BD5`, `8FBCD8`

**Chart type decision guide:**
| Data Scenario | Chart | Use Case |
|---|---|---|
| Temporal progression | Line | Time series |
| Category comparison | Column/Bar | Side-by-side metrics |
| Part-of-whole | Pie/Doughnut | Percentages (6 items max) |
| Data spread | Histogram | Distribution shape |
| Variable relationships | Scatter | Correlation analysis |

</collision_handling>