From 6085471ce4b0be504fdf51161e3f83f30279f6c6 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Wed, 2 Nov 2022 16:51:25 +0000 Subject: [PATCH 1/6] Bump jstransformer-marked to 1.2.0 We use `metalsmith-in-place` to compile our markdown and nunjucks. That in turn has a dependency on `jstransformer`, which then requires transformers of the required type (in this case, `jstransformer-marked`). We have `marked` as a direct dependency, but we're actually at the whim of `jstransformer-marked`'s dependency tree when it comes to processing our files with `metalsmith-in-place`. v1.0.3 of `jstransformer-marked` uses `marked` ^0.3.9 (0.3.19 in our package-lock). v1.2.0 uses `marked` 4.0.18. This creates... problems. --- package-lock.json | 22 ++++++---------------- package.json | 2 +- 2 files changed, 7 insertions(+), 17 deletions(-) diff --git a/package-lock.json b/package-lock.json index af38658be7..894154de01 100644 --- a/package-lock.json +++ b/package-lock.json @@ -35,7 +35,7 @@ "jest-environment-jsdom": "^29.3.1", "jest-puppeteer": "^6.1.1", "js-beautify": "^1.14.7", - "jstransformer-marked": "~1.0.3", + "jstransformer-marked": "1.2.0", "jstransformer-nunjucks": "^1.1.0", "marked": "^4.2.2", "metalsmith": "^2.5.1", @@ -10725,25 +10725,15 @@ } }, "node_modules/jstransformer-marked": { - "version": "1.0.3", + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/jstransformer-marked/-/jstransformer-marked-1.2.0.tgz", + "integrity": "sha512-GWWtG0JSv0BfB6m9ZjlEO2fzctRop0YixdpQSm4mjGHzEqGjmsKABwinypgLWf+7x6RL6OV95xTlke0SzPswTg==", "dev": true, - "license": "MIT", "dependencies": { - "marked": "^0.3.9" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/jstransformer-marked/node_modules/marked": { - "version": "0.3.19", - "dev": true, - "license": "MIT", - "bin": { - "marked": "bin/marked" + "marked": "^4.0.17" }, "engines": { - "node": ">=0.10.0" + "node": ">=8.17.0" } }, "node_modules/jstransformer-nunjucks": { diff --git a/package.json b/package.json index 2504536deb..0320277898 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "jest-environment-jsdom": "^29.3.1", "jest-puppeteer": "^6.1.1", "js-beautify": "^1.14.7", - "jstransformer-marked": "~1.0.3", + "jstransformer-marked": "1.2.0", "jstransformer-nunjucks": "^1.1.0", "marked": "^4.2.2", "metalsmith": "^2.5.1", From cf11cbf9e8f3b03a891d99a92f8429ff0c0bf704 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Wed, 2 Nov 2022 17:01:13 +0000 Subject: [PATCH 2/6] Add autolinks to markdown. Pedantic rules require angle brackets around raw URLs in order to autolink them. This was a bit buggy in early versions of Marked, which is why it's flown under our radar till we bumped Marked. Switching to Github Flavoured Markdown should negate the need to do this and allow future editors not to think about it, but it's probably still worth being widely compliant in case anything changes down the line. --- src/accessibility.md.njk | 6 +++--- src/community/develop-a-component-or-pattern/index.md.njk | 2 +- .../propose-a-content-change-using-github/index.md.njk | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/accessibility.md.njk b/src/accessibility.md.njk index 8c30d52f69..fecfb9d007 100644 --- a/src/accessibility.md.njk +++ b/src/accessibility.md.njk @@ -14,7 +14,7 @@ This page explains how the team works to ensure the Design System and Frontend a ## Accessibility statement for the GOV.UK Design System website -This accessibility statement applies to the GOV.UK Design System at https://design-system.service.gov.uk/, and the components and patterns from the GOV.UK Frontend codebase which appear in the examples throughout the Design System. +This accessibility statement applies to the GOV.UK Design System at , and the components and patterns from the GOV.UK Frontend codebase which appear in the examples throughout the Design System. The GOV.UK Design System team wants as many people as possible to be able to use this website. For example, that means you should be able to: @@ -30,7 +30,7 @@ The team has also made the website text as simple as possible to understand. ### Feedback and contact information -The GOV.UK Design System team is always looking to improve the accessibility of this website. If you find any problems that are not listed on this page or think this website is not meeting accessibility requirements, email the GOV.UK Design System team at govuk-design-system-support@digital.cabinet-office.gov.uk +The GOV.UK Design System team is always looking to improve the accessibility of this website. If you find any problems that are not listed on this page or think this website is not meeting accessibility requirements, email the GOV.UK Design System team at The GOV.UK Design System team will review your request and get back to you in 2 working days. @@ -103,4 +103,4 @@ If you're using these products, you should start [updating your service to use t If you have any questions or need help, contact the GOV.UK Design System team: - using the [#govuk-design-system channel on cross-government Slack](https://ukgovernmentdigital.slack.com/app_redirect?channel=govuk-design-system) -- by email at govuk-design-system-support@digital.cabinet-office.gov.uk +- by email at diff --git a/src/community/develop-a-component-or-pattern/index.md.njk b/src/community/develop-a-component-or-pattern/index.md.njk index f69f8b0c81..1fdc0757c3 100644 --- a/src/community/develop-a-component-or-pattern/index.md.njk +++ b/src/community/develop-a-component-or-pattern/index.md.njk @@ -9,7 +9,7 @@ order: 4 The Design System team focuses on developing [prioritised components and patterns](/community/upcoming-components-patterns/) with the community. However, anyone can choose to work on something from the [list of discussions on GitHub](https://github.com/orgs/alphagov/projects/43/views/2). -If you see something you'd like to work on, join the discussion in the contribution's issue page or email the Design System team at govuk-design-system-support@digital.cabinet-office.gov.uk. +If you see something you'd like to work on, join the discussion in the contribution's issue page or email the Design System team at . If you have an idea for a new component or pattern that’s not already on the list, [propose it](/community/propose-a-component-or-pattern/). diff --git a/src/community/propose-a-content-change-using-github/index.md.njk b/src/community/propose-a-content-change-using-github/index.md.njk index b2b02400be..295504cc73 100644 --- a/src/community/propose-a-content-change-using-github/index.md.njk +++ b/src/community/propose-a-content-change-using-github/index.md.njk @@ -21,7 +21,7 @@ If you do not have one already, you can [create a GitHub account for free](https If you get stuck whilst following these steps and you need help, you can: - get in touch on [#govuk-design-system channel on cross-government Slack](https://ukgovernmentdigital.slack.com/app_redirect?channel=govuk-design-system) -- email the GOV.UK Design System team on
govuk-design-system-support@digital.cabinet-office.gov.uk +- email the GOV.UK Design System team on
## 1. Go to the page you want to edit From 9b3d03892ee06a088f94e654fc0563c2e7b9f56d Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Wed, 2 Nov 2022 21:33:56 +0000 Subject: [PATCH 3/6] Fix list spacing With pedantic rules, we must separate a list from the preceding text with a blank line. This is more relaxed in Github Flavoured Markdown, but no reason not to go for wider compliance. --- src/community/roadmap/index.md.njk | 3 +++ src/components/accordion/index.md.njk | 2 ++ src/components/cookie-banner/index.md.njk | 9 +++++++++ src/components/footer/index.md.njk | 4 ++-- src/components/notification-banner/index.md.njk | 1 + src/components/pagination/index.md.njk | 1 + src/components/radios/index.md.njk | 1 + src/components/tabs/index.md.njk | 1 + .../extending-and-modifying-components/index.md.njk | 1 + src/patterns/confirm-a-phone-number/index.md.njk | 6 ++++-- src/patterns/cookies-page/index.md.njk | 1 + src/patterns/dates/index.md.njk | 1 + src/patterns/question-pages/index.md.njk | 7 ++++--- src/patterns/start-using-a-service/index.md.njk | 2 ++ src/privacy-policy.md.njk | 11 +++++++++++ src/styles/typography/index.md.njk | 9 +++++---- 16 files changed, 49 insertions(+), 11 deletions(-) diff --git a/src/community/roadmap/index.md.njk b/src/community/roadmap/index.md.njk index c88cbb1e0b..999262ad0f 100644 --- a/src/community/roadmap/index.md.njk +++ b/src/community/roadmap/index.md.njk @@ -29,6 +29,7 @@ We recently: ## Working on now We're working to: + - host community co-design work to [turn task-list into a component](/patterns/task-list-pages/) - host community co-design work to make maps better - release the [Hide this page](https://github.com/alphagov/govuk-design-system-backlog/issues/213) component @@ -38,6 +39,7 @@ We're working to: ## Coming up next We're getting ready to: + - implement our [proposal](https://github.com/alphagov/govuk-frontend/discussions/2607) for reducing browser support - release the [Summary Card](https://github.com/alphagov/govuk-design-system-backlog/issues/210) variant - make it easier to find information about contributing and the community @@ -47,6 +49,7 @@ We're getting ready to: ## Future plans We plan to: + - investigate Sass module system - make sure the Design System meets WCAG 2.2 - investigate removing compatibility mode diff --git a/src/components/accordion/index.md.njk b/src/components/accordion/index.md.njk index 23f66b6b9b..6e9955c796 100644 --- a/src/components/accordion/index.md.njk +++ b/src/components/accordion/index.md.njk @@ -55,6 +55,7 @@ Do not use the accordion component if the amount of content inside will make the Accordions, [tabs](/components/tabs/) and [details](/components/details/) all work by hiding sections of content which a user can choose to reveal. Avoid using any of these components within one another. If you decide to use one of these components, consider if: + - the user needs to look at more than one section at a time — an accordion can show multiple sections at a time, unlike tabs - the user needs to switch quickly between sections — tabs can show content without pushing other sections down the page, unlike accordions - there are many sections of content — accordions can fit more sections as they’re arranged vertically, unlike tabs which are arranged horizontally @@ -71,6 +72,7 @@ The accordion component uses JavaScript. When JavaScript is not available, users An accordion will usually start with all sections hidden. To show a section, the user can interact anywhere in the heading button. The heading button includes all of these areas: + - heading text - summary line (if you decide to add one) - call-to-action text to 'show' or 'hide' diff --git a/src/components/cookie-banner/index.md.njk b/src/components/cookie-banner/index.md.njk index fa4b677184..bd6f8f5624 100644 --- a/src/components/cookie-banner/index.md.njk +++ b/src/components/cookie-banner/index.md.njk @@ -20,10 +20,12 @@ Allow users to accept or reject cookies which are not essential to making your s Use this component if your service sets any cookies on a user’s device. Remember, you must: + - tell users about the cookies your service sets on their device - let users accept or reject any cookies that are not essential to providing your service The term ‘non-essential cookies’ includes: + - HTML5 local storage - service workers - any other technologies that store files on the user’s device @@ -37,6 +39,7 @@ This component page shows several options for using a cookie banner, based on th [Audit and categorise your cookies](/patterns/cookies-page/#auditing-and-categorising-your-cookies) as shown in the cookies page pattern to help you choose the best option for your service. You must not take the information on this page as legal advice. Your organisation is responsible and accountable for what they do to comply with data protection legislation, such as: + - Privacy and Electronic Communications Regulations (PECR) - General Data Protection Regulation (GDPR) @@ -45,15 +48,18 @@ Check with your organisation's privacy expert to see how data protection legisla ## How it works Show the cookie banner every time the user accesses your service until they either: + - accept or reject cookies using the buttons in the cookie banner - save their cookie preferences on the service’s [cookies page](/patterns/cookies-page/) Once the user has accepted or rejected cookies, the cookie banner should: + - hide the cookie banner message - show a confirmation message — and a 'hide' button to let the user close the banner - set a cookie to save the user’s preferences for 1 year Make sure the cookie banner does not: + - show when the user visits again, once their preferences have been saved - set any non-essential cookies unless the user accepted them on a previous visit @@ -114,6 +120,7 @@ When the page loads, the `hidden` html attribute hides the component, as well as Use JavaScript to show cookie banner messages to users that have not accepted or rejected cookies by removing the `hidden` attribute as needed. Write your own JavaScript code so that when the user accepts or rejects cookies, the cookie banner will: + - hide the cookie message by adding the hidden attribute - show a confirmation message by removing its hidden attribute - give the confirmation message the `tabindex="-1"` and `role="alert"` attributes — this will allow the element to be focused so assistive technology can read the message @@ -155,6 +162,7 @@ You can use this example text for a service which sets essential and analytics c ### If you’re using more than one type of non-essential cookie You can use this example text for a service that set: + - essential cookies - analytics cookies - functional cookies to remember the user’s settings but are not essential @@ -173,6 +181,7 @@ When the user accepts or rejects cookies, a confirmation message will display. F However, a visible focus indicator does not display around the confirmation message. This is different from the notification banner, which does display a visible focus indicator. We decided to remove the visible focus indicator from the confirmation message for a few reasons, as: + - a user cannot interact with it - it's the first element, at the very top of the page - it displays in place of the cookie message, which is the last thing the user interacted with diff --git a/src/components/footer/index.md.njk b/src/components/footer/index.md.njk index b26d35488a..dfeda6e896 100644 --- a/src/components/footer/index.md.njk +++ b/src/components/footer/index.md.njk @@ -36,8 +36,8 @@ Make it clear whether content is available for re-use - and if it is, under what ## Adding links You can add links to: -- [privacy notice](https://www.gov.uk/service-manual/design/collecting-personal-information-from-users -) + +- [privacy notice](https://www.gov.uk/service-manual/design/collecting-personal-information-from-users) - [accessibility statement](https://www.gov.uk/service-manual/helping-people-to-use-your-service/publishing-information-about-your-services-accessibility) - [cookies page](/patterns/cookies-page/) - terms and conditions diff --git a/src/components/notification-banner/index.md.njk b/src/components/notification-banner/index.md.njk index 400385a5b9..6ee2120a7d 100644 --- a/src/components/notification-banner/index.md.njk +++ b/src/components/notification-banner/index.md.njk @@ -93,5 +93,6 @@ To make the green version of the notification banner accessible: ## Research on this component We need more research to understand: + - how common it is for users to miss important information in notification banners (including users of assistive technology, who might skip straight to the `h1`) - whether it’s sometimes helpful to allow users to dismiss notifications, and how to do this diff --git a/src/components/pagination/index.md.njk b/src/components/pagination/index.md.njk index 5bdfaff79a..98c3cc7500 100644 --- a/src/components/pagination/index.md.njk +++ b/src/components/pagination/index.md.njk @@ -16,6 +16,7 @@ Help users navigate forwards and backwards through a series of pages. For exampl ## When to use this component Consider using pagination when: + - showing all the content on a single page makes the page take too long to load - most users will only need the content on the first page or first few pages diff --git a/src/components/radios/index.md.njk b/src/components/radios/index.md.njk index 585a9e5e69..a5bf785388 100644 --- a/src/components/radios/index.md.njk +++ b/src/components/radios/index.md.njk @@ -63,6 +63,7 @@ If you're asking more than one question on the page, do not set the contents of In some cases, you can choose to display radios 'inline' beside one another (horizontally). Only use inline radios when: + - the question only has two options - both options are short diff --git a/src/components/tabs/index.md.njk b/src/components/tabs/index.md.njk index 77c5fd0933..265570bd79 100644 --- a/src/components/tabs/index.md.njk +++ b/src/components/tabs/index.md.njk @@ -48,6 +48,7 @@ Test your content without tabs first. Consider if it’s better to: Tabs, [accordions](/components/accordion/), and [details](/components/details/) all hide sections of content which a user can choose to reveal. If you decide to use one of these components, consider if: + - the user does not need to view more than one section at a time — consider using tabs - the user needs to switch quickly between sections — tabs can show content without pushing other sections down the page, unlike accordions - there are many pieces of content — tabs can fit fewer sections as they’re arranged horizontally, unlike accordions which are arranged vertically diff --git a/src/get-started/extending-and-modifying-components/index.md.njk b/src/get-started/extending-and-modifying-components/index.md.njk index fbef2a495f..6524d28894 100644 --- a/src/get-started/extending-and-modifying-components/index.md.njk +++ b/src/get-started/extending-and-modifying-components/index.md.njk @@ -13,6 +13,7 @@ You might need to extend or modify components in the GOV.UK Design System from t - meet a specific user need in your service Consider whether your changes: + - help the long term maintenance of your service - allow you to safely install updates from the GOV.UK Design System - reduce the risk of technical debt diff --git a/src/patterns/confirm-a-phone-number/index.md.njk b/src/patterns/confirm-a-phone-number/index.md.njk index b92f1eefcb..49a93d504a 100644 --- a/src/patterns/confirm-a-phone-number/index.md.njk +++ b/src/patterns/confirm-a-phone-number/index.md.njk @@ -25,8 +25,9 @@ You can ask for a security code every time a user signs in or only once per devi ## How it works Send and ask the user for the security code when they: -* create an account -* sign in later + +- create an account +- sign in later ### When the user creates an account @@ -48,6 +49,7 @@ Let the user enter the code in whatever format is familiar to them. Allow additi Give a time limit of 15 minutes for the user to enter the code — the code should expire after this time limit. If the user enters an expired code that was sent more than: + - 15 minutes ago, show a ‘code has expired’ error message and send the user a new code - 2 hours ago, show an ‘incorrect security code’ message, even if the code was correct diff --git a/src/patterns/cookies-page/index.md.njk b/src/patterns/cookies-page/index.md.njk index b7809d793b..8e63bc9127 100644 --- a/src/patterns/cookies-page/index.md.njk +++ b/src/patterns/cookies-page/index.md.njk @@ -48,6 +48,7 @@ You should also identify if each cookie is set on the server or client. The result of your audit will guide your cookie policy and how the service should use a cookies page and cookie banner. The [cookie banner component](/components/cookie-banner/) shows several options for using a cookie banner for services that: + - only set essential cookies - sets non-essential cookies on the server - including services that also set non-essential cookies on the client - sets non-essential cookies - but only on the client diff --git a/src/patterns/dates/index.md.njk b/src/patterns/dates/index.md.njk index 73fe7b91b5..16d5f7c710 100644 --- a/src/patterns/dates/index.md.njk +++ b/src/patterns/dates/index.md.njk @@ -21,6 +21,7 @@ Follow this pattern whenever you need users to provide or select a date as part The way you should ask users for dates depends on the types of date you’re asking for. Dates you may need users to provide include: + - memorable dates, like a date of birth or marriage - dates from documents or cards, like a passport or credit card - approximate dates, like ‘December 2017’ diff --git a/src/patterns/question-pages/index.md.njk b/src/patterns/question-pages/index.md.njk index ded9a20960..d25d7d0922 100644 --- a/src/patterns/question-pages/index.md.njk +++ b/src/patterns/question-pages/index.md.njk @@ -95,9 +95,10 @@ Do not use hint text if you need to give a lengthy explanation with lists and pa Do not use links in hint text. While screen readers will read out the link text when describing the field, they will not tell users the text is a link. If you're asking a question that needs a detailed explanation, use: -* a `h1` heading that's a statement (for example, 'Interview needs') rather than a question -* whatever mix of text, paragraphs, lists and examples best explains your question to users -* a label, above the form input, that asks users a specific question – for example, 'Do you have any interview needs?' + +- a `h1` heading that's a statement (for example, 'Interview needs') rather than a question +- whatever mix of text, paragraphs, lists and examples best explains your question to users +- a label, above the form input, that asks users a specific question – for example, 'Do you have any interview needs?' {{ example({group: "patterns", item: "question-pages", example: "explanatory-text", html: true, nunjucks: true, open: false}) }} diff --git a/src/patterns/start-using-a-service/index.md.njk b/src/patterns/start-using-a-service/index.md.njk index da9ea42e62..dced5418d5 100644 --- a/src/patterns/start-using-a-service/index.md.njk +++ b/src/patterns/start-using-a-service/index.md.njk @@ -19,6 +19,7 @@ The public-facing version of your service will need to start on a GOV.UK content ## How it works A service's start point should: + - give the user just enough information to help them understand what the service does and whether it will meet their need — including [giving the service a name that reflects the problem it solves for users](https://www.gov.uk/service-manual/design/naming-your-service) - include a ‘button’ linking into the service, with text that’s consistent with the action you’re asking users to take — for example, ‘Start now’, ‘Sign in’ or ‘Register or update your details’ (if you need a secondary call to action, use a standard link) - let users sign in, resume an application they’ve already started or update their details (if relevant) @@ -47,6 +48,7 @@ The content team at GDS is responsible for creating mainstream start points on G ### Mainstream start points For a mainstream start point, the options are: + - a simple start page - a start point within a multipart guide diff --git a/src/privacy-policy.md.njk b/src/privacy-policy.md.njk index 65e0ea9839..d7d55f2103 100644 --- a/src/privacy-policy.md.njk +++ b/src/privacy-policy.md.njk @@ -20,6 +20,7 @@ The GOV.UK Design System is provided by the [Government Digital Service (GDS)](h For a number of the activities that we undertake to complete our function, we need to process personal data. The purposes are to manage and coordinate the [GOV.UK Design System](/) and contributions from the community. This includes: + - contribution process, including working with you on contributions, where you’ve proposed to add or improve part of the Design System - support, including both the provision of support and responses to user enquiries - feedback, including gathering it to improve our services, and responding to it, if you have asked us to @@ -30,11 +31,13 @@ This includes: We collect certain information and data about you when you use the [GOV.UK Design System](/). We collect your: + - name - business contact details - user profile on collaboration tools and platforms If you sign up to our mailing list, we'll collect your: + - name - email address and business contact details @@ -47,6 +50,7 @@ The legal basis for processing this data is that processing is necessary for the We also carry out performance analysis to see how you use the GOV.UK Design System and how well the site performs on your device during your visit — we do this to make sure it is meeting the needs of its users and improve it. Where you provide consent, we collect the following information: + - your IP address - the pages you visit on the GOV.UK Design System - how long you spend on each GOV.UK Design System page @@ -58,6 +62,7 @@ The legal basis for performing web analytics is your consent. You will be asked ## How long we keep your data We will only keep your personal data for as long as: + - the law requires us to - we need for the purposes listed above @@ -74,12 +79,14 @@ Your personal data may be transferred outside the United Kingdom while being pro ## Providers we use As part of [GOV.UK Design System](/) we share your personal data with data processors who provide us with: + - software collaboration platforms when you share research, feedback or make a contribution - mailing list providers when you sign up to receive emails from us - [support providers](https://www.gov.uk/government/publications/government-digital-service-user-support-privacy-notice/user-support-privacy-notice) when you contact us for assistance - web analytics services We will not: + - sell or rent your data to third parties - share your data with third parties for marketing purposes @@ -91,16 +98,19 @@ We are committed to doing all that we can to keep your data secure. We set up sy ## Your rights You have the right to request: + - information about how your personal data is processed - a copy of that personal data - that anything inaccurate in your personal data is corrected without undue delay You can also: + - raise an objection about how your personal data is processed - request that your personal data is erased if there is no longer a justification for it - ask that the processing of your personal data is restricted in certain circumstances If your personal data is processed on the basis of consent, you have the right to: + - withdraw consent to the processing of your personal data at any time - request a copy of your personal data - this copy will be provided in a structured, commonly used and machine-readable format @@ -109,6 +119,7 @@ If your personal data is processed on the basis of consent, you have the right t ## Questions and complaints Contact the GDS Privacy Office if you: + - have any questions about anything in this document - think that your personal data has been misused or mishandled - want to make a [subject access request (SAR)](https://ico.org.uk/your-data-matters/your-right-of-access/) diff --git a/src/styles/typography/index.md.njk b/src/styles/typography/index.md.njk index 97f0d47f00..316862e079 100644 --- a/src/styles/typography/index.md.njk +++ b/src/styles/typography/index.md.njk @@ -21,8 +21,8 @@ If your service is publicly available on a subdomain other than service.gov.uk, If you’re not sure whether you should use GDS Transport, do one of the following: - - [read the 'If your service is not on GOV.UK' section on 'Making your service look like GOV.UK'](https://www.gov.uk/service-manual/design/making-your-service-look-like-govuk#if-your-service-isnt-on-govuk) - - [contact the Design System team](/get-in-touch/) +- [read the 'If your service is not on GOV.UK' section on 'Making your service look like GOV.UK'](https://www.gov.uk/service-manual/design/making-your-service-look-like-govuk#if-your-service-isnt-on-govuk) +- [contact the Design System team](/get-in-touch/) ## Headings @@ -77,6 +77,7 @@ The majority of your body copy should use the standard 19px paragraph size. If you need to align text differently to how it usually displays on the page, you can use text alignment override classes. Use: + - `govuk-!-text-align-left` to align text to the left - `govuk-!-text-align-right` to align text to the right - `govuk-!-text-align-centre` to align text to the centre @@ -135,8 +136,8 @@ Include `rel="noreferrer noopener"` along with `target="_blank"` to reduce the r If you're displaying lots of links together and want to save space and avoid repetition, consider doing both of the following: - - adding a line of text before the links saying 'The following links open in a new tab' - - including `(opens in new tab)` as part of the link text, so that part of the link text is visually hidden but still accessible to screen readers +- adding a line of text before the links saying 'The following links open in a new tab' +- including `(opens in new tab)` as part of the link text, so that part of the link text is visually hidden but still accessible to screen readers ### Links on dark backgrounds From db0eb5ca22d144ec382b022201ce920ffa63c775 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Wed, 2 Nov 2022 22:02:06 +0000 Subject: [PATCH 4/6] Set mangle to false We were previously flaky on this - we mangled one email address, but left all others unmangled. I'm not sure how useful this is nowadays, since I'm sure crawlers are smart enough to interpret mangled addresses. Alternatively, we can leave as is and all email addresses will be mangled. --- lib/metalsmith.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/metalsmith.js b/lib/metalsmith.js index 36be4a539f..06c9e9bc60 100644 --- a/lib/metalsmith.js +++ b/lib/metalsmith.js @@ -232,6 +232,7 @@ module.exports = metalsmith(__dirname) // __dirname defined by node.js: name of }, // Markdown engine options + mangle: false, smartypants: true, // use "smart" typographic punctuation pedantic: true, highlight: highlighter From a204ed6c2241cd2a0333a6ee4dd2500a57fcfdb1 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Wed, 2 Nov 2022 22:05:15 +0000 Subject: [PATCH 5/6] Switch to Github Flavoured Markdown Marked defaults to GFM. We've been using pedantic rules and somehow have avoided errors with fenced code blocks, which `markdown.pl` doesn't support. I'm guessing that was a bug with early versions of Marked which has now been fixed, so our fenced code blocks don't work with a newer version of Marked. Best to ditch pedantry and fix GFM-related errors, as the team is deeply into the Github ecosystem anyway, and it requires less effort from content editors. --- lib/metalsmith.js | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/metalsmith.js b/lib/metalsmith.js index 06c9e9bc60..db51baddeb 100644 --- a/lib/metalsmith.js +++ b/lib/metalsmith.js @@ -234,7 +234,6 @@ module.exports = metalsmith(__dirname) // __dirname defined by node.js: name of // Markdown engine options mangle: false, smartypants: true, // use "smart" typographic punctuation - pedantic: true, highlight: highlighter } })) From 1a615e755cda063d4fbf5598d3140fed81cee230 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Tue, 15 Nov 2022 22:14:08 +0000 Subject: [PATCH 6/6] Fix spacing errors Switching to Github Flavoured Markdown results in a LOT of differences between rendering. The bulk of these are related to blank lines in HTML blocks, which fall foul of rules 6 and 7 of HTML blocks in GFM (see: https://github.github.com/gfm/#html-blocks), and cause rendering errors. We can (painstakingly) remove all these blank lines to produce a compiled output that only differs in desirable ways. This is mostly fine, but it does mean that there are now no empty lines in code samples, which may or may not be a blocker. --- lib/file-helper.js | 25 ++++++++++----- lib/metalsmith.js | 2 +- .../contribution-criteria/index.md.njk | 5 --- .../updating-your-code/index.md.njk | 21 ------------- src/styles/colour/index.md.njk | 11 +++++-- src/styles/page-template/index.md.njk | 26 ---------------- views/partials/_example.njk | 31 +++++++++---------- 7 files changed, 40 insertions(+), 81 deletions(-) diff --git a/lib/file-helper.js b/lib/file-helper.js index 48357b0458..329290b6e2 100644 --- a/lib/file-helper.js +++ b/lib/file-helper.js @@ -37,10 +37,16 @@ exports.getNunjucksCode = path => { // Omit any `{% extends "foo.njk" %}` nunjucks code, because we extend // templates that only exist within the Design System – it's not useful to // include this in the code we expect others to copy. - let content = parsedFile.content.replace( - /{%\s*extends\s*\S*\s*%}\s+/, - '' - ) + let content = parsedFile.content + .replace( + /{%\s*extends\s*\S*\s*%}\s+/, + '' + ) + // Remove empty lines to avoid broken markdown rendering + .replace( + /^\s*[\r\n]/gm, + '' + ) return content } @@ -107,12 +113,15 @@ exports.getHTMLCode = path => { return beautify(html.trim(), { indent_size: 2, - end_with_newline: true, - // If there are multiple blank lines, reduce down to one blank new line. - max_preserve_newlines: 1, + end_with_newline: false, + // Remove blank lines + max_preserve_newlines: 0, // set unformatted to a small group of elements, not all inline (the default) // otherwise tags like label arent indented properly - unformatted: ['code', 'pre', 'em', 'strong'] + unformatted: ['code', 'pre', 'em', 'strong'], + // Ensure no empty lines after and tags - this breaks markdown + // rendering + extra_liners: [] }) } diff --git a/lib/metalsmith.js b/lib/metalsmith.js index db51baddeb..9f0bbf82b7 100644 --- a/lib/metalsmith.js +++ b/lib/metalsmith.js @@ -232,7 +232,7 @@ module.exports = metalsmith(__dirname) // __dirname defined by node.js: name of }, // Markdown engine options - mangle: false, + mangle: false, // Don't mangle emails smartypants: true, // use "smart" typographic punctuation highlight: highlighter } diff --git a/src/community/contribution-criteria/index.md.njk b/src/community/contribution-criteria/index.md.njk index 18e9a1c8a2..9ae7bb2b65 100644 --- a/src/community/contribution-criteria/index.md.njk +++ b/src/community/contribution-criteria/index.md.njk @@ -79,7 +79,6 @@ Before a new component or pattern is published the working group reviews the imp }, { html: "

It has been tested in user research and shown to work with a representative sample of users, including those with disabilities.

-

Components and patterns which are not proven usable can be published as experimental. But they must be clearly based on relevant user research from other organisations and best practice, and meet the other criteria.

" } ], @@ -89,9 +88,7 @@ Before a new component or pattern is published the working group reviews the imp }, { html: "

It reuses existing styles and components in the Design System where relevant.

-

Both the guidance and any content included in examples must follow the GOV.UK content style guide.

-

If there is code, it follows the GOV.UK Frontend coding standards and is ready to merge in GOV.UK Frontend.

" } ], @@ -101,9 +98,7 @@ Before a new component or pattern is published the working group reviews the imp }, { html: "

The implementation is versatile enough that the component or pattern can be used in a range of different services that may need it.

-

For example, a versatile date input component could be set up to ask for a year only, a month and year only, a precise date, or any other combination you may need.

-

The component or pattern must also have been tested and shown to work with a range of browsers, assistive technologies and devices.

" } ] diff --git a/src/get-started/updating-your-code/index.md.njk b/src/get-started/updating-your-code/index.md.njk index 5ec9ee2a1c..f293c5fa8b 100644 --- a/src/get-started/updating-your-code/index.md.njk +++ b/src/get-started/updating-your-code/index.md.njk @@ -26,42 +26,34 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org - :top_of_page Deprecated: putting content above the <!DOCTYPE html> will result in broken pages for users of older Internet Explorer versions. - :html_lang htmlLang - :page_title pageTitle - :asset_path assetPath - :head head - :body_classes bodyClasses - :body_start bodyStart - :skip_link_message @@ -78,14 +70,12 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- :cookie_message See the cookie banner component for more details. - header_class @@ -102,7 +92,6 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- homepage_url @@ -119,14 +108,12 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- global_header_text No equivalent. Raise an issue if you need this. - inside_header @@ -143,7 +130,6 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- proposition_header @@ -160,12 +146,10 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- :after_header beforeContent - :content @@ -183,7 +167,6 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- :footer_top @@ -200,7 +183,6 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- :footer_support_links @@ -217,14 +199,12 @@ The main change is changing variables from [snake_case](https://en.wikipedia.org

- :licence_message No equivalent. Raise an issue if you need this. - :body_end bodyEnd @@ -475,7 +455,6 @@ GOV.UK Frontend uses ["Block, Element, Modifier" (BEM)](http://getbem.com/) and form-control
form-control-3-4
form-control-2-3
form-control-1-2
form-control-1-3
form-control-1-4
form-control-1-8 Width override classes - form-section Deprecated: not required with new spacing implementation diff --git a/src/styles/colour/index.md.njk b/src/styles/colour/index.md.njk index c62a377193..23ba61b893 100644 --- a/src/styles/colour/index.md.njk +++ b/src/styles/colour/index.md.njk @@ -30,8 +30,8 @@ use `govuk-colour("red")` rather than `$govuk-error-colour`. - {# colours is an object built by ./lib/colours.js based on data defined in ./data/colours.json #} - {% for groupName, group in colours.applied %} + {#- colours is an object built by ./lib/colours.js based on data defined in ./data/colours.json #} + {% for groupName, group in colours.applied -%} - {% for colour in group %} + {% for colour in group -%} + {% if colour.notes %} + {% else %} + + {% endif %} {% endfor %} {% endfor %} diff --git a/src/styles/page-template/index.md.njk b/src/styles/page-template/index.md.njk index c98ff2e8e6..318887091c 100644 --- a/src/styles/page-template/index.md.njk +++ b/src/styles/page-template/index.md.njk @@ -92,7 +92,6 @@ To change the components that are included in the page template by default, set - @@ -100,13 +99,11 @@ To change the components that are included in the page template by default, set Specify a path to the GOV.UK Frontend assets (icons, images, font files). - - @@ -117,20 +114,16 @@ To change the components that are included in the page template by default, set phase banner component. - - - - @@ -138,7 +131,6 @@ To change the components that are included in the page template by default, set Add content just before the closing </body> element. - @@ -148,13 +140,11 @@ To change the components that are included in the page template by default, set For example: The cookie banner component. - - @@ -162,7 +152,6 @@ To change the components that are included in the page template by default, set Add content that needs to appear centered in the <main> element. - @@ -170,7 +159,6 @@ To change the components that are included in the page template by default, set Add a nonce attribute to the script for your Content Security Policy (CSP). Provide a nonce that hostile actors cannot guess, as otherwise they can easily find a way around your CSP. However, you should use this attribute only if you’re not able to include the hash for the inline scripts in your service’s CSP. - @@ -178,7 +166,6 @@ To change the components that are included in the page template by default, set Override the default footer component. - @@ -188,7 +175,6 @@ To change the components that are included in the page template by default, set For example: <meta name="description" content="My page description"> - @@ -196,7 +182,6 @@ To change the components that are included in the page template by default, set Override the default header component. - @@ -206,19 +191,16 @@ To change the components that are included in the page template by default, set For example: <link rel="shortcut icon" href="favicon.ico" type="image/x-icon" /> - - - @@ -226,13 +208,11 @@ To change the components that are included in the page template by default, set Override the main section of the page, which by default wraps the <main> element, beforeContent block and content block. - - @@ -240,13 +220,11 @@ To change the components that are included in the page template by default, set Set the language of the <main> element if it's different to htmlLang. - - @@ -254,7 +232,6 @@ To change the components that are included in the page template by default, set Override the default page title (<title> element). - @@ -262,7 +239,6 @@ To change the components that are included in the page template by default, set Set the language of the <title> element if it's different to htmlLang. - @@ -270,7 +246,6 @@ To change the components that are included in the page template by default, set Override the default skip link component. - @@ -278,7 +253,6 @@ To change the components that are included in the page template by default, set Set the toolbar colour on some devices. -

@@ -39,7 +39,7 @@ use `govuk-colour("red")` rather than `$govuk-error-colour`.

@@ -48,9 +48,14 @@ use `govuk-colour("red")` rather than `$govuk-error-colour`. {{colour.colour}} {{colour.notes}} +
assetPath Variable
assetUrl Variable Set the domain for assets where an absolute URL is required, for example the Open Graph image.
beforeContent Block
bodyAttributes Variable Add attributes to the <body> element. Add each attribute and its value in the bodyAttributes object.
bodyClasses Variable Add a class to the <body> element.
bodyEnd Block
bodyStart Block
containerClasses Variable Add a class to the container. This is useful if you want to make the page wrapper a fixed width.
content Block
cspNonce Variable
footer Block
head Block
header Block
headIcons Block
htmlClasses Variable Add a class to the <html> element.
htmlLang Variable Set the language of the whole document. If your <title> and <main> element are in a different language to the rest of the page, use htmlLang to set the language of the rest of the page.
main Block
mainClasses Variable Add a class to the <main> element.
mainLang Variable
opengraphImageUrl Variable Set the URL for the Open Graph image meta tag. The URL must be absolute, including the protocol and domain name.
pageTitle Block
pageTitleLang Variable
skipLink Block
themeColor Variable
diff --git a/views/partials/_example.njk b/views/partials/_example.njk index 4e2b182c78..586726ad26 100644 --- a/views/partials/_example.njk +++ b/views/partials/_example.njk @@ -32,7 +32,7 @@
Open this - {# Don't use full title visually as the context is shown based on location of this link #} + {#- Don't use full title visually as the context is shown based on location of this link #} {{ exampleTitle | lower }} example in a new tab @@ -77,13 +77,12 @@
Nunjucks
{% elif not (params.hideTab) %}
Nunjucks
- {% endif %} + {% endif -%}
{%- if (params.group == 'components') %} {% set macroOptions = getMacroOptions(params.item) %} - + {% set macroOptionsHTML %} -

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

@@ -93,7 +92,6 @@

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

- {% for table in macroOptions %} @@ -105,8 +103,7 @@ - - {% for option in table.options %} + {% for option in table.options -%} @@ -115,8 +112,8 @@ Required. {% endif %} {{ option.description | safe }} - {% if (option.isComponent) %} - {# Create separate table data for components that are hidden in the Design System #} + {% if (option.isComponent) -%} + {# Create separate table data for components that are hidden in the Design System -#} {% if (option.name === "hint" or option.name === "label") %} See {{ option.name }}. {% else %} @@ -125,19 +122,19 @@ {% endif %} {% if (option.params) %} See {{ option.name }}. - {% endif %} + {% endif -%} {% endfor %}
{{ table.name }}
{{option.name}} {{option.type}}
{% endfor %} - - {% endset %} - - {% from "govuk/components/details/macro.njk" import govukDetails %} - - {{ govukDetails({ + + {%- endset %} + + {%- from "govuk/components/details/macro.njk" import govukDetails %} + + {{- govukDetails({ summaryHtml: "Nunjucks macro options", html: macroOptionsHTML, classes: "app-options", @@ -145,7 +142,7 @@ id: "options-" + exampleId + "-details" } })}} - {% endif %} + {% endif -%} 

           {{- getNunjucksCode(examplePath) | highlight('js') | safe -}}