feat(seaborn): implement span-basic

[github-actions]

Implementation: span-basic - python/seaborn

Implements the python/seaborn version of span-basic.

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

Parent Issue: #980

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot displays on a warm off-white #FAF8F1 background. A green (#009E73) line shows monthly sales from 2006 to 2011, overlaid with an orange vertical span (Recession 2008–2009, #D55E00 at alpha 0.25) and a blue horizontal span (Target Zone 120–140, #0072B2 at alpha 0.20). The title "span-basic · seaborn · anyplot.ai" is clearly displayed in dark text at the top. Axis labels "Month" (x) and "Sales (thousands $)" (y) are readable with year ticks on x-axis and value ticks on y-axis. The legend sits in the upper left with colored boxes. All text is clearly readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot renders on a warm near-black #1A1A17 background. The green line (#009E73) remains identical to the light render. The orange span now appears as a dark burnt-orange due to alpha blending on the dark background, and the blue horizontal span appears as a deep navy — both expected behaviors of alpha blending with the dark surface. The title, axis labels, tick labels, and legend text are all rendered in light color and are clearly readable against the dark background. No dark-on-dark failures detected. Data colors are identical to the light render — only chrome (background, text) flips. Legibility verdict: PASS.

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

Score: 86/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — Title 24pt, labels 20pt, ticks 16pt, legend 16pt all explicitly set; readable in both themes
• VQ-02: No Overlap (6/6) — No text collisions; legend placement avoids data
• VQ-03: Element Visibility (6/6) — linewidth=3 makes the green line clearly visible through semi-transparent spans; spans themselves are appropriately sized
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette; CVD-safe; line distinguishable from both span overlays
• VQ-05: Layout & Canvas (4/4) — Data fills canvas 2006–2011, tight_layout applied, nothing cut off
• VQ-06: Axis Labels & Title (2/2) — "Sales (thousands $)" includes units; "Month" is descriptive
• VQ-07: Palette Compliance (2/2) — Line is #009E73 (position 1); spans use #D55E00 (position 2) and #0072B2 (position 3) in correct order; backgrounds #FAF8F1/#1A1A17 correct; chrome theme-adaptive in both renders

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured library default with correct Okabe-Ito colors, L-shaped spine frame, and appropriate typography hierarchy. Clean and professional but not publication-ready; no distinctive design flourishes beyond standard best practices.
• DE-02: Visual Refinement (4/6) — Good refinement: top/right spines removed, y-axis-only grid at alpha=0.10 (very subtle), legend with themed background/edge, spine colors set to INK_SOFT. Clearly above library defaults.
• DE-03: Data Storytelling (4/6) — The combination of vertical span (recession period) and horizontal span (target zone) with the recovery line tells a clear story: sales dipped below target during the recession and recovered. Viewer immediately reads the narrative. Score elevated above default (2) for the meaningful scenario and visual hierarchy but no span labels or annotations to guide the viewer explicitly.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: span plot with both vertical (x-axis period) and horizontal (y-axis threshold) highlighted regions overlaid on line data
• SC-02: Required Features (4/4) — Semi-transparent fills (alpha 0.20–0.25 ✓), 2 span regions (within 1–5 ✓), underlying data visible through spans ✓
• SC-03: Data Mapping (3/3) — Vertical span correctly mapped to x-axis datetime range; horizontal span to y-axis value range; line data correctly positioned
• SC-04: Title & Legend (3/3) — Title exact format span-basic · seaborn · anyplot.ai; legend labels descriptive: "Recession (2008–2009)", "Target Zone (120–140)"

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows both vertical spans (time periods) AND horizontal spans (value thresholds); demonstrates the full range of the plot type per spec
• DQ-02: Realistic Context (5/5) — Monthly sales revenue with recession marking and target threshold: a neutral, real-world business scenario that matches the spec's example exactly
• DQ-03: Appropriate Scale (4/4) — Sales 80–160 thousand $, recession dip of ~30 units, target zone 120–140: all plausible and internally consistent; 60-month range appropriate

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → theme tokens → data → plot → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All five imports (os, matplotlib.pyplot, numpy, pandas, seaborn) are used
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; appropriate complexity; no over-engineering or fake UI elements
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png; no deprecated API calls

Library Mastery (4/10)

• LM-01: Idiomatic Usage (3/5) — Uses sns.lineplot() and sns.set_theme() idiomatically. The core visualization features (axvspan, axhspan) are matplotlib primitives — correct tool choice since seaborn lacks span functions, but the seaborn contribution is thin beyond the line and theme.
• LM-02: Distinctive Features (1/5) — No distinctively seaborn features leveraged beyond sns.lineplot and sns.set_theme. The span rendering is entirely matplotlib. Could use seaborn FacetGrid, statistical annotations, or seaborn-specific aesthetic features to differentiate.

Score Caps Applied

• None — No caps triggered (DE-01=4, DE-02=4, neither ≤2 simultaneously; VQ-02/03 > 0; CQ-04 > 0)

Strengths

• Perfect spec compliance: both vertical and horizontal spans demonstrated with appropriate alpha, correct title format, and meaningful legend labels
• Flawless theme adaptation in both renders — correct backgrounds, chrome tokens applied throughout, no dark-on-dark failures
• Excellent data quality: the recession-dipping-below-target narrative is immediately comprehensible and matches spec examples
• Clean, readable code with explicit font sizes and seed set

Weaknesses

• Design excellence is good but not publication-ready (DE-01=4): no distinctive visual touches like span text labels (spec says optional), subtle edge lines on span boundaries, or typographic refinements
• Library mastery is limited (LM-01=3, LM-02=1): only sns.lineplot and sns.set_theme are seaborn-specific; spans are matplotlib primitives — consider adding a seaborn-specific element like sns.despine(), statistical annotations, or regplot for trend context
• DE-03 at 4/6: the story is good but no span labels (e.g., "Recession" text inside the orange band or "Target" inside the blue band) that would make the reading even clearer without needing the legend

Issues Found

1. LM-02 LOW (1/5): No distinctively seaborn features used beyond sns.lineplot
   • Fix: Add a seaborn-specific element — for example, a regplot trend line or annotate the spans with ax.text() labels inside the shaded regions
2. DE-01 MODERATE (4/8): Plot is clean but not publication-ready
   • Fix: Add text labels inside span regions (e.g., "Recession" centered in the orange band, "Target Zone" in the blue band), use slightly more refined whitespace, or use sns.despine() instead of manual spine removal for idiomatic seaborn
3. DE-03 MODERATE (4/6): Story is implicit; explicit span labels would elevate clarity
   • Fix: Add ax.text() centered within each span region (at mid-point of x-range for vertical span, at mid-point of y-range for horizontal span) with the label; this also improves LM score

AI Feedback for Next Attempt

Improve Library Mastery and Design Excellence together: (1) Replace manual spine removal with sns.despine() for idiomatic seaborn; (2) Add text labels inside each span region using ax.text() — a "Recession" label centered in the orange vertical band and a "Target Zone" label in the blue horizontal band — this eliminates legend ambiguity and boosts storytelling (DE-03) while being a seaborn/matplotlib technique that demonstrates design thinking (DE-01, LM-02); (3) Consider adding a subtle regplot or sns.regplot trend overlay to show the underlying growth trend through the recession. These changes address the 4-point gap to reach ≥90.

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 is rendered on a warm off-white background (#FAF8F1). The title "span-basic · seaborn · anyplot.ai" appears clearly in dark ink at the top. An orange vertical span (Okabe-Ito #D55E00, alpha 0.25) covers the recession period 2008–2009, and a blue horizontal span (Okabe-Ito #0072B2, alpha 0.20) covers the target zone y=120–140. The brand green (#009E73) monthly sales line (linewidth=3) runs through the full 2006–2011 time range, clearly visible through both semi-transparent spans. The legend in the upper left is clean and readable. Axis labels: "Month" (x) and "Sales (thousands $)" (y) with proper tick labels at 16pt. The sales line shows a clear dip during the recession period followed by recovery. Top and right spines are removed; a subtle y-axis grid (alpha=0.10) is present. All text — title, axis labels, tick labels, legend — is clearly readable against the warm off-white background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on a warm near-black (#1A1A17) background. The title renders in light text, clearly readable against the dark surface. Both spans retain their Okabe-Ito data colors (orange recession span, blue target zone) — identical to the light render as expected. The brand green line is identical and clearly visible. Tick labels and axis labels appear in soft light color (INK_SOFT = #B8B7B0 for dark theme), readable against the dark background. The legend has an elevated-dark background (#242420) with appropriate light text. No dark-on-dark failures observed — no near-black text on near-black background. All chrome elements correctly flip for the dark theme while data colors remain constant. Legibility verdict: PASS.

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

Score: 88/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — Title 24pt, axis labels 20pt, ticks 16pt, legend 16pt, all explicitly set; readable in both themes
• VQ-02: No Overlap (6/6) — Legend in upper left clear of data; tick labels well-spaced; no collisions
• VQ-03: Element Visibility (6/6) — Spans, line, and legend all clearly visible; alpha levels appropriate
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette; CVD-safe; orange/blue/green remain distinguishable
• VQ-05: Layout & Canvas (4/4) — 16:9 canvas well-utilized; balanced margins; tight_layout prevents clipping
• VQ-06: Axis Labels & Title (2/2) — "Sales (thousands $)" with units; "Month" for time axis
• VQ-07: Palette Compliance (2/2) — First series (line) = #009E73; spans use Okabe-Ito positions 2 & 3; backgrounds #FAF8F1 / #1A1A17; both renders theme-correct

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Above default; Okabe-Ito colors applied thoughtfully with meaningful narrative (recession + recovery + target zone); clear visual intent but still recognizably standard seaborn styling
• DE-02: Visual Refinement (3/6) — Top/right spines removed; subtle grid (alpha=0.10); clean legend with elevated background; above default but not exceptional polish
• DE-03: Data Storytelling (4/6) — Strong narrative: sales dip during recession is visually obvious; dual-span approach (vertical for time period, horizontal for value threshold) demonstrates the spec type meaningfully and guides the viewer's attention

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct span plot with both vertical and horizontal span variants
• SC-02: Required Features (4/4) — Vertical span (2008–2009), horizontal span (120–140), semi-transparent alpha (0.25 / 0.20), underlying data visible through spans
• SC-03: Data Mapping (3/3) — Time on x-axis, sales values on y-axis; spans cover specified ranges
• SC-04: Title & Legend (3/3) — Title "span-basic · seaborn · anyplot.ai" ✓; legend labels match span definitions

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Demonstrates both vertical (time-period) and horizontal (value-threshold) span types; underlying data clearly visible through spans
• DQ-02: Realistic Context (5/5) — Monthly sales revenue with 2008–2009 recession period and target zone; historically grounded, business context, neutral topic
• DQ-03: Appropriate Scale (4/4) — Sales 80–160 (thousands $) over 5 years; realistic recession dip and recovery; np.random.seed(42) for reproducibility

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → theme tokens → data → plot → style → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ✓
• CQ-03: Clean Imports (2/2) — os, matplotlib.pyplot, numpy, pandas, seaborn — all used
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; appropriate complexity; no fake UI or over-engineering
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png; current API used

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5) — Axes-level API (preferred); sns.set_theme with rc params for theme adaptation; proper use of ax= parameter; clean seaborn idioms
• LM-02: Distinctive Features (2/5) — Seaborn's theme system and lineplot used well; span overlays necessarily use matplotlib primitives (sns has no native axvspan/axhspan equivalent); library contribution is primarily in theme management and the line plot

Score Caps Applied

• None — no criterion scored 0; DE-01=5 > 2 and DE-02=3 > 2 (no 75 cap); CQ-04=2 (no 70 cap)

Strengths

• Complete theme adaptation: all chrome tokens (background, ink, ink-soft, elevated-bg) correctly flip for both light and dark renders; no dark-on-dark failures
• Strong data narrative: the recession dip is visually compelling and the dual-span approach (vertical time period + horizontal value threshold) demonstrates both span directions as required by the spec
• Perfect spec and data quality: all required features present, realistic business context, reproducible data generation
• Clean code structure with explicit font sizes, correct Okabe-Ito ordering, and proper seaborn theme setup

Weaknesses

• Design excellence remains modest: while spines are removed and grid is subtle, the overall aesthetic is still standard seaborn output; no distinctive typographic choices, custom tick formatting (e.g., year-only x-ticks), or extra whitespace refinement
• Library mastery is constrained by the plot type: seaborn has no native span primitives, so axvspan/axhspan are handled by matplotlib directly; the seaborn contribution beyond theming is limited to the lineplot

Issues Found

1. DE-01 MODERATE: Styling is functional but not exceptional — custom rc parameters and Okabe-Ito colors are required by platform, not unique design choices
   • Fix: Add custom x-axis tick formatting (e.g., year-only labels), refine legend typography, or add a subtle background gradient or border treatment to distinguish the aesthetic
2. LM-02 LOW: seaborn's distinctive features underutilized — the span overlays are pure matplotlib
   • Fix: Consider using sns.despine() for cleaner spine removal, or leverage seaborn's statistical estimation capabilities (e.g., add a confidence band via sns.lineplot's errorbar parameter to show uncertainty)

AI Feedback for Next Attempt

The implementation is solid and passes Attempt 2 threshold. Primary improvement area is Design Excellence: add custom date tick formatting (show years only, not months), refine the legend placement or remove the box frame, and consider leveraging seaborn's sns.despine() and statistical features to earn higher LM-02 marks.

Verdict: APPROVED