The @property Rule for Typed Custom Properties

A Limitation of Ordinary Custom Properties

A regular custom property, as covered elsewhere in this section, is essentially just stored text - the browser does not know whether --my-color is meant to be a color, a number, or a length, which prevents it from being safely animated or transitioned in some cases.

What @property Adds

@property --highlight-color {
  syntax: '<color>';
  inherits: false;
  initial-value: #1d4ed8;
}

@property registers a custom property with an explicit type (syntax), whether it should inherit down to child elements, and a required fallback (initial-value) - turning a plain text variable into something the browser actually understands and validates.

Why This Enables Smooth Animation

.gradient-box {
  background: linear-gradient(to right, var(--highlight-color), white);
  transition: --highlight-color 0.3s ease;
}
.gradient-box:hover {
  --highlight-color: #dc2626;
}

Without registering --highlight-color as a <color> type, the browser cannot interpolate smoothly between two color values - it can only jump instantly between them. Once typed with @property, the color can transition through intermediate shades exactly like any other native color property.

Common syntax Type Values

Why This Matters for Design Systems

Typed custom properties bring CSS variables closer to how variables behave in a real programming language - validated, predictable, and safely animatable - which is especially valuable in larger design systems where many components share the same set of variables.