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): Warm off-white background (#FAF8F1) — correct anyplot light surface. Bold title "Sales Target Achievement" clearly readable in dark ink; subtitle "gauge-basic · python · plotly · anyplot.ai" in softer secondary ink, readable. Tick labels from 0% to 100% at 10pp intervals are legible. The three gauge arcs are clearly defined: matte red (#AE3030) for 0–30% At Risk, amber (#DDCC77) for 30–70% On Track, and brand green (#009E73) for 70–100% Exceeds Target. A thin dark needle and threshold line mark 72%. The large "72%" center display at fontsize=48 is the clear focal point. Below: green "+2pp vs. 70% goal" delta annotation, three color-chip zone legend, and a bordered "✓ Target Exceeded" callout box — all readable. All text clearly legible against the light background.

Dark render (plot-dark.png): Warm near-black background (#1A1A17) — correct anyplot dark surface. Title "Sales Target Achievement" renders in near-white (#F0EFE8) ink, clearly readable. Subtitle in lighter secondary ink, readable. Tick labels in #B8B7B0 (INK_SOFT dark) are visible against the near-black surface — no dark-on-dark failure. Zone arc colors are identical to the light render (matte red, amber, brand green — theme-invariant data colors as required). Needle and threshold line render as near-white (#F0EFE8), clearly visible against the dark background. The "72%" center display, delta annotation, zone legend, and callout box all adapt correctly to dark chrome. No dark-on-dark text failures observed.

Both renders fully reviewed. Theme adaptation is correct in both.

Score: 88/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All fonts explicitly sized; readable in both themes at full resolution. Minor: annotation text at fontsize=10–11 (40–44 source px) is at the lower bound for 400 px mobile thumbnails.
• VQ-02: No Overlap (6/6) — No text-on-text or text-on-data collisions; zone legend chips evenly spaced; delta/callout vertically stacked with clear separation.
• VQ-03: Element Visibility (6/6) — All arcs clearly visible; slim needle (thickness=0.06) doesn't obscure zones; threshold line at 72% distinct.
• VQ-04: Color Accessibility (1/2) — Red and green arcs are primary zone distinction; text labels provide redundancy, but deuteranopes lose the arc color difference. Direct arc labels or shape redundancy would fully resolve.
• VQ-05: Layout & Canvas (4/4) — 3200×1800 landscape (canvas gate passed); gauge domain well-proportioned; bottom section uses paper coords cleanly; no overflow or clipping.
• VQ-06: Axis Labels & Title (2/2) — Gauge axis dtick=10 with ticksuffix='%'; descriptive title; spec-id subtitle present.
• VQ-07: Palette Compliance (2/2) — Zone colors use Imprint semantic anchors (#AE3030 risk, #DDCC77 caution, #009E73 success); page backgrounds #FAF8F1 / #1A1A17; data colors identical across renders.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Intentional hierarchy: 72% as focal point, delta as secondary insight, zone legend + callout as supporting context. HTML-formatted title, slim needle, Imprint palette semantic anchors. Above default.
• DE-02: Visual Refinement (4/6) — ELEVATED_BG for gauge interior and callout box adds depth. Slim needle minimizes arc coverage. Callout box border in brand green is polished. Above default.
• DE-03: Data Storytelling (4/6) — Delta "+2pp vs. 70% goal" creates immediate benchmark; callout "✓ Target Exceeded" delivers a clear narrative; zone colors guide interpretation. Not maximum: threshold line and needle overlap slightly at the 72% mark.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — go.Indicator with mode="gauge+number" and shape="angular" implements the semi-circular speedometer gauge.
• SC-02: Required Features (4/4) — Semi-circular gauge, three color zones at [30, 70] thresholds, needle + threshold indicator, prominent value display — all present.
• SC-03: Data Mapping (3/3) — value=72, min=0, max=100, thresholds=[30, 70] match the spec example. Axis range correctly configured.
• SC-04: Title & Legend (3/3) — "{Descriptive Title} · gauge-basic · python · plotly · anyplot.ai" format correct. Zone legend with labeled color chips covers each region.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Demonstrates all gauge chart features: zone regions, needle indicator, threshold line, value display, delta context, zone legend, and callout narrative.
• DQ-02: Realistic Context (5/5) — "Sales Target Achievement" at 72% vs. 70% goal is a plausible, neutral business KPI — one of the spec's listed applications.
• DQ-03: Appropriate Scale (4/4) — 0–100% range with 30/70 thresholds; value 72 just above goal creates meaningful context.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat script; no functions or classes; linear flow.
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data; no random elements.
• CQ-03: Clean Imports (2/2) — Only os and plotly.graph_objects — both used.
• CQ-04: Code Elegance (2/2) — Appropriate complexity; no fake interactivity.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (3200×1800) and plot-{THEME}.html; current API.

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — go.Indicator with mode="gauge+number" is Plotly's native gauge; HTML title strings are idiomatic. Missed: the built-in delta parameter (mode="gauge+number+delta") would be more idiomatic than the custom y=0.22 annotation for the +2pp display.
• LM-02: Distinctive Features (3/5) — Uses Plotly-specific: go.Indicator type, HTML-formatted title, gauge steps + threshold line config, write_html for interactive output. Missed the native delta reference line and built-in delta rendering.

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required gauge features present: semi-circular shape, three color zones, needle + threshold line at value, large prominent value display
• Correct Imprint palette usage: semantic zone colors use palette anchors (matte red #AE3030 / amber #DDCC77 / brand green #009E73) — exactly the traffic-light semantic exception the style guide documents
• Excellent theme adaptation — INK tokens correctly propagate to needle color, gauge border, tick labels, and all annotations; no dark-on-dark text failures in either render
• Rich data storytelling: delta annotation, three-chip zone legend, and callout box create a clear KPI narrative well beyond the bare gauge
• Clean, readable code: flat script, fully deterministic data, only used imports, correct PNG+HTML output

Weaknesses

• Missing Plotly's built-in delta parameter: mode="gauge+number+delta" with delta={"reference": goal, "valueformat": ".0f", "suffix": "pp"} would be more idiomatic than the custom annotation at y=0.22
• Red (#AE3030) and green (#009E73) are the sole zone-color distinction; while text labels provide some redundancy, direct arc labels or redundant encoding would improve CVD accessibility for deuteranopes
• Annotation texts at fontsize=10–11 (40–44 source px after scale=4) approach the mobile readability floor at 400 px display width; bumping to fontsize=12 would help

Issues Found

1. LM-01 MILD: Custom delta annotation instead of Plotly's built-in delta parameter
   • Fix: Change mode="gauge+number" to mode="gauge+number+delta" and add delta={"reference": goal, "relative": False, "valueformat": "+.0f", "suffix": "pp", "font": {"size": 14, "color": INK}} in the Indicator — then remove the manual y=0.22 annotation
2. VQ-04 MINOR: Red/green zone-color distinction without redundant encoding for CVD users
   • Fix: The text zone legend already helps; consider adding direct arc labels or bumping the amber zone border width to create a visible boundary between zones

AI Feedback for Next Attempt

Solid implementation with excellent spec coverage and theme handling. To reach higher LM scores: use mode="gauge+number+delta" with the built-in delta parameter instead of a custom annotation — this is the idiomatic Plotly pattern for showing reference deltas on Indicator charts. For the zone legend, consider whether direct arc segment labels (rendered as annotations positioned on the arc midpoints) would be clearer than the bottom chip legend. Minor: bump annotation fontsize from 10–11 to 12 for better mobile thumbnail readability.

Verdict: APPROVED

[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 #FAF8F1 background. Bold title "Sales Target Achievement" in dark ink at top center, with the spec signature "gauge-basic · python · plotly · anyplot.ai" in smaller muted gray below — both lines fully readable. Semicircular gauge arc spans the upper portion with three clearly distinct color zones: #AE3030 Imprint matte red (0–30% At Risk), #DDCC77 Imprint amber (30–70% On Track), and #009E73 Imprint brand green (70–100% Exceeds Target). A slim dark needle points radially to 72%, and a bold threshold marker sits on the arc at that value. Center of gauge shows large "72%" in dark ink with a green "▲2pp vs. goal" delta below. Below the gauge, a zone legend row shows three color-coded bullet chips with range labels. A "✓ Target Exceeded · 72% surpasses the 70% goal" callout box with green border sits at the bottom. All text is clearly readable against the light background.

Dark render (plot-dark.png): Warm near-black #1A1A17 background. Title and subtitle adapt to light off-white (#F0EFE8) and muted light gray (#B8B7B0) respectively — all chrome flipped correctly. Data zone arc colors are identical to the light render (#AE3030 / #DDCC77 / #009E73) — only chrome swapped. Needle, threshold marker, "72%" number, and delta indicator adapt to light-colored text. Zone legend bullets retain their Imprint data colors. Callout box uses dark elevated background (#242420) with the same green border. Gauge tick labels (0%–100%) are in light muted gray. No dark-on-dark failures observed — all text is readable against the dark background.

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	15	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	9	10
Total	94	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set (number=48, delta=13, title=16, gauge ticks=10, annotations=12); well-proportioned at 3200×1800; readable in both themes
• VQ-02: No Overlap (6/6) — No definitive overlap; zone legend items at x=0.50/0.80 are close but text is readable in both renders
• VQ-03: Element Visibility (6/6) — Gauge arcs, needle, threshold marker, center value, delta, zone legend, and callout box are all clearly visible
• VQ-04: Color Accessibility (2/2) — CVD-safe Imprint palette; amber zone buffers red and green; zone labels provide redundant encoding
• VQ-05: Layout & Canvas (4/4) — Gauge domain [0.05,0.95]×[0.30,0.95] fills canvas well; zone legend and callout fill lower region; balanced margins
• VQ-06: Axis Labels & Title (2/2) — Descriptive title; gauge ticks use '%' suffix; zone labels include ranges (0–30%, 30–70%, 70–100%)
• VQ-07: Palette Compliance (2/2) — Zone colors use Imprint palette via valid semantic exception (red=At Risk, amber=On Track, green=Exceeds Target); backgrounds #FAF8F1/#1A1A17; all chrome theme-adaptive

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: semantic zone colors, delta indicator with direction-sensitive colors, color-coded zone legend, styled callout box — clearly above defaults; falls just short of FiveThirtyEight-level publication-ready
• DE-02: Visual Refinement (4/6) — Good refinement: slim needle (thickness=0.06), elevated gauge background, styled callout box with green border and padding; some further polish possible
• DE-03: Data Storytelling (5/6) — Excellent storytelling: current value + delta (+2pp) + color zones + "Target Exceeded" callout create an immediate, unambiguous narrative; viewer instantly grasps performance status

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct gauge chart using go.Indicator with mode="gauge+number+delta" and angular (semicircular) shape
• SC-02: Required Features (4/4) — All spec features present: value=72, min=0, max=100, thresholds=[30,70], three color zones (red/amber/green), prominent value display, needle + threshold indicator
• SC-03: Data Mapping (3/3) — Single-value gauge correctly mapped; range, thresholds, and current value all accurately represented
• SC-04: Title & Legend (3/3) — Two-line indicator title: "Sales Target Achievement" (bold descriptive) + "gauge-basic · python · plotly · anyplot.ai" (spec signature); zone legend labels match data zones

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all gauge features: three threshold zones, needle, arc marker, numeric value, delta vs. goal, zone legend with percentage ranges
• DQ-02: Realistic Context (5/5) — Sales target achievement for the quarter — immediately comprehensible business KPI scenario, neutral, not abstract
• DQ-03: Appropriate Scale (4/4) — 0–100% range with thresholds at 30/70 is sensible for a KPI gauge; 72% vs. 70% goal gives accurate +2pp delta; all values internally consistent

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → theme tokens → data → plot → layout → save; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data; no randomness
• CQ-03: Clean Imports (2/2) — Only import os and import plotly.graph_objects as go — both used
• CQ-04: Code Elegance (2/2) — Clean and appropriately complex for a gauge with annotations; no over-engineering; no fake functionality
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (width=800, height=450, scale=4 → 3200×1800) and plot-{THEME}.html; autosize=False; current API

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Expert use of go.Indicator with gauge mode; steps array for zone coloring; threshold dict for arc marker; delta with increasing/decreasing color overrides — all idiomatic Plotly patterns
• LM-02: Distinctive Features (4/5) — go.Indicator with gauge+number+delta combined mode is distinctly Plotly; HTML color spans in indicator title and annotation text; annotation bgcolor/bordercolor/borderpad styling — several Plotly-specific capabilities leveraged

Score Caps Applied

• None — no caps triggered (DE-01=6 and DE-02=4, both >2; all other gate criteria passed)

Strengths

• Semantic zone colors correctly chosen from Imprint palette (#AE3030 red, #DDCC77 amber, #009E73 brand green) using the valid traffic-light semantic exception
• Excellent data storytelling: delta indicator (+2pp vs. goal), color-coded zone legend, and "✓ Target Exceeded" callout box combine to create a clear, immediate narrative
• Both themes handled correctly — all chrome tokens are theme-adaptive, data zone colors are identical across light and dark renders, backgrounds are #FAF8F1 / #1A1A17
• All font sizes explicitly set throughout; well-proportioned at the 3200×1800 canvas
• Idiomatic Plotly usage: go.Indicator with mode="gauge+number+delta", steps for zones, threshold for arc marker, HTML annotations

Weaknesses

• Zone legend annotations (x=0.50 and x=0.80) may have very tight spacing — the longer "Exceeds Target 70–100%" text center-anchored at x=0.80 sits only 0.30 paper-distance from "On Track 30–70%"; consider shifting to x=0.47/x=0.77 or using explicit xanchor="right" and xanchor="left" on the outer chips
• DE-01 moderate gap: design is polished but falls just short of publication-ready — the callout box and zone legend are good but the gauge face itself (arc thickness, inner/outer radius ratio) could be tuned further for visual impact
• DE-02 refinement opportunity: the elevated gauge background adds some depth but the callout annotation could benefit from rounded padding or a slightly larger borderpad for more breathing room

Issues Found

1. DE-01 MODERATE: Design is strong but not yet top-tier — the gauge face proportions and arc styling could be tuned (e.g., adjusting bar.thickness, gauge inner radius) to make it more visually impactful
   • Fix: Consider minor adjustments to arc proportions and potentially increasing the domain height to let the gauge breathe more
2. Zone legend tightness: The "On Track" and "Exceeds Target" annotation chips may overlap at their text bounds
   • Fix: Shift middle chip to x=0.47 with xanchor="right" and right chip to x=0.77 with xanchor="left", or add align="left"/"right" attributes

AI Feedback for Next Attempt

The implementation is strong and approved. If repaired: focus on the zone legend spacing (shift x positions and use explicit xanchor to prevent crowding) and minor gauge face refinement (arc width, domain sizing) to push DE-01 toward 7-8.

Verdict: APPROVED