Color semántico

Las primitivas responden qué colores existen. Los roles semánticos responden qué color va dónde. Un componente nunca dice Grey/6: dice border/default. Eso da tres cosas gratis:

• Dark mode sin trabajo — el rol apunta a la misma primitiva en ambos temas y la primitiva cambia de valor. Cero condicionales.
• Decisiones consistentes — todos los bordes de input son el mismo borde.
• Cambios baratos — si mañana el hover tonal pasa de 4 a 5, se cambia en un lugar.

En Figma es la colección Semantic de 🌻 FDS Design Tokens. Cada variable tiene su descripción y su nombre de CSS en Dev Mode. En código, el mismo nombre es una variable CSS (--primary-subtle) y una utilidad de Tailwind (bg-primary-subtle).

Anatomía de un nombre#

primary / subtle-hover
└─ rol ─┘ └── uso + estado ──┘

Hay dos familias de roles:

1. Neutros por propiedad — bg/*, border/*, text/*, icon/*, focus/ring. Son el 90% de cualquier pantalla.
2. Roles de color — primary, neutral, success, warning, danger, info. Los seis comparten exactamente los mismos 14 usos, así que un componente con prop color cambia de rol sin tocar su estructura.

Los 14 usos de un rol de color#

Tres excepciones deliberadas: warning/accent usa Yellow 11 → 11 → 12 (el amarillo 9 no se lee como texto), neutral/solid usa Grey 12 → 11 → 10 (un sólido neutro tiene que ser casi negro, no gris medio), y warning/on-solid es Yellow/12, no blanco — el amarillo de marca es demasiado luminoso para texto blanco.

Pares seguros#

Estas combinaciones cumplen contraste AA por construcción. Salirte de ellas significa pasar por el verificador.

text/subtle y text/disabled no garantizan AA: son para placeholders y estados deshabilitados, nunca para contenido que alguien necesite leer.

Todos los roles#

Reglas#

• Elegí por significado, no por apariencia. danger es para errores y destrucción aunque el rojo "quede bien" en otro lado.
• Un solo solid por zona. El sólido es el grito; el tonal es la voz normal.
• El color nunca va solo. Todo estado comunicado por color lleva también icono o texto (1 de cada 12 hombres no distingue rojo de verde).
• Si falta un rol, pedilo. Usar una primitiva directo rompe dark mode y la trazabilidad con Figma.

En código#

<div className="border border-danger-border bg-danger-subtle text-danger-text">
  No pudimos guardar los cambios.
</div>

.alert {
  background: var(--danger-subtle);
  border: 1px solid var(--danger-border);
  color: var(--danger-text);
}

Migración desde las colecciones viejas#

Colors Mode, Buttons y _Primitive quedan deprecadas: apuntan a la paleta anterior (escala 50–950) y no tienen dark real. No las uses en trabajo nuevo.