Design QA Instructions

Summary of steps

• 1. Review PR's changes against Definition of done in Storybook preview links
• 2. Review Percy results, see how below
• 3. Comment on PR with any requests for changes. Repeat above until no changes are needed
• 4. Approve both PR & Percy checks
• 5. Remove Needs design review label

Pre-requisite: Carbon Devtools browser plugin

• Carbon Devtools (Chrome)
• Carbon Devtools (Firefox)

Detailed instructions

1. Review Storybook preview links

Definition of done (DOD) is what both designers and developers should reference when creating and reviewing the PR. Sharing the same standard will reduce time spent on QA. If you notice any gaps in the current DOD, please reach out!

DDS storybook's preview links are automatically generated once the PR is submitted. This usually takes 10-20min to build. Look for the preview links in ibmdotcom-bot comments:

Keep in mind there might be multiple storybooks to review. In general,

• a style package change affects both Web components and React storybooks, so both should be reviewed.
• a new component build in Web components should be reviewed in React wrapper storybook, and not React storybook.
• an experimental component change will require the Feature flag label to generate the Experimental components storybook preview link.
• a RTL (Right to Left language) change will require RTL label to generate the RTL components storybook preview link

2. Review Percy results

Percy checks fail whenever the PR contains a visual change compared to the current production build. This prompts the designer to look into the Percy results to see if this visual change is intentional, or not. This check helps us to catch unintended visual regression that sometimes happen due to our complex tree of dependencies.

To review Percy results:

After clicking "Details", you should see the Percy results page, which looks like below. Any visual differences from Production will be highlighted red.

3. Comment to request changes

Leave a comment or use Request changes comment to provide feedback. After leaving comments, remove 👀 eyes needed and add the ⚒️ fix needed label.

Tips for leaving comments:

• Be conscientious to the PR's specific goal, usually targeted at fixing one specific issue. If you notice problems unrelated (and not triggered by) the target issue, create a new issue instead of mentioning in comments.
• Organize comments into logical sections. Usually design QA reveals lots of comments; when comments are organized, we make an effort to create alignment, and make the detailed comments easier to digest. Some good sections are: by breakpoints, by functionality vs style, or by severity.
• Index the comments with numbers. When the PR owner has a question or response regarding one of the comments, s/he can reference the number.
• Be clear and specific. It helps to have screenshots side by side showing a comparisons of "Current" and "Expected".

4. Submit review on GitHub

To Approve the PR and get a nice green checkmark ✅ :

• Go to "Files changed", then click on "Review changes". If you are requested to review, you would see the notification above with "Add your review" button.
• Enter an optional nice note, then select "Approve".
• To approve Percy results, see above: point 2.

5. Remove Needs design review label

The label Needs design review blocks merge. After both storybooks preview and Percy results are reviewed and approved, remove the label is the final step. The PR owners are responsible to add Ready to merge label that prompts our bots to merge PRs down.