Skip to content

Commit

Permalink
docs: review and update production guidance
Browse files Browse the repository at this point in the history
  • Loading branch information
@colinrotherham
colinrotherham committed Mar 7, 2025
1 parent 888509e commit eb17538
Show file tree
Hide file tree
Showing 8 changed files with 367 additions and 177 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Raising an issue ensures they are openly discussed and before spending any time

## Contributing code

### Node Versions
### Node.js versions

We recommend using [Node Version Manager](https://github.com/nvm-sh/nvm#installing-and-updating) while working on this project.

Expand Down
111 changes: 111 additions & 0 deletions docs/production/import-css.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
---
layout: layouts/get-started.njk
subsection: Setup for production
title: Import MoJ Frontend CSS
eleventyNavigation:
key: Import CSS
parent: Setup for production
order: 50
excerpt: "To load the CSS from MoJ Frontend, you can either add MoJ Frontend and GOV.UK Frontend’s CSS files to your HTML or load the CSS into your own Sass file."
---

To use the CSS from MoJ Frontend and GOV.UK Frontend, you can either:

- add MoJ Frontend and GOV.UK Frontend’s CSS files to your HTML
- load the CSS files 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:

- serve the CSS files from the combined stylesheets folders – recommended
- copy the CSS files into your application

## Serve the CSS files from the combined stylesheets folders – recommended

Set up your routing so requests for the CSS files in `<YOUR-SITE-URL>/stylesheets` are served from both `/node_modules/govuk-frontend/dist/govuk` and `/node_modules/@ministryofjustice/frontend/moj`.

For example if you’re using [express.js](https://expressjs.com/), add the following to your `app.js` file:

```js
router.use('/stylesheets', [
express.static('node_modules/@ministryofjustice/frontend/moj'),
express.static('node_modules/govuk-frontend/dist/govuk')
])
```

Then link the CSS files inside the `<head>` tag of your HTML page or page template.

```html
<head>
<!-- // ... -->
<link rel="stylesheet" href="/stylesheets/govuk-frontend.min.css">
<link rel="stylesheet" href="/stylesheets/moj-frontend.min.css">
<!-- // ... -->
</head>
```

## Copy the CSS files into your application

If you decide to copy the CSS files instead, copy both `/node_modules/@ministryofjustice/frontend/moj/moj-frontend.min.css` and `/node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css` into `<YOUR-APP>/stylesheets` and link the CSS files using the example above.

You should use an automated task or your build pipeline to copy the files, so your project folder stays up to date when updates to MoJ Frontend and GOV.UK Frontend are released.

## Load using Sass

To load all the Sass rules from both MoJ Frontend and GOV.UK Frontend, add the following to your Sass file:

```scss
@forward "node_modules/govuk-frontend/dist/govuk";
@forward "node_modules/@ministryofjustice/frontend/moj/all";
```

## Load an individual component’s CSS using a single Sass forward

You can also load a component and all its dependencies without loading `node_modules/@ministryofjustice/frontend/moj/all` first.

To load the button menu component for example, add the following to your Sass file:

```scss
@forward "node_modules/@ministryofjustice/frontend/moj/components/button-menu/button-menu";
```

## Simplify Sass load paths

If you want to make Sass load paths shorter, add both `node_modules/@ministryofjustice/frontend` and `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

For example, using the Sass compiler:

```js
compile('src/stylesheets/application.scss', {
loadPaths: [
'node_modules/@ministryofjustice/frontend',
'node_modules/govuk-frontend/dist',
],
quietDeps: true
})
```

You can then load stylesheets without using `node_modules/@ministryofjustice/frontend` and `node_modules/govuk-frontend/dist` in your paths:

```scss
@forward "govuk";
@forward "moj/all";
```

## Override with your own CSS

If you want to override MoJ Frontend’s styles with your own styles, `@forward` MoJ Frontend’s styles before your own Sass rules.

## Silence deprecation warnings from dependencies in Dart Sass

You may see deprecation warnings when compiling your Sass. For example:

```console
DEPRECATION WARNING: Using / for division is deprecated and will be removed in Dart Sass 2.0.0.
```

We’re currently unable to fix deprecation warnings from MoJ Frontend. However, you can silence the warnings by following the [Silence deprecation warnings from dependencies in Dart Sass](https://frontend.design-system.service.gov.uk/import-css/#simplify-sass-import-paths) guidance from GOV.UK Frontend.
77 changes: 77 additions & 0 deletions docs/production/import-font-and-image-assets.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
layout: layouts/get-started.njk
subsection: Setup for production
title: Import MoJ Frontend font and image assets
eleventyNavigation:
key: Import font and image assets
parent: Setup for production
order: 60
excerpt: "To use the font and image assets from MoJ Frontend and GOV.UK Frontend, you can either serve the assets from the combined assets folders or copy the font and image files into your application"
---

To use the font and image assets from MoJ Frontend and GOV.UK Frontend, you can either:

- serve the assets from the combined assets folders – recommended
- copy the font and image files into your application

## Serve the assets from the combined assets folders – recommended

Set up your routing so requests for files in `<YOUR-SITE-URL>/assets` are served from both `/node_modules/govuk-frontend/dist/govuk/assets` and `/node_modules/@ministryofjustice/frontend/moj/assets`.

For example if you’re using [express.js](https://expressjs.com/), add the following to your `app.js` file:

```js
router.use('/assets', [
express.static('node_modules/@ministryofjustice/frontend/moj/assets'),
express.static('node_modules/govuk-frontend/dist/govuk/assets')
])
```

## Copy the font and image files into your application

If you decide to copy the assets instead, copy the:

- `/node_modules/@ministryofjustice/frontend/moj/assets/images` contents to `<YOUR-APP>/assets/images`
- `/node_modules/govuk-frontend/dist/govuk/assets/images` contents to `<YOUR-APP>/assets/images`
- `/node_modules/govuk-frontend/dist/govuk/assets/fonts` contents to `<YOUR-APP>/assets/fonts`

You should use an automated task or your build pipeline to copy the files, so your project folder stays up to date when updates to MoJ Frontend and GOV.UK Frontend are released.

### If you have your own folder structure

If you use a different folder structure than `<YOUR-APP>/assets/images` and `<YOUR-APP>/assets/fonts`, you can set Sass variables so that Sass builds the CSS to point to your folders.

Set one of the following with a `@use` line in your Sass file:

- `$govuk-assets-path`
- `$govuk-images-path` and `$govuk-fonts-path`

Set the `$govuk-assets-path` variable if your `font` and `image` folders have the same parent folder. For example:

```scss
// Configure GOV.UK Frontend
@use "node_modules/govuk-frontend/dist/govuk" as * with (
$govuk-assets-path: "/<YOUR-ASSETS-FOLDER>/"
);

// Share config with MOJ Frontend
@forward "node_modules/@ministryofjustice/frontend/moj/all" with (
$moj-assets-path: $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:

```scss
// Configure GOV.UK Frontend
@use "node_modules/govuk-frontend/dist/govuk" as * with (
$govuk-images-path: "/<YOUR-IMAGES-FOLDER>/",
$govuk-fonts-path: "/<YOUR-FONTS-FOLDER>/"
);

// Share config with MOJ Frontend
@forward "node_modules/@ministryofjustice/frontend/moj/all" with (
$moj-images-path: $govuk-images-path,
$moj-fonts-path: $govuk-fonts-path
);
```
38 changes: 9 additions & 29 deletions docs/production/install-moj-frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,36 +10,16 @@ eleventyNavigation:
excerpt: "To start using MoJ styles, components and patterns contained here, you’ll need to include MoJ Frontend in your project."
---

This guide explains how to set up your project so you can start using the styles and coded examples in the MoJ Design System in production.
MoJ Frontend provides the elements developers need to create consistent, easy to use, fast and secure government services.

## Before you start
Use this technical documentation to find out how to:

First you must have followed the [GOV.UK Design System production setup guide](https://design-system.service.gov.uk/get-started/production/).
- [Install with Node.js package manager (npm)](/production/installing-with-npm/)
- [Use Nunjucks](/production/use-nunjucks/)
- [Import CSS](/production/import-css/)
- [Import font and image assets](/production/import-font-and-image-assets/)
- [Import JavaScript](/production/setting-up-javascript/)

## Include the MoJ Frontend in your project
You can also use the option to [try using precompiled files](/production/installing-compiled/) to test how MoJ Frontend works in your application.

To start using MoJ styles, components and patterns contained here, you’ll need to include MoJ Frontend in your project.

### Option 1: install using npm

We recommend [installing MoJ Frontend using npm](/production/installing-with-npm/). Using this option, you will be able to:

- selectively include the CSS or JavaScript for individual components
- build your own styles or components based on the palette or typography and spacing mixins
- customise the build (for example, overriding colours or enabling global styles)
- use the component Nunjucks templates

You will also need to [set up JavaScript](/production/setting-up-javascript/) if you want to use any interactive components.

### Option 2: include compiled files

If your project does not use npm, or if you want to try out MoJ Frontend in your project without installing it through npm, you can [download and include compiled stylesheets, JavaScript and the asset files](/production/installing-compiled/).

Using this option, you will be able to include all the CSS and JavaScript of GOV.UK Frontend in your project.

You will not be able to:

- selectively include the CSS or JavaScript for individual components
- build your own styles or components based on the palette or typography and spacing mixins
- customise the build, for example, overriding colours or enabling global styles
- use the component Nunjucks templates
There are live examples of MoJ Frontend components, and guidance on using them in your service, in the [MoJ Design System](/).
90 changes: 39 additions & 51 deletions docs/production/installing-compiled.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
layout: layouts/get-started.njk
subsection: Setup for production
title: Install MoJ Frontend with compiled files
title: Try MoJ Frontend using precompiled files
redirect_from: /get-started/installing-compiled
eleventyNavigation:
key: Install with compiled files
key: Try MoJ Frontend using precompiled files
parent: Setup for production
order: 30
excerpt: "If your project does not use npm (or you want to try out MoJ Frontend without installing it through npm) download and include compiled stylesheets."
Expand All @@ -17,72 +17,60 @@ You can install MoJ Frontend using the compiled files released with each version
- customise the build, for example, overriding colours or enabling global styles
- use the component Nunjucks templates

In a live application, we recommend that you [install with npm](/production/installing-with-npm/) instead. This will allow you to better integrate the library and more easily upgrade.
<div class="govuk-warning-text">
<span class="govuk-warning-text__icon" aria-hidden="true">!</span>
<strong class="govuk-warning-text__text">
<span class="govuk-visually-hidden">Warning</span>
In your live application, you should <a href="/production/installing-with-npm/">install with Node.js package manager (npm)</a> instead.
</strong>
</div>

## Copy the files

1. Download the `release-<VERSION-NUMBER>.zip` file at the bottom of the [latest MoJ Frontend release note](https://github.com/ministryofjustice/moj-frontend/releases/latest).
2. Unzip the zip file.
3. Copy the `assets` folder to the root of your project’s public folder, so that for example `<YOUR-SITE-URL>/assets/images/moj-logotype-crest.png` shows the `images/moj-logotype-crown.png` image in your users’ browsers.
4. Copy the 2 `.css` files to a stylesheets folder in the root of your project’s public folder, so that for example `<YOUR-SITE-URL>/stylesheets/moj-frontend.min.css` shows the CSS file in your users’ browsers.
5. Copy the `.js` file to a JavaScript folder in the root of your project’s public folder, so that for example `<YOUR-SITE-URL>/javascript/moj-frontend.min.js` shows the JavaScript file in your users’ browsers.

## Check an example page

### With the GOV.UK Design System
## Copy and install the precompiled files

1. Follow [the instructions for installing the GOV.UK Design System](https://frontend.design-system.service.gov.uk/install-using-precompiled-files/)
2. Add `link` tags for the MoJ Frontend CSS, alongside the GOV.UK ones in the `head`:
```html
<link rel="stylesheet" href="/stylesheets/moj-frontend.min.css" />
```
3. Add `script` tags for the MoJ Frontend JavaScript, alongside the GOV.UK at the bottom of the `body`. This includes jQuery, which is a dependency of MoJ Frontend.
```html
<script
src="https://code.jquery.com/jquery-3.6.0.min.js"
integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4="
crossorigin="anonymous"
></script>
<script src="/javascript/moj-frontend.min.js"></script>
<script>
window.MOJFrontend.initAll()
</script>
```
2. Download the `release-<VERSION-NUMBER>.zip` file at the bottom of the [latest MoJ Frontend release note](https://github.com/ministryofjustice/moj-frontend/releases/latest).
3. Unzip the zip file.
4. Copy the `assets` folder to the root of your project’s public folder, so that for example `<YOUR-SITE-URL>/assets/images/moj-logotype-crest.png` shows the `images/moj-logotype-crown.png` image in your users’ browsers.
5. Copy the `.css` file to a stylesheets folder in the root of your project’s public folder, so that for example `<YOUR-SITE-URL>/stylesheets/moj-frontend.min.css` shows the CSS file in your users’ browsers.
6. Copy the `.js` file to a JavaScript folder in the root of your project’s public folder, so that for example `<YOUR-SITE-URL>/javascripts/moj-frontend.min.js` shows the JavaScript file in your users’ browsers.

### Without the GOV.UK Design System
## Update your example page to check for errors

It is unlikely that you would ever want to install the MoJ Design System alone, but if so you can follow the guide below to check that it is working.

1. Create a page in your project using the following HTML (in your live application, you should use the [Design System page template](https://design-system.service.gov.uk/styles/page-template/) instead):
1. Update the example page in your project to match the following HTML (in your live application, you should use the [Design System page template](https://design-system.service.gov.uk/styles/page-template/) instead):

```html
<!DOCTYPE html>
<html lang="en" class="govuk-template ">
<html lang="en" class="govuk-template">
<head>
<title>Example - MoJ Frontend</title>
<meta
name="viewport"
content="width=device-width, initial-scale=1, viewport-fit=cover"
/>
<link rel="stylesheet" href="/stylesheets/moj-frontend.min.css" />
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<link rel="stylesheet" href="/stylesheets/govuk-frontend-<VERSION-NUMBER>.min.css" />
<link rel="stylesheet" href="/stylesheets/moj-frontend-<VERSION-NUMBER>.min.css">
</head>
<body>
<body class="govuk-template__body">
<script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

<!-- component HTML -->
<script
src="https://code.jquery.com/jquery-3.6.0.min.js"
integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4="
crossorigin="anonymous"
></script>
<script src="/javascript/moj-frontend.min.js"></script>
<script>

<script type="module" src="https://code.jquery.com/jquery-3.6.0.min.js" integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script>
<script type="module" src="/javascripts/govuk-frontend-<VERSION-NUMBER>.min.js"></script>
<script type="module" src="/javascripts/moj-frontend-<VERSION-NUMBER>.min.js"></script>

<script type="module">
import * as GOVUKFrontend from '/javascripts/govuk-frontend-<VERSION-NUMBER>.min.js'
window.GOVUKFrontend = GOVUKFrontend
window.GOVUKFrontend.initAll()
window.MOJFrontend.initAll()
</script>
</body>
</html>
```

2. Go to the [Add another component](/components/add-another/) on the Design System website and copy the HTML from the first example.
2. Replace `<VERSION-NUMBER>` so the 5 filenames match the files you [copied from MoJ Frontend and GOV.UK Frontend's GitHub repos](#copy-and-install-the-precompiled-files).

3. Go to the [add another component](/components/add-another/) on the Design System website and copy the HTML from the first example.

3. Replace `<!-- component HTML -->` with the accordion HTML you copied.
4. Replace `<!-- component HTML -->` with the add another HTML you copied.

4. Run your application - you can check it works the same way as the [Add another component example](/examples/add-another/) by clicking the "Add another person" button.
5. Run your application - you can check it works the same way as the [add another component example](/examples/add-another/) by clicking the "Add another person" button.
Loading

0 comments on commit eb17538

Please sign in to comment.