From ef9f589d4c8fc1377fa5386c2b7751bbdcf62424 Mon Sep 17 00:00:00 2001 From: dev Date: Mon, 1 Jun 2026 22:14:26 +0200 Subject: [PATCH] docs(theming): clarify synthetic alpha-scale model + alphaScales opt-in (P1-1) Alpha steps (--scale-*-aN) are unconsumed today (only a test + README ref). The step-9-at-opacity synthesis is a valid 'accent-at-opacity' ramp default, not a bug; it is not a Radix-style reproduction of the solid scale. Documented the model, its limitation, and the already-wired alphaScales opt-in in appendColorAlphaScaleDeclarations. A build-time compositing-inverse generator is deferred until alpha is actually consumed. Co-Authored-By: Claude Opus 4.8 --- src/uix/eidos/THEMING_AUDIT_2026-06-01.md | 3 ++- src/uix/eidos/lib/render-css.ts | 21 +++++++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/src/uix/eidos/THEMING_AUDIT_2026-06-01.md b/src/uix/eidos/THEMING_AUDIT_2026-06-01.md index 3ec3128b1..adce2cf56 100644 --- a/src/uix/eidos/THEMING_AUDIT_2026-06-01.md +++ b/src/uix/eidos/THEMING_AUDIT_2026-06-01.md @@ -44,10 +44,11 @@ definiciones vs referencias). Orden de prioridad para empezar a resolver. ## P1 — Correctitud / cobertura -### P1-1 · Las alpha scales no se autoran — se fabrican desde el step 9 en sRGB +### ✅ P1-1 · Las alpha scales no se autoran — se fabrican desde el step 9 en sRGB *(reframe + documentado; generador diferido)* - `themes/base.ts:28-368` define escalas sólidas; **sin `alphaScales`**. `render-css.ts:1336-1346`: cada `--scale-*-a{n}` = `color-mix(in srgb, var(--scale-*-9) {pct}, transparent)`. - Derivar las 12 alfas de un único step (9) da una rampa monocroma que no sigue la progresión de luminosidad de la escala sólida → a1–a4 sobre superficie clara se ven como tinte del step-9, no como el tinte cercano-a-superficie esperado. **Mina el plan §22-#2 "surface vía alpha"** (las alfas que lo arreglarían son de baja fidelidad). - **Fix**: autorar `alphaScales` reales por paso (Radix las trae), o documentar que la alfa es sintética. +- **✅ Hecho** (reframe + documentación): **hallazgo clave — ningún recipe/componente consume los alpha steps hoy** (solo un test + el README; emitidos para uso futuro). La síntesis (hue del step-9 a 12 niveles de opacidad) es un ramp *acento-a-opacidad* **válido** como default, no un bug — lo que no es es una reproducción Radix de la escala sólida. Documentado el modelo + el límite + el opt-in `alphaScales` (ya cableado en `render-css.ts:1340`, con test) en un comentario del propio `appendColorAlphaScaleDeclarations`. **Diferido a propósito**: el generador compositing-inverse (alpha que reproduce la sólida para toda escala automáticamente) hasta que el alpha se consuma de verdad — así se diseña la fidelidad contra uso real, no especulativamente para tokens inertes. ### P1-2 · Tokens de densidad muertos; tipografía/iconos/radios no escalan - `render-css.ts:348,376` emite `--density-content-scale` y el maestro `--density-scale`, se redeclaran por `[data-density]`, y están en el **contrato público** (`contract.ts:257-284`) — pero **cero consumidores** (grep de `var(--density-content-scale)`/`var(--density-scale)` = 0). Solo `space` y `control-height` escalan. diff --git a/src/uix/eidos/lib/render-css.ts b/src/uix/eidos/lib/render-css.ts index 4a8bd0b87..c0aa04524 100644 --- a/src/uix/eidos/lib/render-css.ts +++ b/src/uix/eidos/lib/render-css.ts @@ -1328,6 +1328,27 @@ function appendColorScaleDeclarations( } } +/** + * Alpha (translucent) variants of a color scale. + * + * If a theme provides explicit `alphaScales` for this scale, those values are + * used verbatim — author them when you need Radix-grade alpha that *reproduces + * the solid scale* over an arbitrary background (`aN` composited over the page + * bg ≈ solid `N`). + * + * Otherwise we synthesize: each `aN` is the scale's SOLID color (step 9) at an + * increasing opacity (`DEFAULT_COLOR_ALPHA_PERCENTAGES`). This is a deliberate + * "accent-at-opacity" ramp — one hue at 12 opacity levels — useful for + * translucent accent tints, hover washes and overlays. It is NOT a per-step + * reproduction of the solid scale (e.g. `a3` over white is a faint step-9 tint, + * not step-3). For that fidelity, provide `alphaScales`. + * + * NOTE (audit P1-1): these tokens are emitted for consumers / future use (the + * "surface via alpha" idea, §22) but no recipe consumes them today. A build-time + * compositing-inverse generator would give solid-scale-reproduction alpha for + * every scale automatically — deferred until alpha is actually consumed, so the + * fidelity can be designed against real usage rather than speculatively. + */ function appendColorAlphaScaleDeclarations( declarations: string[], scaleName: string,