feat(pygal): implement span-basic

[github-actions]

Implementation: span-basic - python/pygal

Implements the python/pygal version of span-basic.

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

Parent Issue: #980

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white #FAF8F1 background. Title "span-basic · pygal · anyplot.ai" is visible at top-center. Y-axis label "Price ($)" and X-axis label "Year" are readable. Tick labels are small but legible. Legend at top-left is truncated ("Recession Peri...", "Risk Zone", "Stock Price") — text is clipped by pygal's legend rendering. Three data series: a green (#009E73) semi-transparent vertical rectangle marks the Recession Period (2008–2009), an orange (#D55E00) semi-transparent horizontal band marks the Risk Zone (y=60–80), and a blue (#0072B2) line shows the Stock Price trend declining during the recession. Spans are semi-transparent, keeping the underlying line visible. The Risk Zone sits far below the stock price range (140–220), leaving a large empty gap in the middle of the canvas. All text is readable against the light background. Legibility: PASS.

Dark render (plot-dark.png): Warm near-black #1A1A17 background. Title and axis labels appear as light text on dark background — readable. Tick labels are light-colored with no dark-on-dark failures. Legend is truncated same as light render. Data colors are identical to the light render (green, orange, blue — Okabe-Ito positions 1–3). However, in dark mode the 25% opacity applied to spans blends heavily with the near-black background: the Risk Zone becomes an almost-solid dark brown band, losing the semi-transparent highlight appearance entirely. The Recession Period span is dark green with reduced but still perceptible transparency. The Stock Price line remains clearly visible. Legibility: PASS for text. FAIL for data element intent — the horizontal Risk Zone span looks like a solid opaque bar rather than a soft highlight.

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

Score: 68/100

Category	Score	Max
Visual Quality	21	30
Design Excellence	8	20
Spec Compliance	12	15
Data Quality	12	15
Code Quality	10	10
Library Mastery	5	10
Total	68	100

Visual Quality (21/30)

• VQ-01: Text Legibility (5/8) - Font sizes explicitly set (title=28, label=22, major=18, legend=16) but legend labels are truncated in both renders; rendered text is small relative to the 4800×2700 canvas
• VQ-02: No Overlap (5/6) - No true text overlap but legend labels are clipped ("Recession Peri..."), reducing readability
• VQ-03: Element Visibility (3/6) - Light render: semi-transparent spans visible. Dark render: Risk Zone becomes nearly opaque dark brown, losing the highlighted-region appearance; Recession Period span is dark green with minimal transparency
• VQ-04: Color Accessibility (2/2) - Okabe-Ito palette is colorblind-safe; green/orange/blue well-separated in luminance
• VQ-05: Layout & Canvas (2/4) - Data clustered in upper 40% of canvas; large empty gap between stock price range (140–220) and Risk Zone (60–80); canvas utilization below ideal
• VQ-06: Axis Labels & Title (2/2) - Correct format "span-basic · pygal · anyplot.ai"; Y-axis "Price ($)" with units; X-axis "Year"
• VQ-07: Palette Compliance (2/2) - First series #009E73 (green), second #D55E00 (orange), third #0072B2 (blue) — correct Okabe-Ito order; backgrounds #FAF8F1 / #1A1A17 correct

Design Excellence (8/20)

• DE-01: Aesthetic Sophistication (4/8) - Well-configured library default with correct palette and theme tokens; no exceptional design decisions beyond functional correctness
• DE-02: Visual Refinement (2/6) - Library defaults with minimal customization; dotted grid visible; no spine control in pygal; legend placement not optimized
• DE-03: Data Storytelling (2/6) - Vertical span over recession period tells a good story (visible price drop). Horizontal Risk Zone at 60–80 adds no story value since stock price never enters that range — weakens the narrative

Spec Compliance (12/15)

• SC-01: Plot Type (4/5) - Correct span plot concept using closed XY polygons; no native span API in pygal so polygon workaround is appropriate; minor deduction for it being a workaround
• SC-02: Required Features (3/4) - Semi-transparent fill (light render ✓), vertical + horizontal spans present, underlying data visible in light. Dark render degrades transparency significantly for Risk Zone
• SC-03: Data Mapping (3/3) - X=Year, Y=Price ($); axes correctly show full data range
• SC-04: Title & Legend (2/3) - Title format "span-basic · pygal · anyplot.ai" is correct; legend labels are truncated ("Recession Peri...")

Data Quality (12/15)

• DQ-01: Feature Coverage (5/6) - Shows both vertical and horizontal span directions with underlying line data; horizontal span disconnected from data range reduces coverage effectiveness
• DQ-02: Realistic Context (5/5) - Stock price chart with recession period highlight is a classic, neutral, real-world use case
• DQ-03: Appropriate Scale (2/4) - Stock price at 140–220 is plausible; but Risk Zone at 60–80 is unrealistically far below the trading range — a risk zone threshold of 60–80 has no meaningful relationship to a stock trading at 140–220

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Clean linear structure: imports → data → plot → save
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set
• CQ-03: Clean Imports (2/2) - Only os, sys, numpy, pygal, Style — all used
• CQ-04: Code Elegance (2/2) - Clean and readable; polygon span approach is well-reasoned
• CQ-05: Output & API (1/1) - Saves plot-{THEME}.png and plot-{THEME}.html correctly

Library Mastery (5/10)

• LM-01: Idiomatic Usage (3/5) - Uses pygal.XY with Style object correctly; fill/stroke options appropriately configured; correct theme token wiring
• LM-02: Distinctive Features (2/5) - Generates interactive HTML output (a pygal-distinctive feature); polygon fill for spans is creative but not a unique pygal capability

Score Caps Applied

• None applied (DE-01=4 > 2, so the "correct but boring" cap does not trigger)

Strengths

• Correct title format "span-basic · pygal · anyplot.ai" and axis labels with units
• Vertical recession span (2008–2009) coincides visually with the stock price decline — good storytelling for that element
• Both PNG and HTML outputs generated correctly; interactive HTML is a genuine pygal advantage
• Reproducibility seed set (np.random.seed(42)); fully deterministic output
• Theme-adaptive backgrounds and text colors correctly implemented with PAGE_BG/INK tokens
• Okabe-Ito palette applied in correct order; first series uses brand green #009E73

Weaknesses

• Dark render: Risk Zone horizontal span becomes nearly opaque dark brown (25% opacity on #1A1A17 background collapses transparency) — loses the semi-transparent highlight appearance entirely; consider using opacity values closer to 0.15 or using CSS-level opacity via pygal's fill-opacity style attribute
• Legend labels truncated ("Recession Peri..." instead of "Recession Period") — pygal is clipping at the legend container width; either shorten series names or configure legend width
• Risk Zone threshold (60–80) is completely disconnected from the stock price range (140–220) — the horizontal span tells no story because the data never enters it; reposition to a value range the data actually overlaps (e.g., 130–150 as a support level)
• Large empty canvas gap between the data range and the risk zone wastes ~40% of the vertical canvas; fixing the risk zone placement will fix this too
• DQ-03: The risk zone values are factually inappropriate for the chosen stock price scale

Issues Found

1. VQ-03 LOW (dark render): Risk Zone span loses transparency in dark theme — the 25% opacity applied to a near-black background produces a near-opaque dark band
   • Fix: Set opacity=".15" in Style or reduce span fill opacity so the dark-mode highlight remains visually soft
2. DE-03 / DQ-03 LOW: Horizontal span at 60–80 is factually disconnected from the stock price data (140–220)
   • Fix: Move Risk Zone to a price range the data actually occupies — e.g., 130–155 (representing a support/floor zone) — so both spans interact with the data line
3. SC-04 / VQ-01 PARTIAL: Legend labels are truncated
   • Fix: Shorten series names (e.g., "Recession" instead of "Recession Period") or use pygal's truncate_legend config to allow longer text

AI Feedback for Next Attempt

Fix three things in order of priority: (1) Move the Risk Zone horizontal span to overlap with the actual data range (130–155 or similar) so the horizontal span has visual and narrative purpose — the data line should pass through or near the highlighted zone. (2) Fix dark-mode transparency — reduce opacity in the Style to ~0.15 or find a way to keep spans visually soft on the dark surface. (3) Shorten legend series names to avoid truncation (e.g., "Recession" and "Risk Zone"). These three changes will significantly improve data storytelling, dark-theme element visibility, and legend readability.

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 chart renders on a warm off-white (#FAF8F1) background. A line chart of stock prices (2006–2016) has two highlighted span regions overlaid: a teal vertical span (#009E73) marking the 2008–2009 Recession Period, and a large salmon horizontal band (#D55E00) marking the Risk Zone (price 60–80). The blue line (#0072B2) shows stock price decline through the recession. Title "span-basic · pygal · anyplot.ai" and axis labels "Year" / "Price ($)" are readable. Grid lines are visible. Legend in top-left shows all three series. All text is readable against the light background.

Dark render (plot-dark.png): The chart renders on a dark near-black (#1A1A17) background. Title, axis labels, tick labels, and legend text all flip to light-colored text — readable against dark background with no dark-on-dark failures. Data colors are identical to the light render (#009E73, #D55E00, #0072B2). The primary issue is that the semi-transparent spans do not create "highlighted region" aesthetics in dark mode: #D55E00 at 25% opacity over #1A1A17 produces a very dark brown-orange rectangle that occupies roughly the bottom 30% of the chart, more resembling a data artifact than a highlight zone. Similarly the #009E73 recession span renders as a murky dark-teal block. Both spans are technically visible but lose their communicative "highlighting" function on dark surfaces.

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

Score: 79/100

Category	Score	Max
Visual Quality	25	30
Design Excellence	10	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	5	10
Total	79	100

Visual Quality (25/30)

• VQ-01: Text Legibility (6/8) — Sizes explicitly set (title=28, label=22, major_label=18, legend=16) but text reads small on the large canvas; legend in top-left is quite tiny
• VQ-02: No Overlap (6/6) — No overlapping elements
• VQ-03: Element Visibility (4/6) — Line and spans visible in light; in dark render spans become opaque murky rectangles that undermine visibility as "highlights"
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette, CVD-safe
• VQ-05: Layout & Canvas (3/4) — Good canvas utilization, minor excess whitespace
• VQ-06: Axis Labels & Title (2/2) — "Year" and "Price ($)" with units
• VQ-07: Palette Compliance (2/2) — First series #009E73, correct Okabe-Ito order, backgrounds #FAF8F1/#1A1A17, chrome flips correctly

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Creative polygon-based span approach; Okabe-Ito palette; but chart looks like a well-configured default, not publication-ready; dark render spans are aesthetically poor
• DE-02: Visual Refinement (2/6) — X and Y guides both on creates a busy grid; no spines removed; minimal visual refinement beyond color tokens
• DE-03: Data Storytelling (4/6) — Strong narrative: recession + risk zone + price decline tells a clear story; viewer immediately understands what happened in 2008–2009

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: vertical span (time period) AND horizontal span (value range) both present
• SC-02: Required Features (4/4) — Semi-transparent fill (opacity=0.25), start/end positions defined, both span directions present, 1–5 spans shown
• SC-03: Data Mapping (3/3) — Years on x-axis, price on y-axis, spans correctly positioned
• SC-04: Title & Legend (3/3) — Title format correct; legend labels: "Recession Period", "Risk Zone", "Stock Price"

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows both vertical and horizontal span types, underlying line data, semi-transparent overlays; minor: could show one more span for 1–5 range coverage
• DQ-02: Realistic Context (5/5) — Stock price chart with recession period and risk zone — real-world, neutral, comprehensible scenario
• DQ-03: Appropriate Scale (4/4) — Stock prices ~130–230, recession decline plausible, risk zone at lower price range — factually coherent

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → data → style → plot → save, no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All imports used; sys path manipulation required for library resolution
• CQ-04: Code Elegance (2/2) — Clean, Pythonic, no fake functionality; polygon span workaround is documented
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html (interactive lib)

Library Mastery (5/10)

• LM-01: Idiomatic Usage (3/5) — Correct use of Style object, XY chart with fill, per-series fill override; misses more distinctive patterns
• LM-02: Distinctive Features (2/5) — Uses pygal's interactive HTML output and fill=True per-series; could further exploit pygal's interactive features (e.g., custom tooltips, value formatting, stroke_style)

Score Caps Applied

• None — DE-01=4 > 2, so the generic/no-refinement cap (75) does not apply; no other caps triggered

Strengths

• Perfect spec compliance: both vertical and horizontal span types correctly implemented
• Strong data storytelling: recession period + risk zone creates an immediately clear financial narrative
• Creative workaround: XY polygon technique correctly simulates native span support pygal lacks
• All theme tokens properly wired; chrome flips correctly in both renders
• Perfect code quality: KISS structure, seed set, clean imports, HTML export included

Weaknesses

• Dark render span aesthetics: semi-transparent spans (#009E73 and #D55E00 at 25% opacity) over #1A1A17 produce opaque dark rectangles that no longer communicate as "highlighted regions" — consider increasing opacity slightly for dark theme or adding a thin stroke outline to the span polygons to preserve their boundary visibility
• Grid is too busy: both x- and y-axis guides active; disable x-guides (show_x_guides=False) and keep only y-guides for a cleaner look
• DE-02 low: no visual refinement beyond basic style tokens; try disabling the dot markers fully, adjusting grid opacity, and reducing visual noise
• LM-02 low: pygal's interactive JS features (tooltip formatting, value_formatter, per-point custom tooltips) are not leveraged

Issues Found

1. DE-02 LOW (2/6): Grid is visually busy with both x and y guides enabled, no spine equivalents removed
   • Fix: Set show_x_guides=False, keep show_y_guides=True only
2. Dark render span visibility: At 25% opacity, Okabe-Ito colors on #1A1A17 become very dark and lose highlight function
   • Fix: Add stroke=True with full-opacity color on span polygons, or conditionally boost span opacity for dark theme (opacity='.35' for dark vs '.25' for light)
3. LM-02 LOW (2/5): Interactive HTML output generated but pygal-specific tooltip/interaction features not used
   • Fix: Use for interactive tooltips; add human_readable=True

AI Feedback for Next Attempt

Improve on three fronts: (1) Visual refinement — disable x-guides (show_x_guides=False), leaving only y-guides; (2) Dark render span quality — the current 25% opacity makes spans look like dark blobs on the dark surface; try adding explicit stroke to the span polygons with to give them a visible boundary, or slightly raise opacity for dark theme; (3) Library mastery — add for interactive tooltip polish and consider . These changes will push DE-02 from 2→4, improve VQ-03 dark render, and raise LM-02 from 2→3.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 2/4

Applied fixes based on AI review feedback.

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

---

🤖 impl-repair

[claude]

AI Review - Attempt 3/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white #FAF8F1 background. Title "span-basic · pygal · anyplot.ai" is displayed in dark text at the top and is clearly readable. The Y-axis label "Price ($)" and X-axis label "Year" are both readable. Tick labels for years (2006–2016) on the x-axis and price values (40–220) on the y-axis are rendered in dark text and are legible. Three series are overlaid: a semi-transparent green vertical span (#009E73, Recession Period 2008–2009), a semi-transparent orange horizontal span (#D55E00, Risk Zone 60–80), and a blue stock price line (#0072B2) with no dots. The legend sits in the top-left and shows all three series, though "Recession Period" is slightly truncated to "Recession Peri..." at the given font size. Subtle dotted y-axis grid lines are present. All text is readable against the light background — no light-on-light failures.

Dark render (plot-dark.png): The background is a warm near-black #1A1A17. Title, axis labels, and tick labels all render in light text and are clearly readable against the dark surface. The data colors are identical to the light render: the green recession span (#009E73), orange risk zone span (#D55E00), and blue stock line (#0072B2) are all present with the same Okabe-Ito colors. The recession span uses a higher opacity (0.45 vs 0.25 in light) to compensate for the dark background — it is noticeably more opaque but the blue stock line remains faintly visible beneath it. The legend text adapts correctly to light-colored text. No dark-on-dark failures detected. Brand green #009E73 remains clearly visible. Both renders pass theme-readability checks.

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

Score: 86/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	12	20
Spec Compliance	14	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	8	10
Total	86	100

Visual Quality (28/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 32px, axis labels 22px, tick labels 18px, legend 18px; all readable in both themes
• VQ-02: No Overlap (6/6) — No text or element collisions in either render
• VQ-03: Element Visibility (5/6) — Spans and line clearly visible; recession span at 0.45 opacity in dark render is slightly heavier than spec's recommended 0.2–0.3 range
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe; vertical and horizontal spans distinguished by both position and color
• VQ-05: Layout & Canvas (3/4) — Good canvas use; the Risk Zone sits at 60–80 while stock data is at 135–215, leaving the lower third of the chart as relatively empty space
• VQ-06: Axis Labels & Title (2/2) — "Year" (x) and "Price ($)" (y) with units
• VQ-07: Palette Compliance (2/2) — First series #009E73, second #D55E00, third #0072B2; backgrounds #FAF8F1 / #1A1A17; chrome adapts correctly in both renders

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Clean warm background, correct palette, no dot markers, y-guides only — clearly above library defaults but not publication-exceptional
• DE-02: Visual Refinement (3/6) — Good grid choices (dotted y-only), show_dots=False; pygal's fixed SVG border frame limits further spine removal
• DE-03: Data Storytelling (4/6) — Recession narrative is impactful and clearly told through the highlighted span coinciding with a sharp price drop; Risk Zone context is less compelling since stock never enters it during the period shown

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct: span regions highlighted via closed polygon fills on an XY line chart
• SC-02: Required Features (4/4) — Semi-transparent fills, vertical span (x-axis range), horizontal span (y-axis range), underlying data visible through spans
• SC-03: Data Mapping (3/3) — X-axis: Year (2006–2016); Y-axis: Price ($); both span directions correctly mapped
• SC-04: Title & Legend (2/3) — Title format correct; legend renders "Recession Peri..." (truncated) due to pygal's legend width constraints

Data Quality (14/15)

• DQ-01: Feature Coverage (6/6) — Both span directions (vertical + horizontal) demonstrated; overlaid on real time-series data
• DQ-02: Realistic Context (5/5) — Financial stock price with 2008–2009 recession and risk-zone threshold — neutral, real-world scenario
• DQ-03: Appropriate Scale (3/4) — Stock price range and recession period are realistic; Risk Zone (60–80) is below the stock's entire observed range (135–215), making it a less meaningful threshold for the data shown

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat structure: imports → data → style → chart → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42)
• CQ-03: Clean Imports (2/2) — All imports used; sys used for path workaround
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; sys.path workaround has clear comment; per-point dict labels are idiomatic
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Correct use of pygal.XY, Style object, fill=True/fill=False per series, render_to_png() + render() for HTML
• LM-02: Distinctive Features (4/5) — HTML interactive export, per-point dict labels with "label" key for hover tooltips, human_readable=True, closed polygon approach for native axvspan-style spans (pygal-specific workaround), adaptive SPAN_OPACITY between themes

Score Caps Applied

• None — all caps conditions clear

Strengths

• Correct Okabe-Ito palette with #009E73 as first series; both renders use proper theme backgrounds
• Elegant closed-polygon approach to create span regions within pygal's XY chart (no native axvspan)
• Per-point dict labels enable interactive HTML tooltips — leverages pygal's distinctive interactivity
• Font sizes all explicitly set to correct pixel values; fully readable in both light and dark
• Clean, flat code structure with reproducible seed and no over-engineering

Weaknesses

• Legend text truncated: "Recession Period" renders as "Recession Peri..." — series name or legend sizing needs adjustment
• Recession span opacity in dark render (0.45) exceeds the spec's 0.2–0.3 recommendation; stock line barely visible through it
• Risk Zone (60–80) is positioned below the stock data range (135–215), making the horizontal span feel disconnected from the actual data narrative — consider raising it to ~130–160 or adjusting the y-axis range
• Lower third of canvas is mostly empty dead space due to the mismatch between the span range and data range

Issues Found

1. SC-04 MINOR: Legend truncates "Recession Period" to "Recession Peri..."
   • Fix: Shorten the series label to "Recession (2008–09)" or increase legend_font_size and chart margins
2. VQ-03 MINOR: Dark render spans are at opacity 0.45, slightly above the 0.2–0.3 spec target
   • Fix: Lower SPAN_OPACITY for dark theme to 0.35 max
3. DQ-03 MINOR: Risk Zone at 60–80 is below the entire price range visible in the chart
   • Fix: Adjust risk zone bounds or y-axis floor so the threshold is meaningful relative to the data

AI Feedback for Next Attempt

(No next attempt needed — this is Attempt 3/3 and the score meets the ≥70 threshold.) If regenerating: raise the Risk Zone bounds to overlap with actual stock data for a more compelling story; shorten the "Recession Period" label to avoid legend truncation; reduce dark-theme span opacity to ≤0.35.

Verdict: APPROVED