Bug: lesson side navigation a11y issues

[thatblindgeye]

Checks

• I have thoroughly read and understand The Odin Project Contributing Guide
• The title of this issue follows the Bug: brief description of bug format, e.g. Bug: Lesson complete button does not update on click
• Would you like to work on this issue?

Bug description

Various a11y issues that should be resolved for the lesson side navigation (this can be considered an epic consisting of several issues; each of these issues should have a separate PR):

• Side navigation not visible at smaller viewports - Basically the lesson side navigation is not visible when zoom is higher or viewport is smaller, which is an issue that needs to be resolved. Ideally the navigation should be collapsible/expandable regardless of viewport/zoom, rather than just completely hiding it at a certain point. This may involve updating the h4 heading

• Related to above, we should move the lesson jump links from the right side of the screen (in LTR languages) to the left in the DOM. This would satisfy being able to traverse those jump links before the actual lesson content (right now you basically have to go through the entire lesson just to get focus into those jump links, unless you're using some AT that has nifty shortcuts that can help alleviate that)

• Reconsider wrapper element for the lesson nav from an aside to a nav. While an aside may make sense in terms of positioning, it really is more of a navigation. Doing this we could also remove the h4 tag as it's no longer really a section of content; we should keep the text, though, and this text should be used as the labeling text for the nav/ul via aria-labelledby

• Apply aria-current="location" to the li element that contains the link which is currently "active". May also want to consider applying a more noticeable style to the current jump link rather than just a slight background/text color change, like removing the left border from all li's except the active one (screenshot below)
  

• Apply a role="list" to the nav ul element. It's redundant, but Safari removes the semantics for lists that remove the list styling. This would apply to other areas of the site that uses lists in this way as well. We should also apply an aria-labelledby to this ul element, referencing the "Lesson contents" heading.

How to reproduce

Visit any lesson (like our working with text lesson) and compare the above comments to the side navigation. Some may not be reproducible without a screen reader (aria-current for example).

Expected behavior

1. The side nav is able to be viewed regardless of zoom/viewport width
2. The side navigation is announced semantically as a navigation element as it contains links for the lesson itself (rather than external links)
3. The side nav and/or ul elements are labeled by the "Lesson content" text
4. The currently active jump link is announced as the current link via aria-current, and has improved active styling
5. The ul element retains its semantics via role="list" for Safari, which removes the semantics when certain styles are applied to the ul

What browsers are you seeing the problem on?

No response

What OS are you using?

No response

Discord Name

No response

Additional Comments

cc @KevinMulhern in case some of these issues need some design input, may be worth getting together async to chat about them

May also be coupled to #4407 and/or #3498

[KevinMulhern]

Thanks for the great write up @thatblindgeye 💪

I've noticed it switches to the mobile layout when zoomed to that level - the lesson content centers and the side nav is hidden. There likely won't be enough space beside the lesson content to show the side nav on that viewport. Repositioning above the lesson content may be an option though?

But, it might also be ok to keep hiding it on smaller view ports. There was a discussion a while back where some users indicated they thought the side nav was a "nice to have". We haven't got any feedback about users missing it on mobile which validates that to a degree.

Is it important to always have the lesson table of contents on all viewports for a11y purposes? if it is, its definitely worth the effort.

[thatblindgeye]

So my rationale is that if it's something we're providing at X viewport/zoom level, it's something we should provide at all viewport/zoom levels. I'd agree that a repositioning would be the best approach (though we'd also need to be sure to make it sticky so that it's always within view to interact with). Repositioning may actually be best in general, i.e. not just at X viewport/zoom level, which can be better explained when I get into keyboard navigation below.

I think the side nav is a little more than just "nice to have", more so in lessons that have more sections to parse. It's a quicker way to jump to a specific section than just scrolling or using the browser search to get to that section, as well as get an idea of the structure/contents of the page (kinda similar to how AT may be able to view all the headings on a page to garner similar info).

In terms of a11y, there's two examples to view it from. For someone like me, I typically need any site I visit to be zoomed at at least 125% so that the text is large enough to read (not just TOP, just basically any site I visit). Currently it basically becomes choosing between readable text or navigation within a lesson. Another scenario is mobile viewing, where it can be even more tedious to scroll through a lesson that has a lot of content just to get to a specific part.

Another PoV would actually be keyboard navigation (which I may need to make an edit to my original post now that I think about it). If I'm navigating via keyboard, there's potentially a lot of content I need to tab through in order to get to a specific section. The lesson navigation alleviates that a lot, though we also need to move the lesson navigation to be before the lesson content within the DOM (currently you'd have to tab through the entire lesson content just to get to the lesson nav)

I'd argue that there being no feedback about a lack of side nav on mobile isn't necessarily validation. It could be, but it could also as likely be that people don't know that a side nav even exists depending on their setup (I think I may have been shocked that there even was one 😆 ) , or they don't know where/how to bring it up.

[KevinMulhern]

Everything except the lesson content is a nice to have in my book 😆

Putting it before the content on smaller viewports seems to be the most practical way to go about it, and a fairly popular UI pattern.

Web.dev

Rails Guides

Educative do something a bit more interesting, they incorporate it into the lesson content itself, its kind of like what we have with our "what you'll learn in this lesson" list:

I'd push back on sticky being a hard requirement for this. The only way I think we'd be able to pull that off is with a select box - it'll likely be too distracting on smaller viewports. But, I'd be open to it if we can find a nice way of doing it. Do you know of any sites that have sticky TOC navs we could look at?

[mao-sz]

Resurrecting this:

Repositioning the TOC to be before the lesson contents sounds great.
Regarding the sticky/no-sticky, how about a non-sticky TOC but a "scroll to top" button appearing when the TOC is outside the viewport? Only renders for the "mobile" layout, that is - the TOC is always visible in desktop layout so it doesn't need it of course.

Alternatively, a stick expandable "On this page" containing the ToC in narrower viewports. An example is in Zod's docs.

Also a 👍 from me regarding the TOC highlighting. I genuinely wasn't aware the highlighted heading had more than just the shaded background. I didn't notice the yellow left border and agree it'll be more noticeable if the other headings have their left borders removed as pictured.

(also really confused at the Safari ul[role="list"] thing. Discovered that during a personal project and it's one hell of a mind boggler)

[Angel-Mathew007]

Hi @thatblindgeye, @KevinMulhern, and team, I’ve gone through the contributing guide and reviewed the discussion here—really appreciate the detailed breakdown of the accessibility concerns and potential solutions. I’d love to help out with this issue, starting with repositioning the lesson TOC before the content in the DOM and implementing aria-current="location" for active links.

I can also explore the role="list" workaround for Safari and test the visibility behavior across zoom levels and mobile viewports. If it’s helpful, I can break this into smaller PRs as suggested.

Let me know if you'd like me to proceed or if there's a preferred starting point. Excited to contribute!

[thatblindgeye]

Sorry @Angel-Mathew007 , I've been a bit out of the TOP game for a while and trying to see if I can slowly get back to it.

I would just want to ping @mao-sz and @KevinMulhern if they'd mind circling back on this and see if their thoughts have changed or anything. I did just edit my initial post to add a couple more points in, namely:

• Moving the "Lesson content" navigation from the right side of the screen to the left (I tinkered around i dev tools and this should be possible without breaking anything, but would need a better look inside the TOP app ran locally). This would satisfy the issue of not being able to traverse those jump links until after the entire lesson content.
• Added a mention of adding aria-labelledby to the ul used for these jump links, which should reference an ID placed on the "Lesson content" text.

[mao-sz]

Thanks @thatblindgeye

Regarding the ToC location, what about keeping it on the right for wide viewport by having the container be a flex row-reverse? That should still allow the ToC to come first in the DOM tree for navigation. Personally I prefer the ToC on the right since that's what I tend to see in more sites than on the left (though that's often because the left contains a fixed sidebar), and it'd be a less dramatic change for most TOP users.

Regarding narrow viewport, I'm in favour of replacing the ToC with a sticky "On this page" dropdown containing the ToC, like with many docs. That seems like the least visually intrusive way to keep a ToC reachable at all times with a narrow viewport but without forcing the user to change their location just to view it (which a scroll-to-top button would be limited by).

I definitely agree with the highlighted ToC item styling changes suggested, as well as any appropriate ARIA changes.

[thatblindgeye]

Regarding the ToC location, what about keeping it on the right for wide viewport by having the container be a flex row-reverse? That should still allow the ToC to come first in the DOM tree for navigation.

There'd be caveats to consider with that approach. Visually the flow might conflict with the tab order in that case (stuff on the right/horizontal end getting focus before stuff on the left/horizontal start). Taking a random lesson page:

To me, the assumption would be focus would go to the "an official flavor of Ubuntu" before the ToC on the right. Though the ToC, visually, might look like it'd come first since it sorta is vertically higher on the page is an argument that could be made, and what the expected tab order can be subjective depending on the context.

since that's what I tend to see in more sites than on the left (though that's often because the left contains a fixed sidebar), and it'd be a less dramatic change for most TOP users.

The page ToC being on the right might be a necessary "evil" with pages like that yeah. MDN does something interesting where the tab order goes through the intro/description paragraph at the top, then goes into the ToC on the right, before bringing focus back to the main flow of the page - see the MDN box-shadow docs.

Keeping the page ToC on the right might be fine if we ever expect the left side to be populated with anything else. That's difficult to really know, though, and at the same time I'm not sure if such a change should be avoided on the potential of a possibility. Personally I think the ToC being on the left would be the better choice, with maybe something like what MDN does being a possible second option. Completely moving the ToC might be temporarily dramatic a change, I wouldn't say that outweighs the benefit of moving it.

[mao-sz]

The MDN way is interesting though would of course require a restructure of the appropriate views. Feels a bit odd that you wouldn't be able to use <article> to capture the entire lesson contents and just need <section>s in separate divs.

Looking at some other sites with similar nav layouts like Zod docs, they just shove the intra-page ToC below the page contents in the hierarchy, so you'd have to tab through the doc to get to the ToC if you're not navigating by other means.

Express docs just have the whole ToC higher than <main> so you tab through it before going to <main>.

Keeping the page ToC on the right might be fine if we ever expect the left side to be populated with anything else. That's difficult to really know, though, and at the same time I'm not sure if such a change should be avoided on the potential of a possibility.

The left-side space in the TOP lesson page could be used for a course ToC which fits what many sites like MDN and various docs do, and would also address the longstanding common "previous lesson" button request/complaint. And would also help justify the recent content centring, since the page looks a little right-weighted for the time being.

[thatblindgeye]

The left-side space in the TOP lesson page could be used for a course ToC which fits what many sites like MDN and various docs do, and would also address the longstanding common "previous lesson" button request/complaint. And would also help justify the recent content centring, since the page looks a little right-weighted for the time being.

So the left side would allow quick navigation to other lessons in the course, and the right would be for the current lesson ToC? If so that definitely sounds nice in terms of being able to quickly get between course lessons faster. Though at that point I imagine tinkering with tab orders while keeping things visually the same would possibly become even more problematic.

Ideally the order should be [soon to be course Toc] > current lesson ToC > current lesson content, with some wiggle room with an MDN like approach where the TOC is between the intro section and main content of the lesson.

It all definitely gets complicated with all that alone, nevermind also having to deal with keeping the ToC navs on mobile views (which a course ToC would most likely also require a similar dropdown approach at those views). There's various ideas that could be gone with, but there's going to be caveats one way or another. That portion doesn't have to be solved this minute, there's still some decent work that can be tackled as part of this issue (the sticky dropdown at narrow viewports, the "current" section styling in the ToC, etc)

[mao-sz]

Is the course ToC important to be before the other elements? Just looking at MDN and how it goes intro > intra-page ToC > rest of page > inter-page ToC.

As for dealing with narrow viewports, could have a sticky navbar up top with the left side expanding the course ToC and the right side expanding the lesson ToC. Or two sticky navbars up top, upper one pointing to the leftside for expandable course ToC, and lower one pointing to the right side for expandable lesson ToC.

Another alternative could be only having a left-side ToC which combines a course and lesson ToC in one.

Just throwing ideas around but perhaps that could cover all our bases, make it easier to deal with nav hierarchy, and only require a single sticky navbar and expandable for narrow viewports. The other lessons in the course ToC won't be expandable to show quick header navigation (since the ToC is generated upon accessing the page) but they don't need to be.