• Status: Accepted
• Author: Tony Braasch
• Deciders: Abyss Team
• Date: 06/03/2024

Context

Stitches, the current style library within the Abyss web component library, is no longer maintained. This necessitates a replacement to ensure continued support and improvements. The new style library needs to be robust, well-supported, and ideally require minimal refactoring of existing code.

Decision

The decision is to replace Stitches with Emotion as the foundational style library for Abyss web.

Consequences

Pros

• Emotion is well-supported and actively maintained, ensuring longevity and access to updates.
• Allows for runtime custom styling using existing css and styled tools.
• Alignment with mobile provides the following advantages:
  • Ability to leverage existing code to more quickly conform the current styled tool to the Stitches API.
  • Continued alignment with token strategy and tooling.
• Emotion's API provides the base tools which, along with some refactoring of our current styled and css tools and ThemeProvider, can deliver a semi-seamless experience for internal and external migration.

Cons

• Although Emotion states it's SSR compatible, SSR implementations can vary by platform and version (eg NextJS 12,13, Express, etc..). Therefore, thorough testing in target platforms will be necessary.
• Additional work required to refactor styled, css, ThemeProvider, and token handling to conform with the current API. Relatively speaking, this should be minimal.

Alternatives Considered

Panda

Pros

• Performance benefits and SSR compatibility due to build time CSS.
• Very similar to the Stitches API, resulting in much less refactoring of the internal code.

Cons

• Build time only, necessitating a runtime system for custom styling by users.

CSS Modules

Pros

• Performance benefits and SSR compatibility due to build time CSS.
• No reliance on any third-party libraries.

Cons

• Build time only, necessitating a runtime system for custom styling by users.
• Requires substantial internal and external refactoring.

Implementation Overview

• Install Emotion within the Abyss web component library.
• Refactor ThemeProvider to use the Emotion theme provider.
• Refactor the styled tool to handle variants, compound variants, and dynamic styling.
• Make any necessary updates to conform with our token API.
• Migrate components to new Emotion styled and css compatible tools.
• Thoroughly test components to identify any styling deviations. For instance, component selectors currently require usage of the @emotion/babel-plugin, and after adding the plugin during the POC, it still wasn't performing as expected, so we may decide not to support this going forward. Anecdotally, usage of component selectors by our Abyss users appears to be minimal.
• Document any issues found that require changes in the current styling configurations passed into either styled components or usage of the css prop and any potential consumer-required updates to the ThemeProvider. This will be used for migration documentation.
• Determine release plan:
  • Currently, a "V2 in V1" approach (shipping the old and the new in the same version of the library) seems most appropriate, as it will be challenging to ensure with 100% certainty that this update won't break some teams' custom styling. We'll advise customers to turn on tree-shaking in their apps, so the code they do not use does not increase their bundle size.
  • Provide clear migration guides and support for teams transitioning from Stitches styled/css/ThemeProvider tools to the Emotion compatible versions.

Note: Many of these steps are well on their way to completion. Here is a link to the branch that encapsulates the work that's been completed thus far during the POC.

Future Considerations

• Conduct thorough testing of Emotion's SSR capabilities to confirm its suitability.

References

• Emotion documentation

Revision History

• 06/03/2024: Initial draft created based on the evaluation of alternatives and the decision to adopt Emotion.