Spacing scale audit: 53 literal spacing values off your own token scale

[PetriLahdelma]

Spacing scale audit: 53 literal spacing values off your own token scale

Hi. I maintain stylelint-plugin-rhythmguard, a Stylelint rule that checks spacing values against a project's own scale. To keep it quiet on code I do not control, I run it against public design systems on pinned commits and publish the numbers. This repository is one of them, and I would rather you saw the audit here than in a report first.

What was run. npx rhythmguard audit . --scale auto at 12cb8b9 over scss. Hairlines of one pixel or less, percentages, and generated or test paths are excluded. Anyone can reproduce it in a checkout of that commit.

What it found. Scale 0, 4, 8, 16, 24, 48 inferred from your own spacing tokens in the stylesheets. 53 literal spacing values are off that scale.

• Values: .125rem ×9, .75rem ×8, 1.25rem ×8, 2rem ×6, 15px ×4
• Properties: padding ×22, margin-top ×9, margin ×4, margin-left ×4, padding-left ×3

Three values usually explain most of the count, and each is a single decision: a step the scale is missing, a slip, or a token nobody defined. A property table led by sibling margins often means the parent could own the spacing with gap.

The ask. Nothing is required. If the numbers are useful, I can open a small PR for the top value with before and after screenshots, or a one-rule Stylelint config at warning level that reports new off-scale values against your tokens and nothing else. If the findings are wrong for this codebase, tell me which ones; false positives are the most valuable report the tool gets and they change its defaults.

The row for this repository will appear in a periodic "State of Spacing" table in the Rhythmguard repository, with this issue linked. If you would rather not be listed, say so here and I will remove it.

Feel free to close this if it is not useful. Thanks for the CSS.

[bobby404-K]

Thanks for running this!

I went through the 53 values, and it looks like there are basically two cases here.

The recurring ones, like .75rem for button/pagination/toast padding and .125rem for form checks, seem intentional. I think those would probably be better as proper tokens rather than changing the values and potentially affecting the UI.

The ones in the docs SCSS look more like they’ve just drifted from the existing scale, so I think those can safely be moved to the nearest scale value.

I can put together a PR that handles it that way — clean up the docs SCSS and add named variables for the recurring values without changing how anything renders. If the preference is to stick to the scale strictly everywhere, I can go with that too.

Also happy to add the Stylelint rule. That seems like a good way to prevent these off-scale values from creeping in again.

[PetriLahdelma]

Thanks for taking the time to go through all 53; that split matches how I read them too. The recurring .75rem and .125rem are decisions, not drift, and whether they deserve names of their own is a question for the Bootstrap maintainers rather than for a linter. The docs SCSS values are the low-risk part.

Whether either of those becomes a PR, and whether a rule belongs in this repository's tooling, is for the maintainers to weigh; I would wait for their view before spending the effort. For what it is worth on the measurement side, the tool now reads $spacer and $spacers from scss/_variables.scss directly, so the 53 were counted against Bootstrap's own scale, not a default one.

[julien-deramond]

Thanks for the work on the Stylelint plugin and the corresponding PR. I’ve closed the associated PR because of #42911 (comment).

That doesn’t necessarily mean the findings are wrong (I haven’t checked all the details) but we won’t be changing the Sass files in v5. At this point, doing so could be breaking, and we’re also about to release v6 (currently in alpha). For the docs, it would take more effort to review and address everything than our current capacity allows, especially given that v5 will mostly remain as it is.

Maybe we could try running the plugin against the v6-dev branch instead to see what it discovers. Then, as you suggested, we can assess whether the findings are actual issues or intentional decisions.

I prefer to be transparent about this: I’m not sure when we’d be able to review the results in detail. There’s still a lot to do in the repo, and we’re working with a small core team.

[PetriLahdelma]

Thanks for the candid answer, and agreed on v5: nothing there is worth a breaking change.

I ran the audit against v6-dev at 5726523, using the $spacers map in scss/_config.scss as the scale (0 to 48px in thirteen steps).

Components (scss/, 119 files): 9 off-scale literals, down from 53 in v5. Five are .125rem and one is -.125rem (calendar, menu, form-range), one is .1rem in form validation, and two are 2px transform nudges (avatar, utilities API). The v6 ladder has no 2px step, so these are the whole list; everything that was .375rem or 1.25rem in v5 is now on scale because v6 added those steps. Whether 2px deserves a $spacers entry or stays a literal is your call; either way the component layer is clean.

Docs (site/src, 50 files): 30 literals, almost all in assets/examples (hero margins of 4rem, 5rem and 7rem, fixed px offsets in the sticky-footer and search examples) plus a handful of .125rem in the site SCSS. That is the low-priority pile bobby404-K identified, and I would leave it alone until v6 ships.

One note for my side rather than yours: v6 wraps the map in defaults(...), which my Sass reader did not unwrap, so I passed the scale by hand. That is fixed in the next release and I will keep the v6-dev row in the public benchmark so you can glance at it whenever there is capacity. Nothing further needed from you; thanks for your time.