v2.0: Anti-pattern detection system by pbakaus · Pull Request #56 · pbakaus/impeccable

pbakaus · 2026-03-20T16:12:48Z

Summary

Working branch for Impeccable v2.0. This release adds a comprehensive anti-pattern detection system -- both a deterministic CLI scanner and browser visualization overlay -- plus major improvements to the build system and critique skill.

Anti-pattern detection engine

25 detection rules across typography, color, layout, visual details, motion, and design quality
Dual-mode scanner: jsdom-based deep analysis (default) with regex-only fast mode (--fast)
Browser visualizer: injects overlays directly on live pages highlighting detected anti-patterns
CLI tool: bun bin/impeccable.mjs detect [target] for standalone usage outside AI harnesses
Unified universal detection script works in both Node.js and browser environments

`/critique` skill overhaul

Sub-agent architecture: LLM design review and automated detection run independently to avoid bias, results synthesized into a combined report
{{scripts_path}} build placeholder resolves per-provider (${CLAUDE_PLUGIN_ROOT}/scripts for Claude Code, relative paths for Cursor/Gemini/Codex/etc.)
Browser overlay is now a visual aid for the user -- agent reads findings from console instead of scrolling through screenshots
allowed-tools frontmatter declares required bash commands

Build system improvements

Shared transformer (shared.js) replaces per-provider duplication
YAML parser now handles simple string arrays (not just - name: objects)
{{scripts_path}} dynamic placeholder -- prefix-aware, provider-aware
Browser detector script auto-generated at build time from shared source

Gallery of Shame

New /gallery page showcasing real anti-pattern examples with live detection overlays

Tests

590+ test assertions covering all 25 detection rules
Browser detector tests
Fixture-based test suite with should-flag/should-pass HTML files

Test plan

Run bun test -- all detection tests pass
Run bun bin/impeccable.mjs detect public/index.html -- CLI works
Run /critique in Claude Code -- sub-agent flow, console-based overlay reading
Verify bun run build succeeds and {{scripts_path}} resolves correctly for Claude Code and Cursor outputs
Check /gallery page loads with live detection overlays

🤖 Generated with Claude Code

… build DRY refactor - Anti-pattern detector script (source/skills/critique/scripts/detect-antipatterns.mjs): CLI tool that scans files/dirs for UI anti-patterns via regex. Detects side-tab accent borders and border-accent-on-rounded patterns across Tailwind, CSS, JSX. Context-aware: skips safe elements (blockquotes, nav, inputs, code), neutral colors, and adjusts thresholds based on border-radius co-occurrence. - Browser visualizer (public/js/detect-antipatterns-browser.js): Drop-in script that highlights anti-patterns directly in the browser with labeled overlays. Two modes: "static" (regex, matches CLI) and "computed" (getComputedStyle, catches CSS cascade). Scans both inline styles and <style> blocks. - Gallery of Shame (public/gallery.html): Standalone page showcasing 11 AI anti-pattern examples with thumbnails and links. Anti-pattern example pages updated from 1080x1080 Twitter format to responsive layouts, labels removed, screenshots retaken at 16:10. - Critique skill updated to run detector before manual review. - Build system: skills now support scripts/ directories alongside reference/. All 8 provider transformers refactored to use shared.js (DRY). - 58 new tests covering detection logic, fixtures, CLI integration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…lat hierarchy Three new detections: - overused-font: flags Inter, Roboto, Open Sans, Lato, Montserrat, Arial as primary font-family or via Google Fonts imports - single-font: file-level analyzer flags pages using only one non-generic font family (needs pairing for typographic hierarchy) - flat-type-hierarchy: file-level analyzer collects all font-size values (px, rem, Tailwind text-* classes, clamp min/max) and flags when the max/min ratio is below 2.0 Detection engine extended to support file-level analyzers alongside line-level matchers. Typography fixtures added for both should-flag and should-pass cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Three detection tiers: - file/dir (default): fast regex scan, zero dependencies - file + --deep: jsdom computed styles, resolves linked local stylesheets by inlining <link rel="stylesheet"> content before parsing - URL (https://...): auto-launches Puppeteer for full browser rendering, handles CDN stylesheets, JS-rendered content, everything New exports: detectAntiPatternsDeep(), detectAntiPatternsUrl() jsdom added as devDependency; puppeteer remains optional (npx cache). TDD: linked-stylesheet fixture demonstrates the gap — regex finds 0 border issues, --deep correctly catches side-tab and top-accent from the external CSS file. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Architecture simplified to two paths: - HTML files: jsdom with getComputedStyle (resolves linked CSS, cascade) - Non-HTML files: regex fallback (CSS, JSX, TSX, etc.) - URLs: Puppeteer (unchanged) - --fast flag forces regex-only for all files Removed --deep flag (jsdom is now the default). Removed static mode from browser script (always uses getComputedStyle — it's in a real browser). Anti-pattern definitions split into: - checkElementBorders() — shared element-level computed style checker - checkPageTypography() — shared page-level checker - REGEX_MATCHERS/REGEX_ANALYZERS — regex fallback for non-HTML Browser script simplified from 470 lines to 250. CLI script reduced from 810 lines to 440. Detection logic is now single-source for jsdom/puppeteer/browser. Fixtures now served via /fixtures/* route in dev server for proper CORS handling of linked stylesheets. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Page-level typography checks (flat hierarchy, single font, overused font) now only run on files that look like full pages (have <!DOCTYPE, <html>, or <head> tags). Partials and components still get element-level border checks. isFullPage() strips HTML comments before checking to avoid false matches on prose that mentions tag names. Added partial-component.html fixture that has Inter, flat sizes, and a side-tab border — verifies only the border is flagged. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Five new detections: - pure-black-white: flags #000/#fff in styles via regex (jsdom bg resolution unreliable for this) - gray-on-color: gray text (low chroma, mid luminance) on colored backgrounds via getComputedStyle + ancestor bg walk - low-contrast: WCAG AA violation (4.5:1 body, 3:1 large text) via computed contrast ratio with resolved effective background - gradient-text: background-clip:text + gradient combo via regex (jsdom doesn't compute background-clip) - ai-color-palette: conservative purple/violet accent detection via regex on known hex values in prominent contexts Background resolution handles jsdom limitation where background shorthand isn't decomposed — falls back to parsing raw style attribute for hex colors. Color fixtures added for both should-flag (all 5 types) and should-pass (tinted neutrals, good contrast, non-purple accents). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Element-level (jsdom) and regex (--fast) detection for: - bg-black, bg-white, text-black: pure black/white - text-white without dark bg class: pure white on light - text-gray-*/slate-*/zinc-* on bg-{color}-*: gray on colored bg - text-purple-*/violet-*/indigo-* on headings/large text: AI palette - from-purple-* to-indigo-*: purple gradient - bg-clip-text + bg-gradient-to-*: gradient text (already existed) text-white is NOT flagged when paired with a dark bg class (bg-black, bg-gray-700+, bg-blue-500+, etc.) since that's intentional contrast. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Mirrors all 5 color anti-pattern checks from the CLI: - pure-black-white (computed bg + Tailwind classes) - gray-on-color (computed style + ancestor bg resolution + Tailwind) - low-contrast (WCAG AA ratio via computed styles) - gradient-text (computed background-clip + Tailwind bg-clip-text) - ai-color-palette (computed hue analysis + Tailwind purple classes) Browser version uses real getComputedStyle so bg resolution works properly (unlike jsdom). Tailwind class checks are shared logic. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…cing, centering Four new layout detections: - nested-cards: jsdom DOM walk finds card-like elements (shadow + rounded + bg) nested inside other card-like elements. Excludes dropdowns (absolute/fixed), form inputs, code blocks, badges (<20 chars), and known component classes. - identical-card-grid: detects grid/flex parents with 3+ children sharing the same structural fingerprint (icon + heading + paragraph template pattern). - monotonous-spacing: regex on raw HTML collects padding/margin/gap values (px, rem, Tailwind classes), rounds to nearest 4px, flags when >60% use the same value with <=3 distinct values. - everything-centered: regex counts text-align:center and Tailwind text-center on text elements, flags when >70% of 5+ text elements are centered. Also narrowed pure-black-white to only flag #000 as background color — text-black, text-white, bg-white, and #fff are no longer flagged (too common, per user feedback). Extensive should-pass fixture covers: shadcn card sub-components, cards with form inputs/dropdowns/code blocks/badges/accordions/tabs/images, pricing cards, varied spacing, mixed centered/left-aligned layouts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Matches CLI behavior: only bg-black and computed #000 backgrounds are flagged. bg-white, text-black, text-white, and #fff are no longer flagged in the browser visualizer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Adds checkLayout() with nested-cards and identical-card-grid detection using computed styles and DOM tree walking. Same logic as CLI: - isCardLike() checks shadow + rounded + bg/border (2 of 3) - Excludes dropdowns, modals, tiny elements, safe tags - Identical grid fingerprints icon + heading + paragraph structure Layout findings are highlighted on the actual elements (not just in the page banner). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Nested cards: fixed dedup to use WeakSet on actual elements instead of tag-name key, so all nested card instances are found (not just the first div-in-div pair). Now catches all 4+ nesting examples. - Dropped identical-card-grid: too many legitimate uses (data displays, pricing cards, navigation tiles) make false positives unavoidable. - Removed from CLI, browser script, tests, and ANTIPATTERNS registry. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Same bug as the CLI had: Set with tag-name key ('DIV:DIV') deduped all nested divs to one finding. Now uses WeakSet on actual elements so each nested card instance gets its own outline. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… fallback Three fixes: - Only flag innermost nested cards: if L1>L2>L3, only L3 gets flagged (not L2). Uses ancestor-filtering after collection pass. - Lower text threshold from 20 to 10 chars to catch short card content like "Inner card via CSS." - isCardLike now also checks raw inline style attribute for box-shadow and border-radius (jsdom doesn't resolve CSS shorthands). Tightened heuristic: shadow or border is mandatory (not optional). Fixes false positive on layout-should-pass where a tinted subsection (rounded + bg, no shadow) inside a card was incorrectly flagged. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

WeakSet.prototype[Symbol.iterator] doesn't exist — can't use for..of. Changed to Set (same fix as CLI). Also updated isCardLike heuristic to require shadow or border as mandatory, matching the CLI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…dd browser tests Major cleanup: - detectUrl() now injects the browser script via page.evaluate() and calls window.impeccableScan() instead of reimplementing all detection logic inline. Removes ~80 lines of triple-duplicated code. - Removed dead isPureBlackOrWhite function. - CLI reduced from 1286 to 1212 lines. New: Puppeteer-powered browser parity tests (detect-antipatterns-browser.test.js): - Starts a local HTTP server for fixtures - Loads fixture pages in headless Chrome - Runs the browser detection script via impeccableScan() - Verifies findings match expectations for all fixture categories: borders, colors, layout, typography, partials 8 new browser tests catch desync between CLI and browser script (like the WeakSet iteration bugs we hit earlier). puppeteer added as devDependency. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

DRY refactor: - detect-antipatterns-core.mjs (297 lines): shared constants (SAFE_TAGS, OVERUSED_FONTS, GENERIC_FONTS, ANTIPATTERNS), color utilities (parseRgb, relativeLuminance, contrastRatio, hasChroma, getHue, colorToHex, isNeutralColor), and pure detection functions (checkBorders, checkColors, isCardLikeFromProps). - CLI (889 lines, was 1212): imports from core, keeps jsdom-specific resolveBackground, page-level analyzers, regex fallback, and CLI logic. - Browser wrapper (335 lines): template with browser-specific DOM adapters, highlighting, scan loop. Core is injected at build time. - build-browser-detector.js: reads core, strips exports, injects into wrapper, writes to public/js/detect-antipatterns-browser.js (generated). - Build step added to scripts/build.js (runs before Bun bundling). Source of truth for detection logic is now the core module. Browser script is generated — do not edit public/js/detect-antipatterns-browser.js directly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The generated browser detector now lives alongside the CLI script in .claude/skills/critique/scripts/ — clearly a build artifact, not a hand-maintained source file in public/js/. - build-browser-detector.js outputs to .claude/ instead of public/js/ - Dev server serves .claude/skills/* for local testing - All fixture and antipattern-example HTML files updated to new path - Puppeteer detectUrl reads browser script from same directory - Browser parity test server updated to serve from .claude/ - Deleted public/js/detect-antipatterns-browser.js Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The skill sync wipes .claude/skills/ and re-copies from dist, deleting the generated browser script. Moved build-browser-detector.js to run AFTER the sync. Dev server's /js/* route now falls through to .claude/skills/critique/scripts/ for built artifacts. All fixture HTML references use /js/detect-antipatterns-browser.js (clean URL). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Combine detect-antipatterns-core.mjs, detect-antipatterns.mjs, and detect-antipatterns-browser-wrapper.js into a single universal file that auto-detects browser vs Node via IS_BROWSER. Shared constants, color utilities, and pure detection logic exist once instead of being duplicated across files. Build script simplified to strip @browser-strip-start/end markers, set IS_BROWSER=true, and wrap in IIFE. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

New detections: - bounce-easing: flags bounce/elastic animation names, animate-bounce (Tailwind), and cubic-bezier curves with overshoot (y values outside [0, 1]) - layout-transition: flags explicit transition of width, height, padding, margin, and max-height/min-width variants; skips transition: all - dark-glow: flags colored box-shadow with blur > 4px on dark backgrounds (luminance < 0.1); skips gray shadows, focus rings (no blur), and non-dark backgrounds Includes 48 new tests across unit, regex, and jsdom fixture tests with dedicated should-flag and should-pass HTML fixtures for both categories. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace the buried "Gallery of Shame" inline link with a compact detector summary card showing all 16 auto-detected anti-patterns as chips grouped by category (Borders, Typography, Color, Layout, Motion). Prominent gallery link in the footer. Revised lead copy to mention the automated detector. Keeps the tabbed Do/Don't pattern reference below unchanged. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace the detector summary card and badge system with a simple inline note below the tabbed Do/Don't patterns: "/critique catches all of these. 16 deterministically, the rest through LLM analysis." Gallery of Shame and Suggest a pattern links sit inline alongside. Subtle divider separates the note from the patterns above. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Extract all regex-on-HTML checks into shared checkHtmlPatterns() function called by both browser and Node paths. Eliminates drift between checkTypography/checkPageTypography and removes separate checkPageMotion/checkPageGlow functions. Add parseGradientColors() utility and checkElementGradientDOM() to detect purple/violet gradient backgrounds on any element including buttons (bypasses SAFE_TAGS). Fix false low-contrast findings on gradient backgrounds by returning null from resolveBackground when a gradient is encountered. Fix "Only font:" double-colon in browser labels. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Detection improvements: - Remove SAFE_TAGS from glow check (buttons/links with glows are valid) - Add gradient color parsing (parseGradientColors) for AI palette detection on gradient backgrounds including buttons - Detect cyan neon text on dark backgrounds as AI palette - Resolve gradient backgrounds as dark for glow detection - Fix pure-black false positive on semi-transparent overlays (a >= 0.9) - Skip low-contrast/gray-on-color when background is a gradient - Fix "Only font:" double-colon in browser labels Test performance: - Split jsdom fixture tests to Node's test runner (bun + jsdom hangs after ~13 instances due to resource leak) - bun test for unit/regex/CLI tests (94 tests, 4s) - node --test for jsdom fixtures (15 tests, 1.3s) - Total: 109 tests in ~5s (was 280s+) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

New detections (browser-only, DOM-based): - line-length: text wider than ~85 chars per line - cramped-padding: <8px padding in bordered/bg containers (2+ borders) - tight-leading: line-height < 1.3x on body text - small-target: interactive elements < 44x44px - skipped-heading: heading levels that skip (h1 then h3) - justified-text: text-align: justify without hyphens: auto - tiny-text: font-size < 12px on body text (>20 chars) - all-caps-body: text-transform: uppercase on >30 chars of body text - wide-tracking: letter-spacing > 0.05em on non-uppercase body text Browser overlay improvements: - Hover swaps label for detail tooltip (CSS-based, not JS events) - Border goes transparent on hover to reveal element underneath - Fixtures: quality-should-flag.html and quality-should-pass.html Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Switch from border to CSS outline for overlays (cleaner, animatable) - On hover: outline expands outward 4px, label shifts up to match, tooltip slides in from below with fade, z-index elevates above others - Exclude page banner from hover transitions via .impeccable-banner class - Reposition overlays on window resize via requestAnimationFrame - CSS-only hover states (no JS event listeners) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Usage: npx impeccable detect [file-or-dir-or-url...] Subcommand structure designed for future expansion. The detect subcommand delegates to the existing detection engine with all its modes (jsdom, regex, Puppeteer). - bin/impeccable.mjs: CLI entry point with bun shebang - package.json: bin field added - Export detectCli (main) from detection script - Updated help text to show impeccable detect usage - Updated CLAUDE.md and README.md with CLI docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The critique skill now has three layers of detection: 1. CLI-first pass (always): Runs the deterministic detector via `node {{skills_dir}}/critique/scripts/detect-antipatterns.mjs --json` with scope checks (file count estimation, --fast for 200-500 files, user prompt for >500 files) 2. Browser visualization (when available): If the AI harness has browser automation (Chrome MCP, Cursor browser), injects the detection script into the page for live visual overlays. Reads the browser script via cat, injects via javascript_tool. 3. LLM analysis (always): The existing deep design critique across 10 dimensions, now informed by deterministic scan results. Add {{skills_dir}} placeholder to build system for cross-provider script paths (.claude/skills, .cursor/skills, .gemini/skills, etc). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add trigger context to description ("Use when...") - Compress scan workflow from 4 verbose steps to concise block - Remove false "zero false negatives" claim, add false-positive guidance - Avoid loading 55KB browser script into context (inject directly) - Remove time-sensitive "2024-2025" reference - Compress 10 evaluation dimensions to AI Slop (expanded) + single holistic review paragraph (Claude knows how to evaluate these) - Revert {{skills_dir}} placeholder (relative paths per skill docs) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Each of the 7 dimension icons now has a continuous subtle animation (breathing draws, pulsing circles, bobbing ball, blinking cursor, toggle wobble) plus an enhanced hover effect. Responsive icon uses transform-box: fill-box for a staggered desktop-to-mobile reflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Switch staircase to grid at 1200px (was 1024px) to prevent tall stairs from clipping at narrow desktop widths - Add 2-col grid at 768px, compact horizontal cards at 520px - Fix count crowding heading: use overflow hidden to gracefully hide count when card is too narrow instead of wrapping or cramming Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…v servers Tier 1: Add Vue/Svelte <style> block extraction and CSS-in-JS template literal detection (styled-components, emotion) so anti-patterns inside framework-specific syntax are caught. Enable multi-line context for CSS files so cross-line patterns like gradient-text are detected. Tier 2: Build a lightweight import graph when scanning directories. Findings are annotated with importedBy context (e.g. "imported by App.tsx") in both human and JSON output. Tier 3: Detect framework config files (Next.js, Vite, SvelteKit, Nuxt, Astro, Angular, Remix), probe the dev server port with HTTP fingerprinting to distinguish the expected framework from unrelated services, and suggest URL-based scanning for more accurate results. Adds realistic Next.js project fixtures (Tailwind, CSS Modules, styled-components) plus Vue, Svelte, JSX, and CSS-in-JS unit fixtures. 158 tests, 356 assertions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add interactive confirmation when scanning directories with 50+ files, warning about jsdom overhead for HTML files and suggesting --fast or targeting a subdirectory. Auto-skipped in non-TTY (piped/CI) contexts. Update CLAUDE.md and README.md to use node/npx instead of bun for the detect CLI, since bun's jsdom is extremely slow and causes scans to hang. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace local detection engine dependency with @impeccable/detect (BSL-1.1 licensed, github:pbakaus/impeccable-detect). The main CLI now delegates both `detect` and `live` commands to the external package. Update critique skill to use `npx @impeccable/detect live` instead of python3 http.server for serving the browser detection overlay. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>