Fully integrating vanilla Emotion as the canonical style system for CSS-in-JS in Gutenberg

[sarayourfriend]

Note: This issue has been updated significantly, please view the revision history for insight into what's changed!

This is the next step in fully ingrating Emotion as the canonical style system for Gutenberg.

Recently we made the decision to ditch the new custom style system for the following reasons:

1. It presented too many difficulties in upgrading Emotion to version 11
2. It implemented a custom iframe solution that diverged from Emotion's upstream solution
3. It potentially introduced too many new ways of doing things like themeing and CSS custom property management that would produce too many new public APIs
4. It would introduce a non-trivial maintenance burden on the Gutenberg core contributors

Because @youknowriad was able to figure out how to integrate the StyleFrame component using the methods from upstream Emotion for iframe support (thanks Riad!) we're able to fully commit to vanilla Emotion for the Gutenberg style system. This means we do not need a custom wrapper around it.

What are we losing by doing this?

Basically "base styles" which were styles that were being applied to each and every element produced by the style system. Practically this meant the ability to force all components to respect reduced motion automagically. I think we can figure out a solution around this using injectGlobal and adding it to the StyleProvider, but it's not a blocker, just something to call out.

Okay, so what are the next steps?

• Delete create-styles Remove create-styles in favor of vanilla emotion. #31048
• Update context to use vanilla emotion Components: Add component system context #30877
• Migrate already integrated ui components to vanilla emotion
  • Start with View which has a cascading effect of needing to handle all components created with createComponent and their dependencies, especially variable dependencies. Because we won't be importing from @wp-g2/styles anymore, the variables won't exist and we need to port them over to the COLORS and CONFIG constants from the existing style system in packages/components/src/utils. components: Use vanilla emotion for view #31099
  • Continue on with the various other components
    • Delete Button, ButtonGroup (we're ditching these implementations) components: Remove ui/button and ui/button-group #31205
    • Surface components: Remove wp-g2 from surface #31238
    • Scrollable components: Remove wp-g2 from scrollable #31207
    • Shortcut components: Remove wp-g2 imports from shortcut #31229
    • Portal, Popover, Card components: Remove G2 portal and refactor Popover to no longer use G2 #31209
    • Tooltip components: Remove wp-g2 from tooltip #31232
    • VisuallyHidden components: Remove wp-g2 imports from visually-hidden #31210
    • Elevation components: Remove wp-g2 imports from elevation #31230
    • Divider components: Remove wp-g2 imports from ui/divider #31212
    • FormGroup, ControlLabel components: Remove wp-g2 from form-group and control-label #31234
    • Flex, VStack, HStack components: Remove wp-g2 from flex, vstack, hstack, spinner and contr… #31243
  • Turn off FontSizePicker and delete it, reverting to the previous, non-g2 implementation components: Remove wp-g2 fontsize control #31287
  • Remove all remaining wp-g2 imports and remove the dependencies components: Remove all remenants of wp-g2 #31292
• Finish the FontSizePicker integration/finish migrating the components from Component System: Continue Integration #28399
  • Item/ItemGroup Components: Add ItemGroup and Item #30097
  • BaseField components: Add BaseField #32250
  • TextInput Components: Integrate TextInput component [WIP] #32381
    • Move utilities used by TextInput over
      • useControlledValue Add useControlledValue #33039
    • Move TextInput over
  • Dropdown
  • Slider (Blocked by TextInput)
  • SelectDropdown
  • Re-introduce the FontSizePicker'
• Add base styles to View and ensure all components use the View component for their base rendering
  • Fix shortcut not using View components: Fix Shortcut polymorphism #31555
  • Add base styles to View
  • Should we actually do this? View isn't the basis of the styled components so this will only cover a small set of components that would actually get the base styles. Should we just use injectGlobal to apply the base styles to * with an !important on the reduced motion ones?
• Upgrade components with their newer, G2 implementations
  • Flex components: Promote ui/Flex and deprecate isReversed prop #31297
  • Text components: Promote Text to full components export #31291
  • VisuallyHidden
    • Original PR: components: Promote VisuallyHidden from ui into full components #31244
    • Revert: Revert "components: Promote VisuallyHidden from ui into full components (#31244)" #31882
    • Fix (incoming)
    • Currently we're banking on the Emotion 11 Upgrade (immediately below) fixing the issues discovered in this PR: Revert "Revert "components: Promote VisuallyHidden from ui into full components (#31244)"" #31902. We're hoping that upgrading will fix the bugs we found where the css from emotion doesn't use the correct emotion cache.
• Upgrade Emotion to version 11 Upgrade to Emotion 11 #31476 Upgrade to Emotion 11 #32216
  • Blocked by an issue in preactjs/compressed-size-check Local dir is not clean up properly before switching to target branch preactjs/compressed-size-action#59
• Promote new components from components/src/ui into components/src and export them as experimental or unstable
  • VStack, HStack components: Promote VStack and HStack #31300
  • Heading components: Promote Heading #31299
  • Divider components: Promote Divider and use readable prop names #31556
  • View components: Promote View #31542
  • Grid components: Promote Grid #31559
  • Elevation components: Promote Elevation #31614
• Migrate new components
  • Separator components: Add Separator #31612 Separator is just a Divider with some default props, in that case... just use Divider.
  • ZStack components: Add ZStack #31613
  • Tag components: Add Tag #32214 (BLOCKED)
    • Add types to Icon components: Add types to Icon #32219
    • Add types to Tooltip (Blocked by Popover promotion)
    • Add types to Button
    • Finally, migrate Tag
  • Badge (BLOCKED by Tag, they both depend on the same background color utilties)
  • AspectRatio [Components]: Add AspectRatio #33603 - decided not to be implemented as there is native css support
  • Image
  • Avatar [Components]: Migrate Avatar #33488
  • SegmentedControl [Components]: Add SegmentedControl #31937
    • Fix the focus ring styles for this component
• Remove all remaining "next" component wrappers components: Remove all withNext wrappers #32205
• Decide what components should be uplifted and which should be replaced
• Replace components that need replacing
  • AccessiblePopover
    • Integrate AccessiblePopover
      • Replace the Card component with the new version from ui Components: update <Card /> implementation to g2 version #32243
        • Promote Surface Components: promote Surface #32439
        • Promote Scrollable Components: promote Scrollable #32446
        • Refactor folder structure: Card: refactor subcomponents folder structure #32557
        • Add types: Card: add types #32561
        • Update implementation to g2: Card: update to g2 implementation #32566
        • Update storybook: Card: update Storybook story #32763
        • Delete old g2 version: Card: delete old version of the g2 implementation #32764
      • Promote Popover Components: promote g2 Popover as Flyout #32197
    • Replace its usages
      • Dropdown
      • Tooltip
      • etc...
  • ColorPicker
    • Blocked by several other components needing to be migrated like TextInput
  • ...
• Uplift components that need uplifting
  • Button
  • Continue making decisions about what components need "uplifting"

Miscellaneous tasks

• Remove color and config utility functions and just use the COLORS and CONFIG objects directly
  • color Components: remove color() utility function, use values directly #31661
  • config Components: remove config() utility function, use values directly #31646
• Remove the implicit children prop from ViewOwnProps and add children to all components that need it explicitly rather than relying on the implicit definition. Components: require explicit children prop for all components #31817
• Remove the components/src/utils/space function and just use ui/utils/space. components: Remove duplicated space utilities #32852
• Rename ViewOwnProps to a clearer name like PolymorphicComponentProps Components: Rename ViewOwnProps to PolymorphicComponentProps #32053
• Allow components to declare that they are not polymorphic (like Divider for example). components: Allow for non-polymorphic components #32796
• Delete unused types from context/polymorphic-component.ts

Component uplifting tasks

• Soft deprecate the various isPrimary,isSecondary etc. props on Button in favor of a single variant prop. Button: deprecate isPrimary, isSecondary, isTertiary and isLink props in favour of variant prop #31713
• Hard deprecate props that were soft deprecated in Button: deprecate isPrimary, isSecondary, isTertiary and isLink props in favour of variant prop #31713 (plus the isPrimary key used in the notice component)
• Extract the Button parts of Button into a BaseButton or PrimitiveButton component that does not include the Tooltip stuff.

CSS-in-JS tasks

A list of high priority components to be refactored is tracked in #35744

• Convert components to CSS-in-JS
  • Add each component as it is converted to this list here
  • Button
  • ButtonGroup
  • Draggable
  • CheckboxControl
  • etc...

Context connecting tasks

A list of high priority components to be refactored is tracked in #35744

• Connect each component to the ui/context
  • Add each component as it is connected to this list
  • Button
  • ButtonGroup
  • etc..

Documentation tasks

• Update root @wordpress/components README.md to describe the structure of the package including the differences between primitive components (like Text) and composed components (like ColorPicker)
  • Create a tracking issue for documenting this Document @wordpress/components structure #33111
  • Document each component's type
  • Update each component's README.md with the new information
  • Update the root README.md with the general description of the component types and their implications

Deprecating `@emotion/css`

• Add an error for @emotion/css as a restricted import components: Restrict imports of @emotion/css #33051
• Start to remove usages of @emotion/css from the codebase and replace with @emotion/styled and @emotion/react
  • ZStack components: Remove @emotion/css from ZStack #33053
  • Divider components: Remove @emotion/css from Divider #33054
  • Spacer components: Remove @emotion/css from Spacer #33055
  • Surface
  • Text
  • Truncate
  • ControlGroup
  • ControlLabel
  • FormGroup
  • ItemGroup
  • BaseField
  • Card and its sub-components
  • Elevation
  • Flex

[gziolo]

Thank you @sarayourfriend for actively seeking better ways to integrate the new Component System. I think it makes perfect sense to try a bit different approach based on all the experience you collected when working on integration so far. In fact, it's closer to what I imagined in the early phase of planning. I hoped we can switch a few lower-level components to their revised implementation and bring all the necessary machinery to make them work with all the new features the that Component System brings. At that stage (#27484 (comment)), I wasn't aware of the limitation you listed but it only shows that the sooner you start integrating components the more you learn about the potential issues that should be addressed with higher priority.

I agree that #30509 is the most important blocker to resolve before we can start using some of the components that are already added to the @wordpress/components/ui folder 👍🏻

[jasmussen]

Question, as the new system is getting integrated, does it make sense to rename --wp-g2- prefix to simply --wp-, to match existing values?

[sarayourfriend]

Question, as the new system is getting integrated, does it make sense to rename --wp-g2- prefix to simply --wp-, to match existing values?

@jasmussen Yes I think ultimately that should be the goal. For now the new style system, as it is integrated, has the --wp-experimental prefix:

gutenberg/packages/components/src/ui/create-styles/create-style-system/constants.js

Line 4 in b53c5e5

export const NAMESPACE = '--wp-experimental';

[jasmussen]

I appreciate you clarifying that to me, thank you!

[sarayourfriend]

Note! I've updated the issue to reflect the current plan. Please review when y'all have time @mtias @gziolo @youknowriad. Thanks!

[gziolo]

Thank you for the update. It looks like everything is on track. 👍🏻

[ciampo]

Remove color and config utility functions and just use the COLORS and CONFIG objects directly

Opened #31661 and #31646

Deprecate the various isPrimary,isSecondary etc. props on Button in favor of a single variant prop.

Opened draft PR #31713

[sarayourfriend]

Migrating a G2 component into Gutenberg.

Helpful example PRs:

• components: Remove wp-g2 from scrollable #31207
• components: Remove wp-g2 imports from elevation #31230

The rough outline of the process is as follows

1. Copy the component from the g2 repo into packages/components/src/component-name (use kebab case for the folder)
2. Add the folder to components/tsconfig.json#includes
3. Rename the hook file to hook.ts and the component file to component.ts(x) and the styles file to styles.ts.
4. Update the imports to import cx and css from emotion.
5. Remove react imports and change them to be from @wordpress/element
6. Remove the ui.get usage and replace it with a combo of the COLORS and CONFIG objects (you can see an example of CONFIG in the Elevation PR I linked. COLORS is very similar)
7. Any other functions called off of ui that don’t currently have a utility in the Gutenberg repo need to have a utility created.
8. Move any functions imported from @wp-g2/utils directly into the Gutenberg repository under the ui/utils folder (like just copy them from G2 into GB)
9. Change @wp-g2/context imports to import from ui/context
10. Fix/add types if they’re missing (they almost certainly are missing, but you can find mostly complete Prop types by searching ComponentName.d.ts in the G2 repo). Also be sure to add the children type which is implicit in the G2 repository but needs to be explicit in the Gutenberg repository.

Usages of the ui.$ function can be completely removed. Usages of createToken need to be replaced with functions that return CSS based on the variables, similar to the Surface PR: #31238

[sarayourfriend]

Regarding base styles, I've added a new comment copied here for ease:

Should we actually do this? View isn't the basis of the styled components so this will only cover a small set of components that would actually get the base styles. Should we just use injectGlobal to apply the base styles to * with an !important on the reduced motion ones?

What do y'all think?

cc @ciampo @youknowriad

The goal is that we want reduced motion to be respected automagically, but maybe there's no way to do that and we just need to use the useReducedMotion hook everywhere 🤔 But I don't know how well that will work in CSS-in-JS as we don't want to depend on runtime changes 🤔 We should be able to apply the media query and potentially override animations if the environment variable is present to disable animations.

Overall just a little stuck thinking about this and curious what other people think.

[ciampo]

I may lack some perspective of the high-level strategy for the components package, but it makes sense to me that, whatever solution we may go for, we would be able to affect all components. Having implementation discrepancies in between components would make it quite hard to maintain and implement features effectively.

View isn't the basis of the styled components so this will only cover a small set of components that would actually get the base styles

Hopefully not a silly question, but — Can't we make changes so that all components are based on View? Would it be too complicated/disruptive?

[...] But I don't know how well that will work in CSS-in-JS as we don't want to depend on runtime changes 🤔 We should be able to apply the media query and potentially override animations if the environment variable is present to disable animations.

Wouldn't be able to wrap some CSS into a @media (prefers-reduced-motion) { ... } query without relying on the useReducedMotion hook's dynamic changes?

[sarayourfriend]

Hopefully not a silly question, but — Can't we make changes so that all components are based on View? Would it be too complicated/disruptive?

Not a silly question. All of the new components ultimately render a View of some sort, but along with that View they may render a styled component. I guess we could make the styled components all inherit from View (styled( View )`` for example) but that's not semantic Emotion in any way at all and it would make getting semantic elements out of styled more difficult (you'd have to pass the as prop rather than just calling off of styled).

Previously, when we were using our own wrapper around Emotion, we were able to make all styled components ultimately inherit from View, but that's not possible without the wrapper around Emotion generating our own custom styled object as far as I know.

Wouldn't be able to wrap some CSS into a @media (prefers-reduced-motion) { ... } query without relying on the useReducedMotion hook's dynamic changes?

As far as I understand it, the FORCE_REDUCED_MOTION environment variable doesn't affect the prefers-reduced-motion query at all, so we always have to check the FORCED_REDUCED_MOTION variable in order for it to work with e2e test expectations. Maybe that's an incorrect understanding though, @gziolo @youknowriad can you confirm this one way or the other? Does the env variable effect the media query?

[annezazu]

Closing this out as it appears much of this work has been completed or is no longer relevant today (it's been three years since last updated). Happy to reopen if that's incorrect!