feat(makie): implement swarm-basic

[github-actions]

Implementation: swarm-basic - julia/makie

Implements the julia/makie version of swarm-basic.

File: plots/swarm-basic/implementations/julia/makie.jl

Parent Issue: #974

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1-matching). Bold dark title "swarm-basic · julia · makie · anyplot.ai" centered at top; dark "Department" (x) and "Performance Score" (y) axis labels; medium-gray tick labels; subtle horizontal y-axis-only gridlines; left/bottom spines only. Four department swarms — Engineering (#009E73 brand green, first series), Sales (#C475FD lavender), Support (#4467A3 blue), Marketing (#BD8233 ochre) — each with a thin dark median line, packed via a nearest-free-slot algorithm that widens where scores cluster and narrows at the tails, with no point overlap. All text is clearly readable against the light background.

Dark render (plot-dark.png): Warm near-black background (#1A1A17-matching). Title, axis labels, and tick labels flip to light/off-white and soft-gray; median lines flip to white for contrast; gridlines remain subtle and theme-adaptive; spine layout matches the light render. Data colors (green/lavender/blue/ochre) are pixel-identical to the light render — only chrome flipped. All text and median markers are clearly visible against the near-black background; no dark-on-dark failures.

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

Score: 85/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8)
• VQ-02: No Overlap (6/6)
• VQ-03: Element Visibility (6/6)
• VQ-04: Color Accessibility (2/2)
• VQ-05: Layout & Canvas (4/4)
• VQ-06: Axis Labels & Title (1/2) - "Performance Score" has no unit/scale hint
• VQ-07: Palette Compliance (2/2)

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) - Clean and professional but close to a well-configured default
• DE-02: Visual Refinement (4/6) - Y-only subtle grid, spines removed, marker stroke for point separation
• DE-03: Data Storytelling (4/6) - Per-department median lines create a focal point, but no annotation drives a single headline insight

Spec Compliance (15/15)

• SC-01: Plot Type (5/5)
• SC-02: Required Features (4/4)
• SC-03: Data Mapping (3/3)
• SC-04: Title & Legend (3/3)

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6)
• DQ-02: Realistic Context (5/5)
• DQ-03: Appropriate Scale (4/4)

Code Quality (10/10)

• CQ-01: KISS Structure (3/3)
• CQ-02: Reproducibility (2/2)
• CQ-03: Clean Imports (2/2)
• CQ-04: Code Elegance (2/2)
• CQ-05: Output & API (1/1)

Library Mastery (5/10)

• LM-01: Idiomatic Usage (4/5)
• LM-02: Distinctive Features (1/5) - Swarm-packing logic is generic Julia code, nothing specific to Makie's recipe/layout ecosystem

Score Caps Applied

• None

Strengths

• Custom greedy nearest-free-slot swarm layout produces genuine density-shaped, non-overlapping point clouds per category, closely mimicking a real beeswarm despite Makie having no native swarm recipe
• First series (Engineering) uses brand green #009E73, remaining departments follow canonical Imprint order (lavender, blue, ochre) identically across light/dark
• Subtle per-department median line implements the spec's suggested "mean or median marker"
• Theme-adaptive chrome fully threaded through spines, gridlines, ticks, and labels — no dark-on-dark or light-on-light failures
• Clean KISS script structure, deterministic via Random.seed!(42)

Weaknesses

• Design Excellence still reads close to a well-configured default — beyond the median line there is no additional visual hierarchy (e.g. callout on the top/bottom department, subtitle context) to sharpen the data story
• Y-axis label "Performance Score" lacks a unit/scale hint (e.g. "Performance Score (0–100)")
• Marker stroke uses strokecolor = PAGE_BG (background-colored halo for point separation) but does nothing for the lower-contrast hues (lavender, ochre) against the light background — consider a thin ink-colored stroke per the style guide's optional outline pattern
• Library Mastery is generic: the swarm-packing algorithm has nothing Makie-specific (no recipes, no GridLayout usage) — could be ported to any language with minimal changes
• Marketing's swarm column ends well short of the right canvas edge, leaving a visibly wider right margin than left — tighten xlims! or widen category spacing for better balance

Issues Found

1. DE-01/DE-02/DE-03 MODERATE: Technically excellent but design excellence is still close to "well-configured default" territory
   • Fix: Add one clear visual-hierarchy device (e.g. bold/annotate the highest- or lowest-median department, or a brief subtitle stating the key comparison) to push Data Storytelling beyond the median lines alone
2. VQ-06 LOW: Value axis label has no unit/scale
   • Fix: Change ylabel to "Performance Score (0–100)" or similar
3. LM-02 LOW: Generic swarm-packing implementation, nothing distinctive to Makie
   • Fix: Consider leveraging Makie-specific capabilities (e.g. a Legend element styled with Makie's layout system, or GridLayout composition) to demonstrate library-specific strengths, or lean further into Makie's high-performance rendering for a denser swarm as a distinguishing feature

AI Feedback for Next Attempt

Solid, spec-compliant swarm plot with correct palette and theme handling — the main gap is Design Excellence and Library Mastery. Add a stronger data-storytelling element (annotate the standout department, or a brief subtitle framing the comparison) and give the value axis a unit hint. For Library Mastery, look for a way to use Makie-specific features (Legend/GridLayout composition, or leaning into CairoMakie's rendering strengths) rather than a fully generic swarm-packing loop.

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. Bold centered title "swarm-basic · julia · makie · anyplot.ai" in dark ink, with a soft-ink subtitle "Support leads with the highest median score (83)" beneath it. Four beeswarm columns (Engineering=teal #009E73, Sales=lavender #C475FD, Support=blue #4467A3, Marketing=ochre #BD8233) sit on a categorical x-axis labeled "Department"; y-axis is "Performance Score (0–100)" with a subtle horizontal gridline every 10 units. Each department has a solid median line, with Support's line rendered bolder to anchor the subtitle's callout. All text — title, subtitle, axis titles, tick labels — is clearly legible against the light background; no light-on-light issues found.

Dark render (plot-dark.png): Warm near-black #1A1A17 background. Same layout and data colors — teal/lavender/blue/ochre are pixel-identical to the light render, confirming only chrome flipped. Title, subtitle, and axis text switch to light ink/soft-ink and remain fully readable; gridlines and median lines switch to a light tone appropriate for the dark surface. No dark-on-dark failures — every label is clearly distinguishable from the background.

Both renders pass the theme-readability checklist: no clipped elements, no wrong-theme chrome, data colors identical across themes.

Score: 91/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — all font sizes explicit (titlesize=20, subtitlesize=14, xlabelsize/ylabelsize=16, ticklabelsize=13), well-proportioned, readable in both themes.
• VQ-02: No Overlap (6/6) — no text collisions; category labels and title/subtitle are cleanly spaced.
• VQ-03: Element Visibility (5/6) — greedy collision-avoidance swarm layout keeps points distinct, but the busiest bands (Sales ~76–81, Marketing ~74–79) still read as visually dense/tight clusters.
• VQ-04: Color Accessibility (2/2) — four hues with good luminance separation, no red-green-only signal.
• VQ-05: Layout & Canvas (4/4) — plot fills a healthy majority of the canvas, balanced margins, no wasted space.
• VQ-06: Axis Labels & Title (2/2) — "Performance Score (0–100)" and "Department" are descriptive; the (0–100) suffix clarifies scale.
• VQ-07: Palette Compliance (2/2) — first series is #009E73, remaining series follow canonical Imprint order (#C475FD, #4467A3, #BD8233); backgrounds are correct #FAF8F1/#1A1A17; chrome theme-correct in both renders.

Design Excellence (16/20)

• DE-01: Aesthetic Sophistication (6/8) - Custom Imprint palette, deliberate typographic hierarchy (title/subtitle/axis), intentional median-line accent for the leading department — clearly above library defaults, short of publication-tier polish.
• DE-02: Visual Refinement (5/6) - Top/right spines removed, subtle single-axis gridline, generous whitespace; minor room to tighten y-axis padding further.
• DE-03: Data Storytelling (5/6) - Subtitle explicitly names the leading department + score, reinforced by a bolder median line, giving the viewer an immediate focal point without needing to infer the insight themselves.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Genuine beeswarm/swarm layout (hand-rolled greedy nearest-slot placement since Makie has no native swarm geom) — individual points visible, spread to avoid overlap.
• SC-02: Required Features (4/4) - Consistent point sizes, median marker per category, color distinguishes categories, clear spacing between groups — matches every spec note.
• SC-03: Data Mapping (3/3) - Category on x-axis, continuous value on y-axis, all points visible within axis bounds.
• SC-04: Title & Legend (3/3) - Title format exactly matches swarm-basic · julia · makie · anyplot.ai; no separate legend needed since categories are already labeled on the x-axis and color-coded consistently.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Four departments with distinct means/spreads (Support tight & high, Sales wide & low, Marketing widest), visible outliers in Engineering/Marketing — shows the full range of swarm-plot behavior.
• DQ-02: Realistic Context (5/5) - Employee performance scores by department is a neutral, comprehensible business scenario.
• DQ-03: Appropriate Scale (4/4) - 0–100 performance scale with plausible department-level differences, consistent with the subtitle's stated Support median.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear imports → data → plot → save; no functions/classes.
• CQ-02: Reproducibility (2/2) - Random.seed!(42).
• CQ-03: Clean Imports (2/2) - CairoMakie, Colors, Random, Statistics — all used (median via Statistics).
• CQ-04: Code Elegance (2/2) - The custom collision-avoidance loop is well-scoped and commented, appropriate complexity for a library without a native swarm primitive; no fake functionality.
• CQ-05: Output & API (1/1) - Saves plot-$(THEME).png via save(...; px_per_unit=2), current CairoMakie API.

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5) - Correct, clean use of Figure/Axis/scatter!/lines! with theme-token kwargs; doesn't reach for higher-level Makie constructs (e.g. Legend, layout grids) beyond what's needed here.
• LM-02: Distinctive Features (2/5) - The swarm placement itself is a generic hand-rolled algorithm portable to any plotting library with a scatter primitive; nothing here is uniquely Makie (no recipes, no GeometryBasics, no Makie-specific layout tricks).

Score Caps Applied

• None

Strengths

• Correct Imprint palette with brand green first series, verified identical across both themes.
• Theme-adaptive chrome fully correct in both light and dark renders — no legibility failures.
• Sound engineering for a library gap: Makie has no native swarm/beeswarm geom, so the greedy nearest-free-slot collision algorithm is a legitimate, well-commented solution rather than a workaround.
• Subtitle explicitly ties the data story to the visual (bolded median line for the leading department).
• Realistic, well-varied data across all four departments (different means, spreads, and outliers).

Weaknesses

• LM-02 is low — the implementation doesn't lean on anything distinctive to Makie beyond colorant"..."/RGBAf tokens; consider a Makie-specific touch (e.g. a Legend block, a custom recipe, or GeometryBasics-based marker shapes) to raise library mastery.
• Busiest swarm bands (Sales ~76–81, Marketing ~74–79) read slightly dense — a marginal reduction in markersize or increase in step_x/min_dist_y would improve point-level visibility without changing the overall shape.
• DE-01/DE-02 are solid but not yet publication-tier — a touch more restraint on y-axis padding and a slightly stronger visual differentiator for the winning department (beyond line-width) would push this further.

AI Feedback for Next Attempt

Implementation is strong and ready to ship. If revisited: ease local point density in the busiest swarm bands (nudge step_x/min_dist_y), and consider a Makie-distinctive flourish (custom recipe, Legend, or GeometryBasics markers) to raise Library Mastery beyond generic scatter usage.

Verdict: APPROVED