feat(plotly): implement sankey-basic

[github-actions]

Implementation: sankey-basic - python/plotly

Implements the python/plotly version of sankey-basic.

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

Parent Issue: #810

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white #FAF8F1 background — correct. Title "Energy Distribution · sankey-basic · plotly · anyplot.ai" in dark #1A1A17 ink at 28px, clearly readable. Four source nodes stacked on the left: Natural Gas (largest, orange #D55E00), Nuclear (blue #0072B2), Renewables (pink/purple #CC79A7), Coal (bottom, green #009E73). Four target nodes on the right (Residential, Commercial, Transportation, Industrial) rendered in dark gray #4A4A44 (INK_SOFT light). Semi-transparent RGBA links at 0.4 opacity flow left-to-right, each tinted after its source node — overlapping bands remain distinguishable. Node borders use PAGE_BG creating clean separation between stacked nodes. All node labels are clearly readable against the light background.

Dark render (plot-dark.png): Near-black #1A1A17 background — correct. Title flips to light cream #F0EFE8 via the INK token — clearly readable. All node labels also render in #F0EFE8 through the global font.color setting — no dark-on-dark text detected anywhere. Source node data colors are identical to the light render: Natural Gas orange, Nuclear blue, Renewables pink, Coal green — only chrome elements changed. Target nodes flip to light gray #B8B7B0 (INK_SOFT dark), clearly visible against the near-black background. Link bands are slightly more muted but remain distinguishable by source color. Both renders pass the readability check.

Score: 90/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	13	15
Code Quality	10	10
Library Mastery	9	10
Total	90	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — Title explicitly 28px, global font explicitly 22px for node labels; all text readable in both themes
• VQ-02: No Overlap (6/6) — No overlapping text or visual elements; node labels positioned cleanly
• VQ-03: Element Visibility (6/6) — Nodes (thickness=35) and links clearly visible; semi-transparent links readable
• VQ-04: Color Accessibility (2/2) — Okabe-Ito is CVD-safe; 0.4 alpha on links provides adequate distinguishability
• VQ-05: Layout & Canvas (4/4) — Sankey fills canvas well with balanced margins; no wasted space
• VQ-06: Axis Labels & Title (2/2) — Descriptive title present; no axes required for Sankey diagram
• VQ-07: Palette Compliance (2/2) — Coal=#009E73 first, then #D55E00, #0072B2, #CC79A7 in canonical Okabe-Ito order; backgrounds #FAF8F1/#1A1A17 correct in both renders

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Thoughtful: Okabe-Ito for sources, adaptive INK_SOFT for targets, PAGE_BG node borders for clean separation. Above defaults but not yet publication-ready
• DE-02: Visual Refinement (4/6) — pad=25 and thickness=35 are well-considered; clean layout with no extraneous elements
• DE-03: Data Storytelling (4/6) — Energy flow story readable through proportional node sizing; Natural Gas dominance immediately visible; color-coded links enable flow tracing

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Sankey diagram with nodes and proportional-width links
• SC-02: Required Features (4/4) — Source→target flows, distinct colors per source, link opacity, no circular flows, readable node labels
• SC-03: Data Mapping (3/3) — Source/target indices correctly mapped; flow values drive link widths proportionally
• SC-04: Title & Legend (3/3) — "Energy Distribution · sankey-basic · plotly · anyplot.ai" contains spec-id, library, anyplot.ai in correct order

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) — 4 sources × 4 targets with varied magnitudes (3–25 TWh); selective absent flows (Coal/Nuclear skip Transportation) add variety; distributions are somewhat similar across sources
• DQ-02: Realistic Context (5/5) — Realistic neutral energy domain: coal, gas, nuclear, renewables flowing to residential, commercial, industrial, transportation sectors
• DQ-03: Appropriate Scale (3/4) — Values plausible but coal-to-residential (5 TWh) and coal-to-commercial (8 TWh) are somewhat generous given coal's modern energy profile

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear structure: imports → theme tokens → data → figure → save
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data
• CQ-03: Clean Imports (2/2) — Only os and plotly.graph_objects imported, both used
• CQ-04: Code Elegance (2/2) — List comprehensions for flow data extraction; RGBA link colors derived from source index cleanly
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; current Plotly API

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Expert go.Sankey usage with all key parameters properly configured: pad, thickness, line, label, color for both node and link dicts
• LM-02: Distinctive Features (4/5) — RGBA source-matched link coloring and interactive HTML export (with built-in hover/zoom/pan) are Plotly-distinctive techniques

Score Caps Applied

• None

Strengths

• Correct Okabe-Ito assignment: Coal=#009E73 (first source = first palette position), remaining sources follow canonical order
• Theme-adaptive chrome fully wired: INK flips between #1A1A17/#F0EFE8, target nodes use INK_SOFT which also adapts, PAGE_BG backgrounds correct
• RGBA link colors (0.4 opacity) keyed to source node — flows traceable while overlapping bands remain distinguishable
• Expert go.Sankey API usage: pad=25, thickness=35, node border = PAGE_BG for clean separation
• Both PNG and HTML outputs generated; deterministic hardcoded data; KISS code structure
• Realistic neutral energy scenario with plausible selective flow absences (Coal/Nuclear not flowing to Transportation)

Weaknesses

• Design Excellence moderate (13/20): aesthetic is above-defaults but not publication-ready; adding a unit reference (TWh) as annotation or subtitle could elevate storytelling
• Coal-to-residential/commercial flows slightly generous for modern energy context (DQ-03 -1)
• Source distributions broadly similar — one source with a starkly different profile would increase DQ-01 contrast

Issues Found

None blocking.

AI Feedback for Next Attempt

Implementation is clean and correct. If refining: (1) consider a subtitle or annotation noting "Values in TWh" to add unit context; (2) adjust coal flows to concentrate more heavily on Industrial (~80%+) to better reflect real-world energy patterns; (3) introduce one source with a markedly different distribution profile to increase feature-coverage contrast.

Verdict: APPROVED