Update documentation for $govuk-assets-path

[wilsond-gds]

Related documentation

Content at https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#if-you-have-your-own-folder-structure regarding overriding default variables in SASS.

Suggestion

@use wants you to explicitly show which default variables you are overriding; @import is much less strict. I found in order to change the assets path, our team’s code needed to use the new syntax:

@use '../../../node_modules/govuk-frontend/govuk/all' with (
$govuk-assets-path: '/public/'
);

I would imagine this pattern would be used for any default variables you’d want to override.

Evidence (where applicable)

See the SASS documentation on this.

[36degrees]

You should definitely be able to override $govuk-assets-path without needing to use @use – do you have a code example of what you were doing when using @import?

[wilsond-gds]

So if I do

// application.scss for 'my' stylesheet

$govuk-assets-path: '/custom-path/';
@use '../../../node_modules/govuk-frontend/govuk/all';

// then add a debug to the gov.uk all.scss file
@debug "value of assets path: #{$govuk-assets-path}";

The console reports node_modules/govuk-frontend/govuk/all.scss:11 Debug: value of assets path: /assets/

If I change 'my' stylesheet to

@use '../../../node_modules/govuk-frontend/govuk/all' with (
$govuk-assets-path: '/custom-path/'
);

The console reports node_modules/govuk-frontend/govuk/all.scss:11 Debug: value of assets path: /custom-path/.

The use of @use versus @import was already in the application.scss file, where we’re just adding a few extra styles to the design system defaults.

[36degrees]

Ah, that's helped me understand it, thank you.

So to summarise, the current documentation works for users importing using @import but if a team is using @use they'll need to pass the variables in as configuration instead?

All of our documentation does assume that users will be importing using @import even if they're using Dart Sass – is there a specific reason you need to use @use here?

[wilsond-gds]

So to summarise, the current documentation works for users importing using @import but if a team is using @use they'll need to pass the variables in as configuration instead?

It seems that way from my experience so far. It seems that this is the way SASS is going so that the global scope is used as little as possible.

All of our documentation does assume that users will be importing using @import even if they're using Dart Sass – is there a specific reason you need to use @use here?

Going back through the history of the repo I can see someone else on the team changed the SCSS from @import to @use – I checked with them and they went with @use as they knew it had better long-term support. I suppose keeping @use is more future proof?

[stevenjmesser]

@claireashworth to check on this with @36degrees.