feat: track CSS custom properties on CSSSourceCode by Copilot · Pull Request #411 · eslint/css

Copilot · 2026-03-27T20:43:05Z

Implements the CSS variable tracking RFC, centralizing custom property tracking on CSSSourceCode so rules don't duplicate this logic. Also fixes variable hoisting — var() references before their declaration now resolve correctly.

`CSSSourceCode` — new API

Three new public methods backed by private #customProperties Map and #declarationVariables WeakMap, populated during traverse():

getDeclarationVariables(declaration) — returns var() function nodes used in a declaration's value, including nested var() in fallback positions (e.g., var(--a, var(--b)))
getClosestVariableValue(func) — returns the closest value for a var() node. Resolution priority per RFC: same-block declaration → fallback → other-block declarations (hoisted) → @property initial-value → undefined
getVariableValues(func) — returns all known values: @property initial-value, then declarations in source order, then fallback

Nested var() calls in fallback positions are handled by #extractNestedVarRefs, which re-parses Raw fallback text nodes (the CSS parser represents fallbacks as raw text) and tracks any nested var() references with correctly adjusted source locations.

// Rule usage example
const closestValue = sourceCode.getClosestVariableValue(varFuncNode);
const allValues = sourceCode.getVariableValues(varFuncNode);
const varsInDecl = sourceCode.getDeclarationVariables(declNode);

`no-invalid-properties` — refactored to use new API

Uses getClosestVariableValue() for primary resolution instead of maintaining its own variable map
Populates internal vars map incrementally via rule visitor methods; hoisting is handled by getClosestVariableValue() which has access to all declarations collected during CSSSourceCode.traverse()
Falls back to direct chain resolution when closest value contains unresolvable nested var() refs
3 test cases move from invalid → valid: when a var() has a valid fallback, the fallback is now preferred over an invalid value from another selector block

Tests

21 tests covering all three CSSSourceCode methods (same-block, fallback priority, hoisting, @property, multiple declarations, cross-declaration isolation, nested var() in fallback positions including deep nesting)
2 hoisting tests for no-invalid-properties

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

eslint-github-bot · 2026-03-27T20:43:12Z

Hi @copilot!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
There should be a space following the initial tag and colon, for example 'feat: Message'.
The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

eslint-github-bot · 2026-03-27T20:45:32Z

Hi @copilot!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
There should be a space following the initial tag and colon, for example 'feat: Message'.
The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

…no-invalid-properties Implements the RFC for CSS custom property tracking on CSSSourceCode: - Add #customProperties map and #declarationVariables WeakMap - Populate during traverse() to track declarations, @Property definitions, and var() references - Add getDeclarationVariables(declaration) method - Add getClosestVariableValue(func) method - Add getVariableValues(func) method Refactor no-invalid-properties rule to use the new API: - Use getClosestVariableValue() for primary variable resolution - Pre-populate vars map from AST to support variable hoisting (fixes #199) - Fallback values take priority over other-block declarations per RFC Add comprehensive tests for all new CSSSourceCode methods. Agent-Logs-Url: https://github.com/eslint/css/sessions/e41fbbf4-0081-469f-8248-1e854213b08c Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

eslint-github-bot · 2026-03-27T21:04:17Z

Hi @copilot!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
There should be a space following the initial tag and colon, for example 'feat: Message'.
The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

eslint-github-bot · 2026-03-27T21:04:20Z

Hi @copilot!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
There should be a space following the initial tag and colon, for example 'feat: Message'.
The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

eslint-github-bot · 2026-03-27T21:06:29Z

Hi @copilot!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
There should be a space following the initial tag and colon, for example 'feat: Message'.
The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

nzakas · 2026-03-30T20:24:51Z

src/rules/no-invalid-properties.js

+ * @param {Function} visitor The visitor function to call for each node.
+ * @returns {void}
+ */
+function walkAST(node, visitor) {


@copilot the rule itself is doing a depth-first traversal of the AST. Doing it again is inefficient. Remove the extra traversal and use the rule methods to do any traversing that is necessary.

Removed the walkAST function and StyleSheet() visitor. The vars map is now populated incrementally in "Rule > Block Declaration:exit" as the rule traverses. Hoisting is handled by sourceCode.getClosestVariableValue() which has access to all declarations collected during CSSSourceCode.traverse(). Commit: 63d930c

…le visitor methods instead Agent-Logs-Url: https://github.com/eslint/css/sessions/fa674c27-bfb3-46b4-8c86-407a2fef55c5 Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

nzakas

LGTM. Would like a second review before merging.

nzakas · 2026-04-01T21:08:26Z

@copilot run ESLint and prettier and fix any problems so the CI passes.

Agent-Logs-Url: https://github.com/eslint/css/sessions/067a08d1-cf1f-4d0b-ac09-9abe4691f119 Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

Copilot · 2026-04-01T21:11:36Z

@copilot run ESLint and prettier and fix any problems so the CI passes.

Fixed in 735ebbe. Ran both ESLint (clean) and Prettier (3 files had formatting issues in css-source-code.js, no-invalid-properties.js, and css-source-code.test.js). All 1021 tests still pass.

lumirlumir · 2026-04-06T11:14:29Z

tests/languages/css-source-code.test.js

+		/**
+		 * Helper to create a CSSSourceCode from CSS text and trigger traversal.
+		 * @param {string} css The CSS text.
+		 * @returns {import("../../src/languages/css-source-code.js").CSSSourceCode} The source code instance.
+		 */
+		function createSourceCode(css) {
+			const sourceCode = new CSSSourceCode({
+				text: css,
+				ast: toPlainObject(parse(css, { positions: true })),
+			});
+
+			// trigger traversal to populate custom properties data
+			sourceCode.traverse();
+			return sourceCode;
+		}


I think it would be clearer to move this helper to the top level, since the same test helper is repeated three times across the newly added describe test blocks.

Moved both createSourceCode and findVarFunc to the top level, shared across all three describe blocks. Commit: 051fea2

lumirlumir · 2026-04-06T11:49:13Z

src/languages/css-source-code.js

+			}
+
+			// Track var() references
+			if (


Should this also handle nested var() calls in fallback positions, such as var(--a, var(--b))?

It seems that no-invalid-properties already has custom logic for resolving nested fallback var() references. If this RFC is meant to centralize that behavior in CSSSourceCode, I think this case need to be covered as well. Otherwise, rules may still need their own fallback parsing logic.

Just for reference, according to MDN, the following syntax is valid:

https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/var#syntax

var(--custom-prop, var(--default-value)); var(--custom-prop, var(--default-value, red));

When I tested it against a nested var() function, it failed:

it("should return nested var() function nodes", () => { const css = "a { color: var(--my-color-1, var(--my-color-2)); }"; const sourceCode = createSourceCode(css); const decl = sourceCode.ast.children[0].block.children[0]; const vars = sourceCode.getDeclarationVariables(decl); console.log(decl.value.children[0]); console.log(vars); assert.strictEqual(vars.length, 2); assert.strictEqual(vars[0].children[0].name, "--my-color-1"); assert.strictEqual(vars[1].children[0].name, "--my-color-2"); });

The stdout is logged as follows:

{ type: 'Function', loc: { source: '<unknown>', start: { offset: 11, line: 1, column: 12 }, end: { offset: 47, line: 1, column: 48 } }, name: 'var', children: [ { type: 'Identifier', loc: [Object], name: '--my-color-1' }, { type: 'Operator', loc: [Object], value: ',' }, { type: 'Raw', loc: [Object], value: ' var(--my-color-2)' } ] } [ { type: 'Function', loc: { source: '<unknown>', start: [Object], end: [Object] }, name: 'var', children: [ [Object], [Object], [Object] ] } ]

Added #extractNestedVarRefs private method that re-parses Raw fallback text using the CSS parser and tracks any nested var() references found. It handles arbitrary nesting depth by recursing. Location info is adjusted to map back to the original source positions via adjustLoc/adjustAllLocs helpers. Two new tests cover single-level and 3-level deep nesting. Commit: 051fea2

nzakas · 2026-04-08T20:06:08Z

@copilot Address @lumirlumir's feedback.

Agent-Logs-Url: https://github.com/eslint/css/sessions/c7fb3f76-2d5b-4f30-bbcb-051fb15694b7 Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

Copilot · 2026-04-08T20:20:18Z

@copilot Address @lumirlumir's feedback.

Both items addressed in 051fea2 — test helpers moved to top level, and nested var() in fallback positions now tracked via #extractNestedVarRefs.

Initial plan

4266600

Copilot AI assigned Copilot and nzakas Mar 27, 2026

github-project-automation bot added this to Triage Mar 27, 2026

github-project-automation bot moved this to Needs Triage in Triage Mar 27, 2026

Copilot started work on behalf of nzakas March 27, 2026 20:43 View session

Copilot AI linked an issue Mar 27, 2026 that may be closed by this pull request

Change Request: Track variables on SourceCode #160

Open

1 task

Copilot AI changed the title ~~[WIP] Add tracking for CSS custom properties in SourceCode~~ feat: track CSS custom properties on CSSSourceCode Mar 27, 2026

eslint-github-bot bot added the feature label Mar 27, 2026

Copilot finished work on behalf of nzakas March 27, 2026 21:06

Copilot AI requested a review from nzakas March 27, 2026 21:07

nzakas reviewed Mar 30, 2026

View reviewed changes

Copilot started work on behalf of nzakas March 30, 2026 20:26 View session

nzakas mentioned this pull request Mar 30, 2026

feat: add CSS custom property tracking to CSSSourceCode #377

Closed

refactor: remove extra AST traversal in no-invalid-properties, use ru…

63d930c

…le visitor methods instead Agent-Logs-Url: https://github.com/eslint/css/sessions/fa674c27-bfb3-46b4-8c86-407a2fef55c5 Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

Copilot finished work on behalf of nzakas March 30, 2026 20:31

Copilot AI requested a review from nzakas March 30, 2026 20:31

nzakas approved these changes Apr 1, 2026

View reviewed changes

nzakas marked this pull request as ready for review April 1, 2026 21:08

Copilot started work on behalf of nzakas April 1, 2026 21:08 View session

nzakas moved this from Needs Triage to Second Review Needed in Triage Apr 1, 2026

fix: apply Prettier formatting to resolve CI failures

735ebbe

Agent-Logs-Url: https://github.com/eslint/css/sessions/067a08d1-cf1f-4d0b-ac09-9abe4691f119 Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

Copilot finished work on behalf of nzakas April 1, 2026 21:12

Copilot AI requested a review from nzakas April 1, 2026 21:12

lumirlumir added the accepted There is consensus among the team that this change meets the criteria for inclusion label Apr 2, 2026

lumirlumir requested changes Apr 6, 2026

View reviewed changes

Copilot started work on behalf of nzakas April 8, 2026 20:06 View session

fix: handle nested var() in fallback, move test helpers to top level

051fea2

Agent-Logs-Url: https://github.com/eslint/css/sessions/c7fb3f76-2d5b-4f30-bbcb-051fb15694b7 Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

Copilot finished work on behalf of nzakas April 8, 2026 20:22

Uh oh!

Conversation

Copilot AI commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CSSSourceCode — new API

no-invalid-properties — refactored to use new API

Tests

Uh oh!

eslint-github-bot bot commented Mar 27, 2026

Uh oh!

eslint-github-bot bot commented Mar 27, 2026

Uh oh!

eslint-github-bot bot commented Mar 27, 2026

Uh oh!

eslint-github-bot bot commented Mar 27, 2026

Uh oh!

eslint-github-bot bot commented Mar 27, 2026

Uh oh!

nzakas Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

nzakas left a comment

Choose a reason for hiding this comment

Uh oh!

nzakas commented Apr 1, 2026

Uh oh!

Copilot AI commented Apr 1, 2026

Uh oh!

lumirlumir Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

lumirlumir Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

nzakas commented Apr 8, 2026

Uh oh!

Copilot AI commented Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 27, 2026 •

edited

Loading

`CSSSourceCode` — new API

`no-invalid-properties` — refactored to use new API