# Programmer

> Read editor.md, editor.json, analyst.json, and designer.json. Resolve chart data from analyst data_tables. Build the final index.html with data-* traceability attributes. Pure implementation — no editorial or visual decisions, no raw data access.

- Skill: `qinghonglin/programmer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add qinghonglin/programmer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qinghonglin/programmer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: QinghongLin (https://skillmd.com/u/qinghonglin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qinghonglin/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_table`s
  - `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-data_table fallback are in **[`references/data_resolution.json`](references/data_resolution.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 `<style>`. 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 `<p>`, 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.