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>
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>
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>
Reverts Codex's overly bureaucratic sub-agent delegation changes (permission
prompts, "not fully compliant" disclaimers) back to clear, practical language.
Uses RFC-style SHOULD for sub-agent delegation with named examples for both
Claude Code (Agent tool) and Codex (natural language spawning).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace the sliding accordion with a 3D card stack for Gallery of Shame
(bottom-right deck offset with scroll/button nav). Patterns now use clean
pill tabs with single-column Don't/Do layout in a white container.
Also scaffolds two new skills: /validate (fast visual validation after UI
changes) and /craft (guided feature design through user interview).
Fixes detection count from 25 to 24, changes badge from "Deterministic"
to "New!".
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Replace tabbed pattern viewer with animated horizontal disclosure
(inspired by jh3y/XJWNMOO): CSS Grid column transitions, hover to
expand, rotated vertical labels, icon anchored at bottom
- Don't/Do toggle in each panel (defaults to Don't)
- Gallery of Shame as 2-column thumbnail sidebar beside the disclosure
- Detection callout as horizontal strip below
- Responsive: stacks at 1060px, gallery becomes 3-col grid
- Remove all em dashes from anti-pattern text (AI slop tell)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Major skill consolidation for v2.0:
- Rename source/skills/frontend-design/ to source/skills/impeccable/
with user-invocable: true and argument-hint: "[teach]"
- Fold teach-impeccable body into impeccable as "Teach Mode" section,
activated via /impeccable teach
- Create deprecation shims:
- frontend-design: redirects to /impeccable
- teach-impeccable: redirects to /impeccable teach
- Update all 16 skill cross-references from {{command_prefix}}frontend-design
to {{command_prefix}}impeccable and {{command_prefix}}teach-impeccable to
{{command_prefix}}impeccable teach
- Update CLI sentinel detection to use 'impeccable' (with teach-impeccable
as legacy fallback)
- Update build system readPatterns() path and EXCLUDED_FROM_SUGGESTIONS
- Update all public files (data.js, cheatsheet, index, viz, demos)
- Update all documentation (README, NOTICE, AGENTS, plugin.json)
- Update all test expectations
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Replace hover outline-offset with outline-color transition (no flicker)
- Label shows type name by default; on hover, detail slides up to replace
it ticker-style with a dark background for visual distinction
- Banner: horizontal scroll with scroll-snap for findings, fixed controls
- Add toggle button to show/hide all overlays
- Overlays use pointer-events:none so page interactions (text selection,
clicks, links) pass through; hover driven via target mouseenter/leave
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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.
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>
- 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>
## 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 🙏
- 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>
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>
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>
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>
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>
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>
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>
- 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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
- 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>
