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

1. Identify scope : single component, single page, full feature, single skill file. The checklist applies recursively to any of these targets.
2. Read source materially : load every *.html, *.css, *.js, *.ts, *.md file in scope. Do not infer ; quote line numbers.
3. Apply the three checklists in order : A11Y -> PERF -> CONSISTENCY. Each rule produces zero or more findings.
4. Grade severity : ERROR (WCAG AA fail or CWV threshold miss), WARNING (missed best practice), INFO (style inconsistency).
5. Emit the report : JSON for parent-agent consumption, Markdown for human review. See references/examples.md for the canonical shape.
6. 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).

PERF checklist (7 rules)

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

CONSISTENCY checklist (6 rules)

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

Severity grading

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)