alirezarezvani/claude-skills / product-team/design-qa/skills/design-qa
design-qa
VerifiedUse when a UI screen, page or component is about to be called done, handed off or shipped, or when generated UI looks generic or half-finished. Gates the rendered result, not the design file - finds controls that do nothing, placeholder copy, removed focus rings, missing loading/empty/error states, low contrast, small targets, hidden focus and broken reflow measured in the real browser, and flags template defaults without blocking on taste.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| assets/capture_snapshot.mjs | script | 3.4 KB |
| assets/collect_snapshot.js | script | 9.6 KB |
| assets/finish_signoff.md | markdown | 1.8 KB |
| assets/snapshot.example.json | config | 3.1 KB |
| assets/states.example.csv | other | 1.2 KB |
| assets/waivers.example.csv | other | 263 B |
| references/generic_ui_defaults.md | markdown | 6.4 KB |
| references/interaction_states.md | markdown | 5.9 KB |
| references/rendered_checks_wcag22.md | markdown | 6.7 KB |
| scripts/finish_lint.py | script | 17.8 KB |
| scripts/rendered_audit.py | script | 16.9 KB |
| scripts/state_matrix_checker.py | script | 11.8 KB |
scripts/rendered_audit.py
View on GitHub#!/usr/bin/env python3
"""Audit a rendered-page snapshot for defects that only show up in the browser: contrast, target size, focus, clipping and reflow.
Source linters guess at what the page will look like; this reads what it did
look like. The input is a JSON snapshot taken by assets/collect_snapshot.js
(DevTools console) or assets/capture_snapshot.mjs (Playwright, with a real
keyboard focus pass), so contrast is measured on the actual background, targets
on their actual box, and focus on the actual focused style.
Findings (WCAG 2.2 Level AA unless noted)
TEXT_CONTRAST text below 4.5:1, or 3:1 for large text (1.4.3) BLOCKER
NO_FOCUS_INDICATOR focused control shows no visible change (2.4.7) BLOCKER
FOCUS_OBSCURED focused control entirely hidden by other content (2.4.11) BLOCKER
REFLOW_SCROLL horizontal scrolling at a 320 CSS px viewport (1.4.10) BLOCKER
NO_ACCESSIBLE_NAME control with an empty computed name (4.1.2) BLOCKER
TARGET_TOO_SMALL pointer target under 24x24 CSS px without the spacing exception (2.5.8) BLOCKER
NOT_KEYBOARD_REACHED control never reached by a full Tab pass (2.1.1) HIGH
TEXT_CLIPPED text cut off by overflow hidden with no ellipsis HIGH
PAGE_SCROLLS_X horizontal scrolling at a wider viewport HIGH
CONTRAST_UNVERIFIED text on an image or gradient: check by eye or with a picker WARN
FOCUS_UNVERIFIED focus not proven (script focus only, or not reached) WARN
TRUNCATED text truncated with an ellipsis: confirm the full value is reachable WARN
Waive a finding the spec allows (e.g. the 2.5.8 Equivalent or Essential
exceptions) with --waivers CSV: id, code, reason. A waiver without a reason is
rejected.
Deterministic, stdlib only, no network.
"""
import argparse
import csv
import json
import math
import re
import sys
SEV_ORDER = {"BLOCKER": 0, "HIGH": 1, "WARN": 2}
EXIT = {"BLOCKED": 4, "FINDINGS": 2, "CLEAN": 0}
MIN_TARGET = 24.0
def _rgb(s):
m = re.match(r"rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)", s or "")
if not m:
m2 = re.match(r"#([0-9a-fA-F]{6})$", s or "")
if not m2:
return None
h = m2.group(1)
return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
return tuple(float(x) for x in m.groups())
def luminance(c):
def ch(v):
v /= 255.0
return v / 12.92 if v <= 0.04045 else ((v + 0.055) / 1.055) ** 2.4
r, g, b = (ch(x) for x in c)
return 0.2126 * r + 0.7152 * g + 0.0722 * b
def contrast(a, b):
la, lb = sorted((luminance(a), luminance(b)), reverse=True)
return (la + 0.05) / (lb + 0.05)
def is_large(px, weight):
# 18pt = 24 CSS px; 14pt bold = 18.67 CSS px (WCAG "large scale").
return px >= 24 or (px >= 18.66 and weight >= 700)
def _dist_point_rect(px, py, r):
dx = max(r["x"] - px, 0, px - (r["x"] + r["w"]))
dy = max(r["y"] - py, 0, py - (r["y"] + r["h"]))
return math.hypot(dx, dy)
def spacing_ok(t, targets):
"""2.5.8 spacing exception: a 24 px circle centred on the target's box must not
intersect another target, or the circle of another undersized target."""
cx, cy = t["rect"]["x"] + t["rect"]["w"] / 2, t["rect"]["y"] + t["rect"]["h"] / 2
for o in targets:
if o is t:
continue
r = o["rect"]
undersized = r["w"] < MIN_TARGET or r["h"] < MIN_TARGET
if undersized:
ox, oy = r["x"] + r["w"] / 2, r["y"] + r["h"] / 2
if math.hypot(cx - ox, cy - oy) < MIN_TARGET:
return False
elif _dist_point_rect(cx, cy, r) < MIN_TARGET / 2:
return False
return True
def analyse(snap, waivers=None):
if not isinstance(snap, dict) or not isinstance(snap.get("elements"), list):
raise ValueError("not a design-qa snapshot (no 'elements' list); capture it with assets/collect_snapshot.js")
els = snap["elements"]
if not els:
raise ValueError("snapshot has no elements; was the page rendered when it was captured?")
vw = (snap.get("viewport") or {}).get("width")
waivers = waivers or {}
findings, used = [], set()
def add(el_id, code, sev, msg, fix):
key = (el_id, code)
if key in waivers:
used.add(key)
return
findings.append({"id": el_id, "code": code, "severity": sev, "message": msg, "fix": fix})
page = snap.get("page") or {}
if page.get("scrollWidth") and page.get("clientWidth") and page["scrollWidth"] > page["clientWidth"] + 1:
over = page["scrollWidth"] - page["clientWidth"]
code = "REFLOW_SCROLL" if vw and vw <= 320 else "PAGE_SCROLLS_X"
wide = [e for e in els if e["rect"]["x"] + e["rect"]["w"] > page["clientWidth"] + 1]
waived = [e for e in wide if (e["id"], code) in waivers]
used.update((e["id"], code) for e in waived)
wide = sorted((e for e in wide if e not in waived), key=lambda e: -(e["rect"]["x"] + e["rect"]["w"]))[:3]
culprits = ", ".join(e["id"] for e in wide) or "unknown"
if waived and not wide:
pass # every overflowing element carries a waiver (e.g. a data table, WCAG 1.4.10 exception)
elif code == "REFLOW_SCROLL":
add("page", "REFLOW_SCROLL", "BLOCKER", f"page scrolls horizontally by {over}px at {vw}px wide; widest: {culprits}",
"Let the widest elements wrap or shrink (max-width:100%, min-width:0 on flex children, overflow-wrap:anywhere).")
else:
add("page", "PAGE_SCROLLS_X", "HIGH", f"page scrolls horizontally by {over}px at {vw}px wide; widest: {culprits}",
"Find the overflowing element; it usually has a fixed width or an unbreakable string.")
targets = [e for e in els if e.get("interactive") and not e.get("disabled")]
pass_info = snap.get("keyboard_pass") or {}
for e in els:
eid = e.get("id", "?")
if e.get("text"):
fg, bg = _rgb(e.get("color")), _rgb(e.get("bg"))
if e.get("bg_unknown") or not bg:
add(eid, "CONTRAST_UNVERIFIED", "WARN", f"text '{e['text'][:40]}' sits on {e.get('bg_unknown') or 'an unknown background'}",
"Check the lightest and darkest point under the text with a color picker; add a scrim if it dips below the threshold.")
elif fg and not e.get("disabled"):
ratio = contrast(fg, bg)
need = 3.0 if is_large(e.get("fontSize", 16), e.get("fontWeight", 400)) else 4.5
if ratio + 1e-9 < need:
add(eid, "TEXT_CONTRAST", "BLOCKER",
f"'{e['text'][:40]}' is {ratio:.2f}:1 ({e.get('color')} on {e.get('bg')}, {e.get('fontSize')}px/{e.get('fontWeight')}); needs {need}:1",
"Darken the text or lighten the background until it passes; check the token, not just this element.")
if e.get("clipped"):
if e.get("ellipsis"):
add(eid, "TRUNCATED", "WARN", f"'{e.get('text', '')[:40]}' is truncated with an ellipsis",
"Make sure the full value is reachable (title, tooltip or detail view).")
else:
add(eid, "TEXT_CLIPPED", "HIGH", f"'{e.get('text', '')[:40]}' is cut off by overflow hidden",
"Let it wrap, give the box room, or truncate deliberately with an ellipsis and a way to read the rest.")
if not (e.get("interactive") and not e.get("disabled")):
continue
if not (e.get("name") or "").strip():
add(eid, "NO_ACCESSIBLE_NAME", "BLOCKER", f"<{e.get('tag')}> has no accessible name in the rendered page",
"Give it visible text, aria-label or aria-labelledby; icon-only buttons need a label.")
r = e["rect"]
if (r["w"] < MIN_TARGET or r["h"] < MIN_TARGET) and not e.get("inline") and not spacing_ok(e, targets):
add(eid, "TARGET_TOO_SMALL", "BLOCKER",
f"target is {r['w']:g}x{r['h']:g} CSS px and too close to its neighbours",
"Make the hit area at least 24x24 (padding or a pseudo-element), or space targets so 24px circles do not overlap.")
f = e.get("focus")
if f is None:
add(eid, "FOCUS_UNVERIFIED", "WARN", "no focus data in the snapshot",
"Capture with assets/capture_snapshot.mjs for a real keyboard pass.")
continue
if f.get("how") == "not reached by Tab":
if pass_info.get("wrapped"):
add(eid, "NOT_KEYBOARD_REACHED", "HIGH", "a full Tab pass never reached this control",
"Remove tabindex=-1 or make it a native control; mouse-only controls fail WCAG 2.1.1.")
else:
add(eid, "FOCUS_UNVERIFIED", "WARN", "the Tab pass stopped before reaching this control",
"Re-run capture_snapshot.mjs with a higher --tabs.")
continue
if f.get("indicator") is False:
add(eid, "NO_FOCUS_INDICATOR", "BLOCKER", f"focused <{e.get('tag')}> '{(e.get('name') or '')[:30]}' shows no visible change",
"Add a :focus-visible outline or ring with at least 3:1 contrast against its surroundings.")
elif f.get("indicator") is None:
add(eid, "FOCUS_UNVERIFIED", "WARN", f"focus indicator not proven ({f.get('how', 'unknown')})",
"Capture with assets/capture_snapshot.mjs for a real keyboard pass.")
if f.get("obscured") is True:
add(eid, "FOCUS_OBSCURED", "BLOCKER", "when focused, this control is entirely covered by other content",
"Check sticky headers, cookie banners and chat widgets; add scroll-padding-top equal to the sticky header height.")
unused = [f"{k[0]}:{k[1]}" for k in waivers if k not in used]
groups = {}
for f in findings:
g = groups.setdefault((f["code"], pattern_of(f["id"])), {
"code": f["code"], "severity": f["severity"], "pattern": pattern_of(f["id"]),
"count": 0, "examples": [], "message": f["message"], "fix": f["fix"]})
g["count"] += 1
if len(g["examples"]) < 3:
g["examples"].append(f["id"])
findings.sort(key=lambda x: (SEV_ORDER[x["severity"]], x["code"], x["id"]))
counts = {k: sum(1 for x in findings if x["severity"] == k) for k in SEV_ORDER}
verdict = "BLOCKED" if counts["BLOCKER"] else ("FINDINGS" if findings else "CLEAN")
return {"verdict": verdict, "url": snap.get("url"), "viewport": snap.get("viewport"),
"elements": len(els), "interactive": len(targets),
"keyboard_pass": "keyboard" if pass_info else "script-or-none",
"counts": counts, "waived": len(used), "unused_waivers": unused,
"groups": sorted(groups.values(), key=lambda g: (SEV_ORDER[g["severity"]], -g["count"], g["code"])),
"findings": findings}
def pattern_of(el_id):
"""Repeated components (table rows, list items) differ only in :nth-of-type
indices; dropping them groups 90 identical row buttons into one finding."""
return re.sub(r":nth-of-type\(\d+\)", "", el_id)
def load_waivers(path):
out = {}
with open(path, newline="", encoding="utf-8-sig") as fh:
for i, r in enumerate(csv.DictReader(fh), 2):
r = {(k or "").strip().lower(): (v or "").strip() for k, v in r.items()}
if not r.get("id") or not r.get("code"):
raise ValueError(f"waivers row {i}: needs id and code")
if not r.get("reason"):
raise ValueError(f"waivers row {i}: a waiver needs a reason (which WCAG exception applies?)")
out[(r["id"], r["code"].upper())] = r["reason"]
return out
def render(out):
vp = out.get("viewport") or {}
lines = [f"design-qa rendered audit: {out['verdict']} ({out.get('url')}, {vp.get('width')}x{vp.get('height')}; "
f"{out['elements']} elements, {out['interactive']} interactive; focus data: {out['keyboard_pass']}; "
f"{out['counts']['BLOCKER']} blocker, {out['counts']['HIGH']} high, {out['counts']['WARN']} warn; {out['waived']} waived)", ""]
for g in out["groups"]:
if g["count"] == 1:
lines.append(f"[{g['severity']}] {g['code']} {g['examples'][0]}")
lines.append(f" {g['message']}")
else:
lines.append(f"[{g['severity']}] {g['code']} x{g['count']} {g['pattern']}")
lines.append(f" e.g. {g['examples'][0]}: {g['message']}")
lines.append(f" fix: {g['fix']}")
for w in out["unused_waivers"]:
lines.append(f"[note] waiver {w} matched nothing; remove it")
return "\n".join(lines)
SAMPLE = {
"tool": "design-qa/collect_snapshot.js", "version": 1, "url": "http://localhost:3000/invoices",
"viewport": {"width": 320, "height": 640}, "page": {"scrollWidth": 412, "clientWidth": 320},
"keyboard_pass": {"reached": 3, "wrapped": True},
"elements": [
{"id": "h1", "tag": "h1", "interactive": False, "text": "Invoices", "rect": {"x": 16, "y": 20, "w": 288, "h": 32},
"color": "rgb(17, 24, 39)", "bg": "rgb(255, 255, 255)", "fontSize": 28, "fontWeight": 700},
{"id": "p.hint", "tag": "p", "interactive": False, "text": "Showing invoices from the last 30 days",
"rect": {"x": 16, "y": 60, "w": 288, "h": 18}, "color": "rgb(156, 163, 175)", "bg": "rgb(255, 255, 255)",
"fontSize": 14, "fontWeight": 400},
{"id": "table.invoices", "tag": "table", "interactive": False, "text": "INV-2026-0042", "rect": {"x": 16, "y": 100, "w": 396, "h": 300},
"color": "rgb(17, 24, 39)", "bg": "rgb(255, 255, 255)", "fontSize": 14, "fontWeight": 400},
{"id": "td.customer", "tag": "td", "interactive": False, "text": "Northwind Traders Internatio", "clipped": True, "ellipsis": False,
"rect": {"x": 120, "y": 140, "w": 90, "h": 20}, "color": "rgb(17, 24, 39)", "bg": "rgb(255, 255, 255)", "fontSize": 14, "fontWeight": 400},
{"id": "button.send", "tag": "button", "interactive": True, "name": "Send", "text": "Send",
"rect": {"x": 16, "y": 420, "w": 80, "h": 36}, "color": "rgb(255, 255, 255)", "bg": "rgb(37, 99, 235)",
"fontSize": 14, "fontWeight": 600, "focus": {"indicator": False, "obscured": False, "how": "keyboard"}},
{"id": "button.more", "tag": "button", "interactive": True, "name": "", "text": "",
"rect": {"x": 97, "y": 426, "w": 20, "h": 20}, "color": "rgb(75, 85, 99)", "bg": "rgb(255, 255, 255)",
"fontSize": 14, "fontWeight": 400, "focus": {"indicator": True, "obscured": False, "how": "keyboard"}},
{"id": "a.export", "tag": "a", "interactive": True, "name": "Export", "text": "Export",
"rect": {"x": 124, "y": 426, "w": 44, "h": 20}, "color": "rgb(37, 99, 235)", "bg": "rgb(255, 255, 255)",
"fontSize": 14, "fontWeight": 400, "focus": {"indicator": True, "obscured": True, "how": "keyboard"}},
{"id": "div.row-menu", "tag": "div", "role": "button", "interactive": True, "name": "Row actions", "text": "",
"rect": {"x": 280, "y": 140, "w": 24, "h": 24}, "focus": {"indicator": None, "obscured": None, "how": "not reached by Tab"}},
{"id": "section.hero > p", "tag": "p", "interactive": False, "text": "Paid on time, every time", "bg_unknown": "background image or gradient",
"rect": {"x": 16, "y": 480, "w": 288, "h": 20}, "color": "rgb(255, 255, 255)", "bg": None, "fontSize": 16, "fontWeight": 400},
],
}
def main(argv=None):
p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0],
epilog="Exit codes: 0 clean, 2 findings, 3 invalid input, 4 blocked.")
p.add_argument("--snapshot", help="snapshot JSON from assets/collect_snapshot.js or capture_snapshot.mjs")
p.add_argument("--waivers", help="CSV of allowed exceptions: id, code, reason")
p.add_argument("--sample", action="store_true", help="run on a built-in example")
p.add_argument("--output", choices=["text", "json"], default="text")
p.add_argument("--json", action="store_true", help="shorthand for --output json")
a = p.parse_args(argv)
if a.json:
a.output = "json"
try:
if a.sample:
snap = SAMPLE
elif a.snapshot:
with open(a.snapshot, encoding="utf-8") as fh:
snap = json.load(fh)
else:
p.print_usage(sys.stderr)
print("error: give --snapshot FILE or --sample", file=sys.stderr)
return 3
out = analyse(snap, load_waivers(a.waivers) if a.waivers else None)
except (OSError, ValueError, KeyError, TypeError) as e:
msg = f"{type(e).__name__}: {e}" if isinstance(e, (KeyError, TypeError)) else str(e)
if a.output == "json":
print(json.dumps({"verdict": "INVALID_INPUT", "errors": [msg]}, indent=2))
else:
print(f"error: {msg}", file=sys.stderr)
return 3
print(json.dumps(out, indent=2) if a.output == "json" else render(out))
return EXIT[out["verdict"]]
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |