UI updates

[shawna-slh]

Hi @WilcoFiers @kengdoj @daniel-montalvo . @Hidde, @nitedog , and I had a chance to work on this together. Based on that, I propose the following edits.

• [x] footer text edits in e-mail
• [x] footer alignment
• [x] update terminology throughout per https://github.com/w3c/wcag-act-rules/issues/56
• [x] in nav, add icon to end of "All WCAG 2 Guidance"

On All Rules page:

• [x] change the box heading, probably to "About WCAG 2 Test Rules"
• [x] change the text, probably to "WCAG 2 Test Rules describe how to test conformance to Web Content Accessibility Guideline (WCAG) success criteria. They are primarily for developers of evaluation tools and test methodologies. Guidance for others is in Understanding WCAG and WCAG Techniques. To learn more, see: WCAG Overview, All WCAG 2 Guidance, About WCAG 2 Test Rules."
• [x] Explain the two lists. Maybe in text (not in a box) before the first list. Maybe under each h2. Rough idea: "Published Rules have been approved by the Accessibility Guidelines Working Group and are implemented in at least 5 evaluation tools or methodologies. Proposed Rules are complete and will be moved to Published when they have 5 implementations." (note that "has 5 implementations" might be too jargony by itself, yet I think OK following something like " are implemented in at least 5 evaluation tools or methodologies" )
• [x] I think leave this sentence (with tweaks to simplify wording a tad), but in regular text below the box: "Additional Rules are in development and will be published on this page when completed."

For each individual Test Rule page:

• [ ] add a "Page Contents" list in box like throughout the WAI website (examples)
  collapsed h2s per comments below
• [x] fix alignment of the box heading
• [x] Consider the first wording in the h1, the title of the box under it, and the content of the box under it. Maybe:
  • [x] h1 "Test Rule" and "Proposed Rule"
  • [x] box title "Rule Mapping"

[WilcoFiers]

WIP

in nav, add icon to end of "All WCAG 2 Guidance"

Which icon needs to be there?

add a "Page Contents" list in box like throughout the WAI website (examples)

I did this, but dislike how it's turning out. Adding a long list at the top of the page pushes all the important content far down. I would prefer to either not have this ToC, or to have it collapsed by default. Don't quite know how to link to the expectations properly. There can be more than one, and the ID changes depending on if there is. Either "#expectation" or "#expectation-1".

box title "Rule Mapping"

I don't quite know what to do with this.

[shawna-slh]

in nav, add icon to end of "All WCAG 2 Guidance"

Which icon needs to be there?

I think this one: https://wai-website-theme.netlify.app/components/icons/#different-view

(I'm confirming that works for Hidde https://github.com/w3c/wai-website/issues/266 )

add a "Page Contents" list in box like throughout the WAI website (examples)

I did this, but dislike how it's turning out. Adding a long list at the top of the page pushes all the important content far down. I would prefer to either not have this ToC, or to have it collapsed by default. Don't quite know how to link to the expectations properly. There can be more than one, and the ID changes depending on if there is. Either "#expectation" or "#expectation-1".

Thanks for giving it a try and bringing it back for additional consideration.

When we did usability testing for the last redesign, a clear finding was that users wanted that Page Contents list at the top. We weren't even specifically looking for that in the UT and in some we had it on the right (e.g., https://www.w3.org/WAI/impl/software ) or not at all -- the overwhelming evidence was to add it. We did that throughout the WAI website redesign.

It serves several purposes, including:

1. giving users an overview of the page contents
2. enabling users to jump directly to a specific section
3. providing an easy anchor link when someone wants to share a pointer to a specific section

When EOWG was reviewing the ACT Rules recently, Carlos noted that a TOC would be useful.

I am open to doing something different — not having it at all or having it collapsed by default — if the user experience warrants that.

Given most ACT Rules users will be regular users and we are optimizing design for them (not the casual user that lands here accidentally or occasionally), I think we don't need it for #1 above.

I don't know enough about how people will use these to say how useful #2 would be. My guess is pretty useful. I'm guessing #3 is somewhat useful.

Maybe best to chat briefly to help me understand the expected user experience? Or, does above convince you? :-)

box title "Rule Mapping"

I don't quite know what to do with this.

https://deploy-preview-51--wcag-act-rules.netlify.app/standards-guidelines/act/rules/html-page-non-empty-title-2779a5/ has a box under the h1. It is currently titled "Conformance Rule". Shadi and others thought a better title for that box would be "Rule Mapping". Does that make sense?

(also, it needs to be left aligned)

[hidde]

https://deploy-preview-51--wcag-act-rules.netlify.app/standards-guidelines/act/rules/html-page-non-empty-title-2779a5/ has a box under the h1. It is currently titled "Conformance Rule". Shadi and others thought a better title for that box would be "Rule Mapping". Does that make sense?

I think “Rule Mapping” is very jargony… across supporting documents, this box gives a quick summary of the document. In the case of a rule, the summary is information about how it maps, but I feel we could use a more generic phrase, something that is closer to the user's mental model.

What about “About this Rule”? Fwiw I've also used “About this Technique” in Techniques.

[hidde]

(also, it needs to be left aligned)

Note this is the WAI website footer, which always starts in the 4th column (the grid area called “content”). I feel we should leave it as is.

[WilcoFiers]

I think it's all there. Work is spread over two PRs though:

https://github.com/w3c/wai-website-theme/pull/33 This updates the template with things we needed. Once that is merged we can create a new Netlify preview for this PR, which lets we'll need for a final review / CfC on this PR: https://github.com/w3c/wcag-act-rules/pull/51/

[hidde]

Which icon needs to be there?

I think this one: https://wai-website-theme.netlify.app/components/icons/#different-view

In my original designs we used the external-link icon, I think more people are familiar with it and it is the most helpful way to distinguish between links within the set of ACT Rules and links that take you out of this set (eg to main WAI website, like in this case). So my vote would be for the external-link icon.

[hidde]

Thanks @WilcoFiers ! I have reviewed the PR. Thanks for fixing my comment so quickly, have approved and merged the changed in.

[shawna-slh]

After analysis of common use cases (I can't remember if that's documented somewhere other than e-mail -- if not,we should), Hidde and I decided best UI for the actual Rules would be H2s collapsed with Expand All - Collapse All button. There are some issues with JAWS bug that need to be worked out.

OK to merge without for now. Please either leave this issue open, or create a new one for it. Thanks! Update: JAWS bug to be addressed! see next comment...

[shawna-slh]

Instead of Page Contents/TOC:

• [ ] Add expand-collapse for h2s, with Expand All - Collapse All buttons, and collapsed by default. Here's the documentation: https://wai-website-theme.netlify.app/components/excol/multiple/

(If having an unknown number of Exceptions complicates things, it seems it would be fine for the user experience if there was

h2 Expectations h3 Expectation 1 h3 Expectation 2

(@hidde plans to address the JAWS bug with site-wide update) fyi @daniel-montalvo & @nitedog

[daniel-montalvo]

Hey @WilcoFiers @nitedog @hidde @shawna-slh I am trying to put together in a single comment what is still missing from the redesign to be ready to merge. Let's then decide which of these deserve a call and which we can continue to sort out online.

• [x] Visual styles for code snipets
• [ ] Add "expand/collapse" functionality as per documentation in https://wai-website-theme.netlify.app/components/excol/multiple/
• [x] Take a pass on grammar and language for the about page and the all rules page. Assuming this is ready now based on reactions to linked comment :-)
• [ ] fix date in footer (details below)
• [ ] figure out how to pull correct banner text, and no icon before "Rule Mapping"

If people think anything is missing feel free to edit this comment or add tasks in further comments. This way we all have a quick way to track these issues.

[WilcoFiers]

@shawna-slh Changing the expectation heading structure is a significant departure from how ACT rules have been written in the past. The solution you suggested was discussed by ACT TF in the past and the current one was preferred. I would prefer to avoid re-opening old discussions. Can you live with the solution that we use currently?

[shawna-slh]

I am totally fine leaving the heading structure as is.

Hopefully it is not too difficult to implement the collapsed headings so users get an overview of the page content, and can easily jump between the test cases and the expectations. (and all the other benefits described in previous issues. :-)

[daniel-montalvo]

Hey @shawna-slh @hidde @WilcoFiers

I have tried excol component in https://deploy-preview-59--wai-wcag-act-rules.netlify.app/standards-guidelines/act/rules/aria-attr-defined-5f99a7/

1. "Expand/collapse all" does not seem to work here. is it me missing something?
2. this is a major change compared to how rules have been showing up before in the CG page. + if excol all does not work, it requires expanding each section at a time, which can be time-consuming. Note that I have note even used nested expand/collapses for the pass/fail/inapplicable test cases.

[shawna-slh]

Hi @daniel-montalvo For sure we would need Expand All - Collapse All to be there.

I'm not sure why Expand All - Collapse All is not showing up. (for trouble shooting: 1. I added it to another page -- and it's not showing up in that preview either. So I thought maybe it just doesn't show up in previews. 2. I did a preview of a page that already has it -- and it did show up.)

I'll wait and see if @hidde has any insight before I spend more time on it.

(I don't have enough perspective on how the specific test cases would be used to know it it is best to not have nested expand/collapses. I am fine going with what is easiest for now, and then asking users once they are out there.)

[hidde]

@daniel-montalvo Just had a look at what might be going on. The 'expand/collapse all' component has two pieces that are needed for it to work: HTML and JS. The HTML part works: an empty div is outputted. The JS part does not, there is some code that executes based on the existence of that empty div, but that code fails. There is a log in the console about translations, I expect this stops further execution of that main.js file, including the bit that would have inserted the “expand/collapse all” logic. It does not seem to be related to previews, as it does work in our components page, which is also a preview.

[shawna-slh]

Hi @Wilco I just notice one little thing in the footer -- the date format should be 00 Month 2021 in:

Date: Updated 00 Month 2021. First published Month 2021.

Reminder from e-mail:

"First published" date is nice to provide, though not required. It's not important to go back and add it for existing ones. Or, could just do a year on those.

[WilcoFiers]

@shawna-slh Where are you seeing this malformed date?

[shawna-slh]

Footer of all pages, e.g., https://wai-wcag-act-rules.netlify.app/standards-guidelines/act/rules/aria-attr-defined-5f99a7/

Unfortunately that is also not pulling the updated banner wording or asterisks icon removed.

[shawna-slh]

I think all of these issues have been addressed, or are no longer relevant. If not, please open new issue(s) for the specific open point. Thanks.