notque/vexjoy-agent / skills/frontend/frontend
frontend
UnverifiedFrontend: UI design, distinctive visual styles, HTML artifacts, Three.js 3D, TypeScript/React/Next.js apps, e-commerce, portfolios, React Native, web performance.
scripts-distinctive-frontend-design/css_slop_rules.py
View on GitHub#!/usr/bin/env python3
"""Canonical rendered-CSS slop rules. Self-contained, dependency-free.
Public surface:
scan_css(css_text: str) -> list[Finding]
Finding(rule_id, severity, message, line)
Deterministic regex/parse only — no LLM. Designed to be vendored as-is into
other skills (e.g. html-artifact). Findings are "warning" severity except
contrast-canary below 1.2:1, which is "error"; callers fail the build on errors.
Rules:
transition-all `transition: all` (shorthand spanning all properties)
universal-hover-scale :hover whose only effect is a broad transform: scale()
gradient-text-headline background-clip:text / -webkit-background-clip:text on h1/h2
focus-ring-fade focus outline/ring animated via transition (fades in)
emoji-feature-icon emoji codepoint as a feature/list icon (CSS content or markup)
two-line-cta clickable/button text that wraps to two lines (heuristic)
contrast-canary same-rule fg/bg: WCAG ratio < 1.2:1 is an ERROR (text is effectively
invisible); otherwise delta-L <= 0.05 AND delta-chroma <= 0.05 is a warning
"""
from __future__ import annotations
import math
import re
from dataclasses import dataclass
@dataclass(frozen=True)
class Finding:
"""One slop-rule hit.
rule_id: stable identifier (see module docstring table).
severity: "warning", or "error" for contrast-canary below _CONTRAST_BLOCK_RATIO.
message: human-readable explanation and fix direction.
line: 1-based best-effort source line.
"""
rule_id: str
severity: str
message: str
line: int
# Contrast-canary thresholds (oklch space): treat as too-low-contrast when BOTH hold.
_CONTRAST_DELTA_L = 0.05 # lightness L is 0..1; <=5% apart
_CONTRAST_DELTA_C = 0.05 # chroma
# WCAG contrast ratio below which the pair is effectively invisible: blocking error.
_CONTRAST_BLOCK_RATIO = 1.2
_EMOJI_RE = re.compile(
"["
"\U0001f300-\U0001faff" # symbols, pictographs, emoji
"\U00002600-\U000027bf" # misc symbols + dingbats
"\U0001f000-\U0001f0ff" # mahjong/dominoes/cards
"\U00002190-\U000021ff" # arrows (often used as icons)
"\U00002b00-\U00002bff" # misc symbols and arrows (stars, checks)
"\U0000fe0f" # variation selector-16
"]"
)
def _line_of(text: str, index: int) -> int:
"""Return the 1-based line number for a character offset."""
return text.count("\n", 0, index) + 1
# --- color parsing (hex + oklch) → (L, chroma) in oklch space ---
def _parse_hex(token: str) -> tuple[float, float, float] | None:
"""Parse #rgb / #rrggbb (alpha ignored) → sRGB 0..1 triple."""
h = token.lstrip("#")
if len(h) in (3, 4):
h = "".join(c * 2 for c in h[:3])
elif len(h) in (6, 8):
h = h[:6]
else:
return None
try:
r = int(h[0:2], 16) / 255.0
g = int(h[2:4], 16) / 255.0
b = int(h[4:6], 16) / 255.0
except ValueError:
return None
return (r, g, b)
def _srgb_to_linear(c: float) -> float:
return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
def _srgb_to_oklch_lc(rgb: tuple[float, float, float]) -> tuple[float, float]:
"""sRGB triple → (L, chroma) in OKLCH. Hue is dropped (not needed here)."""
r, g, b = (_srgb_to_linear(c) for c in rgb)
lm = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
mm = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
sm = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
l_ = lm ** (1 / 3)
m_ = mm ** (1 / 3)
s_ = sm ** (1 / 3)
big_l = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_
a = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_
b2 = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_
chroma = math.hypot(a, b2)
return (big_l, chroma)
_OKLCH_RE = re.compile(r"oklch\(\s*([0-9.]+%?)\s+([0-9.]+)\s+", re.IGNORECASE)
_OKLCH_FULL_RE = re.compile(r"oklch\(\s*([0-9.]+%?)\s+([0-9.]+)\s+([0-9.]+)", re.IGNORECASE)
def _parse_oklch(token: str) -> tuple[float, float] | None:
"""Parse oklch(L C H ...) → (L, chroma). L may be a percentage."""
m = _OKLCH_RE.search(token)
if not m:
return None
raw_l, raw_c = m.group(1), m.group(2)
try:
big_l = float(raw_l[:-1]) / 100.0 if raw_l.endswith("%") else float(raw_l)
chroma = float(raw_c)
except ValueError:
return None
return (big_l, chroma)
def _oklch_to_luminance(token: str) -> float | None:
"""Parse oklch(L C H ...) → WCAG relative luminance (sRGB gamut clamped)."""
m = _OKLCH_FULL_RE.search(token)
if not m:
return None
raw_l = m.group(1)
try:
big_l = float(raw_l[:-1]) / 100.0 if raw_l.endswith("%") else float(raw_l)
chroma = float(m.group(2))
hue = math.radians(float(m.group(3)))
except ValueError:
return None
a, b = chroma * math.cos(hue), chroma * math.sin(hue)
l_ = (big_l + 0.3963377774 * a + 0.2158037573 * b) ** 3
m_ = (big_l - 0.1055613458 * a - 0.0638541728 * b) ** 3
s_ = (big_l - 0.0894841775 * a - 1.2914855480 * b) ** 3
r = 4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_
g = -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_
bl = -0.0041960863 * l_ - 0.7034186147 * m_ + 1.7076147010 * s_
r, g, bl = (min(1.0, max(0.0, c)) for c in (r, g, bl))
return 0.2126 * r + 0.7152 * g + 0.0722 * bl
def _color_to_luminance(value: str) -> float | None:
"""Resolve a single CSS color value to WCAG relative luminance (0..1)."""
value = value.strip()
if value.lower().startswith("oklch("):
return _oklch_to_luminance(value)
hexmatch = re.search(r"#[0-9a-fA-F]{3,8}\b", value)
if hexmatch:
rgb = _parse_hex(hexmatch.group(0))
if rgb is not None:
r, g, b = (_srgb_to_linear(c) for c in rgb)
return 0.2126 * r + 0.7152 * g + 0.0722 * b
return None
def contrast_ratio(fg: str, bg: str) -> float | None:
"""WCAG contrast ratio of two CSS color values (hex or oklch), or None if unparsed."""
lf, lb = _color_to_luminance(fg), _color_to_luminance(bg)
if lf is None or lb is None:
return None
return (max(lf, lb) + 0.05) / (min(lf, lb) + 0.05)
def _color_to_lc(value: str) -> tuple[float, float] | None:
"""Resolve a single CSS color value to (L, chroma) in oklch space."""
value = value.strip()
if value.lower().startswith("oklch("):
return _parse_oklch(value)
hexmatch = re.search(r"#[0-9a-fA-F]{3,8}\b", value)
if hexmatch:
rgb = _parse_hex(hexmatch.group(0))
if rgb is not None:
return _srgb_to_oklch_lc(rgb)
return None
# --- rule scanners ---
# Anchored on the literal "{" so finditer scans directly to each brace instead
# of trying "[^{}]*" from every offset. The old shape r"([^{}]*)\{([^{}]*)\}"
# was O(n^2) on large brace-free input (e.g. a ~500KB minified single line): the
# pre-brace run succeeded to end-of-string, the "\{" failed, and the engine
# retried from the next start position. This form is linear. The selector (the
# pre-brace text) is recovered by slicing from the previous block's close brace.
_BLOCK_RE = re.compile(r"\{([^{}]*)\}", re.DOTALL)
def _iter_blocks(css: str):
"""Yield (selector, body, body_offset) for each top-level rule block.
Behavior matches the prior "([^{}]*)\\{([^{}]*)\\}" form: the selector is the
run of non-brace text immediately preceding the block.
"""
last_close = 0
for m in _BLOCK_RE.finditer(css):
gap = css[last_close : m.start()]
cut = max(gap.rfind("{"), gap.rfind("}"))
selector = (gap[cut + 1 :] if cut != -1 else gap).strip()
yield selector, m.group(1), m.start(1)
last_close = m.end()
def _decls(body: str) -> list[tuple[str, str]]:
"""Split a declaration block into (property, value) pairs (lowercased prop)."""
out: list[tuple[str, str]] = []
for chunk in body.split(";"):
if ":" in chunk:
prop, _, val = chunk.partition(":")
out.append((prop.strip().lower(), val.strip()))
return out
def _scan_transition_all(css: str) -> list[Finding]:
findings: list[Finding] = []
for m in re.finditer(r"transition(?:-property)?\s*:\s*([^;}]*)", css, re.IGNORECASE):
if re.match(r"all\b", m.group(1).strip(), re.IGNORECASE):
findings.append(
Finding(
"transition-all",
"warning",
"transition: all animates every property; name the properties you "
"actually change (e.g. transition: opacity, transform).",
_line_of(css, m.start()),
)
)
return findings
def _scan_universal_hover_scale(css: str) -> list[Finding]:
findings: list[Finding] = []
for selector, body, offset in _iter_blocks(css):
if ":hover" not in selector.lower():
continue
decls = _decls(body)
effective = [(p, v) for p, v in decls if p and v]
if len(effective) != 1:
continue
prop, val = effective[0]
if prop == "transform" and re.match(r"scale\(\s*1(\.0\d*)?\s*\)", val, re.IGNORECASE):
findings.append(
Finding(
"universal-hover-scale",
"warning",
"the only hover effect is a small transform: scale(); a uniform "
"scale-on-hover reads as templated. Give hover a purposeful change.",
_line_of(css, offset),
)
)
return findings
def _scan_gradient_text_headline(css: str) -> list[Finding]:
findings: list[Finding] = []
for selector, body, offset in _iter_blocks(css):
sel = selector.lower()
if not re.search(r"\bh[12]\b", sel):
continue
if re.search(r"(?:-webkit-)?background-clip\s*:\s*text", body, re.IGNORECASE):
findings.append(
Finding(
"gradient-text-headline",
"warning",
"gradient-clipped headline text (background-clip: text on h1/h2) is a "
"signature template look; use a solid headline color.",
_line_of(css, offset),
)
)
return findings
def _scan_focus_ring_fade(css: str) -> list[Finding]:
findings: list[Finding] = []
for selector, body, offset in _iter_blocks(css):
if ":focus" not in selector.lower():
continue
decls = _decls(body)
has_ring = any(p in ("outline", "box-shadow", "border", "outline-color") for p, _ in decls)
trans = next((v for p, v in decls if p in ("transition", "transition-property")), "")
if has_ring and re.search(r"\b(all|outline|box-shadow|border)\b", trans, re.IGNORECASE):
findings.append(
Finding(
"focus-ring-fade",
"warning",
"focus ring is animated via transition; focus indicators must appear "
"instantly for accessibility. Remove the transition on the ring.",
_line_of(css, offset),
)
)
return findings
def _scan_emoji_feature_icon(css: str) -> list[Finding]:
findings: list[Finding] = []
# CSS: content property carrying an emoji (pseudo-element icon).
for m in re.finditer(r"content\s*:\s*([\"'])(.*?)\1", css, re.IGNORECASE | re.DOTALL):
if _EMOJI_RE.search(m.group(2)):
findings.append(
Finding(
"emoji-feature-icon",
"warning",
"emoji used as a feature/list icon (CSS content); use an inline SVG "
"icon set for a deliberate look.",
_line_of(css, m.start()),
)
)
# Markup hook: emoji directly inside a list item / feature element.
for m in re.finditer(r"<li\b[^>]*>(.*?)</li>", css, re.IGNORECASE | re.DOTALL):
if _EMOJI_RE.search(m.group(1)):
findings.append(
Finding(
"emoji-feature-icon",
"warning",
"emoji used as a feature/list icon in markup; use an inline SVG icon set.",
_line_of(css, m.start()),
)
)
return findings
def _scan_two_line_cta(css: str) -> list[Finding]:
findings: list[Finding] = []
# Heuristic: a button/CTA-classed clickable whose text contains a forced break.
pattern = re.compile(
r"<(?:button|a)\b[^>]*(?:class\s*=\s*\"[^\"]*(?:btn|button|cta)[^\"]*\"|role\s*=\s*\"button\")[^>]*>(.*?)</(?:button|a)>",
re.IGNORECASE | re.DOTALL,
)
for m in pattern.finditer(css):
inner = m.group(1)
if re.search(r"<br\s*/?>", inner, re.IGNORECASE) or "\n" in inner.strip():
findings.append(
Finding(
"two-line-cta",
"warning",
"call-to-action text wraps to two lines; keep CTA labels to one short "
"line so the action stays scannable.",
_line_of(css, m.start()),
)
)
return findings
def _scan_contrast_canary(css: str) -> list[Finding]:
findings: list[Finding] = []
for _selector, body, offset in _iter_blocks(css):
fg_val = bg_val = None
for prop, val in _decls(body):
if prop == "color":
fg_val = val if _color_to_lc(val) is not None else None
elif prop in ("background-color", "background") and _color_to_lc(val) is not None:
bg_val = val
if fg_val is None or bg_val is None:
continue
fg, bg = _color_to_lc(fg_val), _color_to_lc(bg_val)
ratio = contrast_ratio(fg_val, bg_val)
if ratio is not None and ratio < _CONTRAST_BLOCK_RATIO:
findings.append(
Finding(
"contrast-canary",
"error",
f"foreground and background contrast is {ratio:.2f}:1 (below "
f"{_CONTRAST_BLOCK_RATIO}:1); the text is effectively invisible. "
"Pick colors with at least 4.5:1 for body text.",
_line_of(css, offset),
)
)
elif abs(fg[0] - bg[0]) <= _CONTRAST_DELTA_L and abs(fg[1] - bg[1]) <= _CONTRAST_DELTA_C:
findings.append(
Finding(
"contrast-canary",
"warning",
"foreground and background are nearly identical "
f"(delta-L<={_CONTRAST_DELTA_L}, delta-chroma<={_CONTRAST_DELTA_C}); text "
"will be unreadable. Widen the lightness gap.",
_line_of(css, offset),
)
)
return findings
_SCANNERS = (
_scan_transition_all,
_scan_universal_hover_scale,
_scan_gradient_text_headline,
_scan_focus_ring_fade,
_scan_emoji_feature_icon,
_scan_two_line_cta,
_scan_contrast_canary,
)
def scan_css(css_text: str) -> list[Finding]:
"""Scan CSS (or HTML containing CSS/markup) for slop patterns.
Returns findings sorted by line, then rule_id. Deterministic.
"""
findings: list[Finding] = []
for scanner in _SCANNERS:
findings.extend(scanner(css_text))
findings.sort(key=lambda f: (f.line, f.rule_id))
return findings
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |