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/css_checks.py

View on GitHub
#!/usr/bin/env python3
"""Declaration-level checks for the interface detector.

Reads CSS from stylesheets, <style> blocks, inline styles, JSX style objects and
css/styled templates; flags generic or low-quality declarations. The entry
point is ui_slop_detector.py; this CLI scans stylesheets alone.

Usage:
  python3 css_checks.py --input styles.css --format text

Exit codes: 0 no findings, 1 findings, 2 bad input.
"""

from __future__ import annotations

import argparse
import importlib.util
import re
import sys
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]


R = _load("ui_rules")
P = _load("css_parse")
Decl, NUM, TEMPLATE = P.Decl, P.NUM, P.TEMPLATE
strip_comments, split_top, kebab, parse_decls = P.strip_comments, P.split_top, P.kebab, P.parse_decls
extract_blocks, px, blank = P.extract_blocks, P.px, P.blank
OVERUSED = {"inter", "roboto", "poppins", "montserrat", "open sans", "lato", "space grotesk",
            "plus jakarta sans", "dm sans", "geist", "outfit", "manrope", "playfair display", "fraunces"}
SYSTEM = {"system-ui", "-apple-system", "blinkmacsystemfont", "segoe ui", "helvetica",
          "helvetica neue", "arial", "sans-serif", "ui-sans-serif"}
SERIF_HINTS = ("serif", "playfair", "fraunces", "recoleta", "newsreader", "cormorant", "garamond",
               "georgia", "lora", "merriweather", "baskerville", "instrument serif")
PAGE_SEL = re.compile(r"(^|[\s,])(html|body|:root|main)\b")
BODY_SEL = re.compile(r"(^|[\s,>+~])(p|body|li|article|blockquote|dd|td)\b|\.prose|\.body(?![\w-])|\.content(?![\w-])")
HEAD_SEL = re.compile(r"(^|[\s,>])h[12]\b|\.hero|\.display|\.headline")
STEP_SEL = re.compile(r"^\s*(from|to|\d+(\.\d+)?%)(\s*,\s*(from|to|\d+(\.\d+)?%))*\s*$")
BG_VAR = re.compile(r"^--(color-)?(bg|background|surface|canvas|paper|page|base)(-[\w-]+)?$")
LAYOUT_PROPS = re.compile(r"(?<![\w-])(width|height|max-height|min-height|top|left|right|bottom|margin[\w-]*|padding[\w-]*)(?![\w-])")
SPACING = re.compile(r"^(padding|margin|gap|row-gap|column-gap)(-[a-z-]+)?$")
EXTRA: list = []


def shadow_layers(value: str) -> List[Tuple[List[float], Optional[R.Color], bool]]:
    out = []
    for layer, _ in split_top(value, ","):
        colors = R.find_colors(layer)
        bare = re.sub(r"#[0-9a-fA-F]+|\w+\([^)]*\)", " ", layer)
        nums = [px(t) or 0.0 for t in re.findall(r"-?\d*\.?\d+(?:px|rem|em)?", bare)]
        out.append((nums, colors[0] if colors else None, "inset" in layer))
    return out


def check_block(selector: str, decls: List[Decl], path: str, cat: dict, ctx: dict) -> List[dict]:
    """Run every declaration rule over one block; update ctx stats in place."""
    f: List[dict] = []
    d: Dict[str, Tuple[str, int]] = {p: (v, ln) for p, v, ln in decls}

    def hit(rule: str, line: int, ev: str, sev: Optional[str] = None) -> None:
        f.append(R.make_finding(cat, rule, path, line, ev, sev))

    radius = px(d.get("border-radius", ("0", 0))[0]) or 0.0
    size = px(d.get("font-size", ("", 0))[0]) or 16.0
    for prop, value, line in decls:
        low = value.lower()
        ctx["spacing"].extend(t for t in low.split() if SPACING.match(prop) and t not in ("0", "auto", "0px"))
        if re.match(r"border-(left|right|inline-start|inline-end)(-width)?$", prop):
            width = px(low) or 0.0
            side_color = R.find_colors(low) or R.find_colors(d.get(prop.replace("-width", "") + "-color", ("", 0))[0])
            if width >= 2 and side_color and not R.is_neutral(side_color[0]):
                hit("side-stripe-border", line, f"{prop}: {value}", None if radius >= 4 else "advisory")
        if prop in ("background-clip", "-webkit-background-clip") and low == "text":
            hit("gradient-text", line, f"{prop}: {value}")
        if "gradient(" in low and prop.startswith("background"):
            hues = [R.hsl(c)[0] for c in R.find_colors(low) if R.chroma(c) >= 0.2]
            violet = [h for h in hues if 235 <= h <= 320]
            if violet and any(abs(h - violet[0]) >= 20 for h in hues):
                hit("ai-hue-gradient", line, f"{prop}: {value}")
            if low.startswith("repeating-") or "repeating-" in low:
                hit("repeating-stripes", line, f"{prop}: {value}")
            elif low.count("linear-gradient(") >= 2 and "1px" in low and "px" in d.get("background-size", ("", 0))[0]:
                hit("grid-line-background", line, f"{prop}: {value}")
        if prop in ("box-shadow", "text-shadow"):
            for nums, color, inset in shadow_layers(low):
                x, y, blur = (nums + [0.0, 0.0, 0.0])[:3]
                if color and x == 0 and y == 0 and blur > 0 and R.chroma(color) >= 0.25 and color[3] > 0.15:
                    hit("glow-shadow", line, f"{prop}: {value}")
                    break
                if prop == "box-shadow" and not inset and (abs(x) >= 3 or abs(y) >= 3) and blur == 0 \
                        and color and color[3] >= 0.5:
                    hit("hard-offset-shadow", line, f"{prop}: {value}")
                    break
        if prop == "font-family":
            face = low.split(",")[0].strip().strip("'\"")
            if face in OVERUSED:
                hit("overused-face", line, f"font-family: {value}")
            elif face in SYSTEM and (PAGE_SEL.search(selector) or HEAD_SEL.search(selector)):
                hit("default-font-stack", line, f"{selector} font-family: {value}")
        if prop == "font-style" and low == "italic" and HEAD_SEL.search(selector) \
                and any(s in d.get("font-family", ("", 0))[0].lower().replace("sans-serif", "") for s in SERIF_HINTS):
            hit("italic-serif-display", line, f"{selector} {{font-style: italic}}")
        if prop == "font-size" and not re.search(r"sr-only|visually-hidden", selector):
            n = px(low)
            floor = 12 if BODY_SEL.search(selector) else 11  # running text 12px, labels and controls 11px
            if n is not None and 0 < n < floor and not re.search(r"\b(calc|max)\(", low):
                hit("tiny-text", line, f"{selector} font-size: {value}".strip())
        if prop == "line-height" and BODY_SEL.search(selector):
            n = NUM.match(low)
            ratio = float(n.group(1)) / size if n and n.group(2) == "px" else float(n.group(1)) if n and not n.group(2) else None
            if ratio is not None and 0 < ratio < 1.3:
                hit("tight-body-leading", line, f"{selector} line-height: {value}")
        if prop == "letter-spacing":
            n = NUM.match(low)
            em = float(n.group(1)) / (size if n.group(2) == "px" else 1) if n and n.group(2) in ("em", "px") else None
            if em is not None and em < -0.04:
                hit("crushed-tracking", line, f"letter-spacing: {value}")
            elif em is not None and em >= 0.05 and BODY_SEL.search(selector) \
                    and "uppercase" not in d.get("text-transform", ("", 0))[0]:
                hit("wide-body-tracking", line, f"{selector} letter-spacing: {value}")
        if prop == "text-align" and low == "justify" and d.get("hyphens", ("", 0))[0] != "auto":
            hit("justified-text", line, f"{selector} text-align: justify")
        if prop in ("transition", "transition-property"):
            first = low.split(",")[0].split()
            if "all" in re.split(r"[\s,]+", low) or (prop == "transition" and first and re.match(r"^[\d.]+m?s$", first[0])):
                hit("transition-all", line, f"{prop}: {value}")
            elif LAYOUT_PROPS.search(low):
                hit("layout-property-motion", line, f"{prop}: {value}")
        if STEP_SEL.match(selector) and LAYOUT_PROPS.fullmatch(prop):
            hit("layout-property-motion", line, f"@keyframes {selector} {{{prop}}}")
        if prop in ("transition-timing-function", "animation-timing-function", "transition", "animation"):
            ys = R.bezier_ys(low)
            if any(y < -0.05 or y > 1.05 for y in ys) or re.search(r"\b(bounce|elastic|wobble|jello|rubber)", low):
                hit("bounce-easing", line, f"{prop}: {value}")
        if prop in ("animation", "animation-name") and low not in ("none", ""):
            ctx["animated"] = ctx["animated"] or (path, line)
            infinite = "infinite" in low or "infinite" in d.get("animation-iteration-count", ("", 0))[0]
            if infinite and re.search(r"marquee|ticker|scroll-x|scroll-left|loop-x|logo-scroll", low):
                hit("marquee-scroll", line, f"{prop}: {value}")
            elif infinite and re.search(r"pulse|ping|blink|breath|glow", low) \
                    and re.search(r"dot|status|live|indicator|online|beacon|ping", selector):
                hit("decorative-pulse", line, f"{selector} {{{prop}: {value}}}")
        if prop == "outline" and low in ("none", "0", "0px") and ":not(:focus-visible)" not in selector.replace(" ", "") \
                and (not ctx["focus_visible"] or (
                "focus-visible" in selector and "box-shadow" not in d and "border" not in d)):
            hit("focus-ring-removed", line, f"{selector} outline: {value}".strip())
        if prop in ("background", "background-color") or BG_VAR.match(prop):
            colors = R.find_colors(low) if "gradient(" not in low and "url(" not in low else []
            if len(colors) == 1 and R.is_cream(colors[0]) and (PAGE_SEL.search(selector) or BG_VAR.match(prop)):
                hit("cream-ground", line, f"{selector or ':root'} {prop}: {value}")
    fg = R.find_colors(d.get("color", ("", 0))[0])
    bg_val = d.get("background-color", d.get("background", ("", 0)))
    bg = R.find_colors(bg_val[0]) if "gradient(" not in bg_val[0] and "url(" not in bg_val[0] else []
    if fg and bg and fg[0][3] >= 0.99 and bg[0][3] >= 0.99:
        bold = (d.get("font-weight", ("400", 0))[0] in ("bold", "bolder", "700", "800", "900"))
        need = 3.0 if size >= 24 or (size >= 18.66 and bold) else 4.5
        ratio = R.contrast(fg[0], bg[0])
        line = d["color"][1]
        if ratio < need:
            hit("low-contrast-pair", line, f"{selector}: {d['color'][0]} on {bg_val[0]} = {ratio:.2f}:1 (needs {need})")
        elif R.is_neutral(fg[0]) and 0.3 < R.hsl(fg[0])[2] < 0.8 and R.chroma(bg[0]) >= 0.3:
            hit("gray-on-color", line, f"{selector}: {d['color'][0]} on {bg_val[0]}")
    for extra in EXTRA:  # further layers register here (extra_checks.check_block)
        f += extra(selector, decls, path, cat, ctx)
    return f


def new_context(text: str) -> dict:
    return {"spacing": [], "animated": None, "focus_visible": ":focus-visible" in text,
            "reduced_motion": "prefers-reduced-motion" in text or "motion-reduce" in text or "motion-safe" in text}


def scan_text(text: str, path: str, cat: dict, js: bool = False, line0: int = 1,
              ctx: Optional[dict] = None) -> Tuple[List[dict], dict]:
    """Scan CSS-bearing text; returns findings and the context stats it gathered."""
    ctx = ctx or new_context(text)
    findings: List[dict] = []
    for selector, decls in extract_blocks(text, line0, js):
        findings += check_block(selector, decls, path, cat, ctx)
    if "@keyframes" in text and not ctx["animated"]:
        ctx["animated"] = (path, line0 + text[:text.index("@keyframes")].count("\n"))
    return findings, ctx


def main(argv: Optional[List[str]] = None) -> int:
    p = argparse.ArgumentParser(description="Run the declaration-level interface rules over stylesheets.")
    p.add_argument("--input", nargs="+", required=True, help="CSS/SCSS files")
    p.add_argument("--format", choices=("text", "json"), default="text", help="Output format")
    args = p.parse_args(argv)
    try:
        cat = R.load_catalog()
        findings: List[dict] = []
        for path in args.input:
            with open(path, encoding="utf-8") as fh:
                text = fh.read()
            found, ctx = scan_text(text, path, cat)
            findings += found + R.file_level(ctx, path, cat)
    except (OSError, UnicodeDecodeError, ValueError) as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2
    return R.print_findings(findings, args.format)


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: 319kUpdated 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