From d2ac9149bcfb6248cd531a0ee238e92cfb45ff74 Mon Sep 17 00:00:00 2001
From: Reid Barber <reid@reidbarber.com>
Date: Fri, 5 Jun 2026 13:44:26 -0500
Subject: [PATCH] initialize spectrum-audit skill

---
 .../s2-docs/scripts/generateAgentSkills.mjs   | 129 ++++++++++++++++++
 .../spectrum-audit/checks/01-setup-config.md  |  53 +++++++
 .../checks/02-component-usage.md              |  37 +++++
 .../spectrum-audit/checks/03-styling.md       |  47 +++++++
 .../spectrum-audit/checks/04-accessibility.md |  30 ++++
 .../spectrum-audit/checks/05-versioning.md    |  18 +++
 .../spectrum-audit/checks/06-testing.md       |  12 ++
 .../skills/spectrum-audit/report-template.md  |  61 +++++++++
 .../skills/spectrum-audit/scoring-rubric.md   |  56 ++++++++
 9 files changed, 443 insertions(+)
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/report-template.md
 create mode 100644 packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md

diff --git a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
index 8815e2e12c2..52d6c869b7a 100644
--- a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
+++ b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
@@ -28,6 +28,11 @@ const MARKDOWN_DOCS_DIST = path.join(REPO_ROOT, 'packages/dev/s2-docs/dist');
 const MDX_PAGES_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/pages');
 const MARKDOWN_DOCS_SCRIPT = path.join(__dirname, 'generateMarkdownDocs.mjs');
 const MIGRATION_REFS_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/migration-references');
+const AUDIT_SKILL_SOURCE_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/skills/spectrum-audit');
+const RSP_S2_SKILL_SOURCE_DIR = path.join(
+  REPO_ROOT,
+  'packages/dev/s2-docs/skills/react-spectrum-s2'
+);
 const WELL_KNOWN_DIR = '.well-known';
 const WELL_KNOWN_SKILLS_DIR = 'skills';
 
@@ -79,6 +84,19 @@ const SKILLS = {
       author: 'Adobe',
       website: 'https://react-aria.adobe.com/'
     }
+  },
+  'spectrum-audit': {
+    name: 'spectrum-audit',
+    description:
+      'Audit a codebase for adherence to the Spectrum design system and React Spectrum S2 best practices. Use when a developer asks to audit, review, lint, or check a project for Spectrum/S2 correctness, configuration, styling, accessibility, or component-usage issues.',
+    kind: 'audit',
+    license: 'Apache-2.0',
+    sourceDir: 's2',
+    compatibility: 'Requires a React project using @react-spectrum/s2.',
+    metadata: {
+      author: 'Adobe',
+      website: 'https://react-spectrum.adobe.com/'
+    }
   }
 };
 
@@ -665,6 +683,59 @@ Use these when you need more component-by-component or API-level detail:
   );
 }
 
+function generateAuditSkillMd(skillConfig) {
+  return (
+    `${generateFrontmatter(skillConfig)}# 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}\`).
+
+### 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.
+
+- [01 — Setup & configuration](references/checks/01-setup-config.md)
+- [02 — Component usage](references/checks/02-component-usage.md)
+- [03 — Styling](references/checks/03-styling.md)
+- [04 — Accessibility & correctness](references/checks/04-accessibility.md)
+- [05 — Versioning & maintenance](references/checks/05-versioning.md)
+- [06 — Testing](references/checks/06-testing.md)
+
+The canonical rules behind these checks live in [Implementation guidance](references/docs-implementation-guidance.md) and [Getting started](references/docs-getting-started.md). When you need a component's API or the canonical component list to judge a finding, use the \`react-spectrum-s2\` skill if it is installed.
+
+### Phase 2 — Score
+
+Apply the [scoring rubric](references/scoring-rubric.md) 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](references/report-template.md): headline score, grade, and severity counts; a summary; scores by category; findings grouped by severity (each with a clickable \`file:line\` and a link to its check file); prioritized action items; and what looks good.
+
+### Phase 4 — Hand off
+
+This skill does not edit code. Recommend:
+
+- The \`react-spectrum-s2\` skill to implement the fixes.
+- The \`migrate-react-spectrum-v3-to-s2\` skill if Spectrum 1 packages (\`@adobe/react-spectrum\`, \`@react-spectrum/*\`, \`@spectrum-icons/*\`) are present.
+`.trimEnd() + '\n'
+  );
+}
+
 /**
  * Copy documentation files to the skill's references directory.
  */
@@ -823,6 +894,52 @@ function writeMigrationReferences(skillDir, sourceDir) {
   ]);
 }
 
+function writeAuditReferences(skillDir, sourceDir) {
+  const refsDir = path.join(skillDir, 'references');
+  fs.mkdirSync(refsDir, {recursive: true});
+
+  // Copy authored audit check files.
+  const checksSourceDir = path.join(AUDIT_SKILL_SOURCE_DIR, 'checks');
+  const checksTargetDir = path.join(refsDir, 'checks');
+  fs.mkdirSync(checksTargetDir, {recursive: true});
+  for (const file of fs.readdirSync(checksSourceDir)) {
+    if (file.endsWith('.md')) {
+      fs.copyFileSync(path.join(checksSourceDir, file), path.join(checksTargetDir, file));
+    }
+  }
+
+  // Copy the authored scoring rubric and report template.
+  for (const file of ['scoring-rubric.md', 'report-template.md']) {
+    fs.copyFileSync(path.join(AUDIT_SKILL_SOURCE_DIR, file), path.join(refsDir, file));
+  }
+
+  // Reuse the generated getting-started doc as the canonical setup reference.
+  copyFocusedDocs(sourceDir, skillDir, [['getting-started.md', 'docs-getting-started.md']]);
+
+  // Reuse the canonical S2 implementation guidance and component decision tree (single source of
+  // truth — don't restate the rules in the audit). Resolve the {{...}} doc-link tokens to the
+  // co-generated react-spectrum-s2 skill's references, which share this skill's parent directory.
+  const guidanceReplacements = {
+    '{{guidesBase}}': '../react-spectrum-s2/references/guides/',
+    '{{componentsBase}}': '../react-spectrum-s2/references/components/',
+    '{{testingBase}}': '../react-spectrum-s2/references/testing/'
+  };
+  fs.writeFileSync(
+    path.join(refsDir, 'docs-implementation-guidance.md'),
+    renderCustomMarkdown(
+      path.join(RSP_S2_SKILL_SOURCE_DIR, 'implementation-guidance.md'),
+      guidanceReplacements
+    ) + '\n'
+  );
+  fs.writeFileSync(
+    path.join(refsDir, 'docs-component-decision-tree.md'),
+    renderCustomMarkdown(
+      path.join(RSP_S2_SKILL_SOURCE_DIR, 'component-decision-tree.md'),
+      guidanceReplacements
+    ) + '\n'
+  );
+}
+
 function collectSkillFiles(skillDir) {
   const files = [];
 
@@ -918,6 +1035,18 @@ function generateSkill(skillConfig, wellKnownRoot) {
     return skillDir;
   }
 
+  if (skillConfig.kind === 'audit') {
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), generateAuditSkillMd(skillConfig));
+    console.log(`Generated ${path.relative(REPO_ROOT, path.join(skillDir, 'SKILL.md'))}`);
+
+    writeAuditReferences(skillDir, skillConfig.sourceDir);
+    console.log(
+      `Copied audit references to ${path.relative(REPO_ROOT, path.join(skillDir, 'references'))}`
+    );
+
+    return skillDir;
+  }
+
   const isS2 = skillConfig.name === 'react-spectrum-s2';
 
   // Parse documentation entries
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md
new file mode 100644
index 00000000000..a48a16f7f2e
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/01-setup-config.md
@@ -0,0 +1,53 @@
+# Check 01 — Setup & configuration
+
+Validates that the project is configured the way [Getting started](../docs-getting-started.md) specifies. Misconfiguration here is high-impact: the `style` macro silently no-ops, CSS bloats, or strings for 30+ languages ship to every user.
+
+Read first: `../docs-getting-started.md` (canonical setup), plus the project's `package.json` and bundler config file.
+
+## Detection inputs (gathered in Phase 0)
+
+- **Package manager:** lockfile — `yarn.lock`, `package-lock.json`, or `pnpm-lock.yaml`.
+- **Bundler:** `vite.config.*`, `webpack.config.*`, `next.config.*`, `.parcelrc` / a `parcel` dependency, `rollup.config.*`, or an esbuild build script.
+- **Installed deps:** `dependencies` / `devDependencies` in `package.json`.
+
+## Checks
+
+### `@react-spectrum/s2` is installed
+- **Detect:** `@react-spectrum/s2` present in `package.json`. If absent, the audit does not apply — stop and tell the user.
+- **Severity:** — (precondition)
+
+### Style macro plugin configured
+- **Rule:** Non-Parcel bundlers must wire `unplugin-parcel-macros` into the build; Parcel needs ≥ 2.12.0. Without it, `style({...})` calls are never evaluated at build time and components render unstyled.
+- **Detect:**
+  - Vite/Rollup/React Router/ESBuild/webpack/Next: `unplugin-parcel-macros` in deps **and** referenced in the bundler config (`macros.vite()`, `macros.webpack()`, `macros.rollup()`, `macros.esbuild()`).
+  - Parcel: `parcel` ≥ 2.12.0 (macros are built in) — no plugin needed.
+  - Next.js: also confirm the app starts with `--webpack` (not Turbopack) — check the `dev`/`build` scripts. `unplugin-parcel-macros` does not work with Turbopack.
+- **Severity:** Critical.
+
+### CSS bundle optimization
+- **Rule:** All S2 + macro-generated CSS should be combined into a single shared `s2-styles` bundle rather than code-split per route. Atomic CSS overlaps heavily between components, so loading it up front is smaller than duplicating it across chunks.
+- **Detect:**
+  - Parcel: `@parcel/bundler-default.manualSharedBundles` with an `s2-styles` entry in the root `package.json`.
+  - webpack/Next: `optimization.splitChunks.cacheGroups` with an `s2`/`s2-styles` group testing for `@react-spectrum/s2` and `macro-*.css`.
+  - Vite/Rollup/React Router: `build.rollupOptions.output.manualChunks` returning `'s2-styles'` for `macro-*.css` and `@react-spectrum/s2/*.css`.
+- **Severity:** High.
+
+### lightningcss minification
+- **Rule:** Compile/minify CSS with lightningcss — it produces a much smaller bundle and dedupes atomic rules.
+- **Detect:** `cssMinify: 'lightningcss'` (Vite/React Router) or `CssMinimizerPlugin.lightningCssMinify` (webpack/Next).
+- **Severity:** Medium.
+
+### Locale optimization
+- **Rule:** S2 ships localized strings for 30+ languages by default. Projects should install the locale optimization plugin and declare only the languages they support.
+- **Detect:** `@react-aria/optimize-locales-plugin` (webpack/Vite/Rollup/React Router/ESBuild) or `@react-aria/parcel-resolver-optimize-locales` (Parcel) installed **and** configured with a `locales` list.
+- **Severity:** Medium.
+
+### Single root Provider, wired to the router
+- **Rule:** Mount one `Provider` from `@react-spectrum/s2/Provider` at the app root, wired to the client router; SSR frameworks (Next.js, React Router) set `locale` from the server request and render `Provider` with `elementType="html"`.
+- **Detect:** exactly one root `Provider`; a `router={{navigate}}` prop; for Next/RR, a server-derived locale. Flag a missing `router`, or SSR setups that don't sync the locale.
+- **Severity:** High. (Provider *scope* misuse — stacking, hard-coded `colorScheme` — is in [04-accessibility](04-accessibility.md).)
+
+### React 19
+- **Rule:** React 19 is recommended for S2.
+- **Detect:** `react` version in `package.json`.
+- **Severity:** Low.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md
new file mode 100644
index 00000000000..fabef2c72e3
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/02-component-usage.md
@@ -0,0 +1,37 @@
+# Check 02 — Component usage
+
+Validates that the project uses S2 components where they exist, builds custom components on React Aria Components + the `style` macro, and follows S2 composition and collection conventions. This is the most judgment-heavy category — read the component's docs (via the `react-spectrum-s2` skill, if installed) before flagging.
+
+Canonical rules: `../docs-implementation-guidance.md` (Component composition, Collections, Typography, Form fields). Reverse-lookup help ("is there an S2 component for this?"): `../docs-component-decision-tree.md`.
+
+## Checks
+
+### Use an S2 component where one exists
+- **Rule:** Prefer S2 components over hand-rolled UI. S2 covers ~85 components — Button, Picker, ComboBox, Menu, Dialog/AlertDialog, Card/CardView, TableView, ListView, Tabs, and more.
+- **Detect:** hand-rolled equivalents — `<div role="button|dialog|menu|listbox|tablist">`, custom dropdown/modal/tooltip implementations, native `<button>`/`<select>` styled to look like Spectrum, native `<table>` for data grids. Cross-check candidates against the canonical component list (`@react-spectrum/s2` exports / the `react-spectrum-s2` skill).
+- **Severity:** High.
+
+### Custom components build on RAC + the style macro
+- **Rule:** When no S2 component fits, build the custom component on React Aria Components (for behavior + accessibility) and style it with the `style` macro — not raw divs with click handlers.
+- **Detect:** interactive custom components using bare `<div onClick>` / `<div onKeyDown>` / `<span onClick>` instead of an RAC primitive or an S2 component.
+- **Severity:** High (accessibility regressions).
+
+### Typed item components
+- **Rule:** Each collection has its own item export — `MenuItem`, `PickerItem`, `ComboBoxItem`, `ListViewItem`, `TreeViewItem`, `Row`/`Cell`/`Column`, `Tag`, `Breadcrumb`, `AccordionItem`, etc. There is no generic `Item`.
+- **Detect:** a generic `Item`/`Section` import in S2 code (usually a Spectrum 1 leftover), or the wrong item type nested inside a collection.
+- **Severity:** Medium.
+
+### Collection conventions
+- **Rule:** Collection items need an `id` (and React `key` when built with `.map`); items whose children aren't plain text need `textValue`; the collection container needs `aria-label`/`aria-labelledby`; virtualized collections must not be wrapped in an `overflow` container; empty/loading/bulk-action UI uses the built-in `renderEmptyState` / `loadingState` / `renderActionBar`.
+- **Detect:** items lacking `id`; non-text item children without `textValue`; a collection with no accessible name; an `overflow*` wrapper around `TableView`/`ListView`/`CardView`/`TreeView`/`Menu`/`ListBox`; hand-rolled empty/spinner/bulk-action UI replacing the built-ins.
+- **Severity:** High for missing `id` / `aria-label` / `textValue` (breaks selection, keyboard nav, screen readers); Medium for the rest.
+
+### Don't reinvent Card / CardView
+- **Rule:** For grids of objects/files/products/people, use `CardView` with a variant (`AssetCard`, `UserCard`, `ProductCard`) or `Card` composed from `CardPreview`/`Content`/`Text`/`Footer`.
+- **Detect:** hand-rolled card `<div>` / `<article>` grids reproducing card layout.
+- **Severity:** Medium.
+
+### Slot discipline
+- **Rule:** Only pass `slot` values the parent documents, and don't inject wrapper elements where a component expects specific slot children.
+- **Detect:** `<div>`/`<span>` wrapping collection-item children; `slot=` values the parent component doesn't define (e.g. `slot="close"` on an arbitrary button).
+- **Severity:** Medium.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md
new file mode 100644
index 00000000000..75033265b0a
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/03-styling.md
@@ -0,0 +1,47 @@
+# Check 03 — Styling
+
+Validates that styling goes through S2 components and the `style` macro with tokens — not escape hatches, raw CSS, or third-party styling systems. Canonical rules: `../docs-implementation-guidance.md` (Styling and Icons sections).
+
+Search the source globs (e.g. `**/*.{tsx,jsx,ts,js}`) for the patterns below.
+
+## Checks
+
+### No `UNSAFE_style` / `UNSAFE_className`
+- **Rule:** Avoid `UNSAFE_style` and `UNSAFE_className`; they bypass tokens and the style layer ordering.
+- **Detect:** grep `UNSAFE_style|UNSAFE_className`.
+- **Severity:** High.
+
+### No concatenation of macro output
+- **Rule:** `style()` results encode style precedence; concatenating them with template literals, `clsx`, `classnames`, or string spaces breaks ordering. Express variation in one `style({...})` call with runtime conditions, or use `mergeStyles`.
+- **Detect:** macro results combined via `` `${style(...)} ...` ``, `clsx(`/`classNames(` wrapping `style(`, or Tailwind utility classes alongside S2 components. grep `clsx|classnames`, `tailwind`, and template-literal `className`s containing `style(`.
+- **Severity:** High.
+
+### No inline `style` alongside the macro
+- **Rule:** Don't combine `className={style({...})}` (or the `styles` prop) with an inline `style={{...}}` on the same element — inline styles bypass tokens and break layer ordering. Inline `style` is only for values genuinely unknowable at build time (e.g. a drag position).
+- **Detect:** elements carrying both `style={{` and `style(` / `styles=`.
+- **Severity:** Medium.
+
+### Tokens, not raw CSS values
+- **Rule:** Macro values are typed tokens, not raw CSS. No hex / `rgb()` / `var()` colors; no string units like `'1rem'` / `'100%'` (use numbers on the 4px grid, or `'full'`); no `'flex-start'` / `'flex-end'` (use `'start'` / `'end'`); no physical sides (use logical `paddingStart`/`marginEnd`/`insetStart`/`borderStartStartRadius` so they flip under RTL).
+- **Detect:** inside `style(` / `styles=`: `#` hex colors, `rgb(`, `var(--`, quoted units (`'…rem'`, `'…px'`, `'…%'`), `'flex-start'`/`'flex-end'`, and physical props `paddingLeft|paddingRight|marginLeft|marginRight|borderTopLeftRadius|borderTopRightRadius`.
+- **Severity:** Medium. Prefer **semantic** color tokens (`accent`, `neutral`, `negative`, `positive`, `informative`, `notice`) where color carries meaning, over raw hue tokens (`red-…`, `blue-…`).
+
+### The `styles` prop is layout-only
+- **Rule:** The `styles` prop on S2 components is restricted to layout properties (margin, width, flex, grid placement, position, z-index, visibility). Non-layout properties belong on a native element's `className={style(...)}`.
+- **Detect:** `styles={style({` on an S2 component containing `backgroundColor`, `color`, `font`, `borderWidth`, or `padding`.
+- **Severity:** Medium.
+
+### Subpath imports, not the barrel
+- **Rule:** Import components from their subpath (`@react-spectrum/s2/Button`), not the package barrel (`@react-spectrum/s2`). Shared types and list-data hooks (`useListData`, `Key`, `Selection`, …) are the exception — they're re-exported from the barrel.
+- **Detect:** a named **component** import from the root: `import {Button|Picker|…} from '@react-spectrum/s2'`.
+- **Severity:** Low.
+
+### No third-party icon or design-system libraries
+- **Rule:** Use S2 icons/illustrations and components. Don't introduce `lucide-react`, `heroicons`, `phosphor-icons`, `react-icons`, or whole design systems (MUI, Chakra, Radix, shadcn/ui, Ant Design) in S2 code.
+- **Detect:** imports from those packages.
+- **Severity:** Medium for icon libraries; High for a competing design system (overlaps with [02-component-usage](02-component-usage.md)).
+
+### Don't restate default prop values
+- **Rule:** Setting a prop to its default — `variant="primary"`, `size="M"`, `density="regular"` — is noise.
+- **Detect:** those literal default props on S2 components.
+- **Severity:** Low.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md
new file mode 100644
index 00000000000..7b126f5e172
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/04-accessibility.md
@@ -0,0 +1,30 @@
+# Check 04 — Accessibility & correctness
+
+Catches accessibility regressions and slot / Provider misuse that S2 otherwise handles for you. Canonical rules: `../docs-implementation-guidance.md` (Buttons with text and icon, Typography, Form fields, Provider scope).
+
+## Checks
+
+### Accessible names
+- **Rule:** Icon-only buttons and every collection container need an accessible name.
+- **Detect:** `Button` / `ActionButton` with only an icon child and no `aria-label`; collections (`ListView`, `TableView`, `CardView`, `TreeView`, `Menu`, `ListBox`, `GridList`, `TagGroup`, `Breadcrumbs`) without `aria-label` / `aria-labelledby`.
+- **Severity:** High.
+
+### Icon + text buttons wrap the label in `Text`
+- **Rule:** A button with **both** an icon and a label must wrap the label in `<Text>`; a bare string sibling next to an icon renders incorrectly.
+- **Detect:** `Button` / `ActionButton` / `LinkButton` with an icon child and a bare string sibling (no `<Text>`).
+- **Severity:** Medium.
+
+### Slot components only inside their slot context
+- **Rule:** `Text`, `Heading`, and `Content` are slot components — standalone (outside a card, dialog, list, picker, menu, tab, etc.) they don't produce correct typography. Use a native element + the `style` macro instead.
+- **Detect:** `<Heading>` / `<Text>` / `<Content>` rendered outside a component that provides their slot.
+- **Severity:** Medium.
+
+### Form fields use props, not wrappers
+- **Rule:** S2 fields render their own label, description, error message, and required indicator. Pass these as props (`label`, `description`, `errorMessage`, `isRequired`, `contextualHelp`) — don't wrap a field in a `<label>` / `<p>` / `<div>` to attach them.
+- **Detect:** an S2 field wrapped in `<label>`, or a sibling `<p>`/`<span>` used as its label or help text.
+- **Severity:** Medium.
+
+### Provider scope and color scheme
+- **Rule:** One root Provider; don't stack Providers (nesting is only for scoping a different `locale`/`router`/`colorScheme` to a subtree); let the Provider manage `colorScheme` — use `lightDark()` for one-off color differences rather than hard-coding `colorScheme="light"|"dark"`.
+- **Detect:** more than one `Provider`; a hard-coded `colorScheme` prop on `Provider`. (Root-Provider setup is in [01-setup-config](01-setup-config.md).)
+- **Severity:** Medium.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md
new file mode 100644
index 00000000000..64aea5673c2
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/05-versioning.md
@@ -0,0 +1,18 @@
+# Check 05 — Versioning & maintenance
+
+## Checks
+
+### On the latest `@react-spectrum/s2`
+- **Rule:** Use the latest S2 release.
+- **Detect:** read the installed `@react-spectrum/s2` version (from the lockfile or `package.json`) and compare against the latest published version (`npm view @react-spectrum/s2 version`, if network access is available; otherwise note that it couldn't be checked).
+- **Severity:** Medium if behind by a minor/patch; High if a major version behind.
+
+### No Spectrum 1 + Spectrum 2 mixing
+- **Rule:** A codebase shouldn't straddle Spectrum 1 and Spectrum 2 long-term.
+- **Detect:** `@react-spectrum/s2` present **and** any Spectrum 1 packages — `@adobe/react-spectrum`, `@react-spectrum/*` (other than `/s2`), or `@spectrum-icons/*` — in `package.json` or imported in source.
+- **Severity:** High. **Hand off:** recommend the `migrate-react-spectrum-v3-to-s2` skill.
+
+### No deprecated props
+- **Rule:** Avoid props marked deprecated in the current S2 docs.
+- **Detect:** cross-check the props in use against the component docs (via the `react-spectrum-s2` skill).
+- **Severity:** Medium.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md b/packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md
new file mode 100644
index 00000000000..8519f8bd540
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/checks/06-testing.md
@@ -0,0 +1,12 @@
+# Check 06 — Testing
+
+Lowest-weight category. Only applies if the project has tests that exercise S2 components.
+
+## Checks
+
+### Use the ARIA pattern testers
+- **Rule:** Test S2 components with the ARIA pattern testers from `@react-spectrum/test-utils` rather than hand-rolled role/selector queries. The testers model real user interaction (open a menu, select a row, toggle a checkbox) and stay correct as internal DOM changes.
+- **Detect:** tests that render S2 collections or overlays and query them with raw `getByRole` / `container.querySelector` chains instead of the `@react-spectrum/test-utils` testers.
+- **Severity:** Low.
+
+If the project has no tests touching S2 components, score this category **100** and label it "not applicable" in the report.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/report-template.md b/packages/dev/s2-docs/skills/spectrum-audit/report-template.md
new file mode 100644
index 00000000000..7ef5239cefc
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/report-template.md
@@ -0,0 +1,61 @@
+# Spectrum Audit report format
+
+Write the report to `SPECTRUM-AUDIT.md` in the audited project (or the audited package's root in a monorepo). Use this structure exactly.
+
+## Template
+
+```markdown
+# Spectrum Audit: <project name>
+
+**Spectrum Adherence Score: <score>/100 (<grade>)**
+<n> Critical · <n> High · <n> Medium · <n> Low
+
+## Summary
+
+<2–3 sentences: the overall state of Spectrum/S2 adherence, the single most important thing to fix, and one thing the project does well.>
+
+## Scores by category
+
+| Category | Grade | Findings |
+|----------|-------|----------|
+| Setup & configuration | <A–F> | <count> |
+| Styling | <A–F> | <count> |
+| Component usage | <A–F> | <count> |
+| Accessibility | <A–F> | <count> |
+| Versioning & maintenance | <A–F> | <count> |
+| Testing | <A–F> | <count> |
+
+## Findings
+
+Group by severity, highest first; omit empty groups. One bullet per finding:
+
+### Critical
+- `path/to/file.tsx:42` — **<rule>**. <Why it matters, one line.> _Fix:_ <remediation>. ([03-styling](references/checks/03-styling.md))
+
+### High
+…
+
+### Medium
+…
+
+### Low
+…
+
+## Action items
+
+- **Fix now** (Critical + High) — most impactful first.
+- **Improve** (Medium).
+- **Polish** (Low).
+- **Follow-ups** — e.g. upgrade to the latest `@react-spectrum/s2`; run the migration skill for remaining Spectrum 1 packages; move to React 19.
+
+## What looks good
+
+- <Genuine positives: correct build setup, good token usage, proper component composition.>
+```
+
+## Rules
+
+- Every finding cites a real `file:line` you actually read or grepped. Never invent locations.
+- Render `file:line` as a clickable link so the user can jump straight to it.
+- Link each finding back to the `references/checks/*.md` file that defines its rule.
+- The audit is **report-only** — do not edit any files. Hand fixes to the `react-spectrum-s2` skill.
diff --git a/packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md b/packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md
new file mode 100644
index 00000000000..db1a2001830
--- /dev/null
+++ b/packages/dev/s2-docs/skills/spectrum-audit/scoring-rubric.md
@@ -0,0 +1,56 @@
+# Spectrum Adherence Scoring
+
+The Spectrum Adherence Score is computed **deterministically** from the findings you recorded — never from a subjective sense of overall quality. The same set of findings must always produce the same score. Do not round, fudge, or "feel out" a number; run the arithmetic below.
+
+## Severity weights
+
+Each finding contributes points equal to its severity:
+
+| Severity | Weight | Meaning |
+|----------|--------|---------|
+| Critical | 10 | Breaks the build, breaks accessibility, or ships visibly broken styling to users. |
+| High | 5 | Wrong approach that will cause real problems — `UNSAFE_*`, bypassing the design system, missing CSS-bundle optimization. |
+| Medium | 2 | Missed reuse or a convention violation that degrades quality but still works. |
+| Low | 1 | Polish: redundant default props, minor token choices, naming. |
+
+## Per-category score
+
+For each of the six categories:
+
+```
+categoryScore = 100 − min(100, Σ severityWeight for findings in that category)
+```
+
+A category with no findings scores 100. A category with one Critical + two Medium findings scores `100 − (10 + 2 + 2) = 86`. The `min(…, 100)` caps deductions so one very-noncompliant category can't push a score below 0.
+
+## Overall score
+
+The overall score is the weighted average of the six category scores:
+
+| Category | Weight |
+|----------|--------|
+| Setup & configuration | 25% |
+| Styling | 20% |
+| Component usage | 20% |
+| Accessibility | 20% |
+| Versioning & maintenance | 10% |
+| Testing | 5% |
+
+```
+overall = round( Σ (categoryScore × categoryWeight) )
+```
+
+## Grade bands
+
+| Score | Grade |
+|-------|-------|
+| 90–100 | A |
+| 80–89 | B |
+| 70–79 | C |
+| 60–69 | D |
+| < 60 | F |
+
+## Notes
+
+- If a category does not apply (e.g. the project has no tests), score it **100** and label it "not applicable" rather than penalizing the project.
+- Always show the raw finding counts next to the score. The number is a summary, not a substitute for reading the findings.