Design System: Standardize Sticky Side Nav

[Aveline-art]

Dependency

• #2173

Overview

As a developer, it is important to standardize our elements for all teams in the website project. For this issue, the element to standardize is the sticky side nav on the about page.

Action Items

• [ ] Edit the code such that the sticky side nav can stand alone, in the same way that Bootstrap or Solid components can stand alone and is up to current protocol and standards
  • [ ] This code needs to belong in various areas of our architecture based on it's language type.
  • [ ] HTML: _includes/elements
  • [ ] SCSS: _scss/elements
  • [ ] JS: assets/js/elements
• [ ] Suggestion: Create a new folder in _includes called "sticky-side-nav"
  • [ ] Using the current sticky side nav as a reference, create a new .md file named "about-side-nav-elements.md"
    • [ ] This .md file will hold a markdown list of elements that can be used dynamically, so it should have the following elements
      • element: - the name of the element in the list (e.g. Letter from the ED)
      • anchor: - the anchor for this element (e.g. #letter)
  • [ ] Create a reusable "include" html in the _includes folder named "sticky-side-nav.html" for the sticky side nav that can be called within other pages that will have a sticky side nav
    • [ ] This should be able to loop through a given .md file (using Liquid) to render the sticky side nav with the page's appropriate elements
  • [ ] Make appropriate changes/additions to JS and SCSS files as needed to ensure it does not break any functionality or style on any other page
  • [ ] Refactor the about.html to use the new html file you created instead of the current code that renders the side nav
• [ ] Make sure this bug does not happen for this component.
  • [ ] This is a bug resulting from using the scroll click on a mouse to traverse the page.
• [ ] Implement accessibility recommendations from Writeup #2173

Resources/Instructions

• Figma design of about page - sticky sidebar nav should adhere to to this design to satisfy WCAG criteria
• about page
• Bootstrap
• Solid
• Writeup from #2173

[AzaniaBG]

Per yesterday's meeting, I updated this issue with an additional action item: Implement accessibility recommendations from Write up. I also added a link to the write up.

[AzaniaBG]

Update: at the All-Team meeting Sunday, we discussed the new Figma designs Sijia created based on WCAG recommendations set forth in #2173. Bonnie approved one of the options and Sijia put this final design in a pink box. I'm not able to edit the Figma to add this issue number, but I gave it to @sijiapitts, and I believe she will add it.

@Aveline-art, @blulady ~ should we update the about page under resources with the new Figma design?

[Aveline-art]

@AzaniaBG I personally think that's a good idea, but feel free to also consult the team lead on this matter as well.

[blulady]

@AzaniaBG @Aveline-art How could I possibly disagree if both of you agree. Yes, we should update the about page.

[AzaniaBG]

Updated issue with approved Figma design for sticky side bar nav (with note that this design should be followed to satisfy WCAG). Feel free to modify as necessary :)

[luiderek]

Got curious about what was behind the sticky-bug. As far as quick and dirty solutions goes, inside assets/js/about.js:

• changing the event listener of scrollHandler from "wheel" to "scroll"
• replacing the STICKYNAVTOP from a fixed constant to the BoundingClientRect.y of the nav element + 30

Seems to do the trick in making the existing sidebar behave better. Not familiar enough with Jekyll's templating or accessibility to really chime in more beyond this.

[github-actions[bot]]

Hi @luiderek, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[luiderek]

Availability: 1pm - 11pm PDT ETA: 1-2 weeks, depending on blockers I run into.

Still not entirely sure about how to set up components for this project, and how much of the past code could be reused to make it accessibility compliant. Will likely draft a call for help in slack within a few days once I get a better sense of where I'm lacking knowledge.

[luiderek]

Update, (It's been 3 days, but I think I've had decent progress.) https://github.com/luiderek/hfla-website/tree/standardize-sticky-sidenav-2174

1. Progress

Addressed the strange scrollhandler behavior by changing it's listener to scroll from wheel.

Moved / renamed about.js to elements/sticky-nav.js.

Moved some CSS properties from components/_about.scss to elements/_sticky-nav.scss. Logic isn't fully decoupled. The about page kinda has it's own monster 900+ line scss file that seems inconsistent with the other pages.

Created a new file _data/navigation/about-page.yml, and iterated through that to load the page sections / navbar anchor links. It's not really an elegant plug-and-play component, but I wasn't sure how much liberties to take in refactoring the existing code, and it'd be moderately easier to replicate and extend to other pages if needed.

Reworked some of the HTML structure and CSS grid rules to better center the content, rather than have everything a fixed distance from the left.

2. Blockers

Unclear on direction on how to better generalize the sticky-nav. I think there's a lot of hard-coded legacy code and I'm not sure of what an example of a "properly structured" page would be that a sticky-nav could be slipped into. The only things I can see would maybe be the join-us page, or alyssabenipayo's past work in the guides-pages.

3. Availability - 1pm-11pm PDT, weekdays/weekends.
4. ETA - Depends. Right now unclear where to take things.

[luiderek]

Taking a break on this issue until I get a better sense of it's scope / ways to achieve it.

Current blockers:

• about.html's structure is unique to the codebase (importing html sections) and not easily generalizable
• it is unclear if there are other instances that would be using the sticky sidebar component to build the component to accommodate
• there are currently 2 different implementations of the sidebar (see guidespages).

After talking to Justin and Jessica, I currently believe it might be best to rework the existing about.html sections into the markdown used by the guides pages (i think its possible, just going to be fairly ugly), and just consolidating the sidebar logic. Would probably be the equivalent of making several medium issues.

Will try to bring up in Sunday meeting to figure out where to go with it.

[ExperimentsInHonesty]

adding this to the dev/pm agenda and moving to the questions column

[jdingeman]

I think we will want to discuss the structure of the about.html because it seems like it had hindered the progress of this issue. Previous dev stated there is legacy code and it is not clear how to make a standardized sticky nav bar with a page that is really hard coded. Also needed to have an example of how else the side bar would be used, but when I tried checking out the guides page in my local, it is hitting an error and will not render the page even when published: false is erased from the guides.html.

This issue may end up with another dependency depending on our conversation on how the about.html should be restructured.

[jdingeman]

Gonna rewrite the issue to open the scope. To make this component reusable, it would be a good idea to have a folder of files that can be used to make the component reusable, i.e. make a folder of sticky-nav-elements which contains markdown files with lists of the elements and their attributes. That way, the component can ideally just run through that markdown file and work the exact same way as it is currently hard coded.

[ExperimentsInHonesty]

@jdingeman I just read through this issue. I agree that the about page is a monster. Each section of the about page should be an include. Then the cards could have an anchor and an include to render the content. Then either the sticky nav menu reads the anchors or its defined in a file the sticky nav for the about page uses.

[ExperimentsInHonesty]

The next step on this issue is to find all the files associated with the about page, and define what each portion does so that anyone who needs to understand this issue, doesn't have to read all the code from scratch.

• issues that have the label: p-feature: About Us
• wiki pages that have the word about in them