Current wording of the summaries for SC 1.2.1 - 1.2.5

• Transcript (audio-only content): For audio content that has no video (like a podcast), provide a transcript.

• Captions (videos and presentations): For videos and presentations (both live and pre-recorded), provide captions.

• Text or audio description (videos and presentations): For videos and presentations, provide an equivalent text description, or an audio description of what happens on screen.

• Audio description (videos presentations if pre-recorded): For videos and presentations that are pre-recorded, provide an audio description of what happens on screen, even if you've already provided a text description.

What's the problem?

There are a few issues with the above:

Problem 1: Wrong link to SC 1.2.5

The last one ('Audio description') corresponds to WCAG SC 1.2.5, not 1.2.4. (The link needs to be fixed).

Problem 2: Not distinguishing between A- and AA-level requirements is making things harder for readers

It's really what the last two requirements ('Text or audio description' and 'Audio description') mean in the context of each other.

I.e. it looks like, if you meet the 'Audio description', you automatically meet 'Text or audio description', right? So what's the point of listing both?

Well, 'Text or audio description' is required for the A level of compliance, while 'Audio description' is required for the AA level. That's why there's a distinction.

This highlights a problem with our current layout: we are not showing the level of conformance that each requirement corresponds to. Initially I thought that that would be a good sacrifice to make to simplify things. But in this case, it makes things more difficult to understand. And it also means that colleagues don't know where to start, if they don't want to meet the AA-level of conformance.

Problem 3: Unclear distinctions between requirements for 'pre-recorded' and 'live' content

• It's not clear which requirement is for pre-recorded content, and which is for live content as well.

• Also, in the WCAG, captions for pre-recorded performances is a A-level requirement, while captions for live performances is a AA-level requirement. The current summaries don't show this distinction. This was intentional, but I'm concerned that, without that distinction between A-level and AA-level requirements, readers might think that these guidelines are hard too hard to get started with.

Suggested solution

Provide alternatives for audio content, videos and presentations

Thanks @lubes72 for this feedback:

• 'pre-recorded' (rather than 'prerecorded')
• don't contract negatives
  • e.g. 'do not' (rather than 'don't')
• don't use 'e.g.' or 'i.e.'
  • use 'for example' or 'like'
• don't say 'do not require' as that's not clear
  • It might be better to say something like 'do not make [something] required'

The summary for this on the overview page is:

Controls do not make things happen as soon as they are touched.

While the title on the detail is:

2.5.2 Pointer Cancellation

Which feels a bit disconnected.

I'm also wondering if it should also mention being able to cancel the touch-down event by sliding your finger or mouse away from the element that was clicked or tapped?

https://github.com/theappbusiness/accessibility-guidelines/blob/master/guidelines/1.1.1.md

I think this would help people navigate, but it means another thing to maintain so has some overhead when iterating on the document.

I'm a tester who joined last Oct, realized the last time this repo was updated was 2 years ago

Potential solution

I imagine that saying 'provide a transcript or an equivalent text description' would clarify things

Todo

Check whether 'transcript' is a term used in the WCAG in relation to videos

https://theappbusiness.github.io/accessibility-guidelines/guidelines/1.4.13.html#for-content-to-be-dismissed

What the summary of 2.4.6 on the overview page says

On the overview page, the summary of Success Criterion 2.4.6 currently tells readers to "provide headings and labels":

Provide headings and form labels that help people find content and complete tasks.

What the official phrasing of 2.4.6 says

But in fact, WCAG SC 2.4.6 doesn't require headings and labels to be provided (that's covered by 1.3.1 and 1.4.2). It only says that headings and labels that are provided must accurately describe topic or purpose:

2.4.6 Headings and Labels: Headings and labels describe topic or purpose. (Level AA)

So, not using labels or headings is not a violation of 2.4.6. What is a violation of 2.4.6 is using labels or headings that don't correctly describe the topic of their associated section or input.

The content of the 'Requirements' section needs to be clarified in the detail page

A form may be written in a way where its purpose or the purpose of some of the components is not clear. This can be passed by using the
HTML 5.2 autocomplete attributes, on fields that collect information about the user.

Possible mis-alignment about what this particular success criterion requires, and what that means on iOS and Android

@KaneCheshire @geftimov:
I don't yet understand what the equivalent requirement is for iOS and Android. So I'm not sure 100% sure whether we're on the same page about what this particular WCAG success criterion is about.

• In HTML, the autocomplete attribute should only be used on input fields that collect information about the user themselves (as browsers will that attribute – eg autocomplete="given-name" – to suggest the auto-suggest the user's given name every time).
• Is this the same in iOS and Android?
  • In particular, I believe that in iOS and Android we can specify the type of information an text input field needs to collect (e.g. email, phone number). These 'types', I believe, are much broader that the possible values of the HTML autocomplete attribute, and don't trigger autocomplete.

On Android:

@geftimov:
I'm not sure that the current 'how to' for Android on the page matches this specific WCAG success criteria. :android:contentDescription="label", android:hint="label" and android:labelFor="@id/edit_text" seem to relate to Success Criteria 3.3.2 'Label and instructions' instead.

"These are the web content accessibility guidelines, so "app" must mean "a web app".

I think we are probably in a state where we can start to hook up the remaining links, even though the detail pages still need some work, I think the overview page is starting to really get into a good state.

https://github.com/theappbusiness/accessibility-guidelines/blob/master/guidelines/1.1.1.md

Refer to the W3C Alt text decision tree

They scored its clarity 3/5

They wrote "Stacking info instead of truncation" which suggests to me that they did understand the SC, but maybe weren't feeling confident that they did.

So, maybe this is only a minor issue (given they they could click through to the detailed view). But we should try to clarify the headline summary

They scored its clarify 3/5.

They wrote

• "Why are we collecting?"
• "Structure of the form input"

I don't think that they understood the SC from the summary.

possible solutions

• persistent
• doesn't automatically disappear

@KaneCheshire @taliazdc @robert-kinder and team,

I’ve worked on improving the structure of the details page.

I’ve experimented for lots of small changes over the past two days, and I’ve submitted two pull requests. Both pull requests apply the same changes:

• one is a pull request for the details page of 1.1.1
• the other is a pull request for details page of 1.3.1.

I've described the issues in more details in the pull request for 1.3.1. (Perhaps it'd have been better to do it here).

Do let me know if you disagree with these changes quickly if possible (even if you're not yet sure how to fix them), as I have some time available tomorrow and I'd like to make more progress on some of the other details pages.

See the details page for 1.3.1

The headline summary of this success criterion currently reads:

Name, Role and State of interactive controls: Make sure the code of each page enables assistive technologies to discover the purpose of every feature, the way that feature is identified, and the state it is currently in.

Designers rated its clarify 4/5, so it's not bad. But they also wrote "add example"?

Overall, reading that sentence again, I feel that it could be written in a clearer way.

"Instructions don't rely on sensory characteristics"

"I think I know what 'sensory characteristics' mean, but I'm not entirely sure".

(From Fred)

Need to replace them with proper HTML text

The following sentence isn't platform-agnostic so makes it appear to be a web-only requirement:

All information and functionality must be available on a screen that's 320 CSS pixel wide, without needing to scroll horizontally

I propose we use "points" instead of CSS or pixels:

All information and functionality must be available on a screen that's 320 points wide, without needing to scroll horizontally

The headline summary currently reads:

Changes on focus: Make sure that just navigating to an interactive control with the keyboard doesn't trigger any action, and doesn't move the keyboard focus somewhere else.

Designers scored the clarity of that statement 3/5.

They wrote "it doesn't tell me what I shouldn't do"

I've just enabled 'Github Pages' in the repository's settings, selecting the master branch as the source for the page.

The settings page now say "Your site is published at https://theappbusiness.github.io/accessibility-guidelines/". But when I visit that URL I get a "404 Site not found error".

I don't understand why that's happening. My understanding is that the index.html file located at the root of the master branch should be served (or at least the README.md should be served).

I've read the docs and don't see why that issue might be happening. The only paragraph that seems somewhat relevant is the following one, on the page titled 'Configuring a publishing source for your GitHub Pages site':

Troubleshooting publishing problems with your GitHub Pages site
Note: If your site's source files are located in the default publishing source—master for user and organization sites or gh-pages for project sites—but your site has not published automatically, make sure someone with admin permissions and a verified email address has pushed to the default publishing source.

I don't understand what that paragraph means. If the "site's source files are located in master", then what does it mean to "make sure someone with admin permissions and a verified email address has pushed to the default publishing source."?

I've merged the updated detail pages for SC1.3.2-2.4.5. But I haven't double-checked whether the phrasing of the summaries on the overview page still match that on the details page.

This needs checking, and where there are inconsistencies, the phrasing of the summaries on the overview page need updating.

Information conveyed through presentation should be available to screen readers or available in text, as per WCAG 1.3.1.

Issue

The headline and the summary of SC 1.3.1 don't mention anything about that fact.

The Guidance for Android section on 1.4.4 text resize is currently empty.

See the equivalent iOS guidance.

Guidance can include the key points directly in the document, and links to the key API references or helpful articles.

What we currently have

Currently, SC3.1.1 (Language of Page) and SC3.1.2 (Language of Parts) are summarised in one bullet point:

Language of content: In code, identify the language that the content is written in (English for example). If the page uses several languages, identify the language of each part.

What's the issue?

We did that to minimise the length of the document. But it means that we can't show that SC3.1.1 is a A-level criterion, while SC 3.1.2 is a AA-level criterion.

Proposed solutions

##### Option 1:

We could distinguish between SC 3.1.1 and SC 3.1.2 on the summary page.

###### Prototype

##### Option 2: Leave things as is

This is a trade-off between different desired outcomes:

• Making it easier to see what's covered by different levels of conformance, to help prioritisation
• Minimising the length of the page
• Making the page easy to understand

Option 3: Keep one entry (rather than having 2), but add a note in the 'Level' column

###### Prototype

Recommendation

I'm tempted to go for Option 1. But I'm not 100% sure. I want to be careful with the length of the page.

We need to decide whether the overview page distinguishes between levels of conformance.

Here's the current summary headline for reference:

Text spacing: Ensure that no information or functionality gets lost if users increase the space between lines, paragraphs, letters and words.

They scored its clarity 3/5.

They wrote "Paddings + margins?", "between lines of paragraph".

I wonder whether there's a way to write this headline summary in a clearer way.

See the details page for 1.3.1

Need to check through the newly added 2.1 success criteria to see whether some of them are web only. It's likely that 'Resize text' is

@taliazdc would like to contribute to this document. At the moment, she cannot review code or merge her own PRs. @KaneCheshire would it be possible for her to be added to the team, so that it's easier to collaborate on this doc?

This ambiguity / lack of clarity was raised by @robert-kinder in a related conversation.

Here's my summary of the situation, and of the decision that we need to make:

• Web pages should have a main heading (using the <h1> element), as well as a page title (using the <title>) element. The main heading is visible on the page. The title is visible on the browser tab, and is announced by screen readers. This is what allows screen reader users to orientate between the tabs of their web browsers.

• WCAG SC 1.4.2 has been written for web pages (back in early 2000s when native mobile apps didn't exist). And its only requirement is about the <title> of a web page.

• 1.4.2 says nothing about what the main headings of a web page should be. But it's convention and best practice for the <h1> and the <title> to mirror each other – with the exception that the <title> should also indicate the name of the website/service. @robert-kinder has documented an example of how the content of h1 and of title should compare.

• It's not 100% clear whether and how 1.4.2 applies to native mobile apps. Some people say that the WCAG apply to native apps (with a bit of interpretation/adaptation). Some people say that the WCAG don't apply.

• But the new UK public sector procurement law will apply the WCAG to native apps started June 2021. So my opinion is that, when a WCAG Success Criterion translates well to native mobile, we should apply it there too.

• In the case of 1.4.2, there's an ambiguity: the Success Criteria's only requirement is for the title of a document (i.e. <title> for a HTML page, or equivalent for a PDF or Word document). It doesn't say anything about what the main heading of a page should be. So maybe, yes, we should make this 'web only'.

• But at the same time, I'm imagining that for a native mobile app, the equivalent of <title> would be the title that appears in the navigation bar at the top of the screen. I'm imagining that, on native mobile app, the title that appears in the navigation bar at the top of the screen serves the same purpose as <title> and <h1> at the same time. So I'd like to investigate further.

@KaneCheshire @geftimov @amryousef-tab what are your thoughts?

There is a lack of wider understanding that (bluetooth) keyboards are used to navigate native apps. This leads people to mistakenly believe that SC 2.1 (Make all functionality work with a keyboard) is only web only.

A possible solution would be to state in the overview page beneath the 2.1 heading:

"Note: Some users use (wireless) keyboards or other input devices to interact with native mobile apps - in particular, users with mobility impairments. Therefore, this section is applicable to all applications. To find out more, please see [external URL(s)]"

Not perfect, but might help

The guidance for Web in 2.4.7 says:

browsers don’t show focus rings around native HTML buttons when they’re clicked.

That's actually not correct. Browsers will show author-defined focus styles on native HTML buttons too.

See https://developer.paciellogroup.com/blog/2018/03/focus-visible-and-backwards-compatibility/

See the issue

Look at the overview page on an iPhone 5

Next steps

Implement proper 'cluster' pattern for badges

On the overview page, the 'Page titled' guideline (2.4.2) is labelled as Web-only.

But there's no reason to support that.

On the contrary:
* The W3C working group note on the matter say that 2.4.2 apply to native apps

• The BBC Mobile Accessibility Guidelines offer iOS and Android guidance for it

Here's a situation of struggle that I've witnessed, as a Agile Delivery Lead used our checklist today:

Situation of struggle:

“I struggle when I read something that I don’t understand. I want to know whether this requirement is about something ‘under the hood’ that I’m not meant to understand, or something that’s within my realm but I’m not getting it."

In other words:

“Highlight what’s engineering stuff, so that people who are not engineer don’t feel intimidated by the document when understand some of this engineering stuff”.

Conclusion:

So, although I’d rather not assign roles to requirements right now, in our overview page, on our own (i.e. without consultation, buy-in and ownership with the different CoPs), I think that we could try to use language like “Design” and “Code” (and maybe just that) to indicate what each bullet point is about.

… even if we end up with both “design” and “code” being indicated for most bullet point. (At least, for the few are code, we avoid the situation of struggle above, and we avoid putting off non-tech people)

This issues takes the specific example of issues with our current wording of SC 1.2.1 - 1.2.5, to highlight problems with the structure of our summary and suggest a solution.

Current wording of the summaries for SC 1.2.1 - 1.2.5

• Transcript (audio-only content): For audio content that has no video (like a podcast), provide a transcript.

• Captions (videos and presentations): For videos and presentations (both live and pre-recorded), provide captions.

• Text or audio description (videos and presentations): For videos and presentations, provide an equivalent text description, or an audio description of what happens on screen.

• Audio description (videos presentations if pre-recorded): For videos and presentations that are pre-recorded, provide an audio description of what happens on screen, even if you've already provided a text description.

What's the problem?

There are a few issues with the above:

Problem 1: Wrong link to SC 1.2.5

The last one ('Audio description') corresponds to WCAG SC 1.2.5, not 1.2.4. (The link needs to be fixed).

Problem 2: Not distinguishing between A- and AA-level requirements is making things harder for readers

It's really what the last two requirements ('Text or audio description' and 'Audio description') mean in the context of each other.

I.e. it looks like, if you meet the 'Audio description', you automatically meet 'Text or audio description', right? So what's the point of listing both?

Well, 'Text or audio description' is required for the A level of compliance, while 'Audio description' is required for the AA level. That's why there's a distinction.

This highlights a problem with our current layout: we are not showing the level of conformance that each requirement corresponds to. Initially I thought that that would be a good sacrifice to make to simplify things. But in this case, it makes things more difficult to understand. And it also means that colleagues don't know where to start, if they don't want to meet the AA-level of conformance.

Problem 3: Unclear distinctions between requirements for 'pre-recorded' and 'live' content

• It's not clear which requirement is for pre-recorded content, and which is for live content as well.

• Also, in the WCAG, captions for pre-recorded performances is a A-level requirement, while captions for live performances is a AA-level requirement. The current summaries don't show this distinction. This was intentional, but I'm concerned that, without that distinction between A-level and AA-level requirements, readers might think that these guidelines are hard too hard to get started with.

Suggested solution

Prototypes

• Prototype A: Table with Requirement first. In the 'overview-layout-test1' branch, I've experimented with a new layout using a table.

• Prototype B: Table with Level and Responsibility first. In the 'overview-layout-test1b' branch, I've also prototyped a slightly different version, where the 'Level' and 'Responsibility' columns come before the 'Requirement' column.

• Prototype C: Table with Level and Who first. The 'overview-layout-test1c' branch is the same as Prototype B, except that I've replaced the column header name 'Responsibility' by the word' Who'. I think that 'Who' is slightly less descriptive, but it makes the column narrower, leaving out more width for the requirement column. This makes the requirement easier to read, and takes less lines).

• Prototype D: Table with Who first, then Requirement and Level last. The 'overview-layout-test1d' branch is the same as Prototype B, except that I've put the 'Who' column first, and the 'Level column' last.

Comments

• I'm using tables (one for each Guideline, e.g. "Guideline 2.1: Provide alternatives for audio content, videos and presentations"), rather than just lists of bullet points

• The tables have a column for "Conformance level"

  • This is for distinguishing between A- and AA-level requirements
  • I suggest that we don't list AAA- level requirements, as they are not used in any standard. Instead, I propose that we use the content from AAA-level requirements in other documents or training workshops, when we provide best practices not covered by the WCAG AA standard.

• The tables have a column for "Responsibility" (e.g. Design, Content, Engineering)

  • This is to make it easier for colleagues to:
    • Understand what success criteria they need to understand and focus on
    • Not get confused by success criteria that are fully outside what is typically considered their immediate remit, so that they find this document easier to read

• The tables DO NOT have any other column

  I know that it can be tempting to solve other usability issues, or answer other feature requests, by adding new columns. But if we add any other column, our document will become unpleasant to look at and overwhelming. I propose that we stick to 3 (or less) columns maximum.

  For example, one issue is that some people don't expect that most of these success criteria apply to native apps. So it can be tempting to add a column that says either "Web" or "Native and Web". I propose that we do not do that, because, unless exception, all of these success criteria apply to native apps. I think that it's better to just call out those exceptions.

• I'm not yet sure which prototype works best. Probably B or C

Note

Right now we're working with plain Markdown, for two reasons:

• Plain markdown makes it really easy for anyone to quickly update the document, without requiring knowledge of HTML/CSS, and without getting bogged down in code
• The simplicity of plain Markdown forces us to focus and find simple solutions to usability issues / feature requests.
  It could be tempting to just say "oh, the document isn't working right now, but we'll ask a designer to design it better and we can use CSS to solve all our problems".

I suggest that instead of doing that, we solve our most important problems using the simplicity of plain Markdown. This avoids feature bloat and procrastination.

But, once the content of this document, and its structure, is stable, yes let's improve its elegance and usability with CSS, for sure.

And once we use CSS, it might be that we stop using a table, and use something like dots or tags to achieve the same structure is a more elegant way.

Next steps

What do you think?

The issue

The summary of 1.4.13 currently reads like this:

Extra content on hover or focus. If content (like a tooltip) appears when users hover over an element with their mouse (or tab to it with their keyboard), it must be easy to dismiss, easy to reach and remain visible.

@lubes72 asked "remain visible when?".

Potential solutions

• Maybe replace 'and remain visible' with 'and does not disappear before users want to'. But that's quite long
• Maybe replace 'and remain visible' with 'and does not disappear too early'.
• Maybe keep as is?

Next steps

• Any other thoughts from anyone?

What's the issue

On top of my head, I believe that unaware designers can easily cause failures to SC1.3.2.

E.g. when they create designs where elements are not in the same left-to-right reading order when viewed on different screen sizes.

Educating designers about this potential barrier is important. But the current wording of this summary suggests that it's purely an engineering issue.

Next steps

• Look at the official wording of the success criterion
  • Can designers cause this issue?
  • What's the official short name of this success criterion in the WCAG?
• Propose new phrasing for the name of this success criterion
• Add 'Design' to the 'Responsibility' column of the table, if appropriate

Are there any examples of how (or indeed, where) Apple support this on iOS? As far as I know there's no built-in way to support navigating content with just a keyboard without some extra work from the developers, so wondering how this is a requirement that Apple handle, or how we're expected to handle it natively.

There are ways to do it by writing lots of custom code similar to this: https://gist.github.com/adamyanalunas/b1ce3af40843a356dc3cade6e6ab6a21

But as far as I can see it's not natively support out-the-box with a couple of lines of code like most other examples we've got so far.

Note also that gist is just for a UITableView, this doesn't cover UICollectionView or any other type of view that is on screen, so extra work would be needed to support those, as well as support traversing from a table to another element, like a tab bar.

I feel like this is a problem that hasn't yet been solved because it's not part of iOS?