My own tool gave me a D

My own tool gave me a D

One command scores your UI.

I build a lot of shadcn apps. So I built something to check them.

It's called shadscan. One command, no AI, no API keys, nothing uploaded. It reads your React shadcn code and scores the UI fundamentals out of 100 - the same score every run, on your machine or in CI.

Then I ran it on my own site.

64. D.

What it actually checks

More than 60 deterministic rules across 6 categories. Not vibes - the specific things that are easy to postpone:

• Is a theme provider mounted?
• Is there an app-level command menu?
• Is there a dark-mode keyboard shortcut?
• Do pointer targets reach 24×24 CSS pixels?
• Is the document language declared?
• Is metadata configured, and is there a favicon?

Every finding carries the evidence behind it and one of three dispositions: fix, decide, or verify. The decide ones are questions for you, not tasks for a machine - that distinction is the reason the output is usable rather than a wall of warnings.

One command

pnpm dlx @shadscan/cli

That's the whole thing. It doesn't start your app, edit your files, call a model, or send your source anywhere. The same input gives the same score, which is what makes it safe to gate on.

Then hand it to an agent

This is the part I actually use.

pnpm dlx @shadscan/cli --prompt

That generates a handoff: every finding grouped into work items, with evidence and acceptance criteria attached.

Paste it into your coding agent with instructions like these:

Summarise the work items by severity and point out the files with the most issues. Propose a prioritised remediation plan from the fix items, and list every decide item as a question for me rather than a task. Stop and share the plan before changing anything.

It comes back with a plan you approve or rewrite. That's how my site went from 64 to 100 - and the decide items stayed decisions I made, rather than guesses the agent made on my behalf.

Put it in the pipeline

A pre-commit gate, so a bad score blocks the commit:

npx skills add TheOrcDev/skills --skill shadscan-pre-commit

Or a GitHub Action that audits every push, records the score, and opens an issue when it slips:

name: shadscan
on:
  push:
    branches: [main]
permissions:
  contents: read
  issues: write
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: TheOrcDev/shadscan@main
        with:
          path: .
          fail-under: "80"
          create-issue: "true"

Once it's in CI you stop thinking about it, which is the only way a quality gate survives contact with a real project.

One thing to actually do this week

Run it on the project you'd be most embarrassed to have audited.

pnpm dlx @shadscan/cli

You don't have to fix anything. Look at the number, read the top three findings, close the terminal. Two minutes, and you'll learn more about your UI than a week of "looks fine to me."

It's free and open source, and it covers more than React on its own: Next.js, Vite, TanStack Start, Laravel, Astro and React Router are all supported today. Contributions for anything else are welcome.

github.com/TheOrcDev/shadscan - a star helps.