Migración de tokens legacy

LEGACY: usa este contrato con versiones desplegadas que todavía no admitan design.tokens. También puedes mantenerlo tras actualizar: el nuevo runtime conserva su compatibilidad indefinidamente.

El contrato de diseño anterior por categorías seguirá soportado indefinidamente hasta que se comunique a los consumidores una decisión explícita de retirada. La configuración nueva debe usar design.tokens; los grupos legacy son una entrada de compatibilidad, no opciones canónicas equivalentes.

Prioridad de resolución

Los valores se aplican en este orden:

Valores predeterminados de los tokens de dominio de Consents.
Overrides legacy resueltos por categoría.
Overrides canónicos de design.tokens.

Un override canónico prevalece sobre cualquier alias legacy que apunte al mismo token de dominio. Si el valor canónico es inválido, se descarta y se mantiene el valor legacy ya resuelto.

Los avisos legacy se emiten siempre con el prefijo [Consents Theme]. Se agrupan en un único mensaje de consola y se deduplican por código de diagnóstico y ruta de configuración; no dependen de un flag de entorno de producción.

Aliases escalares

Una clave legacy puede alimentar varios tokens de dominio. Al migrar, configura cada destino por separado cuando esos usos necesiten divergir.

Ruta legacy	Destino o destinos canónicos
`design.color.background-neutral-primary`	`component-background-color`
`design.color.background-surface-default`	`header-background-color`, `footer-background-color`, `parent-statement-background-color`, `language-selector-menu-background-color`, `dialog-background-color`
`design.color.background-button-default`	`footer-button-background-color`
`design.color.background-button-hover`	`footer-button-hover-background-color`
`design.color.background-button-pressed`	`footer-button-pressed-background-color`
`design.color.background-semantic-critical-primary`	`validation-alert-background-color`
`design.color.text-neutral-primary`	`title-color`, `description-color`, `language-selector-text-color`, `parent-statement-text-color`, `parent-statement-description-color`, `child-statement-text-color`, `child-statement-description-color`, `dialog-text-color`
`design.color.text-button-inverse`	`footer-button-text-color`
`design.color.text-semantic-critical-primary`	`validation-alert-text-color`
`design.color.icon-neutral-primary`	`collapse-button-icon-color`, `language-selector-icon-color`
`design.color.icon-neutral-secondary`	`statement-help-icon-color`, `checkbox-unchecked-icon-color`
`design.color.icon-button-primary`	`checkbox-checked-icon-color`
`design.color.icon-semantic-critical-primary`	`validation-alert-icon-color`
`design.color.border-neutral-primary`	`statement-card-border-color`
`design.color.border-neutral-secondary`	`container-border-color`, `statement-divider-color`
`design.spacing.spacing-global-padding-x`	`global-padding-x`
`design.spacing.spacing-global-padding-y`	`global-padding-y`
`design.spacing.spacing-section-gap`	`section-gap`, `info-message-padding-y`
`design.spacing.spacing-statement-vertical-gap`	`statement-description-gap`
`design.spacing.spacing-header-padding-x`	`header-padding-x`
`design.spacing.spacing-header-padding-top`	`header-padding-top`
`design.spacing.spacing-header-padding-bottom`	`header-padding-bottom`
`design.spacing.spacing-header-content-gap`	`header-content-gap`
`design.spacing.spacing-statement-parent-padding-x`	`parent-statement-padding-x`
`design.spacing.spacing-statement-parent-padding-y`	`parent-statement-padding-y`
`design.spacing.spacing-statement-parent-vertical-gap`	`parent-statement-description-gap`
`design.spacing.spacing-statement-child-padding-x`	`child-statement-padding-x`
`design.spacing.spacing-statement-child-padding-y`	`child-statement-padding-y`
`design.spacing.spacing-statement-child-vertical-gap`	`child-statement-description-gap`
`design.spacing.spacing-statement-child-indent`	`child-statement-indent`
`design.spacing.spacing-statement-box-gap`	`statement-list-gap`
`design.spacing.spacing-statement-box-padding-x`	`statement-list-padding-x`
`design.spacing.spacing-statement-help-icon-size`	`statement-help-icon-size`
`design.spacing.spacing-footer-padding-x`	`footer-padding-x`
`design.spacing.spacing-footer-padding-y`	`footer-padding-y`
`design.spacing.spacing-footer-section-gap`	`footer-section-gap`
`design.spacing.spacing-alert-padding-x`	`validation-alert-padding-x`
`design.spacing.spacing-alert-padding-y`	`validation-alert-padding-y`
`design.spacing.spacing-button-desktop-padding-x`	`footer-button-desktop-padding-x`
`design.spacing.spacing-button-padding-y`	`footer-button-padding-y`
`design.spacing.spacing-dialog-padding`	`dialog-padding`
`design.spacing.spacing-dialog-padding-x`	`dialog-padding-x`
`design.spacing.spacing-dialog-padding-y`	`dialog-padding-y`
`design.spacing.spacing-dialog-offset`	`dialog-popper-offset`
`design.spacing.spacing-language-selector-gap`	`language-selector-flag-label-gap`
`design.radius.radius-global`	`global-radius`
`design.radius.radius-button`	`footer-button-radius`
`design.radius.radius-statement-box`	`statement-card-radius`
`design.radius.radius-menu`	`language-selector-menu-radius`
`design.radius.radius-dialog`	`dialog-popper-radius`
`design.radius.radius-alert`	`validation-alert-radius`
`design.shadows.shadow-statement-box`	`statement-card-shadow`
`design.shadows.shadow-language-selector-menu`	`language-selector-menu-shadow`
`design.shadows.shadow-dialog`	`dialog-popper-shadow`
`design.border.border-statement-box`	`statement-card-border-width`
`design.border.border-container`	`container-border-width`

design.color.text-neutral-secondary sigue alimentando su uso interno anterior de MUI. No tiene fan-out canónico porque actualmente ningún uso público de dominio representa ese contenido.

Los tokens canónicos container-background-color y statement-card-background-color siguen siendo transparentes salvo que se configuren directamente. Los aliases legacy amplios de fondo no convierten estas nuevas superficies en opacas.

Aliases tipográficos

En cada grupo de la tabla, sustituye {property} por family, size, weight, lineheight o letterspacing.

Patrón de token legacy	Destino o destinos canónicos
`headings-h4-{property}`	`title-typography`
`headings-h6-{property}`	`info-message-typography`
`base-regular-{property}`	`language-selector-text-typography`, `parent-statement-description-typography`, `child-statement-description-typography`, `validation-alert-typography`
`base-medium-{property}`	`child-statement-text-typography`, `footer-button-typography`
`body-medium-{property}`	`parent-statement-text-typography`
`typography-base-family`	Todos los tokens de dominio tipográficos públicos

Los valores tipográficos legacy de primer nivel se aplican globalmente. design.typography.xs se mapea a mobile y design.typography.xl a desktop. Los demás bloques de breakpoint legacy no tienen efecto.

Las cinco propiedades antiguas se mantienen exclusivamente para los payloads legacy. Al migrar, selecciona un estilo semántico completo; la API canónica solo permite sobrescribir su familia:

json

{
  "design": {
    "tokens": {
      "title-typography": {
        "style": "h4",
        "family": "Inter",
        "desktop": {
          "style": "h3"
        },
        "mobile": {
          "style": "h5",
          "family": "Menlo"
        }
      }
    }
  }
}

Consulta Validaciones de tokens para ver los límites que siguen aplicándose a las propiedades tipográficas antiguas.

Claves deprecadas sin efecto

Estas claves públicas conocidas se mantienen para que los payloads existentes sigan aceptándose, pero no afectan al componente renderizado:

design.spacing.spacing-dialog-section-gap
design.spacing.spacing-dialog-header-gap

design.components, las categorías desconocidas, los nombres de token legacy desconocidos y los breakpoints tipográficos legacy no soportados tampoco tienen efecto. Generan un aviso deduplicado.

Procedimiento de migración

Carga el payload existente sin reescribirlo.
Añade las entradas correspondientes bajo design.tokens.
Compara el renderizado light/dark y desktop/mobile.
Elimina una clave legacy solo cuando estén representados todos sus destinos canónicos.

El editor de Integration Testing de Admin conserva los grupos legacy cargados, pero solo edita tokens de dominio canónicos. Usa su editor JSON para eliminar las claves legacy después de validar la migración.