feat(plotly): implement gauge-basic

[github-actions]

Implementation: gauge-basic - python/plotly

Implements the python/plotly version of gauge-basic.

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

Parent Issue: #857

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The gauge displays on a warm off-white #FAF8F1 background. A semi-circular gauge chart titled "Sales Target Achievement" occupies the upper two-thirds of the canvas, with the subtitle "gauge-basic · plotly · anyplot.ai" in lighter gray beneath the title. Three color zones arc across the gauge: vermillion (#D55E00) from 0–30%, orange (#E69F00) from 30–70%, and bluish green (#009E73) from 70–100%. A thick black arc (using INK token #1A1A17) runs from 0% to 72%, covering the inner portion of the zone arcs. A tick-mark threshold indicator sits at 72%. Percentage tick labels (0%–100% at every 10%) surround the perimeter. The value "72%" is displayed in large dark text centered below the gauge. All text is clearly readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on a near-black #1A1A17 background. The title and subtitle render in light text (#F0EFE8 / #B8B7B0), clearly readable. The three zone colors are identical to the light render (vermillion, orange, green — data colors unchanged). The indicator bar arc now renders as a cream/off-white color (INK = #F0EFE8 in dark mode), creating a light band covering the inner zone area. Tick labels and the "72%" value are rendered in light text and are fully legible. No dark-on-dark text failures. Legibility verdict: PASS.

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

Score: 84/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set (title 32px, subtitle 22px, number 96px, ticks 18px); readable in both themes
• VQ-02: No Overlap (6/6) — Perimeter tick labels well-spaced, no collisions
• VQ-03: Element Visibility (5/6) — Zone arcs visible on outer rim; thick indicator bar (thickness=0.18) covers the inner portion of zones, reducing their visual area
• VQ-04: Color Accessibility (2/2) — Okabe-Ito stand-ins for bad/caution/good; CVD-safe
• VQ-05: Layout & Canvas (3/4) — Gauge fills upper 60% well; lower half canvas is empty (inherent to semi-circular type)
• VQ-06: Axis Labels & Title (2/2) — "Sales Target Achievement" is descriptive; tick labels carry % suffix
• VQ-07: Palette Compliance (2/2) — Backgrounds are #FAF8F1 / #1A1A17; zone colors use Okabe-Ito (semantic ordering justified); all chrome is theme-adaptive

Design Excellence (9/20)

• DE-01: Aesthetic Sophistication (4/8) — Thoughtful semantic color mapping (Okabe-Ito as bad/caution/good stand-ins) is a nice touch; but overall appearance is a default plotly Indicator gauge with correct colors applied — not notably polished
• DE-02: Visual Refinement (2/6) — Explicit margins and theme tokens are set; beyond that this is the default plotly gauge aesthetic. The thick bar arc (0.18 thickness) dominates the dial face and creates visual clutter rather than refinement
• DE-03: Data Storytelling (3/6) — The gauge communicates a KPI in context: three zones tell a good/caution/bad story; the large "72%" and the threshold marker emphasize that the value just cleared the goal threshold. Functional storytelling, but no zone labels or callout to highlight the significance of crossing 70%

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Semi-circular gauge using go.Indicator(mode="gauge+number") — correct type
• SC-02: Required Features (4/4) — Value, min/max range, thresholds at [30, 70], three color zones, arc indicator, numeric display — all present
• SC-03: Data Mapping (3/3) — value=72, min=0, max=100 matches spec example exactly
• SC-04: Title & Legend (3/3) — "gauge-basic · plotly · anyplot.ai" present as subtitle; no legend needed for single-value gauge

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all features of a basic gauge: range, zones, threshold marker, numeric readout
• DQ-02: Realistic Context (5/5) — "Sales Target Achievement" quarterly KPI is a real, neutral business scenario
• DQ-03: Appropriate Scale (4/4) — 0–100% scale with 72% current and 30/70 zone boundaries are realistic

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Imports → tokens → data → plot → save; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic (hardcoded scalar values)
• CQ-03: Clean Imports (2/2) — Only os and plotly.graph_objects imported and used
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; appropriate complexity for a single-trace gauge
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; uses current plotly API

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct use of go.Indicator with mode="gauge+number", gauge.steps, gauge.threshold, and gauge.axis; HTML formatting in title is plotly-idiomatic
• LM-02: Distinctive Features (3/5) — go.Indicator is a plotly-native chart type unavailable in most other libraries; HTML-in-title formatting leverages plotly's string rendering

Score Caps Applied

• None — No caps triggered (DE-01=4 > 2, so the "DE-01 ≤ 2 AND DE-02 ≤ 2" cap does not apply)

Strengths

• Perfect spec compliance and data quality: exact example values, all required features (value, range, zones, threshold marker), realistic business scenario
• Thoughtful semantic color assignment: Okabe-Ito vermillion/orange/green as bad/caution/good stand-ins, all CVD-safe
• Flawless code quality: KISS structure, fully deterministic, clean imports, correct outputs
• Both renders are theme-correct and fully legible (backgrounds #FAF8F1 / #1A1A17, all chrome tokens adapted)

Weaknesses

• Indicator bar thickness=0.18 is too wide — the black/cream arc dominates the dial face and covers the inner portion of the color zones, reducing their visual impact and making the gauge look heavy
• Design sophistication is limited to default plotly Indicator styling with correct colors; no visual refinement beyond explicit margins and theme tokens
• No zone labels or emphasis element to guide viewer interpretation (e.g., a label or annotation indicating "Above Target" or highlighting that 72% crossed the 70% threshold)

Issues Found

1. DE-02 LOW: Indicator bar is too thick (0.18) — creates a heavy black/cream band that obscures the inner zone areas and dominates the visual
   • Fix: Reduce bar.thickness to 0.05–0.08 for a slim arc indicator, letting the zone colors breathe; alternatively add a narrow needle-style marker at the current value instead
2. DE-01 LOW: Default plotly gauge appearance with no aesthetic polish beyond colors and margins
   • Fix: Add a subtle legend or zone labels inside/outside the gauge, refine the bgcolor of the gauge face, adjust border styling, or use a custom font to lift the design above default
3. DE-03: Zone context exists but lacks emphasis on the threshold-crossing story
   • Fix: Add a small annotation below the gauge like "✓ Target Exceeded" or label the threshold lines at 30% and 70% with their names (e.g., "At Risk", "On Track", "Exceeds Target")

AI Feedback for Next Attempt

Reduce bar thickness to 0.06 or less so the Okabe-Ito zone colors are fully visible across their entire width — the zones are the main storytelling element and they shouldn't be covered by the indicator arc. Add zone threshold labels (e.g., "At Risk | On Track | Exceeds Target") either as gauge axis text or as small annotations to guide interpretation and increase design sophistication. Consider a thin-line tick needle at the value instead of a filled arc for cleaner aesthetics. The code quality and spec compliance are already perfect — focus all effort on visual polish and storytelling.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/3

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): A semi-circular speedometer gauge on a warm off-white #FAF8F1 background, titled "Sales Target Achievement" in bold dark text (32px), with the subtitle "gauge-basic · plotly · anyplot.ai" in lighter text below. The gauge arc is divided into three color zones: vermillion (#D55E00) from 0–30%, amber (#E69F00) from 30–70%, and bluish green (#009E73) from 70–100%. A slim black needle and a threshold marker both point to 72%. The large central numeric display shows 72% in dark text. Below the arc, a three-item zone legend row uses colored bullet chips (●) matching each zone's color with labels "At Risk 0–30%", "On Track 30–70%", and "Exceeds Target 70–100%". A green-bordered callout box at the bottom reads "✓ Target Exceeded · 72% surpasses the 70% goal". All text is clearly readable against the light background; no light-on-light issues.

Dark render (plot-dark.png): The same layout on a warm near-black #1A1A17 background. The gauge's elevated background region shifts to #242420. The slim needle and threshold marker flip to off-white (#F0EFE8) for theme contrast. The three zone colors (vermillion, amber, bluish green) are identical to the light render — data colors do not change. The title, subtitle, and numeric "72%" display are all rendered in light text and are clearly readable against the dark surface. Tick labels, zone legend text, and callout text all adapt to lighter tones. No dark-on-dark failures observed.

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

Score: 94/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 32px, ticks 18px, value 96px, annotations 18–24px. Readable in both themes.
• VQ-02: No Overlap (6/6) — No overlapping elements. Tick marks at 10% intervals are well-spaced.
• VQ-03: Element Visibility (6/6) — Gauge zones vivid, needle + threshold marker clearly visible, value display prominent.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito CVD-safe colors used for all three zones; zones distinguishable without relying on hue alone.
• VQ-05: Layout & Canvas (4/4) — Gauge fills ~60% of canvas, balanced margins, zone legend and callout well-placed below.
• VQ-06: Axis Labels & Title (2/2) — Descriptive title; gauge axis ticks carry "%" suffix via ticksuffix.
• VQ-07: Palette Compliance (2/2) — Zone colors are Okabe-Ito positions 1, 2, and 5 (green, vermillion, amber); backgrounds are #FAF8F1 (light) and #1A1A17 (dark); all chrome tokens adapt correctly.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (5/8) — Deliberate design choices: CVD-safe zone colors instead of cliché red/green/yellow, slim needle (thickness=0.06) to keep zone colors unobscured, color-coded legend chips, callout box framing the insight. Above a configured default (4), but not quite publication-ready (6+).
• DE-02: Visual Refinement (4/6) — No unnecessary clutter, explicit margins, elevated-bg on gauge interior and callout box, subtle gauge border. Refinement is evident though relies heavily on Plotly's built-in gauge renderer.
• DE-03: Data Storytelling (5/6) — The "✓ Target Exceeded" callout with green border immediately communicates the insight; zone labels ("At Risk / On Track / Exceeds Target") provide instant context; threshold marker at 72% creates visible proof of exceedance. Viewer grasps the story without analysis.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Semi-circular gauge chart using go.Indicator(mode="gauge+number").
• SC-02: Required Features (4/4) — Single value, min/max range, thresholds at [30, 70] creating three color zones, prominent value display, needle indicator, threshold line.
• SC-03: Data Mapping (3/3) — value=72, min=0, max=100, thresholds=[30, 70] all correctly mapped.
• SC-04: Title & Legend (3/3) — Title "Sales Target Achievement" with subtitle "gauge-basic · plotly · anyplot.ai" in the required format; zone legend clearly labeled.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all gauge aspects: value, range, three threshold zones, needle, numeric display, callout.
• DQ-02: Realistic Context (5/5) — Quarterly sales target achievement (72% vs. 70% goal) is a genuine, neutral business scenario.
• DQ-03: Appropriate Scale (4/4) — 0–100% range with thresholds at 30%/70% and a value of 72% are entirely realistic for KPI dashboards.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: constants → data → plot → layout → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — All data hardcoded; deterministic by nature.
• CQ-03: Clean Imports (2/2) — Only os and plotly.graph_objects.
• CQ-04: Code Elegance (2/2) — Clean and Pythonic; comments explain non-obvious choices (slim needle rationale, zone legend intent).
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html with current Plotly API.

Library Mastery (10/10)

• LM-01: Idiomatic Usage (5/5) — go.Indicator with mode="gauge+number" is the canonical Plotly pattern for gauges. write_image() + write_html() per library conventions.
• LM-02: Distinctive Features (5/5) — go.Indicator gauge with steps (color zones), threshold (indicator line), and bar (needle) is Plotly-exclusive — cannot be replicated in matplotlib/seaborn without custom arc drawing.

Score Caps Applied

• None — no caps triggered.

Strengths

• CVD-safe Okabe-Ito zone colors instead of the conventional red/green palette — accessible and on-brand
• Slim needle (thickness=0.06) keeps zone colors fully visible while still indicating position
• "✓ Target Exceeded" callout box with threshold-line context creates immediate data storytelling
• Perfect theme adaptation: all chrome tokens (INK, INK_SOFT, ELEVATED_BG, PAGE_BG) propagate correctly to both renders
• Full spec compliance with clean, idiomatic Plotly code

Weaknesses

• DE-01 has room to grow: the gauge ring styling is Plotly-native with minimal customization beyond colors; stronger typographic contrast or a custom gauge ring style could push toward publication-ready
• DE-02: the canvas could benefit from a subtle typographic variation in the value annotation or a secondary context annotation to add visual depth

Issues Found

1. DE-01 MODERATE: Design is above defaults but not publication-ready. The gauge ring styling is Plotly-native with minimal customization beyond colors.
   • Improvement: Consider bolder typographic hierarchy for the value display, or a secondary annotation with context to elevate visual sophistication.

AI Feedback for Next Attempt

Implementation is well-executed and approvable. If iterating further: (1) increase typographic contrast between the "72%" value and supporting annotations for stronger visual hierarchy; (2) explore a custom ring or background treatment to feel less like a library default. These are refinements, not blockers.

Verdict: APPROVED