Add section about documenting magic numbers
- Dominant language
- No language data
- Stars
- 24
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
@spaceninja wrote this in a PR comment thread about why we prefer to convert "magic numbers" into variables. We should add a section rephrasing this to the CSS Guide:
> Magic numbers in CSS files are a mystery. Why is it this particular value? What happens if I change it? Does it match anything else?
> Turning your magic numbers into variables or custom properties is a form of documentation and safety checks:
> By naming your number, you help explain what it means. $touch-target-size tells you at a glance what the number means and opens the door to reuse elsewhere.
> It's also a form of safety check — if you set this value here and then it also gets used somewhere else but both locations are hard-coded, then a future dev doesn't know they need to update both if we want those sizes to match.
> Thus, as a general practice, unless we have good reason, we convert almost all values to variables, custom properties, or design tokens.
> Sometimes you really do have a special one-off magic number. "The component is sized at 137px wide because that's the only size that looks good". In those cases, when you don't need to reuse the value, then a descriptive comment explaining the source of the magic number is sufficient.
> But in general, coming across a magic number with an unclear meaning and source is a red flag in a CSS file.
> In almost every instance, I have found that what felt arbitrary made more sense when converted to a standard design token that already exists, or by documenting it so it could be reused.
> In this case, your magic number is a very good one that can and should be reused elsewhere — minimum touch target size! That's a great case for making a design token, or at least a variable.
Contributor guide
Assessment
This issue has not been assessed yet.