New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/tools/cmd/godoc: improve accessibility #22171

Open
jimmyfrasche opened this Issue Oct 6, 2017 · 23 comments

Comments

Projects
None yet
10 participants
@jimmyfrasche
Member

jimmyfrasche commented Oct 6, 2017

This is a meta issue for improving the accessibility of godoc.

  • need hover/focus styles for buttons and button-like links (easy, but requires design)
  • insufficient contrast on date stamp for blog entries (easy)
  • malformed definition lists (easy)
  • embedded playground buttons not in focus order (easy)
  • Mobile menu needs better keyboard and screen reader support (moderate)
  • missing lang on html tag (difficult)
  • UI exposed by -analysis=pointer,type inaccessible by keyboard and screen reader (very difficult)
  • expanding/collapsing section inaccessible by keyboard (difficult, in progress)
  • expanding/collapsing sections announce state glyph but not state (difficult, in progress)
  • insufficient contrast on default focus ring for top level menu
  • links can only be identified by color https://golang.org/cl/69150
  • missing label and submit button on search form https://golang.org/cl/69190
  • insufficient contrast for placeholder text in search form https://golang.org/cl/69190
  • permalinks are insufficiently labeled https://golang.org/cl/69210
  • images without alt attribute https://golang.org/cl/69130
  • package docs skips heading level 3 https://golang.org/cl/69171

If you discover an issue not in the above list, please report it here so that it can be addressed.

If you want to help out and aren't sure where to start or just want to make sure that tools you create are as accessible possible, see (or update!) WebAccessibilityResourcesAndTips on the wiki.

@gopherbot

This comment has been minimized.

gopherbot commented Oct 7, 2017

Change https://golang.org/cl/69130 mentions this issue: godoc: add alt attr to gopher on main package index

@gopherbot

This comment has been minimized.

gopherbot commented Oct 7, 2017

Change https://golang.org/cl/69150 mentions this issue: godoc: better distinguish links and link state

gopherbot pushed a commit to golang/tools that referenced this issue Oct 7, 2017

godoc: add alt attr to gopher on main package index
The gopher with a miner hat on /pkg had no alt attribute
so screen readers would announce the image by its filename.
As the image is purely decorative, adding the empty string
as alternative text prevents the image from being announced.

For golang/go#22171

Change-Id: Ib214f296d3d9f9084c44d4e33d1cbe432f2183ed
Reviewed-on: https://go-review.googlesource.com/69130
Reviewed-by: Ian Lance Taylor <iant@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Oct 8, 2017

Change https://golang.org/cl/69190 mentions this issue: godoc: add label and button to search bar

@gopherbot

This comment has been minimized.

gopherbot commented Oct 8, 2017

Change https://golang.org/cl/69210 mentions this issue: godoc: accessible permalinks

@gopherbot

This comment has been minimized.

gopherbot commented Oct 9, 2017

Change https://golang.org/cl/69171 mentions this issue: godoc: avoid skipping heading level in package docs

gopherbot pushed a commit to golang/tools that referenced this issue Oct 9, 2017

godoc: avoid skipping heading level in package docs
The heading of the #pkg-index section of package documentation pages
uses an h2 heading but its 'Examples' and 'Package files' subsections
use h4 headings, skipping the h3 level.

This change switches the h4s to h3s and adds styling to preserve the
current font-size with the new heading level.

For golang/go#22171

Change-Id: Ifd2cacab22c1e82fd6f061b9322523fa5859a80f
Reviewed-on: https://go-review.googlesource.com/69171
Reviewed-by: jimmy frasche <soapboxcicero@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Oct 9, 2017

I created a wiki page for anyone who wants to help out or to make sure that tools they create are as accessible as possible: https://github.com/golang/go/wiki/WebAccessibilityResourcesAndTips

gopherbot pushed a commit to golang/tools that referenced this issue Oct 12, 2017

godoc: accessible permalinks
This CL makes permalinks accessible to keyboard-users and screen
readers.

Adding an aria-label to permalinks overrides the default content
of "pilcrow".

As the permalinks only showed on hover they were inaccessible
to users who could only use a keyboard and are now always shown.

For golang/go#22171

Change-Id: I6ce3828dfedfd7edc29dd16f3eb94a0abcabfc7c
Reviewed-on: https://go-review.googlesource.com/69210
Reviewed-by: Andrew Bonventre <andybons@golang.org>

gopherbot pushed a commit to golang/tools that referenced this issue Oct 13, 2017

godoc: add label and button to search bar
To increase accessibility of the search bar,
an aria-label for screen readers and a submit
button was added.

The search field was given the semantically correct
input type and marked required field as hints to UAs
that can use that to provide context to the user.

The placeholder text was restyled for improved contrast.
The javascript for handling placeholders was removed
as it is no longer necessary.

For golang/go#22171

Change-Id: I8db6428bb727a09e7f175e77100b4bcf9b6a5f3e
Reviewed-on: https://go-review.googlesource.com/69190
Reviewed-by: Andrew Bonventre <andybons@golang.org>

gopherbot pushed a commit to golang/tools that referenced this issue Oct 13, 2017

godoc: better distinguish links and link state
There were two issues with links in godoc:

1) They were only distinguished from ordinary text only by color,
affecting those with color-vision deficiencies.

2) The same blue used for links is used by non-links,
affecting everybody.

This change adds a an underline to all links.

Usually, it is safe to skip underlining in locations where it clear
that the only contents are navigational links, such as #pkg-index.
However, (2) prevented this.

To work around this I used some less well supported CSS techniques:
http://caniuse.com/#feat=text-decoration

Less capable browsers, which are unlikely to be used by developers, may
have a less than optimal experience, unfortunately. In more capable
browsers, including those without full support, the experience is quite
pleasant and the additional underlying does not interfere with the godoc
aesthetic.

For golang/go#22171

Change-Id: I5a0d817793e8aa31912ba065b4e5a63d4a3f138c
Reviewed-on: https://go-review.googlesource.com/69150
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@bontibon

This comment has been minimized.

Contributor

bontibon commented Oct 13, 2017

@jimmyfrasche IMO the underline effects in CL 69150 makes the docs look messy, especially in the package table of contents. I'm curious if anyone else feels that way.

screenshot_2017-10-13_19-09-22

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Oct 13, 2017

@bontibon The purpose is to distinguish between clickable and not clickable elements. That means having to distinguishing them by both shape and color. This helps users who have trouble seeing certain colors, a monochrome display, and new users who haven't acclimated to the fact that you can click "func Count(s, substr string) int" but not "Package strings" despite them both being the same blue.

@dsnet

This comment has been minimized.

Member

dsnet commented Oct 17, 2017

I find the underlines fairly hard to read. Perhaps we should keep the underline, but make it an opacity of 30% or something.

@griesemer

This comment has been minimized.

Contributor

griesemer commented Oct 17, 2017

cc: @rsc

I strongly agree with @bontibon: This new look is quite ugly in my mind. When we started on godoc, we made the deliberate decision to not have the underlines. Also, all the section titles now have a paragraph symbol at the end (see e.g. https://tip.golang.org/doc/). Overall, the graphic quality of golang.org has deteriorated significantly here.

I am all for accessibility, but surely the answer is not to make golang.org less accessible for the majority of people. I'm taking part of the blame here since I gave the go-ahead signal but then didn't really look at the changes.

Going forward, I suggest:

  • Significant visual changes to godoc really need some vetting before they are committed. There's a lot of fine-tuning that went into godoc in the first place; let's not undermine that work.

  • Let's revert the underbar change. It's really bad, graphically (also no faint underbars please).

  • Instead, make it possible to enable underbars if desired. Perhaps there's a link to a web-page version with accessibility features enabled. I suspect it may require as little as a different .css.

In summary, let's provide accessibility without compromising the vast majority of users.

Thanks.

@paranoiacblack

This comment has been minimized.

Contributor

paranoiacblack commented Oct 17, 2017

I'd like to note that as a colorblind person with mild deutranopia and tritanopia, I find this much harder to read overall, despite the anchor tags standing out. In general, I'm not really a fan of using text-decoration as a color blindness accessibility signal. If you really want to use text-decoration, though, it'd probably be better to settle on subtle dotted lines with a clear line-height between the anchor tag and the underlined text.

Are there any other approaches being considered here? If the goal is to distinguish links by not only color alone, a different font (like a fixed width font that stands out on a coding page) might be better suited.

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Oct 18, 2017

I'm going to respond out of order but try to hit everything. Please let me know if I missed anything.

In the future, I will post in this thread with screenshots whenever I make a CL that changes visuals in any way so everyone knows that something unhappy is afoot. Other than these and a small contrast tweak here or there, there should only be one other as far as I can tell, though: visible hover/focus states for buttons and button-themed links. Regardless, I'll look forward to more thorough reviews.

@griesemer The ever-present pilcrows (¶) are because if they're not always there's never a way to get to them to without using a mouse. In the first patch set, they were pushed further to the right and de-emphasized to counteract them always being visible. Even if that had made it, it looks like it wouldn't have meshed well with underlines and would require its own formatting. But for that matter they don't work with the toggled sections either. Maybe that feature needs more of a holistic re-think—that was certainly the minimal patch.

we made the deliberate decision to not have the underlines

I don't have any vision or motor deficiencies that would make a lack of underlines on links troublesome for me. Generally, I think no underlines looks better, but there are more considerations to balance than just aesthetics.

I'm not a fan of how it works on godoc. The headers and links being the same color, especially when all or part of a header is a link, means I have to guess whether something might be clickable and check by hovering over the link.

I've been using Go a long time and by now I've roughly memorized everything that is and is not a link so it only shows up as sometimes clicking a header and realizing that it's not a link. It's as small as an inconvenience can get, but it's still irksome when run across.

If I did have a motor deficiency and were new to Go, it could take actual effort and strain to position the mouse to check (which I would have to do until the keyboard accessibility is 100%). If I had total color blindness on top of that, I'd have to do that for every word in every page. It would not be a welcoming experience to the language.

surely the answer is not to make golang.org less accessible for the majority of people

I agree that the change that ended up being pushed is less than ideal. I think that the readability could be improved (see below) without as great an aesthetic impact.

Instead, make it possible to enable underbars if desired. Perhaps there's a link to a web-page version with accessibility features enabled. I suspect it may require as little as a different .css.

A css file with for the visual issues would be quite small. The mechanism to enable that stylesheet would likely not be as small. And such a mechanism would of course itself have to be both accessible and easily discoverable or it would be of little use to those who need it. Like with any configuration option, it would require changes to be tested both with the accessible stylesheet enabled and disabled, except few will, so when there are any changes that need additional handling in the accessible stylesheet it will tend to lag behind the main stylesheet.

A style that is readable and acceptable to everyone would be simpler and better for everyone.

@dsnet The original CL for the underlines in fact had the underline color at 50% opacity to counteract the harsher interactions, particularly with the pkg-index:

half-transparent

Here's a variant with the text color at .3 opacity:
black-variant

Here's a dotted line as @paranoiacblack suggests. It may work better in conjunction with one of the above, this one is just the same color as the link:
dotted

Unfortunately the only way to adjust the underline's position to the text is to fake it with it a border or box-shadow. That has a lot of edge cases and requires a bit of code to cover everything, but here's a very rough sketch using border. It does have its virtues and might work better with a transparent border and it would need some more spacing, as noted:
border

Just to round out the options in case it gives anyone ideas, another tact is to attach an icon of some sort as a signifier, akin to the ▹/▾ used for collapsible sections:
icons

I'm not a designer by any means so if anyone has better ideas I'd love to hear them.

@dsnet

This comment has been minimized.

Member

dsnet commented Oct 18, 2017

The ever-present pilcrows (¶) are because if they're not always there's never a way to get to them to without using a mouse.

If that's the rationale, we should use CSS and/or JS to detect mobile and display it permanently only in that situation. Given that Go is mostly developed on desktops or laptops with full browsers, it seems sensible to prioritize making sure things looks nice on that platform first.

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Oct 18, 2017

@dsnet it has nothing to do with touch (though that benefits as well) it's about people who can't use a mouse or find it difficult and all of the devices to aid accessibility that work by synthetic keyevent.

@griesemer

This comment has been minimized.

Contributor

griesemer commented Oct 18, 2017

Again, I am all for accessibility but we should do it right and not compromise one experience for a slightly improved experience for others. The result will not be satisfying for anybody.

A css file with for the visual issues would be quite small. The mechanism to enable that stylesheet would likely not be as small. And such a mechanism would of course itself have to be both accessible and easily discoverable or it would be of little use to those who need it.

I don't see why this mechanism is complicated. We serve the html which is generated via templates. It can't be too hard to replace the .css reference to a different one; perhaps based on a cookie.

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Oct 18, 2017

Sorry if I was unclear. I meant not just the mechanism to include the alternate stylesheet, but the mechanism in the user interface of the site allowing one to enable the alternate stylesheet.

There are probably other configuration options that would eventually get exposed: maybe being able to set the default GOOS/GOARCH in addition to a per-package UI, as requested in #22178 . Not very useful when running a local godoc but I'm sure it could be handy for someone using tip.golang.org. Since it's a general settings page, it would probably suffice to have a gear icon in the navigation bar that goes to the settings page.

If it turns into a grab bag, it won't be immediately apparent that you need to go there to turn on visual accessibility settings—few sites offer such choices, even in config so it's not something one learns to expect. It would be discoverable though and certainly better than nothing.

If it stays focused on accessibility settings, a generic gear icon wouldn't be wrong but it would be sort of deceiving—everyone would click it to see what fun config parameters can be messed with. To make it clear that it is solely for accessibility settings, it should be so labeled. But having something named "accessibility settings" would take up quite a bit of real estate in the navigation menu, so it's going to get pushed down somewhere else. The label would be more appropriate but the overall discoverability would be worse since it would itself be harder to find. One compromise would be to put in the navigation bar but slightly out of the way:
link in nav bar

Another compromise would be to more selective about where to include visual indication and by having an appropriate variety of stylings based on context. Things like the package index could be considered sufficiently self-evidently navigation to be exempted. Links in headers could have their own appropriate style and links in general text areas another.

@andybons

This comment has been minimized.

Member

andybons commented Oct 24, 2017

We are looking to roll master to golang.org, so I’m going to revert the changes to the underlines and permalinks since those seem the most contentious.

@jimmyfrasche please don’t interpret this as being unappreciative or dismissive of the work you’re doing, because we are very happy you’re doing it and this is very important work. Feel free to open another set of CLs (revert the reverts if you like) so that we can better discuss the design decisions with the relevant people.

gopherbot pushed a commit to golang/tools that referenced this issue Oct 24, 2017

Revert "godoc: accessible permalinks"
This reverts commit f57adc1.

Reason for revert: See golang/go#22171 (comment) for reasoning.

Change-Id: Ifd81ad716cf2acdf7a1d73602ac781186aca5596
Reviewed-on: https://go-review.googlesource.com/73150
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Oct 24, 2017

Change https://golang.org/cl/73151 mentions this issue: Revert "godoc: better distinguish links and link state"

gopherbot pushed a commit to golang/tools that referenced this issue Oct 24, 2017

Revert "godoc: better distinguish links and link state"
This reverts commit 9bd2f44.

Reason for revert: golang/go#22171 (comment)

Update golang/go#22171

Change-Id: I41da526912b3484721782e0dad02d97ab2845a12
Reviewed-on: https://go-review.googlesource.com/73151
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@agnivade

This comment has been minimized.

Member

agnivade commented Feb 2, 2018

I just ran a google lighthouse test on the godoc page and we have a 97% score on accessibility.

  • Page specifies valid language
    <html> element does not have a [lang] attribute.
  • Elements use attributes correctly
  • ARIA attributes follow best practices
  • Elements have discernible names
  • Elements describe contents well
  • Color contrast is satisfactory
  • Elements are well structured
  • Page specifies valid language
  • Meta tags used properly.

I believe setting the lang attribute to "en" should fix it according to this site https://dequeuniversity.com/rules/axe/2.2/html-lang-valid. @jimmyfrasche - Any reason you have set the missing lang on html tag (difficult) item to difficult level ?

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Feb 2, 2018

Lighthouse is the least useful a11y analyzer I've ever seen. I would recommend only using it if you need to triage major issues on an extremely inaccessible site, since that seems to be all it is concerned with.

The SiteImprove chrome extension is the best one I've found (though it sometimes nags about signing up for their newsletter or somesuch, but that can be skipped).

Even so, these are all static analyzers and, as such, while quite helpful, they have occasional false positives and many false negatives. Also, the criteria they're evaluating (WCAG) are necessarily a bit vague. The real test is if you can use the site exactly as well regardless of assistive technology or any temporary or permanent loss of ability.

That is obviously quite hard to evaluate. In practice a good proxy for this is to:

  • ensure everything is denoted by both shape and color and that all colors contrast one another sufficiently
  • ensure the semantics of the produced documents are correct since they need to be machine-readable
  • ensure that the site is entirely usable by keyboard as most assistive technologies simulate key presses
  • ensure all content is can be accessed by a screen reader (most of this is covered by the last two items)

It can be quite hard to get all of those 100% so the goal is to get them as close as is possible within reason.

I marked the lang tag as hard because while the language of the document itself is en, the language of a given's documentation need not be.

@agnivade

This comment has been minimized.

Member

agnivade commented Feb 2, 2018

Thanks. But isn't the lang attribute supposed to contain the language of the document ? Or are you saying that there are translations of godoc, in which case the lang attribute needs to be dynamically set or sth ?

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented Feb 2, 2018

Godoc can display arbitrary user packages. The site will be in en but the documentation for a given package might be de or ja or anything else. I am unsure if there would be side effects from not also marking those correctly. To even attempt to mark them correctly would require some kind of program to analyze the docs and guess the language or an out of band way to specify the BCP 47 tag of a package.

@agnivade

This comment has been minimized.

Member

agnivade commented Feb 2, 2018

Got it. Thanks for the clarification.

@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Mar 29, 2018

@agnivade agnivade changed the title from godoc: improve accessibility to x/tools/cmd/godoc: improve accessibility May 30, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment