Token validations
This page describes the current validation behavior for SET_CONFIG design token overrides.
When validation runs
Token validation runs after the host sends SET_CONFIG and before the component builds the configurable theme.
The sanitizer currently covers design.color, design.radius, design.spacing and design.typography.
design.shadows, design.border and design.components are not sanitized by these semantic validation rules.
Shadows and border values are resolved by their normal runtime resolvers.
components is reserved and is not consumed by the current runtime.
Validation result
| Severity | Runtime behavior |
|---|---|
error | Rendering continues. The invalid override is discarded and the default semantic value is used. |
warning | Rendering continues. The override is kept and the warning is logged. |
The sanitizer validates the config, removes the first invalid override it can map to a token, and validates again. This repeats up to the number of design overrides plus one pass. Invalid override removal is attempted in this order: color, radius, spacing, typography.
Color validation
Color validation uses the active theme mode from payload.theme.
When theme is omitted, light is used.
Color values can be primitive color keys or valid CSS color strings.
Contrast is checked only for token pairs where the foreground or background token has an override. If the validator cannot resolve a color or compute its contrast ratio, that contrast rule is skipped. The runtime resolver still warns and ignores invalid color values.
| Token pair | Rule |
|---|---|
text-neutral-primary on background-neutral-primary | Normal text |
text-neutral-primary on background-surface-default | Normal text |
text-neutral-secondary on background-surface-default | Normal text |
text-button-inverse on background-button-default | Normal text |
text-button-inverse on background-button-hover | Normal text |
text-button-inverse on background-button-pressed | Normal text |
text-semantic-critical-primary on background-semantic-critical-primary | Normal text |
icon-neutral-primary on background-surface-default | UI component |
icon-neutral-secondary on background-surface-default | UI component |
icon-semantic-critical-primary on background-semantic-critical-primary | UI component |
border-neutral-primary on background-surface-default | UI component |
border-neutral-secondary on background-surface-default | UI component |
| Rule type | Error threshold | Warning threshold |
|---|---|---|
| Normal text | Below WCAG AA 4.5:1 | Meets AA but is below AAA 7:1 |
| UI component | Below WCAG AA 3:1 | Meets AA but is below AAA 4.5:1 |
The same token pairs are also checked for identical foreground and background colors. Identical resolved colors are treated as an error.
Radius validation
Radius overrides can be direct numbers in pixels or radius primitive token names.
| Token | Limit |
|---|---|
radius-global | Maximum 32px (radius-4xl) |
radius-statement-box | Maximum 32px (radius-4xl) |
Other radius tokens are resolved by the runtime but do not currently have a semantic limit rule.
Spacing validation
Spacing overrides can be direct numbers in pixels or spacing primitive token names.
| Token | Limit |
|---|---|
spacing-statement-help-icon-size | Minimum 12px, maximum 40px, and not greater than the smallest current line height between body-medium-lineheight and base-medium-lineheight |
spacing-dialog-padding-x | Minimum 8px |
spacing-dialog-padding-y | Minimum 8px |
The help icon size dynamic limit uses typography overrides when present.
With default typography, the dynamic maximum is 22px.
This spacing validation is not evaluated separately for xs and xl.
The current validator uses top-level typography overrides when present and otherwise falls back to the XL typography defaults; breakpoint-specific typography blocks do not change this spacing limit today.
Typography validation
Typography overrides are validated on the effective xs and xl maps.
The runtime merges default tokens, top-level typography overrides and breakpoint overrides before validating.
A top-level typography override is validated in both effective maps.
An xs override is validated only in the mobile map, and an xl override is validated only in the desktop/tablet map.
| Token group | Validated pair |
|---|---|
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 |
| Rule | Limit |
|---|---|
| Font size | Minimum 14px, maximum 40px |
| Line height | Must be greater than or equal to the resolved font size |
The font-size minimum and maximum do not change by breakpoint.
The same 14px to 40px range is applied to the effective xs and xl values.
sm, md, lg and base blocks are typed but are not consumed by the current resolver path.
Prefer top-level values plus xs and xl.
Resolver fallback
Validation is not the only fallback path. The runtime resolvers also ignore unsupported values by category:
| Category | Accepted values |
|---|---|
color | Color primitive key or valid CSS color string |
spacing | Spacing primitive key or number in pixels |
radius | Radius primitive key or number in pixels |
typography | Typography primitive key |
shadows | Shadow primitive key or raw CSS shadow string |
border | Stroke primitive key or number in pixels |
Invalid resolver values are ignored and logged; the default semantic token value remains in use.