Merge branch 'main' into tags

.eleventy.js

@@ -28,6 +28,9 @@ export default function (eleventyConfig) {
   eleventyConfig.addWatchTarget('./src/')
   eleventyConfig.addWatchTarget('./docs/assets/')
 
+  // Add images to docs
+  eleventyConfig.addPassthroughCopy('docs/assets/images')
+
   // Add syntax highlighting to code blocks
   eleventyConfig.addPlugin(syntaxHighlight)
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NHS England
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,27 @@
 # NHS App Frontend
 
 NHS App Frontend is a CSS library built on top of [nhsuk-frontend](https://github.com/nhsuk/nhsuk-frontend) providing styles for the NHS App.
+
+> [!NOTE]
+> We are currently in the process of testing NHS App Frontend. The NHS App Frontend is not currently used on the NHS App.
+
+## Contact the team
+
+NHS App Frontend is mainatined by staff at NHS England. If you have a question, you can use [GitHub issues](https://github.com/nhsuk/nhsapp-frontend/issues) or one of these Slack channels:
+
+- [#general](https://nhs-service-manual.slack.com/archives/CDJ29AQCD) on NHS service manual Slack
+- [#forum-app-design-system](https://nhsdigitalcorporate.enterprise.slack.com/archives/C06GY1LRP19) on NHS England Slack
+
+## Building on the NHS digital service manual
+
+The NHS App uses the [NHS design system](https://service-manual.nhs.uk/design-system), however it also uses custom design styles, components and patterns that need documenting with guidance.
+
+## Documenting NHS App design styles, components and patterns
+
+We use a GitHub project board to track the design styles, components and patterns being used on the NHS app, including progress, examples, feedback, questions and user insights. All this information links back to the [NHS digital service manual community backlog](https://github.com/nhsuk/nhsuk-service-manual-community-backlog/projects/1) so anyone working on an NHS project can look and learn from it.
+
+---
+
+### **[View and discuss NHS App design styles, components and patterns](https://github.com/orgs/nhsuk/projects/8/views/1)**
+
+---

docs/_includes/layouts/sidebar.njk

@@ -12,7 +12,7 @@
       </div>
 
       <div class="nhsuk-grid-column-three-quarters">
-        <main role="main" id="maincontent" class="nhsuk-main-wrapper">
+        <main role="main" id="maincontent" class="nhsuk-main-wrapper app-content">
           {% block main %}
             {{ content | safe }}
           {% endblock main %}

docs/assets/css/_content.scss

@@ -0,0 +1,6 @@
+.app-content {
+  // So images do not break the container
+  img {
+    max-width: 100%;
+  }
+}

docs/assets/css/app.scss

@@ -15,5 +15,6 @@
 // Import all styles specific for the design system docs
 @import "docs/assets/css/components/side-navigation";
 @import "docs/assets/css/tabs.scss";
+@import "docs/assets/css/content.scss";
 @import "docs/assets/css/example.scss";
 @import "docs/assets/css/utilities.scss";

docs/components/badge.md

@@ -0,0 +1,60 @@
+---
+layout: layouts/component.njk
+title: Badge
+description: Use badges to alert users to unread information. Badges can include a number count.
+backlogID: 0
+tags:
+  - component
+---
+
+## When to use
+
+Badges can be placed:
+
+- on the edge of an icon
+- on a card
+
+Badges help to notify users about unread information that needs their attention. This could include new messages or new documents.
+
+## How to use
+
+Badges should be dynamic and temporary. After users have viewed the relevant information, badges should either:
+
+- disappear
+- remain if there are still unread items (but with an adjusted number count, if one is used)
+
+There are different size and colour variations of badges.
+
+### Large badges
+
+{% example "badges/badge-large.njk" %}
+
+Large badges always include a number count. This tells users how many items need their attention.
+
+Above the count of 9, large badges always display 9+. This allows the width of the badge to be restricted to two characters.
+
+### Small badges
+
+Small badges are simple circles. They can be placed:
+
+- on the edge of icons, such as on the bottom navigation
+- on cards, alongside text, such as “Document attached” on appointment cards
+
+{% example "badges/badge-small.njk" %}
+
+The colour of small badges can be:
+
+- red for important notifications that needs to stand out on a page
+- blue for secondary notifications that can afford to be less prominent
+
+{% example "badges/badge-small-red.njk" %}
+
+For example, users will see a red badge on the bottom navigation to indicate unread messages. When they then navigate to their messages inbox to view those messages, unread message headings are indicated by blue badges.
+
+## Accessibility
+
+Badges are designed to stand out when placed over icons and cards. The contrast ratio is 3:1, meeting [WCAG 2.2. Contrast (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum).
+
+We use visually hidden text to convey badges to screen reader users. Large badges announce the number count up to 9. They announce "nine plus" after that to match the visual display of 9+.
+
+Small badges could announce "New notification", "Important" or "You have unread messages" depending on the context.

docs/components/bottom-navigation.md

@@ -0,0 +1,36 @@
+---
+layout: layouts/component.njk
+title: Bottom navigation
+description: The bottom navigation helps users return to the homepage or move to a hub page.
+backlogID: 518
+tags:
+  - component
+---
+
+![The bottom navigation menu. It contains four icons with text labels: Home, Services, Your health and Messages.](/assets/images/bottom-nav.png)
+
+## When to use
+
+The bottom navigation is visible at the bottom of most pages in the NHS App. The exception is when external pages open in a web browser overlay.
+
+The top navigation remains fixed in position as users scroll.
+
+## When not to use
+
+The bottom navigation is not part of the web browser version of the NHS App. The same links are contained within an NHS.UK header instead. The bottom navigation is also not visible when external content is opened in a browser overlay within the NHS App, for example if a user navigates to the help and support pages hosted on the NHS website.
+
+## How to use
+
+Each hub is represented by a text label and an icon. The text labels match the main heading on the respective hub page.
+
+![Details of the bottom navigation menu. Icons become highlighted when selected. An unread indicator can be placed over icons.](/assets/images/bottom-nav-2.png)
+
+## Accessibility
+
+Bear in mind that the bottom navigation can be easier for users to reach than the top navigation. This lends itself to links that users may need more frequently.
+
+## Research
+
+The ‘Home’ link was previously placed on the top navigation of the NHS App. In usability testing, participants found it easier to use the link when it was placed on the bottom navigation. They also noticed that this placement was more consistent with other popular apps.
+
+We also tested recognition of the hub page icons. The icons were well recognised. The use of text labels was needed to help users differentiate the ‘Services’ and ‘Your health’ icons.

docs/components/card-links.md

@@ -52,7 +52,7 @@ If you are using icons, they should have [aria labels/hidden text?] so that scre
 
 Use badges to alert users to new, important information that sits beyond a card link. This could include unread messages or new appointment details.
 
-[embed badge example]
+{% example "cards/card-link-with-badge.njk" %}
 
 ## Content guidance
 

docs/components/top-navigation.md

@@ -0,0 +1,36 @@
+---
+layout: layouts/component.njk
+title: Top navigation
+description: Use the top navigation to help users access ‘Help’ and ‘Account and settings’ links from anywhere in the app.   
+backlogID: 524
+tags:
+  - component
+---
+
+![The top navigation menu. There are two right-aligned icons: one is a question mark and the other is shaped like a person.](/assets/images/top-nav.png)
+
+## When to use
+
+The top navigation is visible at the top almost every screen within the main app journey. The exception is when external pages open in a web browser overlay.
+
+The top navigation remains fixed in position as users scroll.
+
+## When not to use
+
+On the web browser version of the NHS App, we use an [NHS.UK header](https://service-manual.nhs.uk/design-system/components/header) with text links, instead of the top navigation with icons.
+
+## How to use
+
+The top navigation includes a link to the NHS App help and support pages hosted on NHS.UK. This is a contextual link that takes users to a page relevant to their location in the app. For example, if a user is on a prescription screen, the help link will open a help page about prescriptions.
+
+The top also includes an ’Account and settings’ link. This opens the respective hub page.
+
+![Details of the top navigation menu. The question mark icon links to Help and Support. The person icon links to Account.](/assets/images/top-nav-2.png)
+
+## Accessibility
+
+The top navigation icons do not have text labels. They have aria labels which are announced by screen readers.
+
+## Research
+
+In our research, people recognised the meaning of the icons without the need for text labels.

docs/examples/badges/badge-large.njk

@@ -0,0 +1,13 @@
+---
+layout: layouts/example.njk
+title: Badge Large
+figmaLink: "https://www.figma.com/design/6f2CbcZ7cnpNrtKEcfQp8X/NHS-App-Design-System?node-id=128-7303&t=UdzCaY5YPtBypveQ-0"
+vueLink: "https://nhsappvuecomponentlibraryv1.nonlive.nhsapp.service.nhs.uk/?path=/docs/components-nhsbadge-large--docs"
+---
+
+{% from "badge/large/macro.njk" import badgeLarge %}
+
+{{ badgeLarge({
+  count: 3,
+  label: 'notifications'
+}) }}

docs/examples/badges/badge-small-red.njk

@@ -0,0 +1,15 @@
+---
+layout: layouts/example.njk
+title: Badge Small
+figmaLink: "https://www.figma.com/design/6f2CbcZ7cnpNrtKEcfQp8X/NHS-App-Design-System?node-id=128-7303&t=UdzCaY5YPtBypveQ-0"
+vueLink: "https://nhsappvuecomponentlibraryv1.nonlive.nhsapp.service.nhs.uk/?path=/docs/components-nhsbadge-small--docs"
+---
+
+{% from "badge/small/macro.njk" import badgeSmall %}
+
+{{ badgeSmall({
+label: 'New',
+color: 'red',
+text: 'Document attached',
+classes: 'nhsuk-body-m'
+}) }}

docs/examples/badges/badge-small.njk

@@ -0,0 +1,14 @@
+---
+layout: layouts/example.njk
+title: Badge Small
+figmaLink: "https://www.figma.com/design/6f2CbcZ7cnpNrtKEcfQp8X/NHS-App-Design-System?node-id=128-7303&t=UdzCaY5YPtBypveQ-0"
+vueLink: "https://nhsappvuecomponentlibraryv1.nonlive.nhsapp.service.nhs.uk/?path=/docs/components-nhsbadge-small--docs"
+---
+
+{% from "badge/small/macro.njk" import badgeSmall %}
+
+{{ badgeSmall({
+label: 'New',
+text: 'Document attached',
+classes: 'nhsuk-body-m'
+}) }}

docs/examples/cards/card-link-with-badge.njk

@@ -0,0 +1,17 @@
+---
+layout: layouts/example.njk
+title: Card link with description
+figmaLink: "https://www.figma.com/file/6f2CbcZ7cnpNrtKEcfQp8X/NHS-App-Design-System?type=design&node-id=128%3A7303&mode=design&t=DLiyCHcTTAYkEDa0-1"
+vueLink: "https://nhsappvuecomponentlibraryv1.nonlive.nhsapp.service.nhs.uk/?path=/docs/components-nhscardlink--docs"
+---
+
+{% from "card/macro.njk" import card %}
+
+{{ card({
+  title: 'Messages',
+  href: '#',
+  badgeLarge: {
+    count: 4,
+    label: 'unread messages'
+  }
+}) }}

docs/index.njk

@@ -4,6 +4,7 @@
 
 {%- from 'hero/macro.njk' import hero -%}
 {%- from 'card/macro.njk' import card -%}
+{%- from 'badge/large/macro.njk' import badgeLarge -%}
 
 {% block header %}
   {{ super() }}

src/all.scss

@@ -3,3 +3,4 @@
 
 @import "./components/card/card.scss";
 @import "./components/tag/tag.scss";
+@import "./components/badge/badge";

src/components/badge/_badge.scss

@@ -0,0 +1,73 @@
+// ==========================================================================
+// COMPONENTS / #BADGE
+// ==========================================================================
+
+@use "sass:math";
+
+.nhsapp-badge {
+  @include nhsuk-typography-responsive(19);
+
+  display: inline-block;
+
+  background-color: $nhsuk-error-color;
+  border-radius: nhsuk-spacing(1);
+  color: $color_nhsuk-white;
+  font-weight: bold;
+  padding: 0 nhsuk-spacing(2);
+
+  @include mq($from: tablet) {
+    padding: 0 12px;
+  }
+}
+
+.nhsapp-badge-small {
+  position: relative;
+
+  display: inline-flex;
+  align-items: baseline;
+}
+
+/**
+  * Mixin to position the small badge
+  * @param {number} $size - The size of the badge
+  */
+@mixin small-badge-position($size: 8px) {
+  position: relative;
+  width: $size;
+  height: $size;
+  margin-right: $size;
+  border-radius: math.div($size, 2);
+
+  $font-height: 0.7em; // The height of a capital letter in the specific font we use (Frutiger)
+  bottom: calc(0.5 * ($font-height - $size));
+}
+
+$nhsapp-badge-size-mobile: 8px;
+$nhsapp-badge-size-tablet: 12px;
+
+.nhsapp-badge-small__indicator {
+  @include small-badge-position($nhsapp-badge-size-mobile);
+
+  @include mq($from: tablet) {
+    @include small-badge-position($nhsapp-badge-size-tablet);
+  }
+
+  background-color: $color_nhsuk-blue;
+}
+
+.nhsapp-badge-small--red {
+  .nhsapp-badge-small__indicator {
+    background-color: $nhsuk-error-color;
+  }
+}
+
+.nhsapp-badge-small--absolute {
+  .nhsapp-badge-small__indicator {
+    position: absolute;
+
+    left: -2 * $nhsapp-badge-size-mobile;
+    @include mq($from: tablet) {
+      left: -2 * $nhsapp-badge-size-tablet;
+    }
+  }
+}

src/components/badge/large/badge-large.njk

@@ -0,0 +1,11 @@
+{%- if params.count -%}
+<span class="nhsapp-badge">
+    <span class="nhsuk-u-visually-hidden">You have</span>
+    {% if params.count > 9 %}
+        +9
+    {% else %}
+        {{ params.count }}
+    {% endif %}
+    <span class="nhsuk-u-visually-hidden">{{ params.label }}</span>
+</span>
+{%- endif -%}

src/components/badge/large/macro.njk

@@ -0,0 +1,3 @@
+{% macro badgeLarge(params) %}
+  {%- include "./badge-large.njk" -%}
+{% endmacro %}