svelte-kit-vice/src/uix/eidos/TYPOGRAPHY_ENGINE_RFC.md

RFC — Motor de tipografía reference-grade (eidos)

Estado: PROPUESTA (2026-06-05). Plan para elevar la tipografía de eidos a la par o por encima de los frameworks de referencia, replicando el enfoque del color (COLOR_ENGINE_RFC.md): auditar → comparar → extender de forma ADITIVA detrás del contrato de tokens congelado, por fases.

1. Estado actual (auditoría)

TypographyPrimitiveSet (lib/primitives/typography.ts + config-types.ts) → emisión en render-css.ts → tokens → componentes <Text> / <Heading> / <SText>.

• 4 familias (primary Instrument Sans · secondary/display Lora · mono Azeret Mono).
• 8 tamaños xxs 10px … xxxl 80px, cada uno size / lineHeight / letterSpacing fijos en px.
• 4 pesos (400/500/600/700).
• 13 estilos nombrados (hero, h1–h6, body, prose, label, caption, code) con size responsive por breakpoint en algunos ({ base, md }).
• Eje --scaling (zoom global 90–110%) que multiplica los px.
• Tokens: --font-family-*, --font-size-* (calc(px * --scaling)), --font-line-height-*, --font-letter-spacing-*, --font-weight-*, --style-{name}-*.
• Brazo de medición: el motor canvas-text (<SText>) cuenta líneas exactas replicando el navegador (productionizado — ver lib/canvas-text/fix-stext.md).

Bueno hoy: estilos semánticos nombrados, sizes responsive, eje de scaling (poco común), contrato de tokens + theming, medición exacta de líneas.

2. Comparación con referencia (el gap)

Capacidad	Referencia	Eidos hoy
Tipografía fluida (clamp() por viewport)	Utopia, Carbon, Tailwind(opt)	❌ px fijos + breakpoints manuales
Variable fonts (1 archivo, wght + opsz)	Material 3, Apple	❌ TTF estáticas por peso
WOFF2 + subsetting + fallback con métricas (anti-CLS)	Next/Fontaine	❌ TTF, sin subset, sin size-adjust
Optical sizing (opsz)	Apple, Material	❌
Tracking por tamaño (óptico)	Material, Apple, Radix	❌ todo 0
text-wrap: balance/pretty	Tailwind, Chakra	❌
Measure (ancho de línea ~65ch)	clásico, Tailwind prose	❌
font-feature-settings (tabular-nums…)	Tailwind, Radix	❌
Estilos nombrados · eje de scaling	Chakra/Material · Apple(parcial)	✅

3. Modelo de inclusión: extender, no reemplazar

Principio rector (idéntico a color): todo lo nuevo es ADITIVO sobre TypographyPrimitiveSet, detrás del contrato de tokens congelado. Lo viejo (px fijos) sigue funcionando; lo nuevo se activa por config. Los nombres de token (--font-size-X, --style-Y-*) no cambian — solo cambia la fórmula del valor (igual que en color el token --scale-* pasó de hex a oklch() sin renombrar).

Capas de la implementación, paralelas a color:

Pieza	Dónde	Análogo en color
Matemática pura (fluid scale Utopia)	eidos/lib/type-scale.ts (puro)	arts/color / build-scheme.ts
Tipo + config	config-types.ts (TypographyPrimitiveSet)	EidosConfig
Emisión CSS	render-css.ts (appendTypographyDeclarations)	appendColorScaleDeclarations
Fuentes	themes/fonts.css (woff2/variable)	themes/base (paleta)
Componentes	<Text> / <Heading> (props nuevas)	<Button> etc.
Runtime opcional	eidos.applyTypeScale(seed)	eidos.applyColorScheme(seed)

4. Tipografía fluida (Fase 1, el corazón)

Fórmula (estilo Utopia) — un tamaño se vuelve un clamp(min, fluido, max) en rem (a11y: respeta el zoom del navegador), donde el tramo fluido interpola entre dos viewports:

slope      = (maxRem − minRem) / (maxVw − minVw)
interceptRem = minRem − slope · minVw
size = clamp(minRem, interceptRem + slope·100vw, maxRem)

• rem, no px: mejora la accesibilidad (el zoom de fuente del SO/navegador escala). El token --font-size-X mantiene su nombre; su valor pasa de calc(px*scaling) a calc(clamp(...rem...) * var(--scaling)) — transparente para los consumidores.
• El eje --scaling (zoom discreto del sistema) compone encima del clamp vía calc(clamp(...) * var(--scaling)). Dos ejes ortogonales: fluid (continuo, por viewport) + scaling (discreto, preferencia).
• Simplifica los estilos nombrados: hero/h1/h2 ya no necesitan size responsive { base, md } manual — el clamp cubre el viewport de forma continua. El emisor de @media por breakpoint para size se puede retirar (menos CSS).
• Tipo: TextMetric.size acepta hoy string; se extiende a string | FluidSize donde FluidSize = { min: string; max: string; minVw?: string; maxVw?: string }. string (px fijo) sigue válido → backward-compatible.

5. Fuentes modernas (Fase 2, mayor golpe perf+calidad)

• WOFF2 + variable: migrar fonts.css de TTF estáticas por peso a woff2 variable (Instrument Sans / Lora / Azeret Mono tienen versión variable con eje wght; Lora además ital). Un archivo por familia en vez de 3–10.
• Anti-CLS: por cada familia, un @font-face de fallback con métricas sobreescritas (size-adjust, ascent-override, descent-override, line-gap-override) que iguala la geometría de la webfont al fallback de sistema → cero salto de layout al cargar (enfoque Fontaine / next/font). Las métricas se precalculan por fuente.
• unicode-range subsetting (latin / latin-ext separados) → cargar solo lo usado.
• preload de la familia crítica (primary regular).
• Tipo: FontFamily += axes?: { wght?: [min,max]; opsz?: [min,max] } + sizeAdjust? / overrides de métricas + unicodeRanges?. source ya existe. ✅
• Optical sizing ✅: font-optical-sizing: auto en :root cuando alguna familia declara opsz.
• Eje de peso variable ✅: cuando un face omite weight y la familia declara axes.wght, el @font-face emite el rango (font-weight: 100 900) → un solo face cubre todo el eje. (render-css > renderFontFace; test en active-eidos-config.test.ts.)

Estado §5: el motor está cableado — @font-face config-driven, fallback anti-CLS, unicode-range, y ahora el consumo de axes (rango de peso + optical sizing). Inerte hasta que un tema declare axes — como el wide-gamut de color: listo, pero no ejercitado por los assets actuales (TTF estáticas). Pendiente de assets: migrar a woff2 variable reales; preload (cierre aparte).

6. Tracking · leading · features · measure · wrap (Fase 3)

• Tracking/leading como escalas (estilo Tailwind): TypographyPrimitiveSet += tracking + leading → --tracking-{key} / --leading-{key}. Tracking óptico por defecto (negativo en display, ~0 en body, positivo en xs/caption).
• font-feature-settings: features?: Record<string,string> → --font-feature-{key} (presets tabular, oldstyle, ligatures, smallcaps). Prop numeric en componentes.
• Measure: token --measure-{key} (60ch/66ch/72ch) para prosa legible.
• text-wrap: props wrap: 'balance' | 'pretty' | 'nowrap' en <Text>/<Heading> (keyword CSS, sin token); default balance en headings, pretty en prose.

7. Vínculo con <SText> (brazo de medición)

El motor canvas-text cuenta líneas exactas replicando el navegador (ya productionizado). Es la otra mitad del sistema: la tipografía visual (este RFC) y la medición (SText). Al emitir fluid/tracking, <SText> los mide igual (lee getComputedStyle real), así que el conteo sigue siendo fiel sin cambios — el epoch de useFontReady (T1) ya cubre el re-cálculo tras cargar variable fonts.

8. Doctrina (paralela a color)

• Escala + estilos nombrados = canon del eidos (como roles/variants de color): valores themeables, pero el set de estilos es canon.
• Fuentes = dato del tema (como la paleta): el tema trae las suyas.
• Fluid / tracking / features = capacidades del motor, default-on con fallback (como el wide-gamut OKLCH): sRGB-idéntico donde no hay soporte.
• Theme = retintar/retipar lo perceptualmente fijo: cambia QUÉ fuente es primary, no QUÉ significa h1.

9. Contrato de tokens (añadidos)

Congelados, bare-prefixed (§6 THEMING). Nuevos: --tracking-{key}, --leading-{key}, --font-feature-{key}, --measure-{key}. Reformulados (mismo nombre, valor fluido): --font-size-{key}. Sin cambios de nombre → cero rotura de componentes.

10. Fases — estado (cerrado)

1. ✅ Motor fluido — type-scale.ts (puro fluidClamp) + FluidSize + clamp() rem en appendTypographyDeclarations (scaling compone); @media de size retirado.
2. ✅ Fuentes — @font-face config-driven + fallback anti-CLS (métricas) + unicode-range + FontFamily.axes (rango de peso variable + font-optical-sizing) + font preloads (collectFontPreloads / eidos.fontPreloads()). Assets aún TTF estáticas → la variabilidad es capacidad de motor, no visible todavía (como wide-gamut).
3. ✅ Tracking/leading/features/measure/wrap — escalas config-driven + props de componente (<Text>/<Heading>) + tokens semánticos (--leading-{role} / --tracking-{role}) ahora config-driven (typography.semanticLeading / semanticTracking).
4. ✅ Escala — diseño de dos zonas (intencional), ver abajo. NO se cambiaron los valores (sería regresión perceptual): la "irregularidad" es deliberada.
5. ✅ Docs + demo — este RFC + demo /temas/tipografia (escala/familias/ejes en vivo)
   • eidos.applyTypeScale(seed) runtime (buildTypeScale, hermano de applyColorScheme).

Fase 4 — la escala es un diseño de dos zonas (intencional)

La escala (xxs 10 · xs 12 · sm 14 · md 16 · lg 18→20 · xl 24→28 · xxl 40→48 · xxxl 64→80) NO es un único ratio modular, y eso es deliberado:

• Zona UI (xxs–md): pasos finos (~1.14–1.2) para controles, etiquetas y cuerpo, donde la granularidad importa y los saltos grandes molestan.
• Zona display (lg–xxxl): saltos grandes (~1.25–1.7) para jerarquía y titulares, donde el contraste manda.

Un ratio único uniforme (lo que produce applyTypeScale) es la alternativa opt-in en runtime; la escala autorada conserva su afinado de dos zonas (como Radix / Material, que también afinan en vez de imponer un ratio puro). Cambiarla sería una regresión, no una mejora — por eso Fase 4 es documentación, no recableado.

Verificación por fase

• npm run check 0 errores; render-css snapshot regenerado (generated/base.css).
• Backward-compat: un config con sizes en px (string) sigue emitiendo igual.
• Navegador: el fluid escala con el viewport; <SText> cuenta líneas correctas; sin CLS al cargar las variable fonts.

Fuera de alcance

• Justificación / guionado / balanceo de líneas propio (el navegador + text-wrap lo hacen; <SText> solo mide).
• Subsetting dinámico en runtime (los unicode-range estáticos bastan).