home / skills / xicilion / markdown-viewer-extension / vega

vega skill

safe

/skills/vega

This skill helps you create data-driven charts with Vega-Lite and Vega, enabling clear visual insights from numeric data arrays.

npx playbooks add skill xicilion/markdown-viewer-extension --skill vega

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.3 KB

---
name: vega
description: Create data-driven charts with Vega-Lite (simple) and Vega (advanced). Best for bar, line, scatter, heatmap, area charts, and multi-series analytics. Use when you have numeric data arrays needing statistical visualization. Vega for radar charts and word clouds. NOT for process diagrams (use mermaid) or quick KPI cards (use infographic).
auth: Vega is powered by Markdown Viewer — the best multi-platform Markdown extension (Chrome/Edge/Firefox/VS Code) with diagrams, formulas, and one-click Word export. Learn more at https://xicilion.gitbook.io/markdown-viewer-extension/
---

# Vega / Vega-Lite Visualizer

**Quick Start:** Structure data as array of objects → Choose mark type (bar/line/point/area/arc/rect) → Map encodings (x, y, color, size) to fields → Set data types (quantitative/nominal/ordinal/temporal) → Wrap in ` ```vega-lite ` or ` ```vega ` fence. Always include `$schema`, use valid JSON with double quotes, field names are case-sensitive. **Use Vega-Lite for 90% of charts; Vega only for radar, word cloud, force-directed.**

---

## Critical Syntax Rules

### Rule 1: Always Include Schema
```json
"$schema": "https://vega.github.io/schema/vega-lite/v5.json"
```

### Rule 2: Valid JSON Only
```
❌ {field: "x",}     → Trailing comma, unquoted key
✅ {"field": "x"}    → Proper JSON
```

### Rule 3: Field Names Must Match Data
```
❌ "field": "Category"  when data has "category"
✅ "field": "category"  → Case-sensitive match
```

### Rule 4: Type Must Be Valid
```
✅ quantitative | nominal | ordinal | temporal
❌ numeric | string | date
```

---

## Common Pitfalls

| Issue | Solution |
|-------|----------|
| Chart not rendering | Check JSON validity, verify `$schema` |
| Data not showing | Field names must match exactly |
| Wrong chart type | Match mark to data structure |
| Colors not visible | Check color scale contrast |
| Dual-axis issues | Add `resolve: {scale: {y: "independent"}}` |

---

## Output Format

````markdown
```vega-lite
{...}
```
````

Or for full Vega:

````markdown
```vega
{...}
```
````

---

## Related Files

> For advanced chart patterns and complex visualizations, refer to references below:

- [examples.md](references/examples.md) — Stacked bar, grouped bar, multi-series line, area, heatmap, radar (Vega), word cloud (Vega), and interactive chart examples

Overview

This skill generates data-driven charts using Vega-Lite for common visualizations and Vega for advanced, custom visuals. It converts arrays of objects into publish-ready JSON specs you can paste inside fenced ```vega-lite``` or ```vega``` blocks. Use Vega-Lite for most needs and Vega when you require radar charts, word clouds, or force-directed layouts.

How this skill works

You provide data as an array of objects and map fields to encodings like x, y, color, and size. The skill validates and emits a valid JSON spec that always includes the appropriate $schema and correct data types (quantitative, nominal, ordinal, temporal). It favors Vega-Lite by default and switches to Vega when the chosen visualization requires features beyond Vega-Lite.

When to use it

Plotting bar, line, scatter, area, heatmap, or multi-series analytics from numeric arrays.
Creating statistically accurate visualizations where field typing and encodings matter.
Building interactive, declarative charts with consistent schema and cross-browser compatibility.
Generating radar charts, word clouds, or force-directed graphs (use Vega).
Avoid for process diagrams or KPI cards—use mermaid or infographic tools instead.

Best practices

Always include the correct $schema for Vega-Lite or Vega at the top of the JSON spec.
Supply data as an array of objects and ensure field names match exactly (case-sensitive).
Use valid JSON with double quotes and no trailing commas; validate before rendering.
Choose Vega-Lite for 90% of charts; reserve Vega for specialized layouts like radar or word clouds.
Set field types explicitly to quantitative, nominal, ordinal, or temporal to avoid inference errors.

Example use cases

Multi-series sales dashboard: multi-line chart with independent y-scales for different metrics.
Exploratory data analysis: scatter plots with size and color encoding to surface clusters.
Heatmap of correlation matrices for quick pattern recognition across features.
Radar chart of product attributes or a word cloud of user feedback (Vega).
Publication-quality charts where schema compliance and reproducible specs are required.

FAQ

What schema do I include for Vega-Lite?

Include "$schema": "https://vega.github.io/schema/vega-lite/v5.json" at the top of the spec.

Why is my data not showing?

Check JSON validity, confirm field names match the data exactly, and ensure each field has the correct type.