mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-18 09:06:53 +03:00
codex/release-signed-bundle-cli
89
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Paul Bakaus
|
6443980117 | Improve CLI install prompts | ||
|
Paul Bakaus
|
9b0b63c04f | Prepare CLI 3.0.0, skill 3.6.0, extension 1.2.0 | ||
  
|
672517f76e |
Add automatic design hook install and exceptions (#170)
* docs: add PRD for design detector hook integration Plans a PostToolUse hook for Claude Code and Codex that runs the existing design detector after every relevant file write and feeds findings back to the agent as advisory system-reminder context. No implementation in this commit; covers UX, technical design, build pipeline changes, distribution, coverage tradeoffs, and rollout. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: revise hook PRD with best-practices review Folds in the P0/P1/P2 findings from an online best-practices critique against the official Claude Code and Codex hook references plus 10+ 2026 community guides and similar prior-art tools (claw-hooks, claude-code-hooks-mastery). Key changes: - Exec form everywhere (Codex snippet was shell form), with Windows rationale. - Default timeout dropped from 10s to 5s. - Re-entrancy guard (CLAUDE_HOOK_DEPTH) and per-file edit counter. - Session-scoped finding dedup promoted from open question to v1. - Per-language inline-ignore syntax map (HTML/JSX/CSS/JS). - Hard-skip rules for sensitive paths and generated/lock files. - Honest framing about Claude Code lacking per-plugin hook disable. - Honest framing about Bash-written files being invisible in v1. - Codex Windows-not-supported call-out, feature flag note, trust ceremony detail. - Optional NDJSON audit log via IMPECCABLE_HOOK_LOG. - Findings cap lowered 8 → 5 with attention-budget rationale. - Versioned envelope ([impeccable@1]) on rendered template. - Expanded test plan, decision log, and stdin payload appendix. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(hooks): ship the design detector hook for Claude Code and Codex Implements docs/hooks-prd.md: a PostToolUse hook that runs the impeccable design detector after every Edit/Write/MultiEdit on a UI file and pushes findings into the agent's next-turn context as a short system reminder. Silent on clean files. Never blocks an edit. Why this matters: today, design slop (side-tab borders, gradient text, purple/cyan palettes, bounce easing, etc.) only gets caught when a human notices or someone explicitly runs /impeccable audit. The hook closes the loop at the moment slop is written. What ships in v1 - skill/scripts/hook.mjs: PostToolUse entry. Reads stdin, runs the detector in-process (no `npx impeccable` cold start), emits hookSpecificOutput.additionalContext when fresh findings exist. - skill/scripts/hook-lib.mjs: extracted helpers (config, cache, filter, render, audit log, runHook orchestrator). 100% unit-testable. - skill/scripts/hook-session-start.mjs: SessionStart greeting, gated by a project-scannable probe + 30-day throttle. - skill/scripts/hook-admin.mjs: backs /impeccable hooks on/off/status/ignore-rule/ignore-file/reset. Hardening built in - Re-entrancy guard (IMPECCABLE_HOOK_DEPTH) so the hook can never recursively spawn itself. - Hard-skip regexes for sensitive paths (.env, .pem, id_rsa, secrets, credentials, .git) and generated/lock/build output. These fire before the file is even read; cannot be turned off via config. - Path-traversal check on the inbound file_path. - Session-scoped dedup keyed by (session, file, rule, line) so the same finding never lands in context twice. Prevents the ~12.5K wasted tokens per chatty session called out in the PRD. - Per-(session, file) edit counter with a one-shot suppression notice on the 7th edit, silent after. - Fail-open contract: every error path returns exit 0 with no stdout. Optional NDJSON audit log via IMPECCABLE_HOOK_LOG. Three kill switches (precedence high to low): 1. IMPECCABLE_HOOK_DISABLED env var (1/true/yes/on, case-insensitive) 2. .impeccable/hook.json `enabled: false` 3. /impeccable hooks off slash command (writes the JSON) Inline ignores are language-aware. `// impeccable: ignore <rule>` for JS/TS, `<!-- impeccable: ignore <rule> -->` for HTML/Vue/Svelte/Astro, `{/* impeccable: ignore <rule> */}` for JSX/TSX, `/* impeccable: ignore <rule> */` for CSS. `*` matches any rule. Directive applies to the next non-blank line. Same shape as ESLint, Stylelint, Biome. Build pipeline - scripts/lib/transformers/hooks.js: per-provider hooks.json builders, plus the slim .codex-plugin/plugin.json manifest. - providers.js: emitHooks: 'claude' for claude-code, emitHooks: 'codex' for codex and agents. Codex also emits emitCodexPlugin. - factory.js: emits hooks/hooks.json next to the skills tree. - build.js: syncs hooks/ into harness roots and into the slim plugin/ subtree; writes .codex-plugin/plugin.json. Build is idempotent (verified: 98 staged files unchanged across two runs). Claude Code wiring uses exec form (command + args) and the ${CLAUDE_PLUGIN_ROOT} placeholder. Matcher: Edit|Write|MultiEdit. `if:` glob filters to UI extensions before spawning Node. PostToolUse timeout 5s, SessionStart timeout 3s. Codex wiring uses ${PLUGIN_ROOT} (Codex's native placeholder), matcher Edit|Write|apply_patch, no `if:` analog (the script does the extension filter). macOS and Linux only; hooks are disabled on Windows in current Codex builds. The trust ceremony and feature flag are documented in README.md. Routing - /impeccable hooks lives outside the 23-command router table on purpose: it is plumbing, not a design skill. The hidden routing slot is added to SKILL.md alongside pin/unpin so the LLM knows to dispatch it. The 23-command count and all stale-count validators remain happy. Tests - tests/hook.test.mjs: 38 unit tests covering env parsing, config load + defaults + malformed, cache round-trip + GC, ignoreRules/minSeverity/inline ignores (all four languages), globbing with **/*/{a,b}, render template with cap + clamp + 0-line prefix drop, audit log NDJSON, payload event-name parameterization, re-entrancy, kill switches, sensitive-path + generated-path + traversal skips, allowlist filter, config ignoreFiles, edit counter cycle including the 7th-edit notice, MultiEdit and apply_patch payload shapes, detector throw swallow, malformed stdin, missing file race. - tests/hook-build.test.mjs: 18 integration tests covering hook manifest shape (matcher, timeouts, exec form, if: glob, placeholders), Codex differences (${PLUGIN_ROOT}, no if:, no SessionStart), Codex plugin manifest (no inline hooks field to avoid the duplicate-file error), routing across the hooksJsonFor table, and presence of all three committed artifacts plus the bundled detector the runtime relative-import path depends on. Full suite: 175 bun tests + 186 node tests, all green. Docs - README.md: new "Design hook" section explaining default behavior, per-project / global / inline disable paths, the JSON schema knobs, the audit log debug flag, and the slop / a11y coverage split. - HARNESSES.md: flips the `hooks` row for Codex from No -> Yes (Claude was already Yes), adds a per-harness hook-surface table with the manifest location and matcher each provider uses. Open questions from the PRD intentionally deferred to v2: Bash-write blind spot, effort-aware suppression, Stop-hook session summary, per-rule severity, async hook mode. None block v1. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix Codex hook scanning: apply_patch paths and co-located stylesheets Parse file targets from Codex apply_patch command bodies, co-scan imported and sibling CSS when UI components are edited, drop the git-sweep PostToolUse group, and align Codex SessionStart manifest and trust docs with the official hooks spec. Co-authored-by: Cursor <cursoragent@cursor.com> * Gitignore hook session cache and drop local test HTML Hook dedup/throttle state in .impeccable/hook.cache.json is per-project runtime data like other .impeccable/ sidecars. Remove an untracked bad-nested-flexbox scratch page from site/public/. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix Claude Code hook: drop Edit-only if filter so Write/MultiEdit fire Claude's if permission rule binds to one tool name, so Edit(*.{…}) never spawned the hook on Write or MultiEdit despite the matcher listing them. Extension filtering now lives in hook-lib on both Claude and Codex. Co-authored-by: Cursor <cursoragent@cursor.com> * Surface Cursor design findings via stop-hook followup Replace dropped postToolUse additional_context with afterFileEdit recording and a one-shot stop followup_message so anti-pattern nudges reach the agent. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix design hook packaging and scans * Fix Cursor hook pending bucket fallback * Fix Sass hook scan coverage * Fix Cursor hook review findings * Fix session start dead hook normalization * Fix hook config and relative scan paths * Remove SessionStart design hook * Remove redundant afterFileEdit normalization * Fix Cursor suppression and module style scans * Fix sensitive path hook filter * Fix disabled Cursor stop hook emission * Refresh hook harness artifacts * Fix Cursor hook manifest install * Add hook ignore-value support * Ignore hook runtime files locally * Fix Codex plugin hook packaging * fix: address PR review bot findings Block numeric hook depth counters from re-entering. Avoid following stylesheet imports from traversal-looking hook targets. * fix: gate ignore-value suggestions by supported rules Only render exact ignore-value commands when the same finding can be suppressed by ignoreValues. * Package Codex plugin as hook-only * Remove Codex plugin packaging * Recover hook install probe plumbing * Remove Codex hook packaging follow-up doc * Remove extra hook docs and skill wording changes * Install real design hooks via skills CLI * Add provider hook smoke runner * Fix Cursor hook delivery with preToolUse gate * Simplify Cursor hook install to preToolUse * Clarify confirmed hook exceptions * Persist hook ignores in shared config * Guard font hook exceptions * Fix hook install after main rebase * Fix hook scan target handling * fix: address hook review findings * Address hook review feedback * Stabilize DeepSeek insert live fixture * Fix Cursor hook Python shell write bypass --------- Co-authored-by: Cursor <cursoragent@cursor.com> |
||
|
Paul BakausandGitHub
|
e3e22007a9 |
[codex] Improve detector false positive handling (#232)
* Improve detector false positive handling * Register docs integrity test * Fix clipped overflow decorative skip |
||
|
Abdul WahabandGitHub
|
4e251061b8 | Fix sr-only text overflow false positive (#197) | ||
|
9ffd3211d5 |
Neo Kinpaku design system + Live Mode v3 (#169)
* Add neo kinpaku design system page * skill: rip out baked-in category recipes and saturated-default motion tropes Programmatic bias mining (impeccable-evals) traced four major defects back to specific lines in this skill that contradicted SKILL.md's own first-order-reflex warning: - brand.md "Pairing and voice" prescribed four category→aesthetic recipes (editorial → serif+sans, tech/dev/fintech → tight tracking, consumer/food/travel → script/display serif, creative → rule-break). These directly drove OpenAI's 76% extreme-negative letter-spacing on tech briefs and Anthropic/Google's 28-34% italic-serif-display slop on editorial/food briefs. Replaced with one sentence: the shape depends on the brand, not on the brand's category. - brand.md "Brand permissions" had "Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero." — a four-for-one slop driver behind 97% OpenAI comically-large H1, 42% bad-SVG illustration, and the editorial-italic slop. Deleted outright. - typeset.md and teach.md repeated the same category recipes; trimmed to the principle without the recipe. - SKILL.md Typography: added a hard hero-H1 ceiling (clamp() max ≤ 6rem ≈ 96px), with a <codex> block to make it explicit since OpenAI over-indexes here (97% ≥128px vs 24% for Anthropic). - animate.md, bolder.md, brand.md: removed "staggered reveals" and "scroll-triggered transitions" as the prescribed default ambitious motion. By 2026 that's the saturated AI tell, not a choreography. Reserved stagger for legitimate list-sibling rhythm. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: anti-cream + codex-specific defect bans + universal slop bans Second pass after measuring more biases against the eval corpus. - SKILL.md Color: explicit "cream/sand/beige body bg is the saturated AI default of 2026" rule. Tone down the "tint every neutral" line so it doesn't read as "default to warm-tinted near-white" (which OpenAI hits at 74% and Anthropic at 31%-47%). - SKILL.md Absolute bans: add universal bans for two slop patterns detected at 55-95% across providers — tiny uppercase tracked eyebrow above every section (the 2023-era kicker that's now AI grammar) and numbered section markers (01/02/03). Also explicit "text that overflows its container is the universal defect on tablet/mobile." - SKILL.md Absolute bans → <codex> block: ban the GPT-specific defects Paul annotated repeatedly — `border:1px solid` + soft-wide-shadow (≥16px blur) "ghost cards", `border-radius:32px+` over-rounding, hand-drawn/sketchy SVG illustrations (loose-sketch / *-sketch classes, feTurbulence paper-grain filters), repeating-linear-gradient stripes, "X theater" AI-slop copy phrases. - SKILL.md Motion → <gemini> block: the image :hover transform tell (38% Google skill-on rate). Hover effects on images add no info; the image isn't an action target. Animate card chrome, not the image. - SKILL.md Typography: hard display letter-spacing floor ≥-0.04em (OpenAI defaults to -0.075em → cramped). Existing hero ceiling <codex> block extended with the letter-spacing rule. - codex.md Step A example: stop seeding "warm-grounded (deep oxblood + cream)" as the warm-palette template, which primes the cream default. - colorize.md Tinted backgrounds: stop printing the literal cream recipe `oklch(97% 0.01 60)`; replace with brand-anchored guidance. - document.md examples: warm-ash-cream → cool-paper so the example doesn't seed cream as the canonical neutral example. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: universal anti-slop bans + contrast/font-count/all-caps-body rules Third pass after measuring the rest of the cross-provider matrix: - Color: explicit "Verify contrast" rule. Low-contrast text fires at 68% across all providers skill-on (90+% off). The most common failure is muted gray body on a tinted near-white; light-gray-for- elegance is named as the single biggest cause of unreadable AI pages. - Typography: max-3-font-families rule. Overused-fonts (>4 families) fires at 28% Anthropic / 36% Google / 0% OpenAI skill-on; >50% off. Also: universal "no all-caps body copy" (moved from brand-only ban to Shared design laws since product-register also overuses caps). - Copy: anti-aphoristic-cadence ban targets Anthropic's signature "X. No Y." / "X. Just Y." voice (63% skill-on copy-slop rate, 77% off — the worst rate in the matrix). Once-is-voice / three-or-more- is-tell framing per the runner's copy-slop detector. - Copy: anti-SaaS-buzzword-string ban with the literal phrase list the detector watches for (streamline/empower/supercharge, trusted- by-leading, best-in-class/enterprise-grade/cutting-edge, etc). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: strengthen anti-cream rule across full warm-neutral band Smoke validation showed the cream fix worked for Google + OpenAI but Anthropic Sonnet italian-restaurant still shipped `--paper: oklch(90% .018 88)` — cream just outside the L≥95% band the rule cited. Broaden the rule: - Band: OKLCH L 0.84-0.97, C < 0.06, hue 40-100 (was 95-97% / 60-95). - Name the token-name tells explicitly (paper / cream / sand / bone / flour / linen / parchment / wheat / biscuit / ivory) — the model defaults to one of these regardless of what hex it lands on. - Call out the specific brief patterns ("warm, traditional, family- coastal-Italian" / "editorial-restraint") that the model translates into cream by reflex. Then provide three explicit non-cream options: saturated brand color, true off-white at C=0, or darker mid-tone. Warmth in the brand is carried by accent + typography + imagery, not by body bg. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v3.2.0: skill bias-fix release Bumps version from 3.1.1 to mark the four-commit skill cleanup that rips out baked-in category recipes (brand.md), saturated-default motion tropes (staggered reveals everywhere), the cream/sand body-bg AI tell, codex-specific defects (1px+wide-shadow, over-rounding, hand-drawn SVGs, stripes, X-theater copy), the extreme-letter-spacing default, and universal slop bans (all-caps eyebrow on every section, numbered-section markers, all-caps body, font-family-count > 3, aphoristic copy cadence, SaaS buzzword strings). Plus a hard hero-H1 ceiling (clamp() ≤6rem) and a Gemini-specific image:hover transform block. Validated against ~190 post-fix samples — see impeccable-evals biases tab for per-provider deltas. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * drop "no pure black/white" rule entirely The rule was contested in the design world and causing more damage than good — pushing every page into the tinted-near-white default which is the cream/sand AI tell we already explicitly ban elsewhere. Vercel, SVKMS, Brutalist sites, et al. use pure black/white successfully; the skill shouldn't second-guess that. Skill markdown deletions: - SKILL.md Color: drop the "Never use #000 or #fff" bullet. - color-and-contrast.md: drop the "Never Use Pure Gray or Pure Black" subsection, the "Never pure black" table-row prescription, and the "Avoid: Using pure black for large areas" bullet. - colorize.md: drop the "NEVER use pure black or pure white for large areas" bullet. - polish.md: drop the "Tinted neutrals: No pure gray or pure black" half of the bullet (the gray-on-color bullet survives). Detector code (cli/engine): - registry/antipatterns.mjs: remove the `pure-black-white` entry. - rules/checks.mjs: remove the three `findings.push({ id: 'pure-black-white', ... })` emit points (inline #000 bg, Tailwind bg-black class, plain-HTML scan path). - engines/regex/detect-text.mjs: remove the two pure-black-white regex rules (CSS `background: #000…` + Tailwind `bg-black`). - detect-antipatterns-browser.js: regenerated via scripts/build-browser-detector.js. Tests: - detect-antipatterns-fixtures.test.mjs: invert the assertion that pure-black-white fires; expect it to NOT fire post-v3.2. Drop the Tailwind bg-black-opacity edge-case test (no longer relevant). - detect-antipatterns.test.js: drop the standalone "detects pure- black-white in styled-components" test and remove pure-black-white from the multi-detector assertions in PricingCard, globals.css, and GlobalStyle.tsx tests. 166 bun tests pass; 24 node fixture tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: strip example patterns from copy rules, strengthen gemini block v3.2 rerun validation surfaced two issues: 1. Copy-slop detector fires more on Gemini under v3.2 (48% → 84%) than under no-skill baseline. Root cause: the anti-aphoristic-cadence rule printed the literal "X. No Y." / "X. Just Y." patterns as examples, and Gemini imitated them as the recommended voice. Same recipe-becomes- bias trap we hit with brand.md:116's "Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines" enumeration. Fix: describe the cadence as a rhythm ("serious statement, then punchy short negation") without printing literal patterns. Buzzword list trimmed to a single inline phrase family rather than quoted strings. 2. Gemini image:hover transform Gemini-tell hadn't dropped (31% off → 32% v3.2). Strengthen the <gemini> block: explicit "Never animate <img> elements on hover", call out the Tailwind group-hover:scale / group-hover:rotate / group-hover:translate parent-hover patterns by name (Gemini was reaching for these via Tailwind even though the prior text talked about :hover on the image directly). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: simplify context loading and inline register directive Replaces load-context.mjs's JSON output with a tight markdown block from the renamed context.mjs. The script now extracts PRODUCT.md's `## Register` field and appends a `NEXT STEP:` directive naming the matching reference (brand.md / product.md), which moved Gemini from skipping the register load entirely to honoring it. Drops the `.impeccable.md` auto-migration; makes IMPECCABLE_CONTEXT_DIR a lazy escape hatch consulted only when the default paths come up empty. Setup is now four bullets in one list. The DESIGN.md nudge is gone; in its place, a "familiarize with the existing design system" step that calls out CSS / tokens / running app as authoritative sources alongside DESIGN.md. The standalone `### Register` H3 stays for the cascade rules (task cue → surface → register field). New LLM-backed test suite at tests/skill-behavior/ runs five scenarios against claude-haiku-4-5, gpt-5.4-mini, and gemini-3.1-flash-lite via Vercel AI SDK. Captures real tool traces, asserts on context.mjs calls, brand.md loads, and teach.md fallback. Skips cleanly when API keys are unset. 13-14/15 pass; only stable failure is the v3.2.0-era gpt-mini S4 "don't re-run" regression. Adds @ai-sdk/google as devDep and the test:skill-behavior npm script. Touches em-dashes in skill/SKILL.md and four reference files so `bun run build:skills` passes its skill-prose validator. teach.md and document.md drop their "re-run the loader to refresh session cache" steps since the agent's own write is now the freshest source. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: merge orphan reference files into command sub-skills + inline S-tier invariants Two related restructurings: 1. SKILL.md now carries the cross-domain invariants that catch defects in any project (contrast/placeholder/gray-on-color, similar-font pairing, text-wrap, tabular-nums, centered-stack default, Flex/Grid choice, auto-fit grids, semantic z-index, reduced motion, stagger vs section-fade, premium motion materials, focus-visible, placeholders-aren't-labels, dropdown overflow trap, button/link copy). Greenfield-only rules (theme picking, color strategy, tinted neutrals) live under "New projects only". 2. Reference files merged into their command counterparts: - spatial-design.md -> layout.md - motion-design.md -> animate.md - color-and-contrast.md -> colorize.md - responsive-design.md -> adapt.md - ux-writing.md -> clarify.md - typography.md -> typeset.md (bolder.md redirected) - cognitive-load.md + heuristics-scoring.md + personas.md -> critique.md craft.md and shape.md "load references" lists updated to new file homes. interaction-design.md stays standalone (no 1:1 command verb). Net: 36 -> 27 reference files. Same content, fewer files, no orphaned reference loaded only from craft.md. Also extends the routing rules: if the user's first word doesn't match a command but the intent clearly maps to one, load that command's reference and proceed as if invoked. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: add sub-command + existing-project scenarios; move sub-command load to step 2 Adds three new LLM-backed scenarios to tests/skill-behavior: - S6: `/impeccable polish` → loads polish.md - S7: `/impeccable audit` → loads audit.md - S8: existing SvelteKit project (PRODUCT.md + DESIGN.md + src/app.css + src/lib/components/*.svelte + src/routes/+page.svelte) → agent reads at least one project code file to understand the existing design system S6/S7 surface a real model-floor: gpt-5.4-mini reads brand.md, reads the target index.html, and just does the polish/audit without ever loading the sub-command reference. Stronger SKILL.md wording didn't move it. Captured in the README baseline as a known weakness. Claude and Gemini honor the load reliably. To fix Gemini on S6/S7, sub-command reference loading is now Setup step 2 (right after context.mjs), not step 4 — placing it before the model gets focused on "doing the work". Step 3 (design-system familiarization) is tightened to require at least one project code read even when a sub-command reference loads in step 2, so Claude doesn't laser-focus on the sub-command flow and skip the broader exploration. Two new fixtures: MINIMAL_LANDING_HTML (a tiny static landing page for S6/S7) and SVELTE_PROJECT_FILES (a minimal SvelteKit scaffold with tokens, components, and a routes/+page.svelte for S8). Both designed to look real enough that agents treat them as production code. Suite is now 24 tests across three providers; baseline is 21-22/24, with the stable failures being gpt-5.4-mini scenarios 6 and 7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: add reveal-animation safety rule (must enhance, not gate visibility) Class-triggered visibility transitions pause on hidden tabs and headless renderers. The italian-restaurant smoke produced a build where 2 sections shipped opacity:0 because the CSS transition never advanced past currentTime=0 (timeline paused). Added one-liner under Motion to prevent the antipattern: reveals must enhance an already-visible default, never gate content visibility on a class-triggered transition. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: restore prescriptive cream/sand/beige paragraph Bisection across 5 historical skill commits on Gemini 3.5 flash fast lane n=3 found that |
||
|
Paul BakausandGitHub
|
e1d3ea0b6f |
Detector architecture v2: static engine, benchmarks, lab, and visual contrast (#156)
* Add detector benchmark lab and visual contrast fallback * Expand visual contrast fixture coverage * Add browser visual contrast fallback * Show visual contrast overlays in detector lab * Fix detector lab short viewport layout * Fix detector lab visual overlays * Add visual contrast to browser scan overlays * Avoid browser scroll jumps during visual contrast scans * Resolve visual contrast lazily on scroll * Refresh detector lab visual counts lazily * Update pnpm lockfile for static parser deps * Address Bugbot detector API comments * Report extension visual contrast errors * Refactor detector into engine modules * Address Bugbot detector comments * Fix latest Bugbot detector notes * Fix visual contrast fixture labels * Refine detector lab fixtures * Fix stale detector overlay references * Fix detector lab fixture URLs * Fix typography lab fixture highlights * Fix typography lab page-level signal * Fix visual overlay lifecycle cleanup * Remove dead spotlight timer cleanup * Make browser async APIs reject consistently |
||
|
e7e923c4ef |
Skill + craft cleanup, detector hardening, native subagent pipeline (#152)
* 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 |
||
|
444e4acad3 |
Detector: add italic-serif display headline + hero eyebrow chip rules (#127) (#129)
* 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> |
||
|
Paul BakausandClaude Opus 4.7
|
64c6df216b |
fix(detector): contrast checks run on styled <a> and <button> (v1.0.3)
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> |
||
|
Paul BakausandClaude Opus 4.7
|
b5c203f38a |
feat(detector): flag Fraunces, Geist, and the new monoculture fonts
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> |
||
|
Paul BakausandClaude Opus 4.6
|
00d485659a |
Fix false positives: bg-black opacity modifiers and background-image contrast
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> |
||
|
Paul BakausandClaude Opus 4.6
|
6e12f215c8 |
Detect side-tab borders built with CSS variables
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> |
||
|
Paul Bakaus
|
30d1e06a75 |
Detect side-tab borders on modern color formats and label cards
- 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. |
||
|
Paul BakausandClaude Opus 4.6
|
06ef4f3c14 |
Handle emoji-only text in contrast and icon-tile detection
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> |
||
|
Paul BakausandClaude Opus 4.6
|
3569085cea |
Make cramped-padding rule asymmetric and proportional to font-size
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> |
||
|
Paul BakausandClaude Opus 4.6
|
5bc5ece1ab |
Wire quality rules into the CLI and add Puppeteer fixture tests
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> |
||
|
Paul BakausandClaude Opus 4.6
|
8b93dfad5e |
Merge color/motion/glow/layout fixture pairs into side-by-side files
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>
|
||
|
Paul BakausandClaude Opus 4.6
|
e1032b7285 |
Add icon-tile-stack rule and cross-validate engine against skill
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> |
||
|
Paul BakausandClaude Opus 4.6
|
b391485e16 |
Detect low-contrast and gray text over gradient backgrounds
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> |
||
|
Paul BakausandClaude Opus 4.6
|
3c9cc86061 |
Merge CLI into main repo, switch everything to Apache 2.0
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> |
||
|
Paul BakausandClaude Opus 4.6
|
3974789903 |
Remove detection engine files, now in @impeccable/detect package
Remove all detection engine source, tests, fixtures, and build scripts that have been extracted to the @impeccable/detect package (BSL-1.1). - Delete source/skills/critique/scripts/ (detect-antipatterns.mjs, browser.js) - Delete scripts/build-browser-detector.js - Delete tests/detect-antipatterns*.test.* and tests/fixtures/antipatterns/ - Delete .claude/skills/critique/scripts/detect-antipatterns-browser.js - Update scripts/build.js to read detection count from npm package - Update server/index.js to serve browser script from npm package - Update CLAUDE.md to reference @impeccable/detect - Update package.json test script (detection tests removed) - Update .gitignore (remove obsolete browser script entry) - Rebuild all provider skill distributions with updated critique skill Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Paul BakausandClaude Opus 4.6
|
8d05411c3e |
Harden CLI detection for framework files, multi-file projects, and dev servers
Tier 1: Add Vue/Svelte <style> block extraction and CSS-in-JS template literal detection (styled-components, emotion) so anti-patterns inside framework-specific syntax are caught. Enable multi-line context for CSS files so cross-line patterns like gradient-text are detected. Tier 2: Build a lightweight import graph when scanning directories. Findings are annotated with importedBy context (e.g. "imported by App.tsx") in both human and JSON output. Tier 3: Detect framework config files (Next.js, Vite, SvelteKit, Nuxt, Astro, Angular, Remix), probe the dev server port with HTTP fingerprinting to distinguish the expected framework from unrelated services, and suggest URL-based scanning for more accurate results. Adds realistic Next.js project fixtures (Tailwind, CSS Modules, styled-components) plus Vue, Svelte, JSX, and CSS-in-JS unit fixtures. 158 tests, 356 assertions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
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> |
||
|
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> |
||
|
Paul BakausandClaude Opus 4.6
|
2201d86af0 |
Add test fixture for short text in wide containers, document test runner
- Add short-text-in-wide-container examples to quality-should-pass fixture - Add Testing section to CLAUDE.md - Revert unnecessary line-length estimatedLines guard (textLen > 80 already sufficient) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
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> |
||
|
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> |
||
|
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> |
||
|
Paul BakausandClaude Opus 4.6
|
d8803c8151 |
Fix browser script serving: run build after skill sync, serve via /js/
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> |
||
|
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> |
||
|
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> |
||
|
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>
|
||
|
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> |
||
|
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> |
||
|
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> |
||
|
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> |
||
|
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> |
||
|
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> |