Validaciones de tokens
Esta página describe el comportamiento actual de validación de overrides de tokens de diseño enviados mediante SET_CONFIG.
Cuándo se valida
La validación de tokens se ejecuta después de que el host envía SET_CONFIG y antes de que el componente construya el tema configurable.
El saneado cubre actualmente design.color, design.radius, design.spacing y design.typography.
design.shadows, design.border y design.components no pasan por estas reglas de validación semántica.
Los valores de shadows y border se resuelven mediante sus resolvers normales de runtime.
components está reservado y el runtime actual no lo consume.
Resultado de validación
| Severidad | Comportamiento en runtime |
|---|---|
error | El render continúa. El override inválido se descarta y se usa el valor semántico por defecto. |
warning | El render continúa. El override se mantiene y el warning se registra en consola. |
El saneador valida la configuración, elimina el primer override inválido que puede asociar a un token y vuelve a validar. Esto se repite hasta el número de overrides de diseño más una pasada adicional. La eliminación de overrides inválidos se intenta en este orden: color, radius, spacing, typography.
Validación de color
La validación de color usa el modo de tema activo en payload.theme.
Cuando theme se omite, se usa light.
Los valores de color pueden ser claves de primitivas de color o strings CSS de color válidos.
El contraste solo se comprueba en pares de tokens donde el token de primer plano o el token de fondo tiene un override. Si el validador no puede resolver un color o calcular su ratio de contraste, esa regla de contraste se omite. El resolver de runtime sigue avisando e ignorando valores de color inválidos.
| Par de tokens | Regla |
|---|---|
text-neutral-primary sobre background-neutral-primary | Texto normal |
text-neutral-primary sobre background-surface-default | Texto normal |
text-neutral-secondary sobre background-surface-default | Texto normal |
text-button-inverse sobre background-button-default | Texto normal |
text-button-inverse sobre background-button-hover | Texto normal |
text-button-inverse sobre background-button-pressed | Texto normal |
text-semantic-critical-primary sobre background-semantic-critical-primary | Texto normal |
icon-neutral-primary sobre background-surface-default | Componente UI |
icon-neutral-secondary sobre background-surface-default | Componente UI |
icon-semantic-critical-primary sobre background-semantic-critical-primary | Componente UI |
border-neutral-primary sobre background-surface-default | Componente UI |
border-neutral-secondary sobre background-surface-default | Componente UI |
| Tipo de regla | Umbral de error | Umbral de warning |
|---|---|---|
| Texto normal | Inferior a WCAG AA 4.5:1 | Cumple AA pero queda por debajo de AAA 7:1 |
| Componente UI | Inferior a WCAG AA 3:1 | Cumple AA pero queda por debajo de AAA 4.5:1 |
Los mismos pares de tokens también se comprueban para detectar colores de primer plano y fondo idénticos. Los colores resueltos idénticos se tratan como error.
Validación de radius
Los overrides de radius pueden ser números directos en píxeles o nombres de tokens primitivos de radius.
| Token | Límite |
|---|---|
radius-global | Máximo 32px (radius-4xl) |
radius-statement-box | Máximo 32px (radius-4xl) |
El resto de tokens de radius se resuelve en runtime, pero actualmente no tiene una regla de límite semántico.
Validación de spacing
Los overrides de spacing pueden ser números directos en píxeles o nombres de tokens primitivos de spacing.
| Token | Límite |
|---|---|
spacing-statement-help-icon-size | Mínimo 12px, máximo 40px y no mayor que el menor line height actual entre body-medium-lineheight y base-medium-lineheight |
spacing-dialog-padding-x | Mínimo 8px |
spacing-dialog-padding-y | Mínimo 8px |
El límite dinámico del icono de ayuda usa los overrides de tipografía cuando existen.
Con la tipografía por defecto, el máximo dinámico es 22px.
Esta validación de spacing no se evalúa por separado para xs y xl.
El validador actual usa overrides tipográficos de nivel superior cuando existen y, si no, cae a los defaults de tipografía XL; los bloques tipográficos específicos de breakpoint no cambian hoy este límite de spacing.
Validación de tipografía
Los overrides de tipografía se validan sobre los mapas efectivos xs y xl.
El runtime mezcla tokens por defecto, overrides tipográficos de nivel superior y overrides por breakpoint antes de validar.
Un override tipográfico de nivel superior se valida en ambos mapas efectivos.
Un override xs se valida solo en el mapa móvil, y un override xl se valida solo en el mapa escritorio/tablet.
| Grupo de tokens | Par validado |
|---|---|
headings-h4 | headings-h4-size / headings-h4-lineheight |
headings-h6 | headings-h6-size / headings-h6-lineheight |
base-regular | base-regular-size / base-regular-lineheight |
base-medium | base-medium-size / base-medium-lineheight |
body-medium | body-medium-size / body-medium-lineheight |
| Regla | Límite |
|---|---|
| Tamaño de fuente | Mínimo 14px, máximo 40px |
| Interlineado | Debe ser mayor o igual que el tamaño de fuente resuelto |
El mínimo y máximo de font size no cambia por breakpoint.
El mismo rango de 14px a 40px se aplica a los valores efectivos xs y xl.
Los bloques sm, md, lg y base están tipados, pero el resolver actual no los consume.
Es preferible usar valores de nivel superior junto con xs y xl.
Fallback del resolver
La validación no es el único mecanismo de fallback. Los resolvers de runtime también ignoran valores no soportados por categoría:
| Categoría | Valores aceptados |
|---|---|
color | Clave de primitiva de color o cadena CSS de color válida |
spacing | Clave de primitiva de spacing o número en píxeles |
radius | Clave de primitiva de radius o número en píxeles |
typography | Clave de primitiva tipográfica |
shadows | Clave de primitiva de shadow o cadena CSS de sombra |
border | Clave de primitiva de stroke o número en píxeles |
Los valores inválidos para el resolver se ignoran y se registran en consola; el valor semántico por defecto sigue aplicándose.