# ux-audit
> Reproducible UX audits for web solutions with Claude — versioned check catalog, hybrid browser + code verification, remediation plan, re-audit, and GitHub release.
[🇩🇪 Deutsche Version](README.de.md)
> **Note:** The check catalog (`checks/`) and templates (`templates/`) are written in German, tuned for Swiss public-sector solutions (eCH-0059). The methodology itself is language-agnostic.
## Overview
`ux-audit` is a Claude Skill that runs a reproducible UX audit on online solutions (websites, web apps, dashboards) against a versioned best-practice catalog — the same philosophy as [mcp-audit](https://github.com/malkreide/mcp-audit-skill): **a versioned checklist instead of gut feeling.** It covers the full lifecycle from audit through fixes to release.
## Features
- **Four-phase lifecycle:** Audit → Remediation → Re-Audit → GitHub Release
- **Hybrid verification:** live browser walkthrough (accessibility tree, keyboard pass, viewport switching, Lighthouse) **plus** code analysis (grep, review) — every finding anchored to a selector + measurement or `file:line`
- **Honest about its own limits:** a mandatory hydration probe distinguishes a real defect from an audit-environment limit; checks that cannot be exercised become `unverified` (never a false `fail`) and are handed off with a concrete manual test instruction
- **26-check catalog:** `USE` (10, Nielsen heuristics), `A11Y` (10, WCAG 2.2 AA), `PERF` (6, Core Web Vitals)
- **Applicability filter:** `applies_when` clauses select only relevant checks per solution profile
- **eCH-0059 escalation:** differentiated by WCAG level (A/AA escalate, AAA does not)
- **UX score:** weighted pass rate with a release-ready criterion
- **File-based tracker:** everything lives in an `audit/` folder in the target repo — versioned via Git, no external service
## Prerequisites
- Claude Code or Cowork with the in-app browser
- Optional: `lighthouse` (via `npx`) for Core Web Vitals measurements
- Optional: local access to the target repo for the code-analysis half of the hybrid audit
## Installation
```bash
git clone https://github.com/malkreide/ux-audit-skill.git ~/.claude/skills/ux-audit
```
## Usage
In Claude Code / Cowork:
```
Mach ein UX-Audit von https://example.ch
```
The skill auto-triggers. Run phases individually too: *"Erstelle den Remediation-Plan"*, *"Mach den Re-Audit"*, *"Bereite den Release vor"*. Or use the slash command `/audit-ux <url-or-repo-path> [phase]`.
## Project Structure
```
ux-audit/
├── SKILL.md # Methodology: 4 phases, 6 audit steps, anti-patterns
├── checks/ # 26 checks + MANIFEST.txt
├── templates/ # profile.yaml, finding.md, audit-report.md, remediation-plan.md
├── .claude/commands/ # /audit-ux slash command
├── CHANGELOG.md
└── LICENSE
```
Artifacts the skill produces in the audited repo:
```
<target-repo>/audit/
├── profile.yaml # solution profile (drives the applicability filter)
├── findings/ # one finding per failed check
├── screenshots/ # browser evidence (best-effort)
├── remediation-plan.md # ordered, checkable plan in waves
└── reports/ # audit + re-audit reports with UX score
```
## Changelog
See [CHANGELOG.md](CHANGELOG.md)
## Credits
- Methodology model: [mcp-audit](https://github.com/malkreide/mcp-audit-skill)
- Inspiration: [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), Nielsen Norman Group, W3C WCAG 2.2, web.dev
## License
MIT License — see [LICENSE](LICENSE)
## Author
Hayal Özkan · [malkreide](https://github.com/malkreide)