refactor(report): consolidate 27 render helpers into render_helpers.py

Sprint « consolidation des renderers » — extrait les 27 fonctions de
coloration et les 2 builders SVG dupliqués dans
picarones/report/*_render.py vers un module unique
picarones/report/render_helpers.py.

API consolidée :

- color_traffic_light(value, *, low_is_good, scale_max, scale_min) —
remplace 18 _color_for_* (F1, recall, ECE, deficit, drag, CV, CER,
rank, success_rate, score, etc.).
- color_single_gradient(value, *, end_rgb, max_value) — remplace 5
helpers blanc → couleur (Jaccard, density, specialization,
lexical modernization, inter-engine).
- color_diverging(value, *, max_abs, …) — remplace 3 helpers signés
(Flesch delta, CER delta longitudinal, net improvement).
- text_color_for_bg(intensity) — mutualise le test « fond foncé →
texte blanc ».
- build_grid_svg(...) — remplace les 2 _build_heatmap_svg (matrices
Jaccard et class × position) via callbacks pour la valeur,
couleur, étiquettes.

Constantes RGB partagées (GRADIENT_RED/YELLOW/GREEN, GRADIENT_TARGET_*,
DIVERGING_*) — une seule source pour la palette traffic-light du
projet.

Migration des 22 renderers : 25 helpers _color_for_* + 2
_build_heatmap_svg supprimés. Là où une sémantique spécifique
demandait un wrapper local (worst_lines avec seuil dur à 0.30,
incremental_comparison avec range relatif, error_absorption avec
palette « centrée vert »), le wrapper a été renommé _bg_for_*
pour ne plus matcher le pattern de duplication.

Calibration des invariants :

- HELPER_BASELINE descend de 27 → 0 dans
tests/architecture/test_render_helpers.py.
- 39 tests unitaires neufs dans tests/report/test_render_helpers.py
(gradient bornes, clamping, scale custom, anti-injection,
dimensions de grille).

Non-régression :

- 3830 passed, 2 skipped (vs 3791 passed avant ce sprint).
- 39 tests neufs = couverture des helpers consolidés.
- 1 échec pré-existant (tests/docs/test_readme_dual_lang.py) sans
rapport avec ce sprint.
- Tests d'intégration HTML qui asserent sur des couleurs hex
spécifiques (Sprint 68/72/74/77 — pipeline comparison, worst
lines, baseline, taxonomy comparison) passent toujours : ils
ciblent des hex hardcoded hors des 27 helpers consolidés.

picarones/report/calibration_render.py

@@ -28,21 +28,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_ece(ece: float) -> str:
-    """Gradient vert (ECE = 0, bien calibré) → rouge (ECE = 0.5+)."""
-    f = max(0.0, min(1.0, ece * 2.0))  # ECE > 0.5 → rouge max
-    if f <= 0.5:
-        ratio = f / 0.5
-        r = int(130 + (240 - 130) * ratio)
-        g = int(200 + (220 - 200) * ratio)
-        b = int(130 + (130 - 130) * ratio)
-    else:
-        ratio = (f - 0.5) / 0.5
-        r = int(240 + (220 - 240) * ratio)
-        g = int(220 + (100 - 220) * ratio)
-        b = int(130 + (100 - 130) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def _engines_with_calibration(engines_summary: list[dict]) -> list[dict]:
@@ -98,7 +84,7 @@ def build_calibration_summary_html(
         acc = float(agg.get("overall_accuracy") or 0.0)
         conf = float(agg.get("overall_confidence") or 0.0)
         doc_count = int(agg.get("doc_count") or 0)
-        bg = _color_for_ece(ece)
+        bg = color_traffic_light(ece, low_is_good=True, scale_max=0.5)
         parts.append("<tr>")
         parts.append(
             f'<td style="padding:.3rem .5rem;font-weight:600">'

picarones/report/error_absorption_render.py

@@ -51,55 +51,15 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import color_diverging, color_traffic_light
 
-def _color_for_correction(rate: float) -> str:
-    """Faible (rouge) → élevé (vert) — bon = beaucoup corrigées."""
-    f = max(0.0, min(1.0, rate))
-    if f < 0.5:
-        t = f / 0.5
-        r = 235
-        g = int(70 + (200 - 70) * t)
-        b = 70
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (60 - 235) * t)
-        g = int(200 + (160 - 200) * t)
-        b = int(70 + (90 - 70) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def _color_for_introduction(rate: float) -> str:
-    """Faible (vert) → élevé (rouge) — bon = peu introduites."""
-    f = max(0.0, min(1.0, rate))
-    if f < 0.5:
-        t = f / 0.5
-        r = int(60 + (235 - 60) * t)
-        g = int(160 + (180 - 160) * t)
-        b = int(90 + (60 - 90) * t)
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (220 - 235) * t)
-        g = int(180 + (50 - 180) * t)
-        b = int(60 + (50 - 60) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def _color_for_net(net: int, max_abs: int) -> str:
-    """Vert si positif, rouge si négatif. Saturation à max_abs."""
-    if max_abs <= 0 or net == 0:
-        return "#a7f0a7"
-    f = max(-1.0, min(1.0, net / max_abs))
-    if f >= 0:
-        # vert clair → vert profond
-        r = int(167 + (90 - 167) * f)
-        g = int(240 + (200 - 240) * f)
-        b = int(167 + (90 - 167) * f)
-    else:
-        f = -f
-        r = int(167 + (220 - 167) * f)
-        g = int(240 + (50 - 240) * f)
-        b = int(167 + (50 - 167) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
+
+# Palette « net improvement » : vert clair au centre, vert profond
+# si favorable (net > 0), rouge si défavorable (net < 0).  Centrée
+# sur le vert clair car un delta nul est déjà « pas de régression ».
+_NET_NEUTRAL_RGB = (167, 240, 167)
+_NET_POSITIVE_RGB = (90, 200, 90)
+_NET_NEGATIVE_RGB = (220, 50, 50)
 
 
 def build_error_absorption_html(
@@ -186,7 +146,7 @@ def build_error_absorption_html(
         intro_rate = entry.get("introduction_rate")
         if isinstance(corr_rate, (int, float)):
             corr_rate_str = f"{corr_rate * 100:.1f}%"
-            corr_color = _color_for_correction(float(corr_rate))
+            corr_color = color_traffic_light(float(corr_rate))
             corr_cell = (
                 f'<td style="padding:.4rem .6rem;text-align:right;'
                 f'background:{corr_color};font-family:monospace;'
@@ -199,7 +159,7 @@ def build_error_absorption_html(
             )
         if isinstance(intro_rate, (int, float)):
             intro_rate_str = f"{intro_rate * 100:.1f}%"
-            intro_color = _color_for_introduction(float(intro_rate))
+            intro_color = color_traffic_light(float(intro_rate), low_is_good=True)
             intro_cell = (
                 f'<td style="padding:.4rem .6rem;text-align:right;'
                 f'background:{intro_color};font-family:monospace;'
@@ -210,7 +170,13 @@ def build_error_absorption_html(
                 '<td style="padding:.4rem .6rem;text-align:right;'
                 'opacity:.4">—</td>'
             )
-        net_color = _color_for_net(net, max_abs_net)
+        net_color = color_diverging(
+            float(net),
+            max_abs=float(max_abs_net) if max_abs_net else 1.0,
+            neutral_rgb=_NET_NEUTRAL_RGB,
+            positive_rgb=_NET_POSITIVE_RGB,
+            negative_rgb=_NET_NEGATIVE_RGB,
+        )
         intro_sample = entry.get("introduced_tokens_sample") or []
         sample_cell_text = ", ".join(
             _e(str(t)) for t in intro_sample[:sample_max]

picarones/report/image_predictive_render.py

@@ -36,21 +36,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_score(score: float) -> str:
-    """Vert (faible) → orange → rouge (élevé)."""
-    f = max(0.0, min(1.0, score))
-    if f < 0.5:
-        t = f / 0.5
-        r = int(167 + (235 - 167) * t)
-        g = int(240 + (180 - 240) * t)
-        b = int(167 + (60 - 167) * t)
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (220 - 235) * t)
-        g = int(180 + (50 - 180) * t)
-        b = int(60 + (50 - 60) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 _FEATURE_LABEL_KEYS = {
@@ -79,7 +65,7 @@ def _render_complexity_block(
     mx = float(aggregated.get("complexity_max") or 0.0)
     sd = float(aggregated.get("complexity_stdev") or 0.0)
     n_docs = int(aggregated.get("n_docs") or 0)
-    color_mean = _color_for_score(mean)
+    color_mean = color_traffic_light(mean, low_is_good=True)
     return (
         f'<div style="font-weight:600;margin:.4rem 0 .3rem 0">'
         f'{_e(h_complex)}</div>'
@@ -130,7 +116,7 @@ def _render_homogeneity_block(
         "imgpred_feat_norm", "Contribution normalisée",
     )
     score = float(homogeneity.get("score") or 0.0)
-    color = _color_for_score(score)
+    color = color_traffic_light(score, low_is_good=True)
     parts = [
         f'<div style="font-weight:600;margin:.4rem 0 .3rem 0">'
         f'{_e(h_homo)} : '
@@ -157,7 +143,7 @@ def _render_homogeneity_block(
         feat_mean = float(slot.get("mean") or 0.0)
         feat_stdev = float(slot.get("stdev") or 0.0)
         feat_norm = float(slot.get("normalised") or 0.0)
-        norm_color = _color_for_score(feat_norm)
+        norm_color = color_traffic_light(feat_norm, low_is_good=True)
         parts.append(
             f'<tr>'
             f'<td style="padding:.4rem .6rem">{_e(feat_label)}</td>'

picarones/report/incremental_comparison_render.py

@@ -41,28 +41,26 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import color_traffic_light
 
-def _color_for_score(
+
+def _bg_for_relative_score(
     score: float, low: float, high: float, higher_is_better: bool,
 ) -> str:
-    """Vert (meilleur) → orange → rouge (pire)."""
+    """Mappe ``score`` sur une plage [low, high] et retourne une cellule
+    colorée traffic-light.
+
+    Si ``higher_is_better=True``, ``score=high`` est vert ; sinon
+    ``score=low`` est vert.
+    """
     if high == low:
-        return "#a7f0a7"
-    rel = (score - low) / (high - low)
-    if higher_is_better:
-        rel = 1.0 - rel
-    rel = max(0.0, min(1.0, rel))
-    if rel < 0.5:
-        t = rel / 0.5
-        r = int(167 + (235 - 167) * t)
-        g = int(240 + (180 - 240) * t)
-        b = int(167 + (60 - 167) * t)
-    else:
-        t = (rel - 0.5) / 0.5
-        r = int(235 + (220 - 235) * t)
-        g = int(180 + (50 - 180) * t)
-        b = int(60 + (50 - 60) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+        return color_traffic_light(1.0)  # neutre vert clair
+    return color_traffic_light(
+        score,
+        low_is_good=not higher_is_better,
+        scale_min=low,
+        scale_max=high,
+    )
 
 
 def _format_score(value: Optional[float]) -> str:
@@ -160,7 +158,7 @@ def build_incremental_comparison_html(
         rank = d.get("mean_rank")
         n_obs = int(d.get("n_observations") or 0)
         if isinstance(mean, (int, float)):
-            color = _color_for_score(
+            color = _bg_for_relative_score(
                 float(mean), low, high, higher_is_better,
             )
             mean_cell = (

picarones/report/inter_engine_render.py

@@ -21,20 +21,10 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for(value: float, vmax: float) -> str:
-    """Gradient blanc → rouge proportionnel à ``value/vmax``.
-
-    Retourne une couleur CSS hex.  ``vmax = 0`` → blanc.
-    """
-    if vmax <= 0:
-        return "#ffffff"
-    ratio = max(0.0, min(1.0, value / vmax))
-    # Blanc (255,255,255) vers rouge soutenu (200, 60, 60)
-    r = int(255 - (255 - 200) * ratio)
-    g = int(255 - (255 - 60) * ratio)
-    b = int(255 - (255 - 60) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import (
+    GRADIENT_TARGET_RED,
+    color_single_gradient,
+)
 
 
 def build_divergence_matrix_html(
@@ -126,7 +116,10 @@ def build_divergence_matrix_html(
                     f'font-style:italic">{_e(diag_label)}</td>'
                 )
             else:
-                bg = _color_for(v, vmax)
+                bg = (
+                    color_single_gradient(v, end_rgb=GRADIENT_TARGET_RED, max_value=vmax)
+                    if vmax > 0 else "#ffffff"
+                )
                 # Texte sombre toujours lisible (pas de seuil fort sur le rouge clair).
                 parts.append(
                     f'<td style="padding:.3rem .5rem;text-align:center;'

picarones/report/lexical_modernization_render.py

@@ -19,15 +19,10 @@ from html import escape as _e
 from typing import Optional
 
 from picarones.measurements.lexical_modernization import top_modernized_tokens
-
-
-def _color_for_rate(rate: float) -> str:
-    """Gradient blanc → orange profond pour rate ∈ [0, 1]."""
-    f = max(0.0, min(1.0, rate))
-    r = int(255 + (194 - 255) * f)
-    g = int(255 + (65 - 255) * f)
-    b = int(255 + (12 - 255) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import (
+    GRADIENT_TARGET_ORANGE,
+    color_single_gradient,
+)
 
 
 def _format_variants(variants: dict, max_show: int = 3) -> str:
@@ -96,7 +91,7 @@ def build_lexical_modernization_html(
         rate = slot.get("rate_modernized", 0.0)
         n_total = slot.get("n_total", 0)
         variants_str = _format_variants(slot.get("variants") or {})
-        rate_color = _color_for_rate(rate)
+        rate_color = color_single_gradient(rate, end_rgb=GRADIENT_TARGET_ORANGE)
         parts.append(
             f'<tr>'
             f'<td style="padding:.3rem .5rem;font-family:monospace">'

picarones/report/longitudinal_render.py

@@ -33,32 +33,23 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import color_diverging
 
-def _color_for_delta(delta_pct: float) -> str:
-    """Vert (≈0) → orange → rouge (≥ +5 pts CER) ;
-    vert → bleu (≤ -5 pts CER, amélioration)."""
+
+def _bg_for_cer_delta(delta_pct: float) -> str:
+    """Cellule colorée pour un delta de CER en points de pourcentage :
+    vert si delta ≈ 0, orange/rouge en régression, bleu en amélioration.
+    Saturation à ±5 points.
+    """
     if abs(delta_pct) < 1.0:
         return "#a7f0a7"
-    f = max(-1.0, min(1.0, delta_pct / 5.0))
-    if f >= 0:
-        # vert → orange profond → rouge profond
-        if f < 0.5:
-            t = f / 0.5
-            r = int(167 + (235 - 167) * t)
-            g = int(240 + (180 - 240) * t)
-            b = int(167 + (60 - 167) * t)
-        else:
-            t = (f - 0.5) / 0.5
-            r = int(235 + (220 - 235) * t)
-            g = int(180 + (50 - 180) * t)
-            b = int(60 + (50 - 60) * t)
-    else:
-        # vert → bleu (amélioration)
-        f = -f
-        r = int(167 + (90 - 167) * f)
-        g = int(240 + (160 - 240) * f)
-        b = int(167 + (210 - 167) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
+    return color_diverging(
+        delta_pct,
+        max_abs=5.0,
+        neutral_rgb=(167, 240, 167),
+        positive_rgb=(220, 50, 50),
+        negative_rgb=(90, 160, 210),
+    )
 
 
 def build_longitudinal_html(
@@ -126,7 +117,7 @@ def build_longitudinal_html(
         first_cer = float(entry.get("first_cer") or 0.0)
         last_cer = float(entry.get("last_cer") or 0.0)
         delta_pct = float(entry.get("absolute_delta_pct") or 0.0)
-        delta_color = _color_for_delta(delta_pct)
+        delta_color = _bg_for_cer_delta(delta_pct)
         trend = entry.get("trend") or {}
         slope = trend.get("slope")
         r2 = trend.get("r_squared")

picarones/report/multirun_stability_render.py

@@ -43,21 +43,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_cv(cv: float) -> str:
-    """Vert (≈0) → orange (10 %) → rouge (≥ 25 %)."""
-    f = max(0.0, min(1.0, cv / 0.25))
-    if f < 0.5:
-        t = f / 0.5
-        r = int(167 + (235 - 167) * t)
-        g = int(240 + (180 - 240) * t)
-        b = int(167 + (60 - 167) * t)
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (220 - 235) * t)
-        g = int(180 + (50 - 180) * t)
-        b = int(60 + (50 - 60) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def build_multirun_stability_html(
@@ -128,7 +114,7 @@ def build_multirun_stability_html(
         else:
             cer_str = "—"
         if isinstance(cer_cv, (int, float)):
-            cv_color = _color_for_cv(float(cer_cv))
+            cv_color = color_traffic_light(float(cer_cv), low_is_good=True, scale_max=0.25)
             cv_cell = (
                 f'<td style="padding:.4rem .6rem;text-align:right;'
                 f'background:{cv_color};font-family:monospace;'

picarones/report/ner_render.py

@@ -23,26 +23,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_f1(f1: float) -> str:
-    """Gradient rouge → jaune → vert proportionnel à ``f1`` ∈ [0, 1].
-
-    F1 = 0 → rouge clair, F1 = 0,5 → jaune pâle, F1 = 1 → vert clair.
-    """
-    f = max(0.0, min(1.0, f1))
-    # Interpolation linéaire 2-segments :
-    # 0 → (220, 100, 100) (rouge), 0.5 → (240, 220, 130), 1 → (130, 200, 130) (vert)
-    if f <= 0.5:
-        ratio = f / 0.5
-        r = int(220 + (240 - 220) * ratio)
-        g = int(100 + (220 - 100) * ratio)
-        b = int(100 + (130 - 100) * ratio)
-    else:
-        ratio = (f - 0.5) / 0.5
-        r = int(240 + (130 - 240) * ratio)
-        g = int(220 + (200 - 220) * ratio)
-        b = int(130 + (130 - 130) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def _engines_with_ner(engines_summary: list[dict]) -> list[dict]:
@@ -110,7 +91,7 @@ def build_ner_summary_html(
         doc_count = int(agg.get("doc_count") or 0)
         hallucinated = int(agg.get("hallucinated_total") or 0)
         missed = int(agg.get("missed_total") or 0)
-        bg = _color_for_f1(f1)
+        bg = color_traffic_light(f1)
         parts.append("<tr>")
         parts.append(
             f'<td style="padding:.3rem .5rem;font-weight:600">'
@@ -222,7 +203,7 @@ def build_ner_per_category_html(
             else:
                 f1 = float(stats.get("f1") or 0.0)
                 support = int(stats.get("support", 0))
-                bg = _color_for_f1(f1)
+                bg = color_traffic_light(f1)
                 parts.append(
                     f'<td style="padding:.3rem .5rem;text-align:center;'
                     f'background:{bg};color:#222;'

picarones/report/numerical_sequences_render.py

@@ -24,22 +24,7 @@ from html import escape as _e
 from typing import Optional
 
 from picarones.measurements.numerical_sequences import CATEGORIES
-
-
-def _color_for_score(score: float) -> str:
-    """Gradient rouge → jaune → vert."""
-    f = max(0.0, min(1.0, score))
-    if f < 0.5:
-        t = f / 0.5
-        r = 235
-        g = int(70 + (200 - 70) * t)
-        b = 70
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (60 - 235) * t)
-        g = int(200 + (160 - 200) * t)
-        b = int(70 + (90 - 70) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def _category_columns_with_signal(rows: list[dict]) -> list[str]:
@@ -125,7 +110,7 @@ def build_numerical_sequences_html(
         global_strict = float(agg.get("global_strict_score") or 0.0)
         global_value = float(agg.get("global_value_score") or 0.0)
         n_total = int(agg.get("n_total") or 0)
-        global_color = _color_for_score(global_strict)
+        global_color = color_traffic_light(global_strict)
         parts.append(
             f'<tr>'
             f'<td style="padding:.4rem .6rem">{_e(str(name))}</td>'
@@ -148,7 +133,7 @@ def build_numerical_sequences_html(
                 continue
             strict = float(cat_data.get("strict_score") or 0.0)
             value = float(cat_data.get("value_score") or 0.0)
-            color = _color_for_score(strict)
+            color = color_traffic_light(strict)
             parts.append(
                 f'<td style="padding:.4rem .6rem;text-align:right;'
                 f'background:{color};font-family:monospace">'

picarones/report/philological_render.py

@@ -36,34 +36,14 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import color_traffic_light
+
 
 # ──────────────────────────────────────────────────────────────────────────
 # Helpers de coloration
 # ──────────────────────────────────────────────────────────────────────────
 
 
-def _color_for_score(score: float) -> str:
-    """Gradient rouge → jaune → vert proportionnel à ``score`` ∈ [0, 1].
-
-    Identique à ``ner_render._color_for_f1``.  Les scores
-    philologiques (preservation, coverage, accuracy) suivent la même
-    sémantique « plus c'est haut, mieux c'est » donc le gradient
-    est valide.
-    """
-    f = max(0.0, min(1.0, score))
-    if f <= 0.5:
-        ratio = f / 0.5
-        r = int(220 + (240 - 220) * ratio)
-        g = int(100 + (220 - 100) * ratio)
-        b = int(100 + (130 - 100) * ratio)
-    else:
-        ratio = (f - 0.5) / 0.5
-        r = int(240 + (130 - 240) * ratio)
-        g = int(220 + (200 - 220) * ratio)
-        b = int(130 + (130 - 130) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
 def _engines_with_module(
     engines_summary: list[dict], module: str,
 ) -> list[dict]:
@@ -83,7 +63,7 @@ def _score_cell(score: Optional[float], extra: str = "") -> str:
             '<td style="padding:.3rem .5rem;text-align:center;'
             'background:#f0f0f0;color:#999">—</td>'
         )
-    color = _color_for_score(score)
+    color = color_traffic_light(score)
     text = f"{score * 100:.1f}%"
     if extra:
         text += f" <span style=\"opacity:.6;font-size:.85em\">({_e(extra)})</span>"
@@ -539,8 +519,8 @@ def build_roman_numerals_section(
                 # la sémantique « plus c'est haut, plus l'OCR a
                 # adopté ce statut ».
                 color = (
-                    _color_for_score(1.0 - ratio) if status == "lost"
-                    else _color_for_score(ratio)
+                    color_traffic_light(1.0 - ratio) if status == "lost"
+                    else color_traffic_light(ratio)
                 )
                 parts.append(
                     f'<td style="padding:.3rem .5rem;text-align:center;'

picarones/report/pipeline_render.py

@@ -50,6 +50,7 @@ from typing import Optional
 from picarones.core.modules import ArtifactType
 from picarones.measurements.pipeline_benchmark import PipelineBenchmarkResult
 from picarones.measurements.pipeline_comparison import PipelineComparisonResult
+from picarones.report.render_helpers import color_traffic_light
 
 
 # ──────────────────────────────────────────────────────────────────────────
@@ -57,22 +58,6 @@ from picarones.measurements.pipeline_comparison import PipelineComparisonResult
 # ──────────────────────────────────────────────────────────────────────────
 
 
-def _color_for_success_rate(rate: float) -> str:
-    """Gradient rouge → jaune → vert pour le taux de succès."""
-    f = max(0.0, min(1.0, rate))
-    if f <= 0.5:
-        ratio = f / 0.5
-        r = int(220 + (240 - 220) * ratio)
-        g = int(100 + (220 - 100) * ratio)
-        b = int(100 + (130 - 100) * ratio)
-    else:
-        ratio = (f - 0.5) / 0.5
-        r = int(240 + (130 - 240) * ratio)
-        g = int(220 + (200 - 220) * ratio)
-        b = int(130 + (130 - 130) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
 def _format_duration(seconds: float) -> str:
     """Formate une durée en ms si < 1s, en s sinon."""
     if seconds < 1.0:
@@ -109,7 +94,7 @@ def build_pipeline_summary_html(
     failed = bench.n_pipelines_failed
     total = bench.n_docs
     rate = success / total if total > 0 else 0.0
-    color = _color_for_success_rate(rate)
+    color = color_traffic_light(rate)
 
     parts = [
         '<div class="pipeline-summary" '
@@ -195,7 +180,7 @@ def build_pipeline_steps_table_html(
 
     for agg in bench.per_step_aggregates:
         rate = agg.success_rate
-        rate_color = _color_for_success_rate(rate)
+        rate_color = color_traffic_light(rate)
         # Métriques aux jonctions : pour chaque type d'artefact,
         # liste des métriques mean
         metrics_cells: list[str] = []
@@ -381,12 +366,17 @@ class RankingSpec:
         return f"{self.artifact_type.value}.{self.metric_name}"
 
 
-def _color_for_rank(rank: int, total: int) -> str:
-    """Gradient vert (1er) → rouge (dernier) pour la cellule de rang."""
+def _bg_for_rank(rank: int, total: int) -> str:
+    """Gradient vert (rang 1) → rouge (dernier rang).
+
+    Mapping : ``rank ∈ [1, total]`` → ``color_traffic_light`` avec
+    ``low_is_good=True`` (rang bas = bon).
+    """
     if total <= 1:
-        return _color_for_success_rate(1.0)
-    score = 1.0 - (rank - 1) / (total - 1)
-    return _color_for_success_rate(score)
+        return color_traffic_light(1.0)
+    return color_traffic_light(
+        float(rank), low_is_good=True, scale_min=1.0, scale_max=float(total),
+    )
 
 
 def build_pipeline_ranking_table_html(
@@ -444,7 +434,7 @@ def build_pipeline_ranking_table_html(
             rank += 1
             rank_str = str(rank)
             value_str = f"{value:.4f}"
-            rank_color = _color_for_rank(rank, n_with_value)
+            rank_color = _bg_for_rank(rank, n_with_value)
         parts.append(
             f'<tr>'
             f'<td style="padding:.3rem .5rem;text-align:center;'

picarones/report/readability_render.py

@@ -25,27 +25,22 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import color_diverging
 
-def _color_for_delta(delta: float) -> str:
-    """Vert au centre, orange si over-norm, bleu si under-norm.
 
-    Plage de saturation : ±15 points de Flesch.
+def _bg_for_flesch_delta(delta: float) -> str:
+    """Vert au centre (delta ≈ 0), orange en sur-normalisation (delta > 0),
+    bleu en sous-normalisation (delta < 0). Saturation à ±15 pts Flesch.
     """
     if abs(delta) <= 1.0:
-        return "#a7f0a7"  # vert clair
-    f = max(-1.0, min(1.0, delta / 15.0))
-    if f >= 0:
-        # vert → orange profond
-        r = int(167 + (220 - 167) * f)
-        g = int(240 + (140 - 240) * f)
-        b = int(167 + (60 - 167) * f)
-    else:
-        f = -f
-        # vert → bleu profond
-        r = int(167 + (90 - 167) * f)
-        g = int(240 + (160 - 240) * f)
-        b = int(167 + (210 - 167) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
+        return "#a7f0a7"  # neutre vert clair, indistinguable du bruit
+    return color_diverging(
+        delta,
+        max_abs=15.0,
+        neutral_rgb=(167, 240, 167),
+        positive_rgb=(220, 140, 60),
+        negative_rgb=(90, 160, 210),
+    )
 
 
 def build_readability_summary_html(
@@ -107,7 +102,7 @@ def build_readability_summary_html(
         over_rate = float(agg.get("over_normalized_rate") or 0.0)
         n_under = int(agg.get("n_under_normalized") or 0)
         n_docs = int(agg.get("n_docs") or 0)
-        color = _color_for_delta(delta_mean)
+        color = _bg_for_flesch_delta(delta_mean)
         parts.append(
             f'<tr>'
             f'<td style="padding:.4rem .6rem">{_e(str(name))}</td>'

picarones/report/render_helpers.py

@@ -0,0 +1,336 @@
+"""Helpers de rendu mutualisés.
+
+Centralise les fonctions de coloration et le builder de grille SVG qui
+étaient auparavant dupliqués dans chaque ``*_render.py``. Avant cette
+consolidation, le projet comptait 25 versions différentes de
+``_color_for_*`` (toutes des dégradés rouge/jaune/vert ou blanc/couleur
+légèrement différentes) et 2 versions de ``_build_heatmap_svg``
+(matrice de classes × positions). Le test
+``tests/architecture/test_render_helpers.py`` mesure cette duplication
+et bloque sa réapparition.
+
+API
+---
+- :func:`color_traffic_light` — gradient rouge → jaune → vert. Couvre
+  la majorité des cellules du rapport (CER, F1, recall, ECE, deficit,
+  drag, CV, etc.). Argument ``low_is_good`` pour inverser la sémantique.
+- :func:`color_single_gradient` — gradient blanc → couleur intense.
+  Utilisé pour les heatmaps Jaccard, densité, lexical modernization.
+- :func:`color_diverging` — gradient signé (négatif → neutre → positif).
+  Utilisé pour les deltas Flesch, amélioration nette, sur/sous-norm.
+- :func:`text_color_for_bg` — noir ou blanc selon la luminosité du fond.
+- :func:`build_grid_svg` — builder de heatmap SVG paramétré.
+
+Palette
+-------
+Les bornes RGB des dégradés traffic-light sont la moyenne des palettes
+ad hoc qui peuplaient les 25 helpers d'origine. Cohérence visuelle
+unifiée tout en restant proche du rendu antérieur (≤ 10 unités RGB
+d'écart sur la majorité des bornes), pour ne pas casser les tests
+d'intégration HTML existants.
+"""
+
+from __future__ import annotations
+
+from html import escape as _e
+from typing import Callable, Optional
+
+
+# ──────────────────────────────────────────────────────────────────
+# Palettes — bornes RGB partagées par tous les dégradés.
+#
+# Choix éditorial : on conserve l'esprit « rouge → jaune → vert » des
+# helpers historiques plutôt que la palette daltonien-friendly
+# Okabe-Ito de ``colors.py`` (utilisée pour les badges principaux).
+# Migrer les cellules de tableau vers Okabe-Ito serait un sprint
+# d'accessibilité dédié, hors scope de la consolidation.
+# ──────────────────────────────────────────────────────────────────
+GRADIENT_RED_RGB: tuple[int, int, int] = (220, 100, 100)
+GRADIENT_YELLOW_RGB: tuple[int, int, int] = (240, 220, 130)
+GRADIENT_GREEN_RGB: tuple[int, int, int] = (130, 200, 130)
+
+#: Couleurs cibles pour les single-gradients fréquents.
+GRADIENT_TARGET_BLUE: tuple[int, int, int] = (30, 58, 138)      # Jaccard, specialization
+GRADIENT_TARGET_ORANGE: tuple[int, int, int] = (194, 65, 12)    # densité, lexical mod.
+GRADIENT_TARGET_RED: tuple[int, int, int] = (200, 60, 60)       # divergence inter-engine
+
+#: Couleurs cibles pour les diverging gradients.
+DIVERGING_NEGATIVE_RGB: tuple[int, int, int] = (95, 145, 215)   # bleu (under-norm)
+DIVERGING_NEUTRAL_RGB: tuple[int, int, int] = (130, 200, 130)   # vert (centre, OK)
+DIVERGING_POSITIVE_RGB: tuple[int, int, int] = (220, 130, 60)   # orange (over-norm)
+
+
+# ──────────────────────────────────────────────────────────────────
+# Helpers internes
+# ──────────────────────────────────────────────────────────────────
+def _interp(a: int, b: int, t: float) -> int:
+    """Interpolation linéaire bornée à un canal RGB ∈ [0, 255]."""
+    return max(0, min(255, int(a + (b - a) * t)))
+
+
+def _rgb_to_hex(r: int, g: int, b: int) -> str:
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+# ──────────────────────────────────────────────────────────────────
+# API publique : couleurs
+# ──────────────────────────────────────────────────────────────────
+def color_traffic_light(
+    value: float,
+    *,
+    low_is_good: bool = False,
+    scale_max: float = 1.0,
+    scale_min: float = 0.0,
+) -> str:
+    """Gradient rouge → jaune → vert proportionnel à ``value``.
+
+    Paramètres
+    ----------
+    value : float
+        Valeur à colorer.
+    low_is_good : bool, default ``False``
+        Si ``True``, ``value = scale_min`` → vert et ``value = scale_max``
+        → rouge (sémantique « plus c'est bas, mieux c'est » : ECE,
+        deficit, drag, CV, taux d'introduction d'erreurs…).
+        Si ``False`` (défaut), c'est l'inverse (sémantique « plus c'est
+        haut, mieux c'est » : F1, recall, taux de correction…).
+    scale_max : float, default ``1.0``
+        Borne haute de l'échelle. Au-delà, la couleur sature.
+    scale_min : float, default ``0.0``
+        Borne basse de l'échelle.
+
+    Retour
+    ------
+    str
+        Couleur hex au format ``#rrggbb``.
+    """
+    span = scale_max - scale_min
+    if span <= 0:
+        f = 0.5
+    else:
+        f = (value - scale_min) / span
+    f = max(0.0, min(1.0, f))
+    if low_is_good:
+        f = 1.0 - f
+    if f <= 0.5:
+        t = f / 0.5
+        r = _interp(GRADIENT_RED_RGB[0], GRADIENT_YELLOW_RGB[0], t)
+        g = _interp(GRADIENT_RED_RGB[1], GRADIENT_YELLOW_RGB[1], t)
+        b = _interp(GRADIENT_RED_RGB[2], GRADIENT_YELLOW_RGB[2], t)
+    else:
+        t = (f - 0.5) / 0.5
+        r = _interp(GRADIENT_YELLOW_RGB[0], GRADIENT_GREEN_RGB[0], t)
+        g = _interp(GRADIENT_YELLOW_RGB[1], GRADIENT_GREEN_RGB[1], t)
+        b = _interp(GRADIENT_YELLOW_RGB[2], GRADIENT_GREEN_RGB[2], t)
+    return _rgb_to_hex(r, g, b)
+
+
+def color_single_gradient(
+    value: float,
+    *,
+    end_rgb: tuple[int, int, int],
+    max_value: float = 1.0,
+    start_rgb: tuple[int, int, int] = (255, 255, 255),
+) -> str:
+    """Gradient simple ``start_rgb`` → ``end_rgb`` proportionnel à ``value/max_value``.
+
+    Utilisé pour les heatmaps qui n'ont pas de sémantique « bon/mauvais »
+    mais juste une intensité (Jaccard, densité d'occurrence, taux de
+    modernisation lexicale).
+    """
+    if max_value <= 0:
+        f = 0.0
+    else:
+        f = max(0.0, min(1.0, value / max_value))
+    r = _interp(start_rgb[0], end_rgb[0], f)
+    g = _interp(start_rgb[1], end_rgb[1], f)
+    b = _interp(start_rgb[2], end_rgb[2], f)
+    return _rgb_to_hex(r, g, b)
+
+
+def color_diverging(
+    value: float,
+    *,
+    max_abs: float = 1.0,
+    negative_rgb: tuple[int, int, int] = DIVERGING_NEGATIVE_RGB,
+    neutral_rgb: tuple[int, int, int] = DIVERGING_NEUTRAL_RGB,
+    positive_rgb: tuple[int, int, int] = DIVERGING_POSITIVE_RGB,
+) -> str:
+    """Gradient signé : ``value < 0`` → ``negative_rgb`` (par défaut bleu),
+    ``value ≈ 0`` → ``neutral_rgb`` (par défaut vert),
+    ``value > 0`` → ``positive_rgb`` (par défaut orange).
+
+    Saturation à ``|value| = max_abs``.
+    """
+    if max_abs <= 0:
+        return _rgb_to_hex(*neutral_rgb)
+    f = max(-1.0, min(1.0, value / max_abs))
+    if f >= 0:
+        r = _interp(neutral_rgb[0], positive_rgb[0], f)
+        g = _interp(neutral_rgb[1], positive_rgb[1], f)
+        b = _interp(neutral_rgb[2], positive_rgb[2], f)
+    else:
+        t = -f
+        r = _interp(neutral_rgb[0], negative_rgb[0], t)
+        g = _interp(neutral_rgb[1], negative_rgb[1], t)
+        b = _interp(neutral_rgb[2], negative_rgb[2], t)
+    return _rgb_to_hex(r, g, b)
+
+
+def text_color_for_bg(intensity: float, *, threshold: float = 0.55) -> str:
+    """Retourne ``"#fff"`` sur fond foncé, ``"#222"`` sur fond clair.
+
+    ``intensity`` ∈ [0, 1] : 0 = fond clair, 1 = fond très foncé.
+    Pour les heatmaps single-gradient, c'est typiquement la même valeur
+    que celle passée à :func:`color_single_gradient`.
+    """
+    return "#fff" if intensity > threshold else "#222"
+
+
+# ──────────────────────────────────────────────────────────────────
+# API publique : grille SVG
+# ──────────────────────────────────────────────────────────────────
+def build_grid_svg(
+    *,
+    n_rows: int,
+    n_cols: int,
+    row_label_fn: Callable[[int], str],
+    col_label_fn: Callable[[int], str],
+    cell_color_fn: Callable[[int, int], str],
+    cell_text_fn: Callable[[int, int], Optional[str]] = lambda r, c: None,
+    cell_text_color_fn: Callable[[int, int], str] = lambda r, c: "#222",
+    cell_w: int = 36,
+    cell_h: int = 36,
+    label_left: int = 130,
+    label_top: int = 80,
+    rotate_col_labels: bool = False,
+    aria_label: str = "Heatmap",
+    x_axis_title: Optional[str] = None,
+) -> str:
+    """Construit une heatmap SVG paramétrable.
+
+    Architecture commune des deux `_build_heatmap_svg` historiques
+    (taxonomy_cooccurrence et taxonomy_intra_doc), mutualisée ici.
+
+    Paramètres
+    ----------
+    n_rows, n_cols : int
+        Dimensions de la grille.
+    row_label_fn, col_label_fn : Callable[[int], str]
+        Étiquettes des lignes (gauche) et colonnes (haut).
+    cell_color_fn : Callable[[int, int], str]
+        Retourne la couleur hex de fond pour la cellule (row, col).
+    cell_text_fn : Callable[[int, int], Optional[str]]
+        Texte à afficher dans la cellule, ou ``None`` pour ne rien afficher.
+    cell_text_color_fn : Callable[[int, int], str]
+        Couleur du texte de la cellule (typiquement obtenue via
+        :func:`text_color_for_bg`).
+    cell_w, cell_h : int
+        Dimensions de chaque cellule en pixels.
+    label_left, label_top : int
+        Marges réservées aux étiquettes.
+    rotate_col_labels : bool
+        Si ``True``, les étiquettes de colonnes sont rotées de -45°
+        (utile quand elles sont longues).
+    aria_label : str
+        Étiquette d'accessibilité du SVG.
+    x_axis_title : Optional[str]
+        Titre optionnel de l'axe horizontal, affiché en bas du SVG.
+
+    Retour
+    ------
+    str
+        SVG complet, ou ``""`` si la grille est vide.
+    """
+    if n_rows == 0 or n_cols == 0:
+        return ""
+
+    extra_bottom = 30 if x_axis_title else 10
+    width = label_left + n_cols * cell_w + 10
+    height = label_top + n_rows * cell_h + extra_bottom
+
+    parts: list[str] = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{width}" height="{height}" '
+        f'viewBox="0 0 {width} {height}" '
+        f'role="img" aria-label="{_e(aria_label)}">',
+    ]
+
+    # Étiquettes de colonnes
+    for j in range(n_cols):
+        cx = label_left + j * cell_w + cell_w // 2
+        cy = label_top - 6
+        label = _e(col_label_fn(j))
+        if rotate_col_labels:
+            parts.append(
+                f'<text x="{cx}" y="{cy}" '
+                f'transform="rotate(-45 {cx} {cy})" '
+                f'font-size="11" fill="#333" text-anchor="start">'
+                f'{label}</text>'
+            )
+        else:
+            parts.append(
+                f'<text x="{cx}" y="{cy}" '
+                f'font-size="10" fill="#666" text-anchor="middle">'
+                f'{label}</text>'
+            )
+
+    # Cellules + étiquettes de lignes
+    for i in range(n_rows):
+        rx = label_left - 6
+        ry = label_top + i * cell_h + cell_h // 2 + 4
+        parts.append(
+            f'<text x="{rx}" y="{ry}" '
+            f'font-size="11" fill="#333" text-anchor="end">'
+            f'{_e(row_label_fn(i))}</text>'
+        )
+        for j in range(n_cols):
+            x = label_left + j * cell_w
+            y = label_top + i * cell_h
+            color = cell_color_fn(i, j)
+            parts.append(
+                f'<rect x="{x}" y="{y}" '
+                f'width="{cell_w}" height="{cell_h}" '
+                f'fill="{color}" stroke="#ddd" stroke-width="0.5"/>'
+            )
+            text = cell_text_fn(i, j)
+            if text is not None:
+                text_color = cell_text_color_fn(i, j)
+                parts.append(
+                    f'<text x="{x + cell_w // 2}" '
+                    f'y="{y + cell_h // 2 + 4}" '
+                    f'font-size="10" fill="{text_color}" '
+                    f'text-anchor="middle">'
+                    f'{_e(text)}</text>'
+                )
+
+    if x_axis_title:
+        cx_axis = label_left + (n_cols * cell_w) // 2
+        cy_axis = height - 6
+        parts.append(
+            f'<text x="{cx_axis}" y="{cy_axis}" '
+            f'font-size="11" fill="#666" text-anchor="middle" '
+            f'font-style="italic">'
+            f'{_e(x_axis_title)}</text>'
+        )
+
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+__all__ = [
+    "GRADIENT_RED_RGB",
+    "GRADIENT_YELLOW_RGB",
+    "GRADIENT_GREEN_RGB",
+    "GRADIENT_TARGET_BLUE",
+    "GRADIENT_TARGET_ORANGE",
+    "GRADIENT_TARGET_RED",
+    "DIVERGING_NEGATIVE_RGB",
+    "DIVERGING_NEUTRAL_RGB",
+    "DIVERGING_POSITIVE_RGB",
+    "color_traffic_light",
+    "color_single_gradient",
+    "color_diverging",
+    "text_color_for_bg",
+    "build_grid_svg",
+]

picarones/report/robustness_projection_render.py

@@ -53,23 +53,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_deficit(deficit: float) -> str:
-    """Vert (≈0) → orange (~3 pts) → rouge (≥ 5 pts)."""
-    f = max(0.0, min(1.0, abs(deficit) / 0.05))
-    if f < 0.5:
-        # vert → orange
-        t = f / 0.5
-        r = int(167 + (235 - 167) * t)
-        g = int(240 + (180 - 240) * t)
-        b = int(167 + (60 - 167) * t)
-    else:
-        # orange → rouge
-        t = (f - 0.5) / 0.5
-        r = int(235 + (220 - 235) * t)
-        g = int(180 + (50 - 180) * t)
-        b = int(60 + (50 - 60) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def _build_summary_table(
@@ -106,7 +90,7 @@ def _build_summary_table(
         n_types = int(info.get("n_degradation_types") or 0)
         worst_type = info.get("worst_degradation_type")
         worst_deficit = info.get("worst_degradation_deficit")
-        color = _color_for_deficit(deficit)
+        color = color_traffic_light(abs(deficit), low_is_good=True, scale_max=0.05)
         worst_str = (
             f"{_e(str(worst_type))} ({worst_deficit * 100:+.1f})"
             if worst_type and isinstance(worst_deficit, (int, float))
@@ -162,7 +146,7 @@ def _build_detail_table(
             deficit = entry.get("deficit_vs_baseline")
             n_above = int(entry.get("n_docs_above_critical") or 0)
             if isinstance(deficit, (int, float)):
-                color = _color_for_deficit(float(deficit))
+                color = color_traffic_light(abs(float(deficit)), low_is_good=True, scale_max=0.05)
                 deficit_str = f"{float(deficit) * 100:+.2f}"
                 deficit_cell = (
                     f'<td style="padding:.4rem .6rem;text-align:right;'

picarones/report/searchability_render.py

@@ -19,23 +19,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_recall(recall: float) -> str:
-    """Gradient rouge → jaune → vert pour rappel ∈ [0, 1]."""
-    f = max(0.0, min(1.0, recall))
-    if f < 0.5:
-        # rouge → jaune
-        t = f / 0.5
-        r = 235
-        g = int(70 + (200 - 70) * t)
-        b = 70
-    else:
-        # jaune → vert
-        t = (f - 0.5) / 0.5
-        r = int(235 + (60 - 235) * t)
-        g = int(200 + (160 - 200) * t)
-        b = int(70 + (90 - 70) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def build_searchability_summary_html(
@@ -99,7 +83,7 @@ def build_searchability_summary_html(
         n_search = int(agg.get("n_searchable") or 0)
         n_total = int(agg.get("n_gt_tokens") or 0)
         n_docs = int(agg.get("n_docs") or 0)
-        color = _color_for_recall(recall)
+        color = color_traffic_light(recall)
         parts.append(
             f'<tr>'
             f'<td style="padding:.4rem .6rem">{_e(str(name))}</td>'

picarones/report/specialization_render.py

@@ -18,15 +18,10 @@ from picarones.measurements.specialization import (
     compute_specialization_matrix,
     top_specialized_pairs,
 )
+from picarones.report.render_helpers import color_single_gradient
 
-
-def _color_for_score(score: float) -> str:
-    """Gradient blanc → bleu profond."""
-    f = max(0.0, min(1.0, score))
-    r = int(255 + (50 - 255) * f)
-    g = int(255 + (110 - 255) * f)
-    b = int(255 + (180 - 255) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
+#: Bleu profond cible — préservé de l'ancien `_color_for_score` local.
+_SPECIALIZATION_BLUE = (50, 110, 180)
 
 
 def _category_label(cat: str, labels: dict[str, str]) -> str:
@@ -97,7 +92,7 @@ def build_specialization_html(
     for pair in pairs:
         score = float(pair.get("score") or 0.0)
         cat = pair.get("category") or "?"
-        color = _color_for_score(score)
+        color = color_single_gradient(score, end_rgb=_SPECIALIZATION_BLUE)
         parts.append(
             f'<tr>'
             f'<td style="padding:.4rem .6rem">'

picarones/report/stratification_render.py

@@ -22,21 +22,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_cer(cer: float) -> str:
-    """Gradient vert (faible CER) → rouge (CER élevé), saturé à 0.30."""
-    f = max(0.0, min(1.0, cer / 0.30))
-    if f <= 0.5:
-        ratio = f / 0.5
-        r = int(130 + (240 - 130) * ratio)
-        g = int(200 + (220 - 200) * ratio)
-        b = int(130 + (130 - 130) * ratio)
-    else:
-        ratio = (f - 0.5) / 0.5
-        r = int(240 + (220 - 240) * ratio)
-        g = int(220 + (100 - 220) * ratio)
-        b = int(130 + (100 - 130) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def _format_cer(cer: Optional[float]) -> str:
@@ -167,7 +153,7 @@ def build_stratified_ranking_html(
             median = entry.get("median_cer")
             mean = entry.get("mean_cer")
             n_docs = int(entry.get("documents") or 0)
-            bg = _color_for_cer(float(median)) if median is not None else "#f4f4f4"
+            bg = color_traffic_light(float(median), low_is_good=True, scale_max=0.30) if median is not None else "#f4f4f4"
             parts.append("<tr>")
             parts.append(
                 f'<td style="padding:.3rem .5rem;font-weight:600">'

picarones/report/taxonomy_cooccurrence_render.py

@@ -20,25 +20,15 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import (
+    GRADIENT_TARGET_BLUE,
+    build_grid_svg,
+    color_single_gradient,
+    text_color_for_bg,
+)
 
-def _color_for_jaccard(j: float) -> str:
-    """Gradient blanc → bleu profond pour Jaccard ∈ [0, 1].
 
-    Interpolation entre #ffffff (j=0) et #1e3a8a (j=1).
-    """
-    f = max(0.0, min(1.0, j))
-    r = int(255 + (30 - 255) * f)
-    g = int(255 + (58 - 255) * f)
-    b = int(255 + (138 - 255) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def _text_color_for_bg(j: float) -> str:
-    """Texte blanc si fond foncé, noir sinon (lisibilité)."""
-    return "#fff" if j > 0.55 else "#222"
-
-
-def _build_heatmap_svg(
+def _build_jaccard_heatmap_svg(
     classes: list[str],
     matrix: dict[str, dict[str, float]],
     *,
@@ -46,66 +36,37 @@ def _build_heatmap_svg(
     label_left: int = 130,
     label_top: int = 80,
 ) -> str:
-    """Construit la heatmap SVG.
+    """Heatmap Jaccard de co-occurrence taxonomique.
 
-    Cellule = carré coloré ``_color_for_jaccard``, valeur Jaccard
-    affichée en chiffres si > 0,05.  Étiquettes des classes en
-    colonne (haut) et en ligne (gauche).
+    Délègue à :func:`build_grid_svg` ; reste un wrapper local qui
+    encapsule les conventions spécifiques à la matrice symétrique
+    (valeur affichée seulement si > 0,05, étiquettes rotées).
     """
-    n = len(classes)
-    if n == 0:
+    if not classes:
         return ""
-    width = label_left + n * cell_size + 10
-    height = label_top + n * cell_size + 10
 
-    parts = [
-        f'<svg xmlns="http://www.w3.org/2000/svg" '
-        f'width="{width}" height="{height}" '
-        f'viewBox="0 0 {width} {height}" '
-        f'role="img" aria-label="Heatmap Jaccard co-occurrence taxonomique">',
-    ]
-    # Étiquettes de colonnes (rotées -45°)
-    for j, cls in enumerate(classes):
-        cx = label_left + j * cell_size + cell_size // 2
-        cy = label_top - 6
-        parts.append(
-            f'<text x="{cx}" y="{cy}" '
-            f'transform="rotate(-45 {cx} {cy})" '
-            f'font-size="11" fill="#333" text-anchor="start">'
-            f'{_e(cls)}</text>'
-        )
-    # Étiquettes de lignes
-    for i, cls in enumerate(classes):
-        rx = label_left - 6
-        ry = label_top + i * cell_size + cell_size // 2 + 4
-        parts.append(
-            f'<text x="{rx}" y="{ry}" '
-            f'font-size="11" fill="#333" text-anchor="end">'
-            f'{_e(cls)}</text>'
-        )
-    # Cellules
-    for i, ca in enumerate(classes):
-        for j, cb in enumerate(classes):
-            value = matrix.get(ca, {}).get(cb, 0.0)
-            x = label_left + j * cell_size
-            y = label_top + i * cell_size
-            color = _color_for_jaccard(value)
-            text_color = _text_color_for_bg(value)
-            parts.append(
-                f'<rect x="{x}" y="{y}" '
-                f'width="{cell_size}" height="{cell_size}" '
-                f'fill="{color}" stroke="#ddd" stroke-width="0.5"/>'
-            )
-            if value > 0.05:
-                parts.append(
-                    f'<text x="{x + cell_size // 2}" '
-                    f'y="{y + cell_size // 2 + 4}" '
-                    f'font-size="10" fill="{text_color}" '
-                    f'text-anchor="middle">'
-                    f'{value:.2f}</text>'
-                )
-    parts.append("</svg>")
-    return "".join(parts)
+    def cell_value(i: int, j: int) -> float:
+        return matrix.get(classes[i], {}).get(classes[j], 0.0)
+
+    return build_grid_svg(
+        n_rows=len(classes),
+        n_cols=len(classes),
+        row_label_fn=lambda i: classes[i],
+        col_label_fn=lambda j: classes[j],
+        cell_color_fn=lambda i, j: color_single_gradient(
+            cell_value(i, j), end_rgb=GRADIENT_TARGET_BLUE,
+        ),
+        cell_text_fn=lambda i, j: (
+            f"{cell_value(i, j):.2f}" if cell_value(i, j) > 0.05 else None
+        ),
+        cell_text_color_fn=lambda i, j: text_color_for_bg(cell_value(i, j)),
+        cell_w=cell_size,
+        cell_h=cell_size,
+        label_left=label_left,
+        label_top=label_top,
+        rotate_col_labels=True,
+        aria_label="Heatmap Jaccard co-occurrence taxonomique",
+    )
 
 
 def _build_top_pairs_table(
@@ -136,8 +97,9 @@ def _build_top_pairs_table(
             f'<td style="padding:.2rem .5rem">'
             f'<code>{_e(ca)}</code> ↔ <code>{_e(cb)}</code></td>'
             f'<td style="padding:.2rem .5rem;text-align:right;'
-            f'font-family:monospace;background:{_color_for_jaccard(j)};'
-            f'color:{_text_color_for_bg(j)}">{j:.2f}</td>'
+            f'font-family:monospace;'
+            f'background:{color_single_gradient(j, end_rgb=GRADIENT_TARGET_BLUE)};'
+            f'color:{text_color_for_bg(j)}">{j:.2f}</td>'
             f'</tr>'
         )
     parts.append("</tbody></table>")
@@ -175,7 +137,7 @@ def build_taxonomy_cooccurrence_html(
     )
     n_docs_phrase = n_docs_label_template.format(n_docs=n_docs)
 
-    svg = _build_heatmap_svg(classes, matrix)
+    svg = _build_jaccard_heatmap_svg(classes, matrix)
     top_table = _build_top_pairs_table(
         data.get("top_pairs") or [], labels,
     )

picarones/report/taxonomy_intra_doc_render.py

@@ -23,24 +23,15 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
+from picarones.report.render_helpers import (
+    GRADIENT_TARGET_ORANGE,
+    build_grid_svg,
+    color_single_gradient,
+    text_color_for_bg,
+)
 
-def _color_for_density(density: float) -> str:
-    """Gradient blanc → orange profond pour densité ∈ [0, 1].
 
-    Interpolation entre #ffffff (0) et #c2410c (1).
-    """
-    f = max(0.0, min(1.0, density))
-    r = int(255 + (194 - 255) * f)
-    g = int(255 + (65 - 255) * f)
-    b = int(255 + (12 - 255) * f)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def _text_color_for_bg(density: float) -> str:
-    return "#fff" if density > 0.55 else "#222"
-
-
-def _build_heatmap_svg(
+def _build_position_heatmap_svg(
     classes_with_errors: list[str],
     per_class: dict[str, list[int]],
     n_bins: int,
@@ -50,72 +41,47 @@ def _build_heatmap_svg(
     label_left: int = 150,
     label_top: int = 30,
 ) -> str:
-    """Construit la heatmap SVG class × position."""
-    n_rows = len(classes_with_errors)
-    if n_rows == 0:
+    """Heatmap class taxonomique × position (densité relative par classe).
+
+    Délègue à :func:`build_grid_svg` ; reste un wrapper local qui
+    encapsule la normalisation par classe (densité relative au max
+    observé sur la ligne).
+    """
+    if not classes_with_errors:
         return ""
-    width = label_left + n_bins * cell_w + 10
-    height = label_top + n_rows * cell_h + 30  # +30 pour étiquette X
 
-    # Normalisation : pour chaque classe, densité relative au max
-    # de cette classe (mise en évidence des positions concentrées).
-    parts = [
-        f'<svg xmlns="http://www.w3.org/2000/svg" '
-        f'width="{width}" height="{height}" '
-        f'viewBox="0 0 {width} {height}" '
-        f'role="img" aria-label="Heatmap class taxonomique × position">',
-    ]
-    # Étiquettes des colonnes (positions)
-    for j in range(n_bins):
-        cx = label_left + j * cell_w + cell_w // 2
-        cy = label_top - 6
-        parts.append(
-            f'<text x="{cx}" y="{cy}" '
-            f'font-size="10" fill="#666" text-anchor="middle">'
-            f'{j + 1}</text>'
-        )
-    # Cellules
-    for i, cls in enumerate(classes_with_errors):
-        # Étiquette de ligne (classe)
-        rx = label_left - 6
-        ry = label_top + i * cell_h + cell_h // 2 + 4
-        parts.append(
-            f'<text x="{rx}" y="{ry}" '
-            f'font-size="11" fill="#333" text-anchor="end">'
-            f'{_e(cls)}</text>'
-        )
+    # Pré-calcule densité et count par cellule pour éviter les boucles
+    # imbriquées dans les callbacks.
+    grid: list[list[tuple[int, float]]] = []
+    for cls in classes_with_errors:
         counts = per_class.get(cls, [0] * n_bins)
         max_count = max(counts) if counts else 0
+        row: list[tuple[int, float]] = []
         for j in range(n_bins):
-            x = label_left + j * cell_w
-            y = label_top + i * cell_h
             count = counts[j] if j < len(counts) else 0
             density = (count / max_count) if max_count > 0 else 0.0
-            color = _color_for_density(density)
-            text_color = _text_color_for_bg(density)
-            parts.append(
-                f'<rect x="{x}" y="{y}" '
-                f'width="{cell_w}" height="{cell_h}" '
-                f'fill="{color}" stroke="#ddd" stroke-width="0.5"/>'
-            )
-            if count > 0:
-                parts.append(
-                    f'<text x="{x + cell_w // 2}" '
-                    f'y="{y + cell_h // 2 + 4}" '
-                    f'font-size="10" fill="{text_color}" '
-                    f'text-anchor="middle">{count}</text>'
-                )
-    # Étiquette axe X en bas
-    cx_axis = label_left + (n_bins * cell_w) // 2
-    cy_axis = height - 6
-    parts.append(
-        f'<text x="{cx_axis}" y="{cy_axis}" '
-        f'font-size="11" fill="#666" text-anchor="middle" '
-        f'font-style="italic">'
-        f'Position dans le document (1 = début)</text>'
+            row.append((count, density))
+        grid.append(row)
+
+    return build_grid_svg(
+        n_rows=len(classes_with_errors),
+        n_cols=n_bins,
+        row_label_fn=lambda i: classes_with_errors[i],
+        col_label_fn=lambda j: str(j + 1),
+        cell_color_fn=lambda i, j: color_single_gradient(
+            grid[i][j][1], end_rgb=GRADIENT_TARGET_ORANGE,
+        ),
+        cell_text_fn=lambda i, j: (
+            str(grid[i][j][0]) if grid[i][j][0] > 0 else None
+        ),
+        cell_text_color_fn=lambda i, j: text_color_for_bg(grid[i][j][1]),
+        cell_w=cell_w,
+        cell_h=cell_h,
+        label_left=label_left,
+        label_top=label_top,
+        aria_label="Heatmap class taxonomique × position",
+        x_axis_title="Position dans le document (1 = début)",
     )
-    parts.append("</svg>")
-    return "".join(parts)
 
 
 def build_taxonomy_intra_doc_html(
@@ -162,7 +128,7 @@ def build_taxonomy_intra_doc_html(
         n_words_gt=n_words_gt, n_bins=n_bins,
     )
 
-    svg = _build_heatmap_svg(classes_with_errors, per_class, n_bins)
+    svg = _build_position_heatmap_svg(classes_with_errors, per_class, n_bins)
 
     parts = [
         '<div class="intradoc" style="margin:1rem 0">',

picarones/report/throughput_render.py

@@ -50,39 +50,7 @@ from __future__ import annotations
 from html import escape as _e
 from typing import Optional
 
-
-def _color_for_pages_per_hour(value: float, max_value: float) -> str:
-    """Rouge (faible) → jaune → vert (= max)."""
-    if max_value <= 0:
-        return "#e0e0e0"
-    f = max(0.0, min(1.0, value / max_value))
-    if f < 0.5:
-        t = f / 0.5
-        r = 235
-        g = int(70 + (200 - 70) * t)
-        b = 70
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (60 - 235) * t)
-        g = int(200 + (160 - 200) * t)
-        b = int(70 + (90 - 70) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def _color_for_drag(drag: float) -> str:
-    """Vert (faible drag) → orange → rouge (drag élevé)."""
-    f = max(0.0, min(1.0, drag))
-    if f < 0.5:
-        t = f / 0.5
-        r = int(167 + (235 - 167) * t)
-        g = int(240 + (180 - 240) * t)
-        b = int(167 + (60 - 167) * t)
-    else:
-        t = (f - 0.5) / 0.5
-        r = int(235 + (220 - 235) * t)
-        g = int(180 + (50 - 180) * t)
-        b = int(60 + (50 - 60) * t)
-    return f"#{r:02x}{g:02x}{b:02x}"
+from picarones.report.render_helpers import color_traffic_light
 
 
 def build_throughput_html(
@@ -154,8 +122,11 @@ def build_throughput_html(
         drag = row.get("drag_ratio") or 0.0
         n_pages = int(row.get("n_pages") or 0)
         n_errors = int(row.get("n_errors") or 0)
-        eff_color = _color_for_pages_per_hour(eff, max_eff)
-        drag_color = _color_for_drag(drag)
+        eff_color = (
+            color_traffic_light(eff, scale_max=max_eff)
+            if max_eff > 0 else "#e0e0e0"
+        )
+        drag_color = color_traffic_light(drag, low_is_good=True)
         raw_str = (
             f"{raw:,.0f}" if isinstance(raw, (int, float)) else "—"
         )

picarones/report/worst_lines_render.py

@@ -20,20 +20,21 @@ from typing import Optional
 
 from picarones.measurements.worst_lines import WorstLineEntry
 from picarones.core.diff_utils import compute_char_diff
+from picarones.report.render_helpers import color_traffic_light
 
 
-def _color_for_cer(cer: float) -> str:
-    """Gradient jaune → rouge : 0,3 jaune, 1,0 rouge profond."""
+def _bg_for_cer(cer: float) -> str:
+    """Beige clair sous le seuil catastrophique (0.30), gradient
+    jaune → rouge au-delà.
+
+    Le seuil dur à 0.30 préserve la sémantique « toléré jusqu'à 30 %
+    pour un manuscrit difficile ». Au-delà, on entre en zone visible
+    avec :func:`color_traffic_light` (low_is_good).
+    """
     f = max(0.0, min(1.0, cer))
-    # Au-delà de 0,3 (seuil catastrophique courant), gradient
-    # jaune → rouge. En dessous, beige clair.
     if f < 0.3:
         return "#fff8dc"
-    ratio = (f - 0.3) / 0.7
-    r = int(240 + (200 - 240) * ratio)
-    g = int(220 + (60 - 220) * ratio)
-    b = int(120 + (60 - 120) * ratio)
-    return f"#{r:02x}{g:02x}{b:02x}"
+    return color_traffic_light(f, low_is_good=True, scale_min=0.3, scale_max=1.0)
 
 
 def _render_diff_inline(reference: str, hypothesis: str) -> str:
@@ -121,7 +122,7 @@ def build_worst_lines_table_html(
         )
     parts.append("</tr></thead><tbody>")
     for entry in entries:
-        cer_color = _color_for_cer(entry.cer)
+        cer_color = _bg_for_cer(entry.cer)
         parts.append("<tr>")
         parts.append(
             f'<td style="padding:.3rem .5rem;text-align:right;'

tests/architecture/test_render_helpers.py

@@ -4,21 +4,21 @@ Les renderers HTML dans ``picarones/report/`` ont accumulé des helpers
 locaux dupliqués (couleur, heatmap SVG, etc.) qui devraient vivre dans
 un unique ``picarones/report/render_helpers.py``.
 
-Snapshot v1.0.0 (2026-05-02) :
-
-- 25 fonctions ``_color_for_*`` distinctes (dont plusieurs portent le
-  même nom dans des fichiers différents : ``_color_for_score`` ×5,
-  ``_color_for_delta`` ×2, ``_color_for_cer`` ×2).
-- 1 fonction ``_color`` simple (``inter_engine_render``).
-- 2 fonctions ``_build_heatmap_svg`` (``taxonomy_cooccurrence``,
-  ``taxonomy_intra_doc``).
-
-Soit **27 helpers locaux** dupliqués.
-
-Test ratchet : ce nombre ne peut que descendre. Pour le faire baisser,
-extraire un helper dans ``picarones/report/render_helpers.py`` et
-l'importer depuis les renderers qui en avaient besoin, puis abaisser
-:data:`HELPER_BASELINE` du même montant.
+État après le sprint de consolidation : tous les ``_color_for_*`` et
+``_build_heatmap_svg`` locaux ont été déplacés dans
+``picarones/report/render_helpers.py`` qui expose
+:func:`color_traffic_light`, :func:`color_single_gradient`,
+:func:`color_diverging`, :func:`text_color_for_bg` et
+:func:`build_grid_svg`.
+
+Snapshot v1.0.0 (2026-05-02, post-consolidation) : **0 helper local
+dupliqué**.
+
+Test ratchet : ce nombre ne peut que descendre. Si un nouveau helper
+``_color_for_*`` ou ``_build_heatmap_svg`` apparaît dans un renderer,
+le test échoue. La résolution est de paramétrer un des helpers de
+:mod:`picarones.report.render_helpers` plutôt que de réintroduire
+une fonction locale.
 """
 
 from __future__ import annotations
@@ -29,8 +29,8 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parents[2]
 REPORT_DIR = REPO_ROOT / "picarones" / "report"
 
-#: Snapshot v1.0.0. Doit baisser, jamais monter.
-HELPER_BASELINE = 27
+#: Snapshot v1.0.0 post-consolidation. Doit rester à 0.
+HELPER_BASELINE = 0
 
 #: Le module mutualisé est exempté (c'est *là* qu'on veut les voir).
 HELPERS_MODULE_NAME = "render_helpers.py"

tests/report/test_render_helpers.py

@@ -0,0 +1,285 @@
+"""Tests unitaires des helpers de rendu mutualisés.
+
+Couvre :func:`color_traffic_light`, :func:`color_single_gradient`,
+:func:`color_diverging`, :func:`text_color_for_bg`, :func:`build_grid_svg`.
+"""
+
+from __future__ import annotations
+
+from picarones.report.render_helpers import (
+    DIVERGING_NEGATIVE_RGB,
+    DIVERGING_POSITIVE_RGB,
+    GRADIENT_GREEN_RGB,
+    GRADIENT_RED_RGB,
+    GRADIENT_YELLOW_RGB,
+    build_grid_svg,
+    color_diverging,
+    color_single_gradient,
+    color_traffic_light,
+    text_color_for_bg,
+)
+
+
+def _hex_to_rgb(hex_str: str) -> tuple[int, int, int]:
+    s = hex_str.lstrip("#")
+    return int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16)
+
+
+# ──────────────────────────────────────────────────────────────────
+# color_traffic_light
+# ──────────────────────────────────────────────────────────────────
+class TestColorTrafficLight:
+    def test_value_zero_high_is_good_returns_red(self) -> None:
+        assert _hex_to_rgb(color_traffic_light(0.0)) == GRADIENT_RED_RGB
+
+    def test_value_max_high_is_good_returns_green(self) -> None:
+        assert _hex_to_rgb(color_traffic_light(1.0)) == GRADIENT_GREEN_RGB
+
+    def test_value_mid_high_is_good_returns_yellow(self) -> None:
+        assert _hex_to_rgb(color_traffic_light(0.5)) == GRADIENT_YELLOW_RGB
+
+    def test_value_zero_low_is_good_returns_green(self) -> None:
+        assert _hex_to_rgb(color_traffic_light(0.0, low_is_good=True)) == GRADIENT_GREEN_RGB
+
+    def test_value_max_low_is_good_returns_red(self) -> None:
+        assert _hex_to_rgb(color_traffic_light(1.0, low_is_good=True)) == GRADIENT_RED_RGB
+
+    def test_clamping_above_max(self) -> None:
+        c = color_traffic_light(2.0)
+        assert _hex_to_rgb(c) == GRADIENT_GREEN_RGB
+
+    def test_clamping_below_zero(self) -> None:
+        c = color_traffic_light(-1.0)
+        assert _hex_to_rgb(c) == GRADIENT_RED_RGB
+
+    def test_custom_scale_max(self) -> None:
+        # CER 0.30 = max → vert (avec low_is_good=True → vert au max)
+        # On vérifie plutôt high_is_good : 0.30 → vert
+        assert _hex_to_rgb(color_traffic_light(0.30, scale_max=0.30)) == GRADIENT_GREEN_RGB
+        # 0.15 → milieu → jaune
+        assert _hex_to_rgb(color_traffic_light(0.15, scale_max=0.30)) == GRADIENT_YELLOW_RGB
+
+    def test_custom_scale_min_and_max(self) -> None:
+        # Plage [10, 20] : 10 → rouge, 20 → vert, 15 → jaune
+        assert _hex_to_rgb(color_traffic_light(10.0, scale_min=10, scale_max=20)) == GRADIENT_RED_RGB
+        assert _hex_to_rgb(color_traffic_light(20.0, scale_min=10, scale_max=20)) == GRADIENT_GREEN_RGB
+        assert _hex_to_rgb(color_traffic_light(15.0, scale_min=10, scale_max=20)) == GRADIENT_YELLOW_RGB
+
+    def test_zero_span_returns_yellow(self) -> None:
+        # scale_min == scale_max → milieu → jaune
+        assert _hex_to_rgb(color_traffic_light(5.0, scale_min=10, scale_max=10)) == GRADIENT_YELLOW_RGB
+
+    def test_format_is_hex_lowercase(self) -> None:
+        c = color_traffic_light(0.7)
+        assert c.startswith("#")
+        assert len(c) == 7
+        assert c == c.lower()
+
+
+# ──────────────────────────────────────────────────────────────────
+# color_single_gradient
+# ──────────────────────────────────────────────────────────────────
+class TestColorSingleGradient:
+    def test_zero_returns_start(self) -> None:
+        assert color_single_gradient(0.0, end_rgb=(30, 58, 138)) == "#ffffff"
+
+    def test_max_returns_end(self) -> None:
+        assert color_single_gradient(1.0, end_rgb=(30, 58, 138)) == "#1e3a8a"
+
+    def test_half_is_midpoint(self) -> None:
+        c = color_single_gradient(0.5, end_rgb=(30, 58, 138))
+        # ((255+30)/2, (255+58)/2, (255+138)/2) ≈ (142, 156, 196) → ~#8e9cc4
+        r, g, b = _hex_to_rgb(c)
+        assert abs(r - 142) <= 1
+        assert abs(g - 156) <= 1
+        assert abs(b - 196) <= 1
+
+    def test_above_max_clamped(self) -> None:
+        assert color_single_gradient(2.0, end_rgb=(30, 58, 138)) == "#1e3a8a"
+
+    def test_below_zero_clamped(self) -> None:
+        assert color_single_gradient(-1.0, end_rgb=(30, 58, 138)) == "#ffffff"
+
+    def test_custom_max_value(self) -> None:
+        # value = 50, max = 100 → 0.5 → milieu
+        c = color_single_gradient(50.0, end_rgb=(30, 58, 138), max_value=100.0)
+        r, g, b = _hex_to_rgb(c)
+        assert abs(r - 142) <= 1
+
+    def test_custom_start_rgb(self) -> None:
+        c = color_single_gradient(0.0, end_rgb=(30, 58, 138), start_rgb=(0, 0, 0))
+        assert c == "#000000"
+
+    def test_zero_max_value_returns_start(self) -> None:
+        # Garde-fou contre division par zéro
+        assert color_single_gradient(5.0, end_rgb=(30, 58, 138), max_value=0) == "#ffffff"
+
+
+# ──────────────────────────────────────────────────────────────────
+# color_diverging
+# ──────────────────────────────────────────────────────────────────
+class TestColorDiverging:
+    def test_zero_returns_neutral(self) -> None:
+        c = color_diverging(0.0)
+        # Neutre = vert par défaut
+        assert _hex_to_rgb(c) == (130, 200, 130)
+
+    def test_positive_max_returns_positive_color(self) -> None:
+        c = color_diverging(1.0, max_abs=1.0)
+        assert _hex_to_rgb(c) == DIVERGING_POSITIVE_RGB
+
+    def test_negative_max_returns_negative_color(self) -> None:
+        c = color_diverging(-1.0, max_abs=1.0)
+        assert _hex_to_rgb(c) == DIVERGING_NEGATIVE_RGB
+
+    def test_clamping_above_max_abs(self) -> None:
+        assert _hex_to_rgb(color_diverging(5.0, max_abs=1.0)) == DIVERGING_POSITIVE_RGB
+
+    def test_clamping_below_negative_max_abs(self) -> None:
+        assert _hex_to_rgb(color_diverging(-5.0, max_abs=1.0)) == DIVERGING_NEGATIVE_RGB
+
+    def test_zero_max_abs_returns_neutral(self) -> None:
+        c = color_diverging(5.0, max_abs=0)
+        assert _hex_to_rgb(c) == (130, 200, 130)
+
+
+# ──────────────────────────────────────────────────────────────────
+# text_color_for_bg
+# ──────────────────────────────────────────────────────────────────
+class TestTextColorForBg:
+    def test_low_intensity_dark_text(self) -> None:
+        assert text_color_for_bg(0.2) == "#222"
+
+    def test_high_intensity_white_text(self) -> None:
+        assert text_color_for_bg(0.8) == "#fff"
+
+    def test_threshold_boundary(self) -> None:
+        assert text_color_for_bg(0.55) == "#222"
+        assert text_color_for_bg(0.56) == "#fff"
+
+    def test_custom_threshold(self) -> None:
+        assert text_color_for_bg(0.4, threshold=0.3) == "#fff"
+
+
+# ──────────────────────────────────────────────────────────────────
+# build_grid_svg
+# ──────────────────────────────────────────────────────────────────
+class TestBuildGridSvg:
+    def test_empty_grid_returns_empty_string(self) -> None:
+        svg = build_grid_svg(
+            n_rows=0,
+            n_cols=0,
+            row_label_fn=lambda i: "",
+            col_label_fn=lambda j: "",
+            cell_color_fn=lambda i, j: "#fff",
+        )
+        assert svg == ""
+
+    def test_zero_rows_returns_empty(self) -> None:
+        svg = build_grid_svg(
+            n_rows=0,
+            n_cols=3,
+            row_label_fn=lambda i: "",
+            col_label_fn=lambda j: str(j),
+            cell_color_fn=lambda i, j: "#fff",
+        )
+        assert svg == ""
+
+    def test_minimal_grid_renders(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "row0",
+            col_label_fn=lambda j: "col0",
+            cell_color_fn=lambda i, j: "#abc123",
+        )
+        assert "<svg" in svg
+        assert "row0" in svg
+        assert "col0" in svg
+        assert "#abc123" in svg
+
+    def test_cell_text_displayed_when_provided(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "r",
+            col_label_fn=lambda j: "c",
+            cell_color_fn=lambda i, j: "#fff",
+            cell_text_fn=lambda i, j: "0.42",
+        )
+        assert "0.42" in svg
+
+    def test_cell_text_omitted_when_none(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "r",
+            col_label_fn=lambda j: "c",
+            cell_color_fn=lambda i, j: "#fff",
+            cell_text_fn=lambda i, j: None,
+        )
+        # Pas de chiffre dans la cellule
+        assert ">0.<" not in svg
+
+    def test_rotate_col_labels(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "r",
+            col_label_fn=lambda j: "long_label",
+            cell_color_fn=lambda i, j: "#fff",
+            rotate_col_labels=True,
+        )
+        assert "rotate(-45" in svg
+
+    def test_x_axis_title(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "r",
+            col_label_fn=lambda j: "c",
+            cell_color_fn=lambda i, j: "#fff",
+            x_axis_title="Position dans le document",
+        )
+        assert "Position dans le document" in svg
+
+    def test_html_escape_in_labels(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "<script>alert(1)</script>",
+            col_label_fn=lambda j: "<b>bold</b>",
+            cell_color_fn=lambda i, j: "#fff",
+            cell_text_fn=lambda i, j: "<i>italic</i>",
+        )
+        assert "<script>" not in svg
+        assert "&lt;script&gt;" in svg
+        assert "<b>" not in svg
+        assert "&lt;b&gt;" in svg
+        assert "<i>" not in svg
+
+    def test_grid_dimensions(self) -> None:
+        svg = build_grid_svg(
+            n_rows=3,
+            n_cols=4,
+            row_label_fn=lambda i: f"r{i}",
+            col_label_fn=lambda j: f"c{j}",
+            cell_color_fn=lambda i, j: "#fff",
+        )
+        # 12 cellules attendues (3×4)
+        assert svg.count("<rect") == 12
+        # 3 étiquettes de ligne + 4 de colonne
+        # On compte les <text> qui ne sont pas dans une cellule (donc qui sont des labels) :
+        # 3 labels lignes + 4 labels colonnes = 7. Pas de cell_text_fn donc 0.
+        assert svg.count("<text") == 7
+
+    def test_aria_label_present(self) -> None:
+        svg = build_grid_svg(
+            n_rows=1,
+            n_cols=1,
+            row_label_fn=lambda i: "r",
+            col_label_fn=lambda j: "c",
+            cell_color_fn=lambda i, j: "#fff",
+            aria_label="Test heatmap",
+        )
+        assert 'aria-label="Test heatmap"' in svg