Diseñar con tokens
Cómo cada superficie de este boilerplate se mantiene fiel al tema — un único conjunto de tokens semánticos, cero colores a fuego, y componentes que se reestilizan solos cuando cambia el tema.
Todos los colores de este boilerplate son un token semántico: background, foreground, muted, primary, border. Los componentes nunca nombran un color — nombran un rol, y el tema decide qué aspecto tiene ese rol.
Esa única regla es la razón por la que cambiar el aspecto entero de la app es tocar un solo archivo CSS.
Por qué tokens semánticos
Los colores a fuego se pudren. El primer text-gray-500 parece inofensivo; seis meses después hay cuarenta, se lanza el modo oscuro, y la mitad están mal de formas que nadie nota hasta que una captura acaba en la presentación de un cliente.
Los tokens invierten el problema. Un componente dice text-muted-foreground — "texto secundario" — y cada tema trae su propia respuesta sobre qué significa eso.
La paleta vive en un solo archivo
packages/ui/src/styles/globals.css define cada token dos veces: una bajo :root para el tema claro, otra bajo .dark. Nada más en el repositorio declara un color.
Los componentes siguen siendo ignorantes
Una tarjeta es bg-card text-card-foreground. No tiene ni idea de si se renderiza sobre el blanco de la landing o el negro del dashboard, y esa ignorancia es justamente la ventaja.
El radio y el espaciado siguen la misma regla
La escala de redondeo deriva de una sola variable --radius. ¿Quieres un producto de aristas más marcadas? Cambia una línea y cada botón, tarjeta y diálogo te sigue.
Qué te llevas
- Recambiar el tema es un cambio de configuración, no una migración.
- El modo oscuro es correcto por construcción, no por auditoría.
- Los componentes nuevos heredan el lenguaje visual gratis — si solo usan tokens, no pueden salirse de la marca.
La disciplina no cuesta nada al empezar y es casi imposible de aplicar a posteriori. Empieza con ella.