Automatic CSS Variable Scoping

Overview

Currently, CSS variables are treated just like any other property in blocks. This means that conflicting variable names are expected to be explicitly resolved by the developer, but we can do better than that!

Problem

CSS variable can be given special treatment in blocks. Consider two blocks a and b:

/* a.block.css */
:scope {
  --my-var: red;
}
.class {
  color: var(--my-var);
}

/* b.block.css */
:scope {
  --my-var: blue;
}
.class {
  color: var(--my-var);
}

If both blocks are applied to the same element, their --my-var definitions will conflict, causing unexpected behavior and requiring explicit resolution.

Now consider two blocks base and extended:

/* base.block.css */
:scope {
  --theme-color: red;
}
.class {
  color: var(--theme-color);
}

/* extended.block.css */
@block-reference base from "base.block.css";
:scope {
  extends: base;
  --theme-color: blue;
  --local-var: red;
}
.bar {
  color: var(--local-var);
}

Here, the exception is elements with block extended applied will use the re-defined --my-var class for all inherited styles.

Proposal

Compiled blocks should rewrite variable names to unique identifiers. This is easily done by prefixing all vars with their uid:

/* a.block.css */
.a {
  --a-my-var: red;
}
.a__class {
  color: var(--a-my-var);
}

/* b.block.css */
.b {
  --b-my-var: blue;
}
.b__class {
  color: var(--b-my-var);
}

In blocks that extend a base block, conflicting css var names should inherit the name of their base block, while locally defined names should be prefixed with the local uid. So our extended block example becomes:

/* base.block.css */
.base {
  --base-theme-color: red;
}
.base__class {
  color: var(--base-theme-color);
}

/* extended.block.css */
.extended {
  --base-theme-color: blue;
  --extended-local-var: red;
}
.extended__bar {
  color: var(--extended-local-var);
}

No files, tests, or entry points are named in the issue. Use the proposed block examples as acceptance criteria: standalone variables receive unique prefixes, while inherited variables retain the base block name and local variables use the extending block's identifier.