Add section about documenting magic numbers

[spaceninja]

@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.