feat!: Consolidate Grid Space and Component Space into one set of spacing tokens

[VincentSmedinga]

Describe the pull request

What

• Removes the Grid Space tokens, replacing:
  • var(--ams-space-grid-sm) with var(--ams-space-lg)
  • var(--ams-space-grid-md) with var(--ams-space-xl) while changing its value from 48 to 56.
  • var(--ams-space-grid-lg) with var(--ams-space-2xl); this is a new token
  • The other options weren’t in use
• Removes tokens for gap and margin; their utility classes can use the space tokens directly.
• Makes space tokens for Compact Mode responsive again to save more space on mobile phones. The value for var(--ams-space-xl) has also changed here, from 32 to 36.
• Adds 4 space tokens that use one size in narrow windows and another on wide ones. This is what we needed to ensure the Grid can take its space on large screens, while not using so much screen space on small screens. It also removes the incorrect coupling between this kind of white space and the grid gaps. Changing one for the better always made the other worse, but these custom pairs seem the correct modelling for the difference in responsive behaviour that has always been there in the background. An advantage of these pairs is also that they reuse existing spacing lengths instead of introducing new ones.
• This also addresses the problem where Grid Space seemed too small on mobile. Vertical space around grids is now 27 instead of 16, and horizontal is 27 as well, instead of 24.
• I think having 27px whitespace between the grid’s content and the edges of the screen (at 320 pixels wide, so it’s around 30 on actual phones) is the best compromise between keeping enough horizontal room for the content and communicating our spacious branding.
• Updates the documentation accordingly.

To help understand how the values changed, here are screenshots from the new (left) and previous (right) token tables, for Spacious (above) and Compact mode (below):

Why

This is meant to make our spacing system easier to use. Many people find it confusing to have both ‘grid spacing’ and ‘regular spacing’. It also lets us set the gap between components without needing separate grid cells.

Usually, choosing a size between xs and xl will be sufficient for most people.

If they think they need one of the custom pairs, which are a bit more complex, knowing that they range between existing spacing lengths will help them understand.

How

n/a

Checklist

Before submitting your pull request, please ensure you have done the following. Check each checkmark if you have done so or if it wasn't necessary:

• Add or update unit tests
• Add or update documentation
• Add or update stories
• Add or update exports in index.* files
• Start the PR title with a Conventional Commit prefix, as explained here.

Additional notes

• n/a

[VincentSmedinga]

I’m not sure we still need these three options – 50%, 100% or 150% of a grid gap as padding above or below it. I think we can just keep the medium value, like we do for horizontal (inline) padding.

If people want more than a grid gap of whitespace below something, they can add a bottom margin through or .ams-mb-* utility classes.

This is also the only place where the ams.space.xl-2xl custom pair is used, so if we remove small and large block padding, we can also remove one custom pair space token.