Syne stays in reflex_fonts_to_reject but no longer gets a standalone
DON'T rule in the skill or a separate LLM-only entry in the catalog.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Clarify that /impeccable craft runs /shape internally (not the other way around)
- Add three-mode documentation (freeform/craft/teach) to /impeccable page with anchor links
- Add sidebar sub-links for /impeccable craft and /impeccable teach
- Fix hallucinated npx impeccable live description in tutorial and visual-mode page
- Remove nonsensical "Do not skip the independent part" from critique tutorial
- Make Step 4 less prescriptive (users can fix all at once or one-by-one)
- Improve CLI and browser extension install copy with specific features and use cases
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The skill's "don't use Inter / don't use dark / don't center" negatives
were creating new attractors (the model picks Fraunces / light / grid
instead, every time). Inline always-applicable principles into SKILL.md,
add a font selection anti-attractor procedure that forces the model to
enumerate AND reject its reflex defaults, switch high-stakes blocks to
XML structure, tighten side-tab and gradient-text bans to specific CSS
patterns, ban Syne explicitly, and strip named font/color prescriptions
from the references. Validated against the internal eval framework on
Qwen 3.6 Plus across 7 niches: Fraunces dropped from 92% to 0% on kids
reading, side-tabs from 76% to 20% on vintage moto, no theme regressions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
A new icon-tile-stack detection (the canonical AI feature-card with a
small rounded-square icon container above a heading), backed by a
two-column TDD fixture, plus a single-source-of-truth design that ties
the engine to the impeccable skill so they can no longer drift silently.
Detection
- New icon-tile-stack rule (slop): heading's previousElementSibling is
a 32–128px rounded-square element with a non-transparent background
or border, contains an svg/icon-i child, and sits above (not next to)
the heading. Excludes round avatars, wide thumbnails, side-by-side
layouts, tiny icons, and hero images.
- Two-column fixture convention: a single icon-tile-stack.html with a
flag column (4 cases) and pass column (6 cases), with snippet-text
matching used by the fixture test.
Single source of truth
- Each ANTIPATTERNS entry can now declare skillSection + skillGuideline.
18 of 25 rules carry these fields; the build's new
validateAntipatternRules() in scripts/build.js fails if any declared
skillGuideline isn't found verbatim in the right SKILL.md section.
- scripts/build-extension.js now includes the description field in
extension/detector/antipatterns.json (it was previously dropped).
- The existing count validator was promoted from warn to error so
command count drift fails the build the same way detection drift does.
Impeccable skill DON'Ts
- Added 4 new top-level DON'Ts that target real default AI behavior:
single-font, flat-type-hierarchy, all-caps-body, line-length.
- Cut 7 new DON'Ts I had drafted (tight-leading, tiny-text, wide-tracking,
justified-text, low-contrast, cramped-padding, skipped-heading) because
they teach things every model already knows from CSS/a11y basics. The
detector still catches all of them.
Stale count cleanup
- 22 commands → 21 across 17 references in HTML, README, NOTICE, AGENTS,
plugin.json, marketplace.json (left over from the validate skill removal).
- Dropped the hand-coded "212 design guidelines" marketing copy on the
homepage, which never mapped to any real count.
Sub-agent
- New private .claude/agents/anti-patterns.md captures the full TDD
recipe, schema, plug-in points, jsdom constraints, and pre-commit
checklist so future sessions can add rules end-to-end without
re-investigating the wiring.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Rename /craft skill to /shape and make it planning-only (no code output)
- Add /impeccable craft sub-command that calls /shape, loads references,
builds with visual iteration until delightful
- Replace all " -- " (em dash substitutes) with proper punctuation across
all skill files and index.html
- Move v1.6 changelog entry to "View older releases" section
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The CLI and detection engine now live in pbakaus/impeccable-detect
(published as 'impeccable' on npm, BSL-1.1). This repo is purely
Apache 2.0: skills, prompts, website, and build system.
- Remove bin/ (CLI moved to CLI repo)
- Remove README.npm.md (moved to CLI repo)
- Remove @impeccable/detect dependency, add impeccable dependency
- Set package.json to private (no longer published to npm)
- Update all references from @impeccable/detect to impeccable
- Update CLAUDE.md, NOTICE.md, FAQ, and changelog
- Rebuild all provider skill distributions
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>
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>
