Diseño visual
El sistema debajo de cada pantalla: tokens para color, tipo, espacio, forma, profundidad y movimiento, y las especificaciones de componentes construidas a partir de ellos. El skill designer aplica este sistema a páginas reales. Construye el sistema una vez; deja que las páginas lo gasten.
Las reglas que más importan
- Escribe la dirección de diseño en palabras antes que cualquier token. Tres o cuatro frases: para quién es, cómo debería sentirse, cómo nunca debe sentirse, y lo único que toma prestado del tema. Cada decisión de token se verifica contra ese párrafo.
- Los componentes referencian tokens semánticos, nunca primitivos.
--color-text-primary, no--grey-900. El modo oscuro, la personalización y los cambios de marca se convierten en un re-mapeo, no en una reescritura. - Verifica el contraste para cada par real, en ambos temas, contra la tabla siguiente. Una paleta que funciona sobre blanco puede fallar sobre su propia superficie teñida.
- Un valor predeterminado no es una decisión. Los grises del framework, Inter en todo, un radio de 4px en cada caja: cada uno se ve bien y juntos se ven como cualquier otro producto. Decide cada valor o acéptalo a sabiendas.
- Cada especificación de componente lista todos los estados: predeterminado, hover, foco, activo, deshabilitado, cargando, error y seleccionado donde corresponda. Los estados faltantes se inventan en la construcción, de manera inconsistente.
- Menos valores, usados de manera consistente. Una escala de 6 pasos usada en todas partes supera a una de 14 pasos usada al azar.
Cuándo no usar
- Organizar una página específica, elegir qué va arriba del pliegue, criticar una pantalla o ejecutar un rediseño:
designer. - Generar ilustraciones, íconos, imágenes de héroe o marcas:
artist. - Gráficos y paletas de visualización de datos: el skill
frontendenreferences/charts.md. Los colores categóricos de gráficos tienen restricciones que una paleta de marca no tiene. - Implementar los tokens en un framework:
frontend.
Orden de construcción
Cada capa depende de la anterior:
- Párrafo de dirección.
- Color: primitivos, luego tokens semánticos.
- Tipo: familias, luego escala y roles.
- Escala de espaciado y cuadrícula.
- Radio, borde y elevación.
- Tokens de movimiento.
- Tokens de componentes y especificaciones de componentes.
Color
Estructura:
Primitivos (valores brutos, una rampa por tono, ej. 50, 100 ... 900, 950):
--blue-600: oklch(0.55 0.17 255)
Tokens semánticos (referencian primitivos, nombrados por función):
--color-bg, --color-surface, --color-surface-raised
--color-text, --color-text-muted, --color-text-on-accent
--color-accent, --color-accent-hover
--color-border, --color-focus-ring
--color-danger, --color-success, --color-warning (cada uno con una variante segura para texto)
Reglas que separan una paleta pensada de una predeterminada:
- Construye rampas en OKLCH. La claridad se mantiene perceptualmente uniforme entre tonos, por lo que un azul 600 y un verde 600 tienen el mismo peso visual. La claridad HSL miente.
- Tiñe los neutros. El gris puro y el negro o blanco puro se ven sin dueño. Añade una pequeña cantidad de croma (aproximadamente 0.005 a 0.015) hacia el tono de la marca.
- Texto sobre una superficie coloreada usa un tono oscuro del tono de esa superficie, no gris neutro. El gris sobre el color se ve deslavado.
- Elige un nivel de compromiso y mantente firme: contenido (suelo neutro, un acento), comprometido (tono de marca presente en todo), paleta completa, o empapado (el tono de marca es el suelo). Un medio compromiso se lee como indecisión.
- Nunca dejes que el color transmita significado por sí solo. Combínalo con un ícono, una etiqueta o un patrón.
- Cuidado con los reflejos actuales. Una página crema cálida con una tipografía de exhibición serif y un acento terracota, o un casi negro con un acento ácido, son a lo que recurren los diseños generados cuando no se ha decidido nada. Úsalos solo cuando el párrafo de dirección los pida.
Contraste (WCAG 2.2)
| Par | AA | AAA |
|---|---|---|
| Texto del cuerpo (por debajo del tamaño grande) | 4.5:1 | 7:1 |
| Texto grande: 24px regular, o aproximadamente 18.7px bold, y superior | 3:1 | 4.5:1 |
| Límites de componentes de UI, íconos, indicadores de foco, marcas de gráficos que transmiten significado | 3:1 | ninguna |
- El texto de marcador de posición que le dice algo al usuario es texto: 4.5:1.
- Los controles deshabilitados están exentos, pero el usuario aún debe poder ver que hay un control.
- Mide los colores calculados, incluyendo opacidad y superposiciones. Una etiqueta con opacidad al 60% sobre una tarjeta teñida es un nuevo color.
Tipografía
- Elige familias para el registro del contenido, no por costumbre. Tres roles: una familia de exhibición con carácter, usada con moderación; una familia de cuerpo cómoda; una familia utilitaria para etiquetas, leyendas y datos (figuras tabulares para números en tablas).
- Combina con un contraste claro (serif con sans, geométrica con humanista) o usa una sola familia con diferentes pesos. Dos familias que son similares pero no iguales se leen como un error.
- Escala modular. Elige una proporción: 1.2 para UI de producto densa, 1.25 a 1.333 para contenido y marketing. Nombra roles, no tamaños:
display,h1ah4,body-lg,body,body-sm,label,caption. - Medida de 60 a 75 caracteres para el texto del cuerpo (
max-width: 70ch). - Tipo de exhibición obtiene un tracking más ajustado (alrededor de
-0.02ema-0.04em) y un límite de tamaño (aproximadamente 6rem medianteclamp()). Más grande rara vez se lee como intencional. text-wrap: balanceen encabezados,text-wrap: prettyen prosa del cuerpo.- Altura de línea: aproximadamente 1.5 para el cuerpo, 1.1 a 1.25 para exhibición.
Espacio, forma, profundidad
- Escala de espaciado sobre una base de 4 u 8: por ejemplo 4, 8, 12, 16, 24, 32, 48, 64. Los componentes usan tokens, nunca valores en píxeles brutos.
- Radio: dos o tres valores con una regla sobre dónde se aplica cada uno. Radios anidados: el radio interno es igual al radio externo menos el relleno entre ellos.
- Elevación: tres o cuatro niveles, cada uno vinculado a una función (tarjeta en reposo, menú desplegable, modal). En temas oscuros, eleva la elevación con una superficie más clara, no con una sombra más pesada.
Movimiento
- Tokens: duraciones (por ejemplo 120ms, 200ms, 320ms) y dos o tres curvas de easing (una para entrar, otra más pronunciada para salir). Los elementos las reutilizan; nadie elige un valor por elemento.
- El movimiento explica un cambio: de dónde vino algo, qué respondió. El movimiento que solo decora parece generado.
- Un momento coreografiado supera a que todo se desvanezca a la vez.
- Respeta
prefers-reduced-motion: reduce: elimina el movimiento y las transiciones largas, mantén los cambios de opacidad. - No escalar fotos al hacer hover. Anima el contenedor (sombra, borde, fondo).
Modo oscuro
- Un tema oscuro es un re-mapeo de tokens semánticos, nunca una inversión. Usa grises oscuros para el fondo, no negro puro, y reduce el croma de los acentos que brillan.
- Vuelve a verificar cada par de contraste en el tema oscuro.
- Evita el destello del tema incorrecto: decide el tema en un pequeño script inline en el head del documento, antes de la primera renderización.
Lee references/dark-mode.md al implementar cambio de tema, persistencia o imágenes en modo oscuro.
Especificaciones de componentes
Lee references/component-spec.md antes de escribir una especificación de componente. Contiene la plantilla y la lista de verificación de estados.
Errores comunes
- 11 tonos nombrados del 100 al 900. Eso son 9 pasos. Nombra las rampas para que el recuento y los nombres coincidan (50, 100 ... 900, 950 da 11).
- El "texto grande" significa 18 puntos, no 18 píxeles. El texto del cuerpo regular de 18px necesita 4.5:1, no 3:1. El umbral de texto grande es 24px regular o aproximadamente 18.7px bold.
- Tokens primitivos en componentes. Funciona hasta el primer tema. Luego cada componente necesita edición.
- Contraste verificado en el mock, no en la compilación. La opacidad, las superposiciones y el anti-aliasing cambian el color real. Mide los píxeles renderizados o los estilos calculados.
- Un ajuste global para solucionar un problema local. Oscurecer toda la paleta para rescatar un par fallido desplaza todos los demás pares. Arregla el token del par.
- Un token que nadie usa, o un valor bruto que nadie tokenizó. Ambos significan que el sistema y la compilación se han desviado. Busca en la compilación valores hex y píxeles brutos.
- Una nueva fuente cargada para un solo encabezado. Cada familia cuesta tiempo de carga. Usa las familias que el sistema ya carga.
Verificación
- Párrafo de dirección escrito, y cada familia de tokens puede rastrearse hasta él.
- Cada par de texto y UI pasa AA en claro y oscuro, medido en la página construida.
- Los componentes usan solo tokens semánticos:
grepno muestra valores de color o espaciado brutos en el código del componente. - Cada especificación de componente lista todos sus estados.
- Configuración de movimiento reducido probada: no queda movimiento.
- El cambio de tema no muestra destello en una recarga forzada con la configuración opuesta del sistema.