Skip to content

Commit 5b8f4da

Browse files
author
Saurabh Arora
committed
feat: added a skill for data story telling and visualizations/ data products
1 parent f17eb99 commit 5b8f4da

2 files changed

Lines changed: 1211 additions & 0 deletions

File tree

‎.opencode/skills/ai-dataviz/SKILL.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
name: ai-dataviz
3+
description: >
4+
Build modern, AI-first data visualizations and data storytelling interfaces
5+
using code-based component libraries (shadcn/ui, Recharts, Tremor, Nivo, D3,
6+
Victory, visx) instead of legacy BI tools. Use this skill whenever the user
7+
asks to visualize data, build dashboards, create analytics views, chart
8+
metrics, tell a data story, build a reporting interface, create KPI cards,
9+
plot graphs, or explore a dataset — even if they mention PowerBI, Tableau,
10+
Streamlit, Metabase, Looker, Grafana, or similar tools. Also trigger when the
11+
user says "make a dashboard", "show me the data", "chart this", "visualize
12+
trends", "build an analytics page", "data story", or anything involving
13+
turning raw data into interactive visual interfaces. If the task involves
14+
presenting data visually — this is the skill. Always prefer building a real,
15+
interactive, code-based UI over exporting to or recommending a BI platform.
16+
---
17+
18+
# AI-First Data Visualization
19+
20+
## Table of Contents
21+
22+
1. [Philosophy](#philosophy)
23+
2. [Technology Stack](#technology-stack)
24+
3. [Building a Data Visualization](#building-a-data-visualization)
25+
- [Step 1: Understand the Data Story](#step-1-understand-the-data-story)
26+
- [Step 2: Choose the Right Chart Type](#step-2-choose-the-right-chart-type)
27+
- [Step 3: Build the Interface](#step-3-build-the-interface)
28+
- [Step 4: Apply Design Principles](#step-4-apply-design-principles)
29+
- [Step 5: Add Interactivity & Annotations](#step-5-add-interactivity--annotations)
30+
- [Step 6: Tell the Story](#step-6-tell-the-story)
31+
4. [Environment-Specific Guidance](#environment-specific-guidance)
32+
5. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
33+
6. [Quick Reference](#quick-reference)
34+
35+
---
36+
37+
## Philosophy
38+
39+
AI agents can generate production-quality, interactive data interfaces in
40+
minutes using modern component libraries — more customizable, no vendor lock-in,
41+
embeddable anywhere.
42+
43+
**Default behavior**: When the user hasn't specified a tool, build a code-first
44+
interactive UI using the stack below. Don't ask — just deliver something great.
45+
46+
**When the user explicitly names a tool** (PowerBI, Tableau, Looker, Metabase,
47+
Grafana, Streamlit, etc.) — **use that tool**. They have a reason: org policy,
48+
existing infra, stakeholder requirements. Help them do it well in their chosen
49+
tool. Only suggest the code-first alternative if they ask for options or if
50+
there's a clear technical blocker (e.g., the BI tool can't support what they
51+
need).
52+
53+
---
54+
55+
## Technology Stack
56+
57+
Full library docs: `references/component-guide.md`
58+
59+
### Framework Priority
60+
61+
1. **React + Tailwind** — Default. Use when the environment supports JSX/TSX.
62+
2. **HTML + CSS + Vanilla JS** — Fallback without React. Use D3 or Chart.js.
63+
3. **Python (Plotly/Dash)** — Only for Python-only environments (Jupyter, scripts).
64+
65+
### Component Libraries
66+
67+
| Library | Best For | When to Use |
68+
|---------|----------|-------------|
69+
| **shadcn/ui charts** | General dashboards, most chart types | Default first choice |
70+
| **Recharts** | Line, bar, area, composed, radar charts | Fine-grained control |
71+
| **Tremor** | KPI cards, metric displays, full layouts | Complete analytics dashboards |
72+
| **Nivo** | Heatmaps, treemaps, choropleth, calendar, Sankey | Advanced / exotic types |
73+
| **visx** | Bespoke custom visualizations | D3-level control with React |
74+
| **D3.js** | Force-directed graphs, DAGs, maps | Maximum flexibility |
75+
| **Victory** | Animated charts | When animation quality matters most |
76+
77+
**Supporting**: Tailwind CSS · Radix UI · Framer Motion · Lucide React · date-fns · Papaparse · lodash
78+
79+
---
80+
81+
## Building a Data Visualization
82+
83+
### Step 1: Understand the Data Story
84+
85+
Before writing any code, identify:
86+
87+
- **What question does the data answer?** ("How are costs trending?", "Where do users drop off?")
88+
- **Who is the audience?** Executive → KPIs only. Analyst → drill-down + filters. Public → narrative flow.
89+
- **What's the key insight?** Every great viz has ONE takeaway. Design around it.
90+
91+
### Step 2: Choose the Right Chart Type
92+
93+
| Data Relationship | Chart Type | Library |
94+
|-------------------|-----------|---------|
95+
| Trend over time | Line chart, Area chart | shadcn/Recharts |
96+
| Comparison across categories | Bar chart (horizontal for many) | shadcn/Recharts |
97+
| Part of a whole | Donut, Treemap | shadcn/Nivo |
98+
| Distribution | Histogram, Box plot, Violin | Nivo/visx |
99+
| Correlation | Scatter, Bubble chart | Recharts/visx |
100+
| Geographic | Choropleth, Dot map | Nivo/D3 |
101+
| Hierarchical | Treemap, Sunburst | Nivo |
102+
| Flow / Process | Sankey, Funnel | Nivo/D3 |
103+
| Single KPI | Metric card, Gauge, Sparkline | Tremor/shadcn |
104+
| Multi-metric overview | Dashboard grid of cards | Tremor + shadcn |
105+
| Ranking | Horizontal bar, Bar list | Tremor |
106+
| Status / Progress | Tracker, Progress bar | Tremor |
107+
| **Column / model lineage** | **Force-directed DAG** | **D3** |
108+
| **Pipeline dependencies** | **Hierarchical tree, DAG** | **D3 / Nivo** |
109+
| **Multi-dimensional quality** | **Radar / Spider chart** | **Recharts** |
110+
| **Activity density over time** | **Calendar heatmap** | **Nivo** |
111+
| **Incremental change breakdown** | **Waterfall chart** | **Recharts (custom)** |
112+
| **Ranking shift over time** | **Bump chart** | **Recharts (custom)** |
113+
114+
### Step 3: Build the Interface
115+
116+
Start from this layout and remove what the data doesn't need:
117+
118+
```
119+
┌─────────────────────────────────────────────────┐
120+
│ Header: Title + Description + Date Range │
121+
├─────────────────────────────────────────────────┤
122+
│ KPI Row: 3-5 metric cards with sparklines │
123+
├─────────────────────────────────────────────────┤
124+
│ Primary Visualization (largest chart) │
125+
├────────────────────┬────────────────────────────┤
126+
│ Secondary Chart │ Supporting Chart / Table │
127+
├────────────────────┴────────────────────────────┤
128+
│ Detail Table (sortable, filterable) │
129+
└─────────────────────────────────────────────────┘
130+
```
131+
132+
A single insight might just be one chart with a headline and annotation.
133+
Scale complexity to match the data and audience.
134+
135+
### Step 4: Apply Design Principles
136+
137+
- **Data-ink ratio**: Remove chartjunk — unnecessary gridlines, redundant labels, decorative borders.
138+
- **Color with purpose**: Encode meaning (red = bad, green = good, blue = neutral). Max 5–7 colors. Single-hue gradient for sequential data.
139+
- **Typography hierarchy**: Title → subtitle (muted) → axis labels (small) → data labels.
140+
- **Responsive**: `min-h-[VALUE]` on all charts. Grid stacks on mobile. Test at 375/768/1280px.
141+
- **Whitespace**: Give charts room. A padded dashboard reads better than a dense wall.
142+
- **Animation**: Entry transitions only. `duration-300` to `duration-500`. Never continuous.
143+
- **Accessibility**: `aria-label` on charts, WCAG AA contrast, don't rely on color alone.
144+
145+
### Step 5: Add Interactivity & Annotations
146+
147+
**Interactivity priority order:**
148+
1. Tooltips — exact values on hover (every chart)
149+
2. Filtering — date range, category, segment
150+
3. Sorting — click column headers in tables
151+
4. Drill-down — click bar/slice to reveal detail
152+
5. Cross-filtering — selection in one chart filters others
153+
6. Export — CSV download of underlying data
154+
7. Annotations — callouts that turn a chart into a story
155+
156+
**Annotations** are the most underused technique in data storytelling. Every
157+
chart with a clear insight should have at least one. Use them to mark:
158+
- Inflection points and trend reversals
159+
- Threshold crossings and goal lines (amber)
160+
- External events: releases, incidents, campaigns (indigo / red)
161+
- Anomalies that demand explanation (red)
162+
- Achievements against target (green)
163+
164+
Limit to **3 annotations per chart** — more and none stand out. Never overlap
165+
data. Implementation patterns: `references/component-guide.md` → Annotation Patterns.
166+
167+
### Step 6: Tell the Story
168+
169+
- **Headline states the insight**: "Revenue grew 23% QoQ, driven by enterprise deals" — not "Q3 Revenue Chart"
170+
- **Annotate key moments**: Mark inflection points, anomalies, goal lines directly on the chart
171+
- **Contextual comparisons**: vs. prior period, vs. target, vs. benchmark
172+
- **Progressive disclosure**: Overview first — detail on demand. Don't front-load complexity.
173+
174+
---
175+
176+
## Environment-Specific Guidance
177+
178+
| Environment | Approach |
179+
|-------------|----------|
180+
| **Claude Artifacts** | React (JSX), single file, default export. Available: `recharts`, `lodash`, `d3`, `lucide-react`, shadcn via `@/components/ui/*`, Tailwind. |
181+
| **Claude Code / Terminal** | Full project: Vite + React + Tailwind. Add shadcn/ui + Recharts. Structure: `src/components/charts/`, `src/components/cards/`, `src/data/`. |
182+
| **Python / Jupyter** | Plotly for charts, Plotly Dash for dashboards. Same design principles apply. |
183+
| **Cursor / Bolt / other IDEs** | Match existing framework. Include install commands. Prefer shadcn/ui if already present, Tremor for dashboard-heavy apps. |
184+
185+
---
186+
187+
## Anti-Patterns to Avoid
188+
189+
- **Screenshot charts** — build interactive components, never static images
190+
- **Defaulting to BI tools unprompted** — when no tool is specified, build code-first; don't suggest "just use Tableau" as a lazy out
191+
- **Default matplotlib** — always customize if forced into Python
192+
- **Rainbow palettes** — use deliberate, meaningful colors
193+
- **3D charts** — almost never appropriate
194+
- **Pie charts > 5 slices** — use horizontal bar instead
195+
- **Unlabeled dual y-axes** — use two separate charts instead
196+
- **Truncated bar axes** — always start at zero
197+
- **Chartjunk** — no gratuitous gradients, shadows, or decoration
198+
199+
---
200+
201+
## Quick Reference
202+
203+
| Pattern | Implementation |
204+
|---------|---------------|
205+
| KPI card + sparkline | Tremor `Card` + `SparkAreaChart` or shadcn `Card` + axisless Recharts `AreaChart` |
206+
| Time series | shadcn `ChartContainer` + Recharts `LineChart`. Add date picker, granularity toggle, prior-period dashed overlay. |
207+
| Categorical comparison | Recharts `BarChart`. Horizontal bars for 10+ categories. Sort toggle + threshold line. |
208+
| Funnel | Nivo `Funnel`. Show step labels, conversion %, drop-off highlight. |
209+
| Geographic | Nivo `Choropleth` + GeoJSON. Color legend + hover tooltip. |
210+
| Table with inline visuals | Tremor/shadcn `Table` with embedded sparklines, progress bars, badges. Sortable + searchable. |
211+
| Force-directed DAG | D3 force simulation + React SVG. Rectangles nodes, directed edges, arrowheads, drag. Color by node type. |
212+
| Radar / spider | Recharts `RadarChart`. Current vs. benchmark (dashed). `domain={[0,100]}` for consistent axes. |
213+
| Calendar heatmap | Nivo `ResponsiveCalendar`. Single-hue sequential palette. Wrap in fixed-height div. |
214+
| Waterfall | Recharts `ComposedChart` with invisible spacer `Bar` + colored value `Bar`. Green = positive, red = negative. |
215+
| Annotations | Recharts `ReferenceLine` (goal/event), `ReferenceArea` (time window), custom dot renderer (anomalies). |
216+
217+
Full implementations: `references/component-guide.md`

0 commit comments

Comments
 (0)