Kicking LibSass to the curb (and other stylish things)

[zarahzachz]

RFC: Kicking LibSass to the curb (and other stylish things)

Date : Oct 22, 2022
Author: @zarahzachz
Status : Review

Problem

Importing the provided SCSS files distributed by the design system is the recommended way for application teams to consume the design system's styles. And for teams to do that, they must have the same (or a compatible) version of LibSass, the Sass compiler used by the design system.

As of August 2020, LibSass was officially deprecated, with Sass recommending projects adopt Dart Sass instead. There is no simple upgrade path from LibSass to Dart Sass as Dart Sass is not backwards compatible.

This deprecation of LibSass gave us the opportunity to re-evaluate how the design system builds and provides its styles to consuming teams.

We considered four options:

1. Leave Sass in favor of a CSS-only solution
2. Leave Sass in favor of a CSS-in-JS solution
3. Do nothing
4. Upgrade to Dart Sass

👎 Leave Sass in favor of one of the following solutions:

Due to the incompatibility between LibSass and Dart Sass, we wanted to explore non-Sass alternatives to see if the design system could gain anything by switching.

CSS-only

A CSS-only solution would allow the design system to stop using Sass as a dependency entirely and distribute styles that are universal (CSS), which require no pre-processing.

Explorations in this space determined a CSS-only solution has limitations that would require additional plugins to resolve. It seemed silly to remove Sass just to recreate it with additional packages.

CSS-in-JS

CSS-in-JS is a pattern recommended by Storybook. You can read more details on this experiment here, but the tl;dr of it was that this was not a good solution to adopt.

👎 Do nothing

The design system's use of LibSass throws deprecation warnings, but it doesn't prevent teams from continuing to use the design system's styles.

However, because LibSass is no longer being maintained it lags behind Dart Sass in features and CSS compatibility. Using LibSass will also become a blocker for teams as the delta between the most up-to-date Node version and the Node version required for LibSass continue to grow.

Due to these concerns, doing nothing is not an option.

👍 Upgrade to Dart Sass

Dart Sass is the primary implementation of Sass and is not backwards compatible with LibSass. Therefore, to consider switching compilers, the design system will need to make several changes to how it builds and distributes its styles.

Despite the effort needed to accommodate Dart Sass, this was seen as the most workable solution; Adopting Dart Sass solves the LibSass deprecation problem without requiring a complex and complete overhaul of how the design system currently writes its styles.

Proposal

The design system will switch Sass compilers from LibSass to Dart Sass. To support this transition, the design system will need to make several changes to how it currently builds and distributes its styles to teams.

1. The design system will no longer distribute SCSS to teams

In order to reduce complexity for application teams and allow us to make build adjustments in the future without impacting them, we’re only going to be distributing pre-compiled CSS in the future.

Moving forward, application teams will use the design system's compiled CSS, available via CDN (for no-config fans) and npm. The CSS consumed will be a singular file, available in non-minified versions to provide code comments for additional documentation.

2. (Most) design tokens will be accessible via CSS custom properties

Currently, if teams need to overwrite specific Sass variables, they need to write Sass to do so (which requires a compiler). In having teams consume CSS, they can apply overwrites to CSS custom properties without the need of a compiler. It's just CSS.

It's worth noting only theme-defined tokens will be accessible.

Converting the design system's tokens to CSS custom properties will be part of the work associated with switching to Dart Sass.

3. Source SCSS files need to be cleaned up

Our SCSS files were written to support LibSass syntax and currently use outdated (or incorrect syntax). An effort will need to be made to clean these files to better align with Dart Sass and modern CSS syntax. Updating our source SCSS files will need to happen in this switch to Dart Sass.

• Resolve linting errors
• Removing @extend as it introduces specificity problems
• Removing functions (calc(), math.div, percent(), etc.) from SCSS files where static values would suffice, e.g. don't use calc() when the value isn't dynamic
• Consolidate SCSS sub-directories
• Review current use of SCSS utility functions, consolidate or remove as necessary
• Dart Sass has a change of syntax requiring the removal of @import in favor of @use

4. Update the design system documentation site

We want to make the transition to Dart Sass as transparent as possible. Therefore, we will be including detailed information on the change on our documentation site.

The "Getting started" section will need to be updated to include a migration guide, installation, CDN usage, and a CSS custom property reference guide. There will also be instructions on using the design system's CSS.

Changes will also need to be made throughout our documentation to reference CSS custom properties instead of Sass variables.

We're excited to implement these changes as we feel it'll provide design system users a more flexible and modern product in the future.