Site Auditor skill

Create the Site Auditor skill — a quality gate that runs structured audits across accessibility, design quality, and performance. It outputs findings, fixes what it can, and re-runs until clean.

This is an action skill, not just knowledge. The core behavior is a loop: audit → findings → fix → re-audit → repeat until clean.

## Triggers

`"audit my site"` · `"check accessibility"` · `"review my UI"` · `"is my site ready to ship"` · `"WCAG"` · `"a11y"` · `"design review"`

## What it checks

### Accessibility
- WCAG 2.1 AA compliance
- ARIA patterns for blocks
- Keyboard navigation
- Focus management
- Color contrast
- Semantic HTML
- wp-components a11y
- WordPress accessibility coding standards

### Design quality
- Composition and visual hierarchy
- Typography choices
- Mobile responsiveness
- Anti-patterns: card overuse, pill clusters, stat strips, generic AI aesthetics
- One purpose per section, brand-first, real visual anchors

### Performance
- Unoptimized images
- Render-blocking resources
- Missing lazy loading
- Viewport meta

## How it works

The skill reads the project's theme/plugin files and checks them against the rules. It outputs structured findings (what's wrong, severity, how to fix), then fixes what it can automatically. After fixing, it re-runs the audit to verify. This loop continues until the audit passes or only manual-fix items remain.

Can be invoked directly on any project, or called by the Site Builder skill as a final phase before deploy.

## Sources

The rules should be built from the best of three existing frontend design skills, extended with WordPress-specific conventions:

- **[Vercel's web-design-guidelines](https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines)**— 100+ audit rules covering accessibility, focus states, forms, animation, typography, images, performance, navigation, dark mode, touch, and i18n
- **[OpenAI's frontend-skill](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4)** — Hard rules for composition (one purpose per section, brand-first, reduce clutter, real visual anchors)
- **[Anthropic's frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)** — Design thinking process, typography choices, creative direction, avoiding generic AI aesthetics

### WordPress-specific extensions
- Block editor patterns
- WordPress Design System (WPDS)
- `theme.json` design tokens
- Font handling via `enqueue_block_assets`
- Style variations

## Deliverables

- [ ] `skills/site-auditor/SKILL.md` — Main skill definition with triggers, procedure, and rules
- [ ] `skills/site-auditor/references/` — Detailed rule docs organized by category (accessibility, design, performance)
- [ ] `skills/site-auditor/scripts/` — Any helper scripts for automated checks

## Future

If Studio ships `studio site audit` (structured JSON output) and `studio site screenshot` (visual verification), this skill should use those commands instead of reading code directly.

Inspired by https://regionallyfamous.com/wordpress-needs-a-front-door/.