Sass Module Refactor

[joshblack]

This issue currently tracks our efforts refactoring our codebase to Dart Sass using Sass modules.

Components

• Accordion
• Breadcrumb
• Button
• Checkbox
• Code Snippet
• Combobox
• Content Switcher feat(ContentSwitcher): add ContentSwitcher to @carbon/styles #8862
• Copy Button
• Data Table @tay1orjones feat(data-table): add data-table to sass modules style package #8844
• Date Picker @tay1orjones feat(date-picker): move styles to sass modules #8895
• Dropdown
• File Uploader @tay1orjones feat(file-uploader): add FileUploader to @carbon/styles #8920
• Floating Menu
• Form
• Grid fix(css-grid): various bugfixes, first docs pass #8797
• Refactor Inline Loading to use Sass Modules #9027
• Link
• Listbox
• List
• Loading feat(InlineLoading): refactor InlineLoading to sass module #9030
• Menu @tay1orjones feat(menu): add Menu to @carbon/styles #8922
• Modal @tay1orjones feat(modal): add Modal to @carbon/styles #8923
• MultiSelect
• Notification fix(sass): notification refactor inline toast #9004
• Number Input
• Overflow Menu
• Pagination Nav Pagination Nav SASS Refactor #9068
• Pagination @jnm2377 feat(sass-modules): adds Pagination and Select styles and stories #8953
• Popover @dakahn
• Progress Bar Refactor ProgressBar to use Sass Modules #9075 @tw15egan
• Progress Indicator @jnm2377 feat(ProgressIndicator): add @carbon/styles #9022
• Radio Button @dakahn feat(Radiobutton): sass module refactor #8980
• Search @dakahn feat(search): sass module refactor #8967
• Select @jnm2377 feat(sass-modules): adds Pagination and Select styles and stories #8953
• Skeleton @jnm2377 Skeleton sass module refactor #9130
• Slider @sstrubberg feat(slider): sass refactor, added story #8981
• Structured List @sstrubberg feat(structured-list): sass module refactor #8931
• Tabs @sstrubberg
• Tag @dakahn
• Text area feat(TextArea): refactor TextArea to sass modules #9037
• Text Input @sstrubberg feat(text-input): storybook and carbon/styles #8988
• Tile Refactor Tile to use Sass Modules #9049 @tw15egan feat(Tile): sass module refactor #9054
• Time Picker feat(TimePicker): sass module refactor #9061 @tw15egan
• Toggle feat(Toggle): refactor Toggle to use sass modules #9026
• Toolbar @andreancardona fix(sass): notification refactor inline toast #9004
• Tooltip feat(Tooltip): sass module refactor #8982 @dakahn
• Tree View @andreancardona feat(unstable_treeview): sass refactor #9105
• UI Shell @jnm2377 UI Shell Sass module refactor #9129

[joshblack]

Links & Resources

• 2021 Release Proposals #7538 (comment)
• https://sass-lang.com/blog/the-module-system-is-launched
• https://css-tricks.com/introducing-sass-modules/
• https://sass-lang.com/documentation/at-rules/use
• https://sass-lang.com/documentation/at-rules/forward

[joshblack]

Reference

Migration process

• Find the component SCSS file from packages/components
• Create an _index.scss file for this component over in packages/styles/scss/components/<component>/_index.scss
• Copy over on the *.scss files, ignore the JS/HBS/md files for the most part, into this folder
• Update the _<component>.scss file with the following changes:
  • Remove the import-once import
  • Remove the exports mixin that is used
  • Update _index.scss to @use '<component>'; and include the mixin afterwards

@use 'example-component';

@include example-component.example-component;

• Update the imports of the file from @import to @use
  • css--reset -> utilities/component-reset
  • Duration tokens coming from _motion.scss and have a name change
  • rem and em helpers come from ../utilities/convert
  • carbon--spacing -> spacing
  • carbon--breakpoint -> breakpoint
  • Update tokens to use CSS Custom Properties
• Update scss/components/_index.scss entrypoint
• Update any calculations on tokens to use calc()

Common migrations

$prefix

+@use '../../config' as *;

type-style

+@use '../../type';

...

.#{$prefix}--component {
-  @include type-style('body-short-01');
+  @include type.type-style('body-short-01');
}

Button reset

-@import '../../globals/scss/helper-mixins';
+@use '../../utilities/button-reset';

Component reset

-@import '../../globals/scss/css--reset';
+@use '../../utilities/component-reset';

Tokens

-@import '../../globals/scss/vars';
+@use '../../theme' as *;

duration--* / component-tokens

-@import '../../globals/scss/vars';
@use '../../motion' as *;

...

.#{$prefix}--my-component {
-  transition: color $duration--fast-01 motion(standard, productive);
+  transition: color $duration-fast-01 motion(standard, productive);
}

helper mixins

-@import '../../globals/scss/helper-mixins';

// Focus outline
+@use '../../utilities/focus-outline' as *;

spacing

-@import '../../globals/scss/vars';
+@use '../../spacing' as *;

rem

+@use '../../utilities/convert' as *;