Docs should never reference CSS values, only token names

[bennypowers]

Docs pages currently reference CSS values. After all the work we've done to prepare and release our design system tokens, we should encourage designers and developers to use them at all times, and not directly use their values. This would have many benefits for designers and developers alike:

• token values can change over time, so users would not need to constantly refer back to the docs, cross reference with token tables, then update their sources
• docs authors would not need to update the values in the docs when the tokens change, either
• when writing new docs, docs authors would not need to context-switch between designs (with hex values) and tokens tables, instead letting the machine do that work for them by simply referencing the token names listed in the docs
• much of the work of documenting which tokens are used and for what could be automated
• referring to tokens by name rather than by value would encourage users to use the tokens rather than simply copy/pasting the values: increased exposure and usage would lead to more consistent UX and DX

for example, on Accordion's style page, we have this table:

Property	Light theme	Dark theme
Color - panel header	#F2F2F2	#292929

Instead, we should have

Property	Light theme	Dark theme
Color - panel header	--rh-color-surface-lighter	--rh-color-surface-dark-alt

Taking this idea a step further, our markdown sources should not have to manually update these tables, but we should be able to generate them from a list of token names, perhaps with each name associated with a per-file description. Maybe something like this:

- | Property {style="width: 33%" } | Light theme {style="width: 33%" } | Dark theme |
- | ------------------------------ | --------------------------------- | ---------- |
- | Color - panel header           | `#F2F2F2`                         | `#292929`  |
+ {% tokenTable variant="context", tokens=[{
+    name: 'Color - panel header',
+    light: '--rh-color-surface-lighter',
+    dark: '--rh-color-surface-dark-alt',
+ ]} %}

WDYT @coreyvickery?

[zeroedin]

As talked about in Office hours, I like this idea.

I had a similar conversation with @nikkimk and @Nouveau with the general idea of not using #hex code values which may change instead using and linking to the tokens data which would always be up to date single source of truth.

This PR was part of that extended conversation which started in the coffee shop in Pittsburgh. This extends from that idea of pulling that data from tokens and not having the values in the raw HTML.

[coreyvickery]

@bennypowers @zeroedin Yes, let's do this idea.