[css-values-5]: Inline type assertion of custom properties (variables)

[brandonmcconnell]

Abstract

Currently, defining custom properties (variables) with specific types in CSS requires the use of @property rules. While effective, this approach requires separating the definition of variables from where they are used, even in simple cases. This can lead to scattered declarations and reduce the modularity of stylesheets.

Sometimes, this is necessary and even useful, but for simpler cases, it would be easier and preferable to type variables inline where they are used.

Motivation

A common scenario where this issue is evident is when animating gradients, where defining custom properties using @property is required to type the variables appropriately as lengths/percentages/etc.

/* Define the custom property with @property rule */
@property --gradient-pos {
  syntax: "<length-percentage>";
  inherits: false;
  initial-value: 0%;
}

.my-gradient {
  background: linear-gradient(90deg, red var(--gradient-pos), blue);
  animation: moveGradient 5s infinite alternate;
}

@keyframes moveGradient {
  to {
    --gradient-pos: 100%;
  }
}

To address this issue, I propose an inline type assertion syntax using angle brackets—common in other languages and already used for types in CSS—within the var() function. This would allow the type of a custom property to be specified directly where it is used, simplifying the syntax and improving modularity without needing to resort to @property for simpler cases.

This yields some benefits:

1. Simplicity: Reduces the need for boilerplate code and keeps stylesheets modular.
2. Maintainability: Keeps type information close to its usage, making stylesheets easier to manage and understand.
3. Consistency: Works well with existing CSS variable usage patterns, providing a natural extension to current practices.

Syntax: var<TYPE>(…)

The new syntax for inline type assertions within the var() function would be:

var<TYPE>(--custom-property, fallback-value)

Example:

.my-gradient {
  background: linear-gradient(90deg, red var<<length-percentage>>(--gradient-pos, 0%), blue);
  animation: moveGradient 5s infinite alternate;
}

@keyframes moveGradient {
  to {
    --gradient-pos: 100%;
  }
}

Alternative syntax: typed(TYPE, var(…))

An alternative syntax for inline type assertions could be to wrap var() in a separate typed function:

typed(TYPE, var(--custom-property, fallback-value))

Example:

.my-gradient {
  background: linear-gradient(90deg, red typed(<number>, var(--gradient-pos, 0%)), blue);
  animation: moveGradient 5s infinite alternate;
}

@keyframes moveGradient {
  to {
    --gradient-pos: 100%;
  }
}

Pro/con of this alternative syntax:

Pro	Con
No new general syntax: simpler functional syntax in line with general CSS	The first TYPE argument for typed(), by nature, would need to be explicit and static. Using something like typed(var(--my-desired-type), var(--my-var)) would not work, which could be confusing for users

Related issues

• [css-properties-values-api] Shorthand for custom property declaration #7523
  Similar goal of simplifying @property usage, but not a duplication or conflict with this issue