{"slug": "shadscan-deterministic-ui-audits-for-shadcn-apps", "title": "Shadscan – Deterministic UI Audits for Shadcn Apps", "summary": "Shadscan, a new deterministic UI audit tool for React shadcn apps, scores UI fundamentals from 0 to 100 and provides evidence for each finding, covering command menus, theme shortcuts, route states, accessible controls, form feedback, metadata, and mobile behavior. The tool, available via pnpm dlx @shadscan/cli, is read-only and does not start the app, edit files, call an AI model, upload source, or require secrets. It offers JSON, prompt, and CI outputs, and includes a composite GitHub Action that enforces score floors and creates issue reports.", "body_md": "[Website](https://www.shadscan.com) ·\n[Scan a repository](https://www.shadscan.com/scan) ·\n[Docs](https://www.shadscan.com/docs) ·\n[59 rules](/TheOrcDev/shadscan/blob/main/docs/rules.md) ·\n[Sponsor](https://www.shadscan.com/sponsors)\n\nShadscan 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.\n\nThe 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.\n\nRun Shadscan from the root of a project:\n\n```\npnpm dlx @shadscan/cli\n```\n\nThe project path defaults to the current directory. Pass a path to scan another app:\n\n```\npnpm dlx @shadscan/cli ../my-shadcn-app\n```\n\nUsing npm or Bun:\n\n```\nnpx --yes @shadscan/cli\nbunx @shadscan/cli\n```\n\nCommands resolve to the latest stable release. Prereleases are published\nunder the `next`\n\ntag (`@shadscan/cli@next`\n\n) for early testing.\n\nInteractive human scans show progress immediately and keep each completed phase above the final report:\n\n```\n✓ Resolving project\n✓ Discovering app structure\n✓ Evaluating UI rules\n✓ Preparing report\n```\n\nJSON, prompt, CI, non-TTY stderr, and `--no-interactive`\n\noutput stay quiet.\nRedirecting stdout keeps the report clean while progress remains on an eligible\nstderr terminal.\n\nEvery interactive scan ends with a short menu — pick with the arrow keys and Enter: copy the agent handoff to your clipboard, print it, launch an installed coding agent, or add a pre-commit score gate. The handoff is highlighted first, so a single Enter grabs it; press Esc to keep just the score.\n\n```\nYour shadscan score: [###############-] 92/100 (Grade A)\nshadscan has entered the chat.\n\nCategories:\n  Foundation:           20/20 (100%)\n  Interaction:        12.2/20  (61%)\n  States:               20/20 (100%)\n  Accessibility:        20/20 (100%)\n  Forms and Data Entry: 10/10 (100%)\n  Production Polish:    10/10 (100%)\n\nMissing: command menu has a Cmd/Ctrl+K shortcut\n  Evidence: No complete mounted Cmd/Ctrl+K command-menu shortcut was found.\n  Fix: Register a shortcut that prevents the browser default and toggles the menu.\n```\n\nEvery report separates:\n\n**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.\n\n```\n# Machine-readable, versioned report\npnpm dlx @shadscan/cli --json\n\n# Paste-ready remediation plan for a coding agent\npnpm dlx @shadscan/cli --prompt\n\n# Explicitly launch an installed agent with the generated plan\npnpm dlx @shadscan/cli --apply --agent codex\n\n# Fail CI when the complete assessed score is below the floor\npnpm dlx @shadscan/cli@0.8.0 --fail-under 80 --no-interactive --no-roast\n\n# Audit one category while investigating a focused area\npnpm dlx @shadscan/cli --category accessibility\n\n# See which workspace packages shadscan found, without scanning\npnpm dlx @shadscan/cli --list-projects\n\n# Scan one package of a monorepo instead of pooling every application\npnpm dlx @shadscan/cli --project apps/web\n```\n\nUse `--format human`\n\n, `--format json`\n\n, or `--format prompt`\n\nwhen output selection\nneeds to be explicit. Pin an exact package version in CI; unqualified commands\nresolve to the latest stable release. Run `pnpm dlx @shadscan/cli --help`\n\nfor\nevery option.\n\nThe repository doubles as a composite GitHub Action that runs the CLI, writes the score to the job summary, enforces an optional score floor, and can create or update a tracked issue containing the findings and a paste-ready AI-agent remediation handoff.\n\n```\nname: shadscan\non:\n  push:\n    branches: [main]\n\npermissions:\n  contents: read\n  issues: write # only needed with create-issue\n\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: TheOrcDev/shadscan@main\n        with:\n          path: .\n          version: 0.8.0 # pin an exact CLI version in CI\n          fail-under: \"80\"\n          create-issue: \"true\"\n```\n\nInputs: `path`\n\n, `version`\n\n, `category`\n\n, `fail-under`\n\n, `create-issue`\n\n,\n`issue-label`\n\n, and `github-token`\n\n. Outputs: `score`\n\n, `grade`\n\n, and\n`report-path`\n\n(the machine-readable JSON report). With `create-issue`\n\n, the\naction keeps a single open issue per label up to date instead of filing a new\nissue on every run, and the issue body embeds the same `--prompt`\n\nhandoff you\nwould generate locally — ready to paste into a coding agent.\n\n`--prompt`\n\nturns the same deterministic report into a neutral, paste-ready plan\nfor another coding agent. The handoff includes:\n\n- prioritized work items grouped as\n`fix`\n\n,`decide`\n\n, or`verify`\n\n; - rule IDs, evidence, suggested fixes, and acceptance criteria;\n- detected framework, package manager, and source-coverage context;\n- repository-owned verification commands that the agent must inspect first;\n- the exact pinned Shadscan command to rescan after the work.\n\n`--apply`\n\nis an explicit local action. It validates an installed Claude Code,\nCodex CLI, or Grok Build executable before launching it. Shadscan itself still\ndoes not make an AI request; the selected external agent follows its own\nprovider and approval model.\n\nThe bundled ruleset contains 59 deterministic checks across six weighted categories.\n\n| Category | Examples |\n|---|---|\n| Foundation | shadcn config, mounted theme provider, metadata, favicon, not-found and error boundaries |\n| Interaction | dark-mode and command-menu shortcuts, safe global hotkeys, mobile navigation, focus visibility |\n| States | loading and Suspense fallbacks, empty states, retryable errors, pending actions, mounted toasts |\n| Accessibility | names and labels, semantic controls, alt text, landmarks, live regions, keyboard and focus behavior |\n| Forms and Data Entry | validation, rendered field errors, error associations, legends, button types, autocomplete |\n| Production Polish | complete metadata, social previews, Button icon spacing, responsive shells, SEO files, mobile overflow |\n\nSee the generated [rule catalog](/TheOrcDev/shadscan/blob/main/docs/rules.md) for every rule ID, confidence\nlevel, score behavior, and supported adapter.\n\nRaw 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.\n\nRules 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.\n\nRun shadscan at a workspace root and it audits every React application it\nfinds, pooling their findings into one score. The report lists each package\nwith its own score so the pooled number is explicable, and `--list-projects`\n\nprints that list without scanning.\n\nPackages are classified as **applications** or **libraries**. A library — a\nReact package with no application entry point — is scanned and reported, but\nits findings do not count toward the score: it has no document shell, so it\nwould fail rules about page titles and favicons that it should never satisfy,\nand pooling those would punish you for owning a design system. Packages that\nshadscan cannot audit at all, such as one that does not declare React, are\nlisted as skipped with the reason.\n\nWorkspaces are found by walking the tree for `package.json`\n\nfiles, so pnpm,\nnpm, yarn, bun, Turborepo, Nx and Lerna all work without configuration. A\nworkspace containing a single application is scanned exactly as before, so the\ncommon \"app at the root plus shared packages\" layout keeps its existing score.\nUse `--project <path>`\n\nto scan one package on its own.\n\nThe [web scanner](https://www.shadscan.com/scan) audits a public GitHub\nrepository without installing the CLI or exposing an API key to the browser.\nGitHub access, extraction, rate limiting, and scanning stay on the server.\n\nFor agent and service integrations, Shadscan also exposes a versioned hosted API for public GitHub repositories and sanitized gzip tar snapshots.\n\n[Pinned agent instructions](https://www.shadscan.com/agent/v1.md)[OpenAPI 3.1 contract](https://www.shadscan.com/openapi.json)[Hosted API setup and security](/TheOrcDev/shadscan/blob/main/docs/hosted-api.md)[Web scanner architecture and deployment](/TheOrcDev/shadscan/blob/main/docs/web-scanner.md)\n\nThe hosted surfaces are opt-in and have separate source-handling contracts from the local CLI.\n\nRepository development uses Node.js 24 and pnpm 11.15.1. The published CLI has a Node.js 18 compatibility floor.\n\n```\npnpm install\npnpm cli:test\npnpm test:api\npnpm test:web\npnpm exec playwright install chromium\npnpm test:e2e\npnpm docs:check\npnpm check\npnpm typecheck\npnpm build\n```\n\nThe product site and its own dogfood target live at the repository root. The\npublished CLI lives in [ packages/cli](/TheOrcDev/shadscan/blob/main/packages/cli).\n\n| Document | Purpose |\n|---|---|\n|\n\n[CLI contract](/TheOrcDev/shadscan/blob/main/docs/cli-contract.md)[Rule catalog](/TheOrcDev/shadscan/blob/main/docs/rules.md)[Hosted API](/TheOrcDev/shadscan/blob/main/docs/hosted-api.md)[Web scanner](/TheOrcDev/shadscan/blob/main/docs/web-scanner.md)[Release guide](/TheOrcDev/shadscan/blob/main/docs/releasing.md)[Security policy](/TheOrcDev/shadscan/blob/main/SECURITY.md)The Shadscan CLI is available under the\n[MIT License](/TheOrcDev/shadscan/blob/main/packages/cli/LICENSE). The header and badges are rendered by\n[shieldcn](https://shieldcn.dev), a shadcn-styled badge and README graphics\nservice.", "url": "https://wpnews.pro/news/shadscan-deterministic-ui-audits-for-shadcn-apps", "canonical_source": "https://github.com/TheOrcDev/shadscan", "published_at": "2026-08-02 12:09:30+00:00", "updated_at": "2026-08-02 12:22:23.263068+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Shadscan", "shadcn", "React", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/shadscan-deterministic-ui-audits-for-shadcn-apps", "markdown": "https://wpnews.pro/news/shadscan-deterministic-ui-audits-for-shadcn-apps.md", "text": "https://wpnews.pro/news/shadscan-deterministic-ui-audits-for-shadcn-apps.txt", "jsonld": "https://wpnews.pro/news/shadscan-deterministic-ui-audits-for-shadcn-apps.jsonld"}}