2026-09-02 · 8 min read
- css
- design-systems
- frontend
Custom properties preserve token sequences rather than typed values by default. A variable can be present and inherit correctly, yet make width, color, transform, or another consumer invalid after substitution.
Calculations add dimensional rules: addition and subtraction require compatible types, while multiplication and division support depends on the CSS feature and browser level. Percentages can also resolve against different containing blocks.
Define a token type strategy
Choose whether a design token stores a unitless scale value, a complete dimension, or an entire expression. Use names and documentation that make the choice visible to consumers.
- Use unitless values when consumers intentionally choose dimensions.
- Use complete lengths when the unit is part of the design contract.
- Avoid variables that alternate between numbers and lengths by theme.
- Consider registered custom properties when typing and animation matter.
Compose calculations safely
Format expressions so addition and subtraction have required whitespace. After substituting every var(), verify that operations combine compatible dimensions and that nested fallbacks produce valid tokens.
A syntactically valid expression can still fail at computed-value time or resolve unexpectedly because the percentage basis, font metrics, viewport, or container changed. Inspect the affected element rather than only the root token definition.
Trace cascade and fallback behavior
Custom properties inherit unless their registration says otherwise. Follow cascade layers, selector specificity, media and container conditions, shadow boundaries, and inline styles to find the value that actually reaches the consumer.
A var() fallback is used when the referenced custom property is missing or invalid for substitution, not whenever the final property value is inconvenient. Build fallbacks as complete valid token sequences.
- Test missing, initial, inherited, and explicitly empty values.
- Check nested fallback commas and function boundaries.
- Avoid using important flags as a substitute for tracing the cascade.
- Document the supported browser baseline for newer math functions.
Verify real layout conditions
Use Flashman's CSS formatter to inspect expressions, units converter for scale checks, color tool for calculated color contrast, diff to review token changes, and Markdown editor to document the design-token contract.
Test zero, negative and extreme values, mixed absolute and relative units, zoom, text scaling, mobile viewports, writing modes, containers, themes, forced colors, reduced motion, printing, and every supported browser.