Bugzilla

When we were first adding space token variables we considered adding comments next to them to indicate approximate px values (4px, 8px, 16px, etc.), but thought it might be too misleading since we use `rem` units that can vary depending on platform / user preferences for font size. After using the tokens for a while though it turns out developers are finding the names and calculations a bit hard to parse, especially since Figma designs tend to surface px values based on a 4px scale. Instead of a developer looking at a Figma mockup that uses 8px for padding and having to figure out that the probably want  `--space-small: calc(2 * var(--space-xsmall))` because our base font-size in content is 15px and `2 * 0.267 * 15 = 8.01` it would be much nicer if we provided handy comments alongside the variables - like this:

```css
/** Space **/
--space-xxsmall: calc(0.5 * var(--space-xsmall));   /* 2px */
--space-xsmall: 0.267rem; /* 4px */
--space-small: calc(2 * var(--space-xsmall)); /* 8px */
--space-medium: calc(3 * var(--space-xsmall)); /* 12px */
--space-large: calc(4 * var(--space-xsmall)); /* 16px */
--space-xlarge: calc(6 * var(--space-xsmall)); /* 24px */
--space-xxlarge: calc(8 * var(--space-xsmall)); /* 32px */
```

We support comments in `design-tokens.json` (e.g. [here](https://searchfox.org/mozilla-central/rev/5da13af5e6be251b70e994c8b4bd35fb5271f1e3/toolkit/themes/shared/design-system/design-tokens.json#151)). The tokens may be added on the line above so TBD if we want to sort through figuring out how to add inline comments or if just having any kind of comment will add the clarity we need for devs trying to map from Figma to design tokens.

When we were first adding space token variables we considered adding comments next to them to indicate approximate px values (4px, 8px, 16px, etc.), but thought it might be too misleading since we use `rem` units that can vary depending on platform / user preferences for font size. After using the tokens for a while though it turns out developers are finding the names and calculations a bit hard to parse, especially since Figma designs tend to surface px values based on a 4px scale. Instead of a developer looking at a Figma mockup that uses 8px for padding and having to figure out that the probably want  `--space-small: calc(2 * var(--space-xsmall))` because our base font-size in content is 15px and `2 * 0.267 * 15 = 8.01` it would be much nicer if we provided handy comments alongside the variables - like this:

```css
/** Space **/
--space-xxsmall: calc(0.5 * var(--space-xsmall)); /* 2px */
--space-xsmall: 0.267rem; /* 4px */
--space-small: calc(2 * var(--space-xsmall)); /* 8px */
--space-medium: calc(3 * var(--space-xsmall)); /* 12px */
--space-large: calc(4 * var(--space-xsmall)); /* 16px */
--space-xlarge: calc(6 * var(--space-xsmall)); /* 24px */
--space-xxlarge: calc(8 * var(--space-xsmall)); /* 32px */
```

We support comments in `design-tokens.json` (e.g. [here](https://searchfox.org/mozilla-central/rev/5da13af5e6be251b70e994c8b4bd35fb5271f1e3/toolkit/themes/shared/design-system/design-tokens.json#151)). The tokens may be added on the line above so TBD if we want to sort through figuring out how to add inline comments or if just having any kind of comment will add the clarity we need for devs trying to map from Figma to design tokens.