feat(matplotlib): implement bar-race-animated

[github-actions]

Implementation: bar-race-animated - python/matplotlib

Implements the python/matplotlib version of bar-race-animated.

File: plots/bar-race-animated/implementations/python/matplotlib.py

Parent Issue: #3653

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white #FAF8F1 background. A 2×3 grid of small multiples displays horizontal bar charts for years 2019–2024. Each panel title (bold, ~14pt dark ink) shows the year. Company names on the y-axis and dollar-value labels on the right of each bar use ~9–9.5pt dark-soft ink. Bars are colored with the Okabe-Ito palette in canonical order: Alphabet=#009E73, Amazon=#D55E00, Apple=#0072B2, Meta=#CC79A7, Microsoft=#E69F00, Nvidia=#56B4E9, Tesla=#F0E442. All text is readable against the light background, though value labels and tick labels are smaller than the guideline minimums (9–9.5pt vs recommended ≥16pt).

Dark render (plot-dark.png): Identical layout on a warm near-black #1A1A17 background. Title, year labels, company names, and value labels all render in light-colored ink (cream/soft-grey tokens), fully readable against the dark surface. No dark-on-dark failures. Bar data colors are identical to the light render — only the chrome (background, text, spine) flips. The theme-adaptive token system works correctly in both renders.

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

Score: 81/100

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

Visual Quality (25/30)

• VQ-01: Text Legibility (5/8) — All text readable in both themes, but sizes are set below guidelines: title 20pt (need ≥24), tick labels 9.5pt (need ≥16), value labels 9pt
• VQ-02: No Overlap (6/6) — No overlapping elements across all 6 panels
• VQ-03: Element Visibility (5/6) — Most bars clearly visible; narrowest bars (Tesla $75B, Nvidia $145B in 2019) are very thin but still distinguishable by color
• VQ-04: Color Accessibility (2/2) — Okabe-Ito is CVD-safe; adequate contrast in both themes
• VQ-05: Layout & Canvas (4/4) — 2×3 grid fills canvas well; balanced margins; tight_layout effective
• VQ-06: Axis Labels & Title (1/2) — Main title is descriptive; value labels include "$B" unit; missing explicit x-axis label stating units
• VQ-07: Palette Compliance (2/2) — Okabe-Ito in canonical order; light/dark backgrounds correct (#FAF8F1/#1A1A17); chrome tokens flip correctly

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured with correct palette and spine cleanup, but no intentional visual hierarchy or focal point; looks like a polished default
• DE-02: Visual Refinement (4/6) — Top, right, and bottom spines removed; no grid; page-bg bar edges give separation; above-default refinement visible
• DE-03: Data Storytelling (2/6) — Data selection (tech giants 2019–2024) is inherently interesting, but no visual emphasis distinguishes the most compelling trend (Nvidia's explosive rise from $145B to $3,280B); viewer must find the story themselves

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — 2×3 small multiples of horizontal bar charts; correct static fallback per spec
• SC-02: Required Features (4/4) — Bars sorted by value per panel; entity labels attached; year as time indicator; consistent entity colors across all frames
• SC-03: Data Mapping (3/3) — X=market cap, Y=company names; shared max scale across all panels; all data visible
• SC-04: Title & Legend (3/3) — "Tech Giant Market Cap · bar-race-animated · python · matplotlib · anyplot.ai" matches required format exactly

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — 7 entities, 6 time snapshots, rank changes between years, consistent colors, value labels — all aspects shown
• DQ-02: Realistic Context (5/5) — Real-world, neutral business domain: tech company market caps 2019–2024
• DQ-03: Appropriate Scale (4/4) — Values closely match historical reality (Apple $1T→$3.75T, Nvidia $145B→$3.28T, Microsoft $1.2T→$3.13T)

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → theme tokens → data → subplot loop → suptitle → save
• CQ-02: Reproducibility (2/2) — Fully deterministic; all data hardcoded, no randomness
• CQ-03: Clean Imports (2/2) — Only os and matplotlib.pyplot imported, both used
• CQ-04: Code Elegance (2/2) — Pythonic; no fake UI elements; good use of dict and list indexing
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png; current matplotlib API used

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5) — Good axes-based barh(), plt.subplots(2,3), tick_params, tight_layout; slightly above baseline
• LM-02: Distinctive Features (2/5) — Subplots grid + per-bar color list are correct but not distinctive matplotlib capabilities; no ArtistAnimation, axes insets, blended transforms, or other matplotlib-specific advanced features

Score Caps Applied

• None

Strengths

• Perfect spec compliance — small multiples grid correctly implements the static fallback for animation
• Excellent data quality — realistic tech company market cap data (2019–2024) with historically plausible values
• Perfect code quality — KISS structure, deterministic data, clean imports, correct output format
• Correct theme-adaptive chrome — both light and dark renders pass the readability check with no dark-on-dark failures
• Consistent entity colors across all panels using Okabe-Ito in canonical order

Weaknesses

• Font sizes below guidelines: main title 20pt (need ≥24), year-panel titles 14pt, value labels 9pt, y-tick labels 9.5pt (need ≥16) — increase all to meet minimums
• No explicit x-axis label with units (e.g., "Market Cap (USD Billions)")
• No visual storytelling emphasis — Nvidia's rise from $145B (2019) to $3,280B (2024) is the most dramatic data story but nothing highlights it
• LM-02 low — standard matplotlib patterns only; no distinctive library features leveraged

Issues Found

1. VQ-01 LOW: Font sizes are explicitly set but below required minimums (title 20pt vs ≥24pt; ticks 9.5pt vs ≥16pt; value labels 9pt)
   • Fix: Increase title to fontsize=24+, year panel titles to 14-16pt (in context of 6 panels), value labels to 12-14pt, y-tick labels to 12pt minimum
2. VQ-06 PARTIAL: No x-axis label stating units
   • Fix: Add ax.set_xlabel("Market Cap (USD Billions)", fontsize=12, color=INK_SOFT) to each panel, or add a shared axis label via fig.text()
3. DE-03 LOW: No visual storytelling — the Nvidia story is not highlighted
   • Fix: Consider adding a subtle annotation in the 2024 panel marking Nvidia's bar, or use slightly larger opacity/edge emphasis for the Add workflow diagram for new prototype discovery #1 ranked bar in each panel, or add a subtitle noting the key insight
4. LM-02 LOW: Generic matplotlib usage
   • Fix: Consider using mpl_toolkits.axes_grid1 for shared axis labels, or matplotlib's ArtistAnimation for an exported GIF (if pipeline supports it), or add a rank-change arrow between panels using ConnectionPatch

AI Feedback for Next Attempt

Increase all font sizes to meet the style guide minimums: title ≥24pt, tick labels ≥16pt, value labels ≥12pt (adjust for small-multiples context). Add an x-axis label with units. Add a visual storytelling element to emphasize the most interesting data story (Nvidia's explosive rise or the competitive dynamics). Consider using matplotlib's ConnectionPatch to draw rank-change arrows between panels — this would demonstrate distinctive library mastery while enhancing storytelling. These changes alone should push the score above 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): A 6-panel (2×3) small-multiples bar chart race on a warm off-white #FAF8F1 background, showing 7 tech companies (Alphabet, Amazon, Apple, Meta, Microsoft, Nvidia, Tesla) ranked by market cap (USD billions) at year-end 2019–2024. Each panel has a bold year title (20pt), horizontal bars colored with Okabe-Ito positions 1–7 (Alphabet=green #009E73, Amazon=vermillion, Apple=blue, Meta=pink, Microsoft=orange, Nvidia=sky-blue, Tesla=yellow), sorted descending by value with the highest company at the top. Value labels appear to the right of each bar in INK_SOFT, with Nvidia's label in its brand sky-blue with a white path-effects stroke. The 2024 panel includes an arrow annotation "×23 since 2019" pointing to Nvidia's bar and an inset sparkline in the lower-right corner charting Nvidia's trajectory. The suptitle "Tech Giant Market Cap · bar-race-animated · python · matplotlib · anyplot.ai" is displayed at the top. All text is readable against the light background; x-axis labels (14pt) and value labels (13pt) are present but slightly below the recommended sizes for the canvas.

Dark render (plot-dark.png): The same 6-panel layout on a warm near-black #1A1A17 background. All chrome tokens flip correctly: suptitle, year panel titles, and company labels render in light ink (#F0EFE8 / #B8B7B0), clearly visible against the dark surface. No dark-on-dark failures detected — tick labels, value labels, and annotation text all use light adaptive tokens. The bar colors are identical to the light render (Okabe-Ito positions 1–7 unchanged). The annotation box uses the elevated dark surface (#242420) with appropriate light-colored text. The sparkline fill and line in the 2024 panel retain the same Nvidia sky-blue color.

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

Score: 85/100

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

Visual Quality (24/30)

• VQ-01: Text Legibility (5/8) — suptitle 24pt ✓, panel year titles 20pt ✓, y-tick company labels 16pt ✓; x-axis "Market Cap ($B)" labels at 14pt (guide: 20pt) and value labels at 13pt (guide: 16pt) are below recommended minimums for the 4800×2700px canvas; both renders are readable but text is smaller than optimal
• VQ-02: No Overlap (5/6) — clean layout overall; minor crowding in 2024 panel with sparkline + annotation competing for space with bar value labels
• VQ-03: Element Visibility (5/6) — all bars clearly visible and distinct; Nvidia's $145B bar in 2019 is very short but correctly labeled
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe by design
• VQ-05: Layout & Canvas (3/4) — well-proportioned 2×3 grid, nothing cut off; figsize=(20,11) deviates slightly from the standard 16×9 guideline
• VQ-06: Axis Labels & Title (2/2) — "Market Cap ($B)" on each panel, suptitle correct
• VQ-07: Palette Compliance (2/2) — Alphabet (first alphabetically) gets #009E73 ✓, backgrounds #FAF8F1/#1A1A17 correct, data colors identical across both renders

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (5/8) — above default: path_effects stroke on Nvidia labels, inset sparkline, deliberate Nvidia narrative thread across 6 panels, intentional color emphasis; not at maximum as small multiples is the static fallback approach
• DE-02: Visual Refinement (4/6) — top/right/bottom spines removed, tick length=0, bar edges set to PAGE_BG for clean visual separation; no grid lines is a missed opportunity for bar-length comparison aid
• DE-03: Data Storytelling (5/6) — strong: Nvidia's ×23 rise is a clear focal point, arrow annotation with growth multiplier, sparkline showing full 2019→2024 trajectory; reordering across panels communicates the race narrative effectively

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — small multiples grid is the correct static alternative for animated bar chart race per spec note and matplotlib library guide
• SC-02: Required Features (4/4) — bars sorted by value at each frame (descending, highest on top) ✓; entity labels on y-axis ✓; year as time indicator ✓; consistent entity colors across all panels ✓
• SC-03: Data Mapping (3/3) — X: market cap values, Y: companies sorted by value, all 7 entities and 6 time points shown
• SC-04: Title & Legend (3/3) — "Tech Giant Market Cap · bar-race-animated · python · matplotlib · anyplot.ai" matches required format; y-axis labels serve as implicit legend

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — shows ranking changes, value changes, and race dynamics across 6 time points; Nvidia narrative adds storytelling depth; minor deduction for only 6 discrete snapshots
• DQ-02: Realistic Context (5/5) — well-known tech company market cap data, realistic figures, neutral subject
• DQ-03: Appropriate Scale (4/4) — billions of dollars, realistic range $75B–$3,750B

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — no functions or classes, flat linear structure
• CQ-02: Reproducibility (2/2) — hardcoded data, fully deterministic
• CQ-03: Clean Imports (2/2) — all 4 imports (os, patheffects, pyplot, GridSpec) are used
• CQ-04: Code Elegance (2/2) — no fake UI, clean iteration patterns
• CQ-05: Output & API (1/1) — saves as plot-{THEME}.png, no deprecated API usage

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Axes methods throughout, GridSpec for multi-panel, inset_axes for sparkline, modern Python patterns
• LM-02: Distinctive Features (4/5) — matplotlib.patheffects (withStroke + Normal) for Nvidia label stroke is a specialized and distinctive feature; inset_axes, fill_between, and annotate with complex arrowprops further showcase matplotlib's depth

Score Caps Applied

• None

Strengths

• Excellent Nvidia storytelling: sparkline inset, arrow annotation with ×23 multiplier, and path-effect value labels create a clear focal point across all 6 panels
• Correct use of small multiples as the approved static alternative for animated bar chart race, covering all 6 year snapshots (2019–2024)
• Strong matplotlib feature usage — path_effects for text stroke, inset_axes for the embedded sparkline, GridSpec for precise panel layout
• Perfect theme implementation: #FAF8F1/#1A1A17 backgrounds, all chrome tokens applied correctly, data colors identical across both renders
• Clean code structure with complete Okabe-Ito palette assignment, flat structure, and all spec-required static features present

Weaknesses

• Value labels (13pt) and x-axis "Market Cap ($B)" labels (14pt) are below the recommended minimum sizes (16pt and 20pt respectively) for the 4800×2700px canvas; at full resolution these will read small
• No grid lines — even subtle y-axis grid lines (alpha=0.10) would aid bar-length comparison across the sorted rankings in each panel
• figsize=(20, 11) deviates slightly from the standard landscape canvas (16×9)

Issues Found

1. VQ-01 LOW: Value labels fontsize=13 and x-axis label fontsize=14 fall below the canvas size guidelines (16pt tick/value labels, 20pt axis labels)

   • Fix: Increase value label fontsize from 13 → 16 and x-axis label fontsize from 14 → 20

2. DE-02 MID: No grid lines present — bar charts benefit from subtle reference lines for value comparison

   • Fix: Add ax.xaxis.grid(True, alpha=0.10, color=INK, linewidth=0.6) after setting up each panel

AI Feedback for Next Attempt

The implementation is strong overall — the Nvidia narrative, path effects, and sparkline are well-executed. Focus the next attempt on two fixes: (1) increase value label fontsize from 13 to 16 and x-axis "Market Cap ($B)" label fontsize from 14 to 20 to meet high-resolution canvas guidelines; (2) add subtle x-axis grid lines (ax.xaxis.grid(True, alpha=0.10, color=INK, linewidth=0.6)) to improve bar-length comparison readability. These are targeted, low-risk changes that will bring the implementation to full quality.

Verdict: APPROVED