bestdeejay-design/agent-skills / skills/frontend-perfection
frontend-perfection
VerifiedAudit and polish frontend (static HTML/CSS/JS or built SPA) to measurable perfection: real-Chrome Lighthouse >=13 runs (mobile+desktop, no Playwright internals), SEO meta layer, WCAG contrast by computed luminance, heading order, a11y checks (axe-core subset), back-to-top navigation, design tokens (zero raw hex), adaptive checks, OG-image generation, plus Security/Privacy/i18n static coverage (HTTPS/mixed content, CSP, SRI, security headers, noopener, secrets-in-URL, cookie consent, i18n lang/dir/Intl). Front-End Checklist-inspired. Triggers: 'frontend audit', 'perfect the layout', 'lighthouse check', 'make it 100/100/100/100', 'audit the page', 'fix performance', 'contrast check', 'design tokens', 'og image', 'security headers', 'privacy', 'https', 'mixed content', 'CSP', 'SRI', 'i18n', 'internationalization', 'social share meta'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.7 KB |
| evals/evals.json | config | 598 B |
| readme.ru.md | markdown | 3.0 KB |
| references/canonical-patterns.md | markdown | 5.4 KB |
| scripts/audit.js | script | 9.8 KB |
| scripts/meta_audit.py | script | 31.2 KB |
| scripts/package.json | manifest | 25 B |
| scripts/security_privacy_audit.py | script | 23.8 KB |
| skill.json | config | 2.5 KB |
references/canonical-patterns.md
View on GitHub# frontend-perfection — Canonical Patterns
Deep dive behind `scripts/audit.js` + `scripts/meta_audit.py`. Grounded in
canonical sources (August 2026); every URL is a live, real-world reference:
- **Lighthouse (Google)** — <https://github.com/GoogleChrome/lighthouse>
— the audit engine this skill wraps on the Node API
- **chrome-launcher (Google)** — <https://github.com/GoogleChrome/chrome-launcher>
— the stable CDP launch mechanism this skill uses instead of Playwright internals
- **Anthropic official skills (frontend-design)** — <https://github.com/anthropics/skills>
— reference for agent-side frontend workflow skills
- **obra/superpowers (perfection)** — <https://github.com/obra/superpowers>
— reference for "perfection"-style high-bar agent skills
- **Open Graph protocol** — <https://ogp.me/>
— the social share spec the OG-block implements
- **WCAG 2.2 (W3C)** — <https://www.w3.org/TR/WCAG22/>
— the contrast (1.4.3) and other rules the audit computes, not eyeballs
---
## 1. Why a stable runner (not Playwright/CDP internals)
Legacy implementations grabbed the CDP port from private Playwright fields
(e.g. `browser._impl_obj._connection._transport._ws_url`). These are
**unsupported internals** and break silently when the transport changes
(WebSocket → PipeTransport). The canonical engineering answer, used by
Lighthouse's own tooling, is `chrome-launcher`: it launches the real Chrome,
returns `{ port, pid }` via its public API, and requires no private fields.
This skill builds on that contract and therefore survives upstream refactors.
**Lighthouse ≥ 13**: the package no longer exports the function directly as
the module (`require("lighthouse")` is a namespace). Canonical call is
`require("lighthouse").default(...)`. The skill does both: feature-detect the
shape, then call whatever is a function. This is the same fallback pattern
Google uses in its own docs for dual ESM/CJS exports.
## 2. Dependency isolation — canonical layout
Global `npm install -g` historically did not resolve from `require()` on
Node ≥ 20/22 (global prefix lives outside `NODE_PATH`). The canonical
patterns the skill implements (all three, in order):
- local `node_modules` next to the script (self-contained, `npm i -g` not needed)
- `NODE_PATH` (the documented npm/Node escape hatch for global resolution)
- `npm root -g` auto-discovery
This mirrors how Lighthouse's CLI bundles its deps and how
`PROJECT_ROOT/node_modules` hoisting works in npm workspaces — no module is
ever assumed "just available".
## 3. Techniques the analogues have that this implementation lacks
- **Lighthouse CI server/cluster mode** (Google `lighthouse-ci`,
<https://github.com/GoogleChrome/lighthouse-ci>): persistent server,
regression budgets, GitHub action integration. This skill is a local,
single-run runner — there is no `assert` budget deck or PR blamer.
- **Screenshot diffing on layout changes** (visual regression tooling like
`backstopjs`): pixel-level before/after on the same page. This skill
verifies metrics and checks, not pixels.
- **Cumulative browser profile budgets** (`bundle-buddy`/`size-limit`-style JS
size gates): the Lighthouse JS-bundle audit (`unused-javascript`) is
surfaced as a failed audit id, but there is no bytes regression suite.
- **Full WCAG 2.2 scope** (color-contrast-enhanced AA/AAA, non-text
contrast 1.4.11, target-size 2.5.5): the skill implements the 4.5:1 text
branch (1.4.3) via computed luminance; 3:1 UI/component and AAA are
explicitly out of scope.
- **Real social-cache verification harness**: ogp.me documents the tags, but
nothing canonical automates "is my preview right in WhatsApp *today*";
the skill bakes the *known constraints* (crop-safe zone ~640px, URL change
to bust caches, forced reflow before capture) into the workflow instead.
## 4. Determinism contract
- `meta_audit.py`: offline, no network, no wall-clock dependence; same
files → same report. Report field order is stable (checks in fixed id
order, summary block last).
- `audit.js`: Lighthouse itself is non-deterministic across runs (CPU, cache,
Chrome version), so the *scores* are best-effort; the *failed audit ids*
(what to fix) are the stable contract. `--threshold` gates exit code
machine-checkably.
## 5. Exit-code contract
- `audit.js`: `0` = all measured categories ≥ threshold; `1` = below; `2` =
runner error (missing module / URL unreachable / crash).
- `meta_audit.py`: `0` = no violations; `1` = violations found; `2` = usage /
I/O error (missing file args). Downstream tooling may therefore `&&`-chain
audit passes.
## Sources
- GoogleChrome/lighthouse: <https://github.com/GoogleChrome/lighthouse>
- GoogleChrome/chrome-launcher: <https://github.com/GoogleChrome/chrome-launcher>
- GoogleChrome/lighthouse-ci: <https://github.com/GoogleChrome/lighthouse-ci>
- anthropics/skills (frontend-design): <https://github.com/anthropics/skills>
- obra/superpowers: <https://github.com/obra/superpowers>
- Open Graph protocol: <https://ogp.me/>
- WCAG 2.2: <https://www.w3.org/TR/WCAG22/>
- WAI-ARIA 1.2: <https://www.w3.org/TR/wai-aria-1.2/>
- axe-core rule catalog (Deque): <https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md>
- MDN accessibility: <https://developer.mozilla.org/en-US/docs/Web/Accessibility>
- WCAG 2.4.1 Bypass Blocks / back-to-top UX: <https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html> + Nielsen Norman 'Back to top' patternRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |