feat(highcharts): implement span-basic

[github-actions]

Implementation: span-basic - python/highcharts

Implements the python/highcharts version of span-basic.

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

Parent Issue: #980

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The chart renders on a warm off-white (#FAF8F1) background. A bold title "span-basic · highcharts · anyplot.ai" appears at the top in dark ink, followed by a subtitle "S&P 500 Index with Financial Crisis Period Highlighted" in secondary ink. A green (#009E73) line with circular markers traces 16 quarterly S&P 500 values from Q1 2007 through Q4 2010, showing a clear rise then dramatic crash and recovery. A salmon-orange vertical span band (rgba(213,94,0,0.18)) covers the Financial Crisis period (Q4 2007–Q1 2009) with an orange "Financial Crisis" label at the top. A light amber horizontal span band (rgba(230,159,0,0.18)) covers the Bear Market Zone (below 1000 points) with a "Bear Market Zone" label in amber (#E69F00) at lower-left. All main chrome text is clearly readable against the light background. Minor issue: the "Bear Market Zone" label (#E69F00 amber) has low contrast against the light amber band — visible but not optimal.

Dark render (plot-dark.png): The chart renders on a warm near-black (#1A1A17) background. Title, subtitle, axis labels, and tick labels all flip to light/white text (INK token: #F0EFE8, INK_SOFT: #B8B7B0) — no dark-on-dark failures. The data line stays #009E73 (identical to the light render), confirming theme-independent data colors. The Financial Crisis vertical span becomes a dark brownish-red and remains distinct against the near-black background. The Bear Market Zone horizontal band appears dark brownish-amber. The overlap zone of both span bands creates a very dark brownish-black region in the crisis trough area (Q4 2008–Q1 2009), slightly reducing green line contrast there, though the line and markers remain visible. All text is clearly readable against the dark background.

Both renders pass the theme-readability check. The Bear Market Zone label contrast in the light render is the main visual concern.

Score: 90/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set and scaled for 4800×2700: title 72px, subtitle 48px, axis labels 44px, tick labels 32–36px. All readable in both themes.
• VQ-02: No Overlap (6/6) — No overlapping text. Span labels positioned without collision.
• VQ-03: Element Visibility (5/6) — Line (width 6) and markers (radius 12) clearly visible. Slight visibility reduction in the span-overlap zone in dark mode.
• VQ-04: Color Accessibility (1/2) — Bear Market Zone label (#E69F00 amber on light amber band) has low contrast in the light render. Okabe-Ito palette is CVD-safe; no red-green sole signal.
• VQ-05: Layout & Canvas (4/4) — Good canvas utilization, balanced margins, nothing cut off.
• VQ-06: Axis Labels & Title (2/2) — Y-axis "Index Value (Points)" with units; X-axis "Quarter"; subtitle provides additional context.
• VQ-07: Palette Compliance (2/2) — First series #009E73; span fills from Okabe-Ito (#D55E00, #E69F00); backgrounds #FAF8F1/#1A1A17; all chrome tokens theme-adaptive.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above well-configured library default: subtitle adds narrative context, span colors from Okabe-Ito, warm theme palette throughout. Not yet "strong design" — lacks exceptional typographic hierarchy or artistic refinement.
• DE-02: Visual Refinement (4/6) — Subtle grid (rgba 10% opacity), theme-adaptive axis lines creating effective L-frame, generous margins. Good but not fully polished.
• DE-03: Data Storytelling (4/6) — Dual-span design creates a compelling S&P 500 crisis narrative. Visual hierarchy from overlapping bands guides viewer to the trough. Above default; not exceptional.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct span plot; both vertical (time period) and horizontal (value threshold) spans implemented using Highcharts plotBands.
• SC-02: Required Features (4/4) — Semi-transparent fill (0.18 alpha), vertical and horizontal spans, text labels within regions, underlying data visible.
• SC-03: Data Mapping (3/3) — X-axis: quarters; Y-axis: index values. All 16 points visible.
• SC-04: Title & Legend (3/3) — Title format "span-basic · highcharts · anyplot.ai" correct. Series named "S&P 500".

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Both span types demonstrated with meaningful overlap, showcasing semi-transparency, dual span directions, and labeled regions.
• DQ-02: Realistic Context (5/5) — S&P 500 during the 2008 financial crisis: real, historically grounded, neutral business/finance scenario.
• DQ-03: Appropriate Scale (4/4) — Values (798–1527 range) historically accurate for 2007–2010 S&P 500. Crisis trough matches actual Q4 2008/Q1 2009 levels.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → tokens → data → chart setup → export.
• CQ-02: Reproducibility (2/2) — Deterministic hardcoded data.
• CQ-03: Clean Imports (2/2) — All imports used. Minor note: LineSeries imported from highcharts_core.options.series.area instead of .line (non-idiomatic but functional).
• CQ-04: Code Elegance (2/2) — Clean, readable, appropriate complexity. No fake UI elements.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Current API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Uses Chart, HighchartsOptions, LineSeries, and plotBands on both axes — the canonical Highcharts approach. Correct Selenium headless pipeline with inline JS.
• LM-02: Distinctive Features (4/5) — plotBands with labels on both xAxis and yAxis is the Highcharts-native feature for span visualization — not easily replicated in other libraries without custom patches.

Score Caps Applied

• None

Strengths

• Uses Highcharts plotBands natively for both x-axis (vertical span) and y-axis (horizontal span) — the idiomatic, library-distinctive approach
• Real, historically accurate S&P 500 data during the 2008 financial crisis creates a compelling, factually grounded narrative
• Dual-span design demonstrates the full breadth of the spec with both span types and their intersection
• Full theme adaptation: all chrome tokens correctly flipped between light and dark; data line stays #009E73 in both renders
• Span fill colors drawn from Okabe-Ito (#D55E00, #E69F00) at 0.18 alpha — semi-transparent as specified

Weaknesses

• Bear Market Zone label (#E69F00 amber) on the light amber band in the light render has low contrast — consider using a darker color (INK or #D55E00) for the label
• In the dark render, the span-overlap zone (crisis × bear market) becomes very dark brownish-black, reducing line visibility in that area; consider reducing opacity to 0.12–0.14 for dark theme
• LineSeries imported from highcharts_core.options.series.area instead of the conventional highcharts_core.options.series.line
• Design excellence (13/20) has room for improvement: stronger typographic hierarchy, more refined color treatments

Issues Found

1. VQ-04 LOW: Bear Market Zone label (#E69F00) has inadequate contrast against light amber band in light render
   • Fix: Change label color to INK (#1A1A17) or #D55E00 to ensure readable contrast on the yellow band
2. DE-01 MODERATE: Design is competent but not exceptional; aesthetic sophistication could be elevated
   • Fix: Consider gradient span borders, a more refined legend placement, or additional typographic weight variation

AI Feedback for Next Attempt

Bear Market Zone label contrast is the primary VQ concern — switch its color to INK or #D55E00 for legibility on the light amber background. In the dark render, reduce span opacity slightly (0.12) to prevent the overlap zone from going near-black. For design improvement, consider subtle gradient borders on the span edges or a more polished legend treatment. The dual plotBands approach is architecturally correct — keep it.

Verdict: APPROVED