Usability-, accessibility-, and general user interface tweaks

[juhalehtonen]

Perhaps an issue is not the best place to gather these, so please feel free to move elsewhere. I wanted to compile these somewhere so that they can be addressed one way or the other.

Observing the site, I came up with the following list of small items that could possibly be tweaked:

• Get Started -button at the front page: only text is clickable, not the visual button
• Get Started -button at the front page: opens to new tab without any particular reason
• Search Documentation -button is styled to look like a text field but isn't
• Search Documentation -button hints at Mac-only button (cmd) for non-Mac OSes
• Mailing list join button / form submit gives no visual feedback when form cannot be submitted (nothing happens)
• "Example code windows" accordion toggle icon: clickable area too small
  • Ideally a clickable area should be at least 44 x 44 pixels. I think we could make the whole "tool bar" area clickable, sidestepping the icon issue entirely
• "Example code windows" accordion titles are not headings
  • Using heading elements would improve navigation possibilities and probably have some impact on SEO
• Search modal: labels on checkboxes are not clickable
  • Clicking on a label should (de)activate that labels' checkbox
• "Including packages": clickable area on remove package -icon too small
  • Same 44 x 44 pixels issue here. Probably no space to make it this big, but a size-improvement would still be helpful in removing the need for a very fine pointer to hit the target.
• Docs sidebar: Placed in the markup before the content is. Causes CTRL/CMD+F in-page searches to be very cumbersome, as user needs to first pass all the results in the navigation
• Docs sidebar: "Including packages" allows removing Ash core from selection, but still shows contents on sidebar
  • More specifically, the function reference remains but the guides do not
• Docs sidebar: "Including packages" allows changing Ash core version, but still shows contents from initial load
  • More specifically, having 2.0.0RC12 loaded means that all links lead to 2.0.0RC12 content, despite choosing a different version of Ash
• Package version indicator: absolute position floats above headings/content in certain screen size + content combinations
  • Happens on desktop too if the top heading is long enough
• Right-hand function list: clicks on anchors have a visual jerk
  • More specifically, there's some kind of animated nudge when a link is clicked
• Function documentation: There is some kind of "snap to element" behavior that makes scrolling with a mouse extremely jerky and difficult. Relates to above point about Right-hand function list.
  • In general we probably should avoid touching native scrolling at all.
• Docs content area: narrow area for scrolling, makes scrolling page unnecessarily difficult as scrolling has to happen within the narrow content container instead of anywhere on the page
• Mobile UI: hamburger icon on left side harder to use for larger part of the population
  • Most people are right-handed, so when using mobile phones they tend to hold it on their right hand when using one-handed. This leaves their thumb at the absolute opposite side from the menu button.
• Mobile UI: hamburger icon doesn't show state
  • The icon could update to show whether it is active or not, making understanding the system's state easier
• Mobile UI: floating menu doesn't close when loading new content
  • My assumption is that most users would prefer to read the content as the next thing after choosing an item from the menu
• Mobile UI: Scroll position doesn't reset to the top when navigating to a new section.

[juhalehtonen]

Added three more UI tweaks to the list:

1. Docs content area: narrow area for scrolling, makes scrolling page unnecessarily difficult as scrolling has to happen within the narrow content container instead of anywhere on the page
2. Docs sidebar: Placed in the markup before the content is. Causes CTRL/CMD+F in-page searches to be very cumbersome, as user needs to first pass all the results in the navigation
3. Get Started -button at the front page: opens to new tab without any particular reason

[zachdaniel]

For button styled to look like a text field, that was inspired by how they do it on tailwindcss, will probably keep it that way.

[zachdaniel]

As for removing the ash core package, it should still display as present, interestingly, because whenever you're viewing a guide from a specific package (i.e if you were linked there) we include it in the selected packages (temporarily, i.e if you leave the sidebar would change). Its kind of a weird system though.

[zachallaun]

I'd like to add a few things that I noticed in the same vein as those that @juhalehtonen suggested. If preferable, I'd be happy to create a new issue for this, but it seems like this issue could perhaps just become a catch-all for these sorts of minor UI enhancements/tweaks.

1. Mobile UI: Scroll position doesn't reset to the top when navigating to a new section.
2. Function documentation: There is some kind of "snap to element" behavior that makes scrolling with a mouse (haven't tried with trackpad) extremely jerky and difficult. In general, I think that scroll behavior should be left alone except in rare circumstances.

I'd also like to add a 👍 to "Mobile UI: floating menu doesn't close when loading new content" -- it was on my list as well.

[zachdaniel]

Addressed a fair amount of these. Realistically I've addressed all of them that I personally will (or checked them off because they are working as intended), but others are more than welcome to take the remaining items :D

[juhalehtonen]

Thanks @zachallaun for pointing these ones out. I've added your points to the description of the issue to help keep them from being forgotten.

For future reference, one sample page where the scroll-hijacking is very visible is https://ash-hq.org/docs/module/ash/2.2.0/ash-resource-info .

[juhalehtonen]

I whipped up a quick-and-ugly CSS demo on how we could address the two points of:

• Docs sidebar: Placed in the markup before the content is. Causes CTRL/CMD+F in-page searches to be very cumbersome, as user needs to first pass all the results in the navigation
• Docs content area: narrow area for scrolling, makes scrolling page unnecessarily difficult as scrolling has to happen within the narrow content container instead of anywhere on the page

Essentially the main points here are the order properties (to ensure in-page search finds content first) and avoiding any overflow-hiding techniques, allowing the body to pass the browser scrolling to the main content.

Not quite sure how to apply these ideas to the existing Tailwind classes though, so perhaps someone more well versed with that framework can figure that one out 🙂