From an engineers perspective, whenever specifying colors from now on we should use the form:
```
color: rgb(var(--tone-red-500));
```
Please note:
- Use rgb. This lets us do this like rgb(var(--tone-red-500) / 10%) so we can use a 10% opacity red-500 if we ever need to whilst still making use of our color tokens.
- Use --tone-colorName-000 (so the prefix tone). Previously we could use a mix of --gray-500: $gray-500 (note the left hand CSS prop and right hand SASS var) for the things we need to theme currently. As we no longer use SASS we can't do --gray-500: --gray-500, so we now do --tone-gray-500: --gray-500.
Just for clarity after that, whenever specifying a color anywhere, use rgb and --tone. There is only one reason where you might not use tone, and that is if you never want a color to be affected by a theme (for example a background shadow probably always should use --black)
There are a 2 or 3 left for the code editor, plus our custom-query values
This commit uses docfy to isolate the individual parts and options and investigates the why you might use certain options and document how you might use certain options.
Originally we used a single %icon-definition CSS component to represent this, but seeing as some of them don't have icons, it didn't seem like the best name. So this PR splits this component into various different ones and then uses the new ones to continue to provide a now deprecated %icon-definition.
The component is currently a CSS only component that assumes a single (or multiple) description lists for its markup component, and provides for multiple different options (including a reversed mode which I'm still not totally sure about, but we don't use this right now anyway).
- %icon-definition
- %horizontal-kv-list
- %csv-list
- %tag-list
- %badge
