feat(matplotlib): implement barcode-code128

[github-actions]

Implementation: barcode-code128 - python/matplotlib

Implements the python/matplotlib version of barcode-code128.

File: plots/barcode-code128/implementations/python/matplotlib.py

Parent Issue: #3809

---

🤖 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. The title "barcode-code128 · python · matplotlib · anyplot.ai" appears centered at the top in dark ink at 12pt — readable and proportional at ~55% of canvas width. The barcode itself occupies the central portion of the canvas: high-contrast black bars on the off-white background with quiet zones on both sides. Below the barcode, "SHIP-2024-ABC123" appears in bold monospace at 16pt in dark ink. All spines and tick marks are hidden. All text is clearly readable against the light background. No overlapping elements. Legibility: PASS.

Dark render (plot-dark.png): The same plot on a warm near-black (#1A1A17) background. The barcode is correctly inverted: cream/near-white bars (#F0EFE8 INK token) on the dark background — the LinearSegmentedColormap maps INK↔PAGE_BG appropriately per theme. The title and "SHIP-2024-ABC123" text render in light ink (#F0EFE8), clearly legible against the dark surface. No dark-on-dark failures. All text is readable. The barcode pattern is identical between both renders (same encoded content), with only the color polarity flipped. Legibility: PASS.

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

Score: 86/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — Title (12pt) and human-readable text (16pt monospace bold) both explicitly set and proportional in both themes
• VQ-02: No Overlap (6/6) — No overlapping elements; clean separation between title, barcode, and label
• VQ-03: Element Visibility (6/6) — Barcode bars render at optimal contrast in both themes (binary INK↔PAGE_BG colormap)
• VQ-04: Color Accessibility (2/2) — Maximum luminance contrast (near-black/near-white), CVD-safe by design
• VQ-05: Layout & Canvas (4/4) — Barcode occupies ~55% width and ~35% height with balanced margins; subplots_adjust tuned manually
• VQ-06: Axis Labels & Title (2/2) — Title follows mandated format exactly; no axis labels needed for barcode
• VQ-07: Palette Compliance (2/2) — Backgrounds are #FAF8F1 (light) and #1A1A17 (dark); chrome tokens (INK, INK_SOFT) adapt correctly; binary barcode uses INK/PAGE_BG rather than categorical Okabe-Ito (appropriate for this plot type)

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Clean, professional appearance that reads like a well-configured default; the layout is correct but no distinctive design embellishment (e.g., section annotations, branded border, structural call-outs) elevates it beyond functional
• DE-02: Visual Refinement (4/6) — All spines removed, no unnecessary grid, deliberate subplots_adjust; above default (2) but the vertical whitespace between title and barcode feels slightly loose without a compensating design element
• DE-03: Data Storytelling (2/6) — Barcode displayed accurately with human-readable label, but no structural annotations to guide the viewer (start guard, data region, check symbol, stop guard); viewer sees a barcode but gains no insight into its anatomy

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Code 128 barcode; rendered as a 2D binary image with proper bar/space widths
• SC-02: Required Features (4/4) — Quiet zones ✓, Start pattern (START_B = [2,1,1,4,1,2]) ✓, check digit via modulo-103 ✓, Stop pattern ✓, human-readable text below ✓
• SC-03: Data Mapping (3/3) — "SHIP-2024-ABC123" encoded correctly via Code B character set lookup
• SC-04: Title & Legend (3/3) — Title: "barcode-code128 · python · matplotlib · anyplot.ai" ✓

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Complete barcode anatomy shown (start, data, checksum, stop, quiet zones, human text); only Code B subset demonstrated — spec notes subset A/B/C switching for optimal efficiency, a longer or mixed string would better showcase that
• DQ-02: Realistic Context (5/5) — "SHIP-2024-ABC123" is a plausible, neutral shipping/logistics identifier matching the spec's example data
• DQ-03: Appropriate Scale (4/4) — 16-character content within recommended 48-char limit; bar width ratios maintain standard Code 128 proportions

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No functions or classes; flat: constants → encoding tables → data → compute bars → plot → save
• CQ-02: Reproducibility (2/2) — Deterministic: hardcoded content string, no random data
• CQ-03: Clean Imports (2/2) — All five imports used: plt, np, LinearSegmentedColormap, os, sys
• CQ-04: Code Elegance (2/2) — The large lookup tables (CODE128_B, CHECKSUM_PATTERNS) are necessary for the encoding; logic is clean and readable
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png; no bbox_inches='tight'; current API

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — ax.imshow() for the 2D binary array is the idiomatic matplotlib approach; subplots_adjust for padding control; all Axes-method API (not pyplot-method)
• LM-02: Distinctive Features (3/5) — LinearSegmentedColormap.from_list() for a custom two-stop theme-adaptive colormap is a distinctive matplotlib color API feature used creatively here; not a pattern easily replicated in other plotting libraries

Score Caps Applied

• None

Strengths

• Complete, accurate Code 128B encoding from scratch: correct START_B, modulo-103 checksum, STOP pattern, and full Code B character set
• Theme-adaptive LinearSegmentedColormap elegantly inverts bar/space colors between themes by mapping the binary array to INK/PAGE_BG tokens
• All required spec features present: quiet zones, start/stop patterns, check digit, human-readable text in monospace bold below barcode
• Perfect spec compliance — uses the exact example content from the spec data section
• Fully self-contained with no external barcode library dependencies

Weaknesses

• DE-01/DE-03: No structural annotations to identify barcode zones (quiet zone, start guard, data region, check symbol, stop guard) — adding subtle labels above the barcode in INK_MUTED would add storytelling without cluttering
• DE-02: The vertical whitespace between the title and the barcode top edge is somewhat large and unanchored; tightening top margin and/or placing a subtle top-aligned horizontal rule or framing element would add refinement
• DQ-01: Only Code B subset is demonstrated; encoding a longer string like "SHIP-2024-ABC123 QTY:42" that exercises numeric pairs (subset C eligible) would better showcase the spec's multi-subset capability

Issues Found

1. DE-01/DE-03 LOW: Barcode displayed correctly but without structural call-outs or visual hierarchy cues
   • Fix: Add small ax.text() labels above the barcode (in INK_MUTED, fontsize ~8) identifying "quiet zone", "start", "data", "check", "stop" sections using the x-pixel boundaries already computed in the encoding loop
2. DE-02 LOW: Large unanchored whitespace between title and barcode
   • Fix: Reduce the gap by adjusting fig.subplots_adjust(top=0.92) or add a thin horizontal rule (ax.axhline) as a visual anchor at the top of the barcode area

AI Feedback for Next Attempt

Score is 86/100 — solid technical execution but 4 points short of the 90 threshold. Focus entirely on Design Excellence: (1) add small zone-annotation labels above the barcode (quiet zone / start / data / check / stop) in INK_MUTED at ~8pt to bring DE-03 up with visual storytelling; (2) tighten the whitespace between title and barcode or add a subtle framing element for DE-02; (3) consider whether the human-readable text could be placed inside a lightly tinted ELEVATED_BG box for a more polished DE-01. Keep all current technical correctness — do not change the encoding logic, theme tokens, or canvas size.

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): Warm off-white (#FAF8F1) background — correct. The title "barcode-code128 · python · matplotlib · anyplot.ai" appears in dark ink at the top, clearly readable. Structural zone annotation labels (Quiet Zone, Start, Data · Code B (16 chars), Check, Stop, Quiet Zone) in muted gray sit above the barcode connected by bracket lines — visible at full resolution though small (fontsize=6). The barcode itself fills the upper-center with high-contrast near-black bars on off-white spaces. Bold monospace "SHIP-2024-ABC123" appears below the barcode, prominent and clearly readable. Approximately 25-30% of the canvas below the human-readable text is empty. All text is readable against the light background; no light-on-light failures.

Dark render (plot-dark.png): Warm near-black (#1A1A17) background — correct. The title is in light (#F0EFE8) text, clearly visible. Zone annotation labels appear in a light muted tone and are readable. The LinearSegmentedColormap correctly inverts: bars are rendered as off-white (#F0EFE8) on the dark (#1A1A17) background, giving an authentic dark-mode barcode appearance. The human-readable "SHIP-2024-ABC123" text is in light bold monospace — prominent and clear. No dark-on-dark failures found anywhere. All chrome adapts correctly to the dark theme.

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

Score: 86/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (6/8) — Title and human-readable text are clear in both themes; zone annotation labels at fontsize=6 are borderline small at mobile widths (~400px)
• VQ-02: No Overlap (6/6) — No overlapping elements anywhere
• VQ-03: Element Visibility (6/6) — Barcode bars highly visible in both themes; structural brackets clearly rendered
• VQ-04: Color Accessibility (2/2) — Maximum contrast (near-black bars on off-white, inverted for dark mode)
• VQ-05: Layout & Canvas (3/4) — ~25-30% of canvas below human-readable text is empty (ylim bottom=275, last content at y≈228)
• VQ-06: Axis Labels & Title (2/2) — Title correct; no axis labels needed; zone labels serve the informational role
• VQ-07: Palette Compliance (2/2) — Backgrounds correct (#FAF8F1 light / #1A1A17 dark); binary colormap correctly uses INK/PAGE_BG tokens; Okabe-Ito N/A for this binary utility plot

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Clean functional design; structural annotation brackets with tick marks are a thoughtful educational touch; barcode's functional requirements naturally constrain aesthetic scope
• DE-02: Visual Refinement (3/6) — All four spines removed, no unnecessary grid, clean whitespace; bottom empty space slightly detracts from proportional balance
• DE-03: Data Storytelling (4/6) — Zone annotations (Quiet Zone, Start, Data · Code B, Check, Stop) with bracket lines excellently explain barcode anatomy; clear visual hierarchy: title → zone labels → barcode → human-readable text

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Code 128 barcode visualization
• SC-02: Required Features (4/4) — All required: quiet zones, start pattern, modulo-103 check digit, stop pattern, human-readable text below, high-contrast bars
• SC-03: Data Mapping (3/3) — Content "SHIP-2024-ABC123" correctly encoded and displayed
• SC-04: Title & Legend (3/3) — Title is exactly "barcode-code128 · python · matplotlib · anyplot.ai"

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — All structural elements shown (start, data, check, stop, quiet zones, human-readable); single subset (B) demonstrated; spec mentions subset switching but doesn't require multi-subset comparison
• DQ-02: Realistic Context (5/5) — "SHIP-2024-ABC123" is a realistic and neutral shipping label code matching spec example
• DQ-03: Appropriate Scale (4/4) — 16 characters is within the recommended 48-char limit; good demo size

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No functions or classes; clean procedural code
• CQ-02: Reproducibility (2/2) — No randomness; deterministic barcode encoding via lookup tables
• CQ-03: Clean Imports (2/2) — All imports used: matplotlib.pyplot, numpy, LinearSegmentedColormap, os, sys
• CQ-04: Code Elegance (2/2) — Well-organized lookup tables, clear encoding logic, no fake interactivity
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png without bbox_inches='tight'

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — ax.imshow for 2D array, ax.text for annotations, ax.plot for bracket lines — all correct axes-level methods
• LM-02: Distinctive Features (4/5) — LinearSegmentedColormap.from_list for theme-adaptive binary colormap is a clever and distinctive matplotlib feature that elegantly handles the light/dark inversion

Score Caps Applied

• None — no caps triggered

Strengths

• Correct and complete Code 128 Subset B implementation: start pattern, data symbols, modulo-103 checksum, and stop pattern all correctly encoded
• Theme-adaptive LinearSegmentedColormap for bars/spaces elegantly inverts between light and dark themes — bars appear dark-on-light and light-on-dark correctly
• Structural zone annotations (Quiet Zone, Start, Data, Check, Stop) with bracket lines provide excellent educational context for the barcode anatomy
• Human-readable text below barcode in bold monospace matches real-world barcode label conventions and is clearly visible in both themes
• Clean KISS code with no functions/classes, deterministic output, and only used imports

Weaknesses

• Zone annotation text at fontsize=6 is borderline small at mobile widths (~400px); increase to 7-8pt for better readability when the image is displayed at smaller sizes
• Approximately 25-30% of the canvas below the human-readable text is empty (ylim bottom=275 but last content at y≈228); tighten ylim or adjust subplots_adjust to center barcode content vertically and reduce wasted canvas area

Issues Found

1. VQ-01 MINOR: Zone annotation labels at fontsize=6 may be too small at mobile display widths
   • Fix: Increase zone label fontsize from 6 to 7-8pt
2. VQ-05 / DE-02 MINOR: Large empty space at bottom (~25-30% of canvas below human-readable text)
   • Fix: Set ax.set_ylim(barcode_height + 55, -38) (reduce bottom limit from 275 to ~255) or adjust fig.subplots_adjust(bottom=0.02) to better center the barcode content

AI Feedback for Next Attempt

The implementation is solid and correct. If repairing: (1) increase zone annotation fontsize from 6 to 7-8pt for mobile readability, and (2) reduce the empty bottom canvas space by tightening ylim from barcode_height + 75 to barcode_height + 55 and adjusting fig.subplots_adjust(bottom=0.02). These are minor polish items — the core barcode encoding, theme adaptation, and educational annotations are excellent.

Verdict: APPROVED