@wix/zero-config-implementation 1.20.0 → 1.21.0

package/dist/information-extractors/css/selector-matcher.d.ts

@@ -1,3 +1,6 @@
 import { ExtractedCssInfo } from '../../index';
 import { ExtractedElement } from '../react/extractors/core/tree-builder';
-export declare function matchCssSelectors(html: string, elements: ExtractedElement[], cssInfos: ExtractedCssInfo[]): ExtractedElement[];
+export declare function matchCssSelectors(html: string, elements: ExtractedElement[], cssInfos: ExtractedCssInfo[]): {
+    elements: ExtractedElement[];
+    varUsedByTraceId: Map<string, Set<string>>;
+};

package/dist/information-extractors/css/types.d.ts

@@ -46,4 +46,14 @@ export interface CSSParserAPI {
      * @returns DOM-matchable selector string or null
      */
     getDomSelector: (selector: string) => string | null;
+    /**
+     * Determines the CSS property type for a custom property based on how it is used.
+     * If all usages of varName are within the same CSS property, returns that property name.
+     * If usages differ, returns the CSS data type inferred from the initial value
+     * ('color', 'length', 'number', or 'string').
+     * Returns undefined if the variable is never used via var().
+     * @param varName - The CSS variable name (with or without --)
+     * @param defaultValue - The initial value string of the custom property
+     */
+    getVarPropertyType: (varName: string, defaultValue: string) => string | undefined;
 }

package/dist/manifest-pipeline.d.ts

@@ -17,6 +17,7 @@ export interface ExtractedCssInfo {
 }
 export interface ComponentInfoWithCss extends CoupledComponentInfo {
     css: ExtractedCssInfo[];
+    varUsedByTraceId: Map<string, Set<string>>;
 }
 /** The result of processing a single component through the manifest pipeline. */
 export interface ProcessComponentResult {

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -76,5 +76,5 @@
       ]
     }
   },
-  "falconPackageHash": "9d8e025c881d82e1e831ca0c9455a53b725239084e43035bef8a1981"
+  "falconPackageHash": "3957b9b1458a26239d8d8e3088fe1996b439e4c7aa91e8add92e1305"
 }

package/src/converters/data-item-builder.ts

@@ -377,7 +377,7 @@ function handleSemanticType(dataItem: DataItem, resolvedType: ResolvedType): voi
   dataItem.text = {}
 }
 
-const EVENT_HANDLER_ATTR_TO_DATA_TYPE: Record<string, string> = {
+const EVENT_HANDLER_ATTR_TO_DATA_TYPE: Record<string, (typeof DATA_TYPE)[keyof typeof DATA_TYPE]> = {
   onclick: DATA_TYPE.onClick,
   onchange: DATA_TYPE.onChange,
   onkeypress: DATA_TYPE.onKeyPress,

package/src/converters/to-editor-component.ts

@@ -24,22 +24,32 @@ import { formatDisplayName } from './utils'
 const EXCLUDED_PROPS = new Set(['id', 'className', 'elementProps', 'wix'])
 
 export function toEditorReactComponent(component: ComponentInfoWithCss): EditorReactComponent {
+  const nearestCommonAncestorCustomProps = buildNearestCommonAncestorCustomProps(component)
   return {
-    editorElement: buildEditorElement(component),
+    editorElement: buildEditorElement(component, nearestCommonAncestorCustomProps),
   }
 }
 
-function buildEditorElement(component: ComponentInfoWithCss): EditorElement {
+function buildEditorElement(
+  component: ComponentInfoWithCss,
+  nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
+): EditorElement {
   const rootElement = component.elements[0]
   const childElements = rootElement?.children ?? []
+  const rootCustomProps = rootElement ? (nearestCommonAncestorCustomProps.get(rootElement.traceId) ?? {}) : {}
 
   return {
     selector: buildSelector(rootElement),
     displayName: formatDisplayName(component.componentName),
     data: buildData(component.props, component.propUsages),
-    elements: buildElements(childElements, component.innerElementProps, component.propUsages),
+    elements: buildElements(
+      childElements,
+      nearestCommonAncestorCustomProps,
+      component.innerElementProps,
+      component.propUsages,
+    ),
     cssProperties: buildCssProperties(rootElement),
-    cssCustomProperties: buildCssCustomPropertiesForElement(rootElement),
+    cssCustomProperties: rootCustomProps,
   }
 }
 
@@ -75,6 +85,7 @@ function buildData(
 
 function buildElements(
   elements: ExtractedElement[],
+  nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
 ): Record<string, ElementItem> {
@@ -84,7 +95,7 @@ function buildElements(
     const elementData = innerElementProps?.get(element.traceId)
     const data = elementData && propUsages ? buildData(elementData, propUsages) : undefined
     const cssProps = buildCssProperties(element)
-    const cssCustomProps = buildCssCustomPropertiesForElement(element)
+    const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
     result[element.name] = {
       elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
@@ -95,11 +106,13 @@ function buildElements(
         ...(data && Object.keys(data).length > 0 && { data }),
         // CSS properties from heuristic + matched CSS files
         ...(Object.keys(cssProps).length > 0 && { cssProperties: cssProps }),
-        // CSS custom properties from matched rules for this element
+        // CSS custom properties placed on the Nearest Common Ancestor of all elements that use each variable
         ...(Object.keys(cssCustomProps).length > 0 && { cssCustomProperties: cssCustomProps }),
         // Recursively build nested elements
         elements:
-          element.children.length > 0 ? buildElements(element.children, innerElementProps, propUsages) : undefined,
+          element.children.length > 0
+            ? buildElements(element.children, nearestCommonAncestorCustomProps, innerElementProps, propUsages)
+            : undefined,
       },
     }
   }
@@ -107,6 +120,174 @@ function buildElements(
   return result
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS Custom Properties — Nearest Common Ancestor computation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Pre-computes a map of traceId → custom property items to assign to each element.
+ * Each custom property is placed on the nearest common ancestor (Nearest Common Ancestor) of all elements
+ * that use it via var(). Falls back to the element that defines it if unused.
+ */
+function buildNearestCommonAncestorCustomProps(
+  component: ComponentInfoWithCss,
+): Map<string, Record<string, CssCustomPropertyItem>> {
+  const parentMap = buildParentMap(component.elements)
+
+  // Collect default values from matched elements only — this excludes values from theme/modifier
+  // selectors that were not applied during mock rendering (e.g. .component.dark when variant='light').
+  const allCustomPropertyValues = collectMatchedCustomPropertyValues(component.elements)
+
+  // Fall back to the raw CSS scan for any vars not captured by element matching
+  // (e.g. vars defined in a selector that matched no element in the rendered output).
+  for (const cssInfo of component.css) {
+    for (const [varName, defaultValue] of cssInfo.customProperties) {
+      if (!allCustomPropertyValues.has(varName)) {
+        allCustomPropertyValues.set(varName, defaultValue)
+      }
+    }
+  }
+
+  const nearestCommonAncestorCustomProps = new Map<string, Record<string, CssCustomPropertyItem>>()
+
+  for (const [varName, defaultValue] of allCustomPropertyValues) {
+    if (varName === '--display') continue
+
+    const usedByTraceIds = component.varUsedByTraceId.get(varName) ?? new Set<string>()
+
+    let nearestCommonAncestorTraceId: string | undefined
+    if (usedByTraceIds.size > 0) {
+      nearestCommonAncestorTraceId = findNearestCommonAncestor(usedByTraceIds, parentMap)
+    } else {
+      // Fallback: place on the element whose CSS selector defines the variable
+      nearestCommonAncestorTraceId = findDefiningElement(component.elements, varName)
+    }
+
+    if (!nearestCommonAncestorTraceId) continue
+
+    const cssPropertyType = getVarPropertyTypeFromCssInfos(varName, defaultValue, component.css)
+    const cleanVarName = varName.startsWith('--') ? varName.slice(2) : varName
+
+    const existingProps = nearestCommonAncestorCustomProps.get(nearestCommonAncestorTraceId) ?? {}
+    existingProps[cleanVarName] = {
+      defaultValue,
+      ...(cssPropertyType !== undefined && { cssPropertyType }),
+    }
+    nearestCommonAncestorCustomProps.set(nearestCommonAncestorTraceId, existingProps)
+  }
+
+  return nearestCommonAncestorCustomProps
+}
+
+/**
+ * Queries each CSS parser API for the property type of a variable and returns
+ * the first defined result.
+ */
+function getVarPropertyTypeFromCssInfos(
+  varName: string,
+  defaultValue: string,
+  cssInfos: ComponentInfoWithCss['css'],
+): CssCustomPropertyItem['cssPropertyType'] {
+  for (const cssInfo of cssInfos) {
+    const propertyType = cssInfo.api.getVarPropertyType(varName, defaultValue)
+    if (propertyType !== undefined) return propertyType as CssCustomPropertyItem['cssPropertyType']
+  }
+  return undefined
+}
+
+/**
+ * Walks the element tree and collects custom property default values from the CSS selector
+ * matches recorded on each element. Only values from selectors that matched during mock rendering
+ * are included, so theme/modifier variant values (e.g. .component.dark) are excluded when the
+ * corresponding class was not present on the rendered element.
+ */
+function collectMatchedCustomPropertyValues(elements: ExtractedElement[]): Map<string, string> {
+  const values = new Map<string, string>()
+  for (const element of elements) {
+    const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+    if (matcherData) {
+      for (const [varName, varValue] of Object.entries(matcherData.customProperties)) {
+        if (!values.has(varName)) values.set(varName, varValue)
+      }
+    }
+    for (const [varName, varValue] of collectMatchedCustomPropertyValues(element.children)) {
+      if (!values.has(varName)) values.set(varName, varValue)
+    }
+  }
+  return values
+}
+
+/**
+ * Builds a map of traceId → parent traceId by recursively walking the element tree.
+ */
+function buildParentMap(elements: ExtractedElement[], parentTraceId?: string): Map<string, string> {
+  const parentMap = new Map<string, string>()
+  for (const element of elements) {
+    if (parentTraceId !== undefined) {
+      parentMap.set(element.traceId, parentTraceId)
+    }
+    for (const [childTraceId, childParentTraceId] of buildParentMap(element.children, element.traceId)) {
+      parentMap.set(childTraceId, childParentTraceId)
+    }
+  }
+  return parentMap
+}
+
+/**
+ * Returns the path from the root element down to the given traceId (inclusive).
+ */
+function pathFromRoot(traceId: string, parentMap: Map<string, string>): string[] {
+  const path = [traceId]
+  let currentTraceId = traceId
+  while (parentMap.has(currentTraceId)) {
+    currentTraceId = parentMap.get(currentTraceId) as string
+    path.unshift(currentTraceId)
+  }
+  return path
+}
+
+/**
+ * Finds the nearest common ancestor traceId for a set of element traceIds.
+ * If a single traceId is given, returns it directly.
+ */
+function findNearestCommonAncestor(traceIds: Set<string>, parentMap: Map<string, string>): string {
+  const traceIdList = [...traceIds]
+  if (traceIdList.length === 1) return traceIdList[0]
+
+  const paths = traceIdList.map((traceId) => pathFromRoot(traceId, parentMap))
+  const shortestPathLength = Math.min(...paths.map((path) => path.length))
+
+  let nearestCommonAncestorTraceId = paths[0][0]
+  for (let depth = 0; depth < shortestPathLength; depth++) {
+    const candidateTraceId = paths[0][depth]
+    if (paths.every((path) => path[depth] === candidateTraceId)) {
+      nearestCommonAncestorTraceId = candidateTraceId
+    } else {
+      break
+    }
+  }
+
+  return nearestCommonAncestorTraceId
+}
+
+/**
+ * Finds the traceId of the first element in the tree whose matched CSS rules
+ * define the given custom property (fallback when var() usage is not tracked).
+ */
+function findDefiningElement(elements: ExtractedElement[], varName: string): string | undefined {
+  for (const element of elements) {
+    const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+    if (matcherData?.customProperties[varName] !== undefined) return element.traceId
+    const childResult = findDefiningElement(element.children, varName)
+    if (childResult !== undefined) return childResult
+  }
+  return undefined
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS Properties helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
  * Returns the CSS property values matched for this specific element's selector(s).
  * Reads from css-matcher.matches which is populated by matchCssSelectors.
@@ -146,30 +327,3 @@ function buildCssProperties(element: ExtractedElement | undefined): Record<strin
 
   return result
 }
-
-/**
- * Build cssCustomProperties for a single element from this element's matched rules only.
- * Only includes --vars that were declared in a rule that matched this element's selector(s).
- */
-function buildCssCustomPropertiesForElement(
-  element: ExtractedElement | undefined,
-): Record<string, CssCustomPropertyItem> {
-  const matcherData = element?.extractorData.get('css-matcher') as MatchedCssData | undefined
-  const customProperties = matcherData?.customProperties
-  if (!customProperties || Object.keys(customProperties).length === 0) {
-    return {}
-  }
-
-  const result: Record<string, CssCustomPropertyItem> = {}
-  for (const [name, value] of Object.entries(customProperties)) {
-    // Skip --display (handled in regular properties)
-    if (name === '--display') continue
-
-    // Strip the -- prefix from the name
-    const cleanName = name.startsWith('--') ? name.slice(2) : name
-    result[cleanName] = {
-      defaultValue: value,
-    }
-  }
-  return result
-}

package/src/information-extractors/css/parse.ts

@@ -1,4 +1,7 @@
+import { CSS_PROPERTIES } from '@wix/zero-config-schema'
+import { camelCase } from 'case-anything'
 import { transform } from 'lightningcss'
+import type { TokenOrValue } from 'lightningcss'
 import type { CSSParserAPI, CSSProperty } from './types'
 // Store parsed selectors for later DOM selector computation
 const parsedSelectors = new Map<string, unknown[]>()
@@ -13,7 +16,7 @@ export function parseCss(cssString: string): CSSParserAPI {
   parsedSelectors.clear()
 
   // Parse all properties eagerly at initialization using lightningcss
-  const allProperties = parseAllProperties(cssString)
+  const { propertiesMap: allProperties, varUsagesByProperty } = parseAllProperties(cssString)
 
   return {
     getPropertiesForSelector(selector: string): CSSProperty[] {
@@ -25,27 +28,8 @@ export function parseCss(cssString: string): CSSParserAPI {
     },
 
     getVarUsages(varName: string): string[] {
-      // Normalize variable name to include --
       const normalizedVarName = varName.startsWith('--') ? varName : `--${varName}`
-
-      const propertyNames = new Set<string>()
-
-      // Search through all properties for var() usage
-      for (const properties of allProperties.values()) {
-        for (const property of properties) {
-          // Check if the value contains var(--varName)
-          const varPattern = new RegExp(`var\\(\\s*${escapeRegex(normalizedVarName)}\\s*[,)]`, 'i')
-
-          if (varPattern.test(property.value)) {
-            // Ignore shorthand properties (values with multiple space-separated values)
-            if (!isShorthandValue(property.value)) {
-              propertyNames.add(property.name)
-            }
-          }
-        }
-      }
-
-      return Array.from(propertyNames)
+      return [...(varUsagesByProperty.get(normalizedVarName) ?? [])]
     },
 
     getUniqueProperties(selectors: string[]): Map<string, string> {
@@ -76,17 +60,35 @@ export function parseCss(cssString: string): CSSParserAPI {
       if (!parsed) return null
       return buildDomSelector(parsed)
     },
+
+    getVarPropertyType(varName: string, defaultValue: string): string | undefined {
+      const usages = this.getVarUsages(varName)
+      if (usages.length === 0) return undefined
+      const uniqueProperties = [...new Set(usages)]
+      if (uniqueProperties.length === 1) {
+        const camelCased = camelCase(uniqueProperties[0])
+        const validValues = Object.values(CSS_PROPERTIES.CSS_PROPERTY_TYPE) as string[]
+        if (validValues.includes(camelCased)) return camelCased
+      }
+      return inferCssDataType(defaultValue)
+    },
   }
 }
 
 /**
- * Parses all selectors and their properties from the CSS using lightningcss
+ * Parses all selectors and their properties from the CSS using lightningcss.
+ * Also builds a direct map of var() usages by scanning unparsed declaration tokens,
+ * since serialized property values lose var() references.
  * Supports @media rules, @keyframes, and nested selectors
  * @param cssString - CSS string to parse
- * @returns Map from selector to its CSS properties
+ * @returns propertiesMap (selector → properties) and varUsagesByProperty (varName → CSS property names)
  */
-function parseAllProperties(cssString: string): Map<string, CSSProperty[]> {
+function parseAllProperties(cssString: string): {
+  propertiesMap: Map<string, CSSProperty[]>
+  varUsagesByProperty: Map<string, Set<string>>
+} {
   const propertiesMap = new Map<string, CSSProperty[]>()
+  const varUsagesByProperty = new Map<string, Set<string>>()
 
   try {
     // Use lightningcss transform with visitor to collect properties
@@ -113,10 +115,26 @@ function parseAllProperties(cssString: string): Map<string, CSSProperty[]> {
               // Extract properties from declarations
               const properties: CSSProperty[] = []
               for (const decl of rule.value.declarations?.declarations ?? []) {
-                const extracted = extractPropertyNameAndValue(decl)
+                const declTyped = decl as LightningDecl
+                const extracted = extractPropertyNameAndValue(declTyped)
                 if (extracted) {
                   properties.push(extracted)
                 }
+
+                // Track var() usages by scanning unparsed declaration tokens directly.
+                // propertyValueToString cannot recover var() from unparsed values, so
+                // we inspect the token array instead.
+                if (declTyped.property === 'unparsed') {
+                  const unparsed = declTyped.value as { propertyId?: { property?: string }; value?: unknown[] }
+                  const cssPropertyName = unparsed.propertyId?.property
+                  if (cssPropertyName) {
+                    for (const varName of extractVarNamesFromTokens(unparsed.value ?? [])) {
+                      const usageSet = varUsagesByProperty.get(varName) ?? new Set<string>()
+                      usageSet.add(cssPropertyName)
+                      varUsagesByProperty.set(varName, usageSet)
+                    }
+                  }
+                }
               }
 
               // Store properties for each selector
@@ -176,7 +194,36 @@ function parseAllProperties(cssString: string): Map<string, CSSProperty[]> {
     console.error('CSS parsing error:', error)
   }
 
-  return propertiesMap
+  return { propertiesMap, varUsagesByProperty }
+}
+
+/**
+ * Extracts all CSS custom property names referenced via var() from a lightningcss token array.
+ * Handles nested token arrays recursively (e.g. tokens inside function arguments).
+ */
+function extractVarNamesFromTokens(tokens: unknown[]): string[] {
+  const varNames: string[] = []
+
+  for (const token of tokens) {
+    if (!token || typeof token !== 'object') continue
+    const tokenObj = token as Record<string, unknown>
+
+    if (tokenObj.type === 'var') {
+      const varValue = tokenObj.value as Record<string, unknown> | undefined
+      const nameObj = varValue?.name as Record<string, unknown> | undefined
+      const identName = nameObj?.ident as string | undefined
+      if (identName) {
+        varNames.push(identName.startsWith('--') ? identName : `--${identName}`)
+      }
+    } else if (tokenObj.type === 'function' || Array.isArray(tokenObj.value)) {
+      const nestedTokens = tokenObj.value as unknown[]
+      if (Array.isArray(nestedTokens)) {
+        varNames.push(...extractVarNamesFromTokens(nestedTokens))
+      }
+    }
+  }
+
+  return varNames
 }
 
 /**
@@ -271,7 +318,7 @@ interface LightningDecl {
 
 interface CustomPropertyValue {
   name: string
-  value: unknown[]
+  value: TokenOrValue[]
 }
 
 /**
@@ -339,19 +386,33 @@ function serializeCustomPropertyValue(valueArray: unknown[]): string {
           parts.push(`rgba(${r}, ${g}, ${b}, ${a})`)
         }
       }
-    } else if (t.type === 'length' || t.type === 'dimension') {
-      const dim = (t.value as Record<string, unknown>) ?? t
-      const unit = dim.unit as string
-      const val = dim.value as number
-      parts.push(`${val}${unit}`)
-    } else if (t.type === 'number') {
-      parts.push(String(t.value))
+    } else if (t.type === 'length' || t.type === 'resolution') {
+      // length/resolution: { unit: string, value: number }
+      const dim = t.value as Record<string, unknown>
+      parts.push(`${dim.value}${dim.unit}`)
+    } else if (t.type === 'angle') {
+      // angle: { type: 'deg' | 'rad' | 'grad' | 'turn', value: number }
+      const dim = t.value as Record<string, unknown>
+      parts.push(`${dim.value}${dim.type}`)
+    } else if (t.type === 'time') {
+      // time: { type: 'seconds' | 'milliseconds', value: number }
+      const dim = t.value as Record<string, unknown>
+      const unit = dim.type === 'milliseconds' ? 'ms' : 's'
+      parts.push(`${dim.value}${unit}`)
     } else if (t.type === 'token') {
       const tokenValue = t.value as Record<string, unknown>
       if (tokenValue.type === 'ident') {
         parts.push(tokenValue.value as string)
       } else if (tokenValue.type === 'string') {
         parts.push(`"${tokenValue.value}"`)
+      } else if (tokenValue.type === 'number') {
+        parts.push(String(tokenValue.value))
+      } else if (tokenValue.type === 'percentage') {
+        parts.push(`${(tokenValue.value as number) * 100}%`)
+      } else if (tokenValue.type === 'dimension') {
+        parts.push(`${tokenValue.value}${tokenValue.unit}`)
+      } else if (tokenValue.type === 'white-space') {
+        parts.push(tokenValue.value as string)
       }
     }
   }
@@ -448,3 +509,69 @@ function isShorthandValue(value: string): boolean {
 function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
+
+const ANGLE_UNITS = new Set(['deg', 'rad', 'grad', 'turn'])
+const TIME_UNITS = new Set(['s', 'ms'])
+
+/**
+ * Infers the CSS data type category from a custom property's initial value string.
+ * Uses lightningcss to parse the value and inspect the first token's type.
+ * Returns a value from CSS_PROPERTIES.CSS_DATA_TYPE.
+ */
+function inferCssDataType(defaultValue: string): string {
+  const { CSS_DATA_TYPE } = CSS_PROPERTIES
+  let inferredType: string = CSS_DATA_TYPE.string
+
+  try {
+    transform({
+      filename: 'input.css',
+      code: Buffer.from(`.x { --foo: ${defaultValue}; }`),
+      minify: false,
+      visitor: {
+        Rule: {
+          style(rule) {
+            for (const declaration of rule.value.declarations?.declarations ?? []) {
+              const decl = declaration as LightningDecl
+              if (decl.property === 'custom') {
+                const tokens = (decl.value as CustomPropertyValue).value
+                if (tokens?.length > 0) {
+                  const firstToken = tokens[0]
+                  if (firstToken.type === 'color') {
+                    inferredType = CSS_DATA_TYPE.color
+                  } else if (firstToken.type === 'length') {
+                    inferredType = CSS_DATA_TYPE.length
+                  } else if (firstToken.type === 'angle') {
+                    inferredType = CSS_DATA_TYPE.angle
+                  } else if (firstToken.type === 'time') {
+                    inferredType = CSS_DATA_TYPE.time
+                  } else if (firstToken.type === 'token') {
+                    const raw = firstToken.value
+                    if (raw.type === 'number') {
+                      inferredType = CSS_DATA_TYPE.number
+                    } else if (raw.type === 'percentage') {
+                      inferredType = CSS_DATA_TYPE.percentage
+                    } else if (raw.type === 'dimension') {
+                      const unit = raw.unit.toString()
+                      if (ANGLE_UNITS.has(unit)) {
+                        inferredType = CSS_DATA_TYPE.angle
+                      } else if (TIME_UNITS.has(unit)) {
+                        inferredType = CSS_DATA_TYPE.time
+                      } else {
+                        inferredType = CSS_DATA_TYPE.length
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            return undefined
+          },
+        },
+      },
+    })
+  } catch {
+    // Fall back to 'string' if parsing fails
+  }
+
+  return inferredType
+}

package/src/information-extractors/css/selector-matcher.ts

@@ -8,12 +8,13 @@ export function matchCssSelectors(
   html: string,
   elements: ExtractedElement[],
   cssInfos: ExtractedCssInfo[],
-): ExtractedElement[] {
+): { elements: ExtractedElement[]; varUsedByTraceId: Map<string, Set<string>> } {
   const $ = cheerio.load(html)
 
   // Build traceId -> matches map
   const matchesByTraceId = new Map<string, CssSelectorMatch[]>()
   const customPropsByTraceId = new Map<string, Record<string, string>>()
+  const varUsedByTraceId = new Map<string, Set<string>>()
 
   for (const cssInfo of cssInfos) {
     const allProps = cssInfo.api.getAllProperties()
@@ -51,6 +52,15 @@ export function matchCssSelectors(
             const existing = matchesByTraceId.get(traceId) ?? []
             existing.push({ selector, properties: regular })
             matchesByTraceId.set(traceId, existing)
+
+            // Track which CSS custom properties are used (via var()) by this element
+            for (const regularProp of regular) {
+              for (const varName of extractVarRefs(regularProp.value)) {
+                const traceIdSet = varUsedByTraceId.get(varName) ?? new Set()
+                traceIdSet.add(traceId)
+                varUsedByTraceId.set(varName, traceIdSet)
+              }
+            }
           }
 
           if (Object.keys(custom).length > 0) {
@@ -65,7 +75,24 @@ export function matchCssSelectors(
     }
   }
 
-  return enrichElements(elements, matchesByTraceId, customPropsByTraceId)
+  return {
+    elements: enrichElements(elements, matchesByTraceId, customPropsByTraceId),
+    varUsedByTraceId,
+  }
+}
+
+/**
+ * Extracts all CSS custom property names referenced via var() in a property value string.
+ */
+function extractVarRefs(value: string): string[] {
+  const varNames: string[] = []
+  const varPattern = /var\(\s*(--[\w-]+)/g
+  let varMatch = varPattern.exec(value)
+  while (varMatch !== null) {
+    varNames.push(varMatch[1])
+    varMatch = varPattern.exec(value)
+  }
+  return varNames
 }
 
 function enrichElements(

package/src/information-extractors/css/types.ts

@@ -53,4 +53,15 @@ export interface CSSParserAPI {
    * @returns DOM-matchable selector string or null
    */
   getDomSelector: (selector: string) => string | null
+
+  /**
+   * Determines the CSS property type for a custom property based on how it is used.
+   * If all usages of varName are within the same CSS property, returns that property name.
+   * If usages differ, returns the CSS data type inferred from the initial value
+   * ('color', 'length', 'number', or 'string').
+   * Returns undefined if the variable is never used via var().
+   * @param varName - The CSS variable name (with or without --)
+   * @param defaultValue - The initial value string of the custom property
+   */
+  getVarPropertyType: (varName: string, defaultValue: string) => string | undefined
 }