Proposal: Accessibility guidelines

Development
#1

Good morning!

I’ve been spending a bit of time lately to write a first draft of an Accessibility guideline document for the XWiki community.

Here is the first draft on a design page.

The goals of this guideline are multiple:

  • Show that the XWiki community cares about accessibility and makes efforts towards a better user experience whatever the means used to navigate XWiki.
  • Inform and educate the community about the key considerations to create an accessible tool.
  • Provide concise rules for designers and developers of our community to achieve a basic level of accessibility
  • Ensure some consistency in our level of accessibility through time.

What this guideline is not:

  • A set of precise rules with a clear definition of what to do:
    • Official standard documentation (HTML, ARIA, CSS) already does this job better :slight_smile:
    • It would become difficult to maintain
    • This would make it a chore for non technical members of the community to read and understand
  • A description of the pros of accessibility.
    • This is information that can already be found in many other places online and not specific to our community so it’s not needed in our documentation.

I think this guideline would be in its own document, probably under FrontEnd Resources, with a link pointing towards it in the Development best practices page and a Design best practices page (left to be created yet).

Do you agree with the idea of adopting some accessibility guidelines in our community?
Feel free to update the first draft with whatever changes you think fits :slight_smile:
We can discuss large changes here.
I’d also be interested to know whether the community agrees with the goals of those guidelines I described above (if not, I’ll handle rewriting some of the guidelines to take into account this change of goal).

Thank you!
Lucas C.

#2

Thanks a lot @CharpentierLucas This is great and much needed.

In this reply, I’m not going to focus on the proposed rules inside the guidelines but more about how to organize it.

Yes

You refer to “XWiki Community” a few times but I’m not sure if we have the same definition. For me a user of XWiki is part of the XWiki Community and we don’t know if they care about accessibility or not, and it doesn’t matter. What is important to me is that the XWiki Developers care about it and that we produce a software that is accessible, and extensions that are also accessible. So I’d refer to “XWiki Developers” instead of “XWiki Community”.

Now I think this document has 2 target category of users:

Right now we have the following resources related to accessibility:

So I think we need the following:

WDYT?

Thanks

1 Like
#3

PS: Note that instead of a design.xwiki.org page, you could also have created a draft page at https://dev.xwiki.org/xwiki/bin/view/Drafts/ But it’s fine, no need go change anything. just a FYI.

#4

:+1:
I checked and it seems I only used this wording in this forum topic but not in the guidelines themselves.

  1. :+1: https://dev.xwiki.org/xwiki/bin/view/UserExperience/ looks like the best place to put them
  2. Thanks! I wouldn’t have thought of this doc, :+1: to add a link there for the sake of scripting users (second category of user you listed)
  3. :+1: I’ll probably move around a few other docs related to accessibility so that it makes more sense and it’s not as scattered as it was.
  4. There’s already a link to the WCAG testing page in https://design.xwiki.org/xwiki/bin/view/Proposal/Accessibilityguidelines#HIn-buildaccessibilitytesting :slight_smile:
#6
  • An interactive element is any element you could consider tapping when using XWiki on your phone. This guideline ensures it’s not too difficult to interact with this interface, even if your screen is small!

Does it mean that an interactive element is only when using a phone media? When using a desktop browser this rule doesn’t apply?

When visualizing how users interact with a feature, keep in mind that they own’t not only use a mouse

Typo

Some information are implied in the design and should be conveyed even to users with a limited vision. That’s why along designs should be provided annotations that are not visible but still better the experience for low vision users. For example, HTML provides a few landmarks that make it way easier for screen-reader users to navigate a page.

This is abstract to me and some examples would go a long way. Actually I’d suggest that ALL sections show an example of both DOs and DON’Ts. That would make it so much easier to apply and understand.

Note that this choice can be difficult to make for action links: links that redirect to a new URL which is just a new state of the current page.

So that what’s the recommendation? Again some examples of dos and don’t would help.

If they hold no semantics whatsoever, use an empty description with alt="".

Why? could you explain why it’s better to be empty than not existing?

These checklists can guide manual validation of the accessibility of a feature.

Typo → This checklist

Those are usually the mo

Missing end of sentence

Globally sounds good (but I’m not an expert at all), so +0 from me but I’d really like to see examples of do and don’t as I don’t feel I’m able to understand the points enough right now to be able to apply them.

Thanks

#7

This is an illustration to figure out what interactive elements are, and also put the idea that phone users are also people that can benefit from accessibility. This size guideline is really useful for touchscreen users :slight_smile:. The element itself doesn’t get the interactive property depending on the interaction pattern. It’s a property we design and implement, and it will be used differently by different browsers and devices.

I added For example in front of this point and rephrased it a bit in hopefully a clearer way. :+1:

:ok_hand: Fixed.

I added some DOs and DON’Ts for most guidelines (all except User Flow which is more conceptual and needs a large example to illustrate).

Added extensive DOs and DON’T here, and moved this sentence in a comment because it’s not as important as the main point.

Explained in detail in the guideline :+1:

Fixed :+1:

Thank you for your feedback on the content!
Lucas C.

#8

So the rule of 24x24 is true for any element you interact with, whether it’s on touchscreen or not, right? that’s what I was lacking.

ok I see you added visual examples. I was actually thinking about code examples for DOs and DONTs since we’re developers and it would help more for us to talk about code than something visual which can be implemented in lots of different ways and is subject to interpretations. You could leave the visuals now that you have them if you want, but showing code examples would help more IMO.

Thanks!

#9

Yes :+1: The touchscreen is a relatable example :slight_smile:

In the introduction I added the sentences In order to understand them all, looking at the way they are rendered in your browser is as important as looking at the way they are implemented using the "Inspect" feature of your browser. Some of those DOs and DON'T will look exactly the same on your browser, in this case it's especially important to check their HTML. This notice goal is to say that the way the TODOs are implemented is also relevant (in most cases it’s more important than the visuals). I wanted to avoid putting code blocks in the guidelines to keep them short and easy to read through. Not every XWiki dev is fluent with HTML and/or CSS and I think the most important here is that everyone can understand the concepts. I could create a child page with all the TODO HTML contents in code blocks so that devs interested in it can find them easily. It would be titled something along the lines of Accessibility guidelines: DO and DON'T implementations. Would that be okay?

Thanks,
Lucas.

#10

err? How could you implement some feature of XWiki that must respect the guidelines and not know what HTML/CSS to use? :slight_smile:

#11

That’s not enough. This doc is about MUST and SHOULD so you also need to know how to implement things as otherwise, you won’t be able to respect the guidelines.

#12

I disagree with this. This doc is about MUST do, not just nice to have. And it’s targeted to developers. So we need to know precisely how to implement things. This is basically the same as https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/

I thought we had agreed that the idea of this doc was to replace (ie merge) the rules for CSS/HTML that are currently on https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/XhtmlCssCodeStyle/ ?

#13

When working on the design part of it or on a backend for the feature, it’s not always easy or necessary to care about the exact HTML/CSS we’ll use to display this UI / expose the features IMO. It’s important to be able to identify some pain points early on to avoid or plan addressing them.

As said above, we can put the code examples in a child page, just like the accessibility guidelines would be for our user experience documentation. More about the difference I think there is between those and the codestyle doc below vvv

I think most of them can be linked to the accessibility guidelines. However, IMO those docs fulfill different roles: codestyle rules list arbitrary decisions we took for the community (because sometimes we have multiple ways to approach a problem and the best solution is to be consistent on how we answer it), while the accessibility guidelines document lists generic accessibility concerns that are particularly important in the context of XWiki. Codestyle rules are not covered by our automatic tests, while things in the accesibility guidelines are covered in the automatic tests. Note that pointer input size should be removed from the codestyle because it’s now in the WCAG standard.

A lot of “how to implement things” depends on context. Axe-core uses heuristics and I don’t think it’d be useful to try and give the exact definition they came up with for each rule. For some rules it’s easy to get close enough with a couple sentences. I don’t think it’s relevant or possible to try and give MUST rules for every single case. This is also why AI is not performing so well on improving accessibility and automated accessibility tests cannot spot out 100% of violations.

The best solution to answer this issue in my opinion is to make sure devs understand the idea behind the rule, and give DOs with concrete implementations for the most common cases. The DOs will be the MUST rules we follow. The exlanations make sure that devs can recognize situations where they must use the guidelines and make the best choice when they encounter a difficult situation not covered in the guidelines.

#14

Well, I’m not sure I understand your points and the need for an XWiki accessibility guide. Why do we need one since that guide already exists and it’s called the WCAG Guidelines, and we’re supposed to follow it 100% (for AA version 2.1 at least)?

The only interest I see in having an XWiki accessibility document is to explain how we map the generic WCAG guidelines into XWiki-specific implementations.

I really don’t see the need for 3 docs:

  • WCAG docs
  • XWiki accessibility guidelines docs
  • XWiki codestyle docs for WCAG

This is just too much IMO. We just need 2 docs:

  • A link to the WCAG guidelines (external link). This explains the concepts and rationales for the various rules. No need to paraphrase it.
  • A doc on the XWiki side to list specific actions that we can take.

Exactly, this is why we need them! We’re in the XWiki context and even in XWiki we can have sub contexts. The only thing we need is to help developers to the max so that they know what to do when coding.

I agree about The DOs will be the MUST rules we follow. (And ideally have automated checks where we can). The rest is just a best effort since we can’t recommend anything. And I don’t see the point in paraphrasing with less precisions what’s already in the official WCAG guidelines for the rules for which we can’t figure out an actionable strategy.

Thanks