SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsshadscan

shadscan

General & other

View repository

Updated 10-15 17:23

About this skill

shadscan

shadscan is a deterministic static analyzer for shadcn/React apps. It grades UI fundamentals — same result every run, built for the terminal and CI. Use it to measure and then raise the quality of shadcn components, and to gate merges on a minimum score.

This skill is the driver. The actual fixes belong to the shadcn-capable agents (designer / Ridd, nextjs / Theo); this skill tells you how to run the tool, read the score, and loop until the grade passes.

What it scores

One 0–100 score plus a letter grade, across six categories:

Category What it inspects
foundation Base component setup, tokens, structural correctness
interaction Pointer/keyboard interaction wiring
states hover / focus / active / disabled / loading / error coverage
accessibility Labels, roles, ARIA, contrast, keyboard reachability
forms Form composition, validation, field/label association
production-polish Empty states, responsiveness, finishing details

Command surface

# Audit the project (or a path). Human output with evidence + suggested fixes.
npx @shadscan/cli [path]

# Machine-readable report (schema v4) — parse this in scripts/CI.
npx @shadscan/cli --json

# Paste-ready Markdown handoff for an AI agent — THIS is the fix-loop input.
npx @shadscan/cli --format prompt

# Launch an installed coding agent directly with the findings.
npx @shadscan/cli --apply --agent claude   # or: codex | grok

# Audit one category only (tight loops).
npx @shadscan/cli --category accessibility

# CI gate: exit 1 when the score is below the floor (or can't be assessed).
npx @shadscan/cli --fail-under 85

# Neutral copy for CI/logs (disable the "roast" tone).
npx @shadscan/cli --json --no-roast

# Install a pre-commit hook that runs the scan.
npx @shadscan/cli setup --pre-commit

Other flags: --no-interactive (skip the post-scan menu — always use this in scripts), --roast (force roast copy into JSON/CI), --version, --help.

The audit → fix → re-score loop (how to get a good score)

Do not one-shot fixes and declare victory. Iterate against the tool:

  1. Baseline. Run npx @shadscan/cli <path> --json --no-interactive and record the score, grade, and per-category breakdown. Report the number.
  2. Get the handoff. Run npx @shadscan/cli <path> --format prompt to get the neutral, paste-ready findings, or scan one category with --category to focus. The prompt output is written for an agent — feed it to the fixer.
  3. Fix by category, lowest first. Apply changes with the shadcn patterns the fixer already knows (see mapping below). Never edit components/ui/*.tsx source directly — customize via className/props or re-add with shadcn@latest add <c> --overwrite.
  4. Re-scan only what changed. Re-run on the touched path (or category) and confirm the score moved up. If a category didn't improve, read its evidence again — the tool cites exact locations.
  5. Repeat until the grade meets the target (or --fail-under passes).
  6. Report the delta. State before → after score and which categories moved.

Category → fixer knowledge

The categories map almost 1:1 onto patterns the designer (Ridd) agent already documents — reuse them rather than inventing fixes:

  • accessibility → Ridd's Accessibility Checklist (labels, ARIA, focus order, contrast ≥ 4.5:1).
  • states → Ridd's States list: implement hover, focus, active, disabled, loading, and error for every interactive element.
  • forms → Ridd's react-hook-form + zod Form pattern (FormField/FormLabel/ FormMessage association).
  • foundation / interaction / production-polish → composition and app-integration concerns; hand to nextjs (Theo) when the fix is structural or data-bound, keep with Ridd when it's presentational.

Agent handoff modes

  • Advisory (default in this repo): --format prompt → paste the findings to the fixer agent, apply, re-scan. Keeps the human/agent in control of edits.
  • Direct: --apply --agent claude launches Claude Code with the handoff. Use when you want the tool to drive the agent end-to-end.

CI gate (checker-owned)

The tester (Jason) agent owns the gate, not the fix:

  • Threshold: add npx @shadscan/cli . --fail-under <N> --no-interactive --no-roast as a CI step. Non-zero exit fails the build.
  • GitHub Action: shadscan ships .github/workflows/shadscan.yml. Inputs: path, version, category, fail-under, create-issue, issue-label, github-token. Outputs: score, grade, report-path — surface these in the PR.
  • Pre-commit: npx @shadscan/cli setup --pre-commit for local enforcement.

See references/reference.md for the full flag list, JSON schema notes, a ready-to-drop Action workflow, and a per-category fix playbook.