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. 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 — data card, grain, geo hunt
• insights.md — scoring, slots, great vs dark
• style.md — mandatory style ask + token lock
• charts.md — insight → mark, maps, huge digits
• layout.md — density, through-line chrome
• voice.md — copy, connectors, locales
• motion.md — walk, digits, punctuation
• 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.