Legacy token migration

LEGACY: use this contract with deployed versions that do not yet support design.tokens. You may also keep it after upgrading: the new runtime retains compatibility indefinitely.

The category-based design contract remains supported indefinitely until an explicit removal decision is communicated to consumers. New configuration must use design.tokens; the legacy groups are compatibility input, not equivalent canonical options.

Resolution priority

Values are applied in this order:

Consents domain token defaults.
Resolved legacy category overrides.
Canonical design.tokens overrides.

A canonical override therefore wins over every legacy alias that targets the same domain token. If the canonical value is invalid, it is discarded and the already resolved legacy value remains.

Legacy warnings are always emitted with the [Consents Theme] prefix. They are grouped in one console message and deduplicated by diagnostic code and configuration path; no production environment flag is required.

Scalar aliases

One legacy key can feed several domain tokens. Migrate each target separately when those usages need to diverge.

Legacy path	Canonical target or targets
`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 still feeds its previous internal MUI usage. It has no canonical fan-out because no public domain use currently represents that content.

The canonical container-background-color and statement-card-background-color remain transparent unless configured directly. The broad legacy background aliases do not make these new surfaces opaque.

Typography aliases

For each group below, replace {property} with family, size, weight, lineheight or letterspacing.

Legacy token pattern	Canonical target or targets
`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`	Every public typography domain token

Top-level legacy typography values apply globally. design.typography.xs maps to mobile and design.typography.xl maps to desktop. Other legacy breakpoint blocks have no effect.

The five former properties remain available only to legacy payloads. When migrating, select a complete semantic style; the canonical API only allows its family to be overridden:

json

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

See Token validations for the limits that still apply to the former typography properties.

Deprecated keys without effect

These known public keys are retained so existing payloads remain accepted, but they do not affect the rendered component:

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

design.components, unknown category keys, unknown legacy token names and unsupported legacy typography breakpoints also have no effect. They produce a deduplicated warning.

Migration procedure

Load the existing payload without rewriting it.
Add the corresponding entries under design.tokens.
Compare light/dark and desktop/mobile rendering.
Remove a legacy key only after all of its canonical targets are represented.

The Admin Integration Testing editor preserves loaded legacy groups but edits only canonical domain tokens. Use its JSON editor to remove legacy keys after validating the migration.