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:
- Baseline. Run
npx @shadscan/cli <path> --json --no-interactive and
record the score, grade, and per-category breakdown. Report the number.
- 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.
- 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.
- 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.
- Repeat until the grade meets the target (or
--fail-under passes).
- 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.
1---2name: shadscan3description: This skill should be used when the user asks to "audit my shadcn app", "run shadscan", "improve my shadscan score", "raise my shadscan grade", "fix accessibility/states/forms regressions in my shadcn components", or "add a shadscan CI gate". Drives the shadscan static analyzer (`npx @shadscan/cli`) through an audit → fix → re-score loop against shadcn React components, and wires it into CI as a score gate.4---56# shadscan78`shadscan` is a **deterministic static analyzer for shadcn/React apps**. It9grades UI fundamentals — same result every run, built for the terminal and CI.10Use it to measure and then *raise* the quality of shadcn components, and to gate11merges on a minimum score.1213This skill is the driver. The actual fixes belong to the shadcn-capable agents14(`designer` / Ridd, `nextjs` / Theo); this skill tells you how to run the tool,15read the score, and loop until the grade passes.1617## What it scores1819One `0–100` score plus a letter grade, across six categories:2021| Category | What it inspects |22|----------|------------------|23| `foundation` | Base component setup, tokens, structural correctness |24| `interaction` | Pointer/keyboard interaction wiring |25| `states` | hover / focus / active / disabled / loading / error coverage |26| `accessibility` | Labels, roles, ARIA, contrast, keyboard reachability |27| `forms` | Form composition, validation, field/label association |28| `production-polish` | Empty states, responsiveness, finishing details |2930## Command surface3132```bash33# Audit the project (or a path). Human output with evidence + suggested fixes.34npx @shadscan/cli [path]3536# Machine-readable report (schema v4) — parse this in scripts/CI.37npx @shadscan/cli --json3839# Paste-ready Markdown handoff for an AI agent — THIS is the fix-loop input.40npx @shadscan/cli --format prompt4142# Launch an installed coding agent directly with the findings.43npx @shadscan/cli --apply --agent claude # or: codex | grok4445# Audit one category only (tight loops).46npx @shadscan/cli --category accessibility4748# CI gate: exit 1 when the score is below the floor (or can't be assessed).49npx @shadscan/cli --fail-under 855051# Neutral copy for CI/logs (disable the "roast" tone).52npx @shadscan/cli --json --no-roast5354# Install a pre-commit hook that runs the scan.55npx @shadscan/cli setup --pre-commit56```5758Other flags: `--no-interactive` (skip the post-scan menu — always use this in59scripts), `--roast` (force roast copy into JSON/CI), `--version`, `--help`.6061## The audit → fix → re-score loop (how to get a good score)6263Do not one-shot fixes and declare victory. Iterate against the tool:64651. **Baseline.** Run `npx @shadscan/cli <path> --json --no-interactive` and66 record the score, grade, and per-category breakdown. Report the number.672. **Get the handoff.** Run `npx @shadscan/cli <path> --format prompt` to get68 the neutral, paste-ready findings, or scan one category with `--category`69 to focus. The `prompt` output is written *for* an agent — feed it to the70 fixer.713. **Fix by category, lowest first.** Apply changes with the shadcn patterns72 the fixer already knows (see mapping below). Never edit73 `components/ui/*.tsx` source directly — customize via `className`/props or74 re-add with `shadcn@latest add <c> --overwrite`.754. **Re-scan only what changed.** Re-run on the touched path (or category) and76 confirm the score moved up. If a category didn't improve, read its evidence77 again — the tool cites exact locations.785. **Repeat** until the grade meets the target (or `--fail-under` passes).796. **Report the delta.** State before → after score and which categories moved.8081### Category → fixer knowledge8283The categories map almost 1:1 onto patterns the `designer` (Ridd) agent already84documents — reuse them rather than inventing fixes:8586- `accessibility` → Ridd's Accessibility Checklist (labels, ARIA, focus order,87 contrast ≥ 4.5:1).88- `states` → Ridd's States list: implement hover, focus, active, disabled,89 loading, **and** error for every interactive element.90- `forms` → Ridd's react-hook-form + zod Form pattern (`FormField`/`FormLabel`/91 `FormMessage` association).92- `foundation` / `interaction` / `production-polish` → composition and93 app-integration concerns; hand to `nextjs` (Theo) when the fix is structural94 or data-bound, keep with Ridd when it's presentational.9596## Agent handoff modes9798- **Advisory (default in this repo):** `--format prompt` → paste the findings to99 the fixer agent, apply, re-scan. Keeps the human/agent in control of edits.100- **Direct:** `--apply --agent claude` launches Claude Code with the handoff.101 Use when you want the tool to drive the agent end-to-end.102103## CI gate (checker-owned)104105The `tester` (Jason) agent owns the gate, not the fix:106107- **Threshold:** add `npx @shadscan/cli . --fail-under <N> --no-interactive108 --no-roast` as a CI step. Non-zero exit fails the build.109- **GitHub Action:** shadscan ships `.github/workflows/shadscan.yml`. Inputs:110 `path`, `version`, `category`, `fail-under`, `create-issue`, `issue-label`,111 `github-token`. Outputs: `score`, `grade`, `report-path` — surface these in112 the PR.113- **Pre-commit:** `npx @shadscan/cli setup --pre-commit` for local enforcement.114115See `references/reference.md` for the full flag list, JSON schema notes, a116ready-to-drop Action workflow, and a per-category fix playbook.
b-open-io