Spacing scale: where do your spacing tokens live? (audit from the Rhythmguard benchmark)

[PetriLahdelma]

Spacing scale: where do your spacing tokens live? (audit from the Rhythmguard benchmark)

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 17efdf9 over packages/components/src. 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. The audit could not find a spacing token set here (it looks for --space-* / --spacing-* custom properties, Sass $spacer / $spacing-* variables and maps, or a Tailwind --spacing base), so it measured against a default 4px scale instead. Against that default it reported 2 literal values, a number that says more about my token discovery than about your CSS, so I am not treating it as a finding.

The ask. If you can point me at where the spacing scale is defined (a token file, a Sass map, a package), I will teach the tool to read it, re-run the audit on the real scale, and post the result here. If spacing is intentionally not on a scale, saying so is just as useful and I will mark the row that way.

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.

[mfal]

Thanks for this — and specifically for opening an issue instead of publishing a row you couldn't explain. The number you got (2) is almost exactly right, for reasons that have nothing to do with your token discovery. More on that below.

Where the scale lives

Source of truth: packages/design-tokens/src/size.yml, published as @mittwald/flow-design-tokens. Two parallel sets, same steps, different units:

size-px:            size-rem:
  xxxs: 1px           xxxs: 0.0625rem
  xxs:  2px           xxs:  0.125rem
  xs:   4px           xs:   0.25rem
  s:    8px           s:    0.5rem
  m:    16px          m:    1rem
  l:    24px          l:    1.5rem
  xl:   32px          xl:   2rem
  xxl:  64px          xxl:  4rem

8px base with 4px and 2px steps below it, plus a 1px hairline. rem for spacing that must stay proportional to text as the user scales font size, px for values that stay fixed (border widths, focus-ring offsets, inner padding). Both units are deliberate and both are the scale — a tool that assumes one unit per scale will see half of it.

style-dictionary compiles that to two things worth reading:

• dist/css/base.css → --size-px--* / --size-rem--* (double dash before the step name)
• dist/json-runtime/base.json → { "size-px": { "m": { "value": "16px", "path": ["size-px","m"] } }, … }

The JSON is the easier target. Your discovery missed it because the tokens are named size, not space/spacing — size covers spacing, control dimensions and border widths from one scale here, so spacing would have been the wrong name.

Docs: https://flow.mittwald.de/foundations/structure/spacing — and sorry, the site is German only. That is the same special orientation as below: we started in German because the audience was in-house and German-speaking. English is very likely to follow before long. The table on that page is readable either way.

The part that will change your measurement

Flow's SCSS almost never references the scale directly. It goes through a component-token layer — 75 category files like src/actions/button.yml — that resolves to it:

--button--padding-x: var(--size-px--m);

.button { padding-inline: var(--button--padding-x); }

In packages/components/src that's 10 spacing declarations pointing at --size-* directly against 230 pointing at a component token. So a literal-value check over the SCSS is measuring a layer where there is almost nothing to find — the discipline sits one level up, in the token definitions. The check that actually tests it: every spacing/padding/gap component token resolves to the scale — 133 of 133 in base.css, none with a raw value. If Rhythmguard could follow a var() chain to its root token, that would be the interesting audit here, and I suspect for other systems built the same way.

Your 2 literals are real

Both are in DateRangeInput.module.scss — padding-inline-end: 2px and padding-inline-start: 2px, nudging the react-aria date segments apart. On-scale (2px is xxs), just not through a token. A fair finding; we'll take it.

On the listing

Fine by us, with one thing worth knowing so the row isn't misread. Flow is public and anyone can install it, but it is not a general-purpose design system you adapt to your own brand. It is built for mStudio and for developers writing mStudio extensions, and the customization surface is deliberately thin: two themes, light and dark, off the same tokens, switched by a data-theme attribute. There is no brand-token layer to override. Base tokens are set with UX and are not a public extension point.

What is worth looking at is the concepts, and none of them are secret: the size scale doing double duty for spacing and dimensions, the rem/px split, the component-token indirection, and the remote-DOM layer that lets a sandboxed extension render real Flow components in the host. That is the part with something to say about DX.

Re-run it on the real scale whenever you like and post the numbers — happy to look at them. Thanks for building the thing and for the careful way you're rolling it out.

[PetriLahdelma]

Thank you for the detailed map and for the time it took to write it; it improved the tool in three places, and here are the numbers you asked for.

Re-run against the real scale. Reading @mittwald/flow-design-tokens/dist/css/base.css with a --size-(px|rem)-- pattern, the audit infers 0, 1, 2, 4, 8, 16, 24, 32, 64 px (the two unit sets collapse to one ladder, as they should) and finds 0 off-scale literals across the 130 stylesheets in packages/components/src. The two 2px values in DateRangeInput.module.scss are on scale and now show up only as token opportunities, which matches your reading exactly.

What changed on my side. @mittwald/flow-design-tokens is on the list of packages scale: "auto" reads when a project depends on it, with that name pattern, so a Flow consumer gets your scale with no configuration. Preparing this re-run also exposed a bug: a per-source tokenPattern in the audit's config file was being dropped; fixed today.

The var() chain audit is the right observation about systems built like Flow, and I have filed it as PetriLahdelma/stylelint-plugin-rhythmguard#110 with your description of the 133-of-133 check as the target. No promise on timing, but it is the next real capability.

Your row in the public table now reads "scale in @mittwald/flow-design-tokens", with no count until the benchmark can install dependencies. Nothing further needed from you; thanks again.