Calcite-components: Docs: Document CSS variables

[driskull]

Description

Document the CSS variables we would like to expose for users to be be able to overwrite.

These could be documented in each component and the more global ones could be documented in a section on storybook using a markdown file and an .mdx file.

Which Component

All components. Can start with variables that are common to all and more basic variables like color, font, etc and work toward styling

Background

The ArcGIS JS API currently allows theming via Sass but is looking to use calcite components within their widget and allow styling without Sass using CSS variables.

Resources

N/A

[caripizza]

It looks like Stencil may be able to do this for us in the component .scss files:
https://stenciljs.com/docs/docs-json#css-variables

[driskull]

Nice, yes lets do that.

[jcfranco]

Moving to the 5/24-6/7 sprint. cc @caripizza

[jcfranco]

@asangma Is this on your radar for this sprint?

[asangma]

@jcfranco I won't be able to get to this for the 6/7 sprint.

[asangma]

@jcfranco I need to get up to speed on Storybook.js so I think this won't be done in this sprint.

[jcfranco]

@asangma I think for this one we need to first determine which ones are the global CSS vars. Those would get a Storybook MDX page (e.g. https://raw.githubusercontent.com/Esri/calcite-components/master/src/1-introduction.stories.mdx). We also need to decide what will be the best way to doc these. I guess the simplest would be a markdown table for each CSS var group where we list the vars and their purpose:

### Global Category/Group

| CSS custom property    | Description    |
|------------------------|----------------|
| --calcite-some-prop    | what it do     |
| --calcite-another-prop | what it do too |

Secondly, any component-level CSS vars would only need a custom Stencil @prop --calcite-some-var: what it do JSDoc tag entry (see @caripizza's comment above https://github.com/Esri/calcite-components/issues/1097#issuecomment-841327765). On a related note, are these ready to be exposed or should we focus on the global ones for now?

[driskull]

Lets let this issue focus on the global ones and we can create individual issues for components.

[caripizza]

@jcfranco @driskull I can doc the CSS properties from each component stylesheet over in #2241 if that's helpful. I like the idea of using this issue to doc the global vars. (Adam and I are working on getting those added for our next developer docs update.)

[asangma]

LOL! I just saw the last couple comments here.
I started on some tables similar to what you suggest @jcfranco.

[asangma]

I've also had a chat with @bstifle about _broadly_ documenting the font size usage in different scales.
Note: I am updating files for the Storybook but I'm guessing this info would likely go on Developers yeah?

[macandcheese]

Yep, I would suspect we eventually have a more comprehensive "theming" page on the Developers site that provided these css vars, and maybe some live updating components to see the result (similar to Storybook). We could even have a few custom themes we use as samples across our examples, something Material does a great job at in their usage examples.