spectrum-audit

Spectrum Audit

Audit a codebase for adherence to the Spectrum design system and React Spectrum S2 best practices, then produce a scored, prioritized report. This skill is report-only — it does not modify any files.

When to use

Use when a developer asks to audit, review, lint, or check a project for Spectrum / S2 correctness, configuration, styling, accessibility, or component-usage issues.

Requires a project with @react-spectrum/s2 installed. If S2 is not a dependency, say so and stop.

How it works

Run these phases in order.

Phase 0 — Scope

• Identify the project — or, in a monorepo, the specific package — to audit. Audit the package, not the workspace root.
• Detect the package manager from the lockfile, the bundler (Vite / webpack / Next.js / Parcel / Rollup / ESBuild), and read package.json dependencies.
• Confirm @react-spectrum/s2 is installed. Establish the source globs to scan (e.g. src/**/*.{tsx,jsx,ts,js}).
• Check whether the react-spectrum-s2 skill is available (listed among the agent's installed skills, or present under a local skills directory such as .cursor/skills/ or .agents/skills/). Record whether it was found — the report template uses this.

Phase 1 — Run the checks

Work through each check file in references/checks/, in order. For every violation, record a finding: {file:line, rule, severity, category, fix}. Cite only line numbers you actually read or grepped — never invent locations. Record one finding per distinct root cause at a file:line — if multiple check files cover the same issue (e.g. a missing collection aria-label or a third-party design system), assign it to the most specific check and do not duplicate it across categories.

• 01 — Setup & configuration
• 02 — Component usage
• 03 — Styling
• 04 — Accessibility & correctness
• 05 — Versioning & maintenance
• 06 — Testing

The canonical rules behind these checks live in the react-spectrum-s2 skill — read its SKILL.md (implementation guidance) and references/guides/getting-started.md, references/guides/component-decision-tree.md, and references/components/ as needed. If that skill is not installed, proceed using the check files alone, but note the limitation in the report (see Phase 3).

Phase 2 — Score

Apply the scoring rubric to the recorded findings to compute per-category scores and the overall Spectrum Adherence Score. The score is arithmetic over counted findings — do not estimate it.

Phase 3 — Report

Write SPECTRUM-AUDIT.md to the audited project following the report template: headline score, grade, and severity counts; a summary; scores by category; findings grouped by severity (each with a clickable file:line and the check name that defines its rule); prioritized action items; what looks good; and — if react-spectrum-s2 was not detected in Phase 0 — a recommendation to install it.

Phase 4 — Hand off

This skill does not edit code. Recommend:

• The react-spectrum-s2 skill to implement the fixes. If it is not installed:

  npx skills add https://react-spectrum.adobe.com --skill react-spectrum-s2
  

• The migrate-react-spectrum-v3-to-s2 skill if Spectrum 1 packages (@adobe/react-spectrum, @react-spectrum/*, @spectrum-icons/*) are present.