Add aria-describedby to file list items for better accessibility

nationalarchives · Sep 4, 2024 · f88a88f · f88a88f
1 parent 0b962ea
commit f88a88f
Show file tree

Hide file tree

Showing 6 changed files with 44 additions and 22 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased](https://github.com/nationalarchives/tna-frontend/compare/v0.2.11...HEAD)
 
 ### Added
+
+- Items in a file list now require an ID so that an `aria-describedby` attribute can be used to describe the file details
+
 ### Changed
 
 - Updated default text on cookie banner hide buttons

diff --git a/src/nationalarchives/components/files-list/files-list.scss b/src/nationalarchives/components/files-list/files-list.scss
@@ -45,6 +45,9 @@
   &__item-title {
   }
 
+  &__item-body {
+  }
+
   &__item-meta {
     margin-top: 0;
   }

diff --git a/src/nationalarchives/components/files-list/files-list.stories.js b/src/nationalarchives/components/files-list/files-list.stories.js
@@ -28,6 +28,7 @@ export const Default = Template.bind({});
 Default.args = {
   items: [
     {
+      id: "file-1",
       text: "Preservation policy part 1",
       href: "#",
       fileType: "PDF",
@@ -37,6 +38,7 @@ Default.args = {
         "The principles according to which The National Archives will preserve and care for our archival collections.",
     },
     {
+      id: "file-2",
       text: "Preservation policy part 2",
       href: "#",
       fileType: "PDF",
@@ -45,6 +47,7 @@ Default.args = {
         "The principles according to which The National Archives will preserve and care for our archival collections.",
     },
     {
+      id: "file-3",
       text: "Preservation policy part 3",
       href: "#",
       fileType: "PDF",

diff --git a/src/nationalarchives/components/files-list/fixtures.json b/src/nationalarchives/components/files-list/fixtures.json
@@ -7,6 +7,7 @@
         "itemHeadingLevel": 3,
         "items": [
           {
+            "id": "file-1",
             "text": "Preservation policy part 1",
             "href": "#",
             "file_type": "PDF",
@@ -15,13 +16,15 @@
             "description": "The principles according to which The National Archives will preserve and care for our archival collections."
           },
           {
+            "id": "file-2",
             "text": "Preservation policy part 2",
             "href": "#",
             "file_type": "PDF",
             "file_size": "0.9MB",
             "description": "The principles according to which The National Archives will preserve and care for our archival collections."
           },
           {
+            "id": "file-3",
             "text": "Preservation policy part 3",
             "href": "#",
             "file_type": "PDF",
@@ -30,14 +33,15 @@
           }
         ]
       },
-      "html": "<div class=\"tna-files-list\"><svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"tna-files-list__icon\" width=\"24\"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d=\"M288 32c0-17.7-14.3-32-32-32s-32 14.3-32 32V274.7l-73.4-73.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l128 128c12.5 12.5 32.8 12.5 45.3 0l128-128c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L288 274.7V32zM64 352c-35.3 0-64 28.7-64 64v32c0 35.3 28.7 64 64 64H448c35.3 0 64-28.7 64-64V416c0-35.3-28.7-64-64-64H346.5l-45.3 45.3c-25 25-65.5 25-90.5 0L165.5 352H64zm368 56a24 24 0 1 1 0 48 24 24 0 1 1 0-48z\"/></svg><ul class=\"tna-files-list__items\"><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\">Preservation policy part 1</a></h3><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></li><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\">Preservation policy part 2</a></h3><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></li><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\">Preservation policy part 3</a></h3><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl></li></ul></div>"
+      "html": "<div class=\"tna-files-list\"><svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"tna-files-list__icon\" width=\"24\"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d=\"M288 32c0-17.7-14.3-32-32-32s-32 14.3-32 32V274.7l-73.4-73.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l128 128c12.5 12.5 32.8 12.5 45.3 0l128-128c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L288 274.7V32zM64 352c-35.3 0-64 28.7-64 64v32c0 35.3 28.7 64 64 64H448c35.3 0 64-28.7 64-64V416c0-35.3-28.7-64-64-64H346.5l-45.3 45.3c-25 25-65.5 25-90.5 0L165.5 352H64zm368 56a24 24 0 1 1 0 48 24 24 0 1 1 0-48z\"/></svg><ul class=\"tna-files-list__items\"><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\" aria-describedby=\"file-1\">Preservation policy part 1</a></h3><div class=\"tna-files-list__item-body\" id=\"file-1\"><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></div></li><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\" aria-describedby=\"file-2\">Preservation policy part 2</a></h3><div class=\"tna-files-list__item-body\" id=\"file-2\"><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></div></li><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\" aria-describedby=\"file-3\">Preservation policy part 3</a></h3><div class=\"tna-files-list__item-body\" id=\"file-3\"><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl></div></li></ul></div>"
     },
     {
       "name": "with classes",
       "options": {
         "itemHeadingLevel": 3,
         "items": [
           {
+            "id": "file-1",
             "text": "Preservation policy part 1",
             "href": "#",
             "file_type": "PDF",
@@ -48,14 +52,15 @@
         ],
         "classes": "files__test-class"
       },
-      "html": "<div class=\"tna-files-list files__test-class\"><svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"tna-files-list__icon\" width=\"24\"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d=\"M288 32c0-17.7-14.3-32-32-32s-32 14.3-32 32V274.7l-73.4-73.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l128 128c12.5 12.5 32.8 12.5 45.3 0l128-128c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L288 274.7V32zM64 352c-35.3 0-64 28.7-64 64v32c0 35.3 28.7 64 64 64H448c35.3 0 64-28.7 64-64V416c0-35.3-28.7-64-64-64H346.5l-45.3 45.3c-25 25-65.5 25-90.5 0L165.5 352H64zm368 56a24 24 0 1 1 0 48 24 24 0 1 1 0-48z\"/></svg><ul class=\"tna-files-list__items\"><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\">Preservation policy part 1</a></h3><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></li></ul></div>"
+      "html": "<div class=\"tna-files-list files__test-class\"><svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"tna-files-list__icon\" width=\"24\"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d=\"M288 32c0-17.7-14.3-32-32-32s-32 14.3-32 32V274.7l-73.4-73.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l128 128c12.5 12.5 32.8 12.5 45.3 0l128-128c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L288 274.7V32zM64 352c-35.3 0-64 28.7-64 64v32c0 35.3 28.7 64 64 64H448c35.3 0 64-28.7 64-64V416c0-35.3-28.7-64-64-64H346.5l-45.3 45.3c-25 25-65.5 25-90.5 0L165.5 352H64zm368 56a24 24 0 1 1 0 48 24 24 0 1 1 0-48z\"/></svg><ul class=\"tna-files-list__items\"><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\" aria-describedby=\"file-1\">Preservation policy part 1</a></h3><div class=\"tna-files-list__item-body\" id=\"file-1\"><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></div></li></ul></div>"
     },
     {
       "name": "with attributes",
       "options": {
         "itemHeadingLevel": 3,
         "items": [
           {
+            "id": "file-1",
             "text": "Preservation policy part 1",
             "href": "#",
             "file_type": "PDF",
@@ -68,7 +73,7 @@
           "data-testattribute": "foobar"
         }
       },
-      "html": "<div class=\"tna-files-list\" data-testattribute=\"foobar\"><svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"tna-files-list__icon\" width=\"24\"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d=\"M288 32c0-17.7-14.3-32-32-32s-32 14.3-32 32V274.7l-73.4-73.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l128 128c12.5 12.5 32.8 12.5 45.3 0l128-128c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L288 274.7V32zM64 352c-35.3 0-64 28.7-64 64v32c0 35.3 28.7 64 64 64H448c35.3 0 64-28.7 64-64V416c0-35.3-28.7-64-64-64H346.5l-45.3 45.3c-25 25-65.5 25-90.5 0L165.5 352H64zm368 56a24 24 0 1 1 0 48 24 24 0 1 1 0-48z\"/></svg><ul class=\"tna-files-list__items\"><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\">Preservation policy part 1</a></h3><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></li></ul></div>"
+      "html": "<div class=\"tna-files-list\" data-testattribute=\"foobar\"><svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"tna-files-list__icon\" width=\"24\"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d=\"M288 32c0-17.7-14.3-32-32-32s-32 14.3-32 32V274.7l-73.4-73.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l128 128c12.5 12.5 32.8 12.5 45.3 0l128-128c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L288 274.7V32zM64 352c-35.3 0-64 28.7-64 64v32c0 35.3 28.7 64 64 64H448c35.3 0 64-28.7 64-64V416c0-35.3-28.7-64-64-64H346.5l-45.3 45.3c-25 25-65.5 25-90.5 0L165.5 352H64zm368 56a24 24 0 1 1 0 48 24 24 0 1 1 0-48z\"/></svg><ul class=\"tna-files-list__items\"><li class=\"tna-files-list__item\"><h3 class=\"tna-files-list__item-title tna-heading-s\"><a href=\"#\" class=\"tna-files-list__link\" aria-describedby=\"file-1\">Preservation policy part 1</a></h3><div class=\"tna-files-list__item-body\" id=\"file-1\"><dl class=\"tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta\"><dt>File type</dt><dd><span class=\"tna-dl-chips__item\"></span></dd><dt>File size</dt><dd><span class=\"tna-dl-chips__item\"></span></dd></dl><p class=\"tna-files-list__item-description\">The principles according to which The National Archives will preserve and care for our archival collections.</p></div></li></ul></div>"
     }
   ]
 }
diff --git a/src/nationalarchives/components/files-list/macro-options.json b/src/nationalarchives/components/files-list/macro-options.json
@@ -11,6 +11,12 @@
     "required": true,
     "description": "",
     "params": [
+      {
+        "name": "id",
+        "type": "string",
+        "required": true,
+        "description": ""
+      },
       {
         "name": "title",
         "type": "string",

diff --git a/src/nationalarchives/components/files-list/template.njk b/src/nationalarchives/components/files-list/template.njk
@@ -6,27 +6,29 @@
     {%- for item in params.items %}
     <li class="tna-files-list__item">
       <h{{ params.itemHeadingLevel }} class="tna-files-list__item-title tna-heading-s">
-        <a href="{{ item.href }}" class="tna-files-list__link">{{ item.text }}</a>
+        <a href="{{ item.href }}" class="tna-files-list__link" aria-describedby="{{ item.id }}">{{ item.text }}</a>
       </h{{ params.itemHeadingLevel }}>
-      <dl class="tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta">
-        <dt>File type</dt>
-        <dd>
-          <span class="tna-dl-chips__item">{{ item.fileType }}</span>
-        </dd>
-        <dt>File size</dt>
-        <dd>
-          <span class="tna-dl-chips__item">{{ item.fileSize }}</span>
-        </dd>
-        {%- if item.fileExtent %}
-        <dt>Extent</dt>
-        <dd>
-          <span class="tna-dl-chips__item">{{ item.fileExtent }}</span>
-        </dd>
+      <div class="tna-files-list__item-body" id="{{ item.id }}">
+        <dl class="tna-dl-chips tna-dl-chips--plain tna-files-list__item-meta">
+          <dt>File type</dt>
+          <dd>
+            <span class="tna-dl-chips__item">{{ item.fileType }}</span>
+          </dd>
+          <dt>File size</dt>
+          <dd>
+            <span class="tna-dl-chips__item">{{ item.fileSize }}</span>
+          </dd>
+          {%- if item.fileExtent %}
+          <dt>Extent</dt>
+          <dd>
+            <span class="tna-dl-chips__item">{{ item.fileExtent }}</span>
+          </dd>
+          {%- endif %}
+        </dl>
+        {%- if item.description %}
+        <p class="tna-files-list__item-description">{{ item.description }}</p>
         {%- endif %}
-      </dl>
-      {%- if item.description %}
-      <p class="tna-files-list__item-description">{{ item.description }}</p>
-      {%- endif %}
+      </div>
     </li>
     {%- endfor %}
   </ul>