Commit Graph
92 Commits
Author SHA1 Message Date
Paul BakausandClaude Opus 4.6 fda447ee8b Merge layout findings into existing overlays instead of stacking
When an element already has an overlay from per-element checks (e.g.
side-tab), layout findings (e.g. nested-cards) now merge into the
same overlay label instead of creating a duplicate stacked on top.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 16:21:25 -07:00
Paul BakausandClaude Opus 4.6 3818073268 Reposition overlays after ancestor CSS transitions (reveal animations)
Use a document-level transitionend listener instead of per-element
listeners, so overlays reposition when a parent's transform transition
ends (e.g. reveal animations with translateY on an ancestor container).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 16:15:12 -07:00
Paul BakausandClaude Opus 4.6 05c9776fd8 Fix overlay positioning for fixed elements and improve test fixture
Overlays for elements inside position:fixed contexts now use
position:fixed with viewport-relative coords, so they stay pinned
on scroll. Extracted shared positionOverlay() helper for consistent
coordinate handling across highlight, reposition, and IO callbacks.

Updated fixture with a real fixed footer scenario.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 23:15:43 -07:00
Paul BakausandClaude Opus 4.6 9ffa802c89 Hide overlays for non-rendered elements using IntersectionObserver
Overlays are now created hidden and revealed by an IntersectionObserver
(rootMargin: 99999px), so they automatically show/hide when their target
becomes visible or invisible -- handles closed <details>, display:none,
hidden modals, overflow:hidden clipping, etc. without polling.

Adds overlay-positioning.html test fixture with 9 scenario groups
covering transforms, closed details, sticky, overflow, position offsets,
flex/grid, containing-block creators, and combinations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 23:12:24 -07:00
Paul BakausandClaude Opus 4.6 3f86b72c88 Isolate browser tabs for critique sub-agents to prevent interference
Each assessment now creates its own tab and labels it ([LLM] or [Human])
so parallel sub-agents don't fight over the same page state.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 22:30:00 -07:00
Paul BakausandClaude Opus 4.6 efcfd5dadd Merge main into v2.0: consolidate critique skill with scoring, personas, and detection
Merges 54 commits from main including factory-based build system, Trae support,
improved skill descriptions, and security hardening. Consolidates the critique
skill to combine v2.0's sub-agent architecture and automated anti-pattern
detection with main's Nielsen heuristics scoring, cognitive load assessment,
persona-based testing, and structured follow-up workflow. Fixes browser detector
build to create target directory after skill sync.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 22:20:04 -07:00
Paul BakausandClaude Opus 4.6 a9bf70f1ab Refine critique and audit skills based on review feedback
- Collapse inline cognitive load section into reference pointer
- Differentiate audit (technical, code-level) from critique (UX, holistic)
- Add MANDATORY PREPARATION block to audit for context gathering
- Rename Riley persona to "Deliberate Stress Tester", remove pricing focus
- Restore stripped checklist items, persona examples, and emotional journey detail
- Restore "Don't soften criticism" and IMPORTANT/NEVER lines in audit
- Restore constraints question in Phase 3
- Fix em dash formatting (use proper — not --)
- Shorten descriptions while preserving key trigger terms

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 16:57:47 -07:00
Paul BakausandClaude Opus 4.6 85e6d99fde Merge main and resolve frontmatter conflicts
Combine PR's enhanced descriptions (scoring, personas, cognitive load)
with main's argument-hint format. Rebuild all providers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 16:07:38 -07:00
Paul BakausandGitHub e3eb40c726 Merge pull request #61 from mvanhorn/docs/dropdown-positioning-guidance
docs: add dropdown positioning guidance to interaction-design reference
2026-03-24 15:59:14 -07:00
Paul BakausandClaude Opus 4.6 bea7315076 Merge main and resolve conflicts for description improvements
Take PR's improved skill descriptions (with "Use when..." trigger
phrases) and combine with main's argument-hint format. Drop old args
blocks and deleted transformer files.

Rebuild all providers so descriptions propagate everywhere.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 15:52:32 -07:00
Paul BakausandClaude Opus 4.6 83b01ecfa2 Use {{command_prefix}} for skill invocation references
Skill cross-references like "Use the frontend-design skill" and
"run teach-impeccable" now use {{command_prefix}} so each provider
gets the correct invocation syntax (/ for most, $ for Codex).

Prose references to skill content ("guidelines in the frontend-design
skill") are left unchanged since they're not invocation instructions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 15:24:29 -07:00
Paul BakausandClaude Opus 4.6 6de73abf1b Fix invalid YAML frontmatter and consolidate build transformers
Fixes #67: argument-hint values starting with [ were parsed as YAML flow
sequences. Replace structured args arrays in source files with pre-formatted
argument-hint strings, and quote values starting with [ or { in
generateYamlFrontmatter().

Also consolidates 8 nearly-identical transformer files into a single
config-driven createTransformer() factory. Adding a new provider now
requires only a config object in providers.js instead of a full file.

- Replace args source frontmatter with argument-hint strings
- Add YAML quoting for values starting with [ or {
- Add quote stripping to parseFrontmatter() for round-trip support
- Create factory.js + providers.js, delete 8 individual transformers
- Replace 16 explicit build.js calls with a loop over PROVIDERS
- Consolidate 8 test files into 2 (factory + providers)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 09:48:42 -07:00
Gabi 2b68f01ea3 feat: give critique and audit actual teeth — scoring, personas, cognitive load
Critique was vibes-only before. Now it scores against Nielsen's 10 heuristics
(0-4 each, /40 total) so you get a number, not just feelings. Added 5 user
personas that auto-select based on the interface type — a power user and a
first-timer break different things, turns out. Cognitive load checklist catches
the "why does this screen make my brain hurt" problems.

Audit gets the same treatment: 0-4 per dimension, /20 total, P0-P3 severity
instead of the vague Critical/High/Medium/Low labels nobody agrees on.

Both now present recommendations inline — no plan file, no /next or /fix-all
commands. Just tell the AI what to fix and it does it. Simpler.

New reference files: heuristics-scoring, personas, cognitive-load.
2026-03-24 00:13:00 +01:00
rohan-tesslandGitHub bec84bd2e6 Merge branch 'main' into improve/skill-review-optimization 2026-03-23 11:48:39 +05:30
Matt Van HornandClaude Opus 4.6 773a1c37ac docs: add dropdown positioning guidance to interaction-design reference
Adds a new "Dropdown & Overlay Positioning" section covering the overflow
clipping problem, CSS Anchor Positioning API, popover + anchor combo,
portal/teleport patterns, fixed positioning fallback, and anti-patterns.

Closes #48

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-21 08:37:33 -07:00
Paul BakausandClaude Opus 4.6 df1c26ce63 Fix user-invokable -> user-invocable spelling across entire codebase
PR #50 fixed the output SKILL.md files but the source files, build
scripts, tests, docs, and server code still used the wrong spelling.
Claude Code expects `user-invocable` (with c) for slash command
autocomplete to work.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 23:33:22 -07:00
Paul BakausandClaude Opus 4.6 1260c2350e Remove small-target detection (too aggressive for regular links)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 18:17:25 -07:00
Paul BakausandClaude Opus 4.6 122dddb686 Fix CLI docs and browser detector bugs
- Fix README CLI examples to use `bun bin/impeccable.mjs` instead of `npx impeccable`
- Fix classList.match() crash in Node/jsdom by converting DOMTokenList to string
- Fix overlapping page-level banners by merging all findings into a single banner

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 18:15:37 -07:00
rohan-tessl 430909da38 feat: improve skill descriptions for impeccable
## Summary

Hey @pbakaus 👋

I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after:

| Skill | Before | After | Change |
|-------|--------|-------|--------|
| distill | 31% | 80% | +49% |
| delight | 32% | 74% | +42% |
| polish | 44% | 80% | +36% |
| animate | 55% | 89% | +34% |
| clarify | 49% | 83% | +34% |
| critique | 51% | 85% | +34% |
| normalize | 46% | 80% | +34% |
| optimize | 49% | 83% | +34% |
| adapt | 48% | 81% | +33% |
| extract | 48% | 81% | +33% |
| harden | 49% | 79% | +30% |
| arrange | 51% | 76% | +25% |
| bolder | 51% | 76% | +25% |
| colorize | 48% | 72% | +24% |
| overdrive | 48% | 70% | +22% |
| typeset | 64% | 85% | +21% |
| audit | 61% | 81% | +20% |
| onboard | 56% | 75% | +19% |
| quieter | 59% | 76% | +17% |
| teach-impeccable | 68% | 80% | +12% |
| frontend-design | 76% | 76% | +0% |

**Note:** These skills are auto-generated from `source/skills/` via your build system, so the changes target the source files directly. The `dist/` outputs were regenerated with `bun run build`.

<details>
<summary>Changes made</summary>

All changes are limited to the `description` field in each skill's YAML frontmatter (in `source/skills/*/SKILL.md`). No skill body content was modified.

The consistent improvement across all skills was adding:
- **"Use when..." clauses** with explicit trigger terms — the #1 issue flagged by the reviewer. Without these, agents have no clear signal for when to select a skill from a large library.
- **Natural user keywords** — terms users would actually say (e.g., "too bold", "laggy", "spacing issues") rather than abstract descriptors.
- **Specific concrete actions** — listing what the skill actually does rather than describing outcomes in vague terms.
- **Quoted string format** — ensuring descriptions use standard YAML quoted strings.

`frontend-design` was already well-scored and left unchanged.

</details>

## Type of change

- [x] New / updated skill reference

## Checklist

- [x] Source files updated in `source/`
- [x] `bun run build` ran successfully
- [x] `bun test` passes
- [ ] Tested with at least one provider (Cursor / Claude Code / Gemini CLI / Codex / Copilot / Kiro / OpenCode)
- [ ] README / DEVELOP.md updated if needed

---

Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@rohan-tessl](https://github.com/rohan-tessl) - if you hit any snags.

Thanks in advance 🙏
2026-03-20 12:46:14 +05:30
Paul BakausandClaude Opus 4.6 4f18ddaf52 Improve critique skill: sub-agents, scripts_path, browser overlays
- Add {{scripts_path}} build placeholder that resolves per-provider
  (${CLAUDE_PLUGIN_ROOT}/scripts for Claude Code, relative paths for others)
- Restructure critique into sub-agent architecture: LLM review and
  detector run independently to avoid bias, results synthesized at end
- Browser overlay is now a visual aid for the user only -- agent reads
  findings from console via [impeccable] prefix instead of scrolling
- Add scroll-to-top instruction before overlay injection
- Add allowed-tools frontmatter for detector bash commands
- Fix YAML parser to handle simple string arrays (not just - name: objects)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 19:29:22 -07:00
Paul BakausandClaude Opus 4.6 a243cbfdcb Stronger guardrail: detector must run after LLM review
Claude was running the detector in parallel with the LLM review
despite the section ordering. Added explicit instruction: "Do not
run the detector before or in parallel with your LLM review."

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 18:12:18 -07:00
Paul BakausandClaude Opus 4.6 87067cad7e Clarify detector accepts markup files, not CSS-only
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 18:10:54 -07:00
Paul BakausandClaude Opus 4.6 cda5e42fa9 Flip critique order: LLM assessment first, detector second
The detector findings were anchoring the LLM's thinking too heavily,
making the critique feel detector-driven rather than design-driven.
Now the LLM forms its own assessment first, then the detector runs
to catch anything missed. The report structure reflects this: LLM
assessment comes before deterministic scan in the Anti-Patterns
Verdict.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 18:05:48 -07:00
Paul BakausandClaude Opus 4.6 699c1043cc Fix critique skill from real-world testing
Detection fixes:
- Cramped padding: skip small elements (labels/badges < 100x30px)
  and require >20 chars of text content
- Skip browser extension elements (claude-*, cic-*) from scan loop
  and quality checks to avoid flagging the Claude Chrome indicator

Skill prompt fixes:
- Use python HTTP server + script tag injection instead of direct
  javascript_tool evaluation (avoids CORS issues)
- Add cleanup step for the HTTP server

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 17:21:38 -07:00
Paul BakausandClaude Opus 4.6 a24328a0fa Skip CLI detector for URLs (avoids Puppeteer install)
URLs should use browser visualization + LLM analysis instead of
the CLI detector, which would need to install Puppeteer and its
dependencies first.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 13:12:31 -07:00
Paul BakausandClaude Opus 4.6 4591e51b6f Tighten critique skill per best practices (195 -> 104 lines)
- 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>
2026-03-19 12:26:04 -07:00
Paul BakausandClaude Opus 4.6 2f49a2709f Enhance /critique skill with CLI-first scan and browser visualization
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>
2026-03-19 12:09:39 -07:00
Paul BakausandClaude Opus 4.6 afcff7eea0 Add impeccable CLI with detect subcommand
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>
2026-03-19 00:27:14 -07:00
Paul BakausandClaude Opus 4.6 8899d514b8 Polish browser overlay UX: hover expansion, tooltip, resize tracking
- 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>
2026-03-18 23:34:54 -07:00
Paul BakausandClaude Opus 4.6 50485e0453 Add 9 design quality detections, improve browser overlay UX
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>
2026-03-18 23:12:41 -07:00
Paul BakausandClaude Opus 4.6 4d2ef64935 Fix glow/gradient detection, fix test performance (280s -> 5s)
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>
2026-03-18 14:49:40 -07:00
Paul BakausandClaude Opus 4.6 0574bd0be2 DRY: extract checkHtmlPatterns, add gradient background detection
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>
2026-03-18 11:19:04 -07:00
Paul BakausandClaude Opus 4.6 c751015fa1 Add motion and dark-glow anti-pattern detection (15 → 16)
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>
2026-03-18 08:36:21 -07:00
Paul BakausandClaude Opus 4.6 d1d8929dc2 Merge 3 detection scripts into one universal file
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>
2026-03-17 19:17:00 -07:00
Paul BakausandClaude Opus 4.6 fbfe525f4f Move generated browser script to .claude/skills/critique/scripts/
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>
2026-03-17 18:11:35 -07:00
Paul BakausandClaude Opus 4.6 623a8a8375 Extract shared core module, generate browser script at build time
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>
2026-03-17 18:04:19 -07:00
Paul BakausandClaude Opus 4.6 7bc3a5567d DRY: replace Puppeteer page.evaluate with browser script injection, add 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>
2026-03-17 16:53:13 -07:00
Paul BakausandClaude Opus 4.6 add8c1958d Fix nested card detection: innermost-only, lower threshold, raw style 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>
2026-03-17 16:34:04 -07:00
Paul BakausandClaude Opus 4.6 f90e640892 Fix nested card detection, drop identical-card-grid
- 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>
2026-03-17 15:54:00 -07:00
Paul BakausandClaude Opus 4.6 72b9ca2941 Add layout anti-pattern detection: nested cards, identical grids, spacing, 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>
2026-03-17 15:15:40 -07:00
Paul BakausandClaude Opus 4.6 27715edf8a Add Tailwind color class detection for all color anti-patterns
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>
2026-03-17 12:52:21 -07:00
Paul BakausandClaude Opus 4.6 8a357d4754 Add color and contrast anti-pattern detection
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>
2026-03-17 12:41:45 -07:00
Paul BakausandClaude Opus 4.6 ed1579ee37 Skip page-level checks on partials/components
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>
2026-03-17 11:49:32 -07:00
Paul BakausandClaude Opus 4.6 37393f1793 Normalize detection to jsdom by default, regex as fallback
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>
2026-03-17 11:44:00 -07:00
Paul BakausandClaude Opus 4.6 32a54138bb Add deep detection via jsdom and URL scanning via Puppeteer
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>
2026-03-17 11:07:47 -07:00
Paul BakausandClaude Opus 4.6 1fb896a3ff Add typography anti-pattern detection: overused fonts, single font, flat 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>
2026-03-17 11:00:58 -07:00
Paul BakausandClaude Opus 4.6 f9bfe18d26 Add anti-pattern detection CLI, browser visualizer, gallery page, and 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>
2026-03-17 10:54:06 -07:00
Paul BakausandClaude Opus 4.6 e818c14ff1 Distinguish fluid vs fixed type scales for apps vs content pages
The typeset skill universally recommended fluid sizing via clamp(),
but no major app design system (Material, Polaris, Primer, Carbon)
uses fluid type in product UI. Now recommends fixed rem scales for
app UIs and reserves fluid type for marketing/content page headings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-17 08:18:15 -07:00
Paul BakausandClaude Opus 4.6 61eaceefdd Add overdrive ASCII banner on skill activation
Starts the response with a distinctive speed-line banner
to set the tone for the skill.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-16 15:51:55 -07:00
Paul BakausandClaude Opus 4.6 fcc70fd4c9 Require direction confirmation and browser iteration for overdrive
Two new mandatory sections in the skill:

1. Propose Before Building — must present 2-3 directions with
   trade-offs and get user confirmation before writing code. This
   skill has the highest misfire potential.

2. Iterate with Browser Automation — must use browser tools to
   visually verify effects and iterate. Complex effects never work
   on the first try.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-16 11:45:30 -07:00