Cómo usar tokens semánticos de color

Tu marca usa el verde. El botón principal es verde, el mensaje de éxito es verde y el elemento seleccionado de la navegación también es verde. Todo parece coordinado hasta que la marca cambia al morado. ¿Debería volverse morada también la confirmación de una subida correcta? ¿Y el contorno de foco o la advertencia junto a una cuenta a punto de caducar?

Los tokens semánticos de color hacen explícitas esas decisiones. Un token primitivo identifica un valor de color, como green-700. Un token semántico identifica su función, como action-primary-background o status-success-text. Los componentes hacen referencia a la función, de modo que una actualización de marca pueda cambiar los usos previstos sin modificar accidentalmente todos los elementos que tengan un tono parecido.

Empieza por el error que quieres evitar

Imagina un espacio de trabajo con un botón «Crear proyecto», una confirmación «Guardado», un mensaje de error y un enlace seleccionado en la barra lateral. El diseñador original eligió el mismo verde oscuro para el botón, la confirmación y el enlace seleccionado. Con buen criterio, un desarrollador almacenó ese valor una sola vez y lo reutilizó. Ahora, una nueva dirección de marca pide un color principal diferente.

Cambiar la variable verde compartida actualiza los tres elementos. La implementación es coherente con el código original, pero la decisión es incorrecta: la confirmación era verde porque comunica éxito, no porque represente la acción principal de la marca. Esa distinción existía en la cabeza del diseñador y nunca llegó a las reglas reutilizables.

Antes de añadir tokens, escribe esa diferencia con palabras sencillas. «La acción principal sigue la marca del producto. Los mensajes de éxito conservan su significado de estado. La selección necesita un estado activo claro». Estas afirmaciones aportan más valor que empezar por una convención de nombres, porque indican qué valores pueden cambiar juntos sin provocar problemas.

Cómo hace Atlassian visible la función en la interfaz

La guía de color de Atlassian relaciona un tablero de Jira con tokens de selección, texto y fondo de un botón de marca. Su vocabulario distingue las funciones del color del grado de énfasis y del estado de interacción. También trata por separado la selección y el foco de teclado: un elemento seleccionado debe conservar su tratamiento de selección cuando se añade un indicador de foco.

Fíjate en por qué una interfaz anotada resulta más útil que una paleta por sí sola. Una muestra de color puede indicar su valor. El tablero muestra qué parte de la experiencia debe usar ese valor y por qué. Puedes comprobar si la etiqueta se refiere al texto, a una superficie o a un icono, en lugar de deducir el uso previsto por la saturación aparente del color.

Para un sistema pequeño, adopta ese hábito antes de adoptar todo el catálogo de nombres. Coloca el token propuesto junto a un uso real, describe qué circunstancia debería hacer que cambiara y muestra un uso que no debería controlar. «Acción de marca» y «operación realizada correctamente» pueden empezar con el mismo verde y seguir siendo decisiones independientes. Si tu mapa no puede expresar esa diferencia, está almacenando una paleta, no la semántica de la interfaz.

Haz concreta la prueba de dependencias

Un pequeño mapa de alias basta para poner de manifiesto el error. En este ejemplo ilustrativo, el éxito y la acción principal parten del mismo valor, pero hacen referencia a funciones separadas:

:root {
  --palette-green-700: #236646;
  --palette-purple-700: #6439a8;
  --action-primary-bg: var(--palette-green-700);
  --action-primary-fg: #fff;
  --status-success-text: var(--palette-green-700);
}
[data-brand="purple"] {
  --action-primary-bg: var(--palette-purple-700);
}

Cambiar el atributo de marca debe modificar los elementos que usan --action-primary-bg. No debe modificar una etiqueta de éxito que use --status-success-text. Si cambian ambos, revisa las referencias reales de los componentes antes de elegir otro tono. Si no cambia ninguno, busca un color escrito directamente en el código o una regla más específica que lo sobrescriba. Esta es una prueba de dependencias; los valores ilustrativos siguen necesitando comprobaciones de contraste en sus contextos reales.

Después, prueba el color de primer plano junto con el de fondo. La superficie de una acción y su etiqueta forman una pareja. Actualizar solo la superficie puede hacer que una etiqueta antes legible deje de serlo, especialmente cuando una marca más clara sustituye a otra oscura. Documenta la función asociada en el mapa, de modo que cambiar una desencadene la revisión de la otra, sin depender de que el revisor lo recuerde.

Comprueba la migración en tres pasadas:

1. Mantén los valores sin cambios. Introduce los alias y compara con la referencia visual. Las diferencias inesperadas apuntan a errores de asignación.
2. Cambia temporalmente una función. Examina todos los elementos que deben usarla, incluidos los que deberían permanecer sin cambios.
3. Restaura el tema aprobado. Revisa las combinaciones de estados de paso del puntero, foco, desactivación y selección. Registra por separado los valores directos que sean deliberados y el trabajo de migración pendiente.

Separa valores, funciones y decisiones de componente

Un sistema pequeño puede empezar con dos capas. La capa de valores contiene los colores concretos. La capa de funciones asigna esos valores a los propósitos de la interfaz. Una tercera capa específica de componente resulta útil cuando un componente necesita evolucionar de forma independiente, pero no es obligatoria en todos los proyectos pequeños.

Por ejemplo, neutral-950 podría contener el neutro más oscuro. Tanto text-primary como border-strong podrían apuntar inicialmente a él. Siguen siendo funciones distintas porque mejorar la legibilidad del cuerpo de texto no tiene por qué oscurecer todos los bordes marcados. Que los valores sean idénticos hoy no demuestra que dos decisiones deban compartir nombre para siempre.

El error contrario consiste en crear un token único para cada elemento visible. Si todos los párrafos normales del cuerpo cumplen la misma función, asignar un token de texto propio a cada párrafo añade mantenimiento sin aportar significado. Una pregunta útil es: ¿querríamos alguna vez cambiar deliberadamente uno de estos usos sin cambiar el otro? Si la respuesta es sí, considera funciones separadas. Si es no, reutiliza la función existente.

Los nombres deben ayudar a elegir correctamente sin abrir todos los componentes. Un desarrollador que busque un borde de error para un campo no debería tener que adivinar si accent-strong, special-red o brand-secondary significa peligro. Prefiere una función comprensible a una abreviatura ingeniosa, especialmente si ese mismo contexto lo va a utilizar un agente de programación.

Asigna colores semánticos a las funciones de la interfaz

Empieza por examinar una página representativa en varios estados. Una captura estática del panel predeterminado no revelará acciones desactivadas, mensajes de validación, foco de teclado ni un elemento de menú seleccionado. Necesitas suficientes estados para descubrir las funciones reales del color, no todos los estados teóricos que una gran organización podría admitir algún día.

Para el espacio de trabajo ficticio, el primer mapa puede cubrir el fondo de página, las superficies elevadas, el texto principal, el texto secundario, los bordes normales, la acción principal, el texto sobre esa acción, la selección, el foco, el éxito, las advertencias y los errores. Algunas funciones necesitan una pareja de primer plano y fondo. Una superficie de éxito clara y su texto oscuro son valores distintos que comparten un propósito.

La primera revisión consiste en asignar funciones. Marca cada color visible en la página de ejemplo y pregunta qué comunica. Si un panel verde pálido solo agrupa controles relacionados, corresponde a una función de superficie o agrupación. Si anuncia que una operación ha terminado correctamente, corresponde a un mensaje de estado. Estos usos pueden parecerse, pero sus cambios futuros deberían seguir reglas diferentes.

Mantén la descripción escrita junto al nombre del token. «Fondo de acción principal: la acción disponible más importante de una sección» resulta más útil que limitarse a «verde». Incluye un ejemplo de contraste cuando pueda haber confusión: el token no significa «cualquier elemento que queramos que la gente vea». Un mensaje de error importante sigue necesitando el tratamiento de estado adecuado.

Prueba un cambio de marca antes de darlo por definitivo

Este ejemplo es deliberadamente pequeño. El espacio de trabajo empieza con una acción de marca verde y mensajes de éxito verdes. Más adelante, el color de acción cambia a otro tono de marca. Quieres que el botón y el tratamiento de la navegación seleccionada sigan la nueva dirección, mientras que «Guardado» conserve su función de éxito reconocible.

Primero, identifica las funciones afectadas por la decisión de marca. El fondo del botón y su texto de primer plano necesitan revisarse juntos. La selección puede utilizar una superficie o un indicador independiente derivado de la marca. El logotipo es un recurso de marca, no un token de botón corriente. No cambies su color mediante una regla general de interfaz sin considerar los requisitos propios de ese recurso.

A continuación, cambia las asignaciones de funciones en una copia de la página. No busques todas las apariciones del antiguo valor hexadecimal para sustituirlas indiscriminadamente. Buscar valores directos resulta útil para localizar posibles casos, pero no permite saber si una aparición concreta representa un enlace, un estado de éxito o un detalle de una ilustración.

Por último, revisa todos los elementos que usan las funciones modificadas. La acción principal podría aparecer en una página blanca, en un panel claro y dentro de un diálogo. Un relleno nuevo que destaca en un contexto puede confundirse con el fondo en otro. El cambio de asignación solo está completo cuando los usos previstos siguen comunicando la acción correcta y continúan siendo legibles.

Especifica los estados sin crear un color para cada cosa

La apariencia predeterminada de una acción es solo una parte de su comportamiento. El paso del puntero, la pulsación, el foco, la selección y la desactivación pueden expresar cosas diferentes. Un elemento de navegación puede seguir seleccionado mientras recibe también el foco de teclado. Un botón puede tener foco sin estar pulsado. Evita reducir todas esas condiciones a un único color «activo».

Empieza por la información que debe comunicar cada estado. El paso del puntero indica una relación con el cursor. El foco muestra a quien usa el teclado dónde tendrá lugar la interacción. La selección identifica una elección persistente. Los tratamientos visuales pueden compartir recursos, pero deben seguir distinguiéndose cuando coinciden varios estados. Un borde, un subrayado, un icono o una forma pueden transmitir parte del mensaje.

En la barra lateral del ejemplo, podrías usar un fondo de selección sutil y un contorno de foco claro. El contorno no debería desaparecer porque el elemento ya esté seleccionado. Revisa directamente ese estado combinado. Mirar muestras de color aisladas no permite ver si ambos tratamientos interfieren entre sí en el componente real.

El estilo de desactivación merece el mismo cuidado. Una acción desactivada necesita una explicación cuando el usuario no puede deducir por qué no está disponible. Volver gris un botón no comunica si falta un campo obligatorio, si no se dispone de un permiso o si ya hay una operación en curso. Un token identifica una función visual; no puede sustituir la lógica de interacción ni el texto explicativo.

Mantén visibles las excepciones específicas de componente. Si una confirmación destructiva necesita un tratamiento de botón distinto, documenta su propósito, en lugar de sustituir silenciosamente el token de acción principal dentro de un diálogo. La excepción puede ser legítima. El problema empieza cuando nadie puede saber si es intencional o un atajo puntual de implementación.

Acompaña el color con un significado legible

El color facilita recorrer visualmente una interfaz, pero el significado debe mantenerse cuando resulta difícil distinguir el tono. Un borde rojo por sí solo obliga al usuario a deducir qué ha ocurrido. Una etiqueta de error y un mensaje útil para corregirlo hacen comprensible el estado. Del mismo modo, un icono de éxito acompañado de «Cambios guardados» comunica más que un punto verde sin etiqueta.

La guía del W3C sobre el uso del color explica el requisito de no depender exclusivamente del color para transmitir información o identificar una acción. Aplica ese principio a cada función en su contexto. En este espacio de trabajo, los mensajes de estado incluyen texto legible, los elementos seleccionados conservan un tratamiento de selección visible y los enlaces siguen siendo identificables más allá de una diferencia sutil de tono.

El contraste es una comprobación aparte. Un color puede comunicar el significado correcto y aun así ser demasiado tenue para leerse. Evalúa las parejas de primer plano y fondo, en lugar de asignar a una muestra de marca una etiqueta general de «accesible». Un primer plano oscuro sobre una superficie de éxito clara es una combinación distinta del texto blanco sobre un botón de éxito de color saturado.

Para el texto normal, el criterio de contraste mínimo de WCAG exige generalmente 4.5:1; para el texto que reúne las condiciones de texto grande, 3:1, con las excepciones definidas. La explicación del contraste del W3C detalla el alcance y las condiciones. Mide la pareja real y su uso renderizado: que una pareja supere la prueba no certifica un componente, un tema ni un sitio completo.

Los valores del ejemplo anterior permiten verlo de forma concreta. Al calcular la luminancia relativa del verde #236646 y el morado #6439a8, se obtienen relaciones de contraste de 6.86:1 y 7.80:1 frente al blanco. Frente al negro, los mismos rellenos dan 3.06:1 y 2.69:1. Por tanto, ambos admiten una etiqueta blanca con el umbral de texto normal, pero ninguno admite una etiqueta negra con ese umbral. El nombre semántico no determina este resultado: lo hacen los valores concretos de primer plano y fondo. Conserva el cálculo asociado a esa pareja para que un futuro color de marca más claro desencadene una nueva comprobación.

No soluciones todos los fallos oscureciendo la interfaz entera. Examina qué función falla, sobre qué superficie y en qué estado. El texto secundario sigue teniendo una función de lectura. Un mensaje de ayuda demasiado pálido no mejora porque se lo llame «sutil». A la inversa, convertir todos los separadores en líneas oscuras y gruesas puede borrar la jerarquía que el sistema debía crear.

Revisa el tema oscuro como una nueva asignación

Un tema oscuro es una prueba de exigencia útil porque separa el propósito de la apariencia. El texto principal sigue necesitando ser el texto principal, pero su valor cambia. Una superficie elevada sigue necesitando distinguirse de la página. Los mensajes de éxito deben seguir siendo comprensibles aunque sus valores de fondo y primer plano sean distintos de los del tema claro.

No te limites a invertir cada valor primitivo ni a reutilizar los valores del tema claro sobre una página oscura. Revisa las relaciones. Una acción brillante que parecía equilibrada sobre blanco puede dominar una superficie oscura. Un borde discretamente visible en un panel claro puede desaparecer. Las imágenes, los logotipos y los gráficos también pueden requerir decisiones que queden fuera del mapa semántico de color.

Usa el mismo contenido en las vistas previas de ambos temas. De lo contrario, las diferencias de densidad o de imágenes pueden distraer de las decisiones sobre el color. Incluye un error de formulario, un mensaje de éxito, un elemento de navegación seleccionado, un control con foco y algo de texto secundario. Estos estados permiten una comparación más útil que una galería de botones atractivos en su estado predeterminado.

Los nombres de las funciones deben mantenerse estables durante la comparación. Si te encuentras cambiando text-primary por white-text en el tema oscuro, estás volviendo a introducir un valor en un nombre que debía describir una función. Mantén el significado constante y cambia la asignación que lo hace posible.

Dale al agente de programación el mapa, además de la paleta

Cuando pidas a un agente que ajuste una página, incluye las decisiones sobre las funciones junto con la referencia visual. Una captura muestra los colores actuales. No explica cuáles deben seguir vinculados durante un cambio de marca ni qué combinaciones de estados deben continuar funcionando. Una tabla breve de asignaciones y un componente representativo hacen que esa intención sea mucho más fácil de comprobar.

En las vistas previas HTML compatibles de OpenDesign, puedes revisar el resultado renderizado, usar los controles disponibles de edición manual de estilos y añadir comentarios en la zona pertinente para la conversación. Usa esas funciones para señalar una discrepancia concreta, como un aviso de éxito que utiliza el tratamiento de acción principal. El comentario debe identificar tanto la función prevista como la ubicación visible.

Por ejemplo, pide al agente que actualice la asignación de acción principal conservando las funciones de éxito y error, y que después muestre los usos de los botones afectados en sus distintos estados. Si tu proyecto ya tiene convenciones para los tokens, proporciona esos archivos o el contexto de diseño. Evita pedir un sistema de nombres completamente nuevo como parte de una pequeña corrección de color.

Después de una corrección visual, revisa la referencia del componente en los archivos generados. El botón puede tener el aspecto correcto y seguir usando el token de éxito; el siguiente cambio de tema volvería a revelar el mismo error de dependencia.

Migra primero un componente representativo

Puedes introducir funciones semánticas sin sustituir todo el sitio de una vez. Elige un componente con varios estados significativos, como el formulario de creación de proyectos. Enumera sus valores actuales, decide la función de cada uno y asigna esas funciones a la paleta existente. Al principio, el diseño visible puede permanecer casi sin cambios.

Después, cambia la asignación de una función como prueba controlada. Si las acciones principales deben cambiar juntas, verifica que lo hagan los botones previstos. Si los mensajes de estado deben permanecer independientes, verifica que no cambien con el color de acción. La prueba trata de la dependencia, no de si el color temporal sería una buena elección definitiva para la marca.

Conserva un registro de los elementos que todavía usan valores directos. Algunos serán deliberados: una ilustración, un logotipo de un socio o una visualización de datos pueden no pertenecer a la misma función de interfaz. Otros serán trabajo de migración pendiente. Señala la diferencia para que la siguiente persona no confunda una conversión incompleta con una excepción aprobada.

Cuando el componente representativo se comporte correctamente, amplía la migración a los componentes relacionados. Revisa la página renderizada después de cada grupo significativo, en lugar de confiar en una sustitución global. Las reglas compartidas pueden afectar a contextos que no tenías abiertos. Una migración pequeña permite descubrirlos antes de que resulte más difícil comparar toda la interfaz.

Qué debe dejar una revisión útil de tokens

La revisión final debe dejar un mapa que otra persona pueda usar: nombres de funciones, propósitos previstos, valores actuales para cada tema compatible y algunos componentes representativos que muestren su comportamiento. Añade notas donde una función deba ir emparejada con otra, como el texto sobre el fondo de una acción. Registra las excepciones relevantes sin convertir cada píxel en una regla independiente.

Pide a un compañero que elija, con ese mapa, el token para un mensaje de éxito nuevo y para una acción principal nueva. Si elige correctamente sin tener que adivinar a partir de las muestras de color, el sistema está siendo útil. Si ambas decisiones siguen desembocando en «usa el verde de marca», aclara las descripciones de las funciones antes de añadir más tokens.