search

alphagov / govuk-design-system

One place for service teams to find styles, components and patterns for designing government services.
https://www.gov.uk/design-system
MIT License
512 stars 232 forks source link

Update links to WCAG criteria to make them clearer #4313

Open calvin-lau-sig7 opened 3 days ago

calvin-lau-sig7 commented 3 days ago

What

Changes identified unclear links on all WCAG-related links on the Design System.

This was done as a batch job to address about 40 flagged links in the link text audit, but these changes have not been drafted or approved there.

Full review of the changes in this PR is needed before publish.

What we've done

All instances of link text to WCAG 2.2 criteria are clearly identified as WCAG 2.2 criteria, with SC number and name

On the top-of-page WAG 2.2 call-outs, we've removed "users can successfully" at the end of the lead-in line into the anchor links.

From: To [use component/pattern] and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:

To: To [use component/pattern] and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that:

As a result, we've edited all the anchor links to be more descriptive within the link text, instead of relying on the lead-in sentence.

Why

This more clearly communicates what the link is and where it goes to. Part of https://github.com/alphagov/govuk-design-system/issues/4267.

netlify[bot] commented 3 days ago

You can preview this change here:

Name Link
Latest commit 8448a39ebb3dd3d3c1bff17dcb3babbcee37c502
Latest deploy log https://app.netlify.com/sites/govuk-design-system-preview/deploys/673e1e6792160900080b8098
Deploy Preview https://deploy-preview-4313--govuk-design-system-preview.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

owenatgov commented 2 days ago

These are looking good. IMO ideally the callout links would also include the 'make sure that' from the lead-in paragraph to make it as clear as possible but I think that might tip this over into make the link too wordy and the experience bad for everyone else.

Question for you @calvin-lau-sig7: Do you think that instances of components need a 'component' suffix? For example the second callout link for back links is now 'users can interact with Back links' and I wonder if it should be 'users can interact with Back link components'. I'm not 100% about that as feedback because the user has the context of the page they're on so interested in your thoughts here.

calvin-lau-sig7 commented 2 days ago

Question for you @calvin-lau-sig7: Do you think that instances of components need a 'component' suffix? For example the second callout link for back links is now 'users can interact with Back links' and I wonder if it should be 'users can interact with Back link components'. I'm not 100% about that as feedback because the user has the context of the page they're on so interested in your thoughts here.

Yeah, I better add the "component/pattern" words in... I've got a distinction in my head between the component itself, and the page control – like the "Back links component" is the code that generates individual "back links" throughout a service.

But seeing as we're taking the wordy approach as standard, it makes sense for us to go use the wordy version everywhere it makes sense to.

I'll edit the PR...

calvin-lau-sig7 commented 2 days ago

@selfthinker As mentioned in standup, here's a few things I wanted to mention for your awareness.

I'm looking to make these widespread edits:

The style format for the success criterion is my best interpretation of following the GOV.UK style guide – alas WCAG's style for success criterion is inconsistent across their website.

I'm open to any other comments you have on these changes as well!

calvin-lau-sig7 commented 1 day ago

IMO ideally the callout links would also include the 'make sure that' from the lead-in paragraph to make it as clear as possible but I think that might tip this over into make the link too wordy and the experience bad for everyone else.

@owenatgov Looking at this again, this might be a good move... let me have a think 🤔

calvin-lau-sig7 commented 1 day ago

I've taken in @owenatgov's suggestion to move the "make sure that" wording into the links, as I've agreed that it'll make the link text much clearer as messages. I've made the edits as a new commit and will verify it all looks good in preview tomorrow.

We'll need to review these in PR before push. cc @selfthinker