# Generated Accessibility Gap Audit

Use this reference when a diff introduces or modifies an interactive component — a menu, modal/dialog, tabs, combobox, disclosure, tooltip, accordion, or custom form control — and the component's origin is AI/LLM-generated or suspected to be.

## What people get wrong

The common bad assumption is:

> "It looks and behaves correctly in a mouse-driven click-through, so it's accessible."

That is incomplete, and it is the specific gap generated frontend code falls into systematically. Models trained heavily on visual/structural patterns reproduce a component's DOM shape and CSS with high fidelity — divs, click handlers, conditional rendering, styling — because that is the dense part of the training signal. Keyboard operability, focus management, and ARIA state are comparatively sparse and easy to omit while still producing something that *looks* like a working component in a quick visual check. A generated `<div onClick={...}>` styled to look exactly like a button, with no `role="button"`, no `tabIndex`, no `onKeyDown` for Enter/Space, and no focus-visible state, passes every visual QA pass and fails every keyboard/screen-reader user.

## Officially grounded shape (W3C ARIA Authoring Practices Guide)

The APG defines, per widget pattern, the required:

- **role** — the ARIA role (or correct native HTML element) that identifies the widget's semantic type to assistive technology,
- **keyboard interaction** — the specific key bindings required for that pattern (e.g., a menu requires Arrow Up/Down to move focus among items, Escape to close, Enter/Space to activate; a tabs widget requires Arrow Left/Right to move between tabs and typically automatic or manual activation),
- **focus management** — where focus moves on open/close/activation (e.g., a modal must trap focus within itself while open and restore focus to the triggering element on close),
- **required states/properties** — the ARIA attributes that communicate current state (`aria-expanded`, `aria-selected`, `aria-checked`, `aria-haspopup`, `aria-controls`, `aria-activedescendant`, etc., depending on pattern).

Do not treat these as optional polish. A component missing any of the four is not "mostly accessible" — it is non-operable for keyboard-only and screen-reader users for that specific interaction.

## Non-negotiable audit rules

1. **Identify the correct APG pattern first.** Match the component to its specific APG pattern (menu vs. menubar vs. listbox vs. combobox are not interchangeable) before auditing — applying the wrong pattern's checklist produces false passes and false negatives.
2. **Test keyboard operability by tracing code, not by assuming it from visual markup.** Confirm there is an actual `onKeyDown`/`onKeyUp` handler (or native element providing it for free) implementing every key binding the APG pattern requires — a component with only `onClick` is not keyboard-operable regardless of how it looks.
3. **Verify focus management explicitly for overlay patterns.** For any modal, dialog, or popover pattern, confirm: focus moves into the overlay on open, focus is trapped within it while open, and focus returns to a sensible element (typically the trigger) on close. Absence of any of these three is a confirmed gap, not a style preference.
4. **Check that ARIA state attributes are wired to actual component state, not hardcoded.** `aria-expanded="false"` hardcoded in JSX/template that never updates when the component opens is a common generated-code pattern — flag it as equivalent to having no `aria-expanded` at all, since it actively communicates wrong state.
5. **Prefer native HTML elements over ARIA-patched divs wherever the pattern allows it**, per the APG's own guidance that native semantics are more robust than reconstructed ARIA — flag a custom `<div>`-based reconstruction of something a native `<button>`, `<dialog>`, or `<select>` already provides for free, unless there's a stated, real constraint the native element can't meet.
6. **Do not accept a passing automated accessibility linter (eslint-plugin-jsx-a11y, axe-core static rules) as sufficient evidence of full compliance.** Static linters catch a meaningful but partial subset (missing `alt`, some ARIA misuse); keyboard operability and focus-trap correctness generally require code tracing or runtime interaction testing beyond static lint rules — say so explicitly rather than treating a clean lint run as a full pass.

## Audit workflow

1. Identify each new/modified interactive component in the diff and match it to its specific APG pattern.
2. Pull the APG page for that exact pattern (`official_docs` URL in this skill's `metadata.json`) and extract its required role, keyboard bindings, focus-management behavior, and ARIA state attributes.
3. Trace the component's actual code against each of the four requirement categories; do not infer from the visual/CSS layer.
4. For each requirement category, classify as: `present and correctly wired`, `present but not wired to real state` (e.g., hardcoded ARIA attribute), or `missing`.
5. Prioritize `missing` keyboard-operability and focus-management findings above missing/incorrect ARIA attributes above missing native-element preference — a component nobody can reach by keyboard is a harder blocker than a suboptimal role choice.

## High-risk assumptions to kill

- "It has an ARIA role, so it's accessible." A role without the matching keyboard interaction and state management is worse than no role at all — it advertises a contract to assistive technology that the component does not fulfill.
- "The design system's base component is accessible, so anything built from AI-generated composition around it is too." Verify the generated wiring code didn't strip or override the base component's accessible behavior (e.g., replacing a native `<button>` wrapper with a styled `<div>` for layout convenience).
- "This passed a quick manual click-through, so keyboard/screen-reader behavior is fine." A mouse-driven manual check exercises none of the keyboard or AT-specific code paths that are exactly where generated code is most likely to have gaps.

## When to push back

Push back if the user asks you to:

- approve an interactive component with no traced keyboard-handler evidence because "it looks right,"
- treat a passing static a11y linter run as proof of full APG-pattern compliance,
- skip focus-management review on a modal/overlay pattern because "it's just a small popover."

Those are exactly the corners where generated code's semantic gaps hide.

# Hallucinated API Verification

Use this reference when a diff — especially one flagged or suspected as AI/LLM-generated — calls a framework/library API (a hook, a component prop, a lifecycle method, a utility export, a CLI flag) and you need to determine whether that API actually exists and behaves as claimed for the project's installed version.

## What people get wrong

The common bad assumption is:

> "It compiles, TypeScript didn't complain, and it reads like idiomatic React/Vue/Angular — so the API is real."

That is not evidence. Three independent failure modes hide behind a clean-looking call:

1. **Version drift** — the API existed in an earlier or later major version than the one installed (e.g., a hook or lifecycle method from a different major, a removed legacy API reintroduced from training data).
2. **Cross-framework bleed** — the model composed a plausible-sounding API by blending conventions from a *different* framework or library (e.g., invoking a Vue-shaped lifecycle name inside a React component, or a Redux Toolkit-shaped selector inside a Zustand store).
3. **Fully invented surface** — a prop, config key, or method that never existed in any version, constructed by pattern-completing the surrounding code's naming conventions.

TypeScript type-checking and successful compilation catch none of these reliably: overly-permissive types (`any`, loose generic constraints, ambient `declare` fallbacks), stale `@types` packages, or type-narrowing gaps let a nonexistent runtime API pass static checks silently.

## Non-negotiable verification rules

1. **Pin the version before checking the API.** Read `package.json` and the lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) to determine the *actual installed* major/minor version of the framework or library in scope. Do not check an API claim against "React" in the abstract — check it against the resolved version.
2. **Resolve the Context7 library ID before querying.** Call `resolve-library-id` for the framework/library named in the diff, then `query-docs` with the specific API name/signature as the query. Do not skip straight to `query-docs` with a guessed ID.
3. **A miss on Context7 is not automatically a hallucination, but it is not automatically fine either.** If Context7 has no documentation coverage for a library, fall back to the library's official docs site directly (fetch or search), and only after that fails, label the claim `unverified — possible hallucination` rather than silently accepting it.
4. **Do not accept "it's probably a newer/undocumented API."** Generated code asserting the use of a bleeding-edge, unstable, or "experimental" API is a signal to verify harder, not a license to skip verification — check the changelog/release notes for the pinned version, not just the latest docs.
5. **Distinguish "does not exist" from "exists but deprecated/discouraged."** Both are findings, but they carry different severity and different remediation (delete the call vs. migrate to the current-recommended replacement per official docs).
6. **Never paraphrase from training-data memory as if it were verified.** If Context7 and official docs are both unreachable for a given library, say so explicitly and mark every affected claim `inference — not independently verified`, not `documentation-based`.

## Verification workflow

1. Extract every non-trivial framework/library API call touched or added in the diff (hooks, component props, lifecycle/lifecycle-like methods, exported utilities, CLI flags/config keys).
2. Resolve the pinned version for each library from the manifest/lockfile.
3. Resolve the Context7 library ID for that library (`resolve-library-id`), preferring a version-matched result when the tool exposes one.
4. Query Context7 for each API name/signature (`query-docs`) with a specific, non-generic query (e.g., "React 18 useDeferredValue signature" — not "React hooks").
5. Cross-check any result against the pinned version's changelog/release notes if the API's introduction or removal version is ambiguous.
6. Classify each API call as one of:
   - `verified` — found in Context7/official docs for the pinned version, cite the source,
   - `verified but deprecated for this version` — exists, but current docs recommend a replacement,
   - `unverified — possible hallucination` — not found after checking Context7 and official docs,
   - `inference — not independently verified` — verification tooling was unreachable.

## High-risk assumptions to kill

- "The model probably trained on the latest docs, so it's current." Training cutoffs lag releases and generated code frequently mixes API eras.
- "It's a small helper method, not worth checking." Small invented helpers (a nonexistent utility export, a fabricated config key) are exactly the pattern that slips through review silently because no one runs it until production.
- "The linter/type-checker would have caught a nonexistent API." Loose types, ambient declarations, and stale `@types` packages routinely let a nonexistent runtime member pass static analysis.
- "This project always uses the latest version, so version pinning doesn't matter here." Verify the actual lockfile — do not assume.

## When to push back

Push back if the user asks you to:

- approve an API call because "it looks right" without running the verification workflow above,
- skip version-pinning because "we're always on latest" without checking the lockfile,
- treat a Context7 miss as automatic proof the API doesn't exist without a fallback official-docs check.

Those are shortcuts that convert a verification claim into an unverified guess.

# Slopsquat Dependency Check

Use this reference whenever a diff introduces a new package dependency — a new entry in `package.json`/`requirements.txt`/equivalent manifest, a new lockfile entry, or an import statement pulling from a package not previously present in the project.

## What people get wrong

The common bad assumption is:

> "The model wrote this import, the package name sounds like a real, well-known library, so it must exist and be the right one."

That is the exact mechanism of a slopsquat attack. LLMs, when asked to solve a problem, will sometimes hallucinate a plausible-sounding package name that does not exist — a name that reads as if it *should* be the canonical solution to the stated problem. Attackers monitor this pattern and pre-register those exact hallucinated names on public registries (npm, PyPI, etc.) with malicious payloads, betting that a generated suggestion will eventually get installed verbatim by someone who does not check. A name "sounding right" is therefore not weak evidence of legitimacy — it is close to zero evidence, because it is the precise signal an attacker optimizes for.

This is distinct from classic typosquatting (a deliberate misspelling of a real popular package, e.g. `reactt` or `lodash-es-`) — slopsquatting targets names an AI model is likely to *invent* for a given task, which may not resemble any existing real package at all.

## Non-negotiable check rules

1. **Every new dependency gets a live registry lookup — no exceptions for "obviously real" names.** Resolve the package on its actual public registry (npm registry for JS/TS, PyPI for Python, crates.io for Rust, RubyGems, etc.) via `WebFetch`/`WebSearch`. Do not accept the name on the strength of it sounding familiar or matching a well-known naming convention.
2. **Verify identity, not just existence.** A registry hit is not sufficient — confirm the resolved package's publisher/maintainer, description, weekly download count, repository link, and first-publish date align with what the diff claims the package does. A newly-squatted name can exist on the registry with near-zero downloads and no meaningful history.
3. **Treat a registry miss as a hard blocker, not a note.** If the exact package name does not resolve on the registry at all, this is the strongest possible slopsquat signal — the install must not proceed until the correct real package name is identified and independently confirmed.
4. **Check for confusable near-misses even on a registry hit.** Compare the found package against the likely *intended* real package for the stated purpose (e.g., is there a much more widely-used, near-identically-named alternative that this name is shadowing or bidding to be confused with?).
5. **Do not let version-pinning or lockfile presence substitute for a registry check.** A lockfile entry only proves something was resolved and installed at some point — potentially by an earlier, equally unverified step — not that the package is legitimate.
6. **Escalate, do not silently "fix," a suspicious name.** If a dependency looks slopsquatted, do not unilaterally swap in what you assume is the "real" package — flag it explicitly and require the author to confirm intent, since silently substituting could also introduce the wrong package.

## Verification workflow

1. Diff the manifest/lockfile to enumerate every newly introduced package name and version constraint.
2. For each new name, perform a live registry lookup (`WebFetch`/`WebSearch` against the registry's public package page or API).
3. Record, per package: registry hit/miss, publisher, download volume/popularity signal, repository URL, first-publish date.
4. Cross-reference the package's stated purpose in the diff/commit message against what the registry listing actually describes.
5. Classify each new dependency as:
   - `registry-verified` — resolves to a real, actively-maintained package matching the claimed purpose; cite the registry URL,
   - `registry-verified but low-confidence` — resolves, but with signals worth a human look (very new, near-zero downloads, unrelated description, generic/unmaintained-looking repo),
   - `slopsquat-risk / registry-lookup-failed` — does not resolve, or resolves to something that plausibly is a hallucinated-name squat.

## High-risk assumptions to kill

- "It's a scoped package under a name I recognize (e.g., `@react-...`), so the scope itself vouches for it." Scopes can be squatted or created by unrelated parties; verify the specific scope owner too.
- "The AI tool that generated this surely only suggests real packages." That is precisely the failure mode this check exists to catch — treat every model-suggested package name with the same suspicion regardless of tool confidence.
- "It installed successfully, so it must be real." A successful `npm install`/`pip install` only proves the name resolved on the registry at install time — it says nothing about whether the package is the legitimate, intended one or a malicious squat.

## When to push back

Push back if the user asks you to:

- approve a new dependency without a registry lookup because "we're in a hurry,"
- silently rename a suspicious dependency to what you guess was intended, rather than flagging it for explicit confirmation,
- treat popularity of the *stated* library concept (e.g., "everyone uses a library like this") as a substitute for verifying *this specific* package name resolves to that library.

Those shortcuts reintroduce exactly the supply-chain risk this check exists to close.