Merge pull request #7055 from alphagov/bk-replace-import-with-use-contributing

Update contributing docs for sass modules

Author: domoscargin

docs/contributing/coding-standards/components.md

@@ -11,8 +11,8 @@ Generally, folder and file names should be singular, for example ‘accordion’
 When creating your component, you should create the following files in the component’s folder:
 
 - `README.md` - Summary documentation with links to the installation instructions and component documentation on <https://design-system.service.gov.uk/>
-- `_[component-name].scss` - An SCSS file to generate the styles for this component only. It delegates the CSS generation to the \_index.scss file.
-- `_index.scss` - The actual styles for the component that you can import in 2 ways - [on their own using `[component-name].scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css) or [alongside other components in `components/_index.scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css)
+- `_index.scss` - The main Sass entry point for the component. Generates the styles by including the mixin from the `_mixin.scss` file. You can include `_index.scss` [on its own](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css), or [alongside other components in `components/_index.scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css)
+- `_mixin.scss` - The actual styles for the component, contained within a mixin. The `_index.scss` file includes the mixin. You should not include the `_mixin.scss` file directly.
 - `[component-name].yaml` - Lists the component's Nunjucks macro options and includes examples using these options. Both the options and examples are used to generate component documentation in the review app. The examples are also used to test component behaviour, and to generate [fixtures for testing alternative implementations of the design system](https://frontend.design-system.service.gov.uk/testing-your-html/).
 - `macro.njk` - The main entry point for rendering the component. It provides a `govuk[ComponentName](params)` macro, delegating render to the `template.njk` file
 - `template.njk` - The template used for rendering the component using any `params` provided to the macro
@@ -24,6 +24,11 @@ If your component uses JavaScript, you must also create the following files in t
 - `[component-name].unit.test.mjs` - Unit tests to verify any component-specific lower-level logic.
 - `[component-name].test.js` - Functional tests to verify the behaviour of the whole component
 
+In version 7 of GOV.UK Frontend, we'll remove support for `@import` in Sass. Before then, you must include the following files to continue supporting `@import`:
+
+- `_[component-name].import.scss` - An import-only SCSS file to generate the styles for just this component. It delegates the CSS generation to the `_index.import.scss` file, and emits a warning that this usage is deprecated.
+- `_index.import.scss` - An import-only SCSS file which generates the styles by including the mixin from the `_mixin.scss` file.
+
 ## Building your components
 
 To help you build and initialise your own JavaScript components, GOV.UK Frontend provides some of its internal features for you to reuse. Follow our guidance on [building JavaScript components](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#building-your-own-javascript-components) to use these features.

docs/contributing/coding-standards/css.md

@@ -1,8 +1,36 @@
-# CSS Style Guide
+# CSS and Sass Style Guide
+
+## Sass modules
+
+GOV.UK Frontend supports both `@import` and `@use` to include Sass files.
+
+Our public API is prefixed with `govuk-` to ensure consistent naming and avoid
+clashes with Sass elements in your application. You should `@use` govuk-frontend
+modules without a namespace:
+
+Bad:
+
+```scss
+@use "foo";
+
+.bar {
+  color: foo.govuk-function("baz")
+}
+```
+
+Good:
+
+```scss
+@use "foo" as *;
+
+.bar {
+  color: govuk-function("baz")
+}
+```
 
 ## Class naming convention
 
-## `govuk` namespacing
+### `govuk` namespacing
 
 All class names start with a `.govuk-` namespace to reduce the likelihood of
 conflicting with existing classes in your application. It also helps to identify
@@ -11,7 +39,7 @@ where the styling for a particular element is coming from.
 If you are building components for your own application or framework you should
 use a different prefix, for example `.app-` or the initials of your department.
 
-## Block Element Modifier (BEM)
+### Block Element Modifier (BEM)
 
 GOV.UK Frontend uses the Block Element Modifier (BEM) methodology when naming
 CSS classes. This is designed to help developers understand how the different
@@ -300,7 +328,7 @@ margin: 1px 2px 3px;
 Bad:
 
 ```scss
-@import 'foo';
+@use 'foo';
 
 $govuk-font-family-gds-transport: 'GDS Transport', arial, sans-serif;
 
@@ -312,7 +340,7 @@ $govuk-font-family-gds-transport: 'GDS Transport', arial, sans-serif;
 Good:
 
 ```scss
-@import "foo";
+@use "foo";
 
 $govuk-font-family-gds-transport: "GDS Transport", arial, sans-serif;
 
@@ -323,20 +351,20 @@ $govuk-font-family-gds-transport: "GDS Transport", arial, sans-serif;
 
 ### Files should always have a final newline
 
-### The basenames of `@import`ed SCSS partials should not begin with an underscore and should not include the filename extension
+### The basenames of `@use`ed SCSS partials should not begin with an underscore and should not include the filename extension
 
 Bad:
 
 ```scss
-@import "_foo.scss";
-@import "_bar/foo.scss";
+@use "_foo.scss";
+@use "_bar/foo.scss";
 ```
 
 Good:
 
 ```scss
-@import "foo";
-@import "bar/foo";
+@use "foo";
+@use "bar/foo";
 ```
 
 ### Properties should be formatted with a single space separating the colon from the property's value

packages/govuk-frontend/src/govuk/tools/_exports.scss

@@ -24,7 +24,7 @@ $govuk-imported-modules: () !default;
 ///
 /// @param {String} $name - Name of module - must be unique within the codebase
 /// @content The passed content will only be outputted if a module of the same
-///   $name has not already been outputted
+///   $name has not already been outputted. Use only with `@import`, not `@use`.
 /// @access public
 
 @mixin govuk-exports($name) {