Custom Properties

While CSS Variables currently provide a way to define user-controlled properties, they have limited usefulness outside reuse through a var() reference and cannot be more strictly defined. CSS Properties & Values API Level 1, aka Custom Properties, extend CSS Variables to allow us to register properties and define their type, initial value, and determine inheritance. This gives a great deal of power and flexibility

.thing {
  --my-color: green;
  --my-color: url('not-a-color'); // It's just a variable! It doesn't know any better
  color: var(--my-color); // This is now sad!
}

window.CSS.registerProperty({
  name: '--my-color',
  syntax: '<color>', // Now it's def a color. That `url` junk is skipped!
});

Anatomy of a Registered Custom Property

 // From https://drafts.css-houdini.org/css-properties-values-api/ June 7, 2018

CSS.registerProperty({
  name: '--foo', // String, name of the custom property
  syntax: '<color>', // String, how to parse this property. Defaults to *
  inherits: false, // Boolean, if true should inherit down the DOM tree
  initialValue: 'black', // String, initial value of this property
});

There are a number of supported syntaxes from the CSS Values and Units spec that can be used when registering a Custom Property:

<length>

Any valid length value

<number>

Any valid number value

<percentage>

Any valid percentage value

<length-percentage>

Any valid length or percentage value, or any calc expression combining length and percentage components

<color>

Any valid color value

<image>

Any Any valid image value

<url>

Any valid url value

<integer>

Any valid integer value

<angle>

Any valid angle value

<time>

Any valid time value

<resolution>

Any valid resolution value

<transform-list>

Any valid transform function value

<custom-ident>

Any valid ident value

You can also use + to allow for a space-separarted list of one or more items of that syntax, and separate syntaxes with | to allow one syntax or another