# Interactive Viz

> Builds a tight interactive data story: hunt structure and geo, find many on-page insights, lock a through-line spine, ask the user for visual style every run, then ship creative marks (maps, unusual axes, huge moving digits) in one dense article. Use when the user asks for a viz, interactive story, infographic, scrolly, chart page, map, or to turn a CSV, API, database, or diary into a visual narrative.

- Skill: `tarlarion/interactive-viz` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add tarlarion/interactive-viz`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tarlarion/interactive-viz/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: tarlarion (https://skillmd.com/u/tarlarion)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tarlarion/interactive-viz

---


# Interactive viz

Any dataset → **one article**, not a dashboard and not a stack of scrolly parking lots.

Read this file first. Open a reference only when that step starts.

Quality bar: a reader gets the claim in three seconds, sees **why the next block exists**, and feels the numbers move. If the page looks like four widgets with empty air between them, it failed — even if the stats are correct.

## Pipeline — do not skip ahead

```
Task Progress:
- [ ] 1. Data structure — data card + geo hunt
- [ ] 2. Insights — 10–16 claims, each gets an on-page slot
- [ ] 3. Params — 2–4 axes
- [ ] 4. Spine — through-line (why N follows N−1)
- [ ] 5. Visual style — ASK the user, then lock tokens
- [ ] 6. Marks — insight → mark; maps + huge digits required when data allows
- [ ] 7. Copy — kicker / hed / dek + connector
- [ ] 8. Layout — tight band, no empty steps
- [ ] 9. Section motion — the walk
- [ ] 10. Insight + digit motion — punctuation
- [ ] Verify desktop + one mobile width
- [ ] Write viz-memory.md
```

If the user jumps to “make it pretty”, still write a short data card and the top 5 insights first.

After step 4, show the spine as:

```
01 — question
    because 00 raised …
02 — question
    because 01 asked …
```

Ask only if two spines are equally good.

Then **always** run the style ask in [style.md](style.md). Do not proceed to marks until the user answers. Existing `viz-memory.md` tokens may be offered as “Keep current” — they do not skip the question.

## Hard rejects (the last run failed these)

A page **fails** if any of these are true:

1. **Air** — a copy step uses `min-height` ≥ 40vh, or the gap between sections is a blank band. Target: section gap ≤ 32px desktop / 20px mobile.
2. **Orphan blocks** — two adjacent sections do not share a clock, an entity, or a one-line “because”. Four independent playheads = fail.
3. **Safe marks** — the only charts are a horizontal line, a ribbon, stems, and bars. If the data has a place, station, city, trip, or country and there is **no map**, fail.
4. **Dead numbers** — the hero measure is a static `<h2>`. Digits must be **huge** and **move** with the playhead or count up on enter.
5. **Thin story** — fewer than 8 insights are visible on the page (pins, digits, list rows, map cities, slices). Insights that live only in chat do not count.
6. **Unasked style** — paper, type, or accent were chosen without asking the user on this run.

## Stop rules

- No chart before insights.
- No style before params.
- No marks, copy, or CSS before the user answers the style ask.
- No insight motion before the finding is named.
- One question per section.
- **One clock** for the piece when sections share time. Later sections read the same cursor.
- Playhead / scroll owns the story. Hover only inspects.
- Do not interpolate measured points unless the user asks.
- Switchers resort the same set. Color stays on the entity, not the rank.
- Dark insights: stillness or color. Never celebration.
- Scrolly is allowed only as a **sticky chart + short notes**. Notes are auto-height. Never pad a step to fill the viewport.

## References

- [explore.md](explore.md) — data card, grain, geo hunt
- [insights.md](insights.md) — scoring, slots, great vs dark
- [style.md](style.md) — mandatory style ask + token lock
- [charts.md](charts.md) — insight → mark, maps, huge digits
- [layout.md](layout.md) — density, through-line chrome
- [voice.md](voice.md) — copy, connectors, locales
- [motion.md](motion.md) — walk, digits, punctuation
- [examples.md](examples.md) — quality bar vs last failure

## Memory

If the project has `viz-memory.md` or `.cursor/nyt-viz-memory.md`, read it as law for that repo.

After a shipped section, append: locked params, insights kept **and where they sit on the page**, style tokens, which findings may move.