From aa2faed25e1efed4f8f74b6ba61b25ed54af103b Mon Sep 17 00:00:00 2001 From: Brett Kyle <22524634+domoscargin@users.noreply.github.com> Date: Wed, 29 Apr 2026 09:03:44 +0100 Subject: [PATCH 1/4] Rename import-css page to include-css --- netlify.toml | 5 +++++ source/importing-css-assets-and-javascript/index.html.md.erb | 2 +- source/{import-css => include-css}/index.html.md.erb | 0 source/install-using-precompiled-files/index.html.md.erb | 2 +- source/installing-with-npm/index.html.md.erb | 4 ++-- 5 files changed, 9 insertions(+), 4 deletions(-) rename source/{import-css => include-css}/index.html.md.erb (100%) diff --git a/netlify.toml b/netlify.toml index 860a9bc8..e2370910 100644 --- a/netlify.toml +++ b/netlify.toml @@ -19,6 +19,11 @@ to = "/configure-components/" status = 301 +[[redirects]] + from = "/import-css/" + to = "/include-css/" + status = 301 + # Asset filenames with fingerprint hashes (which at the minute is only the font # from GOV.UK Frontend) are given an 'infinite' max-age and treated as # immutable. diff --git a/source/importing-css-assets-and-javascript/index.html.md.erb b/source/importing-css-assets-and-javascript/index.html.md.erb index 6793e5da..5a244ef3 100644 --- a/source/importing-css-assets-and-javascript/index.html.md.erb +++ b/source/importing-css-assets-and-javascript/index.html.md.erb @@ -9,6 +9,6 @@ prevent_indexing: true This content has moved. You can now find out how to import CSS, assets and javascript as 3 separate pages in the following locations: -- [Import CSS](../import-css/) +- [Import CSS](../include-css/) - [Import font and images assets](../import-font-and-images-assets/) - [Import JavaScript](../import-javascript/) diff --git a/source/import-css/index.html.md.erb b/source/include-css/index.html.md.erb similarity index 100% rename from source/import-css/index.html.md.erb rename to source/include-css/index.html.md.erb diff --git a/source/install-using-precompiled-files/index.html.md.erb b/source/install-using-precompiled-files/index.html.md.erb index 735431bb..aed3e185 100644 --- a/source/install-using-precompiled-files/index.html.md.erb +++ b/source/install-using-precompiled-files/index.html.md.erb @@ -66,5 +66,5 @@ You can now get the full code for page layouts and other components from the [De If the accordion does not work, you can find out more about how to import GOV.UK Frontend's CSS and JavaScript in: -- [Import CSS](../import-css/) +- [Import CSS](../include-css/) - [Import JavaScript](../import-javascript/) diff --git a/source/installing-with-npm/index.html.md.erb b/source/installing-with-npm/index.html.md.erb index f7d5c96b..00ecbf3c 100644 --- a/source/installing-with-npm/index.html.md.erb +++ b/source/installing-with-npm/index.html.md.erb @@ -19,7 +19,7 @@ weight: 10 3. Install [Dart Sass](https://www.npmjs.com/package/sass) - version 1.79.0 or higher. - You might see deprecation warnings when compiling your Sass. If required, you can [silence deprecation warnings caused by dependencies](../import-css/#silence-deprecation-warnings-from-dependencies-in-dart-sass). + You might see deprecation warnings when compiling your Sass. If required, you can [silence deprecation warnings caused by dependencies](../include-css/#silence-deprecation-warnings-from-dependencies-in-dart-sass). Do not use either LibSass or Ruby Sass as they are no longer supported by the Sass developers or GOV.UK Frontend. Projects using these compilers should [migrate to Dart Sass](https://sass-lang.com/blog/libsass-is-deprecated#how-do-i-migrate) as soon as possible. @@ -61,7 +61,7 @@ Paste the HTML into a page or template in your application. The accordion will use a generic font until you get the font and images working, and will not be interactive until you get the JavaScript working. -There are also different ways you can [import GOV.UK Frontend's CSS](../import-css/), including into your project's main Sass file: +There are also different ways you can [import GOV.UK Frontend's CSS](../include-css/), including into your project's main Sass file: ```scss @import "node_modules/govuk-frontend/dist/govuk"; From 66b6f31abdd73782d67654aeea0339a5d199af89 Mon Sep 17 00:00:00 2001 From: Brett Kyle <22524634+domoscargin@users.noreply.github.com> Date: Wed, 29 Apr 2026 09:03:53 +0100 Subject: [PATCH 2/4] Update include css page --- source/include-css/index.html.md.erb | 196 ++++++++++++++++++--------- 1 file changed, 130 insertions(+), 66 deletions(-) diff --git a/source/include-css/index.html.md.erb b/source/include-css/index.html.md.erb index 70645142..11340ce5 100644 --- a/source/include-css/index.html.md.erb +++ b/source/include-css/index.html.md.erb @@ -1,23 +1,23 @@ --- -title: Import CSS +title: Include CSS weight: 30 --- -# Import CSS +# Include CSS -To import the CSS from GOV.UK Frontend, you can either: +To include the CSS from GOV.UK Frontend, you should either: - add GOV.UK Frontend's CSS file to your HTML -- import the CSS into your own Sass file +- include GOV.UK Frontend in your Sass build ## Add the CSS file to your HTML -If you decide to add the CSS to your HTML, you can do one of the following: +If you decide to add the CSS to your HTML, you should either: - set up your routing so requests for the CSS file are served from `node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css` - copy the `node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css` file into your application -Then link the CSS file inside the `` tag of your HTML page or page template. +Then link to `govuk-frontend.min.css` inside the `` tag of your HTML page or page template. ```html @@ -27,126 +27,190 @@ Then link the CSS file inside the `` tag of your HTML page or page templat ``` -## Import using Sass +## Include GOV.UK Frontend styles in your Sass build + +We plan to deprecate using `@import` to include GOV.UK Frontend in a future v6.x release. You’ll no longer be able to include GOV.UK Frontend with `@import` from the next major release, v7.0.0. See the [GOV.UK Frontend v5.x documentation](/v5/import-css/) if you need to include GOV.UK Frontend with `@import` before the next major release. + +To include all the styles from GOV.UK Frontend in your compiled stylesheet, add the following to a Sass file: -To import all the Sass rules from GOV.UK Frontend, add the following to your Sass file: ```scss -@import "node_modules/govuk-frontend/dist/govuk"; +@use "node_modules/govuk-frontend/dist/govuk" as *; ``` -## Import specific parts using Sass +This lets you access [GOV.UK Frontend’s Sass API](/sass-api-reference/) (variables, functions and mixins) in that Sass file. Each file using GOV.UK Frontend’s Sass API needs its own `@use` statement. + +```scss +@use "node_modules/govuk-frontend/dist/govuk" as *; + +@media govuk-from-breakpoint(tablet) { + // Styles for tablet and wider screens +} +``` + +If you want to extend or modify GOV.UK Frontend’s styles with your own styles, follow the same principles as for [extending and modifying components](https://design-system.service.gov.uk/get-started/extending-and-modifying-components/). You can add your own Sass rules after including GOV.UK Frontend with `@use`. + +## Shorten Sass URLs + +If you’re using a bundler such as Webpack or Vite, it may already locate GOV.UK Frontend inside `node_modules` if the included URL starts with `govuk-frontend`. Check your bundler’s documentation to confirm. -If you want to improve how quickly your service's pages load in browsers, you can import only the Sass rules you need. +### Use `pkg:` URLs to shorten Sass URLs -1. Import `node_modules/govuk-frontend/dist/govuk/base` in your Sass file. -2. Import only the Sass you need based on the components and other classes your service is using. +If you’re not using a bundler, we recommend using [`pkg:` URLs](https://sass-lang.com/blog/announcing-pkg-importers/) to let Sass find GOV.UK Frontend in your project’s `node_modules` directory. -The biggest optimisations come from excluding any components or overrides you're not using. +If you’re calling the Sass compiler from the command line, pass the [`--pkg-importer=node`](https://sass-lang.com/documentation/cli/dart-sass/#pkg-importer-node) option. -You must import the layers in the order listed in the example below. +If you’re using the Sass JavaScript API, add the [Sass `NodePackageImporter`](https://sass-lang.com/documentation/js-api/classes/nodepackageimporter/#md:writing-sass-packages) to the [list of `importers`](https://sass-lang.com/documentation/js-api/interfaces/options/#importers) in the `options` object. + +Then include GOV.UK Frontend using the `pkg:govuk-frontend` URL: + +```scss +@use "pkg:govuk-frontend" as *; +``` + +If you cannot use `pkg:` URLs, you can also [configure your Sass load paths or Ruby assets paths](/v5/import-css/#simplify-sass-import-paths) to make Sass import paths shorter. + +## Configure GOV.UK Frontend + +To configure any of [GOV.UK Frontend’s settings](/sass-api-reference/#settings) when including it, add a `with` clause listing each setting you want to modify to your `@use` rule: ```scss -// 'Base' includes everything from settings, tools and helpers. Nothing -// in the base outputs any CSS. +@use "node_modules/govuk-frontend/dist/govuk" as * with ( + $govuk-assets-path: "/path/to/assets/" +); +``` -@import "node_modules/govuk-frontend/dist/govuk/base"; +## Include specific parts of GOV.UK Frontend using Sass + +If you want to improve how quickly your service’s pages load in browsers, you can include only the Sass rules you need from GOV.UK Frontend. + +Most of the CSS output comes from components, so you can make your pages load faster by excluding any components or overrides you do not use. + +```scss +// Base provides GOV.UK Frontend's Sass API, allowing you to configure GOV.UK Frontend. +// You can skip `@use`ing Base if: +// - you do not need to configure GOV.UK Frontend +// - the code in this file does not use GOV.UK Frontend's Sass API + +@use "node_modules/govuk-frontend/dist/govuk/base" as * with ( +$govuk-assets-path: "/path/to/assets/" +); // Basic content styles for typography, links etc. Approximately 10% of // the CSS output if you include everything. -@import "node_modules/govuk-frontend/dist/govuk/core"; +@use "node_modules/govuk-frontend/dist/govuk/core"; // Objects include things like the page template, grid and form groups. // Approximately 5% of the CSS output if you include everything. -@import "node_modules/govuk-frontend/dist/govuk/objects"; +@use "node_modules/govuk-frontend/dist/govuk/objects"; // The components themselves - try to only include the components you // are using in your project. Approximately 70% of the CSS output if // you include everything. -<% components.each do |component| %> -@import "node_modules/govuk-frontend/dist/govuk/components/<%= component %>"; -<% end %> +@use "node_modules/govuk-frontend/dist/govuk/accordion"; +@use "node_modules/govuk-frontend/dist/govuk/components/back-link"; +@use "node_modules/govuk-frontend/dist/govuk/components/breadcrumbs"; +@use "node_modules/govuk-frontend/dist/govuk/components/button"; +@use "node_modules/govuk-frontend/dist/govuk/components/character-count"; +@use "node_modules/govuk-frontend/dist/govuk/components/checkboxes"; +@use "node_modules/govuk-frontend/dist/govuk/components/cookie-banner"; +@use "node_modules/govuk-frontend/dist/govuk/components/date-input"; +@use "node_modules/govuk-frontend/dist/govuk/components/details"; +@use "node_modules/govuk-frontend/dist/govuk/components/error-message"; +@use "node_modules/govuk-frontend/dist/govuk/components/error-summary"; +@use "node_modules/govuk-frontend/dist/govuk/components/exit-this-page"; +@use "node_modules/govuk-frontend/dist/govuk/components/fieldset"; +@use "node_modules/govuk-frontend/dist/govuk/components/file-upload"; +@use "node_modules/govuk-frontend/dist/govuk/components/footer"; +@use "node_modules/govuk-frontend/dist/govuk/components/header"; +@use "node_modules/govuk-frontend/dist/govuk/components/hint"; +@use "node_modules/govuk-frontend/dist/govuk/components/input"; +@use "node_modules/govuk-frontend/dist/govuk/components/inset-text"; +@use "node_modules/govuk-frontend/dist/govuk/components/label"; +@use "node_modules/govuk-frontend/dist/govuk/components/notification-banner"; +@use "node_modules/govuk-frontend/dist/govuk/components/pagination"; +@use "node_modules/govuk-frontend/dist/govuk/components/panel"; +@use "node_modules/govuk-frontend/dist/govuk/components/password-input"; +@use "node_modules/govuk-frontend/dist/govuk/components/phase-banner"; +@use "node_modules/govuk-frontend/dist/govuk/components/radios"; +@use "node_modules/govuk-frontend/dist/govuk/components/select"; +@use "node_modules/govuk-frontend/dist/govuk/components/service-navigation"; +@use "node_modules/govuk-frontend/dist/govuk/components/skip-link"; +@use "node_modules/govuk-frontend/dist/govuk/components/summary-list"; +@use "node_modules/govuk-frontend/dist/govuk/components/table"; +@use "node_modules/govuk-frontend/dist/govuk/components/tabs"; +@use "node_modules/govuk-frontend/dist/govuk/components/tag"; +@use "node_modules/govuk-frontend/dist/govuk/components/task-list"; +@use "node_modules/govuk-frontend/dist/govuk/components/textarea"; +@use "node_modules/govuk-frontend/dist/govuk/components/warning-text"; /* // Alternatively, you can import all components: -@import "node_modules/govuk-frontend/dist/govuk/components"; +@use "node_modules/govuk-frontend/dist/govuk/components"; */ // Utilities, for example govuk-clearfix or govuk-visually-hidden. // Approximately 1% of the CSS output if you include everything. -@import "node_modules/govuk-frontend/dist/govuk/utilities"; +@use "node_modules/govuk-frontend/dist/govuk/utilities"; // Overrides, used to adjust things like the amount of spacing on an // element. Override classes always include `-!-` in the class name. // Approximately 15% of the CSS output if you include everything. -@import "node_modules/govuk-frontend/dist/govuk/overrides"; +@use "node_modules/govuk-frontend/dist/govuk/overrides"; /* // Alternatively, you can import the specific groups of overrides // you need for your project: -<% examples = { - 'display' => %w(govuk-!-display-inline), - 'spacing' => %w(govuk-!-margin-4 govuk-!-static-padding-4), - 'text-align' => %w(govuk-!-text-align-left), - 'typography' => %w(govuk-!-font-size-19 govuk-!-font-weight-bold), - 'width' => %w(govuk-!-width-two-thirds) -} %> -<% overrides.each do |override| %> - -// <%= override.sub('-', ' ').humanize %> overrides<% if examples.key?(override) %> - for example <%= examples[override].join(', ') %><% end %> -@import "node_modules/govuk-frontend/dist/govuk/overrides/<%= override %>"; -<% end %> -*/ -``` -You can remove lines that import parts of the CSS you do not need. +// Display overrides - for example govuk-!-display-inline +@use "node_modules/govuk-frontend/dist/govuk/overrides/display"; -[Read more about the different parts of GOV.UK Frontend’s CSS](https://github.com/alphagov/govuk-frontend/tree/main/packages/govuk-frontend/src). +// Spacing overrides - for example govuk-!-margin-4, govuk-!-static-padding-4 +@use "node_modules/govuk-frontend/dist/govuk/overrides/spacing"; -## Import an individual component’s CSS using a single Sass import +// Text align overrides - for example govuk-!-text-align-left +@use "node_modules/govuk-frontend/dist/govuk/overrides/text-align"; -You can also import a component and all its dependencies without importing `node_modules/govuk-frontend/dist/govuk/base` first. +// Typography overrides - for example govuk-!-font-size-19, govuk-!-font-weight-bold +@use "node_modules/govuk-frontend/dist/govuk/overrides/typography"; -For example, to import the button component, add the following to your Sass file: +// Width overrides - for example govuk-!-width-two-thirds +@use "node_modules/govuk-frontend/dist/govuk/overrides/width"; +*/ -```scss -@import "node_modules/govuk-frontend/dist/govuk/components/button"; ``` -We're deprecating using `_.scss` files (like `node_modules/govuk-frontend/dist/govuk/components/button/button`) and will remove them in the next major release of GOV.UK Frontend. -## Simplify Sass import paths +You can remove lines that include parts of the CSS you do not need. + +Read more about the [different parts of GOV.UK Frontend’s CSS](https://github.com/alphagov/govuk-frontend/tree/main/packages/govuk-frontend/src). -If you want to make Sass import paths shorter, add `node_modules/govuk-frontend/dist` to either your: +Previously, you could use `_.scss` files (such as `node_modules/govuk-frontend/dist/govuk/components/button/button`), but these are now deprecated, and we’ll remove them in the next major release of GOV.UK Frontend, v7.0.0. -- [Sass load paths](https://sass-lang.com/documentation/at-rules/import#finding-the-file) -- [assets paths](http://guides.rubyonrails.org/asset_pipeline.html#search-paths) if you use Ruby in your project +## Use GOV.UK Frontend’s Sass API -You can then import without using `node_modules/govuk-frontend/dist/` in your import path. For example: +If you need to build your own CSS, you can use GOV.UK Frontend’s Sass API to make your styles consistent with GOV.UK Frontend’s CSS and avoid re-implementing features used to create GOV.UK Frontend’s CSS. + +The variables, functions and mixins will be available in the file that [includes GOV.UK Frontend](#include-gov-uk-frontend-styles-in-your-sass-build). In other files, you’ll need to add the following at the top of the file: ```scss -@import "govuk/components/button/button"; -``` +@use "node_modules/govuk-frontend/dist/govuk/base" as *; -## Override with your own CSS +// Use variable, functions and mixins from GOV.UK Frontend +``` -If you want to override GOV.UK Frontend's styles with your own styles, `@import` GOV.UK Frontend's styles before your own Sass rules. +You can find the list of the variables, functions and mixins available in the [GOV.UK Frontend Sass API reference](/sass-api-reference/). ## Silence deprecation warnings from dependencies in Dart Sass -If you're using Dart Sass 1.33.0 or greater, you may see deprecation warnings when compiling your Sass. For example: - -``` -DEPRECATION WARNING: Using / for division is deprecated and will be removed in Dart Sass 2.0.0. -``` +When compiling, Sass may warn you about deprecations from its upcoming [breaking changes](https://sass-lang.com/documentation/breaking-changes/). You can silence any warnings caused by GOV.UK Frontend and other dependencies. -You can silence the warnings caused by GOV.UK Frontend and other dependencies. If you're: +If you’re calling the Sass compiler from the command line, pass the [`--quiet-deps` flag](https://sass-lang.com/documentation/cli/dart-sass/#quiet-deps). -- calling the Sass compiler from the command line, [pass the `--quiet-deps` flag](https://sass-lang.com/documentation/cli/dart-sass#quiet-deps) -- using the JavaScript API, [include `quietDeps: true`](https://sass-lang.com/documentation/js-api#quietdeps) in the `options` object +If you’re using the Sass JavaScript API, include [`quietDeps: true`](https://sass-lang.com/documentation/js-api/interfaces/options/#quietDeps) in the `options` object. -You'll still see deprecation warnings if you're using `/` for division in your own Sass code. +You’ll still see deprecation warnings caused by your own Sass code. From 9ba5dd45e4b8695629c4ec26f47a416b119a0410 Mon Sep 17 00:00:00 2001 From: Brett Kyle <22524634+domoscargin@users.noreply.github.com> Date: Wed, 29 Apr 2026 08:48:59 +0100 Subject: [PATCH 3/4] Update fonts page --- .../index.html.md.erb | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/source/import-font-and-images-assets/index.html.md.erb b/source/import-font-and-images-assets/index.html.md.erb index a64fc123..7a108962 100644 --- a/source/import-font-and-images-assets/index.html.md.erb +++ b/source/import-font-and-images-assets/index.html.md.erb @@ -11,10 +11,14 @@ To use the font and image assets from GOV.UK Frontend, you can either: - copy the font and image files into your application ## Serve the assets from the GOV.UK Frontend assets folder - recommended +- serve the assets from the GOV.UK Frontend assets folder (recommended) +- copy the font and image files into your application + +## Serve the assets from the GOV.UK Frontend assets folder Set up your routing so requests for files in `/assets` are served from `/node_modules/govuk-frontend/dist/govuk/assets`. -For example if you're using [express.js](https://expressjs.com/), add the following to your `app.js` file: +For example if you use the web framework [Express.js](https://expressjs.com/), add the following to your `app.js` file: ```javascript const path = require('path'); @@ -23,7 +27,7 @@ app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-fron ## Copy the font and image files into your application -If you decide to copy the assets instead, copy the: +If you decide to copy the assets instead, copy these 3 items: - `/node_modules/govuk-frontend/dist/govuk/assets/images` folder to `/assets/images` - `/node_modules/govuk-frontend/dist/govuk/assets/fonts` folder to `/assets/fonts` @@ -33,24 +37,23 @@ You should use an automated task or your build pipeline to copy the files, so yo ### If you have your own folder structure -If you use a different folder structure than `/assets/images` and `/assets/fonts`, you can set Sass variables so that Sass builds the CSS to point to your folders. - -Set one of the following before the `@import` line in your Sass file: - -- `$govuk-assets-path` -- `$govuk-images-path` and `$govuk-fonts-path` +If you use a different folder structure than `/assets/images` and `/assets/fonts`, you can [configure GOV.UK Frontend](/include-css/#configure-gov-uk-frontend) so that Sass builds the CSS according to your folder structure. -Set the `$govuk-assets-path` variable if your `font` and `image` folders have the same parent folder. For example: +Configure the [`$govuk-assets-path`](/sass-api-reference/#govuk-assets-path) variable if your `font` and `image` folders have the same parent folder. For example: ```scss -$govuk-assets-path: "//"; +@use "node_modules/govuk-frontend/dist/govuk" as * with ( + $govuk-assets-path: "//" +); ``` -Set the `$govuk-images-path` and `$govuk-fonts-path` variables if your `font` and `image` folders have different parent folders. For example: +Configure the [`$govuk-images-path`](/sass-api-reference/#govuk-images-path) and [`$govuk-fonts-path`](/sass-api-reference/#govuk-fonts-path) variables if your `font` and `image` folders have different parent folders. For example: ```scss -$govuk-images-path: "//"; -$govuk-fonts-path: "//"; +@use "node_modules/govuk-frontend/dist/govuk" as * with ( + $govuk-images-path: "//", + $govuk-fonts-path: "//" +); ``` -You can also use your own function to generate paths, for example if you're using `asset-pipeline` in [sass-rails](https://github.com/rails/sass-rails). Set the `$govuk-image-url-function` and `$govuk-font-url-function` variables to the name of your function. +You can also use your own function to generate paths, for example if you’re using `asset-pipeline` in [sass-rails](https://github.com/rails/sass-rails). Configure the [`$govuk-image-url-function`](/sass-api-reference/#govuk-image-url-function) and [$govuk-font-url-function](/sass-api-reference/#govuk-font-url-function) variables with the function you need to use. \ No newline at end of file From 7dff5b23f3ac4126ad65fc6e2b23355df9220552 Mon Sep 17 00:00:00 2001 From: Brett Kyle <22524634+domoscargin@users.noreply.github.com> Date: Wed, 29 Apr 2026 08:58:19 +0100 Subject: [PATCH 4/4] Update install page --- source/installing-with-npm/index.html.md.erb | 40 ++++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/source/installing-with-npm/index.html.md.erb b/source/installing-with-npm/index.html.md.erb index 00ecbf3c..0dbec48f 100644 --- a/source/installing-with-npm/index.html.md.erb +++ b/source/installing-with-npm/index.html.md.erb @@ -11,7 +11,7 @@ weight: 10 GOV.UK Frontend requires Node.js version 12.17.0 or later to support ECMAScript (ES) modules. Where possible, we recommend you install the latest Long Term Support (LTS) version. -2. `cd` to the root of your project and check if you have a [`package.json` file](https://docs.npmjs.com/files/package.json). If you do not have the file, create it by running: +2. `cd` to the root of your project and check if you have a [package.json file](https://docs.npmjs.com/cli/v11/configuring-npm/package-json). If you do not have the file, create it by running: ``` npm init @@ -19,11 +19,11 @@ weight: 10 3. Install [Dart Sass](https://www.npmjs.com/package/sass) - version 1.79.0 or higher. - You might see deprecation warnings when compiling your Sass. If required, you can [silence deprecation warnings caused by dependencies](../include-css/#silence-deprecation-warnings-from-dependencies-in-dart-sass). + You might see deprecation warnings when compiling your Sass. If required, you can [silence deprecation warnings caused by dependencies](/include-css/#silence-deprecation-warnings-from-dependencies-in-dart-sass). - Do not use either LibSass or Ruby Sass as they are no longer supported by the Sass developers or GOV.UK Frontend. Projects using these compilers should [migrate to Dart Sass](https://sass-lang.com/blog/libsass-is-deprecated#how-do-i-migrate) as soon as possible. + Do not use either LibSass or Ruby Sass as they are no longer supported by the Sass developers or GOV.UK Frontend. Projects using these compilers should [migrate to Dart Sass](https://sass-lang.com/blog/libsass-is-deprecated/#how-do-i-migrate) before updating to GOV.UK Frontend v6.0. -You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](../use-nunjucks/). +You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend’s Nunjucks macros](/use-nunjucks/). ## Install GOV.UK Frontend @@ -35,21 +35,21 @@ npm install govuk-frontend --save When the installation finishes, the `govuk-frontend` package will be in your `node_modules` folder. -## Get the CSS, Assets and JavaScript working +## Add HTML for a component -Add the HTML for a component to your application. We recommend the accordion component as this makes it easier to spot if JavaScript is not working. +Add the HTML for a component to your application. We recommend the accordion component as this makes it easy to spot if JavaScript is not working. Go to the [example accordion component](https://design-system.service.gov.uk/components/accordion/#accordion-example) on the GOV.UK Design System website, then copy the HTML. Paste the HTML into a page or template in your application. -### Get the CSS working +## Get the CSS working 1. Copy the `/node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css` file into your application. 2. Add your CSS file to your page layout if you need to. For example: - ```html + ```scss @@ -61,33 +61,33 @@ Paste the HTML into a page or template in your application. The accordion will use a generic font until you get the font and images working, and will not be interactive until you get the JavaScript working. -There are also different ways you can [import GOV.UK Frontend's CSS](../include-css/), including into your project's main Sass file: +There are also different ways you can [include GOV.UK Frontend’s CSS](/include-css/), including into your project’s main Sass file: ```scss -@import "node_modules/govuk-frontend/dist/govuk"; +@use "node_modules/govuk-frontend/dist/govuk" as *; ``` -### Get the font and images working +## Get the font and images working -Your component will not use the right font or images until you've added GOV.UK Frontend's assets to your application. +Your component will not use the correct font or images until you’ve added GOV.UK Frontend’s assets to your application. 1. Copy the following 3 items: + - `/node_modules/govuk-frontend/dist/govuk/assets/images` folder to `/assets/images` - `/node_modules/govuk-frontend/dist/govuk/assets/fonts` folder to `/assets/fonts` - `/node_modules/govuk-frontend/dist/govuk/assets/manifest.json` file to `/assets` -2. Run your application, then use [the Fonts tab in Firefox Page Inspector](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts#The_Fonts_tab) to check the accordion is using the GDS Transport font. +2. Run your application, then use [the Fonts tab in Firefox Page Inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_fonts/index.html#The_Fonts_tab) to check the accordion is using the GDS Transport font. -In your live application, we recommend [using an automated task or your build pipeline](../import-font-and-images-assets/) instead of copying the files manually. +You can also [configure how GOV.UK Frontend locates its font and image assets](/import-font-and-images-assets/) to suit your application architecture. -### Get the JavaScript working +## Get the JavaScript working 1. Add the following to the top of the `` section of your page template: - ```html + ```scss ``` - 2. Copy the `/node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.js` file into your application. 3. Import the file before the closing `` tag of your page template, then run the `initAll` function to initialise all the components. For example: @@ -107,9 +107,9 @@ In your live application, we recommend [using an automated task or your build pi In your live application, we recommend: -- [using an automated task or your build pipeline](../import-javascript/) instead of copying the files manually -- importing only the components your application uses and [using `createAll` to initialise](../import-javascript/#import-individual-components) all their instances on the page +- [using an automated task or your build pipeline](https://frontend.design-system.service.gov.uk/import-javascript/) instead of copying the files manually +- importing only the components your application uses and [using createAll to initialise](/import-javascript/#import-individual-components) all their instances on the page Make sure you import all the components used throughout your application or some components will not work correctly for disabled users who use assistive technologies. -Once your testing is complete you can use the full code for page layouts and other components from the [Design System website](https://design-system.service.gov.uk/). +Once your testing is complete, you can use the full code for page layouts and other components from the [Design System website](https://design-system.service.gov.uk/).