From 3251f7a207d323b56c677f643d9b28e3cf1e5c24 Mon Sep 17 00:00:00 2001
From: GCHQ-Developer-299
 <111292477+GCHQ-Developer-299@users.noreply.github.com>
Date: Wed, 28 Feb 2024 09:21:16 +0000
Subject: [PATCH] docs(root): add accessible labels to chip icons

add aria-labels to the examples in IcChip's guidance pages

ref #1560
---
 .../components/chips/accessibility.mdx        |   4 +-
 .../structured/components/chips/code.mdx      | 216 ++++++++++--------
 .../structured/components/chips/guidance.mdx  |   4 +-
 3 files changed, 122 insertions(+), 102 deletions(-)

diff --git a/src/content/structured/components/chips/accessibility.mdx b/src/content/structured/components/chips/accessibility.mdx
index beda5b4ff..2cd456ffc 100644
--- a/src/content/structured/components/chips/accessibility.mdx
+++ b/src/content/structured/components/chips/accessibility.mdx
@@ -1,7 +1,7 @@
 ---
 path: "/components/chip/accessibility"
 
-date: "2023-02-03"
+date: "2024-02-28"
 
 title: "Chip"
 
@@ -27,6 +27,8 @@ When an interactive chip is disabled, the `aria-disabled` tag is set to `true`.
 
 Make sure that focus is moved to an intuitive element of the page after a chip is dismissed.
 
+When an icon is slotted into a chip, ensure it either has an accessible label provided through alt text on an `<img>`, a title element within an `<svg>`, or an `aria-label`. If the icon is purely decorative, use `aria-hidden=true` to hide it from assistive technology.
+
 ## For Assistive Technology
 
 Dismissible chips use the role of button as opposed to link in order to help users of assistive technologies understand that the button is performing an action on the page instead of navigating them to a new location. Users should be aware that activating the button will remove the chip from the list.
diff --git a/src/content/structured/components/chips/code.mdx b/src/content/structured/components/chips/code.mdx
index 7c630d3cf..49beaaf31 100644
--- a/src/content/structured/components/chips/code.mdx
+++ b/src/content/structured/components/chips/code.mdx
@@ -1,7 +1,7 @@
 ---
 path: "/components/chip/code"
 
-date: "2024-02-02"
+date: "2024-02-28"
 
 title: "Chip"
 
@@ -27,48 +27,52 @@ export const snippetsDefault = [
   {
     language: "Web component",
     snippet: `<ic-chip label="Americano" dismissible="true" id='my-chip'>
-      <svg
-        slot="icon"
-        viewBox="0 0 24 24"
-        fill="currentColor"
-        xmlns="http://www.w3.org/2000/svg"
-      >
-        <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-      </svg>
-      </ic-chip>
-      <ic-chip label="Cappuccino">
-        <svg
-          slot="icon"
-          viewBox="0 0 24 24"
-          fill="currentColor"
-          xmlns="http://www.w3.org/2000/svg"
-        >
-          <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-        </svg>
-      </ic-chip>`,
+  <svg
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </svg>
+</ic-chip>
+<ic-chip label="Cappuccino">
+  <svg
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </svg>
+</ic-chip>`,
   },
   {
     language: "React",
     snippet: `<IcChip label="Americano" dismissible onIcDismiss={(ev) => console.log(ev)}>
-      <SlottedSVG
-        slot="icon"
-        viewBox="0 0 24 24"
-        fill="currentColor"
-        xmlns="http://www.w3.org/2000/svg"
-      >
-        <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-      </SlottedSVG>
-      </IcChip>
-      <IcChip label="Cappuccino">
-        <SlottedSVG
-          slot="icon"
-          viewBox="0 0 24 24"
-          fill="currentColor"
-          xmlns="http://www.w3.org/2000/svg"
-        >
-          <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-        </SlottedSVG>
-      </IcChip>`,
+  <SlottedSVG
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </SlottedSVG>
+</IcChip>
+<IcChip label="Cappuccino">
+  <SlottedSVG
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </SlottedSVG>
+</IcChip>`,
   },
 ];
 
@@ -87,6 +91,7 @@ export const snippetsDefault = [
       viewBox="0 0 24 24"
       fill="currentColor"
       xmlns="http://www.w3.org/2000/svg"
+      aria-label="coffee"
     >
       <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z" />
     </svg>
@@ -97,6 +102,7 @@ export const snippetsDefault = [
       viewBox="0 0 24 24"
       fill="currentColor"
       xmlns="http://www.w3.org/2000/svg"
+      aria-label="coffee"
     >
       <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z" />
     </svg>
@@ -115,28 +121,30 @@ export const snippetsOutline = [
   {
     language: "Web component",
     snippet: `<ic-chip label="Americano" variant="outlined">
-    <svg
-      slot="icon"
-      viewBox="0 0 24 24"
-      fill="currentColor"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-       <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
-    </svg>
-  </ic-chip>`,
+  <svg
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
+  </svg>
+</ic-chip>`,
   },
   {
     language: "React",
     snippet: `<IcChip label="Americano" variant="outlined">
-    <SlottedSVG
-      slot="icon"
-      viewBox="0 0 24 24"
-      fill="currentColor"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-       <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
-    </SlottedSVG>
-  </IcChip>`,
+  <SlottedSVG
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
+  </SlottedSVG>
+</IcChip>`,
   },
 ];
 
@@ -155,6 +163,7 @@ export const snippetsOutline = [
       viewBox="0 0 24 24"
       fill="currentColor"
       xmlns="http://www.w3.org/2000/svg"
+      aria-label="coffee"
     >
       <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z" />
     </svg>
@@ -167,32 +176,34 @@ export const snippetsDismissible = [
   {
     language: "Web component",
     snippet: `<ic-chip label="Americano" dismissible="true" id='my-chip'>
-    <svg
-      slot="icon"
-      viewBox="0 0 24 24"
-      fill="currentColor"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-       <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-    </svg>
-  </ic-chip>
-  <script>
-    const chip = document.querySelector('#my-chip');
-    chip.addEventListener('icDismiss', (ev) => console.log(ev));
-  </script>`,
+  <svg
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </svg>
+</ic-chip>
+<script>
+  const chip = document.querySelector('#my-chip');
+  chip.addEventListener('icDismiss', (ev) => console.log(ev));
+</script>`,
   },
   {
     language: "React",
     snippet: `<IcChip label="Americano" dismissible onIcDismiss={(ev) => console.log(ev)}>
-    <SlottedSVG
-      slot="icon"
-      viewBox="0 0 24 24"
-      fill="currentColor"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-    </SlottedSVG>
-  </IcChip>`,
+  <SlottedSVG
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </SlottedSVG>
+</IcChip>`,
   },
 ];
 
@@ -211,6 +222,7 @@ export const snippetsDismissible = [
       viewBox="0 0 24 24"
       fill="currentColor"
       xmlns="http://www.w3.org/2000/svg"
+      aria-label="coffee"
     >
       <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z" />
     </svg>
@@ -228,6 +240,7 @@ export const snippetsDisabled = [
     viewBox="0 0 24 24"
     fill="currentColor"
     xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
   >
     <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
   </svg>
@@ -238,33 +251,36 @@ export const snippetsDisabled = [
     viewBox="0 0 24 24"
     fill="currentColor"
     xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
   >
-     <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
+    <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
   </svg>
 </ic-chip>`,
   },
   {
     language: "React",
     snippet: `<IcChip label="Americano" dismissible disabled>
-    <SlottedSVG
-      slot="icon"
-      viewBox="0 0 24 24"
-      fill="currentColor"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
-    </SlottedSVG>
-  </IcChip>
-  <IcChip label="Americano" variant="outlined" dismissible disabled>
-    <SlottedSVG
-      slot="icon"
-      viewBox="0 0 24 24"
-      fill="currentColor"
-      xmlns="http://www.w3.org/2000/svg"
-    >
-      <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
-    </SlottedSVG>
-  </IcChip>`,
+  <SlottedSVG
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z"/>
+  </SlottedSVG>
+</IcChip>
+<IcChip label="Americano" variant="outlined" dismissible disabled>
+  <SlottedSVG
+    slot="icon"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-label="coffee"
+  >
+    <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
+  </SlottedSVG>
+</IcChip>`,
   },
 ];
 
@@ -283,6 +299,7 @@ export const snippetsDisabled = [
       viewBox="0 0 24 24"
       fill="currentColor"
       xmlns="http://www.w3.org/2000/svg"
+      aria-label="coffee"
     >
       <path d="M2,21V19H20V21H2M20,8V5H18V8H20M20,3A2,2 0 0,1 22,5V8A2,2 0 0,1 20,10H18V13A4,4 0 0,1 14,17H8A4,4 0 0,1 4,13V3H20M16,5H6V13A2,2 0 0,0 8,15H14A2,2 0 0,0 16,13V5Z" />
     </svg>
@@ -293,6 +310,7 @@ export const snippetsDisabled = [
       viewBox="0 0 24 24"
       fill="currentColor"
       xmlns="http://www.w3.org/2000/svg"
+      aria-label="coffee"
     >
       <path d="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z" />
     </svg>
diff --git a/src/content/structured/components/chips/guidance.mdx b/src/content/structured/components/chips/guidance.mdx
index e7b996b9c..e13fc3546 100644
--- a/src/content/structured/components/chips/guidance.mdx
+++ b/src/content/structured/components/chips/guidance.mdx
@@ -3,7 +3,7 @@ path: "/components/chip"
 
 navPriority: 9
 
-date: "2023-04-17"
+date: "2024-02-28"
 
 title: "Chip"
 
@@ -188,7 +188,7 @@ Use an icon on the left of a dismissible or static chip to provide additional me
 
 When including an icon in a chip make sure that the icon is understandable and relevant to the information presented.
 
-Always provide alternative descriptions for icons. Don't use icons if they aren't necessary.
+Always provide alternative descriptions for icons, or mark them as decorative. Don't use icons if they aren't necessary.
 
 ## Related components