How to add a design review gate to your pull requests
Install the TheDesignAgent GitHub App, or add one GitHub Actions workflow, and every pull request's preview deploy gets its changed pages reviewed for UX and visual quality, with one updating PR comment and a check that fails below your threshold.
To add a design review gate to your pull requests, install the TheDesignAgent GitHub App, or add the design review action to a GitHub Actions workflow. When a pull request's preview deploy is ready, it reviews the pages that pull request changed, posts the scores and top findings as one comment that updates on every push, and fails the check if a page scores below your threshold. Mark the check as required and nothing ships below the bar.
It's the same review your coding agent gets from TheDesignAgent while it builds, run once more where every change has to pass: the pull request.
What it reviews
- UX: job fit, UX heuristics, cognitive load and pattern conformance, scored 0–10, with findings and suggested fixes.
- Visual: brand compliance, visual hierarchy and aesthetics, scored 0–10 from a real screenshot of the preview.
- Only what changed: it diffs the pull request against its base branch and maps changed files to Next.js App Router pages. A change to
app/orders/_components/table.tsxreviews/orders.
Set it up with the GitHub App
The app is the quickest way in: no workflow file, and no API key stored in your repo.
1. Install it. Open GitHub reviews in your dashboard, choose Install the GitHub App, pick the repos to review, and authorize. You land back on the dashboard with the installation linked to your account, and reviews for its repos bill that account.
2. Set up each repo. For each repo, choose UX, Visual or both, and set the score to fail below. If your Vercel previews are protected, paste a Protection Bypass for Automation secret (Vercel → Project → Settings → Deployment Protection). It's stored encrypted and sent only to the preview's own domain.
3. Make it a gate. In your branch protection rules, mark the TheDesignAgent design review check as required.
From then on, each preview deploy of a pull request gets a check run and one comment. Use Re-run on the check to review the same preview again.
Or set it up with GitHub Actions
Use the action if you want the review to run in your own CI, pinned to a version.
1. Add secrets. Get an API key from your dashboard and add it as a repository secret named THEDESIGNAGENT_API_KEY. If your Vercel previews are protected, add the bypass secret as VERCEL_AUTOMATION_BYPASS_SECRET.
2. Add the workflow as .github/workflows/design-review.yml:
name: Design review
on:
deployment_status:
jobs:
design-review:
if: github.event.deployment_status.state == 'success' && !contains(github.event.deployment_status.environment, 'Production')
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v7
with:
ref: ${{ github.event.deployment.sha }}
fetch-depth: 0
- uses: CMBurnett/thedesignagent-action@v1
with:
api-key: ${{ secrets.THEDESIGNAGENT_API_KEY }}
vercel-bypass-secret: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
threshold: 6
Vercel posts a deployment status to GitHub when a preview is ready, so the review runs against that commit's live preview and the comment lands on its pull request. Not on Vercel? Run the action on pull_request with a base-url that serves the branch.
3. Make it a gate. In your branch protection rules, mark the design-review check as required.
Use one or the other on a repo, not both, or each pull request gets two reviews.
Start in report-only mode. Leave the threshold empty for the first week. The review comments without failing, so you can see where your pages score and pick a bar that catches real problems without blocking good work. Scores vary by about ±0.5 between runs of an unchanged page, so set the bar about 0.5 below the score you want to hold. Each PR comment marks a change within that range as normal variance.
Make the reviews sharper
Both use the same project context as your coding agents, from the .thedesignagent file at the root of your repo. Add a check section to give important pages a task that describes the user's job, a page-specific threshold, or a concrete URL for a dynamic route, to skip pages behind your app's sign-in, and to list decisions you've made on purpose so reviews stop recommending against them (you can also keep these on the project in your dashboard):
{
"project_id": "proj_...",
"check": {
"threshold": 6,
"exclude": ["/dashboard", "/admin"],
"decisions": ["Show all five credit packs; don't fold them."],
"pages": [
{ "path": "/orders/123", "code": "app/orders/[id]/page.tsx", "task": "Review an order and decide whether to refund it" }
]
}
}
To see what a run would cover before you turn it on, run this locally:
npx -y --package=@thedesignagent/mcp thedesignagent check --changed --base-url https://your-preview.vercel.app --dry-run
Where it fits
The gate is the last check, not the only one. The cheapest place to catch the wrong screen is before it's built, so give your coding agent the brief and review loop too: Claude Code, Codex or Cursor. Then the gate mostly confirms what the agent already fixed, and catches what slipped through. For why the default output needs catching, see why AI-generated UI looks AI-generated.
Common questions
How do I add design review to pull requests?
Install the TheDesignAgent GitHub App on your repos and link it to your account, or add the TheDesignAgent design review action to a GitHub Actions workflow. When a pull request's preview deploy is ready, either one reviews the pages the pull request changed, comments the scores on the PR and fails the check below your threshold.
Should I use the GitHub App or the GitHub Action?
Use the GitHub App for one-click setup: no workflow file and no API key in your repo, and settings live in the dashboard. Use the Action if you want the review to run in your own CI, pinned to a version, or on hosts other than Vercel.
Does the design review gate work with protected Vercel previews?
Yes. Create a Protection Bypass for Automation secret in Vercel and add it in the GitHub App's repo settings, or pass it to the action. It is sent only with requests to the preview's own domain.
Which pages does the design review gate check?
The pages the pull request changed: changed files are mapped to Next.js App Router pages, so a change to a component under app/orders reviews /orders. Dynamic routes and pages behind login can be listed with a concrete URL in the .thedesignagent file.