UI Review

UI Tests protect you from accidental regressions. But, before you ship, you’ll want to invite developers, designers, and PMs to review the UI, discuss changes, and get the final sign off.

UI Review creates a changeset of the exact visual changes introduced on a new branch. You assign reviewers who can comment and request tweaks on changes that aren’t quite right. Think of it like a code review, but for your UI.

Previously, this feature was only available for accounts that linked projects with GitHub, GitLab, or Bitbucket. We are now making the feature available to all of our customers, for both linked and unlinked projects.

Enable

Linked projects

Enable UI Review for your project on the Manage screen.

Once enabled, visit the Reviews tab in the web app sidebar. There you’ll be prompted to install the GitHub app or webhooks for GitLab/Bitbucket.

Unlinked projects

For any existing projects not already taking advantage of UI Review, you can enable it on the project’s Manage screen (see above). Any new projects will automatically have UI Review enabled.

Create a Review

Linked projects

If you have linked your project to a repository on GitHub, Bitbucket, or GitLab, enabled UI Review, and set up CI, Chromatic will run builds automatically for each commit on a PR branch. Nothing else is needed from you to create a Review.

Unlinked projects

Navigate to the Reviews link in the sidebar and click the “Create Review” button.

• Select the base branch, which is the branch that’s used as the source of truth for comparison.
• Select the head branch, which is the branch that has the changes that you want to compare with the source of truth. Then, click “Continue to review.”
• Enter a title for the Review. Then, press “Compare branches”

Understanding the Review

Once a Review has been created—either manually or through CI—navigate to the Reviews tab and select the appropriate Review. You will then land on the Activity tab, which shows a timeline of builds, active discussions, and Review status. This showcases what needs to be done in the Review process.

Invite teammates

Invite other developers, designers, PMs, and stakeholders to help review changes. This closes the feedback loop between disciplines and helps you find the answer to “does this look right?”

If you linked your project to GitHub, Bitbucket, or GitLab, your project permissions are synced so collaborators can sign in to review immediately. If your project is unlinked, use the project invite code to add collaborators.

Assign reviewers

Use the Assign Reviewers link on the Review’s Activity screen to choose reviewers from the project’s collaborators. Reviewers will be emailed a link to the Review screen to begin their review.

Pull requests from forks

Chromatic supports UI Test and UI Review across forks, but there’s some caveats. First, it only works with CI integration configured to also build PR branches from forks. Secondly, you must expose your project token so that forks can use it. The easiest way to do that is to simply include it in in your package.json, for example:

{
  "scripts": {
    "chromatic": "chromatic --project-token <CHROMATIC_PROJECT_TOKEN>"
  }
}

If you use a CI provider other than GitHub, you can still use an environment variable. Just make sure your CI is configured to also build forked branches. The project token does not grant access to the project (it can only retrieve a strict set of insensitive data), but it does allow running new builds which count against your snapshot quota.

Review the changes

The Review screen includes a Changeset tab showing a side-by-side view of all visual changes introduced on your head branch. It compares the UI on the head branch to the base branch. You’ll see each change’s component story before and after the head branch changes are applied to your base branch.

Discussions

Reviewers can request updates to the implementation via the comment box beneath each change. Discussions are threaded and attached to the specific story represented by the change.

UI checklist

At the bottom of the Review screen’s activity tab is a list of tasks that must be completed before UI is ready to be signed off on. If changes are found, the Review will enter the 🟡 Pending state. When changes are approved and checklist items are complete, the Review will be 🟢 Passed. Here’s how to resolve these tasks:

1. Changeset must be approved → Assign reviewers or approve yourself.
2. Outstanding discussions must be resolved → Click ‘Resolve’ on discussions.
3. All assigned reviewers must approve → Click ‘Approve’ in the Review screen tab bar.

Closing a Review

Linked projects

No action is required on linked projects to close a Review. Once the PR branch is merged, the Review will be closed automatically.

Unlinked projects

Once a Review is complete, it can be closed by clicking the ‘Close review’ menu item in the ‘Review now’ button tooltip. Your review will then be displayed in the list of ‘Closed’ Reviews on the Reviews page.

PR check for “UI Review”

Linked projects

You’ll get a ‘UI Review’ status check for each PR that shows the state of the UI Checklist. Require the check in GitHub, GitLab, or Bitbucket to ensure that impactful changes are considered by the team before merging.

Unlinked projects

Manually created Reviews will not create a “UI Review” status check in GitHub, GitLab, or Bitbucket. To create a status check in your Git provider for manually created Reviews, you can use a custom webhook.

Next: Learn about documenting reusable components

Now that you’ve seen how to review the UI changeset before merging, learn how Chromatic makes sharing versioned and interactive component docs simple.

Read next chapter

Frequently asked questions