feat(matplotlib): implement surface-basic

[github-actions]

Implementation: surface-basic - python/matplotlib

Implements the python/matplotlib version of surface-basic.

File: plots/surface-basic/implementations/python/matplotlib.py

Parent Issue: #1013

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): A warm off-white background (#FAF8F1) displays a 3D surface plot with excellent visual clarity. The title "surface-basic · matplotlib · anyplot.ai" and axis labels (X Axis, Y Axis, Z Axis) are rendered in dark text and fully readable. Tick labels on all axes are clearly visible. A Gaussian-with-ripples mathematical surface is visualized using the viridis colormap, transitioning smoothly from purple (low values) through green to yellow (high values). The colorbar on the right displays "Z Value" with scale indicators. Grid lines are subtle and appropriate. All text is readable against the light background; no dark-on-light contrast failures detected.

Dark render (plot-dark.png): The same plot rendered on a warm near-black background (#1A1A17) with light text throughout. Title and axis labels appear in light color and are clearly readable against the dark background. Tick labels are visible. The data colors are identical to the light render—the same viridis gradient (purple to yellow) representing the mathematical surface. Grid lines are light and subtle. Colorbar is properly themed with light text. No dark-on-dark failures detected; all elements have sufficient contrast. Both renders show identical data representation with only chrome (background, text, grid) adapting between themes, exactly as specified.

Score: 81/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (5/8) - Readable but font sizes undersized (18pt labels, 14pt ticks vs. 20pt/16pt guidelines)
• VQ-02: No Overlap (6/6) - Clean, no overlapping elements
• VQ-03: Element Visibility (6/6) - Excellent visibility of all components
• VQ-04: Color Accessibility (2/2) - Viridis colormap is perceptually-uniform and CVD-safe
• VQ-05: Layout & Canvas (4/4) - Perfect balance and utilization
• VQ-06: Axis Labels & Title (2/2) - Correct format with appropriate labels for mathematical data
• VQ-07: Palette Compliance (2/2) - Images show correct viridis colormap and proper theme-adaptive chrome

Design Excellence (8/20)

• DE-01: Aesthetic Sophistication (3/8) - Generic library defaults, no custom design thinking
• DE-02: Visual Refinement (2/6) - Minimal customization beyond defaults
• DE-03: Data Storytelling (3/6) - Good data choice but no visual hierarchy or emphasis

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct 3D surface plot
• SC-02: Required Features (4/4) - All features present (smooth colormap, axis labels, colorbar, appropriate grid)
• SC-03: Data Mapping (3/3) - X, Y, Z correctly mapped
• SC-04: Title & Legend (3/3) - Correct title format

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Surface shows peaks, valleys, oscillations
• DQ-02: Realistic Context (5/5) - Neutral mathematical/scientific context
• DQ-03: Appropriate Scale (4/4) - Grid range and proportions correct

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) - Clean Imports → Data → Plot → Save
• CQ-02: Reproducibility (2/2) - Deterministic data generation
• CQ-03: Clean Imports (2/2) - Only necessary imports
• CQ-04: Code Elegance (2/2) - Appropriate complexity
• CQ-05: Output & API (0/1) - Hardcoded to 'plot.png' instead of 'plot-{THEME}.png'

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Correct matplotlib patterns with 3D projection
• LM-02: Distinctive Features (3/5) - Uses 3D-specific features but in standard way

Score Caps Applied

• None

Strengths

• Both renders display with correct visual appearance and proper theme-adaptive chrome throughout
• Excellent clarity: no overlapping text, readable in both themes, all elements visible
• All specification requirements met completely
• Clean code structure with good naming conventions
• Appropriate mathematical function demonstrating surface features well
• Proper 3D perspective with good viewing angle
• Professional colorbar integration

Weaknesses

• CRITICAL: Source code lacks explicit theme-adaptive styling implementation. Images show proper theme adaptation, but code doesn't include ANYPLOT_THEME reading or color token assignments (PAGE_BG, INK, INK_SOFT). Code appears incomplete or mismatched from generated images.
• Font sizes undersized: axis labels 18pt (should be 20pt), tick labels 14pt (should be 16pt), colorbar ticks 12pt (too small)
• Output filename hardcoded to 'plot.png' instead of using theme-aware 'plot-{THEME}.png' pattern
• Generic styling using library defaults without custom design elements or visual hierarchy
• No visual storytelling or emphasis to guide viewer's attention

Issues Found

1. CRITICAL - VQ-01 & VQ-07: Code missing theme-adaptive styling logic. While images demonstrate correct theming, implementation file lacks ANYPLOT_THEME environment variable handling and color token setup (PAGE_BG, INK, INK_SOFT, etc.).
   • Fix: Add theme detection with and set colors for figure, axes, text, grid, and spines
2. VQ-01: Font sizes undersized relative to guidelines
   • Fix: Set axis labels to 20pt (currently 18pt), tick labels to 16pt (currently 14pt), colorbar ticks to at least 14-16pt (currently 12pt)
3. CQ-05: Output filename needs theme awareness
   • Fix: Change save call to use f'plot-{THEME}.png' instead of hardcoded 'plot.png'
4. DE-01 LOW: Generic styling with library defaults
   • Fix: Consider subtle visual enhancements within the matplotlib ecosystem

AI Feedback for Next Attempt

The implementation demonstrates correct understanding of 3D surface visualization and good code structure. Primary issue is the disconnect between the themed images and the untheemed source code—this must be resolved by adding explicit theme-adaptive styling to the Python file. Additionally, increase font sizes to match the guidelines and fix the output filename. These changes would bring this to 88-90 range. Consider adding design sophistication to exceed 90.

[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): The 3D surface plot displays a Gaussian-like function with radial ripple patterns on a warm off-white background (#FAF8F1). The viridis colormap ranges from deep purple (low values ~0.0) to bright yellow (high values ~0.8), effectively showing the height variation. The title "surface-basic · matplotlib · pyplots.ai" is rendered in dark gray, clearly readable against the light background. X, Y, and Z axis labels are dark and legible. Tick labels on all three axes are clearly visible. The colorbar on the right shows the Z Value scale with proper label visibility. The viewing angle (elev=30°, azim=45°) provides excellent perspective. All text elements are well-positioned with no overlaps.

Dark render (plot-dark.png): The same surface is rendered on a warm near-black background (#1A1A17). The viridis colormap colors are identical to the light render (same purple-to-yellow gradient), confirming proper color consistency. Text elements are rendered in light colors for readability: the title, axis labels, and tick labels all appear in light gray/off-white, making them clearly visible against the dark background. The colorbar text is also light-colored. All chrome elements have been adapted to the dark theme with good contrast. No "dark-on-dark" failures are present. The mesh wireframe is subtle and visible without overwhelming the data.

Both renders demonstrate proper theme adaptation with identical data colors across themes and context-appropriate chrome adjustments. All text is legible in both renders.

Score: 79/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	12	20
Spec Compliance	12	15
Data Quality	15	15
Code Quality	8	10
Library Mastery	5	10
Total	79	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set; title 24pt, axis labels 18pt, tick labels 14pt; perfectly readable in both themes
• VQ-02: No Overlap (6/6) - Zero overlapping elements; colorbar, title, and axis labels all clearly separated
• VQ-03: Element Visibility (6/6) - Surface geometry clearly visible; 40×40 grid provides smooth rendering without density artifacts
• VQ-04: Color Accessibility (2/2) - viridis colormap is perceptually uniform and colorblind-safe
• VQ-05: Layout & Canvas (4/4) - Excellent proportions, viewing angle optimizes 3D depth perception, nothing cut off
• VQ-06: Axis Labels & Title (2/2) - Descriptive labels (X, Y, Z axes) present; title format present
• VQ-07: Palette Compliance (2/2) - viridis correctly used for continuous data; background appears to be themed; text colors are theme-adaptive in both renders

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (4/8) - Well-configured library default; viridis colormap is elegant; viewing angle is intentional and professional. Lacks custom refinements expected of publication-quality work.
• DE-02: Visual Refinement (4/6) - 3D plots lack traditional spines/grid elements; mesh edges removed; layout is clean and minimal. Some refinement evident.
• DE-03: Data Storytelling (4/6) - The radial ripple pattern demonstrates surface features well; central peak is a clear focal point. Mathematical function is instructive and shows oscillation with damping.

Spec Compliance (12/15)

• SC-01: Plot Type (5/5) - Correct 3D surface plot using ax.plot_surface()
• SC-02: Required Features (4/4) - All spec features present: smooth viridis colormap, axis labels, colorbar with label, 3D visualization
• SC-03: Data Mapping (3/3) - X axis range [-4, 4], Y axis range [-4, 4], Z values computed correctly and visible
• SC-04: Title & Legend (0/3) - CRITICAL ERROR: Title reads "surface-basic · matplotlib · pyplots.ai" but should be "surface-basic · matplotlib · anyplot.ai"

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Surface shows all aspects: central peak, radial ripples, smooth gradient transitions, and amplitude damping at edges
• DQ-02: Realistic Context (5/5) - Mathematical function (Gaussian-modulated sinusoid) is neutral, pedagogically sound, commonly used for testing visualization tools
• DQ-03: Appropriate Scale (4/4) - Grid size (40×40), value range, and proportions are appropriate for clear visualization

Code Quality (8/10)

• CQ-01: KISS Structure (3/3) - Linear flow: imports → data generation → 3D plot creation → styling → save
• CQ-02: Reproducibility (2/2) - Data generation uses np.linspace (fully deterministic)
• CQ-03: Clean Imports (2/2) - Only matplotlib.pyplot and numpy; both are used
• CQ-04: Code Elegance (2/2) - Appropriate complexity, no over-engineering, no fake functionality
• CQ-05: Output & API (0/1) - CRITICAL ERROR: Code saves as plt.savefig("plot.png", ...) but should save as plt.savefig(f"plot-{THEME}.png", ...). Additionally, code does not implement theme token reading via os.getenv("ANYPLOT_THEME") or apply theme-adaptive chrome. The images show proper theming, suggesting the pipeline compensates, but the code itself is non-compliant with the matplotlib implementation guide.

Library Mastery (5/10)

• LM-01: Idiomatic Usage (4/5) - Good use of ax.plot_surface(), fig.colorbar(), ax.view_init(). Proper matplotlib 3D API. Doesn't leverage advanced features.
• LM-02: Distinctive Features (1/5) - 3D projection is matplotlib-specific, but otherwise uses standard library features generically

Score Caps Applied

• None applied; no catastrophic failures

Strengths

• Excellent visual output in both light and dark themes with proper theme adaptation
• Smooth, high-quality 3D surface rendering with proper perspective
• Clear, readable text at all sizes and colors in both themes
• Appropriate data choice demonstrating surface plot capabilities
• Clean, simple code structure with proper imports

Weaknesses

• Title text error: "pyplots.ai" instead of "anyplot.ai" (SC-04 failure)
• Missing theme token implementation: Code does not read ANYPLOT_THEME environment variable or apply theme-adaptive colors to chrome elements. While rendered images show proper theming (suggesting the pipeline handles this), the code as written is incomplete and non-maintainable.
• Output filename error: Saves as "plot.png" instead of "plot-{THEME}.png", violating the matplotlib implementation API.
• Generic colormap design: viridis is appropriate but not customized; first-attempt implementations typically show aesthetic refinement beyond library defaults

Issues Found

1. SC-04 CRITICAL: Title text incorrect

   • Current: "surface-basic · matplotlib · pyplots.ai"
   • Expected: "surface-basic · matplotlib · anyplot.ai"
   • Fix: Correct the domain name in line 35

2. CQ-05 CRITICAL: Output API and theme handling non-compliant

   • Missing: os.getenv("ANYPLOT_THEME") reading
   • Missing: Theme-adaptive colors for title, labels, ticks, background, spines
   • Missing: f-string formatting for output filename
   • Fix: Implement complete theme token system with proper colors for light and dark themes, and save with correct filename pattern

AI Feedback for Next Attempt

Fix the two critical code errors: (1) correct the title text to use "anyplot.ai", and (2) implement complete theme token reading and application throughout the code. The visual output is excellent and the data choice is sound; the fixes are straightforward code improvements that will bring the implementation into full compliance. After these fixes, expect approval on Review 3.

Verdict: REJECTED

Reason: Below Attempt 2 threshold (79 < 80). Critical code non-compliance issues prevent approval despite excellent visual output. Pushing to repair loop with specific, actionable feedback.