frontend-agents-a11y-perf-consistency-auditor

Frontend Agents : A11y + Perf + Consistency Auditor

This skill is an AGENT skill : it codifies a three-axis static-analysis checklist (Accessibility, Performance, Consistency) and the audit-report shape that parent agents consume. Spawn this skill when auditing a UI component, a pull request, a feature branch, or a newly-authored skill file. The skill does NOT cover general accessibility theory (see [[frontend-a11y-aria-patterns]]), Core Web Vitals theory (see [[frontend-perf-core-web-vitals-inp]]), design-token enforcement (see [[frontend-agents-design-system-validator]]), automated visual regression testing, or browser-rendered audits. This is STATIC ANALYSIS only.

Quick Reference

Audit workflow

Identify scope : single component, single page, full feature, single skill file. The checklist applies recursively to any of these targets.
Read source materially : load every *.html, *.css, *.js, *.ts, *.md file in scope. Do not infer ; quote line numbers.
Apply the three checklists in order : A11Y -> PERF -> CONSISTENCY. Each rule produces zero or more findings.
Grade severity : ERROR (WCAG AA fail or CWV threshold miss), WARNING (missed best practice), INFO (style inconsistency).
Emit the report : JSON for parent-agent consumption, Markdown for human review. See references/examples.md for the canonical shape.
Suggest fixes : every finding includes a fix snippet citing the relevant skill (e.g. [[frontend-a11y-motion-contrast-wcag22]] SC reference).

Decision tree 1 : Which checklist first ?

Auditing a UI component, page, or feature ?
  -> Run A11Y first (semantic-HTML-first rule catches structural issues
     that affect everything else), then PERF, then CONSISTENCY.

Auditing a skill file or documentation ?
  -> Run CONSISTENCY first (file shape, frontmatter, line count), then
     scan code blocks within the docs for A11Y and PERF issues.

Auditing a pull-request diff (incremental change) ?
  -> Run all three on the changed files, plus CONSISTENCY on any newly
     added files. Skip unchanged files unless they reference changed APIs.

Audit triggered by a Lighthouse regression ?
  -> PERF first (the regression is metric-driven), then A11Y on the same
     scope to catch what Lighthouse missed (semantic HTML correctness).

Decision tree 2 : ARIA needed or native enough ?

Element behaves like a button (click to perform action) ?
  -> Use <button>. ERROR if `<div role="button">` is found.
     Native button gets focus-trap, keyboard activation (Space, Enter),
     forced-colors mapping (ButtonText), and screen-reader semantics for free.

Element behaves like a link (navigation) ?
  -> Use <a href>. ERROR if `<button>` used for navigation.

Element is a form control ?
  -> Use <input>, <select>, <textarea>, <button>. ERROR if a div + custom
     keyboard handlers reimplements one of these.

Element is a disclosure (expand / collapse panel) ?
  -> Use <details> + <summary>. Native browser handles state + keyboard.

Element is a dialog ?
  -> Use <dialog> + showModal(). ERROR if a custom modal is built.

Element has NO native equivalent (combobox, custom tree, custom slider) ?
  -> ARIA is required. Follow the W3C WAI APG pattern exactly.
     See [[frontend-a11y-aria-patterns]].

Decision tree 3 : Performance regression : CLS, LCP, or INP ?

Layout shifted as content loaded ?
  -> CLS. Audit <img>, <video>, <iframe>, ad slots for explicit width / height
     or aspect-ratio. Audit webfont swap for matched fallback metrics.

Hero element rendered late on first paint ?
  -> LCP. Audit for `fetchpriority="high"`, `<link rel="preload">`, and
     verify `loading="lazy"` is NOT on the LCP image.

Click felt laggy ?
  -> INP. Audit event handlers for synchronous long tasks. Verify yielding
     via scheduler.yield with setTimeout fallback. Check for
     requestAnimationFrame misuse as a generic yield.

Animation feels janky ?
  -> Audit animation properties. ERROR if width / height / top / left animated.
     Only transform / opacity / filter are compositor-only.

All metrics look fine but real users complain ?
  -> Field RUM. Lab metrics underestimate INP. Audit for third-party
     scripts blocking the main thread.

A11Y checklist (9 rules)

Anchored to W3C : WCAG 2.2 (verified 2026-05-19) and W3C WAI APG (verified 2026-05-19).

ID	Rule	Severity	WCAG / APG anchor
A1	Every interactive element has an accessible name (visible text, `aria-label`, or `aria-labelledby`).	ERROR	WCAG 4 1 2 Name, Role, Value
A2	`:focus { outline: none }` MUST have a matching `:focus-visible { outline: ... }` with 3 to 1 contrast against the unfocused state.	ERROR	WCAG 2 4 7 Focus Visible + 2 4 13 Focus Appearance
A3	Modal `<dialog>` uses `dialog.showModal()` AND has `aria-labelledby` (or `aria-label`).	ERROR	APG Dialog Modal pattern
A4	Live regions exist in the DOM BEFORE the message is inserted.	ERROR	APG Alert pattern, MDN ARIA Live Regions
A5	Target size meets 24-by-24 CSS pixel test OR matches one of the five exceptions (spacing, equivalent, inline, UA, essential).	ERROR	WCAG 2 5 8 Target Size (Minimum) AA
A6	Text contrast meets 4 5 to 1 (normal text) or 3 to 1 (large text) ; non-text and UI contrast meets 3 to 1.	ERROR	WCAG 1 4 3 + 1 4 11
A7	Every CSS animation has a `@media (prefers-reduced-motion: reduce)` branch.	ERROR	MDN prefers-reduced-motion
A8	NO positive `tabindex` values (0 and -1 are acceptable).	ERROR	WCAG 2 4 3 Focus Order
A9	Semantic HTML preferred over ARIA roles. `<div role="button">` is an ERROR ; use `<button>`.	ERROR	First rule of ARIA

PERF checklist (7 rules)

Anchored to web.dev : Core Web Vitals (verified 2026-05-19) and web.dev : Optimize INP (verified 2026-05-19).

ID	Rule	Severity	Metric
P1	`<img>`, `<video>`, `<iframe>` have explicit `width` and `height` attributes OR an `aspect-ratio` CSS rule.	ERROR	CLS
P2	LCP image has `fetchpriority="high"`. Bonus : `<link rel="preload" as="image" imagesrcset=... fetchpriority="high">`.	ERROR	LCP
P3	Below-the-fold images have `loading="lazy"`. The LCP image does NOT have `loading="lazy"`.	ERROR	LCP
P4	Animations use ONLY `transform`, `opacity`, or `filter`. ERROR if `width`, `height`, `top`, `left`, `margin`, or `padding` is animated.	WARNING	INP, animation jank
P5	`will-change` applied transiently (during interaction) and removed after. NEVER permanently.	WARNING	Memory, INP
P6	Webfont files are at most 100 KB woff2 per face. `font-display: swap` declared.	WARNING	LCP, CLS
P7	Critical CSS inlined in `<head>` OR `<link rel="preload" as="style">` for the critical bundle.	WARNING	LCP

CONSISTENCY checklist (6 rules)

Anchored to the package validator scripts at Skill-Package-Workflow-Template/scripts/.

ID	Rule	Severity
C1	YAML frontmatter has `name`, `description` (folded scalar `>`, NOT quoted), `license: MIT`, `compatibility`, `metadata` with `author` and `version`.	ERROR
C2	Skill folder contains exactly `SKILL.md` + `references/methods.md` + `references/examples.md` + `references/anti-patterns.md`. NO `README.md` inside skill folders.	ERROR
C3	`SKILL.md` is at most 500 lines. Overflow lives in `references/`.	ERROR
C4	All skill content is English-only. NEVER Dutch or other languages inside skill files.	ERROR
C5	Section headings use `:` as separator (e.g. `## Quick Reference`, `### Pattern : foo`). NEVER em-dash.	ERROR
C6	Cross-references use `[[skill-name]]` Markdown link format.	WARNING

Severity grading

Severity	Definition
ERROR	Violates WCAG 2 2 AA, misses a Core Web Vital threshold at p75, or breaks the package quality contract.
WARNING	Missed best practice that does not block conformance.
INFO	Style inconsistency, naming drift, missing optional metadata.

Audit-report output shape

The agent emits TWO parallel formats per audit.

JSON for parent-agent consumption

{
  "scope": "skills/source/frontend-component/frontend-component-modal-toast-system/",
  "summary": {
    "files_audited": 4,
    "findings": { "ERROR": 0, "WARNING": 2, "INFO": 1 }
  },
  "findings": [
    {
      "id": "A2-2026-05-19-001",
      "severity": "WARNING",
      "category": "A11Y",
      "rule": "A2",
      "file": "SKILL.md",
      "line": 142,
      "message": "Example code block uses :focus { outline: none } without :focus-visible override.",
      "fix": "Add :focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }",
      "reference": "[[frontend-a11y-motion-contrast-wcag22]] SC 2 4 13"
    }
  ]
}

Markdown for human review

# Audit Report

**Scope** : skills/source/frontend-component/frontend-component-modal-toast-system/
**Files audited** : 4
**Findings** : 0 ERROR, 2 WARNING, 1 INFO

## Findings

### WARNING : A2 (Focus visible override missing)
- **File** : SKILL.md
- **Line** : 142
- **Issue** : Example code block uses `:focus { outline: none }` without `:focus-visible` override.
- **Fix** : Add `:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }`
- **Reference** : [[frontend-a11y-motion-contrast-wcag22]] SC 2 4 13

See references/examples.md for the canonical full report and several worked audits.

Cross-references

[[frontend-a11y-aria-patterns]] : ARIA role surface, APG patterns (alert, dialog, combobox, tabs).
[[frontend-a11y-focus-keyboard-inert]] : focus management, :focus-visible, inert attribute.
[[frontend-a11y-motion-contrast-wcag22]] : WCAG 2 2 nine new SCs, motion / contrast preferences, forced-colors.
[[frontend-perf-core-web-vitals-inp]] : LCP / INP / CLS thresholds, yield ladder, Speculation Rules.
[[frontend-perf-animation-gpu-containment]] : compositor-only animations, CSS containment.
[[frontend-impl-design-tokens]] : three-tier token chain, naming conventions (delegated enforcement to [[frontend-agents-design-system-validator]]).
[[frontend-agents-design-system-validator]] : token-enforcement-specific auditor.

Reference Links

references/methods.md : full rule surface for all 22 checks, file-pattern matching, severity thresholds, JSON Schema for the report.
references/examples.md : sample audit reports (JSON + Markdown) for three representative targets (a component, a feature branch, a skill file).
references/anti-patterns.md : eight anti-patterns the auditor catches with high frequency, with the rule ID, symptom, and fix snippet.

Authoritative sources

W3C : WCAG 2.2 (verified 2026-05-19)
W3C WAI : ARIA Authoring Practices Guide (verified 2026-05-19)
W3C WAI APG : Patterns (verified 2026-05-19)
web.dev : Vitals (verified 2026-05-19)
web.dev : Optimize INP (verified 2026-05-19)
MDN : :focus-visible (verified 2026-05-19)
MDN : ARIA Live Regions (verified 2026-05-19)