feat(highcharts): implement sankey-basic

[github-actions]

Implementation: sankey-basic - python/highcharts

Implements the python/highcharts version of sankey-basic.

File: plots/sankey-basic/implementations/python/highcharts.py

Parent Issue: #810

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1 — correct). Title "sankey-basic · highcharts · anyplot.ai" is dark bold text, clearly readable. Subtitle "U.S. Energy Flow (values in TWh)" readable in softer dark text. Five source nodes on the left (Coal, Natural Gas, Nuclear, Petroleum, Renewable) use custom dark hex colors — steel blue, gold-olive, purple, teal, dark green — NOT Okabe-Ito. Two intermediate vertical nodes (Electricity, Transportation) in dark brown and amber. Four destination nodes on the right (Industrial, Residential, Commercial, and a small olive node). Flow links are semi-transparent (opacity 0.5) and inherit source-node color, creating a flowing visual. Node labels are white bold text with dark text outline — all readable. Minor issue: the Renewable source node at the bottom-left is partially cropped at the canvas edge (marginBottom=80 too small). All text is readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): Near-black background (~#1A1A17 — correct). Title and subtitle use light-colored text (INK/INK_SOFT tokens correctly applied) — clearly readable against the dark background. No dark-on-dark failures. Node colors are identical to the light render (same custom dark hex values — data colors correctly unchanged between themes). The dark node colors (#1A3A5C, #6B4E12, #5B2E8F etc.) have reduced contrast against the near-black background compared to the light render, but nodes and labels remain distinguishable. Same bottom-cropping of Renewable node as in the light render. White node labels with dark outline remain readable in dark theme. Legibility verdict: PASS — all chrome elements correctly flip to light on dark; no dark-on-dark text failures.

Score: 85/100

Category	Score	Max
Visual Quality	26	30
Design Excellence	12	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	85	100

Visual Quality (26/30)

• VQ-01: Text Legibility (8/8) — Font sizes explicitly set: title 64px, subtitle 40px, data labels 36px — all readable at 4800×2700px in both themes
• VQ-02: No Overlap (6/6) — All node labels inside nodes with white text and dark outline; no overlapping text
• VQ-03: Element Visibility (6/6) — Nodes and links clearly visible; nodeWidth=50 and nodePadding=35 appropriate
• VQ-04: Color Accessibility (2/2) — White text on colored nodes provides sufficient contrast; linkOpacity=0.5 helps overlapping flows
• VQ-05: Layout & Canvas (2/4) — Renewable source node at bottom-left is partially cropped at canvas edge; marginBottom=80 too small for the data
• VQ-06: Axis Labels & Title (2/2) — Subtitle "U.S. Energy Flow (values in TWh)" provides units and context
• VQ-07: Palette Compliance (0/2) — Custom dark hex colors (#1A3A5C, #6B4E12, #5B2E8F, #0A6B78, #155415…) are NOT Okabe-Ito. Fallback #306998 (Python Blue) present in code. First source node (Coal) must be #009E73.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (4/8) — Configured appearance with intent for contrast management, but bypassing Okabe-Ito makes this non-standard; visually functional but not publication-ready
• DE-02: Visual Refinement (4/6) — Clean layout, legend disabled, no unnecessary chrome, good whitespace; bottom crop detracts
• DE-03: Data Storytelling (4/6) — Energy flow story is legible — Petroleum dominance in Transportation, Nuclear wholly to Electricity, multi-path Natural Gas; proportional widths guide the viewer

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Sankey diagram with proportional-width links
• SC-02: Required Features (4/4) — Source→intermediate→destination flows, distinct colors, visible labels, linkOpacity for crossing flows, no circular flows
• SC-03: Data Mapping (3/3) — source/target/value correctly mapped; 15 flows within 5–50 spec range
• SC-04: Title & Legend (3/3) — Title "sankey-basic · highcharts · anyplot.ai" correct format; no legend required for node-labeled Sankey

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Multi-level flows, varied magnitudes (20–280 TWh), crossing flows, intermediate nodes — full Sankey feature set demonstrated
• DQ-02: Realistic Context (5/5) — U.S. Energy Flow is a well-known, neutral, real-world science/infrastructure domain
• DQ-03: Appropriate Scale (4/4) — TWh values and proportions (Petroleum→Transportation dominant, Renewable small) factually plausible

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat: imports → data → chart config → export; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic; hardcoded data, no random elements
• CQ-03: Clean Imports (2/2) — All imports used
• CQ-04: Code Elegance (2/2) — Clean, appropriately complex; dict comprehension for nodes is idiomatic
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct highcharts_core usage with sankey series type, inline JS module loading, proper node/link data structure with keys parameter
• LM-02: Distinctive Features (3/5) — Sankey is a Highcharts module; uses linkColorMode='from', curveFactor, nodePadding, nodeWidth, nodeFormat in tooltips — Highcharts-specific features

Score Caps Applied

• None

Strengths

• Correct multi-level Sankey (sources → intermediates → destinations) matching spec exactly
• Realistic and neutral energy flow dataset with plausible TWh proportions
• Font sizes explicitly set for large canvas — all text readable in both themes
• Theme-adaptive chrome correctly implemented (background, title, subtitle switch between themes)
• Correct inline Highcharts + sankey module loading; proper HTML and PNG output for both themes
• White node labels with dark text outline ensure legibility on all node colors in both themes

Weaknesses

• VQ-07: Node colors are arbitrary custom hex values (#1A3A5C, #6B4E12, #5B2E8F, #0A6B78, #155415…) — must use Okabe-Ito in canonical order. Apply to source nodes: Coal=#009E73, Natural Gas=#D55E00, Nuclear=#0072B2, Petroleum=#CC79A7, Renewable=#E69F00. Remove the #306998 fallback.
• VQ-05: Renewable source node partially cropped at bottom canvas edge — increase marginBottom from 80 to at least 150
• DE-01: Dark-tone color scheme bypasses Okabe-Ito entirely; using Okabe-Ito colors for source nodes (with semi-transparent links inheriting source color via linkColorMode='from') would fix palette compliance and improve aesthetics simultaneously

Issues Found

1. VQ-07 FAIL (0/2): Node colors are NOT Okabe-Ito. Replace node_colors dict with Okabe-Ito values for source nodes (at minimum), and remove the #306998 fallback.
2. VQ-05 PARTIAL (2/4): Renewable node clipped. Fix: "marginBottom": 150 in chart.options.chart.

AI Feedback for Next Attempt

Replace all custom node hex colors with Okabe-Ito palette applied in canonical order to source nodes: Coal=#009E73, Natural Gas=#D55E00, Nuclear=#0072B2, Petroleum=#CC79A7, Renewable=#E69F00. For intermediate and destination nodes, either extend with Okabe-Ito positions 6–7 (#56B4E9, #F0E442) and derived neutrals, or use muted variants. Remove the #306998 fallback. Also increase "marginBottom" to 150 to prevent Renewable node clipping.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/4

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white background (~#FAF8F1) with a bold dark title "sankey-basic · highcharts · anyplot.ai" and subtitle "U.S. Energy Flow (values in TWh)" in softer dark text. The Sankey diagram fills ~75% of the canvas with five source nodes on the left (Coal in brand green #009E73, Natural Gas in vermillion orange, Nuclear in blue, Petroleum in reddish-purple, Renewable in gold-yellow) flowing through intermediate nodes (Electricity in sky blue, Transportation in yellow) to three destination nodes (Industrial, Residential, Commercial) on the right. Links inherit source node colors at 0.5 opacity, creating a coherent visual flow. Node labels are bold white text with a dark outline for contrast, readable across all nodes. All text — title, subtitle, and node labels — is clearly readable against the light background.

Dark render (plot-dark.png): The same diagram renders on a near-black background (~#1A1A17) with the title and subtitle rendered in light cream/off-white text, clearly legible against the dark surface. Data node colors are identical to the light render — Coal remains #009E73, Natural Gas #D55E00, Nuclear #0072B2, Petroleum #CC79A7, Renewable #E69F00, Electricity #56B4E9, Transportation #F0E442 — confirming only chrome (background, text) flips between themes, not the Okabe-Ito data colors. Node labels retain white text with dark outline, remaining readable on the dark surface. No dark-on-dark failures observed. Both renders pass legibility checks.

Score: 88/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	12	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	88	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — Title 64px, subtitle 40px, node labels 36px bold, all explicitly set and readable; minor: node label color hardcoded #FFFFFF rather than INK-adaptive, though textOutline (#333333) compensates
• VQ-02: No Overlap (6/6) — Node labels well-positioned within nodes; no collisions between Electricity and Transportation labels in the middle column
• VQ-03: Element Visibility (6/6) — Node widths (50px), padding (35px), and 0.5 link opacity all well-calibrated for flow density; all flows visually distinct
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe; 0.5 opacity on links maintains readability where flows cross
• VQ-05: Layout & Canvas (4/4) — 4800×2700 landscape; Sankey fills ~75% of canvas with generous symmetric margins (180/160px)
• VQ-06: Axis Labels & Title (2/2) — Title follows required format; subtitle "U.S. Energy Flow (values in TWh)" includes units
• VQ-07: Palette Compliance (2/2) — First node (Coal) correctly uses #009E73; all subsequent nodes follow Okabe-Ito canonical order; backgrounds are #FAF8F1 (light) and #1A1A17 (dark); theme-adaptive title/subtitle colors

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Professional look achieved via linkColorMode:"from" (links inherit source color), curveFactor:0.5 for smooth curves, and proper Okabe-Ito node coloring; clearly above generic defaults but stops short of exceptional; no creative focal-point emphasis
• DE-02: Visual Refinement (4/6) — Chrome thoughtfully stripped (credits off, legend off); node padding creates breathing room between flows; link opacity is tasteful; for Sankey no spine/grid to remove, but available chrome is well-handled
• DE-03: Data Storytelling (3/6) — Multi-level energy flow (sources → electricity → end use) naturally conveys a story; linkColorMode creates a visual thread tracing energy origins; but no deliberate emphasis on the dominant flow (Petroleum → Transportation at 280 TWh) or other key insight

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Highcharts Sankey with native sankey.js module
• SC-02: Required Features (4/4) — Source/target/value mapping; link widths proportional to flow; distinct node colors; link opacity for crossing flows; no circular flows; node labels clearly visible
• SC-03: Data Mapping (3/3) — 15 flows correctly mapped; proportional widths accurately reflect TWh values; multi-level flow structure (source → transformer → end use) implemented
• SC-04: Title & Legend (3/3) — Title format "sankey-basic · highcharts · anyplot.ai" correct; legend correctly omitted (Sankey uses colored nodes directly)

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all Sankey aspects: multiple sources, intermediate transformation node (Electricity), direct flows (Petroleum → Transportation), and three end-use destinations; 15 distinct flows
• DQ-02: Realistic Context (5/5) — U.S. energy flow in TWh — neutral scientific/infrastructure domain; no controversial content
• DQ-03: Appropriate Scale (4/4) — Petroleum dominates transportation (280 TWh); Nuclear contributes substantially to electricity (200 TWh); relative proportions align with real U.S. energy patterns

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear structure: imports → tokens → data → nodes/links → chart config → HTML → screenshot
• CQ-02: Reproducibility (2/2) — Data is hardcoded; fully deterministic, no random seed needed
• CQ-03: Clean Imports (2/2) — All imports (os, tempfile, time, urllib.request, pathlib, highcharts_core, selenium) are actually used
• CQ-04: Code Elegance (2/2) — Appropriate complexity; dict comprehension for nodes_data; set for deduplication; no over-engineering
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly; current highcharts-core API

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct highcharts-core pattern (Chart → HighchartsOptions → series); properly downloads and inlines sankey.js for headless Chrome; nodeFormat/pointFormat tooltip customization; slightly below full idiomatic as series uses raw dicts rather than typed series objects
• LM-02: Distinctive Features (3/5) — Uses Highcharts-distinctive Sankey options: linkColorMode:"from" (links inherit source-node color), curveFactor:0.5, nodeWidth/nodePadding tuning, and rich nodeFormat/pointFormat tooltip templates

Score Caps Applied

• None

Strengths

• Correct Okabe-Ito palette applied at node level with Coal as #009E73 brand green first
• linkColorMode:"from" creates a visually coherent source-tracing effect unique to Highcharts Sankey
• Both renders pass theme checks — backgrounds, title/subtitle colors all correctly adaptive
• Realistic U.S. energy flow data with multi-level transformation (sources → electricity → end use)
• Node padding and link opacity thoughtfully tuned for readability of crossing flows
• All chrome stripped (credits, legend) appropriate for Sankey

Weaknesses

• Node label color hardcoded to #FFFFFF rather than adapting to INK token (textOutline compensates, but not fully theme-adaptive)
• No storytelling emphasis on the dominant flow (Petroleum → Transportation at 280 TWh) — a size annotation or highlighted node would elevate DE-03
• LM-01 slightly below full idiom: series defined as raw dict rather than typed Highcharts series objects

Issues Found

1. DE-03 MODERATE: No visual emphasis on key insight (Petroleum as dominant energy source for transportation)
   • Fix: Consider using a highlighted node color or a subtitle annotation pointing to the largest flow
2. VQ-01 MINOR: Node labels use hardcoded white (#FFFFFF) rather than theme-adaptive INK token
   • Fix: Use INK for node label color so it adapts properly; textOutline alone is a workaround not a solution

AI Feedback for Next Attempt

The core implementation is solid — palette, data, layout, and both-theme rendering are all correct. To improve to 90+: (1) add a subtle visual emphasis on the dominant flow or node (e.g., Petroleum node slightly bolder border or a subtitle callout) to push DE-03 above 3; (2) make node label color theme-adaptive (INK token) rather than hardcoded white; (3) consider using typed Highcharts series objects for LM-01 idiom points.

Verdict: APPROVED