* skill: drop quality tiers, keep the real brand-craft guardrails
Codex's craft/brand pass introduced fast/ship/showpiece "quality bars"
plus brand-specific build gates, asset ledgers, sub-agent review, and
self-graded fallback labels. In practice those tiers became escape
hatches rather than craft pressure: the final output should always be
10/10, and the real decision points are splashiness and maximalism, not
quality.
Removed:
- All quality-bar / showpiece / fast / ship framing in shape.md and craft.md
- Standalone Brand Direction (#4) and Asset Requirements (#10) sections
in shape's brief; renumbered back to 1-10
- The Brand hard rules section in brand.md (folded its real prohibitions
into the existing Imagery and Brand bans sections)
- Brand-specific build-gate item, mock-fidelity bullet, production-bar
bullet, present-step bullet in craft.md
- Asset ledger ceremony in craft Step 4
- Review-only sub-agents and "self-reviewed fallback, not independently
validated" machinery in craft.md and polish.md
- The For brand surfaces, assess hard failures subsection in polish.md
and the brand checklist row
- tests/brand-showpiece-reference.test.mjs (and its package.json wiring)
Kept (the real nuggets):
- Asset-substitution prohibition: image-led briefs ship real/generated
assets or canvas/SVG/WebGL, not generic CSS panels, cards, bullets,
or copy
- Repeated tiny uppercase tracked kicker labels as a brand ban
- Detector/QA output is defect evidence only, never proof of quality
- "What visual assets are real content here?" discovery question
- Inspect each major section individually for brand and long-form work
- repeated-section-kickers detection rule + fixture
- CLI improvements (JSON to stdout, -json/-fast aliases, severity field)
- critique.md: npx impeccable detect --json fix
Harness output dirs refreshed via bun run build. Full test suite (186)
passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* skill: strip gate ceremony; require shape pause; allow compact briefs
The setup gate table and IMPECCABLE_PREFLIGHT banner pushed every
craft run through ritual restatement (PRODUCT.md → original prompt
→ round 1 → round 2 → 70-line "confirmed brief" → critique → summary,
all saying the same thing). Replaced with imperative prose that still
demands the same work but skips the user-facing telemetry.
Specifically:
SKILL.md
- Drop the Setup gate table and IMPECCABLE_PREFLIGHT banner.
- Keep the imperative steps explicitly: load context, identify register
and load brand.md or product.md, AND load the matching command
reference (craft.md / shape.md / etc.) when a sub-command is invoked.
The command-reference step is non-negotiable; without craft.md loaded
the agent skips the shape-and-confirm pause.
craft.md
- Drop the Build Gate / Craft Contract formal sections; replace with
one paragraph stating prerequisites.
- Step 1 explicitly requires ending the response after presenting the
shape output; the user must confirm before any code lands. Allows a
compact 3-5 bullet brief when the prompt + PRODUCT.md already pin
direction (full 10-section structure reserved for genuinely
ambiguous tasks).
- Step 3 image gate skips silently when image generation isn't
natively available; no user-facing announcement.
- Step 6 explicitly legitimizes "first pass clean, shipping" as a
valid endpoint and bans inventing fake defects to demonstrate
iteration.
shape.md
- Cap discovery at 1 round by default; second round only when first
leaves material gaps.
- Adds an "assert-then-confirm, not menu-with-escape" rule: when
PRODUCT.md and the prompt make one option obvious, name it and ask
for confirm or override instead of enumerating "Restrained /
Committed / Or something else?" as a real choice.
- Phase 2 brief has two forms now: compact (default for clear briefs)
and full structured (genuinely ambiguous). Open Questions can't
double as leading-with-Recommend; if you'd write "Recommend: X",
decide X.
- Image gate same as craft.md.
Validated end-to-end with a Haiku skill-on observability run: agent
loads craft.md plus the brief's recommended implementation refs,
pauses for one productive question (accent color, trace fidelity,
CTA), and ships an artifact with zero side-tab violations vs. the
original v1 baseline. Cost trades up modestly for that quality.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* craft.md Step 6: Reading the screenshot is the inspection, not taking it
A v4 eval run took 4 targeted screenshots (hero, mobile, tablet,
query-section) and then never Read any of them back. The agent treated
browser_screenshot itself as "I inspected" and shipped without the
multimodal feedback loop ever closing. Detector caught the resulting
slop (5+ side-tab violations) on adjacent runs that did the same thing.
Step 6 now spells out the pattern explicitly: take the screenshot,
then Read the resulting PNG so its image content enters the
conversation as multimodal input, then critique what you actually see
in the image. With a check: "if your critique could have been written
without looking at the image, you didn't look at the image."
Validated with v5b: agent took 6 screenshots, Read all 6 back, and
shipped with zero detector findings (vs the previous greenfield runs
that hit 1-12 findings each).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* craft + brand: framework foundation, build-pipeline respect, image verification
Three closely-linked additions surfaced by an eval-harness session
investigating why the agent always shipped flat single-file HTML and
zero imagery on greenfield brand briefs.
1. craft.md gains a new Step 0 "Project Foundation" before Shape.
Detects existing framework / component library / icon set and
uses what's there. Greenfield: ask the user via AskUserQuestion
with sensible defaults framed by the brief (Astro for content/
brand sites, SvelteKit/Next/Nuxt for app surfaces, single
index.html only for one-shot demos). Skipping the framework
decision and writing flat HTML "to satisfy the spec" produces
work that reads as a 2018 prototype regardless of visual
quality.
2. craft.md Step 5 production bar gains two bullets:
- Respect the build pipeline. Edit source files and run the
project's `npm run build`; do not write to build/ / dist/ /
.next/ directly with cat/heredoc/Bash redirects. Bypassing
the pipeline skips asset hashing, image optimization, code
splitting, and CSS extraction.
- Verify external image URLs before referencing them. Use an
image-search MCP, web-fetch tool, or browser if available;
guessed photo IDs ship as broken-image placeholders.
3. brand.md "Imagery" section:
- Generalizes the Unsplash URL guidance to "verify URLs
before referencing them" with a hierarchy: image-search MCP
> web-fetch > confidence-restricted manual selection >
fewer photos.
- Tightens the tech/dev-tool exception. Old line "zero imagery
can be correct" gave models a permission slip. New framing
keeps the underlying truth (typography + code + diagrams
primarily carry voice) but raises the floor: imagery still
earns its place when it serves the brief, and skipping it
requires naming the typographic/diagrammatic move that's
carrying the visual weight instead. "Zero imagery is the
failure mode of laziness, not restraint."
Eval-harness corpus that prompted this: 19/19 brand landing tasks
shipped 0 images each, including ones where Opus had taste enough
to break the dev-tool color default lane. The skill needs to teach
both halves of the decision; the harness shouldn't have to nudge.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* detector: body-text-viewport-edge rule + OKLCH/var-resolution + anchor-inherit FP fixes
New rule: body-text-viewport-edge flags body paragraphs that render flush
against the left/right viewport edges (no container padding). Tested via
the new tests/fixtures/antipatterns/body-text-viewport-edge.html fixture
(3 flag cases, 5 pass cases) and the test in detect-antipatterns-browser.
False-positive class fixes — all jsdom-mode only (real browsers resolve
the cascade correctly so these gates stay inert there). Five related
gaps that compounded into ~14× spurious contrast findings on Tailwind v4
pages with OKLCH color tokens:
• OKLCH parser. jsdom returns the literal "oklch(...)" string from
getComputedStyle; the detector now converts to sRGB via Björn
Ottosson's matrices. Handles Tailwind v4's compact minified form
"oklch(21.5%.02 50)" (no space after %).
• var() resolution. resolveBackground + checkElementColors now
accept the existing customPropMap and parse `var(--color-paper)`
etc. as proper RGB via the new parseColorResolved helper.
• bg-color before bg-image. The old order bailed on any gradient
ancestor before checking for a solid background-color underneath,
causing the body's decorative paper-grain gradient to be measured
against instead of the page's actual `bg-paper` cream.
• body/html-level gradient → white fallback. When the only opaque
ancestor we can read is body/html with a gradient overlay (and
jsdom can't decompose `background: var(--paper) gradient` to
extract the solid color), return white instead of falling through
to resolveGradientStops — which was picking up paper-grain noise
colors and using them as the bg.
• Anchor-inherit workaround for jsdom :link UA specificity.
Tailwind v4's preflight declares `a { color: inherit }` (0,0,1).
jsdom's UA stylesheet has `:link { color: blue }` at (0,1,1) and
wins the cascade. Real Chrome wraps :link in :where() (0,0,0) so
the page rule wins. When the page declares the inherit rule AND
we see jsdom's default `rgb(0,0,238)` on an anchor, walk to the
nearest non-anchor ancestor and use its color.
• Alpha-fallback safety gate. When text has alpha<1 AND we couldn't
find an opaque ancestor (effectiveBg null), skip the contrast
finding. Covers any remaining FP class the deeper fixes miss.
Verified end-to-end against an Opus iter-1 artifact on Tailwind v4 with
14 cream/cream FPs + 2 blue-link UA FPs before; 0 findings after, while
the color.html fixture's 12 real low-contrast cases continue to flag
(verified via direct detectHtml calls).
cli/engine/detect-antipatterns-browser.js is the generated browser
distribution — regenerated from .mjs via scripts/build-browser-detector.js
(no manual edits to the generated file).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* craft.md: tighten verbose passages, de-codex Step 6, cut redundancies
Cumulative reduction: 218 → 155 lines (-29%).
Step 0: drop the "Why this matters" paragraph at the end. The body of
Step 0 already makes the framework-pick point; the paragraph just
re-explains it with extra rhetoric.
Step 1: replace the 4-sentence "you must end your response" block with a
single line. The original said the same thing three different ways.
Step 3: trim the conditional / defensive scaffolding (Purpose subsection,
"do not skip because the eventual UI is semantic..." paragraph,
duplicated approval-loop guidance). Mock fidelity inventory preserved.
Step 4: drop the "keep UI text semantic" sentence; it duplicates Step 5's
"Semantic first" rule. The rasterized-vs-semantic decision rule stays.
Step 5: tighten each production-bar bullet to bold-lead + specifics
format. All 15 rules preserved (real content, mock ingredients, semantic
first, spacing/alignment, typography, state coverage, interaction quality,
icon set, build pipeline, image URL verification, optimized imagery,
premium motion, maintainability, technical cleanliness, ask-when-uncertain).
Step 6: rewrite around "look at what you built like a designer would —
your eyes are whatever the harness gives you." Drops Codex-specific
"In Codex, use browser-use" bias. Drops the verbose 3-step Read pattern
(condensed to one sentence). Drops the 1-8 numbered checklist (replaced
by a tight paragraph). Keeps the load-bearing rules: read the PNG,
don't fabricate iteration, mock fidelity reference, exit bar = studio
defensibility.
Step 7: drop the closing "Iterate based on feedback. Good design is
rarely right on the first pass" preachy filler.
All em-dashes converted to semicolons / colons / periods to satisfy
the skill prose validator.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* build: native subagent pipeline + Codex-only asset producer
Adds an agent cross-compile pipeline alongside the existing skill
pipeline. Sources live at skill/agents/*.md; providers that declare
agentFormat (codex-toml, claude-md) emit native subagent files. An
optional providers: <list> field on an agent gates which harnesses
get a copy; default (no field) ships everywhere.
The impeccable-asset-producer agent is opt-in to Codex only. It's
useful for Codex's native image generation path and is untested
elsewhere; Claude has no native image gen anyway.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* brand: inverse-test + cultural-symbol palette guardrail
Two additions to the brand register reference:
- Inverse slop test: describe the page the way a competitor would
describe theirs. If that sentence fits the modal landing page in
the category, restart.
- Palette guardrail: when a cultural-symbol palette is the obvious
pull, reach past it. Let cultural reading come from typography,
imagery, and copy.
Harness mirrors regenerated; some also catch up to the image-
verification paragraph from e3ad2ef that hadn't been re-synced.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* PRODUCT.md: widen audience beyond developers
Designers, product managers, and engineers all use AI coding tools
and want better design output. Keeping the audience narrow to
"frontend and full-stack developers" understates who the skill is
actually for. Also retitles "developer" to "user/builder" in the
purpose statement.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* site + build: bump rule count to 29, strip changelog from detector check
Two changes:
- site/pages/index.astro: three live mentions of "28 rules / checks"
bumped to 29 after the body-text-viewport-edge rule landed in
b9bf496.
- scripts/build.js: the detection-count validator was reading the
unstripped content, so historical counts inside changelog entries
(e.g. "28 rules" from an older release note) were flagging against
the current detector total. The command-count check already strips
the changelog ul; the detection check now does the same.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: align hero-eyebrow-chip fixture with relaxed rule gates
b9bf496 intentionally relaxed two gates in checkHeroEyebrow:
- removed the heading-size ≥ 48px anchor (modern hero h1s use
clamp/vw/var that jsdom can't resolve)
- raised the eyebrow text ceiling from 30 to 60 chars
Two fixture cases that satisfied the negative side of the old gates
now match the rule:
- "Body-Sized Heading Below Eyebrow" — 24px h1 with tracked-caps
label above. Per the rule's stated intent ("a tiny tan label
directly above any h1 is the antipattern regardless of how big
the h1 ends up"), this is a flag.
- "Long Uppercase Sentence Above Hero" — 46-char tracked-caps label
is under the new 60-char ceiling, so still eyebrow-shaped.
Both cases moved from the should-pass column to should-flag, with
case descriptions rewritten to explain the gate they exercise.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Paul Bakaus <paulbakaus@pauls-mbp-3.lan>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(detector): flag italic-serif display heroes and uppercase eyebrow chips (#127)
Two new rules covering the structural tells of late-2025/early-2026
AI-generated marketing pages.
- italic-serif-display: oversized italic serif (Fraunces, Recoleta,
Newsreader, Playfair, Cormorant, Tiempos, ...) as the primary hero
headline. Anchored on h1 (or h2 at >= 48px) with font-style: italic
and a serif primary face.
- hero-eyebrow-chip: uppercase letter-spaced label sitting as the
previousElementSibling of a hero h1 (font-size >= 48px). Bounded
text length 2-30 chars, letter-spacing >= 1.6px, font-size <= 14px.
The pill-chip variant (background + border-radius: 999px) falls out
of the same gates for free.
Both follow the existing icon-tile-stack pattern: pure check function +
browser DOM adapter + jsdom adapter, wired into both element loops.
Two-column fixtures (4 flag / 6 pass each) drive the jsdom tests.
Skill copy in source/skills/impeccable/reference/typography.md and
critique.md calls out the patterns by name. The italic-serif rule's
description acknowledges that editorial/magazine register may legitimately
want the pattern -- judge by context.
Closes#127
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add sandbox gotchas for Codex
* Trim verbose detector skill copy
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Paul Bakaus <paulbakaus@pauls-mbp-3.lan>
SAFE_TAGS skipped <a> and <button> categorically to avoid noise on
inline links and unstyled controls. The blanket skip overshot: a
pill-style anchor or styled button with its own opaque background
was silently exempted from the contrast check, so a "Get started"
button with charcoal text on near-black background (~2:1) read as
fine to both the CLI and the browser overlay.
The bail in checkColors now permits <a> and <button> when they have
their own opaque background AND direct text. Inline links and bare
controls keep skipping. checkElementColorsDOM no longer short-circuits
before reaching checkColors so the exception fires on the browser path.
Adds readOwnBackgroundColor() helper to handle jsdom's missing
shorthand decomposition; falls back to parsing the inline style attr
when getComputedStyle returns empty (real browsers always decompose,
so the fallback is a no-op there).
Fixture gains four cases: pill-style <a> low-contrast (flag),
<button> low-contrast (flag), inline <a> with no own bg (pass),
pill-style <a> with high contrast (pass). Three new tests assert
the right flags fire and the no-regression cases stay clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds Fraunces, Geist (Sans/Mono), Mona Sans, Plus Jakarta Sans,
Space Grotesk, Recoleta, and Instrument Sans to OVERUSED_FONTS.
Brand-domain exceptions for Geist on vercel.com / nextjs.org /
v0.app and Mona Sans on github.com / githubnext.com.
Updates four should-pass fixtures that used the now-flagged faces
as "good examples"; switches to Newsreader + Karla. Adds positive
assertions for Fraunces and Geist.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two detector bugs that produced false positives on sites like uselinkshot.com:
1. The bg-black regex matched Tailwind opacity modifiers (bg-black/3,
hover:bg-black/5) because / is a word boundary. Added negative lookahead.
2. resolveBackground ignored url() background-images, walking past them to
the body's white bg. White text on a dark hero image was flagged as
1.0:1 white-on-white. Now bails on url() images like it does for gradients.
Also: extension build auto-generates dist/extension.zip, version bumps for
CLI (2.1.7) and extension (1.0.1).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jsdom's CSSOM silently drops any border shorthand containing var(),
leaving the computed style empty — which hid the canonical real-world
side-tab pattern (border-left: Npx solid var(--brand)) from the Node
detector path. Real browsers resolve var() natively, so this only
affected the jsdom path.
Add a pre-pass that walks the stylesheets, reads border shorthands off
rule.style (jsdom preserves them there even when it drops them from
cssText), resolves var() against :root custom properties via the
documentElement's computed style, and attaches the result to a per-
element override map. checkElementBorders consults the map whenever
jsdom returned an empty width, or substitutes a resolved color when
jsdom kept a literal var() string. Hex and named colors are normalized
to rgb() so isNeutralColor can classify them correctly — without that,
--line:#e5e7eb slipped through as non-neutral.
Adds four flag cases and three pass cases to modern-color-borders.html
covering shorthand, mixed neutral+colored, border-right, card-shaped
label, neutral-resolving var, thin var, and uniform all-sides var.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix isNeutralColor to handle oklch, oklab, lch, lab, hsl, and hwb
with format-specific chroma/saturation thresholds. jsdom returns
these formats literally, so the previous rgb-only regex caused every
modern-format border color to be silently treated as neutral and
skipped by checkBorders.
- Flip the unknown-format fallback from neutral to colored, so
unrecognized color strings err on the side of detection.
- Introduce a narrower BORDER_SAFE_TAGS set (SAFE_TAGS minus 'label')
used only by the border checks. Card-shaped clickable labels with
thick colored side borders are now detected, while colors, motion,
and nested-card checks continue to skip labels to avoid false
positives on real form labels.
- Add tests/fixtures/antipatterns/modern-color-borders.html with 8
flag cases (oklch x3, oklab, lch, lab, plus 2 label cards) and
10 pass cases (neutrals across formats, plain inline labels,
thin/neutral-bordered labels, colored-on-all-sides).
Reproducer (preop-portal demo): side-tab findings rise from 0 to 12.
Emojis render as multicolor glyphs regardless of CSS \`color\`, so the
text color is irrelevant for contrast calculations. The detector was
flagging emoji icons as low-contrast whenever the surrounding bg/text
colors were close (e.g. an emoji card with text-color set to match
the bg). Adds an isEmojiOnlyText() helper that returns true when the
direct text consists entirely of emoji characters (and zero-width
joiners, variation selectors, skin-tone modifiers, regional
indicators), and skips both gray-on-color and low-contrast checks
when it's true.
Same insight fixes a missed icon-tile-stack detection: many AI-
generated cards use \`<div class="card-icon">⚡</div>\` where the
tile contains the emoji directly as text, not an <svg>/<i> child.
The detector now also recognizes these "inline emoji icon" tiles.
Both fixes are TDD'd: new test cases in color.html (two emoji cards
with matching text/bg colors) and icon-tile-stack.html (the inline
emoji tile pattern). The test suite went from green → red → green
across both rules.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The old rule used a fixed 8px floor on minPad, which produced false
positives on small inline pills (like the homepage's .detection-cmd
at 6px vertical / 14px horizontal on 13px font) and false negatives
on large text (a 24px heading with 8px padding all around passed
the floor but is genuinely too tight for the text size).
The new rule uses two independent axis thresholds that scale with
font-size:
vertical: max(4px, fontSize × 0.3)
horizontal: max(8px, fontSize × 0.5)
The asymmetry reflects typographic reality: line-height already
provides built-in vertical breathing room (the line box is taller
than the cap height), so vertical padding can be tighter than
horizontal. Both thresholds scale with font-size — bigger text
demands proportionally more padding.
Behavior changes
- Small inline pills with line-height-aware padding now pass
(.detection-cmd: V 6 ≥ 4, H 14 ≥ 8). The homepage CSS is unchanged.
- Cramped large text now flags (24px heading with 8px padding fails
H 8 < 12). The old rule missed this entirely.
- All original 8px-floor flag cases still flag — 4px on 14px text
is still 4 < 4.2 vertical, 2px is still cramped, etc.
- Snippet now indicates which axis failed and the specific threshold
for the font-size: "6px vertical padding (need ≥4.8px for 16px text)"
instead of the old "6px padding (need >=8px)".
Fixture
- tests/fixtures/antipatterns/cramped-padding.html is a new
comprehensive side-by-side fixture with 8 flag cases and 12 pass
cases spanning small pills, cards, code blocks, interactive
elements, and big text. Replaces the prior 3-case version.
Test
- tests/detect-antipatterns-browser.test.mjs asserts exactly 8
cramped-padding findings with detailed comments listing each
expected case and which axis fails.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The quality detection rules (line-length, cramped-padding, tight-leading,
tiny-text, justified-text, all-caps-body, wide-tracking, skipped-heading)
were originally added as browser-only and wired only into the overlay
loop. The CLI's jsdom path silently skipped all of them.
Two of the eight rules genuinely need real browser layout
(line-length reads rect.width for chars-per-line; cramped-padding reads
rect.width/height to filter small badges). The other six only need
computed CSS values and pure DOM walks — they can run in jsdom too.
Refactor
- Extract a pure checkQuality(opts) from checkElementQualityDOM, taking
pre-resolved lineHeightPx and letterSpacingPx so each adapter handles
its own unit resolution.
- Add resolveFontSizePx(el, win) — walks the parent chain to compute
effective font-size in pixels, handling px / rem / em / % through
inheritance. Browsers do this automatically in getComputedStyle, but
jsdom returns "0.875rem" verbatim, which broke naive parseFloat math.
- Add resolveLengthPx(value, fontSizePx) — generic CSS length → px
helper used for line-height and letter-spacing in the Node adapter.
- Extract checkPageQualityFromDoc(doc) and add a Node call site so
skipped-heading fires from the CLI too.
- Add checkElementQuality(el, style, tag, window) Node adapter and wire
it into detectHtml's element loop.
Tests
- New tests/detect-antipatterns-browser.test.mjs — Puppeteer-backed
runner that spins up a temporary static server (port 8765, mirrors
the dev server's /fixtures/* and /js/* routes) and uses detectUrl()
to load fixtures in headless Chrome. Asserts the two browser-only
rules (cramped-padding, line-length) that need real layout.
- New tests/fixtures/antipatterns/cramped-padding.html — focused
side-by-side fixture for the cramped-padding rule. Pass column
includes a faithful replica of .detection-cmd from the homepage
(the disputed "small inline pill" case the user is deciding what
to do with). Test asserts 3 findings: 2 from the obvious flag
column + 1 from the disputed pill.
- New tests/fixtures/antipatterns/quality.html — merged side-by-side
replacement for the orphaned quality-should-flag/pass.html files.
Covers all 7 typography-quality rules. The 6 jsdom-compatible rules
are asserted in the jsdom test; line-length stays in the Puppeteer
test.
- Delete the orphaned quality-should-flag.html / quality-should-pass.html.
- Wire the new browser test into bun run test (~2.6s overhead).
Coverage win: the CLI now catches tight-leading, tiny-text,
justified-text, all-caps-body, wide-tracking, and skipped-heading on
real projects, where it previously missed all six.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Each problem-space fixture is now a single file with two columns: left
for cases that should flag, right for cases that should not. Matches the
icon-tile-stack convention and makes browser-based visual review easier.
The pass column proves that no false positives leak from look-alike
patterns next to the real anti-patterns.
Merged (4 pairs → 4 files)
- color-should-{flag,pass}.html → color.html
- motion-should-{flag,pass}.html → motion.html
- glow-should-{flag,pass}.html → glow.html
- layout-should-{flag,pass}.html → layout.html
Left untouched
- should-{flag,pass}.html — used by the CLI smoke tests in
detect-antipatterns.test.js, which need a known-clean fixture for the
exit-code-0 path.
- typography-should-{flag,pass}.html — all three typography rules
(overused-font, single-font, flat-type-hierarchy) are page-level and
fundamentally can't share a page with their pass cases. Loading two
font stacks suppresses single-font; varied sizes suppress flat-type-
hierarchy. Documented in the test file.
Test calibration
- Hardcoded the jsdom finding counts (motion: 2 bounce + 2 layout-
transition; glow: 1 dark-glow). Real browser sees more because
jsdom doesn't fully apply class-based styles, but the pass-column
count is reliably 0. Browser-verified all 4 fixtures show expected
flag counts and zero pass-column false positives.
Fixture chrome fixes
- Sub-section labels (.col h3) now use #64748b instead of #94a3b8 so
the fixture's own UI doesn't trigger low-contrast. glow.html got a
CSS restructure into card-dark/card-light/card-medium variants so
every text/background pairing meets WCAG AA. layout.html's "card
with image" gradient changed from blue→purple to amber→rose so it
doesn't trip ai-color-palette.
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>
Previously checkColors bailed out whenever an ancestor used a gradient
background, since resolveBackground returned null. As a result, gray or
low-contrast text inside any gradient container was completely invisible
to both rules — e.g. the gray heading on bad-contrast.html.
Add a resolveGradientStops fallback that walks parents for gradient
stops and runs contrast against the worst-case stop, plus gray-on-color
when every stop is chromatic. parseGradientColors now also accepts hex
so jsdom fixtures with raw inline gradients work too. Extended the
color-should-flag fixture and tests to cover the gradient case.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Merges the impeccable-detect CLI repo (pbakaus/impeccable-cli@831a6cc)
into this repo. The BSL-1.1 license that motivated the split is gone;
everything is now Apache 2.0.
- Add bin/, src/, detection tests and fixtures from CLI repo
- Merge package.json: name → "impeccable", add bin/exports/files fields
- Internal refs now read from local src/ instead of node_modules/
- Update SPDX headers, NOTICE.md, CLAUDE.md, FAQ, npm README
- Add prepack/postpack scripts for CLI-focused README on npm
- Remove terminal license labels (no longer needed)
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
- 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>
