Breaking Change: Change @import to @use sass feature

.changeset/odd-actors-deliver.md

@@ -0,0 +1,5 @@
+---
+"@primer/css": major
+---
+
+Breaking Change: Change @import to @use sass feature

DEVELOP.md

@@ -18,7 +18,7 @@ Here's what you need to know about how the files are structured in both git and
 - When published, all of the files in `src/` are "hoisted" to the package root so that you can import, say, utilities with:
 
   ```scss
-  @import '@primer/css/utilities/index.scss';
+  @use '@primer/css/utilities' as utilities;
   ```
 
 - All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with `../`), so everything should work fine as long as the `@primer/css` directory is in one of your Sass include paths (i.e. `node_modules`).

README.md

@@ -43,15 +43,15 @@ npm install --save @primer/css
 The included source files are written in [Sass] using SCSS syntax. After [installing](#install) with npm, you can add your project's `node_modules` directory to your Sass [include paths](https://github.com/sass/node-sass#includepaths) (AKA [load paths](http://technology.customink.com/blog/2014/10/09/understanding-and-using-sass-load-paths/) in Ruby), then import it like this:
 
 ```scss
-@import "@primer/css/index.scss";
+@use "@primer/css" as primer;
 ```
 
 You can import individual Primer modules directly from the `@primer/css` package:
 
 ```scss
-@import "@primer/css/core/index.scss";
-@import "@primer/css/product/index.scss";
-@import "@primer/css/marketing/index.scss";
+@use "@primer/css/core" as primer-core;
+@use "@primer/css/product" as primer-product;
+@use "@primer/css/marketing" as primer-marketing;
 ```
 
 ## Development

docs/stories/GettingStarted.mdx

@@ -28,7 +28,7 @@ Here's what you need to know about how the files are structured in both git and
 - When published, all of the files in `src/` are "hoisted" to the package root so that you can import, say, utilities with:
 
   ```scss
-  @import '@primer/css/utilities/index.scss';
+  @use '@primer/css/utilities' as utilities;
   ```
 
 - All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with `../`), so everything should work fine as long as the `@primer/css` directory is in one of your Sass include paths (i.e. `node_modules`).
@@ -57,25 +57,25 @@ sass:
 It's best practice to import all of this scss into one file, usually named `index.scss`. From this file you'll import one or more Primer CSS bundles and any other custom code you write.
 
 ```scss
-@import '@primer/css/core/index.scss';
+@use '@primer/css/core/index.scss';
 // These files live in the same directory as the index file.
-@import './custom-1.scss';
-@import './custom-2.scss';
+@use './custom-1.scss';
+@use './custom-2.scss';
 ```
 
 Here's an example of how it might look if you installed only a few Primer CSS components with some custom variable overrides. The `$blue` uses the default primer blue in the text utilities, then the new blue in `"custom-that-uses-primer-variables.scss"` and `.foo`.
 
 ```scss
-@import '@primer/css/utilities/index.scss';
-@import 'primer-buttons/index.scss';
+@use '@primer/css/utilities/index.scss';
+@use 'primer-buttons/index.scss';
 
 // Import color variables for custom code
-@import 'primer-support/index.scss';
+@use 'primer-support/index.scss';
 
 // Override default blue
 $blue: #0000ff;
 
-@import './custom-that-uses-primer-variables.scss';
+@use './custom-that-uses-primer-variables.scss';
 
 .foo {
   background: $blue;

script/dist.js

@@ -87,7 +87,7 @@ function getExternalImports(scss, relativeTo) {
   const dir = dirname(relativeTo)
   // XXX: this might *seem* fragile, but since we enforce double quotes via
   // stylelint, I think it's kosher.
-  scss.replace(/@import "(.+)\/index\.scss";/g, (_, dep) => {
+  scss.replace(/@use "(.+)\/index\.scss";/g, (_, dep) => {
     imports.push(join(dir, dep))
   })
   return imports

src/autocomplete/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/autocomplete/index.scss";
+@use "@primer/css/autocomplete/index.scss";
 ```
 
 ## Build

src/autocomplete/index.scss

@@ -1,3 +1 @@
-// support files
-@import '../support/index.scss';
-@import './suggester.scss';
+@use './suggester.scss';

src/autocomplete/suggester.scss

@@ -1,5 +1,6 @@
 // Needs refactoring
 // stylelint-disable selector-max-type, selector-no-qualifying-type
+@use '../support/index.scss' as *;
 
 .suggester {
   position: relative;

src/avatars/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/avatars/index.scss";
+@use "@primer/css/avatars/index.scss";
 ```
 
 ## Build

src/avatars/avatar-parent-child.scss

@@ -1,3 +1,4 @@
+@use '../support/index.scss' as *;
 // .avatar-parent-child is when you see a small avatar at the bottom right
 // corner of a larger avatar.
 //

src/avatars/index.scss

@@ -1,5 +1,3 @@
-@import '../support/index.scss';
-
 // Avatars
-@import './avatar-parent-child.scss';
-@import './circle-badge.scss';
+@use './avatar-parent-child.scss';
+@use './circle-badge.scss';

src/base/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/base/index.scss";
+@use "@primer/css/base/index.scss";
 ```
 
 ## Build

src/base/base.scss

@@ -1,4 +1,6 @@
 // stylelint-disable selector-max-type, selector-no-qualifying-type, primer/typography
+@use '../support/index.scss' as *;
+
 * {
   box-sizing: border-box;
 }

src/base/index.scss

@@ -1,7 +1,6 @@
-@import '../support/index.scss';
-@import './native-colors.scss';
-@import './normalize.scss';
-@import './base.scss';
-@import './kbd.scss';
-@import './typography-base.scss';
-@import './octicons.scss';
+@use './native-colors.scss';
+@use './normalize.scss';
+@use './base.scss';
+@use './kbd.scss';
+@use './typography-base.scss';
+@use './octicons.scss';

src/base/kbd.scss

@@ -1,5 +1,6 @@
 // Keyboard shortcuts
 // stylelint-disable selector-max-type
+@use '../support/index.scss' as *;
 
 kbd {
   display: inline-block;

src/base/native-colors.scss

@@ -1,5 +1,6 @@
 // color-scheme
 // Enables color modes for native elements
+@use '../support/mixins/color-modes.scss' as *;
 
 @include color-mode(light) { color-scheme: light; }
 

src/base/normalize.scss

@@ -1,5 +1,6 @@
 // stylelint-disable
 /*! normalize.css v4.1.1 | MIT License | github.com/necolas/normalize.css */
+@use '../support/index.scss' as *;
 
 /**
  * 1. Change the default font family in all browsers (opinionated).

src/base/typography-base.scss

@@ -1,6 +1,8 @@
 // Headings
 // --------------------------------------------------
 // stylelint-disable selector-max-type
+@use '../support/index.scss' as *;
+
 h1,
 h2,
 h3,

src/box/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/box/index.scss";
+@use "@primer/css/box/index.scss";
 ```
 
 ## Build

src/box/box-overlay.scss

@@ -1,3 +1,5 @@
+@use '../support/index.scss' as *;
+
 .Box--overlay {
   // stylelint-disable-next-line primer/responsive-widths
   width: 448px;

src/box/index.scss

@@ -1,2 +1 @@
-@import '../support/index.scss';
-@import './box-overlay.scss';
+@use './box-overlay.scss';

src/branch-name/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/branch-name/index.scss";
+@use "@primer/css/branch-name/index.scss";
 ```
 
 ## Build

src/branch-name/branch-name.scss

@@ -1,4 +1,5 @@
 // stylelint-disable selector-max-type, selector-no-qualifying-type
+@use '../support/index.scss' as *;
 
 // A nice way to display branch names inside the UI. Can be a link or not.
 

src/branch-name/index.scss

@@ -1,3 +1,2 @@
 // support files
-@import '../support/index.scss';
-@import './branch-name.scss';
+@use './branch-name.scss';

src/buttons/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/buttons/index.scss";
+@use "@primer/css/buttons/index.scss";
 ```
 
 ## Build

src/buttons/button-group.scss

@@ -2,6 +2,7 @@
 //
 // A button group is a series of buttons laid out next to each other, all part
 // of one visual button, but separated by rules to be separate.
+@use '../support/index.scss' as *;
 
 .BtnGroup {
   display: inline-block;

src/buttons/button.scss

@@ -1,4 +1,5 @@
 // stylelint-disable selector-max-type, no-duplicate-selectors
+@use '../support/index.scss' as *;
 
 // Base button styles
 .btn {

src/buttons/index.scss

@@ -1,4 +1,3 @@
-@import '../support/index.scss';
-@import './button.scss';
-@import './button-group.scss';
-@import './misc.scss';
+@use './button.scss';
+@use './button-group.scss';
+@use './misc.scss';

src/buttons/misc.scss

@@ -1,4 +1,5 @@
 // stylelint-disable selector-max-type
+@use '../support/index.scss' as *;
 
 // Link-like buttons
 //

src/color-modes/index.scss

@@ -1,11 +1,11 @@
 // All themes
 
-@import './themes/light.scss';
-@import './themes/light_colorblind.scss';
-@import './themes/light_high_contrast.scss';
-@import './themes/light_tritanopia.scss';
-@import './themes/dark.scss';
-@import './themes/dark_dimmed.scss';
-@import './themes/dark_high_contrast.scss';
-@import './themes/dark_colorblind.scss';
-@import './themes/dark_tritanopia.scss';
+@use './themes/light.scss';
+@use './themes/light_colorblind.scss';
+@use './themes/light_high_contrast.scss';
+@use './themes/light_tritanopia.scss';
+@use './themes/dark.scss';
+@use './themes/dark_dimmed.scss';
+@use './themes/dark_high_contrast.scss';
+@use './themes/dark_colorblind.scss';
+@use './themes/dark_tritanopia.scss';

src/color-modes/themes/dark.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/dark';
+@use '@primer/primitives/dist/css/functional/themes/dark';

src/color-modes/themes/dark_colorblind.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/dark-colorblind';
+@use '@primer/primitives/dist/css/functional/themes/dark-colorblind';

src/color-modes/themes/dark_dimmed.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/dark-dimmed';
+@use '@primer/primitives/dist/css/functional/themes/dark-dimmed';

src/color-modes/themes/dark_high_contrast.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/dark-high-contrast';
+@use '@primer/primitives/dist/css/functional/themes/dark-high-contrast';

src/color-modes/themes/dark_tritanopia.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/dark-tritanopia';
+@use '@primer/primitives/dist/css/functional/themes/dark-tritanopia';

src/color-modes/themes/light.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/light';
+@use '@primer/primitives/dist/css/functional/themes/light';

src/color-modes/themes/light_colorblind.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/light-colorblind';
+@use '@primer/primitives/dist/css/functional/themes/light-colorblind';

src/color-modes/themes/light_high_contrast.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/light-high-contrast';
+@use '@primer/primitives/dist/css/functional/themes/light-high-contrast';

src/color-modes/themes/light_tritanopia.scss

@@ -1 +1 @@
-@import '@primer/primitives/dist/css/functional/themes/light-tritanopia';
+@use '@primer/primitives/dist/css/functional/themes/light-tritanopia';

src/core/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/core/index.scss";
+@use "@primer/css/core/index.scss";
 ```
 
 ## Build

src/core/index.scss

@@ -5,21 +5,16 @@
  * Released under MIT license. Copyright (c) 2019 GitHub Inc.
  */
 
-// Global requirements
-@import '../support/index.scss';
-
-// Color modes
-
 // Core modules
-@import '../base/index.scss';
-@import '../box/index.scss';
-@import '../buttons/index.scss';
-@import '../table-object/index.scss';
-@import '../forms/index.scss';
-@import '../layout/index.scss';
-@import '../navigation/index.scss';
-@import '../pagination/index.scss';
-@import '../tooltips/index.scss';
+@use '../base/index.scss' as base;
+@use '../box/index.scss' as box;
+@use '../buttons/index.scss' as buttons;
+@use '../table-object/index.scss' as table-object;
+@use '../forms/index.scss' as forms;
+@use '../layout/index.scss' as layout;
+@use '../navigation/index.scss' as navigation;
+@use '../pagination/index.scss' as pagination;
+@use '../tooltips/index.scss' as tooltips;
 
 // Utilities always go last so that they can override components
-@import '../utilities/index.scss';
+@use '../utilities/index.scss' as utilities;

src/docs.scss

@@ -9,9 +9,9 @@
 // Only meant for the docs at https://primer.style/css
 
 // CSS color variables
-@import './color-modes/index.scss';
+@use './color-modes/index.scss' as color-modes;
 
 // Global requirements
-@import './core/index.scss';
-@import './product/index.scss';
-@import './marketing/index.scss';
+@use './core/index.scss' as core;
+@use './product/index.scss' as product;
+@use './marketing/index.scss' as marketing;

src/forms/README.md

@@ -10,7 +10,7 @@ generated: true
 Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
 
 ```scss
-@import "@primer/css/forms/index.scss";
+@use "@primer/css/forms/index.scss";
 ```
 
 ## Build

src/forms/form-control.scss

@@ -1,3 +1,4 @@
+@use '../support/index.scss' as *;
 // Needs refactoring
 // stylelint-disable selector-no-qualifying-type, selector-max-compound-selectors
 // stylelint-disable selector-max-type

src/forms/form-group.scss

@@ -1,5 +1,6 @@
 // stylelint-disable selector-max-compound-selectors
 // stylelint-disable selector-max-type
+@use '../support/index.scss' as *;
 
 // Form groups
 //

src/forms/form-select.scss

@@ -1,6 +1,8 @@
 // Custom select
 //
 // Apply `.select` to any `<select>` element for custom styles.
+@use '../support/index.scss' as *;
+
 .form-select {
   display: inline-block;
   max-width: 100%;