Form UX Design skill for Claude Code

#!/usr/bin/env python3
"""Audit the forms in rendered HTML for common form-UX defects.

Checks each visible field for: a programmatic label, placeholder used as the only
label, a missing or disabled autocomplete token on fields whose purpose is
recognizable (email, name, address, phone, card, password, one-time code), wrong
input types (type="number" for phone, postal code or card data; text for email),
blocked paste, asterisk-only required marking, radio/checkbox groups without a
fieldset and legend, tiny selects that should be radios, and disabled submit buttons.

Usage:
    python3 audit_form.py <file.html> [--max-fields N] [--strict]

--max-fields N  also report an error when a form asks more than N questions
                (a radio or checkbox group counts as one question)
--strict        exit 1 on warnings as well as errors

Save rendered HTML first (View Source of the live page, or
`curl -s URL > page.html`; for client-rendered apps copy document.documentElement.outerHTML).
Exit codes: 0 clean, 1 findings at the failing level, 2 unreadable input.
Standard library only.
"""
from __future__ import annotations

import re
import sys
from dataclasses import dataclass, field
from html.parser import HTMLParser
from pathlib import Path

SKIP_TYPES = {"hidden", "submit", "button", "reset", "image"}
VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"}

# (pattern on name/id/label, expected autocomplete token, expected type or None)
PURPOSES: list[tuple[str, str, str | None]] = [
    (r"e-?mail", "email", "email"),
    (r"one.?time|otp|verification.?code|\bsms.?code", "one-time-code", None),
    (r"(new|confirm|repeat).?pass", "new-password", "password"),
    (r"pass(word|wd)?\b|\bpwd\b", "current-password", "password"),
    (r"user.?name|\blogin\b", "username", None),
    (r"first.?name|given.?name|\bfname\b|forename", "given-name", None),
    (r"last.?name|family.?name|surname|\blname\b", "family-name", None),
    (r"full.?name|^name$|your.?name", "name", None),
    (r"phone|mobile|\btel\b|telephone", "tel", "tel"),
    (r"zip|postal|post.?code", "postal-code", None),
    (r"address.?(line)?.?2|addr2|apartment|suite", "address-line2", None),
    (r"address.?(line)?.?1|addr1|street", "address-line1", None),
    (r"\bcity\b|\btown\b", "address-level2", None),
    (r"\bstate\b|province|county|region", "address-level1", None),
    (r"country", "country", None),
    (r"card.?num|cc.?num|\bpan\b|credit.?card", "cc-number", None),
    (r"cvc|cvv|csc|security.?code", "cc-csc", None),
    (r"expir|\bexp\b|cc.?exp", "cc-exp", None),
    (r"name.?on.?card|card.?holder|cc.?name", "cc-name", None),
    (r"birth|\bdob\b|bday", "bday", None),
    (r"company|organi[sz]ation|employer", "organization", None),
]
NUMBER_IS_WRONG = {"tel", "postal-code", "cc-number", "cc-csc", "cc-exp", "one-time-code"}


@dataclass
class Field:
    tag: str
    attrs: dict[str, str]
    line: int
    label_text: str = ""
    in_label: bool = False
    in_fieldset_with_legend: bool = False


@dataclass
class Form:
    line: int
    fields: list[Field] = field(default_factory=list)
    submits: list[tuple[dict[str, str], int]] = field(default_factory=list)
    selects: list[tuple[Field, int]] = field(default_factory=list)


class Collector(HTMLParser):
    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self.forms: list[Form] = []
        self.current: Form | None = None
        self.labels_for: dict[str, str] = {}
        self.label_stack: list[dict] = []
        self.ids_text: dict[str, str] = {}
        self.text_capture: list[tuple[str, str, list[str]]] = []
        self.fieldsets: list[dict] = []
        self.select: Field | None = None
        self.option_count = 0
        self.button: tuple[dict[str, str], int] | None = None

    def _form(self) -> Form:
        if self.current is None:  # fields outside any <form> are grouped as a pseudo-form
            self.current = Form(line=self.getpos()[0])
            self.forms.append(self.current)
        return self.current

    def handle_starttag(self, tag, attrs_list):
        a = {k: (v or "") for k, v in attrs_list}
        line = self.getpos()[0]
        if "id" in a and tag not in VOID:
            self.text_capture.append((tag, a["id"], []))
        if tag == "form":
            self.current = Form(line=line)
            self.forms.append(self.current)
        elif tag == "label":
            self.label_stack.append({"for": a.get("for"), "text": [], "fields": []})
        elif tag == "fieldset":
            self.fieldsets.append({"legend": False})
        elif tag == "legend" and self.fieldsets:
            self.fieldsets[-1]["legend"] = True
        elif tag in ("input", "textarea", "select"):
            t = a.get("type", "text").lower() if tag == "input" else tag
            if tag == "input" and t in ("submit", "image"):
                self._form().submits.append((a, line))
                return
            if tag == "input" and t in SKIP_TYPES:
                return
            f = Field(tag=tag, attrs=a, line=line)
            f.in_fieldset_with_legend = any(fs["legend"] for fs in self.fieldsets)
            if self.label_stack:
                f.in_label = True
                self.label_stack[-1]["fields"].append(f)
            self._form().fields.append(f)
            if tag == "select":
                self.select, self.option_count = f, 0
        elif tag == "option" and self.select is not None:
            self.option_count += 1
        elif tag == "button":
            t = a.get("type", "submit").lower()
            if t == "submit":
                self._form().submits.append((a, line))

    def handle_endtag(self, tag):
        if tag == "form":
            self.current = None
        elif tag == "label" and self.label_stack:
            lab = self.label_stack.pop()
            text = " ".join("".join(lab["text"]).split())
            if lab["for"]:
                self.labels_for[lab["for"]] = text
            for f in lab["fields"]:
                f.label_text = text
        elif tag == "fieldset" and self.fieldsets:
            self.fieldsets.pop()
        elif tag == "select" and self.select is not None:
            self._form().selects.append((self.select, self.option_count))
            self.select = None
        if self.text_capture and self.text_capture[-1][0] == tag:
            _, ident, buf = self.text_capture.pop()
            self.ids_text[ident] = " ".join("".join(buf).split())

    def handle_data(self, data):
        for lab in self.label_stack:
            lab["text"].append(data)
        for _, _, buf in self.text_capture:
            buf.append(data)


def purpose_of(f: Field, label: str) -> tuple[str, str | None] | None:
    hay = " ".join([f.attrs.get("name", ""), f.attrs.get("id", ""), label]).lower()
    hay = re.sub(r"[_\-\[\]]", " ", hay)
    for pattern, token, typ in PURPOSES:
        if re.search(pattern, hay):
            return token, typ
    return None


def audit(path: Path, max_fields: int | None) -> tuple[list[str], list[str]]:
    html = path.read_text(encoding="utf-8", errors="replace")
    c = Collector()
    c.feed(html)
    errors: list[str] = []
    warns: list[str] = []
    groups: dict[str, list[Field]] = {}

    for n, form in enumerate(c.forms, 1):
        tag = f"form {n} (line {form.line})"
        visible = form.fields
        grouped = {f.attrs.get("name") or id(f) for f in visible
                   if f.tag == "input" and f.attrs.get("type", "").lower() in ("radio", "checkbox")}
        singles = [f for f in visible
                   if not (f.tag == "input" and f.attrs.get("type", "").lower() in ("radio", "checkbox"))]
        questions = len(singles) + len(grouped)
        print(f"{tag}: {questions} questions ({len(visible)} controls)")
        if max_fields is not None and questions > max_fields:
            errors.append(f"{tag}: {questions} questions exceeds --max-fields {max_fields}; justify or remove fields")
        for f in visible:
            a = f.attrs
            ident = a.get("name") or a.get("id") or f.tag
            where = f"{tag}, field '{ident}' (line {f.line})"
            label = f.label_text or c.labels_for.get(a.get("id", ""), "")
            if not label and a.get("aria-labelledby"):
                label = " ".join(c.ids_text.get(i, "") for i in a["aria-labelledby"].split()).strip()
            if not label:
                label = a.get("aria-label", "")
            itype = a.get("type", "text").lower() if f.tag == "input" else f.tag

            if itype in ("radio", "checkbox"):
                if a.get("name"):
                    groups.setdefault(f"{tag}|{a['name']}", []).append(f)
                if not label:
                    errors.append(f"{where}: {itype} has no label")
                continue

            if not label:
                if a.get("placeholder"):
                    errors.append(f"{where}: placeholder \"{a['placeholder']}\" is the only label; add a visible <label>")
                else:
                    errors.append(f"{where}: no programmatic label (label[for], wrapping label, aria-labelledby)")
            if "*" in label and "required" not in label.lower():
                warns.append(f"{where}: asterisk in label; mark optional fields with \"(optional)\" instead, or explain the asterisk once")
            if re.search(r"return\s+false|preventDefault", a.get("onpaste", "")):
                errors.append(f"{where}: paste is blocked")

            p = purpose_of(f, label)
            ac = a.get("autocomplete", "").strip().lower()
            if p:
                token, want_type = p
                if not ac:
                    warns.append(f"{where}: add autocomplete=\"{token}\" (WCAG 1.3.5, autofill)")
                elif ac in ("off", "nope", "false", "disabled"):
                    warns.append(f"{where}: autocomplete=\"{ac}\" blocks autofill; use \"{token}\"")
                elif token not in ac.split() and not (token.endswith("password") and "password" in ac):
                    warns.append(f"{where}: autocomplete=\"{ac}\" — expected a token like \"{token}\"; check the purpose")
                if itype == "number" and token in NUMBER_IS_WRONG:
                    errors.append(f"{where}: type=\"number\" for {token}; use type=\"text\" inputmode=\"numeric\" (or type=\"tel\" for phone)")
                if want_type == "email" and itype not in ("email",):
                    warns.append(f"{where}: use type=\"email\" for the email keyboard and autofill")
                if want_type == "tel" and itype not in ("tel",):
                    warns.append(f"{where}: use type=\"tel\" for the phone keypad")
                if token == "new-password" and re.search(r"confirm|repeat|again", (ident + label).lower()):
                    warns.append(f"{where}: confirm-password field; a show-password toggle usually replaces it")

        for sel, count in form.selects:
            ident = sel.attrs.get("name") or sel.attrs.get("id") or "select"
            real = count - (1 if count > 0 else 0)  # allow one placeholder option
            if 0 < real <= 2:
                warns.append(f"{tag}, select '{ident}' (line {sel.line}): {real} real options; radios show the choice without a click")

        if not form.submits:
            warns.append(f"{tag}: no submit button found")
        for attrs, line in form.submits:
            if "disabled" in attrs:
                warns.append(f"{tag}, submit (line {line}): disabled submit hides why the form cannot be sent; keep it enabled and show errors")

    for key, fields in groups.items():
        if len(fields) > 1 and not all(f.in_fieldset_with_legend for f in fields):
            tag, name = key.split("|", 1)
            warns.append(f"{tag}: group '{name}' ({len(fields)} options) needs <fieldset> with <legend> holding the question")

    if not c.forms:
        warns.append("no form fields found — is this the rendered HTML?")
    return errors, warns


def main() -> int:
    args = sys.argv[1:]
    if not args or args[0] in ("-h", "--help"):
        print(__doc__)
        return 2
    strict = "--strict" in args
    max_fields = None
    if "--max-fields" in args:
        i = args.index("--max-fields")
        try:
            max_fields = int(args[i + 1])
        except (IndexError, ValueError):
            print("error: --max-fields needs an integer", file=sys.stderr)
            return 2
    path = Path(args[0])
    if not path.is_file():
        print(f"error: cannot read {path}", file=sys.stderr)
        return 2
    errors, warns = audit(path, max_fields)
    for e in errors:
        print(f"ERROR  {e}")
    for w in warns:
        print(f"WARN   {w}")
    print(f"\n{len(errors)} error(s), {len(warns)} warning(s)")
    if errors or (strict and warns):
        return 1
    return 0


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