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/package-lock.json b/package-lock.json index b7cba017..de602e25 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "1.0.0", "hasInstallScript": true, "devDependencies": { - "govuk-frontend": "^6.1.0", + "govuk-frontend": "github:alphagov/govuk-frontend#cf77c484e", "govuk-frontend-v4": "npm:govuk-frontend@^4.10.1", "govuk-frontend-v5": "npm:govuk-frontend@^5.14.0", "hyperlink": "^5.0.4", @@ -4529,9 +4529,8 @@ } }, "node_modules/govuk-frontend": { - "version": "6.1.0", - "resolved": "https://registry.npmjs.org/govuk-frontend/-/govuk-frontend-6.1.0.tgz", - "integrity": "sha512-sqivexZFa82LiDIDVMItsUlqEXE/wEUWWBqzEoxHvUFLBH7bY0C8lVrj1qsDThSnj5JEUMS7isBAbKnfQ5Qp6g==", + "version": "6.1.0-publish-preview-slash-in-branch-name", + "resolved": "git+ssh://git@github.com/alphagov/govuk-frontend.git#cf77c484e8a7fe3d40c66542c9b663833b986828", "dev": true, "license": "MIT", "engines": { diff --git a/package.json b/package.json index 0ee322a2..8a47c9ba 100644 --- a/package.json +++ b/package.json @@ -5,14 +5,14 @@ "scripts": { "start": "bundle exec middleman server", "postinstall": "npm run build:sassdoc && npm run build:sassdocv5 && npm run build:sassdocv4", - "build:sassdoc": "sassdoc --no-update-notifier --parse node_modules/govuk-frontend/dist/govuk/ > data/sassdoc.json", - "build:sassdocv5": "sassdoc --no-update-notifier --parse node_modules/govuk-frontend-v5/dist/govuk/ > data/sassdoc-v5.json", - "build:sassdocv4": "sassdoc --no-update-notifier --parse node_modules/govuk-frontend-v4/govuk/ > data/sassdoc-v4.json", + "build:sassdoc": "sassdoc -c sassdoc.config.json --parse node_modules/govuk-frontend/dist/govuk/ > data/sassdoc.json", + "build:sassdocv5": "sassdoc -c sassdoc.config.json --parse node_modules/govuk-frontend-v5/dist/govuk/ > data/sassdoc-v5.json", + "build:sassdocv4": "sassdoc -c sassdoc.config.json --parse node_modules/govuk-frontend-v4/govuk/ > data/sassdoc-v4.json", "lint": "standard", "check-links": "hyperlink --canonicalroot https://frontend.design-system.service.gov.uk --internal --recursive build/index.html --skip 'property=\"og:image\"' --skip 'application.js' | tee check-links.log | tap-mocha-reporter min" }, "devDependencies": { - "govuk-frontend": "^6.1.0", + "govuk-frontend": "github:alphagov/govuk-frontend#cf77c484e", "govuk-frontend-v4": "npm:govuk-frontend@^4.10.1", "govuk-frontend-v5": "npm:govuk-frontend@^5.14.0", "hyperlink": "^5.0.4", diff --git a/sassdoc.config.json b/sassdoc.config.json new file mode 100644 index 00000000..e6391941 --- /dev/null +++ b/sassdoc.config.json @@ -0,0 +1,4 @@ +{ + "exclude": ["**/*.import.scss"], + "no-update-notifier": true +} \ No newline at end of file diff --git a/source/import-css/index.html.md.erb b/source/import-css/index.html.md.erb deleted file mode 100644 index 70645142..00000000 --- a/source/import-css/index.html.md.erb +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Import CSS -weight: 30 ---- - -# Import CSS - -To import the CSS from GOV.UK Frontend, you can either: - -- add GOV.UK Frontend's CSS file to your HTML -- import the CSS into your own Sass file - -## Add the CSS file to your HTML - -If you decide to add the CSS to your HTML, you can do one of the following: - -- 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. - -```html - - - - - -``` - -## Import using Sass - -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"; -``` - -## Import specific parts using Sass - -If you want to improve how quickly your service's pages load in browsers, you can import only the Sass rules you need. - -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. - -The biggest optimisations come from excluding any components or overrides you're not using. - -You must import the layers in the order listed in the example below. - -```scss -// 'Base' includes everything from settings, tools and helpers. Nothing -// in the base outputs any CSS. - -@import "node_modules/govuk-frontend/dist/govuk/base"; - -// 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"; - -// 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"; - -// 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 %> - -/* -// Alternatively, you can import all components: -@import "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"; - -// 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"; - -/* -// 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. - -[Read more about the different parts of GOV.UK Frontend’s CSS](https://github.com/alphagov/govuk-frontend/tree/main/packages/govuk-frontend/src). - -## Import an individual component’s CSS using a single Sass import - -You can also import a component and all its dependencies without importing `node_modules/govuk-frontend/dist/govuk/base` first. - -For example, to import the button component, add the following to your Sass file: - -```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 - -If you want to make Sass import paths shorter, add `node_modules/govuk-frontend/dist` to either your: - -- [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 - -You can then import without using `node_modules/govuk-frontend/dist/` in your import path. For example: - -```scss -@import "govuk/components/button/button"; -``` - -## Override with your own CSS - -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. - -## 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. -``` - -You can silence the warnings caused by GOV.UK Frontend and other dependencies. 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) -- using the JavaScript API, [include `quietDeps: true`](https://sass-lang.com/documentation/js-api#quietdeps) in the `options` object - -You'll still see deprecation warnings if you're using `/` for division in your own Sass code. 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 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/include-css/index.html.md.erb b/source/include-css/index.html.md.erb new file mode 100644 index 00000000..11340ce5 --- /dev/null +++ b/source/include-css/index.html.md.erb @@ -0,0 +1,216 @@ +--- +title: Include CSS +weight: 30 +--- + +# Include CSS + +To include the CSS from GOV.UK Frontend, you should either: + +- add GOV.UK Frontend's CSS file to your HTML +- 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 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 to `govuk-frontend.min.css` inside the `` tag of your HTML page or page template. + +```html + + + + + +``` + +## 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: + + +```scss +@use "node_modules/govuk-frontend/dist/govuk" as *; +``` + +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. + +### Use `pkg:` URLs to shorten Sass URLs + +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. + +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. + +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 +@use "node_modules/govuk-frontend/dist/govuk" as * with ( + $govuk-assets-path: "/path/to/assets/" +); +``` + +## 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. + +@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. + +@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. + +@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: +@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. + +@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. + +@use "node_modules/govuk-frontend/dist/govuk/overrides"; + +/* +// Alternatively, you can import the specific groups of overrides +// you need for your project: + +// Display overrides - for example govuk-!-display-inline +@use "node_modules/govuk-frontend/dist/govuk/overrides/display"; + +// Spacing overrides - for example govuk-!-margin-4, govuk-!-static-padding-4 +@use "node_modules/govuk-frontend/dist/govuk/overrides/spacing"; + +// Text align overrides - for example govuk-!-text-align-left +@use "node_modules/govuk-frontend/dist/govuk/overrides/text-align"; + +// Typography overrides - for example govuk-!-font-size-19, govuk-!-font-weight-bold +@use "node_modules/govuk-frontend/dist/govuk/overrides/typography"; + +// Width overrides - for example govuk-!-width-two-thirds +@use "node_modules/govuk-frontend/dist/govuk/overrides/width"; +*/ + +``` + +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). + +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. + +## Use GOV.UK Frontend’s Sass API + +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 +@use "node_modules/govuk-frontend/dist/govuk/base" as *; + +// Use variable, functions and mixins from GOV.UK Frontend +``` + +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 + +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. + +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). + +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 caused by your own Sass code. 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..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](../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. + 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](../import-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/).