Re: [csswg-drafts] Source maps for CSS (#13098)

I'm definitely interested in this from a Sass perspective. We've generated source maps for many years, but it's never been entirely clear what the standard *is*. The [original spec](https://github.com/tc39/ecma426/blob/main/source-map-rev3.md) is quite vague on certain points: the "names" field has no intrinsically-defined meaning, for example, and there's no explicit indication of how a specific point in the target file maps to a specific point in the source file. I think some of these issues are already addressed in the ECMA draft, although perhaps not specifically for CSS. In practice what we did was experiment with what Chrome supported and try to target that as best as possible.

There are a few general thoughts I have here:

* There's a tension between the detail of the source map on one hand and the file size and compilation time on the other. Sass has the _capacity_ to generate an explicit mapping for every token in the document, but to do so would involve more time and/or memory overhead to compute or store the source spans of those tokens, and it's unclear if any tools would consume tokens at such a fine granularity. In practice, browsers seem to only include source map links for style rules; everything else is ignored. PostCSS respects source maps for any statement-level construct (style rules, at-rules, declarations, and comments), but no further.

  In Sass, we actually generate source maps at slightly finer granularity than either of these. If you have `declaration: $variable`, we'll map `declaration` to the location of its name and separately map `$variable` to the location of the variable definition. To the best of my knowledge, no tooling actually uses this information, but we try to prefigure a better future 🙂.

* JS source maps are most commonly used *in motion*—they're consulted while JS code is running, often during debugging, so that the mapping of variable names between the source and target files is very important for the user experience, while the specific mappings of subexpressions are secondary. CSS source maps, on the other hand, are exclusively used *at rest*. CSS doesn't have debugging in the same sense as an imperative language, so the more important questions tend to be "where did this specific value come from".

* In Sass specifically, the lexical source location of a given target is only a partial answer to the question "where did this come from". Sass *is* an imperative language even though the CSS it generates is not, and a given style rule or declaration may be generated through a sequence of mixins which only collectively fully describe its source. In other words, a fully explanatory CSS source map would have to include a stack trace for each target location rather than a single mapping.

  That said, computing and storing stack traces is expensive (we actually recently had a bug where we were accidentally doing this for all declarations, and it caused substantial performance degradation for large stylesheets). Even if this were something specified and supported by browsers, we'd need ot think carefully about whether we could find a way to make it work performantly before shipping it in Sass.

-- 
GitHub Notification of comment by nex3
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/13098#issuecomment-3534714017 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Friday, 14 November 2025 21:44:14 UTC