skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-14 15:16:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

Neo Kinpaku design system + Live Mode v3 (#169)

Browse Source 
* 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 0cf2debd was the peak quality state. The regression
between 0cf2debd and HEAD came from simplifying the long anti-cream
paragraph into a one-liner.

Restoring the paragraph (with em-dashes replaced by parens to satisfy
prose lint) recovers ~0.22pt average on Gemini vs HEAD, with the
largest gains on:
- 09-luxury-hotel: +0.50 (restores editorial drama in photo-led briefs)
- 10-food-magazine: +0.67
- 03-italian-restaurant: +0.51

The paragraph's load-bearing parts are the (a)(b)(c) alternatives that
give the model actionable replacements for cream-tinted body bg
("saturated brand color as body", "true off-white at chroma 0",
"darker mid-tone tinted neutral"). Without them, the one-line warning
left the model with no concrete alternative.

Cross-provider validation showed the pattern matches historical
behavior: Gemini benefits from prescriptive scaffold (+0.12 over off),
Sonnet is roughly neutral (+0.01), GPT-5.5 slightly regresses (-0.11
matching the v3.1.0 pattern of -0.11). The skill has never been
uniformly better than skill-off across providers; this is the closest
achievable state without provider-specific rework.

The structural improvements from the prior restructure stay (file
merges, S-tier inlines, routing rule extension, reveal-animation
safety rule).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: teach CLAUDE.md / AGENTS.md / DEVELOP.md about the skill-behavior tests

Adds the `bun run test:skill-behavior` script to the test commands lists
in all three docs. CLAUDE.md gets a full `### Skill-behavior tests`
subsection paralleling the existing Live-mode E2E one: how the suite
works (inlines source SKILL.md, scoped tools, asserts on the trace),
which providers it always runs (claude-haiku-4-5, gpt-5.4-mini,
gemini-3.1-flash-lite — all three every run), the eight scenarios, the
baseline (21-22/24 with stable gpt-mini sub-command-routing failures),
auth via repo-root `.env`, and how to add a scenario.

AGENTS.md gets the one-liner plus a paragraph in Testing Guidelines that
points contributors at the suite for Setup-touching edits (SKILL.md
Setup section, context.mjs, teach.md, document.md, register / sub-command
refs).

DEVELOP.md gets a short Testing section that didn't exist before, plus a
nudge in the "Test across providers" bullet pointing at the new suite as
the automated way to do that.

No code changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* detector: add 5 new antipatterns (em-dash-overuse, broken-image, marketing-buzzword, numbered-section-markers, aphoristic-cadence)

Consolidates eval-side detection logic into the canonical impeccable
detector. Before this change, the eval harness had its own duplicate
implementations of em-dash, copy-slop, and broken-image checks. They
now live alongside the existing 28 antipatterns in the impeccable
registry, available to the CLI, browser extension, critique skill,
and eval (via the existing slop grader child-process call).

New antipatterns:
- em-dash-overuse: 5+ em-dashes in body text content (threshold
  permits legitimate prose use of em-dash; only triggers on AI
  cadence-level density)
- broken-image: <img> with empty src, missing src, or src="#"
- marketing-buzzword: SaaS phrase list (streamline / empower /
  supercharge / enterprise-grade / cutting-edge / etc)
- numbered-section-markers: repeated 01 / 02 / 03 sequence as
  section labels — the AI editorial scaffold one tier deeper than
  tracked eyebrow chips
- aphoristic-cadence: 3+ manufactured-contrast ("Not a X. A Y.")
  or short-rebuttal ("Sentence. No clause." / "Sentence. Just
  clause.") constructions in body text

Engine wiring:
- broken-image runs as a static-html element rule (selector: img)
  and a fallback regex matcher (for non-HTML files)
- em-dash / buzzword / numbered / aphoristic run as regex
  page-analyzers, factored into a new runTextContentAnalyzers()
  helper that both detectText (non-HTML) and detectHtml (HTML)
  call, so .html files get the same coverage as .css/.tsx

Tests: 166 detector + 12 browser + 24 fixture all pass.
Browser detector rebuilt (162.7 KB).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* skill: drop unvalidated anti-centering rule; add image-led hero carve-out

The anti-centering rule ("Don't default to centering everything") was
added without empirical support. We have a detector for it
(everything-centered, threshold ≥70%) that fires on 0 / 998 samples
in the corpus — never validated, never useful.

Meanwhile the rule was almost certainly responsible for collapsing
Gemini 3.5 flash's luxury-hotel skill-on output from the canonical
"full-bleed photo + centered overlay headline" cinematic hero (the
shape skill-off Gemini chooses 67% of the time) to a 50/50
magazine grid (full-bleed rate drops to 18% under skill-on, -49pp).

Changes:
- skill/SKILL.md #### Layout: drop "Don't default to centering..."
- skill/reference/brand.md ## Layout: drop the same rule; replace
  with a positive carve-out — image-led briefs (hotels, restaurants,
  magazines, photography) often want full-bleed hero with overlaid
  menu and centered headline; let the photograph be the design
- skill/reference/layout.md: drop the assessment question and the
  "asymmetric breaks centered-content pattern" framing

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Apply neo-kinpaku design system and improve live picker UX

Restyle the live picker to match the site kinpaku kit, persist pick mode
in localStorage, fix DESIGN.md color swatches in the parser, and land the
neo-kinpaku site refresh with new tokens, assets, palette script, and
detector rules.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add live Steer end-to-end: poll protocol, browser UI, and E2E harness.

Wire page-level Steer through the live server and agent poll loop with steer_done
unlock semantics, extend live.md for agents, and add smoke tests with LLM
handleSteer plus recovery for hidden heroes, HMR lag, and dev-tool overlays.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add experimental live-poll --stream mode; keep one-shot default for Cursor.

Stream keeps one process alive with ack-aware resume, but live.md documents
that Cursor should stay on one-shot background notify after testing showed
~5s pickup vs sub-second on exit-based notify.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Sync harness output and fix build validators for poll stream release.

Regenerate provider skills after live-poll --stream work, update homepage
detection counts to 41, and replace em dashes in site/skill copy so
bun run build passes prose and count checks.

Co-authored-by: Cursor <cursoragent@cursor.com>

* homepage: add testimonials marquee section

A two-row testimonial marquee on a tinted graphite plinth, sitting
between the hero and the slop teaser.

29 testimonials sourced via api.fxtwitter.com (lightly cleaned: leading
@-mention reply targets stripped, trailing self-links removed). Avatars
downloaded into site/public/assets/testimonials/ so they're served
locally. Quote order curated for impact — both rows lead with the
punchiest quotes (Ben Davis spotlight, "Impeccable > Claude design",
"THIS. This shit works.", "Uninstall whatever frontend skill you're
using.") so the first viewport is loaded with the most memorable
testimonials.

Engineering notes:
- Section uses width:100vw + margin-left:calc(50% - 50vw) to escape
  main.site-content's max-width + side padding (cards now clip cleanly
  at the actual viewport edges).
- Marquee runs at 110s linear infinite. Both rows share the same
  duration so on-screen speeds match; track is doubled so the loop
  back to 0 reads as continuous.
- Hero min-height reduced from 100svh to calc(100svh - 115px) so the
  dotted divider and top of row A peek above the fold on landing,
  signalling the section is there.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* homepage: keep the hero demo clear of the fixed header on short viewports

The hero centers its content in the full viewport (the site header is a fixed
overlay), so on shorter screens the tall Live Mode demo tucked under the nav.
Raise the hero's top padding above the 97px header (113px wide, 108/92px when
stacked) so content always pins below the header while still centering on tall
viewports, and cap the demo frame to the viewport so the whole demo stays on
screen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add steer voice input and refine processing animation.

Wire Web Speech API on the Steer mic with auto-submit, block Cursor's preview browser with a clear message, and replace truncated "Working" text with a dots-only processing state.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add agent poll connectivity indicator and tighten global bar spacing.

Surface poller state on the Impeccable mark via SSE and /status, with an instant disconnected tooltip, steer timeout failsafe, and matched brand/chat section gaps.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix steer focus to allow page text selection without losing type-to-steer.

Blur the hidden steer input on page interaction, pause refocus during selection gestures, and reschedule focus recovery after clicks and cleared selections.

Co-authored-by: Cursor <cursoragent@cursor.com>

* site: rework "Design in production" section glyphs and audience band

Put the three how-it-works steps back into thin-line cards and drop the
overused browser-chrome bars from each glyph. Redraw the step 2 and 3
visuals to mirror the real Live Mode UI: step 2 shows the on-canvas pick
outline with an attached comment bubble, step 3 shows the floating
contextual accept bar plus the source-write confirmation. Re-treat the
audience tiles as verdigris-lined text (no card box) under a "Who it's
for" eyebrow, so each role reads as distinct from the gold step band.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add live insert mode with HMR-safe placeholder recovery.

Ships insert picking, scaffold helpers, variant cycling fixes for hidden
variants, and placeholder snapshot/recreation so Astro HMR does not drop
the wait-state box or re-anchor to the hero container.

Co-authored-by: Cursor <cursoragent@cursor.com>

* site: mobile pass — hamburger nav + designing hero overflow fix

The header was rendering inline nav links + GitHub button that overflowed
narrow viewports (~363px). Pre-existing display:none hacks hid Designing
and Live to make the row fit, but those items still belonged in the menu.

Header.astro: added a hamburger toggle button + inline script. The right
cluster (nav + GitHub) becomes a collapsible drawer below the header on
mobile, with data-nav-open driving the open/closed state and animating
the two-line glyph into an X.

kinpaku-kit.css: hamburger button (kinpaku-bordered glyph), mobile drawer
panel (solid lacquer-deep bg, hairline separators between rows, full-width
tappable rows), and overrides for the older sub-pages.css mobile rules
(horizontal-scroll mask on the nav, hidden [data-nav="home"] item, hidden
GitHub star label) — all redundant now that the drawer surfaces everything.

home-kinpaku.css: dropped the @media (max-width: 560px) block that hid
Designing / Live / GitHub. The drawer pattern shows them all.

designing-kinpaku.css: hero h1 "Designing with Impeccable" was overflowing
at narrow viewports. Three fixes:
  - grid-template-columns 1fr → minmax(0, 1fr) so the column shrinks to
    fit container instead of growing to "Impeccable"'s 472px intrinsic
    min-content width.
  - mobile h1 size override (clamp(2.2rem, 11vw, 3rem) at <=480px) since
    the display token's 3.4rem minimum is sized for desktop hero impact.
  - hide the decorative loop-wheel SVG below 600px (was overflowing 22px
    past the right edge).

Verified clean at both 363px and 403px viewports across /, /docs,
/docs/animate, /slop, /designing, /live-mode. scrollWidth matches viewport
width on every page (no horizontal scroll).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* detector: refine new rules + run provider tells in browser env

Follow-up to the detector port (rules landed in 7648af00):
- oversized-h1: flag long headlines set at display size, not punchy
  one/two-word heroes (length, not size alone, is the tell)
- provider tells (--gpt/--gemini) now always run in a real browser env
  (detector page, live overlay, extension); gating is a CLI-output
  concern only, applied in the Node engine return paths
- move theater-slop-phrase into checkHtmlPatterns so it runs in the
  bundled browser path, not just CLI/static (browser bundle excludes
  detect-text.mjs)
- hero-eyebrow-chip overlay highlights the eyebrow, not the heading
- gemini-tells fixture: data-URI images so the hover-zoom renders
- rebuild browser bundle

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: migrate /detector lab to neo-kinpaku design system

Rebuild the detector lab tool shell on --ks-* tokens (lacquer ground,
gold hairlines, champagne/mono type) instead of the legacy warm-paper
palette. Swap the "/" placeholder for the real carved-tile brand lockup,
restyle the toolbar actions as kinpaku primary/secondary buttons, and
recolor the finding overlay from off-brand magenta to vermilion.

Update the global theme-color from #fafafa to #010101 (the sRGB render
of the lacquer ground) so the browser chrome matches the dark site.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Homepage: hero finalist, compact live demo, real picker bar.

Switch the hero to m-01-v2-01, tighten the in-hero demo layout, and replace
the marketing gbar with a shared LiveDemoGbar that mirrors live-browser.js.
Size the bar with max-content so controls are not clipped inside the capsule.

Co-authored-by: Cursor <cursoragent@cursor.com>

* site: migrate /cases/neo-mirai to neo-kinpaku design system

Rebuild the Neo Mirai case-study page on --ks-* tokens: lacquer ground
(drops the off-brand magenta radial spotlight), Alumni Sans Pinstripe
display headings instead of the banned italic serif, gold eyebrow/labels,
gold hairline image frames, kinpaku primary/secondary buttons, and a
lacquer-deep command panel with a gold-bordered code block.

Opt .neon-case-page into the shared kinpaku site-header/footer chrome in
kinpaku-kit.css (per the "add new kinpaku pages to the selector list"
note) so the global header and footer go dark to match the page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: consolidate kinpaku header+footer into one reusable .kinpaku-chrome class

The dark header/footer were not a reusable unit: the header was scoped to
a per-page selector list, the github star pill was home-only, and the
default footer was copy-pasted into four page stylesheets. Pages not on
the lists (like /cases/neo-mirai) fell back to the legacy light chrome.

Collapse all of it into one `.kinpaku-chrome` block in kinpaku-kit.css —
header, github pill, and default footer — and opt every kinpaku page in
via a single body class. Delete the four duplicated per-page footer
blocks and the home-only github pill. The home page keeps its textured
verdigris footer as a deliberate override, raised to body.home-kinpaku
specificity so it wins regardless of import order. Genuinely light pages
(privacy, tutorials) just omit the class.

Fixes on /cases/neo-mirai: footer and github star now render dark/kinpaku
(were legacy-light), and the content sections are wrapped in the .neon-case
container so they sit in header-aligned gutters instead of bleeding to the
viewport edge.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: migrate privacy + tutorials to kinpaku via a reusable surface class

These were the last two light pages. Rather than rewrite their per-rule
styling, add a reusable .kinpaku-surface class that remaps the legacy
--color-* / --font-* tokens to kinpaku values at the body scope, so the
existing legacy-token CSS (sub-pages.css prose, the pages' inline styles)
renders dark for free. Same trick docs-kinpaku/slop-kinpaku use per page,
lifted into one shared class. Pair it with .kinpaku-chrome for header +
footer.

privacy + both tutorials pages now carry both classes. Also force the
sub-1.2rem headings (tutorial card titles, prose h1/h2) back to the
upright body face: the legacy display face was italic serif, and the
kinpaku Pinstripe face reads wrong synthesized-italic at small sizes.

No light pages remain.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: re-add Tutorials to the /docs sidebar

Tutorials lost its docs placement across two refactors: the Astro docs
rebuild never carried over the sidebar tutorials list the old generated
pages had, and the kinpaku homepage redesign dropped the "Full
walkthrough" link. It survived only via /designing and /live-mode.

Add a "Tutorials" group at the top of the docs sidebar (matching the
command-category styling) linking the index plus all four tutorials,
restoring the old information architecture.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: make kinpaku the default — flip legacy :root tokens to dark (phase 1)

Repoint the legacy design tokens in tokens.css from light-mode to kinpaku:
--font-* now reference the --ks-* brand faces (retiring Cormorant/Instrument/
Space Grotesk), surfaces carry dark-lacquer oklch, and --color-accent is gold
instead of magenta. Values mirror the per-page kinpaku remaps.

Every live page already overrides these at its body-class scope, so this
changes the fallback (any classless/new page now renders kinpaku) without
altering existing pages — verified home, designing, slop, live-mode, docs
unchanged, and the deliberate-light demos (slop specimens, home's Aurelia
mock) still render light via their own colors.

First step toward removing the per-page remaps; those become redundant next.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* detector + slop: cream-palette rule, drop everything-centered, polish catalog

- new deterministic cream-palette rule ("claude beige"): flags warm
  lightly-tinted off-white page backgrounds; wired into static + browser
  engines, with fixture + test
- remove everything-centered rule entirely (no longer in the skill) from
  registry, regex analyzer (+ index-offset fix), checkPageLayout, and tests
- catch Instrument Serif in overused-font (regex + OVERUSED_FONTS)
- /slop: reconcile catalog (cream card in, everything-centered out; counts),
  and fix demo visuals — visible hairline border, gigantic clipped hero,
  more extreme crushed tracking, padded gray-on-color card, uniform-rhythm
  monotonous-spacing, long line-length line, elastic-overshoot dialog for
  bounce easing, real zooming image for image-hover; flip the demo surface
  off warm beige to a cool neutral

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* detector page: add cream-palette fixture to the catalog

Surfaces the new cream/beige palette rule on /detector alongside the
other Color specimens.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: shared docs sidebar + tutorial pages join the layout

Extract the /docs section sidebar into a reusable DocsSidebar component
and wire it into all three entry points so the navigation is consistent
across docs index, command pages, and tutorial pages.

site/components/DocsSidebar.astro (new): one source of truth. Loads the
tutorials + skills collections, renders Tutorials → Commands grouped by
category, and highlights the active entry via activeCommand / activeTutorial
props.

site/pages/docs/index.astro: swap the inline sidebar markup for the
component. Drop the "All tutorials" link — the dedicated tutorials
listing page wasn't earning its slot in the rail.

site/layouts/Doc.astro: same swap. Command pages now also see the
Tutorials section above Commands, matching /docs.

site/pages/tutorials/[...slug].astro: rewrite from a standalone page
(custom .tutorial-page wrapper, ad-hoc breadcrumb) to the full
skills-layout shell with DocsSidebar in the left rail. Tutorial content
now reads in the same layout as command reference pages.

site/content/tutorials/brand-vs-product.md (deleted): the skill picks
the register automatically from PRODUCT.md, so a tutorial telling users
to pick it themselves was misleading.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* detector: catch Tailwind warm-light bg utilities in cream-palette

The static engine can't resolve Tailwind classes to computed CSS, so a
`bg-amber-50` on <body> slipped past the cream-palette rule. Add a
class-list fallback that scans body/html for arbitrary `bg-[...]` values
and named warm-light utilities (amber/orange/yellow/stone), each run
through the same isCreamColor test so neutrals and over-saturated shades
drop out. Fixture + test for the class-only case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: drop redundant per-page token remaps (phase 2)

With kinpaku now the :root default, the --color-* / --font-* remap blocks
in docs/slop/designing/live-mode-kinpaku.css re-declared values identical
to :root. Removed them, keeping only the --ks-muted alias (still read by
name in those files) and each page's shell (gradient bg, color, min-height).

home-kinpaku.css keeps its remap: it uses home-specific values (e.g.
--color-charcoal: var(--ks-text), --color-cream: var(--ks-lacquer-raised))
plus the --cat-* gradient overrides, so it is not redundant.

Verified designing (PRODUCT.md viz), slop (specimens stay light), docs,
live-mode unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: drop italic from 15 dead editorial-serif heading rules

Audited every font-style: italic in sub-pages.css and main.css against
the live markup. Removed italic from the 15 rules whose selectors don't
appear in any page/component/content/script:

  sub-pages.css: docs-home-card-title, docs-category-title,
    tutorial-embed-caption, skill-demo-caption, skill-source-card-subtitle,
    skill-references-heading, skill-reference-title
  main.css: hero-title-combined, hero-tagline-combined, impeccable-title,
    loading-state, install-primary-howto .install-path-desc em,
    install-howto-steps > li::before, install-step-status, consulting-title

These were dormant remnants of the retired Cormorant italic-serif look —
the kinpaku Pinstripe face renders them as bad synthesized-italic, but
no markup matches the selectors so nothing rendered. Removed only the
font-style declaration; the rest of each rule stays (whole-rule cleanup
is out of scope).

Kept the 5 live selectors (slop-section-heading, tutorial-card-title,
visual-mode-demo-caption, visual-mode-method-name, gallery-card-title)
per the "if they're not used anywhere" condition, plus .prose em (real
emphasis) and .prose blockquote (conventional blockquote italic).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* skill: brand-seed palette.mjs + Setup step to run it

New-brand color now starts from a curated seed color (129 OKLCH seeds)
instead of the model guessing or defaulting to warm-cream. The script
returns one seed + composition guidance (pure-bg architecture, perceptual
text-on-fill, anti-cliché moods, jewel-tone range), with inverse-frequency
hue weighting for fair rainbow exposure and deterministic --from picking.
SKILL.md Setup step 5 makes it run for greenfield projects. Curation
tooling lives in the impeccable-evals repo (tools/palette/).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Remove accidental live mode inject from Base.astro.

The localhost live.js tag was left in the site layout after a dev session and should never ship in the Astro template.

Co-authored-by: Cursor <cursoragent@cursor.com>

* site: dedicated /changelog + /faq, epic v3.5.0 notes, Live Mode → Beta

Split changelog and FAQ out of the homepage into two standalone kinpaku
pages, linked from the footer (and a quiet hint under the Get-started CTA).

/changelog: every release inline (no collapsible), newest first. The
v3.5.0 entry leads with a one-line summary, a real before/after pair from
the GPT-5.5 eval corpus (luxury-hotel brief, skill off vs on), and a stat
row (74% cream-bg, 76% extreme tracking, 90%+ low-contrast — measured
across ~190 samples). Then five scannable bold-led bullets, biggest
takeaway first: per-provider skill compilation, the bias-fix, Live Mode,
the 7 new detector rules, the tighter skill. Before/after JPGs optimized
to ~470KB total (down from ~2.5MB PNGs).

/faq: the six support questions, each deep-linkable.

Live Mode is now Beta everywhere it surfaces: the /live-mode eyebrow
badge and note, the homepage bento tile badge, and the changelog entry.
The historical v3.0 changelog entry stays "Alpha" — accurate to what
shipped then.

Footer trimmed to the four links not already in the top nav (Changelog,
FAQ, Privacy, GitHub).

Version bumped 3.2.0 → 3.5.0 across the three plugin manifests; the
3.2 bias-fix work folds into this release rather than shipping separately.

astro.config.mjs: disable the dev toolbar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: point /design-system hero at the m-01-v2-01 finalist

design-system.css referenced kintsugi-hero-v2.png, an untracked orphan
that was never committed. Repoint it at the committed m-01-v2-01 finalist
so /design-system and the homepage hero share one image, and the page
no longer depends on a file outside the repo. The v2 orphan moved to tmp/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* build: sync harness mirrors + green the prose gate

Rebuild propagates the committed skill source (palette.mjs Setup step,
detector rule updates, brand.md) into the 13 harness output dirs and the
plugin subtree, which had drifted from source.

Also fixes the prose validator, which had been red on six pre-existing
hits across committed files:
- Four em dashes in code comments (Testimonials.astro, LiveDemoGbar.astro,
  index.astro) and one in skill/reference/live.md — reworded to colons/commas.
- Two in the slop catalog (an em-dash-overuse specimen and the
  marketing-buzzword rule naming "empower"). Those are intentional: the
  slop page documents every antipattern by example, so it must contain
  them. Exempted site/pages/slop from validateProse rather than neutering
  the specimens.

`bun run build` is now green end to end: counts validate, prose passes,
site builds.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* skill: rewrite no-section-fade rule to fix Gemini zero-motion overcorrection

The old rule ("whole-section fade-on-scroll is the saturated AI motion
reflex") drove Gemini to overcorrect into shipping pages with no motion
at all: motion-variety 39% / zero-motion 12% with the skill on, vs
~74-78% variety and ~3% zero-motion without it.

Rewrite keeps the legitimate-stagger carve-out, names the defect at
shape level (one identical entrance on every section) without
enumerating motion primitives, and adds an explicit clause that
suppressing the reflex is never grounds for a static page.

Validated on Gemini 3.5-flash (n=10, luxury-hotel + infra-platform):
motion-variety 39% -> 70%, zero-motion 12% -> 0%, staggered-reveal
stays 0% (reflex not re-inflated).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* release: bump CLI to 2.2.0 and extension to 1.1.0

Both ship the expanded detector: the 7 new rules (cream-palette,
em-dash-overuse, marketing-buzzword, numbered-section-markers,
aphoristic-cadence, broken-image, italic-serif-display) plus
hero-eyebrow-chip, with everything-centered removed. 41 rules total.

The extension settings page already supports toggling them: the rule
list renders from detector/antipatterns.json, grouped by category, and
disabledRules flows through chrome.storage.sync into the scan config,
which detect.js honors by rule id. New rules are toggleable with no UI
change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* release: fix release.mjs for the moved changelog + add CLI/ext entries

The changelog moved from site/pages/index.astro to its own
site/pages/changelog.astro with new markup (cf-version / cf-entry /
cf-items), which left release.mjs reading the wrong file with the old
selectors. All three release commands would have failed at note
extraction. Point it at changelog.astro, match cf-version, and scope
notes to the <ul class="cf-items"> bullet list — that also skips the
lead paragraph, before/after figure, and stat row on the v3.5.0 entry,
keeping release notes to clean bullets.

Add CLI v2.2.0 and Extension v1.1.0 changelog entries (the shared
detector update: 7 new rules, everything-centered removed, 41 total;
plus the extension's per-rule toggles) so release:cli and release:ext
have notes to extract.

Verified extraction for all three labels: v3.5.0 (5 bullets),
CLI v2.2.0 (3), Extension v1.1.0 (2).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: correct dev server port to 4321 and drop stale pnpm-lock

Astro serves on 4321, not 3000 as the docs claimed; update CLAUDE.md,
AGENTS.md, and screenshot-antipatterns.js. Remove the leftover
pnpm-lock.yaml from the Astro migration so Cloudflare's frozen install
uses the maintained, in-sync bun.lock instead of a drifted pnpm lockfile.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: rework /designing flow, rhythm, Live Mode mock, and CTA

Restructure the page so iteration reads as the core value, not net-new.
The four loop phases are wrapped in a track with a sticky scroll-spy nav
(Start/Iterate/Polish/Maintain) that pins under the header and highlights
the active phase; the surfaces section (skill/CLI/extension) moves out of
the loop into the post-loop context group so the loop runs uninterrupted.

Fix the iterate split: shared subgrid row tracks so the terminal and the
Live Mode mock align on the same baseline regardless of paragraph length,
wider intro measure (52ch, was a crammed 36ch), and a deeper picker stage
so the context and global bars breathe instead of stacking on the card.

Rebuild the Live Mode mock to mirror the real picker: carved-tile mark plus
Pick / Insert / Detect / DESIGN.md controls on lacquer-deep with the gold
border, and a /impeccable live entry line so the reader knows how to start.

Reframe Start as the hard mode, move h3 subheads off the thin display face
onto Albert Sans, and trim Start so it no longer dominates the loop.

Rework the closing CTA into two standalone raised cards (the bento plinth
made them read as boxes nested in a box), and fix the tutorials copy: there
are three walkthroughs now, and the brand-vs-product tutorial is gone, so
drop it from the CTA and remove the dead lane link to it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: reorder Get Started so usage follows setup, link out to more

Move the /impeccable usage examples below the Chrome extension, CLI, and
Stay-updated block. Running a command is the logical next step once the
skill, extension, CLI, and subscriptions are all in place, so the section
now reads install -> set up the extras -> use it. Add a closing "Go deeper"
line linking to the Designing with Impeccable workflow page and the docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: install compiled per-provider skill variants, not uncompiled source

`npx skills add` (and `impeccable skills install`, which wrapped it) installed
the uncompiled skill/ source verbatim: the skills CLI dedupes discovery by name
and picks skill/SKILL.md first, so installs shipped unresolved {{placeholders}}
and no vendored detector (#168).

- Rename skill/SKILL.md -> skill/SKILL.src.md so the skills CLI's discovery
  skips the source and falls through to a compiled .agents variant; update the
  build reader, skill-behavior harness, and docs to match.
- Refactor `impeccable skills install` to copy each harness's compiled variant
  from the universal bundle (real dirs, no npx skills, no symlink), with
  project/global harness detection and a --providers override.
- Fix stale unit tests (replacePlaceholders, readPatterns, transformer
  prefix/summary) that asserted removed pre-v3.0 behavior, and wire the three
  orphaned test files into `bun run test` so the drift can't recur.
- Split skills-cli.test.js: pure blocks run by default, network blocks move
  behind a new `bun run test:cli-e2e`; fix its stale update assertions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: default to `npx impeccable skills install`, restore install-method panel

Get Started recommended `npx skills add`, which installs a single shared build
across harnesses. Make our CLI the default (it installs the build compiled for
each harness) and bring back the "Other install methods" disclosure the
neo-kinpaku redesign dropped.

- Homepage: primary command is now `npx impeccable skills install`; a native
  <details> panel offers the Claude Code plugin and `npx skills` (caveated as
  installing one shared build rather than the per-harness one).
- FAQ: recommend `npx impeccable skills install` to install, `--force` to
  reinstall, and note the npx skills shared-build caveat.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* site: reword craft tagline so it doesn't lead with "Shape"

The craft card's tagline began with the word "Shape", which reads like
the name of the sibling /shape command and made the two cards look
swapped (#166). Reword to "Design it, then build it, all in one flow."
No data was actually swapped; this is a copy collision fix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* skill: rename teach -> init and expand its setup flow

Rename the `/impeccable teach` command to `/impeccable init` across the
skill, site, CLI, and tests. `teach` stays as a deprecated router alias and
/docs/teach + /skills/teach redirect to /docs/init.

Expand the command beyond writing PRODUCT.md/DESIGN.md: the same codebase
crawl now also pre-configures `.impeccable/live/config.json` (Step 6, with
CSP consent) so live mode boots with no first-time detour, and the flow ends
by recommending the best commands to run next from what the scan surfaced
(Step 7).

Fold two items into the unreleased v3.5.0 changelog entry: the init rename
and the brand-seed palette picker. No version bump.

Regenerates all harness skill output dirs and the _redirects file.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: lead README install + usage with the CLI installer

Add `npx impeccable skills install` as the recommended install option and
update the Usage section to the `/impeccable <command>` form, dropping the
nonexistent `/normalize` example.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(skill-behavior): swap to production-tier models (sonnet + gpt-5.5)

Replace the cheap-tier default lineup (claude-haiku-4-5, gpt-5.4-mini) with
production-tier models (claude-sonnet-4-6, gpt-5.5) so the skill-behavior
suite reflects what users actually run. gemini stays on flash-lite.

Sync the docs (CLAUDE.md, AGENTS.md, tests/skill-behavior/README.md): new
model names, cost estimate raised to ~$0.50-1.50/sweep, and the old 21-22/24
baseline reframed as previous-cheap-tier history pending re-measurement on
the new lineup.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat: self-updating skill via boot-time version check

context.mjs now polls a new lightweight /api/version endpoint at most once
per day (cached globally in ~/.impeccable) and appends an UPDATE_AVAILABLE
directive when a newer skill version has shipped, prompting the agent to
offer `npx impeccable skills update`. Best-effort and silent on any failure;
asks before updating; suppresses re-prompts for a declined version for a
week. Opt out with IMPECCABLE_NO_UPDATE_CHECK=1.

- skill/scripts/context.mjs: version read, throttle + anti-nag cache, directive
- scripts/build.js + _redirects: /api/version endpoint (from plugin.json version)
- skill/SKILL.src.md: document the UPDATE_AVAILABLE boot branch
- tests/context.test.mjs: coverage for cached/newer/suppressed/opt-out paths
- changelog: v3.5.0 entry
- synced harness skill dirs via bun run build

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test: cover the self-update path (network + LLM behavior)

context.test.mjs: add a localhost stub-server integration test for the live
fetch path (poll /api/version, cache a newer version, stay silent on
same-or-older, fail silent + stamp lastCheck when unreachable). Runs against
127.0.0.1 only, never the real site; uses async spawn so the in-process stub
isn't deadlocked by spawnSync blocking the event loop.

skill-behavior: add scenario 9 asserting the agent surfaces UPDATE_AVAILABLE
but never auto-runs `npx impeccable skills update` without asking. New
prepareWorkspace `skillVersion` copy-mode (so context.mjs has a SKILL.md to
version-check), env threading through runTurn -> execBash, and bash-output
capture to prove the agent actually received the directive. Passed on
claude-sonnet-4-6, gpt-5.5, and gemini-3.1-flash-lite.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Paul Bakaus
2026-05-28 14:22:22 -07:00
committed by GitHub
co-authored by Claude Opus 4.7 Cursor
parent 84135db0e6
commit 9ffd3211d5
955 changed files with 121730 additions and 38852 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli/engine/browser/injected/index.mjs
+44 -7
View File
@@ -9,8 +9,21 @@ if (IS_BROWSER) {
const EXTENSION_MODE = (_myScript && _myScript.dataset.impeccableExtension === 'true')
|| document.documentElement.dataset.impeccableExtension === 'true';
const BRAND_COLOR = 'oklch(55% 0.25 350)';
const BRAND_COLOR_HOVER = 'oklch(45% 0.25 350)';
// Kinpaku gold — pinned to the site's brand token (see
// site/styles/kinpaku-tokens.css --ks-kinpaku). Keep this in sync with
// the picker's C.brand in skill/scripts/live-browser.js and the kit's
// picker section in site/styles/kinpaku-kit.css.
//
// One color across both light and dark host pages. The outline is a
// 2px gesture pointing at an element + a labeled tag — it's a marker,
// not body text, so it doesn't need WCAG AA against the page. The
// label text inside the gold tag is dark (LABEL_INK) which has ~16:1
// against the leaf gold, so reading the rule name is solid in both
// modes. Hover deepens the gold (preserves chroma — never drops it,
// dropping chroma washes the gold into a sand/olive tone).
const BRAND_COLOR = 'oklch(84% 0.19 80.46)';
const BRAND_COLOR_HOVER = 'oklch(74% 0.18 80)';
const LABEL_INK = 'oklch(4% 0.004 95)';
const LABEL_BG = BRAND_COLOR;
const OUTLINE_COLOR = BRAND_COLOR;
@@ -278,7 +291,7 @@ if (IS_BROWSER) {
display: 'flex', alignItems: 'center',
whiteSpace: 'nowrap',
fontSize: '11px', fontWeight: '600', letterSpacing: '0.02em',
color: 'white', lineHeight: '14px',
color: LABEL_INK, lineHeight: '14px',
background: LABEL_BG,
fontFamily: 'system-ui, sans-serif',
borderRadius: '4px 4px 0 0',
@@ -398,7 +411,7 @@ if (IS_BROWSER) {
banner.className = 'impeccable-overlay impeccable-banner';
Object.assign(banner.style, {
position: 'fixed', top: '0', left: '0', right: '0', zIndex: '100000',
background: LABEL_BG, color: 'white',
background: LABEL_BG, color: LABEL_INK,
fontFamily: 'system-ui, sans-serif', fontSize: '13px',
display: 'flex', alignItems: 'center', pointerEvents: 'auto',
height: '36px', overflow: 'hidden', maxWidth: '100vw',
@@ -1223,12 +1236,12 @@ if (IS_BROWSER) {
}
console.group(
`%c[impeccable] ${allFindings.length} anti-pattern${allFindings.length === 1 ? '' : 's'} found`,
'color: oklch(60% 0.25 350); font-weight: bold'
'color: oklch(84% 0.19 80.46); font-weight: bold'
);
for (const { el, findings } of allFindings) {
for (const f of findings) {
console.log(`%c${f.type || f.id}%c ${f.detail || f.snippet}`,
'color: oklch(55% 0.25 350); font-weight: bold', 'color: inherit', el);
'color: oklch(84% 0.19 80.46); font-weight: bold', 'color: inherit', el);
}
}
console.groupEnd();
@@ -1249,6 +1262,10 @@ if (IS_BROWSER) {
const groupMap = new Map();
const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
// Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
// real browser env (detector page, live overlay, extension) running every
// check is free, so we always surface them; the gating is purely a CLI
// output concern, applied in the Node engines' detect* return paths.
for (const el of document.querySelectorAll('*')) {
// Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
@@ -1270,11 +1287,23 @@ if (IS_BROWSER) {
...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementHeroEyebrowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementOversizedH1DOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
].filter(f => _ruleOk(f.type));
addBrowserFindings(groupMap, el, findings);
// Hero eyebrow: the offending element is the eyebrow above the heading,
// not the heading itself — highlight the previous sibling instead.
const eyebrowFindings = checkElementHeroEyebrowDOM(el)
.map(f => ({ type: f.id, detail: f.snippet }))
.filter(f => _ruleOk(f.type));
if (eyebrowFindings.length > 0 && el.previousElementSibling) {
addBrowserFindings(groupMap, el.previousElementSibling, eyebrowFindings);
}
}
const pageLevelFindings = [];
@@ -1306,6 +1335,14 @@ if (IS_BROWSER) {
addBrowserFindings(groupMap, document.body, qualityFindings);
}
const creamFindings = checkCreamPalette(document)
.map(f => ({ type: f.id, detail: f.snippet }))
.filter(f => _ruleOk(f.type));
if (creamFindings.length > 0) {
pageLevelFindings.push(...creamFindings);
addBrowserFindings(groupMap, document.body, creamFindings);
}
// Regex-on-HTML checks (shared with Node)
// Clone the document and strip impeccable-live overlay nodes before the
// regex scan, so the inspector's own inline styles (transitions on top/
cli/engine/cli/main.mjs
+16 -10
View File
@@ -41,7 +41,7 @@ function formatFindings(findings, jsonMode) {
// Stdin handling
// ---------------------------------------------------------------------------
async function handleStdin() {
async function handleStdin(options = {}) {
const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);
const input = Buffer.concat(chunks).toString('utf-8');
@@ -50,10 +50,10 @@ async function handleStdin() {
const fp = parsed?.tool_input?.file_path;
if (fp && fs.existsSync(fp)) {
return HTML_EXTENSIONS.has(path.extname(fp).toLowerCase())
? detectHtml(fp) : detectText(fs.readFileSync(fp, 'utf-8'), fp);
? detectHtml(fp, options) : detectText(fs.readFileSync(fp, 'utf-8'), fp, options);
}
} catch { /* not JSON */ }
return detectText(input, '<stdin>');
return detectText(input, '<stdin>', options);
}
@@ -81,6 +81,8 @@ Scan files or URLs for UI anti-patterns and design quality issues.
Options:
--fast Regex-only mode (skip static HTML/CSS analysis, faster but misses linked stylesheets)
--json Output results as JSON
--gpt Also report GPT-specific provider tells (off by default)
--gemini Also report Gemini-specific provider tells (off by default)
--help Show this help message
Detection modes:
@@ -106,6 +108,10 @@ async function detectCli() {
const jsonMode = args.includes('--json');
const helpMode = args.includes('--help');
const fastMode = args.includes('--fast');
const providers = [];
if (args.includes('--gpt')) providers.push('gpt');
if (args.includes('--gemini')) providers.push('gemini');
const scanOptions = { providers };
const targets = args.filter(a => !a.startsWith('--'));
if (helpMode) { printUsage(); process.exit(0); }
@@ -113,7 +119,7 @@ async function detectCli() {
let allFindings = [];
if (!process.stdin.isTTY && targets.length === 0) {
allFindings = await handleStdin();
allFindings = await handleStdin(scanOptions);
} else {
const paths = targets.length > 0 ? targets : [process.cwd()];
const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
@@ -124,8 +130,8 @@ async function detectCli() {
if (/^https?:\/\//i.test(target)) {
try {
const scanner = browserDetector
? (url) => browserDetector.detectUrl(url)
: (url) => detectUrl(url);
? (url) => browserDetector.detectUrl(url, scanOptions)
: (url) => detectUrl(url, scanOptions);
allFindings.push(...await scanner(target));
} catch (e) { process.stderr.write(`Error: ${e.message}\n`); }
continue;
@@ -192,9 +198,9 @@ async function detectCli() {
const ext = path.extname(file).toLowerCase();
let fileFindings;
if (!fastMode && HTML_EXTENSIONS.has(ext)) {
fileFindings = await detectHtml(file);
fileFindings = await detectHtml(file, scanOptions);
} else {
fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file);
fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, scanOptions);
}
// Annotate findings with import context
const importers = importedByMap.get(file);
@@ -209,9 +215,9 @@ async function detectCli() {
} else if (stat.isFile()) {
const ext = path.extname(resolved).toLowerCase();
if (!fastMode && HTML_EXTENSIONS.has(ext)) {
allFindings.push(...await detectHtml(resolved));
allFindings.push(...await detectHtml(resolved, scanOptions));
} else {
allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved));
allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, scanOptions));
}
}
}
cli/engine/detect-antipatterns-browser.js
+588 -75
View File
@@ -38,7 +38,7 @@ const OVERUSED_FONTS = new Set([
// Older monoculture (still ubiquitous):
'inter', 'roboto', 'open sans', 'lato', 'montserrat', 'arial', 'helvetica',
// Newer monoculture (the Anthropic-skill / Vercel / GitHub default wave):
'fraunces', 'instrument sans',
'fraunces', 'instrument sans', 'instrument serif',
'geist', 'geist sans', 'geist mono',
'mona sans',
'plus jakarta sans', 'space grotesk', 'recoleta',
@@ -165,6 +165,15 @@ const ANTIPATTERNS = [
skillSection: 'Color & Contrast',
skillGuideline: 'AI color palette',
},
{
id: 'cream-palette',
category: 'slop',
name: 'Cream / beige palette',
description:
'A warm cream or beige page background has become the default "tasteful" AI surface, reached for by reflex. Choose a background that comes from a deliberate palette, not the safe warm off-white.',
skillSection: 'Color & Contrast',
skillGuideline: 'cream and beige as the default surface',
},
{
id: 'nested-cards',
category: 'slop',
@@ -183,15 +192,6 @@ const ANTIPATTERNS = [
skillSection: 'Layout & Space',
skillGuideline: 'same spacing everywhere',
},
{
id: 'everything-centered',
category: 'slop',
name: 'Everything centered',
description:
'Every text element is center-aligned. Left-aligned text with asymmetric layouts feels more designed. Center only hero sections and CTAs.',
skillSection: 'Layout & Space',
skillGuideline: 'Center everything',
},
{
id: 'bounce-easing',
category: 'slop',
@@ -247,17 +247,72 @@ const ANTIPATTERNS = [
skillSection: 'Typography',
skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
},
{
id: 'numbered-section-markers',
category: 'slop',
severity: 'advisory',
name: 'Numbered section markers (01 / 02 / 03)',
description:
'Numbered display markers as section labels (01, 02, 03) are the AI editorial scaffold one tier deeper than tracked eyebrow chips. If you find yourself reaching for them, choose a different section cadence.',
skillSection: 'Layout & Space',
skillGuideline: 'numbered section markers',
},
{
id: 'em-dash-overuse',
category: 'slop',
name: 'Em-dash overuse',
description:
'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
skillSection: 'Copy',
skillGuideline: 'no em dashes',
},
{
id: 'marketing-buzzword',
category: 'slop',
name: 'Marketing buzzword',
description:
'Generic SaaS phrases (streamline / empower / supercharge / world-class / enterprise-grade / next-generation / cutting-edge / etc) are instant AI tells. Pick a specific verb and noun that says what the product literally does.',
skillSection: 'Copy',
skillGuideline: 'marketing buzzwords',
},
{
id: 'aphoristic-cadence',
category: 'slop',
name: 'Aphoristic-cadence copy',
description:
'Three or more sections landing on a short rebuttal sentence ("X. No Y." / "X. Just Y.") or a manufactured-contrast aphorism ("Not a feature. A platform.") reads as AI cadence, not voice. Once is fine; the pattern is the tell.',
skillSection: 'Copy',
skillGuideline: 'aphoristic cadence',
},
{
id: 'oversized-h1',
category: 'slop',
name: 'Oversized hero headline',
description:
'A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold. A punchy one- or two-word headline at that size is fine — the problem is a long headline blown up too large. Set long headlines smaller, or tighten the copy.',
skillSection: 'Typography',
skillGuideline: 'long headline set at display size',
},
{
id: 'extreme-negative-tracking',
category: 'slop',
name: 'Crushed letter spacing',
description:
'Letter-spacing pulled tighter than the point where characters keep their own shapes costs legibility. Tighten display type optically, not destructively.',
skillSection: 'Typography',
skillGuideline: 'letter spacing crushed past legibility',
},
{
id: 'broken-image',
category: 'quality',
name: 'Broken or placeholder image',
description:
'<img> tags with empty src, missing src, or placeholder values ship as broken-image boxes. Use real images, generated assets, or remove the tag.',
skillSection: 'Imagery',
skillGuideline: 'broken image references',
},
// ── Quality: general design and accessibility issues ──
{
id: 'pure-black-white',
category: 'quality',
name: 'Pure black background',
description:
'Pure #000000 as a background color looks harsh and unnatural. Tint it slightly toward your brand hue (e.g., oklch(12% 0.01 250)) for a more refined feel.',
skillSection: 'Color & Contrast',
skillGuideline: 'pure black (#000)',
},
{
id: 'gray-on-color',
category: 'quality',
@@ -297,7 +352,9 @@ const ANTIPATTERNS = [
category: 'quality',
name: 'Cramped padding',
description:
'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.',
'Text is too close to the edge of its container. Two shapes: (1) an element with its own text where the padding is too low for the font size, and (2) a wrapper with text-bearing children and near-zero padding against a visible boundary (border, outline, or non-transparent background) — children land flush against the boundary line. Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers.',
skillSection: 'Layout & Space',
skillGuideline: 'inside bordered or colored containers',
},
{
id: 'body-text-viewport-edge',
@@ -350,6 +407,70 @@ const ANTIPATTERNS = [
description:
'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
},
{
id: 'text-overflow',
category: 'quality',
name: 'Content overflowing its container',
description:
'Content renders wider than its container, spilling out or forcing a horizontal scrollbar. Let text wrap, constrain widths, or give the region a deliberate scroll affordance.',
skillSection: 'Layout & Space',
skillGuideline: 'content wider than its container',
},
{
id: 'clipped-overflow-container',
category: 'quality',
name: 'Positioned child clipped by overflow container',
description:
'A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape. Let the overflow be visible, or move the positioned layer out of the clip.',
skillSection: 'Layout & Space',
skillGuideline: 'overflow container clipping positioned children',
},
// ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
{
id: 'gpt-thin-border-wide-shadow',
category: 'slop',
severity: 'advisory',
gated: 'gpt',
name: 'Hairline border with wide shadow',
description:
'A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once.',
skillSection: 'Visual Details',
skillGuideline: 'hairline border plus wide diffuse shadow',
},
{
id: 'repeating-stripes-gradient',
category: 'slop',
severity: 'advisory',
gated: 'gpt',
name: 'Repeating-gradient stripes',
description:
'Repeating-gradient stripes used as surface decoration are a recurring generated-UI signature. Reach for a deliberate texture or leave the surface plain.',
skillSection: 'Visual Details',
skillGuideline: 'repeating-gradient decorative stripes',
},
{
id: 'theater-slop-phrase',
category: 'slop',
severity: 'advisory',
gated: 'gpt',
name: 'Theater framing copy',
description:
'Dismissing something as "theater" is a recurring generated-copy tic. Say plainly what the thing does or does not do.',
skillSection: 'Copy',
skillGuideline: 'theater framing copy',
},
{
id: 'image-hover-transform',
category: 'slop',
severity: 'advisory',
gated: 'gemini',
name: 'Image hover transform',
description:
'Scaling or rotating an image on hover is a recurring generated-UI signature. Let imagery sit still, or use a subtler, purposeful interaction.',
skillSection: 'Motion',
skillGuideline: 'image scale or rotate on hover',
},
];
// --- cli/engine/shared/color.mjs ---
@@ -527,11 +648,6 @@ function checkColors(opts) {
}
const findings = [];
// Pure black background (only solid or near-solid, not semi-transparent overlays)
if (bgColor && bgColor.a >= 0.9 && bgColor.r === 0 && bgColor.g === 0 && bgColor.b === 0) {
findings.push({ id: 'pure-black-white', snippet: '#000000 background' });
}
if (hasDirectText && textColor && !isEmojiOnly) {
// Run background-dependent checks against either a solid bg or, if the
// ancestor is a gradient, against every gradient stop (use the worst case).
@@ -587,9 +703,6 @@ function checkColors(opts) {
// Tailwind class checks
if (classList) {
const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ');
if (/\bbg-black\b(?!\/)/.test(classStr)) {
findings.push({ id: 'pure-black-white', snippet: 'bg-black' });
}
const grayMatch = classStr.match(/\btext-(?:gray|slate|zinc|neutral|stone)-\d+\b/);
const colorBgMatch = classStr.match(/\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/);
@@ -905,12 +1018,6 @@ function checkHtmlPatterns(html) {
// --- Color ---
// Pure black background
const pureBlackBgRe = /background(?:-color)?\s*:\s*(?:#000000|#000|rgb\(\s*0,\s*0,\s*0\s*\))\b/gi;
if (pureBlackBgRe.test(html)) {
findings.push({ id: 'pure-black-white', snippet: 'Pure #000 background' });
}
// AI color palette: purple/violet
const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
if (purpleHexRe.test(html)) {
@@ -1027,6 +1134,39 @@ function checkHtmlPatterns(html) {
}
}
// --- Provider tells (gated): repeating-gradient stripes (GPT) ---
if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
}
// --- Provider tells (gated): "X theater" framing copy (GPT) ---
// Lives here (regex-on-HTML) rather than in the text-content analyzers so it
// runs in the bundled browser path too, not just the CLI/static path.
{
const bodyText = html
.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
.replace(/<[^>]+>/g, ' ');
const tm = /\b(\w+)\s+theater\b/i.exec(bodyText);
if (tm) findings.push({ id: 'theater-slop-phrase', snippet: `"${tm[0].trim()}"` });
}
// --- Provider tells (gated): image hover transform (Gemini) ---
// A CSS `img...:hover { transform: ... }` rule, or a Tailwind hover:scale /
// hover:rotate / hover:translate utility on an <img>. Each distinct
// mechanism is its own finding.
const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
if (imgHoverCss.test(html)) {
findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
}
const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
let im;
while ((im = imgTagRe.exec(html)) !== null) {
if (/\bhover:(?:scale|rotate|translate|skew)-/.test(im[1])) {
findings.push({ id: 'image-hover-transform', snippet: 'Tailwind hover transform on <img>' });
}
}
return findings;
}
@@ -1673,7 +1813,7 @@ function resolveLengthPx(value, fontSizePx) {
// Both adapters resolve font-size, line-height and letter-spacing to pixels
// before calling this so the pure function only deals with numbers.
function checkQuality(opts) {
const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0 } = opts;
const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
const findings = [];
// Skip browser extension injected elements
const elId = el.id || '';
@@ -1724,6 +1864,155 @@ function checkQuality(opts) {
}
}
// --- Flush against a visible boundary ---
// Fires when a container has a visible boundary (border, outline, OR a
// non-transparent background) AND near-zero padding on the bounded
// side(s) AND text-bearing children land flush against the boundary.
//
// Distinct from cramped-padding: that rule needs the element itself to
// have direct text (hasDirectText). This rule targets the OPPOSITE
// shape — a container with NO direct text, only children — which is
// exactly what cramped-padding misses (a section wrapping a label +
// list lands a free pass).
//
// The classic shape: agent writes `padding: 28px 0 0` shorthand on a
// section that also has a border, zeroing horizontal padding so the
// text-bearing children touch the side borders. Background and
// outline count too: a colored card with zero padding has the same
// visual failure mode.
{
const FLUSH_SKIP_TAGS = new Set(['HTML', 'BODY', 'MAIN', 'HEADER', 'FOOTER', 'NAV', 'ARTICLE', 'ASIDE', 'BUTTON', 'A', 'LABEL', 'SUMMARY', 'CODE', 'PRE', 'INPUT', 'TEXTAREA', 'SELECT', 'FORM', 'FIGURE', 'TABLE', 'TBODY', 'THEAD', 'TR', 'TD', 'TH']);
const upperTag = tag ? tag.toUpperCase() : '';
const elPosition = style.position || '';
if (
!FLUSH_SKIP_TAGS.has(upperTag) &&
!hasDirectText &&
!['fixed', 'absolute'].includes(elPosition) &&
el.children && el.children.length > 0
) {
const isTransparent = (c) =>
!c || c === 'transparent' || c === 'rgba(0, 0, 0, 0)' ||
/^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(c);
const borderW = {
top: parseFloat(style.borderTopWidth) || 0,
right: parseFloat(style.borderRightWidth) || 0,
bottom: parseFloat(style.borderBottomWidth) || 0,
left: parseFloat(style.borderLeftWidth) || 0,
};
const borderVisible = {
top: borderW.top > 0 && !isTransparent(style.borderTopColor),
right: borderW.right > 0 && !isTransparent(style.borderRightColor),
bottom: borderW.bottom > 0 && !isTransparent(style.borderBottomColor),
left: borderW.left > 0 && !isTransparent(style.borderLeftColor),
};
// Outline detection. jsdom decomposes `border` shorthand into
// border{Top,…}Width/Color but does NOT decompose `outline` —
// the longhands come back empty when the value was set via the
// shorthand. Fall back to parsing `style.outline` ourselves.
let outlineW = parseFloat(style.outlineWidth) || 0;
let outlineStyleVal = style.outlineStyle || '';
let outlineColorVal = style.outlineColor || '';
if (!outlineW && style.outline) {
const wMatch = style.outline.match(/(\d+(?:\.\d+)?)\s*px/);
if (wMatch) outlineW = parseFloat(wMatch[1]) || 0;
if (!outlineStyleVal) {
outlineStyleVal = /\b(solid|dashed|dotted|double|groove|ridge|inset|outset)\b/.test(style.outline) ? 'solid' : '';
}
if (!outlineColorVal) {
const cMatch = style.outline.match(/(rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}|[a-zA-Z]+)\s*$/);
if (cMatch) outlineColorVal = cMatch[1];
}
}
const outlineVisible = outlineW > 0 && !isTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
const bgVisible = !isTransparent(style.backgroundColor);
const anyVisible = borderVisible.top || borderVisible.right || borderVisible.bottom || borderVisible.left || outlineVisible || bgVisible;
if (anyVisible) {
// Resolve padding to px (jsdom returns raw "1.5rem" etc., not the
// computed px value; parseFloat would strip the unit and treat
// 1.5rem as 1.5px, false-flagging legitimate insets).
const pad = {
top: resolveLengthPx(style.paddingTop, fontSize) ?? 0,
right: resolveLengthPx(style.paddingRight, fontSize) ?? 0,
bottom: resolveLengthPx(style.paddingBottom, fontSize) ?? 0,
left: resolveLengthPx(style.paddingLeft, fontSize) ?? 0,
};
const PAD_THRESHOLD = 2;
// Children-insulate-this-side: a side is insulated if ANY direct
// child has its own padding ≥ 4px on that side. Rationale: in
// typical flow, only the first/last (or leftmost/rightmost)
// children actually sit at the parent's edges. If even one of
// them has its own padding, the visual flush is broken on that
// side. Classic example: a column-flow card frame where the
// top child (header) has padding-top:12 and the bottom child
// (footer) has padding-bottom:8 — the parent's padding:0 doesn't
// matter; nothing is actually flush. The `any-child-insulates`
// heuristic accepts some false negatives (a card with one heavily
// padded middle child won't flag) for far fewer false positives.
const CHILD_INSULATE_THRESHOLD = 4;
const childrenInsulate = { top: false, right: false, bottom: false, left: false };
for (const child of el.children) {
let childStyle = null;
if (win && typeof win.getComputedStyle === 'function') {
try { childStyle = win.getComputedStyle(child); } catch {}
}
if (!childStyle && typeof getComputedStyle === 'function') {
try { childStyle = getComputedStyle(child); } catch {}
}
if (!childStyle) continue;
const childPad = {
top: resolveLengthPx(childStyle.paddingTop, fontSize) ?? 0,
right: resolveLengthPx(childStyle.paddingRight, fontSize) ?? 0,
bottom: resolveLengthPx(childStyle.paddingBottom, fontSize) ?? 0,
left: resolveLengthPx(childStyle.paddingLeft, fontSize) ?? 0,
};
for (const s of ['top', 'right', 'bottom', 'left']) {
if (childPad[s] >= CHILD_INSULATE_THRESHOLD) childrenInsulate[s] = true;
}
}
const flushSides = [];
for (const side of ['top', 'right', 'bottom', 'left']) {
const sideBounded = borderVisible[side] || outlineVisible || bgVisible;
if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side]) {
flushSides.push(side);
}
}
if (flushSides.length > 0) {
// Confirm at least one direct child has substantial text content
// (> 4 chars). Without this, the flush is harmless: e.g. an
// image-only card.
let hasTextChild = false;
for (const child of el.children) {
const childText = (child.textContent || '').trim();
if (childText.length > 4) { hasTextChild = true; break; }
}
if (hasTextChild) {
const cls = (typeof el.className === 'string' && el.className.trim())
? el.className.trim().split(/\s+/)[0]
: '';
const boundaryParts = [];
const borderSidesVisible = ['top', 'right', 'bottom', 'left'].filter(s => borderVisible[s]);
if (borderSidesVisible.length === 4) boundaryParts.push('border');
else if (borderSidesVisible.length > 0) boundaryParts.push(`border-${borderSidesVisible.join('/')}`);
if (outlineVisible) boundaryParts.push('outline');
if (bgVisible) boundaryParts.push('bg');
const sidesLabel = flushSides.length === 4 ? 'all sides' : flushSides.join('/');
const ident = cls
? `<${tag.toLowerCase()}> "${cls}"`
: `<${tag.toLowerCase()}>`;
findings.push({
id: 'cramped-padding',
snippet: `${ident}: children flush against ${boundaryParts.join('+')} on ${sidesLabel} (no inset)`,
});
}
}
}
}
}
// --- Body text touching viewport edge --- (browser-only: needs rect)
// Catches the failure mode where the agent ships body paragraphs
// with NO container providing horizontal padding — text bleeds
@@ -1804,6 +2093,20 @@ function checkQuality(opts) {
}
}
// --- Crushed letter spacing (mirror of wide-tracking) ---
// Tracking pulled tighter than ~-0.05em crushes characters into each other.
// Optical tightening that display type legitimately wants (around -0.02em)
// stays well above this floor.
if (hasDirectText && textLen > 20 && fontSize > 0) {
if (letterSpacingPx != null && letterSpacingPx < 0) {
const trackingEm = letterSpacingPx / fontSize;
if (trackingEm <= -0.05) {
const excerpt = (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 40);
findings.push({ id: 'extreme-negative-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em — "${excerpt}"` });
}
}
}
return findings;
}
@@ -1820,7 +2123,7 @@ function checkElementQualityDOM(el) {
const rect = el.getBoundingClientRect();
const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth });
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth, win: typeof window !== 'undefined' ? window : null });
}
// Pure page-level skipped-heading walk. Takes a Document so it works in both
@@ -1862,7 +2165,7 @@ function checkElementQuality(el, style, tag, window) {
const fontSize = resolveFontSizePx(el, window);
const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null, win: window });
}
function checkElementBorders(tag, style, overrides, resolvedRadius) {
@@ -2303,40 +2606,213 @@ function checkPageLayout(doc, win) {
}
}
// Everything centered
const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, li, div, button');
let centeredCount = 0;
let totalText = 0;
for (const el of textEls) {
const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length >= 3);
if (!hasDirectText) continue;
totalText++;
let cur = el;
let isCentered = false;
while (cur && cur.nodeType === 1) {
const rawStyle = cur.getAttribute?.('style') || '';
const cls = cur.getAttribute?.('class') || '';
if (/text-align\s*:\s*center/i.test(rawStyle) || /\btext-center\b/.test(cls)) {
isCentered = true;
break;
}
if (cur.tagName === 'BODY') break;
cur = cur.parentElement;
}
if (isCentered) centeredCount++;
}
if (totalText >= 5 && centeredCount / totalText > 0.7) {
findings.push({
id: 'everything-centered',
snippet: `${centeredCount}/${totalText} text elements centered (${Math.round(centeredCount / totalText * 100)}%)`,
});
}
return findings;
}
// ─── Cream / beige palette (the default "tasteful" AI surface) ────────────────
// A warm, lightly-tinted off-white page background — light, with R≥G≥B and a
// small warm tint (not white, not a strong color). The current reflex surface.
function isCreamColor(rgb) {
if (!rgb) return false;
const { r, g, b } = rgb;
if (Math.min(r, g, b) < 209) return false; // must be light
if (!(r >= g && g >= b)) return false; // warm ordering
const warmth = r - b;
return warmth >= 6 && warmth <= 48; // tinted, not white, not strong
}
// Tailwind background utilities that render as a warm off-white surface. The
// static engine doesn't fetch Tailwind's CSS, so a `bg-amber-50` on <body>
// resolves to nothing in computed style — catch it from the class list
// instead. Candidate tokens map to their actual Tailwind hex and are still
// filtered through isCreamColor, so neutral grays (stone) and over-saturated
// shades drop out on their own.
const TAILWIND_BG_HEX = {
'bg-amber-50': '#fffbeb', 'bg-amber-100': '#fef3c7',
'bg-orange-50': '#fff7ed', 'bg-orange-100': '#ffedd5',
'bg-yellow-50': '#fefce8',
'bg-stone-50': '#fafaf9', 'bg-stone-100': '#f5f5f4', 'bg-stone-200': '#e7e5e4',
};
function creamFromClassList(cls) {
if (!cls) return null;
// Arbitrary value: bg-[#f5f0e6] / bg-[rgb(245_240_230)] (underscores = spaces).
const arb = cls.match(/\bbg-\[([^\]]+)\]/);
if (arb && isCreamColor(parseAnyColor(arb[1].replace(/_/g, ' ')))) return `bg-[${arb[1]}]`;
// Named warm-light utilities.
for (const [tok, hex] of Object.entries(TAILWIND_BG_HEX)) {
if (new RegExp(`(^|\\s)${tok}($|\\s)`).test(cls) && isCreamColor(parseAnyColor(hex))) return tok;
}
return null;
}
function checkCreamPalette(doc, win) {
const findings = [];
const body = doc.body || (doc.querySelector ? doc.querySelector('body') : null);
if (!body) return findings;
const html = doc.documentElement;
const getCS = (el) => (win ? win.getComputedStyle(el) : getComputedStyle(el));
// 1. Computed background — covers inline / <style> / linked CSS, and Tailwind
// once it's actually rendered (browser path).
let bg = readOwnBackgroundColor(body, getCS(body));
if (!bg || bg.a === 0) {
if (html) bg = readOwnBackgroundColor(html, getCS(html));
}
if (isCreamColor(bg)) {
findings.push({ id: 'cream-palette', snippet: `cream/beige page background rgb(${bg.r}, ${bg.g}, ${bg.b})` });
return findings;
}
// 2. Tailwind class fallback — for the static path, where utility classes
// never resolve to computed CSS.
for (const el of [body, html]) {
const tok = creamFromClassList(el && el.getAttribute ? el.getAttribute('class') : '');
if (tok) {
findings.push({ id: 'cream-palette', snippet: `cream/beige page background (Tailwind ${tok})` });
break;
}
}
return findings;
}
// ─── Oversized hero headline ────────────────────────────────────────────────
// Fires when a *long* headline is set at display size, so a full sentence ends
// up dominating the viewport. A punchy one- or two-word headline at the same
// size is a legitimate stylistic choice and must pass — length, not size
// alone, is the tell.
const OVERSIZED_H1_FONT_PX = 72;
const OVERSIZED_H1_MIN_CHARS = 40;
function checkOversizedH1({ tag, fontSize, headingText }) {
if (tag !== 'h1') return [];
const textLen = headingText.length;
if (fontSize >= OVERSIZED_H1_FONT_PX && textLen >= OVERSIZED_H1_MIN_CHARS) {
return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars "${headingText.slice(0, 60)}"` }];
}
return [];
}
function checkElementOversizedH1(el, style, tag, window) {
if (tag !== 'h1') return [];
const fontSize = resolveFontSizePx(el, window);
const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
return checkOversizedH1({ tag, fontSize, headingText });
}
function checkElementOversizedH1DOM(el) {
const tag = el.tagName.toLowerCase();
if (tag !== 'h1') return [];
const style = getComputedStyle(el);
const fontSize = parseFloat(style.fontSize) || 0;
const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
return checkOversizedH1({ tag, fontSize, headingText });
}
// ─── GPT tell: hairline border + wide diffuse shadow (gated --gpt) ────────────
function shadowMaxBlurPx(boxShadow) {
if (!boxShadow || boxShadow === 'none') return 0;
let maxBlur = 0;
// Split into layers on commas not inside parentheses (rgba(...) etc.).
for (const layer of boxShadow.split(/,(?![^()]*\))/)) {
// Strip colors and keywords (rgba()/hsl()/hex/named/inset/px), leaving the
// ordered length tokens: offsetX offsetY blur [spread]. Static jsdom keeps
// unitless zeros ("0 0 24px"); browsers normalize to px ("0px 0px 24px") —
// both reduce to the same numbers here.
const cleaned = layer.replace(/rgba?\([^)]*\)|hsla?\([^)]*\)|#[0-9a-f]+|\b[a-z]+\b/gi, ' ');
const nums = [...cleaned.matchAll(/-?\d*\.?\d+/g)].map(m => parseFloat(m[0]));
if (nums.length >= 3) maxBlur = Math.max(maxBlur, nums[2]);
}
return maxBlur;
}
function checkGptThinBorderWideShadow({ borderWidths, boxShadow }) {
const maxBorder = Math.max(0, ...borderWidths);
const hasThinBorder = maxBorder > 0 && maxBorder <= 1.5;
const blur = shadowMaxBlurPx(boxShadow);
if (hasThinBorder && blur >= 16) {
return [{ id: 'gpt-thin-border-wide-shadow', snippet: `${maxBorder}px border + ${Math.round(blur)}px shadow blur` }];
}
return [];
}
function borderWidthsFromStyle(style) {
return [
parseFloat(style.borderTopWidth) || 0,
parseFloat(style.borderRightWidth) || 0,
parseFloat(style.borderBottomWidth) || 0,
parseFloat(style.borderLeftWidth) || 0,
];
}
function checkElementGptBorderShadow(el, style) {
return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
}
function checkElementGptBorderShadowDOM(el) {
const style = getComputedStyle(el);
return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
}
// ─── Clipped overflow container ───────────────────────────────────────────────
// A clipping container (overflow hidden/clip, not a scroll region) wrapping an
// absolutely/fixed-positioned descendant clips popovers/menus that must escape.
function classSelector(el) {
const cls = (el.getAttribute ? el.getAttribute('class') : el.className) || '';
const tokens = String(cls).trim().split(/\s+/).filter(Boolean);
const tag = el.tagName ? el.tagName.toLowerCase() : 'el';
return tokens.length ? `${tag}.${tokens.join('.')}` : tag;
}
function checkClippedOverflow(el, style, getStyle) {
const clips = (v) => v === 'hidden' || v === 'clip';
const scrolls = (v) => v === 'auto' || v === 'scroll';
const ox = style.overflowX || '', oy = style.overflowY || '', ov = style.overflow || '';
const anyClip = clips(ox) || clips(oy) || clips(ov);
const anyScroll = scrolls(ox) || scrolls(oy) || scrolls(ov);
if (!anyClip || anyScroll) return [];
if (!el.querySelectorAll) return [];
for (const child of el.querySelectorAll('*')) {
const pos = (getStyle(child).position) || '';
if (pos === 'absolute' || pos === 'fixed') {
return [{ id: 'clipped-overflow-container', snippet: `${classSelector(el)} clips a positioned child` }];
}
}
return [];
}
function checkElementClippedOverflow(el, style, tag, window) {
return checkClippedOverflow(el, style, (n) => window.getComputedStyle(n));
}
function checkElementClippedOverflowDOM(el) {
const style = getComputedStyle(el);
return checkClippedOverflow(el, style, (n) => getComputedStyle(n));
}
// ─── Text overflow (browser-only: needs scrollWidth/clientWidth) ──────────────
const TEXT_OVERFLOW_SKIP_TAGS = new Set(['pre', 'code', 'textarea', 'svg', 'canvas', 'select', 'option', 'marquee']);
function checkElementTextOverflowDOM(el) {
const tag = el.tagName.toLowerCase();
if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
// Only the element that actually owns overflowing text — not its ancestors,
// which inherit a wider scrollWidth from the spilling descendant.
const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
if (!hasDirectText) return [];
const style = getComputedStyle(el);
const isScrollRegion = (s) => /(auto|scroll)/.test(s.overflowX || '') || /(auto|scroll)/.test(s.overflow || '');
if (isScrollRegion(style)) return [];
// A scrollable ancestor means this overflow is intentional and scrollable.
for (let p = el.parentElement; p; p = p.parentElement) {
if (isScrollRegion(getComputedStyle(p))) return [];
}
const delta = el.scrollWidth - el.clientWidth;
if (el.clientWidth > 0 && delta >= 16) {
return [{ id: 'text-overflow', snippet: `${classSelector(el)} overflows its box by ${Math.round(delta)}px` }];
}
return [];
}
// --- cli/engine/browser/injected/index.mjs ---
const IS_BROWSER = typeof window !== 'undefined';
@@ -2349,8 +2825,21 @@ if (IS_BROWSER) {
const EXTENSION_MODE = (_myScript && _myScript.dataset.impeccableExtension === 'true')
|| document.documentElement.dataset.impeccableExtension === 'true';
const BRAND_COLOR = 'oklch(55% 0.25 350)';
const BRAND_COLOR_HOVER = 'oklch(45% 0.25 350)';
// Kinpaku gold — pinned to the site's brand token (see
// site/styles/kinpaku-tokens.css --ks-kinpaku). Keep this in sync with
// the picker's C.brand in skill/scripts/live-browser.js and the kit's
// picker section in site/styles/kinpaku-kit.css.
//
// One color across both light and dark host pages. The outline is a
// 2px gesture pointing at an element + a labeled tag — it's a marker,
// not body text, so it doesn't need WCAG AA against the page. The
// label text inside the gold tag is dark (LABEL_INK) which has ~16:1
// against the leaf gold, so reading the rule name is solid in both
// modes. Hover deepens the gold (preserves chroma — never drops it,
// dropping chroma washes the gold into a sand/olive tone).
const BRAND_COLOR = 'oklch(84% 0.19 80.46)';
const BRAND_COLOR_HOVER = 'oklch(74% 0.18 80)';
const LABEL_INK = 'oklch(4% 0.004 95)';
const LABEL_BG = BRAND_COLOR;
const OUTLINE_COLOR = BRAND_COLOR;
@@ -2618,7 +3107,7 @@ if (IS_BROWSER) {
display: 'flex', alignItems: 'center',
whiteSpace: 'nowrap',
fontSize: '11px', fontWeight: '600', letterSpacing: '0.02em',
color: 'white', lineHeight: '14px',
color: LABEL_INK, lineHeight: '14px',
background: LABEL_BG,
fontFamily: 'system-ui, sans-serif',
borderRadius: '4px 4px 0 0',
@@ -2738,7 +3227,7 @@ if (IS_BROWSER) {
banner.className = 'impeccable-overlay impeccable-banner';
Object.assign(banner.style, {
position: 'fixed', top: '0', left: '0', right: '0', zIndex: '100000',
background: LABEL_BG, color: 'white',
background: LABEL_BG, color: LABEL_INK,
fontFamily: 'system-ui, sans-serif', fontSize: '13px',
display: 'flex', alignItems: 'center', pointerEvents: 'auto',
height: '36px', overflow: 'hidden', maxWidth: '100vw',
@@ -3563,12 +4052,12 @@ if (IS_BROWSER) {
}
console.group(
`%c[impeccable] ${allFindings.length} anti-pattern${allFindings.length === 1 ? '' : 's'} found`,
'color: oklch(60% 0.25 350); font-weight: bold'
'color: oklch(84% 0.19 80.46); font-weight: bold'
);
for (const { el, findings } of allFindings) {
for (const f of findings) {
console.log(`%c${f.type || f.id}%c ${f.detail || f.snippet}`,
'color: oklch(55% 0.25 350); font-weight: bold', 'color: inherit', el);
'color: oklch(84% 0.19 80.46); font-weight: bold', 'color: inherit', el);
}
}
console.groupEnd();
@@ -3589,6 +4078,10 @@ if (IS_BROWSER) {
const groupMap = new Map();
const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
// Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
// real browser env (detector page, live overlay, extension) running every
// check is free, so we always surface them; the gating is purely a CLI
// output concern, applied in the Node engines' detect* return paths.
for (const el of document.querySelectorAll('*')) {
// Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
@@ -3610,11 +4103,23 @@ if (IS_BROWSER) {
...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementHeroEyebrowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementOversizedH1DOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
].filter(f => _ruleOk(f.type));
addBrowserFindings(groupMap, el, findings);
// Hero eyebrow: the offending element is the eyebrow above the heading,
// not the heading itself — highlight the previous sibling instead.
const eyebrowFindings = checkElementHeroEyebrowDOM(el)
.map(f => ({ type: f.id, detail: f.snippet }))
.filter(f => _ruleOk(f.type));
if (eyebrowFindings.length > 0 && el.previousElementSibling) {
addBrowserFindings(groupMap, el.previousElementSibling, eyebrowFindings);
}
}
const pageLevelFindings = [];
@@ -3646,6 +4151,14 @@ if (IS_BROWSER) {
addBrowserFindings(groupMap, document.body, qualityFindings);
}
const creamFindings = checkCreamPalette(document)
.map(f => ({ type: f.id, detail: f.snippet }))
.filter(f => _ruleOk(f.type));
if (creamFindings.length > 0) {
pageLevelFindings.push(...creamFindings);
addBrowserFindings(groupMap, document.body, creamFindings);
}
// Regex-on-HTML checks (shared with Node)
// Clone the document and strip impeccable-live overlay nodes before the
// regex scan, so the inspector's own inline styles (transitions on top/
cli/engine/engines/browser/detect-url.mjs
+2 -1
View File
@@ -3,6 +3,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { finding } from '../../findings.mjs';
import { filterByProviders } from '../../registry/antipatterns.mjs';
import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
@@ -212,7 +213,7 @@ async function detectUrl(url, options = {}) {
}, () => browser.close());
}
}
return results.map(f => finding(f.id, url, f.snippet));
return filterByProviders(results.map(f => finding(f.id, url, f.snippet)), options.providers);
}
async function createBrowserDetector(options = {}) {
cli/engine/engines/regex/detect-text.mjs
+136 -21
View File
@@ -1,6 +1,7 @@
import { GENERIC_FONTS } from '../../shared/constants.mjs';
import { isFullPage } from '../../shared/page.mjs';
import { finding } from '../../findings.mjs';
import { filterByProviders } from '../../registry/antipatterns.mjs';
import { profileFindings, profileStep } from '../../profile/profiler.mjs';
// ---------------------------------------------------------------------------
@@ -11,6 +12,17 @@ const hasRounded = (line) => /\brounded(?:-\w+)?\b/.test(line);
const hasBorderRadius = (line) => /border-radius/i.test(line);
const isSafeElement = (line) => /<(?:blockquote|nav[\s>]|pre[\s>]|code[\s>]|a\s|input[\s>]|span[\s>])/i.test(line);
/** Strip HTML to plain text — drops script/style/comments/tags so
* content-text analyzers don't false-positive on code or CSS. */
function stripHtmlToText(html) {
return html
.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
.replace(/<!--[\s\S]*?-->/g, ' ')
.replace(/<[^>]+>/g, ' ')
.replace(/\s+/g, ' ');
}
function isNeutralBorderColor(str) {
const m = str.match(/solid\s+(#[0-9a-f]{3,8}|rgba?\([^)]+\)|\w+)/i);
if (!m) return false;
@@ -57,16 +69,12 @@ const REGEX_MATCHERS = [
test: (m, line) => +m[1] >= 3 && hasBorderRadius(line),
fmt: (m) => m[0] },
// --- Overused font ---
{ id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica|Fraunces|Geist Sans|Geist Mono|Geist|Mona Sans|Plus Jakarta Sans|Space Grotesk|Recoleta|Instrument Sans)\b/gi,
{ id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica|Fraunces|Geist Sans|Geist Mono|Geist|Mona Sans|Plus Jakarta Sans|Space Grotesk|Recoleta|Instrument Sans|Instrument Serif)\b/gi,
test: () => true,
fmt: (m) => m[0] },
{ id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat|Fraunces|Plus\+Jakarta\+Sans|Space\+Grotesk|Instrument\+Sans|Mona\+Sans|Geist)\b/gi,
{ id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat|Fraunces|Plus\+Jakarta\+Sans|Space\+Grotesk|Instrument\+Sans|Instrument\+Serif|Mona\+Sans|Geist)\b/gi,
test: () => true,
fmt: (m) => `Google Fonts: ${m[1].replace(/\+/g, ' ')}` },
// --- Pure black background ---
{ id: 'pure-black-white', regex: /background(?:-color)?\s*:\s*(#000000|#000|rgb\(0,\s*0,\s*0\))\b/gi,
test: () => true,
fmt: (m) => m[0] },
// --- Gradient text ---
{ id: 'gradient-text', regex: /background-clip\s*:\s*text|-webkit-background-clip\s*:\s*text/gi,
test: (m, line) => /gradient/i.test(line),
@@ -75,10 +83,6 @@ const REGEX_MATCHERS = [
{ id: 'gradient-text', regex: /\bbg-clip-text\b/g,
test: (m, line) => /\bbg-gradient-to-/i.test(line),
fmt: () => 'bg-clip-text + bg-gradient' },
// --- Tailwind pure black background ---
{ id: 'pure-black-white', regex: /\bbg-black\b/g,
test: () => true,
fmt: (m) => m[0] },
// --- Tailwind gray on colored bg ---
{ id: 'gray-on-color', regex: /\btext-(?:gray|slate|zinc|neutral|stone)-(\d+)\b/g,
test: (m, line) => /\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/.test(line),
@@ -124,6 +128,14 @@ const REGEX_MATCHERS = [
const found = m[1].match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
return `transition-property: ${found ? found.join(', ') : m[1].trim()}`;
} },
// --- Broken image: src="" or src="#" or src=" " ---
{ id: 'broken-image', regex: /<img\b[^>]*?\bsrc\s*=\s*(?:""|''|"\s+"|'\s+'|"#"|'#')/gi,
test: () => true,
fmt: (m) => m[0].slice(0, 100) },
// --- Broken image: <img> with no src attribute at all ---
{ id: 'broken-image', regex: /<img\b(?:(?!\bsrc\s*=)[^>])*>/gi,
test: (m) => !/\bsrc\s*=/i.test(m[0]),
fmt: (m) => m[0].slice(0, 100) },
];
const REGEX_ANALYZERS = [
@@ -197,18 +209,86 @@ const REGEX_ANALYZERS = [
const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0];
return [finding('monotonous-spacing', filePath, `~${dominant}px used ${maxCount}/${rounded.length} times (${Math.round(pct * 100)}%)`)];
},
// Everything centered (regex)
// Em-dash overuse: 5+ em-dashes or "--" in body text content
// (occasional em-dash use in prose is fine; the pattern fires only
// when count crosses into AI-cadence territory).
(content, filePath) => {
const lines = content.split('\n');
let centered = 0, total = 0;
for (const line of lines) {
if (/<(?:h[1-6]|p|div|li|button)\b[^>]*>/i.test(line) && line.trim().length > 20) {
total++;
if (/text-align\s*:\s*center/i.test(line) || /\btext-center\b/.test(line)) centered++;
const text = stripHtmlToText(content);
let count = 0;
const re = /[—]|--(?=\S)/g;
while (re.exec(text) !== null) count++;
if (count < 5) return [];
return [finding('em-dash-overuse', filePath, `${count} em-dashes in body text`)];
},
// Marketing buzzwords: SaaS phrase list
(content, filePath) => {
const text = stripHtmlToText(content);
const lower = text.toLowerCase();
const BUZZWORDS = [
'streamline your', 'empower your', 'supercharge your',
'unleash your', 'unleash the power', 'leverage the power',
'built for the modern', 'trusted by leading', 'trusted by the world',
'best-in-class', 'industry-leading', 'world-class', 'enterprise-grade',
'next-generation', 'cutting-edge', 'transform your business',
'revolutionize', 'game-changer', 'game changing',
'mission-critical', 'best of breed', 'future-proof', 'future proof',
'seamless experience', 'seamlessly integrate',
'drive engagement', 'drive growth', 'drive results',
'harness the power',
];
let count = 0;
let firstSample = '';
for (const phrase of BUZZWORDS) {
let from = 0;
while (true) {
const idx = lower.indexOf(phrase, from);
if (idx === -1) break;
count++;
if (!firstSample) {
firstSample = text.slice(Math.max(0, idx - 12), Math.min(text.length, idx + phrase.length + 12)).trim();
}
from = idx + phrase.length;
}
}
if (total < 5 || centered / total <= 0.7) return [];
return [finding('everything-centered', filePath, `${centered}/${total} text elements centered (${Math.round(centered / total * 100)}%)`)];
if (count === 0) return [];
return [finding('marketing-buzzword', filePath, `${count} buzzword phrase${count === 1 ? '' : 's'}: "${firstSample}"`)];
},
// Numbered section markers (01 / 02 / 03 ...)
(content, filePath) => {
const text = stripHtmlToText(content);
const re = /\b(0[1-9]|1[0-2])\b/g;
const seen = new Set();
let m;
while ((m = re.exec(text)) !== null) seen.add(m[1]);
if (seen.size < 3) return [];
const sorted = [...seen].sort();
let sequential = 0;
for (let i = 1; i < sorted.length; i++) {
if (parseInt(sorted[i], 10) === parseInt(sorted[i - 1], 10) + 1) sequential++;
}
if (sequential < 2) return [];
return [finding('numbered-section-markers', filePath, `Sequence: ${sorted.slice(0, 6).join(', ')}`)];
},
// Aphoristic cadence: manufactured-contrast + short-rebuttal
(content, filePath) => {
const text = stripHtmlToText(content);
const NOT_A_RE = /\bNot an? [a-z][^.!?]{1,40}[.!]\s+[A-Z][^.!?]{1,60}[.!]/g;
const SHORT_REBUTTAL_RE = /\b[A-Z][^.!?]{4,80}[.!]\s+(No|Just)\s+[a-z][^.!?]{2,60}[.!]/g;
let count = 0;
let firstSample = '';
let m;
NOT_A_RE.lastIndex = 0;
while ((m = NOT_A_RE.exec(text)) !== null) {
count++;
if (!firstSample) firstSample = m[0].trim().slice(0, 80);
}
SHORT_REBUTTAL_RE.lastIndex = 0;
while ((m = SHORT_REBUTTAL_RE.exec(text)) !== null) {
count++;
if (!firstSample) firstSample = m[0].trim().slice(0, 80);
}
if (count < 3) return [];
return [finding('aphoristic-cadence', filePath, `${count} aphoristic constructions: "${firstSample}"`)];
},
// Dark glow (page-level: dark bg + colored box-shadow with blur)
(content, filePath) => {
@@ -328,6 +408,36 @@ function runRegexMatchers(lines, filePath, lineOffset = 0, blockContext = null,
return findings;
}
/** Page-level analyzers that scan rendered text content (em-dash use,
* buzzword phrases, numbered section markers, aphoristic cadence).
* These are detector-agnostic — they work on any HTML/text source
* and don't need a parsed DOM. Exported so detectHtml can call them
* for `.html` files (which otherwise skip the regex engine). */
const TEXT_CONTENT_ANALYZER_IDS = [
'em-dash-overuse',
'marketing-buzzword',
'numbered-section-markers',
'aphoristic-cadence',
];
function runTextContentAnalyzers(content, filePath, options = {}) {
const profile = options?.profile;
if (!isFullPage(content)) return [];
// The 4 text-content analyzers are at indices 3-6 in REGEX_ANALYZERS.
const findings = [];
for (let i = 0; i < TEXT_CONTENT_ANALYZER_IDS.length; i++) {
const analyzer = REGEX_ANALYZERS[3 + i];
const ruleId = TEXT_CONTENT_ANALYZER_IDS[i];
findings.push(...profileFindings(profile, {
engine: 'regex',
phase: 'text-content',
ruleId,
target: filePath,
}, () => analyzer(content, filePath)));
}
return findings;
}
function detectText(content, filePath, options = {}) {
const profile = options?.profile;
const findings = [];
@@ -393,7 +503,10 @@ function detectText(content, filePath, options = {}) {
'single-font',
'flat-type-hierarchy',
'monotonous-spacing',
'everything-centered',
'em-dash-overuse',
'marketing-buzzword',
'numbered-section-markers',
'aphoristic-cadence',
'dark-glow',
];
for (let i = 0; i < REGEX_ANALYZERS.length; i++) {
@@ -407,14 +520,16 @@ function detectText(content, filePath, options = {}) {
}
}
return deduped;
return filterByProviders(deduped, options?.providers);
}
export {
REGEX_MATCHERS,
REGEX_ANALYZERS,
TEXT_CONTENT_ANALYZER_IDS,
extractStyleBlocks,
extractCSSinJS,
runRegexMatchers,
runTextContentAnalyzers,
detectText,
};
cli/engine/engines/static-html/css-cascade.mjs
+32
View File
@@ -241,6 +241,9 @@ const STATIC_DEFAULT_STYLE = {
borderBottomColor: 'rgb(0, 0, 0)',
borderLeftColor: 'rgb(0, 0, 0)',
borderRadius: '0px',
outlineWidth: '0px',
outlineColor: 'rgb(0, 0, 0)',
outlineStyle: 'none',
boxShadow: 'none',
fontFamily: '',
fontSize: '16px',
@@ -266,6 +269,9 @@ const STATIC_DEFAULT_STYLE = {
paddingLeft: '0px',
position: 'static',
display: '',
overflow: 'visible',
overflowX: 'visible',
overflowY: 'visible',
};
const STATIC_PROP_MAP = {
@@ -282,6 +288,9 @@ const STATIC_PROP_MAP = {
'border-right-color': 'borderRightColor',
'border-bottom-color': 'borderBottomColor',
'border-left-color': 'borderLeftColor',
'outline-width': 'outlineWidth',
'outline-color': 'outlineColor',
'outline-style': 'outlineStyle',
'box-shadow': 'boxShadow',
'font-family': 'fontFamily',
'font-size': 'fontSize',
@@ -305,6 +314,9 @@ const STATIC_PROP_MAP = {
'padding-left': 'paddingLeft',
'position': 'position',
'display': 'display',
'overflow': 'overflow',
'overflow-x': 'overflowX',
'overflow-y': 'overflowY',
};
const STATIC_NAMED_COLORS = {
@@ -511,6 +523,26 @@ function expandStaticDeclaration(prop, value) {
}
return out;
}
if (p === 'outline') {
// `outline` shorthand: width | style | color, in any order. Reuse the
// border parser for width + color, then sniff a style keyword from the
// tokens (solid|dashed|...). `outline: 0` (single-token zero) zeros
// the width and effectively hides the outline.
const tokens = splitCssTokens(v);
const parsed = parseStaticBorder(v);
const styleToken = tokens.find(t =>
/^(none|hidden|solid|dashed|dotted|double|groove|ridge|inset|outset)$/i.test(t)
);
const out = [];
if (parsed.width) out.push(['outlineWidth', parsed.width]);
if (parsed.color) out.push(['outlineColor', parsed.color]);
if (styleToken) out.push(['outlineStyle', styleToken.toLowerCase()]);
// `outline: 0` with no other tokens: explicit zero width.
if (!parsed.width && /^0(?:px|rem|em|%)?$/.test(v.trim())) {
out.push(['outlineWidth', '0px']);
}
return out;
}
const sideMatch = p.match(/^border-(top|right|bottom|left)$/);
if (sideMatch) {
const parsed = parseStaticBorder(v);
cli/engine/engines/static-html/detect-html.mjs
+36 -2
View File
@@ -7,13 +7,17 @@ import { finding } from '../../findings.mjs';
import { profileFindings, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
import {
checkElementBorders,
checkElementClippedOverflow,
checkElementColors,
checkElementGlow,
checkElementGptBorderShadow,
checkElementHeroEyebrow,
checkElementIconTile,
checkElementItalicSerif,
checkElementMotion,
checkElementOversizedH1,
checkElementQuality,
checkCreamPalette,
checkHtmlPatterns,
checkPageLayout,
checkPageQualityFromDoc,
@@ -21,7 +25,8 @@ import {
resolveBackground,
resolveBorderRadiusPx,
} from '../../rules/checks.mjs';
import { detectText } from '../regex/detect-text.mjs';
import { filterByProviders } from '../../registry/antipatterns.mjs';
import { detectText, runTextContentAnalyzers } from '../regex/detect-text.mjs';
import {
StaticDocument,
buildStaticStyleMap,
@@ -64,6 +69,20 @@ function checkStaticPageTypography(document, window) {
return findings;
}
function checkElementBrokenImage(el) {
const src = (el.getAttribute && el.getAttribute('src')) ?? el.attribs?.src;
// Missing src attribute entirely
if (src === undefined || src === null) {
return [{ id: 'broken-image', snippet: '<img> with no src attribute' }];
}
const trimmed = String(src).trim();
// Empty or placeholder-only src values
if (trimmed === '' || trimmed === '#') {
return [{ id: 'broken-image', snippet: `<img src="${src}">` }];
}
return [];
}
const STATIC_ELEMENT_RULES = [
{ id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window)) },
{ id: 'color-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementColors(el, style, tag, window, customPropMap, false) },
@@ -72,7 +91,11 @@ const STATIC_ELEMENT_RULES = [
{ id: 'icon-tile-stack', selector: 'h1,h2,h3,h4,h5,h6', run: (el, tag, _style, window) => checkElementIconTile(el, tag, window) },
{ id: 'italic-serif-display', selector: 'h1,h2', run: (el, tag, style) => checkElementItalicSerif(el, style, tag) },
{ id: 'hero-eyebrow-chip', selector: 'h1', run: (el, tag, style, window, customPropMap) => checkElementHeroEyebrow(el, style, tag, window, customPropMap) },
{ id: 'broken-image', selector: 'img', run: (el) => checkElementBrokenImage(el) },
{ id: 'quality-rules', selector: '*', run: (el, tag, style, window) => checkElementQuality(el, style, tag, window) },
{ id: 'oversized-h1', selector: 'h1', run: (el, tag, style, window) => checkElementOversizedH1(el, style, tag, window) },
{ id: 'clipped-overflow-container', selector: '*', run: (el, tag, style, window) => checkElementClippedOverflow(el, style, tag, window) },
{ id: 'gpt-thin-border-wide-shadow', selector: '*', run: (el, tag, style) => checkElementGptBorderShadow(el, style) },
];
async function detectHtml(filePath, options = {}) {
@@ -158,6 +181,9 @@ async function detectHtml(filePath, options = {}) {
for (const f of runPageCheck('layout-rules', () => checkPageLayout(document, window))) {
findings.push(finding(f.id, filePath, f.snippet));
}
for (const f of runPageCheck('cream-palette', () => checkCreamPalette(document, window))) {
findings.push(finding(f.id, filePath, f.snippet));
}
for (const f of runPageCheck('skipped-heading', () => checkPageQualityFromDoc(document))) {
findings.push(finding(f.id, filePath, f.snippet));
}
@@ -166,9 +192,17 @@ async function detectHtml(filePath, options = {}) {
))) {
findings.push(finding(f.id, filePath, f.snippet));
}
// Text-content analyzers (em-dash overuse, marketing buzzwords,
// numbered section markers, aphoristic cadence) live in the regex
// engine. Call them from here so .html files get the same coverage
// as .css/.tsx files. These are scoped to text content only and
// don't overlap with static-html's element/page rules.
for (const f of runPageCheck('text-content', () => runTextContentAnalyzers(html, filePath, options))) {
findings.push(finding(f.antipattern, filePath, f.snippet));
}
}
return findings;
return filterByProviders(findings, options.providers);
}
export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };
cli/engine/registry/antipatterns.mjs
+160 -19
View File
@@ -63,6 +63,15 @@ const ANTIPATTERNS = [
skillSection: 'Color & Contrast',
skillGuideline: 'AI color palette',
},
{
id: 'cream-palette',
category: 'slop',
name: 'Cream / beige palette',
description:
'A warm cream or beige page background has become the default "tasteful" AI surface, reached for by reflex. Choose a background that comes from a deliberate palette, not the safe warm off-white.',
skillSection: 'Color & Contrast',
skillGuideline: 'cream and beige as the default surface',
},
{
id: 'nested-cards',
category: 'slop',
@@ -81,15 +90,6 @@ const ANTIPATTERNS = [
skillSection: 'Layout & Space',
skillGuideline: 'same spacing everywhere',
},
{
id: 'everything-centered',
category: 'slop',
name: 'Everything centered',
description:
'Every text element is center-aligned. Left-aligned text with asymmetric layouts feels more designed. Center only hero sections and CTAs.',
skillSection: 'Layout & Space',
skillGuideline: 'Center everything',
},
{
id: 'bounce-easing',
category: 'slop',
@@ -145,17 +145,72 @@ const ANTIPATTERNS = [
skillSection: 'Typography',
skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
},
{
id: 'numbered-section-markers',
category: 'slop',
severity: 'advisory',
name: 'Numbered section markers (01 / 02 / 03)',
description:
'Numbered display markers as section labels (01, 02, 03) are the AI editorial scaffold one tier deeper than tracked eyebrow chips. If you find yourself reaching for them, choose a different section cadence.',
skillSection: 'Layout & Space',
skillGuideline: 'numbered section markers',
},
{
id: 'em-dash-overuse',
category: 'slop',
name: 'Em-dash overuse',
description:
'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
skillSection: 'Copy',
skillGuideline: 'no em dashes',
},
{
id: 'marketing-buzzword',
category: 'slop',
name: 'Marketing buzzword',
description:
'Generic SaaS phrases (streamline / empower / supercharge / world-class / enterprise-grade / next-generation / cutting-edge / etc) are instant AI tells. Pick a specific verb and noun that says what the product literally does.',
skillSection: 'Copy',
skillGuideline: 'marketing buzzwords',
},
{
id: 'aphoristic-cadence',
category: 'slop',
name: 'Aphoristic-cadence copy',
description:
'Three or more sections landing on a short rebuttal sentence ("X. No Y." / "X. Just Y.") or a manufactured-contrast aphorism ("Not a feature. A platform.") reads as AI cadence, not voice. Once is fine; the pattern is the tell.',
skillSection: 'Copy',
skillGuideline: 'aphoristic cadence',
},
{
id: 'oversized-h1',
category: 'slop',
name: 'Oversized hero headline',
description:
'A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold. A punchy one- or two-word headline at that size is fine — the problem is a long headline blown up too large. Set long headlines smaller, or tighten the copy.',
skillSection: 'Typography',
skillGuideline: 'long headline set at display size',
},
{
id: 'extreme-negative-tracking',
category: 'slop',
name: 'Crushed letter spacing',
description:
'Letter-spacing pulled tighter than the point where characters keep their own shapes costs legibility. Tighten display type optically, not destructively.',
skillSection: 'Typography',
skillGuideline: 'letter spacing crushed past legibility',
},
{
id: 'broken-image',
category: 'quality',
name: 'Broken or placeholder image',
description:
'<img> tags with empty src, missing src, or placeholder values ship as broken-image boxes. Use real images, generated assets, or remove the tag.',
skillSection: 'Imagery',
skillGuideline: 'broken image references',
},
// ── Quality: general design and accessibility issues ──
{
id: 'pure-black-white',
category: 'quality',
name: 'Pure black background',
description:
'Pure #000000 as a background color looks harsh and unnatural. Tint it slightly toward your brand hue (e.g., oklch(12% 0.01 250)) for a more refined feel.',
skillSection: 'Color & Contrast',
skillGuideline: 'pure black (#000)',
},
{
id: 'gray-on-color',
category: 'quality',
@@ -195,7 +250,9 @@ const ANTIPATTERNS = [
category: 'quality',
name: 'Cramped padding',
description:
'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.',
'Text is too close to the edge of its container. Two shapes: (1) an element with its own text where the padding is too low for the font size, and (2) a wrapper with text-bearing children and near-zero padding against a visible boundary (border, outline, or non-transparent background) — children land flush against the boundary line. Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers.',
skillSection: 'Layout & Space',
skillGuideline: 'inside bordered or colored containers',
},
{
id: 'body-text-viewport-edge',
@@ -248,6 +305,70 @@ const ANTIPATTERNS = [
description:
'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
},
{
id: 'text-overflow',
category: 'quality',
name: 'Content overflowing its container',
description:
'Content renders wider than its container, spilling out or forcing a horizontal scrollbar. Let text wrap, constrain widths, or give the region a deliberate scroll affordance.',
skillSection: 'Layout & Space',
skillGuideline: 'content wider than its container',
},
{
id: 'clipped-overflow-container',
category: 'quality',
name: 'Positioned child clipped by overflow container',
description:
'A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape. Let the overflow be visible, or move the positioned layer out of the clip.',
skillSection: 'Layout & Space',
skillGuideline: 'overflow container clipping positioned children',
},
// ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
{
id: 'gpt-thin-border-wide-shadow',
category: 'slop',
severity: 'advisory',
gated: 'gpt',
name: 'Hairline border with wide shadow',
description:
'A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once.',
skillSection: 'Visual Details',
skillGuideline: 'hairline border plus wide diffuse shadow',
},
{
id: 'repeating-stripes-gradient',
category: 'slop',
severity: 'advisory',
gated: 'gpt',
name: 'Repeating-gradient stripes',
description:
'Repeating-gradient stripes used as surface decoration are a recurring generated-UI signature. Reach for a deliberate texture or leave the surface plain.',
skillSection: 'Visual Details',
skillGuideline: 'repeating-gradient decorative stripes',
},
{
id: 'theater-slop-phrase',
category: 'slop',
severity: 'advisory',
gated: 'gpt',
name: 'Theater framing copy',
description:
'Dismissing something as "theater" is a recurring generated-copy tic. Say plainly what the thing does or does not do.',
skillSection: 'Copy',
skillGuideline: 'theater framing copy',
},
{
id: 'image-hover-transform',
category: 'slop',
severity: 'advisory',
gated: 'gemini',
name: 'Image hover transform',
description:
'Scaling or rotating an image on hover is a recurring generated-UI signature. Let imagery sit still, or use a subtler, purposeful interaction.',
skillSection: 'Motion',
skillGuideline: 'image scale or rotate on hover',
},
];
const RULE_ENGINE_SUPPORT = {
@@ -269,10 +390,30 @@ function getRuleEngineSupport(engine) {
return RULE_ENGINE_SUPPORT[engine] || new Set();
}
// Set of provider tags that gate rules off by default (e.g. 'gpt', 'gemini').
const GATED_PROVIDERS = new Set(
ANTIPATTERNS.map(rule => rule.gated).filter(Boolean),
);
// Drop findings for rules gated behind a provider tag unless that provider
// was explicitly enabled (CLI --gpt / --gemini). Non-gated findings always
// pass through. `findings` carry the rule id on `.antipattern`.
function filterByProviders(findings, providers = []) {
const enabled = new Set(providers || []);
if (!GATED_PROVIDERS.size) return findings;
return findings.filter(f => {
const rule = getAntipattern(f.antipattern);
if (!rule || !rule.gated) return true;
return enabled.has(rule.gated);
});
}
export {
ANTIPATTERNS,
RULE_ENGINE_SUPPORT,
GATED_PROVIDERS,
getAntipattern,
getRulesForCategory,
getRuleEngineSupport,
filterByProviders,
};
cli/engine/rules/checks.mjs
+416 -48
View File
@@ -78,11 +78,6 @@ function checkColors(opts) {
}
const findings = [];
// Pure black background (only solid or near-solid, not semi-transparent overlays)
if (bgColor && bgColor.a >= 0.9 && bgColor.r === 0 && bgColor.g === 0 && bgColor.b === 0) {
findings.push({ id: 'pure-black-white', snippet: '#000000 background' });
}
if (hasDirectText && textColor && !isEmojiOnly) {
// Run background-dependent checks against either a solid bg or, if the
// ancestor is a gradient, against every gradient stop (use the worst case).
@@ -138,9 +133,6 @@ function checkColors(opts) {
// Tailwind class checks
if (classList) {
const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ');
if (/\bbg-black\b(?!\/)/.test(classStr)) {
findings.push({ id: 'pure-black-white', snippet: 'bg-black' });
}
const grayMatch = classStr.match(/\btext-(?:gray|slate|zinc|neutral|stone)-\d+\b/);
const colorBgMatch = classStr.match(/\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/);
@@ -456,12 +448,6 @@ function checkHtmlPatterns(html) {
// --- Color ---
// Pure black background
const pureBlackBgRe = /background(?:-color)?\s*:\s*(?:#000000|#000|rgb\(\s*0,\s*0,\s*0\s*\))\b/gi;
if (pureBlackBgRe.test(html)) {
findings.push({ id: 'pure-black-white', snippet: 'Pure #000 background' });
}
// AI color palette: purple/violet
const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
if (purpleHexRe.test(html)) {
@@ -578,6 +564,39 @@ function checkHtmlPatterns(html) {
}
}
// --- Provider tells (gated): repeating-gradient stripes (GPT) ---
if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
}
// --- Provider tells (gated): "X theater" framing copy (GPT) ---
// Lives here (regex-on-HTML) rather than in the text-content analyzers so it
// runs in the bundled browser path too, not just the CLI/static path.
{
const bodyText = html
.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
.replace(/<[^>]+>/g, ' ');
const tm = /\b(\w+)\s+theater\b/i.exec(bodyText);
if (tm) findings.push({ id: 'theater-slop-phrase', snippet: `"${tm[0].trim()}"` });
}
// --- Provider tells (gated): image hover transform (Gemini) ---
// A CSS `img...:hover { transform: ... }` rule, or a Tailwind hover:scale /
// hover:rotate / hover:translate utility on an <img>. Each distinct
// mechanism is its own finding.
const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
if (imgHoverCss.test(html)) {
findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
}
const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
let im;
while ((im = imgTagRe.exec(html)) !== null) {
if (/\bhover:(?:scale|rotate|translate|skew)-/.test(im[1])) {
findings.push({ id: 'image-hover-transform', snippet: 'Tailwind hover transform on <img>' });
}
}
return findings;
}
@@ -1224,7 +1243,7 @@ function resolveLengthPx(value, fontSizePx) {
// Both adapters resolve font-size, line-height and letter-spacing to pixels
// before calling this so the pure function only deals with numbers.
function checkQuality(opts) {
const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0 } = opts;
const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
const findings = [];
// Skip browser extension injected elements
const elId = el.id || '';
@@ -1275,6 +1294,155 @@ function checkQuality(opts) {
}
}
// --- Flush against a visible boundary ---
// Fires when a container has a visible boundary (border, outline, OR a
// non-transparent background) AND near-zero padding on the bounded
// side(s) AND text-bearing children land flush against the boundary.
//
// Distinct from cramped-padding: that rule needs the element itself to
// have direct text (hasDirectText). This rule targets the OPPOSITE
// shape — a container with NO direct text, only children — which is
// exactly what cramped-padding misses (a section wrapping a label +
// list lands a free pass).
//
// The classic shape: agent writes `padding: 28px 0 0` shorthand on a
// section that also has a border, zeroing horizontal padding so the
// text-bearing children touch the side borders. Background and
// outline count too: a colored card with zero padding has the same
// visual failure mode.
{
const FLUSH_SKIP_TAGS = new Set(['HTML', 'BODY', 'MAIN', 'HEADER', 'FOOTER', 'NAV', 'ARTICLE', 'ASIDE', 'BUTTON', 'A', 'LABEL', 'SUMMARY', 'CODE', 'PRE', 'INPUT', 'TEXTAREA', 'SELECT', 'FORM', 'FIGURE', 'TABLE', 'TBODY', 'THEAD', 'TR', 'TD', 'TH']);
const upperTag = tag ? tag.toUpperCase() : '';
const elPosition = style.position || '';
if (
!FLUSH_SKIP_TAGS.has(upperTag) &&
!hasDirectText &&
!['fixed', 'absolute'].includes(elPosition) &&
el.children && el.children.length > 0
) {
const isTransparent = (c) =>
!c || c === 'transparent' || c === 'rgba(0, 0, 0, 0)' ||
/^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(c);
const borderW = {
top: parseFloat(style.borderTopWidth) || 0,
right: parseFloat(style.borderRightWidth) || 0,
bottom: parseFloat(style.borderBottomWidth) || 0,
left: parseFloat(style.borderLeftWidth) || 0,
};
const borderVisible = {
top: borderW.top > 0 && !isTransparent(style.borderTopColor),
right: borderW.right > 0 && !isTransparent(style.borderRightColor),
bottom: borderW.bottom > 0 && !isTransparent(style.borderBottomColor),
left: borderW.left > 0 && !isTransparent(style.borderLeftColor),
};
// Outline detection. jsdom decomposes `border` shorthand into
// border{Top,…}Width/Color but does NOT decompose `outline` —
// the longhands come back empty when the value was set via the
// shorthand. Fall back to parsing `style.outline` ourselves.
let outlineW = parseFloat(style.outlineWidth) || 0;
let outlineStyleVal = style.outlineStyle || '';
let outlineColorVal = style.outlineColor || '';
if (!outlineW && style.outline) {
const wMatch = style.outline.match(/(\d+(?:\.\d+)?)\s*px/);
if (wMatch) outlineW = parseFloat(wMatch[1]) || 0;
if (!outlineStyleVal) {
outlineStyleVal = /\b(solid|dashed|dotted|double|groove|ridge|inset|outset)\b/.test(style.outline) ? 'solid' : '';
}
if (!outlineColorVal) {
const cMatch = style.outline.match(/(rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}|[a-zA-Z]+)\s*$/);
if (cMatch) outlineColorVal = cMatch[1];
}
}
const outlineVisible = outlineW > 0 && !isTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
const bgVisible = !isTransparent(style.backgroundColor);
const anyVisible = borderVisible.top || borderVisible.right || borderVisible.bottom || borderVisible.left || outlineVisible || bgVisible;
if (anyVisible) {
// Resolve padding to px (jsdom returns raw "1.5rem" etc., not the
// computed px value; parseFloat would strip the unit and treat
// 1.5rem as 1.5px, false-flagging legitimate insets).
const pad = {
top: resolveLengthPx(style.paddingTop, fontSize) ?? 0,
right: resolveLengthPx(style.paddingRight, fontSize) ?? 0,
bottom: resolveLengthPx(style.paddingBottom, fontSize) ?? 0,
left: resolveLengthPx(style.paddingLeft, fontSize) ?? 0,
};
const PAD_THRESHOLD = 2;
// Children-insulate-this-side: a side is insulated if ANY direct
// child has its own padding ≥ 4px on that side. Rationale: in
// typical flow, only the first/last (or leftmost/rightmost)
// children actually sit at the parent's edges. If even one of
// them has its own padding, the visual flush is broken on that
// side. Classic example: a column-flow card frame where the
// top child (header) has padding-top:12 and the bottom child
// (footer) has padding-bottom:8 — the parent's padding:0 doesn't
// matter; nothing is actually flush. The `any-child-insulates`
// heuristic accepts some false negatives (a card with one heavily
// padded middle child won't flag) for far fewer false positives.
const CHILD_INSULATE_THRESHOLD = 4;
const childrenInsulate = { top: false, right: false, bottom: false, left: false };
for (const child of el.children) {
let childStyle = null;
if (win && typeof win.getComputedStyle === 'function') {
try { childStyle = win.getComputedStyle(child); } catch {}
}
if (!childStyle && typeof getComputedStyle === 'function') {
try { childStyle = getComputedStyle(child); } catch {}
}
if (!childStyle) continue;
const childPad = {
top: resolveLengthPx(childStyle.paddingTop, fontSize) ?? 0,
right: resolveLengthPx(childStyle.paddingRight, fontSize) ?? 0,
bottom: resolveLengthPx(childStyle.paddingBottom, fontSize) ?? 0,
left: resolveLengthPx(childStyle.paddingLeft, fontSize) ?? 0,
};
for (const s of ['top', 'right', 'bottom', 'left']) {
if (childPad[s] >= CHILD_INSULATE_THRESHOLD) childrenInsulate[s] = true;
}
}
const flushSides = [];
for (const side of ['top', 'right', 'bottom', 'left']) {
const sideBounded = borderVisible[side] || outlineVisible || bgVisible;
if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side]) {
flushSides.push(side);
}
}
if (flushSides.length > 0) {
// Confirm at least one direct child has substantial text content
// (> 4 chars). Without this, the flush is harmless: e.g. an
// image-only card.
let hasTextChild = false;
for (const child of el.children) {
const childText = (child.textContent || '').trim();
if (childText.length > 4) { hasTextChild = true; break; }
}
if (hasTextChild) {
const cls = (typeof el.className === 'string' && el.className.trim())
? el.className.trim().split(/\s+/)[0]
: '';
const boundaryParts = [];
const borderSidesVisible = ['top', 'right', 'bottom', 'left'].filter(s => borderVisible[s]);
if (borderSidesVisible.length === 4) boundaryParts.push('border');
else if (borderSidesVisible.length > 0) boundaryParts.push(`border-${borderSidesVisible.join('/')}`);
if (outlineVisible) boundaryParts.push('outline');
if (bgVisible) boundaryParts.push('bg');
const sidesLabel = flushSides.length === 4 ? 'all sides' : flushSides.join('/');
const ident = cls
? `<${tag.toLowerCase()}> "${cls}"`
: `<${tag.toLowerCase()}>`;
findings.push({
id: 'cramped-padding',
snippet: `${ident}: children flush against ${boundaryParts.join('+')} on ${sidesLabel} (no inset)`,
});
}
}
}
}
}
// --- Body text touching viewport edge --- (browser-only: needs rect)
// Catches the failure mode where the agent ships body paragraphs
// with NO container providing horizontal padding — text bleeds
@@ -1355,6 +1523,20 @@ function checkQuality(opts) {
}
}
// --- Crushed letter spacing (mirror of wide-tracking) ---
// Tracking pulled tighter than ~-0.05em crushes characters into each other.
// Optical tightening that display type legitimately wants (around -0.02em)
// stays well above this floor.
if (hasDirectText && textLen > 20 && fontSize > 0) {
if (letterSpacingPx != null && letterSpacingPx < 0) {
const trackingEm = letterSpacingPx / fontSize;
if (trackingEm <= -0.05) {
const excerpt = (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 40);
findings.push({ id: 'extreme-negative-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em — "${excerpt}"` });
}
}
}
return findings;
}
@@ -1371,7 +1553,7 @@ function checkElementQualityDOM(el) {
const rect = el.getBoundingClientRect();
const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth });
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth, win: typeof window !== 'undefined' ? window : null });
}
// Pure page-level skipped-heading walk. Takes a Document so it works in both
@@ -1413,7 +1595,7 @@ function checkElementQuality(el, style, tag, window) {
const fontSize = resolveFontSizePx(el, window);
const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null, win: window });
}
function checkElementBorders(tag, style, overrides, resolvedRadius) {
@@ -1854,40 +2036,213 @@ function checkPageLayout(doc, win) {
}
}
// Everything centered
const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, li, div, button');
let centeredCount = 0;
let totalText = 0;
for (const el of textEls) {
const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length >= 3);
if (!hasDirectText) continue;
totalText++;
let cur = el;
let isCentered = false;
while (cur && cur.nodeType === 1) {
const rawStyle = cur.getAttribute?.('style') || '';
const cls = cur.getAttribute?.('class') || '';
if (/text-align\s*:\s*center/i.test(rawStyle) || /\btext-center\b/.test(cls)) {
isCentered = true;
break;
}
if (cur.tagName === 'BODY') break;
cur = cur.parentElement;
}
if (isCentered) centeredCount++;
}
if (totalText >= 5 && centeredCount / totalText > 0.7) {
findings.push({
id: 'everything-centered',
snippet: `${centeredCount}/${totalText} text elements centered (${Math.round(centeredCount / totalText * 100)}%)`,
});
}
return findings;
}
// ─── Cream / beige palette (the default "tasteful" AI surface) ────────────────
// A warm, lightly-tinted off-white page background — light, with R≥G≥B and a
// small warm tint (not white, not a strong color). The current reflex surface.
function isCreamColor(rgb) {
if (!rgb) return false;
const { r, g, b } = rgb;
if (Math.min(r, g, b) < 209) return false; // must be light
if (!(r >= g && g >= b)) return false; // warm ordering
const warmth = r - b;
return warmth >= 6 && warmth <= 48; // tinted, not white, not strong
}
// Tailwind background utilities that render as a warm off-white surface. The
// static engine doesn't fetch Tailwind's CSS, so a `bg-amber-50` on <body>
// resolves to nothing in computed style — catch it from the class list
// instead. Candidate tokens map to their actual Tailwind hex and are still
// filtered through isCreamColor, so neutral grays (stone) and over-saturated
// shades drop out on their own.
const TAILWIND_BG_HEX = {
'bg-amber-50': '#fffbeb', 'bg-amber-100': '#fef3c7',
'bg-orange-50': '#fff7ed', 'bg-orange-100': '#ffedd5',
'bg-yellow-50': '#fefce8',
'bg-stone-50': '#fafaf9', 'bg-stone-100': '#f5f5f4', 'bg-stone-200': '#e7e5e4',
};
function creamFromClassList(cls) {
if (!cls) return null;
// Arbitrary value: bg-[#f5f0e6] / bg-[rgb(245_240_230)] (underscores = spaces).
const arb = cls.match(/\bbg-\[([^\]]+)\]/);
if (arb && isCreamColor(parseAnyColor(arb[1].replace(/_/g, ' ')))) return `bg-[${arb[1]}]`;
// Named warm-light utilities.
for (const [tok, hex] of Object.entries(TAILWIND_BG_HEX)) {
if (new RegExp(`(^|\\s)${tok}($|\\s)`).test(cls) && isCreamColor(parseAnyColor(hex))) return tok;
}
return null;
}
function checkCreamPalette(doc, win) {
const findings = [];
const body = doc.body || (doc.querySelector ? doc.querySelector('body') : null);
if (!body) return findings;
const html = doc.documentElement;
const getCS = (el) => (win ? win.getComputedStyle(el) : getComputedStyle(el));
// 1. Computed background — covers inline / <style> / linked CSS, and Tailwind
// once it's actually rendered (browser path).
let bg = readOwnBackgroundColor(body, getCS(body));
if (!bg || bg.a === 0) {
if (html) bg = readOwnBackgroundColor(html, getCS(html));
}
if (isCreamColor(bg)) {
findings.push({ id: 'cream-palette', snippet: `cream/beige page background rgb(${bg.r}, ${bg.g}, ${bg.b})` });
return findings;
}
// 2. Tailwind class fallback — for the static path, where utility classes
// never resolve to computed CSS.
for (const el of [body, html]) {
const tok = creamFromClassList(el && el.getAttribute ? el.getAttribute('class') : '');
if (tok) {
findings.push({ id: 'cream-palette', snippet: `cream/beige page background (Tailwind ${tok})` });
break;
}
}
return findings;
}
// ─── Oversized hero headline ────────────────────────────────────────────────
// Fires when a *long* headline is set at display size, so a full sentence ends
// up dominating the viewport. A punchy one- or two-word headline at the same
// size is a legitimate stylistic choice and must pass — length, not size
// alone, is the tell.
const OVERSIZED_H1_FONT_PX = 72;
const OVERSIZED_H1_MIN_CHARS = 40;
function checkOversizedH1({ tag, fontSize, headingText }) {
if (tag !== 'h1') return [];
const textLen = headingText.length;
if (fontSize >= OVERSIZED_H1_FONT_PX && textLen >= OVERSIZED_H1_MIN_CHARS) {
return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars "${headingText.slice(0, 60)}"` }];
}
return [];
}
function checkElementOversizedH1(el, style, tag, window) {
if (tag !== 'h1') return [];
const fontSize = resolveFontSizePx(el, window);
const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
return checkOversizedH1({ tag, fontSize, headingText });
}
function checkElementOversizedH1DOM(el) {
const tag = el.tagName.toLowerCase();
if (tag !== 'h1') return [];
const style = getComputedStyle(el);
const fontSize = parseFloat(style.fontSize) || 0;
const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
return checkOversizedH1({ tag, fontSize, headingText });
}
// ─── GPT tell: hairline border + wide diffuse shadow (gated --gpt) ────────────
function shadowMaxBlurPx(boxShadow) {
if (!boxShadow || boxShadow === 'none') return 0;
let maxBlur = 0;
// Split into layers on commas not inside parentheses (rgba(...) etc.).
for (const layer of boxShadow.split(/,(?![^()]*\))/)) {
// Strip colors and keywords (rgba()/hsl()/hex/named/inset/px), leaving the
// ordered length tokens: offsetX offsetY blur [spread]. Static jsdom keeps
// unitless zeros ("0 0 24px"); browsers normalize to px ("0px 0px 24px") —
// both reduce to the same numbers here.
const cleaned = layer.replace(/rgba?\([^)]*\)|hsla?\([^)]*\)|#[0-9a-f]+|\b[a-z]+\b/gi, ' ');
const nums = [...cleaned.matchAll(/-?\d*\.?\d+/g)].map(m => parseFloat(m[0]));
if (nums.length >= 3) maxBlur = Math.max(maxBlur, nums[2]);
}
return maxBlur;
}
function checkGptThinBorderWideShadow({ borderWidths, boxShadow }) {
const maxBorder = Math.max(0, ...borderWidths);
const hasThinBorder = maxBorder > 0 && maxBorder <= 1.5;
const blur = shadowMaxBlurPx(boxShadow);
if (hasThinBorder && blur >= 16) {
return [{ id: 'gpt-thin-border-wide-shadow', snippet: `${maxBorder}px border + ${Math.round(blur)}px shadow blur` }];
}
return [];
}
function borderWidthsFromStyle(style) {
return [
parseFloat(style.borderTopWidth) || 0,
parseFloat(style.borderRightWidth) || 0,
parseFloat(style.borderBottomWidth) || 0,
parseFloat(style.borderLeftWidth) || 0,
];
}
function checkElementGptBorderShadow(el, style) {
return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
}
function checkElementGptBorderShadowDOM(el) {
const style = getComputedStyle(el);
return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
}
// ─── Clipped overflow container ───────────────────────────────────────────────
// A clipping container (overflow hidden/clip, not a scroll region) wrapping an
// absolutely/fixed-positioned descendant clips popovers/menus that must escape.
function classSelector(el) {
const cls = (el.getAttribute ? el.getAttribute('class') : el.className) || '';
const tokens = String(cls).trim().split(/\s+/).filter(Boolean);
const tag = el.tagName ? el.tagName.toLowerCase() : 'el';
return tokens.length ? `${tag}.${tokens.join('.')}` : tag;
}
function checkClippedOverflow(el, style, getStyle) {
const clips = (v) => v === 'hidden' || v === 'clip';
const scrolls = (v) => v === 'auto' || v === 'scroll';
const ox = style.overflowX || '', oy = style.overflowY || '', ov = style.overflow || '';
const anyClip = clips(ox) || clips(oy) || clips(ov);
const anyScroll = scrolls(ox) || scrolls(oy) || scrolls(ov);
if (!anyClip || anyScroll) return [];
if (!el.querySelectorAll) return [];
for (const child of el.querySelectorAll('*')) {
const pos = (getStyle(child).position) || '';
if (pos === 'absolute' || pos === 'fixed') {
return [{ id: 'clipped-overflow-container', snippet: `${classSelector(el)} clips a positioned child` }];
}
}
return [];
}
function checkElementClippedOverflow(el, style, tag, window) {
return checkClippedOverflow(el, style, (n) => window.getComputedStyle(n));
}
function checkElementClippedOverflowDOM(el) {
const style = getComputedStyle(el);
return checkClippedOverflow(el, style, (n) => getComputedStyle(n));
}
// ─── Text overflow (browser-only: needs scrollWidth/clientWidth) ──────────────
const TEXT_OVERFLOW_SKIP_TAGS = new Set(['pre', 'code', 'textarea', 'svg', 'canvas', 'select', 'option', 'marquee']);
function checkElementTextOverflowDOM(el) {
const tag = el.tagName.toLowerCase();
if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
// Only the element that actually owns overflowing text — not its ancestors,
// which inherit a wider scrollWidth from the spilling descendant.
const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
if (!hasDirectText) return [];
const style = getComputedStyle(el);
const isScrollRegion = (s) => /(auto|scroll)/.test(s.overflowX || '') || /(auto|scroll)/.test(s.overflow || '');
if (isScrollRegion(style)) return [];
// A scrollable ancestor means this overflow is intentional and scrollable.
for (let p = el.parentElement; p; p = p.parentElement) {
if (isScrollRegion(getComputedStyle(p))) return [];
}
const delta = el.scrollWidth - el.clientWidth;
if (el.clientWidth > 0 && delta >= 16) {
return [{ id: 'text-overflow', snippet: `${classSelector(el)} overflows its box by ${Math.round(delta)}px` }];
}
return [];
}
export {
checkBorders,
isEmojiOnlyText,
@@ -1945,4 +2300,17 @@ export {
checkPageTypography,
isCardLike,
checkPageLayout,
isCreamColor,
checkCreamPalette,
checkOversizedH1,
checkElementOversizedH1,
checkElementOversizedH1DOM,
shadowMaxBlurPx,
checkGptThinBorderWideShadow,
checkElementGptBorderShadow,
checkElementGptBorderShadowDOM,
checkClippedOverflow,
checkElementClippedOverflow,
checkElementClippedOverflowDOM,
checkElementTextOverflowDOM,
};
cli/engine/shared/constants.mjs
+1 -1
View File
@@ -24,7 +24,7 @@ const OVERUSED_FONTS = new Set([
// Older monoculture (still ubiquitous):
'inter', 'roboto', 'open sans', 'lato', 'montserrat', 'arial', 'helvetica',
// Newer monoculture (the Anthropic-skill / Vercel / GitHub default wave):
'fraunces', 'instrument sans',
'fraunces', 'instrument sans', 'instrument serif',
'geist', 'geist sans', 'geist mono',
'mona sans',
'plus jakarta sans', 'space grotesk', 'recoleta',