UI check GitHub Action for every pull request

Coding agents write a lot of UI code quickly, and the same problems slip through review again and again: a link to #, a button whose handler does nothing, a list with no empty state, a new shade of blue. They're easy to miss when reading a diff and easy to fix when someone points at the line.

The UXKIN UI Check points at the line. It runs in your pull request job, reads only the lines the change adds, and reports what it finds where the reviewer is already looking. It needs no account or token, and your code never leaves GitHub.

Add it to your repository

Create .github/workflows/ui-check.yml with this, commit it, and open a pull request:

name: UI check

on:
  pull_request:

permissions:
  contents: read

jobs:
  ui-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: uxkin/ui-check@v1

That's all. It runs on every pull request from then on. No secrets to add, and it only needs permission to read the code. To see what it reports first, look at this demo pull request.

What it checks

Controls that do nothing

Links to # or javascript:, handlers like onClick={() => {}}, and click handlers on a <div> that keyboard users can't reach.

Missing states

A component that fetches data and renders a list, but has no loading, error or empty state. In Next.js, a loading or error file next to the page counts.

Token drift

A hex or rgb color that isn't used anywhere else in the project. Your existing palette and colors defined in token or theme files aren't flagged; only new one-off values are.

Accessibility basics

Images without alt, form fields without a label, focus outlines removed without a replacement, and positive tabIndex values.

Generic patterns

Lorem ipsum, sample names like "John Doe", purple-to-blue gradients, "Submit" and "Click here" labels, and emoji used as icons.

Read the results

Findings appear on the changed lines in the pull request's Files changed tab, and all of them are listed in the job summary with the file, the line and what to do. Each has a severity:

• Error: clearly broken for some people (an image without alt text, lorem ipsum). Fails the job by default.
• Warning: very likely a problem, worth a look before merging.
• Notice: a generic pattern worth a second thought. Often fine.

Fix what it finds

Fix it yourself, or hand the list to your coding agent. Copy the findings from the job summary into this prompt:

The UXKIN UI Check on this pull request reported the findings below. Fix each one within the scope of this change:

[paste the findings from the job summary]

For each finding:
- Fix the cause, not the symptom: a link that goes nowhere becomes a real link or a <button>; a list without states gets designed loading, error and empty states; a new color becomes one of the project's existing tokens.
- Reuse the project's components and tokens. Don't add new ones unless the finding needs it.
- If a finding is intentional, add a uxkin-ignore comment on that line with a short reason instead.

Then render the changed screens, check them at 390px and 1440px and by keyboard, and list what you fixed, what you ignored and why, and what you checked.

Options

The defaults suit most projects. To make it stricter, narrower or quieter:

      - uses: uxkin/ui-check@v1
        with:
          fail-on: warning            # error (default), warning or never
          paths: "src/**/*.{tsx,css}" # which files to check
          ignore: "src/legacy/**"     # extra files to skip
          disable: "generic-label"    # checks to turn off

To silence one line, add a comment containing uxkin-ignore on it, or uxkin-ignore-next-line on the line above.

What it doesn't do

It's a source check, not a visual review. It reads code, so it can't tell whether a screen looks right, whether the main task is easy, or whether it fits your product. A clean run means none of these checks matched the new code, nothing more.

Use it to catch the mechanical problems early, then look at the rendered screens before merging. The coding agent UI checklist covers the parts only a person (or an agent that can see the app) can check.

Questions