From 5ba0cc9f2526d4b636c1d65a975f6865ab25836d Mon Sep 17 00:00:00 2001
From: "R.Eugenio" <yo@reugenio.com>
Date: Tue, 30 Dec 2025 21:35:08 +0100
Subject: [PATCH] docs(colors): Document perceptual correction algorithm in
 detail
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added extensive documentation explaining:
- The problem (blue goes to black, red stays red when darkened)
- Technical cause (ITU-R BT.709 luminance formula)
- Solution (threshold 0.15, correction factor)
- How to disable if needed

Status: PENDING CONSENSUS - needs team input on colors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/core/style.zig | 56 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/src/core/style.zig b/src/core/style.zig
index 490e949..2dc806d 100644
--- a/src/core/style.zig
+++ b/src/core/style.zig
@@ -38,13 +38,67 @@ pub fn isFancy() bool {
 }
 
 // =============================================================================
-// Perceptual Color Correction
+// Perceptual Color Correction - Sistema de Compensación de Colores
+// =============================================================================
+//
+// PROBLEMA A RESOLVER:
+// --------------------
+// Cuando se oscurecen colores para fondos de paneles (deriveDarkPalette),
+// algunos colores pierden su identidad y "van a negro" más rápido que otros:
+//   - Panel AZUL: al oscurecerse, parece casi negro (pierde identidad)
+//   - Panel ROJO: al oscurecerse, sigue viéndose "rojo oscuro" (mantiene identidad)
+//
+// CAUSA TÉCNICA:
+// --------------
+// La luminosidad percibida por el ojo humano sigue la fórmula ITU-R BT.709:
+//   L = 0.2126*R + 0.7152*G + 0.0722*B
+//
+// Valores para colores puros:
+//   - Azul puro  (0,0,255): L = 0.0722 (MUY baja)
+//   - Rojo puro  (255,0,0): L = 0.2126 (baja pero ~3x más que azul)
+//   - Verde puro (0,255,0): L = 0.7152 (alta)
+//
+// El azul tiene la menor contribución a la luminosidad percibida, por eso
+// al oscurecerlo pierde rápidamente su identidad visual.
+//
+// SOLUCIÓN IMPLEMENTADA:
+// ----------------------
+// Umbral de corrección: 0.15
+//   - Colores con L < 0.15 (como azul ~0.07): reciben boost
+//   - Colores con L >= 0.15 (como rojo ~0.21): NO se modifican
+//
+// El "boost" consiste en REDUCIR el porcentaje de blend hacia negro,
+// dejando más del color base visible en el fondo oscurecido.
+//
+// Factor de corrección = max(0.75, L / 0.15)
+//   - Azul: max(0.75, 0.07/0.15) = max(0.75, 0.47) = 0.75
+//   - Rojo: L=0.21 >= 0.15, no aplica corrección (factor = 1.0)
+//
+// Aplicación en deriveDarkPalette:
+//   - focus_blend = 80% * factor    (sin corrección: 80%, con: 60%)
+//   - unfocus_blend = 96% * factor  (sin corrección: 96%, con: 72%)
+//
+// ESTADO ACTUAL (2025-12-30):
+// ---------------------------
+// - Activado por defecto (perceptual_correction_enabled = true)
+// - Umbral: 0.15
+// - PENDIENTE DE CONSENSO: El usuario R.Eugenio considera que necesita
+//   más opiniones antes de decidir si este algoritmo es el correcto.
+//   Los colores son subjetivos y requieren consenso del equipo.
+//
+// CÓMO DESACTIVAR:
+// ----------------
+// En runtime: Style.setPerceptualCorrection(false)
+// O cambiar el default aquí abajo a false.
+//
 // =============================================================================
 
 /// Enable perceptual correction for panel colors.
 /// When enabled, colors with VERY low perceived luminance (e.g., blue ~0.07)
 /// get a boost to avoid going to black when darkened.
 /// Colors like red (~0.21) are NOT affected as they darken well naturally.
+///
+/// PENDIENTE DE CONSENSO - ver documentación arriba.
 var perceptual_correction_enabled: bool = true;
 
 /// Get whether perceptual correction is enabled