feat(bokeh): implement span-basic

[github-actions]

Implementation: span-basic - python/bokeh

Implements the python/bokeh version of span-basic.

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

Parent Issue: #980

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (~#FAF8F1). Title "span-basic · bokeh · anyplot.ai" in dark bold ink, large and prominent. Axis labels "Month" and "Revenue (thousands $)" in dark ink; tick labels in muted dark gray. Legend box with warm elevated background showing "Monthly Revenue". Green line (#009E73, BRAND) traces 24 months of revenue (100–145K range) with small scatter markers. Blue vertical span (months 10–12) labeled "Q4 Peak Season" in matching blue text. Orange/golden horizontal span (revenue 120–140K) labeled "Target Range" in amber. Both spans semi-transparent; underlying data fully visible. Subtle grid lines at 10% alpha. All text clearly readable against the light background — no light-on-light issues.

Dark render (plot-dark.png): Near-black background (~#1A1A17). Title in light/white ink, clearly readable. Axis labels in light ink; tick labels in muted light gray. Legend has dark elevated box with readable label. Data colors identical to light render: same green line (#009E73). Blue vertical span appears as deep teal-blue on dark background. Orange horizontal span renders as dark amber/brown at low alpha — still distinguishable with the "Target Range" label in orange text. No dark-on-dark failures detected. All chrome adapts correctly between themes.

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

Score: 85/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 48pt, axis 36pt, ticks 28pt, legend 28pt). Readable in both themes. Minor: title-to-label ratio slightly compressed.
• VQ-02: No Overlap (6/6) — No overlapping text. Span labels clearly positioned in their respective regions.
• VQ-03: Element Visibility (5/6) — Line clearly visible. Scatter markers (size=16) are slightly small for 4800×2700 — appear as small dots.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito throughout, CVD-safe. No red-green only distinctions.
• VQ-05: Layout & Canvas (3/4) — Good canvas utilization (~60–70%), balanced margins.
• VQ-06: Axis Labels & Title (2/2) — Title format correct. Y-axis has units "thousands $".
• VQ-07: Palette Compliance (2/2) — First series #009E73, span colors from Okabe-Ito, backgrounds #FAF8F1/#1A1A17, all chrome theme-correct in both renders.

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured functional default. Intentional Okabe-Ito span colors with matching labels. But plot border retained (outline_line_color=INK_SOFT), no spine removal, design doesn't transcend library defaults.
• DE-02: Visual Refinement (3/6) — Subtle 10% grid is good. However, the box border around the plot area remains, both x and y grids are active (y-only preferred for line charts), and no individual axes are hidden.
• DE-03: Data Storytelling (4/6) — Clear story: revenue trend with Q4 peak season and target range highlighted. Span labels create focal points. Viewer immediately sees the key periods/ranges.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct span/highlighted region plot using Bokeh BoxAnnotation. Both vertical and horizontal spans.
• SC-02: Required Features (4/4) — Semi-transparent fill (alpha 0.2–0.25), both span directions, underlying data visible, span labels, edge lines.
• SC-03: Data Mapping (3/3) — X=Month, Y=Revenue correctly assigned. Vertical span on x-range, horizontal on y-range.
• SC-04: Title & Legend (3/3) — Title "span-basic · bokeh · anyplot.ai" exactly correct. Legend label "Monthly Revenue" appropriate.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Both span directions shown with underlying time series, labels, and semi-transparent fills.
• DQ-02: Realistic Context (5/5) — Monthly revenue business scenario, Q4 peak season, target revenue range — real-world, neutral.
• DQ-03: Appropriate Scale (4/4) — Revenue 100–145K over 24 months with upward trend and seasonality is realistic.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No functions/classes. Linear flow: imports → tokens → data → figure → spans → labels → chrome → save.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used.
• CQ-04: Code Elegance (2/2) — Clean, Pythonic, no over-engineering.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html via current Bokeh API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — ColumnDataSource, BoxAnnotation (canonical Bokeh span model), Label for annotations, and proper export_png/output_file/save trio.
• LM-02: Distinctive Features (3/5) — BoxAnnotation is distinctly Bokeh and HTML export is used. However, HoverTool (Bokeh's signature interactive feature for showing revenue values on hover) is absent — missing the strongest showcase of what makes Bokeh unique vs. static libraries.

Score Caps Applied

• None — no cap conditions triggered.

Strengths

• Correct use of Bokeh BoxAnnotation for both vertical and horizontal span regions
• Perfect spec compliance — both span types with correct alpha, labels, and underlying line data
• Full theme-adaptive chrome with all tokens applied correctly in both renders
• 100% Data Quality — realistic revenue scenario, seed set, both span directions shown
• Perfect code quality — KISS structure, clean imports, reproducible output

Weaknesses

• Plot outline border retained (outline_line_color=INK_SOFT) instead of being removed — set p.outline_line_color = None for L-shaped or borderless look (DE-02)
• Both x and y grids shown — remove x-grid (p.xgrid.grid_line_color = None) for cleaner line chart styling (DE-02)
• Scatter markers size=16 slightly small for 4800×2700 canvas — increase to 20–22 (VQ-03)
• HoverTool not used — adding a tooltip showing Month and Revenue values would showcase Bokeh's distinctive interactive capability over static libraries (LM-02)
• No spine removal on individual axes — hiding top/right axis lines would improve visual polish (DE-01)

Issues Found

1. DE-02 LOW: Box border around plot area retained via outline_line_color=INK_SOFT; x-grid active alongside y-grid.
   • Fix: p.outline_line_color = None; p.xgrid.grid_line_color = None
2. DE-01 BELOW-POTENTIAL: Visual design functional but no spine removal or aesthetic elevation above configured defaults.
   • Fix: Hide top/right border, use y-only grid, consider removing legend box frame (p.legend.border_line_color = None)
3. LM-02 MODERATE: HoverTool absent — the most distinctive Bokeh capability is not used.
   • Fix: Add HoverTool with tooltips showing @x (Month) and @y{0.0} (Revenue) on the line/scatter renderer
4. VQ-03 MINOR: Scatter markers size=16 appear as small dots at full canvas resolution.
   • Fix: Increase to size=20 or size=22

AI Feedback for Next Attempt

Remove the plot outline border (p.outline_line_color = None) and x-axis grid (p.xgrid.grid_line_color = None) for a cleaner line chart. Add a HoverTool with tooltips on the line/scatter to showcase Bokeh's distinctive interactive capability (@x Month, @y{0.0} Revenue). Increase scatter marker size to 20–22. Consider removing the legend border frame for a more refined look. These changes target DE-01, DE-02, and LM-02 which are the primary gaps from 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): Warm off-white background (#FAF8F1), correct. Title "span-basic · bokeh · anyplot.ai" in dark ink at top-left, fully readable. X-axis label "Month" and Y-axis label "Revenue (thousands $)" in dark ink with units. Tick labels in #4A4A44, readable. Legend "Monthly Revenue" in a styled box at top-left. Line in #009E73 (brand green) traces 24 monthly revenue data points with small green scatter markers. Vertical BoxAnnotation in #0072B2 (Okabe-Ito blue) spans months 10–12 with a "Q4 Peak Season" label in blue above the span. A large horizontal BoxAnnotation in #E69F00 (Okabe-Ito orange) spans y=120–140 (upper half of the chart) with a "Target Range" label in darker orange (#B8720B). Semi-transparent fills (alpha 0.2–0.25) keep the data line visible through both spans. Y-only grid at alpha 0.10. All text clearly readable against the light background.

Dark render (plot-dark.png): Warm near-black background (#1A1A17), correct. Title in #F0EFE8, axis labels in #F0EFE8, tick labels in #B8B7B0 — all readable against dark background, no dark-on-dark failures. Data line is identical #009E73 (matches light render exactly). The vertical span renders as a dark teal column (near-black blended with 25% #0072B2), and the "Q4 Peak Season" label in solid #0072B2 has reduced but sufficient contrast against it. The horizontal span renders as a large dark golden-brown band (near-black blended with 20% #E69F00) covering the upper half of the chart; the "Target Range" label in #E69F00 orange has reduced contrast against this golden surface — visible but not ideal. No critical legibility failures; all chrome elements pass the dark-on-dark check.

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

Score: 89/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (6/8) — All font sizes explicitly set (title 48pt, axes 36pt, ticks/labels 28pt). "Target Range" label (orange on orange-tinted span) and "Q4 Peak Season" label (blue on dark-blue span) both readable but contrast is below ideal in dark mode.
• VQ-02: No Overlap (6/6) — No overlapping text elements anywhere.
• VQ-03: Element Visibility (5/6) — Line (width=4) and spans well-proportioned; scatter markers (size=20) slightly small for 4800px canvas.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito throughout, CVD-safe, adequate contrast.
• VQ-05: Layout & Canvas (4/4) — Good canvas utilization, nothing cut off.
• VQ-06: Axis Labels & Title (2/2) — "Revenue (thousands $)" with units, "Month" descriptive.
• VQ-07: Palette Compliance (2/2) — Primary series #009E73, span fills from Okabe-Ito (#0072B2, #E69F00), backgrounds #FAF8F1/#1A1A17, both renders theme-correct.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Thoughtful Okabe-Ito span colors, labeled regions add context, clearly above library defaults. Not publication-ready but well above generic.
• DE-02: Visual Refinement (4/6) — Y-only grid at alpha 0.10, no outline box (outline_line_color=None), L-shaped spines, styled legend. Good refinement.
• DE-03: Data Storytelling (4/6) — Two span types create a clear narrative: Q4 peak season (vertical) + target revenue range (horizontal). Visual hierarchy through labeled colored regions guides the viewer.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct span plot with both vertical and horizontal span types.
• SC-02: Required Features (4/4) — Semi-transparent fills (alpha 0.2–0.25), span labels, optional edge lines all present.
• SC-03: Data Mapping (3/3) — X=Month, Y=Revenue correctly mapped; spans at correct positions.
• SC-04: Title & Legend (3/3) — Title "span-basic · bokeh · anyplot.ai" correct format; legend "Monthly Revenue" correct.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Both span directions demonstrated: vertical (time period) and horizontal (value range).
• DQ-02: Realistic Context (5/5) — Monthly revenue over 2 years, Q4 peak season and target range — neutral business context.
• DQ-03: Appropriate Scale (4/4) — Revenue 99–145K over 24 months with seasonal variation and growth trend. Plausible.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat: imports → data → 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 (os, numpy, bokeh.io, bokeh.models, bokeh.plotting).
• CQ-04: Code Elegance (2/2) — Clean, Pythonic, appropriate complexity.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png + plot-{THEME}.html. Current Bokeh API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — ColumnDataSource, figure(), BoxAnnotation, HoverTool, Label, export_png + output_file + save — expert idiomatic Bokeh usage.
• LM-02: Distinctive Features (4/5) — BoxAnnotation (Bokeh-specific span model), HoverTool with custom tooltips, Label annotations, dual HTML+PNG output — distinctive Bokeh features leveraged well.

Score Caps Applied

• None

Strengths

• Perfect spec compliance: both vertical (Q4 peak season) and horizontal (target range) span types with correct alpha levels and Okabe-Ito span colors
• Idiomatic Bokeh usage: BoxAnnotation (the canonical Bokeh span model), HoverTool, Label annotations, and HTML output alongside PNG
• Realistic business scenario (monthly revenue over 2 years) with plausible values and seed-set reproducibility
• Theme-adaptive chrome thoroughly applied: all six token variables correctly wired to every text and chrome element

Weaknesses

• Span label contrast in dark mode: "Q4 Peak Season" (#0072B2 text on dark-blue span) and "Target Range" (#E69F00 text on golden-brown span) both have reduced contrast against their colored backgrounds in dark mode
• Scatter markers (size=20) slightly small for a 4800px canvas; size 28–32 would be more comfortable at full resolution
• Horizontal span (y=120–140) covers ~65% of the vertical data range, creating a large muted-gold area in dark mode that competes with the line; reducing alpha to 0.15 would improve legibility

Issues Found

1. VQ-01 MINOR: Span label text colors are not sufficiently adapted to their span backgrounds in dark mode — both labels use their span's own fill color as text color, resulting in reduced contrast when rendered on the semi-transparent span surface
   • Fix: Use a higher-contrast color for span labels on dark theme (e.g., INK for text inside the span, or a lighter/darker variant that passes contrast check)
2. VQ-03 MINOR: Scatter markers (size=20) are slightly small at 4800×2700
   • Fix: Increase to size=28 or size=32

AI Feedback for Next Attempt

Span label contrast fix: on dark theme, the span label text colors (#0072B2 and #E69F00) blend into the semi-transparent span backgrounds. Use INK (#F0EFE8) or a higher-contrast variant for span labels in dark mode. Also increase scatter marker size from 20 to 28–30 for better visibility at full 4800px resolution.

Verdict: APPROVED