[SIP-37] Proposal to implement CSS-in-JS using Emotion 👩‍🎤

[SIP-37] Proposal to implement CSS-in-JS using Emotion 👩‍🎤

Motivation

Superset has been built with React components utilizing a few layers of styling. Most components are build using React-Bootstrap (v0.31), which is in turn built on Bootstrap 3. Bootstrap 3 is built using LESS, and is themed/overridden in Superset with Bootswatch and a Bootswatch theme called Cosmo, also built with LESS. At this point, efforts have been made to consolidate styling with LESS variables, and cleaning up use of LESS styles throughout the codebase, but some key problems remain:

1. Upgrading to newer versions of Bootstrap and/or React-Bootstrap are non-trivial, as they require migration to SASS from LESS.
2. Current Cosmo/Bootswatch themes, and indeed many of the custom styles elsewhere, will not be compatible with upgraded Bootstrap/React-Bootstrap
3. Most importantly, the development experience in customizing and styling components is difficult. Changing existing styles can have unexpected fallout in unintended views/components. It’s also difficult to track down all the existing styles affecting any given component, which may be scattered in a number of different LESS files.

Migrating to CSS-in-JS accomplishes a few goals:

• Organizes code’s separation of concerns by component, rather than by language
• Allows simpler and cleaner implementation of an atomic design system
• Allows variants triggered by props (e.g. <Button primary> or <Card small>)
• Simplifying, segmenting, or removing LESS usage over time, simplifying the codebase (particularly in deprecating Bootswatch/Cosmo)
• More robust theming capabilities
• Component library agnostic
• Snapshot serializers for CSS testing
• Typescript support
• Provides an easier path to restyle React-Bootstrap, and/or upgrade it!

Proposed Change

In short, the plan is to implement components using Emotion. This can be done immediately for new components with no fallout to the existing codebase, but can also be extended to wrap or rewrite existing components in the interest of modernizing old code and libraries.

Further implementation details below.

New or Changed Public Interfaces

N/A

New dependencies

Emotion and various submodules - MIT License babel-plugin-emotion - MIT License emotion-ts-plugin - MIT License jest-emotion - MIT License

Migration Plan and Compatibility

The plan to move toward Emotion-styled components would take the following path:

1. Coping/migrating LESS variables (colors, font sizes, etc) to JS based theme file, and provide it to all components in the React component tree via Emotions ThemeProvider HOC. This will lead to duplication of these variables, but this is temporary.
2. Create all styles for NEW components using Emotion, either with their CSS prop using “object styles”, the styled pattern using “tagged template literals”, or the useTheme hook.

To extend this idea toward deprecating Bootswatch/Cosmo, and eventually upgrading React-Bootstrap, the following approach may be used:

1. Migrating React-Bootstrap based components into similarly named wrapper components, and applying custom styles and theme variables as needed to shape the atomic component toward the target design(s). Here’s a sketch of how a wrapped React-Bootstrap button might look, with some arbitrary custom styles illustrating prop and theme usage.

/** @jsx jsx */

import styled from '@emotion/styled';
import { withTheme } from 'emotion-theming';
import {
    Button as React_Bootstrap_Button,
    // @ts-ignore
  } from 'react-bootstrap';

const Button = styled(React_Bootstrap_Button)`

  font-family: ${(props) => props.theme.font-family};
  border-radius: ${(props) => props.theme.borderRadius};
  background-color: ${props => props.primary ? props.theme.colors.primary : props.theme.colors.secondary};

  a {
    padding: 0;
    opacity: 0.8;
    &:active {
      opacity: 1;
      border: 2px solid ${(props) => props.theme.colors.secondary.light2};
    }
  }
`;

export default withTheme(Button);

1. Wherever possible, migrate LESS styles from Cosmo/Bootswatch/custom styles, and put it into atomic components.
2. When LESS code has been sufficiently migrated into Emotion components, delete Cosmo theme and Bootswatch files (hooray!)
3. When all React-Bootstrap imports/usages have migrated to Superset-owned Emotion-styled components, it should be possible to upgrade React-Bootstrap and make relatively minor/straightforward changes to correct any unexpected style changes.

In the event of an emergency involving support or implementation of Emotion, it should be fairly straightforward to migrate to Styled-Components as an optional ejection path. They follow the same patterns.

Rejected Alternatives

• Styled Components - The leading package, and the leading competition to Emotion. Downsides are that it is larger, less performant (they’re addressing this), and that it doesn’t (yet) support sourcemaps. The scale of this community is the largest, so it may be warranted to swtich to this in the future, which at this point is relatively trivial.
• JSS - Popular, but that seems to be in large part due to its use in Material UI. It doesn’t seem to provide selling points that outweigh the features, ease of use, and emerging patterns provided by Emotion (and Emotion-like) libraries
• Glamorous - Follows similar patterns to Emotion/Styled-Components. The founder has officially recommended that users switch to Emotion (over Styled-Components) and has provided a codemod to do so.
• Aphrodite, Radium, Styletron - These (and others) provide plenty of feature overlap in their CSS-in-JS approaches, but seem lacking in OSS adoption and community support.

[kristw]

Just want to add another long-term benefit I see from using css-in-js is avoiding dead css code. Currently it is very difficult to check if a css rule is ever used at all. With css-in-js and proper linting, we could get rid of unused rules more confidently and naturally.

[rusackas]

@etr2460 For the css prop (using object styles), Emotion uses the csstype package under the hood to check for valid CSS properties and values. There’s a pragma to add at the top of the file for this to work (unless using babel plugin, apparently).

For the styled(someElement)`...` syntax, it lets you type props, and checks their validity.

The docs/examples on the matter here explain it more eloquently than I can 😃