From 1c31e536e22b5f6366987384cf2aa7b574f3826a Mon Sep 17 00:00:00 2001 From: Kevin Van Lierde Date: Thu, 1 Feb 2024 00:32:03 +0100 Subject: [PATCH] feat: define global urls with markdown refs Added value: define reusable links in a single config file. By having @metalsmith/markdown retrieve them from global metadata, they are also available for e.g. layouts to render. --- data/markdown_refs.yaml | 11 +++++++++++ lib/metalsmith.js | 9 ++++++++- src/accessibility-statement.md | 10 +++++----- src/accessibility/accessibility-strategy/index.md | 14 +++++++------- src/components/back-link/index.md | 2 +- src/components/breadcrumbs/index.md | 2 +- src/components/button/index.md | 6 +++--- src/components/checkboxes/index.md | 4 ++-- src/components/date-input/index.md | 2 +- src/components/details/index.md | 2 +- src/components/error-message/index.md | 4 ++-- src/components/error-summary/index.md | 2 +- src/components/fieldset/index.md | 2 +- src/components/file-upload/index.md | 4 ++-- src/components/index.md | 2 +- src/components/panel/index.md | 2 +- src/components/phase-banner/index.md | 2 +- src/components/radios/index.md | 4 ++-- src/components/select/index.md | 4 ++-- src/components/skip-link/index.md | 2 +- src/components/summary-list/index.md | 6 +++--- src/components/table/index.md | 2 +- src/components/tabs/index.md | 2 +- src/components/tag/index.md | 2 +- src/components/task-list/index.md.njk | 2 +- src/components/text-input/index.md | 2 +- src/components/textarea/index.md | 4 ++-- src/components/warning-text/index.md | 2 +- src/get-started/focus-states/index.md | 2 +- src/patterns/addresses/index.md | 2 +- src/patterns/bank-details/index.md | 2 +- src/patterns/complete-multiple-tasks/index.md | 2 +- src/patterns/confirm-an-email-address/index.md | 2 +- src/patterns/cookies-page/index.md | 2 +- src/patterns/email-addresses/index.md | 4 ++-- src/patterns/equality-information/index.md | 2 +- src/patterns/national-insurance-numbers/index.md | 2 +- src/patterns/payment-card-details/index.md | 2 +- .../problem-with-the-service-pages/index.md | 2 +- src/patterns/question-pages/index.md | 2 +- src/patterns/service-unavailable-pages/index.md | 2 +- src/patterns/telephone-numbers/index.md | 2 +- src/styles/index.md | 2 +- 43 files changed, 81 insertions(+), 63 deletions(-) create mode 100644 data/markdown_refs.yaml diff --git a/data/markdown_refs.yaml b/data/markdown_refs.yaml new file mode 100644 index 0000000000..135dbf3b88 --- /dev/null +++ b/data/markdown_refs.yaml @@ -0,0 +1,11 @@ +govuk: https://www.gov.uk/ +govuk_frontend_design_system: https://frontend.design-system.service.gov.uk/ +govuk_design_system: https://design-system.service.gov.uk/ +govuk_prototype_kit: https://prototype-kit.service.gov.uk +govuk_design_system_accessibility: https://design-system.service.gov.uk/accessibility/ + +component_radio: /components/radios/ +component_checkbox: /components/checkbox/ +pattern_check_answers: /patterns/check-answers/ + +lib_nunjucks: https://mozilla.github.io/nunjucks/ \ No newline at end of file diff --git a/lib/metalsmith.js b/lib/metalsmith.js index d130d178ee..48dd4911cc 100644 --- a/lib/metalsmith.js +++ b/lib/metalsmith.js @@ -75,7 +75,13 @@ module.exports = metalsmith .metadata({ title: '[TITLE NOT SET]', colours, - + // add a list of .md links and/ or image references that can be reused across all pages + // using the [title][identifier] notation + globalLinks: (function() { + const source = metalsmith.matter.parse(metalsmith.matter.wrap(readFileSync(join(process.cwd(), 'data', 'markdown_refs.yaml'), 'utf-8'))) + delete source.contents + return source + }()), // include access to metalsmith environment variables // used to e.g. detect when we're building in a preview environment env: (value) => metalsmith.env(value) @@ -187,6 +193,7 @@ module.exports = metalsmith // render markdown in source files .use( markdown({ + globalRefs: 'globalLinks', render(source) { return marked.parse(source) } diff --git a/src/accessibility-statement.md b/src/accessibility-statement.md index ff70d576df..0ba459ae11 100644 --- a/src/accessibility-statement.md +++ b/src/accessibility-statement.md @@ -6,7 +6,7 @@ layout: layout-single-page-prose.njk # Accessibility statement -The GOV.UK Design System team (the team) is committed to making its website at [design-system.service.gov.uk](https://design-system.service.gov.uk/) and the GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk](https://frontend.design-system.service.gov.uk/) accessible, in accordance with the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018. +The GOV.UK Design System team (the team) is committed to making its website at [design-system.service.gov.uk][govuk_frontend_design_system] and the GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk][govuk_frontend_design_system_] accessible, in accordance with the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018. This accessibility statement applies to both websites and the components and patterns from the GOV.UK Frontend codebase which appear in the examples throughout the Design System. @@ -23,9 +23,9 @@ AbilityNet has [advice on making your device easier to use](https://mcmw.ability ## Compliance status -The Design System website at [design-system.service.gov.uk](https://design-system.service.gov.uk/) is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard. +The Design System website at [design-system.service.gov.uk][govuk_design_system] is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard. -The GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk](https://frontend.design-system.service.gov.uk/) is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard. +The GOV.UK Frontend documentation website at [frontend.design-system.service.gov.uk][govuk_frontend_design_system] is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard. The GOV.UK Frontend codebase at [github.com/alphagov/govuk-frontend](https://github.com/alphagov/govuk-frontend) is fully compliant with the Web Content Accessibility Guidelines (WCAG) version 2.2 AA standard. @@ -82,11 +82,11 @@ Additional accessibility concerns from the GOV.UK Frontend codebase include: This statement was prepared on 23 October 2019. It was last reviewed and updated on 2 August 2023. -The [GOV.UK Design System website](https://design-system.service.gov.uk/) was last audited for accessibility issues by an external group on 7 October 2019. The test was carried out by the [Digital Accessibility Centre (DAC)](https://digitalaccessibilitycentre.org/). +The [GOV.UK Design System website][govuk_design_system] was last audited for accessibility issues by an external group on 7 October 2019. The test was carried out by the [Digital Accessibility Centre (DAC)](https://digitalaccessibilitycentre.org/). DAC tested a sample of pages to cover the different content types in the GOV.UK Design System website. They were: -- [the homepage](https://design-system.service.gov.uk/) +- [the homepage][govuk_design_system] - [a short content page](https://design-system.service.gov.uk/community/design-system-working-group/) - [a long content page](https://design-system.service.gov.uk/styles/layout/) - [an overview page](https://design-system.service.gov.uk/community/) diff --git a/src/accessibility/accessibility-strategy/index.md b/src/accessibility/accessibility-strategy/index.md index f26d80d321..118cce15e9 100644 --- a/src/accessibility/accessibility-strategy/index.md +++ b/src/accessibility/accessibility-strategy/index.md @@ -65,9 +65,9 @@ An ‘accessibility concern’ is our umbrella term for any question about the a Accessibility concerns can surface in any product, including: - [GOV.UK Frontend](https://design-system.service.gov.uk/get-started/production/) -- the [GOV.UK Design System website](https://design-system.service.gov.uk/) -- the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/) -- the [GOV.UK Frontend technical documentation website](https://frontend.design-system.service.gov.uk/) +- the [GOV.UK Design System website][govuk_design_system] +- the [GOV.UK Prototype Kit][govuk_prototype_kit] +- the [GOV.UK Frontend technical documentation website][govuk_frontend_design_system] - other content produced by the GOV.UK Design System team The GOV.UK Design System’s top focus for accessibility is on styles and components included in GOV.UK Frontend and patterns built using GOV.UK Frontend. @@ -287,13 +287,13 @@ If an incoming query is more than a quickly-answered question, it will be record By keeping accessibility concerns in the same place as all our GitHub issues, the team can more easily identify accessibility concerns related to other items. Addressing and storing accessibility concerns separate from GitHub issues could lead to them receiving less attention. -If an accessibility concern turns out to be a bug the team cannot quickly fix, the team will determine whether it should be recorded in the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/). +If an accessibility concern turns out to be a bug the team cannot quickly fix, the team will determine whether it should be recorded in the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility]. We also will record relevant accessibility concerns for specific styles, components or patterns in their corresponding guidance pages. ### Recording WCAG compliance status -If the GOV.UK Design System does not meet the requirements of level AA accessibility compliance, the team will update the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/) and keep the records of changes required until compliance is met. +If the GOV.UK Design System does not meet the requirements of level AA accessibility compliance, the team will update the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility] and keep the records of changes required until compliance is met. ## Proposed accessibility activities @@ -343,7 +343,7 @@ Initially, the team will assess the performance of this accessibility strategy b - use of the strategy to guide and improve the GOV.UK Design System team’s decision-making - progress and completion of activities mentioned in the strategy - number of accessibility concerns recorded as GitHub issues in the team’s repositories -- number of accessibility concerns listed in the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/) +- number of accessibility concerns listed in the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility] #### Additional indicators @@ -359,7 +359,7 @@ If capacity is available to expand measurement efforts, additional performance i ### Recording performance measurement results -The team will gather performance measurement results every 6 months and record them in the team’s internal documentation. The team will also review the [GOV.UK Design System accessibility statement](https://design-system.service.gov.uk/accessibility/) every 6 months and update as needed. +The team will gather performance measurement results every 6 months and record them in the team’s internal documentation. The team will also review the [GOV.UK Design System accessibility statement][govuk_design_system_accessibility] every 6 months and update as needed. The team will use the results of performance measurement and accessibility statement reviews to help inform quarterly planning. diff --git a/src/components/back-link/index.md b/src/components/back-link/index.md index 9d133678d8..8be4138ad1 100644 --- a/src/components/back-link/index.md +++ b/src/components/back-link/index.md @@ -74,7 +74,7 @@ Make sure the link takes users to the previous page they were on, in the state t Where possible, ensure the back link works even when JavaScript is not available. If this is not possible, you should hide the back link when JavaScript is not available. -There are 2 ways to use the back link component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the back link component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "back-link", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/breadcrumbs/index.md b/src/components/breadcrumbs/index.md index f0f5adfa50..ed64aff4a3 100644 --- a/src/components/breadcrumbs/index.md +++ b/src/components/breadcrumbs/index.md @@ -60,7 +60,7 @@ The breadcrumbs should start with your 'home' page and end with the parent secti

Make sure no other interactive elements are too close to the breadcrumbs. This is to make sure users can easily interact with the breadcrumbs. This relates to WCAG 2.2 success criterion 2.5.8 Target Size (minimum).

-There are 2 ways to use the breadcrumbs component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the breadcrumbs component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "breadcrumbs", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/button/index.md b/src/components/button/index.md index eaa4141f46..629d1e3ad0 100644 --- a/src/components/button/index.md +++ b/src/components/button/index.md @@ -49,8 +49,8 @@ Write button text in sentence case, describing the action it performs. For examp - ‘Save and come back later’ when a user can save their information and come back later - ‘Add another’ to add another item to a list or group - ‘Pay’ to make a payment -- ‘Confirm and send’ on a [check answers](/patterns/check-answers/) page that does not have any legal content a user must agree to -- ‘Accept and send’ on a [check answers](/patterns/check-answers/) page that has legal content a user must agree to +- ‘Confirm and send’ on a [check answers][pattern_check_answers] page that does not have any legal content a user must agree to +- ‘Accept and send’ on a [check answers][pattern_check_answers] page that has legal content a user must agree to - ‘Sign out’ when a user is signed in to an account You may need to include more or different words to better describe the action. For example, ‘Add another address’ and ‘Accept and claim a tax refund’. @@ -65,7 +65,7 @@ Align the primary action button to the left edge of your form.

Do not decrease the height or target area of buttons. This is to make sure users can easily interact with buttons. This is to comply with WCAG 2.2 success criterion 2.5.8 Target Size (minimum).

-There are 2 ways to use the button component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the button component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. ### Default buttons diff --git a/src/components/checkboxes/index.md b/src/components/checkboxes/index.md index 40960deab2..a822c9ff98 100644 --- a/src/components/checkboxes/index.md +++ b/src/components/checkboxes/index.md @@ -22,7 +22,7 @@ Use the checkboxes component when you need to help users: ## When not to use this component -Do not use the checkboxes component if users can only choose one option from a selection. In this case, use the [radios component](/components/radios/). +Do not use the checkboxes component if users can only choose one option from a selection. In this case, use the [radios component][component_radio]. ## How it works @@ -49,7 +49,7 @@ If you're asking just [one question per page](/patterns/question-pages/#start-by Read more about [why and how to set legends as headings](/get-started/labels-legends-headings/). -There are 2 ways to use the checkboxes component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the checkboxes component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "checkboxes", example: "default", html: true, nunjucks: true, open: false, size: "m", titleSuffix: "second" }) }} diff --git a/src/components/date-input/index.md b/src/components/date-input/index.md index b81a25e060..6599a2a67b 100644 --- a/src/components/date-input/index.md +++ b/src/components/date-input/index.md @@ -37,7 +37,7 @@ Make sure that any example dates you use in hint text are valid for the question Accept month names written out in full or abbreviated form (for example, ‘january’ or ‘jan’) as some users may enter months in this way. -There are 2 ways to use the date input component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the date input component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "date-input", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }} diff --git a/src/components/details/index.md b/src/components/details/index.md index 11ebe93761..a8230085b8 100644 --- a/src/components/details/index.md +++ b/src/components/details/index.md @@ -33,7 +33,7 @@ The details component is less visually prominent than tabs and accordions, so te The details component is a short link that shows more detailed help text when a user clicks on it. -There are 2 ways to use the details component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the details component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "details", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }} diff --git a/src/components/error-message/index.md b/src/components/error-message/index.md index e258df6b6b..4a250ee683 100644 --- a/src/components/error-message/index.md +++ b/src/components/error-message/index.md @@ -11,7 +11,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} @@ -181,7 +181,7 @@ Use template messages for common errors on: - [file upload](/components/file-upload/#error-messages) - [names](/patterns/names/#error-messages) - [National Insurance numbers](/patterns/national-insurance-numbers/#error-messages) -- [radios](/components/radios/#error-messages) +- [radios][component_radio] - [telephone numbers](/patterns/telephone-numbers/#error-messages) - [text input](/components/text-input/#error-messages) - [textarea](/components/textarea/#error-messages) diff --git a/src/components/error-summary/index.md b/src/components/error-summary/index.md index d71f57e50e..e0f52d4db8 100644 --- a/src/components/error-summary/index.md +++ b/src/components/error-summary/index.md @@ -32,7 +32,7 @@ As well as showing an error summary, follow the [validation pattern](/patterns/v And make your [error messages](/components/error-message/#be-clear-and-concise) clear and concise. -There are 2 ways to use the error summary component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the error summary component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "error-summary", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }} diff --git a/src/components/fieldset/index.md b/src/components/fieldset/index.md index 11afdcfa5e..05fb9eb370 100644 --- a/src/components/fieldset/index.md +++ b/src/components/fieldset/index.md @@ -17,7 +17,7 @@ Use the fieldset component when you need to show a relationship between multiple {{ example({ group: "components", item: "fieldset", example: "address-group", html: true, nunjucks: true, open: false, size: "xl", loading: "eager" }) }} -If you’re using the examples or macros for [radios](/components/radios/), [checkboxes](/components/checkboxes/) or [date input](/components/date-input/), the fieldset will already be included. +If you’re using the examples or macros for [radios][component_radio], [checkboxes][component_checkbox] or [date input](/components/date-input/), the fieldset will already be included. ## How it works diff --git a/src/components/file-upload/index.md b/src/components/file-upload/index.md index ab77300b91..046ade32b1 100644 --- a/src/components/file-upload/index.md +++ b/src/components/file-upload/index.md @@ -11,7 +11,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} @@ -69,7 +69,7 @@ To upload a file, the user can either:

You can make it easier for the user to reuse a file by showing it as an option for the user to select instead of the file upload. Consider users on public devices before choosing to make the file available to preview or download. This is to comply with WCAG 2.2 success criterion 3.3.7 Redundant Entry.

-There are 2 ways to use the file upload component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the file upload component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "file-upload", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/index.md b/src/components/index.md index 36a6c95735..b17266c0c7 100644 --- a/src/components/index.md +++ b/src/components/index.md @@ -8,6 +8,6 @@ Components are reusable parts of the user interface that have been made to suppo You can use individual components in many different [patterns](/patterns/) and contexts. For example, you can use the [text input](/components/text-input/) component to ask for an email address, a National Insurance number or someone’s name. -Each component in the GOV.UK Design System has coded examples. If you're using the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), or have included [GOV.UK Frontend](https://frontend.design-system.service.gov.uk/) in your build, coded examples will render the same as in the Design System. +Each component in the GOV.UK Design System has coded examples. If you're using the [GOV.UK Prototype Kit][govuk_prototype_kit], or have included [GOV.UK Frontend][govuk_frontend_design_system] in your build, coded examples will render the same as in the Design System. The GOV.UK Design System's code is public and freely available under a [Massachusetts Institute of Technology (MIT) license](https://github.com/alphagov/govuk-frontend/blob/main/LICENSE.txt). You can [find our code repositories on GitHub](https://github.com/topics/govuk-design-system-team), where we [code in the open](https://gds.blog.gov.uk/2012/10/12/coding-in-the-open/). diff --git a/src/components/panel/index.md b/src/components/panel/index.md index 66829b3935..e54b435f4f 100644 --- a/src/components/panel/index.md +++ b/src/components/panel/index.md @@ -24,7 +24,7 @@ Never use the panel component to highlight important information within body con ## How it works -There are 2 ways to use the panel component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the panel component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "panel", example: "default", html: true, nunjucks: true, open: false, size: "m", titleSuffix: "second" }) }} diff --git a/src/components/phase-banner/index.md b/src/components/phase-banner/index.md index 307c64929b..c9b7dd9511 100644 --- a/src/components/phase-banner/index.md +++ b/src/components/phase-banner/index.md @@ -54,7 +54,7 @@ Your banner must be directly under the black GOV.UK header and colour bar.

Do not make the phase banner ‘sticky’ to the top of the page by using `position: fixed` or any other method. This is to make sure it does not cover or obscure any content which has a focus applied. This is to comply with WCAG 2.2 success criterion 2.4.11 Focus not Obscured (minimum).

-There are 2 ways to use the phase banner component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the phase banner component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "phase-banner", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/radios/index.md b/src/components/radios/index.md index 393b20e842..391a793689 100644 --- a/src/components/radios/index.md +++ b/src/components/radios/index.md @@ -17,7 +17,7 @@ Use the radios component when users can only select one option from a list. ## When not to use this component -Do not use the radios component if users might need to select more than one option. In this case, you should use the [checkboxes](/components/checkboxes/) component instead. +Do not use the radios component if users might need to select more than one option. In this case, you should use the [checkboxes][component_checkbox] component instead. ## How it works @@ -48,7 +48,7 @@ If you are asking just [one question per page](/patterns/question-pages/#start-b Read more about [why and how to set legends as headings](/get-started/labels-legends-headings/). -There are 2 ways to use the radios component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the radios component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "radios", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }} diff --git a/src/components/select/index.md b/src/components/select/index.md index 299bf2f75e..ea00188eac 100644 --- a/src/components/select/index.md +++ b/src/components/select/index.md @@ -42,7 +42,7 @@ The select component should only be used as a last resort in public-facing servi The select component allows users to choose an option from a long list. Before using the select component, try asking users questions which will allow you to present them with fewer options. -Asking questions means you’re less likely to need to use the select component, and can consider using a different solution, such as [radios](/components/radios/). +Asking questions means you’re less likely to need to use the select component, and can consider using a different solution, such as [radios][component_radio]. ## How it works @@ -50,7 +50,7 @@ If you use the component for settings, you can make an option pre-selected by de If you use the component for questions, you should not pre-select any of the options in case it influences users' answers. -There are 2 ways to use the select component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the select component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "select", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/skip-link/index.md b/src/components/skip-link/index.md index d7fcbe4e48..63a55636d6 100644 --- a/src/components/skip-link/index.md +++ b/src/components/skip-link/index.md @@ -29,6 +29,6 @@ Including the skip link component gives users the option to bypass the top-level The skip link component is visually hidden until a keyboard press activates it. -There are 2 ways to use the skip link component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the skip link component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "skip-link", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/summary-list/index.md b/src/components/summary-list/index.md index afb6092848..3eca39dcae 100644 --- a/src/components/summary-list/index.md +++ b/src/components/summary-list/index.md @@ -41,7 +41,7 @@ See the full list of [components and patterns affected by WCAG 2.2](/accessibili Use a summary list to show information as a list of key facts. -You can use it to display metadata like ‘Last updated’ with a date like ‘22 June 2018’, or to summarise a user’s responses at the end of a form like the [check answers](/patterns/check-answers/) pattern. +You can use it to display metadata like ‘Last updated’ with a date like ‘22 June 2018’, or to summarise a user’s responses at the end of a form like the [check answers][pattern_check_answers] pattern. [Summary cards](#summary-cards) are a variant within this component. You can use summary cards to show multiple summary lists that describe the same type of thing, such as people. You can also add card actions that apply to the entire summary list. @@ -60,7 +60,7 @@ Each row of a summary list is made up of a: You can show a single or multiple summary lists on a page. If you’re showing multiple summary lists on a page, you can add structure by using headings or summary cards. -There are 2 ways to use the summary list component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the summary list component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "summary-list", example: "without-actions", html: true, nunjucks: true, open: false }) }} @@ -175,7 +175,7 @@ If a card action cannot easily be undone or might have serious consequences, con ## Research on this component -This component was developed and tested by the Government Digital Service as part of the [check answers pattern](/patterns/check-answers/). +This component was developed and tested by the Government Digital Service as part of the [check answers pattern][pattern_check_answers]. The Department for Education contributed the summary card. It’s being used in some of their services, such as: diff --git a/src/components/table/index.md b/src/components/table/index.md index 593e02305d..6a2f0cf482 100644 --- a/src/components/table/index.md +++ b/src/components/table/index.md @@ -35,7 +35,7 @@ There are other styling options for table captions. You can use `govuk-table__ca Use table headers to tell users what the rows and columns represent. Use the `scope` attribute to help users of assistive technology distinguish between row and column headers. -There are 2 ways to use the table component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the table component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "table", example: "default", html: true, nunjucks: true, open: false, size: "m", titleSuffix: "second" }) }} diff --git a/src/components/tabs/index.md b/src/components/tabs/index.md index 1982108d56..c736d0c9e8 100644 --- a/src/components/tabs/index.md +++ b/src/components/tabs/index.md @@ -54,7 +54,7 @@ If you decide to use one of these components, consider if: ## How it works -There are 2 ways to use the tabs component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the tabs component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "tabs", example: "default", html: true, nunjucks: true, open: false, size: "xl", titleSuffix: "second" }) }} diff --git a/src/components/tag/index.md b/src/components/tag/index.md index 06534ef8d4..0e34220ec2 100644 --- a/src/components/tag/index.md +++ b/src/components/tag/index.md @@ -42,7 +42,7 @@ Use the tag component when it’s possible for something to have more than one s ## How it works -There are two ways to use the tag component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are two ways to use the tag component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. Tags are only used to indicate a status. Do not make a tag interactive by making it into a link or button. Use adjectives (descriptive words) and not verbs (action words) for the names of your tags. Using a verb might make a user think that clicking on them will do something. diff --git a/src/components/task-list/index.md.njk b/src/components/task-list/index.md.njk index 7436d000b4..ab9232ce4e 100644 --- a/src/components/task-list/index.md.njk +++ b/src/components/task-list/index.md.njk @@ -32,7 +32,7 @@ The task list should not be used as a way of showing users their answers. For th ## How it works -There are 2 ways to use the task list component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://govuk-prototype-kit.herokuapp.com), you can use the Nunjucks macro. +There are 2 ways to use the task list component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit](https://govuk-prototype-kit.herokuapp.com), you can use the Nunjucks macro. {{ example({ group: "components", item: "task-list", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/components/text-input/index.md b/src/components/text-input/index.md index b137647e28..b36aa87439 100644 --- a/src/components/text-input/index.md +++ b/src/components/text-input/index.md @@ -39,7 +39,7 @@ If you’re asking just [one question per page](/patterns/question-pages/#start- Read more about [why and how to set legends as headings](/get-started/labels-legends-headings/). -There are 2 ways to use the text input component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the text input component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "text-input", example: "default", html: true, nunjucks: true, open: false, size: "s", titleSuffix: "second" }) }} diff --git a/src/components/textarea/index.md b/src/components/textarea/index.md index 6c36e033bb..8e473aecd9 100644 --- a/src/components/textarea/index.md +++ b/src/components/textarea/index.md @@ -17,7 +17,7 @@ Use the textarea component when you need to let users enter an amount of text th ## When not to use this component -Users can find open-ended questions difficult to answer. It might be better to break up one complex question into a series of simple ones, for example where users can select from options using [radios](/components/radios/). +Users can find open-ended questions difficult to answer. It might be better to break up one complex question into a series of simple ones, for example where users can select from options using [radios][component_radio]. ### If you need to ask an open question @@ -29,7 +29,7 @@ You must label textareas. Placeholder text is not a suitable substitute for a la Labels must be aligned above the textarea they refer to. They should be short, direct and written in sentence case. Do not use colons at the end of labels. -There are 2 ways to use the textarea component. You can use HTML or, if you’re using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the textarea component. You can use HTML or, if you’re using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "textarea", example: "default", html: true, nunjucks: true, open: false, size: "m", titleSuffix: "second" }) }} diff --git a/src/components/warning-text/index.md b/src/components/warning-text/index.md index aca752b186..c85397bde6 100644 --- a/src/components/warning-text/index.md +++ b/src/components/warning-text/index.md @@ -17,7 +17,7 @@ Use the warning text component when you need to warn users about something impor ## How it works -There are 2 ways to use the warning text component. You can use HTML or, if you are using [Nunjucks](https://mozilla.github.io/nunjucks/) or the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk), you can use the Nunjucks macro. +There are 2 ways to use the warning text component. You can use HTML or, if you are using [Nunjucks][lib_nunjucks] or the [GOV.UK Prototype Kit][govuk_prototype_kit], you can use the Nunjucks macro. {{ example({ group: "components", item: "warning-text", example: "default", html: true, nunjucks: true, open: false, titleSuffix: "second" }) }} diff --git a/src/get-started/focus-states/index.md b/src/get-started/focus-states/index.md index 0ce664b8c9..6cc369fee8 100644 --- a/src/get-started/focus-states/index.md +++ b/src/get-started/focus-states/index.md @@ -29,7 +29,7 @@ When form inputs are focused, they have a yellow outline and a thick black borde ![A text input labelled "What is your name?". The example shows the text input both unfocused and focused.](text-input-focus.png) -[Radios](/components/radios/) and [checkboxes](/components/checkboxes/) use the same style. +[Radios][component_radio] and [checkboxes][component_checkbox] use the same style. ![Yes and no radio options to answer the question "Have you changed your name?". In this example, the "No" option is focused.](radios-focus.png) diff --git a/src/patterns/addresses/index.md b/src/patterns/addresses/index.md index 2a77e8e5fa..bc76f9d925 100644 --- a/src/patterns/addresses/index.md +++ b/src/patterns/addresses/index.md @@ -12,7 +12,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/bank-details/index.md b/src/patterns/bank-details/index.md index 9d37d8f9f2..4ca4505c6b 100644 --- a/src/patterns/bank-details/index.md +++ b/src/patterns/bank-details/index.md @@ -12,7 +12,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/complete-multiple-tasks/index.md b/src/patterns/complete-multiple-tasks/index.md index 4381e252fc..d2ea492102 100644 --- a/src/patterns/complete-multiple-tasks/index.md +++ b/src/patterns/complete-multiple-tasks/index.md @@ -148,7 +148,7 @@ This can be helpful when a task involves: - looking up information, such as details about previous jobs - answers that need to be checked carefully with someone else -Do this by asking a radio question at the end of the task – either as the last question (if the task is a single page) or on the [‘Check answers’ page](/patterns/check-answers/) (if the task uses multiple [question pages](/patterns/question-pages/)). +Do this by asking a radio question at the end of the task – either as the last question (if the task is a single page) or on the [‘Check answers’ page][pattern_check_answers] (if the task uses multiple [question pages](/patterns/question-pages/)). Ask ‘Have you completed this section?’ with the radio options ‘Yes, I’ve completed this section’ or ‘No, I’ll come back later’. diff --git a/src/patterns/confirm-an-email-address/index.md b/src/patterns/confirm-an-email-address/index.md index df35304e18..8dce3126dd 100644 --- a/src/patterns/confirm-an-email-address/index.md +++ b/src/patterns/confirm-an-email-address/index.md @@ -12,7 +12,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/cookies-page/index.md b/src/patterns/cookies-page/index.md index a0f5853562..c4a17841e6 100644 --- a/src/patterns/cookies-page/index.md +++ b/src/patterns/cookies-page/index.md @@ -89,7 +89,7 @@ Link to the cookies page from the [service footer](/components/footer/) and from ## Letting users accept or reject cookies on the cookies page -Use [radios](/components/radios/) and a [button](/components/button/) to let users accept or reject non-essential cookies. +Use [radios][component_radio] and a [button](/components/button/) to let users accept or reject non-essential cookies. Load the page with the radios set to ‘no’ on the user’s first visit. If they’ve previously used the service and set their preferences, load the page with those preferences selected. diff --git a/src/patterns/email-addresses/index.md b/src/patterns/email-addresses/index.md index 8d87e3b9bf..17206a582d 100644 --- a/src/patterns/email-addresses/index.md +++ b/src/patterns/email-addresses/index.md @@ -11,7 +11,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} @@ -36,7 +36,7 @@ See the full list of [components and patterns affected by WCAG 2.2](/accessibili {% from "_example.njk" import example %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {{ example({ group: "patterns", item: "email-addresses", example: "default", html: true, nunjucks: true, open: false, size: "s", loading: "eager" }) }} diff --git a/src/patterns/equality-information/index.md b/src/patterns/equality-information/index.md index c2088c929f..eaef6172dc 100644 --- a/src/patterns/equality-information/index.md +++ b/src/patterns/equality-information/index.md @@ -57,7 +57,7 @@ When asking users for equality information, make it clear: For a service that people are likely to use on a one-off basis: -- place equality questions between the [‘check your answers’ page](/patterns/check-answers/) and the [confirmation page](/patterns/confirmation-pages/) +- place equality questions between the [‘check your answers’ page][pattern_check_answers] and the [confirmation page](/patterns/confirmation-pages/) - show the user a screen explaining why you’re asking the questions and what you’ll do with the information they provide, like the one below {{ example({ group: "patterns", item: "equality-information", example: "explainer-screen", html: true, nunjucks: true, open: false, loading: "eager" }) }} diff --git a/src/patterns/national-insurance-numbers/index.md b/src/patterns/national-insurance-numbers/index.md index ec38163a03..37cb8c15b8 100644 --- a/src/patterns/national-insurance-numbers/index.md +++ b/src/patterns/national-insurance-numbers/index.md @@ -12,7 +12,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/payment-card-details/index.md b/src/patterns/payment-card-details/index.md index 8b3c4eec4d..9a2ff938dd 100644 --- a/src/patterns/payment-card-details/index.md +++ b/src/patterns/payment-card-details/index.md @@ -11,7 +11,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/problem-with-the-service-pages/index.md b/src/patterns/problem-with-the-service-pages/index.md index 164d49b24b..f8a83d6884 100644 --- a/src/patterns/problem-with-the-service-pages/index.md +++ b/src/patterns/problem-with-the-service-pages/index.md @@ -12,7 +12,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/question-pages/index.md b/src/patterns/question-pages/index.md index 9e24937b3a..cfabd432c8 100644 --- a/src/patterns/question-pages/index.md +++ b/src/patterns/question-pages/index.md @@ -49,7 +49,7 @@ To help you work out what to ask, you can carry out a [question protocol](https: If you ask for optional information: - in most contexts, add ‘(optional)’ to the labels of optional fields -- for [radios](/components/radios/) and [checkboxes](/components/checkboxes/), add ‘(optional)’ to the legend +- for [radios][component_radio] and [checkboxes][component_checkbox], add ‘(optional)’ to the legend Never mark mandatory fields with asterisks. diff --git a/src/patterns/service-unavailable-pages/index.md b/src/patterns/service-unavailable-pages/index.md index 7c71b5ca79..4038f67d02 100644 --- a/src/patterns/service-unavailable-pages/index.md +++ b/src/patterns/service-unavailable-pages/index.md @@ -12,7 +12,7 @@ layout: layout-pane.njk {% from "govuk/components/inset-text/macro.njk" import govukInsetText %} {% from "govuk/components/tag/macro.njk" import govukTag %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {% set wcagCallout %} diff --git a/src/patterns/telephone-numbers/index.md b/src/patterns/telephone-numbers/index.md index d44e3e0fd4..93793096a9 100644 --- a/src/patterns/telephone-numbers/index.md +++ b/src/patterns/telephone-numbers/index.md @@ -10,7 +10,7 @@ layout: layout-pane.njk {% from "_example.njk" import example %} -This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK](https://www.gov.uk/). +This guidance is for government teams that build online services. [To find information and services for the public, go to GOV.UK][govuk]. {{ example({ group: "patterns", item: "telephone-numbers", example: "default", html: true, nunjucks: true, open: false, loading: "eager" }) }} diff --git a/src/styles/index.md b/src/styles/index.md index 077116814b..4b0299bc4a 100644 --- a/src/styles/index.md +++ b/src/styles/index.md @@ -7,6 +7,6 @@ showSubNav: true Make government services look and feel like GOV.UK. -If you are using the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk) or have [GOV.UK Frontend](https://frontend.design-system.service.gov.uk/) included in your build, the coded examples in the Design System will not need any additional styling. +If you are using the [GOV.UK Prototype Kit][govuk_prototype_kit] or have [GOV.UK Frontend][govuk_frontend_design_system] included in your build, the coded examples in the Design System will not need any additional styling. If you need to apply styles manually, you should still follow existing GOV.UK conventions. For example, do not assign new meanings to colours, do not change the style of buttons or adjust the thickness of borders on form inputs.