The PR lines up a toolbar with mt-[13px], gap-[18px], and p-[22px]. The theme already has a spacing scale — --space-2, --space-3, --space-4, or the Tailwind steps the team already uses. The new numbers are close. They are not on the scale, and the next agent will invent another set.
I’ve started treating a magic spacing value as a draft, not as a token. If 18px is visually right, the review question is which existing step it should be, and only then whether the scale itself needs a new step.
Why the magic numbers show up
The model copies a screenshot or a Figma pixel value and pastes it as an arbitrary utility or a literal in CSS. Arbitrary values feel precise. They also bypass the scale that keeps typography, cards, and form rows aligned.
A stack of near-miss values (12px, 13px, 14px) is harder to tighten later than one slightly loose token.
A simple spacing policy
- Margin, padding, and gap use the existing spacing scale
- No arbitrary pixel utilities (
mt-[13px],gap: 18px) in feature CSS - A new step is a token change, named and documented, not a one-off in a leaf component
- Do not “kern” a single screen with values the rest of the app does not use
Paste the scale into the prompt when the agent is doing layout. In review, search the diff for [Npx], bare px in margin and padding, and spacing literals that are not CSS variables or scale utilities.
What to put in the prompt
Use the existing spacing scale only (space-1 through space-8 / the standard Tailwind spacing steps we already use).
Do not add arbitrary pixel margin, padding, or gap values.
If a screenshot uses 18px and the nearest step is 16px, use the step and note the difference.
If you believe a new step is required, propose the token; do not invent a magic value in this file.
Reject / send back
Reject
- Arbitrary
mt-[13px]/gap-[18px]in a feature file - A new spacing token used only by one toolbar
- Mixing scale utilities and raw pixels in the same stack
- “Pixel-perfect” adjustments that ignore the scale
Accept
- Layout that uses existing spacing tokens or utilities
- A documented choice of the nearest step, even if Figma was one pixel off
- A token PR that adds a named step and uses it in the new layout
