From d579076b2aea79e718fbb24845eabc62619d2543 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 24 Jun 2025 14:10:36 -0400 Subject: [PATCH 01/12] feat: CSS variable tracking --- designs/2025-css-vars-tracking/README.md | 93 ++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 designs/2025-css-vars-tracking/README.md diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md new file mode 100644 index 00000000..e9dff6c4 --- /dev/null +++ b/designs/2025-css-vars-tracking/README.md @@ -0,0 +1,93 @@ +- Repo: eslint/css +- Start Date: 2025-06-24 +- RFC PR: +- Authors: Nicholas C. Zakas + +# CSS Custom Property Tracking in SourceCode + +## Summary + +This RFC proposes to add capabilities to `CSSSourceCode` to track CSS custom properties (also known as CSS variables). This includes identifying where custom properties are defined and where they are used, as well as providing a way to retrieve the value of a custom property at a specific location in the code. + +## Motivation + +CSS custom properties are a foundational part of modern CSS development. They allow for more modular and maintainable stylesheets. For a CSS linter to provide accurate and helpful rules, it needs to be able to understand how custom properties are being used. Currently, any rule that needs to validate property values must implement its own logic for tracking custom properties, leading to duplicated effort and potential inconsistencies. + +By building this functionality directly into `CSSSourceCode`, we can provide a consistent and reliable way for all rules to access information about custom properties. Uses of this information include: + +* `no-invalid-properties` rule +* `font-family-fallbacks` rule +* Detecting references to undefined custom properties. +* Future: Detecting unused custom properties. + +This change is based on the discussion in [eslint/css#160](https://github.com/eslint/css/issues/160). + +## Detailed Design + +The proposed changes are implemented in the [`CSSSourceCode`](https://github.com/eslint/css/blob/main/src/languages/css-source-code.js) class. + +### `customProperties` Map + +A new public property, `customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have two properties: + +* `declarations`: An array of `Declaration` nodes where the custom property is defined. +* `references`: An array of `Function` nodes (specifically `var()` functions) where the custom property is used. + +### `getDeclarationVariables()` Method + +A new public method, `getDeclarationVariables(declaration)`, will be added to `CSSSourceCode`. This method will take a `Declaration` node as an argument and return an array of `Function` nodes representing the `var()` functions used in that declaration's value. + +### `getVariableValue()` Method + +A new public method, `getVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by searching for the last declaration of the custom property that appears before the given `Function` node in the source code. This also leaves open the possibility that we could change how this value is calculated to be more accurate in the future. + +### Initialization + +The `traverse()` method in `CSSSourceCode` will be updated to populate the `customProperties` map and the internal data structure used by `getDeclarationVariables()`. During traversal, it will identify `Declaration` nodes that define custom properties and `Function` nodes that are `var()` calls. + +## Documentation + +Because we don't provide documentation for `CSSSourceCode`, we will rely primarily on TypeScript types to inform rule developers as to these new class members. + +## Drawbacks + +The primary drawback of this approach is that it only tracks custom properties within a single file. It cannot resolve custom properties that are defined in other files or via mechanisms like inline styles on HTML elements. For the initial implementation, this is considered an acceptable tradeoff. + +## Backwards Compatibility Analysis + +This is a new feature and does not change any existing APIs. It is fully backwards compatible. + +## Alternatives + +The primary alternative is to have each rule implement its own custom property tracking logic. This is the current state of affairs and is what this RFC aims to improve upon. A centralized approach is more efficient and less error-prone. + +## Open Questions + +**Should we expose `customProperties` publicly?** + +It's unclear if this is useful to rules directly. The primary use case for this data is through the provided methods (`getDeclarationVariables()` and `getVariableValue()`), which offer a more controlled and convenient interface. + +So far, we don't have any use cases for rules accessing `customProperties` directly, so perhaps it's better to keep it private until we have a use case it solves? + +**Should we use "var" instead of "variable" in function names?** + +The proposed API includes methods like `getDeclarationVariables()` and `getVariableValue()`. Since CSS custom properties are commonly referred to as "CSS variables" in the community, there's a question about whether the method names should use the shorter "var" terminology instead. For example: + +- `getDeclarationVars()` instead of `getDeclarationVariables()` +- `getVarValue()` instead of `getVariableValue()` + +Using "var" would be more concise and align with the CSS `var()` function syntax that developers are already familiar with. However, "variable" is more explicit and follows common naming conventions in programming APIs. + +## Help Needed + +No help is needed to implement this RFC. + +## Frequently Asked Questions + +**Why does `getVariableValue()` return a `Raw` instead of a string?** + +The `getVariableValue()` method returns a `Raw` node instead of a string to preserve the original source information and maintain consistency with the AST structure. A `Raw` node contains not only the text value but also the location, which is valuable for rules that need to report issues or apply fixes at specific locations in the source code. Additionally, returning the actual AST node allows for future extensibility. If we later need to return more complex computed values or support different node types, the API won't need to change. + +## Related Discussions + +- [Change Request: Track variables on SourceCode #160](https.github.com/eslint/css/issues/160) From e2810f76712f208cb68aaa6bdaf163cef8e9b67b Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Wed, 25 Jun 2025 11:02:49 -0400 Subject: [PATCH 02/12] Add TypeScript types to clarify new features --- designs/2025-css-vars-tracking/README.md | 27 +++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index e9dff6c4..bb82a549 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -22,12 +22,25 @@ By building this functionality directly into `CSSSourceCode`, we can provide a c This change is based on the discussion in [eslint/css#160](https://github.com/eslint/css/issues/160). +**Note:** The logic described in this RFC is already implemented in the [`no-invalid-properties`](https://github.com/eslint/css/blob/main/docs/rules/no-invalid-properties.md) rule. This proposal wants to standardize the logic and make it available to all rules. + ## Detailed Design The proposed changes are implemented in the [`CSSSourceCode`](https://github.com/eslint/css/blob/main/src/languages/css-source-code.js) class. ### `customProperties` Map +```ts +interface CustomPropertyUses { + declarations: Array; + references: Array; +} + +interface CSSSourceCode { + customProperties: Map +} +``` + A new public property, `customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have two properties: * `declarations`: An array of `Declaration` nodes where the custom property is defined. @@ -35,15 +48,27 @@ A new public property, `customProperties`, will be added to `CSSSourceCode`. Thi ### `getDeclarationVariables()` Method +```ts +interface CSSSourceCode { + getDeclarationVariables(declaration: DeclarationPlain): Array; +} +``` + A new public method, `getDeclarationVariables(declaration)`, will be added to `CSSSourceCode`. This method will take a `Declaration` node as an argument and return an array of `Function` nodes representing the `var()` functions used in that declaration's value. ### `getVariableValue()` Method +```ts +interface CSSSourceCode { + getVariableValue(func: FunctionNode): Raw; +} +``` + A new public method, `getVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by searching for the last declaration of the custom property that appears before the given `Function` node in the source code. This also leaves open the possibility that we could change how this value is calculated to be more accurate in the future. ### Initialization -The `traverse()` method in `CSSSourceCode` will be updated to populate the `customProperties` map and the internal data structure used by `getDeclarationVariables()`. During traversal, it will identify `Declaration` nodes that define custom properties and `Function` nodes that are `var()` calls. +The `traverse()` method in `CSSSourceCode` will be updated to populate the `customProperties` map and the internal data structure (`WeakMap>`) used by `getDeclarationVariables()`. During traversal, it will identify `Declaration` nodes that define custom properties and `Function` nodes that are `var()` calls. ## Documentation From b12f7f072aa0048395877ad21cb34684bfab4980 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Wed, 9 Jul 2025 11:46:57 -0400 Subject: [PATCH 03/12] Add @property, switch customProperties to private --- designs/2025-css-vars-tracking/README.md | 38 +++++++++++++++--------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index bb82a549..63bc5277 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -33,18 +33,20 @@ The proposed changes are implemented in the [`CSSSourceCode`](https://github.com ```ts interface CustomPropertyUses { declarations: Array; + definitions: Array; references: Array; } interface CSSSourceCode { - customProperties: Map + #customProperties: Map } ``` -A new public property, `customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have two properties: +A new public property, `#customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have two properties: -* `declarations`: An array of `Declaration` nodes where the custom property is defined. -* `references`: An array of `Function` nodes (specifically `var()` functions) where the custom property is used. +* `declarations`: An array of `DeclarationPlain` nodes where the custom property value is declared. +* `definitions`: Array of `AtrulePlain` nodes where the custom property is defined using an [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) rule. +* `references`: An array of `FunctionNode` nodes (specifically `var()` functions) where the custom property is used. ### `getDeclarationVariables()` Method @@ -56,19 +58,29 @@ interface CSSSourceCode { A new public method, `getDeclarationVariables(declaration)`, will be added to `CSSSourceCode`. This method will take a `Declaration` node as an argument and return an array of `Function` nodes representing the `var()` functions used in that declaration's value. -### `getVariableValue()` Method +### `getClosestVariableValue()` Method ```ts interface CSSSourceCode { - getVariableValue(func: FunctionNode): Raw; + getClosestVariableValue(func: FunctionNode): Raw; } ``` -A new public method, `getVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by searching for the last declaration of the custom property that appears before the given `Function` node in the source code. This also leaves open the possibility that we could change how this value is calculated to be more accurate in the future. +A new public method, `getClosestVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by searching for the last declaration of the custom property that appears before the given `Function` node in the source code. This also leaves open the possibility that we could change how this value is calculated to be more accurate in the future. + +### `getVariableValues()` Method + +```ts +interface CSSSourceCode { + getVariableValues(func: FunctionNode): Array; +} +``` + +A new public method, `getVariableValues(func)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return an array of `Raw` nodes representing the declared values of the custom property. The fallback value, if specified in the `FunctionNode`, is returned as the last element of the array. ### Initialization -The `traverse()` method in `CSSSourceCode` will be updated to populate the `customProperties` map and the internal data structure (`WeakMap>`) used by `getDeclarationVariables()`. During traversal, it will identify `Declaration` nodes that define custom properties and `Function` nodes that are `var()` calls. +The `traverse()` method in `CSSSourceCode` will be updated to populate the `#customProperties` map and the internal data structure (`WeakMap>`) used by `getDeclarationVariables()`. During traversal, it will identify `Declaration` nodes that define custom properties and `Function` nodes that are `var()` calls. ## Documentation @@ -88,12 +100,6 @@ The primary alternative is to have each rule implement its own custom property t ## Open Questions -**Should we expose `customProperties` publicly?** - -It's unclear if this is useful to rules directly. The primary use case for this data is through the provided methods (`getDeclarationVariables()` and `getVariableValue()`), which offer a more controlled and convenient interface. - -So far, we don't have any use cases for rules accessing `customProperties` directly, so perhaps it's better to keep it private until we have a use case it solves? - **Should we use "var" instead of "variable" in function names?** The proposed API includes methods like `getDeclarationVariables()` and `getVariableValue()`. Since CSS custom properties are commonly referred to as "CSS variables" in the community, there's a question about whether the method names should use the shorter "var" terminology instead. For example: @@ -103,6 +109,10 @@ The proposed API includes methods like `getDeclarationVariables()` and `getVaria Using "var" would be more concise and align with the CSS `var()` function syntax that developers are already familiar with. However, "variable" is more explicit and follows common naming conventions in programming APIs. +**Should `getVariableValues()` return the fallback value?** + +The fallback value is already available in the `FunctionNode` passed into `getVariableValues()`, so rule authors can still get access to that value easily. It seems like a nice touch to always have it as the last element of the returned array, but that also means that a non-declared value is present in the array, which could potentially be confusing. + ## Help Needed No help is needed to implement this RFC. From ddd61ebc317e717a7b83c3a1461467cfe198e0b3 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 22 Jul 2025 11:38:16 -0400 Subject: [PATCH 04/12] Update designs/2025-css-vars-tracking/README.md Co-authored-by: Francesco Trotta --- designs/2025-css-vars-tracking/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index 63bc5277..b257e3b6 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -42,7 +42,7 @@ interface CSSSourceCode { } ``` -A new public property, `#customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have two properties: +A new public property, `#customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have three properties: * `declarations`: An array of `DeclarationPlain` nodes where the custom property value is declared. * `definitions`: Array of `AtrulePlain` nodes where the custom property is defined using an [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) rule. From 0466e46fd71742b34f77be978d503a528065e102 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Wed, 30 Jul 2025 11:06:09 -0400 Subject: [PATCH 05/12] Update designs/2025-css-vars-tracking/README.md Co-authored-by: Francesco Trotta --- designs/2025-css-vars-tracking/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index b257e3b6..0f5f100e 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -42,7 +42,7 @@ interface CSSSourceCode { } ``` -A new public property, `#customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have three properties: +A new private property, `#customProperties`, will be added to `CSSSourceCode`. This will be a `Map` where the keys are the custom property names (e.g., `--my-color`) and the values are `CustomPropertyUses` objects. The `CustomPropertyUses` class will have three properties: * `declarations`: An array of `DeclarationPlain` nodes where the custom property value is declared. * `definitions`: Array of `AtrulePlain` nodes where the custom property is defined using an [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) rule. From 8da0d1240d5e1e78422f9b0a2f899b59b360b01b Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Thu, 31 Jul 2025 14:23:15 -0400 Subject: [PATCH 06/12] Answer open questions --- designs/2025-css-vars-tracking/README.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index 0f5f100e..0b1e3104 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -100,18 +100,7 @@ The primary alternative is to have each rule implement its own custom property t ## Open Questions -**Should we use "var" instead of "variable" in function names?** - -The proposed API includes methods like `getDeclarationVariables()` and `getVariableValue()`. Since CSS custom properties are commonly referred to as "CSS variables" in the community, there's a question about whether the method names should use the shorter "var" terminology instead. For example: - -- `getDeclarationVars()` instead of `getDeclarationVariables()` -- `getVarValue()` instead of `getVariableValue()` - -Using "var" would be more concise and align with the CSS `var()` function syntax that developers are already familiar with. However, "variable" is more explicit and follows common naming conventions in programming APIs. - -**Should `getVariableValues()` return the fallback value?** - -The fallback value is already available in the `FunctionNode` passed into `getVariableValues()`, so rule authors can still get access to that value easily. It seems like a nice touch to always have it as the last element of the returned array, but that also means that a non-declared value is present in the array, which could potentially be confusing. +n/a ## Help Needed From e13bf02b781332cc1493f3a5e2a7cecb2102dae4 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Thu, 31 Jul 2025 14:33:53 -0400 Subject: [PATCH 07/12] Update getClosestVariableValue() definition --- designs/2025-css-vars-tracking/README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index 0b1e3104..c9f63df1 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -62,11 +62,17 @@ A new public method, `getDeclarationVariables(declaration)`, will be added to `C ```ts interface CSSSourceCode { - getClosestVariableValue(func: FunctionNode): Raw; + getClosestVariableValue(func: FunctionNode): Raw | undefined; } ``` -A new public method, `getClosestVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by searching for the last declaration of the custom property that appears before the given `Function` node in the source code. This also leaves open the possibility that we could change how this value is calculated to be more accurate in the future. +A new public method, `getClosestVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by: + +1. If the current rule block has one or more custom properties declaration for the variable, then return the value of the last custom property declaration in the block. This mimics the way CSS calculates custom property values. +2. If `var()` has a fallback value, return the fallback value. +3. If one of the previous rules had a custom property declaration, then return the last value of the custom property. +4. If there's a `@property` block for the custom property that has an `initial-value`, return the `initial-value`. +5. Otherwise, return `undefined`. ### `getVariableValues()` Method From 23247297d7c5795215daae5f12ac7c7864ba5afd Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Thu, 31 Jul 2025 14:36:51 -0400 Subject: [PATCH 08/12] Update getVariableValues() definition --- designs/2025-css-vars-tracking/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index c9f63df1..111bb280 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -82,7 +82,11 @@ interface CSSSourceCode { } ``` -A new public method, `getVariableValues(func)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return an array of `Raw` nodes representing the declared values of the custom property. The fallback value, if specified in the `FunctionNode`, is returned as the last element of the array. +A new public method, `getVariableValues(func)`, will be added to `CSSSourceCode`. This method will take a `var()` `FunctionNode` as an argument and return an array of `Raw` nodes representing the declared values of the custom property. The returned array is made up of the following: + +1. If there is a `@property` for the custom property that has an `initial-value`, then the `initial-value` is the first element in the array. +2. The `Raw` values defined in custom property declarations throughout the file, both before and after the `FunctionNode` come next in source order. +3. The fallback value, if specified in the `FunctionNode`, is returned as the last element of the array. ### Initialization From 2969f9ba5c8b30c1a4f7f40efff2a9bae3693c48 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Fri, 22 Aug 2025 10:06:36 -0400 Subject: [PATCH 09/12] Mention Raw | Value for dealing with custom property values --- designs/2025-css-vars-tracking/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index 111bb280..15427ee1 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -62,11 +62,11 @@ A new public method, `getDeclarationVariables(declaration)`, will be added to `C ```ts interface CSSSourceCode { - getClosestVariableValue(func: FunctionNode): Raw | undefined; + getClosestVariableValue(func: FunctionNode): Value | Raw | undefined; } ``` -A new public method, `getClosestVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property (which is currently always a `Raw` node). It will do this by: +A new public method, `getClosestVariableValue(node)`, will be added to `CSSSourceCode`. This method will take a `var()` `Function` node as an argument and return the computed value of the custom property. It will do this by: 1. If the current rule block has one or more custom properties declaration for the variable, then return the value of the last custom property declaration in the block. This mimics the way CSS calculates custom property values. 2. If `var()` has a fallback value, return the fallback value. @@ -78,13 +78,13 @@ A new public method, `getClosestVariableValue(node)`, will be added to `CSSSourc ```ts interface CSSSourceCode { - getVariableValues(func: FunctionNode): Array; + getVariableValues(func: FunctionNode): Array; } ``` -A new public method, `getVariableValues(func)`, will be added to `CSSSourceCode`. This method will take a `var()` `FunctionNode` as an argument and return an array of `Raw` nodes representing the declared values of the custom property. The returned array is made up of the following: +A new public method, `getVariableValues(func)`, will be added to `CSSSourceCode`. This method will take a `var()` `FunctionNode` as an argument and return an array of nodes representing the declared values of the custom property. The returned array is made up of the following: -1. If there is a `@property` for the custom property that has an `initial-value`, then the `initial-value` is the first element in the array. +1. If there is a `@property` for the custom property that has an `initial-value`, then the `initial-value` is the first element in the array (a `Value` node). 2. The `Raw` values defined in custom property declarations throughout the file, both before and after the `FunctionNode` come next in source order. 3. The fallback value, if specified in the `FunctionNode`, is returned as the last element of the array. @@ -118,9 +118,9 @@ No help is needed to implement this RFC. ## Frequently Asked Questions -**Why does `getVariableValue()` return a `Raw` instead of a string?** +**Why does `getVariableValue()` return `Raw | Value` instead of a string?** -The `getVariableValue()` method returns a `Raw` node instead of a string to preserve the original source information and maintain consistency with the AST structure. A `Raw` node contains not only the text value but also the location, which is valuable for rules that need to report issues or apply fixes at specific locations in the source code. Additionally, returning the actual AST node allows for future extensibility. If we later need to return more complex computed values or support different node types, the API won't need to change. +The `getVariableValue()` method returns `Raw | Value` instead of a string to preserve the original source information and maintain consistency with the AST structure. A `Raw` or `Value` node contains not only the text value but also the location, which is valuable for rules that need to report issues or apply fixes at specific locations in the source code. Additionally, returning the actual AST node allows for future extensibility. If we later need to return more complex computed values or support different node types, the API won't need to change. ## Related Discussions From a4b72518b731ab5e375b808384825da4913e3841 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 26 Aug 2025 10:53:00 -0400 Subject: [PATCH 10/12] Update designs/2025-css-vars-tracking/README.md Co-authored-by: Milos Djermanovic --- designs/2025-css-vars-tracking/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index 15427ee1..8397f381 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -124,4 +124,4 @@ The `getVariableValue()` method returns `Raw | Value` instead of a string to pre ## Related Discussions -- [Change Request: Track variables on SourceCode #160](https.github.com/eslint/css/issues/160) +- [Change Request: Track variables on SourceCode #160](https://github.com/eslint/css/issues/160) From 2b89b34b5122cccc4d572425c09befd55fe5be7d Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 26 Aug 2025 10:53:10 -0400 Subject: [PATCH 11/12] Update designs/2025-css-vars-tracking/README.md Co-authored-by: Milos Djermanovic --- designs/2025-css-vars-tracking/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index 8397f381..a55a2fca 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -1,6 +1,6 @@ - Repo: eslint/css - Start Date: 2025-06-24 -- RFC PR: +- RFC PR: https://github.com/eslint/rfcs/pull/136 - Authors: Nicholas C. Zakas # CSS Custom Property Tracking in SourceCode From 4e289e0077a185af72e7bdd1a5ca5e845f59af9a Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 26 Aug 2025 10:53:19 -0400 Subject: [PATCH 12/12] Update designs/2025-css-vars-tracking/README.md Co-authored-by: Milos Djermanovic --- designs/2025-css-vars-tracking/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-css-vars-tracking/README.md b/designs/2025-css-vars-tracking/README.md index a55a2fca..f143543f 100644 --- a/designs/2025-css-vars-tracking/README.md +++ b/designs/2025-css-vars-tracking/README.md @@ -52,7 +52,7 @@ A new private property, `#customProperties`, will be added to `CSSSourceCode`. T ```ts interface CSSSourceCode { - getDeclarationVariables(declaration: DeclarationPlain): Array; + getDeclarationVariables(declaration: DeclarationPlain): Array; } ```