[CSS-in-JS] Starting simple usage docs

[cchaos]

Some quick docs to get us started with defined examples to test.

Checklist

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_4558/

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_4558/

[cchaos]

@thompsongl I'm thinking we should get these starter docs in sooner rather than later so that subsequent updates to the context will also update these examples showing how it changes.

[cchaos]

I had to ignore these because TS complains that the custom keys don't exist.

[thompsongl]

You need to tell useEuiTheme that the custom keys exist:

const [theme] = useEuiTheme<{colors: {
  customColorPrimaryHighlight: string;
  customColorPrimaryText: string
}}>();

[cchaos]

Is there a way to do that on creation of the modifications instead of usage?

[thompsongl]

Unfortunately, no. A given useEuiTheme doesn't/can't have enough knowledge about which provider it's accessing to be able to infer any extensions. This is mostly a limitation of how React context works.
If we want typed, autocomplete-ready theme variables for the base EUI theme, then we have to do this extra step to get extensions to work also.

[thompsongl]

I'd imagine that if an app is planning on extending the theme and wants to use it in many places, they could create a wrapped hook to hide the details:

const useExtendedEuiTheme = () => {
  const [theme, colorMode, modifications] = useEuiTheme<{colors: {
    customColorPrimaryHighlight: string;
    customColorPrimaryText: string
  }}>();
  return [theme, colorMode, modifications];
}

[cchaos]

K, then I'm just going to leave the ts comments in for now to see if we can address a bit better.

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_4558/

[thompsongl]

I'm good merging this in its current state and with the one change noted in my earlier comment.
Any alterations can happen in subsequent PRs to the feature branch as parts get added or refactored.