feat(highcharts): implement bar-race-animated

[github-actions]

Implementation: bar-race-animated - python/highcharts

Implements the python/highcharts version of bar-race-animated.

File: plots/bar-race-animated/implementations/python/highcharts.py

Parent Issue: #3653

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Six-panel 2×3 grid of horizontal bar charts on a warm off-white (#FAF8F1) background. Each panel represents a year from 2019–2024 with the year displayed as a bold 38px panel title. Companies are sorted ascending by market value within each panel. Colors follow Okabe-Ito order: TechCorp Alpha (#009E73 green), DataSphere (#D55E00 vermillion), CloudNine (#0072B2 blue), InnovateTech (#CC79A7 reddish purple), CyberCore (#E69F00 orange), QuantumByte (#56B4E9 sky blue), NetPrime (#F0E442 yellow), DigiWave (adaptive neutral #1A1A1A black). Data labels on bars show formatted values (e.g., $168B). Main title and subtitle are dark and clearly legible. All axis labels and company names are readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): Same 6-panel layout on a dark (#1A1A17) background. All chrome elements correctly flip: title, subtitle, year labels, company name labels, and axis tick labels all render in light ink tokens (INK/INK_SOFT). Data colors for positions 1–7 are identical to the light render. DigiWave bars correctly switch to near-white (#E8E8E0) as position-8 adaptive neutral. No dark-on-dark text failures observed. Data labels on bars remain readable. The elevated panel backgrounds use #242420 (ELEVATED_BG) providing subtle visual separation. Legibility verdict: PASS.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 85/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All sizes explicitly set (title 52px, year labels 38px, company labels 22px, axis label 22px, ticks 18px, data labels 19px). Data labels at 19px are the minimum for this canvas but readable; minor deduction.
• VQ-02: No Overlap (6/6) — No overlapping text; company labels and bar data labels all clear.
• VQ-03: Element Visibility (6/6) — Bars clearly visible with consistent pointWidth=58; no crowding.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe; all bars distinguishable without relying on hue alone.
• VQ-05: Layout & Canvas (3/4) — 6 panels fill the 4800×2700 canvas well; chart area accounts for ~75% of canvas. Minor deduction for tight 28px gap between panels.
• VQ-06: Axis Labels & Title (2/2) — X-axis: "Market Value ($B)" with unit; main title correctly formatted; subtitle provides context.
• VQ-07: Palette Compliance (2/2) — First series (TechCorp Alpha) is #009E73; all 8 entities follow Okabe-Ito in canonical order with correct position-8 adaptive neutral; backgrounds are #FAF8F1/#1A1A17; chrome theme-correct in both renders.

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured above defaults: correct palette, elevated panel backgrounds with rounded corners, bold year titles. But fundamentally a small-multiples grid without exceptional visual hierarchy or typographic distinction.
• DE-02: Visual Refinement (4/6) — Good refinement: no bar borders (borderWidth: 0), subtle GRID-colored gridlines, elevated panel backgrounds (#ELEVATED_BG), no legend, rounded corners on containers. Missing: no spine removal, no whitespace annotations.
• DE-03: Data Storytelling (3/6) — Consistent per-entity colors allow cross-panel entity tracking, and sorted ordering at each step reveals the "race" narrative. However, no emphasis or annotation highlights the most interesting rank changes (e.g., DigiWave's crash in 2022).

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct small-multiples horizontal bar chart per spec fallback ("For static output or libraries without animation support, show a small multiples grid of key time snapshots").
• SC-02: Required Features (4/4) — Bars sorted by value at each frame ✓; entity labels attached to bars ✓; visible time indicator (year labels) ✓; consistent entity colors across frames ✓.
• SC-03: Data Mapping (3/3) — X-axis: Market Value ($B); Y-axis: companies sorted by value; bars encode value correctly.
• SC-04: Title & Legend (3/3) — Title: "bar-race-animated · python · highcharts · anyplot.ai" ✓; no legend (appropriately disabled, entity identity via y-axis labels).

Data Quality (14/15)

• DQ-01: Feature Coverage (6/6) — Shows 8 entities over 6 time snapshots; clear ranking changes visible (DigiWave drops dramatically in 2022, QuantumByte rises to top in 2023–2024). Full bar-race feature set demonstrated.
• DQ-02: Realistic Context (4/5) — Fictional tech company names with plausible market cap values in a neutral business context. Slightly generic vs. a domain-specific real-world scenario.
• DQ-03: Appropriate Scale (4/4) — Market values range ~10B–450B, appropriate for mid-large technology firms over 2019–2024.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat script: imports → theme tokens → data → loop over years → HTML assembly → save.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set before data generation.
• CQ-03: Clean Imports (2/2) — All imports used; no unused libraries.
• CQ-04: Code Elegance (2/2) — Clean loop over years; per-point color assignment is concise; HTML assembly is readable.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; no bare plot.png; current Highcharts API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct Chart/HighchartsOptions/BarSeries API; container specified; data labels via data_labels dict; options set via dict assignments. Slightly below perfect as chart assembly in a loop, while correct, doesn't leverage Highcharts' responsive features.
• LM-02: Distinctive Features (3/5) — Per-point color assignment via data dict (Highcharts-specific); formatted data labels with ${point.y:.0f}B syntax; HTML multi-chart assembly with multiple chart instances. Could go further with Highcharts' synchronized axes, custom tooltip formatting, or responsive layouts.

Score Caps Applied

• None applied. DE-01=4 > 2 and DE-02=4 > 2 so the "correct but boring" cap does not trigger.

Strengths

• Perfect spec compliance: small multiples correctly implements the bar-race spec fallback with all required features (sorted bars, entity labels, time indicator, consistent colors).
• Flawless code quality: clean KISS structure, seed set, correct output files.
• Excellent palette and theme compliance: Okabe-Ito in canonical order, adaptive neutral for position 8, correct background tokens in both themes with no dark-on-dark failures.
• Per-point Highcharts color assignment enables per-entity color tracking, which is the core bar-race mechanic.

Weaknesses

• Design Excellence is the main gap (11/20): no emphasis or narrative highlighting the most dramatic rank changes. DigiWave's crash in 2022 is the most interesting story and goes unannounced. Consider a subtitle annotation or rank-change callout on the most dramatic mover.
• Data storytelling (DE-03): adding a rank annotation (e.g., "Add workflow diagram for new prototype discovery #1" or rank number next to the top bar in each panel) would immediately improve storytelling without complexity.
• LM-02: Highcharts-specific features underused — synchronized axis ranges across panels are already implemented (max_val shared), but custom Highcharts tooltip formatting or a shared legend/annotation connecting panels would push library mastery higher.

Issues Found

1. DE-03 MODERATE: No visual emphasis on rank leaders or dramatic movers. The "race" narrative is implicit only.
   • Fix: Add rank number labels (e.g., #1) next to the top bar in each panel, or annotate the most dramatic change across panels.
2. DE-01 MODERATE: Elevated panel backgrounds are a nice touch but the overall look remains a clean default grid — no typographic hierarchy beyond year labels.
   • Fix: Bold or larger data labels for top-ranked bars; slightly larger gap between rows vs columns; or a subtle rank indicator embedded in bar width progression.
3. LM-02 MINOR: Highcharts multi-chart assembly is functional but doesn't leverage synchronized crosshair, shared tooltip, or responsive plugins.
   • Fix: Add a Highcharts-native rank annotation via renderer or plotBands to mark top position in each panel.

AI Feedback for Next Attempt

The implementation is technically excellent — perfect spec compliance, clean code, and flawless theme handling. To reach 90+, focus on Design Excellence: (1) Add rank number labels ("#1", "#2"...) overlaid on each bar or next to bar labels to make the ranking explicit. (2) Annotate the most dramatic story in the data — DigiWave's collapse from ~125B in 2020 to ~10B in 2022 is compelling; mark it in the 2022 panel with a callout or distinct annotation. (3) Consider increasing DE-02 refinement by adding a thin separator line or rank-based background shading between top-3 and the rest. These additions require no restructuring — the core implementation is solid.

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): Six horizontal bar charts arranged in a 2×3 small-multiples grid on a warm off-white #FAF8F1 background. Each panel shows one year (2019–2024) with 8 technology companies ranked by descending market value. Bars use distinct Okabe-Ito colors: TechCorp Alpha is #009E73 (brand green), DataSphere #D55E00 (vermillion), CloudNine #0072B2 (blue), InnovateTech #CC79A7 (reddish purple), CyberCore #E69F00 (orange), QuantumByte #56B4E9 (sky blue), NetPrime #F0E442 (yellow), DigiWave adaptive black #1A1A1A. Per-bar data labels (e.g. "$1888B") appear in dark ink. The main page title ("bar-race-animated · python · highcharts · anyplot.ai") and subtitle are clearly visible in dark ink. Year labels inside each chart are bold and readable. All text is readable against the light background — PASS.

Dark render (plot-dark.png): Same layout on a warm near-black #1A1A17 background. Chart containers render with the elevated-dark #242420 fill. All Okabe-Ito data colors (positions 1–7) are identical to the light render — only the adaptive neutral (DigiWave, position 8) flips to #E8E8E0 as expected. Main title, subtitle, year labels, company names, and axis tick labels all render in light ink (#F0EFE8 / #B8B7B0), clearly visible against the dark surface. Grid lines are appropriately subtle. No dark-on-dark failures detected — PASS.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 83/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 52px CSS, year labels 38px, axis labels 22px, tick labels 18px, data labels 19px); all readable in both renders. Minor deduction: main CSS title is not set through Highcharts native styling.
• VQ-02: No Overlap (6/6) — No text collisions in any of the 6 panels in either render.
• VQ-03: Element Visibility (4/6) — Most bars clearly visible with data labels. Extreme outlier values in 2022 (DataSphere ~$3000B) and 2024 (TechCorp Alpha ~$2926B) compress shorter bars to ~10–20% of panel width, reducing readability for those entries.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito is CVD-safe; bars are wide enough for shape-independent identification.
• VQ-05: Layout & Canvas (4/4) — 2×3 grid fills ~90% of the 4800×2700 canvas; balanced margins; nothing cut off.
• VQ-06: Axis Labels & Title (2/2) — X-axis "Market Value ($B)" has units; y-axis shows entity names.
• VQ-07: Palette Compliance (2/2) — First categorical entity is #009E73; Okabe-Ito order maintained; backgrounds #FAF8F1 / #1A1A17; all chrome is theme-adaptive.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Above plain defaults: card-like rounded containers, Okabe-Ito throughout, inline page title/subtitle hierarchy. Not yet at publication-ready (no emphasis on the "race" leader, no highlight of the most dramatic shift).
• DE-02: Visual Refinement (4/6) — Subtle GRID color (10% opacity), borderWidth: 0 on bars, credits: false, custom margins, ELEVATED_BG containers. Axis lines/ticks are appropriately styled with INK_SOFT.
• DE-03: Data Storytelling (3/6) — Small multiples effectively show time progression with year labels. However, there is no visual emphasis on the leading company or the most dramatic ranking change; the viewer must read all bars to find the story.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Horizontal bar chart in small-multiples grid; valid static fallback per spec.
• SC-02: Required Features (4/4) — Bars sorted by value each frame; entity labels attached to bars; visible time indicator (year title); colors consistent per entity across all frames.
• SC-03: Data Mapping (3/3) — Companies on y-axis, market value on x-axis; all data visible.
• SC-04: Title & Legend (3/3) — HTML title is exactly bar-race-animated · python · highcharts · anyplot.ai; no legend needed (company names on y-axis).

Data Quality (12/15)

• DQ-01: Feature Coverage (5/6) — Rankings change year-to-year; all 8 entities compete across 6 snapshots; bar race behavior is demonstrated. Minor deduction: entities don't cross ranks dramatically enough in the middle years to fully showcase the "race" nature.
• DQ-02: Realistic Context (4/5) — Fictional tech company names in a plausible market-value scenario; neutral topic; descriptive subtitle.
• DQ-03: Appropriate Scale (3/4) — Most values are plausible; a single extreme outlier (~$3000B for DataSphere in 2022) distorts the scale and is unrealistic relative to peers in the same year.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear Imports → Data → Chart loop → HTML assembly → Save; no functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imported modules are used.
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; list comprehension for chart scripts; appropriate complexity.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Uses Chart, HighchartsOptions, BarSeries, chart.to_js_literal() correctly; per-point color assignment via {"color": ...} in series data is idiomatic Highcharts.
• LM-02: Distinctive Features (3/5) — Uses to_js_literal() for HTML embedding, per-point color overrides, and Highcharts format-string data labels ("${point.y:.0f}B"). Multiple chart instances in a coordinated grid is a meaningful use of the library.

Score Caps Applied

• None — no caps triggered (all critical criteria > 0; DE-01=5 > 2 and DE-02=4 > 2).

Strengths

• Perfect spec compliance: all required bar-race features present with correct static fallback (small multiples grid).
• Clean code structure with seed, adaptive theme tokens, and proper HTML+PNG dual output.
• Consistent per-entity Okabe-Ito coloring maintained across all 6 year panels.
• Card-like chart containers with rounded corners give the grid a polished, dashboard-like appearance.
• Both light and dark renders are fully readable with correct backgrounds and adaptive chrome.

Weaknesses

• Extreme outlier values (DataSphere in 2022 ~$3000B, TechCorp Alpha in 2024 ~$2926B) distort the shared x-axis scale, compressing most bars in those panels to a fraction of panel width.
• No visual storytelling emphasis — no highlighted "winner" bar, no callout for the most dramatic ranking change, no leader annotation.
• Design Excellence headroom: DE-01 could reach 6–7 with a subtle rank-change indicator or emphasis on the leading entity per year.

Issues Found

1. VQ-03 PARTIAL: Extreme outlier values compress most bars in 2022 and 2024 panels.
   • Fix: Clamp or smooth extreme values in data generation, or use per-chart max instead of a single global max_val, or increase shuffle variability to distribute rankings more evenly.
2. DE-03 LOW: No visual hierarchy emphasizing the leader or key ranking changes.
   • Fix: Highlight the top-ranked bar each year (e.g., slightly bolder label, a small #1 annotation, or a thin rank-leader border) so the "race" narrative is immediately visible.
3. DQ-03 PARTIAL: Single extreme outlier in 2022 is unrealistic relative to peers.
   • Fix: Cap shuffle_factor magnitude or add value bounds to prevent any single entity from being 5–10× larger than peers in the same year.

AI Feedback for Next Attempt

The implementation is structurally solid and spec-compliant. Primary improvements needed: (1) fix data generation to avoid extreme outliers that distort the shared axis — consider clamping values to within 3× of the median per year; (2) add a visual storytelling layer to DE-03 — highlight the rank-1 bar per panel with a subtle but distinct treatment (thicker label, small crown/badge annotation, or contrasting opacity on non-leaders); (3) optionally move to per-chart max instead of global max_val to make each year's rankings more legible at the cost of cross-year comparability.

Verdict: APPROVED