What

Allow the components package to be themed by its consumers

How

The components package would allow theming by exposing a few CSS variables (e.g "primary color", "text color", "background color", "border radius"...). The package would have default values for each variable, but any consumer of the package would be able to override those values.

These variables would be applied to all components in the package, regardless of how they are used within the editor. But given the nature of CSS and CSS variables, different overrides could be applied in different DOM subtrees (e.g the sidebar wrapper could set a different background colors from the navigation panel, etc etc).

Having the package expose its own variables (instead of using gutenberg-specific variables) would help to decouple the package from the rest of the editor, and make it more reusable.

Things to discuss / refine:

• Which variables should we exposed? Ideally for the first iteration, as least as possible
• How do we document these variables?
• Should the package have any concepts of dark/light themes? (personally I don't think so, as that would being a lot of extra complexity).

Action plan

• Introduce experimental Theme component Components: Try color theming #44668
• Storybook decorator Storybook: Add theme switcher tool #44715
• Components theming: use new accent color in every component  #45249
• Potentially look at more theme variables (background) Components: Add themeable background color #45466
• Investigate feasibility of automatically choosing a text color with enough contrast, given the background Components: Add themeable background color #45466
• Limit as much as possible the usage of the Theming APIs outside of the components package until they are ready
  • Making sure that the package doesn’t export anything related to its APIs (especially for WP Core releases) Theme component: Remove public export #46427
  • Potentially adding a console.warn when using about it not being ready for prod?
  • Stating it very clearly in README that it’s experimental (and potentially removing the relevant section from CONTRIBUTING) Theme component: Remove public export #46427
  • We can’t avoid CSS leaks (CSS variables will just cascade), but we could try to limit them as much as possible — i.e.:
    • by adding custom style lints to prevent usages of those variables outside of the components package Add stylelint rule to prevent theme CSS vars outside of wp-components #59020
    • by adding inline comments where the variables are declared
• Should the generated grayscale colors be desaturated a little?
• Is gray a good name for the theming variables? (see convo)
• Move away from static SASS functions (like lighten and rgba) which don't work with dynamic, runtime theme colors (see convo)
• Investigate what to do about components using Slot/Fill and portals in general (ie. Popover and components using Popovers that may want their popover content to be themed accordingly)
  • Including Tooltips
• Should we use hsl (and expose each color's component as a separate variable)? Should use OKLCH + polyfills?
• Search for remaining --wp-admin* css variables and see if we should something about it
• Deal with the @base-styles and @block-editor overrides
• Update contributing guidelines
• Add style lints to catch direct --wp-admin-theme-color usage in wp-components Components: Add stylelint rule for theme var regressions #58098 Components: Add eslint rule for theme var regressions #58130
• Semantically named variables or not?

Context

• Previous attempt: Add rudimentary theme support for Emotion components #36042
• Conversation Components: Retire LIGHT_GRAY color object #43994 (comment)