mirror of
https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git
synced 2026-08-01 10:56:17 +00:00
b484e8338c
A ready-to-use Claude Code environment for website design, bundling: - .mcp.json: Playwright + Chrome DevTools + shadcn MCP servers - CLAUDE.md: the design loop (plan -> commit to a look -> build -> screenshot -> review) - .claude/agents/design-review.md: 7-phase design-review subagent (WCAG AA, responsive) - .claude/commands: /design-review, /design-plan - scripts/design-audit.mjs: standalone multi-viewport screenshot + heuristic audit - .github/workflows/design-review.yml: CI design gate (template) - docs/: STACK, SETUP, WORKFLOW - examples/juniper-audit/: a real audit run (report + 6 viewport screenshots) Pairs with the ui-ux-pro-max skill (knowledge layer) and the official frontend-design plugin (taste layer). Lives on its own branch as a self-contained starter; copy stack/ out to seed a standalone repo. Co-authored-by: Claude <noreply@anthropic.com>
55 lines
2.9 KiB
Markdown
55 lines
2.9 KiB
Markdown
# Worked example — auditing a production marketing site
|
||
|
||
This is a **real run** of `scripts/design-audit.mjs` against a live single-page marketing site
|
||
(a financial-services firm's homepage), captured to show what the heuristic layer of the stack
|
||
produces before you wire it into your own project.
|
||
|
||
## How it was produced
|
||
|
||
```bash
|
||
# serve the site, then audit it over HTTP (not file://, so asset/CORS noise is realistic)
|
||
python3 -m http.server 8099 # in the site directory
|
||
node scripts/design-audit.mjs --url http://localhost:8099/ --out examples/juniper-audit
|
||
```
|
||
|
||
## What's here
|
||
|
||
- [`report.md`](./report.md) — ranked findings + console health
|
||
- [`report.json`](./report.json) — the same, machine-readable (what CI consumes)
|
||
- [`screenshots/`](./screenshots) — full-page capture at all six viewport tiers (360 → 1920 px)
|
||
|
||
## Reading the results
|
||
|
||
The site is genuinely well-built (design tokens, self-hosted fonts, `prefers-reduced-motion`,
|
||
scroll-reveal). The audit still surfaced three actionable items — exactly the kind a human
|
||
misses on a quick look:
|
||
|
||
| Finding | Severity | Why it matters |
|
||
|---------|----------|----------------|
|
||
| 2–3 sampled interactive elements show no visible focus indicator | High | Keyboard users can't see where they are — WCAG 2.4.7 |
|
||
| 14 tap targets < 44×44 px on mobile | Medium | Small touch targets → mis-taps on phones |
|
||
| ~1 text node below AA contrast (approximate) | Medium | Lead to verify by hand; contrast is estimated from the nearest opaque background |
|
||
|
||
The single console error is a `404` for one asset — worth chasing, but not a layout defect.
|
||
|
||
## Two things this example teaches about the tooling
|
||
|
||
1. **Serve over HTTP, not `file://`.** Opening via `file://` produces a wall of font-CORS
|
||
errors that are pure artifacts (browsers block cross-origin font fetches from `null` origin).
|
||
The numbers above are from a real HTTP serve, so the console is clean.
|
||
|
||
2. **Full-page capture + aggressive scroll-reveal don't fully mix.** The script auto-scrolls to
|
||
trigger `IntersectionObserver` reveals before shooting, which recovers most content — but a
|
||
page that reveals sections only on fine-grained scroll can still show a blank band in a
|
||
single full-page screenshot. That's both a tooling limit **and** a real robustness signal
|
||
(the same content is invisible to some crawlers, print, and any non-interactive capture).
|
||
For those pages, the interactive **`/design-review`** subagent — which scrolls naturally,
|
||
waits, and interacts — is the more reliable check. Heuristics catch the mechanical defects;
|
||
the subagent judges the experience.
|
||
|
||
## The point
|
||
|
||
This is the *fast, automatic* half of the stack (also runs in CI). The *full* review —
|
||
interaction flows, visual taste, edge cases — is the `design-review` subagent invoked with
|
||
`/design-review <url>`. Use both: heuristics to gate merges, the subagent to raise the bar.
|