feat(altair): implement funnel-basic

[github-actions]

Implementation: funnel-basic - python/altair

Implements the python/altair version of funnel-basic.

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

Parent Issue: #789

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot displays a centered horizontal bar chart on a warm off-white #FAF8F1 background, functioning as a funnel chart. The title "Sales Funnel · funnel-basic · altair · anyplot.ai" is rendered in bold dark text at the top center. Five horizontal bars decrease in width from top to bottom: Awareness (widest, brand green #009E73), Interest (orange-red #D55E00), Consideration (blue #0072B2), Intent (reddish purple #CC79A7), and Purchase (golden orange #E69F00). Stage labels appear in bold dark text on the far left. Value/percentage labels ("1000 · 100.0%", "600 · 60.0%", etc.) appear in bold dark text immediately to the right of each bar. All text is clearly readable against the light background. No grid lines or axis borders. Bars have rounded corners with subtle PAGE_BG stroke separating them.

Dark render (plot-dark.png): The same layout is displayed on a near-black #1A1A17 background. The title and all stage labels render in light off-white text, clearly readable against the dark surface. The value/percentage labels are also light text. The Okabe-Ito data colors are identical to the light render — the brand green, orange-red, blue, pink, and golden-orange bars are visually the same in both themes. No dark-on-dark failures observed: stage labels, title, and value labels are all clearly distinguishable against the dark background. The configure_axis labelColor=INK and mark_text color=INK tokens correctly flip between themes.

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

Score: 87/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — Title 28px, stage labels 20px bold, value text 20px bold all explicitly set; readable in both themes
• VQ-02: No Overlap (6/6) — Stage labels, bars, and value labels all clearly separated with ample spacing
• VQ-03: Element Visibility (6/6) — All five bars clearly visible including the smallest (Purchase); rounded corners aid definition
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe; each stage distinctly identifiable
• VQ-05: Layout & Canvas (3/4) — Canvas is 4200×2700px (width=1400 × scale 3.0) vs the recommended 4800×2700; layout is well-balanced but slightly narrower than spec
• VQ-06: Axis Labels & Title (2/2) — Descriptive stage names on Y axis; title is clear
• VQ-07: Palette Compliance (2/2) — First stage uses #009E73 ✓; Okabe-Ito order followed for all 5 stages ✓; backgrounds #FAF8F1/#1A1A17 ✓; chrome correctly flips between themes ✓

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Rounded bar corners, dual-metric labels (count + %), and per-stage color mapping elevate this above a plain default bar chart. Not yet at FiveThirtyEight-level polish — no typographic hierarchy beyond bold labels, no distinctive whitespace treatment.
• DE-02: Visual Refinement (4/6) — Grid disabled, Y-axis domain/ticks disabled, view border removed (stroke=None). Clear intentional refinement above library defaults. The bar stroke in PAGE_BG provides subtle separation.
• DE-03: Data Storytelling (3/6) — The dual value+percentage labels give the viewer conversion context, and the narrowing funnel shape guides the eye. However, no visual emphasis on specific drop-offs (the 40% Awareness→Interest drop is the biggest story, unmarked), and no color-intensity or size variation creates a focal point.

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct funnel chart: stages ordered largest→smallest, bars centered and narrowing
• SC-02: Required Features (4/4) — Distinct colors per stage ✓; value+percentage labels on each segment ✓; width proportional to value ✓; stages ordered correctly ✓
• SC-03: Data Mapping (3/3) — Stages on Y axis, bar width encodes value, all 5 stages visible
• SC-04: Title & Legend (2/3) — Title is "Sales Funnel · funnel-basic · altair · anyplot.ai"; required format is {spec-id} · {library} · anyplot.ai = "funnel-basic · altair · anyplot.ai". The extra "Sales Funnel · " prefix deviates from the required format. No legend needed (stages are directly labeled).

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — All funnel aspects shown: progressive narrowing, 5 distinct stages, both absolute and relative values
• DQ-02: Realistic Context (5/5) — AIDAR sales funnel (Awareness→Purchase) with plausible, neutral marketing conversion data
• DQ-03: Appropriate Scale (4/4) — Values [1000, 600, 400, 200, 100] with 10% final conversion are realistic for a sales pipeline

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: theme tokens → data → chart components → compose → save
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data, no randomness
• CQ-03: Clean Imports (2/2) — Only os, altair, and pandas imported; all used
• CQ-04: Code Elegance (2/2) — Idiomatic Altair layer composition; no fake UI; appropriate complexity
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Uses x+x2 ranged bar encoding, layer composition with +, configure_* chain for theme, alt.Title with properties. Slightly above default patterns.
• LM-02: Distinctive Features (3/5) — x/x2 encoding for centered bars (Vega-Lite/Altair-distinctive); layer composition; tooltip encoding; HTML export. Several Altair-specific features leveraged.

Score Caps Applied

• None applied (DE-01=5 > 2, DE-02=4 > 2; all other caps not triggered)

Strengths

• Perfect palette compliance: #009E73 first, correct Okabe-Ito order, backgrounds and chrome both theme-correct
• Clean dual-metric labels (value + %) that let viewers read conversion rates at a glance
• All text sizes explicitly set; both themes fully readable with no dark-on-dark failures
• Excellent code quality: KISS structure, deterministic, all Altair idioms used correctly
• Spec fully satisfied: all required funnel features present with realistic sales data

Weaknesses

• Title format deviates from required {spec-id} · {library} · anyplot.ai — needs to be "funnel-basic · altair · anyplot.ai" (the "Sales Funnel · " prefix is not the spec-id)
• No visual emphasis on key conversion drop-offs; the largest drop (Awareness→Interest, -40%) is not highlighted — a color-intensity gradient or annotation callout would create a focal point
• Canvas is slightly narrow (4200×2700 vs recommended 4800×2700); increase width to 1600 for exact compliance
• Design sophistication is good but not exceptional — typography hierarchy could be strengthened with, e.g., a subtitle showing total drop-off rate or a muted annotation for conversion context

Issues Found

1. SC-04 WRONG FORMAT: Title "Sales Funnel · funnel-basic · altair · anyplot.ai" — required is funnel-basic · altair · anyplot.ai
   • Fix: Change title string to exactly "funnel-basic · altair · anyplot.ai"
2. DE-03 LOW: Funnel data is clearly displayed but no visual hierarchy emphasizes the key insight (stage-to-stage conversion drops)
   • Fix: Use opacity/color intensity variation to highlight larger drop-off stages, or add a small conversion-rate text annotation (e.g., "−40%") between stages
3. VQ-05 MINOR: Canvas width 4200px instead of recommended 4800px
   • Fix: Change width=1400 to width=1600 to produce 4800×2700px output

AI Feedback for Next Attempt

Fix title format first: "funnel-basic · altair · anyplot.ai" (no descriptive prefix). Increase width to 1600. For design: add inter-stage conversion annotations (e.g., "↓ 40%" between Awareness and Interest bars) or use decreasing bar opacity/saturation to visually weight the drop story. The dual value+percentage labels are a strong foundation — build on them with a subtle emphasis mechanism.

Verdict: REJECTED