[CSS-in-JS] Global theme

[cchaos]

This is a starting PR to work out the basic global theme object

Help

See outdated commentary

_I'll also comment about/point to these in the code._

1. I'm having some issues about where I'm using computed() and getting an error around 'getOwnPropertyDescriptor' like with the text variants if I try to pull them out of the theme.js file.
2. I can't seem to declare themes with buildTheme() outside of theme.js
3. color keys are getting removed/not outputting?
4. Can't seem to pass any values that aren't a number or string, like if we want an array
5. Trying to be efficient by mapping through arrays to create theme keys comes with some TS challenges
6. Can we use useEuiTheme in helper functions to get something like the current base value when computing other theme values?
7. Trying to just re-use a full object is not working. Like if the key is:

font.xs: {
  fontSize: computed();
  lineHeight: computed();
}

And I try to use it like this to spread those keys onto a new key, it doesn't work:

title.xs: {
  ...computed(
      [`${COLOR_MODE_KEY}.font.xs`],
      ([font]) => font
    ),
}

Discuss

COLOR_MODE_KEY

tl;dr: Using LIGHT and DARK keys at any level of nesting (#4643 (comment))

See outdated commentary

Can we get rid of having to specify [COLOR_MODE_KEY] which evaluates to colors in order to distinguish between light and dark theme values? Instead can the actual light and dark keys be those?

Before

const euiTheme = {
  [COLOR_MODE_KEY] = {
    light: {
      colors: {
        primary: '#hash'
      },
    },
    dark: {
      colors: {
        primary: '#hash'
      },
    }
  },
  size: {
    // This is nice because most likely isn't affected by light/dark mode, so you only have to specify once
  },
  focus: {
    // This is less so because instead of the consumer being able to just say `focus.background` they have to say `focus.colors.background`
    [COLOR_MODE_KEY] = {
      light: {
        background: computed('for light theme'),
      },
      dark: {
        background: computed('for dark theme'),
      },
    },
    size: {
      m: computed(),
    }
  }
};

Instead, it could be a top level key that either exists or doesn't (for single color mode)

const euiTheme = {
  light: {
    colors: {
      primary: '#hash'
    },
    size: {
      // This may not actually be affected by light/dark color mode, but it makes most sense as a creator of the theme and as a consumer to not have to split/create a `colors` key every time you want to adjust for light or dark mode
    },
    focus: {
      background: computed('for light theme'),
      size: {
        m: computed(),
      }
    }
  },
  dark: {
    colors: {
      primary: '#hash'
    },
    size: {
      // This may not actually be affected by light/dark color mode, but it makes most sense as a creator of the theme and as a consumer to not have to split/create a `colors` key every time you want to adjust for light or dark mode
    },
    focus: {
      background: computed('for dark theme'),
      size: {
        m: computed(),
      }
    }
  }
};

Or even better, just remove always check for light or dark at any nested level

const euiTheme = {
  colors: {
    light: {
      primary: '#hash',
    },
    dark: {
      primary: '#hash',
    },
  },
  size: {
    // This is nice because most likely isn't affected by light/dark mode, so you only have to specify once
  },
  focus: {
    // Internal components can specify light/dark even inside the key?
    background: {
      light: computed('for light theme'),
      dark: computed('for dark theme'),
    },
    size: {
      m: computed(),
    },
  },
};

Chakra uses hooks internally when creating the theme that would look something like this, though I'm not convinced this is the best approach or is able to work with computed values, just an example:

const euiTheme = {
  colors: {
    primary: useColorMode('#hashForLight', '#hashForDark'),
  },
  focus: {
    // This is certainly the most condensed/efficient way and most similar to our current SASS `lightOrDarkTheme()` function
    background: useColorMode('#hashForLight', '#hashForDark'),
    size: {
      m: computed(),
    },
  },
};

Global vs Component theme

We should limit the top level euiTheme to truly just the global tokens like color, size, type sizes, etc. Even things like euiFontWeightCode should be scoped to it's own theme.

Before:

const euiTheme = {
  colors: {
    primary: '#hash'
  },
  ...moreGlobals,
  button: {
    primary: {
      fill: computed(),
      color: computed(),
    },
    size: {
      m: computed(),
    }
  }
};

After:

const euiTheme = {
  colors: {
    primary: '#hash'
  },
  ...onlyGlobals,
};

// Only imported if consumers want to alter this specific "theme"
const euiButton = {
  primary: {
    fill: useEuiTheme(),
    color: useEuiTheme(),
  },
  size: {
    m: useEuiTheme(),
  }
}

Checklist Ignoring for now, will go through it all on the feature branch

[cchaos]

@thompsongl We talked through a bunch of these, but thought it would be helpful to point them out in the code for easier reference too.

[thompsongl]

See cchaos#44 for a concept on changing how colorMode keys work, and an update to allow dependecy-less computed methods.

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[thompsongl]

@cchaos Some unused variable files exist:

• _colors_vis.ts
• _z_index.ts
• title.ts

Do you have any later plans for them or should we remove them?

[thompsongl]

jenkins test this

[kibanamachine]

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

[kibanamachine]

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

[cchaos]

Yeah they're not used yet but I didn't want to lose this initial conversion work. Im ok to leave in.

[cchaos]

🥳 I'm happy with and approve the state of these global items and the docs. 😉

The only other thing I'd like to improve is somehow getting all the <h2>s on the global values page into the side nav.

But we can do a follow up for that.

[kibanamachine]

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

[kibanamachine]

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

[thompsongl]

🙀

[chandlerprall]

LGTM 👍