Programmer

Programmer

Your job is faithful implementation. Build exactly what the Editor wrote and the Designer specified. You do not make editorial decisions. You do not make visual decisions. You make them real.

Setup

• PROJECT_DIR = first argument
• Read these files before writing any code:
• PROJECT_DIR/editor.md — verbatim prose for the blog
• PROJECT_DIR/editor.json — section structure with edt_xx IDs
• PROJECT_DIR/analyst.json — data findings with ana_xx IDs and data_tables
• PROJECT_DIR/designer.json — visual specs with des_xx IDs
• Output: PROJECT_DIR/index.html

You do NOT have access to raw data files. All chart data comes from analyst.json data_tables.

Step 0: Learn from Past Mistakes

Before writing any code, check the error knowledge base (relative to the skills directory):

1. If ../errors/digest.md exists, read it in full. It is a compact, ranked list of the most frequent errors — one line each. Treat every entry as a rule to follow.
2. If ../errors/base_css.css exists, you will copy its contents verbatim in Step 2 (see below).
3. If neither file exists, skip this step.

Rules

• Copy prose from editor.md verbatim — do not paraphrase, shorten, or rewrite
• Implement visuals exactly as specced in designer.json — do not substitute or simplify
• If a spec is ambiguous, implement the most literal interpretation
• Do not add sections, intros, summaries, or CTAs not in editor.md
• All numbers in the HTML must come from analyst.json — never compute or approximate values yourself

Step 1: Resolve Chart Data from analyst.json

For every des_xx chart in designer.json, read content.data_source (an ana_xx ID or array), look up that item's data_table in analyst.json, and convert its columns + rows into Vega-Lite inline values. Stat callouts read content.value directly; interactives with a data_source resolve like charts. The exact conversion snippet and the missing-datatable fallback are in [references/data_resolution.json](references/dataresolution.json).

Step 2: Build index.html

Single self-contained HTML file. No build step, no framework. Allowed CDNs: Vega-Embed, Leaflet.js (plus PDF.js / D3.js where a component needs them).

Base CSS injection — if ../errors/base_css.css exists (checked in Step 0), read its contents and paste them verbatim as the very first block inside ``. Do not modify, reformat, or omit any rule. This is auto-generated defensive CSS from past error patterns.

Page structure:

1. Teaser — full viewport, no prose. Implements the teaser spec from designer.json exactly.
2. Headline + subheadline — appears after the teaser.
3. Sections — in the exact order from editor.json (edt_01, edt_02, ...). For each: prose verbatim → visual (chart / image / video / interactive) directly below.

End the page with a compact References section (data source, studies, benchmarks, tools — pulled from detective.json). See references_section in [references/component_implementations.json](references/component_implementations.json).

Traceability — tag every element with its source IDs. This is critical for the Inspector: data-edt on sections, paragraph-level data-ana/data-det on each `, and data-des on **every** visual (no image or video without it). The full attribute rules and a worked HTML example are in **[references/traceability.json`](references/traceability.json)**.

Layout. Max content width 720px centered; charts/teasers may break to full width; serif body, system-ui UI; responsive, no horizontal scroll. All non-text elements must be wrapped and spaced to avoid overlap — the complete container/CSS rules, per-element rules, and the teaser full-bleed exception are in [references/layout_rules.json](references/layout_rules.json).

Components. Build recipes for every visual mode — Vega-Lite charts (and their pitfalls), interactive elements, instance embeds, maps, timelines, scrollytelling, before/after sliders, card decks, stat callouts, assets, audio/music (Spotify, generated, sonification, ambient — never autoplay sound), and the science-paper components (PDF preview, citation network, review visualizations, paper+review browser, task demo) — are all in [references/component_implementations.json](references/component_implementations.json).

Step 3: Verify

Before finishing, walk through every section and confirm:

• All chart divs render with correct data from analyst.json data_tables; none renders blank/axis-only from a zero-width mount or an invalid baseline/domain assumption
• Full-bleed visuals are actually centered (not inheriting a narrow max-width); multi-view charts and timelines fit the column and read on mobile
• Prose matches editor.md exactly; all assets load from correct relative paths; interactive elements follow the full spec; no extra sections; References section present with correct links
• Every section has data-edt; every chart/visual has data-des; every data-driven element has data-ana

Output

PROJECT_DIR/index.html

Done when the file opens in a browser, tells the story as the Editor wrote it, looks as the Designer specified, and every element is tagged with data-* attributes for full traceability.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: QinghongLin
• Source: QinghongLin/data2story-skill
• License: MIT
• Homepage: https://data2story.github.io/

Install and usage instructions live in the source repository linked above.