diff --git a/.github/workflows/sass.yaml b/.github/workflows/sass.yaml index a5f5b78ddf..3881ec2c7e 100644 --- a/.github/workflows/sass.yaml +++ b/.github/workflows/sass.yaml @@ -38,12 +38,12 @@ jobs: - name: Run command run: | mkdir -p .tmp - time sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css + time sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css # Check output for uncompiled Sass - name: Check output run: | - ! grep "\$govuk-" .tmp/all.css + ! grep "\$govuk-" .tmp/index.css dart-sass-latest: name: Dart Sass v1 (latest) @@ -73,12 +73,12 @@ jobs: - name: Run command run: | mkdir -p .tmp - time sh -c 'echo "@import "\""govuk/all"\"";" | sass --stdin --quiet-deps --load-path=packages/govuk-frontend/src > .tmp/all.css' + time sh -c 'echo "@import "\""govuk/all"\"";" | sass --stdin --quiet-deps --load-path=packages/govuk-frontend/src > .tmp/index.css' # Check output for uncompiled Sass - name: Check output run: | - ! grep "\$govuk-" .tmp/all.css + ! grep "\$govuk-" .tmp/index.css # Node Sass v5.0.0 = LibSass v3.5.5 lib-sass: @@ -107,12 +107,12 @@ jobs: - name: Run command run: | mkdir -p .tmp - time node-sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css + time node-sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css # Check output for uncompiled Sass - name: Check output run: | - ! grep "\$govuk-" .tmp/all.css + ! grep "\$govuk-" .tmp/index.css # Node Sass v8.x = LibSass v3 latest lib-sass-latest: @@ -137,12 +137,12 @@ jobs: - name: Run command run: | mkdir -p .tmp - time node-sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css + time node-sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css # Check output for uncompiled Sass - name: Check output run: | - ! grep "\$govuk-" .tmp/all.css + ! grep "\$govuk-" .tmp/index.css ruby-sass: name: Ruby Sass v3.4.0 (deprecated) @@ -165,12 +165,12 @@ jobs: - name: Run command run: | mkdir -p .tmp - time sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css + time sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css # Check output for uncompiled Sass - name: Check output run: | - ! grep "\$govuk-" .tmp/all.css + ! grep "\$govuk-" .tmp/index.css ruby-sass-latest: name: Ruby Sass v3 (latest, deprecated) @@ -193,9 +193,9 @@ jobs: - name: Run command run: | mkdir -p .tmp - time sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css + time sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css # Check output for uncompiled Sass - name: Check output run: | - ! grep "\$govuk-" .tmp/all.css + ! grep "\$govuk-" .tmp/index.css diff --git a/CHANGELOG.md b/CHANGELOG.md index f9fe876ca2..66cff0bdec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,20 @@ We introduced this change in: - [#5499: Rename GOVUKFrontendComponentConfigurable, export ConfigurableComponent](https://github.com/alphagov/govuk-frontend/pull/5499) - [#5456: Refactor Accordion to extend from a GOVUKFrontendConfigurableComponent](https://github.com/alphagov/govuk-frontend/issues/5456) +### Deprecated features + +#### Importing Sass using `govuk/all` + +You'll see a warning when compiling your Sass if you import all of GOV.UK Frontend's styling via `govuk/all`. Importing using the `all` file is deprecated, and we’ll remove it in the next major release. + +In your import statements, use a trailing `/index` rather than `/all` to load GOV.UK Frontend's files: + +- `@import "govuk/index";` instead of `@import "govuk/all";`; + +You do not need `/index` at the end of each import path if you’re using Dart Sass, LibSass 3.6.0 or higher, or Ruby Sass 3.6.0 or higher. + +This change was introduced in [pull request #5518: Deprecate `govuk/all.scss` and only reference `govuk/index.scss` internally](https://github.com/alphagov/govuk-frontend/pull/5518). + ## v5.7.1 (Fix release) To install this version with npm, run `npm install govuk-frontend@5.7.1`. You can also find more information about [how to stay up to date](https://frontend.design-system.service.gov.uk/staying-up-to-date/#updating-to-the-latest-version) in our documentation. diff --git a/docs/contributing/coding-standards/components.md b/docs/contributing/coding-standards/components.md index 4277dfaeb2..7b24dc5ff8 100644 --- a/docs/contributing/coding-standards/components.md +++ b/docs/contributing/coding-standards/components.md @@ -12,7 +12,7 @@ When creating your component, you should create the following files in the compo - `README.md` - Summary documentation with links to the installation instructions and component documentation on - `_[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/_all.scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css) +- `_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) - `[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 diff --git a/packages/govuk-frontend-review/src/stylesheets/app.scss b/packages/govuk-frontend-review/src/stylesheets/app.scss index b0493b2c10..40a4c8ed53 100644 --- a/packages/govuk-frontend-review/src/stylesheets/app.scss +++ b/packages/govuk-frontend-review/src/stylesheets/app.scss @@ -4,7 +4,7 @@ $govuk-new-organisation-colours: true; $govuk-suppressed-warnings: ("organisation-colours"); -@import "govuk/all"; +@import "govuk"; @import "partials/app"; @import "partials/code"; @import "partials/banner"; diff --git a/packages/govuk-frontend-review/tasks/watch.mjs b/packages/govuk-frontend-review/tasks/watch.mjs index 6613a1e095..42f6f6bc3a 100644 --- a/packages/govuk-frontend-review/tasks/watch.mjs +++ b/packages/govuk-frontend-review/tasks/watch.mjs @@ -43,7 +43,7 @@ function getTasks(options) { ), 'compile:scss watch': () => gulp.watch( - ['**/*.scss', join(paths.package, 'dist/govuk/all.scss')], + ['**/*.scss', join(paths.package, 'dist/govuk/index.scss')], { awaitWriteFinish: true, cwd: options.srcPath, diff --git a/packages/govuk-frontend/package.json b/packages/govuk-frontend/package.json index 9f57449ca3..9ca4b53c16 100644 --- a/packages/govuk-frontend/package.json +++ b/packages/govuk-frontend/package.json @@ -4,7 +4,7 @@ "version": "5.7.1", "main": "dist/govuk/all.bundle.js", "module": "dist/govuk/all.mjs", - "sass": "dist/govuk/all.scss", + "sass": "dist/govuk/index.scss", "files": [ "dist", "govuk-prototype-kit.config.json", @@ -13,7 +13,7 @@ ], "exports": { ".": { - "sass": "./dist/govuk/all.scss", + "sass": "./dist/govuk/index.scss", "import": "./dist/govuk/all.mjs", "require": "./dist/govuk/all.bundle.js", "default": "./dist/govuk/all.bundle.js" diff --git a/packages/govuk-frontend/src/govuk/all.scss b/packages/govuk-frontend/src/govuk/all.scss index cbdb155959..b1072069f9 100644 --- a/packages/govuk-frontend/src/govuk/all.scss +++ b/packages/govuk-frontend/src/govuk/all.scss @@ -1 +1,7 @@ @import "index"; + +@include _warning( + "import-using-all", + "Importing using 'govuk/all' is deprecated. Update your import statement to import 'govuk/index'.", + $silence-further-warnings: false +); diff --git a/packages/govuk-frontend/src/govuk/all.unit.test.mjs b/packages/govuk-frontend/src/govuk/all.unit.test.mjs index aa237de637..d606a878a4 100644 --- a/packages/govuk-frontend/src/govuk/all.unit.test.mjs +++ b/packages/govuk-frontend/src/govuk/all.unit.test.mjs @@ -114,6 +114,20 @@ describe('GOV.UK Frontend', () => { } }) + it('outputs a warning when importing the "all" file at root', async () => { + const sass = ` + @import "all"; + ` + + await compileSassString(sass, sassConfig) + + expect(mockWarnFunction.mock.calls[0]).toEqual( + expect.arrayContaining([ + `Importing using 'govuk/all' is deprecated. Update your import statement to import 'govuk/index'. To silence this warning, update $govuk-suppressed-warnings with key: "import-using-all"` + ]) + ) + }) + it('outputs a warning for each layer that has an "all" file', async () => { const sass = ` /* equivalent to importing 'base' */ diff --git a/packages/govuk-frontend/tasks/build/package.unit.test.mjs b/packages/govuk-frontend/tasks/build/package.unit.test.mjs index 20d571d47d..6cb99d2fbe 100644 --- a/packages/govuk-frontend/tasks/build/package.unit.test.mjs +++ b/packages/govuk-frontend/tasks/build/package.unit.test.mjs @@ -109,8 +109,8 @@ describe('packages/govuk-frontend/dist/', () => { // Only sass package entry is compiled to minified CSS bundle .flatMap( - mapPathTo(['**/govuk/all.scss'], ({ dir: requirePath }) => [ - join(requirePath, 'all.scss'), + mapPathTo(['**/govuk/index.scss'], ({ dir: requirePath }) => [ + join(requirePath, 'index.scss'), // CSS bundle, minified join(requirePath, 'govuk-frontend.min.css'), @@ -163,6 +163,15 @@ describe('packages/govuk-frontend/dist/', () => { }) describe('Sass stylesheets', () => { + describe('index.scss', () => { + it('should compile without throwing an exception', async () => { + const file = join(paths.package, 'dist/govuk/index.scss') + await expect(compileSassFile(file)).resolves.not.toThrow() + }) + }) + + // all.scss is deprecated but we still want to make sure it works when used + // as the root for compilation describe('all.scss', () => { it('should compile without throwing an exception', async () => { const file = join(paths.package, 'dist/govuk/all.scss') diff --git a/packages/govuk-frontend/tasks/build/release.mjs b/packages/govuk-frontend/tasks/build/release.mjs index 12a25f8d74..aa6760af57 100644 --- a/packages/govuk-frontend/tasks/build/release.mjs +++ b/packages/govuk-frontend/tasks/build/release.mjs @@ -46,7 +46,7 @@ export default (options) => // Compile GOV.UK Frontend Sass task.name('compile:scss', () => - styles.compile('all.scss', { + styles.compile('index.scss', { ...options, srcPath: join(options.srcPath, 'govuk'), diff --git a/packages/govuk-frontend/tasks/build/release.unit.test.mjs b/packages/govuk-frontend/tasks/build/release.unit.test.mjs index 56dc8e1e76..42783d7a87 100644 --- a/packages/govuk-frontend/tasks/build/release.unit.test.mjs +++ b/packages/govuk-frontend/tasks/build/release.unit.test.mjs @@ -81,7 +81,7 @@ describe('dist/', () => { it('should contain relative paths to sources', () => { expect(sourcemap.sources).toContain( - '../packages/govuk-frontend/src/govuk/all.scss' + '../packages/govuk-frontend/src/govuk/index.scss' ) expect(sourcemap.sources).toContain( '../packages/govuk-frontend/src/govuk/core/_govuk-frontend-properties.scss' diff --git a/packages/govuk-frontend/tasks/styles.mjs b/packages/govuk-frontend/tasks/styles.mjs index 9bca8b8533..bf094f77c2 100644 --- a/packages/govuk-frontend/tasks/styles.mjs +++ b/packages/govuk-frontend/tasks/styles.mjs @@ -15,7 +15,7 @@ export const compile = (options) => * Compile GOV.UK Frontend Sass */ task.name('compile:scss', () => - styles.compile('all.scss', { + styles.compile('index.scss', { ...options, srcPath: join(options.srcPath, 'govuk'),