# How to add a design review gate to your pull requests

> Add one GitHub Actions workflow and two secrets, 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.

Source: https://www.thedesignagent.ai/field-notes/add-a-design-review-gate-to-pull-requests · Workflow · 2026-10-04

To add a design review gate to your pull requests, add the [TheDesignAgent design review action](https://github.com/CMBurnett/thedesignagent-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:** the action 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.tsx` reviews `/orders`.

## Set it up

**1. Add secrets.** Get an API key from [your dashboard](https://www.thedesignagent.ai/dashboard/api-keys) and add it as a repository secret named `THEDESIGNAGENT_API_KEY`. If your Vercel previews are protected, create a **Protection Bypass for Automation** secret in Vercel (Project → Settings → Deployment Protection) and add it as `VERCEL_AUTOMATION_BYPASS_SECRET`.

**2. Add the workflow** as `.github/workflows/design-review.yml`:

```yaml
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.

> **Start in report-only mode.** Leave `threshold` out for the first week. The action comments without failing, so you can see where your pages score and pick a bar that catches real problems without blocking good work.

## Make the reviews sharper

The action uses 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:

```json
{
  "project_id": "proj_...",
  "check": {
    "threshold": 6,
    "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](/field-notes/add-design-review-to-claude-code), [Codex](/field-notes/add-design-review-to-codex) or [Cursor](/field-notes/add-design-review-to-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](/field-notes/why-ai-generated-ui-looks-ai-generated).

## Common questions

### How do I add design review to pull requests?

Add the TheDesignAgent design review action to a GitHub Actions workflow that runs on deployment_status events, with your API key as a repository secret. When a preview deploy is ready, it reviews the pages the pull request changed, comments the scores on the PR and fails the check below your threshold.

### Does the design review gate work with protected Vercel previews?

Yes. Create a Protection Bypass for Automation secret in Vercel and 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.