`@use` tools layer by domoscargin · Pull Request #6854 · alphagov/govuk-frontend

domoscargin · 2026-03-19T00:04:43Z

No description provided.

We'll repeatedly need to check these partials for compilation errors, so makes sense to centralise the functionality.

Supporting both `@import` and `@use` with these functions is tricky: - accessing global scope from within the module isn't straightforward - it muddies the function having to account for both things - when `@use`ing, we can't use a string as `govuk-font-url-function`, but we want to maintain this functionality for `@import` It felt simpler to split the two, though there may be a neater way to do this. Certainly, the fact that `@use` does not support strings will raise problems further down the line. For one, `@use` and `@import` output will diverge (in tests, at least).

github-actions · 2026-03-19T00:07:00Z

Other changes to npm package

diff --git a/packages/govuk-frontend/dist/govuk-prototype-kit/init.scss b/packages/govuk-frontend/dist/govuk-prototype-kit/init.scss
index f70666810..49c04e0bd 100644
--- a/packages/govuk-frontend/dist/govuk-prototype-kit/init.scss
+++ b/packages/govuk-frontend/dist/govuk-prototype-kit/init.scss
@@ -1,4 +1,4 @@
-@import "../govuk/tools/if";
+@use "../govuk/tools/if" as *;
 
 $govuk-prototype-kit-major-version: 0 !default;
 
diff --git a/packages/govuk-frontend/dist/govuk/core/_global-styles.scss b/packages/govuk-frontend/dist/govuk/core/_global-styles.scss
index f6b347003..468381be6 100644
--- a/packages/govuk-frontend/dist/govuk/core/_global-styles.scss
+++ b/packages/govuk-frontend/dist/govuk/core/_global-styles.scss
@@ -1,5 +1,5 @@
 @use "../settings/global-styles" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 @import "../helpers/links";
 @import "links";
diff --git a/packages/govuk-frontend/dist/govuk/core/_index.scss b/packages/govuk-frontend/dist/govuk/core/_index.scss
index 48bdbb747..1b11fe0b3 100644
--- a/packages/govuk-frontend/dist/govuk/core/_index.scss
+++ b/packages/govuk-frontend/dist/govuk/core/_index.scss
@@ -1,5 +1,5 @@
 @use "../settings/global-styles" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 @import "../helpers/links";
 @import "links";
diff --git a/packages/govuk-frontend/dist/govuk/core/_links.scss b/packages/govuk-frontend/dist/govuk/core/_links.scss
index 9e53bc678..b2920cbe7 100644
--- a/packages/govuk-frontend/dist/govuk/core/_links.scss
+++ b/packages/govuk-frontend/dist/govuk/core/_links.scss
@@ -1,6 +1,6 @@
 @use "../settings/links" as *;
 @use "../settings/measurements" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 @import "../helpers/focused";
 @import "../helpers/links";
diff --git a/packages/govuk-frontend/dist/govuk/core/_lists.scss b/packages/govuk-frontend/dist/govuk/core/_lists.scss
index 4f370c0a0..ee537dda1 100644
--- a/packages/govuk-frontend/dist/govuk/core/_lists.scss
+++ b/packages/govuk-frontend/dist/govuk/core/_lists.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 @import "../helpers/typography";
 
diff --git a/packages/govuk-frontend/dist/govuk/core/_section-break.scss b/packages/govuk-frontend/dist/govuk/core/_section-break.scss
index f418e8a86..3d88f1c2f 100644
--- a/packages/govuk-frontend/dist/govuk/core/_section-break.scss
+++ b/packages/govuk-frontend/dist/govuk/core/_section-break.scss
@@ -1,5 +1,5 @@
 @use "../settings/spacing" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 @import "../helpers/spacing";
 
diff --git a/packages/govuk-frontend/dist/govuk/core/_typography.scss b/packages/govuk-frontend/dist/govuk/core/_typography.scss
index cd9969f79..63fbbe2ca 100644
--- a/packages/govuk-frontend/dist/govuk/core/_typography.scss
+++ b/packages/govuk-frontend/dist/govuk/core/_typography.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 @import "../helpers/typography";
 
diff --git a/packages/govuk-frontend/dist/govuk/custom-properties/_breakpoints.scss b/packages/govuk-frontend/dist/govuk/custom-properties/_breakpoints.scss
index 22e19e5c7..caf0f7803 100644
--- a/packages/govuk-frontend/dist/govuk/custom-properties/_breakpoints.scss
+++ b/packages/govuk-frontend/dist/govuk/custom-properties/_breakpoints.scss
@@ -1,7 +1,7 @@
 @use "../settings/custom-properties" as *;
 @use "../settings/media-queries" as *;
-@import "../tools/exports";
-@import "../tools/px-to-rem";
+@use "../tools/exports" as *;
+@use "../tools/px-to-rem" as *;
 
 // CSS custom property for each breakpoint
 @include govuk-exports("govuk/custom-properties/breakpoints") {
diff --git a/packages/govuk-frontend/dist/govuk/custom-properties/_frontend-version.scss b/packages/govuk-frontend/dist/govuk/custom-properties/_frontend-version.scss
index c906f1d76..413923ce6 100644
--- a/packages/govuk-frontend/dist/govuk/custom-properties/_frontend-version.scss
+++ b/packages/govuk-frontend/dist/govuk/custom-properties/_frontend-version.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 
 // This custom property is automatically overwritten during builds and
 // releases. It doesn't need to be updated manually.
diff --git a/packages/govuk-frontend/dist/govuk/custom-properties/_functional-colours.scss b/packages/govuk-frontend/dist/govuk/custom-properties/_functional-colours.scss
index b20b69768..d6ada5c73 100644
--- a/packages/govuk-frontend/dist/govuk/custom-properties/_functional-colours.scss
+++ b/packages/govuk-frontend/dist/govuk/custom-properties/_functional-colours.scss
@@ -1,6 +1,6 @@
 @use "../settings/custom-properties" as *;
 @use "../settings/colours-functional" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/colour";
 
 // CSS custom properties for each functional colour
diff --git a/packages/govuk-frontend/dist/govuk/helpers/_font-faces.scss b/packages/govuk-frontend/dist/govuk/helpers/_font-faces.scss
index 0c0a718a1..5a184b9fb 100644
--- a/packages/govuk-frontend/dist/govuk/helpers/_font-faces.scss
+++ b/packages/govuk-frontend/dist/govuk/helpers/_font-faces.scss
@@ -2,7 +2,8 @@
 /// @group helpers
 ////
 
-@import "../tools/exports";
+@use "../tools/exports" as *;
+@use "../tools/font-url" as *;
 
 /// Font Face - GDS Transport
 ///
diff --git a/packages/govuk-frontend/dist/govuk/helpers/_media-queries.scss b/packages/govuk-frontend/dist/govuk/helpers/_media-queries.scss
index 073a33d1c..3ad1820b0 100644
--- a/packages/govuk-frontend/dist/govuk/helpers/_media-queries.scss
+++ b/packages/govuk-frontend/dist/govuk/helpers/_media-queries.scss
@@ -7,7 +7,7 @@
 @use "sass:string";
 
 @use "../settings/media-queries" as *;
-@import "../tools/px-to-em";
+@use "../tools/px-to-em" as *;
 
 // =========================================================
 // Helpers
diff --git a/packages/govuk-frontend/dist/govuk/helpers/_spacing.scss b/packages/govuk-frontend/dist/govuk/helpers/_spacing.scss
index e2b1784a4..1d3871c94 100644
--- a/packages/govuk-frontend/dist/govuk/helpers/_spacing.scss
+++ b/packages/govuk-frontend/dist/govuk/helpers/_spacing.scss
@@ -7,7 +7,7 @@
 
 @use "../settings/spacing" as *;
 
-@import "../tools/if";
+@use "../tools/if" as *;
 @import "../helpers/media-queries";
 
 /// Single point spacing
diff --git a/packages/govuk-frontend/dist/govuk/helpers/_typography.scss b/packages/govuk-frontend/dist/govuk/helpers/_typography.scss
index 37b75b423..d9b563418 100644
--- a/packages/govuk-frontend/dist/govuk/helpers/_typography.scss
+++ b/packages/govuk-frontend/dist/govuk/helpers/_typography.scss
@@ -12,9 +12,9 @@
 @use "../settings/spacing" as *;
 @use "../settings/typography-font" as *;
 @use "../settings/typography-responsive" as *;
-@import "../tools/font-url";
-@import "../tools/px-to-rem";
-@import "../tools/if";
+@use "../tools/font-url" as *;
+@use "../tools/px-to-rem" as *;
+@use "../tools/if" as *;
 @import "font-faces";
 @import "media-queries";
 @import "spacing";
diff --git a/packages/govuk-frontend/dist/govuk/helpers/_visually-hidden.scss b/packages/govuk-frontend/dist/govuk/helpers/_visually-hidden.scss
index 45649e5f6..134283629 100644
--- a/packages/govuk-frontend/dist/govuk/helpers/_visually-hidden.scss
+++ b/packages/govuk-frontend/dist/govuk/helpers/_visually-hidden.scss
@@ -2,7 +2,7 @@
 /// @group helpers/accessibility
 ////
 
-@import "../tools/if";
+@use "../tools/if" as *;
 
 /// Helper function containing the common code for the following two mixins
 ///
diff --git a/packages/govuk-frontend/dist/govuk/overrides/_display.scss b/packages/govuk-frontend/dist/govuk/overrides/_display.scss
index d41456681..d614e2c9e 100644
--- a/packages/govuk-frontend/dist/govuk/overrides/_display.scss
+++ b/packages/govuk-frontend/dist/govuk/overrides/_display.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 
 // stylelint-disable declaration-no-important
 @include govuk-exports("govuk/overrides/display") {
diff --git a/packages/govuk-frontend/dist/govuk/overrides/_index.scss b/packages/govuk-frontend/dist/govuk/overrides/_index.scss
index 2bbe06bf9..297181477 100644
--- a/packages/govuk-frontend/dist/govuk/overrides/_index.scss
+++ b/packages/govuk-frontend/dist/govuk/overrides/_index.scss
@@ -1,5 +1,5 @@
 @use "../settings/spacing" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/spacing";
 @import "display";
 @import "spacing";
diff --git a/packages/govuk-frontend/dist/govuk/overrides/_spacing.scss b/packages/govuk-frontend/dist/govuk/overrides/_spacing.scss
index 92df8328e..c1fd26e89 100644
--- a/packages/govuk-frontend/dist/govuk/overrides/_spacing.scss
+++ b/packages/govuk-frontend/dist/govuk/overrides/_spacing.scss
@@ -3,7 +3,7 @@
 ////
 @use "sass:map";
 @use "../settings/spacing" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/spacing";
 
 // stylelint-disable declaration-no-important
diff --git a/packages/govuk-frontend/dist/govuk/overrides/_text-align.scss b/packages/govuk-frontend/dist/govuk/overrides/_text-align.scss
index 311d0b0c4..f935f5ac6 100644
--- a/packages/govuk-frontend/dist/govuk/overrides/_text-align.scss
+++ b/packages/govuk-frontend/dist/govuk/overrides/_text-align.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 
 // stylelint-disable declaration-no-important
 @include govuk-exports("govuk/overrides/text-align") {
diff --git a/packages/govuk-frontend/dist/govuk/overrides/_typography.scss b/packages/govuk-frontend/dist/govuk/overrides/_typography.scss
index 8dee1c7bf..ab0dd341a 100644
--- a/packages/govuk-frontend/dist/govuk/overrides/_typography.scss
+++ b/packages/govuk-frontend/dist/govuk/overrides/_typography.scss
@@ -1,6 +1,6 @@
 @use "sass:map";
 @use "../settings/typography-responsive" as *;
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/typography";
 
 @include govuk-exports("govuk/overrides/typography") {
diff --git a/packages/govuk-frontend/dist/govuk/overrides/_width.scss b/packages/govuk-frontend/dist/govuk/overrides/_width.scss
index 7b1277c01..4793200a5 100644
--- a/packages/govuk-frontend/dist/govuk/overrides/_width.scss
+++ b/packages/govuk-frontend/dist/govuk/overrides/_width.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/media-queries";
 
 // stylelint-disable declaration-no-important
diff --git a/packages/govuk-frontend/dist/govuk/tools/_exports.import.scss b/packages/govuk-frontend/dist/govuk/tools/_exports.import.scss
new file mode 100644
index 000000000..a72155f03
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_exports.import.scss
@@ -0,0 +1,2 @@
+@forward "exports";
+
diff --git a/packages/govuk-frontend/dist/govuk/tools/_font-url.import.scss b/packages/govuk-frontend/dist/govuk/tools/_font-url.import.scss
new file mode 100644
index 000000000..eea47c844
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_font-url.import.scss
@@ -0,0 +1,38 @@
+////
+/// @group tools/assets
+////
+@use "sass:meta";
+@use "../settings/assets" as *;
+
+@forward "font-url" hide govuk-font-url;
+
+/// Font URL
+///
+/// If a custom font-url handler is defined ($govuk-font-url-function) then
+/// it will be called, otherwise a url will be returned with the filename
+/// appended to the font path.
+///
+/// @param {String} $filename - Font filename
+/// @return {String} URL for the filename, wrapped in `url()`
+/// @access public
+
+@function govuk-font-url($filename) {
+  // prettier-ignore
+  $custom-function: meta.variable-exists("govuk-font-url-function")
+    and $govuk-font-url-function;
+
+  @if meta.type-of($custom-function) == "string" {
+    @if meta.function-exists($custom-function) {
+      $custom-function: meta.get-function($custom-function);
+    } @else {
+      $custom-function: null;
+    }
+  }
+
+  @if $custom-function {
+    @return meta.call($custom-function, $filename);
+  } @else {
+    @return url($govuk-fonts-path + $filename);
+  }
+}
+
diff --git a/packages/govuk-frontend/dist/govuk/tools/_font-url.scss b/packages/govuk-frontend/dist/govuk/tools/_font-url.scss
index 0c9ebfc11..18088b42c 100644
--- a/packages/govuk-frontend/dist/govuk/tools/_font-url.scss
+++ b/packages/govuk-frontend/dist/govuk/tools/_font-url.scss
@@ -4,6 +4,7 @@
 @use "sass:meta";
 
 @use "../settings/assets" as *;
+@use "../settings/warnings--internal";
 
 /// Font URL
 ///
@@ -21,11 +22,10 @@
     and $govuk-font-url-function;
 
   @if meta.type-of($custom-function) == "string" {
-    @if meta.function-exists($custom-function) {
-      $custom-function: meta.get-function($custom-function);
-    } @else {
-      $custom-function: null;
-    }
+    @warn warnings--internal.warning-text("font-url-string",
+    "Passing a string to $govuk-font-url-function is deprecated. "
+        + "Pass a function using meta.get-function(...) instead.");
+    $custom-function: null;
   }
 
   @if $custom-function {
diff --git a/packages/govuk-frontend/dist/govuk/tools/_if.import.scss b/packages/govuk-frontend/dist/govuk/tools/_if.import.scss
new file mode 100644
index 000000000..71a8a195e
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_if.import.scss
@@ -0,0 +1,2 @@
+@forward "if";
+
diff --git a/packages/govuk-frontend/dist/govuk/tools/_image-url.import.scss b/packages/govuk-frontend/dist/govuk/tools/_image-url.import.scss
new file mode 100644
index 000000000..8d5e77332
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_image-url.import.scss
@@ -0,0 +1,38 @@
+////
+/// @group tools/assets
+////
+@use "sass:meta";
+@use "../settings/assets" as *;
+
+@forward "image-url" hide govuk-image-url;
+
+/// Image URL
+///
+/// If a custom image-url handler is defined ($govuk-image-url-function) then
+/// it will be called, otherwise a url will be returned with the filename
+/// appended to the image path.
+///
+/// @param {String} $filename - Image filename
+/// @return {String} URL for the filename, wrapped in `url()`
+/// @access public
+
+@function govuk-image-url($filename) {
+  // prettier-ignore
+  $custom-function: meta.variable-exists("govuk-image-url-function")
+    and $govuk-image-url-function;
+
+  @if meta.type-of($custom-function) == "string" {
+    @if meta.function-exists($custom-function) {
+      $custom-function: meta.get-function($custom-function);
+    } @else {
+      $custom-function: null;
+    }
+  }
+
+  @if $custom-function {
+    @return meta.call($custom-function, $filename);
+  } @else {
+    @return url($govuk-images-path + $filename);
+  }
+}
+
diff --git a/packages/govuk-frontend/dist/govuk/tools/_image-url.scss b/packages/govuk-frontend/dist/govuk/tools/_image-url.scss
index 92ed9b079..1c629adfc 100644
--- a/packages/govuk-frontend/dist/govuk/tools/_image-url.scss
+++ b/packages/govuk-frontend/dist/govuk/tools/_image-url.scss
@@ -3,13 +3,16 @@
 ////
 @use "sass:meta";
 
+@use "../settings/assets" as *;
+@use "../settings/warnings--internal";
+
 /// Image URL
 ///
 /// If a custom image-url handler is defined ($govuk-image-url-function) then
 /// it will be called, otherwise a url will be returned with the filename
 /// appended to the image path.
 ///
-/// @param {String} Filename for the image to load
+/// @param {String} $filename - Image filename
 /// @return {String} URL for the filename, wrapped in `url()`
 /// @access public
 
@@ -19,11 +22,10 @@
     and $govuk-image-url-function;
 
   @if meta.type-of($custom-function) == "string" {
-    @if meta.function-exists($custom-function) {
-      $custom-function: meta.get-function($custom-function);
-    } @else {
-      $custom-function: null;
-    }
+    @warn warnings--internal.warning-text("image-url-string",
+    "Passing a string to $govuk-image-url-function is deprecated. "
+        + "Pass a function using meta.get-function(...) instead.");
+    $custom-function: null;
   }
 
   @if $custom-function {
diff --git a/packages/govuk-frontend/dist/govuk/tools/_index.import.scss b/packages/govuk-frontend/dist/govuk/tools/_index.import.scss
new file mode 100644
index 000000000..a66bf5bd2
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_index.import.scss
@@ -0,0 +1,2 @@
+@forward "index";
+
diff --git a/packages/govuk-frontend/dist/govuk/tools/_index.scss b/packages/govuk-frontend/dist/govuk/tools/_index.scss
index 55bc3fec5..a0a80adf4 100644
--- a/packages/govuk-frontend/dist/govuk/tools/_index.scss
+++ b/packages/govuk-frontend/dist/govuk/tools/_index.scss
@@ -1,7 +1,7 @@
-@import "exports";
-@import "font-url";
-@import "if";
-@import "image-url";
-@import "px-to-em";
-@import "px-to-rem";
+@forward "exports";
+@forward "font-url";
+@forward "if";
+@forward "image-url";
+@forward "px-to-em";
+@forward "px-to-rem";
 
diff --git a/packages/govuk-frontend/dist/govuk/tools/_px-to-em.import.scss b/packages/govuk-frontend/dist/govuk/tools/_px-to-em.import.scss
new file mode 100644
index 000000000..fdc5f6756
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_px-to-em.import.scss
@@ -0,0 +1,2 @@
+@forward "px-to-em";
+
diff --git a/packages/govuk-frontend/dist/govuk/tools/_px-to-rem.import.scss b/packages/govuk-frontend/dist/govuk/tools/_px-to-rem.import.scss
new file mode 100644
index 000000000..339be8c1d
--- /dev/null
+++ b/packages/govuk-frontend/dist/govuk/tools/_px-to-rem.import.scss
@@ -0,0 +1,2 @@
+@forward "px-to-rem";
+
diff --git a/packages/govuk-frontend/dist/govuk/utilities/_clearfix.scss b/packages/govuk-frontend/dist/govuk/utilities/_clearfix.scss
index 6b360c1e7..369c5e2bf 100644
--- a/packages/govuk-frontend/dist/govuk/utilities/_clearfix.scss
+++ b/packages/govuk-frontend/dist/govuk/utilities/_clearfix.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/clearfix";
 
 @include govuk-exports("govuk/utilities/clearfix") {
diff --git a/packages/govuk-frontend/dist/govuk/utilities/_index.scss b/packages/govuk-frontend/dist/govuk/utilities/_index.scss
index 3c310bbd0..d03744a50 100644
--- a/packages/govuk-frontend/dist/govuk/utilities/_index.scss
+++ b/packages/govuk-frontend/dist/govuk/utilities/_index.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "clearfix";
 @import "visually-hidden";
 
diff --git a/packages/govuk-frontend/dist/govuk/utilities/_visually-hidden.scss b/packages/govuk-frontend/dist/govuk/utilities/_visually-hidden.scss
index 79ca26a7e..d2b1098a1 100644
--- a/packages/govuk-frontend/dist/govuk/utilities/_visually-hidden.scss
+++ b/packages/govuk-frontend/dist/govuk/utilities/_visually-hidden.scss
@@ -1,4 +1,4 @@
-@import "../tools/exports";
+@use "../tools/exports" as *;
 @import "../helpers/visually-hidden";
 
 @include govuk-exports("govuk/utilities/visually-hidden") {

Action run for 65c276e

github-actions · 2026-03-19T00:07:39Z

📋 Stats

No changes to any distributed file sizes!

Action run for 65c276e

domoscargin added 6 commits March 18, 2026 10:14

Refactor tools partial tests to use .each

8428f4c

Add test helper to get sass file names per layer

317d474

We'll repeatedly need to check these partials for compilation errors, so makes sense to centralise the functionality.

Add import-only files

01b0531

Replace imports with uses

1038480

[WIP] Address test suite failures

65c276e

govuk-design-system-ci deployed to govuk-frontend-pr-6854 March 19, 2026 00:04 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`@use` tools layer#6854

`@use` tools layer#6854
domoscargin wants to merge 6 commits intoat-use-settingsfrom
at-use-tools

domoscargin commented Mar 19, 2026

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

domoscargin commented Mar 19, 2026

Uh oh!

github-actions bot commented Mar 19, 2026

Other changes to npm package

Uh oh!

github-actions bot commented Mar 19, 2026

📋 Stats

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants