The Stylelint Rule That Was Silently Rewriting Our SCSS Colors

--- title: The Stylelint Rule That Was Silently Rewriting Our SCSS Colors published: true description: How color-function-notation silently rewrote rgba() to rgb() across our codebase — and three ways to fix it. tags: angular, scss, stylelint, webdev --- A colleague flagged something odd in a PR review — our SCSS colors had changed. Not broken, just different. `rgba(0, 0, 0, 0.7)` had quietly become `rgb(0, 0, 0, 0.7)` across dozens of files. The `a` was just gone. Nobody on the team had touched those lines. No error. No warning. Just silent rewrites on every save. Took us a while to trace it back, but it was one line in `.stylelintrc`. ## The rule ```json "color-function-notation": "legacy" ``` My first thought was — okay, `"legacy"` means keep the old syntax. That's literally what the word means. And technically it does enforce the older comma-separated format, so that part tracks. The issue was our codebase had gotten inconsistent. Some files had already picked up modern `rgb()` syntax through updated dependencies. The rest still used `rgba()`. When Stylelint's auto-fix kicked in, it just... normalised everything. Aggressively. Didn't ask, didn't warn. Hundreds of color changes in commits that had nothing to do with colors. ### What each value does | Value | What it enforces | |---|---| | `"modern"` | `rgb(0 0 0 / 0.7)` — space-separated, slash for alpha | | `"legacy"` | `rgba(0, 0, 0, 0.7)` — traditional comma-separated alpha syntax | | `null` | Nothing — leaves your code exactly as you wrote it | What we actually saw in our project was `rgba()` being rewritten to `rgb(..., alpha)` — not the standard modern space-separated conversion. More on that below. Worth knowing: **none of this happens without auto-fix.** If you're just running Stylelint normally, it warns. The actual rewrites only happen when you run `stylelint --fix`, have a CI step with `--fix` enabled, or have format-on-save turned on in your editor. ## Why this one is easy to miss A lot of articles about `color-function-notation` talk about the dramatic conversion — `rgba(0, 0, 0, 0.7)` turning into `rgb(0 0 0 / 0.7)`. Space-separated, slash before alpha, completely different looking. Hard to miss. What we got was quieter: - **Before:** `rgba(0, 0, 0, 0.7)` - **After:** `rgb(0, 0, 0, 0.7)` Same commas. Same numbers. Just the `a` missing. In a busy PR review across dozens of files, that's almost invisible. And it's not purely cosmetic either. For us the issue showed up as diff noise — but depending on your setup, silent rewrites like this can have downstream effects worth watching for. For us honestly the bigger headache was just the diff noise. PR history full of color changes nobody made. Not ideal. ## One thing to check first If you're using `stylelint-config-standard-scss` — most Angular projects do — this rule is already on inside the preset, set to `"modern"`. So even if you never added it yourself it might already be running. Before changing anything, figure out if it's in your own config or coming from the preset. That changes where you need to override it. In our case it was explicitly set in our own `.stylelintrc`: ```json { "extends": ["stylelint-config-standard-scss"], "rules": { "color-function-notation": "legacy" } } ``` ## Ways to fix it There's no one-size-fits-all here. ### Option 1 — Just turn it off ```json { "rules": { "color-function-notation": null } } ``` Stylelint leaves your color syntax alone entirely. No rewrites, no warnings. **Good for:** when you just need the noise to stop right now. **Downside:** mixed syntax sticks around forever if you never come back to it. ### Option 2 — Clean it up properly, separately ```json { "rules": { "color-function-notation": "modern" } } ``` Set it to `"modern"` and do one isolated cleanup PR — just this, nothing else mixed in. Audit your SCSS before running auto-fix. **Good for:** when you want consistency and have time to do it properly. **Downside:** needs some prep work. Don't just flip it and run. ### Option 3 — Scope it with `overrides` ```json { "overrides": [ { "files": ["**/*.scss"], "rules": { "color-function-notation": null } } ] } ``` Keeps the rule active for CSS, disables it for SCSS only. More precise than a global disable and way cleaner than scattering `/* stylelint-disable */` comments across your whole project. **Good for:** when you want enforcement on CSS but your SCSS theming files need to be left alone. **Downside:** bit more config, but honestly manageable. ### What we did Went with `null`. Stopped the noise, unblocked the team the same day. Will come back with a proper cleanup PR when things settle down. One thing at a time. ## If it's happening on every save locally Check VS Code before you go debugging your pipelines. The Stylelint extension has this: ```json "stylelint.autoFixOnSave": true ``` When that's on, `--fix` runs silently every single save. Seen teams spend a long time pointing fingers at CI when it was their own editor config the whole time. ## How to know if this is your issue - Color changes showing up in diffs nobody made - PR reviews catching `rgba` → `rgb` changes out of nowhere - Weird rendering after running `stylelint --fix` Check your `.stylelintrc`, `.stylelintrc.json`, or `stylelint.config.js` for `color-function-notation`. And check your extended presets too — it might not even be in your own config. ## tl;dr Stylelint auto-fix on an inconsistent codebase will rewrite things you didn't ask it to rewrite. The `color-function-notation` rule is one of the quieter offenders because the change it makes — `rgba` to `rgb` — is easy to overlook. Check your config, check your presets, and don't run auto-fix blind. --- *I write about frontend problems from real projects — follow if that's useful.* *If this helped, drop a ❤️ — it helps with visibility.* *Connect with me:* - *LinkedIn: [Sanket Bhor](https://linkedin.com/in/yourlinkedinhandle)* - *Website: [sanketbhor.dev](https://sanketbhor.dev)*