Redesigned site with modern UI by Sarah-okolo · Pull Request #257 · jsdoc/jsdoc.github.io
This redesign has several accessibility issues:
-
The body text is difficult to read (especially for those with impaired vision or hyperopia). Please consider a larger point-size and/or heavier weight.
-
The new sidebar should appear at the end of the document in source order, as it currently precedes the page's content. This has implications for both screen-readers and text-browsers, which present the contents of the menu first before getting to the material the visitor actually cares about.
This is what the current site and the redesign look like in Lynx (a text-only browser, which is useful for gauging how A11Y-friendly a page's markup is). I strongly encourage you to browse the site yourself in Lynx to get a feel for how usable the site is before and after the UI changes.
Lynx screenshots (click to toggle)
Current site Redesign 

-
Users shouldn't need to manually select dark or light mode; the site's stylesheets should adapt to whichever motif the user's system is set to:
html{ color-scheme: light dark; background-color: light-dark(#fff, #101418); }
The
light-dark()function can drastically simplify your_variables.cssfile, allowing you to do away with the.dark-modeclass and have a single declaration for each colour variable::root{ color-scheme: light dark; --bg-color: light-dark(#f5f8ff, hsl(203, 19%, 13%)); --text-color: light-dark(hsl(207, 24%, 15%), hsl(214, 40%, 92%)); --heading-color: light-dark(hsl(213, 96%, 18%), hsl(216, 63%, 97%)); --heading-line: light-dark(hsl(229, 24%, 87%), hsl(0, 0%, 28%)); --bx-shadow: light-dark(hsl(229, 24%, 87%), hsl(0, 0%, 18%)); --code-bg: light-dark(hsl(214, 40%, 92%), hsl(0, 2%, 9%)); --tomorrow-green: light-dark(#83a303, #97bc02); --nav-link-color: light-dark(hsl(210, 7%, 40%), hsl(214, 12%, 73%)); }
If browser compatibility is a concern, then you can always use media queries instead of
light-dark()andcolor-schemeto have motif-aware styling::root{ /* Light mode variables */ } @media (prefers-color-scheme: dark){ :root{ /* Dark mode variables */ } }
-
JavaScript is required to access the navigation menu on mobile (specifically, the hamburger icon disappears). An accessible, portable website should be usable (or at least navigable) without client-side scripting enabled (albeit without fancier features that require JS but aren't necessary for basic usage).
-
The sidebar menu's sections should be collapsible (possibly by enclosing them in
<details></details>), with the section that contains the current page open by default. For JSDoc's website, I'd make an exception for the sectionsBlock tagsandInline tags, which should always be expanded by default, as those are the sections most returning users will be most interested in (and having them expanded by default facilitates a quick CTRL+F page search).