feat(bokeh): implement gauge-basic

[github-actions]

Implementation: gauge-basic - python/bokeh

Implements the python/bokeh version of gauge-basic.

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

Parent Issue: #857

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The gauge is displayed on a warm off-white #FAF8F1 background. The semi-circular arc is divided into three distinct zones: vermillion/orange (0–30, low), golden-orange (30–70, mid), and brand green (70–100, high), using Okabe-Ito positions 2, 5, and 1 respectively. Tick marks and labels (0, 25, 50, 75, 100) appear in dark grey (INK_SOFT) around the outer edge of the arc. A black triangular needle points to approximately 72, positioned just past the 70 threshold inside the green zone. A dark circular hub sits at the center of the semicircle. The bold value "72" is displayed prominently below the gauge. The title "gauge-basic · bokeh · anyplot.ai" appears at the top in dark ink. All text is clearly readable against the light background — no light-on-light failures.

Dark render (plot-dark.png): The same gauge is rendered on a warm near-black #1A1A17 background. The three zone colors are identical to the light render (vermillion, golden-orange, brand green) — only chrome flips. The needle is now white/cream (#F0EFE8 = INK in dark mode), clearly visible against the dark background. The center hub is light with a dark ring. Tick labels and the "72" value are rendered in light-colored INK_SOFT. The title text is light-colored and readable. No dark-on-dark failures observed — all text is clearly legible against the near-black surface.

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

Score: 87/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — Title 44pt, tick labels 30pt, value 84pt; all explicitly set, readable in both themes
• VQ-02: No Overlap (6/6) — No collisions; tick labels at 0 and 100 positions are near canvas edges but non-overlapping
• VQ-03: Element Visibility (6/6) — All arcs, needle, hub, tick marks, and labels clearly visible at scale
• VQ-04: Color Accessibility (2/2) — Okabe-Ito zone colors are CVD-safe; zones differ sufficiently in hue and luminance
• VQ-05: Layout & Canvas (3/4) — Gauge semicircle and value well-positioned; lower canvas has significant empty space below the 72 label
• VQ-06: Axis Labels & Title (2/2) — Title "gauge-basic · bokeh · anyplot.ai" correct; no axis labels needed for gauge
• VQ-07: Palette Compliance (2/2) — Brand green #009E73 assigned to high zone (semantically correct); background #FAF8F1/#1A1A17 correct; chrome flips correctly in both renders; data colors identical across themes

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (4/8) — Intentional Okabe-Ito zone color assignment, clean minimal chrome, large bold value label. Well-configured but not publication-ready — no zone labels, no contextual subtitle, limited visual hierarchy
• DE-02: Visual Refinement (4/6) — Axes and grid hidden (correct for gauge), PAGE_BG used as zone separator border (nice detail), hub styled with INK/PAGE_BG contrast for theme adaptation. Good refinement above defaults
• DE-03: Data Storytelling (3/6) — Needle clearly in the green zone communicates a positive reading; "72" reinforces it. Missing: zone labels (Low/Mid/High), context text (e.g., target or unit), or any annotation that turns raw value into insight

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct semi-circular speedometer gauge
• SC-02: Required Features (4/4) — value=72, min=0, max=100, thresholds=[30,70], three color zones, needle, center hub, tick marks with labels, prominent value display — all present
• SC-03: Data Mapping (3/3) — Value 72 correctly mapped to angular position; just past 70 threshold into green zone
• SC-04: Title & Legend (3/3) — Title format correct; N/A for legend (single value, no series)

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Demonstrates all core gauge features: semi-circular arc, three semantic color zones, needle indicator, tick scale, value readout
• DQ-02: Realistic Context (5/5) — Value of 72 on a 0–100 scale is plausible for sales performance, NPS, or completion rate; neutral business context
• DQ-03: Appropriate Scale (4/4) — 0–100 range with thresholds at 30 and 70 is a standard gauge configuration; value 72 falls interestingly just past the upper threshold

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat structure: theme tokens → data → geometry → figure → zones → ticks → needle → labels → save
• CQ-02: Reproducibility (2/2) — Deterministic hardcoded values; no randomness needed
• CQ-03: Clean Imports (2/2) — os, numpy, and only used bokeh modules
• CQ-04: Code Elegance (2/2) — annular_wedge used idiomatically (replaces verbose manual polygon patching); zip(..., strict=True) is clean; no fake UI
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — annular_wedge is the correct Bokeh primitive for arc segments; Label model for annotations; proper theme token wiring via figure properties. Solid idiomatic usage
• LM-02: Distinctive Features (3/5) — annular_wedge is Bokeh-native (other libraries would require different primitives); dual output via export_png + output_file/save. Uses Bokeh-specific model layer (Label)

Score Caps Applied

• None

Strengths

• Perfect spec compliance: all gauge features (zones, needle, hub, ticks, value) present and correctly implemented
• Excellent code quality: idiomatic use of annular_wedge, flat KISS structure, clean theme token wiring
• Full theme adaptation: needle, hub, text, and background all adapt correctly between light and dark renders
• Okabe-Ito zone colors used semantically (brand green for high/good zone) — CVD-safe and visually coherent

Weaknesses

• Design storytelling is minimal: no zone labels ("Low" / "Med" / "High"), no contextual subtitle, no annotation explaining what 72 means — the viewer sees a value but not a narrative
• Lower canvas quadrant is largely empty; the gauge composition could be enlarged or supplemented with context text to fill the space more purposefully
• DE-01 does not yet reach "strong design" level: no subtitle, no zone annotations, visual hierarchy limited to needle position and bold value

Issues Found

1. DE-03 LOW (3/6): No zone labels or contextual framing — the gauge displays a value but doesn't guide interpretation
   • Fix: Add zone labels ("Low" / "Med" / "High") inside the arcs or as annotations near zone midpoints; optionally add a subtitle like "Q4 Sales Performance — Target: ≥ 70"
2. DE-01 MODERATE (4/8): Design is clean but not publication-ready — missing typography refinement and contextual hierarchy
   • Fix: Add a subtitle or unit annotation below the value (e.g., "/ 100 pts"); use INK_MUTED for tick labels and reserve INK for the value and title for clearer hierarchy
3. VQ-05 MINOR (3/4): Significant empty space below the value label
   • Fix: Slightly reduce the bottom y_range margin or move the value label closer to the gauge center; alternatively add a unit or context label in the vacant space

AI Feedback for Next Attempt

The core gauge is solid. To reach 90+: (1) Add zone labels — position them inside the arcs at midpoints (e.g., "Low" at ~15°, "Med" at ~90°, "High" at ~165° from center-left) using Label with text_color=PAGE_BG for readability on the colored arcs. (2) Add a subtitle line below the main value ("/ 100 pts" or "Q4 Sales Performance") in INK_MUTED to give context. (3) Tighten the y_range bottom margin to reduce empty space below the "72" label. These changes turn a technically correct gauge into one that tells a story.

Verdict: REJECTED