Feat/accessibility docs

design-system-docs/bridgetown.config.yml

@@ -20,6 +20,10 @@ permalink: pretty
 template_engine: erb
 
 collections:
+  accessibility_for_designers:
+    output: true
+    name: Accessibility for designers
+    permalink: /accessibility/accessibility-for-designers/:slug/
   guides:
     output: true
     name: Guides

design-system-docs/src/_accessibility_for_designers/_defaults.yml

@@ -0,0 +1,7 @@
+layout: accessibility_for_designers
+show_on_this_page: true
+extra_breadcrumbs:
+  - title: 'Accessibility'
+    url: '/accessibility'
+  - title: 'Accessibility for designers'
+    url: '/accessibility/accessibility-for-designers'

design-system-docs/src/_accessibility_for_designers/alt-text.md

@@ -0,0 +1,33 @@
+---
+title: Alternative text (alt-text)
+---
+
+## What is alt-text and why is it important?
+
+Alternative text serves as a textual description of images, graphics, and other non-textual elements within a web page or digital product. The importance of alt text lies in its ability to provide access, context, and inclusivity, making online experiences more meaningful and accessible to a broader range of users.
+
+Alt text is primarily designed to ensure that individuals with visual impairments or those who use screen readers can access and understand the content within images. By describing these visual elements in text form, it allows all our users to experience our products in the same way.
+
+Alt text helps all users understand the context and purpose of images, including those with slow internet connections or who choose to disable image loading. It ensures that no one misses out on vital information conveyed through visuals.
+
+Alt text also plays a significant role in improving the discoverability of web content through search engines. It will also display if the image does not load or there is a slow connection.
+
+## Key points when writing alt-text
+
+When writing alt text (alternative text), it's important to consider several key things to ensure that your content is accessible to individuals with disabilities, particularly those who use screen readers.
+
+- Describe the content: The primary purpose of alt text is to describe the content and function of the image. Be concise and focus on the most important information. Consider what the image conveys and what a person would miss if they couldn't see it. Screen readers already announce that an element is an image, so you can start with the description itself.
+- Be specific: Provide enough detail to convey the essential information. If the image contains text, include that text in the alt text. If the image is a photograph of a person, include their name and relevant details .A good rule of thumb is to aim for 125 characters or less.
+- Context: Consider the context in which the image appears. Sometimes, an image's meaning can change depending on the surrounding content. Tailor your alt text accordingly to make sense in context. Ensure that your alt text is inclusive and respectful of diversity.
+- Avoid redundant text: If the image's purpose is already described in nearby text, you can use shorter alt text or leave it empty (alt=""). However, if the image adds additional context or information, it may still require alt text.
+- Decorative images: If an image is purely decorative and doesn't convey meaningful content or function, it's best to provide empty alt text (alt="") or use the "role" attribute to indicate it's decorative (role="presentation" or role="none").
+
+## Good/bad examples of alt-text
+
+[More examples](https://www.w3.org/WAI/tutorials/images/decorative/#example-1-image-used-as-part-of-page-design)
+
+### Relevant WCAG information
+
+[Non-text Content (Level A)](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
+
+[Alt-text decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)

design-system-docs/src/_accessibility_for_designers/colour-contrast.md

@@ -0,0 +1,106 @@
+---
+title: Colour contrast
+---
+
+## A brief introduction to colour contrast
+
+Colour contrast is a fundamental and critical aspect of design that plays an important role in ensuring the accessibility, readability, and overall usability of our digital products.
+
+The contrast is in reference to the distinction between foreground (text or graphics) and background colours, which directly impacts how easily users can understand and interact with content.
+
+![Text examples illustrating good and bad contrast. On the top, a good example with black text on a white background. On the bottom a bad example, light yellow text on a white background.](/images/accessibility_for_designers/contrast-examples.png)
+
+## Why is colour contrast important?
+
+The importance of colour contrast stems from two main factors: readability and inclusivity.
+
+### Readability
+
+Adequate colour contrast is vital for users so that text and other visual elements (like icons) are legible and easy to understand. Poor contrast can make it difficult for users to read and understand content, especially those with visual impairments.. High contrast ratios between text and background colours allow users to quickly scan and comprehend information without unnecessary effort.
+
+### Inclusivity
+
+Ensuring our digital products are usable for everyone we should aim to make digital experiences available to everyone, regardless of their abilities. A significant portion of the population, including individuals with no colour vision or other visual impairments, rely on good colour contrast to navigate digital interfaces effectively.
+
+### Examples of good and bad colour contrast
+
+![Text examples illustrating good and bad colour contrast. On the left there are three examples with poor contrast. On the right there are three examples of good contrast.](/images/accessibility_for_designers/contrast-examples.png)
+
+### Key points for designers to consider
+
+#### Ratios
+
+WCAG 2.0 level AA requires a contrast ratio of:
+
+- 4.5:1 for normal text
+- 3:1 for large text
+
+WCAG 2.1 requires a contrast ratio of:
+
+- 3:1 for graphics and user interface components (such as form input borders).
+
+WCAG Level AAA requires a contrast ratio of:
+
+- 7:1 for normal text
+- 4.5:1 for large text. Large text is defined as 14 point (typically 18.66px) and bold or larger, or 18 point (typically 24px) or larger.
+
+#### Incidental
+
+Text or images of text that are part of an inactive [user interface component](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum#dfn-user-interface-component), that are [pure decoration](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum#dfn-pure-decoration), that are not visible to anyone, or that are part of a picture that contains significant other visual content, have no contrast requirement.
+
+#### Logotypes
+
+Text that is part of a logo or brand name has no contrast requirement.
+
+#### At Citizens Advice we use the following examples
+
+- Foreground: Brand primary (#004b88)
+- Background: White (#ffffff)
+
+<img src="/images/accessibility_for_designers/text-colour-contrast.png" style="width: 50%" alt="A text example in a brand colour with hex code #004b88 on a white background with hex code #ffffff"/>
+
+- Foreground: Black (#000000)
+- Background: Brand secondary (#ffc354)
+
+<img src="/images/accessibility_for_designers/focus-colour-contrast.png" style="width: 50%" alt="A text example with hex code #000000 on a brand yellow background with hex code #ffc354"/>
+
+- Foreground: Hover background colour (#004b88)
+- Background: Link colour (#F2F8FF)
+
+<img src="/images/accessibility_for_designers/link-colour-contrast.png" style="width: 50%" alt="A text example with hex code #004b88 on a brand yellow background with hex code #F2F8FF"/>
+
+### Check contrast in different screen modes
+
+You should ensure that the colour contrast is effective in different modes and for those with visual impairments:
+
+#### High contrast mode example
+
+![A web page displayed in high contrast mode, featuring a bold black background and bright yellow and white color contrasts.](/images/accessibility_for_designers/high-contrast-mode.png)
+
+#### Colour enhanced example
+
+![A web page displayed in colour enhanced mode, featuring a white background and enhanced colour copy contrasts.](/images/accessibility_for_designers/colour-enhanced-mode.png)
+
+### Focus indication
+
+[WCAG 2.4.7](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html), requires that user interface elements have visible focus indications.
+
+High contrast focus indicators make it easier for individuals who rely on keyboard navigation or screen readers to identify where their focus is on the screen. Without clear focus indication, users might inadvertently interact with the wrong elements, leading to errors and frustration.
+
+We use the Focus colour (#FFD250) to highlight focus areas.
+
+![Four user interface components each highlighted with a glowing yellow outline to indicate that they are in focus.](/images/accessibility_for_designers/focus-states.png)
+
+### How to check contrast
+
+Figma plugin: [Contrast](https://www.figma.com/community/plugin/748533339900865323/contrast)
+Just select any layer and the Contrast plugin will let you know which WCAG guidelines it meets (AA or AAA)
+
+Desktop: [colourcontrast.cc](colourcontrast.cc)
+An online checker where you add the background and foreground colour. You can also test different fonts.
+
+### Relevant WCAG information
+
+- [1.4.3: Contrast (minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum)
+- [1.4.6: Contrast (enhanced)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced)
+- [1.4.11: Contrast (non-text)](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast)

design-system-docs/src/_accessibility_for_designers/keyboard-focus.md

@@ -0,0 +1,19 @@
+---
+title: Keyboard focus
+---
+
+## Introduction to keyboard focus styling
+
+Keyboard focus styling is an indicator to users where they are on a page and which item has keyboard focus so users know what they’re interacting with. Keyboard focus has different variations depending on the component. Focus styling must be clear and visible to the user.
+
+Here are some examples of how we approach keyboard focus styling at Citizens Advice. We use the Focus colour (#FFD250) to highlight focus areas.
+
+![Four user interface components each highlighted with a glowing yellow outline to indicate that they are in focus.](/images/accessibility_for_designers/focus-states.png)
+
+## Why it’s important
+
+Keyboard styling offers clarity to a user and helps them in navigation on a page's content. Bad keyboard focus styling can make users feel lost in a web page and not know how to move forward with their interactions with us. We want users to be able to interact with our products and digital services and have clarity on where they’re going to move to next.
+
+## Relevant WCAG information
+
+[2.4.7 Focus visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)

design-system-docs/src/_accessibility_for_designers/keyboard-interaction.md

@@ -0,0 +1,35 @@
+---
+title: Keyboard interaction
+---
+
+## A brief introduction to keyboard navigation
+
+Products must be operable by keyboard as a range of users use keyboard without a mouse to access content and tools. To be accessible a web page must have visible keyboard focus and a defined tab order and avoid keyboard traps. Some users use a standard keyboard and some use a specialised keyboard to navigate content.
+
+## Why is it important
+
+It’s important for users so they have the same opportunity to interact with all content on a web page and allow users to understand how they can interact with content in a consistent way. Incorrect tabbing order can make users feel confused if pages don’t follow a logical tabbing order and they might not be able to seek the information they need.
+
+## Logical navigation order
+
+Navigation order is the order in which interactive elements like navigation receive focus on a webpage. It’s important that the order feels logical and clear. Tab order should follow the structure of the source code. Tab index should always follow the correct order but there might be instances where focus starts on the most important element on the page. It’s worth considering how your web page breaks down on small devices and how the tab order remains consistent if the visual aspect of it changes from large devices to small breakpoints e.g if a side nav is used and moves into a different position on a small device.
+
+## Documenting the change of keyboard interaction
+
+It’s important to document your tabbing order across pages and forms and share with a developer if there is a user need of why an important element needs to be higher in the tab index order.
+
+## How to check keyboard interaction
+
+Testing keyboard interaction is important, you can use [web aims guide](https://webaim.org/techniques/keyboard/) showcasing interaction types and what keystrokes to use.
+
+### Relevant WCAG information
+
+[2.1 Keyboard Accessible](https://www.w3.org/WAI/WCAG21/Understanding/keyboard-accessible.html)
+
+[2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html)
+
+[2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap)
+
+[2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html)
+
+[2.4.7 Focus visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)

design-system-docs/src/_layouts/accessibility_for_designers.erb

@@ -0,0 +1,35 @@
+---
+layout: default
+---
+
+<main id="cads-main-content" class="cads-grid-container">
+  <div class="cads-grid-row">
+    <div class="cads-grid-col-md-8">
+      <div class="cads-page-content">
+        <h1 class="cads-page-title"><%= resource.data.title %></h1>
+
+        <% if resource.data.show_on_this_page.present? %>
+          <%= render(Shared::OnThisPage.new(content)) %>
+        <% end %>
+
+        <div class="cads-prose">
+          <%= content %>
+        </div>
+      </div>
+      <%= render "feedback_prompt" %>
+    </div>
+    <div class="cads-grid-col-md-4 sidebar">
+      <%=
+        render(CitizensAdviceComponents::SectionLinks.new(
+          title: "In this section",
+          section_title: resource.collection.metadata.name,
+          section_title_url: "/accessibility/#h-accessibility-for-designers"
+        )) do |c|
+          c.with_section_links(resource.collection.resources.map do |foundation|
+            { url: foundation.relative_url, title: foundation.data.title }
+          end)
+        end
+      %>
+    </div>
+  </div>
+</main>

design-system-docs/src/_layouts/basic.erb

@@ -5,6 +5,9 @@ layout: default
 <%= render Shared::PageLayout.new do |c| %>
   <% c.with_main do %>
     <h1 class="cads-page-title"><%= resource.data.title %></h1>
+    <% if resource.data.show_on_this_page.present? %>
+      <%= render(Shared::OnThisPage.new(content)) %>
+    <% end %>
     <div class="cads-prose">
       <%= content %>
     </div>

design-system-docs/src/_pages/accessibility-for-designers.erb

@@ -0,0 +1,21 @@
+---
+title: Accessibility for designers
+layout: default
+permalink: /accessibility/accessibility-for-designers/
+extra_breadcrumbs:
+- title: "Accessibility"
+  url: "/accessibility"
+---
+
+<main id="cads-main-content" class="cads-grid-container">
+  <div class="cads-grid-row">
+    <div class="cads-grid-col-md-8 cads-page-content">
+      <h1>Accessibility for designers</h1>
+      <ul class="text-list__links">
+        <% collections.accessibility_for_designers.resources.each do |foundation| %>
+          <li><a href="<%= foundation.relative_url %>"><%= foundation.data.title %></a></li>
+        <% end %>
+      </ul>
+    </div>
+  </div>
+</main>

design-system-docs/src/_pages/accessibility.erb

@@ -0,0 +1,33 @@
+---
+title: Accessibility
+layout: default
+---
+
+<main id="cads-main-content" class="cads-grid-container">
+  <div class="cads-grid-row">
+    <div class="cads-grid-col-md-8 cads-page-content">
+      <h1 class="cads-page-title">Accessibility</h1>
+      <div class="cads-prose">
+        <p>
+          <a href="/accessibility/general-accessibility">General accessibility</a>
+        </p>
+      </div>
+      <div class="text-list">
+        <h2 class="text-list__title" id="h-for-designers">Accessibility for designers</h2>
+        <ul class="text-list__links">
+          <% collections.accessibility_for_designers.resources.each do |foundation| %>
+            <li><a href="<%= foundation.relative_url %>"><%= foundation.data.title %></a></li>
+          <% end %>
+        </ul>
+      </div>
+      <div class="text-list">
+        <h2 class="text-list__title" id="h-for-content-designers">Accessibility for content designers</h2>
+        <ul class="text-list__links">
+          <li>
+            <a href="/accessibility/accessibility-for-content-designers">General accessibility for content designers</a>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</main>