Banner updates

docs/_includes/arguments/alert.md

@@ -0,0 +1,15 @@
+| Name                   | Type    | Required | Description                                                                         |
+| ---------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
+| text                   | string  | Yes      | The text that displays in the alert. Any string can be used. If you set `html`, this option is not required and is ignored. |
+| html                   | string  | Yes      | The HTML to use in the alert. Any string can be used. If you set `html`, `text` is not required and is ignored.|
+| title                  | string  | Yes      | A short title for each alert, used as a unique accessible label. Can be displayed as a heading in the alert using `showTitleAsHeading`. |
+| showTitleAsHeading     | boolean | No       | Set to true to display the `title` as a heading. The default is `false`. |
+| titleTag               | string  | No       | The HTML tag used for the heading if `showTitleAsHeading` is true. You can only use the values "h2", "h3", or "h4". The default is "h2".|
+| variant                | string  | No       | The alert variant being used. It's "information", "success", "warning" or "error". The default is "information".                                                    |
+| role                   | string  | No       | Overrides the value of the role attribute for the alert. Defaults to "region". |
+| disableAutoFocus       | boolean | No       | If `role` is set to "alert", JavaScript moves the keyboard focus to the alert when the page loads. To disable this behaviour, set `disableAutoFocus` to `true`.|
+| dismissible            | boolean | No       | Set to `true` to allow the alert to be dismissed. The default is `false`. |
+| dismissText            | string  | No       | The text label for the dismiss button. The default is "Dismiss". |
+| focusOnDismissSelector | string  | No       | A CSS selector for an element to place focus on when the alert is dismissed |
+| classes                | string  | No       | The classes that you want to add to the alert. |
+| attributes             | object  | No       | The HTML attributes that you want to add to the alert, for example data attributes. |

docs/_includes/layouts/home.njk

@@ -19,9 +19,8 @@
   <div class="app-layout__content">
       <div class="app-cards">
         {% call card({title: "What's new" })%}
+        <p class="govuk-body">24 February 2025: The <a href="/components/alert/">alert component</a> is now live. It's based on the <a href="/archive/banner/">banner component</a>, which has been archived.</p>
         <p class="govuk-body">18 December 2024: The <a href="/content-standards/style-guide/">MoJ content style guide</a> is now live.</p>
-          <p class="govuk-body">10 December 2024: The <a href="/components/interruption-card/">interruption card component</a> is now live. Use it to help users understand possible errors and avoid serious mistakes.</p>
-          <p class="govuk-body">26 November 2024: We’ve archived the <a href="/archive/password-reveal/">password reveal component</a>. We recommend that teams use the <a href="https://design-system.service.gov.uk/components/password-input/">GOV.UK Design System password input</a> instead.</p>
           <p class="govuk-body"><a href="https://docs.google.com/forms/d/1i7rinQINSjdQ6w_SChXqxQFTttPMgfcSfPamq8YRnP8/viewform">Sign up to get emails</a> about the MoJ Design System.</p>
         {% endcall %}
 

docs/components/banner.md → docs/archive/banner.md

@@ -1,20 +1,20 @@
 ---
-layout: layouts/component.njk
+layout: layouts/archive.njk
 title: Banner
 status: To be reviewed
 statusDate: June 2021
 type: component
+redirect_from: components/banner
 githuburl: https://github.com/ministryofjustice/moj-frontend/discussions/835
 eleventyNavigation:
   key: Banner
-  parent: Components
+  parent: Archive
   excerpt: "Use the banner component to display a prominent message and related actions to take."
 ---
 
-{% banner "The GOV.UK Design System has a similar component" %}
-The [Notification banner component](https://design-system.service.gov.uk/components/notification-banner/) in the GOV.UK Design System has a similar function and visual design to this component.
+{% banner "This component is archived" %}
 
-You should consider using the GOV.UK version if it fits your needs.
+Use the [alert](/components/alert) to display a notification to users.
 {% endbanner %}
 
 {% example "/examples/banner", 225 %}

docs/components/alert.md

@@ -0,0 +1,242 @@
+---
+layout: layouts/component.njk
+title: Alert
+status: Official
+statusDate: February 2025
+type: component
+githuburl: https://github.com/ministryofjustice/moj-frontend/discussions/1163
+eleventyNavigation:
+  key: Alert
+  parent: Components
+  excerpt: "Use the alert component to display a prominent message and related actions to take."
+---
+
+<span class="govuk-caption-xl">The alert component uses visual design to display a notification to users. It has a range of use cases.</span>
+
+{% tabs "Contents" %}
+
+{% tab "Overview" %}
+
+{% example "/examples/alert" %}
+
+## Overview
+
+The alert component presents 1 of 4 types of alerts to a user. It can stay on the page or be dismissed by the user.  
+
+As a leaner component, it’s ideal for internal services and complex user interfaces (such as dashboards and case management systems).  
+
+There are 4 variants of the alert:
+
+1. [Information alert](#information-alert)
+2. [Warning alert](#warning-alert)
+3. [Error alert](#error-alert)
+4. [Success alert](#success-alert)
+
+### Information alert
+
+{% example "/examples/alert-information" %}
+
+The information alert draws a user's attention to something important about a page or service. It has a blue border, and an information icon made up of a blue circle with a white letter 'i'.
+
+#### When to use
+Use the information alert sparingly. This makes users more likely to notice and engage with it. If a lot of information alerts are emerging in a service, it might be a sign that a journey needs redesigning.
+
+The information alert can tell a user about:
+
+- unfinished tasks, linking to where to complete them
+- a major change to a service, until it becomes familiar
+- service downtime  
+
+The information alert can be combined with other alert variants. For linear services, or to display the 'Important' heading, use the <a href="https://design-system.service.gov.uk/components/notification-banner">GOV.UK notification banner component</a>.
+
+#### When not to use
+
+Do not want use this component for a serious issue or to prevent something going wrong. Use the warning alert for this.
+
+### Warning alert
+
+{% example "/examples/alert-warning" %}
+
+The warning alert tells users about something to prevent them from making a mistake. Use it sparingly to avoid alert fatigue. It has an orange border, and a warning icon made up of an orange triangle with a white exclamation mark.  
+
+#### When to use
+
+A warning alert can be used when something:
+
+- is missing but the user can access it another way, for example in a legacy system or on paper
+- has not been updated recently but may still be of use, for example an assessment
+- has become more urgent or important, for example because a deadline is approaching
+
+If you want to add your message to the body copy or do not want a coloured border and icon, use the [GOV.UK inset text component](https://design-system.service.gov.uk/components/inset-text/) or the [GOV.UK warning text component](https://design-system.service.gov.uk/components/warning-text/).
+
+#### When not to use
+
+Do not use this component if the information is about something other than a warning. Select the [information alert](#information-alert) instead.
+
+### Error alert
+
+{% example "/examples/alert-error" %}
+
+The error alert shows the user that something has gone wrong. It pauses the user without interrupting them. It can appear before or after a user input. It has a red border, and an error icon made up of a red octagon with a white 'X'.
+
+<div class="govuk-warning-text">
+  <span class="govuk-warning-text__icon" aria-hidden="true">!</span>
+  <strong class="govuk-warning-text__text">
+    <span class="govuk-visually-hidden">Warning</span>
+    Do not use the error alert for validation errors. Continue to use the <a href="https://design-system.service.gov.uk/components/error-message">GOV.UK error message</a> for this.
+  </strong>
+</div>
+
+#### When to use
+
+The error alert can be displayed when something:
+
+- has changed significantly since the user’s last session, for example, a person has been released from prison or an appointment is now double-booked
+- changed between the user opening the page and interacting with it, for example a case was deleted or assigned to someone else
+- has to be done before this task, for example removing bookings from a property they're archiving
+
+If the user needs to resolve the error, the alert should help them understand how.
+
+#### When not to use
+
+This alert draws a user’s attention to a message, without preventing them from doing other tasks on the page. Use the [interruption card component](/components/interruption-card/) if the user needs to acknowledge something before they continue on their journey.
+
+### Success alert
+
+{% example "/examples/alert-success" %}
+
+The success alert displays a single message after a user has completed a task. It has a green border, and a success icon made up of a green tick.
+
+This alert can be displayed at the top of the page or on the next page (if their task moves them through the service). Adding the alert to existing pages shortens the user journey. This is useful in non-linear services and services where users complete repetitive tasks.
+
+#### When to use
+
+The success banner can be used to show that something has:
+
+- been uploaded or added, such as a file or record
+- changed status, for example allocated to someone or moved to another stage in an application process
+- been cancelled, deleted or another type of destructive (negative) action
+- been changed or deleted from a table using the [multi select component](/components/multi-select/)
+
+If you need to display more information or want a more prominent component, consider the [success variation of the GOV.UK notification banner](https://design-system.service.gov.uk/components/notification-banner/#reacting-to-something-the-user-has-done).
+
+#### When not to use
+
+Do not show the success alert to a user who has completed something more significant (such as a whole application) or reached the end of a service. Select the [GOV.UK confirmation page](https://design-system.service.gov.uk/patterns/confirmation-pages/) instead.
+
+You may not need to display the alert if something else confirms success, for example the [GOV.UK task list component](https://design-system.service.gov.uk/components/task-list/) or the user progressing to another page.
+
+### Things to consider
+
+This alert pauses the user with a prominent message. This prioritisation should match the alert message and its relevance to the user.
+
+An alert needs a title, which does not need to be displayed as a heading. The title gives each alert a unique label and helps screenreaders to identify the alert. It does not have to be read out.
+
+{% endtab %}
+
+{% tab "How to use" %}
+
+## How to use
+
+The alert works best when it contains a single, succinct message.
+
+Do not use it to display large amounts of content. This reduces the prominence of the component and pushes other content down the page. If you cannot communicate your message in under 3 sentences, use a different component.
+
+### What to add to it
+
+The alert contains an icon and is surrounded by a border. It needs to contain body copy, with a full stop at the end of each sentence.
+
+The alert needs a title, which does not need to be shown on the page. The title gives each alert a unique and accessible label, which can be read out to screenreader users.
+
+You can add one heading (but no more) to the body copy. The heading level should follow its position on the page. For example, an alert heading would be an H2 if placed under a main page heading.
+
+You can also add bullet points and links, if needed.
+
+The alert content needs to make sense on its own. This ensures that the message does not rely on the colour and icon, as they're not accessible to everyone.
+
+### Dismissing the alert
+
+{% example "/examples/alert-dismissible" %}
+
+The alert can stay on the page (be persistent) or be dismissed by the user. Dismissing it helps users to manage tasks and keep their interfaces clear. It's particularly helpful for the success alert, where there's nothing more for the user to do.
+
+<div class="govuk-warning-text">
+  <span class="govuk-warning-text__icon" aria-hidden="true">!</span>
+  <strong class="govuk-warning-text__text">
+    <span class="govuk-visually-hidden">Warning</span>
+    Do not set up the alert to auto-dismiss, for example to disappear after a few seconds or when the user interacts with the page. This is not accessible.
+  </strong>
+</div>
+
+When an alert is dismissed, the focus will go to one of the following:
+
+- the heading above, if there are no more alerts on the page
+- the previous or next alert, if there are any more on the page
+- the `main` element, if there's no heading above the alert
+
+If you want the focus to go somewhere else, use the `focusOnDismissSelector` Nunjucks macro option. If this does not work, the focus will go to 1 of the 3 options.
+
+### Height and width
+
+The alert has no minimum or maximum height – it resizes to the contents. It should not be used to display a lot of content, though.
+
+The alert will take the width of the container, and will automatically adjust for readability.
+
+### How often to use it
+
+When considering an alert in a specific case, think about the maximum number of alerts or banners a user might view on a page and in a journey.
+
+If a lot of information and warning alerts are emerging in a service (for example, on every page) it might be a sign of a wider problem. This could be fixed through service design.
+
+#### Stacking alerts
+
+It's OK to present more than 1 alert on a page – they'll stack. When developing your alert strategy, consider:
+
+- separating alerts that do not involve anything further for a user do – these can be easily dismissed
+- combining instances of the warning, error and information states to reduce the number of alerts
+- that the 'alert' read out to screenreader users should only be applied to one alert  
+
+### Where to add it
+
+An alert can be displayed globally or in context, depending on the type of message.
+
+A global alert is shown on all pages (or any page) and is about the service as a whole, for example service downtime. It can also be displayed on a homepage to draw the user’s attention to new and unknown issues. A contextual alert is shown in (and is about) a particular section.
+
+Place alerts about a whole service or page at the top of the page above the main heading and below the back link (if there is one). An alert can also be positioned under a relevant heading, but should not be added to body copy.
+
+### Alert colours and icons
+
+The link text colour is the same as the rest of the variant. Each alert has an icon, which must not be removed. Removing the icon makes an alert too reliant on colour, which cannot be accessed by everyone. Do not change the colours.
+
+#### Alert usage on coloured backgrounds
+
+The alert is accessible on a `govuk-colour("white")` or `govuk-colour("light-grey")` background.
+
+An alert should not be placed on a coloured background because:
+
+- the colour contrast between the border and page may not be accessible
+- the background may distract from the border colour and change the emphasis of the message  
+
+{% endtab %}
+
+{% tab "Examples" %}
+
+## Examples
+
+### Alerts in a case management system
+
+An error and success alert under an H1 shows a user that one of their tasks failed, and another was successful. It can be shown on the dashboard rather than another page.
+
+<p><img src="{{ 'assets/images/alert-example-case-management.png' | rev | url }}" alt="An MoJ webpage showing a success alert positioned below the heading level 1."></p>
+
+### Error alert under a subheading
+
+Alerts positioned inline with other content help people to understand what the message relates to. In this example the heading level of the alert component should be changed to H3 as it appears within an H2 heading.
+
+<p><img src="{{ 'assets/images/alert-example-contextual.png' | rev | url }}" alt="A warning alert with heading level 3 is shown beneath a heading level 2 on an MoJ webpage to highlight the importance of maintaining heading structure.'"></p>
+
+{% endtab %}
+
+{% endtabs %}
+
+<hr />

docs/examples/alert-dismissible/index.njk

@@ -0,0 +1,14 @@
+---
+layout: layouts/example.njk
+title: Alert (example)
+arguments: alert
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=66-5802
+---
+{%- from "moj/components/alert/macro.njk" import mojAlert -%}
+
+{{ mojAlert({
+  variant: "success",
+  title: "File uploaded successfully",
+  dismissible: true,
+  html: '<a href="#">Scan1.jpg</a> has been added to this application.'
+}) }}

docs/examples/alert-error/index.njk

@@ -0,0 +1,14 @@
+---
+layout: layouts/example.njk
+title: Alert (example)
+arguments: alert
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=66-5802
+---
+{%- from "moj/components/alert/macro.njk" import mojAlert -%}
+
+{{ mojAlert({
+  variant: "error",
+  title: "This case has been assigned to someone else",
+  dismissible: false,
+  text: "This case has been assigned to someone else, so you can no longer make changes."
+}) }}

docs/examples/alert-information/index.njk

@@ -0,0 +1,14 @@
+---
+layout: layouts/example.njk
+title: Alert (example)
+arguments: alert
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=66-5802
+---
+{%- from "moj/components/alert/macro.njk" import mojAlert -%}
+
+{{ mojAlert({
+  variant: "information",
+  title: "A section has moved",
+  dismissible: false,
+  html: 'The finance section has moved to the <a href="#">dashboard</a>.'
+}) }}

docs/examples/alert-success/index.njk

@@ -0,0 +1,14 @@
+---
+layout: layouts/example.njk
+title: Alert (example)
+arguments: alert
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=66-5802
+---
+{%- from "moj/components/alert/macro.njk" import mojAlert -%}
+
+{{ mojAlert({
+  variant: "success",
+  title: "Upload successful",
+  dismissible: false,
+  html: '<a href="#">Scan1.jpg</a> uploaded successfully.'
+}) }}

docs/examples/alert-warning/index.njk

@@ -0,0 +1,14 @@
+---
+layout: layouts/example.njk
+title: Alert (example)
+arguments: alert
+figma_link: https://www.figma.com/design/N2xqOFkyehXwcD9DxU1gEq/MoJ-Figma-Kit?node-id=66-5802
+---
+{%- from "moj/components/alert/macro.njk" import mojAlert -%}
+
+{{ mojAlert({
+  variant: "warning",
+  title: "Some information could not be imported",
+  dismissible: false,
+  html: 'Some information could not be imported. Enter <a href="#">client details</a> manually instead.'
+}) }}