Shadscan inspects a React shadcn app, scores its UI fundamentals from 0 to 100, and shows the evidence behind every finding.

It catches the product details that are easy to postpone: command menus, theme shortcuts, route states, accessible controls, form feedback, metadata, mobile behavior, and more.

The default scan is deterministic and read-only. It does not start the app, edit files, call an AI model, upload source, or require application secrets.

Quick Start

Run Shadscan from the root of a project:

pnpm dlx @shadscan/cli

The project path defaults to the current directory. Pass a path to scan another app:

pnpm dlx @shadscan/cli ../my-shadcn-app

Using npm or Bun:

npx --yes @shadscan/cli
bunx @shadscan/cli

Shadscan requires Node.js 18 or newer. Commands resolve to the latest stable release; prereleases are published under the next tag (@shadscan/cli@next).

Interactive human source audits show progress immediately and keep each completed phase above the final report:

✓ Resolving project
✓ Discovering app structure
✓ Evaluating UI rules
✓ Preparing report

Rendered UI checks use phases specific to browser work:

✓ Resolving UI target
✓ Checking mobile and desktop layouts
✓ Preparing UI report

Both checklists are written to stderr for interactive human output only. JSON, CI, TERM=dumb, non-TTY stderr, and --no-interactive output stay quiet; prompt output also stays quiet. Redirecting stdout keeps the report clean while progress remains on an eligible stderr terminal.

What You Get

Your shadscan score: [###############-] 92/100 (Grade A)
shadscan has entered the chat.

Categories:
  Foundation:           20/20 (100%)
  Interaction:        12.2/20  (61%)
  States:               20/20 (100%)
  Accessibility:        20/20 (100%)
  Forms and Data Entry: 10/10 (100%)
  Production Polish:    10/10 (100%)

Missing: command menu has a Cmd/Ctrl+K shortcut
  Evidence: No complete mounted Cmd/Ctrl+K command-menu shortcut was found.
  Fix: Register a shortcut that prevents the browser default and toggles the menu.

Every report separates:

• Fixes: high-confidence defects with repository-relative evidence.
• Decisions: product choices that should be implemented or explicitly waived.
• Advisories: lower-confidence checks that need rendered or manual verification.
• Not applicable: rules excluded because the relevant UI surface is absent.

Common Commands

# Machine-readable, versioned report
pnpm dlx @shadscan/cli --json

# Paste-ready remediation plan for a coding agent
pnpm dlx @shadscan/cli --prompt

# Explicitly launch an installed agent with the generated plan
pnpm dlx @shadscan/cli --apply --agent codex

# Install the current candidate as an exact CI dependency, then enforce a floor
pnpm add --save-dev --save-exact @shadscan/cli
pnpm exec shadscan --fail-under 80 --no-interactive --no-roast

# Audit one category while investigating a focused area
pnpm dlx @shadscan/cli --category accessibility

# Run rendered UI checks against an already-running app
pnpm dlx @shadscan/cli --check-ui http://localhost:3000

# Add same-origin routes to the target URL
pnpm dlx @shadscan/cli --check-ui http://localhost:3000 --route /dashboard --route /settings

Use --format human, --format json, or --format prompt when output selection needs to be explicit.

Pin an exact package version in CI; unqualified commands resolve to the latest stable release. Run pnpm dlx @shadscan/cli --help for every option.

Rendered UI Checks

--check-ui <url> is the home for deterministic checks that need a rendered page. Horizontal overflow is its first check. It opens an already-running local or deployed app in isolated Chromium pages at two fixed CSS viewports — mobile at 320 × 820 and desktop at 1440 × 1000 — and fails on any document-level horizontal overflow, including a one-pixel overflow or a horizontal scrollbar forced on the root or body. The target URL is always checked; repeat --route <path> to add pages, up to ten pages in total. Each route must begin with / and cannot contain a query string or fragment.

The initial request may follow narrowly validated server-side canonical redirects between a conventional two-label apex host and its www host, and from HTTP to HTTPS. For multi-label public suffixes, pass the canonical origin directly. The resolved origin is then pinned for every additional route. Other cross-origin redirects, HTTPS downgrades, and client-side cross-origin navigations remain blocked. Reports use the resolved origin as their target; human output also identifies the originally requested origin when it changed.

This is separate from the default static source audit. It does not add a rule, score, or grade, and the 62-rule catalog and existing mobile-overflow-absent advisory stay unchanged. Shadscan does not start or build the target app, and the command does not need a project directory.

Use --json for its versioned standalone report. A clean result exits 0. Detected overflow exits 1 with the complete report on stdout. Operational or argument errors exit 1, keep stdout empty, and write the error to stderr. If Chromium is not available, install the matching managed browser with:

pnpm dlx [email protected] install chromium

Rendered UI checks perform GET navigations and execute page JavaScript in fresh isolated browser contexts. It reads no project source, invokes no package scripts, and saves no page data. It is available only in the local CLI, not through MCP, the GitHub Action, hosted API, or web scanner.

Agent Handoff

--prompt turns the same deterministic report into a neutral, paste-ready plan for another coding agent. The handoff includes:

• prioritized work items grouped as fix, decide, or verify;
• rule IDs, evidence, suggested fixes, and acceptance criteria;
• detected framework, package manager, and source-coverage context;
• repository-owned verification commands that the agent must inspect first;
• the exact pinned Shadscan command to rescan after the work.

--apply is an explicit local action. It validates an installed Claude Code, Codex CLI, or Grok Build executable before launching it. Shadscan itself still does not make an AI request; the selected external agent follows its own provider and approval model.

MCP Server

shadscan mcp serves the same deterministic audit over the Model Context Protocol on stdio, so coding agents can query results as typed tool calls instead of parsing output:

claude mcp add shadscan -- npx -y @shadscan/cli mcp

Three read-only tools: scan (score plus filterable actionables — by category, severity, or workspace package), list_projects (workspace packages with their application-or-library classification), and explain_rule (what one rule checks and where it applies). Every call re-scans the current file state — results are never cached — and every response carries the engine, ruleset, and schema versions. The server scans inside the roots it was started with and nothing else, and it never writes files. Details and per-client setup live in docs/mcp.md.

Before Every Agent Commit

Install the optional AI-agent commit protocol:

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

Then ask your agent:

Use $shadscan-pre-commit for this task. Establish the current score before
editing, run Shadscan immediately before every commit, and do not commit if the
audit is unassessed or below the task floor.

The skill governs agent behavior only. It does not install dependencies, configure Git, or add a Husky or native pre-commit hook.

What It Checks

The bundled ruleset contains 62 deterministic checks across six weighted categories.

| Category | Examples | | --- | --- | | Foundation | shadcn config, mounted theme provider, metadata, favicon, not-found and error boundaries | | Interaction | dark-mode and command-menu shortcuts, safe global hotkeys, mobile navigation, focus visibility | | States | loading and Suspense fallbacks, empty states, retryable errors, pending actions, mounted toasts | | Accessibility | names and labels, semantic controls, alt text, landmarks, live regions, keyboard and focus behavior | | Forms and Data Entry | validation, rendered field errors, error associations, legends, button types, autocomplete | | Production Polish | complete metadata, social previews, Button icon spacing, responsive shells, SEO files, mobile overflow |

See the CLI documentation for usage, automation, agent workflows, and every supported option.

Scoring

Raw rule points are normalized within each weighted category to produce the 100-point score.

High- and medium-confidence failures can reduce the score. Low-confidence checks stay visible as score-neutral advisories instead of pretending static analysis can prove rendered behavior.

Rules only run where they apply. Shadscan supports Next.js App Router, Pages Router, hybrid Next.js projects, React Router framework mode, TanStack Start, Laravel with Inertia and React, Astro with React islands, Vite React, and generic React applications.

Privacy And Exit Status

The default local scan is static and stays on your machine. The explicit --check-ui mode navigates to the URL you provide under the separate rendered UI contract above.

Findings return exit status 0 unless --fail-under is not satisfied. Discovery, audit, setup, and launched-agent failures return 1. Use --no-interactive for deterministic automation.

Web Scanner And Hosted API

The web scanner audits a public GitHub repository without installing the CLI or exposing an API key to the browser. GitHub access, extraction, rate limiting, and scanning stay on the server.

For agent and service integrations, Shadscan also exposes a versioned hosted API for public GitHub repositories and sanitized gzip tar snapshots.

• Pinned agent instructions
• OpenAPI 3.1 contract
• CLI documentation
• Web scanner

The hosted surfaces are opt-in and have separate source-handling contracts from the local CLI.

Contracts

• Audit JSON uses schema version 4 and is validated by the exported AuditReportSchema.
• Agent prompt output uses prompt version 5.
• Every report identifies the exact bundled ruleset version that produced it.
• RULE_CATALOG exposes immutable rule metadata for integrations.

License

Shadscan is available under the MIT License. The header and badges are rendered by shieldcn, a shadcn-styled badge and README graphics service.