[Documentation] Add system level CSS Custom Property Documentation

[Westbrook]

Expected Behaviour

It's easy to understand and leverage system level CSS Custom Properties in an application that is composed of SWC elements.

Actual Behaviour

There is some component level documentation that is not the most productive as it doesn't map to static values at current.

Prior art

React Spectrum does a version of this in https://react-spectrum.adobe.com/react-spectrum/styling.html#dimension-values and https://react-spectrum.adobe.com/react-spectrum/styling.html#color-values that could stand as a reference.

[mephraim]

In particular, documentation for the color related variables would be useful for our team. We're building components that we'd like to be themable within Spectrum, so most of our colors are specified using the Spectrum CSS color variables.

[Westbrook]

Early thoughts lean toward building off of something like https://webcomponents.dev/edit/EIWbVqsSKu4TtpbPQm7b/src/index.ts where you can click each row to capture the CSS Custom Property (appropriate UX affordance, etc. TK, hand waves). The Spectrum docs use a UI like https://spectrum.adobe.com/page/color/ but the token can be quite long, so we'd likely want to rely on fewer columns for ease of consumption.

Questions:

• This only shows the token and the displayed color in each theme, how would you see wanting to use the actual color value in this experience? Spectrum switches between hex and RGB, but on a purely visual standpoint. Interested to hear if/how that was useful.
  • Kind of implies a done level 2 where you can do some sort of searching, but would want it to be useful if we were to invest in that way.
• This relies on the page level theme to switch the visible values, would you want to be able to manage that locally to the documentation, e.g. a picker that only effecting this list of colors?
• @mephraim is your team leveraging the scale tokens at all? And/or, would they want to?

[Westbrook]

Initial draft of what this might become: https://custom-props-docs--spectrum-web-components.netlify.app/custom-properties/

First thoughts:

• expand to all color themes (via sp-tabs or an sp-picker)
• we should probably stick to global properties for a first pass
• match this with a scales version?
• investigate the right way to surface alias colors. they likely need more description to clarify their usage.
• we know that Spectrum will be expanding the colors available in global in the next quarter or so. should we wait for that to publish something like this?

Extensions:

• support for search
• color relations mapping form Spectrum
• copy multiple to clipboard

[Westbrook]

This feels like a real nice way to make this happen for us... https://spectrum.corp.adobe.com/page/color-palette/#Latest-Spectrum-colors We should have just about all the components needed to build this now. Could be a good demo app for us to maintain for education purposes as well?

[najikahalsema]

I like that idea!