frontend-perfection

name	frontend-perfection
description	Audit 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'.
license	MIT
metadata	{"author":"best","version":"1.5.0"}
when_to_use	Use to audit/polish a frontend to measurable perfection: 'frontend audit', 'perfect the layout', 'lighthouse check', 'make it 100/100/100/100', 'audit the page', 'fix performance', 'contrast check', 'design tokens', 'og image', 'social share meta'. Examples: 'audit my page for Lighthouse 100', 'fix contrast and SEO meta on the homepage'.

frontend-perfection

Audit and polish a frontend — static HTML/CSS/JS or a built SPA — towards verifiable perfection. The skill exists because production web perf tooling commonly breaks when it pokes at private APIs (Playwright internals, old Lighthouse signatures, unisolated global deps). This skill runs on STABLE apis only, computes exactly (luminance, not eyeballs), and demands a before/after report bound to audit ids.

When to use

• User asks to "make the layout perfect", "fix performance", "reach 100/100/100/100", "check the frontend", "audit the page".
• User wants an OG image or social share meta for a homepage.
• User reports contrast problems, missing SEO tags, broken anchors under a fixed header, colors duplicated as raw hex.

Composition

• For Core Web Vitals / schema.org / SEO deep-dives — load seo-toolkit (this skill measures layout, contrast, tokens and a11y; the SEO-layer breadth lives there).
• For a distinctive visual DIRECTION before building — load frontend-design-taste (palette/type/signature), then run this skill to verify the result.

Workflow

1. Locate the project — static files (index.html + css/) or built SPA.
2. Serve it locally if needed: python3 -m http.server 8377 (or the project's dev server). Static files are fine over http://localhost.
3. Run audit.js (Lighthouse, real Chrome):

   node scripts/audit.js --url http://localhost:8377/ --mobile --out lh-mobile.json
   node scripts/audit.js --url http://localhost:8377/ --desktop --out lh-desktop.json
   

   Default threshold is 100; exit 0 only when every measured category is at or above it. Add --only <category> to iterate on one category.
4. Run meta_audit.py (SEO/contrast/headings/tokens, offline):

   python3 scripts/meta_audit.py --html index.html --css main.css css/demo.css --out meta.json
   

   Exit 0 = no violations; exit 1 = violations found.

• Run security_privacy_audit.py (Security/Privacy/i18n, offline) — see the section below. Exit 0 = no violations; exit 1 = violations found.

5. Fix by audit id — every fix must reference the audit it closes (e.g. audit.js color-contrast, meta_audit.py meta:description).
6. Re-audit until green on both form factors. Only then call it done.
7. Write the before/after report in the showcase format: input paths, exact commands, real output, interpretation. Explicitly list what was deliberately NOT done.

audit.js — Lighthouse runner (stable API)

• Real Chrome via chrome-launcher (default channel = installed Chrome; --no-headless to watch). No Playwright dependency, no private fields, no _ws_url transport hacks. CDP port comes from chrome.port (public).
• Lighthouse >= 13 support: module may export a namespace; the script falls back to require("lighthouse").default automatically.
• Dependency isolation: modules resolve local node_modules → NODE_PATH → npm root -g. The script explains how to install instead of dying with Cannot find module:

  npm i lighthouse chrome-launcher     # in the script's dir
  # or globally:
  npm i -g lighthouse chrome-launcher && export NODE_PATH=$(npm root -g)
  

• Output: compact JSON (--out) with per-category scores and only the failed weighted audits (id, title, score, weight) — no 4000-line dump.
• Exit codes: 0 all categories ≥ threshold, 1 below threshold, 2 runner error.

meta_audit.py — static audit (Python stdlib, offline)

Checks and their ids:

id	what it verifies
meta:title / meta:title-length	title present, ≤ 60 chars
meta:description / meta:description-length	description present, ≤ 160 chars
meta:canonical	canonical link
meta:og:*, meta:og:size	OG tags; image must declare 1200×630 (crop-safe)
meta:twitter:card	twitter card tag
meta:json-ld	any application/ld+json script
meta:robots	not blocked with noindex/nofollow
meta:sitemap-link	sitemap referenced
headings:single-h1	exactly one h1
headings:order	h1→h6 sequence, no level skips (h1→h3 is a violation)
tokens:raw-hex	zero raw hex outside the token block (:root/tokens)
contrast:wcag-aa	computed WCAG relative luminance, fg/bg pairs ≥ 4.5:1
adaptive:scroll-padding	fixed header ⇒ scroll-padding-top present
adaptive:media-queries	responsive breakpoints exist for tablet widths
a11y:img-alt	every <img> has an alt attribute (decorative may be empty) — WCAG 1.1.1 / axe image-alt
a11y:button-name / a11y:link-name	buttons and links have an accessible name (text or aria-label) — WCAG 4.1.2 / axe button-name, link-name
a11y:form-label	inputs/selects/textareas have a label (<label for>, wrapper, aria-label) — WCAG 4.1.2 / axe label

Security, Privacy & i18n (static, offline)

scripts/security_privacy_audit.py extends the skill with the Front-End-Checklist Security (22), Privacy (5) and Internationalization (5) categories — the statically verifiable subset. It is pure Python 3 stdlib (no requests/bs4/ PyYAML), mirrors meta_audit.py's JSON/exit-code conventions, and emits audit ids prefixed sec: / priv: / i18n:. It does NOT duplicate the dedicated sibling skills' a11y/perf/testing checks — only Security/Privacy/i18n.

python3 scripts/security_privacy_audit.py --html index.html --css main.css --js app.js --out sec.json
python3 scripts/security_privacy_audit.py --html a.html b.html --json   # stdout JSON

Exit 0 = no violations; 1 = ≥1 violation; 2 = runner error. The report is machine-readable JSON only on stdout (no human summary) — evidence gate.

id	severity	what it verifies
sec:https	high	no http:// URLs in href/src (HTTPS everywhere)
sec:mixed-content	high	no http:// in CSS url()/@import/srcset (mixed content)
sec:csp	medium	Content-Security-Policy present (meta or server header) — OWASP A05
sec:sri	high	external <script>/<link> carry integrity (SRI)
sec:security-headers	low	HSTS/XCTO/XFO/Referrer-Policy/Permissions-Policy (meta; server-side canonical)
sec:noopener	high	target="_blank" carries rel="noopener noreferrer"
sec:secrets-in-url	critical	no tokens/keys in query strings (token=/api_key=/secret=)
sec:localstorage-secrets	medium	no secret keys in localStorage/sessionStorage
sec:csrf	medium	state-changing (POST) forms carry a CSRF token
sec:eval	high	no eval()/new Function() in JS
sec:deprecated-crypto	medium	no md5/sha1 in security context
sec:external-origins	low	external script origins enumerated (info)
sec:internal-leak	medium	no internal IPs / .env references leaked
sec:cookie-flags	low	document.cookie assignments use Secure

Static subset only — runtime/header checks are manual

security_privacy_audit.py covers the static surface. The following require a live server or manual review and are NOT asserted by the script:

• Real HTTP response headers (Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, CSP as a header) — verify with frontend-performance's perf_headers.py (perf:sec:* / perf:hsts) or curl -I.
• Live cookie flags (Secure/HttpOnly/SameSite on Set-Cookie) — inspect response headers.
• CSP violation reporting, real mixed-content in dev proxies, screen-reader/locale correctness.

Routing to dedicated skills

For depth beyond this skill's baseline, delegate to the dedicated sibling skills (same skills/ dir):

• Deep accessibility (95 rules: tables, landmarks, ARIA values, focus traps, runtime contrast, screen-reader) → frontend-a11y (scripts/a11y_audit.py static + a11y_axe.mjs runtime).
• Deep performance (network/headers, Core Web Vitals, bundle size, HTTP/2, caching, service worker) → frontend-performance (perf_headers.py offline + audit.js Lighthouse).
• E2E / visual / contract / a11y-in-CI testing (Playwright, jest-axe, Pact, perf-budget CI) → frontend-testing (scaffolds configs; does not re-audit).

Do NOT re-implement those domains here — this skill owns layout/perf-SEO/tokens + the Security/Privacy/i18n static subset above; the siblings own their full categories.

Design tokens — "colors as constants"

For static projects WITHOUT a build system (plain HTML/CSS/JS), a minimal design system still applies:

• Every hex color must be declared once in the token block (a :root { --color-*: ...; } layer or a dedicated tokens.css).
• Zero raw hex anywhere else — components reference var(--color-*).
• meta_audit.py flags any raw hex outside the token block; this is the enforceable version of "no hardcoded colors".
• The same idea extends to type scale and spacing (custom properties), but the audit enforces colors only.

OG image generation — crop-safe social share

Social networks crop images differently (WhatsApp square-ish, Facebook center-crop). The skill's rules, learned the hard way:

1. Change the file name, never overwrite — social caches keyed by URL will keep showing the old preview forever. New content ⇒ new URL (e.g. og-2026-08-09.png).
2. Content must fit the central safe zone — standard 1200×630 canvas is not enough: keep the hero/graphic content within ~600–640px centered width so a square/center crop (≈630×630) never clips text or logos.
3. Force a reflow before the screenshot — after setting width via inline style, the first screenshot() may capture the stale layout. Read void element.offsetHeight (or getBoundingClientRect()) to force layout sync, then shoot.
4. Declare exact dimensions — og:image:width/og:image:height = 1200/630 so scrapers don't guess and mis-trim.
5. Re-test in 2+ networks after changing the URL (WhatsApp + Telegram at minimum; they cache most aggressively).

Fixed-header anchoring

If position: fixed header exists, anchor jumps hide content underneath. Fix: html { scroll-padding-top: <header-height> } (+ scroll-margin-top on the anchors if needed). meta_audit.py reports adaptive:scroll-padding when this is missing.

Constraints / non-goals

• audit.js opens a real Chrome; do not substitute CLI lighthouse headless-shell in the default call.
• Meta audit is offline and stdlib-only — no PyYAML, no requests.
• Do NOT fix with !important spray or target 100 by hiding audits: raise the underlying metrics (real fix at the root).
• Do NOT delete or modify user tests/screenshots; artifacts go to --out files you name.
• Lighthouse scores on localhost vs production differ (no CDN, no real TLS); state this in the report when it matters.

Examples

Full loop on a static site:

cd ~/projects/lovii_demo
python3 -m http.server 8377 &
node .../audit.js --url http://localhost:8377/ --mobile --out lh-mobile.json
node .../audit.js --url http://localhost:8377/ --desktop --out lh-desktop.json
python3 .../meta_audit.py --html index.html --css main.css css/demo.css --out meta.json

Iterate on one category until green:

node .../audit.js --url http://localhost:8377/ --mobile --only accessibility

See references/canonical-patterns.md for the canonical sources this skill is aligned with, and the showcase in docs/showcase/showcase-frontend-perfection-lovii.md.