Email Design skill for Claude Code

#!/usr/bin/env python3
"""Lint a compiled HTML email for rendering, accessibility and size problems.

Usage:
    python3 scripts/lint_email.py email.html [more.html ...] [--max-width 640]

Checks the *compiled* HTML (MJML / React Email / Maizzle output), not source
templates. Prints one line per finding and exits 1 if any ERROR was found.
Standard library only (Python 3.10+).
"""
from __future__ import annotations

import argparse
import re
import sys
from html.parser import HTMLParser

GMAIL_CLIP_BYTES = 102 * 1024          # Gmail clips the HTML body above ~102 KB
GMAIL_CLIP_WARN = 90 * 1024
GMAIL_STYLE_BYTES = 16 * 1024          # oversized <style> blocks are commonly dropped
VOID = {"img", "br", "hr", "meta", "link", "input", "source", "col", "area", "base", "wbr"}
BANNED_TAGS = {
    "script": "ERROR", "form": "WARN", "iframe": "ERROR", "video": "WARN",
    "object": "ERROR", "embed": "ERROR", "svg": "WARN", "input": "WARN", "button": "WARN",
}
HIDDEN_RE = re.compile(r"display\s*:\s*none|mso-hide\s*:\s*all|max-height\s*:\s*0|opacity\s*:\s*0", re.I)
LAYOUT_CSS_RE = re.compile(r"display\s*:\s*(flex|inline-flex|grid)|position\s*:\s*(absolute|fixed)", re.I)
WIDTH_PX_RE = re.compile(r"(?<![-\w])width\s*:\s*(\d+)px", re.I)


class EmailLinter(HTMLParser):
    def __init__(self, max_width: int) -> None:
        super().__init__(convert_charrefs=True)
        self.max_width = max_width
        self.findings: list[tuple[str, int, str]] = []
        self.stack: list[str] = []
        self.has_doctype = False
        self.html_lang = False
        self.meta_charset = False
        self.meta_viewport = False
        self.meta_color_scheme = False
        self.in_style = False
        self.style_bytes = 0
        self.style_text: list[str] = []
        self.body_seen = False
        self.first_body_text_hidden: bool | None = None
        self.hidden_depth: int | None = None
        self.text_chars = 0
        self.img_count = 0
        self.table_count = 0
        self.presentation_tables = 0
        self.table_stack: list[dict] = []
        self.in_title = False
        self.title_text = ""

    def add(self, level: str, msg: str) -> None:
        self.findings.append((level, self.getpos()[0], msg))

    def handle_decl(self, decl: str) -> None:
        if decl.lower().startswith("doctype"):
            self.has_doctype = True

    def handle_starttag(self, tag: str, attrs_list) -> None:
        attrs = {k.lower(): (v or "") for k, v in attrs_list}
        style = attrs.get("style", "")
        if tag not in VOID:
            self.stack.append(tag)
            if self.hidden_depth is None and HIDDEN_RE.search(style) and self.body_seen:
                self.hidden_depth = len(self.stack)

        if tag == "html":
            self.html_lang = bool(attrs.get("lang"))
        elif tag == "meta":
            if "charset" in attrs or attrs.get("http-equiv", "").lower() == "content-type":
                self.meta_charset = True
            name = attrs.get("name", "").lower()
            if name == "viewport":
                self.meta_viewport = True
            if name in ("color-scheme", "supported-color-schemes"):
                self.meta_color_scheme = True
        elif tag == "title":
            self.in_title = True
        elif tag == "link" and "stylesheet" in attrs.get("rel", "").lower():
            href = attrs.get("href", "")
            if "fonts.googleapis.com" in href or "fonts.bunny.net" in href:
                self.add("INFO", "web font <link>: only some clients load it; keep a system fallback stack")
            else:
                self.add("ERROR", f"external stylesheet <link href='{href}'>: most clients strip it; inline the CSS")
        elif tag == "style":
            self.in_style = True
        elif tag == "body":
            self.body_seen = True
        elif tag == "img":
            self.img_count += 1
            src = attrs.get("src", "")
            if "alt" not in attrs:
                self.add("ERROR", f"<img src='{src[:60]}'> has no alt attribute (use alt=\"\" for decorative images)")
            if src and not src.startswith(("https://", "cid:", "data:")):
                level = "ERROR" if not src.startswith("http://") else "WARN"
                self.add(level, f"<img src='{src[:60]}'> is not an absolute https URL")
            if src.startswith("data:"):
                self.add("WARN", "data: URI image: blocked by Gmail and Outlook, and inflates size toward clipping")
            if "width" not in attrs:
                self.add("WARN", f"<img src='{src[:60]}'> lacks a width attribute; classic Outlook renders it at native size")
            elif attrs["width"].isdigit() and int(attrs["width"]) > self.max_width:
                self.add("WARN", f"<img> width={attrs['width']} exceeds {self.max_width}px")
        elif tag == "table":
            self.table_count += 1
            role = attrs.get("role", "").lower()
            if role == "presentation":
                self.presentation_tables += 1
            self.table_stack.append({"role": role, "has_th": False, "line": self.getpos()[0]})
            w = attrs.get("width", "")
            if w.isdigit() and int(w) > self.max_width:
                self.add("WARN", f"<table width={w}> exceeds {self.max_width}px; stays wide on mobile and in preview panes")
        elif tag == "th" and self.table_stack:
            self.table_stack[-1]["has_th"] = True
        elif tag == "a":
            href = attrs.get("href", "").strip()
            if not href or href == "#":
                self.add("WARN", "<a> with empty or '#' href")
            elif href.lower().startswith("javascript:"):
                self.add("ERROR", "<a href='javascript:...'> is stripped by every client")
        elif tag in BANNED_TAGS:
            self.add(BANNED_TAGS[tag], f"<{tag}> is unsupported or stripped in major email clients")

        if tag == "div" and LAYOUT_CSS_RE.search(style):
            self.add("ERROR", f"<div style='{style[:50]}'> uses flex/grid/absolute positioning; classic Outlook ignores it — use tables")
        elif LAYOUT_CSS_RE.search(style):
            self.add("WARN", f"<{tag}> uses flex/grid/absolute positioning; check fallback in Outlook and Gmail")
        for m in WIDTH_PX_RE.finditer(style):
            if int(m.group(1)) > self.max_width and "max-width" not in style[: m.start()].lower()[-12:]:
                self.add("WARN", f"<{tag}> inline width {m.group(1)}px exceeds {self.max_width}px")

    def handle_endtag(self, tag: str) -> None:
        if tag == "style":
            self.in_style = False
        if tag == "title":
            self.in_title = False
        if tag == "table" and self.table_stack:
            t = self.table_stack.pop()
            if t["role"] != "presentation" and not t["has_th"]:
                self.findings.append(("WARN", t["line"], "layout <table> without role=\"presentation\"; screen readers announce rows and columns"))
        if tag in self.stack:
            while self.stack:
                popped = self.stack.pop()
                if self.hidden_depth is not None and len(self.stack) < self.hidden_depth:
                    self.hidden_depth = None
                if popped == tag:
                    break

    def handle_data(self, data: str) -> None:
        if self.in_style:
            self.style_bytes += len(data.encode())
            self.style_text.append(data)
            return
        if self.in_title:
            self.title_text += data
        if not self.body_seen:
            return
        text = data.strip().replace("‌", "").replace(" ", "").replace("͏", "")
        if text:
            if self.first_body_text_hidden is None:
                self.first_body_text_hidden = self.hidden_depth is not None
            self.text_chars += len(text)


def lint(path: str, max_width: int) -> int:
    with open(path, "rb") as fh:
        raw = fh.read()
    size = len(raw)
    html = raw.decode("utf-8", errors="replace")
    p = EmailLinter(max_width)
    p.feed(html)
    p.close()

    if size > GMAIL_CLIP_BYTES:
        p.findings.append(("ERROR", 0, f"HTML is {size/1024:.1f} KB; Gmail clips above ~102 KB (hides footer and unsubscribe)"))
    elif size > GMAIL_CLIP_WARN:
        p.findings.append(("WARN", 0, f"HTML is {size/1024:.1f} KB; close to Gmail's ~102 KB clipping threshold"))
    if not p.has_doctype:
        p.findings.append(("WARN", 0, "missing <!DOCTYPE html>; some clients fall into quirks mode"))
    if not p.html_lang:
        p.findings.append(("ERROR", 0, "<html> has no lang attribute; screen readers guess the language"))
    if not p.meta_charset:
        p.findings.append(("WARN", 0, "no <meta charset>; non-ASCII text may garble"))
    if not p.meta_viewport:
        p.findings.append(("WARN", 0, "no <meta name=viewport>; mobile clients may zoom out"))
    if not p.meta_color_scheme:
        p.findings.append(("INFO", 0, "no color-scheme meta; Apple Mail will not apply your dark-mode styles"))
    if not p.title_text.strip():
        p.findings.append(("WARN", 0, "empty <title>; shown by some clients and web views"))
    if p.style_bytes > GMAIL_STYLE_BYTES:
        p.findings.append(("WARN", 0, f"<style> totals {p.style_bytes/1024:.1f} KB; Gmail may drop oversized style blocks"))
    css = "".join(p.style_text)
    if css and css.count("{") != css.count("}"):
        p.findings.append(("ERROR", 0, "unbalanced braces in <style>; Gmail discards the entire block on a syntax error"))
    if p.first_body_text_hidden is not True:
        p.findings.append(("WARN", 0, "no hidden preheader as first body text; inbox preview will show the first visible text"))
    if p.img_count and p.text_chars < 200:
        p.findings.append(("WARN", 0, f"only {p.text_chars} chars of live text with {p.img_count} images; image-only emails fail with images off and hurt deliverability"))
    if p.table_count == 0:
        p.findings.append(("WARN", 0, "no tables found; div-only layouts break in classic Outlook for Windows"))

    order = {"ERROR": 0, "WARN": 1, "INFO": 2}
    p.findings.sort(key=lambda f: (order[f[0]], f[1]))
    print(f"== {path} ({size/1024:.1f} KB, {p.table_count} tables, {p.img_count} images)")
    for level, line, msg in p.findings:
        loc = f"L{line}" if line else "doc"
        print(f"  {level:<5} {loc:<6} {msg}")
    errors = sum(1 for f in p.findings if f[0] == "ERROR")
    warns = sum(1 for f in p.findings if f[0] == "WARN")
    print(f"  -> {errors} error(s), {warns} warning(s)")
    return errors


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("files", nargs="+", help="compiled .html email files")
    ap.add_argument("--max-width", type=int, default=640, help="widest allowed fixed width in px (default 640)")
    args = ap.parse_args()
    total = 0
    for f in args.files:
        try:
            total += lint(f, args.max_width)
        except OSError as exc:
            print(f"ERROR cannot read {f}: {exc}", file=sys.stderr)
            total += 1
    return 1 if total else 0


if __name__ == "__main__":
    sys.exit(main())