| name | audit-github-pages-ux |
| description | Audit the rendered user experience of an existing GitHub Pages site or production-equivalent local build and report evidence-backed accessibility, responsive-layout, navigation, content-density, typography, color, brand, and interaction defects. Use for Pages-specific visual and UX verification after a build. Do not use for generic website audits, source-only code review, deployment configuration, or implementing fixes. |
Audit GitHub Pages UX
Evaluate the rendered Pages experience against repository evidence and real reader tasks. Report findings; do not edit unless the user separately asks for fixes.
Establish the audit target
- Confirm the site is GitHub Pages or a production-equivalent local build with the same base path and output.
- Resolve the repository/build path and preview URL before testing. If the rendered target cannot be identified or started safely, request that target and report the audit as not run rather than substituting source inspection.
- Inspect repository branding, documented reader tasks, current site configuration, route expectations, and any explicit design tokens or content rules.
- Record the exact build, URL or local preview, viewport sizes, theme, browser, and available accessibility tooling.
- Do not claim rendered, keyboard, contrast, or screen-reader verification when only source files were inspected.
Read the checklist
Read references/rendered-pages-audit.md before performing the audit.
Audit representative journeys
Cover the smallest set that represents the public site:
- home or landing page;
- primary first-success journey;
- one nested documentation page;
- one code-, table-, image-, or reference-heavy page;
- navigation and search when present;
- not-found, empty, or zero-results behavior;
- light/dark themes and narrow/desktop widths when supported.
Traverse interactive elements with a keyboard and inspect visible states, not screenshots alone.
Report only actionable findings
For every defect include:
- Evidence: page, viewport/theme, element, and observable behavior;
- Impact: blocked reader task or accessibility/usability consequence;
- Severity: critical, major, minor, or enhancement;
- Fix: the smallest advisory correction consistent with the existing stack and tokens; recommending it does not authorize an edit;
- Verification: how to prove the correction worked.
Order findings by user impact, then confidence. Separate confirmed defects from limitations and unverified checks. Do not treat automated accessibility output as certification.
