feat(altair): implement dumbbell-basic

[github-actions]

Implementation: dumbbell-basic - python/altair

Implements the python/altair version of dumbbell-basic.

File: plots/dumbbell-basic/implementations/python/altair.py

Parent Issue: #945

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white background (~#FAF8F1). It shows a horizontal dumbbell chart with 10 employee departments on the Y-axis and satisfaction scores on the X-axis labeled "Employee Satisfaction Score (%)". The "Before policy change" dots are rendered in teal (Okabe-Ito #009E73) and "After policy change" dots in orange. A legend labeled "Policy Change" appears in the top-right corner. Categories are sorted ascending by improvement size, making the storytelling clear. All text (title, axis labels, tick marks, legend) is dark and clearly readable against the light background. The dashed vertical grid lines are somewhat prominent but not overpowering. Legibility verdict: PASS — however, the images appear to have been generated from a different version of the code than what is currently in the file (see Weaknesses).

Dark render (plot-dark.png): The plot renders on a near-black background (~#1A1A17). The data colors — teal for "Before" and orange for "After" — are identical to the light render, confirming correct Okabe-Ito invariance. Title and all text elements appear in light color, readable against the dark background. The legend shows a dark elevated background with light text. No dark-on-dark failures visible. Legibility verdict: PASS — with the same caveat that images appear to be from a different code version than the current file.

Critical discrepancy noted: The current code specifies colors #306998 (Python blue) and #FFD43B (Python yellow) with legend title "Period" and saves to plot.png/plot.html — none of which matches what the images show. The images appear to have been generated from an earlier, corrected version of the implementation.

Score: 75/100

Category	Score	Max
Visual Quality	23	30
Design Excellence	10	20
Spec Compliance	13	15
Data Quality	14	15
Code Quality	9	10
Library Mastery	6	10
Total	75	100

Visual Quality (23/30)

• VQ-01: Text Legibility (6/8) — Font sizes explicitly set (labelFontSize=18, titleFontSize=22, legend 16); images show readable text in both themes
• VQ-02: No Overlap (5/6) — No visible overlap; slight tightness on Y-axis labels for longer department names
• VQ-03: Element Visibility (5/6) — mark_circle(size=350) is well-chosen for 10 categories; connecting lines readable
• VQ-04: Color Accessibility (2/2) — Images show CVD-safe teal+orange; both distinguishable without relying solely on hue
• VQ-05: Layout & Canvas (3/4) — Canvas proportions good; legend floats somewhat isolated in top-right corner
• VQ-06: Axis Labels & Title (2/2) — "Employee Satisfaction Score (%)" is descriptive with units
• VQ-07: Palette Compliance (0/2) — FAIL: Code specifies #306998 (Python blue) and #FFD43B (Python yellow) — both non-Okabe-Ito. First series must be #009E73. Additionally, the code has no ANYPLOT_THEME support and saves to plot.png/plot.html instead of plot-{THEME}.png/plot-{THEME}.html

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured library default; sorted order is intentional but no custom typography, no refined palette in code
• DE-02: Visual Refinement (2/6) — Dashed grid lines (gridDash=[4, 4]) violate style guide (solid preferred); no explicit spine removal; minimal chrome customization
• DE-03: Data Storytelling (4/6) — Sorting by improvement (ascending) is a good storytelling choice; viewer immediately sees which departments improved least vs. most

Spec Compliance (13/15)

• SC-01: Plot Type (5/5) — Correct dumbbell chart: mark_rule for connecting lines + mark_circle for dots, horizontal orientation, categories on Y-axis
• SC-02: Required Features (4/4) — Two dots per category, connecting line, distinct colors, sorted by difference ✓
• SC-03: Data Mapping (3/3) — Categories on Y, values on X, scale domain [45, 90] covers all data [52–85]
• SC-04: Title & Legend (1/3) — Code title uses "pyplots.ai" instead of "anyplot.ai"; legend title is generic "Period" instead of contextual "Policy Change"; extra "Employee Satisfaction" prefix is acceptable but compounds the domain error

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows varied differences (IT +5 to Customer Support +26); sorted order reveals the pattern; one outlier (IT shows slight improvement)
• DQ-02: Realistic Context (5/5) — Employee satisfaction before/after policy changes is realistic, neutral, business-plausible
• DQ-03: Appropriate Scale (4/4) — Scores 52–85 on a 100-point scale are sensible for HR satisfaction data

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) — Clean top-level: imports → data → reshape → chart layers → save
• CQ-02: Reproducibility (2/2) — Hardcoded deterministic data; no random seed needed
• CQ-03: Clean Imports (2/2) — Only altair and pandas imported, both used
• CQ-04: Code Elegance (2/2) — Elegant layer composition (lines + dots); alt.X2 for span encoding is idiomatic
• CQ-05: Output & API (0/1) — Saves as plot.png/plot.html instead of plot-{THEME}.png/plot-{THEME}.html; no ANYPLOT_THEME env var handling at all

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5) — Correct use of mark_rule + mark_circle layer composition; alt.X2 for horizontal span; EncodingSortField for consistent sort across layers
• LM-02: Distinctive Features (2/5) — HTML export and tooltips leverage Altair's interactive nature; layer composition for dumbbell is the key Altair-specific pattern; otherwise fairly generic

Score Caps Applied

• None applied (DE-01=4 > 2, so the "correct but boring" cap does not trigger)

Strengths

• Layer composition (mark_rule + mark_circle) is the correct Altair idiom for dumbbell charts — using alt.X / alt.X2 for the spanning rule is exactly right
• Sorting by improvement with EncodingSortField applied consistently across both layers is technically sound
• Employee satisfaction before/after is a realistic, neutral, engaging dataset
• Font sizes explicitly set throughout (labelFontSize, titleFontSize, legendFontSize)
• 10 categories sorted by difference creates genuine data storytelling

Weaknesses

• Critical: No ANYPLOT_THEME support — code must read os.getenv("ANYPLOT_THEME", "light") and render both light and dark versions with theme-adaptive tokens (PAGE_BG, ELEVATED_BG, INK, INK_SOFT) applied via .configure_view(fill=PAGE_BG), .configure_axis(labelColor=INK_SOFT, ...), .configure_title(color=INK), .configure_legend(...)
• Critical: Wrong output file names — must save as plot-{THEME}.png and plot-{THEME}.html, not bare plot.png/plot.html
• Wrong palette — colors must use Okabe-Ito: #009E73 (before) and #D55E00 (after), not Python blue/yellow
• Wrong branding — title must end with anyplot.ai not pyplots.ai
• Dashed grid — gridDash=[4, 4] should be removed; use solid grid lines with low opacity (gridOpacity≈0.10) or no grid at all
• Legend title — "Period" should be more contextual (e.g., "Policy Change")
• Connecting lines — hardcoded color="#999999" should use INK_SOFT token for theme adaptation

Issues Found

1. CRITICAL — CQ-05 / VQ-07: No theme adaptation. Add ANYPLOT_THEME = os.getenv("ANYPLOT_THEME", "light") and full chrome token setup; save as plot-{THEME}.png and plot-{THEME}.html
2. VQ-07: Colors #306998 and #FFD43B must be replaced with Okabe-Ito #009E73 (before) and #D55E00 (after)
3. SC-04: Change pyplots.ai → anyplot.ai in title; update legend title from "Period" to something contextual
4. DE-02: Replace gridDash=[4, 4] with gridOpacity=0.10 (solid, subtle); or remove grid entirely for this sparse dataset
5. VQ-07 chrome: connecting line color #999999 should be INK_SOFT token; add configure_view(fill=PAGE_BG)

AI Feedback for Next Attempt

Replace the entire chart configuration section with proper ANYPLOT_THEME support: read the env var, define PAGE_BG/ELEVATED_BG/INK/INK_SOFT tokens, use Okabe-Ito colors (#009E73 and #D55E00), apply theme tokens to configure_view/configure_axis/configure_title/configure_legend, use INK_SOFT for the connecting rule color, save as plot-{THEME}.png and plot-{THEME}.html. Fix title to end with anyplot.ai. Remove dashed grid (gridDash) and use gridOpacity=0.10 instead for a subtle solid grid.

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): The chart renders on a warm off-white background (~#FAF8F1). It is a horizontal dumbbell chart with 10 department categories on the Y-axis (IT, R&D, Legal, Operations, Finance, HR, Marketing, Sales, Engineering, Customer Support), sorted ascending by improvement from top to bottom. The X-axis is labeled "Employee Satisfaction Score (%)" with a range of 45–90. Connecting lines are thin gray rules. The two dot series use a teal/green color for "Before" and orange for "After". The legend in the top-right is titled "Policy Change" with "Before"/"After" labels. Title reads "Employee Satisfaction · dumbbell-basic · altair · anyplot.ai". All text — title, axis labels, tick labels, and legend — is clearly readable against the light background. No dark-on-light failures.

Dark render (plot-dark.png): The chart renders on a warm near-black background (~#1A1A17). Layout is identical to the light render. Title, axis labels, and tick labels appear in light/white text, clearly readable against the dark background. Legend box has a dark fill with light text. The data dot colors (teal/green for Before, orange for After) are visually identical to the light render — only the chrome (background, text, legend frame) has adapted to dark mode. No dark-on-dark text failures observed. Connecting lines appear as mid-gray and remain visible. Both renders pass the theme-readability check.

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

Score: 79/100

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

Visual Quality (25/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set (labelFontSize=18, titleFontSize=22, titleFontSize=28); all text readable in both themes
• VQ-02: No Overlap (6/6) — No overlapping text or elements
• VQ-03: Element Visibility (5/6) — Dots at size=350 are visible; connecting lines clear
• VQ-04: Color Accessibility (2/2) — Positional encoding provides CVD-safe differentiation independent of hue
• VQ-05: Layout & Canvas (3/4) — Good horizontal layout; some whitespace at left/right edges
• VQ-06: Axis Labels & Title (2/2) — X-axis has "Employee Satisfaction Score (%)" with units
• VQ-07: Palette Compliance (0/2) — FAIL: Code uses #306998 (Python Blue) and #FFD43B — explicitly non-compliant per quality criteria. First series must be #009E73. Also, no ANYPLOT_THEME environment variable handling in code; theme adaptation appears to work in rendered output but is not explicitly implemented.

Design Excellence (9/20)

• DE-01: Aesthetic Sophistication (4/8) — Looks like a well-configured library default; sorting is intentional but typography and color design are minimal
• DE-02: Visual Refinement (2/6) — Grid uses dashed lines (gridDash=[4, 4]) contradicting style guide preference for solid; gridOpacity=0.3 exceeds the 10-15% guideline; no spine removal configured
• DE-03: Data Storytelling (3/6) — Sorting by difference is a strong storytelling choice that reveals clear ranking; but no annotations, no emphasis on biggest/smallest gap

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct horizontal dumbbell chart with mark_rule connecting dots
• SC-02: Required Features (4/4) — Two dots per category, thin connecting line, distinct colors, horizontal orientation, sorted by difference
• SC-03: Data Mapping (3/3) — Categories on Y, scores on X, color encodes Before/After
• SC-04: Title & Legend (2/3) — Image shows correct "anyplot.ai" domain but code has "pyplots.ai" — this will produce wrong title on future re-runs. Legend labels present and correct.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all dumbbell chart aspects: varied gap sizes, direction (all increase), connecting lines, 10 categories
• DQ-02: Realistic Context (5/5) — Employee satisfaction before/after policy changes is a neutral, realistic business scenario
• DQ-03: Appropriate Scale (4/4) — Scores in 52–85 range are realistic for satisfaction scores

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) — Clean top-level flow: imports → data → chart → save
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data
• CQ-03: Clean Imports (2/2) — Only altair and pandas imported, both used
• CQ-04: Code Elegance (2/2) — Appropriate use of pd.melt(), mark_rule with x2, and layer composition
• CQ-05: Output & API (0/1) — Saves to plot.png and plot.html — must be plot-{THEME}.png and plot-{THEME}.html. No ANYPLOT_THEME reading.

Library Mastery (10/10)

• LM-01: Idiomatic Usage (4/5) — Good use of mark_rule with alt.X2 for connecting lines, alt.EncodingSortField, and layer composition via + operator
• LM-02: Distinctive Features (3/5) — Layer composition, alt.X2 horizontal span encoding, and encoding-level sort are features distinctive to Altair's grammar-of-graphics approach

Score Caps Applied

• None

Strengths

• Correct dumbbell chart structure using idiomatic Altair layer composition (mark_rule + mark_circle)
• Excellent data storytelling through sorting by improvement magnitude
• Realistic, neutral business scenario with varied gap sizes
• Proper use of alt.X2 for horizontal span — exactly the right Altair idiom for this chart type
• Both renders pass theme-readability check visually

Weaknesses

• Code uses non-Okabe-Ito colors (#306998, #FFD43B): replace with Okabe-Ito positions 1 and 2 (#009E73 for Before, #D55E00 for After)
• No ANYPLOT_THEME handling: must read os.getenv("ANYPLOT_THEME", "light") and set PAGE_BG, ELEVATED_BG, INK, INK_SOFT tokens following the altair.md template
• Wrong output filenames: must save as plot-{THEME}.png and plot-{THEME}.html, not plot.png/plot.html
• Wrong domain in title: code has "pyplots.ai" — must be "anyplot.ai"
• Grid styling: change gridDash=[4, 4] to no dash (solid lines), reduce gridOpacity from 0.3 to 0.10 per style guide
• Connecting line color: hardcoded "#999999" must use INK_SOFT token for theme adaptation

Issues Found

1. VQ-07 FAIL: Non-Okabe-Ito colors — #306998 (Python Blue) is explicitly listed as non-compliant
   • Fix: Use range=["#009E73", "#D55E00"] for Before/After colors
2. CQ-05 FAIL: Wrong output filenames + no ANYPLOT_THEME
   • Fix: Add full theme handling block from altair.md, save as chart.save(f'plot-{THEME}.png', scale_factor=3.0) and chart.save(f'plot-{THEME}.html')
3. SC-04 WARN: Title contains "pyplots.ai" in code — fix to "anyplot.ai"
4. DE-02 LOW: Dashed grid at 30% opacity — fix to solid grid at 10% opacity (gridOpacity=0.10, remove gridDash)
5. DE-01/DE-03 LOW: No visual sophistication beyond sorting — consider using color/size emphasis on the widest-gap entry

AI Feedback for Next Attempt

Fix the three blocking issues first: (1) Replace colors with Okabe-Ito — range=["#009E73", "#D55E00"]; (2) Add full ANYPLOT_THEME handling block exactly as shown in altair.md (PAGE_BG, INK, INK_SOFT tokens through configure_view/configure_axis/configure_title/configure_legend); (3) Fix output filenames to plot-{THEME}.png. Then fix title domain "pyplots.ai" → "anyplot.ai", change gridDash to solid (remove gridDash param) and gridOpacity to 0.10, and set line color to use INK_SOFT token. For design points, consider using strokeWidth=3 on the connecting line and alpha contrast or a subtle annotation on the Customer Support row (largest gap).

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 2/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 3/3

Image Description

Light render (plot-light.png): The chart renders on a warm off-white (#FAF8F1) background. The title "Employee Satisfaction · dumbbell-basic · altair · anyplot.ai" appears in dark ink at top-left, clearly readable. Ten horizontal dumbbell entries are shown, sorted by improvement difference (IT at top with smallest gain, Customer Support at bottom with largest). Green dots (#009E73) mark the "Before" values and orange dots (#D55E00) mark the "After" values, each with a subtle PAGE_BG-colored stroke halo. A thin, semi-transparent gray connecting line links each pair. Category labels on the Y-axis (e.g., "IT", "R&D", "Customer Support") are dark and readable. The X-axis label "Employee Satisfaction Score (%)" is clearly legible. A legend in the top-right corner titled "Policy Change" correctly labels Before and After. All text is readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The chart renders on a warm near-black (#1A1A17) background. The title appears in light-colored text, clearly readable against the dark surface. Category labels, tick labels, and the X-axis label all appear as light text — no dark-on-dark failures observed. The data dot colors are identical to the light render (#009E73 green and #D55E00 orange), confirming only the chrome (background, text, grid) flips between themes. The connecting lines are similarly subtle. The legend box uses an elevated dark fill (#242420) with light-colored label and title text. All text is readable against the dark background. Legibility verdict: PASS.

Both renders are theme-correct. No legibility failures in either theme.

Score: 89/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	7	10
Total	89	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set (title=28, axis=22, ticks=18, legend=16); both themes fully readable
• VQ-02: No Overlap (6/6) — 10 categories evenly spaced on Y-axis; no label collisions
• VQ-03: Element Visibility (6/6) — Dots size=420 with stroke halo; connecting lines strokeWidth=3 at 55% opacity
• VQ-04: Color Accessibility (2/2) — Okabe-Ito positions 1+2 (#009E73 vs #D55E00); high contrast, CVD-safe
• VQ-05: Layout & Canvas (4/4) — 4800×2700px canvas (1600×900 @ 3x); chart fills canvas well; legend not overlapping data
• VQ-06: Axis Labels & Title (2/2) — X-axis "Employee Satisfaction Score (%)" includes units; Y-axis title=None is acceptable for labeled categories
• VQ-07: Palette Compliance (2/2) — Before=#009E73 (position 1), After=#D55E00 (position 2); backgrounds #FAF8F1 / #1A1A17 correct; both renders theme-correct

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Above the configured-default look: dot stroke halos add polish, Okabe-Ito applied correctly, layout is clean. Not exceptional: no focal point or emphasis on the most/least improved category.
• DE-02: Visual Refinement (4/6) — configure_view(stroke=None) removes border; gridOpacity=0.10 is very subtle; connecting line opacity=0.55 prevents visual clutter. Solid refinement, not flawless.
• DE-03: Data Storytelling (3/6) — Sorting by difference ascending reveals the pattern (Customer Support improved most, IT least), which is meaningful. However, all dots are the same size and there is no visual emphasis on the extremes; viewer must find the insight themselves.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct horizontal dumbbell/connected dot plot
• SC-02: Required Features (4/4) — Two distinct-color dots per category, thin connecting line, sorted by difference, horizontal orientation
• SC-03: Data Mapping (3/3) — Categories on Y-axis, score values on X-axis; all 10 categories shown
• SC-04: Title & Legend (3/3) — Title contains spec-id (dumbbell-basic), library (altair), anyplot.ai; legend labels "Before"/"After" with "Policy Change" title

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all dumbbell aspects: paired endpoints, connecting lines, multiple categories, variation in differences (6–26 pts)
• DQ-02: Realistic Context (5/5) — Employee satisfaction before/after policy changes; neutral business scenario; all department names generic and inoffensive
• DQ-03: Appropriate Scale (4/4) — Score range 45–90 with data 52–85%; realistic for employee satisfaction surveys; 10 categories appropriate

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → constants → data → chart layers → configure → save; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data
• CQ-03: Clean Imports (2/2) — os, altair, pandas — all used
• CQ-04: Code Elegance (2/2) — Clean layer composition; pd.melt for long-form conversion is appropriate; no over-engineering
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (scale_factor=3.0) and plot-{THEME}.html

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — mark_rule with x+x2 encoding for range lines is the correct Altair idiom; layer composition and configure_* API all used properly; EncodingSortField is Altair-specific
• LM-02: Distinctive Features (3/5) — mark_rule with x2 for dumbbell connector and layer composition are distinctively Altair approaches; tooltips are native. Could go further with interactive selection highlighting or more Altair-specific transforms.

Score Caps Applied

• None

Strengths

• Perfect visual quality across both themes: all font sizes explicitly set, correct Okabe-Ito palette, correct backgrounds, readable in both light and dark modes
• Excellent use of Altair's layer composition (mark_rule + mark_circle) with the idiomatic x/x2 encoding for connecting lines
• Clean KISS code structure with pd.melt for proper long-form data; dot stroke halos add professional polish
• Fully spec-compliant: horizontal orientation, sorted by difference, correct title format, distinct colors for Before/After

Weaknesses

• DE-03: Sorting reveals the pattern but there is no visual emphasis on the extremes — color contrast variation, a size differential on the largest-gain category, or a subtle annotation would help the viewer immediately see the story
• DE-01: The overall design is clean but flat — all categories are presented with equal visual weight; a focal point (e.g., slightly larger or brighter dot for the max-difference row) would elevate sophistication
• LM-02: The implementation uses Altair's correct dumbbell idiom but misses an opportunity to use Altair-specific transforms (e.g., calculate transform for diff labels) or interactive selection for highlighting individual dumbbells

Issues Found

1. DE-03 LOW: The sort-by-difference is a good choice but the visual hierarchy is flat — all dumbbells are identical in weight and emphasis.
   • Fix: Use color saturation, opacity, or size to highlight the highest/lowest difference row; or use an Altair calculate transform to add difference labels at the right end of each dumbbell
2. DE-01 MODERATE: No focal point or narrative emphasis; chart looks functional but not distinctive.
   • Fix: Introduce subtle emphasis — e.g., a slightly different marker size for the top/bottom row, or a thin reference line at a key threshold value

AI Feedback for Next Attempt

To reach 90+: add visual emphasis for the most-improved and least-improved categories (size variation, opacity boost, or a difference label at the end of each dumbbell via Altair's calculate transform). The sort order is correct — now make the story visible without the viewer having to search for it. Remove the grid from the Y-axis (currently both axes get gridlines; only vertical X-axis gridlines are needed for value reading on a horizontal chart).

Verdict: REJECTED