Initial work towards navigation ADR

Author: matt-bernhardt

docs/architecture-decisions/0005-implement-an-accessible-navigation-system.md

@@ -0,0 +1,141 @@
+# 5. Implement an accessible navigation system
+
+Date: 2024-03-22
+
+## Status
+
+Accepted
+
+## Context
+
+Our initial releases of this theme used the [SmartMenus](https://www.smartmenus.org/) library to build its
+navigation menus. While this library is easy to implement and pretty useful, its
+output was flagged during usability and accessibility testing as needing some
+improvements.
+
+The markup which the user finally interacts with looks like this:
+
+```html
+<nav aria-label="Under the Lens: Women Biologists and Chemists at MIT (1865-2024)">
+  <ul class="navigation sm sm-mint" data-smartmenus-id="17111193231069111">
+    ...
+    <li>
+        <a href="/s/under-the-lens/page/timeline" class="has-submenu" id="sm-17111193231069111-1" aria-haspopup="true" aria-controls="sm-17111193231069111-2" aria-expanded="false">Timeline
+        	<span class="sub-arrow"></span>
+        </a>
+        <ul id="sm-17111193231069111-2" role="group" aria-hidden="true" aria-labelledby="sm-17111193231069111-1" aria-expanded="false" style="width: auto; min-width: 10em; display: none; max-width: 20em; top: auto; left: 0px; margin-left: 0px; margin-top: 0px;" class="sm-nowrap">
+            <li>
+                <a href="/s/under-the-lens/page/timeline1">Timeline: The Beginnings</a>
+            </li>
+            ...
+        </ul>
+    </li>
+    ...
+  </ul>
+</nav>
+```
+
+The issue is that the element triggering the flyout menu (the 
+`<span class="sub-arrow"></span>` tag) is inside the anchor element, making it
+challenging for users of assistive technologies to separate their interactions
+with the menu link and the submenu toggle.
+
+The current release of SmartMenus (1.2.1) does not support placing this toggle
+element outside of the link element, so it will be necessary to replace it with
+a library which does support this behavior.
+
+### Option 1: SmartMenus 2
+
+The maintainer for SmartMenus is aware of this problem in the library, as we and
+others have reported it via GitHub (see [issue 204](https://github.com/vadikom/smartmenus/issues/204) and [issue 231](https://github.com/vadikom/smartmenus/issues/231)). He has
+committed to including this as an improvement in the future release of
+SmartMenus 2, and the documentation already available [includes this among its available
+features](https://configurator.smartmenus.org/).
+
+However, at the time of writing [SmartMenus 2 is only available via one alpha
+release](https://github.com/vadikom/smartmenus/releases) - and the maintainer has [cautioned us against using it in a production
+system yet](https://github.com/vadikom/smartmenus/issues/245).
+
+* Pros: Just upgrading our existing menu library as it improves over time is a
+  good philosophy to follow.
+
+* Cons: The timeline for the release of SmartMenus 2 is not clear, and so
+  cannot be guaranteed to happen. Additionally, the significant changes to the
+  library with version 2 will likely require a significant level of effort - so
+  the benefits of a simple upgrade are not likely to accrue based on the
+  materials published so far.
+
+### Option 2: Accessible Menu
+
+One alternative to SmartMenus is the Accessible Menu library, which takes as its
+starting point the ARIA Authoring Practices Guide for navigation menus. One of
+the supported patterns is the Disclosure Navigation Menu with Top-Level Links,
+which includes the needed separation between navigation links and submenu
+toggles.
+
+While the provided example includes this separation only at the top level of the
+menu, the pattern can be extended to all levels - as demonstrated in this
+CodePen.
+
+#### Benefits of Accessible Menu
+
+This menu, when properly configured, appears to implement all the best practices
+for an accessible navigation menu for web application.
+
+#### Drawbacks
+
+There are several significant drawbacks to using this menu library.
+
+* The most significant drawback is that it imposes some operating costs on users
+  of assistive technology that are not ideal. Our recent accessibility testing
+  included some details about this problem while we discussed this menu issue.
+
+* The markup requirements for this library do not immediately align with the
+  markup generated by Omeka. This is manageable by either maintaining a set of
+  custom navigation templates or by writing some javascript to manipulate the
+  DOM prior to instantiating the menu.
+
+* The library is javascript-only, and is not distributed with any CSS rules.
+  While we can develop and maintain these rules ourselves, it makes this library
+  less of a turnkey solution.
+
+### Option 3: CSS-only menu libraries
+
+A third option would be to pursue a "pure CSS" navigation menu, which can be
+found described in several articles around the web.
+
+* Pros: A navigation menu which uses only CSS styles is technically much
+  simpler, lacking the javascript that would need to be maintained (either by
+  ourselves or by a dependency maintainer).
+
+* Cons: These types of navigation systems are likely not going to be fully
+  accessible. There are elements of the WCAG standards which cannot be satisfied
+  by stylesheets alone. An example is WCAG 1.4.13, which requires that revealed
+  content like a submenu must be dismissable without changing the focus on a
+  page.
+
+### Option 4: A bespoke solution
+
+While attempting to implement the Accessible Menu library, we asked for feedback
+about our progress from Rich Caloggero, who was involved in our earlier
+accessibility testing. Rich helpfully assembled a mockup demonstrating a usable
+navigation system with very little javascript (and no stylesheets).
+
+* Pros: This section needs to be filled out.
+
+* Cons: We will be responsible for maintaining the entirety of this solution,
+  and will need to preserve the bandwidth and skills to fulfill this
+  responsibility.
+
+## Decision
+
+We will develop, and maintain, a small set of javascript and stylesheet rules
+for the navigation menu in this theme.
+
+If this proves sustainable, the feature will be considered for promotion to the
+overall style library in order to make the feature available to our other
+web applications.
+
+## Consequences
+
+This section needs to be filled out.