Design token fallbacks: make missing variables visible before release

A CSS fallback can make a missing token look acceptable while leaving the design mapping broken. Audit the token reference and the resolved property together, including the case where a defined variable contains a value invalid for that property.

Trace the semantic role before inspecting the color

Start with the component decision: the card surface should resolve to the design system’s surface role in the selected mode. Trace that role to its primitive and then to the emitted CSS custom property. Record the expected value without assuming white is correct for every theme. AptixLabs’ stylesheet contains named surface, ink and brand tokens; it does not establish a Figma synchronization pipeline. A copied hex value can match one screenshot while bypassing the role. A misspelled custom property can produce an equally plausible fallback and hide the same defect.

Current primary documentation

Distinguish absence from an invalid property value

MDN documents custom-property substitution and fallback behavior. A fallback inside var() is useful when the referenced custom property is unavailable or invalid as a custom property. It is not a universal validator for the receiving CSS property. If --invalid is defined as 16px and is substituted into background-color, the fallback color does not become the result merely because 16px is not a color. The declaration becomes invalid at computed-value time. Record that distinction explicitly so a team does not treat every rendered fallback as proof of a correct token graph.

Run the smallest browser comparison

An isolated Chromium fixture for this guide rendered three synthetic elements. The misspelled --surfac reference with a magenta fallback computed to rgb(255, 0, 255). The defined but wrong-type 16px value used for background-color computed to transparent. The valid --surface reference computed to rgb(255, 255, 255). Those are actual local fixture results, with the browser version retained in result.json. They demonstrate these declarations in one browser, not every cascade, registered-property configuration or supported device. No production stylesheet was changed by the exercise.

.card { background: var(--surfac, #ff00ff); }
.invalid { --invalid: 16px; background-color: var(--invalid, #ff00ff); }

Choose production and diagnostic fallbacks deliberately

An obvious diagnostic color can reveal an unmapped role during development, but it may be inappropriate for a public interface. A production fallback should be a conscious resilience decision with an accompanying check that detects missing references. Test representative hover, disabled and theme states, because inheritance and local overrides can make a token appear only in one branch. Inspect computed styles and the token definition rather than searching only for var() syntax. If @property registration is used, include its syntax, inheritance and initial value in the contract; it changes the cases the audit must cover.

Repair ownership rather than adding another fallback

The corrective record should name the misspelled reference, expected semantic role, affected mode and owning component. Fix the mapping at the appropriate layer and repeat the same browser comparison. Add a release check that can identify unresolved references without hardcoding every visual value into a second theme. Keep legitimate local exceptions documented. A successful default-state capture is incomplete if dark mode or a disabled control still resolves incorrectly. The handoff needs the corrected chain and residual browser coverage, so later maintainers can tell why a fallback exists and when it may be removed.

Figma variables to React design tokens

AI-generated UI quality checklist

Bring one unresolved token chain and its computed style to scope the mapping correction.

B2B SaaS development: scope and acceptance