Review verification checklist

[natalia-fitzgerald]

Before we move the verification checklist to a central place and create a GitHub issue template, please review provide feedback or propose changes.

Verification checklist for DS components

This checklist should be used for verifying CFPB Design System in React components against their source components in the CFPB Design System.

1. Verify the DSR component against the DS

Stories page

• Introduction text matches the DS component page
• Link to the DS component page is included (e.g., Source: https://cfpb.github.io/design-system/components/buttons)
• Each DS component variant is implemented as a separate story
• Story names are written in sentence case (eg., Radio button NOT Radio Button)
• Component and variant names match the DS without repeating the name of the parent component (eg., Button => Primary NOT Button => Primary button )
• Ordering of component and variants matches the ordering in the DS

Component

• Component passes a manual visual review when compared with the DS component
• React renders the HTML markup the same as in the DS (To verify, right click the component in the storybook preview and choose "Inspect." Compare the HTML markup that you see in the dev-tools with the example provided in DS when you click "Show details" within the component)
• Component uses DS classes (organisms, molecules, atoms), as opposed to styles defined in DSR

2. Run accessibility checks

• Component is keyboard-friendly (navigable with tab, space, enter, arrow keys, etc.)
• Component does not introduce new errors or warnings in WAVE
• Component is screen reader friendly (screen reader testing demo)
  • All the meaningful visual information and text of the component is conveyed by the screen reader (text, non-decorative image descriptions, etc.)
  • When interacting with the component using a screen reader, all of the required information required to use it is available (selected vs unselected, button vs link, expanded vs collapsed, etc.)
  • The component has similar screen reader behavior as the sample components in WCAG, the CFPB design system, WebAIM, or similar accessibility examples? https://www.w3.org/TR/WCAG21/
• For reference: CFPB manual web accessibility audit

3. Verify component unit tests

• Verify component unit tests are implemented and passing - 85% or greater (ex: yarn vitest ComponentName)

4. Prepare a PR for code review

• Create a PR with the name: Final verification review for XXXX component
• Copy this verification checklist that's almost complete into the PR description

5. Conduct code PR review

• Submit PR with any necessary changes for code review by frontend devs

6. Conduct component verification PR review

• Apply GitHub label "component-verification"
• Change the component's status from Draft to Verified in Storybook
• Add a DSR contributor as a reviewer (must include a designer review)
• Ping DSR contributors in Slack in the Design System in React channel when ready

7. Verify component

• Merge when design and dev review completed to finish component verification 🎉

Screenshots

For review: @billhimmelsbach @flacoman91 @anselmbradford @virginiacc

[flacoman91]

this checklist looks good!

I added some info about comparing the component between DS and the markup that DSR generates

I also changed the yarn vitest Button to yarn vitest ComponentName to make it more generic instead of targeting a specific test.

[natalia-fitzgerald]

Thanks for your feedback @flacoman91!

[anselmbradford]

A few things:

• It looks like the checkboxes after All steps for existing components plus the following steps should be indented, like the ones in the prior section.

• The CFPB Design System maintainers have been notified that there is a new component that should be added to the system I would change this to opening an issue on the DS repo https://github.com/cfpb/design-system/issues

• Component does not introduce new errors or warnings in [WAVE](https://wave.webaim.org/extension/) deque aXe is also a tool we use.

• Verify component unit tests are implemented and passing - 85% or greater (ex: yarn vitest ComponentName) ideally this shouldn't be a checkbox, but instead should be a PR check that fails if it's not over 85% … however, in practice we may want to introduce code that is lower in coverage as we're working on it, so maybe there could be warning in the PR check? At any rate, this can be automated.

• Copy this verification checklist that's almost complete into the PR description this could be a PR template that's automatically provided as an option when the PR is opened https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

• Apply GitHub label there should be a way to automate this.

• Ping DSR contributors in Slack in the Design System in React channel when ready this is saying ping DSR contributors in slack when the PR is ready to be reviewed? I wonder if there's a Slack integration where adding the GH label could ping the Slack channel.

A lens I'd view each of these checks through is "how can we automate this?" This is a great list of the steps that should happen, but we also don't want to create extra friction, or the steps will be skipped. I wonder if, for example, in regard to the keyboard interactions, whether we could have a test template (Cypress? I know the DSR doesn't currently use Cypress, so is that best?) for keyboard interactions that follows the accessibility audit steps. I'm not sure whether we could cover VoiceOver steps there, but maybe?

[natalia-fitzgerald]

@anselmbradford - These are all super helpful suggestions. I will want to dig into them more next week! I agree that we should automate what we can.

It looks like the checkboxes after All steps for existing components plus the following steps should be indented, like the ones in the prior section.

I removed the checklist formatting from "All steps..."

The CFPB Design System maintainers have been notified that there is a new component that should be added to the system I would change this to opening an issue on the DS repo https://github.com/cfpb/design-system/issues

I updated this above

Component does not introduce new errors or warnings in WAVE deque aXe is also a tool we use.

Do you have a link you would like me to include? Or just mention the tool?

[anselmbradford]

Do you have a link you would like me to include? Or just mention the tool?

There's a chrome extension URL one can google, but it is very long, so I think it could go either way on including it.

[natalia-fitzgerald]

Automation opportunities

These are some automation opportunities that @anselmbradford suggested that we should research further after we release the MVP version of this issue template.

@anselmbradford makes a great point here - "A lens I'd view each of these checks through is "how can we automate this?" This is a great list of the steps that should happen, but we also don't want to create extra friction, or the steps will be skipped."

The following verification tasks could possibly be automated:

1. Verify component unit tests are implemented and passing

• Next step: Research an automated PR check that fails if it's not over 85% (warning in the PR check)

2. Copy this verification checklist that's almost complete into the PR description

• Next step: Research creating a PR template that's automatically provided as an option when the PR is opened https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

3. Apply GitHub label

• Ping DSR contributors in Slack in the Design System in React channel when ready - Research
  • Next step: Research a Slack integration where adding the GH label could ping the Slack channel.

4. Conduct accessibility checks

• Next step: Research creating a test template for keyboard interactions, VoiceOver, etc. that follows the accessibility audit steps.

@anselmbradford @flacoman91 @billhimmelsbach

[natalia-fitzgerald]

@virginiacc @anselmbradford @billhimmelsbach @flacoman91

I made some updates to the checklist above. I am realizing that the specific use case for this checklist is to verify CFPB DS components that have been or are being added to the DSR. We use the word "verified" to describe Design System components that have gone through the "verification" process. The verification process is to review using this checklist. I removed the section called "For new components" because, really, a component should only start this verification process IF it is already in the DS.

We have a CFPB Design System process for adding a new component to the DS and that should be the first step for new components. This should be true whether these new components are cf.gov components or brand new components. It is possible, and likely, that a team will chose to add this type of component as a draft to the DSR while the DS process is taking place.

We may ultimately need a another checklist that is for verifying components that are not (and will never be) DS components. But, without a specific example of this I cannot know that it is an actual need. So, I will wait to make this type of checklist.