Clean 'New in 2.2' code

[remibetin]

Direct link to preview: https://deploy-preview-281--wai-intro-wcag.netlify.app/standards-guidelines/wcag/new-in-22/

Changes:

• Use h4 for "In brief", "Persona example" & "WCAG Success Criteria" headings
• Use relative links when linking to internal WAI website pages.
• Create a new (simple) blockquote component for citing documents such as WCAG.
• Use existing resource link for Understanding links
• Use Markdown rather than HTML wherever possible
• Simplify overall by deleting unused or redundant classes.

Next steps when validated:

• Move component HTML in theme (& delete _includes/blockquote-document.html in this repo)
• Move component CSS in theme (& delete inline_css)
• Document component

[netlify]

✅ Deploy Preview for wai-intro-wcag ready!

Name	Link
🔨 Latest commit	ac52d25
🔍 Latest deploy log	https://app.netlify.com/sites/wai-intro-wcag/deploys/66019bcb0804960008ac6b43
😎 Deploy Preview	https://deploy-preview-281--wai-intro-wcag.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[remibetin]

@shawna-slh What do you think of this cleaned version (changes listed in the description)?

[shawna-slh]

Thanks @remibetin !

brief notes below. we can discuss useful.

wcag pull quote

• nice!
• check were else we've used this or might want to, e.g., @iadawn in redesigning Understanding docs with new In Brief sections?

Understanding links

(e.g., "Understanding Focus Not Obscured (Minimum)")

• I recognize this as a component used in the report tools.
• I think it's too small here. In the tools those links are tangential to the main user flow. Here they are substantial for many users' flow.
• also, not good affordance. doesn't clearly indicate that it will open in new window. kinda feels like it will open a pop-up. maybe that's OK in a tool where folks will likely be using it a lot. I think not good for this resource.

h4

• likely overkill for screen reader navigation, also redundant headings not easy to navigate, see https://validator.w3.org/nu/?doc=https%3A%2F%2Fdeploy-preview-281--wai-intro-wcag.netlify.app%2Fstandards-guidelines%2Fwcag%2Fnew-in-22%2F&showoutline=yes#headingoutline
• thin lighter-color text harder to read
• I'm interested in other perspectives...
• (if leave, probably move the persona description into a <p> instead of including in the <h4>)

[iadawn]

I like the idea of having a WCAG reference element. However I do have a few thoughts:

• The element needs to be called 'wcag-reference' rather than 'blockquote-document'.
• We need to review other usage patterns to ensure that it works in all places.
• Is <blockquote> the semantically correct? Probably, just want to check that it semantically makes sense when we are effectively quoting ourselves.
• A particularly important instance of the above is Understanding documents:
• • Does it still make sense to be using <blockquote>?
• • Does the styling work within the context of the Understanding page - my initial vote is 'no', although I would like to see it in context.
• Remove the target="_blank" from the link to the Understanding page.
• The Understanding link styling does not match that in the QuickRef which might help a bit with - beyond consistency across our resources, I am largely less concerned with the styling in this context. The icon makes it clear that there is more to follow, the onhover style changes make it clear that it is a link. I think there is value in having a blockish styling for a link in this context since otherwise it would look really weird.

[shawna-slh]

The element needs to be called 'wcag-reference' rather than 'blockquote-document'.

hummm... if it's a visual design component, then generic name is better, yes?

Wouldn't we use 'wcag-reference' only if it was actually pulling data?

[iadawn]

It is a design component for a specific purpose. TBH the best way to do it is to have a blockquote design component and a wcag-reference component that (possibly) calls the blockquote element.

And ideally it would be pulling data... but that is a bit too much to ask for at the moment :)

[remibetin]

Kevin: The element needs to be called 'wcag-reference' rather than 'blockquote-document'.

Shawn: hummm... if it's a visual design component, then generic name is better, yes?

@iadawn I agree with @shawna-slh that this new design is meant to be as generic as possible. The current blockquote component has been designed for quoting a person and is not adapted for quoting multiple paragraphs from a document.

Here, we introduce a new blockquote for this purpose, but not necessary just for WCAG. For example, it could be used to cite ATAG guidelines/SC, such as in Guidelines to Make Your No-Code Website Tool Accessible (I am refering to this to illustrate the component could be used to cite other documents, yet I am not sure it would be relevant for this specific section)

TBH the best way to do it is to have a blockquote design component and a wcag-reference component that (possibly) calls the blockquote element.

I would normally agree, but overly breaking-down the code (especially with many includes) can lead to Jekyll performance issues. See https://boris.schapira.dev/notes/2018-11-jekyll-build-optimization/ for more context. Anyway, we could discuss options/alternatives when the moment comes.

And ideally it would be pulling data... but that is a bit too much to ask for at the moment :)

+1 (see our related private discussion)

[remibetin]

@iadawn

Is <blockquote> the semantically correct? Probably, just want to check that it semantically makes sense when we are effectively quoting ourselves.

Well, I get the initial hesitation: it is not immediately crystal-clear.

• HTML Standard reads The blockquote element represents a section that is quoted from another source.
  Question is: what is considered "another source"? Are two documents from the same organization different sources?
• When used in What's New in WCAG 2.2, I tend to think WCAG standard, as a clearly distinct document, from the same organization but different authors, is another source. In contrast, it would appear clearly not allowed to use <blockquote> for a pull quote.

A particularly important instance of the above is Understanding documents. Does it still make sense to be using <blockquote>?

I still think it makes sense. Understanding documents are supporting documents closely related to WCAG, but a different document/source nonetheless: different purpose, different authors, different process to edit and publish, etc.

But that is debatable. What do you think @iadawn @shawna-slh?

FYI, this discussion allowed me to find a more obvious semantic issue for the current blockquote component: w3c/wai-website-theme#90

[iadawn]

I would like to take more time to look at this and provide a more involved response... suffice it to say that at the moment, I would prefer that we don't progress with this new design just yet.

[iadawn]

OK, without the opportunity to pull the content from the WCAG repo there is no point in doing anything other than using a blockquote.

What I would ultimately like to see is:

{% include_cached wcag-success-criterion.html
    heading-level='4'
    shortname='audio-only-and-video-only-prerecorded'
    include-understanding-link=false
%}

Which would pull all the relevant material from the WCAG repo and present it in the appropriate format. I suspect this would need a bit of Ruby to sort out and I don't have time to look at this just not.

For the moment, this is fine as an approach for the What's New In pages.

In terms of the design and whether this would work elsewhere, I will have a think about how to use this in the Understanding pages. The semantics might be ok, but I think the design won't work.

On a final note, I think it should be 'Success Criterion' rather than 'WCAG Success Criteria' when referencing individual criterion.