Are CSS Custom Properties Global Across Linked CSS Documents

Are CSS Custom Properties global across linked CSS documents?

In MDN:

Custom properties participate in the cascade: each of them can appear
several times, and the value of the variable will match the value
defined in the custom property decided by the cascading algorithm.

It works just like any other CSS properties. It should be declared in the ancestor of the target element. So usually it would be declared to the top-level element html or root:.

It does not matter whether CSS custom properties are declared in an external CSS file or the same file.

The following is a sample using two external CSS files. It works on Firefox, Safari and Chrome.

https://thatseeyou.github.io/css3-examples/basics/customproperty.html

variables.css :

:root {
    --red: #f00;
    --green: #0f0;
    --blue: #00f;
}

style.css :

.red {
    background-color: var(--red);
}
.green {
    background-color: var(--green);
}
.blue {
    background-color: var(--blue);
}

HTML :

<!DOCTYPE html>
<html lang="en">
    <head>
        <link href="customproperty/variables.css" rel="stylesheet">
        <link href="customproperty/style.css" rel="stylesheet">
        <style>
            .module {
                --red: #800;
                --green: #080;
                --blue: #008;
            }
        </style>
    </head>
    <body>
        <div class="red">red</div>
        <div class="green">green</div>
        <div class="blue">blue</div>
        <div class="module">
            <div class="red">red in module</div>
            <div class="green">green in module</div>
            <div class="blue">blue in module</div>
        <div>
    </body>
</html>

Is there a difference between CSS custom properties and CSS variables?

A CSS Custom Property is the same thing as a CSS Variable. But that seems to come of some clumsy naming.

They weren't wrong to title the page: Using CSS custom properties (variables)

However a CSS Variable is not a variable in the traditional sense, as there is no way to define it so that it is globally scoped like in a programming language, or CSS Preprocessor (LESS/Sass).

Even a root scoped custom property/variable is not global. Changing the value of a property in a child will not change the value above or for siblings of that scope. If someone is expecting to be global, it may cause confusion and I suspect that's what Mozilla's writers are trying to point out.

if you look at

w3.org's CSS Custom Properties for Cascading Variables

This module introduces a family of custom author-defined properties known collectively as custom properties

Custom properties are definitions that can be referenced using var(--my-custom-prop). Like a variable!

quote continued...

as one only has to change the value once, in the custom property, and the change will propagate to all uses of that variable automatically.

Awkward... The above statement is not true exactly. It seems Mozilla Developer Network documentation is trying clarify that idea so that it's less confusing. Repeating the original quote:

Keep in mind that these are custom properties, not actual CSS variables. The value is computed where it is needed, not stored for use in other rules. For instance, you cannot set a property for an element and expect to retrieve it in a sibling's descendant's rule. The property is only set for the matching selector and its descendants, like any normal CSS.

They're pointing out it's not a variable in the traditional sense of a programming language. But that it is computed just like styles, adhering to the general cascade/scoping rules of CSS.

Thus var(--my-custom-prop) could resolve to very different things based on where it is declared, and that declarations don't propagate out to a higher scope.

Here's a codepen to mess around with if you'd like to try it out.

So think of CSS Custom Property the same as CSS Variable but be sure to remember that values cascade, and there's no global scope.

HTML/CSS - Keep Variable Across Multiple Stylesheets

It should not matter if the CSS custom properties are declared in an external CSS file or the same file. e.g.

global.css

:root {
--text-primary: #b6b6b6;
--text-secondary: #5f5f5f;
--bg-primary: #23232e;
--bg-secondary: #141418;
}

style.css

.primary {
    color: var(--text-primary);
}
.secondary {
    color: var(--text-secondary);
}
.bg-primary {
    background-color: var(--bg-primary);
}
.bg-secondary {
    background-color: var(--bg-secondary);
}

test.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <link href="global.css" rel="stylesheet">
        <link href="style.css" rel="stylesheet">
    </head>
    <body>
        <div class="primary">foo</div>
        <div class="secondary">bar</div>
        <div class="bg-primary">baz</div>
        <div class="bg-secondary">bat</div>
    </body>
</html>

result:

result of the above code example

So it has to be to do with either the order you are importing your css - or else something else to do with how your page is set-up.

So to answer you question: Is there a way to do this?
Yes - that is how they work out of the box.

As an aside you can also access/set your custom properties via javascript. e.g.

getComputedStyle(element).getPropertyValue("--text-primary");
element.style.setProperty("--text-primary", "#f0f0f0");

Accessing a CSS custom property (aka CSS variable) through JavaScript

You can use document.body.style.setProperty('--name', value);:

var bodyStyles = window.getComputedStyle(document.body);
var fooBar = bodyStyles.getPropertyValue('--foo-bar'); //get

document.body.style.setProperty('--foo-bar', newValue);//set

Is there a way to type check CSS custom properties (aka CSS variables)?

Using the new @property rule you can almost have what you want since it will allow to define the type for your variables.

Example:

@property --primary-color {
  syntax: '<color>';
  inherits: false;
  initial-value: blue;
}

.box {
  --primary-color: red; /* this one is valid */
  background:var(--primary-color);
  height:100px;
}

.box-alt {
  --primary-color:10px; /* this one is invalid and will fall to the intial-value */
  background:var(--primary-color);
  border:var(--primary-color) solid green; /* it won't be used here even if contain pixel */
  height:100px;
}

<div class="box"></div>

<div class="box-alt"></div>

using css custom properties variables not working

You did everything right, just keep the variables in (put variable here)

element {
  --main-bg-color: brown;
}
body {
  background-color: var(--main-bg-color);
}

Are CSS Custom Properties Global Across Linked CSS Documents