DesignCheck Documentation

Automated design reviews for your pull requests. Capture screenshots across devices and get visual feedback before merging.

📌 Requirements: DesignCheck works with repositories that have automated preview deployments. We support Vercel, Netlify, Cloudflare Pages, and Railway.

Getting Started

DesignCheck integrates with your existing preview deployment workflow. When you open a pull request, your deployment platform (Vercel, Netlify, Cloudflare Pages, or Railway) creates a preview deployment. DesignCheck automatically detects this deployment, captures screenshots across different devices, and posts them directly to your PR.

Prerequisites

Your repository must have automated preview deployments set up with Vercel, Netlify, Cloudflare Pages, or Railway. If you don't have preview deployments yet, see setup guides below.

Quick Start

Ensure your repository has preview deployments enabled (Vercel/Netlify/Cloudflare/Railway)
Install the DesignCheck GitHub App on your repository
Add a .designcheck.yml file to your repository
Open a pull request and watch DesignCheck capture your designs

Installation

1. Install GitHub App

Install DesignCheck on your GitHub account or organization. You can choose to install it on all repositories or select specific ones.

Install GitHub App

After logging in, you'll be able to install DesignCheck on your repositories from the dashboard.

2. Configure Permissions

The GitHub App requires the following permissions:

Pull requests: Read & Write - To read PR information and post comments
Contents: Read-only - To read .designcheck.yml configuration
Deployments: Read-only - To detect preview deployment URLs

Configuration

Create a .designcheck.yml file in your repository root to configure DesignCheck.

# .designcheck.yml

# Routes to capture screenshots for
routes:
  - "/"
  - "/about"
  - "/pricing"

# Devices to test
devices:
  - "iPhone 14 Pro"
  - "Desktop"

# Wait time before capturing (milliseconds)
delayMs: 2000

Important

DesignCheck only runs on repositories that have a .designcheck.yml file. This is how you opt-in to using DesignCheck.

YAML Reference

`routes`

Array of URL paths to capture. Paths are relative to your deployment URL.

Type: string[]

Required: No

Default: ["/"]

routes:
  - "/"              # Homepage
  - "/about"         # About page
  - "/products"      # Products listing
  - "/products/1"    # Specific product
  - "/dashboard"     # Protected routes work too

`devices`

Array of device presets to use for capturing screenshots.

Type: string[]

Required: No

Default: ["iPhone 14 Pro", "Desktop"]

iPhone 14 Pro

390×844px - Mobile viewport

Mobile

iPad Pro

1024×1366px - Tablet viewport

Tablet

Desktop

1920×1080px - Desktop viewport

Desktop

devices:
  - "iPhone 14 Pro"
  - "iPad Pro"
  - "Desktop"

`delayMs`

Time to wait (in milliseconds) before capturing screenshot. Allows time for animations, async content, and images to load.

Type: number

Required: No

Default: 2000

delayMs: 3000  # Wait 3 seconds

Tip: Increase this value if your screenshots show loading states or incomplete content.

Deployment Providers

DesignCheck integrates with popular deployment providers that support preview deployments. Choose the platform that best fits your workflow:

▲

Vercel

Vercel automatically creates preview deployments for every push to a pull request. DesignCheck detects these deployments and captures screenshots once the build completes.

Setup Steps:

Connect your GitHub repository to Vercel
Ensure "Automatically create deployments for all commits" is enabled (default)
Add .designcheck.yml to your repository
Open a PR - Vercel builds, DesignCheck captures

Netlify

Netlify creates Deploy Previews for pull requests. DesignCheck listens for successful deployments and captures screenshots automatically.

Setup Steps:

Connect your GitHub repository to Netlify
Enable "Deploy Previews" in Site Settings → Build & Deploy
Ensure GitHub notifications are enabled
Add .designcheck.yml to your repository
Open a PR - Netlify builds, DesignCheck captures

Cloudflare Pages

Cloudflare Pages automatically builds preview deployments for pull requests. DesignCheck monitors deployment webhooks to capture screenshots.

Setup Steps:

Connect your GitHub repository to Cloudflare Pages
Enable preview deployments in project settings (enabled by default)
Ensure GitHub integration is active
Add .designcheck.yml to your repository
Open a PR - Cloudflare builds, DesignCheck captures

Railway

Railway creates ephemeral environments for pull requests. DesignCheck detects these deployments through GitHub deployment events.

Setup Steps:

Connect your GitHub repository to Railway
Enable PR deployments in project settings
Ensure GitHub webhook notifications are enabled
Add .designcheck.yml to your repository
Open a PR - Railway builds, DesignCheck captures

Don't have preview deployments yet?

Preview deployments are temporary environments created for each pull request. They allow you to test changes before merging to production.

Getting started is easy:

All platforms above offer free tiers for individual developers
Most can be set up in under 5 minutes
They integrate seamlessly with GitHub repositories
Preview deployments are a best practice for modern development workflows

How It Works

DesignCheck integrates seamlessly with your existing development workflow:

Open a Pull Request

Push your code changes and create a PR on GitHub. DesignCheck checks for .designcheck.yml in your branch.

Deployment Detected

Your deployment provider (Vercel, Netlify, etc.) builds and deploys your preview. DesignCheck automatically detects the preview URL.

Screenshots Captured

DesignCheck visits each route on each device, waits for content to load, and captures full-page screenshots.

Review Posted

A comment is posted to your PR with a link to view all screenshots. Team members can review, annotate, and approve or request changes.

Troubleshooting

DesignCheck not running on my PRs

Check:

.designcheck.yml exists in repository root
File is in the PR branch (not just main)
File has valid YAML syntax
GitHub App is installed on the repository

Screenshots show loading states

Solution:

Increase the delayMs value to give content more time to load:

delayMs: 5000  # Wait 5 seconds

Wrong routes captured

Solution:

Update .designcheck.yml and push a new commit. DesignCheck will re-run with the new configuration.

Images not loading in review

Check:

This is likely a temporary issue. Try refreshing the page. If the problem persists, check the PR comment for any error messages.

Configuration Examples

Minimal (Single Page)

Perfect for simple landing pages or single-page apps.

routes:
  - "/"
devices:
  - "Desktop"

Marketing Website

Test key pages across mobile and desktop.

routes:
  - "/"
  - "/features"
  - "/pricing"
  - "/about"
  - "/contact"
devices:
  - "iPhone 14 Pro"
  - "Desktop"
delayMs: 1500

Dashboard Application

Test across all device sizes with extra loading time for data.

routes:
  - "/login"
  - "/dashboard"
  - "/settings"
  - "/profile"
  - "/analytics"
devices:
  - "iPhone 14 Pro"
  - "iPad Pro"
  - "Desktop"
delayMs: 3000  # Extra time for data to load

E-commerce Store

Test product pages and checkout flow.

routes:
  - "/"
  - "/products"
  - "/products/featured-item"
  - "/cart"
  - "/checkout"
devices:
  - "iPhone 14 Pro"
  - "Desktop"
delayMs: 2500

Ready to get started?

Install DesignCheck on your repository and start getting automated design reviews today.

Get Started View Your Reviews