feat(altair): implement gauge-basic (#5396)

## Implementation: `gauge-basic` - python/altair

Implements the **python/altair** version of `gauge-basic`.

**File:** `plots/gauge-basic/implementations/python/altair.py`

**Parent Issue:** #857

---
:robot: *[impl-generate
workflow](https://github.com/MarkusNeusinger/anyplot/actions/runs/24931340754)*

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/gauge-basic/implementations/python/altair.py

@@ -1,126 +1,135 @@
-""" pyplots.ai
+""" anyplot.ai
 gauge-basic: Basic Gauge Chart
-Library: altair 6.0.0 | Python 3.13.11
-Quality: 92/100 | Created: 2025-12-23
+Library: altair 6.1.0 | Python 3.14.4
+Quality: 88/100 | Updated: 2026-04-25
 """
 
+import os
+
 import altair as alt
 import numpy as np
 import pandas as pd
 
 
-# Data - Sales performance gauge
+# Theme tokens
+THEME = os.getenv("ANYPLOT_THEME", "light")
+PAGE_BG = "#FAF8F1" if THEME == "light" else "#1A1A17"
+ELEVATED_BG = "#FFFDF6" if THEME == "light" else "#242420"
+INK = "#1A1A17" if THEME == "light" else "#F0EFE8"
+INK_SOFT = "#4A4A44" if THEME == "light" else "#B8B7B0"
+INK_MUTED = "#6B6A63" if THEME == "light" else "#A8A79F"
+
+# Okabe-Ito zone colors (colorblind-safe red/yellow/green)
+ZONE_BAD = "#D55E00"  # vermillion
+ZONE_WARN = "#E69F00"  # orange
+ZONE_GOOD = "#009E73"  # bluish green (brand)
+
+# Data — Sales performance gauge
 value = 72
 min_value = 0
 max_value = 100
 thresholds = [30, 70]
 
+# Geometry: semi-circle from -pi/2 (left) to +pi/2 (right)
+boundaries = np.array([min_value] + thresholds + [max_value], dtype=float)
+boundary_angles = -np.pi / 2 + (boundaries - min_value) / (max_value - min_value) * np.pi
+needle_angle = -np.pi / 2 + (value - min_value) / (max_value - min_value) * np.pi
 
-# Calculate angles for semi-circular gauge (180 degrees)
-# Map min_value to -pi/2 (left, 9 o'clock) and max_value to pi/2 (right, 3 o'clock)
-def value_to_angle(v):
-    ratio = (v - min_value) / (max_value - min_value)
-    return -np.pi / 2 + ratio * np.pi
-
-
-# Create arc segments for color zones
-zones = []
-zone_colors = ["#E53935", "#FFD43B", "#4CAF50"]  # Red, Yellow, Green
-boundaries = [min_value] + thresholds + [max_value]
-
-for i in range(len(boundaries) - 1):
-    start_angle = value_to_angle(boundaries[i])
-    end_angle = value_to_angle(boundaries[i + 1])
-    zones.append(
-        {
-            "zone": i,
-            "start": boundaries[i],
-            "end": boundaries[i + 1],
-            "startAngle": start_angle,
-            "endAngle": end_angle,
-            "color": zone_colors[i],
-        }
-    )
-
-zones_df = pd.DataFrame(zones)
+# Zone arcs
+zones_df = pd.DataFrame(
+    {"startAngle": boundary_angles[:-1], "endAngle": boundary_angles[1:], "color": [ZONE_BAD, ZONE_WARN, ZONE_GOOD]}
+)
 
-# Create the gauge background arcs
 gauge_arcs = (
     alt.Chart(zones_df)
-    .mark_arc(innerRadius=220, outerRadius=360, cornerRadius=6)
+    .mark_arc(innerRadius=220, outerRadius=360, cornerRadius=6, stroke=PAGE_BG, strokeWidth=4)
     .encode(
         theta=alt.Theta("startAngle:Q", scale=None),
         theta2="endAngle:Q",
         color=alt.Color("color:N", scale=None, legend=None),
     )
 )
 
-# Create needle indicator
-needle_angle = value_to_angle(value)
+# Needle
 needle_length = 300
-needle_x = needle_length * np.sin(needle_angle)
-needle_y = needle_length * np.cos(needle_angle)
-
-needle_df = pd.DataFrame([{"x": 0, "y": 0, "x2": needle_x, "y2": needle_y}])
-
+needle_df = pd.DataFrame(
+    [{"x": 0.0, "y": 0.0, "x2": needle_length * np.sin(needle_angle), "y2": needle_length * np.cos(needle_angle)}]
+)
 needle = (
     alt.Chart(needle_df)
-    .mark_rule(color="#306998", strokeWidth=10, strokeCap="round")
+    .mark_rule(color=INK, strokeWidth=10, strokeCap="round")
     .encode(
-        x=alt.X("x:Q", scale=alt.Scale(domain=[-500, 500]), axis=None),
-        y=alt.Y("y:Q", scale=alt.Scale(domain=[-200, 500]), axis=None),
+        x=alt.X("x:Q", scale=alt.Scale(domain=[-450, 450]), axis=None),
+        y=alt.Y("y:Q", scale=alt.Scale(domain=[-260, 440]), axis=None),
         x2="x2:Q",
         y2="y2:Q",
     )
 )
 
-# Center hub circle
+# Center hub (two-tone for definition)
 hub_df = pd.DataFrame([{"x": 0, "y": 0}])
-hub = alt.Chart(hub_df).mark_circle(size=2000, color="#306998").encode(x="x:Q", y="y:Q")
+hub_outer = alt.Chart(hub_df).mark_circle(size=2400, color=INK).encode(x="x:Q", y="y:Q")
+hub_inner = alt.Chart(hub_df).mark_circle(size=400, color=PAGE_BG).encode(x="x:Q", y="y:Q")
 
-# Value label with unit
-value_label_df = pd.DataFrame([{"x": 0, "y": -120, "text": f"{value}%"}])
+# Prominent value label (centered below hub)
+value_label_df = pd.DataFrame([{"x": 0, "y": -140, "text": f"{value}"}])
 value_label = (
     alt.Chart(value_label_df)
-    .mark_text(fontSize=80, fontWeight="bold", color="#306998")
+    .mark_text(fontSize=88, fontWeight="bold", color=ZONE_GOOD, baseline="middle")
     .encode(x="x:Q", y="y:Q", text="text:N")
 )
 
-# Min and max labels positioned at arc ends
-min_label_x = 400 * np.sin(value_to_angle(min_value))
-min_label_y = 400 * np.cos(value_to_angle(min_value))
-max_label_x = 400 * np.sin(value_to_angle(max_value))
-max_label_y = 400 * np.cos(value_to_angle(max_value))
+context_label_df = pd.DataFrame([{"x": 0, "y": -220, "text": "Current Sales"}])
+context_label = (
+    alt.Chart(context_label_df)
+    .mark_text(fontSize=22, color=INK_MUTED, baseline="middle")
+    .encode(x="x:Q", y="y:Q", text="text:N")
+)
 
-labels_df = pd.DataFrame(
+# Min and max labels just below the arc ends
+range_label_radius = 290
+range_labels_df = pd.DataFrame(
     [
-        {"x": min_label_x - 50, "y": min_label_y, "text": str(min_value)},
-        {"x": max_label_x + 50, "y": max_label_y, "text": str(max_value)},
+        {"x": range_label_radius * np.sin(boundary_angles[0]), "y": -50, "text": str(min_value)},
+        {"x": range_label_radius * np.sin(boundary_angles[-1]), "y": -50, "text": str(max_value)},
     ]
 )
-range_labels = alt.Chart(labels_df).mark_text(fontSize=36, color="#555555").encode(x="x:Q", y="y:Q", text="text:N")
-
-# Threshold labels on the arc
-threshold_labels_data = []
-for t in thresholds:
-    angle = value_to_angle(t)
-    label_radius = 420
-    threshold_labels_data.append({"x": label_radius * np.sin(angle), "y": label_radius * np.cos(angle), "text": str(t)})
+range_labels = (
+    alt.Chart(range_labels_df)
+    .mark_text(fontSize=26, color=INK_SOFT, fontWeight="bold")
+    .encode(x="x:Q", y="y:Q", text="text:N")
+)
 
-threshold_labels_df = pd.DataFrame(threshold_labels_data)
+# Threshold labels above the arc
+threshold_angles = -np.pi / 2 + (np.array(thresholds, dtype=float) - min_value) / (max_value - min_value) * np.pi
+threshold_label_radius = 400
+threshold_labels_df = pd.DataFrame(
+    {
+        "x": threshold_label_radius * np.sin(threshold_angles),
+        "y": threshold_label_radius * np.cos(threshold_angles),
+        "text": [str(t) for t in thresholds],
+    }
+)
 threshold_labels = (
-    alt.Chart(threshold_labels_df).mark_text(fontSize=32, color="#555555").encode(x="x:Q", y="y:Q", text="text:N")
+    alt.Chart(threshold_labels_df)
+    .mark_text(fontSize=24, color=INK_SOFT, fontWeight="bold", dy=-10)
+    .encode(x="x:Q", y="y:Q", text="text:N")
 )
 
-# Combine all layers
+# Compose layers
 chart = (
-    alt.layer(gauge_arcs, needle, hub, value_label, range_labels, threshold_labels)
+    alt.layer(gauge_arcs, needle, hub_outer, hub_inner, threshold_labels, range_labels, value_label, context_label)
     .properties(
-        width=1600, height=900, title=alt.Title("gauge-basic · altair · pyplots.ai", fontSize=48, anchor="middle")
+        width=1600,
+        height=900,
+        background=PAGE_BG,
+        title=alt.Title(
+            "gauge-basic · altair · anyplot.ai", fontSize=28, anchor="middle", color=INK, fontWeight="normal"
+        ),
     )
-    .configure_view(strokeWidth=0)
+    .configure_view(strokeWidth=0, fill=PAGE_BG)
 )
 
 # Save
-chart.save("plot.png", scale_factor=3.0)
-chart.save("plot.html")
+chart.save(f"plot-{THEME}.png", scale_factor=3.0)
+chart.save(f"plot-{THEME}.html")