CSS Architecture skill for Claude Code

#!/usr/bin/env python3
"""Report CSS specificity hot spots and !important usage (stdlib only).

Usage:
  python3 css_specificity_report.py FILE.css [FILE2.css ...] [--top 20]
         [--max-specificity A,B,C] [--max-important N] [--max-depth N]

Prints totals (selectors, ID selectors, !important, deep descendant chains) and the
highest-specificity selectors with file:line. Exits 1 when a threshold is exceeded,
2 on bad input. Nested rules are scored as written (approximate). Run on compiled CSS
for Sass/Less sources.
"""
import argparse
import re
import sys

SKIP_BLOCK_AT = ("@keyframes", "@-webkit-keyframes", "@font-face", "@page", "@property",
                 "@counter-style", "@font-feature-values", "@view-transition", "@position-try")
LEGACY_PSEUDO_ELEMENTS = {"before", "after", "first-line", "first-letter"}


def strip_comments(css: str) -> str:
    # replace comments with same number of newlines to keep line numbers
    return re.sub(r"/\*.*?\*/", lambda m: "\n" * m.group(0).count("\n"), css, flags=re.S)


def split_top(s: str, sep: str = ","):
    parts, depth, cur, quote = [], 0, [], None
    for ch in s:
        if quote:
            cur.append(ch)
            if ch == quote:
                quote = None
            continue
        if ch in "\"'":
            quote = ch
        elif ch in "([":
            depth += 1
        elif ch in ")]":
            depth -= 1
        if ch == sep and depth == 0:
            parts.append("".join(cur)); cur = []
        else:
            cur.append(ch)
    parts.append("".join(cur))
    return [p.strip() for p in parts if p.strip()]


def read_paren(s: str, i: int):
    """s[i] == '('; return (inner, index after closing paren)."""
    depth, j = 0, i
    while j < len(s):
        if s[j] == "(":
            depth += 1
        elif s[j] == ")":
            depth -= 1
            if depth == 0:
                return s[i + 1:j], j + 1
        j += 1
    return s[i + 1:], len(s)


def add(a, b):
    return (a[0] + b[0], a[1] + b[1], a[2] + b[2])


def specificity(sel: str):
    sel = re.sub(r"\"[^\"]*\"|'[^']*'", "\"\"", sel)
    spec = (0, 0, 0)
    i, n = 0, len(sel)
    while i < n:
        ch = sel[i]
        if ch == "#":
            m = re.match(r"#[\w-]+", sel[i:])
            spec = add(spec, (1, 0, 0)); i += len(m.group(0)) if m else 1
        elif ch == ".":
            m = re.match(r"\.[\w-]+", sel[i:])
            spec = add(spec, (0, 1, 0)); i += len(m.group(0)) if m else 1
        elif ch == "[":
            j = sel.find("]", i)
            spec = add(spec, (0, 1, 0)); i = j + 1 if j != -1 else n
        elif ch == ":":
            if sel.startswith("::", i):
                m = re.match(r"::[\w-]+", sel[i:])
                spec = add(spec, (0, 0, 1)); i += len(m.group(0)) if m else 2
                if i < n and sel[i] == "(":
                    _, i = read_paren(sel, i)
                continue
            m = re.match(r":([\w-]+)", sel[i:])
            if not m:
                i += 1; continue
            name = m.group(1).lower(); i += len(m.group(0))
            arg = None
            if i < n and sel[i] == "(":
                arg, i = read_paren(sel, i)
            if name == "where":
                continue
            if name in ("is", "not", "has", "matches", "-webkit-any", "-moz-any") and arg is not None:
                best = max((specificity(a) for a in split_top(arg)), default=(0, 0, 0))
                spec = add(spec, best)
            elif name in ("nth-child", "nth-last-child") and arg is not None and " of " in arg:
                best = max((specificity(a) for a in split_top(arg.split(" of ", 1)[1])), default=(0, 0, 0))
                spec = add(add(spec, (0, 1, 0)), best)
            elif name in LEGACY_PSEUDO_ELEMENTS:
                spec = add(spec, (0, 0, 1))
            else:
                spec = add(spec, (0, 1, 0))
        elif ch.isalpha() or ch == "-" or ch == "_":
            m = re.match(r"[\w-]+", sel[i:])
            spec = add(spec, (0, 0, 1)); i += len(m.group(0))
        else:
            i += 1  # combinators, *, &, whitespace
    return spec


def compound_depth(sel: str) -> int:
    flat = re.sub(r"\([^()]*\)", "", sel)
    flat = re.sub(r"\s*([>+~])\s*", r" \1 ", flat)
    return len([t for t in flat.split() if t not in (">", "+", "~")])


def parse(path: str):
    with open(path, encoding="utf-8", errors="replace") as fh:
        css = strip_comments(fh.read())
    selectors, important, stack = [], 0, []
    buf_start, line = 0, 1
    i = 0
    while i < len(css):
        ch = css[i]
        if ch in "\"'":
            j = css.find(ch, i + 1)
            i = j + 1 if j != -1 else len(css)
            continue
        if ch == "{":
            prelude = css[buf_start:i].strip()
            skipping = any(s == "skip" for s in stack)
            if prelude.startswith("@"):
                stack.append("skip" if prelude.lower().startswith(SKIP_BLOCK_AT) else "at")
            else:
                stack.append("rule")
                if not skipping and prelude:
                    for s in split_top(prelude):
                        selectors.append((s, specificity(s), compound_depth(s), path, line))
            buf_start = i + 1
        elif ch == "}":
            if re.search(r"!\s*important", css[buf_start:i], re.I):
                important += 1  # last declaration without a trailing semicolon
            if stack:
                stack.pop()
            buf_start = i + 1
        elif ch == ";":
            decl = css[buf_start:i]
            if re.search(r"!\s*important", decl, re.I):
                important += 1
            buf_start = i + 1
        elif ch == "\n":
            line += 1
        i += 1
    return selectors, important


def main() -> int:
    ap = argparse.ArgumentParser(description="CSS specificity report")
    ap.add_argument("files", nargs="+")
    ap.add_argument("--top", type=int, default=20)
    ap.add_argument("--max-specificity", help="fail if any selector exceeds A,B,C (e.g. 0,3,0)")
    ap.add_argument("--max-important", type=int, help="fail if !important count exceeds N")
    ap.add_argument("--max-depth", type=int, default=3, help="flag descendant chains deeper than N (default 3)")
    args = ap.parse_args()

    all_sel, total_imp = [], 0
    for f in args.files:
        try:
            sels, imp = parse(f)
        except OSError as e:
            print(f"error: {e}", file=sys.stderr)
            return 2
        all_sel += sels
        total_imp += imp

    ids = [s for s in all_sel if s[1][0] > 0]
    deep = [s for s in all_sel if s[2] > args.max_depth]
    print(f"files: {len(args.files)}  selectors: {len(all_sel)}  with IDs: {len(ids)}  "
          f"!important: {total_imp}  deeper than {args.max_depth}: {len(deep)}")
    if all_sel:
        hist = {}
        for s in all_sel:
            key = "id" if s[1][0] else f"0,{min(s[1][1], 4)}{'+' if s[1][1] > 4 else ''}"
            hist[key] = hist.get(key, 0) + 1
        print("by class-level specificity: " + ", ".join(f"{k}: {v}" for k, v in sorted(hist.items())))

    print(f"\nTop {args.top} by specificity:")
    for sel, spec, depth, path, line in sorted(all_sel, key=lambda s: s[1], reverse=True)[:args.top]:
        print(f"  ({spec[0]},{spec[1]},{spec[2]})  depth {depth}  {path}:{line}  {sel[:110]}")

    failed = False
    if args.max_specificity:
        try:
            limit = tuple(int(x) for x in args.max_specificity.split(","))
            assert len(limit) == 3
        except (ValueError, AssertionError):
            print("error: --max-specificity must look like 0,3,0", file=sys.stderr)
            return 2
        over = [s for s in all_sel if s[1] > limit]
        if over:
            failed = True
            print(f"\nFAIL: {len(over)} selector(s) exceed specificity {args.max_specificity}")
    if args.max_important is not None and total_imp > args.max_important:
        failed = True
        print(f"FAIL: !important count {total_imp} exceeds {args.max_important}")
    if not failed:
        print("\nOK: within thresholds" if (args.max_specificity or args.max_important is not None) else "")
    return 1 if failed else 0


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