Skip to content

borghei/Claude-Skills / engineering/interface-refinement

interface-refinement

Verified

Refine an existing interface with named commands (critique, polish, distill, typeset, colorize ...), a product and design context file, and a static detector of generic UI patterns. Use when UI looks generic, cluttered or unfinished.

FileKindSize
SKILL.mdskill md22.1 KB
assets/interface-context-template.mdmarkdown2.6 KB
assets/refinement-report-template.mdmarkdown1.5 KB
assets/sample_context.mdmarkdown3.8 KB
assets/sample_context_flawed.mdmarkdown730 B
assets/sample_detector_report.jsonconfig387 B
assets/sample_detector_report_flawed.jsonconfig48.8 KB
assets/sample_refinement_plan.jsonconfig1.7 KB
assets/sample_refinement_plan_flawed.jsonconfig893 B
assets/sample_ui_flawed.cssother2.5 KB
assets/sample_ui_flawed.htmlother4.5 KB
assets/sample_ui_flawed.tsxother1.1 KB
assets/sample_ui_sound.cssother2.3 KB
assets/sample_ui_sound.htmlother2.6 KB
assets/sample_ui_sound.tsxother1.3 KB
references/command-adapt.mdmarkdown2.7 KB
references/command-animate.mdmarkdown2.6 KB
references/command-audit.mdmarkdown3.5 KB
references/command-bolder.mdmarkdown3.2 KB
references/command-clarify.mdmarkdown2.8 KB
references/command-colorize.mdmarkdown2.7 KB
references/command-critique.mdmarkdown3.5 KB
references/command-delight.mdmarkdown1.8 KB
references/command-distill.mdmarkdown2.3 KB
references/command-document.mdmarkdown3.3 KB
references/command-extract.mdmarkdown3.4 KB
references/command-harden.mdmarkdown2.5 KB
references/command-init.mdmarkdown2.9 KB
references/command-layout.mdmarkdown2.3 KB
references/command-onboard.mdmarkdown2.2 KB
references/command-optimize.mdmarkdown3.4 KB
references/command-polish.mdmarkdown2.8 KB
references/command-quieter.mdmarkdown2.3 KB
references/command-typeset.mdmarkdown2.9 KB
references/craft-floor.mdmarkdown3.7 KB
references/detector-rules.jsonconfig22.6 KB
references/detector-rules.mdmarkdown14.5 KB
references/native-platforms.mdmarkdown4.6 KB
references/review-protocol.mdmarkdown5.2 KB
references/surface-modes.mdmarkdown3.4 KB
scripts/class_checks.pyscript12.3 KB
scripts/command_router.pyscript12.7 KB
scripts/context_linter.pyscript13.4 KB
scripts/css_checks.pyscript12.3 KB
scripts/css_parse.pyscript7.6 KB
scripts/extra_checks.pyscript12.7 KB
scripts/markup_checks.pyscript14.6 KB
scripts/system_checks.pyscript9.4 KB
scripts/ui_rules.pyscript12.5 KB
scripts/ui_slop_detector.pyscript12.1 KB

scripts/ui_slop_detector.py

View on GitHub
#!/usr/bin/env python3
"""Static detector for generic and low-quality interface patterns.

Scans HTML, JSX/TSX, Vue, Svelte, Astro and CSS/SCSS/LESS files and reports
each hit with file:line, rule id, severity, evidence, the fix, and the
refinement command that owns it. Runs the declaration rules (css_checks.py),
the utility-class rules (class_checks.py) and the structural rules
(markup_checks.py), then the project-level rules (animation with no
reduced-motion path anywhere in the scan).

Inline waivers need a reason and cover the marker's own line and the next:
  /* ui-refine-ignore side-stripe-border -- severity rule on a square callout */
  <!-- ui-refine-ignore-file * -- deliberate before/after demo -->

Usage:
  python3 ui_slop_detector.py src/ --format text
  python3 ui_slop_detector.py page.html styles.css --fail-on high --format json
  python3 ui_slop_detector.py src/ --scope color,type --skip default-font-stack
  python3 ui_slop_detector.py src/ --context interface-context.md --fail-on advisory

Exit codes: 0 nothing at or above --fail-on, 1 findings at or above it,
2 bad input (missing path, nothing scannable, unreadable file, bad catalog).
"""

from __future__ import annotations

import argparse
import importlib.util
import json
import re
import sys
from collections import Counter
from pathlib import Path
from typing import Dict, List, Optional, Tuple


def _load(name: str):
    """Load a sibling module from this scripts/ folder (keeps the package self-contained)."""
    if name not in sys.modules:
        spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(f"{name}.py"))
        sys.modules[name] = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(sys.modules[name])
    return sys.modules[name]


C = _load("css_checks")
M = _load("markup_checks")
R = _load("ui_rules")
X = _load("extra_checks")
S = _load("system_checks")
if X.check_block not in C.EXTRA:
    C.EXTRA.append(X.check_block)


MARKUP_EXT = {".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte", ".astro"}
STYLE_EXT = {".css", ".scss", ".less"}
SKIP_DIRS = {"node_modules", ".git", "dist", "build", "vendor", ".next", ".nuxt", "coverage", "out"}
PAGE_RULE = re.compile(r"(?<![\w.#-])(?:html|body|:root)(?![\w-])[^{}<>]{0,200}\{([^{}]*)\}")
PAGE_TAG = re.compile(r"<(?:html|body)\b[^>]*?\bclass(?:Name)?=[\"']([^\"']*)[\"']", re.I)
IGNORE_RE = re.compile(r"ui-refine-ignore(-file)?\s+([\w*,-]+)(?:\s*(?:--|:)\s*(\S.*?))?\s*(?:\*/|-->|\}|$)")


class InputError(Exception):
    """Raised for anything the caller must fix before a scan can run."""


def collect(paths: List[str], max_files: int) -> List[Path]:
    files: List[Path] = []
    for raw in paths:
        p = Path(raw)
        if not p.exists():
            raise InputError(f"path not found: {raw}")
        candidates = [p] if p.is_file() else sorted(x for x in p.rglob("*") if x.is_file())
        for f in candidates:
            if any(part in SKIP_DIRS for part in f.parts) or f.name.endswith(".min.css"):
                continue
            if f.suffix.lower() in MARKUP_EXT | STYLE_EXT:
                files.append(f)
    if not files:
        raise InputError("no scannable files (html, jsx, tsx, vue, svelte, astro, css, scss, less)")
    if len(files) > max_files:
        raise InputError(f"{len(files)} files exceeds --max-files {max_files}; narrow the target")
    return files


def waivers(text: str, path: str) -> Tuple[Dict[int, set], set, List[dict]]:
    """Inline waivers: line -> rule ids, file-wide ids, and markers rejected for having no reason."""
    by_line: Dict[int, set] = {}
    whole: set = set()
    rejected: List[dict] = []
    for number, line in enumerate(text.splitlines(), 1):
        for m in IGNORE_RE.finditer(line):
            ids = {x for x in m.group(2).split(",") if x}
            if not (m.group(3) or "").strip():
                rejected.append({"file": path, "line": number, "marker": m.group(0).strip()[:80],
                                 "reason": "waiver has no reason after '--'"})
                continue
            if m.group(1):
                whole |= ids
            else:
                by_line.setdefault(number, set()).update(ids)
                by_line.setdefault(number + 1, set()).update(ids)
    return by_line, whole, rejected


def page_ground(texts: List[str]) -> Optional[str]:
    """The page ground set in the scan (body/html rule, @apply, or <html>/<body> classes), so a component
    scanned with its global stylesheet or layout is judged on the right ground. None when grounds disagree."""
    found = set()
    for text in texts:
        for m in PAGE_RULE.finditer(text):
            applied = re.search(r"@apply\s+([^;}]+)", m.group(1))
            value = re.search(r"background(?:-color)?\s*:\s*([^;}]+)", m.group(1))
            colors = R.find_colors(value.group(1)) if value and "gradient(" not in value.group(1) else []
            found.add(M.K.ground(applied.group(1).split()) if applied else
                      ("dark" if R.luminance(colors[0]) < 0.2 else "light") if colors else None)
        for m in PAGE_TAG.finditer(text):
            dark = re.search(r"(?<![\w:-])dark(?![\w-])", m.group(1))
            found.add("dark" if dark else M.K.ground(m.group(1).split()))
    found.discard(None)
    return found.pop() if len(found) == 1 else None


def waived(f: dict, by_line: Dict[int, set], whole: set) -> bool:
    ids = by_line.get(f["line"], set()) | whole
    return "*" in ids or f["rule"] in ids


def scan(files: List[Path], cat: dict, system: Optional[dict] = None) -> dict:
    texts: Dict[Path, str] = {}
    unreadable: List[str] = []
    for f in files:
        try:
            texts[f] = f.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError) as exc:
            unreadable.append(f"{f}: {exc.__class__.__name__}")
    if not texts:
        raise InputError("no file could be read as UTF-8: " + "; ".join(unreadable))
    joined = "\n".join(texts.values())
    focus_visible = ":focus-visible" in joined or "focus-visible:" in joined
    ground = page_ground(list(texts.values()))
    findings: List[dict] = []
    ignored, rejected = 0, []
    animated, reduced, anywhere = None, False, set()
    shared: Dict[str, tuple] = {}
    for f, text in texts.items():
        path = str(f)
        ctx = C.new_context(text)
        ctx["focus_visible"] = focus_visible
        ctx["shared"] = shared
        ctx["page_ground"] = ground
        if f.suffix.lower() in STYLE_EXT:
            found, ctx = C.scan_text(text, path, cat, ctx=ctx)
        else:
            found = M.scan_markup(text, path, cat, ctx) + X.scan_markup(text, path, cat)
        if system:
            found += S.drift_file(text, path, system, cat)
        found += R.file_level(ctx, path, cat)
        animated = animated or ctx["animated"]
        reduced = reduced or ctx["reduced_motion"]
        by_line, whole, bad = waivers(text, path)
        rejected += bad
        anywhere |= whole
        for x in found:
            if waived(x, by_line, whole):
                ignored += 1
            else:
                findings.append(x)
    if animated and not reduced:
        if "missing-reduced-motion" in anywhere:
            ignored += 1
        else:
            findings.append(R.make_finding(cat, "missing-reduced-motion", animated[0], animated[1],
                                           "animation found; no prefers-reduced-motion or motion-reduce anywhere in scan"))
    for x in X.project_level(shared, cat):
        if "flat-type-hierarchy" in anywhere:
            ignored += 1
        else:
            findings.append(x)
    if system:
        findings = S.honour(findings, system)
        S.escalate(findings, system["refusals"])
    findings.sort(key=lambda x: (x["file"], x["line"], -R.SEVERITY_RANK[x["severity"]]))
    return {"files_scanned": len(texts), "findings": findings, "ignored": ignored, "rejected_waivers": rejected,
            "unreadable": unreadable}


def summarise(report: dict, fail_on: str) -> dict:
    sev = Counter(f["severity"] for f in report["findings"])
    cmd = Counter(f["command"] for f in report["findings"])
    floor = R.SEVERITY_RANK[fail_on]
    blocking = sum(1 for f in report["findings"] if R.SEVERITY_RANK[f["severity"]] >= floor)
    return {"files_scanned": report["files_scanned"], "findings": len(report["findings"]),
            "by_severity": {k: sev.get(k, 0) for k in ("high", "medium", "advisory")},
            "by_command": dict(cmd.most_common()), "fail_on": fail_on, "blocking": blocking,
            "ignored": report["ignored"], "rejected_waivers": len(report["rejected_waivers"]),
            "verdict": "FAIL" if blocking else "PASS"}


def render_text(report: dict, summary: dict) -> str:
    out: List[str] = []
    current = None
    for f in report["findings"]:
        if f["file"] != current:
            current = f["file"]
            out.append(f"\n{current}")
        out.append(f"  {f['line']:>5}  {f['severity']:<8} {f['rule']:<24} {f['evidence']}")
        out.append(f"         fix: {f['fix']}  [run: {f['command']}]")
    for u in report["unreadable"]:
        out.append(f"\n  skipped unreadable file {u}")
    for r in report["rejected_waivers"]:
        out.append(f"\n  waiver rejected {r['file']}:{r['line']}  {r['reason']}")
    s = summary
    out.append(f"\n{s['verdict']}  {s['findings']} finding(s) in {s['files_scanned']} file(s): "
               f"{s['by_severity']['high']} high, {s['by_severity']['medium']} medium, "
               f"{s['by_severity']['advisory']} advisory; {s['blocking']} at or above '{s['fail_on']}'; "
               f"{s['ignored']} waived")
    if s["by_command"]:
        out.append("Commands by finding count: " + ", ".join(f"{k} {v}" for k, v in s["by_command"].items()))
    return "\n".join(out).lstrip("\n")


def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(description="Detect generic and low-quality interface patterns in markup and styles.")
    p.add_argument("paths", nargs="+", help="Files or directories to scan")
    p.add_argument("--format", choices=("text", "json"), default="text", help="Output format")
    p.add_argument("--fail-on", choices=("high", "medium", "advisory"), default="medium",
                   help="Lowest severity that makes the run exit 1 (default medium)")
    p.add_argument("--rules", help="Comma-separated rule ids to keep (default all)")
    p.add_argument("--skip", help="Comma-separated rule ids to drop")
    p.add_argument("--scope", help="Comma-separated scopes to keep: color,type,layout,motion,surface,structure,copy,interaction")
    p.add_argument("--context", help="interface-context.md: report values outside its visual system "
                   "(off-system-* rules) and fail on any rule it lists under Refusals")
    p.add_argument("--max-files", type=int, default=2000, help="Refuse scans larger than this (default 2000)")
    return p


def main(argv: Optional[List[str]] = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        cat = R.load_catalog()
        for flag in (args.rules, args.skip):
            unknown = [x for x in (flag or "").split(",") if x and x not in cat]
            if unknown:
                raise InputError(f"unknown rule id(s): {', '.join(unknown)}")
        scopes = {x for x in (args.scope or "").split(",") if x}
        if scopes - {r["scope"] for r in cat.values()}:
            raise InputError(f"unknown scope(s): {', '.join(sorted(scopes - {r['scope'] for r in cat.values()}))}")
        system = S.load_context(args.context) if args.context else None
        report = scan(collect(args.paths, args.max_files), cat, system)
    except (InputError, ValueError) as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2
    keep = set((args.rules or "").split(",")) - {""}
    drop = set((args.skip or "").split(",")) - {""}
    report["findings"] = [f for f in report["findings"] if (not keep or f["rule"] in keep)
                          and f["rule"] not in drop and (not scopes or f["scope"] in scopes)]
    summary = summarise(report, args.fail_on)
    if args.format == "json":
        print(json.dumps({"summary": summary, **report}, indent=2))
    else:
        print(render_text(report, summary))
    return 1 if summary["blocking"] else 0


if __name__ == "__main__":
    sys.exit(main())
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall