Skip to content

bestdeejay-design/agent-skills / skills/frontend-perfection

frontend-perfection

Verified

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'.

FileKindSize
SKILL.mdskill md15.7 KB
evals/evals.jsonconfig598 B
readme.ru.mdmarkdown3.0 KB
references/canonical-patterns.mdmarkdown5.4 KB
scripts/audit.jsscript9.8 KB
scripts/meta_audit.pyscript31.2 KB
scripts/package.jsonmanifest25 B
scripts/security_privacy_audit.pyscript23.8 KB
skill.jsonconfig2.5 KB

scripts/meta_audit.py

View on GitHub
#!/usr/bin/env python3
"""frontend-perfection — static meta/SEO/design-tokens audit (Python stdlib).

Offline, dependency-free check of a static frontend (HTML + CSS):
  - SEO meta layer: title length, meta description, canonical, OG (1200x630
    safe zone awareness), Twitter card, JSON-LD, robots, sitemap reference.
  - Contrast: WCAG 2.x relative luminance computation for color pairs found
    in CSS (`color`/`background-color`) — measured, not eyeballed.
  - Heading order: h1..h6 sequence, exactly one h1.
  - Design tokens: raw hex colors outside the token block (`:root` / tokens
    file) are violations — all colors must live in tokens.
   - Adaptive hints: fixed-header present -> require scroll-padding-top;
     horizontal overflow candidates at tablet widths (media queries with
     min/max-width that don't reflow the container).
   - Accessibility (axe-core rules, offline subset): img-alt (WCAG 1.1.1),
     button-name / link-name (WCAG 4.1.2, 2.4.4), form-label (WCAG 4.1.2,
     3.3.2), aria-valid (WAI-ARIA 1.2), landmark-unique (WCAG 1.3.1).
   - Front-End Checklist-inspired checks: document (doctype/charset/viewport/
     lang/dir/unique-ids/semantics/favicons/manifest/SRI/defer-async),
     images (dimensions/lazy/srcset/format), JS (inline/console),
     CSS quality (focus styles/print/dark-mode/font-display), perf hints
     (preload/preconnect/render-blocking), security (https/noopener),
     privacy & i18n (consent mention/RTL dir).

Usage:
  python3 meta_audit.py --html index.html --css css/main.css [--css css/*.css]
                        [--out report.json] [--json] [--tokens-block ":root"]

Exit codes: 0 = no violations; 1 = at least one violation found.
"""
import argparse
import html.parser
import json
import os
import re
import sys


# ---------------------------------------------------------------- token colors
HEX_RE = re.compile(r"#[\da-fA-F]{3,8}\b")
RGB_RE = re.compile(r"rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)")

# Colors that conventionally live outside the token block without harm:
# base/transparent values. Everything else must be tokenized.
SHADOW_GREYS = {"#000", "#fff"}


def hex_to_rgb(h):
    h = h.lstrip("#")
    if len(h) in (3, 4):
        h = "".join(c * 2 for c in h)
    if len(h) in (6, 8):
        return tuple(int(h[i : i + 2], 16) for i in (0, 2, 4))
    return None


def parse_color(text):
    m = HEX_RE.search(text)
    if m:
        rgb = hex_to_rgb(m.group(0))
        if rgb:
            return rgb
    m = RGB_RE.search(text)
    if m:
        return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
    return None


def relative_luminance(rgb):
    """WCAG 2.x relative luminance, 0..1."""
    vals = []
    for c in rgb:
        c = c / 255.0
        vals.append(c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4)
    r, g, b = vals
    return 0.2126 * r + 0.7152 * g + 0.0722 * b


def contrast_ratio(a, b):
    la, lb = relative_luminance(a), relative_luminance(b)
    lighter, darker = max(la, lb), min(la, lb)
    return (lighter + 0.05) / (darker + 0.05)


# ---------------------------------------------------------------- HTML parsing
class MetaExtractor(html.parser.HTMLParser):
    def __init__(self):
        super().__init__(convert_charrefs=True)
        self.title = []
        self.meta = {}          # (attr, name_or_property) -> content
        self.links = []         # (rel, href)
        self.headings = []      # (level, text)
        self.has_jsonld = False
        self._in_title = False
        self._in_script = False
        self._script_tag = None
        # axe-core offline subset: image-alt / button-name / link-name / label / aria-valid-attr / landmark-unique
        self.stack = []            # (tag, attrs, textbuf)
        self.imgs = []
        self.buttons = []
        self.anchors = []
        self.inputs = []
        self.labels_for = []
        self.aria_attrs = []
        self.landmark_main = 0
        self.landmark_navs = []
        self.ids = []
        self.first_top_id = None
        self.top_markers = []
        # Front-End Checklist collectors
        self.html_attrs = {}
        self.link_attrs = []     # {rel, href, integrity, media, as}
        self.scripts = []        # {src, defer, async, type, integrity}
        self.img_details = []    # {src, width, height, loading, srcset}
        self.inline_styles = 0
        self.inline_handlers = 0
        self.style_blocks = 0
        self.http_urls = []
        self.charset = ""
        self.semantic_tags = []
        self.inline_scripts = 0
        self._svg_depth = 0

    def handle_starttag(self, tag, attrs):
        attrs = dict(attrs)
        self.stack.append([tag, attrs, []])
        if tag == "img":
            self.imgs.append("alt" in attrs)
            self.img_details.append({
                "src": attrs.get("src", ""),
                "width": attrs.get("width", ""),
                "height": attrs.get("height", ""),
                "loading": attrs.get("loading", ""),
                "srcset": attrs.get("srcset", ""),
            })
            if attrs.get("src", "").startswith("http://"):
                self.http_urls.append(attrs["src"])
        elif tag == "label":
            self.labels_for.append(attrs.get("for", ""))
        elif tag == "html":
            self.html_attrs = attrs
        elif tag == "main":
            self.landmark_main += 1
        elif tag == "nav":
            self.landmark_navs.append(attrs.get("aria-label") or attrs.get("title") or "")
        elif tag in ("input", "select", "textarea"):
            self.inputs.append({
                "tag": tag,
                "id": attrs.get("id", ""),
                "type": attrs.get("type", ""),
                "aria_label": attrs.get("aria-label"),
                "aria_labelledby": attrs.get("aria-labelledby"),
                "wrapped": any(t == "label" for t, _, _ in self.stack[:-1]),
            })
        for k in attrs:
            if k.startswith("aria-"):
                self.aria_attrs.append(k)
            elif k.startswith("on") and k not in ("onload", "onerror"):
                self.inline_handlers += 1
        if "style" in attrs:
            self.inline_styles += 1
        if tag == "style":
            self.style_blocks += 1
        aid = attrs.get("id", "")
        if aid:
            self.ids.append(aid)
        if tag in ("header", "section", "footer", "main", "article", "nav"):
            self.semantic_tags.append(tag)
        if tag in ("section", "header", "main") and self.first_top_id is None and aid:
            self.first_top_id = aid
        if tag != "html":
            cls = (attrs.get("class", "") or "").lower()
            lbl = (attrs.get("aria-label", "") or "").lower()
            if re.search(r"(to-?top|scroll-?top|back-?to-?top|totop|^top$)", cls + " " + aid) or re.search(r"(back to top|to top|наверх|вверх)", lbl):
                self.top_markers.append(tag)
        if tag == "title":
            self._in_title = True
        elif tag == "svg":
            self._svg_depth += 1
        elif tag == "meta":
            key = attrs.get("name") or attrs.get("property") or attrs.get("http-equiv") or attrs.get("itemprop")
            if key:
                self.meta[key.lower()] = attrs.get("content", "")
            if attrs.get("charset"):
                self.charset = attrs["charset"]
        elif tag == "link":
            rel = (attrs.get("rel") or "").lower()
            self.links.append((rel, attrs.get("href", "")))
            self.link_attrs.append({
                "rel": rel,
                "href": attrs.get("href", ""),
                "integrity": attrs.get("integrity", ""),
                "media": attrs.get("media", ""),
                "as": attrs.get("as", ""),
            })
            if attrs.get("href", "").startswith("http://"):
                self.http_urls.append(attrs["href"])
        elif tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
            self.headings.append((tag, ""))
            self._cur_heading = tag
        elif tag == "script":
            t = (attrs.get("type") or "").lower()
            self._script_tag = (t, attrs.get("id", ""))
            self._in_script = True
            self.scripts.append({
                "src": attrs.get("src", ""),
                "defer": "defer" in attrs,
                "async": "async" in attrs,
                "type": t,
                "integrity": attrs.get("integrity", ""),
            })
            if not attrs.get("src") and t not in ("application/ld+json", "application/json"):
                self.inline_scripts += 1
            if attrs.get("src", "").startswith("http://"):
                self.http_urls.append(attrs["src"])
        elif tag == "html":
            pass

    def handle_endtag(self, tag):
        if self.stack:
            popped = self.stack.pop()
            ptag, pattrs, buf = popped
            text = " ".join("".join(buf).split())
            if self.stack:
                self.stack[-1][2].append(text)
            if ptag == "button":
                self.buttons.append({"name": text, "aria": pattrs.get("aria-label") or pattrs.get("aria-labelledby")})
            elif ptag == "a":
                self.anchors.append({
                    "name": text,
                    "aria": pattrs.get("aria-label") or pattrs.get("aria-labelledby") or pattrs.get("title"),
                    "href": pattrs.get("href", ""),
                    "target": pattrs.get("target", ""),
                    "rel": pattrs.get("rel", ""),
                })
                if pattrs.get("href", "").startswith("http://"):
                    self.http_urls.append(pattrs["href"])
        if tag == "title":
            self._in_title = False
        elif tag == "svg":
            self._svg_depth = max(0, self._svg_depth - 1)
        elif tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
            self._cur_heading = None
        elif tag == "script":
            self._in_script = False
            self._script_tag = None

    def handle_data(self, data):
        if self.stack:
            self.stack[-1][2].append(data)
        if self._in_title and self._svg_depth == 0:
            self.title.append(data)
        elif getattr(self, "_cur_heading", None):
            # accumulate heading text across nested tags
            for i, (t, txt) in enumerate(self.headings):
                if t == self._cur_heading and i == len(self.headings) - 1:
                    self.headings[i] = (t, txt + " " + data.strip())
        if self._in_script and self._script_tag and self._script_tag[0] in ("application/ld+json",):
            self.has_jsonld = True


# ---------------------------------------------------------------- CSS helpers
def token_block_ranges(css):
    """Indices of :root / [data-theme] / tokens blocks (CSS custom property definitions)."""
    ranges = []
    for m in re.finditer(r"(:root|\[data-theme[^\]]*\]|\.tokens|\$\{tokens\}|\btokens\b)\s*\{", css):
        start = m.end() - 1
        depth, i = 1, start + 1
        while i < len(css) and depth:
            if css[i] == "{":
                depth += 1
            elif css[i] == "}":
                depth -= 1
            i += 1
        ranges.append((start, i))
    return ranges


def is_inside(pos, ranges):
    return any(s <= pos < e for s, e in ranges)


def extract_pairs(css):
    """(fg, bg) color pairs from rules, approximated: nearest color declarations
    within the same rule block."""
    pairs = []
    for block in re.finditer(r"\{([^{}]*)\}", css):
        body = block.group(1)
        fg = None
        bg = None
        for m in re.finditer(r"(?:color|background-color|background)\s*:\s*([^;}]+)", body):
            val = m.group(1).strip().split()[0] if m.group(1) else ""
            parsed = parse_color(val)
            if parsed is None:
                continue
            if m.group(0).startswith("color"):
                fg = parsed
            elif m.group(0).startswith("background") and m.group(1).strip().startswith("#"):
                bg = parsed
        if fg and bg:
            pairs.append((fg, bg, body.strip()[:80]))
    return pairs


# ---------------------------------------------------------------- audit core
def audit_meta(ext, path):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "meta:" + name, "ok": ok, "detail": detail})

    title = " ".join(ext.title).strip()
    add("title", bool(title), f"title tag: {title[:80]!r}")
    if title:
        add("title-length", len(title) <= 60, f"title length {len(title)} (limit 60)")

    desc = ext.meta.get("description", "")
    add("description", bool(desc), f"meta description: {desc[:80]!r}")
    if desc:
        add("description-length", len(desc) <= 160, f"description length {len(desc)} (limit 160)")

    canon = next((h for rel, h in ext.links if "canonical" in rel), "")
    add("canonical", bool(canon), f"canonical: {canon or 'MISSING'}")

    og = {k: v for k, v in ext.meta.items() if k.startswith("og:")}
    add("og:title", bool(og.get("og:title")), "og:title " + ("OK" if og.get("og:title") else "MISSING"))
    add("og:image", bool(og.get("og:image")), "og:image " + ("OK" if og.get("og:image") else "MISSING"))
    ogw = og.get("og:image:width")
    ogh = og.get("og:image:height")
    if og.get("og:image") and ogw and ogh:
        add("og:size", (int(ogw), int(ogh)) == (1200, 630), f"og:image {ogw}x{ogh} (standard 1200x630; crop-safe ~640px content zone)")
    else:
        add("og:size", False, "og:image:width/height not declared — social crop not predictable")

    tw = {k: v for k, v in ext.meta.items() if k.startswith("twitter:")}
    add("twitter:card", bool(tw.get("twitter:card")), "twitter:card " + ("OK" if tw.get("twitter:card") else "MISSING"))

    add("json-ld", ext.has_jsonld, "JSON-LD structured data " + ("found" if ext.has_jsonld else "MISSING"))

    robots = next((v for k, v in ext.meta.items() if k == "robots"), "")
    add("robots", "noindex" not in robots and "nofollow" not in robots, f"robots: {robots or 'not set (crawlable)'}")

    sitemap = any("sitemap" in rel or "sitemap" in h for rel, h in ext.links)
    add("sitemap-link", sitemap, "sitemap link " + ("found" if sitemap else "not referenced"))

    return checks


def audit_headings(ext):
    checks = []
    levels = [int(t[0][1]) for t in ext.headings]
    h1s = [t for t in ext.headings if t[0] == "h1"]
    checks.append({"id": "headings:single-h1", "ok": len(h1s) == 1, "detail": f"{len(h1s)} h1 tag(s)"})
    skipped = [(a, b) for a, b in zip(levels, levels[1:]) if b > a + 1]
    checks.append({
        "id": "headings:order",
        "ok": not skipped,
        "detail": (" → ".join(f"h{l}" for l in levels) or "(no headings)")
        + (f" — level skipped: {', '.join(f'h{a}→h{b}' for a, b in skipped)}" if skipped else ""),
    })
    return checks


def audit_design_tokens(css, tokens_block=True):
    checks = []
    ranges = token_block_ranges(css) if tokens_block else []
    raw_hex = []
    for m in HEX_RE.finditer(css):
        pos = m.start()
        if is_inside(pos, ranges):
            continue
        val = m.group(0).lower()
        if val in SHADOW_GREYS:
            continue
        raw_hex.append((m.group(0), pos))
    if raw_hex:
        preview = ", ".join(f"{c}@{p}" for c, p in raw_hex[:6])
        tail = f" (+{len(raw_hex) - 6} more)" if len(raw_hex) > 6 else ""
        checks.append({"id": "tokens:raw-hex", "ok": False, "detail": f"{len(raw_hex)} raw hex outside token block: {preview}{tail}"})
    else:
        checks.append({"id": "tokens:raw-hex", "ok": True, "detail": "no raw hex outside token block"})
    return checks


def audit_contrast(css):
    checks = []
    pairs = extract_pairs(css)
    checked = 0
    violations = 0
    for fg, bg, snippet in pairs:
        ratio = contrast_ratio(fg, bg)
        checked += 1
        if ratio < 4.5:
            violations += 1
            checks.append({
                "id": "contrast:wcag-aa",
                "ok": False,
                "detail": f"ratio {ratio:.2f}:1 (< 4.5:1) — {snippet!r}",
            })
    if checked == 0:
        checks.append({"id": "contrast:wcag-aa", "ok": True, "detail": "no explicit fg/bg color pairs found (cannot verify)"})
    elif violations == 0:
        checks.append({"id": "contrast:wcag-aa", "ok": True, "detail": f"all {checked} fg/bg pairs >= 4.5:1"})
    return checks


def audit_adaptive(css):
    checks = []

    fixed_header = re.search(r"position\s*:\s*fixed", css) is not None
    if fixed_header:
        has_sp = re.search(r"scroll-padding-top\s*:", css) is not None
        checks.append({
            "id": "adaptive:scroll-padding",
            "ok": has_sp,
            "detail": "position:fixed found — " + ("scroll-padding-top present" if has_sp else "MISSING scroll-padding-top (anchors hide under header)"),
        })
    else:
        checks.append({"id": "adaptive:scroll-padding", "ok": True, "detail": "no fixed header — no scroll-padding needed"})

    # Horizontal overflow candidates: media min-width breakpoints that don't
    # contain a width-reflow (max-width: 100% / width: auto inside blocks).
    mq = re.findall(r"@media[^{]+\{", css)
    checks.append({
        "id": "adaptive:media-queries",
        "ok": bool(mq),
        "detail": f"{len(mq)} media quer{'y' if len(mq) == 1 else 'ies'}" + ("" if mq else " — responsive breakpoints MISSING for tablet widths (768-1024)"),
    })
    return checks


# ---------------------------------------------------------------- a11y (axe-core subset)
VALID_ARIA = {
    "aria-activedescendant", "aria-atomic", "aria-autocomplete", "aria-braillelabel",
    "aria-brailleroledescription", "aria-busy", "aria-checked", "aria-colcount",
    "aria-colindex", "aria-colindextext", "aria-colspan", "aria-controls", "aria-current",
    "aria-describedby", "aria-description", "aria-details", "aria-disabled", "aria-dropeffect",
    "aria-errormessage", "aria-expanded", "aria-flowto", "aria-grabbed", "aria-haspopup",
    "aria-hidden", "aria-invalid", "aria-keyshortcuts", "aria-label", "aria-labelledby",
    "aria-level", "aria-live", "aria-modal", "aria-multiline", "aria-multiselectable",
    "aria-orientation", "aria-owns", "aria-placeholder", "aria-posinset", "aria-pressed",
    "aria-readonly", "aria-relevant", "aria-required", "aria-roledescription",
    "aria-rowcount", "aria-rowindex", "aria-rowindextext", "aria-rowspan", "aria-selected",
    "aria-setsize", "aria-sort", "aria-valuemax", "aria-valuemin", "aria-valuenow",
    "aria-valuetext",
}


def audit_a11y(ext):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "a11y:" + name, "ok": ok, "detail": detail})

    bad_imgs = [i for i, has_alt in enumerate(ext.imgs) if not has_alt]
    add("img-alt", not bad_imgs,
        f"{len(ext.imgs)} img, {len(bad_imgs)} without alt attribute (WCAG 1.1.1 / axe image-alt)"
        + (" — decorative images may use empty alt=\"\"" if not bad_imgs else ""))

    bad_btns = [b for b in ext.buttons if not (b["name"] or b["aria"])]
    add("button-name", not bad_btns,
        f"{len(ext.buttons)} buttons, {len(bad_btns)} without accessible name (WCAG 4.1.2 / axe button-name)"
        + (" — icon-only buttons need aria-label" if bad_btns else ""))

    bad_links = [a for a in ext.anchors if not (a["name"] or a["aria"])]
    add("link-name", not bad_links,
        f"{len(ext.anchors)} links, {len(bad_links)} without accessible name (WCAG 4.1.2 / axe link-name)"
        + (" — add text or aria-label" if bad_links else ""))

    bad_inputs = [
        i for i in ext.inputs
        if not (i["aria_label"] or i["aria_labelledby"] or i["wrapped"] or i["id"] in ext.labels_for)
    ]
    add("form-label", not bad_inputs,
        f"{len(ext.inputs)} form fields, {len(bad_inputs)} without label (WCAG 4.1.2 / axe label)"
        + (" — add <label for> or aria-label" if bad_inputs else ""))

    bad_aria = sorted({a for a in ext.aria_attrs if a not in VALID_ARIA})
    add("aria-valid", not bad_aria,
        f"{len(ext.aria_attrs)} aria attributes"
        + (f", invalid: {bad_aria[:5]} (WAI-ARIA 1.2 / axe aria-valid-attr)" if bad_aria
           else " — all valid names (WAI-ARIA 1.2 / axe aria-valid-attr)"))

    lm = []
    if ext.landmark_main > 1:
        lm.append(f"{ext.landmark_main} <main> elements")
    unlabeled_navs = [l for l in ext.landmark_navs if not l]
    if len(unlabeled_navs) > 1:
        lm.append(f"{len(unlabeled_navs)} <nav> without distinct aria-label")
    add("landmark-unique", not lm,
        "; ".join(lm) if lm
        else f"{ext.landmark_main} <main>, {len(ext.landmark_navs)} <nav> — unique (WCAG 1.3.1 / axe landmark-unique)")

    return checks


# ---------------------------------------------------------------- Front-End Checklist extensions
RTL_LANGS = ("ar", "he", "fa", "ur", "yi")
RASTER_EXT = (".jpg", ".jpeg", ".png")
MODERN_EXT = (".webp", ".avif")


def audit_document(ext, html_src):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "html:" + name, "ok": ok, "detail": detail})

    has_doctype = re.search(r"^\s*<!doctype\s+html", html_src, re.IGNORECASE) is not None
    add("doctype", has_doctype, "HTML5 doctype first line " + ("OK" if has_doctype else "MISSING"))

    add("charset", bool(ext.charset.lower() == "utf-8"),
        f"charset: {ext.charset or 'MISSING'} (expected utf-8)")

    viewport = ext.meta.get("viewport", "")
    add("viewport", bool(viewport), "viewport meta " + ("OK" if viewport else "MISSING (responsive design)"))

    lang = ext.html_attrs.get("lang", "")
    add("lang", bool(lang), f"<html lang>={lang or 'MISSING'} (BCP 47 needed for a11y/SEO)")

    if lang[:2] in RTL_LANGS:
        add("dir-rtl", ext.html_attrs.get("dir") == "rtl",
            f"lang={lang} requires dir=\"rtl\" — " + ("OK" if ext.html_attrs.get("dir") == "rtl" else "MISSING"))
    else:
        add("dir-rtl", True, "no RTL language — dir attribute not required")

    dup_ids = [i for i in set(ext.ids) if ext.ids.count(i) > 1]
    add("unique-id", not dup_ids,
        f"{len(ext.ids)} ids" + (f", duplicates: {dup_ids[:5]}" if dup_ids else " — all unique"))

    sem = set(ext.semantic_tags)
    missing_sem = [t for t in ("header", "main", "footer") if t not in sem]
    add("semantic", not missing_sem,
        f"semantic elements found: {', '.join(sorted(sem)) or 'NONE'}"
        + (f" — missing: {', '.join(missing_sem)}" if missing_sem else ""))

    fav = any("icon" in l["rel"] for l in ext.link_attrs)
    add("favicons", fav, "favicon link " + ("OK" if fav else "MISSING"))

    manifest = any("manifest" in l["rel"] for l in ext.link_attrs)
    add("web-app-manifest", manifest, "manifest.json link " + ("found" if manifest else "not referenced (PWA)"))

    ext_scripts = [s for s in ext.scripts if s["src"]]
    cdn_scripts = [s for s in ext_scripts if s["src"].startswith(("http://", "https://"))]
    no_sri = [s["src"] for s in cdn_scripts if not s["integrity"]]
    add("sri", not no_sri,
        f"{len(cdn_scripts)} CDN scripts"
        + (f", {len(no_sri)} without SRI integrity (CDN tamper protection)" if no_sri else " — SRI present (local scripts exempt)"))

    blocking = [s["src"] for s in ext_scripts if not (s["defer"] or s["async"] or s["type"] == "module")]
    add("defer-async", not blocking,
        f"{len(ext_scripts)} external scripts"
        + (f", {len(blocking)} render-blocking without defer/async/module" if blocking else " — all async/defer/module"))

    untyped = [i for i in ext.inputs if i["tag"] == "input" and not i["type"]]
    add("input-types", not untyped,
        f"{len(ext.inputs)} form fields"
        + (f", {len(untyped)} inputs without type (defaults to text)" if untyped else " — types set"))

    return checks


def audit_images(ext):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "images:" + name, "ok": ok, "detail": detail})

    imgs = [i for i in ext.img_details if i["src"]]
    no_dim = [i["src"] for i in imgs if not (i["width"] and i["height"])]
    add("dimensions", not no_dim,
        f"{len(imgs)} img" + (f", {len(no_dim)} without width/height (CLS risk)" if no_dim else " — dimensions set"))

    add("lazy-loading", any(i["loading"] == "lazy" for i in imgs) or len(imgs) < 3,
        f"loading=lazy on {sum(1 for i in imgs if i['loading'] == 'lazy')}/{len(imgs)} img — 3+ images should lazy load offscreen content")

    add("srcset", any(i["srcset"] for i in imgs) or len(imgs) < 2,
        "responsive srcset " + ("found" if any(i["srcset"] for i in imgs) else "not used — fixed-size images on varying viewports"))

    raster = [i["src"] for i in imgs if i["src"].lower().endswith(RASTER_EXT)]
    modern = [i["src"] for i in imgs if i["src"].lower().endswith(MODERN_EXT)]
    add("modern-format", not raster or modern,
        f"{len(raster)} raster (jpg/png), {len(modern)} modern (webp/avif)"
        + (" — convert raster to webp/avif" if raster and not modern else ""))

    return checks


def audit_js(ext, html_src):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "js:" + name, "ok": ok, "detail": detail})

    add("no-inline", ext.inline_handlers == 0 and ext.inline_scripts == 0,
        f"inline JS: {ext.inline_handlers} handler attrs (onclick=…), {ext.inline_scripts} inline <script> blocks — keep JS in external files")

    console_hits = len(re.findall(r"console\.(?:log|debug|warn)\s*\(", html_src))
    add("no-console", console_hits == 0,
        f"{console_hits} console.{'log/debug/warn'} call(s) in HTML — remove before production")

    return checks


def audit_css_quality(css, html_src):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "css:" + name, "ok": ok, "detail": detail})

    add("focus-visible", re.search(r":focus(-visible)?\s*\{", css) is not None,
        "visible focus indicator rule " + ("found" if re.search(r":focus(-visible)?\s*\{", css) else "MISSING — keyboard users need :focus-visible styles"))

    add("print", re.search(r"@media\s+print", css) is not None,
        "print stylesheet (@media print) " + ("found" if re.search(r"@media\s+print", css) else "MISSING"))

    dark_css = re.search(r"prefers-color-scheme", css)
    dark_js = re.search(r"prefers-color-scheme|data-theme", html_src)
    add("dark-mode", bool(dark_css or dark_js),
        "dark mode " + ("in CSS (@media prefers-color-scheme)" if dark_css
                        else "via JS (data-theme/matchMedia)" if dark_js
                        else "not implemented"))

    fd_css = re.search(r"font-display\s*:\s*swap", css)
    fd_url = re.search(r"display=swap", html_src)
    add("font-display", bool(fd_css or fd_url),
        "font-display: swap " + ("in CSS @font-face" if fd_css
                                 else "in webfont URL (Google Fonts &display=swap)" if fd_url
                                 else "MISSING — text invisible while webfont loads (FOIT)"))

    return checks


def audit_perf_hints(ext):
    checks = []
    hints = {l["rel"]: l["href"] for l in ext.link_attrs if l["rel"] in ("preload", "preconnect", "dns-prefetch", "prefetch")}
    checks.append({
        "id": "perf:resource-hints",
        "ok": bool(hints),
        "detail": f"resource hints: {', '.join(hints) or 'NONE — add preload/preconnect for critical origins (LCP)'}",
    })
    return checks


def audit_security(ext):
    checks = []

    def add(name, ok, detail):
        checks.append({"id": "security:" + name, "ok": ok, "detail": detail})

    add("https", not ext.http_urls,
        f"{len(ext.http_urls)} http:// URL(s) in src/href" + (" — use https" if ext.http_urls else " — all https"))

    blank = [a["href"] for a in ext.anchors if a["target"] == "_blank" and "noopener" not in (a["rel"] or "")]
    add("noopener", not blank,
        f"{len(blank)} target=_blank link(s) without rel=noopener" + (" — add rel=\"noopener noreferrer\"" if blank else " — ok"))

    return checks


def audit_privacy_i18n(ext, html_src):
    checks = []
    low = html_src.lower()
    consent = any(k in low for k in ("cookie", "consent", "gdpr", "152-фз", "согласие"))
    checks.append({
        "id": "privacy:consent",
        "ok": consent,
        "detail": ("cookie/consent mention found — banner or policy present" if consent
                   else "no cookie/consent mention — check GDPR / 152-ФЗ compliance"),
    })
    return checks


def audit_nav(ext):
    checks = []
    top_ids = {"top", "cover", "hero", "home", "main"}
    if ext.first_top_id:
        top_ids.add(ext.first_top_id)
    has_link = any(
        a.get("href") in ("#", "#top") or a.get("href") == "#" + tid
        for tid in top_ids for a in ext.anchors
    )
    has_btn = bool(ext.top_markers)
    ok = has_link or has_btn
    checks.append({
        "id": "nav:back-to-top",
        "ok": ok,
        "detail": ("back-to-top present (logo link or scroll button)" if ok
                   else "MISSING back-to-top: long pages need a way back — logo links to top and/or a floating scroll-to-top button (arrow in a circle, bottom-right, aria-label, appears after scroll)"),
    })
    return checks

def main():
    ap = argparse.ArgumentParser(description="Static frontend meta/SEO/design-tokens/a11y audit")
    ap.add_argument("--html", required=True, help="Path to index.html")
    ap.add_argument("--css", nargs="+", required=True, help="CSS file(s) — globs expanded by shell")
    ap.add_argument("--out", help="Write JSON report to file")
    ap.add_argument("--json", action="store_true", help="Print report as JSON to stdout")
    args = ap.parse_args()

    if not os.path.isfile(args.html):
        print(f"ERROR: HTML file not found: {args.html}")
        sys.exit(2)

    css_all = []
    for c in args.css:
        if not os.path.isfile(c):
            print(f"ERROR: CSS file not found: {c}")
            sys.exit(2)
        with open(c, encoding="utf-8", errors="replace") as f:
            css_all.append(f.read())
    css = "\n".join(css_all)

    with open(args.html, encoding="utf-8", errors="replace") as f:
        html_src = f.read()

    ext = MetaExtractor()
    ext.feed(html_src)

    checks = []
    checks += audit_meta(ext, args.html)
    checks += audit_headings(ext)
    checks += audit_design_tokens(css, tokens_block=True)
    checks += audit_contrast(css)
    checks += audit_adaptive(css)



    checks += audit_a11y(ext)
    checks += audit_document(ext, html_src)
    checks += audit_images(ext)
    checks += audit_js(ext, html_src)
    checks += audit_css_quality(css, html_src)
    checks += audit_perf_hints(ext)
    checks += audit_security(ext)
    checks += audit_privacy_i18n(ext, html_src)
    checks += audit_nav(ext)

    violations = [c for c in checks if not c["ok"]]
    report = {
        "tool": "frontend-perfection/meta_audit",
        "html": args.html,
        "css": args.css,
        "checks": checks,
        "summary": {
            "total": len(checks),
            "passed": len(checks) - len(violations),
            "violations": len(violations),
        },
    }

    if args.out:
        with open(args.out, "w", encoding="utf-8") as f:
            json.dump(report, f, ensure_ascii=False, indent=2)
        print(f"Report written to {args.out}")

    if args.json:
        print(json.dumps(report, ensure_ascii=False, indent=2))
    else:
        print(f"\n[frontend-perfection] meta audit of {args.html}")
        print(f"  checks: {len(checks)}, passed: {report['summary']['passed']}, violations: {len(violations)}")
        for c in checks:
            flag = "✅" if c["ok"] else "❌"
            print(f"  {flag} {c['id']}: {c['detail']}")

    sys.exit(0 if not violations else 1)


if __name__ == "__main__":
    main()
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall