Tema Starlight Sergio Escobar

Objetivo del setup

Este proyecto usa un tema custom basado en tu paleta Sergio Escobar para light y dark, aplicado sobre los tokens de color de Starlight (--sl-color-*), conservando la configuracion actual de fuentes.

Donde vive cada pieza

• Tema de colores: src/styles/global.css
• Fuentes Starlight activas: src/styles/fonts.css
• Carga de CSS en Starlight: astro.config.mjs -> starlight({ customCss: [...] })
• Selector de tema (header): src/components/starlight/ThemeSelect.astro monta HeroUIThemeSelect.tsx (HeroUI ToggleButtonGroup + @gravity-ui/icons). Importa cada icono por archivo (@gravity-ui/icons/Sun, etc.): el barrel import { Sun } from '@gravity-ui/icons' falla en Vite (CJS/named exports), y el barrel esm/index.js fuerza resoluciones masivas que pueden romperse en Windows. No existe SunLight; el export real es Sun.
• Componentes que consumen colores de Starlight:
  • src/components/VideoManager.tsx
  • src/components/starlight/PageTitle.astro
  • src/components/starlight/PostInfo.astro

import Display from '@gravity-ui/icons/Display';
import Moon from '@gravity-ui/icons/Moon';
import Sun from '@gravity-ui/icons/Sun';

Como se activa light y dark

Starlight marca el documento con data-theme en :root:

• :root[data-theme='light']
• :root[data-theme='dark']

El setup actual define:

• :root, :root[data-theme='light'] -> tokens de light
• :root[data-theme='dark'] -> tokens de dark

Esto permite que light sea el fallback por defecto y dark lo sobrescriba solo cuando corresponde.

Orden y precedencia CSS (clave para fine-tuning)

1. Starlight inyecta sus estilos base.
2. Tus archivos de customCss se cargan encima.
3. En global.css, tus variables redefinen los tokens --sl-color-*.
4. Cualquier regla mas especifica (por ejemplo :root[data-theme='light'] .mi-clase) puede ajustar casos puntuales.

Si ves un color inesperado, casi siempre es un tema de:

• token equivocado,
• especificidad,
• o selector fuera de data-theme.

Mapeo conceptual: paleta Sergio Escobar -> tokens Starlight

Starlight no consume directamente claves como primary, card, muted (estilo design-system generico), sino sus propios tokens --sl-color-*.

Por eso, el setup traduce tu paleta a tokens usados por Starlight:

Concepto visual	Token Starlight	Light	Dark
Texto principal	--sl-color-text	#1a1a1a	#e8ecf4
Fondo global	--sl-color-bg	#ffffff	#0c101c
Fondo nav/superficies	--sl-color-bg-nav	#fafafa	#121a2a
Accent principal	--sl-color-accent	#1e4ba1	#5b8def
Accent fuerte	--sl-color-accent-high	#182775	#7aa7ff
Accent suave	--sl-color-accent-low	#b3c7ff	#ff6b6f
Bordes base	--sl-color-gray-5	#e5e5e5	#3d4a62
Fondo suave	--sl-color-gray-7	#f5f6f8	#151c2c
Error/destructivo	--sl-color-red	#dc2626	#ff6b6b

Escala de grises en este proyecto

La escala --sl-color-gray-1 … --sl-color-gray-7 se usa para jerarquia de contraste:

• gray-1: texto de alto contraste
• gray-2 y gray-3: texto secundario/meta
• gray-5: bordes y separadores
• gray-6 y gray-7: fondos y superficies suaves

En dark, la semantica se mantiene aunque los hex cambian.

Fuentes: que se mantiene y por que

No se modifico la tipografia del setup actual:

• --sl-font: 'Source Sans 3'
• --sl-font-mono: 'JetBrains Mono'

Estan definidos en src/styles/fonts.css y cargados via customCss en astro.config.mjs.

Como llamar colores desde la app

1) CSS normal

.mi-bloque {
  background: var(--sl-color-bg);
  color: var(--sl-color-text);
  border: 1px solid var(--sl-color-gray-5);
}

2) CSS con overrides por tema

.tag {
  color: var(--sl-color-text);
}

:root[data-theme='dark'] .tag {
  color: var(--sl-color-accent-high);
}

3) React/Astro inline style

<div style={{ color: 'var(--sl-color-text)', background: 'var(--sl-color-bg)' }} />

4) Gradientes y mezclas

Para mantener coherencia visual, usa color-mix con tokens:

.chip {
  background: color-mix(in srgb, var(--sl-color-accent) 14%, transparent);
  color: var(--sl-color-accent);
}

Como se conecta con claves de tu tema original

Tu objeto trae claves tipo background, foreground, primary, secondary, muted, etc.

Regla practica para mapear a Starlight:

• foreground -> --sl-color-text
• background -> --sl-color-bg
• primary o accent -> --sl-color-accent
• primary-foreground -> --sl-color-text-invert
• muted -> --sl-color-gray-7 o --sl-color-bg-inline-code
• muted-foreground -> --sl-color-gray-3
• border / input -> --sl-color-gray-5
• destructive -> --sl-color-red
• card / sidebar / popover -> --sl-color-bg-nav o --sl-color-bg-sidebar

Si en el futuro quieres consumir claves exactas (--background, --primary, etc.), puedes declarar esas variables en paralelo, pero para Starlight siempre conviene mantener el puente --sl-color-*.

Nota sobre Catppuccin plugin

Actualmente el proyecto mantiene @catppuccin/starlight en astro.config.mjs.
Tus overrides en global.css ya tienen efecto, pero conceptualmente hay dos capas de tema:

1. Plugin Catppuccin
2. Overrides custom Sergio Escobar

Para simplificar mantenimiento, puedes dejar solo una estrategia (normalmente overrides custom) cuando termines el fine-tuning.

Checklist de fine-tuning

Cuando ajustes colores, sigue este orden:

1. Ajusta tokens base: --sl-color-text, --sl-color-bg, --sl-color-accent.
2. Revisa contraste en:
   • body text
   • links
   • code inline
   • bordes de cards y tablas
3. Ajusta grises gray-2/3/5/7 para micro-jerarquia.
4. Valida componentes custom (VideoManager, PostInfo, PageTitle).
5. Prueba light/dark en paginas largas y en moviles.

Errores comunes

• Usar hex directo en componentes en vez de tokens.
• Cambiar solo light y olvidar dark.
• Tocar --sl-font o --sl-font-mono sin querer al editar bloque :root.
• Definir override fuera de :root[data-theme='dark'] y romper consistencia.

Recomendacion de trabajo

• Mantener un unico archivo fuente de verdad para color: src/styles/global.css.
• Mantener fuente tipografica separada: src/styles/fonts.css.
• Crear una seccion “tokens de marca” al inicio de global.css para documentar cambios.
• Versionar cambios pequenos de contraste (commits cortos) para rollback facil.