Clase 05 · Módulo 04
Tu sistema visual en tokens
Tu sistema visual en tokens
Qué logras en esta clase
Dejas tus decisiones de tipografía, color y espacio escritas de una forma que Claude y el sitio comparten.
- Entiendes qué es un token y qué problema resuelve
- Sabes cómo se declaran en Tailwind 4
- Nombras cada token por su rol
- Compruebas que Claude los respeta en todo el sitio
02
Qué es un token
Un token es una decisión de diseño con nombre. Cambias su valor en un lugar y cambia en todo el sitio.
03
Con tokens y sin tokens
| Situación | Sin tokens | Con tokens |
|---|---|---|
| Cambiar el color de marca | Buscar y reemplazar en decenas de archivos | Editar una línea |
| Pedir una sección nueva | Claude elige colores parecidos | Claude usa los nombres definidos |
| Revisar coherencia | A ojo, página por página | Buscar valores fuera del sistema |
El costo es definirlos antes de construir. Ya hiciste ese trabajo en las clases 2, 3 y 4.
04
Qué decisiones se vuelven tokens
- Colores: los seis roles y los tres estados
- Tipografía: las familias y la escala de tamaños
- Espaciado: la unidad base de la escala
- Forma: el radio de las esquinas y las sombras
- Estructura: el ancho máximo y los puntos de corte
No todo es un token. Un valor que aparece una sola vez no necesita nombre.
05
Dos niveles: primitivos y semánticos
| Nivel | Qué nombra | Ejemplo |
|---|---|---|
| Primitivo | Un valor concreto de la paleta | amber-600 |
| Semántico | El rol que cumple ese valor | primario |
En el sitio se usan los semánticos. El primitivo solo aparece una vez, al decir qué valor tiene cada rol.
06
Dónde viven en Tailwind 4
Tailwind es la herramienta de estilos del curso; su serie vigente es la 4. En ella los tokens se declaran en el propio archivo CSS, dentro de un bloque @theme.
@import "tailwindcss";
@theme {
--color-primario: #b45309;
--radius-tarjeta: 0.75rem;
}Muchos tutoriales muestran un archivo tailwind.config.js. Era la forma de versiones anteriores y ya no es obligatorio.
07
De la variable a la clase
Declaras una variable dentro de @theme y Tailwind crea las clases que la usan. No hay que escribirlas.
08
Cada prefijo genera sus clases
Variable en @theme | Clases que aparecen |
|---|---|
--color-primario | bg-primario, text-primario, border-primario |
--font-titulos | font-titulos |
--text-xl | text-xl |
--spacing | La base de p-4, gap-6, mt-8 |
--radius-tarjeta | rounded-tarjeta |
--breakpoint-md | El prefijo md: |
El prefijo de la variable decide qué tipo de clase se genera. Por eso el nombre debe empezar con el prefijo correcto.
09
Nombra por rol, no por apariencia
Un nombre por apariencia dice cómo se ve hoy: --color-naranja. Un nombre por rol dice para qué sirve: --color-primario, --color-borde, --text-titulo.
10
Tres lugares para una variable
| Dónde | Cuándo se usa |
|---|---|
@theme | Quieres que exista una clase de Tailwind para ese valor |
@theme inline | El token apunta a otra variable, como la fuente de Astro o un rol que cambia en modo oscuro |
:root | Variable común de CSS que no necesita clase propia |
La mayoría de tus tokens va en el primero. El segundo ya lo viste en las clases 2 y 3.
11
¿Quitar la paleta que trae Tailwind?
Se puede vaciar un grupo completo y dejar solo lo tuyo:
@theme {
--color-*: initial;
--color-fondo: #fafaf9;
}- A favor:
bg-blue-500deja de existir; Claude no puede usarla - En contra: pierdes los grises y colores ya hechos; defines todo tú
Conviene cuando la coherencia importa más que la rapidez inicial.
12
El recorrido completo
Cada nivel usa solo el anterior. Una página no define colores; usa componentes. Un componente no inventa valores; usa clases que salen de los tokens.
13
Los componentes base
Son las piezas que se repiten en todo el sitio. Se definen una vez, con tokens.
- Botón: principal y secundario
- Enlace: dentro de texto y en el menú
- Campo de formulario: con su etiqueta y su mensaje de error
- Tarjeta: el recuadro de servicios o productos
- Sección: el contenedor con su ancho y su espacio vertical
En esta clase solo los decides. Se construyen en el módulo 5.
14
Cada componente tiene estados
| Estado | Cuándo ocurre | Qué suele cambiar |
|---|---|---|
| Normal | En reposo | Nada |
| Encima (hover) | El cursor pasa sobre él | Un tono del fondo |
| Foco | Se llega con el teclado | Un contorno bien visible |
| Deshabilitado | No se puede usar | Menos contraste, sin cursor de mano |
15
Tres capas para que Claude los respete
- Los tokens en el CSS. Son la única fuente de valores.
- Unas líneas en
CLAUDE.md. Dicen dónde están los tokens y la regla: usar solo esas clases, sin valores sueltos. - Tu revisión. Miras el diff y buscas lo que se salió del sistema.
Las tres hacen falta. La primera define, la segunda orienta y la tercera comprueba.
16
CLAUDE.md orienta, no bloquea
Como viste en el módulo 2, lo escrito en CLAUDE.md es contexto que Claude sigue, no una regla forzada. En una sesión larga puede escaparse un color fuera del sistema.
17
Cómo detectar valores sueltos
- En VS Code, abre la búsqueda en todo el proyecto (
Ctrl+Shift+F, oCmd+Shift+Fen Mac). - Busca
[#: encuentra colores escritos a mano dentro de clases. - Busca
px]: encuentra tamaños y espacios inventados. - Pídele a Claude que liste cada hallazgo con su archivo.
- Decide, uno por uno, qué token existente lo reemplaza.
18
Cuándo agregar un token nuevo
| Situación | Qué hacer |
|---|---|
| El valor se repite en varios lugares | Token nuevo |
| Representa una decisión de marca | Token nuevo |
| Es un ajuste único en un solo elemento | Valor puntual, sin token |
| Es casi igual a uno existente | Usa el existente |
El riesgo opuesto también existe: cuarenta tokens que nadie recuerda son tan inútiles como ninguno.
19
Una página de muestra
Pídele a Claude una página interna que muestre el sistema completo: los colores con su nombre, los tamaños de letra, los botones en todos sus estados, un campo de formulario y una tarjeta.
Sirve para revisar de un vistazo después de cada cambio de tokens.
20
Lo bueno y lo malo de trabajar así
- Bueno: el sitio se mantiene coherente aunque crezca
- Bueno: los pedidos a Claude se acortan; el sistema ya está dicho
- Bueno: cambiar la marca toma minutos
- Malo: exige decidir antes de ver nada construido
- Malo: las primeras versiones de los tokens casi nunca son las finales
Es normal ajustar valores al ver la primera página. Lo que no cambia son los nombres.
21
Errores comunes con tokens
- Nombrar por apariencia:
--color-azul - Usar un prefijo equivocado y que la clase no aparezca
- Seguir un tutorial antiguo basado en
tailwind.config.js - Definir tokens y luego aceptar valores entre corchetes
- Crear un token por cada caso particular
22
Un sistema que se puede comprobar
Tu sistema visual funciona si se puede comprobar: cada color, tamaño y espacio del sitio sale de un token.
23
Lo que te llevas
- Un token es una decisión de diseño con nombre y un solo lugar donde cambia
- En Tailwind 4 se declaran en el CSS, dentro de
@theme - El prefijo de la variable define qué clases se generan
- Se nombran por rol, no por apariencia
- Claude los respeta con tokens, una nota en
CLAUDE.mdy tu revisión
24
Hazlo ahora
Tiempo: 15 minutos.
- Reúne lo decidido en las clases 2, 3 y 4.
- Escribe una lista con tres columnas: nombre por rol, valor y de qué clase salió.
- Incluye colores, familias, tamaños, radio de esquinas y ancho máximo.
- Marca los que todavía dudas.
- Agrégala a tu brief del módulo 3.
En el módulo 5 crearás el proyecto y esta lista será lo primero que le entregues a Claude.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026