impeccable 2.1.6 → 2.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- The vocabulary you didn't know you needed. 1 skill, 18 commands, and curated anti-patterns for impeccable frontend design.
3
+ The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design.
4
4
 
5
5
  > **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
6
6
 
@@ -12,7 +12,7 @@ Every LLM learned from the same generic templates. Without guidance, you get the
12
12
 
13
13
  Impeccable fights that bias with:
14
14
  - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/impeccable/))
15
- - **18 steering commands** to audit, review, polish, distill, animate, and more
15
+ - **23 commands** to audit, review, polish, distill, animate, and more
16
16
  - **Curated anti-patterns** that explicitly tell the AI what NOT to do
17
17
 
18
18
  ## What's Included
@@ -31,65 +31,50 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou
31
31
  | [responsive-design](source/skills/impeccable/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
32
32
  | [ux-writing](source/skills/impeccable/reference/ux-writing.md) | Button labels, error messages, empty states |
33
33
 
34
- ### 18 Commands
34
+ ### 23 Commands
35
+
36
+ All commands are accessed through `/impeccable`:
35
37
 
36
38
  | Command | What it does |
37
39
  |---------|--------------|
38
- | `/impeccable teach` | One-time setup: gather design context, save to config |
39
40
  | `/impeccable craft` | Full shape-then-build flow with visual iteration |
41
+ | `/impeccable teach` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md |
42
+ | `/impeccable document` | Generate DESIGN.md from existing project code |
40
43
  | `/impeccable extract` | Pull reusable components and tokens into the design system |
41
- | `/audit` | Run technical quality checks (a11y, performance, responsive) |
42
- | `/critique` | UX design review: hierarchy, clarity, emotional resonance |
43
- | `/polish` | Final pass, design system alignment, and shipping readiness |
44
- | `/distill` | Strip to essence |
45
- | `/clarify` | Improve unclear UX copy |
46
- | `/optimize` | Performance improvements |
47
- | `/harden` | Error handling, onboarding, i18n, edge cases |
48
- | `/animate` | Add purposeful motion |
49
- | `/colorize` | Introduce strategic color |
50
- | `/bolder` | Amplify boring designs |
51
- | `/quieter` | Tone down overly bold designs |
52
- | `/delight` | Add moments of joy |
53
- | `/adapt` | Adapt for different devices |
54
- | `/typeset` | Fix font choices, hierarchy, sizing |
55
- | `/layout` | Fix layout, spacing, visual rhythm |
56
- | `/overdrive` | Add technically extraordinary effects |
44
+ | `/impeccable shape` | Plan UX/UI before writing code |
45
+ | `/impeccable critique` | UX design review: hierarchy, clarity, emotional resonance |
46
+ | `/impeccable audit` | Run technical quality checks (a11y, performance, responsive) |
47
+ | `/impeccable polish` | Final pass, design system alignment, and shipping readiness |
48
+ | `/impeccable bolder` | Amplify boring designs |
49
+ | `/impeccable quieter` | Tone down overly bold designs |
50
+ | `/impeccable distill` | Strip to essence |
51
+ | `/impeccable harden` | Error handling, i18n, text overflow, edge cases |
52
+ | `/impeccable onboard` | First-run flows, empty states, activation paths |
53
+ | `/impeccable animate` | Add purposeful motion |
54
+ | `/impeccable colorize` | Introduce strategic color |
55
+ | `/impeccable typeset` | Fix font choices, hierarchy, sizing |
56
+ | `/impeccable layout` | Fix layout, spacing, visual rhythm |
57
+ | `/impeccable delight` | Add moments of joy |
58
+ | `/impeccable overdrive` | Add technically extraordinary effects |
59
+ | `/impeccable clarify` | Improve unclear UX copy |
60
+ | `/impeccable adapt` | Adapt for different devices |
61
+ | `/impeccable optimize` | Performance improvements |
62
+ | `/impeccable live` | Visual variant mode: iterate on elements in the browser |
63
+
64
+ Use `/impeccable pin <command>` to create standalone shortcuts (e.g., `pin audit` creates `/audit`).
57
65
 
58
66
  #### Usage Examples
59
67
 
60
- **`/audit`** - Run quality checks, get a report (no edits)
61
- ```
62
- /audit blog # Audit blog hub + post pages
63
- /audit dashboard # Check dashboard components
64
- /audit checkout flow # Focus on checkout UX
65
- ```
66
- *When to use:* Before making changes, to understand what needs fixing.
67
-
68
- **`/normalize`** - Align with design system
69
- ```
70
- /normalize blog # Apply design tokens, fix spacing
71
- /normalize buttons # Standardize button styles
72
- ```
73
- *When to use:* After audit, to fix inconsistencies.
74
-
75
- **`/critique`** - UX design review
76
68
  ```
77
- /critique landing page # Review landing page UX
78
- /critique onboarding # Check onboarding flow
69
+ /impeccable audit blog # Audit blog hub + post pages
70
+ /impeccable critique landing # UX design review
71
+ /impeccable polish settings # Final pass before shipping
72
+ /impeccable harden checkout # Add error handling + edge cases
79
73
  ```
80
- *When to use:* When you want design feedback, not technical fixes.
81
74
 
82
- **`/polish`** - Final pass before shipping
75
+ Or use `/impeccable` directly with a description:
83
76
  ```
84
- /polish feature modal # Clean up modal before release
85
- /polish settings page # Final review of settings UI
86
- ```
87
- *When to use:* Last step before deploying to production.
88
-
89
- **Combining commands:**
90
- ```
91
- /audit /normalize /polish blog # Full workflow: audit → fix → polish
92
- /critique /harden checkout # UX review + add error handling
77
+ /impeccable redo this hero section
93
78
  ```
94
79
 
95
80
  ### Anti-Patterns
@@ -158,7 +143,17 @@ cp -r dist/gemini/.gemini your-project/
158
143
 
159
144
  **Codex CLI:**
160
145
  ```bash
161
- cp -r dist/codex/.codex/* ~/.codex/
146
+ # Project-local
147
+ cp -r dist/agents/.agents your-project/
148
+
149
+ # Or user-wide
150
+ mkdir -p ~/.agents/skills
151
+ cp -r dist/agents/.agents/skills/* ~/.agents/skills/
152
+ ```
153
+
154
+ **GitHub Copilot:**
155
+ ```bash
156
+ cp -r dist/github/.github your-project/
162
157
  ```
163
158
 
164
159
  **Trae:**
@@ -203,7 +198,7 @@ Most commands accept an optional argument to focus on a specific area:
203
198
  /polish checkout-form
204
199
  ```
205
200
 
206
- **Note:** Codex CLI uses a different syntax: `/prompts:audit`, `/prompts:polish`, etc.
201
+ **Note:** Codex uses skills here, not `/prompts:` commands. Open `/skills` or type `$impeccable`. Repo-local installs live in `.agents/skills/`; user-wide installs live in `~/.agents/skills/`. GitHub Copilot uses `.github/skills/`. Restart the tool if a newly installed skill does not appear.
207
202
 
208
203
  ## CLI
209
204
 
package/bin/cli.js CHANGED
@@ -5,8 +5,6 @@
5
5
  *
6
6
  * Usage:
7
7
  * npx impeccable detect [file-or-dir-or-url...]
8
- * npx impeccable live [--port=PORT]
9
- * npx impeccable live stop
10
8
  * npx impeccable skills help|install|update
11
9
  * npx impeccable --help
12
10
  */
@@ -24,8 +22,6 @@ if (!command || command === '--help' || command === '-h') {
24
22
 
25
23
  Commands:
26
24
  detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issues
27
- live [--port=PORT] Start browser detection overlay server
28
- live stop Stop a running live server
29
25
  skills help List all available skills and commands
30
26
  skills install Install impeccable skills into your project
31
27
  skills update Update skills to the latest version
@@ -49,10 +45,6 @@ if (command === 'detect') {
49
45
  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
50
46
  const { detectCli } = await import('../src/detect-antipatterns.mjs');
51
47
  await detectCli();
52
- } else if (command === 'live') {
53
- process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
54
- const { liveCli } = await import('../src/detect-antipatterns.mjs');
55
- await liveCli();
56
48
  } else if (command === 'skills') {
57
49
  const { run } = await import('./commands/skills.mjs');
58
50
  await run(args.slice(1));
@@ -20,7 +20,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
20
20
  const API_BASE = 'https://impeccable.style';
21
21
 
22
22
  // Provider folder names in project roots
23
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.codex', '.agents', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
23
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
24
24
 
25
25
  function ask(question) {
26
26
  const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -112,7 +112,7 @@ async function downloadAndExtractBundle() {
112
112
  */
113
113
  function normalizeForHash(content) {
114
114
  return content
115
- .replace(/\.(claude|cursor|agents|gemini|codex|kiro|opencode|pi|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
115
+ .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
116
116
  .replace(/^version:\s*.+$/m, 'version: NORMALIZED');
117
117
  }
118
118
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "impeccable",
3
- "version": "2.1.6",
3
+ "version": "2.1.8",
4
4
  "author": "Paul Bakaus",
5
5
  "description": "Design skills, commands, and anti-pattern detection for AI coding agents",
6
6
  "keywords": [
@@ -49,23 +49,35 @@
49
49
  "dev": "bun run server/index.js",
50
50
  "preview": "bun run build && wrangler pages dev",
51
51
  "deploy": "bun run build && wrangler pages deploy build/",
52
- "test": "bun test tests/build.test.js tests/detect-antipatterns.test.js && node --test tests/detect-antipatterns-fixtures.test.mjs && node --test tests/detect-antipatterns-browser.test.mjs && node --test tests/cleanup-deprecated.test.mjs",
52
+ "test": "bun test tests/build.test.js tests/detect-antipatterns.test.js tests/windows-path-fix.test.js && node --test tests/detect-antipatterns-fixtures.test.mjs && node --test tests/detect-antipatterns-browser.test.mjs && node --test tests/cleanup-deprecated.test.mjs && node --test tests/live-wrap.test.mjs && node --test tests/live-accept.test.mjs && node --test tests/live-inject.test.mjs && node --test tests/live-server.test.mjs && node --test tests/framework-fixtures.test.mjs",
53
+ "test:live-e2e": "node --test --test-timeout=600000 tests/live-e2e.test.mjs",
53
54
  "prepack": "cp README.md README.repo.md && cp README.npm.md README.md",
54
55
  "postpack": "cp README.repo.md README.md && rm README.repo.md",
56
+ "release:skill": "node scripts/release.mjs skill",
57
+ "release:cli": "node scripts/release.mjs cli",
58
+ "release:ext": "node scripts/release.mjs extension",
55
59
  "screenshot": "bun run scripts/screenshot-antipatterns.js",
56
60
  "og-image": "bun run scripts/generate-og-image.js"
57
61
  },
58
62
  "dependencies": {
59
- "jsdom": "^29.0.0",
60
- "marked": "^16.1.0"
63
+ "jsdom": "29.0.0",
64
+ "marked": "^16.4.2"
61
65
  },
62
66
  "optionalDependencies": {
63
- "puppeteer": "^24.39.1"
67
+ "puppeteer": "^24.42.0"
64
68
  },
65
69
  "devDependencies": {
70
+ "@ai-sdk/anthropic": "^3.0.71",
71
+ "@ai-sdk/openai": "^3.0.53",
72
+ "@anthropic-ai/claude-agent-sdk": "^0.2.119",
73
+ "@anthropic-ai/sdk": "^0.91.1",
74
+ "@google/genai": "^1.50.1",
75
+ "ai": "^6.0.168",
66
76
  "archiver": "^7.0.1",
77
+ "modern-screenshot": "^4.7.0",
67
78
  "motion": "^12.38.0",
68
- "playwright": "^1.58.2",
69
- "wrangler": "^4.75.0"
79
+ "playwright": "^1.59.1",
80
+ "wrangler": "^4.85.0",
81
+ "zod": "^4.3.6"
70
82
  }
71
83
  }
@@ -516,7 +516,7 @@ function checkColors(opts) {
516
516
  // Tailwind class checks
517
517
  if (classList) {
518
518
  const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ');
519
- if (/\bbg-black\b/.test(classStr)) {
519
+ if (/\bbg-black\b(?!\/)/.test(classStr)) {
520
520
  findings.push({ id: 'pure-black-white', snippet: 'bg-black' });
521
521
  }
522
522
 
@@ -822,9 +822,11 @@ function resolveBackground(el, win) {
822
822
  while (current && current.nodeType === 1) {
823
823
  const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
824
824
 
825
- // If this element has a gradient background, it's opaque but we can't determine the color
825
+ // If this element has a background-image (gradient or url), it's visually
826
+ // opaque but we can't determine the effective color — bail out so callers
827
+ // don't get a false solid-color answer.
826
828
  const bgImage = style.backgroundImage || '';
827
- if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
829
+ if (bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage))) {
828
830
  return null;
829
831
  }
830
832
 
@@ -834,8 +836,8 @@ function resolveBackground(el, win) {
834
836
  const rawStyle = current.getAttribute?.('style') || '';
835
837
  const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
836
838
  const inlineBg = bgMatch ? bgMatch[1].trim() : '';
837
- // Check for gradient in inline style too
838
- if (/gradient/i.test(inlineBg)) return null;
839
+ // Check for gradient or url() image in inline style too
840
+ if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return null;
839
841
  bg = parseRgb(inlineBg);
840
842
  if (!bg && inlineBg) {
841
843
  const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
@@ -883,6 +885,82 @@ function resolveGradientStops(el, win) {
883
885
  return null;
884
886
  }
885
887
 
888
+ // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
889
+ // shorthand like "12px 4px" (uses the first value), or empty / null.
890
+ // Returns the pixel value, or null when the input is unparseable.
891
+ // Percentages convert against `widthPx` when one is supplied. Without a
892
+ // usable width (jsdom returns "auto" for many real-world elements,
893
+ // which parseFloat collapses to 0), fall back to the raw percentage
894
+ // number so callers gating on `> 0` (border-accent-on-rounded,
895
+ // isCardLike's hasRadius) still see a positive value, matching the
896
+ // original parseFloat("50%") === 50 behavior.
897
+ function parseRadiusToPx(value, widthPx) {
898
+ if (!value || typeof value !== 'string') return null;
899
+ const trimmed = value.trim();
900
+ if (!trimmed) return null;
901
+ const first = trimmed.split(/\s+/)[0];
902
+ const num = parseFloat(first);
903
+ if (Number.isNaN(num)) return null;
904
+ if (/%$/.test(first)) {
905
+ if (widthPx && widthPx > 0) return (num / 100) * widthPx;
906
+ return num;
907
+ }
908
+ return num;
909
+ }
910
+
911
+ // jsdom from 29.0.2 onward returns "" for the `border-radius` shorthand
912
+ // in computed style and "0" for longhand reads when the source rule used
913
+ // the shorthand. The rule engine relied on parseFloat(style.borderRadius)
914
+ // to identify circular avatars (border-radius >= width/2) and rounded
915
+ // cards (border-radius > 0); both checks broke silently. This helper
916
+ // recovers the radius via a chain of fallbacks. Browsers resolve the
917
+ // shorthand correctly and exit on the first line.
918
+ function resolveBorderRadiusPx(el, style, widthPx, win) {
919
+ const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
920
+ if (fromComputed !== null) return fromComputed;
921
+
922
+ if (IS_BROWSER || !win) return 0;
923
+
924
+ const fromLonghand = parseRadiusToPx(style.borderTopLeftRadius, widthPx);
925
+ if (fromLonghand !== null && fromLonghand > 0) return fromLonghand;
926
+
927
+ const fromInlineProp = parseRadiusToPx(el.style?.borderRadius, widthPx);
928
+ if (fromInlineProp !== null) return fromInlineProp;
929
+
930
+ const rawStyle = el.getAttribute?.('style') || '';
931
+ const inlineMatch = rawStyle.match(/border-radius\s*:\s*([^;]+)/i);
932
+ if (inlineMatch) {
933
+ const fromRaw = parseRadiusToPx(inlineMatch[1].trim(), widthPx);
934
+ if (fromRaw !== null) return fromRaw;
935
+ }
936
+
937
+ // Walk every stylesheet looking for matching rules. Take the maximum
938
+ // pixel value across all matches so a circle declaration overridden by
939
+ // a more specific rounded-square selector still registers as a circle
940
+ // for the exclusion check (better to under-flag than to false-positive
941
+ // on round avatars).
942
+ let max = 0;
943
+ const sheets = win.document?.styleSheets;
944
+ if (sheets) {
945
+ for (const sheet of sheets) {
946
+ let rules;
947
+ try { rules = sheet.cssRules || []; } catch { continue; }
948
+ for (const rule of rules) {
949
+ if (!rule.style || !rule.selectorText) continue;
950
+ let matches = false;
951
+ try { matches = el.matches(rule.selectorText); } catch { continue; }
952
+ if (!matches) continue;
953
+ const ruleValue = rule.style.borderRadius
954
+ || (rule.style.getPropertyValue && rule.style.getPropertyValue('border-radius'))
955
+ || rule.style.borderTopLeftRadius;
956
+ const px = parseRadiusToPx(ruleValue, widthPx);
957
+ if (px !== null && px > max) max = px;
958
+ }
959
+ }
960
+ }
961
+ return max;
962
+ }
963
+
886
964
  // ─── Section 5: Element Adapters ────────────────────────────────────────────
887
965
 
888
966
  // Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
@@ -1269,7 +1347,7 @@ function checkElementQuality(el, style, tag, window) {
1269
1347
  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
1270
1348
  }
1271
1349
 
1272
- function checkElementBorders(tag, style, overrides) {
1350
+ function checkElementBorders(tag, style, overrides, resolvedRadius) {
1273
1351
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1274
1352
  const widths = {}, colors = {};
1275
1353
  for (const s of sides) {
@@ -1289,7 +1367,14 @@ function checkElementBorders(tag, style, overrides) {
1289
1367
  colors[s] = overrides[s].color;
1290
1368
  }
1291
1369
  }
1292
- return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
1370
+ // resolvedRadius lets the caller pre-resolve the radius via
1371
+ // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
1372
+ // shorthand serialization. Falls back to the computed value for tests
1373
+ // and browser callers that don't pre-resolve.
1374
+ const radius = resolvedRadius != null
1375
+ ? resolvedRadius
1376
+ : (parseFloat(style.borderRadius) || 0);
1377
+ return checkBorders(tag, widths, colors, radius);
1293
1378
  }
1294
1379
 
1295
1380
  function checkElementColors(el, style, tag, window) {
@@ -1344,7 +1429,7 @@ function checkElementIconTile(el, tag, window) {
1344
1429
  siblingBgColor: parseRgb(sibStyle.backgroundColor),
1345
1430
  siblingBgImage: sibStyle.backgroundImage || '',
1346
1431
  siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1347
- siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
1432
+ siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
1348
1433
  hasIconChild: !!iconChild || hasInlineEmojiIcon,
1349
1434
  iconChildWidth: iconWidth,
1350
1435
  });
@@ -1563,7 +1648,8 @@ function isCardLike(el, win) {
1563
1648
  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
1564
1649
  /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
1565
1650
  const hasBorder = /\bborder\b/.test(cls);
1566
- const hasRadius = (parseFloat(style.borderRadius) || 0) > 0 ||
1651
+ const widthPx = parseFloat(style.width) || 0;
1652
+ const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
1567
1653
  /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
1568
1654
  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
1569
1655
  /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
@@ -2244,6 +2330,9 @@ if (IS_BROWSER) {
2244
2330
  // Skip browser extension elements (Claude, etc.)
2245
2331
  const elId = el.id || '';
2246
2332
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
2333
+ // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
2334
+ // These are inspector chrome, not part of the user's design.
2335
+ if (el.closest('[id^="impeccable-live-"]')) continue;
2247
2336
  // Skip html/body -- page-level findings go in the banner, not a full-page overlay
2248
2337
  if (el === document.body || el === document.documentElement) continue;
2249
2338
 
@@ -2297,7 +2386,14 @@ if (IS_BROWSER) {
2297
2386
  }
2298
2387
 
2299
2388
  // Regex-on-HTML checks (shared with Node)
2300
- const htmlPatternFindings = checkHtmlPatterns(document.documentElement.outerHTML);
2389
+ // Clone the document and strip impeccable-live overlay nodes before the
2390
+ // regex scan, so the inspector's own inline styles (transitions on top/
2391
+ // left/width/height, etc.) don't register as page anti-patterns.
2392
+ const docClone = document.documentElement.cloneNode(true);
2393
+ for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
2394
+ node.remove();
2395
+ }
2396
+ const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
2301
2397
  if (htmlPatternFindings.length > 0) {
2302
2398
  const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
2303
2399
  pageLevelFindings.push(...mapped);
@@ -26,10 +26,11 @@ const IS_BROWSER = typeof window !== 'undefined';
26
26
  const IS_NODE = !IS_BROWSER;
27
27
 
28
28
  // @browser-strip-start
29
- let fs, path;
29
+ let fs, path, fileURLToPath;
30
30
  if (!IS_BROWSER) {
31
31
  fs = (await import('node:fs')).default;
32
32
  path = (await import('node:path')).default;
33
+ fileURLToPath = (await import('node:url')).fileURLToPath;
33
34
  }
34
35
  // @browser-strip-end
35
36
 
@@ -511,7 +512,7 @@ function checkColors(opts) {
511
512
  // Tailwind class checks
512
513
  if (classList) {
513
514
  const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ');
514
- if (/\bbg-black\b/.test(classStr)) {
515
+ if (/\bbg-black\b(?!\/)/.test(classStr)) {
515
516
  findings.push({ id: 'pure-black-white', snippet: 'bg-black' });
516
517
  }
517
518
 
@@ -817,9 +818,11 @@ function resolveBackground(el, win) {
817
818
  while (current && current.nodeType === 1) {
818
819
  const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
819
820
 
820
- // If this element has a gradient background, it's opaque but we can't determine the color
821
+ // If this element has a background-image (gradient or url), it's visually
822
+ // opaque but we can't determine the effective color — bail out so callers
823
+ // don't get a false solid-color answer.
821
824
  const bgImage = style.backgroundImage || '';
822
- if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
825
+ if (bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage))) {
823
826
  return null;
824
827
  }
825
828
 
@@ -829,8 +832,8 @@ function resolveBackground(el, win) {
829
832
  const rawStyle = current.getAttribute?.('style') || '';
830
833
  const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
831
834
  const inlineBg = bgMatch ? bgMatch[1].trim() : '';
832
- // Check for gradient in inline style too
833
- if (/gradient/i.test(inlineBg)) return null;
835
+ // Check for gradient or url() image in inline style too
836
+ if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return null;
834
837
  bg = parseRgb(inlineBg);
835
838
  if (!bg && inlineBg) {
836
839
  const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
@@ -878,6 +881,82 @@ function resolveGradientStops(el, win) {
878
881
  return null;
879
882
  }
880
883
 
884
+ // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
885
+ // shorthand like "12px 4px" (uses the first value), or empty / null.
886
+ // Returns the pixel value, or null when the input is unparseable.
887
+ // Percentages convert against `widthPx` when one is supplied. Without a
888
+ // usable width (jsdom returns "auto" for many real-world elements,
889
+ // which parseFloat collapses to 0), fall back to the raw percentage
890
+ // number so callers gating on `> 0` (border-accent-on-rounded,
891
+ // isCardLike's hasRadius) still see a positive value, matching the
892
+ // original parseFloat("50%") === 50 behavior.
893
+ function parseRadiusToPx(value, widthPx) {
894
+ if (!value || typeof value !== 'string') return null;
895
+ const trimmed = value.trim();
896
+ if (!trimmed) return null;
897
+ const first = trimmed.split(/\s+/)[0];
898
+ const num = parseFloat(first);
899
+ if (Number.isNaN(num)) return null;
900
+ if (/%$/.test(first)) {
901
+ if (widthPx && widthPx > 0) return (num / 100) * widthPx;
902
+ return num;
903
+ }
904
+ return num;
905
+ }
906
+
907
+ // jsdom from 29.0.2 onward returns "" for the `border-radius` shorthand
908
+ // in computed style and "0" for longhand reads when the source rule used
909
+ // the shorthand. The rule engine relied on parseFloat(style.borderRadius)
910
+ // to identify circular avatars (border-radius >= width/2) and rounded
911
+ // cards (border-radius > 0); both checks broke silently. This helper
912
+ // recovers the radius via a chain of fallbacks. Browsers resolve the
913
+ // shorthand correctly and exit on the first line.
914
+ function resolveBorderRadiusPx(el, style, widthPx, win) {
915
+ const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
916
+ if (fromComputed !== null) return fromComputed;
917
+
918
+ if (IS_BROWSER || !win) return 0;
919
+
920
+ const fromLonghand = parseRadiusToPx(style.borderTopLeftRadius, widthPx);
921
+ if (fromLonghand !== null && fromLonghand > 0) return fromLonghand;
922
+
923
+ const fromInlineProp = parseRadiusToPx(el.style?.borderRadius, widthPx);
924
+ if (fromInlineProp !== null) return fromInlineProp;
925
+
926
+ const rawStyle = el.getAttribute?.('style') || '';
927
+ const inlineMatch = rawStyle.match(/border-radius\s*:\s*([^;]+)/i);
928
+ if (inlineMatch) {
929
+ const fromRaw = parseRadiusToPx(inlineMatch[1].trim(), widthPx);
930
+ if (fromRaw !== null) return fromRaw;
931
+ }
932
+
933
+ // Walk every stylesheet looking for matching rules. Take the maximum
934
+ // pixel value across all matches so a circle declaration overridden by
935
+ // a more specific rounded-square selector still registers as a circle
936
+ // for the exclusion check (better to under-flag than to false-positive
937
+ // on round avatars).
938
+ let max = 0;
939
+ const sheets = win.document?.styleSheets;
940
+ if (sheets) {
941
+ for (const sheet of sheets) {
942
+ let rules;
943
+ try { rules = sheet.cssRules || []; } catch { continue; }
944
+ for (const rule of rules) {
945
+ if (!rule.style || !rule.selectorText) continue;
946
+ let matches = false;
947
+ try { matches = el.matches(rule.selectorText); } catch { continue; }
948
+ if (!matches) continue;
949
+ const ruleValue = rule.style.borderRadius
950
+ || (rule.style.getPropertyValue && rule.style.getPropertyValue('border-radius'))
951
+ || rule.style.borderTopLeftRadius;
952
+ const px = parseRadiusToPx(ruleValue, widthPx);
953
+ if (px !== null && px > max) max = px;
954
+ }
955
+ }
956
+ }
957
+ return max;
958
+ }
959
+
881
960
  // ─── Section 5: Element Adapters ────────────────────────────────────────────
882
961
 
883
962
  // Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
@@ -1264,7 +1343,7 @@ function checkElementQuality(el, style, tag, window) {
1264
1343
  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
1265
1344
  }
1266
1345
 
1267
- function checkElementBorders(tag, style, overrides) {
1346
+ function checkElementBorders(tag, style, overrides, resolvedRadius) {
1268
1347
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1269
1348
  const widths = {}, colors = {};
1270
1349
  for (const s of sides) {
@@ -1284,7 +1363,14 @@ function checkElementBorders(tag, style, overrides) {
1284
1363
  colors[s] = overrides[s].color;
1285
1364
  }
1286
1365
  }
1287
- return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
1366
+ // resolvedRadius lets the caller pre-resolve the radius via
1367
+ // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
1368
+ // shorthand serialization. Falls back to the computed value for tests
1369
+ // and browser callers that don't pre-resolve.
1370
+ const radius = resolvedRadius != null
1371
+ ? resolvedRadius
1372
+ : (parseFloat(style.borderRadius) || 0);
1373
+ return checkBorders(tag, widths, colors, radius);
1288
1374
  }
1289
1375
 
1290
1376
  function checkElementColors(el, style, tag, window) {
@@ -1339,7 +1425,7 @@ function checkElementIconTile(el, tag, window) {
1339
1425
  siblingBgColor: parseRgb(sibStyle.backgroundColor),
1340
1426
  siblingBgImage: sibStyle.backgroundImage || '',
1341
1427
  siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1342
- siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
1428
+ siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
1343
1429
  hasIconChild: !!iconChild || hasInlineEmojiIcon,
1344
1430
  iconChildWidth: iconWidth,
1345
1431
  });
@@ -1558,7 +1644,8 @@ function isCardLike(el, win) {
1558
1644
  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
1559
1645
  /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
1560
1646
  const hasBorder = /\bborder\b/.test(cls);
1561
- const hasRadius = (parseFloat(style.borderRadius) || 0) > 0 ||
1647
+ const widthPx = parseFloat(style.width) || 0;
1648
+ const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
1562
1649
  /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
1563
1650
  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
1564
1651
  /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
@@ -2239,6 +2326,9 @@ if (IS_BROWSER) {
2239
2326
  // Skip browser extension elements (Claude, etc.)
2240
2327
  const elId = el.id || '';
2241
2328
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
2329
+ // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
2330
+ // These are inspector chrome, not part of the user's design.
2331
+ if (el.closest('[id^="impeccable-live-"]')) continue;
2242
2332
  // Skip html/body -- page-level findings go in the banner, not a full-page overlay
2243
2333
  if (el === document.body || el === document.documentElement) continue;
2244
2334
 
@@ -2292,7 +2382,14 @@ if (IS_BROWSER) {
2292
2382
  }
2293
2383
 
2294
2384
  // Regex-on-HTML checks (shared with Node)
2295
- const htmlPatternFindings = checkHtmlPatterns(document.documentElement.outerHTML);
2385
+ // Clone the document and strip impeccable-live overlay nodes before the
2386
+ // regex scan, so the inspector's own inline styles (transitions on top/
2387
+ // left/width/height, etc.) don't register as page anti-patterns.
2388
+ const docClone = document.documentElement.cloneNode(true);
2389
+ for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
2390
+ node.remove();
2391
+ }
2392
+ const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
2296
2393
  if (htmlPatternFindings.length > 0) {
2297
2394
  const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
2298
2395
  pageLevelFindings.push(...mapped);
@@ -2631,7 +2728,8 @@ async function detectHtml(filePath) {
2631
2728
  for (const el of document.querySelectorAll('*')) {
2632
2729
  const tag = el.tagName.toLowerCase();
2633
2730
  const style = window.getComputedStyle(el);
2634
- for (const f of checkElementBorders(tag, style, borderOverrides.get(el))) {
2731
+ const resolvedRadius = resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window);
2732
+ for (const f of checkElementBorders(tag, style, borderOverrides.get(el), resolvedRadius)) {
2635
2733
  findings.push(finding(f.id, filePath, f.snippet));
2636
2734
  }
2637
2735
  for (const f of checkElementColors(el, style, tag, window)) {
@@ -2685,7 +2783,7 @@ async function detectUrl(url) {
2685
2783
 
2686
2784
  // Read the browser detection script — reuse it instead of reimplementing
2687
2785
  const browserScriptPath = path.resolve(
2688
- path.dirname(new URL(import.meta.url).pathname),
2786
+ path.dirname(fileURLToPath(import.meta.url)),
2689
2787
  'detect-antipatterns-browser.js'
2690
2788
  );
2691
2789
  let browserScript;
@@ -3440,124 +3538,6 @@ async function main() {
3440
3538
  process.exit(0);
3441
3539
  }
3442
3540
 
3443
- // ---------------------------------------------------------------------------
3444
- // Live detection server
3445
- // ---------------------------------------------------------------------------
3446
-
3447
- async function findOpenPort(start = 8400) {
3448
- const net = await import('node:net');
3449
- return new Promise((resolve) => {
3450
- const server = net.default.createServer();
3451
- server.listen(start, '127.0.0.1', () => {
3452
- const port = server.address().port;
3453
- server.close(() => resolve(port));
3454
- });
3455
- server.on('error', () => resolve(findOpenPort(start + 1)));
3456
- });
3457
- }
3458
-
3459
- const LIVE_PID_FILE = path.join((await import('node:os')).default.tmpdir(), 'impeccable-live.json');
3460
-
3461
- async function liveCli() {
3462
- const args = process.argv.slice(2);
3463
- const helpMode = args.includes('--help');
3464
- const stopMode = args.includes('stop');
3465
- const portArg = args.find(a => a.startsWith('--port='));
3466
- const requestedPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
3467
-
3468
- if (helpMode) {
3469
- console.log(`Usage: impeccable live [options]
3470
-
3471
- Start a local server that serves the browser detection overlay script.
3472
- Inject the script into any page to scan for anti-patterns in real time.
3473
-
3474
- Commands:
3475
- live Start the server (default)
3476
- live stop Stop a running live server
3477
-
3478
- Options:
3479
- --port=PORT Use a specific port (default: auto-detect unused port)
3480
- --help Show this help message
3481
-
3482
- The server provides:
3483
- /detect.js The detection overlay script (inject via <script> tag)
3484
- /health Health check endpoint
3485
- /stop Stop the server remotely`);
3486
- process.exit(0);
3487
- }
3488
-
3489
- // Stop a running server
3490
- if (stopMode) {
3491
- try {
3492
- const info = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
3493
- const res = await fetch(`http://localhost:${info.port}/stop`);
3494
- if (res.ok) {
3495
- console.log(`Stopped live server on port ${info.port}.`);
3496
- }
3497
- } catch {
3498
- console.log('No running live server found.');
3499
- }
3500
- process.exit(0);
3501
- }
3502
-
3503
- const http = await import('node:http');
3504
- const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), 'detect-antipatterns-browser.js');
3505
-
3506
- let browserScript;
3507
- try {
3508
- browserScript = fs.readFileSync(scriptPath, 'utf-8');
3509
- } catch {
3510
- process.stderr.write('Error: Browser script not found. Run `npm run build:browser` first.\n');
3511
- process.exit(1);
3512
- }
3513
-
3514
- const port = requestedPort || await findOpenPort();
3515
-
3516
- const shutdown = () => {
3517
- try { fs.unlinkSync(LIVE_PID_FILE); } catch { /* ignore */ }
3518
- server.close();
3519
- process.exit(0);
3520
- };
3521
-
3522
- const server = http.default.createServer((req, res) => {
3523
- // CORS headers for cross-origin injection
3524
- res.setHeader('Access-Control-Allow-Origin', '*');
3525
- res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
3526
- if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
3527
-
3528
- if (req.url === '/detect.js' || req.url === '/') {
3529
- res.writeHead(200, { 'Content-Type': 'application/javascript' });
3530
- res.end(browserScript);
3531
- } else if (req.url === '/health') {
3532
- res.writeHead(200, { 'Content-Type': 'application/json' });
3533
- res.end(JSON.stringify({ status: 'ok', port }));
3534
- } else if (req.url === '/stop') {
3535
- res.writeHead(200, { 'Content-Type': 'text/plain' });
3536
- res.end('stopping');
3537
- shutdown();
3538
- } else {
3539
- res.writeHead(404);
3540
- res.end('Not found');
3541
- }
3542
- });
3543
-
3544
- server.listen(port, '127.0.0.1', () => {
3545
- // Write PID file so `live stop` can find us
3546
- fs.writeFileSync(LIVE_PID_FILE, JSON.stringify({ pid: process.pid, port }));
3547
-
3548
- const url = `http://localhost:${port}`;
3549
- console.log(`Impeccable live detection server running on ${url}\n`);
3550
- console.log(`Inject into any page:`);
3551
- console.log(` const s = document.createElement('script');`);
3552
- console.log(` s.src = '${url}/detect.js';`);
3553
- console.log(` document.head.appendChild(s);\n`);
3554
- console.log(`Stop: npx impeccable live stop`);
3555
- });
3556
-
3557
- process.on('SIGINT', shutdown);
3558
- process.on('SIGTERM', shutdown);
3559
- }
3560
-
3561
3541
  // ---------------------------------------------------------------------------
3562
3542
  // Entry point
3563
3543
  // ---------------------------------------------------------------------------
@@ -3582,7 +3562,6 @@ export {
3582
3562
  buildImportGraph, resolveImport,
3583
3563
  detectFrameworkConfig, isPortListening, FRAMEWORK_CONFIGS,
3584
3564
  main as detectCli,
3585
- liveCli,
3586
3565
  };
3587
3566
 
3588
3567
  // @browser-strip-end